Orc Generate

Orc Generate

Thin orchestrator for plan generation. Owns the workflow loop — delegates ALL planning methodology to thick agents (orc-planner, orc-plan-checker).

Input

• $ARGUMENTS — Plan slug

Templates

• [templates/ROADMAP.md](templates/ROADMAP.md) — Phase tracking

Execution

Step 0: Initialize Todos

Step 1: Load Context

Read:

• .claude/plans/$ARGUMENTS/PROJECT.md — vision
• .claude/plans/$ARGUMENTS/STATE.md — codebase findings
• .claude/plans/$ARGUMENTS/research/SUMMARY.md — domain research synthesis (if exists)

Step 2: Design Phase Breakdown

Analyze PROJECT.md and STATE.md to design phases:

• Atomic tasks per phase
• Each phase independently verifiable
• Order: dependencies → core → enhancements

Step 3: Validate with User

Present your proposed phase breakdown and ask for feedback:

Based on the vision and codebase analysis, here's my proposed phase breakdown:

**Phase 1: **
- Task 1.1: 
- Task 1.2: 

**Phase 2: **
- Task 2.1: 
- Task 2.2: 

**Phase 3: ** (if needed)
- Task 3.1: 

...

for each phase:

**Phase N: **
- Task N.1: 
Please review and let me know:
1. Does this breakdown make sense for your priorities?
2. Should any phases be combined, split, or reordered?
3. Before planning starts, would you like to discuss or research any specific phase?
   Run `/orc-discuss $slug N` or `/orc-phase-research $slug N` standalone, then tell me to proceed.
4. Is anything missing or unnecessary?

Step 4: Write ROADMAP.md

Write .claude/plans/$ARGUMENTS/ROADMAP.md with phase overview. Include Requirements: field per phase (see template).

Step 5: Plan Phases (Team-Based Convergence)

For each phase N (with kebab-case name) defined in ROADMAP.md:

5a. Create phase directory

mkdir -p .claude/plans/$ARGUMENTS/phases/0{N}-{name}

5b. Pre-flight cleanup

ls ~/.claude/teams/plan-$ARGUMENTS-* 2>/dev/null

Clean up orphaned team directories from previous failed runs before creating new team.

5c. Create team

TeamCreate(team_name="plan-$ARGUMENTS-phase-{N}", description="Planner↔checker convergence loop for phase {N}")

5d. Create coordination tasks

TaskCreate(subject="Create phase {N} plan", description="Planner: create PLAN.md for phase {N}")
TaskCreate(subject="Verify phase {N} plan", description="Checker: verify PLAN.md for phase {N}")
TaskCreate(subject="Check ADR compliance for phase {N}", description="Sentinel: check PLAN.md against ADRs for phase {N}")

5e. Spawn planner teammate

Task(
  name="planner",
  subagent_type="orc:orc-planner",
  team_name="plan-$ARGUMENTS-phase-{N}",
  model: "opus",
  prompt="You are the planner teammate on team \"plan-$ARGUMENTS-phase-{N}\".

**Plan template:** Read [templates/PLAN.md](templates/PLAN.md)

**Context to load:**
- .claude/plans/$ARGUMENTS/PROJECT.md
- .claude/plans/$ARGUMENTS/STATE.md
- .claude/plans/$ARGUMENTS/ROADMAP.md (find Phase {N} section)
- .claude/plans/$ARGUMENTS/phases/0{N}-{name}/CONTEXT.md (if exists)
- .claude/plans/$ARGUMENTS/phases/0{N}-{name}/RESEARCH.md (if exists)

**Phase:** {N} — {name}
**Goal:** {goal from ROADMAP}
**Requirements:** {requirement IDs from ROADMAP}

**Task dependency requirement:** Every `` element MUST include a `depends_on` attribute. List comma-separated task IDs this task waits for, or use empty string for no dependencies. Example: ``. This is required — orc-swarm uses it to partition tasks across executor teammates.

Claim \"Create phase {N} plan\" from TaskList. Create PLAN.md, then notify checker."
)

5f. Spawn checker teammate

