| name | milestone-breakdown |
| description | Break down the next open milestone from ROADMAP.md into small, actionable, independently testable tasks in PLAN.md. Trigger whenever the user says "break down", "plan tasks", "create tasks", "task breakdown", "decompose milestone", "phase 2", "let's break this down", references PLAN.md in a planning context, or asks to prepare for implementation. Also trigger when the user has just finished strategic planning and wants to move to the next phase. This skill reads the codebase and docs to produce implementation-aware tasks with architectural hints, test cases, and file associations.
|
| model | opus |
| allowed-tools | Read, Glob, Grep, Edit, Write, Agent |
Milestone Breakdown — Decomposing into Actionable Tasks
For the full workflow this skill belongs to, see workflow-overview.md.
You are guiding the human through the Break-Down phase of an AI-native milestone-driven
workflow. Your job is to turn the next open milestone from ROADMAP.md into a concrete,
ordered list of tasks in PLAN.md — each small enough to implement in a single focused
session, each independently testable and committable.
Prerequisites
ROADMAP.md (the index) must exist with at least one milestone whose status is open.
The full content of each milestone lives in roadmap/NNNN-slug.md.PLAN.md should be empty or contain only completed/postponed tasks from a prior
milestone. If it has uncompleted tasks, confirm with the user before overwriting.
Phase Workflow
Step 1: Select the Milestone
Read the ROADMAP.md index and identify the next [open] milestone. If multiple are
open, approach the next one in order of writing (lowest number). Open its
roadmap/NNNN-slug.md file to read the full milestone content. Update the status to
in progress in both places: the [open] → [in progress] marker on the index line
and the **Status:** field in the milestone file.
Step 2: Codebase Reconnaissance — Delegate to milestone-scout
Before writing any tasks, you need a structured picture of the part of the
codebase the milestone touches: relevant files, conventions to match, test
posture, risks. Delegate this discovery to the milestone-scout subagent
rather than reading the codebase yourself — that keeps your opus session
focused on synthesis instead of file paging.
Spawn the scout with subagent_type: milestone-scout and a self-contained
prompt:
Milestone (verbatim from roadmap/NNNN-slug.md):
<paste the full milestone block — title, value/impact, outcome, success
criteria, notes>
Repo root: <absolute path, or "current working directory">
Hint: <if a top-level CODEBASE.md or specific <module>/CODEBASE.md is
relevant, name it; otherwise omit this line>
Follow your standard report format.
The scout returns a structured report covering:
- Orientation — language, framework, layout shape, dominant conventions.
- Relevant files — capped at ~20, each with a one-line "why".
- Conventions to match — tests, code organization, error handling,
logging, config, async — each cited to a concrete file.
- Risks — tech debt, fragile coupling, missing coverage, migration
implications.
- Preparatory work suggestions — things that ought to happen before the
main tasks. These are suggestions; you decide whether they make it into
PLAN.md.
- Sources used and tooling notes (so you know the report's accuracy
ceiling).
If the scout subagent isn't available in this environment, fall back to
reading the codebase yourself: project root layout (Glob), key affected
files, README/ARCHITECTURE/CONTRIBUTING docs, and existing test conventions.
Note the same categories the scout would have produced.
Consult prior architectural decisions too. In parallel with the scout,
spawn the decision-lookup subagent (subagent_type: decision-lookup) with the
milestone's title and the subsystems it touches. It locates and reads the project's
decision index (architecture/decisions.md by default, or under the architecture-path:
directory set in CLAUDE.md),
pulls only the relevant records, and returns a compact briefing of the decisions
that constrain how this milestone should be built — so you inherit them without
paging the whole decision log into your opus session. If it reports no log exists,
proceed normally. Fold any binding decision it returns into the tasks' Architecture
& Decisions notes, and if the milestone as scoped would cut against an Accepted
decision, raise that with the human before writing the plan.
After the scout returns: if anything about the milestone's scope is unclear
or contradicts what the scout found, ask the human now, before writing. Keep
clarification questions focused and minimal. Once open questions are
resolved, move directly to writing the plan.
Step 3: Write PLAN.md
Write the plan to PLAN.md immediately after resolving any open questions. Do not
present the plan in chat first — the file is the artifact. Follow the format in the
appendix at the end of this document.
Task sizing rules:
- Each task should be implementable within roughly 50% of the available context window.
In practice this means: a task should touch at most 3–5 files and produce at most
~200 lines of new/changed code plus tests.
- If a task feels too large, split it. Prefer more small tasks over fewer large ones.
- Each task must be independently committable — the codebase should pass all tests after
each task is completed.
Ordering rules:
- Order tasks so that each builds on the previous.
- Put foundational work (types, schemas, interfaces) before implementation.
- Put tests alongside their implementation task, not as separate tasks (TDD is handled
in the implementation phase).
- End with integration, wiring, and polish tasks.
Cross-cutting concerns — include a section at the end of the plan:
## Cross-Cutting Concerns
- **Security:** <any auth, input validation, secrets management notes>
- **Performance:** <any known performance constraints or targets>
- **Observability:** <logging, metrics, alerting expectations>
- **Migration:** <data migration steps if applicable>
- **Rollback:** <how to safely revert if something goes wrong>
Step 4: Record Architectural Splits
Most per-task choices belong in a task's Architecture & Decisions notes and nowhere
else — that field exists precisely so small, local decisions stay local. But breaking a
milestone down occasionally forces a milestone-level architectural split: a fork that
shapes many tasks at once and would be expensive to reverse — introducing a new service
boundary, choosing a persistence model for a whole feature, committing to a protocol or a
cross-cutting pattern the rest of the work must honour. When the breakdown lands such a
split, record it as an ADR so the reasoning survives past this planning session.
Record one only when the decision splits the architecture across tasks or commits to a
direction that is costly to undo — not for ordinary per-task choices. For each that
clears the bar, read references/decision-record.md and follow it. Records live in
<architecture-home>/decisions/ — architecture/ is the default home, or the directory
named by an architecture-path: <directory> line in CLAUDE.md. Number the record,
write <architecture-home>/decisions/NNNN-kebab-title.md, and append the one-sentence
entry to <architecture-home>/decisions.md. Reference the record from the affected tasks'
Architecture & Decisions notes (e.g. "per ADR 0007") so the implementer follows it. If
the split would contradict a decision the Step 2 decision-lookup briefing surfaced, flag
it to the human rather than silently overriding — that is a superseding decision and their
call. After writing the record(s), spawn the architecture-summarizer subagent
(subagent_type: architecture-summarizer) with the architecture home and the new ADR
number(s) so the derived <architecture-home>/<topic>.md summaries stay in sync.
Step 5: Review on File
After writing PLAN.md, tell the human the plan is ready for review and point them to
the file (note any decision records you wrote). The human reviews and comments on the file
directly (or asks for changes in chat). Iterate by editing PLAN.md until the human approves.
Step 6: Hand Off
Once approved:
- Present a brief summary and suggest the user commit using
/commit.
- Suggest they move to the Implementation phase when ready.
Important Principles
- Implementation-aware, not implementation-dictating. Provide enough architectural
context that the implementer (which may be a different Claude model or the human
themselves) can make good decisions, but don't write pseudocode or dictate exact
implementations.
- Test cases are first-class. Every task must have test cases described. These become
the starting point for TDD in the implementation phase.
- One task, one commit. If a task can't be meaningfully committed on its own, it's
either too small (merge it) or entangled with another task (restructure).
- File associations matter. Listing the files a task will touch helps the implementer
scope their work and helps the reviewer know what to check.
- Surface unknowns. If during codebase assessment you discover something that could
affect the milestone (tech debt, missing tests, fragile code), flag it as a risk or
add a preparatory task.
Appendix: PLAN.md Format Reference
Plan:
Milestone: roadmap/NNNN-slug.md
Started:
Tasks
[x] 1. Example finished task
- Files:
path/to/file.ts, path/to/file.test.ts
- Description: <What this task accomplishes, written so that an implementer with
access to the codebase but no other context can execute it>
- Architecture & Decisions:
- <Pattern to follow, e.g. "Use the existing Repository pattern from
src/repos/">
- <Key decision, e.g. "Store as JSON column, not a separate table — scope is small">
- Non-Functional Considerations:
- <Security, performance, accessibility, compliance notes if any>
- Test Cases:
- <Test 1: description of what to test and expected outcome>
- <Test 2: ...>
-
- Commit Message:
<conventional commit message for this task>
[ ] 2. Example unfinished task
