git:20260916.cadb06c to git:20260916.8dd269c

- a hint to resume via `review-loop:execute --session <uuid>`. Use when you

- # plan — Planning-Only Sub-Skill

-

- Drive a work item through the Plan loop (Executor drafts → Reviewer

- critiques → iterate) until the Reviewer returns APPROVE, then stop. This

- skill does **not** enter the execution phase; it hands off to

- `review-loop:execute --session <uuid>` (or to a different runtime's

- `execute` skill) via the shared session file.

-

- ## Protocol Imports

-

- The Orchestrator MUST Read each of these files at start. They are the

- single source of truth for this skill's planning loop and output schemas.

-

- - `docs/protocol/session-file.md`

- - `docs/protocol/planning.md`

- - `docs/protocol/executor-output.md`

- - `docs/protocol/reviewer-output.md`

-

- Do not re-derive any rule that already lives in a protocol doc. When a

- step below says "see `docs/protocol/<doc>.md` §Foo", follow that doc

- verbatim.

- The startup read set is complete only after all 4 docs above have been read

- explicitly; the embedded executor/reviewer prompt bodies are not a substitute

- for reading `executor-output.md` and `reviewer-output.md`.

-

- ## Orchestrator rules

-

- - **Plugin agent-type sandbox bug**: every Executor / Reviewer invocation

- MUST use `subagent_type: general-purpose` with the agent's full `.md`

- body inlined in the `prompt` parameter. Never use

- `subagent_type: review-loop:<name>` — plugin-defined agent types have

- their tools silently blocked by the Claude Code sandbox. See

- `CLAUDE.md` §"Plugin agent type sandbox bug" for background.

- - The session file on disk is the single source of truth. Only the

- Orchestrator writes to it. Sub-agents read it.

- - The Live Report after each round is not optional — users must see

- every review finding.

-

- ## Invocation

-

- ```

- run plan on: <work item description> [--handsfree]

- ```

-

- `--handsfree` forwards decision-type Executor questions to the Reviewer

- instead of pausing for the user. External-info questions still pause

- regardless of mode. See `docs/protocol/planning.md` §Question

- classification.

-

- ---

-

- ## Step 0 — Load config and parse flags

-

- Before loading config or checking backend availability, Read the 4 Protocol

- Imports docs listed above.

-

- 1. Read `.review-loop/config.md` if present; otherwise fall back to the

- defaults documented in `skills/review-loop/SKILL.md` §Configuration.

- 2. Detect `--handsfree` in the invocation message. If present (or

- `handsfree: true` in config), enable handsfree for this session.

- 3. Confirm the Reviewer backend is available per `reviewer:` config

- (see `docs/protocol/planning.md` §Reviewer dispatch). For

- `reviewer: codex`, run `which codex`; if missing, suggest

- `reviewer: subagent` and exit.

-

- ## Step 0.5 — Initialize session file

-

- 1. Generate a lowercase UUID.

- 2. Create `.review-loop/sessions/{uuid}.md` with the canonical section

- list per `docs/protocol/session-file.md` §Canonical sections, using

- the `plan` entry-mode column of §Entry-mode initialization table.

- - `## Approved Plan` body is empty; no `Source` sub-field is written

- during planning draft rounds.

- - `## Draft Plan` is present; it will be overwritten by each planning

- round's Executor output (see `docs/protocol/session-file.md`

- §Draft Plan and `docs/protocol/planning.md` §3).

- - `## Current Phase: planning`.

- - `## Current Review Packet` (empty until round 1) and

- `## Evidence Ledger` are part of the canonical list; the Timing Log

- header has the 13 columns of `docs/protocol/session-file.md`

- §Timing Log columns.

- 3. Write the initial `## Session Metadata` block. `entry_point: plan`.

- `plan_source` is **omitted** during planning draft rounds — it is

- written on APPROVE only (per Phase 1 decision; see

- `docs/protocol/session-file.md` §Session Metadata schema).

- 4. Acquire the single-writer lock per

- `docs/protocol/session-file.md` §Lock file lifecycle.

