Task Plan

Task Plan

Turn any input source into a structured backlog that an agent can execute one task at a time in an automated loop. Each task is self-contained, verifiable, and completable in a single iteration.

When to use

Invoke when the user has an input source (PRD, design feedback, issue list, requirements doc, or verbal description) and wants it decomposed into executable tasks. The output is a backlog.md file — a flat task list with dependency graph and priority ordering.

Process

1. Understand the input

Accept input as a file path, URL, pasted text, or verbal description. If none provided, interview the user:

• What are you trying to build or change?
• What does the end state look like?
• What exists today?
• What constraints matter (timeline, tech stack, compatibility)?

Interview deeply — understand intent, not just surface requirements. The quality of the backlog depends on understanding the why.

2. Explore the codebase

Before decomposing, explore the codebase to understand:

• Existing patterns and conventions
• Architecture and integration layers
• What already exists that tasks can build on
• Testing patterns and verification infrastructure

Tasks that ignore existing code lead to rework. An agent executing a task should extend the codebase, not fight it.

3. Surface durable decisions

Identify decisions that span multiple tasks and are unlikely to change:

• Route structures / URL patterns
• Schema shapes and data models
• Key architectural boundaries
• Third-party service interfaces
• Shared component patterns

These go in a ## Decisions section at the top of the backlog so every task can reference them without repeating context.

4. Ask about reference material

Ask the user: "Are there docs, skills, or reference material that will help an agent execute these tasks?"

Examples:

• A Figma workflow doc for design tasks
• API documentation for integration tasks
• A testing guide for the project
• An existing skill relevant to the tech stack

These go in the backlog's reference table so the executing agent knows where to look.

5. Decompose into vertical slices

Break the input into tasks. Each task is a thin vertical slice through all relevant layers (model, logic, API, UI, tests), not a horizontal layer.

Apply these heuristics — read references/task-quality.md for details:

The one-iteration test: Can a fresh agent session complete this task in one loop iteration (~30 min)? If not, split it.

The one-commit test: Does this task produce exactly one coherent commit? If it would need multiple commits, split. If it's too small to commit alone, merge with a sibling.

The cold-start test: Does the task contain enough context (file paths, current state, what to change, how to verify) that an agent with no session memory can execute it? If not, add more detail.

The revert test: Could this commit be reverted cleanly, removing exactly one meaningful thing? If reverting would orphan code or break something unrelated, the task isn't self-contained.

6. Structure each task

Each task needs all of these fields:

• ID — short prefix + number (e.g. AU-1, DB-3). Prefix groups

related tasks (CC = cross-cutting, AU = auth, UI = interface, etc.)

• Title — what changes, not how
• Size — XS (< 10 min), S (10-20 min), M (20-40 min), L (40+ min).

If L, strongly consider splitting

• Deps — task IDs this depends on, or "none"
• Problem — what's wrong or missing (the why)
• What to do — concrete steps with file paths and current state
• Acceptance criteria — observable outcomes, not implementation details
• Verification — exact commands to run and what to check. Can

reference global verification rules or be task-specific

• Files — paths that will be touched

Read references/backlog-format.md for the full template.

7. Add dependency graph and priority order

Draw the dependency graph as a text diagram showing which tasks unblock others. Group tasks into phases where tasks within a phase can be executed in parallel (no mutual dependencies).

Priority order should generally be:

1. Cross-cutting / foundation tasks (unblock many others) 2. Quick wins (XS tasks, batch together) 3. Feature phases (grouped by domain area) 4. Polish and documentation

8. Quiz the user

Present the proposed breakdown as a summary. Ask:

• Does the granularity feel right? (too coarse / too fine)
• Should any tasks be merged or split?
• Are the dependencies correct?
• Is the priority order right?
• Anything missing?

Iterate until approved, then write the file.

9. Write the backlog

Write to the path specified by the user (default: TASKS/<name>/backlog.md). Create the directory if needed.

If the user plans to use /task-loop next, mention that the backlog is ready for loop scaffolding.

Backlog Format

The canonical markdown template for a task backlog.

Template

# <Backlog Title>

<One-line description of the work stream.>

## Status Legend

- `[ ]` Not started
- `[~]` In progress
- `[x]` Complete

## Reference

| Resource | Location |
|----------|----------|
| **<Doc name>** | `<path or URL>` |
| **<Tool/skill>** | `<name or path>` |
| **<Input source>** | `<path, URL, or description>` |

## Decisions

Durable decisions that apply across all tasks:

- **<Category>**: <decision>
- **<Category>**: <decision>

