phased-flow

Structured AI-driven development workflow for Claude Code — logical planning before any code.

What is phased-flow?

phased-flow is a Claude Code skill that enforces a disciplined, phase-gated development workflow. It prevents the most common failure mode of AI-assisted development: writing code before thinking through the problem.

Instead of jumping straight into implementation, phased-flow routes every task through a structured sequence:

1. Understand the context
2. Plan the architecture (using Claude Opus 4.6)
3. Implement from the approved plan (using Claude Sonnet 4.6)
4. Review the code
5. Review for security
6. Capture evidence and archive

The skill is fully reentrant — all state is persisted in files, so you can /clear the Claude Code context at any point and resume exactly where you left off.

Why publish to npm?

phased-flow is distributed as an npm package for a single reason: frictionless installation.

Claude Code skills live in ~/.claude/skills/. Manually cloning a repo and copying files there is error-prone and hard to update. By publishing to npm, any developer can install or update the skill in one command:

npx phased-flow

The installer handles directory creation, file copying, and update detection automatically. No git, no manual file management, no configuration — just run and restart Claude Code.

Installation

Requires Node.js 14 or later and your target AI assistant.

Claude Code (default)

npx phased-flow
# or explicitly:
npx phased-flow --target claude

Installs to ~/.claude/skills/phased-flow/. Restart Claude Code after installation.

GitHub Copilot (VS Code)

Run from the root of the project where you want to use phased-flow:

npx phased-flow --target copilot

Generates .github/copilot-instructions.md. GitHub Copilot picks it up automatically as workspace instructions.

Gemini CLI

Run from your project root (local) or with --global for all projects:

# Local (this project only)
npx phased-flow --target gemini

# Global (all projects)
npx phased-flow --target gemini --global

Generates GEMINI.md in the project root (or ~/.gemini/GEMINI.md for global).

Usage

Once installed, trigger phased-flow in Claude Code by describing what you want to build:

I want to implement user authentication with JWT tokens

Build a REST API endpoint for file uploads

Create a real-time notification system

Claude Code will automatically detect the intent and invoke the phased-flow skill.

You can also restart an interrupted session — phased-flow will read the persisted state and resume from the last completed task.

Task Input Formats

When phased-flow starts, it asks how you want to provide the task. Five formats are supported:

| Format | How it works | |--------|-------------| | Free text | Describe the task directly in the chat | | GitHub issue/PR | Paste the link — phased-flow runs gh issue view and parses acceptance criteria automatically | | Document | Provide the path to a Markdown or PDF file | | Image / screenshot | Attach a screenshot — phased-flow reads it multimodally | | Mixed | Combine any of the above |

When the source is a GitHub issue with a complete description and acceptance criteria, phased-flow skips creating an INTAKE.md and treats the issue as the authoritative source.

The Six Phases

Phase 0 — Context Ingestion

Reads the project's context file (if present) before doing anything else. Establishes shared understanding of the codebase, conventions, and constraints.

Phase 1 — Logical Planning (Opus 4.6)

No code is written here. Claude Opus 4.6 produces a structured PLAN.md covering:

• Objective and success criteria
• Architecture decisions
• All files that will be created or modified
• Task breakdown with explicit dependencies
• Evidence strategy (how completion will be verified)

The plan is written to docs/superpowers/plans/<date-slug>/PLAN.md. Development is blocked until the plan status is set to approved.

Phase 2 — Development (Sonnet 4.6)

Claude Sonnet 4.6 implements each task in the approved plan sequentially. State is persisted in .phased-flow/STATE.json after every completed task, making the session fully resumable.

Phase 3 — Code Review (Sonnet 4.6)

Automated review of all changes against the original plan. Checks for correctness, coverage of all planned tasks, and adherence to project conventions.

Phase 4 — Security Review (Sonnet 4.6)

Dedicated security pass checking for common vulnerabilities: injection, broken auth, insecure data exposure, misconfiguration, and others from OWASP Top 10.

Phase 5 — Evidence Capture

Test results, screenshots, API responses, and logs are collected and stored in docs/superpowers/plans/<id>/evidence/.

Phase 6 — Handoff & Archival

Final summary of what was built, what changed, and where everything lives. Marks the plan as completed in STATE.json.

Golden Rules

These constraints are injected into every subagent dispatched by phased-flow. They cannot be overridden:

