Skip to main content

​
Spec-Kit Workflow

Last Verified: March 2026
Spec-kit is the spec-driven development pipeline used by the command-center-so repository. All features, bug fixes, and significant refactors follow this pipeline before any implementation work begins. The pipeline enforces measurable acceptance criteria, code-cited evidence, and user-authorized closure. The authoritative source for all conventions is the project constitution at .specify/memory/constitution.md (currently v1.4.0).

​
Pipeline Phases

Each phase produces one or more artifacts in .specify/specs/{id}-{slug}/ and is invoked via a slash command or Cursor skill.
PhaseCommandPurposePrimary Output
Constitution/speckit.constitutionEstablish or amend governing principles.specify/memory/constitution.md
Specify/speckit.specifyDefine the problem, current state, and acceptance criteriaspec.md
Clarify/speckit.clarifyResolve ambiguities with code-cited evidence (11-category taxonomy)clarifications.md
Plan/speckit.planDesign phased implementation with AC mapping and researchplan.md, research.md, data-model.md
Tasks/speckit.tasksBreak plan into numbered, dependency-ordered taskstasks.md
Implement/speckit.implementExecute tasks with checklist gates and phased context re-readingCode changes, verification-results.md
Every code claim in a spec must cite an exact file path and line number verified by reading the actual source. A task is not done until its verify step passes and the user authorizes closure.

​
Directory Structure

​
Top-Level .specify/ Layout

.specify/
├── specs/           # Feature specifications (one directory per spec)
├── templates/       # Artifact templates (spec, plan, tasks, checklist)
├── memory/          # Project constitution and persistent context
└── queue/           # Portfolio queue items and session briefs
    └── done/        # Archived queue files for completed specs

​
Per-Spec Directory

Each spec lives in .specify/specs/{id}-{slug}/ where {id} is a 3-digit zero-padded sequential number and {slug} is kebab-case: 
.specify/specs/125-speckit-visual-diagrams/
├── spec.md                    # Feature specification (required)
├── clarifications.md          # Resolved ambiguities (required)
├── plan.md                    # Implementation plan (required)
├── tasks.md                   # Task breakdown (required)
├── research.md                # Phase 0 research output
├── data-model.md              # Entity/schema design
├── verification-results.md    # Post-implementation AC evidence
├── contracts/                 # API contracts
├── checklists/                # Quality validation checklists
├── diagrams/                  # Mermaid .mmd visual diagrams
└── evidence/                  # Validation reports, screenshots

​
Artifact Requirements

