--- name: Factory Spec slug: factory-spec-2 category: AI Engineering description: Factory Spec turns a ready-to-spec queue item into an approved plan through four human review gates. Use it when scope must be decided before code exists, such as for a feature, migration, or other interactive planning task. github: "https://github.com/addyosmani/factory/tree/main/template/.claude/skills/factory-spec" language: Shell stars: 174 forks: 13 install: "npx degit https://github.com/addyosmani/factory/tree/main/template/.claude/skills/factory-spec ~/.claude/skills/factory-spec" installs_to: ~/.claude/skills/factory-spec source_path: template/.claude/skills/factory-spec/SKILL.md collection_size: 12 category_size: 3475 collection_url: "https://dirskills.com/collections/addyosmani/factory" added: 2026-09-07T05:22:07.661Z last_synced: 2026-09-07T05:22:07.661Z canonical_url: "https://dirskills.com/skills/factory-spec-2" --- # Factory Spec Factory Spec turns a ready-to-spec queue item into an approved plan through four human review gates. Use it when scope must be decided before code exists, such as for a feature, migration, or other interactive planning task. **Install:** ```bash npx degit https://github.com/addyosmani/factory/tree/main/template/.claude/skills/factory-spec ~/.claude/skills/factory-spec ``` ## README # Factory spec This skill exists because the cheapest place to fix a decision is before any code encodes it. Once a model has written a thousand lines, changing direction is expensive and every instinct is to patch instead. **This skill is interactive.** It stops and waits for a human. Do not run it inside an unattended routine; a routine that approves its own spec has no gates at all. Read `docs/factory/CONTRACT.md` and `docs/factory/CHARTER.md` before gate 1. ## Gates Four, in order. Stop at each one. Never merge two gates into a single pass. Never proceed on an inferred approval: "looks good" on gate 1 is not approval of gate 2. Write each gate's output into `docs/factory/specs/FQ-/` as its own file, and track approvals in `docs/factory/specs/FQ-/00-status.md`. ### Gate 1 - Product (`01-product.md`) No technical content whatsoever. If you find yourself naming a file or a function, you are in the wrong gate. - The user problem, stated as a person's problem - What success looks like, measurably - A short announcement written as if the change already shipped - Plain HTML mockups for any screen involved, in `mockups/` - **What we are deliberately not doing** That last item is the one people skip and the one that saves the most time. It is also where the kill decision lives: if the honest answer to "should this exist" is no, this gate is where that is cheap to say. **STOP. Ask for approval.** ### Gate 2 - Architecture (`02-architecture.md`) - Which existing systems and modules this touches - New endpoints, data structures, and their shapes - The end-to-end call flow, in order - External dependencies, and whether each is genuinely required - Which `LOAD_BEARING` paths are involved - What could break elsewhere **STOP. Ask for approval.** For anything touching a load-bearing path, also run the `factory-critic` subagent against this document before asking, and include its output. ### Gate 3 - Program design (`03-design.md`) - Exact file paths, new and modified - Type signatures and function contracts, **no implementations** - The call stack for the main flow - The test list: what will be tested and what each test proves - **The three decisions you are least confident about** That last section is the highest-value part of this gate. It is where a reviewer can intervene before the uncertainty is buried under working code. **STOP. Ask for approval.** ### Gate 4 - Slices (`04-slices.md`) Decompose into vertical slices. Each slice must be independently shippable, independently testable, and small enough to review in one sitting. - **Slice 0 is a tracer bullet**: end to end, mostly mocked, proving the shape works. - Each later slice replaces one mock with real behavior. - Each slice gets its own queue entry with its own `done_when`. Once approved, create or update one GitHub issue per slice and apply `factory:ready-to-implement`. Create or update its `factory-handoff:v1` comment with the approved `done_when`, expected files, gate level, and confidence. Also write each slice into the `QUEUE.md` snapshot. The issue label and comment are the handoff back to the unattended part of the factory. **STOP. Ask for approval before writing the queue entries.** After the approved handoff, write a unique `spec` run record under `docs/factory/runs/`. ## Status file `00-status.md` tracks state so the spec survives a context reset or a week away: ``` item: FQ- gate_1_product: approved 2026-08-16 | pending | rejected gate_2_architecture: pending gate_3_design: not-started gate_4_slices: not-started slices_completed: 0 / ? open_questions: - ``` ## For migrations specifically If this spec covers a migration, gate 2 must answer one question before anything else: **What is the oracle?** An old or unlaunched project usually has the thinnest test coverage in the portfolio, which means a migration can compile, typecheck, pass every existing test, and still behave differently. Green does not mean equivalent. So the first slices are not migration slices: 1. Make it build on the current stack 2. Make it typecheck 3. Pin current behavior with characterization tests and golden-master snapshots 4. **Only then** migrate, wide and fast, against the oracle you just built This inverts the usual reading of back-pressure. Instead of accepting the verification budget you have and limiting autonomy to match, you go build a bigger budget first and claim the autonomy it buys. Each of those four steps is itself a clean factory job. If gate 2 cannot name the oracle, the migration is not ready and no amount of agent throughput fixes that.