Tasks, plans, and logs
Use tasks, plans, and logs when agent work needs to survive past one terminal session.
A plain brew is fine for a quick local question. A task-linked brew is better when the work needs review, handoff, or a record a teammate can read later.
Tasks are the unit of intent
A task is where the work starts. It should tell the agent and the reviewer what matters.
A useful task includes:
- The problem or request.
- The expected outcome.
- Important constraints.
- Links, screenshots, or product context where needed.
- The checks that should pass before review.
Keep the task focused. If the description needs three unrelated goals, split it before launching agents.
Plans are immutable versions
An implementation plan captures how the agent intends to approach the work. Read it before the agent edits risky code.
A good plan names:
- Files or subsystems likely to change.
- The smallest implementation path.
- Tests, lint, or manual checks.
- Known risks.
- Out-of-scope work.
Plans are immutable. Each new plan is a new version, and the latest version is the current source of truth. Earlier versions stay as history, so you can see how the direction changed.
When Claude Code proposes a plan and leaves plan mode, Coldtea captures that plan on the linked task automatically. An agent can also write a plan to the task itself. Either way, the plan lands on the task without you copying text around.
The point is not to predict every line of code. The point is to catch bad direction early. To read a plan and respond to it, see plan review.
Session logs are for handoff
A session log records what happened during a brew. It is most useful when it is short and concrete:
- What changed.
- Why it changed.
- What checks ran.
- What failed.
- What the next reviewer should inspect.
A task-linked brew can leave a session log on the task. When a brew compacts its history, Coldtea also records the compaction summary as a log, so a long session still leaves a trail.
Do not use logs as a place for vague status. "Implemented the feature successfully" tells nobody what to trust.
The activity feed
The task detail page keeps an activity feed: a timeline of what changed on the task and when. It records workflow-state moves, priority, assignee, title, and description edits, label changes, parent and subtask changes, task relations, new session logs and implementation plans, cloud runs, and imports from Linear.
Read the activity feed to answer "what happened to this task" without opening every log in full. For the Linear connection, see Linear.
Attachments
A task can carry attachments: files you upload to give the agent or a reviewer more context. Add them when a screenshot, a log file, or a spec explains the request better than prose. An agent that reads the task can fetch the attached files.
Subtasks and relations
A task can have subtasks. Use a parent task for the outcome and subtasks for the separate streams of work under it. You can add subtasks from the task detail page.
A task can also relate to other tasks. The relation kinds are blocks, blocked by, related, duplicate of, and duplicate. Relations show up in the activity feed, so you can see when one task was marked as blocking or duplicating another.
The review path
For task-linked work, review in this order:
- Read the task description.
- Read the latest implementation plan.
- Read the relevant session logs.
- Inspect the diff in the editor.
- Run or review the checks.
- Leave follow-up on the task or send it back to the agent.
That order keeps you grounded. If you start from the final agent summary, you inherit the agent's framing before you have seen the work.
When to skip the task surface
Skip tasks for disposable work:
- Asking an agent to explain a file.
- Running a one-off command.
- Trying a throwaway local experiment.
- Inspecting a project before you know what task to create.
Once the work creates a branch, review, or teammate handoff, move it into a task.
Team habit
Treat the task as the source of truth. Prompts are temporary. Terminal output scrolls. A clear task, a checked plan, and a useful session log give the team something stable to review.
Next: review agent work.