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