Spequa Workflow
Last Verified: 2026-04-12 | Renamed from: spec-kit / speckit (pre-April 2026)
Toolkit: spequa v0.9.0 | Install: pip install spequa or editable install from /tools/spequa
Spequa is the spec-driven development pipeline used across all Equa repositories. 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 (created per-repo via /spequa.1-constitution).
Pipeline Phases (0–16)
The pipeline has 17 numbered phases, invoked via Claude Code slash commands (/spequa.N-name):
| # | Command | Purpose | Primary Output |
|---|
| 0 | /spequa.0-pipeline | Autonomous sequential pipeline loop — runs all phases with gate checks | pipeline-state.md, pipeline-report.md |
| 1 | /spequa.1-constitution | Create or update the project constitution | constitution.md |
| 2 | /spequa.2-problems | Frame the problem space, constraints, and success criteria | Problem statement in spec.md |
| 3 | /spequa.3-spequafy | Create or update the feature specification | spec.md |
| 3.0 | /spequa.3.0-diagnose | Structured bug-fix workflow with root cause analysis | spec.md (diagnostic variant) |
| 3.1 | /spequa.3.1-analyze-domain | Analyze data files and extract domain models | Domain model data for spec.md |
| 4 | /spequa.4-clarify | Identify underspecified areas, ask up to 5 clarification questions | clarifications.md |
| 4.1 | /spequa.4.1-expert-decision | Senior domain expert decision between clarification options | Decision record |
| 5 | /spequa.5-plan | Design phased implementation with AC mapping | plan.md, research.md, data-model.md |
| 5.1 | /spequa.5.1-research | Focused research to resolve technical unknowns during planning | research.md |
| 6 | /spequa.6-tasks | Generate actionable, dependency-ordered task breakdown | tasks.md |
| 6.1 | /spequa.6.1-taskstoissues | Convert tasks into GitHub issues | GitHub issues |
| 7 | /spequa.7-checklist | Generate a custom quality checklist for the feature | checklist.md |
| 8 | /spequa.8-analyze | Cross-artifact consistency and quality analysis (read-only) | Analysis report |
| 9 | /spequa.9-test | Generate test plan and test stubs from spec artifacts | Test files |
| 10 | /spequa.10-implement | Execute the implementation plan, processing all tasks | Code changes, verification-results.md |
| 11 | /spequa.11-docs | Validate documentation structural integrity and cross-references | Doc validation report |
| 12 | /spequa.12-score-docs | Scorecard benchmark rubric for scoring audited documentation | Scorecard |
| 13 | /spequa.13-code-review | 14-gate PR code review checklist | Review verdict |
| 14 | /spequa.14-create-pull-request | Create a PR with pre-flight validation and self-review checklist | GitHub PR |
| 14.1 | /spequa.14.1-pr-checks | Wait for CI checks, summarize pass/fail, gate progression | CI status report |
| 15 | /spequa.15-comet-review | Delegate full PR review to Comet browser sidecar | Browser-based review verdict |
| 15.1 | /spequa.15.1-comet-pr-review | 14-gate PR code review via Comet browser | Browser-based code review |
| 16 | /spequa.16-close | Validate spec completion, capture evidence, formally close | Closure report |
Directory Structure
Per-Spec Directory
Each spec lives in specs/{id}-{slug}/ where {id} is a 3-digit zero-padded sequential number and {slug} is kebab-case:
specs/125-visual-diagrams/
├── spec.md # Feature specification (required)
├── clarifications.md # Resolved ambiguities (required)
├── plan.md # Implementation plan (required)
├── tasks.md # Task breakdown (required)
├── checklist.md # Quality validation checklist
├── research.md # Phase 5.1 research output
├── data-model.md # Entity/schema design
├── verification-results.md # Post-implementation AC evidence
├── contracts/ # API contracts
├── diagrams/ # Mermaid .mmd visual diagrams
└── evidence/ # Validation reports, screenshots
Some repos (particularly command-center-so) may still use a .specify/specs/ path from the pre-rename era. New specs should use specs/ at the repo root. The global platform-level specs live in /equa-specs/ at the workspace root.
Artifact Requirements
Every spec must produce the required artifacts before implementation begins.
| Artifact | Location | Required |
|---|
spec.md | specs/{id}-{slug}/spec.md | Yes |
clarifications.md | specs/{id}-{slug}/clarifications.md | Yes |
plan.md | specs/{id}-{slug}/plan.md | Yes |
tasks.md | specs/{id}-{slug}/tasks.md | Yes |
checklist.md | specs/{id}-{slug}/checklist.md | Yes (phase 7) |
verification-results.md | specs/{id}-{slug}/verification-results.md | Post-implementation |
diagrams/ | specs/{id}-{slug}/diagrams/*.mmd | Conditional |
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. A single global numbering sequence is used across all Equa repos (decided April 2026).
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
| Status | Meaning |
|---|
| DRAFT | spec.md exists, open questions remain |
| SPECIFIED | All clarifications resolved, clarifications.md complete |
| PLANNED | plan.md written with phased approach |
| TASKED | tasks.md created with dependency graph |
| IN PROGRESS | Implementation actively underway |
| IMPLEMENTED | All tasks done, all ACs verified, awaiting user sign-off |
| DONE | User has explicitly approved closure |
Visual Diagrams Convention
Diagrams are conditionally generated based on spec complexity.
When Diagrams Are Generated
| Diagram Type | Trigger | Output Files |
|---|
| Architecture diagram | Plan has 3+ phases with multi-system scope | diagrams/architecture.mmd |
| Task dependency diagram | Tasks has 5+ tasks with inter-task dependencies | diagrams/task-dependencies.mmd |
| Key dependency diagram | Tasks has 5+ tasks with dependencies | diagrams/key-dependencies.mmd |
.mmd files must include the dark theme directive as the first line:
%%{init: {'theme': 'dark'}}%%
plan.md or tasks.md) as fenced Mermaid code blocks. The inline version is the canonical source; the .mmd file is an extracted copy.
Autonomous Pipeline Mode
The full pipeline can be executed automatically using /spequa.0-pipeline, which chains all 17 phases in a single session with gate checks, self-correction on failures, pauses for clarification, and scoring against the R1-R10 rubric.
Gate Configuration
| Gate | Step | Default Mode |
|---|
| Gate 1 | post-specify | PAUSE |
| Gate 2 | post-clarify | PAUSE |
| Gate 3 | post-plan | AUTO |
| Gate 4 | post-tasks | PAUSE |
| Gate 5 | post-analyze | AUTO (always PAUSE on CRITICAL) |
Quality Signal Auto-Pause
The pipeline scans each artifact for quality signals that indicate unresolved issues. Auto-pause fires regardless of gate 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
The autonomous pipeline produces two additional tracking files:
pipeline-state.md — Phase statuses, timestamps, and gate resultspipeline-report.md — AC-by-AC scorecard with evidence (written on completion or halt)
Closure Hard Gates
A spec must not be marked DONE until all of the following are true:
- Every task in
tasks.md is marked [x] Done with date
- Every AC in
spec.md maps to a PASS in verification-results.md
- Lint exits 0 with no new errors
- Type checking exits 0
- All tests pass (existing + new)
- Automated validation evidence in
pipeline-report.md with all ACs at PASS, confirmed by recorded UI/UX demo testing; or user has explicitly approved
- If autopilot was used,
pipeline-state.md shows all gates PASS
Queue Management
The portfolio queue 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.
Templates
Artifact templates are maintained alongside the spequa toolkit source:
| Template | Purpose |
|---|
spec-template.md | User stories, acceptance scenarios, functional requirements |
plan-template.md | Technical context, constitution check, project structure, phased design |
tasks-template.md | Task breakdown format, dependency diagram section, MVP strategy |
checklist-template.md | Quality validation checklist format |
constitution-template.md | Constitution amendment format |
Installation
Spequa is available as a Python package and as Claude Code slash commands:
# PyPI install (any project)
pip install spequa
# Editable install from workspace (recommended for Equa dev)
pip install -e /Users/shawnowen/dev/equa/tools/spequa
# Verify installation — slash commands appear in Claude Code
# /spequa.0-pipeline through /spequa.16-close
Naming History
| Era | Name | Commands | Active Period |
|---|
| v1 | spec-kit / speckit | /speckit.specify, /speckit.clarify, etc. | 2026-01 → 2026-03 |
| v2 | equa-spec | /equa-spec.specify, /equa-spec.pipeline, etc. | 2026-03 → 2026-04 |
| v3 (current) | spequa | /spequa.0-pipeline through /spequa.16-close | 2026-04 → present |
/speckit.*, /equa-spec.*) are no longer recognized. Use the /spequa.* prefix exclusively.
