/large-plan

Invoke as: /large-plan (single segment).
Source: ~/Gits/golems/skills/golem-powers/large-plan/ (symlinked at ~/.claude/commands/large-plan).

Scaffold folder-based plans with phase folders, execute them through the branch-PR-review cycle, and coordinate async agent collaboration.

Quick Actions

Available Scripts

Core Concept

Large plans are folder-based: one folder per phase, each containing a README.md (steps) and findings.md (shared knowledge). A main README.md acts as the index with a progress table and routing.

plan-dir/
  README.md              # Index: progress table, routing, execution rules
  collab.md              # Created when parallel phases exist (see below)
  phase-1-name/
    README.md            # Steps for this phase
    findings.md          # Shared knowledge room (agents write here)
  phase-2-name/
    README.md
    findings.md
  ...

Execution Decision: Sequential vs Parallel

EVERY plan must decide this at scaffold time. Analyze the dependency graph:

Phases with NO cross-dependencies  →  Parallel (collab.md + multiple agents)
Phases that depend on each other   →  Sequential (execute-phase, one at a time)
Mixed                              →  Rounds (parallel within round, sequential between rounds)

Decision tree:

1. Draw the dependency graph from phase Depends On fields
2. Group independent phases into rounds (phases in the same round can run in parallel)
3. If ANY round has 2+ phases → create collab.md at plan root
4. Add ## Execution Strategy to the main README.md showing rounds and parallelism

Example:

## Execution Strategy
 
| Round | Phases | Mode | Agents |
|-------|--------|------|--------|
| 1 | Phase 1, Phase 2 | **parallel** (collab) | brainClaude, golemsClaude |
| 2 | Phase 3 (depends on 1+2) | sequential | mainClaude |
| 3 | Phase 4, Phase 5 | **parallel** (collab) | brainClaude, golemsClaude |

When a round has parallel phases, the orchestrator:

1. Creates/updates collab.md using the collab protocol
2. Spawns one managed cmux agent per phase in the parent/caller agent's workspace unless the user explicitly asks for a different workspace, with explicit role:"worker" unless the seat is the coordinating lead. Do not route by the human's currently focused workspace; if cmux must focus the parent workspace to initialize a terminal, it must restore the user's prior focus after the new pane is available. If a successor/coordinating lead is spawned in a workspace that already has a left lead pane, it must become a tab in that same lead pane; a new left split or third column is a health failure, not an acceptable layout variant.
3. Writes the returned agent_id, surface, workspace, role, session/resume health, inbox health, and topology health into the collab Agent table
4. Each agent's kickoff prompt includes the collab.md path and required DONE marker
5. Orchestrator monitors collab.md, wait_for(agent_id), inbox events, and output DONE files, then advances rounds when all phases are verified done. For file-backed cmux workers, the wait_for(done) call must include the worker's report_path and exact done_marker.
6. Worker completion must wake the owning lead through an adapter-owned guard: Claude native /loop/Cron/Monitor, file-backed wait_for({target_state:"done",report_path,done_marker}), live inbox/subscription, cmux notify, or a recorded temporary watcher. A report DONE marker or visible TASK_DONE without lead notification is completion_notification_missing health evidence. The worker does not have to post to the collab for this to fire; the report path and DONE marker are state, and the inbox/notification/watcher path is the event.
7. Codex leads must arm a guard before delegating: live inbox heartbeat, file-backed wait_for(done) receipt owned by the lead, or a background watcher/loop PID/task id that watches the registered collab/goal/report/DONE paths. Native cmuxlayer delivery may satisfy this when present, but the skill contract does not depend on it. No guard is blocked:health.
8. Completed workers should be harvested, reviewed or handed off, then closed. Keeping a completed worker open is valid for active review, successor orientation, live process state, or paired continuation; stale purposeless panes are done_worker_left_open health evidence. If kept, the Agent row must say KEPT_OPEN:<reason> with owner and next check.

Continuation / Recovery Authority

A large-plan dispatch is not permission to park. When the user has approved the plan or assigned a lane, agents have delegated authority to complete the normal path for that lane: commit, push, PR, review loop, merge when the lead/goal owns merge, restart in-scope services/MCPs, and resume or replace workers that cannot continue. Generic statements like "I can't commit", "I can't merge", "I can't restart BrainLayer/cmuxlayer MCP", or "Codex cannot reconnect MCPs" are not terminal blockers.

Recoverable blockers must become actions:

• For PR work: invoke /pr-loop; approved work already authorizes the full loop unless the goal explicitly says "no merge".
• For daemon/MCP work: checkpoint, restart/reload the in-scope service, verify with a real probe, and continue.
• For Codex MCP reconnect limits: write a handoff and spawn/resume a managed successor that boots with the needed MCPs.
• For stale or idle workers: the lead monitor nudges, supersedes, resumes, or replaces; it does not wait for the user to discover the idle pane.

Only irreversible data loss, force-push/history rewrite, destructive cleanup of unowned work, credential/account changes, paid external actions, or human-only license acceptance become blocked:human.

Plan Lifecycle

