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 Claude Code session.

## Task Tracking

At the start, use `TaskCreate` to create a task for each step:

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 marks tasks 3-5 deleted via `TaskUpdate` 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 `AskUserQuestion` 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.

## Step 2: Decompose Into Shells

Split the spec into shells, each a unit of work for a separate Claude Code session. The user sets the final count in the gate at the end of this step. The analysis here makes that choice informed: find where the work can be cut, name what must stay together, then recommend a count with options.

### Find the Seams

Identify where the work can be cut and the order pieces must land:

- **Dependency order** — foundational work before dependent work: setup and scaffolding (project init, config, CI), then the data and domain layer (models, schemas, types), then core business logic, then the API and service layer, then UI and frontend, then integration and end-to-end concerns. A hard dependency is a strong seam: a later piece cannot be drafted or expanded until an earlier piece's concrete output exists (generated types, framework wiring, patterns later sessions survey against).
- **Natural boundaries** — candidate cut points where one piece's output is another's input. A spec's suggested groupings are a starting point; treat them as candidate seams the count gate may regroup.

A seam is weak when cutting it buys nothing: the two sides share no ordering dependency and would sit comfortably in one session. Shared-nothing independence alone is a weak seam. A seam is strong when one side must exist before the other, or when keeping both sides in one session would overload it: too much code to read in full, too many distinct conventions to absorb, or too much output for one window.

### Keep Combined

Some pieces must share a shell regardless of the count the user picks:

- **Tightly-coupled pieces** — when UI, API, and tests are inseparable, keep them in one shell.
- **Atomic ripple** — when a breaking change to a shared interface requires every consumer across modules to update in lockstep, the change and all consumer updates land in one shell regardless of size. Splitting leaves intermediate states that break dependents.
- **Reachability** — each shell leaves the codebase fully integrated, with no components unreachable from the project's entry points. Bundle tightly-coupled producer/consumer pairs into one shell, or have a foundation shell include a minimal integration point (a single working endpoint or CLI command) that proves the code is reachable. When a shell builds infrastructure a later shell consumes, name that consumer in the Produces field.

These set the ceiling on the count: the work cannot split past the point where a combined piece would break.

Items folded into a shell go into that shell's Implementation Steps. If several folded items have no clear home, group them into a single "minor fixes" shell at the end.

### Wiring Invariants

For each shell, identify the structural contract with the rest of the decomposition:

- **Produces** — What this shell creates that other shells (or the final system) can use. List concrete artifacts at the conceptual level: modules, types, endpoints, data models, UI screens, migration files. File paths are filled in at expansion time.
- **Consumes** — What this shell depends on that must already exist. Either listed in a prior shell's Produces (and that producing shell named directly in this shell's frontmatter `depends_on`), or marked "from existing codebase" if it predates this decomposition. Every Consumes entry must be traceable to a source.
- **Covers spec requirements** — Which `R<N>` IDs from the spec's `## Requirements` section this shell implements. The union of Covers across all shells must equal the full set of R-ids in the spec. Every R-id must appear in at least one shell's Covers. Write one R-id per bullet in the Step 4 template. For partial coverage of a single