Writing Plans
Leave the implementation to the executor: write what each task must make true and how that is judged, not the code.
When to use
- Detailed requirements are approved, or a precise task spans three or more steps or more than one file.
- Skip for single-step or trivial changes.
- If the intent is still ambiguous, invoke
clarifying-intentfirst. If verifiable behavior is still missing, invokewriting-specsfirst. A precise task needs neither. - Fill the classification block (the index's High-risk classification
section). High-risk means any answer there leaves the ordinary route, or
the user marks the work high-risk. For a high-risk target, read the
approved migration and assurance contracts before writing a task. If they
are missing, plan only the gate that is missing, taking the exact proposed
contract as its input, and put no target work in the plan; with none
proposed, write no plan: report that
migration-strategyorverification-strategymust produce it. Record unsettled facts as evidence, never as accepted deviations. - Write separate plans for independent subsystems unless one cutover or
rollback makes them one initiative. If the approved design orders the
work in dependency-ordered slices (a later part builds on what an earlier
one lands), write the first slice's plan now and each later one after its
predecessor lands, against the base then current; the index's
Plan setline names the order.
Available scripts
scripts/plan-version.sh— prints the plan's version, or with--check-contractand--verifychecks task-contract invariants and the decision ledger.scripts/plan-files.sh— checks each task'sFilespaths against a base revision. Read-only.
Step 1: Write the index
- REQUIRED SUB-SKILL: invoke
mapping-the-codebaseon every region the plan will change, unless a boundary record inside its freshness limit covers that region at the base revision. Draw each task'sFilesfrom the record, and list the record's path in every task'sContext. Never put the record in the index'sBound inputs: an executor updates it, and that update is not bound-input drift. - Open
assets/index-template.mdwhen starting the index. Fill the header first. IfArchitectureneeds more than its few sentences (a new subsystem, several components, real integration) andBound inputsholds no approved architecture section, stop and report thatsystem-architectureowns it. - Fill
Plan set:none, or the slices in order, this plan's position, its predecessor plan's path, and the next slice's name. Write only this slice's tasks; the next slice is planned when this one lands. - Leave
Integration cadenceatplan end. Writeper taskonly when the user directly asked for per-task integration, and quote the instruction. - Leave
Out-of-task findingsatlog and report. If the request says to fix whatever turns up along the way, writefix when admitted, quote the instruction, and fill its budget. Plan an instruction with no end as that bounded policy; never copy it into a task or the goal. - If the approved UI design carries Selected visual references, copy
the complete keyed collection into the index, filling
Approved design artifact versionwith the design's identity from its ledger row, and map every Reference ID to an owning task and a conformance evaluator ID in Visual reference coverage. If a reference is missing or an ID has no owner, return the plan toui-ux-design. - Give every file and side effect exactly one owning task. If two tasks fall on the same one, add a dependency and name a single transition owner.
- If one transformation runs across many items, bind the machine-readable inventory and the output pattern instead of listing the items.
Step 2: Write the tasks
Slice vertically: one evaluable capability per task. Split only at a real check boundary. For high-risk target work, read
references/scalable-transformation.mdbefore slicing, and cite, never copy, the migration contract'sTransition and translationsection.A request: let the existing
reportcommand also write CSV. Splitting it into "add a CSV serializer" and "wire a--csvflag" cuts one capability in two: neither half is the requested behavior its own Evaluator could accept. One task, "report --csvwrites the report as CSV", judged by a test that runs the command and parses the file, is the slice. "--csvhonours the--sincefilter" earns a second task: it has its own check.Open
assets/task-template.mdbefore writing each task. FillTask ID,Depends on,Files,Exclusive ownership/effects,Contextas paths. List the plan's00-index.mdin every task'sContext, so a dispatched worker reads the Constraints and Review focus the task inherits.Fill Consumes from earlier tasks' exact Produces names and types. Backtick every name on both lines and every
Depends onID: Step 3.4's script checks no other token. Existing code and external inputs go in Context, never under an invented producer task.Fill
Evaluator: a command that ends on its own, asks for nothing, fails when it selects no tests, and returns a verdict, or a rubric with its accountable judge and deciding observations. For a UI task, copyApplicable visual referencesand give every Reference ID a Visual conformance gates row.Before writing a custom check, look in the repository and its runtime for an existing deterministic checker of that surface (test runner, linter, type checker, schema or config validator, the project's check command), and use it when it verifies the claim. Add a heavy new tool only with a stated reason.
If the task's claim rests on a security boundary (path filter, allowlist, rate limit, lock), the Evaluator tries to get past it through the real component chain: encoded separators, dot segments, case variants, input sent without the client's normalisation. For a counting limit, it also sends more simultaneous attempts than the limit and expects at most the limit to pass.
Fill
Evaluator identity/ownerso the check lives outside what the task may change. If a task may edit its own check, write the permitted scope and require RED or deliberate falsification before GREEN counts.Fill
Suggested tierwith the Model selection section ofdispatching-parallel-agents.Write
00-index.mdplus one file per task to.sdlc-skills/plans/{{YYYY-MM-DD}}-{{topic}}/or the user-set path.
Step 3: Self-review against the inputs, by name
- Trace each requirement and each accepted risk gate (the index's Trace column keeps that name: the check that covers an accepted risk) to a task or phase. Fix each uncovered requirement; cut each task that traces to nothing.
- If you find a gap or contradiction in the approved spec, here or while
writing tasks, stop planning. No task lists the spec among its
Filesor edits it. REQUIRED SUB-SKILL: invokewriting-specsfor a successor spec that names the approved one as its predecessor, and plan against the successor once it is approved. - Replace every
TBD,handle edge cases,similar to task Nwith the task it hides. Replace anExpected:value that did not come from running the command on the current tree with the value the command printed, or with a rubric when the command cannot run yet. A user-facing string the plan fixes (message, label, help text, doc sentence) that states a location, condition, or number names the file and symbol it was checked against; rewrite a claim with no such citation to what is known, or remove it. - Run
bash scripts/plan-version.sh --check-contracton the plan directory; it checksConsumes,Depends on, andImplementation disciplines. It only prints file overlap: settle eachoverlap=line by Step 1.7. Then confirm every task has an executable Evaluator or a controlled rubric, that the index has one top-level Acceptance check, and that its Constraints block holds across every task. - Name in the index's Architecture the one type or module that owns each domain fact more than one task consumes: a type, a set of kinds and where their traits live, the error type that crosses a module boundary. If two tasks each define the same fact, give it one owner and make the others consume it.
- Walk the tasks in dependency order against the bound base revision, not
against the design's description of it. Run
bash scripts/plan-files.sh --base {{revision}} {{plan dir}}and fix eachgapit prints before presenting. Then confirm at each task boundary that every input the next task reads already exists, that every deleted or renamed artifact has no surviving consumer, and that the task's own Evaluator can run on that state. - For every interface a task changes or removes (a type, a kind in a set of
kinds, a trait, a signature, an exported name, a stored format), search
the base revision for its consumers: callers, exhaustive matches,
implementations, serialized copies, in every package of the repository.
Confirm each consumer sits in this task's
Filesor in a dependent task's. A consumer no task owns is a gap: fix it before presenting. A task whoseObjectiverests on a claim about the current code (a command exists, a format carries a field) resolves that claim against the base revision; if it does not hold, stop planning: a spec claim gets a successor through Step 3.2, and a design claim returns to the owner ofsystem-architecturefor a successor design before planning resumes. - Resolve every path and symbol the plan cites against the current revision, and replace any that does not resolve. Cite a path or a symbol, never a line number.
- Confirm every selected Reference ID has a carrying task and a matching conformance evaluator.
- Fill Review focus with up to five spec-implied inputs or failure
modes that no task Evaluator exercises, or mark it
none; give everynone yetrow a check, or name it as uncovered in Step 4.1's presentation. If a task tells things apart by the shape of a string (a key, slug, name, or path used as an identity), name two different inputs that produce the same string and the task test that separates them, or have the task carry the identity as structured data. - REQUIRED SUB-SKILL: invoke
reviewing-planswhen the route is high-risk, and bring every blocker it returns to a recorded decision as that skill says; for any other plan, ask the offer questionreviewing-plansstates.
Step 4: Present, then stop
Run
bash scripts/plan-version.shon the plan directory. Readassets/mode-question.mdbefore presenting, for which modes to offer and recommend. Show the complete index and the printed version to theApproval ruleowner:Plan {{absolute path of the plan directory}} — version {{printed version}} {{goal, architecture, constraints, acceptance, trace, task list, review findings}} 1. Approve — inline, in this session 2. Approve — delegated, a subagent per task 3. Approve — delegated, in waves 4. Approve — inline, in a new session 5. Request changes 6. Reject 7. Cancel Recommendation: {{option}} — {{one sentence}}.Omit modes it does not offer, keeping the numbers. Ask this and end the turn;
clarifying-intentowns what closes it.Do not invoke either executor, create a workspace, or write code in this turn.
Under a standing default, proceed without the pause only when its scope, owner, constraints, and mode explicitly cover unseen plan versions; quote it as the answer in the Step 4.5 row.
If an approval names no mode, ask the mode question in a separate turn.
Add one row to the
External decision ledger(the ledger: add to it, never rewrite it; it sits outside the plan):Identity= the printed version,Location= the index path,State= approved,Bound evidence= theApproval ruleowner and their answer, any review report path, then themode:the mode question maps the answer to. Write nothing about approval into the index.REQUIRED SUB-SKILL: on a direct answer choosing option 1, 2, or 3, invoke the executor that mode names against the approved version before any workspace or implementation action:
executing-plansfor inline,subagent-driven-developmentfor delegated. On option 4, print the prompt the mode question gives and end the turn. This skill writes no code.
Gotchas
- A row keyed to the index's
Normative versionline survives a task-file edit; key rows to the printed version. - One plan for a design of several slices plans every later slice against a base the earlier slices will change: a 37-task plan over a sliced design grew through successors until it finished. A slice planned after its predecessor lands is planned against the code it will meet.
- A
Fileslist written from the design names the files the design discusses, not the ones the change breaks: a plan that added a kind to a set of kinds listed its owning module and missed seven exhaustive matches in another package, each found by a worker mid-task and each a successor version. The map comes first; Step 3.7 searches the base, not the design.