Metadata-Version: 2.4
Name: spequa
Version: 0.9.0
Summary: Spequafy CLI, part of GitHub Spequa. A tool to bootstrap your projects for Spec-Driven Development (SDD).
License: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: httpx[socks]
Requires-Dist: packaging>=23.0
Requires-Dist: platformdirs
Requires-Dist: pyyaml>=6.0
Requires-Dist: readchar
Requires-Dist: rich
Requires-Dist: truststore>=0.10.4
Requires-Dist: typer
Provides-Extra: mcp
Requires-Dist: fastmcp>=1.0.0; extra == 'mcp'
Requires-Dist: gitpython>=3.1.0; extra == 'mcp'
Requires-Dist: pydantic>=2.0.0; extra == 'mcp'
Provides-Extra: test
Requires-Dist: pytest-cov>=4.0; extra == 'test'
Requires-Dist: pytest>=7.0; extra == 'test'
Description-Content-Type: text/markdown

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

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Cross-Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)](#)

---

## 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](docs/pipeline.md) 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](docs/existing-project.md#supported-agents)
- **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](https://docs.astral.sh/uv/) which manages Python versions automatically.

### Install from PyPI (Recommended)

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

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

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

See the [installation guide](docs/installation.md) to compare install methods.

### Alternative: Claude Code Plugin (native slash commands)

Install spequa as a [Claude Code plugin](https://docs.claude.com/claude-code/plugins) 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):**

```bash
# 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):**

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

**Update after workflow edits:**

```bash
claude plugin marketplace update equa-local
```

**Uninstall:**

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

Plugin manifest lives at [`.claude-plugin/plugin.json`](.claude-plugin/plugin.json); the local marketplace is defined in [`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json). Command files under [`.claude/commands/`](.claude/commands/) mirror the canonical workflows in [`.agent/workflows/`](.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](docs/quickstart.md) — Step-by-step SDD workflow
- [Installation](docs/installation.md) — Connecting to the shared toolkit
- [Adding to an Existing Project](docs/existing-project.md) — Bootstrapping, overrides, CI/CD
- [Upgrading & Syncing](docs/upgrade.md) — Auto-sync, pinning, troubleshooting
- [Pipeline](docs/pipeline.md) — Full SDD pipeline flow with quality gates

## License

This project is licensed under the MIT License — see [LICENSE](LICENSE) for details.
