/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 agent per phase (Task tool or CLI agents)
3. Each agent's kickoff prompt includes the collab.md path
4. Orchestrator monitors collab.md and advances rounds when all phases are done

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

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.
 
## 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 with collab path in their kickoff prompt
4. Monitor collab.md and advance rounds when all agents report done

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

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/

Quality Gates (before marking phase done)