run-plan

name	run-plan
disable-model-invocation	false
argument-hint	<plan-file> [phase|finish|status] [auto] [every SCHEDULE] [now] | stop | next
description	Execute the next phase of a plan document: parse phases and status, dispatch implementation in a worktree, verify with a separate agent, update progress tracking, write reports/plan-{slug}.md, and optionally auto-land to main. Can self-schedule recurring runs via cron. Use `next` to check schedule, `stop` to cancel.

/run-plan <plan-file> [phase|finish] [auto] [every SCHEDULE] [now] | stop | next — Plan Phase Executor

Orchestrates plan-driven development. Reads a plan document, identifies the next incomplete phase, dispatches implementation in a worktree, verifies with a separate agent, updates progress tracking, writes a persistent report, and optionally auto-lands to main. Can self-schedule for recurring runs to work through multi-phase plans autonomously.

Ultrathink throughout. Use careful, thorough reasoning at every step.

Arguments

/run-plan <plan-file> [phase] [auto] [every SCHEDULE] [now]
/run-plan stop | next

• plan-file (required) — path to plan, e.g. plans/FISHIES_PLAN.md
• phase (optional) — specific phase, e.g. 4b. If omitted, auto-detect next incomplete phase
• finish (optional) — run ALL remaining phases sequentially until the plan is complete. finish is approval to START — do not ask for confirmation before the first phase (the user already said "finish"). Without auto: pauses BETWEEN phases to show results and ask "continue to next phase?" With auto: runs all phases without pausing (overnight). Each phase still gets full verification, testing, and all safety rails. If any phase fails verification or hits a conflict, stops there. finish and every are mutually exclusive. finish runs all phases in one session. every schedules one phase per cron fire. Combining them is meaningless — finish either completes (cron self-terminates) or fails (Failure Protocol kills the cron). Use one or the other.
• auto (optional) — bypass approval gates, auto-land to main via cherry-pick
• every SCHEDULE (optional) — self-schedule recurring runs via cron:
  • Accepts intervals: 4h, 2h, 30m, 12h
  • Accepts time-of-day: day at 9am, day at 14:00, weekday at 9am
  • Without now: schedules only, does NOT run immediately
  • With now: schedules AND runs immediately
  • Implies auto — scheduling only makes sense for autonomous runs
  • Cron prompt omits phase number so each invocation auto-detects the next incomplete phase
  • Each run re-registers the cron (self-perpetuating)
  • Cron is session-scoped — dies when the session dies
• now (optional) — run immediately. When combined with every, runs immediately AND schedules. Without every, now is the default behavior.
• status — show plan progress: all phases, their status, what's next, and what's blocked. Read-only — no agents dispatched, no approval gate.
• stop — cancel any existing /run-plan cron and exit. Takes precedence over all other arguments.
• next — check when the next scheduled run will fire. Takes precedence over all other arguments except stop.

Detection: scan $ARGUMENTS for:

• stop (case-insensitive) — cancel cron and exit (highest precedence)
• next (case-insensitive) — check schedule and exit
• status (case-insensitive) — show plan progress and exit
• finish (case-insensitive) — run all remaining phases sequentially
• now (case-insensitive) — run immediately
• auto (case-insensitive) — autonomous mode
• every followed by a schedule expression — scheduling mode

Examples:

• /run-plan plans/FISHIES_PLAN.md — interactive, next phase
• /run-plan plans/FISHIES_PLAN.md 4b — interactive, specific phase
• /run-plan plans/FISHIES_PLAN.md finish — interactive, all remaining phases (pauses between each)
• /run-plan plans/FISHIES_PLAN.md finish auto — autonomous, all remaining phases (no pausing)
• /run-plan plans/FISHIES_PLAN.md auto every 4h — schedule every 4h
• /run-plan plans/FISHIES_PLAN.md auto every 4h now — schedule + run now
• /run-plan plans/FISHIES_PLAN.md status — show plan progress
• /run-plan now — trigger the active cron early
• /run-plan stop — cancel scheduled runs
• /run-plan next — check when the next phase will run

Status (if status is present)

If $ARGUMENTS contains status (case-insensitive):

1. Read the plan file specified in the arguments

2. Also read any companion progress document if referenced

