MageByte-Zero/spec-superflow

What it solves

AI coding assistants often start writing code before the requirements are fully understood or drift from the original plan during implementation. spec-superflow prevents this by introducing a risk-based workflow that forces alignment on requirements and design before execution, especially for high-risk changes, while remaining lightweight for simple tweaks.

How it works

The project provides a set of "skills" and a CLI toolchain that can be integrated into various AI agents (like Claude Code, Cursor, Windsurf, etc.). It uses a content-level state machine to route the AI through eight distinct stages:

1. Exploring: Clarifying requirements via the need-explorer skill.
2. Specifying: Creating proposals, specs, designs, and tasks via spec-writer.
3. Bridging: Automatically compressing these artifacts into an execution-contract.md via contract-builder.
4. Executing: Implementing code using TDD and Subagent-Driven Development (SDD) via build-executor.
5. Debugging: Performing root-cause analysis via bug-investigator if implementation fails.
6. Reviewing: Conducting structured code reviews via code-reviewer.
7. Closing: Finalizing and archiving via release-archivist and spec-merger.

Depending on the risk (number of files, impact on API/permissions), it selects between a Full path (all stages) or Quick/Hotfix/Tweak paths (minimal documentation and direct verification).

Who it’s for

Developers working on large-scale feature development, multi-person collaborative projects, or long-term maintenance projects that require strict TDD and review gates.

Highlights

• Multi-Platform Support: Compatible with 19 different AI coding platforms including Cursor, Claude Code, Windsurf, and GitHub Copilot.
• Risk-Based Routing: Automatically chooses between lightweight and comprehensive workflows based on the change's complexity.
• Guard-Protected Execution: High-risk changes require a validated execution plan and review receipts before they can be closed.
• Content-Level Detection: Tracks state based on the actual content of artifacts rather than file timestamps.
• Integrated CLI: Includes a robust toolchain (ssf) for managing checkpoints, handoffs, and git isolation.