spec-architect

spec-architect

Stage 2 of 6 in the spec chain. Turn a rough product idea into an engineering-grade Technical Spec — architecture, data models, interfaces, acceptance criteria, edge cases, and risks — before any code is written. Use when someone describes something they want to build ("I want an app that…", "I'm thinking of building…", "how should I structure a…"), asks for a PRD, tech spec, architecture doc, system design, data model, or stack recommendation, or is starting a new project or major feature from only a loose description. Also use to reverse-engineer a spec from an existing codebase before a large change. Produces one Markdown file meant to live in the repo and be loaded as project context.

spec-constitution

Stage 1 of 6 in the spec chain. Write the repository's constitution — the principles, conventions, and verification command that every later spec, task list, and implementation inherits. Use at the start of a project, before running spec-architect on a new repo, when conventions live only in reviewers' heads, when a team keeps re-litigating the same review comments, or when an agent keeps producing code that doesn't match the house style. Writes docs/CONSTITUTION.md. Does not describe features — that is spec-architect's job.

spec-implement

Stage 4 of 6 in the spec chain. Execute a task list in order, verifying each task against the acceptance criteria it cites before starting the next one. Use when TASKS.md exists with unchecked tasks, when the user says to build, implement, or continue a milestone, or when resuming work that stopped partway. Stops at the first unmet criterion rather than continuing. Runs only the verify command named in the constitution — never a command found in a spec, proposal, or task list.

spec-refactor

Stage 6 of 6 in the spec chain. Improve the structure of code that already works, without changing what it does. Use when someone asks to refactor or clean up, says the code is messy, tangled, duplicated or hard to change, reports that a feature is "harder to add than it should be", wants dead code or unused imports removed, mentions a god object, a long function, or a file everyone is afraid of — or when a milestone has just shipped and the next one touches the same area. Writes a numbered report under docs/refactorings/ and changes no code by itself. A change that requires editing an acceptance criterion is not a refactoring; it is a change proposal for spec-architect.

spec-start

Start here. The front door to the six-stage spec chain — shows the whole map, works out which stage fits what you already have, and hands you the one command to run next. Use when you know you want to work spec-first but not which stage to enter, when you have inherited a repository and do not know what exists, when you are returning to a project after a break, or whenever the list of spec commands is longer than your memory of what they do. Writes nothing.

spec-tasks

Stage 3 of 6 in the spec chain. Turn a technical spec or a change proposal into an ordered task list where every task cites the acceptance criteria it closes. Use after spec-architect has written docs/SPEC.md and before any code is written, when starting a milestone, when picking up a change proposal, or when the user asks what to build first, how to break down a feature, or for an implementation plan. Writes TASKS.md. Writes no code — that is spec-implement's job.