Agent Team Architecture

A comprehensive guide to how the 26 specialized agents work together as a high-performance team across 5 guilds.

Philosophy: Quality Maximized

This agent system is designed with quality as the primary objective. All 25 agents run on Opus for maximum reasoning capability.

• Deep reasoning and nuanced analysis across all agents
• Rich cross-agent collaboration via shared context files
• Sophisticated deliberation protocols

Cost is not a constraint. Excellence is the goal.

CRITICAL: How Agent Spawning Works

Technical Limitations:

• Most agents cannot spawn other agents
• 8 agents with Task tool CAN delegate to sub-agents (guild leads + coordinators):
  • x--project-lead, x--orchestrator, x--ralph, x--debugger
  • qa--test-architect, res--lead, res--codebase-explorer
  • imp--ui-designer
• Keep nesting shallow: max 1 level deep (main → agent → sub-agent)
• Agents CANNOT talk to each other directly (no peer-to-peer messaging)
• All communication flows through the caller (hub-and-spoke per level)
• Maximum 10 parallel agents per batch (hard limit), 5-6 recommended

Communication Pattern:

Main Claude (Hub)
     │
     ├─→ Agent A (returns findings)
     ├─→ Agent B [has Task tool] ──→ Sub-Agent (returns to B)
     └─→ Agent C (returns findings)
          │
          └─→ Main Claude synthesizes and passes context to next batch

Context Persistence: Use feature-context.md as shared living document that all agents read/write.

Guild Architecture (5 Guilds + Cross-Guild Support)

                         ┌─────────────────────────┐
                         │   MAIN CLAUDE CONTEXT   │
                         │    (You orchestrate)    │
                         └───────────┬─────────────┘
                                     │
        ┌────────────────────────────┼────────────────────────────┐
        │              │              │              │             │
        ▼              ▼              ▼              ▼             ▼
  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
  │ STRATEGY │  │IMPLEMENT │  │    QA    │  │   DATA   │  │ RESEARCH │
  │  GUILD   │  │  GUILD   │  │  GUILD   │  │ENGINEER  │  │  GUILD   │
  │  (str--) │  │  (imp--) │  │  (qa--)  │  │  GUILD   │  │  (res--) │
  │  4 agts  │  │  4 agts  │  │  5 agts  │  │ (data--) │  │  4 agts  │
  └──────────┘  └──────────┘  └──────────┘  │  4 agts  │  └──────────┘
                                            └──────────┘

                    ┌──────────────────────┐
                    │   CROSS-GUILD (x--)  │
                    │   3 agents + support │
                    └──────────────────────┘

Guild Details

Strategy Guild (str--) — Thinking & Decisions

Different cognitive modes for analyzing problems. All Opus for deep reasoning.

When to engage: Strategic decisions, risk assessment, research, multi-perspective analysis

Implementation Guild (imp--) — Building Features

Full-stack architecture and implementation.

When to engage: Feature implementation, architecture decisions, UI design, code review, API integration

QA Guild (qa--) — Cognitive Diversity in Testing

Four distinct testing mindsets plus a lead to catch different bug categories.

Cognitive Diversity Rationale:

Bug escapes when ALL testers ask: "Does the feature work?"

Better approach - 4 questions in parallel:
  1. qa--happy-path: "Does it work correctly with valid input?"
  2. qa--chaos-tester: "What inputs break it? What race conditions exist?"
  3. qa--visual-checker: "Does it render correctly across states?"
  4. qa--ux-reviewer: "Is the UX polished and coherent?"

When to engage: After implementation, test strategy planning, visual verification, UX quality review

Data Engineering Guild (data--) — Taming Dirty Data

Handles Google Sheets with dynamic columns, messy formats, schema drift.

When to engage: Google Sheets data, ETL pipelines, schema discovery, data quality

Research Guild (res--) — Parallel Knowledge Gathering

Comprehensive research with confidence-based stopping.

Parallel Search Protocol:

Round 1: 15-20 diverse queries → Execute batch → Score confidence
Round 2: Gap-targeted queries → Execute → Re-score (if < 85%)
Round 3: Final round (if still < 85%) → Synthesize
Max 3 rounds or 85% confidence → Done

When to engage: Research tasks, codebase exploration, best practices, technology evaluation

Cross-Guild Support (x--)

Support Agent: | docs-maintainer | Opus | Documentation (not guild-assigned) | ADR generation, knowledge gaps, learning materials |

