phase-runner

Phase Runner

Plan it. Phase it. Run it. Review it.

Phase Runner breaks big tasks into fine-grained phases, saves them as a local markdown plan, then executes each phase in its own isolated Claude session. When it's all done, it reviews everything.

One task. One document. Many phases. Zero context bleed.

---

Why

Large tasks in a single context window get messy. The model loses focus, skips steps, and makes mistakes that compound. Phase Runner fixes this by enforcing one phase = one independent session.

Every phase starts fresh. Every phase commits. Every plan lives in docs/ as plain markdown — your work documents itself.

The Workflow

phase-plan → phase-run → phase-review

Step	What it does
Plan	Explores the codebase, decomposes the task into bite-sized phases, saves to docs/YYYY-MM-DD-title.md
Run	Executes each phase in its own claude -p session — auto or one-at-a-time
Review	Diffs every change against the plan, flags issues by severity

Installation

Claude Code Marketplace

/plugin marketplace add XinguOh/phase-runner
/plugin install phase-runner@xingu

Manual

git clone https://github.com/XinguOh/phase-runner.git ~/.claude/plugins/marketplaces/xingu

Add to ~/.claude/settings.json:

{
  "enabledPlugins": {
    "phase-runner@xingu": true
  },
  "extraKnownMarketplaces": {
    "xingu": {
      "source": {
        "source": "git",
        "url": "https://github.com/XinguOh/phase-runner.git"
      }
    }
  }
}

Usage

1. Plan

/phase-runner:phase-plan "refactor order management"

Scans your codebase, identifies affected files and dependencies, then generates a phased plan:

# Order Management Refactoring

> Date: 2026-04-01
> Goal: Separate order code into proper data flow layers
> Phases: 4

---

## Phase 1 — Define order types
### Goal
Establish TypeScript types and interfaces for all order entities
### Tasks
- [ ] Create OrderItem, OrderWithDetails interfaces
- [ ] Define OrderCreateInput, OrderUpdateInput
- [ ] Add status label constants
### Files
- Create: `lib/types/orders.ts`
### Commit
`feat: Phase 1 — Define order types`

---

## Phase 2 — Extract API functions
...

## Phase 3 — Create query hooks
...

## Phase 4 — Migrate components
...

All plans are saved to docs/ — one file per task, all phases inside.

2. Run

/phase-runner:phase-run docs/2026-04-01-order-management-refactoring.md

Flag	Behavior
(none)	Auto-run all remaining phases in background (claude -p per phase)
--step	Run the next phase in the current session
--status	Show progress and stop
--phase N	Jump to phase N, then auto-run from there
--dry-run	Preview the next phase without executing
--reset	Clear state and start fresh

Auto mode generates a shell script that spawns an independent claude -p session per phase. Each session plans, executes, verifies, commits, and updates state before the next one begins.

Step mode runs one phase at a time in your current session — useful when you want to stay in the loop.

/phase-runner:phase-run --status

Phase Runner — order-management-refactoring.md
Progress: 2/4 (50%)

  Phase 1 ✅ Define order types (abc1234)
  Phase 2 ✅ Extract API functions (def5678)
  Phase 3 ⏳ Create query hooks ← next
  Phase 4 ⬜ Migrate components

3. Review

/phase-runner:phase-review docs/2026-04-01-order-management-refactoring.md

Reads every file changed across all phases and checks:

• Completeness — Did every phase get implemented? Anything missing?
• Quality — Conventions, type safety, dead code, leftover debug logs
• Risk — Security issues, performance problems, error handling gaps

Issues are reported by severity:

🔴 Must fix    — blocking problems
🟡 Should fix  — recommended improvements
💡 Note        — observations, no action needed

State

Execution state lives in .phase-runner/ (add to .gitignore):

.phase-runner/
├── state.json       # progress tracking
├── runner.sh        # auto-mode script
├── runner.log       # execution log
└── output.log       # full output

State enables resume, status checks, and reset. If a phase fails verification, it commits as partial and keeps going — the pipeline never stops.

Design Principles

• One phase, one session — Clean context per phase. No bleed, no drift.
• Docs as artifact — Plans are markdown in docs/. Your work history writes itself.
• Never stop — Verification failure? Partial commit, move on. Fix it in review.
• What, not how — Plans describe what to do. The executing session figures out how.
• Small phases — Each phase touches 1–5 files. Big enough to be meaningful, small enough to be reliable.

Skills Reference