MageByte-Zero/spec-superflow

What it solves

Spec-superflow provides a structured, recoverable AI programming workflow that prevents AI agents from drifting from the original intent or failing silently. It solves the problem of "hallucinated" completions where an AI might claim a task is finished without actual verification or where complex changes are implemented without a clear, agreed-upon scope.

How it works

The tool implements a disciplined execution pipeline using two primary paths:

• Direct Path: For simple changes with clear goals and reproducible verification. It records the requested scope and final verification results without requiring extensive planning documents.
• Planned Path: For complex, cross-module changes. It requires the creation of a proposal.md (goals, boundaries, risks) and a tasks.md (numbered checkboxes with completion criteria) before execution begins.

It utilizes a set of "Skills" (modular responsibility units) such as spec-writer for planning, build-executor for implementation, and code-reviewer for final verification. The workflow ensures that a task is only marked as verified if a verification command (e.g., npm test) returns a success code and a Git range is recorded.

Who it’s for

Developers using AI coding assistants (such as Claude Code, Cursor, GitHub Copilot CLI, or Gemini CLI) who want to enforce engineering rigor, formal verification, and scope control over AI-generated code changes.

Highlights

• Dual Execution Paths: Switches between lightweight direct execution and structured planning based on task complexity.
• Verifiable Results: Prevents AI from simply stating a task is done; requires actual exit codes from verification commands and Git range audits.
• Recoverable State: Supports checkpoints and session resumption (ssf resume) to recover work-in-progress tasks.
• Git Isolation: Provides built-in support for feature branches and optional Git worktrees to isolate AI changes.
• Broad Platform Support: Compatible with 19 different AI programming platforms/plugins.