Agent Teams (Experimental)

Agent Teams enable peer-to-peer communication between teammates, unlike subagents which only report back to their caller. Use Agent Teams when agents need to debate, challenge each other, or share findings in real-time.

Enabled via: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS in settings.json (already configured)

Limitations:

• Windows: in-process mode only (no split panes)
• One team per session
• Teammates cannot spawn their own teams
• Higher token cost than subagents

When to Use Each

Collaboration Protocols

Protocol 1: Parallel Analysis Fan-Out (Subagents)

When starting a new feature, engage multiple agents simultaneously:

Feature Request
      │
      ├─→ imp--architect (parallel): "Feasible?"
      ├─→ imp--ui-designer (parallel): "UI approach?"
      ├─→ str--critic (parallel): "What could go wrong?"
      └─→ str--researcher (parallel): "Best practices?"
              │
              ▼
      str--synthesizer integrates all inputs

When to use: Starting any non-trivial feature development Method: Subagents (independent analyses, no need for debate)

Protocol 2: Quality Pipeline — Agent Team (Cognitive Diversity)

Post-implementation verification using an Agent Team so testers can share findings:

Code Complete
      │
      ├─→ imp--reviewer + x--debugger (subagents - parallel review)
      │
      └─→ QA Diversity Agent Team:
           Teammate "Happy Path": "Does it work?"
           Teammate "Chaos Tester": "Can I break it?"
           Teammate "Visual Checker": "Does it look right?"
           Teammate "UX Reviewer": "Is the UX polished and coherent?"
           → Teammates share findings with each other
           → Lead produces unified quality report + ux-review.md
      │
      └─→ docs-maintainer (subagent - final documentation)

When to use: After any implementation is complete Method: Agent Team for QA testers (cross-pollination), subagents for review/docs

Protocol 3: Wisdom Council — Agent Team (Strategic Deliberation)

Multi-round deliberation using Agent Team for real debate:

Decision/Problem → Create Agent Team:
      │
      Teammate "Strategist": Vision & long-term implications
      Teammate "Critic": Risks & hidden assumptions
      Teammate "Researcher": Evidence & precedents
      Teammate "Designer" (when UI involved): UX quality, component strategy, visual direction
              │
      Round 1: Each investigates independently
      Round 2: Teammates challenge each other's findings
      Round 3: Final positions stated
              │
              ▼
      Lead (or str--synthesizer subagent): Integrated recommendation

When to use: Major architectural decisions, technology choices, strategic direction Method: Agent Team (debate produces better decisions than isolated analysis)

Protocol 4: Data Pipeline (Subagents — Sequential)

End-to-end data engineering:

Messy Data Source (Google Sheets)
      │
      ├─→ data--schema-finder: Discover actual schema
      │
      ├─→ data--cleaner: Transform and normalize
      │
      ├─→ data--pipeline-builder: Create ETL pipeline
      │
      └─→ data--architect: Review pipeline architecture

When to use: Google Sheets data loading, ETL, schema discovery Method: Subagents (sequential pipeline, each step feeds the next)

Protocol 5: Bug Investigation — Agent Team (Competing Hypotheses)

Systematic debugging where hypotheses compete:

Bug reported → Create Agent Team:
      │
      Teammate per hypothesis: Each tests a different theory
      → Teammates try to disprove each other's theories
      → Surviving hypothesis = likely root cause
              │
              ▼
      Fix → qa--happy-path verifies (subagent) → qa--chaos-tester attacks (subagent)

When to use: Bug reports with unclear root cause, intermittent failures Method: Agent Team for investigation (adversarial), subagents for verification

Protocol 6: Project Alignment Validation (Post-Council)

After Wisdom Council deliberation:
      │
      ▼
x--project-lead reads PROJECT.md + recent retros + CHANGELOG.md
      │
      ▼
Validates Council recommendation against project-wide constraints:
  - Active constraints all features must follow
  - Relevant prior decisions
  - Potential conflicts with the recommended approach
  - Technical debt that might interact
  - Reuse opportunities being missed
      │
      ▼
Flags BLOCKER/WARNING/NOTE conflicts before design work begins

When to use: After Wisdom Council deliberation, BEFORE design validation Method: Subagent (focused analysis, not debate) Why post-Council: Creative exploration should happen unconstrained. Project constraints are checked AFTER to avoid biasing the solution space.

