/drafting

name: drafting
description: Use when you have an approved design or requirements for a multi-step task and need an implementation plan, before touching code.

Drafting

A plan is a set of contracts Sonnet implementers can execute without asking questions, and also the input to the 0.3 engine: a machine-readable task graph, interface stubs, per-task time predictions, a predicted schedule and probe plans. Write it so scripts can parse it. Code the implementer would write anyway burns Opus time and invites transcription errors.

Any build with 2+ tasks runs through `superlite:swarm`: load it before writing the plan. Never use `general-purpose` agents for build or review work.

Save to `docs/plans/YYYY-MM-DD-<topic>.md`. When called from `superlite:inventing`, append to its doc instead. If the spec covers independent subsystems, write one plan per subsystem.

Lint, extract what's stable, fix the rest

`lint --stable` splits the plan into STABLE and FIX tasks (with reasons) and writes `.superlite/stable.json`. A task is stable when its own checks pass, every Consumes has a clean Produces line somewhere (even in an unstable task), it has no taskgraph edge to an unstable task, and it is not on a flagged `CHAIN:`. Plan-level issues (SPEC coverage, `CHAIN:`, the size cap, `MISSED TARGET`) never block stable tasks. `dispatch` offers only stable tasks. The order is fixed: lint, dispatch the whole stable set (`lint --stable` ends with `DISPATCH NOW: ...`), and only then patch the FIX tasks (edits or a full rewrite, as many rounds as needed), re-lint and dispatch the newly stable ones. No agent waits on plan polishing. Dispatched tasks are frozen: a rewrite keeps their blocks byte-identical, else lint reports `FROZEN:` and the change becomes a follow-up fix task, not a restart. `**Status:** draft` stays as an optional manual hold: `next_tasks` and `dispatch` skip draft tasks and their dependents, and draft tasks may keep placeholders.

Write for the split

**Who orchestrates sets the mode** (`superlite-cli orchestrator status`).

• **Human orchestrator** (the human validates the plan before it runs), two phases:

1. Write the review plan: `docs/plans/<date>-<topic>.review.md`, plain words, innomd-drawable diagrams and a few key code snippets, no taskgraph (`review-plan.md`). Nothing is built, dispatched or written except this file before the human's approving reply. With no question batch, list "Run the whole test suite at finish?" (default no) under "Decisions you can change"; the approving reply may set it. 2. When `open_in_harness` is on (`superlite-cli agent_specs status`), open the plan for the user first (After writing below; the harness's open row in `using-superlite/references/<harness>-tools.md`). Show it in plain text, not AskUserQuestion: the path, a five-line summary and "Reply approve to start, or tell me what to change". END THE TURN and do nothing else until the human replies. 3. Read their answer. If you understand it as approval, send approve: `superlite-cli orchestrator approve --review <path>`. Do not pass their words through and do not ask them to retype approve. If you understand it as changes with no approval, revise and ask again. `lint --stable`, `dispatch`, `wave0` and `build_prime` refuse until then. 4. Write the machine plan `docs/plans/<date>-<topic>.md` from the approved review plan, in the order below (same tasks and scope, header `**Review plan:** <path>`), then `lint --stable`, and dispatch the stable set in the same turn. 5. It patches the FIX tasks, re-lints and dispatches the newly stable ones without asking again, as long as each fix stays inside what was approved (sizes, splits, stubs, field corrections). A fix that changes scope, an interface the human saw, or the spec coverage is decided without asking the human: record it as `Ruling: [scope] <decision> - <why> - <cost if wrong>`; `superlite-cli finish` lists these under "Changed from the approved plan". AI orchestrator: no review plan, straight to the machine plan.

• **AI orchestrator** (hands off: the user pre-approved, said "decide yourself", or an agent runs the session): write a queue that starts building while the fixes are made. Lint splits what you write into stable tasks, which build now, and fix tasks, which wait. Follow all six rules. Record open choices as `Ruling:` lines.

In both modes, write for the split:

0. **Lessons.** Before sizing tasks, run `superlite-cli lessons brief --agent drafter --files <paths the plan will touch>` (no `--task`: tasks have no ids yet) and honour what it prints. 1. **One Write, written as if in chunks.** Write the plan whole, in one Write, but order it as if it were written in chunks, so the first tasks stand alone as a stable prefix: the header, Global constraints and the main diagram with its `%% taskgraph`; then, optionally, a Wave 0 skeleton task (`Kind: mechanical`, `Model: haiku`; if you omit it, `superlite-cli wave0` builds the skeleton brief from your Produces lines and Global constraints, so state the language and test command there); then the root and producer tasks (no incoming edges), each with exact `Produces` lines, the correct `Kind` and a size inside the band; then the consumers, each after its producers. Every block is complete, with no placeholders, so lint can mark it stable and the prefix dispatches before any later task is fixed. 2. **Producers first, with exact `Produces` lines.** Lint resolves each `Consumes` against some task's `Produces` line, so write producers before their consumers: exact name, parameter types and return type. A consumer is then stable the moment it's written, even while its producer is still building or being fixed. 3. **Finish each task block before starting the next.** No placeholders, and every field filled. A half-written task is a fix task, and so is everything with an edge to it. 4. **Size each task for the band as you write it.** Fill Components, LOC owned and Tests honestly, and aim for 2-5 m