3. Parse all phases and their status (same parsing logic as Phase 1 steps 2-3: "Extract phases and status" and "Determine target phase." Do NOT run preflight checks — status is read-only)

4. Present a progress table:

   Plan: plans/FISHIES_PLAN.md
   
   | Phase | Status |
   |-------|--------|
   | 1 — Fish Base Class | Done (abc1234) |
   | 2 — Genetics System | Done (def5678) |
   | 3 — Breeding Logic | Next ← |
   | 4 — UI Integration | Blocked (needs 3) |
   
   Next phase: 3 — Breeding Logic
   Dependencies: 1 ✓, 2 ✓
   

5. If a cron is active, also show the schedule:

   Scheduled: every 4h (~8:15 PM ET next, cron XXXX)

6. Exit. Read-only — no agents dispatched, no work done.

Now (standalone — no plan-file provided)

If $ARGUMENTS is just now (no plan-file, no phase, no every):

1. Use CronList to list all cron jobs
2. Find any whose prompt starts with Run /run-plan
3. If found: extract the cron's prompt to get the plan-file, auto, and schedule. Run the phase immediately — proceed to Phase 1. Do NOT ask for confirmation — now IS the confirmation. The cron stays active.
4. If none found: report No active /run-plan cron to trigger. Use /run-plan <plan-file> to run manually. and exit.

Next (if next is present)

If $ARGUMENTS contains next (case-insensitive):

1. Use CronList to list all cron jobs
2. Find any whose prompt starts with Run /run-plan
3. Report:
   • If found: parse the cron expression and compute the next fire time. Use date +%Z for the timezone. Show both relative and absolute:

     Next run-plan phase in ~2h 15m (~8:30 PM ET, cron XXXX). Prompt: Run /run-plan plans/FISHIES_PLAN.md auto every 4h

   • If none found: No active /run-plan cron in this session.
4. Exit. Do not proceed to any phase.

Stop (if stop is present)

If $ARGUMENTS contains stop (case-insensitive):

1. Use CronList to list all cron jobs
2. Delete ALL whose prompt starts with Run /run-plan using CronDelete
3. Report what was cancelled:
   • If one cron found: Run-plan cron stopped (was job ID XXXX, every INTERVAL).
   • If multiple found: Stopped N run-plan crons (IDs: XXXX, YYYY).
   • If none found: No active /run-plan cron found.
4. Exit. Do not proceed to any phase. The stop command does nothing else.

Phase 0 — Schedule (if every is present)

If $ARGUMENTS contains every <schedule>:

1. Parse the schedule — convert to a cron expression. The LLM interprets natural scheduling expressions.

   For interval-based schedules (4h, 2h, 30m): use the CURRENT minute as the offset so the first fire is a full interval from now, not aligned to midnight. Check the current minute with date +%M:

   • 4h at minute 9 → 9 */4 * * * (fires at :09 past every 4th hour)
   • 2h at minute 15 → 15 */2 * * *
   • 30m → */30 * * * * (no offset needed for sub-hour)
   • 1h at minute 9 → 9 * * * *

   For time-of-day schedules (day at 9am, weekday at 2pm): offset round minutes by a few to avoid API busy marks:

   • day at 9am → 3 9 * * *
   • day at 14:00 → 3 14 * * *
   • weekday at 9am → 3 9 * * 1-5

2. Deduplicate — use CronList + CronDelete to remove any whose prompt starts with Run /run-plan.

3. Construct the cron prompt. Strip the phase number (so each invocation auto-detects the next incomplete phase). Always include now in the cron prompt so each cron fire runs immediately AND re-registers itself. Note: this now is for the CRON's invocation, not the current invocation:

   Run /run-plan <plan-file> auto every <schedule> now
   

   Note: the phase number is intentionally omitted so the cron auto-advances.

4. Create the cron — use CronCreate:

   • cron: the cron expression from step 1
   • recurring: true
   • prompt: the constructed command from step 3

5. Confirm with wall-clock time. Always show times in America/New_York (ET) — use TZ=America/New_York date for conversion, not the system timezone (which may be UTC):

   If now is present:

   Run-plan scheduled every 4h. Running now. Next phase run after this one: ~8:15 PM ET (cron ID XXXX).

   If now is NOT present:

   Run-plan scheduled every 4h. First run: ~4:15 PM ET (cron ID XXXX). Use /run-plan next to check, /run-plan stop to cancel.

