8. Workflow Orchestration

The Complete Pipeline

For maximum efficiency, chain tools in this order:

┌─────────────────────────────────────────────────────────────────────┐
│                        PLANNING PHASE                                │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  [PERPLEXITY]              [GEMINI]              [NOTEBOOKLM]       │
│  Deep Research             Diagram Analysis       Doc Synthesis      │
│  "Best practices for..."   Upload architecture   Upload all docs     │
│       ↓                         ↓                      ↓             │
│  spec.md                   mermaid + plan        audio overview      │
│                                                                      │
└────────────────────────────────┬────────────────────────────────────┘
                                 ↓
┌─────────────────────────────────────────────────────────────────────┐
│                      IMPLEMENTATION PHASE                            │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  [CLAUDE CODE]                          [IDE + COPILOT]             │
│  Multi-file implementation              Inline autocomplete          │
│  "Implement per spec.md..."             Quick edits while typing    │
│       ↓                                       ↓                      │
│  Working code + tests                   Polished code               │
│                                                                      │
└────────────────────────────────┬────────────────────────────────────┘
                                 ↓
┌─────────────────────────────────────────────────────────────────────┐
│                       DELIVERY PHASE                                 │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  [CLAUDE CODE]                          [KIMI]                       │
│  PR description                         Stakeholder deck             │
│  /release-notes                         "Create slides from..."     │
│       ↓                                       ↓                      │
│  GitHub PR                              presentation.pptx           │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Session Templates

Research-Heavy Feature

# 1. Research (Perplexity - 10 min)
# "Best practices for WebSocket implementation in Next.js 15"
# → Export to websocket-spec.md

# 2. Implementation (Claude Code - 40 min)
claude
> "Implement WebSocket following websocket-spec.md.
   Add to src/lib/websocket/. Include reconnection logic."

# 3. Stakeholder update (Kimi - 5 min)
# Upload: changes + demo screenshots
# → Generate 5-slide update deck

Visual-Heavy Feature

# 1. UI Prototype (v0 - 10 min)
# Generate dashboard layout

# 2. Visual refinement (Gemini - 5 min)
# Upload Figma polish → Get final code

# 3. Integration (Claude Code - 30 min)
claude
> "Integrate this dashboard component.
   Connect to our data fetching hooks.
   Add proper TypeScript types."

Onboarding New Codebase

# 1. Audio overview (NotebookLM - 15 min)
# Upload all docs → Generate audio → Listen

# 2. Deep questions (Claude Code - 20 min)
claude
> "I just listened to an overview of this codebase.
   Help me understand the payment flow in detail."

# 3. First contribution (Claude Code - 30 min)
claude
> "Add a new endpoint to the payments API.
   Follow the patterns I see in existing endpoints."

---

8.1 Multi-Agent Orchestration Systems

When scaling beyond single Claude Code sessions, external orchestration systems coordinate multiple concurrent agents.

Overview

System	Purpose	Backend	Maturity	Monitoring
Gas Town	Multi-agent workspace manager	Claude Code instances	Experimental	agent-chat (SSE + SQLite)
agent-chat	Real-time monitoring UI	N/A (reads logs)	Early (v0.2.0)	Dashboard

Gas Town (Steve Yegge)

What it is: Orchestrator managing dozens of Claude Code instances with Mad Max-inspired roles:

• Mayor: Central coordinator, generates work, delegates tasks
• Polecats: Ephemeral worker jobs performing coding tasks
• Witness: Supervises workers, helps when stuck
• Refinery: Manages merge queue, resolves conflicts

Key points:

• ✅ Unlocks multi-agent orchestration for Claude Code
• ⚠️ Extremely expensive (creator needed 2nd Anthropic account for spending limits)
• ❌ Experimental, not production-grade
• 🔗 GitHub repo

When to use: Complex, high-level tasks requiring parallel agent work (not granular tasks)

multiclaude (dlorenc)

What it is: Self-hosted system spawning autonomous Claude Code agents:

• Each agent: separate tmux window + git worktree + branch
• Auto-creates PRs, CI = ratchet (passing PRs auto-merge)
• Agent types: worker, supervisor, merge-queue, PR shepherd, reviewer

Key points:

• ✅ Self-hosting since day one (multiclaude builds itself)
• ✅ Extensible via Markdown agent definitions
• ✅ Public Go packages: pkg/tmux, pkg/claude
• 🔗 GitHub repo

When to use: Teams wanting full control over agent orchestration, on-prem/airgap environments

agent-chat (Justin Abrahms)

What it is: Real-time monitoring UI (Slack-like) for agent communications:

• Reads Gas Town's beads.db (SQLite) and multiclaude's JSON message files
• SSE for live updates, workspace channels, unread indicators
• Zero-config defaults, dark theme

Key points:

• ✅ Unified view across multiple orchestration systems
• ⚠️ Very new (48h old, v0.2.0)
• ⚠️ Not compatible with standalone Claude Code (needs Gas Town/multiclaude)
• 🔗 GitHub repo

Architecture pattern (transposable to Claude Code):

1. Hook logs Task agent spawns → SQLite
2. Parent/child relationships tracked
3. SSE endpoint streams updates
4. Dashboard UI consumes stream

See: guide/ops/observability.md for native Claude Code session monitoring

Entire CLI: Governance-First Orchestration

What it is: Agent-native platform focused on governance + sequential handoffs vs pure parallel coordination.

Launched: February 2026 by Thomas Dohmke (ex-CEO GitHub), $60M funding

Architecture difference:

