Skip to content

HOW-AGENTS-WORK.md

Latest commit

 

History

History
105 lines (85 loc) · 3.66 KB

HOW-AGENTS-WORK.md

File metadata and controls

105 lines (85 loc) · 3.66 KB

How Agents Work

What Are Agent Teams?

Claude Code's Agent Teams feature lets you run multiple AI agents in parallel, each in its own tmux pane. Each agent has:

  • Isolated context (200K tokens per agent)
  • Specialized tools (some agents are read-only, others can edit)
  • Message passing between agents
  • Visual monitoring via tmux split panes

Agent Roles

@planner (Read-Only)

Purpose: Analyze the full upgrade path before starting Tools: Read, Bash, Grep, Glob Output: upgrade/plan.md with complete roadmap

@scout (Read-Only)

Purpose: Scan for breaking patterns before each version upgrade Tools: Read, Grep, Glob Output: upgrade/reports/scout-v{N}.md with CLEAR or BLOCKED verdict

@upgrader (Read-Write)

Purpose: Execute ng update and apply version-specific fixes Tools: Read, Write, Edit, Bash Output: upgrade/logs/upgrader-v{N}.log Waits for: @scout CLEAR message

@builder (Read-Only + Bash)

Purpose: Build libraries then app, report results Tools: Bash, Read Output: upgrade/reports/build-v{N}.md Waits for: @upgrader UPGRADE_APPLIED message

@fixer (Read-Write)

Purpose: Fix build errors identified by @builder Tools: Read, Write, Edit, Bash, Grep, Glob Output: upgrade/logs/fixer.log Used by: @builder internally (up to 3 fix-build cycles)

@test-runner (Bash Only)

Purpose: Run unit tests and categorize results Tools: Bash, Read Output: upgrade/reports/tests-v{N}.md

@ui-tester (On-Demand, Browser)

Purpose: Playwright browser smoke tests Tools: Read, Bash, Playwright MCP Output: upgrade/reports/ui-smoke-v{N}.md + screenshots Trigger: Manual via /test-ui command

@verifier (Read-Only)

Purpose: Final GO/NO-GO decision Tools: Read, Bash Output: upgrade/reports/verdict-v{N}.md

Pipeline Flow

/upgrade-to 17
    │
    ├─ Spawn @scout with v17 target
    │   └─ Reads skill files, scans deps, writes report
    │       └─ Messages @upgrader: "CLEAR" or "BLOCKED"
    │
    ├─ @upgrader receives CLEAR
    │   └─ Runs ng update, applies fixes, writes log
    │       └─ Messages @builder: "UPGRADE_APPLIED"
    │
    ├─ @builder receives UPGRADE_APPLIED
    │   └─ Builds library → app
    │       ├─ If fails: calls @fixer → rebuild (up to 3x)
    │       └─ If passes: runs tests
    │           └─ Messages @main: "BUILD_PASSED" or "BUILD_FAILED"
    │
    └─ Main session receives result
        ├─ Runs @verifier for GO/NO-GO
        ├─ If GO: git commit, update state, /compact
        └─ If NO-GO: show reports, suggest /upgrade-fix

Message Passing

Agents communicate using Claude Code's SendMessage function:

SendMessage(to: "upgrader", message: { type: "scout_verdict", verdict: "CLEAR" })
SendMessage(to: "builder", message: { type: "upgrade_status", status: "APPLIED" })
SendMessage(to: "main", message: { type: "build_result", passed: true })

Context Isolation

Each agent runs in its own 200K token context, which means:

  • No shared memory — agents must communicate via messages
  • Independent tool access — each agent has its own tool permissions
  • Parallel execution — agents work simultaneously in tmux panes
  • Resource efficiency — main session stays clean while agents do heavy work

Model Selection

By default, agents use the sonnet model for cost efficiency:

  • Sonnet: Ideal for agents (grep, build, test — mostly mechanical work)
  • Opus: Used for main session orchestration (decision-making, planning)

This is configurable in the agent frontmatter's model field.