Draft Shells

Draft Shells

Decompose a specification file into shells at .turbo/shells/<spec-slug>-NN-<title>.md. Each shell represents one unit of work for a separate Codex session.

Task Tracking

At the start, use update_plan to track each step, restating any remaining steps of a parent workflow alongside them:

1. Resolve the source spec
2. Decompose into shells
3. Resolve open questions
4. Write shell files
5. Present summary

If the confirmed shell count is one, the Single-Shell Bail-out at the end of Step 2 calls update_plan with a shortened step list (removing the remaining steps) and exits.

Step 1: Resolve the Source Spec

Determine which spec to decompose using these rules in order:

1. Explicit path — If the user passed a file path, use it
2. Explicit slug — If a slug was passed, resolve to .turbo/specs/<slug>.md
3. Single file — Glob .turbo/specs/*.md. If exactly one file exists, use it
4. Most recent — If multiple files exist, use the most recently modified
5. Legacy fallback — If .turbo/specs/ does not exist but .turbo/spec.md exists, use it
6. Nothing found — If no spec exists, nothing to decompose; stop

The slug of the resolved spec becomes the prefix for shell file names: a spec at .turbo/specs/<slug>.md produces shells at .turbo/shells/<slug>-NN-<title>.md. For the legacy fallback, use slug legacy.

State the resolved spec path and target shell directory before continuing.

Read the spec and identify:

• Scope — total surface area of work
• Work categories — UI, backend, data layer, infrastructure, tests, documentation, tooling
• Spec requirements — enumerate the R<N> IDs from the spec's ## Requirements section. Every R-id must be tracked in at least one shell's Covers field.
• Dependencies — which pieces must exist before others can start
• Greenfield vs existing — is there an established codebase to work within
• Open questions — decisions the spec deferred that will need to be answered at implementation time

If the spec has no ## Requirements section or contains no R<N>-numbered items, use request_user_input with two options: re-run $draft-spec (then restart Step 1 with the resulting spec) or stop so the user can add a ## Requirements section with enumerated R<N> IDs manually. Shells depend on stable R-ids for coverage tracking.