# aws-samples/sample-claude-code-agent-team architecture

> Architecture diagram of the GitHub repository aws-samples/sample-claude-code-agent-team, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aws-samples/sample-claude-code-agent-team
- Repository: https://github.com/aws-samples/sample-claude-code-agent-team

## Overview

This repository is a Claude Code configuration sample, not an application runtime. Its main workflow has the lead agent research and specify work, delegate tasks to parallel coding and DevOps workers, then run scoped reviews and fixes through end-to-end review. Agent prompts, workflow skills and rules provide guidance; hooks enforce task-format, completion-verification and idle-work guardrails. The README documents the broader workflow, while source excerpts confirm hook behavior and helper calls; unsampled agent and skill internals are not assumed.

Main entry points: [`agents/fullstack-agent.md`](https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/agents/fullstack-agent.md) (Full-stack lead), [`agents/coding-agent.md`](https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/agents/coding-agent.md) (Coding agent), [`agents/devops-agent.md`](https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/agents/devops-agent.md) (DevOps agent), [`rules/testing-standards.md`](https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/rules/testing-standards.md) (Testing standards)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Agent roles"]
  node_lead["Full-stack lead<br/>[fullstack-agent.md]"]
  node_coding["Coding agent<br/>[coding-agent.md]"]
  node_devops["DevOps agent<br/>[devops-agent.md]"]
  node_review["Review agent<br/>[review-agent.md]"]
  node_reviewlite["Review-lite agent"]
  node_sa["Solutions architect<br/>[sa-agent.md]"]
end

subgraph group_workflow["Workflow guidance"]
  node_specskill["Spec workflow<br/>[SKILL.md]"]
  node_protocol["Team protocol"]
  node_testing["Testing standards"]
  node_docs_skill["Documentation skill<br/>[SKILL.md]"]
  node_git_skill["Git workflow<br/>[SKILL.md]"]
end

subgraph group_guardrails["Hook enforcement"]
  node_format_hook["Task format gate"]
  node_completion_hook["Completion verify gate"]
  node_idle_hook["Idle work check"]
  node_hook_common["Hook common helpers"]
end

subgraph group_capabilities["Supporting capabilities"]
  node_cached_fetch["Cached fetch skill<br/>[SKILL.md]"]
  node_brainstorm["Brainstorm command<br/>[brainstorm.md]"]
  node_optimize["Configuration optimizer"]
  node_aws_rules["AWS security guidance"]
  node_settings["Claude settings<br/>[settings.json]"]
end

node_user(("Project user"))

node_user -->|"requests work"| node_lead
node_lead -->|"plans with"| node_specskill
node_lead -->|"delegates build"| node_coding
node_lead -->|"delegates build"| node_devops
node_lead -->|"assigns review"| node_review
node_lead -->|"assigns narrow review"| node_reviewlite
node_lead -.->|"requests architecture review"| node_sa
node_coding -->|"follows team protocol"| node_protocol
node_devops -->|"follows team protocol"| node_protocol
node_review -->|"checks test tiers"| node_testing
node_coding -->|"owns T1 T2"| node_testing
node_devops -->|"owns T3 wiring"| node_testing
node_lead -->|"plans coverage"| node_testing
node_review -.->|"uses guidance"| node_docs_skill
node_coding -.->|"uses guidance"| node_git_skill
node_format_hook -->|"imports helpers"| node_hook_common
node_completion_hook -->|"imports helpers"| node_hook_common
node_idle_hook -->|"imports helpers"| node_hook_common
node_format_hook -.->|"blocks malformed task"| node_user
node_completion_hook -.->|"blocks unverified completion"| node_user
node_idle_hook -.->|"nudges claimable work"| node_user
node_lead -.->|"can invoke"| node_brainstorm
node_lead -.->|"can invoke"| node_optimize
node_devops -.->|"uses security guidance"| node_aws_rules
node_settings -.->|"configures hook"| node_format_hook
node_settings -.->|"configures hook"| node_completion_hook
node_settings -.->|"configures hook"| node_idle_hook
node_coding -.->|"can use skill"| node_cached_fetch

