Spequa

A CLI and template system for Specification-Driven Development (SDD)

Bootstrap projects with structured specifications, implementation plans, and task breakdowns that AI coding agents can execute.

---

What is Spequa?

Spequa provides a methodology and toolchain where specifications drive implementation, not the other way around. Instead of writing code and documenting after the fact, you define what you want in structured specs, and AI agents generate implementation from those specs.

The core workflow:

1. /spequa.00.00-install-spequafy-kit — Install or update Spequa for the active agent
2. /spequa.00.10-run-pipeline — Run the orchestrated SDD loop
3. /spequa.00.30-nhitl-unblock-blocker — Capture/resolve no-human-in-the-loop pause and restart events
4. /spequa.00.35-recursive-blocker-loop — Route blockers into child specs or atomic stop reports before the goal loop stops
5. /spequa.00.40-autonomy-retro — Analyze transcript user inputs, root causes, and avoidable autonomy friction
6. /spequa.00.50-origin-research — Check existing specs, branches, PR lanes, and command context before creating a new feature home
7. /spequa.00.60-formalize-codex-plan — Convert a drafted Codex plan into the correct branch/spec folder and run the full pipeline
8. /spequa.00.70-roadmap — Rank queued roadmap specs, pre-assign numbers, pre-create worktree lanes, and enforce the single publication slot
9. /spequa.01.00-constitution — Define project principles and architectural constraints (once per project)
10. /spequa.01.10-align-spequa-kit-to-project — Align installed commands with repo rules and tooling (runs after install/update)
11. /spequa.2-problems — Frame the problem in problems.md
12. /spequa.2.0.1-define-problem ... /spequa.2.0.14-publish-problem-documentation — Optional atomic PROBLEMO section route
13. /spequa.2.1-problem-quality-gate — Evaluate the problem before spec generation
14. /spequa.3-spequafy — Turn the approved framing or a direct feature request into spec.md
15. /spequa.5-plan — Generate a technical implementation plan from the spec
16. /spequa.6-tasks — Break the plan into dependency-ordered, executable tasks
17. /spequa.6.1-taskstoissues — Mandatory task issue and milestone evidence gate after task generation
18. /spequa.10.00-implement-plan — Execute the task list
19. /spequa.10.10-design-system-gate — Verify current design-system parity before PR review

For read-only Ask / Research / Audit / Plan work between stages, use /spequa.00.20-ask-only-read-only.

See the pipeline diagram for the full pipeline including clarification, checklist, analysis, test, docs, PR, and closure gates.

Key Features

• Template System — Structured templates for specs, plans, tasks, checklists, and project constitutions
• Multi-Agent Support — Works across the configured agent surfaces: Claude Code, GitHub Copilot, Gemini CLI, Cursor, Codex, Windsurf, Kiro, Roo, and more
• Domain Analysis — Extract business entities, rules, and integration patterns from JSON/CSV data files
• NHITL Recovery Log — Capture pause, rerun, kickstart, prompt, and resume actions as structured JSONL evidence with automation recommendations
• Autonomy Retro Metrics — Analyze transcript user inputs, score avoidable human friction, and export a tracking workbook
• Design System Gate — Block PR review until UI/component changes prove current design-system, Storybook, Figma/prototype, and pattern-library parity
• Origin Research Gate — Scan repo-local specs, docs, commands, branches, and worktrees before creating new feature artifacts, then persist the routing report as origin-research.md
• Extension System — Plugin architecture with manifest schema, official + community catalogs
• Cross-Platform — Every automation script has both Bash and PowerShell variants
• MCP Server — Expose spequa tools via the Model Context Protocol

Quick Start

Prerequisites

• Python 3.11+ (check with python3 --version)
• Git
• An AI coding agent (Claude Code, Copilot, Gemini CLI, etc.)

macOS users: The system Python is 3.9 which is too old. Install Python 3.11+ via brew install python@3.13 or use uv which manages Python versions automatically.

Install from PyPI (Recommended)

# Install with uv (recommended — handles Python version automatically)
uv tool install spequa

# Or with pipx (isolated install)
pipx install spequa

# Or with pip (requires Python 3.11+ in your environment)
pip install spequa

Then scaffold your project:

cd your-project
spequafy init --ai claude    # Sets up .spequa/, aligns the repo, and installs agent commands
spequafy --help              # Verify installation

To update later: uv tool upgrade spequa && spequafy update --ai <agent> --ai-skills. To rerun alignment manually after repo architecture changes: spequafy align --all-detected.

Alternative: Submodule Install (Auto-Syncing)

For teams that want the toolkit to auto-sync with upstream on every command:

/path/to/spequa/scripts/bash/spequa-bootstrap.sh

See the installation guide to compare install methods.

Alternative: Claude Code Plugin (native slash commands)

