swe-plan

Pipeline

swe-shape → swe-spec → [swe-plan] → [swe-worktree] → swe-execute → swe-review, with swe-research available at any point.

Each stage runs in its own session: the user invokes one skill, reviews the artifact, clears the context, then invokes the next with the artifacts as input. Assume no memory of other stages beyond the files named below.

• This stage: optional. Decide delivery order and verification boundaries. Most changes skip it.
• Reads: spec.html (the approved design and contracts, written by swe-spec) and brief.md (the approved problem and acceptance criteria, written by swe-shape).
• Writes: plan.md, or nothing when the spec is one coherent slice.
• Next: the user runs swe-worktree or swe-execute. Do not invoke either.

Purpose

Decide delivery order and verification boundaries for complex execution. A plan coordinates specified work; it does not repeat design or narrate how to code it.

A plan is not a Markdown restatement of the spec. spec.html remains the contract, and swe-execute reads it whether or not a plan exists. The plan's only job is to say what is built in what order, how each step is verified, and which spec sections each step needs.

Inputs and Workspace

Read .swe/<change>/spec.html — the canonical contract, at whatever depth each section reached — using its table of contents to load only the sections that affect sequencing. Read brief.md when acceptance, dependencies, or risk require it, and the research reports either artifact links when they affect sequencing, feasibility, rollout, or an early risk-reduction slice. Infer the change directory only when unambiguous.

Write .swe/<change>/plan.md using plan.template.md. The plan is Markdown: it is a short list of slices consumed almost entirely by agents, with little to gain from rich rendering.

Workflow

1. Decide whether to plan. Apply the planning threshold below — it is a gate, not a preference. If the spec is one coherent implementation slice, do not create plan.md; report that execution can proceed directly from the spec. Most changes end here.
2. Identify delivery slices. Find the smallest set of completed, observable or independently risk-reducing outcomes. Prefer thin end-to-end slices over technical layers.
3. Order by dependency and learning. Establish prerequisites, then prioritize early validation of expensive assumptions, integration risk, migration safety, and user-visible value.
4. Preserve valid intermediate states. Every slice must leave the repository buildable, testable, and operationally safe under the specified compatibility strategy.
5. Reference authoritative detail. Link each slice to the exact spec.html section ids it implements and the acceptance criteria it satisfies. Do not copy their contracts.
6. Define verification. Give runnable repository commands and observable results for each slice, including rollback or operational checks only where relevant.
7. Check plan size. If more than roughly eight slices are needed, recommend splitting the change or introducing explicit phases rather than producing a giant plan.
8. Complete, skip, or stop. Finish with exactly one of the outcomes in Completion Criteria.