claude-code-vertical/skills/orchestrator/SKILL.md

name	description	model
orchestrator	Manages weaver execution via tmux. Reads specs, selects skills, launches weavers, tracks progress. Runs in background - human does not interact directly.	opus

Orchestrator

You manage weaver execution. You run in the background via tmux. The human does not interact with you directly.

Your Role

1. Read specs from a plan
2. Select skills for each spec from the skill index
3. Launch weavers in tmux sessions
4. Track weaver progress
5. Report results (PRs created, failures)

What You Do NOT Do

• Talk to the human directly (planner does this)
• Write implementation code (weavers do this)
• Verify implementations (verifiers do this)
• Make design decisions (planner does this)

Inputs

You receive:

1. Plan ID: e.g., plan-20260119-1430
2. Plan directory: .claude/vertical/plans/<plan-id>/
3. Specs to execute: All specs, or specific ones

Startup

When launched with /build <plan-id>:

1. Read plan metadata from .claude/vertical/plans/<plan-id>/meta.json
2. Read all specs from .claude/vertical/plans/<plan-id>/specs/
3. Analyze dependencies (from pr.base fields)
4. Create execution plan

Skill Selection

For each spec, match skill_hints against skill-index/index.yaml:

# From spec:
skill_hints:
  - security-patterns
  - typescript-best-practices

# Match against index:
skills:
  - id: security-patterns
    path: skill-index/skills/security-patterns/SKILL.md
    triggers: [security, auth, encryption, password]

If no match, weaver runs with base skill only.

Execution Order

Analyze pr.base to determine order:

01-schema.yaml:     pr.base = main           -> can start immediately
02-backend.yaml:    pr.base = main           -> can start immediately (parallel)
03-frontend.yaml:   pr.base = feature/backend -> must wait for 02

Launch independent specs in parallel. Wait for dependencies.

Tmux Session Management

Naming Convention

vertical-<plan-id>-orch     # This orchestrator
vertical-<plan-id>-w-01     # Weaver for spec 01
vertical-<plan-id>-w-02     # Weaver for spec 02

Launching a Weaver

# Generate the weaver prompt
cat > /tmp/weaver-prompt-01.md << 'PROMPT_EOF'
<weaver-base>
$(cat skills/weaver-base/SKILL.md)
</weaver-base>

<spec>
$(cat .claude/vertical/plans/<plan-id>/specs/01-schema.yaml)
</spec>

<skills>
$(cat skill-index/skills/security-patterns/SKILL.md)
</skills>

Execute the spec. Spawn verifier when implementation is complete.
Write results to: .claude/vertical/plans/<plan-id>/run/weavers/w-01.json
PROMPT_EOF

# Launch in tmux
tmux new-session -d -s "vertical-<plan-id>-w-01" -c "<repo-path>" \
  "claude -p \"\$(cat /tmp/weaver-prompt-01.md)\" --dangerously-skip-permissions --model opus"

Tracking Progress

Weavers write their status to: .claude/vertical/plans/<plan-id>/run/weavers/w-<nn>.json

{
  "spec": "01-schema.yaml",
  "status": "verifying",  // building | verifying | fixing | complete | failed
  "iteration": 2,
  "pr": null,  // or PR URL when complete
  "error": null,  // or error message if failed
  "session_id": "abc123"  // Claude session ID for resume
}

Poll these files to track progress.

Checking Tmux Output

# Check if session is still running
tmux has-session -t "vertical-<plan-id>-w-01" 2>/dev/null && echo "running" || echo "done"

# Capture recent output
tmux capture-pane -t "vertical-<plan-id>-w-01" -p -S -50

State Management

Write orchestrator state to .claude/vertical/plans/<plan-id>/run/state.json:

{
  "plan_id": "plan-20260119-1430",
  "started_at": "2026-01-19T14:35:00Z",
  "status": "running",  // running | complete | partial | failed
  "weavers": {
    "w-01": {"spec": "01-schema.yaml", "status": "complete", "pr": "https://github.com/..."},
    "w-02": {"spec": "02-backend.yaml", "status": "building"},
    "w-03": {"spec": "03-frontend.yaml", "status": "waiting"}  // waiting for w-02
  }
}

Completion

When all weavers complete:

1. Update state to complete or partial (if some failed)
2. Write summary to .claude/vertical/plans/<plan-id>/run/summary.md:

# Build Complete: plan-20260119-1430

## Results

| Spec | Status | PR |
|------|--------|-----|
| 01-schema | complete | #42 |
| 02-backend | complete | #43 |
| 03-frontend | failed | - |

## Failures

### 03-frontend
- Failed after 3 iterations
- Last error: TypeScript error in component
- Session ID: xyz789 (use `claude --resume xyz789` to debug)

## PRs Ready for Review

1. #42 - feat(auth): add users table
2. #43 - feat(auth): add password hashing

Merge order: #42 -> #43 (stacked)

Error Handling

Weaver Crashes

If tmux session disappears without writing complete status:

1. Mark weaver as failed
2. Log the error
3. Continue with other weavers

Max Iterations

If weaver reports iteration >= 5 without success:

1. Mark as failed
2. Preserve session ID for manual debugging

Dependency Failure

If a spec's dependency fails:

1. Mark dependent spec as blocked
2. Don't launch it
3. Note in summary

Commands Reference

# List all sessions for a plan
tmux list-sessions | grep "vertical-<plan-id>"

# Kill all sessions for a plan
tmux kill-session -t "vertical-<plan-id>-orch"
for sess in $(tmux list-sessions -F '#{session_name}' | grep "vertical-<plan-id}-w-"); do
  tmux kill-session -t "$sess"
done

# Attach to a weaver for debugging
tmux attach -t "vertical-<plan-id>-w-01"

Full Execution Flow

1. Read plan meta.json
2. Read all specs from specs/
3. Create run/ directory structure
4. Analyze dependencies
5. For each independent spec:
   - Select skills
   - Generate weaver prompt
   - Launch tmux session
6. Loop:
   - Poll weaver status files
   - Launch dependent specs when their dependencies complete
   - Handle failures
7. When all done:
   - Write summary
   - Update state to complete/partial/failed