Install spequa as a Claude Code plugin so every workflow is available as a native slash command. Commands appear under the spequa: namespace (e.g. /spequa:clarify, /spequa:plan), autocomplete in the command picker, and stay in sync with the source workflows via symlinks in commands/.

One-time install (local, from this repo clone):

# From anywhere:
claude plugin marketplace add /path/to/spequa    # this repo's root
claude plugin install spequa@equa-local
# Restart Claude Code (or open a new session) to pick up commands

Team install (once the repo is pushed to git):

claude plugin marketplace add <github-org>/spequa
claude plugin install spequa@equa-local

Update after workflow edits:

claude plugin marketplace update equa-local

Uninstall:

claude plugin uninstall spequa@equa-local
claude plugin marketplace remove equa-local

Plugin manifest lives at .claude-plugin/plugin.json; the local marketplace is defined in .claude-plugin/marketplace.json. Command files under .claude/commands/ mirror the canonical workflows in .agent/workflows/; after editing workflows, run claude plugin marketplace update so the plugin picks up changes.

Alternative: Codex Plugin (tracked router skills)

The repository also tracks a Codex plugin wrapper at .codex-plugin/plugin.json. Its generated router skills live under skills/ and load the bundled prompt catalog from .codex/prompts/.

After editing command templates, regenerate and verify the Codex plugin surface:

python3 scripts/generate-codex-plugin.py
python3 scripts/generate-codex-plugin.py --check

The Bash and PowerShell template sync scripts run the same generator automatically, using check mode for dry runs.

Claude Code command name mapping (plugin form → workflow file):

Plugin command	Workflow file
spequa:00.00-install-spequafy-kit	.agent/workflows/spequa.00.00-install-spequafy-kit.md
spequa:00.20-ask-only-read-only	.agent/workflows/spequa.00.20-ask-only-read-only.md
spequa:00.30-nhitl-unblock-blocker	.agent/workflows/spequa.00.30-nhitl-unblock-blocker.md
spequa:00.35-recursive-blocker-loop	.agent/workflows/spequa.00.35-recursive-blocker-loop.md
spequa:00.40-autonomy-retro	.agent/workflows/spequa.00.40-autonomy-retro.md
spequa:00.50-origin-research	.agent/workflows/spequa.00.50-origin-research.md
spequa:00.60-formalize-codex-plan	.agent/workflows/spequa.00.60-formalize-codex-plan.md
spequa:00.70-roadmap	.agent/workflows/spequa.00.70-roadmap.md
spequa:01.00-constitution	.agent/workflows/spequa.01.00-constitution.md
spequa:01.10-align-spequa-kit-to-project	.agent/workflows/spequa.01.10-align-spequa-kit-to-project.md
spequa:2-problems	.agent/workflows/spequa.2-problems.md
spequa:2.0.1-define-problem	.agent/workflows/spequa.2.0.1-define-problem.md
spequa:2.0.2-contextualize-problem	.agent/workflows/spequa.2.0.2-contextualize-problem.md
spequa:2.0.3-identify-affected	.agent/workflows/spequa.2.0.3-identify-affected.md
spequa:2.0.4-scope-quantify-problem	.agent/workflows/spequa.2.0.4-scope-quantify-problem.md
spequa:2.0.5-analyze-root-causes	.agent/workflows/spequa.2.0.5-analyze-root-causes.md
spequa:2.0.6-assess-impact	.agent/workflows/spequa.2.0.6-assess-impact.md
spequa:2.0.7-challenge-assumptions	.agent/workflows/spequa.2.0.7-challenge-assumptions.md
spequa:2.0.8-define-success-preconditions	.agent/workflows/spequa.2.0.8-define-success-preconditions.md
spequa:2.0.9-document-constraints	.agent/workflows/spequa.2.0.9-document-constraints.md
spequa:2.0.10-validate-with-stakeholders	.agent/workflows/spequa.2.0.10-validate-with-stakeholders.md
spequa:2.0.11-score-prioritize	.agent/workflows/spequa.2.0.11-score-prioritize.md
spequa:2.0.12-link-potential-solutions	.agent/workflows/spequa.2.0.12-link-potential-solutions.md
spequa:2.0.13-ideate-solutions-if-none	.agent/workflows/spequa.2.0.13-ideate-solutions-if-none.md
spequa:2.0.14-publish-problem-documentation	.agent/workflows/spequa.2.0.14-publish-problem-documentation.md
spequa:2.1-problem-quality-gate	.agent/workflows/spequa.2.1-problem-quality-gate.md
spequa:3-spequafy	.agent/workflows/spequa.3-spequafy.md
spequa:3.0-diagnose	.agent/workflows/spequa.3.0-diagnose.md
spequa:4-clarify	.agent/workflows/spequa.4-clarify.md
spequa:5-plan	.agent/workflows/spequa.5-plan.md
spequa:6-tasks	.agent/workflows/spequa.6-tasks.md
spequa:7-checklist	.agent/workflows/spequa.7-checklist.md
spequa:8-analyze	.agent/workflows/spequa.8-analyze.md
spequa:9-test	.agent/workflows/spequa.9-test.md
spequa:10.00-implement-plan	.agent/workflows/spequa.10.00-implement-plan.md
spequa:10.10-design-system-gate	.agent/workflows/spequa.10.10-design-system-gate.md
spequa:11-docs	.agent/workflows/spequa.11-docs.md
spequa:13-code-review	.agent/workflows/spequa.13-code-review.md
spequa:13.1-pr-readiness-gate	.agent/workflows/spequa.13.1-pr-readiness-gate.md
spequa:13.2-local-ci-gate	.agent/workflows/spequa.13.2-local-ci-gate.md
spequa:13.2.1-ci-workflow-parity-gate	.agent/workflows/spequa.13.2.1-ci-workflow-parity-gate.md
spequa:13.2.2-python-matrix-gate	.agent/workflows/spequa.13.2.2-python-matrix-gate.md
spequa:13.2.3-markdownlint-gate	.agent/workflows/spequa.13.2.3-markdownlint-gate.md
spequa:13.2.4-generated-surface-parity-gate	.agent/workflows/spequa.13.2.4-generated-surface-parity-gate.md
spequa:13.2.5-zero-stop-local-gate	.agent/workflows/spequa.13.2.5-zero-stop-local-gate.md
spequa:13.2.6-spec-artifact-integrity-gate	.agent/workflows/spequa.13.2.6-spec-artifact-integrity-gate.md
spequa:13.2.7-pr-metadata-dry-run-gate	.agent/workflows/spequa.13.2.7-pr-metadata-dry-run-gate.md
spequa:13.2.8-package-distribution-gate	.agent/workflows/spequa.13.2.8-package-distribution-gate.md
spequa:13.2.9-docs-build-gate	.agent/workflows/spequa.13.2.9-docs-build-gate.md
spequa:13.2.10-secret-scan-gate	.agent/workflows/spequa.13.2.10-secret-scan-gate.md
spequa:14-create-pull-request	.agent/workflows/spequa.14-create-pull-request.md
spequa:14.1-pr-checks	.agent/workflows/spequa.14.1-pr-checks.md
spequa:14.2-pr-linkage-audit	.agent/workflows/spequa.14.2-pr-linkage-audit.md
spequa:14.3-pr-feedback-loop	.agent/workflows/spequa.14.3-pr-feedback-loop.md
spequa:14.3.1-request-copilot-review	.agent/workflows/spequa.14.3.1-request-copilot-review.md
spequa:14.4-browser-session-preflight	.agent/workflows/spequa.14.4-browser-session-preflight.md
spequa:15-comet-review	.agent/workflows/spequa.15-comet-review.md
spequa:16-close	.agent/workflows/spequa.16-close.md
spequa:00.10-run-pipeline, spequa:4.1-expert-decision, spequa:5.1-research, spequa:6.1-taskstoissues, spequa:12-score-docs	(same pattern)

