phased-flow

Plan first, code second. Structured AI workflow that enforces logical planning before any implementation.

  📥 Intake ──→ 🧠 Plan (Opus) ──→ ⛔ Approve? ──→ ⚡ Dev (Sonnet) ──→ 🔍 Review ──→ 🛡️ Security ──→ 🚀 Ship
                     │                    │                │                 │              │
                 EDD Gate:            Human gate       CodeGraph:        SOLID/DRY       OWASP
               "Does this need       blocks until     blast radius      BLOCK/WARN      Top 10
                to exist?"            approved        before edit       enforcement

Quick Start

npx phased-flow                      # Claude Code (default)
npx phased-flow --target copilot     # GitHub Copilot
npx phased-flow --target gemini      # Gemini CLI
npx phased-flow --target all         # All platforms at once

Then describe what you want to build:

I want to implement user authentication with JWT tokens

phased-flow activates automatically — plans with Opus, builds with Sonnet, reviews everything before you ship.

The 6 Phases

  ┌─────────────┐   ┌──────────────────┐   ┌───────────┐   ┌──────────────────┐   ┌───────────────┐
  │  Phase 0    │   │    Phase 1       │   │  Phase 2  │   │  Phase 3 – 4     │   │  Phase 5 – 6  │
  │  Context    │──▶│    Planning      │──▶│   Dev     │──▶│    Reviews       │──▶│     Ship      │
  │             │   │                  │   │           │   │                  │   │               │
  │ Read files  │   │ EDD evaluation   │   │ Task T01  │   │ SOLID / DRY     │   │ Evidence      │
  │ CodeGraph   │   │ Architecture     │   │ Task T02  │   │ Anti-patterns   │   │ PR desc       │
  │ STATE.json  │   │ Task breakdown   │   │ Task T0N  │   │ OWASP Top 10    │   │ Archive       │
  └─────────────┘   └────────┬─────────┘   └───────────┘   └──────────────────┘   └───────────────┘
                             │
                      ⛔ Human gate
                    (approve to continue)

You control the gates. No code runs without your approved plan. No commit happens without your say.

| Phase | Model | What happens | |-------|-------|-------------| | 0 — Context | — | Reads project files, sets up CodeGraph, creates state | | 1 — Planning | Opus | EDD evaluation + logical plan — no code, just architecture | | 2 — Dev | Sonnet | Implements each task from the approved plan | | 3 — Code Review | Sonnet | SOLID, DRY, blast radius, architecture anti-patterns | | 4 — Security | Sonnet | OWASP Top 10 checklist against all changes | | 5 — Evidence | — | Screenshots, API responses, test results | | 6 — Handoff | — | Commit message, PR description, archival |

Key Features

| | | |:--|:--| | 🧠 CodeGraph | Knowledge graph per project · 70% fewer tool calls · 60% less tokens · Blast radius before every edit | | ⚖️ EDD Gate | Evaluates each requirement before planning — does it need to exist? Is there a simpler way? Is effort proportional? | | 🔒 BLOCK/WARN Enforcement | SOLID, DRY, KISS, YAGNI with teeth · Architecture dependency direction · REST / SPA / Microservice anti-patterns | | ⚡ Token Optimization | Selective injection per phase · Only relevant rules per subagent · CodeGraph over file dumps · Task section, not full plan | | 🔄 Reentrant | All state in JSON · /clear safe anytime · Resume from exact last task | | 📦 Epic Mode | Multi-issue milestones · Shared CHANGELOG strategy · PR description gates per issue |

File Structure

.phased-flow/
  STATE.json              # Current phase and task progress
  learned.md              # Anti-false-positive lessons
  archive/                # Completed plans

docs/superpowers/plans/
  2026/
    09/
      12-user-auth/
        PLAN.md           # Approved logical plan
        evidence/         # Screenshots, API responses, tests
        review/           # Code review + security review
      15-payment-flow/
        PLAN.md
        ...
    10/
      03-notifications/
        ...

Platform Support

| Feature | Claude Code | Copilot | Gemini CLI | |---------|:-----------:|:-------:|:----------:| | Full phased workflow | ✅ | ✅ | ✅ | | Subagent dispatch | Native | Inline | Inline | | Model segregation | Auto | Manual | Manual | | Epic mode | ✅ | ✅ | ✅ | | CodeGraph integration | ✅ | — | — |

State files are platform-agnostic — plan with one AI, implement with another.

Requirements

• Node.js 14+ for the installer
• Claude Code, GitHub Copilot, or Gemini CLI
• Access to Claude Opus and Sonnet models (for Claude Code)

License

MIT © Jorge Andres Ricardo