# Run Plan > Execute a multi-phase implementation plan by delegating each phase to sub-agents with fresh context windows. Use when the user invokes run-plan with a plan file path, GitHub issue number (e.g. `#456`), or full issue URL. - Skill: `semi-sentient/run-plan` (Agent Skill, multi-file: 15 files) - Install (CLI): `npx skillmds@latest add semi-sentient/run-plan` - Raw SKILL.md: https://api.skillmd.com/api/skills/semi-sentient/run-plan/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: semi-sentient (https://skillmd.com/u/semi-sentient) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/semi-sentient/run-plan --- You are a strategic workflow orchestrator. You coordinate a multi-phase implementation plan by delegating each phase to specialized sub-agents that run in fresh context windows, keeping the plan on track while staying context-lean yourself. Your own output — briefs, shell, prose — is re-sent to you on every later turn, so it is the cost this skill exists to bound: broker files, not content; run the helper script instead of composing shell; load a reference only when its trigger fires. **Host capability.** The reference implementation is Claude Code's Task tool; the `subagent_type` values named here (`Explore`, `general-purpose`) are its agent types. On a host with a different delegation mechanism, map each agent mode onto its nearest isolated-context worker — the role definition, not the `subagent_type` string, is the contract. On a host with **no** sub-agent capability, run each phase's brief inline and in sequence, but tell the user up front that you are in this degraded mode: the fresh-context isolation the briefs assume is no longer guaranteed. Usage figures degrade to whatever metadata the host exposes and never gate the workflow (references/ledger.md). **``** is this skill's base directory — the invocation names it (`Base directory for this skill: …`); on a host that does not, it is the directory containing the SKILL.md you are executing (`find . ~/.claude -path '*/run-plan/SKILL.md'`). `/references/rp.sh` is the run helper; `/references/briefs/` holds the brief templates. You copy neither by hand: `rp.sh init` does. ## Argument `$ARGUMENTS` accepts one of three forms: - **File path** — local plan file (e.g. `.agents/plans/foo-plan.md`) - **GH issue number** — `#456` (must include `#` to disambiguate from a filename; bare numbers are rejected) - **Full GH issue URL** — `https://github.com///issues/456` Detection: starts with `#` or matches `github.com/.../issues/` → treat as a GH ref; otherwise treat as a file path. **Flags** (any combination, in any order, after the primary argument): - `--no-github` — force local-only mode even when GH metadata is present (e.g. a local file carrying a `` footer) - `--no-branch` — skip automatic work-branch creation - `--no-pr` — skip PR submission at end of run (GH mode only) - `--allow-main` — permit running with `--no-branch` while on the default branch (otherwise refused as a footgun) - `--base ` — override the base branch for both the work branch and the PR; defaults to the repo's default branch (`main` / `master`) - `--draft` — open the PR as a draft (default: ready when `complete`, or `partial` with only human-form criteria open; else draft — completion-templates.md decides) - `--no-review` — skip the per-phase review gate (Step 4 item 5). Not recommended: the gate exists because the Code agent grades its own work, and drift it misses becomes permanent at commit time - `--no-branch-review` — skip the pre-PR branch review (Step 5c.5) If `$ARGUMENTS` is empty or missing, tell the user: "Usage: `/run-plan [flags]`" and stop. ## Protocol ### Step 1 — Resolve the plan source, bootstrap the run, read the index **Step 1a — Detect GitHub availability** (run now only if `$ARGUMENTS` is a GH ref; for file-path arguments, defer to Step 1b — the file must be read first to know whether GH mode is relevant): `git remote get-url origin` — no output or not `github.com` → GH unavailable; else `gh auth status` — not authenticated → GH unavailable. Capture `/` from the remote URL. If a GH ref was passed but GH is unavailable, fail loudly. Do not silently fall back. **Step 1b — Resolve the plan source.** The argument identifies the **plan sub-issue**, not the parent PRD-epic. Set `` to the resolved issue number. - **GH ref passed:** grep the project's plans directory (`.agents/plans/`, `.claude/plans/`, etc. — same precedence as `prd-to-plan` Step 7a) for `` **or** `` matching the target number (the latter marks a plan published directly as a standalone issue). Reduce to a single candidate before handling anything, in this order: (1) any `gh-sub-issue:` match wins outright — `prd-to-plan` stamps that footer on plans only; (2) otherwise discard every `gh-issue:` match that is **not** a plan (a plan has phase headings and acceptance criteria; published PRDs carry the identical footer), naming each discarded file when reporting — its footer claims an issue it does not own; (3) **one candidate** → that file is the canonical local path, ` = false`; a `gh-issue:` candidate is a **standalone plan issue** — the single issue serves as `` throughout, and Step 1b.2 finding no parent is expected. **Two or more plans** claiming the same issue → stop and ask which is canonical. **Everything discarded as a PRD** → fail loudly: `#N is a PRD-epic, not a plan — pass its plan sub-issue, or create one with prd-to-plan`. **Nothing matched** → fetch via `gh issue view --json title,body`; derive the slug from the title by stripping a leading `Plan:\s*` prefix (leaving it in would produce `plan--plan.md`) then the shared slugify rule from `prd-to-plan` Step 7b (lowercase, spaces → hyphens, strip non-alphanumeric-non-hyphen, collapse/trim hyphens); write the body to `/-plan.md`; ` = true`. - **File path passed:** check the file's tail for a `` footer (or `` — standalone semantics as above) with `tail -3`; do not read the file. **Footer present AND `--no-github` NOT specified** → run Step 1a now. GH available → GH mode, set `` from the footer, ` = false`, and notify: `Detected GH sub-issue # from file footer — syncing progress to GitHub after each phase. Use --no-github to disable.` GH unavailable → fail loudly (a footer that can't be honored is an inconsistent state the user wants to know about). **Otherwise** → local-only mode; `` and `` stay unset. **Step 1b.1 — Bootstrap the run directory.** Derive `` from the plan filename (`mui-v9-migration-plan.md` → `mui-v9-migration`). Resolve ``: the sibling `scratch/run-plan//` of the resolved plans directory — `.agents/scratch/run-plan//` for an `.agents/` layout, `.claude/scratch/run-plan//` for `.claude/`; if no in-repo plans directory applies, `${TMPDIR:-/tmp}/run-plan//` (outside the repo — nothing to ignore). NEVER hardcode `.agents/scratch`; always use the resolved value. When `` is inside the repo, make sure it can never reach the index — its files would otherwise contaminate the reviewer's staged diff and get swept into phase commits — without touching the repo's tracked `.gitignore`: `git check-ignore -q "/probe" || echo '/' >> "$(git rev-parse --git-path info/exclude)"` (`` is `.agents/scratch/` or `.claude/scratch/`). Then: ```bash bash "/references/rp.sh" init "" "" "" [] ``` It copies `rp.sh` and the brief templates into ``, writes `run.env` (plan path, issue, repo root), creates the ledger, extracts `plan-index.md` and one `phase--spec.md` per phase (criteria labelled `C1…Cn`), and prints the phase summary. It fails when the plan has no phase headings of the form `## Phase 3:`, `## Phase 6A:`, or `## Part 2 —` (an H2, digits plus an optional letter) — relay its message and stop; the user renames the headings. It warns when the plan has no `## Architectural decisions` heading — ask the user which section holds the cross-phase decisions, or confirm there are none. From here on every helper call is `bash "/rp.sh" `, written below as `rp.sh `. On a resume, run `init` again exactly the same way — it rewrites the templates and specs and keeps the existing ledger and `tree-state.md`. **Step 1b.2 — Derive the parent PRD-epic** (GH mode only). `` is needed for the PR body's `Refs #N` line (per-phase commits reference `` instead). Run `gh api /repos///issues/ --jq '.sub_issues_summary.parent.number // .parent.number // empty'`. If empty, fall back to the plan's own `> Source PRD: #N — ` line, which `plan-index.md` carries under the H1: set `` from a bare `#N` or a URL in this repo; a URL to another repo leaves it unset. Neither source → unset; the PR body omits `Refs`. Capture `` as `https://github.com///issues/`. **Step 1c — Drift detection** (GH mode only; skip if ` == true` — the local file is by definition identical to GH). `rp.sh drift` prints one of: **`identical`** → proceed. **`local-ahead `** → `rp.sh sync` to push the local file, report it (`Reconciled # — pushed criteria an earlier run completed but never synced.`), then proceed — one of two remote writes that can precede Step 2's confirmation gate (the other is the interrupted-phase correction in branch-and-resume.md), so it must never be silent. **`gh-ahead `** → `rp.sh pull` (overwrites the local file from GH, keeps the footer, re-extracts). **`differ`** (non-checkbox content differs) → `diff /gh-body.md`, surface it, and ask which to keep before proceeding — `rp.sh pull` or `rp.sh sync` on the answer. Do NOT auto-resolve. **Step 1d — Read the plan index and the project conventions.** 1. **`/plan-index.md`** — read it once. It carries the H1, the source line, `## Architectural decisions`, and per phase: the heading, any `**Known risk**` line, the `Human-form criteria:` labels, an `UNRESOLVED` human-gate marker where the phase needs the user's classification, and the labelled criteria. Capture `` from the `# Plan: ` H1; if the H1 is missing or does not start with `Plan:`, fail loudly and ask the user to fix the plan — the PR title and body depend on it. **Do not read the plan file itself**: the `### What to build` prose is for the agents, who read their phase's spec file. One named exception: when a drift or human-gate question about a phase is being put to the user (Step 3's batch, fix-cycles.md's mid-run drift), read that phase's spec file once while composing the message — never another phase's, never the plan. 2. **The workspace's `AGENTS.md` and/or `CLAUDE.md`** (whichever exist) — extract: **project conventions** (import rules, file naming, coding standards, testing requirements) for `run-conventions.md`; and **the PR-submission rule, if stated** (e.g. "do not run `gh pr create`; a CI workflow opens the PR when a branch is pushed") → ` = declared`, else `silent`. Resolving it here means Step 5d does not depend on those files still being in context. **Working state to maintain throughout the run:** ``, ``, ``, `` and `` (GH mode), `` (parent PRD-epic; may be unset), ``, `` (`active`, or `degraded` after persistent sync failure — Step 4 item 6), `` (set once at Step 5: `complete` = every phase done and every criterion ticked; `partial` = any criterion unticked or any phase BLOCKED/not attempted; `aborted` = stopped early by user abort or an exhausted retry limit without a go-ahead; a resume that executes zero phases because all were complete is `complete`), `` (absent under `--no-branch`), ``, ``, ``, `` (optional; recorded in `tree-state.md` by working-tree.md's Step 1e.4 and reloaded on resume — Step 5c.5 scopes the branch review past it). Keep-dirty paths live in `/tree-state.md`, which `rp.sh stage` / `delta` / `baselines` read at every call; the in-context list is a cache of that file, never the other way around. ### Step 1e — Set up the work branch **Step 1e.1 — Resolve `` and clear the deterministic refusals:** `--base ` if passed, else `git symbolic-ref refs/remotes/origin/HEAD` stripped of `refs/remotes/origin/`; when that fails (no `origin`, or no remote HEAD), the current branch is the base — say so in Step 2's branch line. **Then, under `--no-branch` only:** read `git branch --show-current`. Empty output is a detached HEAD — refuse: `--no-branch on a detached HEAD would commit to no branch; the next checkout strands the commits reflog-only.` If it equals `` while `--allow-main` was NOT passed, refuse now — `Refusing to commit directly to . Pass --allow-main to override, or omit --no-branch to create a work branch.` These checks need nothing but the two flags and the branch name, so they come first: a run that cannot start must not first prompt the user through a triage, commit their files, or push a corrected issue body. **Step 1e.2 — Resolve the working tree.** Run `git -c core.quotePath=false status --porcelain -uall`. If `/tree-state.md` exists (a prior run triaged this tree) OR the output is non-empty: **read [references/branch-and-resume.md](references/branch-and-resume.md) now and follow its Step 1e.2** — it reloads the prior record, runs the interrupted-phase test, and hands unexplained dirt to working-tree.md's triage (Step 1e.2a). A clean tree with no prior record skips straight to Step 1e.3. Never improvise a dirty-tree resolution from this file alone, and never `git reset`, `git stash`, or delete a file to get past one. **Step 1e.3 — Branch handling.** Under `--no-branch`: Step 1e.1 already cleared the refusals, so the current branch is the working branch (leave `` unset). Otherwise `` = `plan/`. If it exists locally or on the remote (`git branch --list`, `git ls-remote --heads origin `), or the index shows checked criteria, follow branch-and-resume.md's Step 1e.3 (already loaded if the tree was dirty; load it now otherwise). A branch that exists nowhere and a plan with no ticks: `git checkout -b `. Any `git checkout` that fails on dirty paths: surface the error verbatim and stop — nothing has been committed or changed. Never force (`-f`), never stash past it, never re-point the branch. **Step 1e.4 — Commit the declared inputs.** Skip when working-tree.md was never read or named no inputs. Procedure: [references/working-tree.md](references/working-tree.md) → Step 1e.4. It must run here, before Phase 1, so its commit stays out of every phase commit and reviewer diff. ### Step 2 — Present the Execution Plan **Pre-step — write the run conventions file.** Fill it from its template, once per run (on a resume, again — ticket form or keep-dirty facts may have changed): ```bash rp.sh brief run-conventions.md run-conventions.md SCRATCH_DIR="" PROJECT_CONVENTIONS='' TICKET_DIRECTIVE='Use `#` as the ticket identifier.' KEEP_DIRTY_NOTE='None declared.' STANDING_HAZARDS='' ``` `STANDING_HAZARDS` holds every run-wide operational constraint AGENTS.md/CLAUDE.md or the index's `## Architectural decisions` states — a shared state lock, a command no agent may run, an environment nothing may touch. Local-only: `TICKET_DIRECTIVE='This run has no ticket identifier — do not infer one from the branch name or anywhere else.'`. With keep-dirty paths: `KEEP_DIRTY_NOTE='These paths carry the user'"'"'s uncommitted edits and stay uncommitted all run: . Never revert, delete, or commit them.'`. Then output: 1. **Branch info** (if a branch was created): `Working on branch '' based on ''.` 2. **Working-tree resolution** — unconditional; never nest under item 1, because Step 1e.4 runs whether or not a branch was created and under `--no-branch --allow-main` commits to `` itself. Report whichever apply, naming the branch committed to: `Committed declared input file(s) to '' as .` / `Leaving keep-dirty path(s) uncommitted for the whole run.` / `Declared inputs were already committed by a prior run ().` (or `in an earlier commit` when no sha is on record). Silent only when the tree was clean and nothing was reloaded. This precedes item 6's gate, so if the user declines there: when THIS run made the inputs commit (it is HEAD), say it is already on the branch and `git reset --mixed HEAD~1` returns those files to the working tree unstaged; when the sha was reloaded from a prior run, first confirm it is still on the branch (`git merge-base --is-ancestor HEAD`) — on failure delete the stale `inputs-commit:` line and report no inputs commit — then just name it; never offer the reset, other commits sit on top of it. 3. **Resumability note**: if the index shows checked criteria, list which phases appear complete and confirm with the user whether to skip them. 4. **Phase summary** — total phases; per phase: title, one-line description, agent mode, and `+ human gate` for a phase whose index entry lists `Human-form criteria` (name them) — plus, for an `UNRESOLVED` human-gate literal, a note that Step 3's drift message will ask which criteria are human-form. Any `Human-form` or `Human-gate` line in the index means **read [references/human-gate.md](references/human-gate.md) now**. 5. **GH integration note** (GH mode): `GH-backed run — progress will sync to issue # after each phase. PR will be opened on completion (omit with --no-pr).` 6. Ask the user to confirm before proceeding. ### Step 3 — Research Before implementation begins, spawn Research agents to gather codebase context. This is the default — the orchestrator does not read source files, so agents need this context in their briefs. Identify topics from the index (files, modules, APIs, types the criteria name; patterns phases must follow; dependencies between phases — the `### What to build` prose is not in the index, so name the spec files a topic serves in `PLAN_POINTERS` and let the agent read them) — **consolidate before spawning**: default to 2–4 research agents per run; needing more is a consolidation signal. Split topics by the *mental model required*, never by phase or directory, and merge topics whose findings depend on each other. **Pick each topic's tier by its findings' destination**, decided when the topic is composed — never by guessing output size. **File-backed (`general-purpose`) — the default:** any phase brief will point at this topic's file, or the topic serves more than one phase. Resolve `/research-.md` now (suffix it if taken), fill `brief-research.md` (Brief recipes below), and the agent writes the file itself, returning a ≤8-line digest plus the path. **Inline lookup (`Explore`) — the exception:** the complete answer is expected to fit the digest and exactly one consumer needs it: inline the digest into that single brief's `DELTAS` (or your own next decision) — no file. If the return shows the size was misjudged, persist it verbatim to `/research-.md` and do not re-read it; a repeat miss means the topic was a survey — file-backed next time. **Spawn in parallel** when topics are independent (research never modifies the repo). **Verify the write scope after every file-backed return:** on a run that began Step 3 with a clean tree, `git status --porcelain` must be empty — any output means the agent wrote outside its scope: revert those paths and surface the violation before proceeding. Whenever the tree was NOT clean when Step 3 began (keep-dirty paths, kept partial work, plan-file dirt) or for mid-run research, use the snapshot-and-compare form: snapshot `git status --porcelain` before the spawn and compare after; only the delta is a violation. **Batch plan-drift decisions before Phase 1.** A plan is written against a HEAD that has moved by the time it runs. A criterion or `Known risk` line that sequences work relative to a merge, deploy, or apply (`after the PR merges`) is an assumption about this repo's workflow: put it in the batch as a question, never relay it later as a constraint. Every file-backed brief asks for contradictions (the template's Plan drift line). When any digest returns contradictions, or any phase has an `UNRESOLVED` human-gate set, present all of it in ONE message before Phase 1's Code agent is spawned — each with the plan text, the HEAD fact, and a proposed disposition from exactly two — **amend** the plan text (work that has already landed is amended out of the phase, or its criterion reworded to what remains; a phase amended to zero live criteria spawns nothing and is recorded `(no commit — amended out)`), or **proceed as written** — and take the user's answer once; this is a sanctioned stop (Step 4 item 11). After any amendment: edit the plan file, `rp.sh extract` (the spec files must match), and in GH mode `rp.sh sync` (on failure, item 6's `retry` / `continue` / `abort` escalation). "Proceed as written" is made durable too: append ` (accepted as written — )` to the affected criterion or sentence. Never carry known drift into a phase to surface it mid-run one item at a time. Drift found later (a deviation report, a review finding quoting the plan) follows fix-cycles.md → Plan drift found mid-run. **Skip this step only** if the plan is trivially simple (a single-phase config change with no codebase dependencies) — and even then, an unresolved human-form set is still asked before Phase 1, in the same message shape. ### Step 4 — Execute Phases A phase the inputs commit already performed spawns no agent (branch-and-resume.md → Resumability). A phase with human-form criteria runs the loop below for its agent-owned criteria and then stops at its human gate (human-gate.md); a phase whose criteria are all human-form spawns no Code agent and no reviewer. For each phase, sequentially: 1. **Begin the phase.** No wall-clock capture — time and cost come from the ledger rows its sub-agents produce. 2. **Compose the brief** — `rp.sh brief brief-code.md phase--brief-code.md …` per Brief recipes. `SPEC_PATH` points at `phase--spec.md`; nothing from the plan is pasted. 3. **Spawn the agent** with the one-line pointer prompt (Brief recipes). Mode per Agent modes; Architect and Debug briefs are composed per agent-operations.md. 4. **Receive the summary and record its ledger row** — `rp.sh ledger [group] [note]` for EVERY sub-agent return, this step and every other (`n/a` for a field the host did not expose). Analyze the result for success, failures, or concerns. If the summary reports a **blocking** failure, **read [references/fix-cycles.md](references/fix-cycles.md) now** and route through it before the review gate — enter item 5 only once the blocking failure is resolved (a verified Debug fix counts). Fixes land before the phase is reviewed and committed, never after. 5. **Stage and review the phase** (Code-mode phases only; under `--no-review` skip, and flag `(review skipped)` in the tracker): - `rp.sh stage` — stages the phase's changes with the keep-dirty exclusions, making new untracked files visible to the reviewer's `git diff --cached` and freezing exactly what the verdict applies to. If `git diff --cached --quiet` then exits 0, the diff is empty: spawn no reviewer, verify the criteria as the inputs-commit rule does, tick only what verifies, and let item 7 record `(no commit — no changes)`. - `EVIDENCE=$(rp.sh review-path )` — the next evidence path for this phase (unsuffixed for the first review, then `-2`, `-3`, …; derived from disk, never memory, and `rm -f`'d so a stale file can never satisfy the check below). Then `rp.sh brief brief-review.md phase--brief-review.md …` and spawn a fresh **Review** agent. The brief never carries the Code agent's summary or self-assessment — the reviewer's independence from the implementer's self-report is the point of the gate. - Receive the return: `C: VERDICT` lines, `Scope creep:`, `Weak criteria:`, and `Findings:` numbered `F1…` in full. Before routing, `rp.sh evidence "$EVIDENCE" returned>` — it confirms the file exists, holds `C` rows, and names at least that many findings, without you reading it; a failure is an incomplete review: re-spawn the reviewer once (no budget), a second miss escalates to the user. A pass marks the file; item 7's `rp.sh stage` refuses while the phase's latest evidence file is unmarked. The fix agent reads findings from that file, so a finding missing there is a finding nobody fixes. A scoped re-review's `ESCALATE` return carries no verdicts: `rm -f` its evidence path and spawn a fresh full Review agent. Then route — an unplaced `HUMAN-GATE` first (human-gate.md); then: - **Every criterion MET or brief-placed HUMAN-GATE** → item 6. - **Any NOT MET** → if the finding says the plan's own text is wrong or unsatisfiable, fix-cycles.md → Plan drift first; otherwise a blocking failure: a retry Code agent whose `FIX_CYCLE` cites the findings by evidence file and number (fix-cycles.md → Composing a fix-cycle brief), counted against the retry limit, followed by a fresh Review agent — full by default, scoped only under agent-operations.md's two exceptions; verdicts are never carried over without a re-review. - **HUMAN-GATE** (brief-placed) → no action; the criterion waits for the human's report. - **NEEDS-RUNTIME** → proceed; tag those criteria in the progress note and carry them to Step 5's caveats and the PR Test plan. - **Scope creep flagged** → out-of-plan refactors route to a fix like NOT MET; benign additions (an import the manifest missed) are noted and allowed. - **Findings outside the criteria** → a blocking defect routes to a fix like NOT MET (retry limit); a non-blocking defect worth fixing before it ships takes a corrective pass (fix-cycles.md → Corrective-pass budget: after the phase's first corrective pass, only a `behaviour`-tagged finding can draw the second); anything else is noted and carried (item 10). - **Weak criteria flagged** → the verdict stands; a flag routes like an out-of-criteria defect — first corrective pass only (a flag is not a `behaviour` defect) — otherwise carried. A scoped re-review's flag that repeats a standing full-review flag is the same finding, never re-routed. - **One fix cycle per review.** The fix brief carries the review's entire routed finding set in one pass; findings judged not worth fixing are noted and carried in the same turn. - **Invariant:** the Review agent is the last thing to see the phase's diff before checkboxes are ticked (item 6) and the commit happens (item 7). Any modification after the verdict that can reach the commit — a Debug fix, a retry, a corrective pass, anything except an edit to `` itself — invalidates it: re-stage and re-review in full with a fresh agent before proceeding. Two narrow exceptions can scope — never skip — the re-review (a post-verdict delta confined to dependency/generated artifacts, or to test files, documentation files, and declared-comment-only production files): the moment one looks applicable, **read agent-operations.md → Scoped Re-review Exceptions** and run `rp.sh baselines` BEFORE `rp.sh stage` — the index preserves the verdict-time state only until re-staging. Record a scoped review as a deviation in the progress note. The re-review still goes to a **fresh** agent — only its scope narrows, never its independence. When in doubt, full. 6. **Update the plan file** — `rp.sh tick …` for every criterion the reviewer verified MET (under `--no-review`, from the Code agent's self-report, as amended by any Debug agent's verified-fix report); NEEDS-RUNTIME criteria are ticked but tagged in the progress note; human-form criteria stay unticked until the human reports (human-gate.md). The orchestrator never edits the plan by hand for ticks. **(GH mode, `active`)** then `rp.sh sync`; on its failure (it has already retried 3× with backoff), escalate to the user **once** with three options: `retry` — run it again now (e.g. after `gh auth`); `continue` — set ` = degraded`, skip per-phase sync for the rest of the run, one final attempt at Step 5a; `abort` — stop the run (resumable). **(`degraded`)** skip the sync and flag `(GH sync degraded)` in the tracker. 7. **Commit the phase's changes:** - `rp.sh stage` (picks up the plan-file edit; the code is already staged from item 5 when the gate ran). `git diff --cached --quiet` exiting 0 → skip the commit and note `(no commit — no changes)`. - **Fast path** — applies when `/phase--commit-msg.md` exists AND every **post-author change** — a change to the phase's code by any agent after the file was last authored or updated (a fix-cycle Code agent authors or updates it under the message-maintenance rule and says which in its summary) — was a delta consisting solely of production files a scoped re-review verified as declared `[comment-only]` (Exception 2, no escalation). No post-author change qualifies outright. Any other post-author delta — a test file or artifact in it, a refuted or undeclared production file, a Debug code fix — fails: use the fallback. When the fast path rests on comment-only reuse, read the message file (scratch text, never a diff) and confirm its subject and body still describe the phase against the summaries in context; record the reuse and this check in the progress note, and on any mismatch use the fallback. Strip leading/trailing code-fence lines from the file in place (a fence would become the commit subject), then `git commit -F "/phase--commit-msg.md"`. A commit-msg hook rejection → discard the file and use the fallback. - **Fallback** — `Skill(skill="commit", args="#")` (`args="--no-ticket"` in local-only mode — an omitted argument would let the skill infer a ticket this run has none of). The `commit` skill is the single source of truth for commit message format and type selection — never duplicate its guidance here. It commits the index exactly as `rp.sh stage` left it (it reads `git diff --cached` and stages nothing), so keep-dirty exclusions hold through it; a hand-written `git commit` is never a substitute for either path. A hook rejecting the fallback's message → fix-cycles.md → Pre-commit hook failure (message re-author once, no budget). - **Pre-commit hook failure** → fix-cycles.md → Pre-commit hook failure (a Debug agent, then re-stage and re-review; never bypass hooks). - `rp.sh cleanup ` once the commit lands — removes the message file and any scoped-review baselines. A stale message file would satisfy a later run's fast path and commit that phase with an outdated message; a stale baseline would hand a later scoped re-review the wrong delta. 8. **Compute the phase's cost row** — `rp.sh phase-cost ` prints the Research | Code | Review | Total | Active-time cells from the ledger (per-agent figures dot-separated, parallel groups at their max; never hand-tally). 9. **Report progress** — the tracker table (Progress reporting below). 10. **Carry non-blocking concerns** — blocking failures were handled at item 4. Every carried defect ends in one of two places, never implicitly dropped: assigned to a later phase that already touches the same file — listed in that phase's `DELTAS` as a **pre-authorized cleanup** AND named in its Review brief's `SANCTIONED` (omitting either is a brief-composition error: the reviewer reads an unnamed cleanup as scope creep) — or recorded in the final report and, where applicable, the PR's Review notes. Only polish-class defects (house style, naming, comments, formatting — never behaviour) ride a later phase this way, at no corrective-pass cost; a defect carried because its phase exhausted a budget takes the report route only, and a cleanup the later phase's reviewer reports unapplied reverts to carried status. Under `--no-review` the assignment route is unavailable. 11. **Proceed** to the next phase. Rendering the tracker is never a stopping point — compose the next brief in the same turn; end the turn only at Step 5 or at a prompt this skill itself defines (a triage question, an escalation, a human gate, Step 2's confirmation gate). A prompt that puts options to the user ends with one recommendation and its reason — the choice stays theirs; a list without one costs a turn. ### Step 5 — Completion **Classify the run first** — set `` per Working state; every gate below keys off it. Then **read [references/completion-templates.md](references/completion-templates.md)** — it owns the final completion table, the summary comment, Step 5a's degraded-sync reconciliation, the push, the pre-PR branch review's routing, the PR body and submission flow, and Step 5e's cleanup. Skeleton: - Final summary: outcomes across all phases; the completion table rendered from the ledger (one row per sub-agent, phase subtotals, Totals; total active time idle-immune, parallel groups at their max; wall-clock elapsed only as a labelled aside); caveats, manual steps, follow-ups; unchecked criteria; keep-dirty paths still uncommitted and absent from the PR. **Local-only runs:** state plainly that the branch was never pushed and give `git push -u origin ` — everything below is GH-mode only. - **GH mode, outcome `complete` or `partial` only** (skip all of it on `aborted`): **5a** sync reconciliation if degraded (a failing final sync skips 5b and 5d); **5b** summary comment; **5c** `git push -u origin ` (skip under `--no-branch`; deliberately inside the GH block — in a `declared` repo the push is what opens the PR; never auto-force-push; a failed push skips 5d); **5c.5** pre-PR branch review — skip if `--no-branch-review` or 5d will be skipped anyway; ONE fresh Review agent at branch scope briefed from `brief-prepr.md` (completion-templates.md owns the scope ref), scoped past a root inputs commit; **detection-only** — fixes happen only when the user picks that option (a branch-scope finding often sits in the gap between what the plan says and what the user meant); a CONFIRMED correctness finding drafts the PR and is surfaced with options; under `declared`, run 5c.5 BEFORE the push; **5d** submit the PR per `` (`declared` → poll for the workflow's PR and attach the body with `gh pr edit`, never `gh pr create`; `silent` → `gh pr create`); when 5d is skipped in a `declared` repo, say so — a PR exists with the workflow's auto-generated body; **5e** delete the local plan and PRD files only when all four of its conditions hold. Report the PR URL. --- ## Agent modes Five modes, all `general-purpose` except inline-lookup Research (`Explore`): **Research** (file-backed by default; inline lookup for a single small answer), **Code**, **Architect**, **Debug**, **Review**. Research and Review are read-only toward the repo *by conduct*, not by capability; Review keeps the same model tier as Code, never a smaller one. Full definitions, the Architect/Debug brief composition, the scoped re-review exceptions, and the pre-PR variant: [references/agent-operations.md](references/agent-operations.md) — load it when one of those is needed, not before. ## Brief recipes Briefs are files. Fill a template with `rp.sh brief