# Why a coding agent needs a backlog, not a prompt

> Long-horizon tasks, multi-agent sessions and sprint planning all fail the same way when the plan lives in a context window. What to give the agent instead.

Source: https://autoplans.dev/guides/ai-coding-agent-backlog

## Why a coding agent loses track of the plan

A prompt is a good way to start a piece of work and a poor way to hold one. The
plan arrives in the first message; every file the agent reads, every command it
runs and every test result it inspects piles into the same context window on
top of it. By mid-afternoon the plan is the oldest thing in the window, and the
oldest thing is what goes first.

Claude Code's documentation describes the mechanism plainly. When
context fills up it "clears older tool outputs first, then summarizes the
conversation if needed", and while "your requests and key code snippets are
preserved", "detailed instructions from early in the conversation may be lost".
Sessions do not rescue each other either: "Each new session starts with a fresh
context window, without the conversation history from previous sessions."
Other agents manage the window differently, but every window is finite.

The symptoms are recognisable. The agent finishes step three, compacts, and
begins step three again. It reports a feature complete because step five was in
the part that got summarised away. The general failure has a name —
[context rot](/guides/context-rot) — but the specific thing lost here is the
plan, and the fix is not a longer prompt. It is a record that lives outside the
window and that the agent reads and writes as it works.

## Long-horizon tasks and where the plan can live

Long-horizon tasks are the ones that outlast a context window: a feature
spanning several sessions, a migration touching forty files, anything a second
agent picks up part-way through. For those it pays to be exact about which
store survives what.

| Where the plan lives | Survives compaction | Survives a new session | Visible to another agent | Carries status |
|---|---|---|---|---|
| The prompt | No | No | No | No |
| An instruction file (`CLAUDE.md`, `AGENTS.md`) | Yes | Yes | Yes | No — rules, not state |
| The agent's private to-do list | Within the session | No | No | Only to that session |
| A backlog with ids and statuses | Yes | Yes | Yes | Yes |

Instruction files are the right place for conventions and the wrong place for
"we are on step four of seven": they load at session start and are meant to be
stable. See [AGENTS.md](/guides/agents-md) for what earns a place in one.

The private to-do list deserves a warning, because it looks like the answer.
Most agents have one — in the Autoplans desktop app and CLI it is `todowrite` —
and it has checkboxes, so it feels like a backlog. It is scoped to the session,
invisible to everyone else, and gone when the session is. The bundled Autoplans
instructions are explicit that an agent without the real task tools must say so
rather than report a local list as progress ([Agents](/docs/agents)).

An agent-readable backlog needs four things: an id per task the agent can
address, a status it can change, dependencies stored as data rather than prose,
and one call that returns the whole graph. Autoplans links a folder to a
project through `.autoplans/project.json`, and the code agent reads that file
first and loads the open tasks before doing anything else
([Projects](/docs/projects)).

## Vibecoding, and why several agents need one source of truth

Vibecoding — describing what you want, letting an agent build it, and steering
from the result rather than from the diff — scales in one direction: more
agents. One session researches, one implements, one reviews. Claude Code's
subagents are built for exactly this. "Each subagent starts with a fresh,
isolated context window. It doesn't see your conversation history, the skills
you've already invoked, or the files Claude has already read", and "Background
subagents run concurrently while you continue working."

That isolation is the feature and the problem at once. Three agents with three
windows hold three versions of the plan: the researcher found that the auth
middleware has to change first, the implementer never read that, and the
reviewer approves a diff against a plan nobody wrote down. The coordination
layer is you, pasting paragraphs between terminals. AI coding agent
orchestration is a coordination problem before it is a tooling problem, and the
primitive it needs is a shared record with three properties:

- **Addressable.** "Task 3f2a" means the same thing in every window.
- **Stateful.** `in_progress` set by one agent is read by the next.
- **Historical.** What was built, how it was checked and what remains is
  written on the task rather than said in a chat.

