> ## Documentation Index
> Fetch the complete documentation index at: https://docs.equa.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Spequa Workflow

> The spec-driven development pipeline for Equa projects: numbered phases 0–16, artifacts, conventions, and autonomous pipeline mode

# Spequa Workflow

> **Last Verified:** 2026-04-12 | **Renamed from:** spec-kit / speckit (pre-April 2026)
> **Toolkit:** [spequa](https://github.com/EQUAStart/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`):

```mermaid theme={null}
flowchart LR
    P0["0 Pipeline"] --> P1["1 Constitution"]
    P1 --> P2["2 Problems"]
    P2 --> P3["3 Spequafy"]
    P3 --> P4["4 Clarify"]
    P4 --> P5["5 Plan"]
    P5 --> P6["6 Tasks"]
    P6 --> P7["7 Checklist"]
    P7 --> P8["8 Analyze"]
    P8 --> P9["9 Test"]
    P9 --> P10["10 Implement"]
    P10 --> P11["11 Docs"]
    P11 --> P12["12 Score"]
    P12 --> P13["13 Code Review"]
    P13 --> P14["14 Create PR"]
    P14 --> P15["15 Comet Review"]
    P15 --> P16["16 Close"]
```

| #    | 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
```

<Note>
  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.
</Note>

## 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         |

<Note>
  `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.
</Note>

## 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

```mermaid theme={null}
flowchart LR
    DRAFT --> SPECIFIED --> PLANNED --> TASKED
    TASKED --> IN_PROGRESS["IN PROGRESS"] --> IMPLEMENTED --> DONE
```

| 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:

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. Lint exits 0 with no new errors
4. Type checking exits 0
5. All tests pass (existing + new)
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 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:

```bash theme={null}
# 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.