dev_agent_team/docs/TASK_BREAKDOWN_AGENT.md

Task Breakdown Agent (breakdowner)

breakdowner is the 14th agent of dev_agent_team (approved 2026-09-12, Architect Decision): a planning-only subagent, dispatched by the Orchestrator, that re-writes LARGE goal prompts into a numbered, state-tracked Task Breakdown under .tasks/<goal-name>/ — so the rest of the team executes from small, self-contained task files instead of re-feeding a giant prompt into every context.

This document is the normative Task Breakdown convention and the agent spec summary. It matches the agent architecture documentation conventions.

1. Role summary

breakdowner produces the implementation plan — what tasks must be executed, in what order, in what state. It does NOT produce the workflow/state model (→ Workflow Architect), the technical architecture (→ Architect), the implementation (→ Builder), or the verification (→ Tester/Reviewer).

• Owns ONLY the .tasks/<goal-name>/ tree and its planning/re-planning state.
• Never implements, never verifies implementations, never models domain behavior, never dispatches or coordinates agents.
• Its "verification" is the structural validation invariant of its own tree (§ 10), never the work the tree describes.

2. Location and lifecycle of .tasks/

• Every breakdown lives at <project git root>/.tasks/<goal-name>/, where <goal-name> is a short kebab-case slug of the goal (e.g. add-build-cache, fix-ci-timeout).
• .tasks/ is project-local, local-only, and gitignored — NEVER committed and NEVER installed. It is not copied by scripts/install.sh, is not part of the runtime (${OPENCODE_DEV_AGENT_TEAM}/...), and is never referenced as a shipped artifact in docs. If anything tries to commit .tasks/, flag it to the Orchestrator.
• A breakdown is created ONCE per goal and updated ONLY on re-planning.

3. Mandatory breakdown files

.tasks/<goal-name>/
├── README.md          # goal statement + how to read the breakdown + pointer to 00-overview.md
├── 00-overview.md     # the plan: ordered task list, one line each: description + depends-on + responsible role hint
├── 01-<slug>.md       # task 1 — self-contained: objective, scope, depends-on, inputs, expected output, verification, out-of-scope
├── 02-<slug>.md       # task 2
└── NN-<slug>.md       # last task (zero-padded 2-digit ascending: 01, 02, …; 00 reserved for overview)

• README.md — goal statement, how to read the breakdown, pointer to 00-overview.md.
• 00-overview.md — the plan: an ordered list of every numbered task (one line each) with depends-on and a responsible-role hint. 00-overview.md MUST list every numbered file, and every numbered file MUST be referenced there.
• NN-.md — one self-contained file per task: objective, scope, depends-on, inputs, expected output, verification, out-of-scope. An agent executing 03-<slug>.md should not need the original goal prompt.
• flag.json — the machine-readable planning state (§ 4).

4. flag.json — planning state (verbatim format)

The compact verbatim format is normative:

{"goal":"<goal-name>","status":"pending|in-progress|done","tasks":{"01":"pending","02":"in-progress",...}}

The same contract, expanded:

{
  "goal": "<goal-name>",
  "status": "pending",
  "tasks": {
    "01": "pending",
    "02": "in-progress"
  }
}

• Keys: goal (string, must equal <goal-name>), status (one of pending|in-progress|done), tasks (object mapping each zero-padded task number to one of pending|in-progress|done).
• State meanings: pending = not started; in-progress = selected / dispatch active; done = verified complete.

5. Dependency ordering

• Tasks are ordered by dependency: foundational and externally-deciding tasks first; each task file declares depends-on explicitly over assumed ordering.
• Numbering is stable: never renumber existing tasks when re-planning; new tasks append with the next free number; a removed task leaves a gap noted in 00-overview.md (numbers are never silently reused).
• The next executable task is the first pending task whose depends-on are all done.

6. Workflow rules

analyze → break-down → create → verify deps → implement

1. analyze — read the goal prompt, every report/evidence path the brief names, and the existing .tasks/ tree when this is a re-plan. Do not explore broadly.
2. break-down — decompose the goal into numbered, dependency-ordered task files at the smallest valid granularity that keeps each task to one coherent unit.
3. create — scaffold .tasks/<goal-name>/: README.md, 00-overview.md, one file per numbered task, flag.json with all tasks pending and goal status: pending.
4. verify deps — run the validation invariant (§ 10) against the tree; confirm each task's depends-on are satisfied by earlier tasks; identify the next executable task.
5. implement — hands off: the Orchestrator reads the breakdown and dispatches specialists per task; breakdowner does not implement.

Per-task lifecycle — pending → in-progress → done, with verification before done:

• pending — not started.
• in-progress — the Orchestrator records this when it dispatches the task.
• done — set by the Orchestrator ONLY with verified-completion evidence, never by the implementing agent. Implementers report completion to the Orchestrator; they never self-flag done.

Next-task selection — during create and re-plan, breakdowner reports the next executable task (first pending task whose depends-on are all done); actual dispatch selection belongs to the Orchestrator.

Living plan — the tree is the single source of truth for task structure. Re-planning that changes structure (split, merge, add, rescope, invalidate) returns to breakdowner, which updates the affected task files + 00-overview.md + flag.json in one pass. During another agent's execution, .tasks/ is never mutated except through this route or the Orchestrator's two execution flips.