Every spec must produce the required artifacts before implementation begins.
ArtifactLocationRequired
spec.md.specify/specs/{id}-{slug}/spec.mdYes
clarifications.md.specify/specs/{id}-{slug}/clarifications.mdYes
plan.md.specify/specs/{id}-{slug}/plan.mdYes
tasks.md.specify/specs/{id}-{slug}/tasks.mdYes
verification-results.md.specify/specs/{id}-{slug}/verification-results.mdPost-implementation
diagrams/.specify/specs/{id}-{slug}/diagrams/*.mmdConditional
diagrams/ is generated when the plan has 3+ phases with multi-system scope (architecture diagram), or when tasks has 5+ tasks with dependencies (task dependency and key dependency diagrams). See the Visual Diagrams section below.

​
ID Conventions

​
Spec IDs

3-digit zero-padded, sequential: 010, 011, …, 125, 126. Duplicate ID prefixes are prohibited; if a collision is discovered, the newer spec must be renumbered.

​
Task IDs

Prefix S{specId}-T with zero-padded 3-digit task numbers. Example: S125-T001, S125-T002. Tasks are sequential across all phases within a spec.

​
Status Lifecycle

StatusMeaning
DRAFTspec.md exists, open questions remain
SPECIFIEDAll clarifications resolved, clarifications.md complete
PLANNEDplan.md written with phased approach
TASKEDtasks.md created with dependency graph
IN PROGRESSImplementation actively underway
IMPLEMENTEDAll tasks done, all ACs verified, awaiting user sign-off
DONEUser has explicitly approved closure
No spec may skip from DRAFT to IMPLEMENTED. Each phase produces its artifact.

​
Visual Diagrams Convention

Spec 125 added persistent Mermaid diagram generation to the pipeline. Diagrams are conditionally generated based on spec complexity.

​
When Diagrams Are Generated

Diagram TypeTriggerOutput Files
Architecture diagramPlan has 3+ phases with multi-system scopediagrams/architecture.mmd
Task dependency diagramTasks has 5+ tasks with inter-task dependenciesdiagrams/task-dependencies.mmd
Key dependency diagramTasks has 5+ tasks with dependenciesdiagrams/key-dependencies.mmd

​
Format Requirements

All .mmd files must include the dark theme directive as the first line: 
%%{init: {'theme': 'dark'}}%%
Diagrams are also embedded inline in the parent markdown (plan.md or tasks.md) as fenced Mermaid code blocks. The inline version is the canonical source; the .mmd file is an extracted copy.

​
Autopilot Integration

Autopilot Gate 3 (post-plan) and Gate 4 (post-tasks) log a soft warning when qualifying specs lack expected diagrams. This is non-blocking.

​
Autopilot Mode

The full pipeline can be executed automatically using /speckit.autopilot, which chains all phases in a single session: specify, clarify, plan, tasks, analyze, implement. All existing phase rules and artifact requirements still apply.

​
Gate Configuration

GateStepDefault Mode
Gate 1post-specifyPAUSE
Gate 2post-clarifyPAUSE
Gate 3post-planAUTO
Gate 4post-tasksPAUSE
Gate 5post-analyzeAUTO (always PAUSE on CRITICAL)
Override flags:
  • --no-gates — All gates run in AUTO mode
  • --pause-at <step> — Add a PAUSE at a specific gate
  • --skip-clarify — Remove the clarify phase and Gate 2
  • --from <step> — Resume from a specific phase (specify, clarify, plan, tasks, analyze, implement)
  • --agent-mode — Fully autonomous execution (all gates AUTO, quality signals still halt)

​
Quality Signal Auto-Pause

The pipeline scans each artifact for quality signals that indicate unresolved issues. Auto-pause fires regardless of --no-gates or --agent-mode:
  • Canonical marker: [NEEDS CLARIFICATION] (bracket-uppercase)
  • Scanner regex: /\[needs[\s._-]*clarification\]/i (catches common variants)
  • Additional signals: **Unresolved** items in clarifications.md, unmapped ACs in plan.md or tasks.md

​
Spec-Hash Integrity

Every generated artifact includes a spec-hash field (first 8 hex characters of SHA-256 of spec.md at generation time). On resume with --from, each prerequisite artifact’s hash is compared against the current spec.md. A hash mismatch warns in user-mode and auto-halts in agent-mode.

​
Pipeline Artifacts

Autopilot produces two additional tracking files:
  • pipeline-state.md — Phase statuses, timestamps, and gate results
  • pipeline-report.md — AC-by-AC scorecard with evidence (written on completion or halt)

​
Additional Commands

The pipeline includes optional enhancement commands not required by the standard workflow but recommended for high-priority (P0/P1) specs:
CommandPurpose
/speckit.analyzeCross-artifact consistency analysis (read-only). Detects gaps, duplications, and inconsistencies.
/speckit.checklistGenerate quality checklists that validate requirements completeness (“unit tests for English”).
/speckit.taskstoissuesConvert tasks from tasks.md into GitHub issues for project tracking.

​
Closure Hard Gates

A spec must not be marked DONE until all of the following are true:
  1. Every task in tasks.md is marked [x] Done with date
  2. Every AC in spec.md maps to a PASS in verification-results.md
  3. npm run lint exits 0 with no new errors
  4. npx tsc --noEmit exits 0
  5. npm test passes (all existing + new tests)
  6. Automated validation evidence in pipeline-report.md with all ACs at PASS, confirmed by recorded UI/UX demo testing; or user has explicitly approved
  7. If autopilot was used, pipeline-state.md shows all gates PASS

​
Queue Management

The portfolio queue lives at .specify/queue/README.md. It tracks every spec with status, priority, milestone, and linkage to spec artifacts. After completing all tasks for a spec, the implementer updates the queue entry to IMPLEMENTED. Only the user may advance status to DONE. When a spec reaches DONE, its queue file is moved from .specify/queue/ to .specify/queue/done/. The queue README row is updated to reflect DONE status. Spec artifacts in .specify/specs/{id}-{slug}/ remain in place as the permanent record.

​
Templates

Artifact templates are maintained in .specify/templates/:
TemplatePurpose
spec-template.mdUser stories, acceptance scenarios, functional requirements
plan-template.mdTechnical context, constitution check, project structure, phased design
tasks-template.mdTask breakdown format, dependency diagram section, MVP strategy
checklist-template.mdQuality validation checklist format
constitution-template.mdConstitution amendment format
The spec-kit workflow is available through Cursor skills in ~/.cursor/skills/. Each phase has both a base skill and an enhanced speckit-* variant:
SkillDescription
specify / speckit-specifyCreate feature specifications from natural language
clarify / speckit-clarifyStructured clarification with 11-category ambiguity taxonomy
plan / speckit-planImplementation planning with research phase and constitution check (+ architecture diagram for multi-system specs)
tasks / speckit-tasksDependency-ordered task breakdown with parallel markers (+ dependency diagram when 5+ tasks)
implement / speckit-implementExecute tasks with checklist gates and phased re-reading
speckit-analyzeCross-artifact consistency analysis (read-only)
speckit-autopilotFull pipeline orchestration (specify through implement)
speckit-checklistRequirements quality validation checklists
speckit-constitutionManage project constitution with semantic versioning
speckit-taskstoissuesConvert tasks to GitHub issues