Module 8: Project — Complete Multi-Agent System
1. Introduction and Architecture — Complete Multi-Agent System
1. Introduction and Architecture — Complete Multi-Agent System
Description
This is the final module. It's not just another module — it's the integration of everything you built in the 7 previous modules. Custom subagents, memory scopes, parallel delegation, Agent Teams, plugins, hooks, headless SDK, remote control, CLAUDE.md. Every piece you learned exists to get to this point: a functional multi-agent system where 5 agents work in coordination on a real project.
You're not going to learn new concepts. You're going to combine concepts you already master into a system that is greater than the sum of its parts. The team lead coordinates. The frontend-agent and the backend-agent implement in parallel. The testing-agent validates each delivery. The docs-agent reviews quality and documents. The hooks act as automatic quality gates. The SDK monitors progress. Remote control approves critical operations. CLAUDE.md sets the rules of the game. And everything works without you being glued to the terminal.
This module has a clear objective: that you finish with a system you can adapt to your real projects. It's not an academic exercise — it's a professional multi-agent orchestration template.
Where Are We in the Guide?
Context in the Guide
This guide has 8 modules organized into 3 phases:
Phase 1: Advanced Subagents (Modules 1-3) ← COMPLETED
├── Module 1: Custom Subagents ✅
├── Module 2: Agent Memory and Scopes ✅
└── Module 3: Parallel Sub-Agent Delegation ✅
Phase 2: Agent Teams and Plugins (Modules 4-6) ← COMPLETED
├── Module 4: Agent Teams ✅
├── Module 5: Plugins: Create and Distribute ✅
└── Module 6: Advanced Hooks and Headless SDK ✅
Phase 3: Orchestration (Modules 7-8)
├── Module 7: Remote Control and CLAUDE.md for Teams ✅
└── Module 8: Project: Complete Multi-Agent System ← YOU ARE HERE
Total estimated duration: 8-10 hours (self-paced).
Closing the arc
Each module gave you a piece. Now you see the complete puzzle:
| Module | Piece | Role in the Final System |
|---|---|---|
| M1: Custom Subagents | Identity of each agent | Each agent has a specific role, restrictions, and tools |
| M2: Agent Memory | Shared knowledge | Agents share project context via memory scopes |
| M3: Parallel Delegation | Simultaneous work | Frontend and backend work in parallel |
| M4: Agent Teams | Formal coordination | Team lead manages task board, dependencies, conflicts |
| M5: Plugins | Packaging | The configuration of the 5 agents is packaged as a plugin |
| M6: Hooks + SDK | Automation | Hooks validate each delivery, SDK monitors progress |
| M7: Remote Control + CLAUDE.md | Governance | CLAUDE.md as constitution, remote control for approvals |
The System Architecture
Overview
┌─────────────────────────────────────────────────────────────┐
│ CLAUDE.md (M7) │
│ Team constitution │
│ Conventions · Boundaries · Quality standards │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ TEAM LEAD (M4) │ │
│ │ Coordinates · Assigns · Resolves · Reports │ │
│ │ Tools: Agent(frontend), Agent(backend), │ │
│ │ Agent(testing), Agent(docs-review) │ │
│ └───────┬──────────┬──────────┬──────────┬─────────────┘ │
│ │ │ │ │ │
│ ┌─────▼────┐ ┌───▼────┐ ┌──▼───┐ ┌───▼──────┐ │
│ │ FRONTEND │ │BACKEND │ │TESTS │ │DOCS/ │ │
│ │ AGENT │ │ AGENT │ │AGENT │ │REVIEW │ │
│ │ (M1) │ │ (M1) │ │(M1) │ │AGENT(M1) │ │
│ │ │ │ │ │ │ │ │ │
│ │ UI/UX │ │API/DB │ │pytest│ │Quality │ │
│ │ React │ │FastAPI │ │Cover.│ │Docs │ │
│ └──────────┘ └────────┘ └──────┘ └──────────┘ │
│ │ │ │ │ │
│ ┌─────▼──────────▼──────────▼──────────▼─────────────┐ │
│ │ MEMORY SCOPES (M2) │ │
│ │ Project memory: shared context, decisions, types │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ PARALLEL DELEGATION (M3) │ │
│ │ Frontend + Backend simultaneously │ │
│ │ Testing waits for both │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────┐ ┌────────────────┐ ┌───────────────┐ │
│ │ HOOKS (M6) │ │ SDK (M6) │ │ REMOTE (M7) │ │
│ │ Quality gates │ │ Monitoring │ │ Approvals │ │
│ │ PreToolUse │ │ Python script │ │ Mobile ops │ │
│ │ PostToolUse │ │ Status polling │ │ Critical ops │ │
│ │ SubagentStop │ │ Reports │ │ │ │
│ └────────────────┘ └────────────────┘ └───────────────┘ │
│ │
├─────────────────────────────────────────────────────────────┤
│ PLUGIN (M5) │
│ Everything packaged: agents + hooks + CLAUDE.md + skills │
└─────────────────────────────────────────────────────────────┘
The 5 agents
1. Team Lead — The coordinator
- Doesn't write code. Ever.
- Analyzes the codebase, generates the task board, assigns tasks
- Manages dependencies: who waits for whom
- Forwards context between teammates
- Resolves conflicts when two agents produce contradictory results
- Produces the final consolidated report
2. Frontend Agent — The UI specialist
- Implements React components, pages, hooks, styles
- Territory:
src/components/,src/pages/,src/hooks/,src/styles/ - Consumes types published by the backend in
src/types/ - Produces components with loading, error, and empty states
3. Backend Agent — The API specialist
- Implements FastAPI endpoints, Pydantic schemas, business logic
- Territory:
src/api/,src/models/,src/services/ - Publishes shared types in
src/types/for the frontend to consume - Produces endpoints with validation, error handling, and documented schemas
4. Testing Agent — The validator
- Writes and runs tests for the code produced by frontend and backend
- Territory:
tests/ - Reads source code but never modifies it
- Reports coverage, failed tests, and regressions
- Activates after frontend and backend complete
5. Docs/Review Agent — The quality guardian
- Reviews the code of all the agents (read-only)
- Updates project documentation
- Write territory:
docs/ - Reads everything, modifies only documentation
- Produces quality reports: naming, patterns, consistency
Execution flow
1. START
Team lead receives feature request
Reads codebase (Glob, Read, Grep)
Generates task board with 8-10 tasks
Presents for approval
2. PARALLEL EXECUTION (Round 1)
Backend agent → schemas, shared types
Frontend agent → layout, skeleton components (don't depend on the backend)
3. PARALLEL EXECUTION (Round 2)
Backend agent → API endpoints
Frontend agent → components with data (depend on backend types)
4. TESTING
Testing agent waits for frontend + backend to complete
Runs tests
Reports coverage and failures
If there are failures → team lead reassigns the fix to the corresponding agent
5. REVIEW
Docs/Review agent reviews all the produced code
Generates a quality report
Updates documentation
6. QUALITY GATES (automatic hooks)
PostToolUse → automatic lint after each edit
SubagentStop → log of each agent that finishes
PreToolUse → blocking of dangerous operations
7. MONITORING (SDK)
Python script monitors progress
Generates an execution report
8. FINAL REPORT
Team lead consolidates results from all the agents
Produces a report with files, endpoints, components, tests, quality score
What You'll Build in This Module
Capsule by capsule
| # | Capsule | What you build |
|---|---|---|
| 01 | Introduction and Architecture (this one) | Mental model, architecture, execution plan |
| 02 | Team Configuration | 5 agent files, plugin, hooks, CLAUDE.md |
| 03 | Execution and Task Board | Task board, parallel execution, quality gates |
| 04 | Monitoring and Remote Control | SDK monitor, remote approvals, dashboarding |
| 05 | Retrospective and Optimization | Analysis, optimization, guide summary |
Final deliverables
When you finish the 5 capsules you'll have:
your-project/
├── .claude/
│ ├── agents/
│ │ ├── team-lead.md ← Coordinator (M4)
│ │ ├── frontend-agent.md ← UI specialist (M1)
│ │ ├── backend-agent.md ← API specialist (M1)
│ │ ├── testing-agent.md ← Validator (M1)
│ │ └── docs-review-agent.md ← Quality guardian (M1)
│ └── settings.json ← Configured hooks (M6)
├── scripts/
│ ├── hooks/
│ │ ├── post-edit-lint.sh ← Auto-lint hook (M6)
│ │ ├── pre-tool-validate.sh ← Validation hook (M6)
│ │ └── subagent-stop-log.sh ← Logging hook (M6)
│ └── monitor/
│ └── team-monitor.py ← SDK monitoring (M6)
├── multi-agent-plugin/
│ ├── package.json ← Plugin manifest (M5)
│ ├── agents/ ← Packaged agent files
│ └── skills/ ← Team skills
├── CLAUDE.md ← Team constitution (M7)
├── docs/
│ └── execution-report.md ← Report generated by docs-agent
└── src/
├── components/ ← Frontend territory
├── api/ ← Backend territory
├── types/ ← Shared (published by backend)
└── tests/ ← Testing territory
Why This System Is Not an Academic Exercise
Real production patterns
The system you build here implements patterns that exist in real development teams:
1. Separation of responsibilities Each agent has a defined territory. There's no overlap. It's the same principle as microservices, but applied to agents.
2. Coordination via task board The team lead doesn't execute — it coordinates. It's the pattern of a real tech lead: distributes work, manages dependencies, resolves blockers.
3. Automatic quality gates The hooks are the equivalent of CI checks: each change is validated automatically before being accepted.
4. Observability The SDK monitor is the equivalent of Datadog or Grafana for your agent system: you know what's happening, how long it takes, and where there are problems.
5. Governance CLAUDE.md is the equivalent of a coding standards document + architecture decisions record. Remote control is the equivalent of approval gates in a production pipeline.
Adaptation to your project
When you finish this module, you'll be able to:
- Change the agents — Replace frontend/backend with data-engineer/ml-engineer, or with mobile/web, or with whatever specialization your project needs
- Scale the team — Add a 6th agent (security-agent, performance-agent, i18n-agent) without changing the architecture
- Change the stack — The agent files are framework-agnostic. Change React for Vue, FastAPI for Django, pytest for jest — the structure is the same
- Package and distribute — The plugin you create here can be published to npm so your team uses the same configuration
Prerequisites
What you need to have ready
- ✅ Modules 1-7 completed — All the content of this guide
- ✅ A project with frontend + backend — React + FastAPI ideal, but any combo works
- ✅ Claude Code updated — Recent version with subagent support
- ✅ Python 3.10+ — For the monitoring script
- ✅ Node.js 18+ — For the plugin
- ✅ Git initialized — The project must be under version control
Quick check
claude --version
python3 --version
node --version
git status
ls src/You don't need
- ❌ Experience with multi-agent systems — This module guides you step by step
- ❌ A large project — 5-10 code files is enough
- ❌ Production infrastructure — Everything runs locally
Note on Experimental Features
⚠️ EXPERIMENTAL FEATURE
Agent Teams is an experimental feature of Claude Code. If it's not available in your version, each capsule includes a manual alternative using a coordinator subagent. Teammates work as standard subagents in both cases. Hooks and the headless SDK are stable features.
Last verified: March 2026
Mental Model: From Isolated Pieces to an Integrated System
Before this module
You have 7 tools that you know how to use individually:
Subagent ──→ You use it when you need to delegate a task
Memory ────→ You use it when you need to remember something between sessions
Parallel ──→ You use it when you want two things to happen at once
Teams ─────→ You use it when you want formal coordination
Plugin ────→ You use it when you want to package configurations
Hooks ─────→ You use it when you want to automate validations
SDK ───────→ You use it when you want to run Claude from scripts
Remote ────→ You use it when you want to approve things from your phone
CLAUDE.md ─→ You use it when you want to set standards
After this module
You have a system where all the pieces work together:
CLAUDE.md sets the rules
→ Which the plugin packages
→ Which the subagents follow
→ Coordinated by the team lead
→ Which delegates in parallel
→ And hooks validate each step
→ While the SDK monitors
→ And remote control approves the critical parts
→ All connected by memory scopes
The difference between "I know how to use 7 tools" and "I have a system of 7 integrated tools" is the difference between a musician who knows how to play notes and one who knows how to play a song.
Module Learning Flow
Progression
-
Configuration (Capsule 02) — You create the 5 agent files, the plugin that packages them, the hooks that validate, and the CLAUDE.md that governs. When you finish, everything is configured but not executed.
-
Execution (Capsule 03) — You design the task board, launch the team, observe the parallel execution, and see the quality gates in action. When you finish, the team has produced functional code.
-
Monitoring (Capsule 04) — You build the SDK script that monitors progress, configure remote control for approvals, and generate an execution dashboard. When you finish, you have observability of the system.
-
Retrospective (Capsule 05) — You analyze what worked, what didn't, where there were conflicts, and how to optimize. It includes the complete guide summary and the connection to guides #10 and #11.
The progression is: configure → execute → observe → analyze.
Estimated module duration: 1.5-2 hours.
Connection to the Path
In the guide
This is the last module of Guide #9 (Advanced Claude Code Workflows). It closes the arc that began with "how do I create a custom subagent" and ends with "I have a complete multi-agent system."
In the path
Guide #9 is part of the Claude Code Agentic Development Path:
Guide #8: Intermediate Workflows (prerequisite)
Guide #9: Advanced Claude Code Workflows ← THIS GUIDE
Guide #10: Claude Code in CI/CD Pipelines (next)
Guide #11: Security Deep Dive
What you build here connects directly with:
- Guide #10 (CI/CD) — The SDK monitor integrates into GitHub Actions. The hooks become CI checks. The plugin is published to real npm
- Guide #11 (Security) — The PreToolUse hooks are extended with security validations. CLAUDE.md includes security policies. The agent boundaries are audited
Summary
- This module integrates all the concepts from Modules 1-7 into a functional multi-agent system
- The architecture has 5 agents: team lead (coordinator), frontend-agent, backend-agent, testing-agent, and docs/review-agent
- Each previous module contributes a piece: subagents (M1) as the base, memory (M2) for shared context, parallel (M3) for simultaneous work, teams (M4) for coordination, plugins (M5) for packaging, hooks+SDK (M6) for automation and monitoring, remote+CLAUDE.md (M7) for governance
- The execution flow is: task board → parallel execution → testing → review → quality gates → monitoring → report
- It's not an academic exercise — it's a professional template adaptable to real projects
- The module progresses: configure → execute → observe → analyze
- The system implements production patterns: separation of responsibilities, coordination via task board, automatic quality gates, observability, and governance
- Estimated duration: 1.5-2 hours
- Connects with Guide #10 (CI/CD Pipelines) and Guide #11 (Security Deep Dive)
Additional Resources
- Create Custom Subagents (Anthropic Docs) — Official documentation of agent files and frontmatter
- Claude Code Hooks — SessionStart, PreToolUse, PostToolUse, SubagentStop hooks
- Claude Code CLI Reference — Flags
-p,--output-format,--agent - Claude Code Settings — Configuring hooks in settings.json
- Claude Code Best Practices — Best practices for delegation and automation
- Multi-Agent Orchestration (Anthropic) — Multi-agent orchestration patterns
- Claude Code Overview — General context of Claude Code as a platform
- Prompt Engineering: System Prompts — System prompt techniques for specialized agents
Next capsule: In capsule 02 you'll create the 5 complete agent files with their specialized system prompts, the plugin that packages them, the quality gate hooks, and the CLAUDE.md that governs the team. When you finish, you'll have everything configured and ready to execute.