6. If now is present: proceed to Phase 1 (run immediately). If now is NOT present: Exit. The cron fires later.

End-of-phase scheduling note: when a phase finishes and a cron is active, always include the estimated next run time with timezone in the completion message. Example:

Phase complete. Next phase run in ~3h 45m (~11:30 PM ET, cron XXXX).

If every is NOT present, skip this phase and proceed to Phase 1 (bare invocation always runs immediately).

Phase 1 — Parse Plan & Extract Verbatim Phase Text

The key differentiator. Plans have varied formats, so the agent uses LLM comprehension rather than rigid parsing.

Preflight checks

Before parsing, check for stale state from a previous failed run:

1. In-progress git operation?

   ls .git/CHERRY_PICK_HEAD .git/MERGE_HEAD .git/REBASE_HEAD 2>/dev/null
   git status --porcelain | grep '^UU\|^AA\|^DD'
   

   If either command produces output, STOP. Invoke the Failure Protocol.

2. Stash stack?

   git stash list
   

   If there is a stash with message containing "pre-cherry-pick", a previous run's stash was never restored. STOP. Invoke the Failure Protocol — the user needs to git stash pop or git stash drop before a new phase can start safely.

3. Leftover plan worktrees?

   git worktree list
   

   If worktrees from a previous run exist (paths containing plan-), warn the user. Do not remove them — note their presence and continue.

Parse plan

1. Read the plan file in full. Also read any companion progress document if referenced.

2. Extract phases and status — handle four formats:

   • Progress tracker table: rows with ✅ Done, ⬚ (not started), 🟡 (in progress), etc.
   • Numbered phase sections (## Phase 4a — Title): look for completion markers in the section body or companion doc
   • Checklist (- [x] / - [ ]): checked = done, unchecked = not done
   • Narrative: infer status from codebase evidence (files exist, tests pass, etc.)

3. Determine target phase:

   • If phase arg given: use it. If already complete, warn (or skip in auto)
   • If no phase arg: first incomplete phase
   • If ALL phases complete: report "Plan complete" → stop. If every, delete the cron via CronList + CronDelete
   • If multiple phases share the same number (e.g., 4a, 4b, 4c), treat each sub-phase as a separate phase

4. Check dependencies — if a prerequisite phase isn't Done, STOP. Report which dependency is missing. If every, the cron retries later.

5. Check for conflicts — if the target phase is "In Progress" (🟡 or equivalent), another agent may be working on it. STOP. Do not compete.

6. Check for staleness notes — if the plan's Dependencies section contains language like "drafted before," "may need refresh," or "APIs and data structures referenced here are based on [another plan's] design, not actual code," the plan may be stale:

   • Without auto: tell the user "this plan was drafted before its dependency was implemented. Want me to refresh it with /draft-plan?"
   • With auto: dispatch /draft-plan on the plan file to update it. /draft-plan handles existing files as modernizations. After the refresh, re-read the plan and continue.
   • Skip this check if the plan file was modified more recently than the dependency's completion (it may already be up to date).

7. Save the VERBATIM phase text — copy the entire section from the plan file exactly as written. Every sentence, every bullet, every formula, every constraint. This text will be passed to agents in Phase 2 and Phase 3.

   Do NOT summarize, paraphrase, or reinterpret. The plan is the spec.

   Lesson: summarized descriptions cause agents to implement the wrong thing. A vague title like "reset button" was interpreted as "clear canvas" instead of "reset mappings to defaults" because only the title was read. The same will happen with plan phases if the orchestrator summarizes instead of passing verbatim text.

8. Classify UI impact from the plan text. Scan the phase description for UI indicators: mentions of editor, toolbar, canvas, panel, dialog, CSS, button, menu, viewport, renderer, dark mode, layout, or any reference to style.css, index.html, or UI-related JS files. Flag the phase as UI-touching if any are found.

   In finish mode, classify ALL phases upfront and report:

   Running 5 phases. Phases 3 and 5 touch UI — landing will wait for your sign-off at the end.

   This tells the user immediately whether the run will be fully automatic or will need their review before landing. No surprises at Phase 6.

9. Present the phase plan:

   • Without auto: display the phase summary (name, status, dependencies, work items, UI classification) and wait for user approval
   • With auto: proceed immediately

