draft-shells

Name: draft-shells
Author: tobihagemann

3installs29forks

How to install draft-shells?

tobihagemann/turbo/draft-shells

$npx -y skills add tobihagemann/turbo --skill draft-shells

Installs into the current project.

Summary

Decompose a specification file into shells with YAML frontmatter. Each shell captures the wiring invariants (Produces, Consumes, Covers) and high-level Implementation Steps without committing to file paths. Use when the user asks to \"draft shells\", \"create shells\", \"break sp

Files · 1

View on GitHub

SKILL.md

1	# Draft Shells
2
3	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.
4
5	## Task Tracking
6
7	At the start, use `TaskCreate` to create a task for each step:
8
9	1. Resolve the source spec
10	2. Decompose into shells
11	3. Resolve open questions
12	4. Write shell files
13	5. Present summary
14
15	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.
16
17	## Step 1: Resolve the Source Spec
18
19	Determine which spec to decompose using these rules in order:
20
21	1. Explicit path — If the user passed a file path, use it
22	2. Explicit slug — If a slug was passed, resolve to `.turbo/specs/<slug>.md`
23	3. Single file — Glob `.turbo/specs/*.md`. If exactly one file exists, use it
24	4. Most recent — If multiple files exist, use the most recently modified
25	5. Legacy fallback — If `.turbo/specs/` does not exist but `.turbo/spec.md` exists, use it
26	6. Nothing found — If no spec exists, nothing to decompose; stop
27
28	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`.
29
30	State the resolved spec path and target shell directory before continuing.
31
32	Read the spec and identify:
33	- Scope — total surface area of work
34	- Work categories — UI, backend, data layer, infrastructure, tests, documentation, tooling
35	- 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.
36	- Dependencies — which pieces must exist before others can start
37	- Greenfield vs existing — is there an established codebase to work within
38	- Open questions — decisions the spec deferred that will need to be answered at implementation time
39
40	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.
41
42	## Step 2: Decompose Into Shells
43
44	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.
45
46	### Find the Seams
47
48	Identify where the work can be cut and the order pieces must land:
49
50	- 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).
51	- 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.
52
53	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.
54
55	### Keep Combined
56
57	Some pieces must share a shell regardless of the count the user picks:
58
59	- Tightly-coupled pieces — when UI, API, and tests are inseparable, keep them in one shell.
60	- 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.
61	- 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 wor

People who liked this also viewed

6 picks

Type

draft-shells

3installs29forks

View on GitHub

How to install draft-shells?

tobihagemann/turbo/draft-shells

$npx -y skills add tobihagemann/turbo --skill draft-shells

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Draft Shells
2
3	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.
4
5	## Task Tracking
6
7	At the start, use `TaskCreate` to create a task for each step:
8
9	1. Resolve the source spec
10	2. Decompose into shells
11	3. Resolve open questions
12	4. Write shell files
13	5. Present summary
14
15	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.
16
17	## Step 1: Resolve the Source Spec
18
19	Determine which spec to decompose using these rules in order:
20
21	1. Explicit path — If the user passed a file path, use it
22	2. Explicit slug — If a slug was passed, resolve to `.turbo/specs/<slug>.md`
23	3. Single file — Glob `.turbo/specs/*.md`. If exactly one file exists, use it
24	4. Most recent — If multiple files exist, use the most recently modified
25	5. Legacy fallback — If `.turbo/specs/` does not exist but `.turbo/spec.md` exists, use it
26	6. Nothing found — If no spec exists, nothing to decompose; stop
27
28	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`.
29
30	State the resolved spec path and target shell directory before continuing.
31
32	Read the spec and identify:
33	- Scope — total surface area of work
34	- Work categories — UI, backend, data layer, infrastructure, tests, documentation, tooling
35	- 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.
36	- Dependencies — which pieces must exist before others can start
37	- Greenfield vs existing — is there an established codebase to work within
38	- Open questions — decisions the spec deferred that will need to be answered at implementation time
39
40	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.
41
42	## Step 2: Decompose Into Shells
43
44	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.
45
46	### Find the Seams
47
48	Identify where the work can be cut and the order pieces must land:
49
50	- 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).
51	- 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.
52
53	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.
54
55	### Keep Combined
56
57	Some pieces must share a shell regardless of the count the user picks:
58
59	- Tightly-coupled pieces — when UI, API, and tests are inseparable, keep them in one shell.
60	- 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.
61	- 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 wor

People who liked this also viewed

6 picks

Type