Plan

---
name: plan
argument-hint: "<work item description> [--handsfree]"
description: >
  Run the planning phase only: drive a work item from raw description to a
  reviewer-approved plan in `.review-loop/sessions/{uuid}.md`, then exit with
  a hint to resume via `review-loop:execute --session <uuid>`. Use when you
  want plan-only iteration without immediately entering execution.
---

# 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`.
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. 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`) → optional
  context-persist sub-step (§3.5 in the protocol doc) → Reviewer →
  parse → Live Report.
- 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.

## 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.