speckit-design
Skill3 starsChanged 5 days agoApache-2.0View on GitHub
Design a feature in one run on the design model: specify, its clarifications, clarify, the checker, plan, tasks, and analyze with every remediation applied; asks the person only what they must decide, through AskUserQuestion, and ends by printing the build command.
In this repository16 other files it gives its agents.
- .claude/rules/agents.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- speckit-analyzeSkill
- speckit-bdd-checkSkill
- speckit-bdd-featuresSkill
- speckit-buildSkill
- speckit-checklistSkill
- speckit-clarifySkill
- speckit-constitutionSkill
- speckit-convergeSkill
- speckit-implementSkill
- speckit-planSkill
- speckit-reviewSkill
- speckit-specifySkill
- speckit-tasksSkill
- speckit-taskstoissuesSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 2 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 50
Never print a question and stop.
- Distinctive: line 54
Stop, having written nothing, and say why, when:
- Very specific: line 72
Run them in order, from specify or from the stage --from names.
- Very specific: line 106
Run the checker the way the repository runs it: just features when the Justfile has that recipe, else just check, else the checker line of …
- Very specific: line 133
Run
/speckit-analyzeagain: Stop when its report holds no finding above LOW. - Very specific: line 139
After each stage that wrote files, commit what it wrote, with a Conventional Commits header whose scope is the feature's number: docs(NNN): …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Design a feature
One run takes a feature from a description to an analysed task list: the spec, its scenarios in the
living features and the glossary, the plan and its design artifacts, and tasks.md, with every
remediation analyze proposes applied. The person is asked only what they must decide. The build is a
separate command, /speckit-build, on its own model, started in a new session when this one ends.
This command runs on the model its skill's model: line names, for as long as this turn lasts. A
question asked by ending the turn would hand the rest of the run to the session's own model, so the
whole run is one turn.
User input
$ARGUMENTS--from <stage>: resume at a stage of an existing feature (below). The rest of the input is ignored, except after--from specify, where it is the description.- Anything else: the feature description, passed whole to
/speckit-specify. - Nothing: ask for a description through AskUserQuestion (one option, "I'll describe it", whose "Other" text is the description). An answer with no description stops the run, having written nothing.
The question rule
Hold this for every stage, including the stages' own instructions and their hooks:
Every question to the person goes through the AskUserQuestion tool. Never end the turn to ask.
Wherever a stage says to present a question, a table of options, a [NEEDS CLARIFICATION] marker,
a checker finding or a remediation and to wait for the person's reply, ask it through
AskUserQuestion instead: the stage's options become the options (at most four; a recommended one
first, labelled "(Recommended)"), each option's description carries its implication, and the
person's free-text answer arrives through "Other". Up to four independent questions may go in one
call; a question whose options depend on an earlier answer waits for it. Then continue the stage
with the answer exactly as the stage says to use it: specify writes it in place of the marker,
clarify records it under ## Clarifications and in the section it touches.
Never print a question and stop. A run that ends with a question in its last message has failed.
Before anything runs
Stop, having written nothing, and say why, when:
- The branch is the default branch. Its name is
git symbolic-ref --short refs/remotes/origin/HEADwith the remote'sorigin/taken off (that command printsorigin/main, nevermain), ormainwhen there is noorigin/HEAD. Whengit branch --show-currentprints the same name, say: make a branch for the feature first,git switch -c NNN-short-name, with the next spec number. bddorreviewis not installed. Both must be listed underinstalled:in.specify/extensions.yml. Name the one missing; the design writes scenarios throughbdd, and the build it hands over to cannot review withoutreview.--fromnames a stage whose inputs are missing (the table below). Name the earliest stage that produces them, and the command that resumes there.- AskUserQuestion is not among this session's tools (a headless
claude -prun, a subagent). Say the design needs an interactive Claude Code session and stop. Offer no way round it: a design whose decisions were defaulted is not a design.
The stages
Run them in order, from specify or from the stage --from names. Each stage is the existing
command, invoked through the Skill tool exactly as the person would type it, so its own hooks fire
inside it as they do when it is run alone.
| Stage | Needs | Runs | Leaves |
specify | a description; a branch that is not the default | /speckit-specify <description>; its after_specify hook writes the scenarios | specs/NNN-name/spec.md, checklists/requirements.md, .specify/feature.json, features/, GLOSSARY.md |
clarify | spec.md | /speckit-clarify; its before_clarify hook runs the checker first | ## Clarifications in the spec; proposed glossary terms settled |
check | features/, GLOSSARY.md | the repository's checker | nothing when green |
plan | spec.md with no [NEEDS CLARIFICATION]; the checker green | /speckit-plan | plan.md, research.md, data-model.md, contracts/, quickstart.md |
tasks | plan.md | /speckit-tasks | tasks.md |
analyze | tasks.md | /speckit-analyze, then the remediation loop | edits to the spec, plan and tasks; a last report with nothing above low |
--from never rewrites what an earlier stage left. --from specify on a feature directory that
already holds a spec is refused: edit the spec by hand, or resume at clarify. Without a
description after it, it is asked for as when nothing is typed.
specify
Invoke /speckit-specify with the description. When it would present its clarification tables and
wait, ask them through AskUserQuestion (the question rule) and let it write each answer into the
spec. When its after_specify hook has run, .specify/feature.json names the feature directory;
every later stage reads it.
clarify
Invoke /speckit-clarify. Its before_clarify hook runs the checker and turns each finding into a
question, and it then asks up to five of its own, one at a time; each goes through AskUserQuestion,
and each answer is encoded before the next is asked. Every *Proposed.* glossary term the spec
introduced is settled here: ask whether the terms stand as one question listing them, with "accept
all" recommended when no term collides with an existing one.
check
Run the checker the way the repository runs it: just features when the Justfile has that recipe,
else just check, else the checker line of .specify/extensions/bdd/bdd-config.yml with check
--root . --glossary <glossary> --features <features> --specs <specs>. Green is 0 findings. A
finding is settled as /speckit-bdd-check settles one: a refused synonym or a repeated scenario is
fixed without asking; a contradiction or an undefined word is a question. Run the checker again
until it is green. plan does not run before it is.
plan, tasks
Invoke /speckit-plan, then /speckit-tasks. When the plan finds a decision the spec left open, it
is a question, not a guess.
analyze
/speckit-analyze reports and changes nothing. After each report:
- Read
## Declined remediationsinresearch.md. A finding whose remediation is listed there is neither applied nor asked about again. - Apply every remediation that changes neither a decision nor a scenario: a decision is an
answer under
## Clarificationsor a decision inresearch.md; a scenario is a scenario infeatures/. Edit the spec, plan or tasks as the report says. Do not ask. - Ask about every other remediation, through AskUserQuestion, with "apply" and "decline" as the
options and what each would change as their descriptions. A declined one is added under
## Declined remediationsinresearch.md(create the heading if it is missing), one line each: the finding's summary and the person's reason. - A remediation that changes a scenario is made in the feature file first; then the
checkstage runs again before analyze does. - Run
/speckit-analyzeagain. Stop when its report holds no finding above LOW. After the third round, stop anyway and show what remains, through AskUserQuestion: "proceed to build with these" or "stop here".
Commits
After each stage that wrote files, commit what it wrote, with a Conventional Commits header whose
scope is the feature's number: docs(NNN): specify <short name>, docs(NNN): clarify …,
docs(NNN): plan …, docs(NNN): tasks for …, docs(NNN): analyze …, remediations applied. Use the
repository's commit hooks; a hook that refuses a commit is fixed, never skipped.
The end
Record that the design finished: append to the feature's research.md a section
## Design finished
<date>: analyze reported nothing above LOW.(or, when the person chose "proceed to build with these" after the third round, <date>: the
person proceeded with <n> findings above LOW, listing them), and commit it: in the analyze commit
when the last round changed files, alone (docs(NNN): design finished) when it changed nothing.
The build refuses a task list without this section: it is how it knows the analysis ran to
its end. A run stopped by "stop here" records nothing.
Then print, in this order: the feature directory; the task count (0 of N); the checker's result; the
last analyze report's findings by severity; the decisions the person made in this run, one line
each; then exactly:
The design is ready. Start the build with:
/speckit-buildNothing is pushed. The build is started by the person, in a new session in the same checkout, so it reads only what this run wrote.
Repairing one stage
Each stage is still its own command (/speckit-specify, /speckit-clarify, /speckit-plan,
/speckit-tasks, /speckit-analyze). Run one alone to repair it, or resume here with --from.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

