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

name	description
orchestrator	Manages weaver execution via tmux. Reads specs, selects skills, launches weavers in parallel, tracks progress. Runs in background.

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. Analyze dependencies and determine execution order
3. Select skills for each spec from the skill index
4. Launch weavers in tmux sessions
5. Track weaver progress by polling status files
6. Handle failures and dependency blocking
7. Write summary when complete
8. Notify human of results

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 via prompt:

<orchestrator-skill>
[This skill]
</orchestrator-skill>

<plan-id>plan-20260119-1430</plan-id>
<repo-path>/path/to/repo</repo-path>

Execute the plan. Spawn weavers. Track progress. Write summary.

Startup Sequence

1. Read Plan

cd <repo-path>
cat .claude/vertical/plans/<plan-id>/meta.json

Extract:

• specs array
• repo path
• description

2. Read All Specs

for spec in .claude/vertical/plans/<plan-id>/specs/*.yaml; do
  cat "$spec"
done

3. Analyze Dependencies

Build dependency graph from pr.base field:

Spec	pr.base	Can Start
01-schema.yaml	main	Immediately
02-backend.yaml	main	Immediately
03-frontend.yaml	feature/backend	After 02 completes

Independent specs (base = main) → launch in parallel Dependent specs (base = other branch) → wait for dependency

4. Initialize State

cat > .claude/vertical/plans/<plan-id>/run/state.json << 'EOF'
{
  "plan_id": "<plan-id>",
  "started_at": "<ISO timestamp>",
  "status": "running",
  "weavers": {}
}
EOF

Skill Selection

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

# Read the index
cat skill-index/index.yaml

Match algorithm:

1. For each hint in skill_hints
2. Find matching skill ID in index
3. Get skill path from index
4. Collect all matching skill files

If no matches: weaver runs with base skill only.

Launching Weavers

Session Naming

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

Generate Weaver Prompt

For each spec, create /tmp/weaver-prompt-<nn>.md:

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/<matched-skill>/SKILL.md)
</skills>

<verifier-skill>
$(cat skills/verifier/SKILL.md)
</verifier-skill>

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

Begin now.
PROMPT_EOF

Launch Tmux Session

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 claude-opus-4-5-20250514; echo '[Weaver complete]'; sleep 5"

Update State

{
  "weavers": {
    "w-01": {
      "spec": "01-schema.yaml",
      "status": "running",
      "session": "vertical-<plan-id>-w-01"
    }
  }
}

Progress Tracking

Poll Loop

Every 30 seconds:

# Check each weaver status file
for f in .claude/vertical/plans/<plan-id>/run/weavers/*.json; do
  cat "$f" | jq '{spec, status, pr, error}'
done

Status Transitions

Weaver Status	Orchestrator Action
building	Continue polling
verifying	Continue polling
fixing	Continue polling
complete	Record PR, check if dependencies unblocked
failed	Record error, block dependents

Launching Dependents

When weaver completes:

1. Check if any waiting specs depend on this one
2. If dependency met, launch that weaver
3. Update state

Spec 02-backend complete → PR #43
Checking dependents...
  03-frontend depends on feature/backend
  Launching w-03...

Checking Tmux Status

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

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

Error Handling

Weaver Crash

If tmux session disappears without status file update:

{
  "weavers": {
    "w-01": {
      "status": "crashed",
      "error": "Session terminated without completion"
    }
  }
}

Dependency Failure

If a spec's dependency fails:

1. Mark dependent spec as blocked
2. Do not launch it
3. Continue with other independent specs

{
  "weavers": {
    "w-02": {"status": "failed", "error": "..."},
    "w-03": {"status": "blocked", "error": "Dependency w-02 failed"}
  }
}

Max Iterations

If weaver reports iteration >= 5 without success:

• Already marked as failed by weaver
• Orchestrator notes and continues

Completion

When all weavers are done (complete, failed, or blocked):

1. Determine Overall Status

Condition	Status
All complete	complete
Some complete, some failed	partial
All failed	failed

2. Write Summary

cat > .claude/vertical/plans/<plan-id>/run/summary.md << 'EOF'
# Build Complete: <plan-id>

**Status**: <complete|partial|failed>
**Started**: <timestamp>
**Completed**: <timestamp>

## Results

| Spec | Status | PR |
|------|--------|-----|
| 01-schema | ✓ complete | [#42](url) |
| 02-backend | ✓ complete | [#43](url) |
| 03-frontend | ✗ failed | - |

## PRs Ready for Review

Merge in this order (stacked):
1. #42 - feat(auth): add users table
2. #43 - feat(auth): add password hashing

## Failures

### 03-frontend
- **Error**: TypeScript error in component
- **Iterations**: 5
- **Session**: w-03
- **Debug**: `cat .claude/vertical/plans/<plan-id>/run/weavers/w-03.json`
- **Resume**: Find session ID in status file, then `claude --resume <session-id>`

## Commands

```bash
# View PR list
gh pr list

# Merge PRs in order
gh pr merge 42 --merge
gh pr merge 43 --merge

# Debug failed weaver
tmux attach -t vertical-<plan-id>-w-03  # if still running
claude --resume <session-id>            # to continue

EOF

### 3. Update Final State

```json
{
  "plan_id": "<plan-id>",
  "started_at": "<timestamp>",
  "completed_at": "<timestamp>",
  "status": "complete",
  "weavers": {
    "w-01": {"spec": "01-schema.yaml", "status": "complete", "pr": "#42"},
    "w-02": {"spec": "02-backend.yaml", "status": "complete", "pr": "#43"},
    "w-03": {"spec": "03-frontend.yaml", "status": "failed", "error": "..."}
  }
}

4. Notify Human

Output to stdout (visible in tmux):

╔══════════════════════════════════════════════════════════════════╗
║                    BUILD COMPLETE: <plan-id>                      ║
╠══════════════════════════════════════════════════════════════════╣
║  ✓ 01-schema          complete     PR #42                        ║
║  ✓ 02-backend         complete     PR #43                        ║
║  ✗ 03-frontend        failed       -                             ║
╠══════════════════════════════════════════════════════════════════╣
║                                                                  ║
║  Summary: .claude/vertical/plans/<plan-id>/run/summary.md        ║
║  PRs:     gh pr list                                             ║
║                                                                  ║
╚══════════════════════════════════════════════════════════════════╝

Full Execution Flow

1. Read meta.json
2. Read all specs from specs/
3. Create run/ directory structure
4. Analyze dependencies (build graph)
5. Write initial state.json
6. For each independent spec:
   a. Match skills from index
   b. Generate weaver prompt file
   c. Launch tmux session
   d. Update state
7. Poll loop:
   a. Check weaver status files every 30s
   b. Check if tmux sessions still running
   c. Launch dependents when their deps complete
   d. Handle failures
8. When all done:
   a. Determine overall status
   b. Write summary.md
   c. Update state.json
   d. Print completion notification

Tmux Commands Reference

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

# Attach to orchestrator
tmux attach -t "vertical-<plan-id>-orch"

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

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

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