nitrix
1afdd0a462
Human-readable reference for the clarify → plan → tasks → analyze → implement loop and the file structure it produces. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2.6 KiB
Spec-Kit Workflow
How to take a feature from spec to working code.
The Loop
clarify → plan → tasks → analyze → implement
Every step produces files in specs/NNN-feature-name/. Review after each step before moving on.
Steps
1. Clarify the spec (optional)
/speckit.clarify
Asks up to 5 targeted questions about gaps or ambiguities in the spec. Answers get folded back into spec.md. Skip this if the spec is already solid.
2. Create the implementation plan
/speckit.plan
Reads spec.md, checks it against the constitution, and produces:
| File | Content |
|---|---|
plan.md |
Technical design, architecture decisions, contracts |
research.md |
Background research (if needed) |
data-model.md |
Entity definitions (if new entities are involved) |
contracts/ |
API contracts (if applicable) |
Review this carefully. The plan shapes everything downstream.
3. Generate the task list
/speckit.tasks
Reads the plan and generates tasks.md — an ordered, dependency-aware task list. Tasks marked [P] can run in parallel.
4. Check consistency (optional)
/speckit.analyze
Cross-checks spec, plan, and tasks for contradictions, gaps, or drift. Non-destructive — only reports, doesn't change files.
5. Implement
/speckit.implement
Executes the tasks from tasks.md phase by phase. Follows TDD: writes tests first, then implementation. Stops at checkpoints so you can verify.
File structure
Each feature lives in its own directory:
specs/
007-view-event/
spec.md # What and why (from /speckit.specify or migration)
plan.md # How (from /speckit.plan)
research.md # Background research (from /speckit.plan)
data-model.md # Entity definitions (from /speckit.plan)
contracts/ # API contracts (from /speckit.plan)
tasks.md # Ordered task list (from /speckit.tasks)
Starting a brand new feature
If the feature doesn't have a spec yet:
/speckit.specify
Describe what you want in plain language. This creates the spec directory and spec.md from the template. Then continue with the loop above.
Tips
- Don't skip the review. Each step builds on the previous one. Garbage in, garbage out.
- The spec is the source of truth. If something in the plan contradicts the spec, fix the spec first.
- You can re-run steps. Changed the spec after planning? Run
/speckit.planagain. - Constitution governs everything. Principles in
.specify/memory/constitution.mdoverride ad-hoc decisions.