finish mode: overall verification after all phases

In finish mode, after ALL phases complete their per-phase implement → verify loops, run a final overall verification before writing the report and landing:

1. Dispatch an overall verification agent. In worktree mode, run /verify-changes worktree on the full worktree diff. In delegate mode (or mixed), run /verify-changes on main against the commits from all phases combined. This catches cross-phase integration issues: regressions from later phases breaking earlier work, conflicting imports, duplicated code.

2. If ANY phase was classified as UI-touching (step 8), dispatch a dedicated manual testing agent that exercises ALL UI changes together via playwright-cli. This agent:

   • Tests the combined UI state (not each change in isolation)
   • Takes comprehensive screenshots showing everything working together
   • Prepares the sign-off report so the user can review efficiently

   The goal: instead of "3 items need sign-off, go check yourself," the user gets "3 items need sign-off, here are screenshots of all of them working together."

3. Proceed to Phase 5 (write report) with the combined verification results.

Phase 2 — Implement

Execution mode detection

Check the phase text for an execution mode directive:

• ### Execution: delegate <skill> [args] — delegate mode. The phase runs a skill (e.g., /run-plan) that manages its own isolation. The orchestrating agent runs on main, not in a worktree. See "Delegate mode" below.
• ### Execution: worktree or no directive — default worktree mode. See "Worktree mode" below.

Delegate mode

The orchestrating agent runs on main and calls the specified skill. The skill manages its own worktree, verification, and landing.

1. Dispatch agent on main (no isolation: "worktree"). Give the agent:

   • The verbatim phase text (same rule as worktree mode)
   • Instruction to run the specified skill with the given arguments
   • Instruction to wait for the skill to finish and report the result

2. Agent timeout: 2 hours. Same as worktree mode.

3. After the delegate skill finishes, /run-plan proceeds to Phase 3 (verification) which runs on main — checking that the delegated work actually landed correctly.

4. In finish mode: each delegate phase runs independently (no shared worktree — the delegate skill creates and destroys its own).

Use cases:

• ### Execution: delegate /run-plan plans/SUB_PLAN.md finish auto — meta-plans
• ### Execution: delegate /draft-plan plans/FOO.md <description> — plan generation

Worktree mode (default)

One worktree for the entire phase (not per-item). In finish mode, reuse the SAME worktree across all phases — create it once before the first phase, pass the same path to every phase's agent:

Agent timeout: 2 hours. Note the dispatch time. If the implementation agent hasn't returned after 2 hours, declare it failed:

• Mark the phase as "Timed out" in reports/plan-{slug}.md
• The phase stays incomplete for the next run
• The worktree is a cleanup artifact — do NOT auto-land late results
• If the agent eventually returns, ignore it. Timed out = failed, period.
• If the plan was drafted with /draft-plan, the phase may be too large — consider splitting it (each phase should be ~3-5 components, ~500 lines).

1. Dispatch implementation agent with isolation: "worktree". Tell the agent to write a .worktreepurpose file as its first action:

   echo "<session-name or plan-name>: <phase name>" > .worktreepurpose
   

2. Agent prompt MUST include the verbatim plan text. The implementing agent receives the EXACT text of the phase from the plan file — not a summary, not bullet points extracted from it. The full section with every requirement, formula, constraint, design note, and acceptance criterion.

   The plan is the spec. If the agent doesn't have the verbatim text, it will guess, and it will guess wrong.

   For plan sections longer than ~100 lines: write the verbatim text to a temp file (e.g., /tmp/phase-text.md) and tell the agent to Read the file. This avoids the natural LLM tendency to compress long text when inlining it in a prompt. Shorter sections can be inlined directly.

3. If dispatching sub-agents for parallel work items, each sub-agent gets:

   • The full phase context (verbatim) — so they understand the big picture
   • Their specific scope clearly delineated
   • What parallel agents are doing — enough to avoid conflicts (shared files, shared infrastructure) but not so much detail that it confuses their scope.
   • Shared infrastructure dependencies — if a base class or shared module must exist first, that must be built sequentially before dispatching parallel agents. Never dispatch parallel agents that both need to create the same file.

4. Within-phase parallelism is the agent's judgment call — if items are independent, the agent may dispatch sub-agents. If there's shared infrastructure to build first, it works sequentially then parallelizes. The skill does NOT force parallelism.

