claude-code-vertical/CLAUDE.md

Claude Code Vertical

Multi-agent orchestration system for Claude Code. Scale horizontally (multiple planning sessions) and vertically (weavers executing in parallel).

Read the complete workflow: WORKFLOW.md

Architecture

You (Terminal)
    │
    │ /plan
    ▼
Planner (interactive)     ← You talk here
    │
    │ (writes specs)
    ▼
Orchestrator (tmux background)
    │
    ├─→ Weaver 01 (tmux) → Verifier (subagent) → PR
    ├─→ Weaver 02 (tmux) → Verifier (subagent) → PR
    └─→ Weaver 03 (tmux) → Verifier (subagent) → PR

Commands

Command	Description
/plan	Start interactive planning session
/build <plan-id>	Execute a plan (spawns orchestrator + weavers)
/status [plan-id]	Check status of plans and weavers

Quick Start

# Start planning
claude
> /plan

# Design your specs interactively...
# When ready, planner tells you the plan-id

# Execute
> /build plan-20260119-1430

# Check status
> /status plan-20260119-1430

Directory Structure

.claude/vertical/
  plans/
    <plan-id>/
      meta.json           # Plan metadata
      specs/              # Spec YAML files
        01-schema.yaml
        02-backend.yaml
      run/
        state.json        # Orchestrator state
        summary.md        # Human-readable results
        weavers/
          w-01.json       # Weaver status
          w-02.json

All Agents Use Opus

Every agent uses claude-opus-4-5-20250514:

• Planner
• Orchestrator
• Weavers
• Verifiers (subagents)

Key Rules

Tests Never Ship

Weavers may write tests for verification. They are never committed:

git reset HEAD -- '*.test.*' '*.spec.*' '__tests__/' 'tests/'

PRs Are Always Created

A weaver's success = PR created. No PR = failure.

Verification Is Mandatory

Weavers spawn verifier subagents. No self-verification.

Context Is Isolated

Agent	Sees	Doesn't See
Planner	Full codebase, human	Weaver impl
Orchestrator	Specs, skill index	Actual code
Weaver	Its spec, its skills	Other weavers
Verifier	Verification spec	Building spec

Tmux Session Naming

vertical-<plan-id>-orch     # Orchestrator
vertical-<plan-id>-w-01     # Weaver 1
vertical-<plan-id>-w-02     # Weaver 2

Skill Index

Skills live in skill-index/skills/. The orchestrator uses skill-index/index.yaml to match skill_hints from specs.

Resuming Sessions

# Get session ID from weaver status
cat .claude/vertical/plans/<plan-id>/run/weavers/w-01.json | jq -r .session_id

# Resume
claude --resume <session-id>

Debugging

source lib/tmux.sh

vertical_list_sessions                           # List all sessions
vertical_attach vertical-plan-20260119-1430-w-01 # Attach to weaver
vertical_capture_output <session> # Capture output
vertical_kill_plan plan-20260119-1430            # Kill plan sessions

Spec Format

name: feature-name
description: What this PR accomplishes

skill_hints:
  - relevant-skill-1
  - relevant-skill-2

building_spec:
  requirements:
    - Requirement 1
    - Requirement 2
  constraints:
    - Constraint 1
  files:
    - src/path/to/file.ts

verification_spec:
  - type: command
    run: "npm run typecheck"
    expect: exit_code 0
  - type: file-contains
    path: src/path/to/file.ts
    pattern: "expected pattern"

pr:
  branch: feature/branch-name
  base: main
  title: "feat: description"

Oracle for Complex Planning

For complex tasks (5+ specs, unclear dependencies, architecture decisions), the planner invokes Oracle:

npx -y @steipete/oracle \
  --engine browser \
  --model gpt-5.2-codex \
  -p "$(cat /tmp/oracle-prompt.txt)" \
  --file "src/**"

Oracle takes 10-60 minutes and outputs plan.md. The planner transforms this into spec YAMLs.

Parallel Execution

Multiple planning sessions can run simultaneously:

Terminal 1: /plan auth system
Terminal 2: /plan payment system
Terminal 3: /plan notification system

Each spawns its own orchestrator and weavers. All run in parallel.