## How to Use This File

Each task follows this pattern. Complete **all** steps:

1. **Read context** — read the files listed in the task
2. **Make changes** — follow the "What to do" instructions
3. **Verify** — follow the verification steps
4. **Commit** — single coherent commit

---

## <Phase Name>

<Optional phase description.>

### [ ] **<ID>: <Title>** | **Size: <XS|S|M|L>** | **Deps: <IDs or none>**

**Problem:** <What's wrong or missing — the why.>

**What to do:**

1. <Concrete step with file path>
2. <Concrete step>
3. <Concrete step>

**Verification:**

- <Exact command or check>
- <What the output should look like>

**Files:** `<path>`, `<path>`

**Acceptance criteria:** <Observable outcome.> Tests pass.

---

## Dependency Graph

\```text
<ID> (<description>) ──── <ID> (<description>)
                      ├── <ID> (<description>)
                      └── <ID> (<description>)
\```

## Priority Order

**Phase 1 — <Theme>:**

- <ID>, <ID>, <ID>

**Phase 2 — <Theme>:**

- <ID>, <ID>

Notes

• Every task gets an [ ] checkbox for tracking
• Task IDs use a short prefix grouping related tasks (e.g. CC = cross-cutting,

AU = auth, DB = database, UI = user interface)

• The reference table links to docs and tools that help execute tasks
• The decisions section prevents repeating context across tasks
• The dependency graph shows which tasks unblock others
• Priority order groups tasks into execution phases
• Verification can be global (in "How to Use") or per-task or both
• Per-task verification overrides or extends global rules

Task Quality Heuristics

Reference material for decomposing input into high-quality tasks.

The Four Tests

The one-iteration test

Can a fresh agent session complete this task in one loop iteration (~30 min)?

Split if:

• The task requires exploring unfamiliar code AND making changes AND

writing tests — that's three phases of work

• The task touches more than 5-6 files across different concerns
• The task requires multiple rounds of comparison against a reference

(design mockup, spec, existing behaviour)

Don't split if:

• The task is conceptually one thing even if it touches several files

(e.g. adding a field to model + API handler + UI + test)

The one-commit test

Does this task produce exactly one coherent commit?

Split if:

• A reviewer would want to see this as two separate diffs
• The commit message would need "and" connecting unrelated things
• Renames/moves are mixed with content changes (git rename detection breaks)

Merge if:

• Two tasks would produce commits that can't stand alone
• A "setup" task has no value without its first consumer
• The overhead of two separate iterations exceeds the work

The cold-start test

Could an agent with zero session memory execute this task?

Every task should include:

• File paths that will be read and modified
• Current state — what exists now (not just what should change)
• Exact steps — not "fix the layout" but "change the grid from

2 columns to 3 at the md breakpoint in ProductGrid.tsx"

• Verification commands — not "check it works" but "run npm test

and verify the endpoint returns 200 with a valid payload"

• Reference material — links to docs, design files, API specs

The test: if you deleted the problem description and only kept "what to do", could the agent still execute correctly? If yes, the context is sufficient.

The revert test

Could git revert <commit> be applied cleanly?

Fails when:

• A task adds code that another task in the same batch depends on
• A task partially implements something that needs a follow-up to work
• A task changes a shared interface without updating all callers

Size Estimation

If a task is L, ask: can it be split into an M foundation + S additions?

Common Splitting Patterns

By concern: schema change (+ types + migration) in one task, component that uses the schema in the next.

By layer boundary: extract a reusable component first, then use it in the new feature.

By data flow: seed/content changes separate from component/layout changes when they're independently verifiable.

By risk: regression-protection snapshot tests first, then the refactor that might break things.

Common Merging Patterns

Setup + first use: don't create a task that only adds infrastructure with no consumer. Merge it with the first task that uses it.

Rename + update: renames should include all reference updates in one commit (otherwise the build breaks between commits).

Config + verify: adding a config field and verifying it works should be one task, not two.

Anti-Patterns

Too granular: "Add import statement" is not a task. If the overhead of reading the backlog, updating state files, and committing exceeds the actual work, the task is too small.

Too vague: "Fix the layout" gives an agent nothing to work with. Include file paths, current state, what's wrong, and what correct looks like.

Missing verification: "Make the change" without "and verify by running X" means the agent might commit broken code and mark the task done.

Missing file paths: Forces the agent to spend iteration time on codebase exploration instead of execution.

Horizontal layers: "Add all schema changes" then "add all components" means nothing is demoable until everything is done. Prefer vertical slices that deliver one complete feature path.