5. Commit discipline:

   • One logical unit per commit — clean git history
   • npm test before every commit
   • Tests alongside implementation, not deferred to later
   • Agents commit freely in worktrees — that's the point of isolation

6. Running tests in worktrees — CRITICAL. Agents waste hours getting tests working in worktrees without these instructions. Include this VERBATIM in every implementation and verification agent prompt:

   Worktree test recipe:

   1. Run tests with output captured to a file: npm test > .test-results.txt 2>&1 Never pipe through | tail, | head, | grep — it loses output and forces re-runs. Capture once, read the file.
   2. If tests fail, read .test-results.txt to find the failures. Then run ONLY the failing test file to iterate on the fix: npx vitest run tests/unit/the-failing-file.test.js Do NOT re-run npm test to diagnose — that wastes time when the single file takes seconds.
   3. After fixing, run the single file again to confirm. Then run npm test > .test-results.txt 2>&1 ONE more time as the final gate before committing.
   4. Max 2 fix attempts at the same error — do not thrash.
   5. If a test fails in code you didn't touch, it may be pre-existing. See /verify-changes Phase 3 for the pre-existing failure protocol.

7. No steps skipped or deferred. If the plan says "implement 7 components," implement 7 components. If it says "write tests for breeding logic," write those exact tests. Do not stop after the easy items and declare the hard ones "future work."

Phase 3 — Verify (separate agent)

Critical: the verification agent is NOT the implementing agent. Fresh eyes catch implementer blindspots — deferred hard parts, missing tests, stubs, shortcuts.

Agent timeout: 45 minutes. Verification should take 15-30 minutes — reading diffs, running tests, checking acceptance criteria. If a verification agent hasn't returned after 45 minutes, it is thrashing (likely on test setup or repeated test failures). Declare it failed and invoke the Failure Protocol. Do NOT let verification agents run indefinitely — they are the most common source of time waste.

Delegate mode verification

If this phase used delegate execution, verification runs on main:

1. Verify commits landed — check git log --oneline -10 for the delegate's commits. If expected commits are missing, the delegate failed to land — invoke Failure Protocol.
2. Run npm test on main — the delegate already tested, but /run-plan verifies against the plan's acceptance criteria.
3. Check acceptance criteria from the verbatim plan text — the delegate skill doesn't know the plan's criteria, only /run-plan does.
4. Dispatch a verification agent if needed (same rules as worktree mode below, but targeting main instead of a worktree path).

Worktree mode verification

1. Dispatch verification agent targeting the worktree's changes. The verification agent is dispatched without isolation: "worktree" — the Agent tool's isolation parameter creates a NEW worktree, it cannot attach to an existing one. Instead, give the verification agent:

   • The worktree path from Phase 2 (so it can read files and run tests there via cd <worktree-path> && npm test)
   • The worktree branch name (so it can diff against main: git diff main...<branch>)
   • The verbatim phase text from the plan (same text the implementer got)
   • Instruction to run /verify-changes worktree — the verification agent runs this, NOT you. Do NOT run verification yourself — you are the orchestrator with implementer bias.
   • The work items checklist — verify each item was actually implemented, not stubbed or skipped

2. Additional plan-specific checks (the verifier checks these against the verbatim plan text — not against a summary):

   • Do commits cover ALL work items listed in the plan? Any missing?
   • Does implementation follow the plan's stated approach?
   • Are constraints respected?
   • Any deferred hard parts, stubs, TODOs, or placeholder implementations?
   • Do acceptance criteria match?

3. If verification fails:

   • Without auto: present findings, ask user what to do
   • With auto: dispatch fix agent targeting the worktree path (NOT with isolation: "worktree" — that would create a new worktree). Give it the worktree path, verbatim plan text, and verification findings. After the fix agent finishes, re-verify (max 2 rounds). If still failing after 2 fix+verify cycles, STOP — needs human judgment. Invoke the Failure Protocol.

Phase 4 — Update Progress Tracking

After verification passes. These updates happen on MAIN, not in the worktree. The plan file tracks progress across all phases — it's an orchestrator concern, not an implementation artifact. Updating it on main ensures the next cron invocation sees the correct phase status and advances to the next incomplete phase (preventing infinite loops).

