# 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.

| Agent | Model | Cognitive Mode | Capabilities |
|-------|-------|---------------|--------------|
| **str--strategist** (Lead) | Opus | Long-term, systemic, patterns | Systems thinking, scenario planning, leverage points, phase transitions |
| **str--critic** | Opus | Adversarial, risk-finding, bias | Pre-mortem analysis, bias detection, quantified risk, structured disagreement |
| **str--researcher** | Opus | Evidence-gathering, synthesis | Deep synthesis, adversarial research, predictive intelligence, parallel search |
| **str--synthesizer** | Opus | Integration, resolution, clarity | Multi-round deliberation, tension resolution, emergent insights |

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

### Implementation Guild (imp--) — Building Features

Full-stack architecture and implementation.

| Agent | Model | Focus | Capabilities |
|-------|-------|-------|--------------|
| **imp--architect** (Lead) | Opus | Technical feasibility, architecture | Technology radar, proof-of-concept, scalability modeling, TCO analysis |
| **imp--ui-designer** | Opus | UI/UX, components, accessibility | User psychology, design systems, Tailwind/Shadcn, motion design, anti-generic design rules, shadcn mastery, Design Interrogation Protocol. **MANDATORY for all FEATURE requests with UI** (not just "UI" type). Participates in Wisdom Council as design voice and runs Design Validation (Phase 5.5) in /plan. |
| **imp--reviewer** | Opus | Code quality, patterns | Architectural review, system impact analysis, refactoring strategies |
| **imp--api-integrator** | Opus | External API integration | Google APIs, AI APIs, OAuth, webhooks, rate limiting, API client design |

**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.

| Agent | Model | Cognitive Mode | Capabilities |
|-------|-------|---------------|--------------|
| **qa--test-architect** (Lead) | Opus | Test strategy, coverage planning | Test pattern discovery, coverage matrix, TDD planning |
| **qa--happy-path** | Opus | "Does it work correctly?" | Valid inputs, default states, user flows, integration paths |
| **qa--chaos-tester** | Opus | "How can I break it?" | Input attacks, timing attacks, state attacks, error cascades, security |
| **qa--visual-checker** | Opus | "Does it look right?" | Playwright MCP, exhaustive scan, screenshot evidence, responsive testing |
| **qa--ux-reviewer** | Opus | "Is the UX quality high?" | Design taste, flow coherence, performance feel, spec compliance, accessibility |

**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.

| Agent | Model | Focus | Capabilities |
|-------|-------|-------|--------------|
| **data--architect** (Lead) | Opus | Data strategy, pipeline design | Quality frameworks, pipeline architecture, schema governance |
| **data--schema-finder** | Opus | Schema discovery, drift detection | Infer types from messy data, detect column changes, confidence scoring |
| **data--cleaner** | Opus | Transform, normalize, validate | Data cleaning recipes, validation rules, quality reporting |
| **data--pipeline-builder** | Opus | dbt, ETL, workflows | Pipeline code generation, incremental loading, orchestration |

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

### Research Guild (res--) — Parallel Knowledge Gathering

Comprehensive research with confidence-based stopping.

| Agent | Model | Focus | Capabilities |
|-------|-------|-------|--------------|
| **res--lead** (Lead) | Opus | Research orchestration | Campaign protocol, confidence scoring, multi-round research |
| **res--query-generator** | Opus | Search query creation | Diverse query sets, gap detection, coverage matrix |
| **res--evidence-scorer** | Opus | Source weighting, confidence | Credibility scoring, bias detection, conflict resolution |
| **res--codebase-explorer** | Opus | Internal code research | Pattern recognition, file mapping, integration points |

**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--)

| Agent | Model | Purpose | Capabilities |
|-------|-------|---------|--------------|
| **x--project-lead** | Opus | Project-wide alignment and oversight | PROJECT.md ownership, cross-feature consistency, architecture decision tracking, institutional memory |
| **x--orchestrator** | Opus | Feature orchestration across guilds | Guild coordination, parallel work streams, quality gates |
| **x--ralph** | Opus | Execution planning with nano-tasks | Task decomposition, dependency graphs, agent consultation auto-population |
| **x--debugger** | Opus | Root cause analysis when things fail | Causal chain reconstruction, hypothesis trees, predictive prevention |

**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

| Workflow | Method | Why |
|----------|--------|-----|
| Project Alignment | **Subagent** | Focused analysis against PROJECT.md |
| Wisdom Council | **Agent Team** | Multi-round debate |
| QA Cognitive Diversity | **Agent Team** | Cross-pollination of findings |
| Research Campaign | **Agent Team** | Parallel investigation with sharing |
| Bug Hypotheses | **Agent Team** | Adversarial hypothesis testing |
| Feature Orchestration | **Subagent** | Coordination, not debate |
| Code Review | **Subagent** | Focused analysis |
| Data Pipeline | **Subagents** | Sequential, not debatable |
| Ralph Execution | **Subagents** | Task execution is focused |
| Documentation | **Subagent** | Focused single-agent work |