Scaffold plan  →  Analyze dependencies  →  Group into rounds
                                                |
                    ┌───────────────────────────┘
                    ▼
              Round has 1 phase?  →  Execute sequentially (execute-phase)
              Round has 2+ phases? → Create collab.md, spawn agents in parallel
                    |
                    ▼
              All round phases done  →  Advance to next round  →  Repeat

Non-Code Deliverables Check (MANDATORY at scaffold time)

Root cause (April 5 overnight sprint): orcClaude missed the second track — user wanted 9 entity files enhanced for morning walk + code PRs by dawn. Agent only scaffolded the code track.

At scaffold time, ALWAYS ask: "Are there non-code deliverables alongside the code phases?"

Common non-code deliverables:

• Data enrichment / content curation (entity files, research docs, grill enhancement)
• Documentation updates (READMEs, portfolio pages, design docs)
• Configuration changes (LaunchAgents, hooks, environment)
• Research outputs (A/B test results, comparative analysis)

If yes, add a separate phase or parallel track for the non-code work. Non-code deliverables are often the user's PRIMARY goal — the code is just infrastructure supporting it.

Branch Lifecycle (per phase)

master -> feature/phase-N-name -> implement -> commit -> push -> PR
  ^                                                            |
  |__ merge <-- approve <-- fix <-- review (CodeRabbit + Cursor Bugbot + DeepSource)

Phase Template

Each phase README follows this template:

# Phase N: Name
 
> [Back to main plan](../README.md)
 
## Goal
One sentence describing what this phase achieves.
 
## Time
- **Estimate:** NNmin (basis: [complexity/rolling avg from prior phases])
- **Started:** HH:MM
- **Completed:** —
- **Actual:** —
- **Error ratio:** —
 
## Round
Round M (parallel with Phase X, Phase Y) OR Round M (sequential).
 
## Tools
- **Research:** [gemini|cursor|codex] — what to research
- **Code:** [cursor|haiku|sonnet] — what to implement
- **MCPs:** [list relevant MCP servers]
 
## Steps
1. Step one
2. Step two
3. ...
 
## Depends On
- Phase X (for Y reason)
 
## Status
- [ ] Step one
- [ ] Step two

Findings Template

Each phase findings.md is the shared collaboration room:

# Phase N Findings
 
## Decisions
- [timestamp] Decision: ...
 
## Research
- [timestamp] Agent: Found that ...
 
## Task Board
| Task | Owner | Status |
|------|-------|--------|
| Research X | gemini | done |
| Implement Y | cursor | in progress |

Parallel Execution (Collab Protocol)

When a round has 2+ independent phases, use the full collab protocol defined in workflows/collab.md.

The orchestrator MUST:

1. Create collab.md at plan root using the template from the collab workflow
2. Fill in all mandatory sections (Goal, Agents, Task Board, Constraints, Gates)
3. Spawn agents through managed cmux lifecycle in the caller/current workspace unless explicitly overridden, with explicit roles (orchestrator for the coordinating lead, worker for phase executors)
4. Record each returned agent_id plus surface/workspace/session/inbox/topology health before the first task dispatch, and verify get_agent_state agrees with list_surfaces
5. Monitor collab.md, file-backed wait_for, inbox_check, Metacomm inbox events, and file DONE markers; advance rounds only when all agents are verified done

Key rule: If the human has to tell you to update the collab file, the collab has failed. Agents must self-coordinate.

Health rule: missing agent_id, auto-* discovered agents, null cli_session_id on crash-recover/long-running workers, non-resumability, inbox_check.monitor_alive=false, wedged prompts, registry/screen disagreement, registry/surface workspace disagreement, surprise workspace creation, role mismatch, worker-in-left-column placement, or unexpected three-column topology are blocked:health entries, not normal status.

Add these live dispatch failures to the same blocked:health bucket:

• successor_lead_wrong_pane: an orchestrator/successor lead lands as a separate left split instead of a tab in the existing lead pane.
• boot_prompt_typed_not_submitted: the task prompt is visible in the Codex/Cursor/Gemini composer after spawn but was never submitted. Recover with Return if needed, but record the failure even if the worker later produces its report.

Complexity tiers (from collab workflow):

• Lightweight (~40 lines): 2 agents, fully independent work
• Standard (~100 lines): 2-3 agents, some dependencies
• Complex (~200 lines): 3+ agents, multi-repo, round-based

See workflows/collab.md for the full protocol, mandatory sections, update gates, message format, and anti-patterns.

Integration with Other Skills (Building Blocks)

MANDATORY for every phase:

Optional per phase:

PR Review Cycle (per phase)

After push, automated reviewers comment. Classify each:

Repeat push-fix cycle until no real bugs remain.

Platform Features vs Universal Fallbacks

Claude Code features are listed first. If running on Codex or Cursor, use the universal fallback. Full adapter docs: adapters/

Worker Pane Hygiene

Worker panes are working memory, not trophies. After a worker reaches TASK_DONE, Goal achieved, or a verified report DONE marker, the lead should:

1. harvest the report/output path and exact DONE marker;
2. review it or transfer it to a successor/reviewer when needed;
3. close/archive the pane unless it is actively useful.

