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

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

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

No spec may skip from DRAFT to IMPLEMENTED. Each phase produces its artifact.

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`

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.

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 results
pipeline-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

Old command names (/speckit.*, /equa-spec.*) are no longer recognized. Use the /spequa.* prefix exclusively.

Platform Architecture

Compliance & Security

Feature Specifications

Releases

Developer Onboarding

Business

Reference & Templates

Spequa Workflow

Spequa Workflow

Pipeline Phases (0–16)

Directory Structure

Per-Spec Directory

Artifact Requirements

ID Conventions

Spec IDs

Task IDs

Status Lifecycle

Visual Diagrams Convention

When Diagrams Are Generated

Format Requirements

Autonomous Pipeline Mode

Gate Configuration

Quality Signal Auto-Pause

Spec-Hash Integrity

Pipeline Artifacts

Closure Hard Gates

Queue Management

Templates

Installation

Naming History

​Spequa Workflow

​Pipeline Phases (0–16)

​Directory Structure

​Per-Spec Directory

​Artifact Requirements

​ID Conventions

​Spec IDs

​Task IDs

​Status Lifecycle

​Visual Diagrams Convention

​When Diagrams Are Generated

​Format Requirements

​Autonomous Pipeline Mode

​Gate Configuration

​Quality Signal Auto-Pause

​Spec-Hash Integrity

​Pipeline Artifacts

​Closure Hard Gates

​Queue Management

​Templates

​Installation

​Naming History

Spequa Workflow

Pipeline Phases (0–16)

Directory Structure

Per-Spec Directory

Artifact Requirements

ID Conventions

Spec IDs

Task IDs

Status Lifecycle

Visual Diagrams Convention

When Diagrams Are Generated

Format Requirements

Autonomous Pipeline Mode

Gate Configuration

Quality Signal Auto-Pause

Spec-Hash Integrity

Pipeline Artifacts

Closure Hard Gates

Queue Management

Templates

Installation

Naming History