1. Update the plan file's progress tracker on main — change the phase status to Done with the commit hash (from worktree branch or delegate's landed commits) and notes. Examples by format:

   • Table: | **2: Genetics** | ✅ Done | \abc1234` | trait system, 12 tests |`
   • Checklist: - [x] Phase 2 — Genetics System (abc1234, trait inheritance)
   • Section: add **Status:** ✅ Done (abc1234) to the section header

2. Update companion progress doc on main if one exists — add implementation details, architecture notes, lessons learned

3. If no tracker exists:

   • Interactive mode: suggest adding one to the plan file, ask user
   • Auto mode: note in the report that no tracker was updated

4. Mark the phase as "In Progress" and commit:

   git add <plan-file> [companion-doc]
   git commit -m "chore: mark phase <name> in progress"
   

   Mark as 🟡 In Progress (not ✅ Done yet). Committing immediately ensures the next cron invocation sees the phase is being worked on (preventing re-runs). Phase 6 updates the tracker to ✅ Done AFTER landing succeeds. If landing fails, the tracker correctly says "In Progress" — the phase was attempted but not landed.

Phase 5 — Write Report

APPEND a new phase section to reports/plan-{slug}.md, where {slug} is derived from the plan filename (e.g., FISHIES_PLAN.md → plan-fishies). Each plan gets its own report file — different plans never collide. Re-running the same plan appends (multiple phases accumulate).

If the file doesn't exist, create it with a # Plan Report — {plan name} heading. Do NOT overwrite — finish and every modes add multiple phases.

After writing, regenerate PLAN_REPORT.md in the repo root as an index of all plan reports (same pattern as VERIFICATION_REPORT.md index):

1. Scan reports/plan-*.md files
2. For each: extract plan name, phase count, overall status, and count unchecked [ ] sign-off items
3. Write PLAN_REPORT.md with:
   • Needs Sign-off section at top — all unchecked [ ] items across all plan reports, linked to their source file
   • Plans table — each plan report with status and action item count
   • Staleness rule: items >7 days flagged STALE (same as VERIFICATION_REPORT.md)

Past failure: a report was overwritten each run, losing previous data. Same applies here — never overwrite.

Report format — each phase appends a section:

## Phase — 2 Genetics System [UNFINALIZED]

**Plan:** plans/FISHIES_PLAN.md
**Status:** Completed (verified)
**Worktree:** ../plan-fishies-2
**Commits:** abc1234, def5678

### Work Items
| # | Item | Status | Commit |
|---|------|--------|--------|
| 1 | Allele representation | Done | abc1234 |
| 2 | Trait inheritance | Done | def5678 |

### Verification
- Test suite: PASSED (all tests)
- Acceptance criteria: all met

### User Verification
{Only include this section if UI files were changed in this phase.
If no UI files changed, omit the section entirely.}

| Change | Agent Verify | User Verify |
|--------|:-----------:|:----------:|
| Genetics panel | ✅ | [ ] |

### #1 — Genetics panel
- [ ] **Sign off**

1. Open the app, observe the fish tank
2. Click on a fish to view its details
3. Verify the genetics panel shows trait information
4. Check that offspring display inherited traits correctly

![genetics panel](.playwright/output/phase2-genetics-panel.png)

Conditional: Only include the User Verification section if UI files (style.css, index.html, or UI-related JS files) were changed in this phase. If no UI files changed, omit the entire section.

Use actual data. The H1 is # Plan Report — created once when the file doesn't exist. Each phase appends a ## Phase section. Never create a new H1.

Phase 6 — Land

Delegate mode landing

If this phase used delegate execution mode, the delegated skill already landed its own work to main. Phase 6 in delegate mode:

1. Verify commits on main — check git log --oneline -10 for the delegate's commits. If missing, the delegate failed to land — invoke Failure Protocol.
2. Verify the report exists (Phase 5 ran)
3. Update the progress tracker (mark phase done)
4. Skip cherry-picking — work is already on main
5. Done. Proceed to next phase or exit.

Worktree mode landing

Pre-landing checklist (worktree mode only)

Before ANY cherry-pick to main, verify ALL of these. If any fails, STOP.

1. ls reports/plan-{slug}.md — report file exists (Phase 5 ran)
2. Report has a ## Phase section for every completed phase
3. In finish mode: cross-phase /verify-changes worktree returned clean
4. If UI-touching phases: playwright-cli agent ran and produced screenshots
5. If UI-touching phases: report has ### User Verification with [ ] items