click node_lead "https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/agents/fullstack-agent.md"
click node_coding "https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/agents/coding-agent.md"
click node_devops "https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/agents/devops-agent.md"
click node_review "https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/agents/review-agent.md"
click node_reviewlite "https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/agents/review-lite-agent.md"
click node_sa "https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/agents/sa-agent.md"
click node_specskill "https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/skills/spec-workflow/SKILL.md"
click node_protocol "https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/rules/agent-team-protocol.md"
click node_testing "https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/rules/testing-standards.md"
click node_docs_skill "https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/skills/documentation/SKILL.md"
click node_git_skill "https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/skills/git-workflow/SKILL.md"
click node_format_hook "https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/hooks/task_created_format_check.py"
click node_completion_hook "https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/hooks/task_completed_verify_gate.py"
click node_idle_hook "https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/hooks/teammate_idle_workcheck.py"
click node_hook_common "https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/hooks/team_hook_common.py"
click node_cached_fetch "https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/skills/concurrent-cached-fetch/SKILL.md"
click node_brainstorm "https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/commands/brainstorm.md"
click node_optimize "https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/commands/optimize-my-claude.md"
click node_aws_rules "https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/rules/AWS-security-guidelines.md"
click node_settings "https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/settings.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_lead,node_coding,node_devops,node_review,node_reviewlite,node_sa,node_user toneBlue
class node_specskill,node_protocol,node_testing,node_docs_skill,node_git_skill toneAmber
class node_format_hook,node_completion_hook,node_idle_hook,node_hook_common toneMint
class node_cached_fetch,node_brainstorm,node_optimize,node_aws_rules,node_settings toneRose
```

## Components

### Agent roles

- [Full-stack lead](https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/agents/fullstack-agent.md): `agents/fullstack-agent.md`
- [Coding agent](https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/agents/coding-agent.md): `agents/coding-agent.md`
- [DevOps agent](https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/agents/devops-agent.md): `agents/devops-agent.md`
- [Review agent](https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/agents/review-agent.md): `agents/review-agent.md`
- [Review-lite agent](https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/agents/review-lite-agent.md): `agents/review-lite-agent.md`
- [Solutions architect](https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/agents/sa-agent.md): `agents/sa-agent.md`

### Workflow guidance

- [Spec workflow](https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/skills/spec-workflow/SKILL.md): `skills/spec-workflow/SKILL.md`
- [Team protocol](https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/rules/agent-team-protocol.md): `rules/agent-team-protocol.md`
- [Testing standards](https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/rules/testing-standards.md): `rules/testing-standards.md`
- [Documentation skill](https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/skills/documentation/SKILL.md): `skills/documentation/SKILL.md`
- [Git workflow](https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/skills/git-workflow/SKILL.md): `skills/git-workflow/SKILL.md`

### Hook enforcement

- [Task format gate](https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/hooks/task_created_format_check.py): `hooks/task_created_format_check.py`
- [Completion verify gate](https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/hooks/task_completed_verify_gate.py): `hooks/task_completed_verify_gate.py`
- [Idle work check](https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/hooks/teammate_idle_workcheck.py): `hooks/teammate_idle_workcheck.py`
- [Hook common helpers](https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/hooks/team_hook_common.py): `hooks/team_hook_common.py`

### Supporting capabilities

- [Cached fetch skill](https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/skills/concurrent-cached-fetch/SKILL.md): `skills/concurrent-cached-fetch/SKILL.md`
- [Brainstorm command](https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/commands/brainstorm.md): `commands/brainstorm.md`
- [Configuration optimizer](https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/commands/optimize-my-claude.md): `commands/optimize-my-claude.md`
- [AWS security guidance](https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/rules/AWS-security-guidelines.md): `rules/AWS-security-guidelines.md`
- [Claude settings](https://github.com/aws-samples/sample-claude-code-agent-team/blob/main/settings.json): `settings.json`

### Other components

- **Project user**

## Connections

- Project user → Full-stack lead: requests work (evidence: `README.md`)
- Full-stack lead → Spec workflow: plans with (evidence: `README.md`)
- Full-stack lead → Coding agent: delegates build (evidence: `README.md`)
- Full-stack lead → DevOps agent: delegates build (evidence: `README.md`)
- Full-stack lead → Review agent: assigns review (evidence: `README.md`)
- Full-stack lead → Review-lite agent: assigns narrow review (evidence: `README.md`)
- Full-stack lead → Solutions architect: requests architecture review (evidence: `README.md`)
- Coding agent → Team protocol: follows team protocol (evidence: `README.md`)
- DevOps agent → Team protocol: follows team protocol (evidence: `README.md`)
- Review agent → Testing standards: checks test tiers (evidence: `README.md`)
- Coding agent → Testing standards: owns T1 T2 (evidence: `README.md`)
- DevOps agent → Testing standards: owns T3 wiring (evidence: `README.md`)
- Full-stack lead → Testing standards: plans coverage (evidence: `README.md`)
- Review agent → Documentation skill: uses guidance
- Coding agent → Git workflow: uses guidance
- Task format gate → Hook common helpers: imports helpers (evidence: `hooks/task_created_format_check.py`)
- Completion verify gate → Hook common helpers: imports helpers (evidence: `hooks/task_completed_verify_gate.py`)
- Idle work check → Hook common helpers: imports helpers (evidence: `hooks/teammate_idle_workcheck.py`)
- Task format gate → Project user: blocks malformed task
- Completion verify gate → Project user: blocks unverified completion
- Idle work check → Project user: nudges claimable work
- Full-stack lead → Brainstorm command: can invoke
- Full-stack lead → Configuration optimizer: can invoke
- DevOps agent → AWS security guidance: uses security guidance
- Claude settings → Task format gate: configures hook
- Claude settings → Completion verify gate: configures hook
- Claude settings → Idle work check: configures hook
- Coding agent → Cached fetch skill: can use skill
