| name | using-superspec |
| description | Use when the user mentions superspec, when starting a spec-driven change, when unsure which workflow stage applies, or when the repo contains docs/specs/ or docs/specs/changes/ and work is about to begin — establishes source-of-truth rules and routes to the correct stage skill (brainstorming, writing-specs, review-changes, plan-review, execution, code-review) before any other action. |
| metadata | {"tags":["tech:markdown","spec-driven","workflow","router"]} |
Using Superspec
Overview
Superspec is a skills-only spec-driven workflow. Stable specs under docs/specs/{domain}/spec.md are the source of truth. Changes are proposed as deltas under docs/specs/changes/{name}/ and merged into stable specs only after code review.
Violating the letter of the rules is violating the spirit of the rules.
If you were dispatched as a subagent to execute a specific task, skip this skill and do exactly what your dispatcher asked.
If you think there is even a 1% chance a superspec skill applies to the work in front of you, you ABSOLUTELY MUST invoke that skill.
IF A SKILL APPLIES, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
This is not negotiable. You cannot rationalize your way out of this.
The Iron Law
NO SPEC WORK WITHOUT ROUTING TO THE CORRECT STAGE FIRST
Source-of-truth Rules
- Stable specs win.
docs/specs/{domain}/spec.md is the only authoritative requirements source.
- Deltas are pending. Files under
docs/specs/changes/{name}/ are proposals, not truth, until code-review merges them.
- Plans are derived.
tasks.md cites requirements; it does not invent them.
- Precedence: explicit user instructions > superspec skills > default behavior. When they conflict, ask the user.
- If requirements shift mid-execution, STOP and return to
writing-specs. Never invent requirements in code.
Stage Routing
| Entry condition | Stage skill |
|---|
| Raw idea, vague request, "help me build X" | brainstorming |
| Requirements settled in chat, writing/updating a spec or delta | writing-specs |
| Delta specs authored, need validation before planning | review-changes |
| Change approved, need an implementation plan | plan-review |
| Plan approved, implementing tasks | execution |
| All tasks complete, need to verify and merge deltas | code-review |
See references/workflow.md for the full stage DAG.
Red Flags — STOP and Route
| Thought | Reality |
|---|
| "This is too simple to need a spec" | Simple changes break assumptions. Invoke brainstorming. |
| "I'll just patch the stable spec directly" | Stable specs change only through the code-review merge. Use a delta. |
| "I know what the user wants, skip brainstorming" | Requirements MUST be settled with the user before spec writing. |
| "Requirements shifted but I can keep coding" | STOP. Return to writing-specs. |
| "I'll merge deltas now and review later" | Deltas merge only after code-review sign-off. |
Integration
Terminal state is invoking the correct stage skill above. Do NOT start writing code, editing specs, or answering implementation questions until you have routed.
