Claude Code Local Architecture v2

Configuration structure

~/.claude/ — global user configuration

all files present

~/.claude/

◆ settings.json always-on wires all hook events · sets CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 · enables tmuxSplitPanes + teammateMode: tmux · global permissions

▸ commands/ slash commands, user-invoked

◆ plan_to_build.md /plan_to_build v1 — analyze codebase → design solution → compose team from agents/team/ → write exhaustive spec to specs/ → Stop hook validates 7 sections

◆ plan_to_build_v2.md /plan_to_build_v2 v2 — same as v1 + documents that Assigned To is enforced: every task must have an Assigned To matching a Team Member name · references /build_v2

◆ build.md /build v1 — TeamCreate → TaskCreate graph with addBlockedBy deps → deploy builders + validator + spec-updater → monitor via SendMessage → TeamDelete

◆ build_v2.md /build_v2 v2 — TeamCreate with timestamp suffix · per-agent Assigned To filter injected into standing orders · builders poll indefinitely · validator sends targeted wakeup · leader tracks liveness (ping at 10min, escalate at 12min)

▸ agents/team/ self-organizing team workers

◆ builder.md builder v2: polls TaskList filtering on both role:builder AND Assigned To: <own-name> · claims matched task · executes · marks completed · loops indefinitely until shutdown_request

◆ validator.md validator v2: on FAIL — creates fix task with Assigned To: <original-builder>, sends "fix-task created for <builder-name>" to leader who sends targeted wakeup · max 2 fix cycles

◆ spec-updater.md spec-updater runs after all other tasks — re-runs validation commands, writes ## Build Evidence section into spec file with PASS/FAIL per criterion

◆ bug-creator.md bug pipeline investigates codebase, reproduces bug, writes JIRA-format 8-section report to bugs/BUG-NNN/report.md

◆ bug-router.md bug pipeline read-only classifier — reads report + .claude/bug-modules.json, routes to correct fixer agent

◆ bug-fixer-api.md · bug-fixer-frontend.md · bug-fixer-database.md bug pipeline specialist fixers — reads bug report, creates fix plan at specs/fix-NNN.md, executes fix, captures test evidence

◆ bug-reviewer.md bug pipeline adversarial read-only reviewer — 5-point checklist, APPROVE/REJECT verdict, deployed twice in isolation (alpha + beta)

◆ pr-agent.md bug pipeline creates structured PRs via gh pr create with bug summary, root cause, fix description, test evidence

▸ hooks/ system-enforced Python, fires on lifecycle events

◆ pre_tool_use.py PreToolUse blocks dangerous commands (rm -rf, force push) — safety gate before every tool call

◆ enforce_team_lead.py PreToolUse blocks Write/Edit to .claude/ or specs/ from non-team-lead agents during active build sessions

◆ require_team_create.py PreToolUse enforces TeamCreate before TaskCreate — prevents orphaned tasks with no team

