Summary

This project addresses AI coding's common pitfalls: premature execution and specification drift. It provides a "spec-first," contract-driven AI programming workflow plugin, merging planning and disciplined execution. Targeting developers on complex, long-term, or collaborative projects, it enforces rigorous adherence to specifications and quality gates throughout AI-assisted development.

How It Works

Spec-Superflow integrates OpenSpec's schema validation/parsing with Superpowers' execution discipline (TDD, SDD, review gates). Its core innovation is the contract-builder, automatically generating execution-contract.md from planning artifacts as the sole implementation handoff. An 8-skill, content-aware routing system guides the AI through exploration, specification, bridging, execution, debugging, closing, and syncing. Key principles: "Spec First," "Guarded Handoff," "Strong Guardrails," and "Execute Disciplined."

Quick Start & Requirements

Installation spans 17 platforms, including major AI assistants (Claude Code, Codex, Copilot CLI, Gemini CLI), via marketplace plugins or CLI commands (e.g., npx spec-superflow@latest install-cursor). A global CLI tool (npm install -g spec-superflow or npx spec-superflow) offers management commands (list, validate, doctor). The project is self-contained, requiring no external OpenSpec/Superpowers runtimes. Detailed platform support is in docs/platform-matrix.md.

Highlighted Details

• Integrates with 17 AI coding platforms/assistants.
• Enforces "Spec First" methodology, requiring stable planning artifacts before implementation.
• Uses execution-contract.md as the mandatory bridge between planning and execution.
• Implements TDD, Subagent-Driven Development (SDD), and Review Gates.
• Features automatic mode detection for hotfix (≤2 files) and tweak (≤4 files) changes.

Maintenance & Community

No specific details regarding maintainers, community channels (e.g., Discord, Slack), or project roadmap were found in the provided README content.

Licensing & Compatibility

The README does not specify a software license, leaving its terms for commercial use or closed-source linking unclear.

Limitations & Caveats

The tool is not recommended for simple, one-off scripts or tools, or pure consulting/Q&A tasks. While it can ingest existing OpenSpec artifacts, mixing it with other OpenSpec or Superpowers instances within the same session is discouraged. The workflow mandates user approval at the bridging stage and enforces specific paths for bug handling and requirement changes.