Protocol 7: Feature Development Flow (End-to-End Hybrid)

1. User describes feature
         │
         ▼
2. x--orchestrator gathers requirements (subagent)
         │
         ▼
3. PARALLEL ANALYSIS (subagents) - UNCONSTRAINED
   ├─→ imp--architect: Feasibility
   ├─→ imp--ui-designer: Design
   ├─→ str--critic: Risks
   └─→ str--researcher: Best practices
         │
         ▼
4. str--synthesizer integrates all input (subagent)
         │
         ▼
4.5. x--project-lead: Validate recommendation against PROJECT.md (subagent)
     → Flags BLOCKER/WARNING/NOTE conflicts
     → Creative exploration happened first, validation second
         │
         ▼
5. x--ralph creates execution plan (subagent)
         │
         ▼
6. Ralph executes (with MANDATORY agent consultation via subagents)
         │
         ▼
7. QUALITY PIPELINE (Agent Team for QA, subagents for review/docs)
   ├─→ imp--reviewer + x--debugger (subagents - parallel)
   ├─→ QA Diversity Agent Team (happy-path + chaos-tester + visual-checker + ux-reviewer)
   └─→ docs-maintainer (subagent)

Shared Context Protocol

Every feature gets a living document: feature-context.md

# Feature Context: [Feature Name]

## Status
Current phase: [Analysis | Design | Implementation | QA]
Last updated: [timestamp]
Last agent: [agent name]

## Discoveries (Append-Only)
### [agent-name] ([timestamp])
- Finding 1
- Finding 2

## Decisions Made
| Decision | Rationale | Agent | Date |

## Open Questions
- [ ] Question 1 (raised by agent-x)

## Blockers
None currently

Rules:

1. Every agent READS feature-context.md at start
2. Every agent APPENDS findings to Discoveries
3. Every agent ADDS open questions
4. Every agent UPDATES Status section

Ralph Integration

Planning Phase

x--ralph creates:
  - PRD.md (requirements)
  - plan.md (task DAG with agent_consultation)
  - activity.md (progress log)
  - PROMPT_build.md (execution instructions)

Execution Phase (MANDATORY Agent Consultation)

For each task in plan.md:
  1. Read agent_consultation.before → Spawn if set
  2. Execute task
  3. If uncertain → Spawn agent_consultation.during.agent
  4. Read agent_consultation.after → Spawn for review
  5. Only mark complete AFTER feedback incorporated

Default Agent Consultation by Task Type

Agent Roster (Complete Reference)

Model Distribution: 26 Opus = 26 agents (all Opus, quality maximized)

File Ownership During Execution

Project-Level Files (Persistent Across Features)

Planning Phase (Interactive)

Preparation Phase (/ralph command)

Execution Phase (Ralph Loop)

Key Insight

"Ralph" is not a separate agent file. Ralph = Claude Code + PROMPT_build.md instructions, invoked via the /ralph-loop:ralph-loop terminal command.

When agents are consulted during Ralph execution (via agent_consultation in task spec), Ralph uses the Task tool to invoke them.

Summary

1. 5 guilds + cross-guild support — Strategy, Implementation, QA, Data Engineering, Research
2. 26 agents with clear guild assignment and naming convention ({guild}--{name})
3. All Opus — Every agent runs on Opus for maximum quality
4. Hybrid orchestration — Subagents for focused tasks, Agent Teams for debate workflows
5. Project-level oversight — x--project-lead maintains PROJECT.md and ensures cross-feature alignment
6. Shared context files — feature-context.md persists context across agent batches
7. Persistent project memory — PROJECT.md, CHANGELOG.md, and decisions/ folder survive across feature cycles
8. Cognitive diversity in QA — 4 distinct testing mindsets (happy-path, chaos, visual, UX) via Agent Team
9. Mandatory agent consultation — Ralph execution includes before/during/after agent spawning
10. Parallel execution — Multiple agents work simultaneously (max 10, recommend 5-6)
11. Shallow nesting — 8 guild leads/coordinators can delegate via Task tool (max 1 level deep)
12. Agent Teams for debate — Wisdom Council, QA Pipeline, Research, and Bug Investigation use peer-to-peer teams
13. UX quality gate — qa--ux-reviewer evaluates design taste, flow coherence, and spec compliance post-implementation
14. Post-execution documentation — CHANGELOG.md and ADRs generated after every Ralph run