It is valid to keep a completed worker open when it supports active review, successor orientation, live process state, or paired continuation. If a worker stays open, the Agent row must say KEPT_OPEN:<reason> with owner and next check. A completed or stale worker left visible with no current purpose is done_worker_left_open health evidence. Use judgment; the rule is critical cleanup, not bureaucracy.

Cursor-Workflows Inner Loop Recon

For read-heavy, cross-skill remediation, use cursor-workflows as an inner loop, not a single shallow gather. Use lib/autocursor.py primitives: parallel() for independent file reads, then loop_until_dry() to expand from findings into follow-up checks, red-team passes, and targeted probes until consecutive rounds add no stable new findings. Keep it read-only unless the user explicitly asks for mutation; the lead still owns edits, verification, and final synthesis.

Use this when the contract spans multiple skills/adapters/evals/reports and a single pass could miss second-order drift. Do not use it reflexively for simple local edits.

Time Tracking & Estimation Calibration (MANDATORY)

Data from April 5 overnight sprint (brainlayer, Codex workers): estimated 90min/phase, actual 15min average. Started at 6x overestimate, auto-calibrated to 1.25x by phase 7. Record timestamps at phase start + PR creation. Without tracking, estimates never calibrate.

At Scaffold Time

The main README.md progress table MUST include estimate and actual columns:

## Progress
 
| Phase | Status | Estimate | Started | Completed | Actual | Error |
|-------|--------|----------|---------|-----------|--------|-------|
| 1. Setup | ✅ done | 30min | 1:15 AM | 1:28 AM | 13min | 2.3x |
| 2. Search | ✅ done | 30min | 1:30 AM | 1:42 AM | 12min | 2.5x |
| 3. Hybrid | 🔄 active | 15min* | 1:45 AM | — | — | — |
| 4. Evals | ⏳ pending | 15min* | — | — | — | — |
 
*Auto-recalibrated from rolling avg of phases 1-2 (12.5min → round to 15min)
Rolling calibration: 2.3x → 2.5x → tracking...

At Phase Start (CLOCK IN)

brain_store(
  content: "CLOCK IN [plan-name / Phase N]: Started HH:MM. Estimate: NNmin. Basis: [first phase=complexity, later=rolling avg].",
  tags: ["time-tracking", "clock-in", "<project>"],
  importance: 5
)

Fill in the phase template's Time section: Started, Estimate.

At Phase Complete (CLOCK OUT)

brain_store(
  content: "CLOCK OUT [plan-name / Phase N]: PR merged HH:MM. Actual: NNmin. Estimated: NNmin. Error: X.Xx. Rolling avg (last 3): NNmin.",
  tags: ["time-tracking", "clock-out", "<project>"],
  importance: 5
)

Fill in the phase template's Time section: Completed, Actual, Error ratio. Update the main README progress table.

Auto-Recalibration (after 3+ phases)

Once 3 phases have actuals:

rolling_avg = average(last 3 actuals)
remaining_phases × rolling_avg = estimated total remaining

Report: "Phases 1-3 done in 38min total. Rolling avg: 12.7min.
         Remaining 4 phases: ~51min at current pace.
         Sprint total ETA: ~89min (original estimate was 630min = 7.1x overestimate)"

Rule: After 3+ phases, new estimates MUST be within 2x of rolling average. Don't keep estimating 90min when actuals are 15min.

Why This Matters

User correction (April 5): "No, I'm saying it will take probably hours, not weeks" — after orc estimated a 2-week timeline for work that took one evening. Time tracking turns this from a repeated correction into self-correcting behavior.

Quality Gates (before marking phase done)

Phase N+1: Adversarial Evaluator (NON-NEGOTIABLE)

Closes the self-audit-as-evaluator substitution loophole. Observed at P5 fix queue 2026-05-17 — agent self-graded "evaluator replay PASS" without dispatching a separate evaluator. /goal hook silently passed.

Every /large-plan output that produces code, scripts, configs, or plist drafts MUST end with a Phase N+1 that:

1. Spawns a separate evaluator subagent (NOT the producing agent's self-audit).
   • Use Agent(subagent_type=evaluator, ...) or equivalent platform fallback.
   • The evaluator MUST be a different agent invocation from the one that produced the work.
2. Hands the evaluator a verbatim copy of every "Pass criterion" from the original /goal hook (no paraphrasing, no summarization).
3. Requires the evaluator to re-Read each cited file:line and run anti-fabrication checks (per /never-fabricate Live-citation gate).
4. The evaluator MUST score ≥8/10 OR produce an ITERATE verdict with specific fixes.
5. SELF-AUDIT IS NOT EVALUATION. If the producing agent grades its own work, the /goal hook does not pass — re-dispatch with explicit subagent_type ≠ producing agent.

Template: workflows/phase-evaluator.md — minimal evaluator-subagent dispatch (prompt format, scoring rubric link).

Done-gate semantics:

Evidence: 4-of-4 /goal outputs 2026-05-17 night surfaced critical issues only when externally evaluated. P5 fix queue silently substituted self-audit for the required external evaluator replay (skillcreator-p5fix mine [1438]).