refactor(skills): use .agents/ instead of .agent/ for phased execution

Standardize on the .agents/ directory across all phased-execution
skills (phase state, reports, sessions, validate.sh, PLAN.md, and
per-story/feature/workflow trees). Legacy dot-less agent/ fallbacks
in migration scripts are untouched.
This commit is contained in:
2026-09-05 10:52:37 -04:00
parent e8a2106172
commit e505df62e8
26 changed files with 209 additions and 209 deletions
+15 -15
View File
@@ -1,23 +1,23 @@
---
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.
description: Runs the .agents/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**
- `.agents/PLAN.md` — master plan; LOCKED DECISIONS are binding
- `.agents/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)
- `.agents/phases/todo/NN_name.md` — legacy single-file phase (still executable as one unit)
- `.agents/phases/complete/` — finished phases; mirrors the `todo/` layout (completed task files and the phase overview move here)
- `.agents/reports/<phase>/<task>.a<N>.{md,err,validate}` — per-task executor reports, stderr, and validation logs (legacy phases: `.agents/reports/<phase>.a<N>.*`)
- `.agents/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
final report, **and** `.agents/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
@@ -31,7 +31,7 @@ the terminal: tool calls, assistant text, `◐ thinking…` / `◑ thought for N
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
child's session file (`.agents/phase-sessions/`), so a completed phase is
never lost to a truncated stream.
## Commands
@@ -73,8 +73,8 @@ 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
the user at `.agents/reports/<phase>/<task>.a*.{md,err,validate}` (legacy
phases: `.agents/reports/<phase>.a*.*`) — the script also prints a ready to run
`pi --session … -c “…”` command to continue the failed session manually.
## Configuration (environment variables)
@@ -92,7 +92,7 @@ phases: `.agent/reports/<phase>.a*.*`) — the script also prints a ready to run
## Setup notes
- First run creates `.agent/validate.sh` from `assets/validate.sh` if missing.
- First run creates `.agents/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
@@ -101,9 +101,9 @@ phases: `.agent/reports/<phase>.a*.*`) — the script also prints a ready to run
- 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/` (plus
`pipeline.log` in `.agent/`); if the project is versioned, git-ignore those
runtime artifacts only — `.agent/` itself is tracked and committed.
- Child executor sessions are kept in `.agents/phase-sessions/` (plus
`pipeline.log` in `.agents/`); if the project is versioned, git-ignore those
runtime artifacts only — `.agents/` itself is tracked and committed.
- 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
+4 -4
View File
@@ -1,11 +1,11 @@
You are a phase executor in a phased build pipeline. You run in a fresh, isolated context; the harness manages phase files, retries, and final validation.
Target phase file: `.agent/phases/todo/{{PHASE}}`
Target phase file: `.agents/phases/todo/{{PHASE}}`
## Steps
1. Read `.agent/PLAN.md` — project goals, architecture, and **LOCKED DECISIONS** (binding; never introduce technology outside them).
1. Read `.agents/PLAN.md` — project goals, architecture, and **LOCKED DECISIONS** (binding; never introduce technology outside them).
2. Read `AGENTS.md` if present.
3. Read the completed phase files so your work stays architecturally consistent with what is already built: every `00_phase.md` in `.agent/phases/complete/*/`, plus any legacy flat phase files directly in `.agent/phases/complete/`.
3. Read the completed phase files so your work stays architecturally consistent with what is already built: every `00_phase.md` in `.agents/phases/complete/*/`, plus any legacy flat phase files directly in `.agents/phases/complete/`.
4. Read the target phase file and complete **every** task in it, in order.
5. Write the unit and integration tests required by the phase's Testing & Quality section. Do not omit parts of the code to inflate coverage.
6. Run the project's full test suite and linter. If anything fails — including the phase's coverage criterion — fix it and re-run until green.
@@ -13,7 +13,7 @@ Target phase file: `.agent/phases/todo/{{PHASE}}`
## Rules
- Work only on the target phase; never start work from other files in `todo/`.
- Do **not** move, rename, or edit the phase file, other files in `.agent/phases/todo/`, `.agent/PLAN.md`, or anything in `.agent/phases/complete/`. The harness moves the phase file on success.
- Do **not** move, rename, or edit the phase file, other files in `.agents/phases/todo/`, `.agents/PLAN.md`, or anything in `.agents/phases/complete/`. The harness moves the phase file on success.
- Do not assume the code is correct; fix any errors you find while testing.
- Leave the repository functional when you finish.
@@ -1,19 +1,19 @@
You are the phase-completion executor in a phased build pipeline. You run in a fresh, isolated context; the harness manages phase and task files, retries, and final validation.
Phase overview: `.agent/phases/todo/{{PHASE}}/00_phase.md`
Phase overview: `.agents/phases/todo/{{PHASE}}/00_phase.md`
## Steps
1. Read `.agent/PLAN.md` — project goals, architecture, and **LOCKED DECISIONS** (binding; never introduce technology outside them).
1. Read `.agents/PLAN.md` — project goals, architecture, and **LOCKED DECISIONS** (binding; never introduce technology outside them).
2. Read `AGENTS.md` if present.
3. Read the phase overview `.agent/phases/todo/{{PHASE}}/00_phase.md`.
4. Check the phase's task index against `.agent/phases/complete/{{PHASE}}/`: if any task is missing from there, the overview itself still carries work (a legacy phase with an inline task list) — implement that remaining work now, in order, including its tests.
3. Read the phase overview `.agents/phases/todo/{{PHASE}}/00_phase.md`.
4. Check the phase's task index against `.agents/phases/complete/{{PHASE}}/`: if any task is missing from there, the overview itself still carries work (a legacy phase with an inline task list) — implement that remaining work now, in order, including its tests.
5. Otherwise every task is done: this is the final verification pass. Verify **each** completion criterion in the phase overview (commands to run, endpoints to hit, artifacts to exist), and execute any phase-level verification blocks it defines (e.g. a dedicated E2E or contract test suite).
6. Run the project's full test suite and linter. If anything fails — including the phase's coverage criterion or a completion criterion — fix it and re-run until green.
7. If you find defects in previously completed work (failing tests, lint errors, bugs), fix those as part of this pass.
## Rules
- Never start work from other files in `todo/`.
- Do **not** move, rename, or edit the phase overview, other files in `.agent/phases/todo/`, `.agent/PLAN.md`, or anything in `.agent/phases/complete/`. The harness moves the phase file on success.
- Do **not** move, rename, or edit the phase overview, other files in `.agents/phases/todo/`, `.agents/PLAN.md`, or anything in `.agents/phases/complete/`. The harness moves the phase file on success.
- Do not assume the code is correct; fix any errors you find while testing.
- Leave the repository functional when you finish.
@@ -1,12 +1,12 @@
You are a task executor in a phased build pipeline. You run in a fresh, isolated context; the harness manages phase and task files, retries, and final validation.
Target task file: `.agent/phases/todo/{{PHASE}}/{{TASK}}`
Target task file: `.agents/phases/todo/{{PHASE}}/{{TASK}}`
## Steps
1. Read `.agent/PLAN.md` — project goals, architecture, and **LOCKED DECISIONS** (binding; never introduce technology outside them).
1. Read `.agents/PLAN.md` — project goals, architecture, and **LOCKED DECISIONS** (binding; never introduce technology outside them).
2. Read `AGENTS.md` if present.
3. Read the phase overview `.agent/phases/todo/{{PHASE}}/00_phase.md` — objective, dependencies, testing & quality mandate, and completion criteria.
4. Read this phase's completed task files (`.agent/phases/complete/{{PHASE}}/*.md`, excluding `00_phase.md`) and the `00_phase.md` overviews of other completed phases (`.agent/phases/complete/*/00_phase.md`) so your work stays architecturally consistent with what is already built.
3. Read the phase overview `.agents/phases/todo/{{PHASE}}/00_phase.md` — objective, dependencies, testing & quality mandate, and completion criteria.
4. Read this phase's completed task files (`.agents/phases/complete/{{PHASE}}/*.md`, excluding `00_phase.md`) and the `00_phase.md` overviews of other completed phases (`.agents/phases/complete/*/00_phase.md`) so your work stays architecturally consistent with what is already built.
5. Read the target task file and complete it fully, in order.
6. Write the unit and integration tests required by the task. Do not omit parts of the code to inflate coverage.
7. Run the project's full test suite and linter. If anything fails — including the task's coverage criterion — fix it and re-run until green.
@@ -14,7 +14,7 @@ Target task file: `.agent/phases/todo/{{PHASE}}/{{TASK}}`
## Rules
- Work only on the target task; never start the next task or work from other files in `todo/`.
- Do **not** move, rename, or edit the task file, `00_phase.md`, other files in `.agent/phases/todo/`, `.agent/PLAN.md`, or anything in `.agent/phases/complete/`. The harness moves the task file on success.
- Do **not** move, rename, or edit the task file, `00_phase.md`, other files in `.agents/phases/todo/`, `.agents/PLAN.md`, or anything in `.agents/phases/complete/`. The harness moves the task file on success.
- Do not assume the code is correct; fix any errors you find while testing.
- Leave the repository functional when you finish.
+2 -2
View File
@@ -1,7 +1,7 @@
#!/usr/bin/env bash
# .agent/validate.sh — validation gate for the phased-execution pipeline.
# .agents/validate.sh — validation gate for the phased-execution pipeline.
#
# A phase is only moved to .agent/phases/complete/ if this script exits 0.
# A phase is only moved to .agents/phases/complete/ if this script exits 0.
# Adapt the checks below to this project's real test suite, linter, and
# coverage floor, then commit the result.
set -uo pipefail
+5 -5
View File
@@ -1,11 +1,11 @@
#!/usr/bin/env bash
# auto-phase.sh — run the full phased pipeline, no LLM in the loop.
#
# Processes every pending task in .agent/phases/todo/ in pipeline order
# Processes every pending task in .agents/phases/todo/ in pipeline order
# (phase order, then task order within each phase). Each task runs in its
# own pi process (fresh context); .agent/validate.sh runs after EVERY task.
# own pi process (fresh context); .agents/validate.sh runs after EVERY task.
# On failure the executor's session is resumed for up to MAX_FIX_ATTEMPTS
# fixer rounds. A task moves to .agent/phases/complete/ only after the
# fixer rounds. A task moves to .agents/phases/complete/ only after the
# child exits 0 AND validation passes; a phase completes when its
# 00_phase.md final pass succeeds (legacy phases: when their file moves).
# Stops at the first task that cannot be completed — re-run this script to
@@ -17,12 +17,12 @@ set -uo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$SCRIPT_DIR/lib.sh"
# Make interruptions visible: state stays in .agent/phases/todo, and the
# Make interruptions visible: state stays in .agents/phases/todo, and the
# failed executor's session is still resumable on the next run.
trap 'echo; echo "✗ ERROR: interrupted (SIGINT) — ${unit:-the pipeline} is left in $PHASE_TODO/; re-run to continue where it stopped" >&2; exit 130' INT
trap 'echo; echo "✗ ERROR: interrupted (SIGTERM) — ${unit:-the pipeline} is left in $PHASE_TODO/; re-run to continue where it stopped" >&2; exit 143' TERM
cd "$(find_root)" || die "no .agent/phases/todo found in this or parent directories (run /to-phase or /audit-create first)"
cd "$(find_root)" || die "no .agents/phases/todo found in this or parent directories (run /to-phase or /audit-create first)"
build_pi_args
delivered=()
+23 -23
View File
@@ -3,16 +3,16 @@
# Sourced by run-task.sh, run-phase.sh, and auto-phase.sh. Not meant to be run directly.
#
# Phase state lives in files, not chat context:
# .agent/PLAN.md master plan, LOCKED DECISIONS (binding)
# .agent/phases/todo/NN_name/ pending phase: 00_phase.md (overview) + NN_task.md task files
# .agent/phases/todo/NN_name.md legacy single-file phase (still executable)
# .agent/phases/complete/ finished phases — mirrors the todo/ layout
# .agent/reports/ per-task executor reports, stderr, validation logs
# .agent/phase-sessions/ child pi session files (resumable fixers)
# .agents/PLAN.md master plan, LOCKED DECISIONS (binding)
# .agents/phases/todo/NN_name/ pending phase: 00_phase.md (overview) + NN_task.md task files
# .agents/phases/todo/NN_name.md legacy single-file phase (still executable)
# .agents/phases/complete/ finished phases — mirrors the todo/ layout
# .agents/reports/ per-task executor reports, stderr, validation logs
# .agents/phase-sessions/ child pi session files (resumable fixers)
#
# The unit of execution is the TASK: each task file runs in its own pi
# subprocess (fresh context) with bounded fixer retries, and
# .agent/validate.sh runs after EVERY task. A unit only moves to complete/
# .agents/validate.sh runs after EVERY task. A unit only moves to complete/
# after the child exits 0, the child's stream ends with a clean final
# report, and validation passes. When all of a phase's tasks are done,
# 00_phase.md runs as the phase's final pass (any remaining inline work +
@@ -24,22 +24,22 @@ EXECUTOR_PROMPT_FILE="$SKILL_DIR/assets/executor-prompt.md"
TASK_EXECUTOR_PROMPT_FILE="$SKILL_DIR/assets/task-executor-prompt.md"
PHASE_FINAL_PROMPT_FILE="$SKILL_DIR/assets/phase-final-prompt.md"
PHASE_TODO=".agent/phases/todo"
PHASE_DONE=".agent/phases/complete"
PHASE_REPORTS=".agent/reports"
PHASE_SESSIONS=".agent/phase-sessions"
PHASE_TODO=".agents/phases/todo"
PHASE_DONE=".agents/phases/complete"
PHASE_REPORTS=".agents/reports"
PHASE_SESSIONS=".agents/phase-sessions"
MAX_FIX_ATTEMPTS="${MAX_FIX_ATTEMPTS:-3}"
warn() { echo "⚠ $*" >&2; }
die() { echo "✗ ERROR: $*" >&2; exit 1; }
# --- project root -------------------------------------------------------------
# Walk up from $PWD to the nearest directory containing .agent/phases/todo.
# Walk up from $PWD to the nearest directory containing .agents/phases/todo.
find_root() {
local d
d="$(pwd)"
while :; do
if [[ -d "$d/.agent/phases/todo" ]]; then printf '%s\n' "$d"; return 0; fi
if [[ -d "$d/.agents/phases/todo" ]]; then printf '%s\n' "$d"; return 0; fi
[[ "$d" == "/" ]] && return 1
d="$(dirname "$d")"
done
@@ -47,7 +47,7 @@ find_root() {
# --- unit selection -------------------------------------------------------------
# A unit is the smallest schedulable piece of work, referenced relative to
# .agent/phases/todo/:
# .agents/phases/todo/:
# directory phase → each task file "NN_name/NN_task.md" (sort order), then
# the phase overview "NN_name/00_phase.md" as the final pass
# legacy flat → the phase file itself, "NN_name.md"
@@ -225,7 +225,7 @@ fix_prompt() {
# --- child executor -----------------------------------------------------------
# run_child <unit> <attempt> <prompt> [resume-session]
# Attempt 1: fresh session in .agent/phase-sessions/.
# Attempt 1: fresh session in .agents/phase-sessions/.
# Attempt N>1: resumes the given session file — the failed executor's own
# session, tracked by execute_unit (so retries keep its work). When no
# session was captured (or FRESH_FIX=1) a fresh ephemeral session runs with
@@ -287,17 +287,17 @@ run_child() {
# --- validation gate ----------------------------------------------------------
ensure_validate() {
if [[ ! -f .agent/validate.sh ]]; then
cp "$SKILL_DIR/assets/validate.sh" .agent/validate.sh
chmod +x .agent/validate.sh
warn "no .agent/validate.sh found — created it from the skill template."
if [[ ! -f .agents/validate.sh ]]; then
cp "$SKILL_DIR/assets/validate.sh" .agents/validate.sh
chmod +x .agents/validate.sh
warn "no .agents/validate.sh found — created it from the skill template."
warn "adapt it to this project's real test/lint/coverage commands; it is the pass/fail gate after every task."
fi
}
# run_validation <logfile>; returns 0 iff .agent/validate.sh exits 0.
# run_validation <logfile>; returns 0 iff .agents/validate.sh exits 0.
run_validation() {
bash .agent/validate.sh >"$1" 2>&1
bash .agents/validate.sh >"$1" 2>&1
}
# --- notifications ------------------------------------------------------------
@@ -382,8 +382,8 @@ execute_unit() {
errors+="[child run ended without a clean final report]"$'\n'"$(tail -c 4000 "$(unit_report "$unit" "$attempt" err)" 2>/dev/null)"
fi
if ! run_validation "$(unit_report "$unit" "$attempt" validate)"; then
warn ".agent/validate.sh FAILED — see $(unit_report "$unit" "$attempt" validate)"
errors+="[.agent/validate.sh FAILED]"$'\n'"$(tail -n 120 "$(unit_report "$unit" "$attempt" validate)" 2>/dev/null)"
warn ".agents/validate.sh FAILED — see $(unit_report "$unit" "$attempt" validate)"
errors+="[.agents/validate.sh FAILED]"$'\n'"$(tail -n 120 "$(unit_report "$unit" "$attempt" validate)" 2>/dev/null)"
fi
if [[ -z "$errors" ]]; then
+3 -3
View File
@@ -2,7 +2,7 @@
# run-phase.sh — run every remaining task of one phase to completion.
#
# Each task runs in its own pi process (fresh context) with the
# .agent/validate.sh gate after every task; the phase ends with its
# .agents/validate.sh gate after every task; the phase ends with its
# 00_phase.md final pass.
#
# Usage:
@@ -16,12 +16,12 @@ set -uo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$SCRIPT_DIR/lib.sh"
# Make interruptions visible: state stays in .agent/phases/todo, and the
# Make interruptions visible: state stays in .agents/phases/todo, and the
# failed executor's session is still resumable on the next run.
trap 'echo; echo "✗ ERROR: interrupted (SIGINT) — ${phase:-this phase} is left in $PHASE_TODO/; re-run to continue" >&2; exit 130' INT
trap 'echo; echo "✗ ERROR: interrupted (SIGTERM) — ${phase:-this phase} is left in $PHASE_TODO/; re-run to continue" >&2; exit 143' TERM
cd "$(find_root)" || die "no .agent/phases/todo found in this or parent directories (run /to-phase or /audit-create first)"
cd "$(find_root)" || die "no .agents/phases/todo found in this or parent directories (run /to-phase or /audit-create first)"
phase="${1:-}"
if [[ -n "$phase" ]]; then
+2 -2
View File
@@ -16,12 +16,12 @@ set -uo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$SCRIPT_DIR/lib.sh"
# Make interruptions visible: state stays in .agent/phases/todo, and the
# Make interruptions visible: state stays in .agents/phases/todo, and the
# failed executor's session is still resumable on the next run.
trap 'echo; echo "✗ ERROR: interrupted (SIGINT) — ${unit:-this task} is left in $PHASE_TODO/; re-run to continue" >&2; exit 130' INT
trap 'echo; echo "✗ ERROR: interrupted (SIGTERM) — ${unit:-this task} is left in $PHASE_TODO/; re-run to continue" >&2; exit 143' TERM
cd "$(find_root)" || die "no .agent/phases/todo found in this or parent directories (run /to-phase or /audit-create first)"
cd "$(find_root)" || die "no .agents/phases/todo found in this or parent directories (run /to-phase or /audit-create first)"
unit="${1:-}"
if [[ -n "$unit" ]]; then