Autoplans separates the roles the same way: the Ai-Planning agent turns a goal
into tasks and deliberately writes no implementation code, the Ai-Code-Agent
works the backlog and keeps it current, and both write to the same project
([Agents](/docs/agents)).

## What an automated sprint planning AI can produce, and what it cannot judge

Ask an automated sprint planning AI for a backlog and, given the codebase, four
things come out reliably.

| It can produce | Because |
|---|---|
| Tasks with a title and done-criteria | The work is legible in the code |
| Subtasks, one level down | The steps of a task follow from the task |
| Dependencies | "B needs A" is usually visible in the code |
| A priority and a type per task | Defaults a person can correct |

The Autoplans planning agent clarifies scope, names risks and breaks work into
small verifiable tasks with priorities, types and dependencies. The planner
shipped in the Claude Code plugin is held to four rules: ground the breakdown
in files that actually exist; split any task whose description needs the word
"and" to explain what done looks like; order by dependency rather than by
category, since "write tests" is not a phase; and where the request is
underspecified, create an explicit decision task instead of guessing. That last
rule is the useful one: the planner's job is to make the unknowns visible, not
to resolve them.

What it cannot judge is everything outside the repository: whether the feature
is worth building at all, what the deadline is, how much of the team's week it
deserves, which risk is acceptable to carry. AI sprint planning for developers
works when a person reviews the draft before it becomes the plan, which is why
the plugin's planner is told not to call `create_task` or `bulk_create_tasks`
itself — the main thread confirms with you before anything is written.

One honest limit: Autoplans has no epic object. The hierarchy is task and
subtask, one level deep in practice — the planner breaks a task into steps, not
a tree, though nothing in the schema stops a subtask being given children of
its own. The grouping epics provide elsewhere comes instead from the dependency
graph, which the [task map](/docs/task-map) draws with the startable tasks in
the leftmost column.

## What a multi-agent coding session manager has to track

A session is one conversation with one agent in one folder; a task is the
record of a piece of work. There is no automatic link between them — Autoplans
says so plainly ([Sessions](/docs/sessions)) — so the agent makes the link, on
the task, while it works. For a multi-agent coding session manager, "tracking"
comes down to three things.

**Which sessions exist and how they relate.** The desktop app runs many at
once, an agent can spawn sub-sessions, and the task map's sessions lane draws
parent to child with dashed arrows. A conversation started in another coding
agent can be adopted through **Session → Continue from another agent…**.

**Status transitions made by the agent that did the work.** The Autoplans code
agent must set a task `in_progress` the moment it starts, use `completed` only
once the work is written and verified, fall back to `waiting_for_review` when
it could not verify it, and update a task retroactively if it finished matching
work without marking it.

**Handoffs written on the task.** On completion the agent posts a comment
saying what was built, how it was checked and what remains. Agent comments are
prefixed `[Autoplans Code Agent]`, so a reader can tell agent history from
human history ([Tasks](/docs/tasks)).

The MCP tools shaped for this loop are the `code_agent_*` set
([MCP tools](/docs/tools)):

| Tool | Arguments | Answers |
|---|---|---|
| `code_agent_get_my_tasks` | `projectId`, `status?` | What is assigned to `ai-agent` here |
| `code_agent_get_task_with_dependencies` | `taskId` | The task, its dependencies, and `hasUncompletedDependencies` |
| `code_agent_update_task_status` | `taskId`, `status`, `comment?` | A status change and a comment in one call |
| `code_agent_add_comment` | `taskId`, `content` | A progress note on the task |

One task, from any MCP client, runs like this:

```text
code_agent_get_task_with_dependencies  taskId=3f2a…
  → hasUncompletedDependencies: false
code_agent_update_task_status          taskId=3f2a… status=in_progress
… edit, run the tests …
code_agent_update_task_status          taskId=3f2a… status=completed
                                       comment="Rate limiter added; unit tests pass; docs still to write"
```