| Rule | Detail | |------|--------| | No auto-commit | The developer always controls git commit and git push | | No code without an approved plan | Phase 2 will not start until Phase 1 plan is approved | | Model segregation | Opus 4.6 for planning only, Sonnet 4.6 for implementation and review | | Context first | Project context file is always read before any work begins | | State persistence | STATE.json is updated after every completed task | | Clean resumption | /clear is safe — resume picks up from persisted files |

File Structure

After running phased-flow on a task, your project will contain:

.phased-flow/
  STATE.json                        # Current phase, task index, plan reference
  learned.md                        # Project-specific review lessons (anti-false-positives)
  archive/                          # Completed plans and epics

docs/superpowers/plans/
  2026-05-01-user-auth/
    PLAN.md                         # Approved logical plan
    INTAKE.md                       # Processed task source (omitted for complete GitHub issues)
    evidence/
      T01/                          # Evidence for task 1
      T02/                          # Evidence for task 2
    review/
      code-review.md
      security-review.md

docs/superpowers/prs/               # Epic mode only
  2026-05-01-issue-42-pr-description.md

Model Distribution

| Phase | Model | Reason | |-------|-------|--------| | Planning | claude-opus-4-6 | Highest reasoning capacity for architecture decisions | | Development | claude-sonnet-4-6 | Fast, capable implementation | | Code review | claude-sonnet-4-6 | Pattern recognition across changed files | | Security review | claude-sonnet-4-6 | Broad vulnerability surface coverage |

Epic Mode

Use epic mode when several related issues or features belong to the same initiative. Instead of treating each plan as independent, phased-flow links them under a shared epic_id in STATE.json.

When to use it: phased-flow asks at the start of Phase 0 whether the plan is independent or part of an epic. Choose epic if you're working through a multi-issue milestone.

What changes in epic mode:

• STATE.json is created from EPIC-STATE.tpl.json, which tracks multiple plans and their issues
• Phase 6 requires a PR description file (docs/superpowers/prs/YYYY-MM-DD-issue-N-pr-description.md) before archiving — generated from PR.tpl.md
• CHANGELOG entries can be accumulated per-epic rather than per-plan

CHANGELOG strategies (set at epic creation):

| Strategy | Behavior | |----------|----------| | per-epic | All plans accumulate into a single CHANGELOG block for the epic | | per-plan | Each plan gets its own CHANGELOG entry | | none | CHANGELOG is skipped entirely |

Plans that only contain tests (no production code changes) inherit the version of the implementation plan they test and do not create their own CHANGELOG entry.

learned.md — Anti-False-Positive System

Each project gets a .phased-flow/learned.md file created automatically in Phase 0. It accumulates project-specific knowledge that prevents review agents from flagging known-good patterns as issues.

Structure:

# Lecciones aprendidas — [project name]

## Confirmed architecture patterns
- [pattern and why it's correct]

## Actual framework behavior
- [behavior reviewers tend to misread]

## Documented false positives
| Finding | Why it's not actionable |
|---------|------------------------|
| [finding] | [reason] |

To update: Edit the file manually when a review flags something that is intentional.

To re-run a review with updated learned.md: Set current_phase in STATE.json to "code_review" or "security" and re-invoke the skill.

Resuming After a Break

If you close Claude Code or run /clear mid-session, phased-flow resumes automatically on the next invocation. It reads .phased-flow/STATE.json and picks up from the last completed task — no repeated work, no lost context.

Requirements

• Claude Code — the Anthropic CLI/IDE extension
• Node.js 14 or later (for the installer)
• Access to Claude Opus 4.6 and Claude Sonnet 4.6 models

Platform Compatibility

| Feature | Claude Code | GitHub Copilot | Gemini CLI | |---------|-------------|----------------|------------| | Phased workflow (0–6) | ✅ Full | ✅ Sequential | ✅ Sequential | | Subagent dispatch | ✅ Native (Agent tool) | ⚠️ Inline only | ⚠️ Inline / activate_skill | | Model segregation (planning vs dev) | ✅ Automatic | ✅ Manual guidance | ✅ Manual guidance | | Epic mode (STATE.json) | ✅ | ✅ | ✅ | | learned.md anti-false-positive | ✅ | ✅ | ✅ | | PR description gate | ✅ | ✅ | ✅ |

State files (.phased-flow/STATE.json, PLAN.md, learned.md) are platform-agnostic — you can plan with one AI and implement with another.

License

MIT © Jorge Andres Ricardo