---
name: phased-execution
description: Runs the .agent/phases/ phased-execution pipeline (ported from opencode's next-phase/auto-phase commands). Use when the user asks to run the next phase, run all phases, run the phase pipeline, or check pipeline status. Each phase executes in a separate pi subprocess so this chat's context stays small.
---

# Phased Execution

Phase state lives in files, not chat:

- `.agent/PLAN.md` — master plan; LOCKED DECISIONS are binding
- `.agent/phases/todo/NN_name.md` — pending phases (alphanumerical sort = execution order)
- `.agent/phases/complete/` — finished phases
- `.agent/reports/` — per-phase executor reports, stderr, and validation logs
- `.agent/validate.sh` — the pass/fail gate for every phase

The scripts run each phase in a **separate pi process** (fresh context) with
bounded fixer retries (the failed executor's session is resumed, so retries
keep its work). A phase only moves to `complete/` after the child exits 0
**and** `.agent/validate.sh` passes. This chat only dispatches and relays
results — do not implement phase code yourself; that is what the subprocess
is for.

## Commands

(Resolve `scripts/` against this skill's directory.)

Run the next phase, or a specific one:

```bash
bash scripts/run-phase.sh            # first pending phase
bash scripts/run-phase.sh 03_api.md  # specific phase (warns if out of order)
```

Run the whole pipeline — every pending phase, in order, stopping at the first
phase that fails after all retries:

```bash
bash scripts/auto-phase.sh
```

Re-running `auto-phase.sh` after a failure continues where it stopped.

## After a run

Relay to the user: the phase name, its executor report (printed at the end of
the script output), and the validation outcome. On failure, point the user at
`.agent/reports/<phase>.a*.{md,err,validate}` and offer to resume the failed
executor's session: `pi --session-dir .agent/phase-sessions -c` (or suggest
running the script again to retry automatically).

## Configuration (environment variables)

| Var | Default | Meaning |
|-----|---------|---------|
| `MAX_FIX_ATTEMPTS` | `3` | Fixer retries per phase |
| `PHASE_MODEL` | session default | `--model` for child executors (e.g. `anthropic/claude-sonnet-4-5`) |
| `PHASE_THINKING` | session default | `--thinking` level for child executors |
| `PHASE_COMMIT` | `0` | `1` = `git commit --no-gpg-sign` after each passing phase |
| `PI_TRUST` | `0` | `1` = pass `--approve` (load project `.pi/` settings/skills into children) |
| `FRESH_FIX` | `0` | `1` = fixer retries start fresh instead of resuming the failed session |
| `QUIET` | `0` | `1` = suppress live progress display (reports are still written) |

## Setup notes

- First run creates `.agent/validate.sh` from `assets/validate.sh` if missing.
  It must be adapted to the project's real checks — it is the authoritative
  quality gate.
- Phase files are created by the `/to-phase`, `/audit-create`, `/new-project`,
  and `/new-python-*` prompt templates.
- Child executor sessions are kept in `.agent/phase-sessions/`; add it to
  `.gitignore` if the project is versioned.