Agent Context And Instructions

Context Sources

Coldtea agents can benefit from several kinds of context:

Repository instructions for the coding agents your team uses.
Task descriptions and implementation plans in Coldtea.
Terminal output, logs, and running app state visible in other panes.
Editor selections and annotations.
Worktree, branch, and project context.
Connected services where your workspace has enabled them.

Use durable repo instructions for rules that apply across many sessions. Use Coldtea tasks and annotations for task-specific intent.

Write Repository Instructions Like Internal Docs

Agent instruction files work best when they are short, concrete, and tied to the actual repo. Prefer:

Commands that should be used for build, lint, test, and local development.
Architecture boundaries the agent must respect.
Style rules that differ from common defaults.
High-risk areas that require extra review.
Known flaky tests or setup caveats.
Links to deeper internal docs instead of copying every detail into one huge file.

Avoid vague instructions such as "write clean code" or "use best practices." They cost context without changing behavior.

Suggested Instruction Shape

For a team adopting Coldtea, keep repository agent instructions close to this shape:

# Project Instructions

## Product

One paragraph explaining what this repo does and who uses it.

## Commands

- Install:
- Dev:
- Lint:
- Test:
- Build:

## Architecture

- Important directories:
- Where new features belong:
- What should not be changed casually:

## Coding Rules

- Language and type rules:
- Styling/component conventions:
- Testing expectations:

## Agent Workflow

- Plan before broad changes.
- Keep edits scoped.
- Run relevant checks.
- Report anything not verified.

The exact content should be specific to the repo. Coldtea should not require a single universal template.

Task-Specific Context

For a Coldtea task, include:

The user or customer problem.
The intended behavior after the change.
Relevant files, routes, or services if known.
What is out of scope.
The expected verification command or scenario.

If the task is large, ask for or write an implementation plan before launching implementation work.

Annotations As Precision Context

Annotations are best for small, specific feedback:

"This error message should mention the provider name."
"This branch should stay unchanged."
"This selector is the one the agent should inspect."

Use annotations when a screenshot, terminal line, or code selection would be clearer than another paragraph of prose.

Context Hygiene

More context is not always better. When agents drift, stale or excessive context is often the reason.

Good defaults:

Keep always-on instructions short.
Link to deeper docs by topic.
Put temporary task details in Coldtea tasks or session prompts.
Remove obsolete instructions when the repo changes.
Prefer one clear source of truth for each concern.