skills/phased-execution/SKILL.md

name, description

name	description
phased-execution	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 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 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.