Note: the older dot-form invocations (/spequa.4-clarify) come from placing the workflow files directly in ~/.claude/commands/ (filename = command id). The plugin form uses the <plugin>:<command> namespace convention and is the recommended path because it's versioned, uninstallable, and shareable.

Project Structure

spequa-main/
├── src/
│   ├── spequafy_cli/           # CLI application (Typer + Rich; includes `_nhitl.py`)
│   └── spequa_mcp/           # MCP server (FastMCP)
├── templates/                 # Master SDD templates
│   ├── spec-template.md       # Feature specification
│   ├── plan-template.md       # Implementation plan
│   ├── tasks-template.md      # Task breakdown
│   ├── checklist-template.md  # Quality checklist
│   ├── constitution-template.md # Project constitution
│   ├── commands/              # AI agent slash commands
│   └── skills/                # Static agent skills
├── extensions/                # Extension system + catalogs
├── scripts/                   # Bash + PowerShell automation
├── sample-data/               # Example datasets (financial, ecommerce, CRM)
├── tests/                     # Pytest test suite
└── docs/                      # Documentation (DocFX)

The SDD Methodology

Spequa implements Specification-Driven Development — a methodology where specifications are the primary artifact and code is the generated output.

Core principles:

• Specifications as the source of truth — code serves specifications, not the other way around
• Executable specifications — precise enough to generate working systems
• Constitutional governance — immutable architectural principles (Articles I-IX) enforced through template gates
• Test-first thinking — test scenarios are part of the specification, not an afterthought

Documentation

• Quick Start Guide — Step-by-step SDD workflow
• Installation — Connecting to the shared toolkit
• Adding to an Existing Project — Bootstrapping, overrides, CI/CD
• Upgrading & Syncing — Auto-sync, pinning, troubleshooting
• Pipeline — Full SDD pipeline flow with quality gates

License

Copyright (c) 2026 Equa, Inc.

This project is licensed under the MIT License — see LICENSE for details.