spequa 0.9.1

Spequafy CLI, part of GitHub Spequa. A tool to bootstrap your projects for Spec-Driven Development (SDD).

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.1-constitution — Define project principles and architectural constraints (once per project)
2. /spequa.3-spequafy — Describe a feature in natural language, get a structured specification
3. /spequa.5-plan — Generate a technical implementation plan from the spec
4. /spequa.6-tasks — Break the plan into dependency-ordered, executable tasks
5. /spequa.10-implement — Execute the task list

See the pipeline diagram for the full pipeline including optional quality gates (/spequa.4-clarify, /spequa.8-analyze, /spequa.9-test).

Key Features

• Template System — Structured templates for specs, plans, tasks, checklists, and project constitutions
• Multi-Agent Support — Works with 18 AI agents: 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
• 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/ and agent commands
spequafy --help              # Verify installation

To update later: pip install --upgrade spequa && spequafy update

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.

Command name mapping (plugin form → workflow file):

Plugin command	Workflow file
spequa:4-clarify	.agent/workflows/spequa.4-clarify.md
spequa:5-plan	.agent/workflows/spequa.5-plan.md
spequa:3-spequafy	.agent/workflows/spequa.3-spequafy.md
spequa:6-tasks	.agent/workflows/spequa.6-tasks.md
spequa:8-analyze	.agent/workflows/spequa.8-analyze.md
spequa:10-implement	.agent/workflows/spequa.10-implement.md
spequa:9-test	.agent/workflows/spequa.9-test.md
spequa:13-code-review	.agent/workflows/spequa.13-code-review.md
spequa:14-create-pull-request	.agent/workflows/spequa.14-create-pull-request.md
spequa:16-close	.agent/workflows/spequa.16-close.md
spequa:1-constitution	.agent/workflows/spequa.1-constitution.md
spequa:3.0-diagnose	.agent/workflows/spequa.3.0-diagnose.md
spequa:7-checklist, spequa:15-comet-review, spequa:11-docs, spequa:4.1-expert-decision, spequa:0-pipeline	(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)
│   └── 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
├── 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

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