• Without auto: Phase complete. Output:

  Phase complete. Report written to reports/plan-{slug}.md. Review the worktree and cherry-pick when ready, or use /commit land.

  All interactive landing and cleanup is the user's decision. /run-plan is DONE after writing the report.

• With auto but User Verify items exist: Check the report you just wrote in Phase 5 — if it has a ### User Verification section with unchecked [ ] items, UI changes need human sign-off before landing. Output:

  Phase complete. Report written to reports/plan-{slug}.md. User verification needed before landing — review the report, sign off on UI changes, then run /commit land from the worktree.

  Items needing sign-off: [list from the User Verification section]

  Do NOT auto-land. The worktree is ready; the user reviews and lands when satisfied. This is the landing gate for UI changes — auto automates everything EXCEPT human judgment.

  In finish mode: all phases share one worktree. Do NOT land individual phases as they complete — wait until ALL phases are done, then land everything together. Even non-UI phases should wait, because if a later phase has UI that the user rejects, the earlier phases may need to be revised too. The worktree accumulates all commits; landing is one atomic cherry-pick sequence at the end after all sign-offs.

• With auto and NO User Verify items: Auto-land verified phase commits to main. Exception for finish mode: do NOT auto-land per-phase — a later phase may have UI that needs sign-off. In finish mode, wait until all phases complete, then land everything together (same as the User Verify gate above). Only auto-land per-phase when running a single phase (no finish flag).

  Auto-land steps (single phase, or after all finish-mode phases complete):

  1. Try cherry-picking WITHOUT stashing first. Git allows cherry-picks on a dirty working tree as long as the cherry-picked files don't overlap with uncommitted changes. Other sessions may have uncommitted work in the tree — stashing captures THEIR changes too, and the pop can silently merge or lose them.

     If git refuses with "your local changes would be overwritten," the cherry-pick touches files with uncommitted changes. Handle with LLM-assisted merge:

     1. Note which files overlap
     2. Capture the pre-stash state of each overlapping file: git diff <file> — save/remember this output. It's your evidence of what the uncommitted changes were (possibly from another session).
     3. git stash -u -m "pre-cherry-pick stash"
     4. git cherry-pick <commit-hash>
     5. git stash apply (NOT pop — keep the stash as a recovery path)
     6. If stash apply produces conflict markers (<<<<<<<), resolve them — read both sides and combine. This is expected for overlaps.
     7. For every overlapping file, READ the result and compare against the pre-stash diff from step 2. Verify every changed line from the uncommitted changes is still present AND the cherry-pick's changes landed correctly. If the merge dropped changes, restore them.
     8. After verification, drop the stash: git stash drop
     9. If you genuinely can't reconcile, STOP and report to the user.

  2. Verify main is clean before cherry-picking:

     npm test
     

     If main's tests are already failing, STOP. Invoke the Failure Protocol — do not cherry-pick on top of broken code.

  3. Cherry-pick sequentially — one commit at a time. Try without stash first (step 1). Only stash if git refuses due to file overlap.

  4. If a cherry-pick conflicts: unlike individual issues, a plan phase is one logical unit — partial landing is not useful. Abort all cherry-picks and invoke the Failure Protocol.

     git cherry-pick --abort
     

     Re-run the phase after the conflicting code is resolved on main.

  5. Extract logs and mark worktree as landed: a. Copy unique session logs from worktree to main's .claude/logs/ b. Write .landed marker (atomic: .tmp → mv):

     status: full
     date: <ET timestamp>
     source: run-plan
     phase: <phase name>
     commits: <list of cherry-picked hashes>
     

  6. Commit extracted logs:

     git add .claude/logs/
     git commit -m "chore: session logs from run-plan phase"
     

  7. Restore stash if one was created:

     git stash pop
     

  8. Run tests after all cherry-picks land:

     npm test
     

     If tests fail, invoke the Failure Protocol.

  9. Update tracker to Done — now that landing succeeded, update the plan file's progress tracker from 🟡 In Progress to ✅ Done:

     git add <plan-file>
     git commit -m "chore: mark phase <name> done (landed)"
     

  10. Update the plan report (reports/plan-{slug}.md) — mark the phase section as landed. Regenerate PLAN_REPORT.md index.

  11. Done. Worktree cleanup: worktrees with status: full in .landed are safe to remove.