---

## 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`

```markdown
# 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

| Task Type | before | after |
|-----------|--------|-------|
| UI Component | imp--ui-designer | qa--visual-checker |
| UX/Flow | imp--ui-designer | qa--ux-reviewer |
| API/Logic | imp--architect | imp--reviewer |
| Data Task | data--schema-finder | data--cleaner |
| Data Pipeline | data--architect | data--pipeline-builder |
| Test Writing | qa--test-architect | qa--chaos-tester |
| Bug Fix | x--debugger | qa--happy-path |
| Documentation | — | docs-maintainer |
| Research | str--researcher | str--synthesizer |
| Strategic Decision | str--strategist | str--synthesizer |

---

## Agent Roster (Complete Reference)

| # | Agent | Guild | Model | Specialty |
|---|-------|-------|-------|-----------|
| 1 | **str--strategist** | Strategy (Lead) | Opus | Long-term vision, system dynamics |
| 2 | **str--critic** | Strategy | Opus | Risk analysis, assumption testing |
| 3 | **str--researcher** | Strategy | Opus | Evidence gathering, parallel search |
| 4 | **str--synthesizer** | Strategy | Opus | Integration, resolution, clarity |
| 5 | **imp--architect** | Implementation (Lead) | Opus | Technical feasibility, architecture |
| 6 | **imp--ui-designer** | Implementation | Opus | UI/UX, components, accessibility |
| 7 | **imp--reviewer** | Implementation | Opus | Code quality, patterns |
| 8 | **imp--api-integrator** | Implementation | Opus | External APIs, Google, OAuth, webhooks |
| 9 | **qa--test-architect** | QA (Lead) | Opus | Test strategy, coverage planning |
| 10 | **qa--happy-path** | QA | Opus | Constructive testing, verification |
| 11 | **qa--chaos-tester** | QA | Opus | Adversarial testing, break things |
| 12 | **qa--visual-checker** | QA | Opus | UI verification, screenshots |
| 13 | **qa--ux-reviewer** | QA | Opus | UX quality, design taste, flow coherence |
| 14 | **data--architect** | Data Engineering (Lead) | Opus | Data strategy, pipeline design |
| 15 | **data--schema-finder** | Data Engineering | Opus | Schema discovery, drift detection |
| 16 | **data--cleaner** | Data Engineering | Opus | Transform, normalize, validate |
| 17 | **data--pipeline-builder** | Data Engineering | Opus | dbt, ETL, workflows |
| 18 | **res--lead** | Research (Lead) | Opus | Research orchestration, campaigns |
| 19 | **res--query-generator** | Research | Opus | Search query creation, gap finding |
| 20 | **res--evidence-scorer** | Research | Opus | Source weighting, confidence |
| 21 | **res--codebase-explorer** | Research | Opus | Internal code research |
| 22 | **x--project-lead** | Cross-Guild | Opus | Project-wide alignment, cross-feature oversight |
| 23 | **x--orchestrator** | Cross-Guild | Opus | Feature orchestration across guilds |
| 24 | **x--ralph** | Cross-Guild | Opus | Execution planning, nano-tasks |
| 25 | **x--debugger** | Cross-Guild | Opus | Root cause analysis, bug hunting |
| — | **docs-maintainer** | Support | Opus | Documentation, ADRs |

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

---

## File Ownership During Execution

### Project-Level Files (Persistent Across Features)

| File | Owner | Updated By | Purpose |
|------|-------|------------|---------|
| `PROJECT.md` | x--project-lead | x--project-lead after each feature | Living project document - vision, architecture, cross-feature rules |
| `CHANGELOG.md` | Ralph (post-execution) | Ralph after each run | Cumulative record of what was built, when, and why |
| `decisions/ADR-*.md` | Ralph (post-execution) | docs-maintainer | Architecture Decision Records - persistent decision history |

### Planning Phase (Interactive)

| File | Created By | Purpose |
|------|------------|---------|
| Alignment summary | /plan command | Shared understanding (in conversation) |

### Preparation Phase (/ralph command)

| File | Created By | Updated By | Purpose |
|------|------------|------------|---------|
| `PRD.md` | /ralph | Human only | Requirements document |
| `plan.md` | /ralph | Ralph (mark complete) | Task definitions |
| `activity.md` | /ralph | Ralph | Progress log |
| `PROMPT_build.md` | /ralph | Never (static) | Execution instructions |
| `feature-context.md` | x--orchestrator | All agents | Shared context |

### Execution Phase (Ralph Loop)

| File | Created By | Updated By | Truth Level |
|------|------------|------------|-------------|
| `event.jsonl` | Ralph | Ralph (append-only) | **LEVEL 1: Ultimate Truth** |
| `state.json` | Ralph | Ralph (derived) | LEVEL 2: Current State |
| `activity.md` | /ralph | Ralph (derived) | LEVEL 3: Human View |
| `feature-context.md` | Earlier | All agents (append) | Shared Context |

### 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