ducoterra
3bacbff874
- retries now resume the failed executor's session (pre/post session tracking replaces the broken mtime-vs-ref check) - report recovery from the session file when the JSON stream loses its tail (child signaled mid-flush) - progress.mjs: thinking indicators (◐ thinking… / ◑ thought for Ns), compaction (⧉ …) and provider auto-retry lines; trims trailing whitespace so no blank lines after LLM text; exits 1 on truncated stream, model error, or missing final text (pi --mode json always exits 0 even on errors) - explicit ✗ ERROR lines + exit codes: 0 ok, 1 phase failed, 130/143 interrupted (INT/TERM traps; post-pipeline check covers the case where bash suppresses the INT trap after a job dies from SIGINT) - PIPESTATUS captured in a single statement (any following command resets it) - skills dir: .gitignore README.md so pi's skill scanner (which honors .gitignore) stops warning 'description is required'
91 lines
4.2 KiB
Markdown
91 lines
4.2 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. A phase only moves to `complete/` after the child exits
|
|
0, the child's stream ends with a clean final report, **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.
|
|
|
|
## 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 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
|
|
|
|
Exit codes: `0` = success (or nothing to run), `1` = phase failed after all
|
|
attempts / no pending phases error, `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 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}` — 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 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.
|
|
- 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.
|