Failure Protocol

If anything goes wrong during an auto or every run — cherry-pick conflict, test failures after landing, verification fails after 2 fix cycles, all agents fail — execute these steps in this exact order:

1. Kill the cron FIRST

This is the most critical step. A broken run leaves state that a subsequent cron run will stomp on.

CronList → find the /run-plan job ID → CronDelete

Do this BEFORE any cleanup or reporting. Even if you're about to fix the problem, kill the cron. The user can restart it after reviewing.

2. Restore the working tree

If a cherry-pick is in a conflicted state:

git cherry-pick --abort

If a stash was created during Phase 6 auto-land:

git stash pop

If git stash pop conflicts, do NOT attempt to clean up. Do NOT git stash drop (destroys untracked files). Do NOT git checkout -- . (also destroys untracked files extracted during the failed pop). The conflicted state preserves all data — leave it as-is and report to the user:

Stash pop conflicts. Stash preserved (contains untracked files). Run git stash show to inspect, then git stash pop manually.

Never destroy work to clean up. It's always better to STOP with a messy state than to lose files trying to clean up.

3. Write the failure to the plan report

Add a ## Run Failed section at the top of the report:

## Run Failed — YYYY-MM-DD HH:MM

**Plan:** plans/FISHIES_PLAN.md
**Phase:** 2 — Genetics System
**Failed at:** Phase N — [description]
**Error:** [what went wrong]
**State:**
- Cherry-picks landed before failure: [list or "none"]
- Stash restored: yes/no
- Worktree with changes: [path]
- Cron killed: yes (was job ID XXXX)

**To resume:** Review the state above, then either:
- Fix the issue in the worktree and re-run `/run-plan <plan-file> <phase>`
- Run `/run-plan <plan-file> auto every <interval>` to restart the cron

4. Alert the user

Output a clear, prominent message:

⚠ RUN-PLAN FAILED — cron stopped

Phase [N] failed: [one-line reason]
[specific error details]

What happened:
  - Implementation was in worktree [path]
  - [M] commits were cherry-picked to main before failure (or "none")
  - Stash was [restored / not needed]
  - Cron job [ID] has been CANCELLED

Working tree is clean. See reports/plan-{slug}.md for full details.
To restart: /run-plan <plan-file> auto every INTERVAL
To cancel: /run-plan stop

When to trigger

Invoke this protocol for ANY of these:

• Cherry-pick conflict during Phase 6
• npm test fails after cherry-picks are landed
• Verification fails after 2 fix+verify cycles (auto mode)
• Preflight checks detect stale state (conflict markers, orphaned stash)
• Any unrecoverable error that stops the run from completing normally

Do NOT invoke for:

• Individual test failures in the worktree during implementation (the implementer fixes those as part of their workflow)
• Warnings or non-blocking issues

Key Rules

• Never weaken tests — fix the code, not the test. Do not loosen tolerances, skip assertions, or remove test cases.
• Honest status reporting — if the user asks "are you stuck?", answer with DATA: (1) current phase and when it started, (2) agent duration and tool call count, (3) errors or retries. Do not say "everything is fine" if an agent has been running >30 minutes or retried 2+ times.

Edge Cases

• No progress tracker: LLM reads plan sections + checks codebase for evidence of completion (files exist, tests pass, git log mentions the phase)
• Phase fails verification: auto mode tries one fix cycle (dispatch fix agent + re-verify), then stops after 2 total cycles
• All phases complete: report "Plan complete", delete cron if scheduled
• Dependency not met: stop cleanly, report which dependency. If every, the cron retries on next invocation (the dependency may be completed by then)
• Phase "In Progress": another agent may be working — stop, don't compete. Report the conflict.
• Existing worktree for phase: previous incomplete run — ask user (interactive) or try to resume from the existing worktree (auto)
• Implementation produces no commits: the agent worked but committed nothing. Report in reports/plan-{slug}.md as "No commits produced — investigate worktree." Do not attempt to cherry-pick nothing. In auto mode, invoke the Failure Protocol (this is an unrecoverable state for cron)
• Plan file not found: stop immediately, report the error
• Phase arg doesn't match any phase: stop, list available phases