agentleFS
thinkmorestupidlessthinkmorestupidless/ankka/.claude/skills/speckit-design/SKILL.md

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.

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
  1. Distinctive:

    Never print a question and stop.

    line 50
  2. Distinctive:

    Stop, having written nothing, and say why, when:

    line 54
  3. Very specific:

    Run them in order, from specify or from the stage --from names.

    line 72
  4. Very specific:

    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 …

    line 106
  5. Very specific:

    Run /speckit-analyze again: Stop when its report holds no finding above LOW.

    line 133
  6. Very specific:

    After each stage that wrote files, commit what it wrote, with a Conventional Commits header whose scope is the feature's number: docs(NNN): …

    line 139

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

  1. The branch is the default branch. Its name is git symbolic-ref --short refs/remotes/origin/HEAD with the remote's origin/ taken off (that command prints origin/main, never main), or main when there is no origin/HEAD. When git branch --show-current prints the same name, say: make a branch for the feature first, git switch -c NNN-short-name, with the next spec number.
  2. bdd or review is not installed. Both must be listed under installed: in .specify/extensions.yml. Name the one missing; the design writes scenarios through bdd, and the build it hands over to cannot review without review.
  3. --from names a stage whose inputs are missing (the table below). Name the earliest stage that produces them, and the command that resumes there.
  4. AskUserQuestion is not among this session's tools (a headless claude -p run, 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.

StageNeedsRunsLeaves
specifya description; a branch that is not the default/speckit-specify <description>; its after_specify hook writes the scenariosspecs/NNN-name/spec.md, checklists/requirements.md, .specify/feature.json, features/, GLOSSARY.md
clarifyspec.md/speckit-clarify; its before_clarify hook runs the checker first## Clarifications in the spec; proposed glossary terms settled
checkfeatures/, GLOSSARY.mdthe repository's checkernothing when green
planspec.md with no [NEEDS CLARIFICATION]; the checker green/speckit-planplan.md, research.md, data-model.md, contracts/, quickstart.md
tasksplan.md/speckit-taskstasks.md
analyzetasks.md/speckit-analyze, then the remediation loopedits 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:

  1. Read ## Declined remediations in research.md. A finding whose remediation is listed there is neither applied nor asked about again.
  2. Apply every remediation that changes neither a decision nor a scenario: a decision is an answer under ## Clarifications or a decision in research.md; a scenario is a scenario in features/. Edit the spec, plan or tasks as the report says. Do not ask.
  3. 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 remediations in research.md (create the heading if it is missing), one line each: the finding's summary and the person's reason.
  4. A remediation that changes a scenario is made in the feature file first; then the check stage runs again before analyze does.
  5. Run /speckit-analyze again. 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-build

Nothing 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.