init

2026-08-21 02:30:51 -04:00
commit 38ecedcaa3
7 changed files with 532 additions and 0 deletions
@@ -0,0 +1,71 @@
+---
+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.