- 5. Run `python3 scripts/evidence_ledger.py snapshot --session {uuid}`

- to store snap/0 (the only way `## Evidence Ledger` is ever written).

- 6. Tell the user the session path so they can inspect it.

-

- ## Step 1 — Parse the work item

-

- Extract from the user's message: title, problem description, context,

- acceptance criteria. If critical information is missing, ask ONE

- clarifying question before proceeding.

-

- ## Step 1.5 — Detect pre-existing state (no auto-dispatch)

-

- **`plan` does not auto-route into execution.** If the work item looks

- like it should skip the planning loop, print a suggestion and exit

- instead of dispatching — the user is the one who chose the `plan`

- entry point, and the hand-off is their call.

-

- Check:

-

- - **Plan already exists**: the user's message says "review this",

- points at an already-written plan doc, or the conversation shows an

- approved plan. → Suggest:

- ```

- Detected: existing plan in the conversation/context.

- Next: review-loop:execute --plan "<text|path>" --title "<title>"

- (or review-loop:execute --session <uuid> if you already have a session)

- ```

- - **Code already implemented**: `git status` shows substantial,

- task-relevant changes. → Suggest:

- ```

- Detected: implementation appears to already be in the working tree.

- Next: review-loop:execute --review-only --description "<what was done>"

- ```

- - **Neither** → proceed to Step 1.6.

-

- Print the suggestion and exit. Do **not** dispatch Executor / Reviewer.

- Before exiting on the suggest-and-exit branch, release the single-writer lock per docs/protocol/session-file.md §Lock file lifecycle before exiting.

- The user can rerun with the suggested command if they agree.

-

- ## Step 1.6 — Historical context retrieval (optional, fail-silently)

-

- This step is strictly optional. Skip it entirely and silently if no

- external memory tool is available. Never ask the user to install

- anything. Never mention the tool name to users who don't have it. The

- fail-silently contract applies to the entire lifecycle — probe failure,

- runtime failure, malformed output — per `CLAUDE.md` §"Optional

- integrations must fail silently".

-

- 1. **Availability probe**: check if a `mempalace_search` MCP tool is

- listed, OR run `which mempalace` via Bash. If neither, skip.

- 2. **Resume dedup**: if the session file already carries a

- `## Historical Context` section (should not happen for `plan` fresh

- init — guard anyway), skip.

- 3. Extract 1-2 specific search terms from the work item.

- 4. Call the memory tool with a **10-second timeout**; kill the probe at

- the deadline rather than awaiting it. If the call errors, hangs,

- times out, returns non-zero, produces stderr, or returns malformed

- output, **silently skip this step and continue.**

- 5. If the top results parse cleanly, append up to 3 bullets under a

- `## Historical Context` section. Otherwise skip — no empty section.

-

- ## Step 2 — Planning round loop

-

- Run the planning loop per `docs/protocol/planning.md` §Round loop. For

- this skill specifically:

-

- - Each round: update context file → Executor → update context file

- (write the round's draft into `## Draft Plan`; `evidence_ledger.py

- snapshot`; rewrite `## Current Review Packet` in full with the

- planning-round delta — the plan-text diff between rounds from

- `evidence_ledger.py delta` — unresolved findings + Executor response,

- and `Author route: executor` — planning is always Executor-authored;

- `evidence_ledger.py route` answers `executor` outside the execution

- phase) → optional context-persist sub-step

- (§3.5 in the protocol doc) → Reviewer → parse → `finding_triage.py check` (mandatory rubric gate per

- `docs/protocol/execution.md` §Mandatory rubric gate: every `[CRITICAL]`

- carries the six fields `Trigger:`, `Reachability:`, `Impact:`,

- `Likelihood:`, `Fix cost:`, `Cheaper response:`; `incomplete` → discard

- the output as malformed, record `rubric_incomplete: finding #n missing

- <fields>`, re-dispatch the Reviewer once with the missing-field list,

- second `incomplete` → reviewer failure for the round; never implement a

- CRITICAL that failed triage) → Live Report (Timing

- Log row with the 13 columns, `N/A` where unmeasured).