Aspect	Gas Town / multiclaude	Entire CLI
Paradigm	Coordination (tmux multiplexing)	Governance (approval gates)
Agent spawning	Manual (tmux/worktrees)	Automatic (handoff protocol)
Parallelization	Yes (5+ agents)	No (sequential handoffs)
Context preservation	Manual (shared files)	Automatic (checkpoints)
Audit trail	None	Built-in (compliance-ready)
Rewind	No	Yes (restore to checkpoints)

Key points:

• ✅ Full audit trail: prompts → reasoning → outputs (SOC2, HIPAA compliance)
• ✅ Agent handoffs with context (Claude → Gemini → Claude)
• ✅ Approval gates before deploy (human-in-loop)
• ⚠️ No parallel execution (sequential only)
• ⚠️ Very new (launched Feb 10-12, 2026) - limited production feedback
• 🔗 GitHub repo / entire.io

Agent handoff flow (how context actually passes between agents):

Claude Code                    Gemini CLI                   Entire
-----------                    ----------                   ------

works on feature
"blocked on X,
 delegate to Gemini" ---------> hook PreToolUse[Task]
                                (captures the handoff)
                                                   |
                                receives full       |
                                context:            |
                                - reasoning trace   |
                                - files touched     |
                                - decisions made    |
                                - rejected approaches|
                                                    |
                                works...            |
                                completes           |
                                                    v
                                               hook PostToolUse[Task]
                                               (captures result)

Result: each agent in the chain sees the reasoning of previous agents.
No "cold start" — full context preserved across agent switches.

When to use Entire CLI:

# Use Case 1: Compliance-critical workflows
entire capture --agent="claude-code" --require-approval="security-team"
[... Claude makes changes ...]
# Changes blocked until security-team approves via: entire approve

# Use Case 2: Sequential agent handoff (Claude → Gemini)
entire capture --agent="claude-code" --task="architecture"
[... Claude designs system ...]
entire handoff --to="gemini" --task="visual-design"
# Gemini receives full context from Claude's session

# Use Case 3: Debugging with rewind
entire log  # See all decision checkpoints
entire rewind --to="before-refactor"  # Restore exact state

Complementarity matrix:

Use Case	Best Tool
Parallel features (5+ agents)	Gas Town
Visual monitoring	agent-chat
macOS parallel with GUI	Conductor
Sequential handoffs + governance	Entire CLI
Single agent + cost tracking	Native Claude Code + ccusage

Practical workflow (hybrid approach):

# 1. Use Gas Town for parallel feature work
gastown spawn --agents=5 --tasks="auth, tests, docs, refactor, deploy"

# 2. Use Entire for sequential refinement with governance
entire capture --agent="claude-code"
[... implement critical feature ...]
entire checkpoint --name="feature-complete"
entire handoff --to="gemini" --task="ui-polish" --require-approval

Status: Production v1.0+ (macOS/Linux, Windows via WSL)

Full docs: AI Traceability Guide, Third-Party Tools

Security & Cost Warnings

Before using external orchestrators:

Risk	Mitigation
Cost explosion	Set Anthropic spending limits, use Haiku for workers
Lost work	"Vibe coding" accepts work loss for throughput - have rollback plan
Experimental status	Not for production critical paths, test in staging first
Context leakage	Logs may contain sensitive data - review before enabling monitoring UI

Integration with Native Claude Code

If you're not using Gas Town/multiclaude, you can still:

1. Log multi-instance sessions via hooks (see examples/hooks/session-logger.sh)
2. Track --delegate operations with custom hook logging Task agent spawns
3. Build lightweight dashboard using SSE pattern from agent-chat

Conceptual architecture:

# Hook: .claude/hooks/multi-agent-logger.sh
# Triggered on PostToolUse when tool="Task"
# Logs: timestamp, parent_session_id, child_agent_id, task_description

# Dashboard: Simple Go HTTP server streaming logs via SSE
# UI: React/HTML consuming SSE stream

When NOT to Use Orchestrators

Use single Claude Code session when:

• Task is ❤️ steps or affects <5 files
• You need full control/oversight of every change
• Budget constraints prevent multi-agent costs
• Codebase is simple enough for sequential work

Use orchestrators when:

• Task naturally parallelizes (multiple independent features)
• You have budget for parallel agents (multiply costs by N agents)
• Experimentation tolerance is high (work may be lost/redone)
• Team has SRE capacity to monitor/intervene

8.2 Domain-Specific Agent Frameworks

Beyond general-purpose coding assistants, specialized frameworks target specific use cases with built-in context, evaluation, and deployment patterns.

nao (Analytics Agents)

URL: github.com/getnao/nao | Stack: TypeScript 58.9%, Python 38.5%

What it is: Open-source framework for building and deploying analytics agents. Two-step architecture: build agent context via CLI (databases, docs, metadata) → deploy chat UI for natural language data queries.

Key features:

• Database agnostic (PostgreSQL, BigQuery, Snowflake, Databricks)
• Built-in evaluation framework with unit testing
• Native data visualization in chat interface
• Self-hosted deployment with Docker
• Stack: Fastify, Drizzle ORM, tRPC, React, shadcn UI

Relevance to Claude Code: While nao deploys agents as standalone services (not Claude Code plugins), its patterns are transposable:

• Context builder architecture: Structuring complex agent context (similar to .claude/agents/ best practices)
• Evaluation framework: Measuring agent quality through metrics, unit tests, and feedback loops (gap in current Claude Code workflows)
• Database integrations: Patterns for injecting database context into agent prompts

When to use: Data teams building conversational analytics interfaces for business users. For Claude Code users, nao serves as reference architecture for agent evaluation and database context patterns.

Status: Active open-source project, production-ready, well-documented