◆ validate_plan_format.py PreToolUse blocks Write to specs/*.md if any of the 7 required sections are missing

◆ validate_task_description.py PreToolUse blocks TaskCreate if description is under-specified — enforces exhaustive task descriptions

◆ enforce_test_evidence.py PostToolUse ensures test output is captured to bugs/NNN/test-results.md before PR creation in bug pipeline

◆ merge_gate.py PreToolUse blocks merge commands unless both adversarial reviewer verdicts are APPROVE — prevents unreviewed merges

◆ enforce_review_isolation.py PreToolUse prevents reviewer-alpha and reviewer-beta from reading each other's verdicts before both complete

◆ session_start.py · stop.py Session session_start: loads CONTEXT.md + TODO.md · stop: wires to plan_to_build Stop hook validators before session ends

▸ validators/

◆ validate_new_file.py · validate_file_contains.py Stop hook blocks session end unless new specs/*.md written with all 7 required sections: Task Description, Objective, Relevant Files, Step by Step Tasks, Acceptance Criteria, Team Orchestration, Team Members

▸ skills/ always-on engineering philosophy library (48 skills)

◆ writing-plans/ · test-driven-development/ · systematic-debugging/ core mandatory planning, TDD, and debugging protocols — embedded into agent standing orders

◆ verification-before-completion/ · safe-rollback/ safety never declare done without running commands and showing output · git rollback when fix cycles exhausted

◆ + 43 more skills library brainstorming, code-refactoring, frontend/backend guidelines, k8s-sre, playwright, pr workflow, and more

Runtime architecture — v2 · local interactive mode

Claude Code CLI — agent team mode v2

Assigned To enforced · indefinite poll · liveness · timestamp teams

flowchart TD DEV([Developer
Terminal + tmux]) -->|"/plan_to_build_v2
'add feature X'"| PTB DEV -->|"/build_v2 specs/plan.md"| BUILD subgraph PLAN_PHASE ["Plan Creation — plan_to_build_v2.md"] PTB["Analyze codebase directly
no subagents — understand patterns"] --> DESIGN DESIGN["Design solution
task type · complexity
architecture decisions"] --> TEAM_COMP TEAM_COMP["Compose team from agents/team/*.md
builder count · workstream split
every task MUST have Assigned To"] --> WRITE_SPEC WRITE_SPEC["Write exhaustive spec to specs/*.md
task IDs · deps · full descriptions
Assigned To = Team Member name"] --> HOOK_STOP HOOK_STOP["Stop hook fires
validate_new_file.py
validate_file_contains.py
7 required sections?
file created this session?"] end HOOK_STOP -->|"PASS → allow stop
FAIL → block + fix"| REPORT1 REPORT1["Plan report
+ EXECUTION DIRECTIVE
FORBIDDEN: direct implementation
REQUIRED: /build_v2 only"] REPORT1 -->|"'/build_v2 specs/plan.md'"| BUILD subgraph BUILD_PHASE ["Build Orchestration — build_v2.md"] BUILD["Team Lead
reads spec
disallowed: Write, Edit, NotebookEdit"] --> TEAM_CREATE TEAM_CREATE["TeamCreate
name = plan-YYYYMMDD-HHMM
timestamp prevents collision"] --> TASK_GRAPH TASK_GRAPH["TaskCreate x N
one per plan task + addBlockedBy deps
auto spec-updater task blocked by all"] --> DEPLOY subgraph DEPLOY ["Parallel Deploy — run_in_background: true"] B1["builder-1
standing orders include:
Assigned To: builder-1 filter
poll indefinitely — no retry limit"] B2["builder-2
Assigned To: builder-2 filter
poll indefinitely — no retry limit"] VAL_A["validator
on FAIL: names target builder
creates fix task Assigned To: builder-N
sends wakeup via leader"] SPEC_U["spec-updater
runs last — blocked by all
re-runs commands
writes Build Evidence to spec"] end DEPLOY --> MONITOR MONITOR["Team Lead monitors
receives SendMessage reports
tracks last_seen per agent
does NOT poll — event-driven"] MONITOR -->|"Validation FAILED
fix_cycle less than 2"| FIX_TASK FIX_TASK["validator names builder:
fix task Assigned To: builder-N
leader sends wakeup to builder-N
builder re-checks immediately"] FIX_TASK -->|"builder wakes and claims"| DEPLOY MONITOR -->|"FAILED max cycles"| ESCALATE ESCALATE["Escalate to user
collect failure details
do NOT create more fix tasks"] MONITOR -->|"agent silent 10+ min"| LIVENESS LIVENESS["Leader pings agent
no response in 2 min?
Escalate: agent hung on task-ID
await user decision"] end BUILD_PHASE --> SHUTDOWN SHUTDOWN["SendMessage shutdown_request
to all agents
wait shutdown_response
TeamDelete"] --> BUILD_REPORT BUILD_REPORT["Build Report
agents · tasks · assigned vs actual owner
validation results · fix cycles
spec evidence · files changed"] subgraph HOOKS ["Hooks — Python via uv run"] H1["PreToolUse — 7 guards
dangerous cmd · team lead writes · team before tasks
plan format · task quality · merge gate · branch discipline"] H2["PostToolUse
enforce_test_evidence · validate_bug_report
validate_pr_test_evidence"] H3["Stop
validate_new_file.py + validate_file_contains.py
blocks if spec incomplete"] H4["Session lifecycle
SessionStart: load CONTEXT.md
SubagentStart/Stop: audit log"] end style DEV fill:#edf2fb,stroke:#2a5fa5,color:#1a1a1a style PLAN_PHASE fill:#edf2fb,stroke:#2a5fa5,color:#1a1a1a style PTB fill:#edf2fb,stroke:#2a5fa5,color:#1a1a1a style DESIGN fill:#edf2fb,stroke:#2a5fa5,color:#1a1a1a style TEAM_COMP fill:#edf2fb,stroke:#2a5fa5,color:#1a1a1a style WRITE_SPEC fill:#eef7f1,stroke:#2d7a4f,color:#1a1a1a style HOOK_STOP fill:#fdf6e3,stroke:#b08a2e,color:#1a1a1a style REPORT1 fill:#edf2fb,stroke:#2a5fa5,color:#1a1a1a style BUILD_PHASE fill:#f3f0fa,stroke:#6450b4,color:#1a1a1a style BUILD fill:#f3f0fa,stroke:#6450b4,color:#1a1a1a style TEAM_CREATE fill:#fdf0ec,stroke:#c84b2f,color:#1a1a1a style TASK_GRAPH fill:#f3f0fa,stroke:#6450b4,color:#1a1a1a style DEPLOY fill:#f0ecfc,stroke:#6450b4,color:#1a1a1a style B1 fill:#fdf0ec,stroke:#c84b2f,color:#1a1a1a style B2 fill:#fdf0ec,stroke:#c84b2f,color:#1a1a1a style VAL_A fill:#fdf0ec,stroke:#c84b2f,color:#1a1a1a style SPEC_U fill:#f0ecfc,stroke:#2d7a4f,color:#7a7468 style MONITOR fill:#fdf6e3,stroke:#b08a2e,color:#1a1a1a style FIX_TASK fill:#fdf0ec,stroke:#c84b2f,color:#1a1a1a style LIVENESS fill:#fdf0ec,stroke:#c84b2f,color:#1a1a1a style ESCALATE fill:#fdf0ec,stroke:#c84b2f,color:#1a1a1a style SHUTDOWN fill:#eef7f1,stroke:#2d7a4f,color:#1a1a1a style BUILD_REPORT fill:#eef7f1,stroke:#2d7a4f,color:#1a1a1a style HOOKS fill:#fdf6e3,stroke:#b08a2e,color:#1a1a1a style H1 fill:#fdf6e3,stroke:#b08a2e,color:#7a7468 style H2 fill:#fdf6e3,stroke:#b08a2e,color:#7a7468 style H3 fill:#fdf6e3,stroke:#b08a2e,color:#7a7468 style H4 fill:#fdf6e3,stroke:#b08a2e,color:#7a7468

Agent coordination — v2 message ladder (fix cycle with wakeup)

build_v2 — fix cycle message sequence

validator wakeup · indefinite polling · liveness ping

sequenceDiagram actor U as User participant L as Leader participant TL as TaskList participant B1 as builder-1 participant B2 as builder-2 participant V as validator participant SU as spec-updater U->>L: /build_v2 specs/my-plan.md L->>L: Parse plan, extract team and tasks L->>L: TeamCreate(my-plan-20260315-1430) L->>TL: TaskCreate(task-1, Assigned To: builder-1) L->>TL: TaskCreate(task-2, Assigned To: builder-2, blocked by task-1) L->>TL: TaskCreate(validate-all, blocked by task-1 and task-2) L->>TL: TaskCreate(spec-update, blocked by all) par Deploy all agents once L-->>B1: Deploy(name=builder-1, standing orders with Assigned To filter) L-->>B2: Deploy(name=builder-2, standing orders with Assigned To filter) L-->>V: Deploy(name=validator) L-->>SU: Deploy(name=spec-updater) end B1->>TL: TaskList() find role:builder AND Assigned To:builder-1 B2->>TL: TaskList() find role:builder AND Assigned To:builder-2 — no match, wait 30s B1->>TL: TaskUpdate(task-1, owner=builder-1, in_progress) B1->>B1: Execute task-1 B1->>TL: TaskUpdate(task-1, completed) B1->>L: Task task-1 complete Note over B2: task-2 now unblocked B2->>TL: TaskList() — task-2 matches Assigned To:builder-2 B2->>TL: TaskUpdate(task-2, owner=builder-2, in_progress) B2->>B2: Execute task-2 B2->>TL: TaskUpdate(task-2, completed) B2->>L: Task task-2 complete Note over B1,B2: Both poll indefinitely — no self-termination V->>TL: TaskList() — validate-all unblocked V->>V: Run validation commands... FAILED V->>TL: TaskCreate(fix-task, Assigned To: builder-1) V->>TL: TaskCreate(revalidate, blocked by fix-task) V->>L: Validation FAILED — fix-task created for builder-1 Note over L: v2 — targeted wakeup L->>B1: SendMessage(wakeup — fix-task available, re-check now) Note over B1: skips 30s wait, re-checks immediately B1->>TL: TaskList() — fix-task matches Assigned To:builder-1 B1->>TL: TaskUpdate(fix-task, owner=builder-1, in_progress) B1->>B1: Apply fix B1->>TL: TaskUpdate(fix-task, completed) B1->>L: fix-task complete V->>TL: TaskList() — revalidate unblocked V->>V: Run validation commands... PASSED V->>TL: TaskUpdate(revalidate, completed) V->>L: Validation PASSED SU->>TL: TaskList() — spec-update unblocked SU->>SU: Re-run validations, write Build Evidence to spec SU->>L: Spec update COMPLETE Note over L: v2 — liveness check (if any agent silent 10+ min) L->>B2: SendMessage(ping — status check) B2->>L: SendMessage(still polling, no tasks assigned to me) L->>L: Update last_seen for B2 L->>B1: SendMessage(shutdown_request) L->>B2: SendMessage(shutdown_request) L->>V: SendMessage(shutdown_request) L->>SU: SendMessage(shutdown_request) L->>L: TeamDelete L->>U: Build Complete report

Command internals — v2 engineering philosophy

📋 plan_to_build_v2.md

1

Analyze Requirements
parse USER_PROMPT · determine task type + complexity

2

Understand Codebase Directly
no subagents — Read, Grep, Glob existing patterns and architecture

3

Design Solution
architecture decisions · technical approach · edge cases

4

Define Team Members
builder count · names · agent types from agents/team/*.md · one validator

5

Exhaustive Task Descriptions v2
fully self-contained · file paths · code patterns · acceptance criteria · every task has Assigned To matching a Team Member

6

Save + Stop Hook Validates
validate_new_file.py + validate_file_contains.py block if any of 7 sections missing

7

EXECUTION DIRECTIVE in spec
FORBIDDEN: direct implementation · REQUIRED: /build_v2 command only

⚙️ build_v2.md

1

Team Lead — never writes code
disallowed-tools: Write, Edit, NotebookEdit · reads plan · builds agent name list for wakeup broadcasts

2

Timestamped team + full task graph v2
TeamCreate(plan-YYYYMMDD-HHMM) · TaskCreate per task · addBlockedBy deps · auto spec-updater last

3

Deploy once with per-agent standing orders v2
each builder gets Assigned To: <own-name> filter injected · run_in_background:true · poll indefinitely

4

Event-driven monitoring + liveness v2
wait for SendMessage · track last_seen per agent · ping at 10min silence · escalate at 12min

5

Targeted wakeup on fix tasks v2
validator names target builder in message · leader sends direct wakeup · builder re-checks immediately, no 30s wait

6

Clean shutdown
SendMessage shutdown_request to every agent · wait response · TeamDelete · build report with assigned vs actual owner

🪝 hooks — Python lifecycle events

Pre

PreToolUse — 7 guards
dangerous cmd · team lead writes · team before tasks · plan format · task quality · merge gate · branch discipline

Post

PostToolUse — 4 validators
post_tool_use · test evidence · bug report 8 sections · PR test evidence

Stop

Stop — spec gate
new file in specs/ required · all 7 sections present · blocks session end if missing

Ses

Session lifecycle
SessionStart: load CONTEXT.md · SessionEnd: persist state · SubagentStart/Stop: audit log

Cfg

All wired in settings.json
uv run $HOME/.claude/hooks/*.py — portable $HOME paths, no hardcoded usernames

🤖 agent standing orders v2

B

Builder loop v2
TaskList → match role:builder AND Assigned To:<own-name> → claim → TaskGet → execute → complete → SendMessage → repeat

V

Validator loop v2
claim (role:validator) → run all commands → PASS: complete · FAIL: create fix task Assigned To:builder-N · report to leader with builder name

S

Spec-updater (runs last)
blocked by all other tasks · re-runs commands · writes ## Build Evidence into spec · read-only for src

⊘

Ownership is explicit v2
builders check both role: AND Assigned To: — tasks not addressed to them are skipped even if unblocked

∞

Indefinite polling v2
no max retry limit — poll every 30s, respond to wakeup immediately · shutdown only on shutdown_request from leader

Engineering philosophy — skills embedded in commands

Skills → Command embedding traceability matrix

deterministic enforcement

Skill / Rule	Embedded In	Enforcement	Key Rule
writing-plans	plan_to_build_v2 → Step 5 task descriptions	prompt + hook	≥50-word exhaustive descriptions, design assertions per task, 7 required spec sections, every task has Assigned To
brainstorming	plan_to_build_v2 → Steps 1–3 analysis	prompt	ultrathink approach, consider edge cases and scalability before writing tasks
plan-reviewer	plan_to_build_v2 → self-verify before save	prompt	count builders, validators, check every acceptance criterion, verify all Assigned To names match Team Members
test-driven-development	builder standing orders (implicit)	prompt	agents follow TDD as part of their base agent definition — test first is mandatory
systematic-debugging	validator fix cycle dispatch	prompt	fix tasks include reproduce → isolate → root cause → fix protocol
verification-before-completion	build_v2 → validator standing orders	prompt	never report PASS without running actual commands and capturing actual output
safe-rollback	build_v2 → max fix cycles exhausted	prompt	after 2 failed fix cycles, validator escalates — team lead reports, no further fix tasks
executing-plans	build_v2 → task graph execution	prompt	dependency ordering via addBlockedBy — agents never start tasks before prerequisites complete
Assigned To enforcement	build_v2 → per-agent standing orders	prompt (v2)	each agent's standing orders inject their own name — only claim tasks where Assigned To matches exactly
Indefinite polling	build_v2 → builder + validator standing orders	prompt (v2)	no max retry count — agents poll every 30s indefinitely, only self-stop on explicit shutdown_request
Targeted wakeup	build_v2 → Phase 4 monitor	prompt (v2)	validator names target builder in failure message → leader sends direct wakeup → builder re-checks immediately
Liveness detection	build_v2 → Phase 4 monitor	prompt (v2)	leader tracks last_seen per agent; pings after 10min silence; escalates to user if no pong in 2min
Team name collision prevention	build_v2 → Phase 2 TeamCreate	prompt (v2)	team name = plan-name-YYYYMMDD-HHMM — timestamp suffix guarantees uniqueness across re-runs
spec section check	validate_plan_format.py + validate_file_contains.py	SYSTEM	7 sections required — blocks Write and blocks Stop if missing
task quality check	validate_task_description.py	SYSTEM	TaskCreate blocked if description is under-specified — enforces exhaustive agent context
team lead enforcement	enforce_team_lead.py	SYSTEM	Write/Edit to .claude/ and specs/ blocked during active build — only team lead may write spec
merge gate	merge_gate.py	SYSTEM	merge commands blocked unless bug pipeline state shows both reviewer verdicts are APPROVE
review isolation	enforce_review_isolation.py	SYSTEM	reviewer-alpha cannot read reviewer-beta verdict (and vice versa) until both complete
test evidence capture	enforce_test_evidence.py	SYSTEM	PR creation blocked unless test results committed to bugs/NNN/test-results.md
spec build evidence	spec-updater standing orders	structural	spec-updater task always auto-created by /build_v2, blocked by all others — spec becomes system of record
dangerous command guard	pre_tool_use.py	SYSTEM	rm -rf, force push, --no-verify blocked before every tool call — safety net for all agents

v1 vs v2 — coordination model comparison

What changed and why

4 targeted fixes · no architectural rewrites

Concern	v1 behaviour	v2 fix	Risk removed
Task claiming	⚠ agents filter by role:builder only — any builder could claim any builder task	✓ per-agent Assigned To filter injected at deploy time — builders only claim their own tasks	Parallel builders executing each other's tasks; wasted work; wrong specialist on wrong task
Builder lifecycle	✗ max 5 retries → self-terminate → fix tasks created by validator sit unclaimed	✓ poll every 30s indefinitely — shutdown_request from leader is the only exit	Fix tasks orphaned after validation failure; build stalls silently
Fix task discovery	⚠ builders discover fix tasks only on their next 30s poll cycle (if still alive)	✓ validator reports builder name → leader sends direct wakeup → builder re-checks immediately	Fix cycle latency; orphaned tasks if builder already idle
Team name	✗ team name = plan filename — collision if plan is run twice	✓ team name = plan-name-YYYYMMDD-HHMM — unique per run	TeamCreate failure; orphaned tasks from prior run mixed with new run
Hung agents	✗ no detection — silent agent looks identical to busy agent to leader	✓ last_seen tracked per agent; ping at 10min silence; escalate to user at 12min	Build hangs indefinitely waiting for an agent that is stuck on a blocking call
Build report	⚠ shows tasks and owners — no distinction between intended and actual assignment	✓ report shows both Assigned To (intended) and actual claiming agent — drift is visible	Hidden task ownership violations in parallel builds