Task(
  name="checker",
  subagent_type="orc:orc-plan-checker",
  team_name="plan-$ARGUMENTS-phase-{N}",
  model: "opus",
  prompt="You are the checker teammate on team \"plan-$ARGUMENTS-phase-{N}\".

**Context to load:**
- .claude/plans/$ARGUMENTS/ROADMAP.md (Phase {N} section)
- .claude/plans/$ARGUMENTS/phases/0{N}-{name}/CONTEXT.md (if exists)

**Phase:** {N} — {name}
**Plan path:** .claude/plans/$ARGUMENTS/phases/0{N}-{name}/PLAN.md

Wait for planner to notify you before starting. Claim \"Verify phase {N} plan\" from TaskList when ready."
)

5f2. Spawn sentinel teammate

Task(
  name="sentinel",
  subagent_type="orc:orc-adr-sentinel",
  team_name="plan-$ARGUMENTS-phase-{N}",
  model: "opus",
  prompt="You are the ADR sentinel on team \"plan-$ARGUMENTS-phase-{N}\".

**ADR directory:** docs/adr/
**Phase plan:** .claude/plans/$ARGUMENTS/phases/0{N}-{name}/PLAN.md
**Roadmap:** .claude/plans/$ARGUMENTS/ROADMAP.md

**Phase:** {N} — {name}

Wait for planner to notify you, then check for ADR deviations."
)

5g. Monitor convergence

Receive messages from teammates automatically. The planner↔checker loop self-sustains via SendMessage:

1. Planner creates PLAN.md → notifies checker
2. Checker verifies → sends PASSED or ISSUES
3. If ISSUES: planner revises → notifies checker → checker re-verifies
4. Repeat until PASSED or 3 iterations

Track via TaskList: When both "Create phase plan" and "Verify phase plan" tasks are completed, convergence is reached.

If 3 iterations with still failing:

AskUserQuestion:
  header: "Stuck"
  question: "Phase {N} plan failed verification after 3 planner↔checker rounds. How should I proceed?"
  options:
    - label: "Force proceed"
      description: "Accept the plan with known issues"
    - label: "Provide guidance"
      description: "I'll give specific direction for the planner"
    - label: "Abandon phase"
      description: "Skip this phase entirely"

Monitoring protocol:

• Don't react to every idle notification. Teammates go idle between turns — this is normal.
• Gate progress on actual output: check if PLAN.md exists in phase directory before nudging.
• Only re-send instructions if a teammate has been idle for >2 minutes AND expected PLAN.md is missing.
• If a teammate goes idle repeatedly without progress after 3 checks, investigate via TaskList.
• Sentinel messages are deviation reports — present significant ones to user via AskUserQuestion before proceeding to next phase.

5h. Shutdown and cleanup

SendMessage(type="shutdown_request", recipient="planner", content="Phase plan converged.")
SendMessage(type="shutdown_request", recipient="checker", content="Phase plan converged.")
SendMessage(type="shutdown_request", recipient="sentinel", content="Phase plan converged.")

Wait for all 3 shutdown confirmations before proceeding.

TeamDelete()

Continue to next phase.

Step 6: Report Completion

After all phases have converged:

Plan generation complete:
├── ROADMAP.md
└── phases/
    ├── 01-/PLAN.md (verified)
    ├── 02-/PLAN.md (verified)
    └── ...

All phase plans passed planner↔checker verification.
Run: /orc-swarm [phase description] to plan implementation of each phase

If any phase was force-proceeded:

Plan has known issues in phase(s): {list}.
Review phase PLAN.md files before proceeding.

Document Size Limits

| Document | Rationale | |----------|-----------| | ROADMAP.md | Overview must fit in single read | | STATE.md | Incremental updates, not rewrites |

Execution Rules

1. Always create the team — never plan a phase in a single agent
2. Both agents use opus — planning and verification need strongest model
3. Don't duplicate agent work — let planner↔checker iterate peer-to-peer
4. Monitor, don't micromanage — only intervene on escalations or completion
5. Wait for shutdown confirmations — never TeamDelete before all 3 agents confirm
6. Pre-flight cleanup — check for orphaned teams before creating new ones
7. FINDINGS.md is append-only — checker appends per round, never overwrites

Readiness Checklist

Before completing, verify ALL:

• [ ] ROADMAP.md written with requirement IDs per phase
• [ ] All phase PLAN.md files created and verified by checker
• [ ] Total tasks across all phases <= 10
• [ ] Phase dependencies are explicit and acyclic
• [ ] Each phase plan has populated musthaves (truths, artifacts, keylinks)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: qGolem
• Source: qGolem/orc
• License: MIT

Install and usage instructions live in the source repository linked above.