skills/phased-execution/SKILL.md

---
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 task, run the next phase, run all phases, run the phase pipeline, or check pipeline status. Each task 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/` — a pending phase: `00_phase.md` (objective, dependencies, task index, testing & quality, completion criteria) plus `NN_task.md` task files (task sort order = execution order)
- `.agent/phases/todo/NN_name.md` — legacy single-file phase (still executable as one unit)
- `.agent/phases/complete/` — finished phases; mirrors the `todo/` layout (completed task files and the phase overview move here)
- `.agent/reports/<phase>/<task>.a<N>.{md,err,validate}` — per-task executor reports, stderr, and validation logs (legacy phases: `.agent/reports/<phase>.a<N>.*`)
- `.agent/validate.sh` — the pass/fail gate, run after **every task**

The unit of execution is the **task**: each task runs in a **separate pi
process** (fresh context) with bounded fixer retries. A task only moves to
`complete/` after the child exits 0, the child's stream ends with a clean
final report, **and** `.agent/validate.sh` passes. When all of a phase's tasks
are done, `00_phase.md` runs as the phase's **final pass** (remaining inline
work + completion criteria + phase-level verification); moving it completes
the phase and is the `PHASE_COMMIT` commit point. This chat only dispatches
and relays results — do not implement task code yourself; that is what the
subprocesses are for.

## Live display

While a phase runs, `scripts/progress.mjs` relays the child's JSON stream to
the terminal: tool calls, assistant text, `◐ thinking…` / `◑ thought for Ns`
indicators, yellow `⧉ compacting context` lines (these can take minutes —
not a hang), and provider auto-retry notices. If the child dies mid-flush and
the stream loses the final message, the report is recovered from the
child's session file (`.agent/phase-sessions/`), so a completed phase is
never lost to a truncated stream.

## Commands

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

Run the next task, or a specific one:

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

Run one phase to completion — all of its remaining tasks, then its
`00_phase.md` final pass:

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

Run the whole pipeline — every pending task, in order (phase order, then task
order), stopping at the first task 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

Exit codes: `0` = success (or nothing to run), `1` = task/phase failed after all
attempts, `130`/`143` = interrupted (Ctrl+C / SIGTERM).
Failures always print a `✗ ERROR:` line with the last error output — if the
script's output looks like it ended abruptly, re-run it; the failed executor's
session is resumed automatically (retries continue the child's own session,
keeping its work).

Relay to the user: the task (or 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>/<task>.a*.{md,err,validate}` (legacy
phases: `.agent/reports/<phase>.a*.*`) — the script also prints a ready to run
`pi --session … -c “…”` command to continue the failed session manually.

## 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 completed **phase** (when its `00_phase.md` final pass passes; legacy: when its file moves) |
| `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) |
| `PHASE_NOTIFY` | `1` | `0` = disable ntfy push notifications. When on and `~/.env/pi-ntfy.env` exists, a notification is sent after every unit completes (`task` for each task file, `phase` for a phase's final pass) |

## 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 directories are created by the `phase-authoring` skill or the
  `/to-phase`, `/audit-create`, `/new-project`, and `/new-python-*` prompt
  templates.
- Legacy flat phase files (`todo/NN_name.md`) are still executed as a single
  unit; `phase-authoring`'s `migrate-phases-to-tasks.sh` converts them to the
  directory layout (the phase's final pass then picks up any inline task list).
- Child executor sessions are kept in `.agent/phase-sessions/`; add it to
  `.gitignore` if the project is versioned.
- If you keep non-skill markdown (e.g. a `README.md`) in a skills directory
  (like `~/.pi/agent/skills/`), pi warns “description is required” for it.
  Add a `.gitignore` in that directory listing the file — pi's skill scanner
  honors `.gitignore`, so the file is skipped.