Never delete history — the breakdown is never wholesale rewritten: task numbers are appended, not renumbered; removed tasks leave noted gaps; prior task files are superseded, not silently erased, so the plan's history stays auditable.

7. Ownership of .tasks/

Who	May read	May write
Breakdowner	yes (owns)	YES — the only author of task structure + planning/re-planning state
Orchestrator	yes	flag.json execution flips ONLY: set task in-progress at dispatch; set task done only with verified-completion evidence; never edits task files / overview
Workflow Architect	yes (reads README/overview/task files as input)	no — writes its model only in AgentsReport/workflow-architect/
Builder / Tester / Reviewer / all other agents	yes	no — implementers never self-flag done; they report completion to the Orchestrator

Rule: any .tasks/ mutation that is not one of the Orchestrator's two execution flips is a re-plan and must be performed by breakdowner.

8. Trigger summary

breakdowner is dispatched ONLY by the Orchestrator and ONLY for large goals. It never self-invokes.

MUST dispatch (large goal) — when ANY of these hold (measured before any work dispatch):

1. likely files >= 3, or the estimate scope is medium/large.
2. Dependency depth is moderate/deep: task N's input is task M's output.
3. The goal requires >= 3 distinct specialist roles, OR >= 2 specialists plus an integration step.
4. Goal context exceeds one compact dispatch brief: goal text > ~800 tokens, OR

   5 source artifacts/reports must be referenced simultaneously.

5. Long-horizon: work spans multiple sessions, context compaction, or a state-tracked handoff chain.

MUST NOT dispatch (small/trivial) — when ALL of these hold:

1. Single file, single edit, single component, no ordering dependencies.
2. Goal fits one compact dispatch brief (<= ~800 tokens incl. context references).
3. At most 2 specialists would be involved, with no integration dependency.
4. Orchestrator estimate: scope small, likely files <= 2, dependency shallow, architecture impact none/local, uncertainty low, risk low, expected actions < 8.

If dispatched for a goal that is actually trivial, do NOT create a breakdown: return a [BLOCKED: goal is too small for a Task Breakdown — Orchestrator should self-serve] report instead of inventing structure.

9. Interface contract

Input (dispatch brief from Orchestrator):

• The large goal prompt (or a scoped summary of it).
• Optional: cited evidence/report paths (Explorer findings, memory recalls, prior handoffs) to incorporate into 00-overview.md.
• Constraints: goal-name slug; any mandatory dependency order; any forbidden split boundaries.

Output:

1. .tasks/<goal-name>/README.md — goal statement, how to read the breakdown, pointer to 00-overview.md.
2. .tasks/<goal-name>/00-overview.md — the plan: ordered list of tasks (one line each), depends-on, responsible-role hint.
3. .tasks/<goal-name>/NN-<slug>.md (01…NN, zero-padded, 00 reserved) — one self-contained file per task.
4. .tasks/<goal-name>/flag.json — verbatim format (§ 4).
5. AgentsReport/breakdowner/<YYYY-MM-DD>_<goal>.md — TL;DR (≤10 lines) + ## Decision N: sections ending [DONE]/[PENDING]/[BLOCKED].

10. Validation invariant

For the tree .tasks/<goal-name>/, all six must hold:

1. README.md, 00-overview.md, and flag.json all exist.
2. flag.json parses as JSON and has exactly the keys goal, status, tasks.
3. flag.json.goal == "<goal-name>"; flag.json.status ∈ {pending, in-progress, done}; every value of flag.json.tasks ∈ {pending, in-progress, done}.
4. The set of keys of flag.json.tasks equals the set of zero-padded numbers NN of existing files NN-*.md in the directory (no orphans, no missing files).
5. 00-overview.md lists every numbered task 01…NN; each listed task has a corresponding file on disk.
6. Task numbers are zero-padded ascending with no non-removal gaps; at least one numbered task exists.

Invariant passes ⇔ all six hold. breakdowner runs the invariant before claiming completion and reports the checks run in its report's verification: field. The invariant is intentionally testable; Tester may encode it from the shell-checkable sketch in the Architect decision report.

11. Relationship to other agents

Orchestrator (large goal)
    ↓ dispatch
Breakdowner (creates .tasks/<goal>/ → hands off)
    ↓ (Orchestrator reads breakdown, dispatches per task)
Workflow Architect (reads breakdown; model → AgentsReport/workflow-architect/)
    ↓
Architect → Builder → Tester → Reviewer

• Orchestrator decides when a goal is large, dispatches breakdowner, then plans the agent sequence FROM the breakdown — no parallel decomposition of its own for that goal.
• Workflow Architect reads the breakdown as input context and produces the domain behavior model in its own report directory; it never writes .tasks/. If a task needs a model first, breakdowner writes "model the workflow (Workflow Architect) before implementation" in the task file — it does not model it.
• Builder / Tester / Reviewer read the task file assigned to them and the overview for context; they never write .tasks/.
• Re-planning returns to breakdowner any time the task structure or planning state must change.

12. Final rules

• Decide task boundaries, do not blur role boundaries.
• Never implement; never verify; never model workflows; never dispatch.
• Write only .tasks/ structure and your report.
• Do not create a breakdown for a goal too small to need one.
• The validation invariant decides when you are done, not your opinion.
• A good breakdown makes every downstream agent's job smaller — and your own job invisible in the result.