- - Round 2+ scope-drift check per `docs/protocol/planning.md` §4: an

- undisclosed material change to the plan's design decisions is CRITICAL;

- a disclosed equivalent simplification is not automatically CRITICAL.

- - Planning rounds have no Step 3.4 gate, so `docs/protocol/execution.md`

- §Gate rubric revalidation does not apply here; an incomplete

- planning-round CRITICAL is discarded and retried per the per-backend

- table in `docs/protocol/execution.md` §Mandatory rubric gate.

- - Loop control: `APPROVE` → promote `## Draft Plan` into

- `## Approved Plan` with `- Source: reviewer-approved`, write

- `plan_source: reviewer-approved` to `## Session Metadata`, **remove

- `## Draft Plan` entirely** from the session file, and exit the

- planning loop (do NOT continue into execution — that is the `execute`

- skill's job).

- - `REQUEST_CHANGES` → feed feedback into the next Executor round.

- - Soft-limit prompt + stuck detection per

- `docs/protocol/planning.md` §Loop control.

-

- ### Executor dispatch (Claude Code)

-

- Follow `docs/protocol/planning.md` §Executor dispatch, Claude Code

- block. Reminder:

-

- Dispatch anchor: `plan_executor_dispatch_skill`. The planning-phase Executor

- is a `judgment`-tier dispatch; missing `tier` defaults to `judgment`.

-

- ```

- Agent tool parameters:

- subagent_type: general-purpose

- model: {executor_model if set and != "inherit"; else judgment_model if set; else omit}

- prompt: |

- You are the Executor in a review-loop workflow.

-

- {contents of agents/executor.md body}

-

- Read the context file first: {session_file_path}

- DO NOT modify the context file.

- ## Your Task

- Produce a detailed solution plan following the output format in your

- instructions.

- {if round > 1:}

- ## Previous Reviewer Feedback (address each point)

- {reviewer_feedback}

- **CRITICAL — plugin sandbox bug**: Never use `subagent_type: review-loop:executor`. That agent type has tools silently blocked — Executor will run with `tool_uses: 0` and hallucinate output. Always use `subagent_type: general-purpose` with the executor body inlined as shown above.

-

- ### Reviewer dispatch (Claude Code)

-

- Follow `docs/protocol/planning.md` §Reviewer dispatch, Claude Code

- block. Two modes (`codex` and `subagent`) controlled by `reviewer:` in

- `.review-loop/config.md`. For subagent mode, `subagent_type` is

- `general-purpose` with the `agents/reviewer.md` body inlined plus an

- explicit "Report only, do not modify any files" instruction. Every

- prompt opens with "Read `## Current Review Packet` first. Load a

- `## Review History` entry only when the packet references it or a

- claim needs provenance. Absence of irrelevant history is not a

- defect."; the flat all-rounds findings dump is gone.

-

- ## Step 3 — Exit with hand-off hint

-

- After the Reviewer returns `APPROVE`:

-

- 1. The session file now has `## Approved Plan` populated with

- `- Source: reviewer-approved` and `## Session Metadata.plan_source:

- reviewer-approved`. `## Draft Plan` has been removed.

- 2. Release the lock per `docs/protocol/session-file.md` §Lock file

- lifecycle.

- 3. Print the delivery hand-off:

-

- ```

- ── review-loop:plan — approved ──────────────────

- Session: {uuid}

- Session file: .review-loop/sessions/{uuid}.md

- Plan rounds: {N}

- Status: Approved (plan_source: reviewer-approved)

- Next: review-loop:execute --session {uuid}

- ────────────────────────────────────────────────

- ```

- The `plan` skill does not deliver code and does not enter any execution

- stage. `completed_stages` is not minted here — that is strictly the

- `execute` skill's responsibility. No auto-dispatch.

- ---

- ## Context Management

- The Orchestrator keeps a minimal state between rounds (session path,

- latest Reviewer feedback, round number). All durable state lives on

- disk in the session file. See `docs/protocol/planning.md` §Context

- management discipline.