72 lines
3.1 KiB
Markdown
72 lines
3.1 KiB
Markdown
---
|
|
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.
|