`code_agent_update_task_status` accepts `pending`, `in_progress`, `blocked` and
`completed`; to park work as `waiting_for_review` or record a `failed` attempt,
call `update_task`, which takes the full status set. In the Claude Code plugin,
`/start` pulls the task with its dependencies and stops rather than starting
blocked work, and `/finish` reads the working diff with `git diff` "rather than
relying on memory of this session" before commenting and setting the status.

## The context switching cost between editor and tracker

The last argument for a backlog over a prompt is the one people feel daily.
Every trip out of the editor to move a card in a browser tab costs the thread
you were on, so updates get batched until later and the record drifts from the
code. A tracker that is only accurate at the end of the day is one no agent can
trust at the start of it.

Two things cut context switching to almost nothing. The agent maintains the
record itself, through tools, as part of the work, and the record appears where
you already are: the [VS Code extension](/vscode) puts projects and tasks in
the sidebar and opens the task map from a status-bar button, the
[Obsidian plugin](/obsidian) syncs the backlog into notes where ticking a
checkbox sets the task `completed`, and the OpenCode plugin surfaces your
in-progress tasks when a session begins ([OpenCode](/docs/opencode)). Pushes to
a connected repository are matched back to tasks ([GitHub](/docs/github)).

None of this depends on Autoplans. If your backlog lives in
[Jira](/compare/jira) or [Linear](/compare/linear), apply the same test: can the
agent read it in one call, address a task by id, change its status and leave a
comment, with you relaying none of it.

## Questions

### How do I give a coding agent a backlog?

Give it three things: a project the folder is linked to, a read tool returning
the open tasks with their dependencies, and write tools for status and
comments. Then put "update the task as you work" in the agent's instruction
file rather than in every prompt. With Autoplans that is
`.autoplans/project.json`, `list_tasks` for the read, and the `code_agent_*`
tools for the writes; the bundled agents already carry the rule.

### Can I run multiple coding agents on one project?

Yes, provided they share the record. To run multiple coding agents on one
project, point each at the same project id. The desktop app and the VS Code
extension read `.autoplans/project.json` themselves; the agent prompts bundled
with the desktop app, the CLI and the OpenCode plugin tell the agent to read
it. No MCP client reads it on its own — the server is remote HTTP and has no
view of your filesystem — so for any other client put the instruction in the
agent's instruction file; an `AGENTS.md` line is the place for it. Then
let status do the coordinating: treat `in_progress` as taken, and start nothing
that reports `hasUncompletedDependencies: true`. Give each agent a role (plan,
implement, review) rather than a slice of the same task.

### How do I set up a task backlog for Claude Code?

Two routes. The plugin:
`/plugin marketplace add mohamedgb00714/autoplans-plugins`, then
`/plugin install autoplans`. Claude Code prompts for the API key when the
plugin is enabled and keeps it in plugin configuration; the plugin's MCP entry
reads it from there as `${user_config.api_token}`, not from the environment. It
adds `/plan`, `/start`, `/tasks` and `/finish`, the `autoplans-planner` agent,
and the MCP server. Or the server alone, in a `.mcp.json` at the project root —
Claude Code's project scope, which its documentation says to check into version
control. Claude Code expands `${VAR}` when it reads the file, so put the
variable in the header and export the key in the shell you start it from, and
the committed copy carries no secret:

```json
{
  "mcpServers": {
    "autoplans": {
      "type": "http",
      "url": "https://autoplans.dev/api/v1/mcp",
      "headers": { "Authorization": "Bearer ${AUTOPLANS_API_KEY}" }
    }
  }
}
```

Per-client blocks are on the [MCP server page](/mcp-server) and the
[Claude Code setup page](/mcp-server/claude-code).

### What makes a backlog agent-readable?

Ids, statuses, dependencies as data, and one round trip to fetch the graph. The
Autoplans `list_tasks` response carries `parentTaskId`, `dependsOnTaskIds`,
`subtaskCount` and `commentCount` on every task, which is the whole plan —
nodes and edges — in a single call. An AI coding agent backlog that takes five
calls and a parser to reconstruct is one the agent will reconstruct wrongly.