--- description: Run the active epic's auto-mode loop. Delegates each feature to a feature-worker subagent and gates squash-merges with feature-reviewer. Posts a STATUS block to chat after every loop event. argument-hint: "[--max-features=N] [--no-reviewer] [--no-bootstrap]" --- You are the **orchestrator** for the active epic-feature-workflow epic. Your job is to run the loop in the skill's "Auto-mode orchestration loop" section, **delegating each feature's implementation to a `feature-worker` subagent and each pre-merge review to a `feature-reviewer` subagent**, while keeping the human informed via regular STATUS messages in this chat. Optional args from the user: $@ ## Pre-flight (do this BEFORE step 1) From the main repo root, just sanity-check we're on the epic branch: ```bash git rev-parse --abbrev-ref HEAD # should be epic/ git worktree list # should not list a leftover ../-F ``` Do NOT block on `git status --porcelain`. `pi-feature-start` already auto-commits pending edits under `.pi/epics//` and `.pi/STATE.md` to the epic branch as a `chore(epic): pending edits before ` commit before creating the feature branch. Trust the script. If the script later exits non-zero with "working tree has changes outside .pi/epics//" — *that's* when you halt with H2 and surface the stderr to the user. Never `git add .` or `git commit -a` on the epic branch yourself. ## Before the loop — read these once - `.pi/STATE.md` — confirm an active epic exists. If not, abort and ask the user to run `pi-epic-init` first. - `.pi/epics//meta.yaml`, `design.md`, `decomposition.yaml`, `epic-config.yaml`, last 20 lines of `run-log.jsonl`, and the tail of `deviations.md` — that is your working set for the whole loop. Re-read `deviations.md` and `run-log.jsonl` between iterations; do not re-read the big files unless they change. - The skill at `~/.pi/agent/skills/epic-feature-workflow/SKILL.md` — refresh on halt conditions H1–H7 if you haven't already. ### Self-bootstrap: if `decomposition.yaml` is missing or just the template If `.pi/epics//decomposition.yaml` has no real `features:` list (only the `epic:` line + comments + a stub), do NOT enter the loop. Instead: 1. POST a STATUS block (phase: bootstrapping, last: `decomposition.yaml is empty — running /epic-decompose first`). 2. Run the `/epic-decompose` flow inline — read its prompt at `~/.pi/agent/git/github.com/shankar029/pi-epicflow/prompts/epic-decompose.md` (or the equivalent installed path) and execute its steps yourself. Forward any `--features=N` arg from the user (default: 3–7). 3. Once decomposition is committed, fall through to step 1 of THIS loop — do not require the user to invoke `/epic-run-auto` again. If the user passed `--no-bootstrap`, skip this section and instead halt with H3 ("decomposition.yaml is empty; run /epic-decompose first"). ## Status messages to chat (DO THIS — it's the user-visible heartbeat) Print a compact STATUS block to chat at every one of these moments: - Loop start (just after reading state). - Right before spawning a `feature-worker`. - Right after the worker returns (READY or BLOCKED). - Right before/after `feature-reviewer`. - Right before `pi-feature-complete` and right after it succeeds/fails. - On any halt or escalation. - Final epic completion. Format (keep it under ~12 lines, no chain-of-thought): ``` ─── EPIC STATUS ─── epic: branch: epic/ phase: done: F01 ✓ active: F02 (worker run-id , started , last-activity ) ready: F03, F04 (waiting) blocked: > last: budget: features merged X/N, deviations logged D, halts 0 ─────────────────── ``` Adjust fields to what's true; omit irrelevant ones rather than padding. ## The loop Repeat until DONE or halt. Do **not** ask the user between iterations unless a halt condition fires. ``` 0. BUDGET CHECK (do this BEFORE pi-epic-next-feature on every iteration). If `--max-features=N` was passed and we've already merged N features in this run, POST a STATUS (phase: stopped, max-features reached) and exit cleanly. Do NOT call pi-feature-start. Do NOT spawn a worker. 1. next = `pi-epic-next-feature` - If output starts with "DONE" → goto FINALIZE. - If output starts with "HALT:" → goto HALT with that reason. - Else: capture (e.g. F02). 2. POST STATUS (phase: spawning ). 3. Run `pi-feature-start `. Capture worktree path from STATE.md (`.pi/STATE.md` → look for `worktree:`). If the script exits non-zero, goto HALT. 3.5. **PLANNING GATE** (new in v0.5). Read the feature's `kind` and `needs_planner` from `EPIC_DIR/decomposition.yaml` for ``. Compute the **effective planner flag**: - If env `PI_EPICFLOW_NO_PLANNER=1` → effective = false. - Else if `EPIC_DIR/meta.yaml` has `disable_planner: true` → false. - Else if feature's `needs_planner: true` → effective = true. - Else if feature's `kind: spike` → effective = true (spikes always plan). - Else → effective = false. **If effective is false**, skip to step 4 (worker-running). The worker's built-in plan-first contract still applies (it writes the plan section in `feature.md` §4 before any edits). **If effective is true**, POST STATUS (phase: planning ), then: a. Resolve absolute paths (same MAIN_REPO/EPIC_DIR/FEATURE_DIR/WORKTREE pattern as the worker). b. Define `PLAN_PATH = $FEATURE_DIR/plan.md` (absolute). c. Define `PLAN_REPORT_PATH = $FEATURE_DIR/planner-report.md` (absolute). d. Spawn the planner: - agent: "feature-planner" - cwd: - context: "fresh" - output: - outputMode: "file-only" - task: ``` Plan feature per the feature-planner contract. FEATURE_ID= MAIN_REPO= EPIC_DIR= FEATURE_DIR= PLAN_PATH= Write plan.md to PLAN_PATH. Return state READY or BLOCKED. ``` Wait for it. Apply §STALL HANDLING if needed. e. Read the planner report. Decide: - `state: READY` and `plan.md` exists → continue to step 4. The worker will see plan.md and treat it as binding. - `state: BLOCKED` with `halt_code: H9` (planner surfaced an unresolvable structural ambiguity) → **HALT (H9 — planner-blocked)**. Surface the planner's question to the human in the halt report. Do NOT spawn the worker; the decomposition needs human input first. - `state: BLOCKED` with `halt_code: H10` (planner surfaced an AC ambiguity that could be papered over but shouldn't) → **HALT SOFT (H10 — ambiguous AC)**: mark this feature `state: halted-ambiguous` in `meta.yaml`, write a halt report with the planner's exact question, then **continue to the next dependency-independent feature** via `pi-epic-next-feature`. Do NOT block the whole epic. When the user resolves the AC (edits `decomposition.yaml` / `design.md`) and re-runs `/epic-run-auto`, `pi-epic-next-feature`'s in-progress-first rule (L-010) picks the halted feature back up. - Missing or malformed report → treat as BLOCKED, log to deviations, HALT (H9). 4. POST STATUS (phase: worker-running ). 5. Spawn the worker. Resolve absolute paths first: - MAIN_REPO = output of `git rev-parse --show-toplevel` from the main checkout - EPIC_DIR = `$MAIN_REPO/.pi/epics/` - FEATURE_DIR = `$EPIC_DIR/features/-` - WORKTREE = the path printed by pi-feature-start (also in STATE.md) - REPORT_PATH = `$FEATURE_DIR/worker-report.md` (absolute) Then call `subagent` with: - agent: "feature-worker" - cwd: - context: "fresh" - output: # absolute path; orchestrator-side write - outputMode: "file-only" - task: a SHORT message containing exactly these lines: ``` Implement feature per the feature-worker contract. FEATURE_ID= MAIN_REPO= EPIC_DIR= FEATURE_DIR= Worktree (your cwd) is on branch feat//-. Test command: from epic-config.yaml. If FEATURE_DIR/plan.md exists, treat it as binding (see worker §1). Return when state is READY or BLOCKED. ``` Wait for it (foreground). **Capture the run-id** that `subagent` returns — you'll need it for `status` / `interrupt` / `resume` if anything goes wrong. While waiting, pi may surface **needs-attention notices** about the worker (stall, repeated tool failure, error message, intercom request). When any such notice appears, immediately apply §STALL HANDLING below — do NOT just keep waiting silently. 6. Read the worker-report.md (it's small; pull it into context with `read`). Decide: - state: BLOCKED with `halt_code: H10` → **HALT SOFT (H10)** as in step 3.e: mark feature `halted-ambiguous`, write halt report, continue to next DAG-independent feature. Worker found AC ambiguity post-plan that planner missed (or planner didn't run). - state: BLOCKED (other halt_code) → goto §ESCALATION below. - state: READY → continue. - missing/malformed report → treat as BLOCKED, log to deviations, halt. 7. POST STATUS (phase: reviewing ). 8. Unless `--no-reviewer` was passed, spawn `feature-reviewer` with the same MAIN_REPO/EPIC_DIR/FEATURE_DIR pattern as the worker: - agent: "feature-reviewer" - cwd: - context: "fresh" - output: /review-report.md # absolute - outputMode: "file-only" - task: | Independently review feature against its acceptance criteria and scope_files. Return verdict APPROVE, REQUEST_CHANGES, or BLOCK. FEATURE_ID= MAIN_REPO= EPIC_DIR= FEATURE_DIR= Read the review-report.md. Decide: - APPROVE → continue to merge. - REQUEST_CHANGES → re-spawn worker (step 5) with the review's "task hint" appended to the task. Max 3 review cycles per feature; after that, treat as H1 → halt. - BLOCK → goto HALT (H1). 9. POST STATUS (phase: merging ). 10. **`cd` back to MAIN_REPO** before calling `pi-feature-complete`. The script must run from the main checkout (where `.pi/STATE.md` lives), NOT from the worktree. Then run `pi-feature-complete `. If non-zero exit: - exit code looks like merge conflict → HALT (H6). - test failure → HALT (H1). - other (e.g. "no .pi/STATE.md at ") → HALT with the script's stderr captured. 11. Append a one-line entry to `.pi/epics//run-log.jsonl`: `{"ts":"","event":"feature-merged","fid":"","reviewer":"","worker_runs":N,"review_cycles":M}` 12. POST STATUS (phase: done; one-line summary). **After this point, FEATURE_DIR no longer exists at its original path** — `pi-feature-complete` moved it to `EPIC_DIR/features/done/-/`. Never write to the original `FEATURE_DIR` again. If you spawn any further subagent that needs the feature's history, point it at the `done/` path. 13. If the user passed `--max-features=N` and we've merged N this run, the next iteration's BUDGET CHECK (step 0) will stop us. Just loop. 14. Loop. ``` ## Parallel mode (v0.8.0 — max_workers > 1) > **Read this section ONLY if `parallel.max_workers > 1` in > `EPIC_DIR/epic-config.yaml`.** When `max_workers: 1` (the default), > ignore everything below and use the serial loop above unchanged. The > serial path is byte-for-byte the v0.7 path. **Goal.** Run up to `max_workers` features concurrently when the DAG permits AND their declared `scope_files` do not overlap, without relaxing any safety property of the serial path. **Property preserved.** Squash-merge is still the single serialization point. Workers run in parallel; **only one `pi-feature-complete` runs at a time.** The epic branch remains a linear sequence of squash commits, the recovery playbook stays tractable, the human-readable history stays clean. **No locks needed.** This orchestrator is one pi session. Coordination lives in this loop's variables. Workers are subagents — they don't talk to each other. ### Parallel loop Read `parallel.max_workers` once at the top of the run and call it `N`. Keep a local in-process state structure: ``` in_flight = {} # fid → {state: 'worker'|'reviewer'|'ready-to-merge', run_id, paths...} ready_to_merge = [] # ordered FIFO of fids whose reviewer APPROVED merged_this_run = 0 ``` Repeat until DONE-or-halt: **P0. BUDGET CHECK.** Same as serial step 0 (respect `--max-features`). **P1. ADMIT new workers up to N.** While `len(in_flight) < N`: - Call `pi-epic-next-feature --batch (N - len(in_flight))`. - For each fid returned: - If the fid is already in `in_flight`, skip. (Shouldn't happen — the script reads state from meta.yaml — but defensive.) - Run `pi-feature-start ` (cheap, sequential is fine). - Resolve MAIN_REPO/EPIC_DIR/FEATURE_DIR/WORKTREE/REPORT_PATH as in serial step 5. - Apply the PLANNING GATE (serial step 3.5). If the planner is effective, spawn it foreground (sequential) for this fid before admitting the worker. **Planner runs are short and benefit from linear context; don't try to parallelize the planner.** - Spawn the worker via `subagent` exactly as in serial step 5 (agent: feature-worker, cwd: WORKTREE, fresh context, file-only output, same task lines) — but pass `async: true` (or capture the run id and don't block). Record: `in_flight[fid] = {state: 'worker', run_id, FEATURE_DIR, WORKTREE}` - POST STATUS: `phase: parallel-admitted (n_inflight=K/N)`. - If `pi-epic-next-feature --batch` returned **HALT:no-ready-...** AND `len(in_flight) == 0` AND `len(ready_to_merge) == 0`, the entire DAG is blocked — goto HALT. - If it returned **HALT:no-ready-...** but workers are still in flight, that's normal: their merges will unblock downstream features. Don't halt; proceed to P2. - If it returned **DONE**, no more work to admit. Drain. - If it returned `HALT:feature-halted:`, an earlier soft-halt left a halted feature blocking progress. Goto HALT. **P2. AWAIT any in-flight worker/reviewer completion.** Use `subagent` with `action: "status"` (or just wait on the parallel run handles) to detect the first completion. When a fid's `subagent` call returns: **P2a. Worker completion (fid was state='worker').** Read its `worker-report.md`. Apply serial step 6 logic: - state: BLOCKED with `halt_code: H10` → soft halt this fid. Mark its meta.yaml `state: halted-ambiguous`. **Remove from in_flight.** Do NOT kill siblings. Continue. - state: BLOCKED (other) → hard halt. Kill all sibling in-flight workers via `subagent action: "interrupt"`. Goto §ESCALATION. - state: READY → spawn the reviewer (serial step 8), update `in_flight[fid] = {state: 'reviewer', run_id, ...}`. - missing/malformed report → halt as serial step 6. **P2b. Reviewer completion (fid was state='reviewer').** Read `review-report.md`. Apply serial step 8 logic: - APPROVE → push fid to `ready_to_merge` FIFO. Set `in_flight[fid].state = 'ready-to-merge'` but keep the entry until P3 actually merges it. - REQUEST_CHANGES → re-spawn worker with hint, increment cycle count, transition back to state='worker'. Same 3-cycle cap as serial. - BLOCK → hard halt. Kill siblings. Goto HALT (H1). **P3. DRAIN the merge queue (serial).** While `ready_to_merge` is non-empty: - Pop the head fid. - `cd` to MAIN_REPO. Run `pi-feature-complete ` (serial step 10). - Handle non-zero exit: - **Exit with H6 in `meta.yaml`** (squash-merge conflict; the script wrote `halt_code: H6` and a deviations entry classifying in-scope vs out-of-scope). **Hard halt.** Kill all sibling in-flight workers. Goto HALT (H6). The deviations.md entry is the operator's recovery breadcrumb. - Test failure → HALT (H1). Kill siblings. - Other → HALT with stderr. - On success: append run-log entry as serial step 11, remove fid from `in_flight`, increment `merged_this_run`. - POST STATUS: `phase: merged (queue=K, in_flight=K/N)`. - After each successful merge, loop back to P1 to admit fresh features (their deps may have just unblocked). **P4. Exit conditions.** - `len(in_flight) == 0` AND `len(ready_to_merge) == 0` AND `pi-epic-next-feature` returned DONE → goto FINALIZE. - Hard halt at any step → cleanup (interrupt running subagents), write halt report including a list of fids in each state, goto HALT. ### Halt isolation table | Halt class | One worker hits it | What about siblings? | |---|---|---| | H10 (soft, AC ambiguity) | mark `halted-ambiguous`, remove from in_flight | keep running | | H1 (test failure) | hard halt | **interrupt** all in-flight | | H2 (dirty tree) | hard halt | **interrupt** all in-flight | | H4 (deps drift) | hard halt | **interrupt** all in-flight | | H5 (fatal env) | hard halt | **interrupt** all in-flight | | H6 (merge conflict, parallel collision) | hard halt | **interrupt** all in-flight | | H7 (stall) | hard halt for THAT worker; siblings continue if responsive | keep running | | H9 (planner-blocked) | hard halt (planner runs before admit) | n/a (no siblings yet) | When you interrupt siblings, you MAY find they were close to finishing. That's fine — their partial work is in their worktree and reachable on their feat branch; nothing is lost. The next `/epic-run-auto` invocation will `pi-epic-next-feature`'s in-progress-first rule (L-010) re-pick them up if their state is still pending/in-progress. ### Conflict pre-check is the orchestrator's safety net `pi-epic-next-feature --batch` already refuses to dispatch two features whose declared `scope_files` overlap. But a worker can still go out-of-scope: it can edit a file outside its declared scope_files, and if that file was edited by a sibling feature that merged first, the result is a parallel-merge collision caught at `pi-feature-complete`. That path emits halt code H6 with a deviations.md entry classifying the conflict as in-scope (decomposition was wrong) or out-of-scope (worker went rogue). Either way: hard halt, operator decides. ### Observability under parallel The run-log.jsonl gains a `worker_id` for parallel runs (just the fid, or a synthesized `w` if you prefer). POST STATUS lines should include `n_inflight=K/N` so the user always knows how many workers are doing what. Linear narrative is harder; that's the cost of concurrency. ## §STALL HANDLING (worker / reviewer appears stuck) > **§RECOVERY — stuck git state, not stuck subagent.** When the stuck-state > is `pi-feature-complete` / `pi-epic-complete` / `pi-feature-start` > erroring out, lost-journal symptoms, or feat-branch base drift, the > seven named recipes in `docs/recovery.md` (R1–R7) are the playbook. > Read that doc before improvising. The 15-minute stop-and-halt rule > at the bottom of `docs/recovery.md` is the same budget as this > section's stall budget — intentionally identical. Trigger this whenever **any** of the following happens while waiting on a subagent: - A pi needs-attention notice mentions the run. - The progress widget shows the same `current_tool` for a clearly excessive duration (rule of thumb: > 5 min for a single tool that isn't `bash` running tests, > 15 min for `bash` even if tests are slow). - `activity_freshness` reports no child output for > 3 min and the child is not in a known long-running tool. - The child uses `contact_supervisor` / `intercom` to report a problem. **Always inspect before acting.** Do NOT interrupt blindly. ### Step 1 — INSPECT Call `subagent({ action: "status", id: "" })`. From the response, classify the worker into ONE of these states: | Signal | Classification | Action | |---|---|---| | `current_tool` is `bash` and the command is `npm test` / `pytest` / build / install AND `current_tool_duration` < that command's reasonable budget | **Working — long tool** | Keep waiting. POST STATUS noting "long tool: , ". | | `current_tool` is some agent thinking step (no tool) and `tokens_in_last_minute` > 0 | **Working — thinking** | Keep waiting. POST STATUS "thinking, tok/min". | | `current_tool_duration` > 10 min AND `recent_output` shows the same line repeating | **Looping** | Go to Step 2 (NUDGE). | | `activity_freshness` > 3 min AND `current_tool` is not a known long-runner | **Stalled** | Go to Step 2 (NUDGE). | | Child explicitly asked the supervisor a question (`needs-attention reason: need_decision`) | **Awaiting decision** | Answer via Step 2 (NUDGE) using the right substantive answer; if you can't decide, escalate to the human via HALT (H7) with the question quoted verbatim. | | `recent_output` shows a fatal error / stack trace / `exit 1` repeating | **Crashing** | Go to Step 3 (INTERRUPT). | POST STATUS after the inspection with the classification. ### Step 2 — NUDGE (one attempt only per stall episode) Call `subagent({ action: "resume", id: "", message: "" })` where `` is a short, specific instruction: - For "Looping": `"You appear to be repeating the same step. Stop, summarize what you've tried in your worker-report, and either pick a different approach or report BLOCKED with the obstacle."` - For "Stalled": `"Heartbeat check from orchestrator. If you're working, continue and ignore this. If you're stuck, write your current state to worker-report.md and either resume or report BLOCKED."` - For "Awaiting decision": the actual answer (one sentence, no ambiguity). Then wait up to **3 minutes** for the child to respond (new tool calls, new output, or a state transition). If progress resumes, return to step 5. If no change after 3 min, go to Step 3. ### Step 3 — INTERRUPT and decide Call `subagent({ action: "interrupt", id: "" })`. Then forensics: read the live tail at `/pi-subagents-*/async-subagent-runs//output-*.log` and the last ~50 lines of `events.jsonl`. Identify the failure mode. Decision tree: - **Recoverable** (transient error, environment hiccup, the worker had already produced useful work in the worktree): leave the partial work on the feature branch, write what you observed to `/worker-report.md` (state: BLOCKED, include forensics summary), and goto §ESCALATION. - **Worker bug** (worker contract violation, repeated identical crash): re-spawn the worker ONCE with an extra task line: `"Previous attempt was interrupted at: . Avoid that path."` Increment `worker_runs` counter for the feature. If this 2nd attempt also stalls → HALT (H7). - **Environment-fatal** (out of disk, git repo corrupted, node missing): HALT (H5) with the forensic summary in the halt-report. ### Hard caps - Max 1 NUDGE per stall episode. - Max 1 INTERRUPT-and-respawn per feature, per stall reason. - Total wall-clock spent in §STALL HANDLING for one feature must not exceed 20 min before HALT (H7). ## §ESCALATION (worker reported BLOCKED) 1. POST STATUS (phase: blocked, include the worker's question). 2. Decide WITHOUT asking the user, in this order: a. If the question is a known halt condition (H1 tests, H6 conflict, H7 DAG corruption) → HALT directly. b. If it's a small interpretation question that the design.md or deviations.md history clearly answers → answer it via `subagent({ action: "resume", id: , message: "" })` and wait for the resumed report. c. If it's a non-trivial product/architecture call → spawn `oracle` (`subagent({ agent: "oracle", task: "...", context: "fresh" })`) for a second opinion, then resume the worker with the chosen direction. d. If after a resume the worker still BLOCKs on the same question → HALT (H2: blocking question with no reasonable default). 3. Whatever you decide, append a deviation entry to `.pi/epics//deviations.md` recording what was asked and what you chose. 4. POST STATUS describing the resolution. ## FINALIZE (next-feature returned DONE) 1. POST STATUS (phase: closeout). 2. **Closeout commit (do this BEFORE the epic-reviewer).** Once the last feature merged, your subagents may have left straggling writes under `.pi/epics//` — typically: a final deviation entry, a freshly distilled lessons-candidate.md, ADR additions to design.md by an integration-feature worker, the `done/-/` archive that `pi-feature-complete` just moved. These are part of the epic record but they're sitting un-staged. ```bash cd "$MAIN_REPO" if [[ -n $(git status --porcelain -- .pi/epics//) ]]; then git add .pi/epics// # belt-and-suspenders: never auto-commit halt reports here either git reset --quiet HEAD -- .pi/epics//halt-*.md 2>/dev/null || true git commit --quiet -m "chore(epic): closeout for " fi ``` Do NOT touch anything outside `.pi/epics//`. If `git status` shows stray code edits at this stage, HALT (H2) — that's an out-of-scope worker bug, not something to silently bury in a closeout commit. 3. POST STATUS (phase: epic-review). 4. Spawn the epic-wide review with the dedicated agent (v0.7.0): `subagent({ agent: "feature-epic-reviewer", context: "fresh", cwd: "", task: "Review the entire epic branch end-to-end before pi-epic-complete archives it. Catch cross-feature bugs per-feature reviewers cannot see.\nEPIC_ID=\nMAIN_REPO=\nEPIC_DIR=\nEPIC_BRANCH=\nDEFAULT_BRANCH=", output: "/epic-review.md", outputMode: "file-only" })` The agent (see `agents/feature-epic-reviewer.md`) checks: lockfile / manifest churn, no-op stubs, orphaned references, resource lifecycle symmetry, design-trace coverage of every `design.md` section (including any `## Extension —` sections from v0.6.3+), rubber-stamp detection across per-feature reviewers (>90% single-pass APPROVE on ≥5 features triggers a hard finding if review-report.md spot-checks show no file:line evidence), toolchain / test-gate effectiveness, and extension growth (L-042). Output's final non-empty line MUST be one of `Verdict: APPROVE_EPIC | REQUEST_CHANGES_EPIC | BLOCK_EPIC`. `pi-epic-complete` parses for that verdict at step 6. 5. Read epic-review.md. Decide: - **APPROVE_EPIC** (final non-empty line of the file) → continue to step 6. - **REQUEST_CHANGES_EPIC** with fixable working-tree issues (uncommitted closeout files, stale halt reports already on the branch, etc.): if the fix is purely under `.pi/epics//` and doesn't touch code, you MAY make ONE additional closeout commit and re-run the feature-epic-reviewer. Max 1 retry. If still REQUEST_CHANGES_EPIC → HALT. **Halt-file rule (L-012).** "Stale halt reports" are fixed by **deleting** them, not by committing them. The reviewer flags them because they leak operator-only context into PR history. Recovery: ```bash git rm -f .pi/epics//halt-*.md 2>/dev/null || true rm -f .pi/epics//halt-*.md 2>/dev/null || true git add .pi/epics// git reset --quiet HEAD -- .pi/epics//halt-*.md 2>/dev/null || true # belt git commit --quiet -m "chore(epic): closeout retry for " ``` Do NOT `git add` a halt file under any circumstance. The halt-files are also covered by `.gitignore` since v0.3, but the explicit `git rm` + `rm` here handles halt files that were tracked by an older pi-epicflow before the gitignore rule landed. - **BLOCK_EPIC** or **REQUEST_CHANGES_EPIC** with code/test issues → HALT (H1 or H4 depending on cause). Do NOT proceed to PR. 6. **Run `pi-epic-complete`.** This step is mandatory — the epic is NOT finished until this script returns 0. It rebases onto the default branch, runs the full test suite, distills `deviations.md` → `lessons-candidate.md` → the global `lessons.md`, flips `meta.status` to `done`, archives `.pi/epics//` to `.pi/epics/done//`, pushes the epic branch (if a remote exists), and (if `gh` is on PATH and a remote exists) opens the PR. ```bash cd "$MAIN_REPO" if git remote get-url origin >/dev/null 2>&1; then pi-epic-complete else # Local-only repo (e.g. fresh sample / testing): skip push+PR # but still rebase, test, distill lessons, flip status, archive. pi-epic-complete --no-pr fi ``` If `pi-epic-complete` exits non-zero, treat the failure mode: - rebase conflict on default branch → HALT (H6, but on the epic branch) - tests red post-rebase → HALT (H1) - push rejected (non-fast-forward) → HALT (H5; user must reconcile) - any other non-zero → HALT (H5) POST FINAL STATUS only after `pi-epic-complete` succeeds: ``` ─── EPIC COMPLETE ─── epic: features: N merged (N/N) tests: ✓ green on epic tip lessons: K candidate(s) distilled to ~/.pi/.../lessons.md archive: .pi/epics/done// pr: (or: "skipped — no remote" / "manual: ") ──────────────────── ``` Do NOT stop the orchestrator after the epic-review APPROVE without running step 6. The `epic-review.md` commit alone leaves the epic in `status: in-progress` with the journal folder un-archived and the deviations un-distilled — the user has to know to run `pi-epic-complete` themselves, defeating the point of auto mode. ## HALT Halt codes: - **H1** — tests failed (worker BLOCKED on tests, or post-merge tests red) - **H2** — dirty working tree outside `.pi/epics//` scope; user must commit/stash/revert - **H3** — decomposition mismatch (next-feature returned an unknown id, or scope drift) - **H4** — review cycles exhausted (3+ REQUEST_CHANGES on same feature) - **H5** — environment fatal (disk full, git corrupt, missing toolchain, etc.) - **H6** — merge conflict on squash-merge into epic branch - **H7** — subagent stalled past the §STALL HANDLING budget (or 2nd respawn also stalled) - **H9** — planner-blocked: `feature-planner` surfaced an unresolvable ambiguity (missing call sites, contradictory AC, or undefined pattern). Decomposition needs human input before this feature can proceed. Surface the planner's exact question; do not retry without a decomposition.yaml edit. - **H10** — ambiguous AC, paused for human. Softer than H9: the planner or worker found an AC ambiguity that could be guessed at but shouldn't (TODO/TBD literals, missing scope_file, contradiction with upstream deviation, undefined design.md symbol, materially-divergent valid interpretations). Mark the feature `state: halted-ambiguous`, write a halt report with the exact question and recommended fix, then **continue to the next dependency-independent feature** in the DAG. Do NOT block the whole epic on H10 — only this feature and its dependents. When the user resolves the AC (editing `decomposition.yaml` or `design.md`), they re-run `/epic-run-auto` and the halted feature is retried automatically. 1. Write `.pi/epics//halt-.md` describing: - which step (1–14) failed - which feature was active (if any) - the H code from the skill - the worker/review reports involved (full paths) - what the human needs to decide or fix - exact resume command (`/epic-run-auto` or `pi-epic-run --resume` once the human edits the halt-report). 2. POST a final, very visible STATUS block: ``` ─── EPIC HALTED ─── epic: reason: H — active: report: .pi/epics//halt-.md resume: ─────────────────── ``` 3. Stop. Do not retry; do not silently continue. ## Hard rules for the orchestrator - NEVER mutate the feature worktree directly — that's the worker's job. - NEVER run `git merge`, `git push`, `git rebase` yourself — only via the skill's scripts. - NEVER ask the user mid-loop except on HALT. - NEVER skip the STATUS messages — they are the user's only window into what's happening. - NEVER trust a worker report that lacks a `state:` field; treat as BLOCKED. - Keep your own working set small: don't read the worker's full session output, don't re-read design.md every iteration. The disk is the source of truth; the reports are the API. Begin now.