diff --git a/CLAUDE.md b/CLAUDE.md index 1787172..cc20209 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -118,17 +118,33 @@ All user-facing UI text **must be in Russian**. The only exception is the brand ## Agent Team -This project has a team of 16 specialist agents (15 specialists + 1 Orchestrator). +This project has a team of 20 agents organized in a 4-tier hierarchy: 1 orchestrator, 3 leads, 14 specialists, and 2 staff. Agent files: `.claude/agents/`. Shared protocol: `.claude/agents-shared/team-protocol.md`. +### Team Hierarchy + + Orchestrator (Tech Lead) + ├── Architecture Lead → Backend Architect, Frontend Architect, DB Architect, Remotion Engineer, Sr. Backend Engineer, Sr. Frontend Engineer + ├── Quality Lead → Frontend QA, Backend QA, Security Auditor, Design Auditor, Performance Engineer + ├── Product Lead → UI/UX Designer, Technical Writer, ML/AI Engineer + ├── DevOps Engineer (staff) + └── Debug Specialist (staff) + +### Architect vs. Engineer Role Split + +**Architects** (Backend Architect, Frontend Architect) design specs, API contracts, component trees, and patterns. They advise — they do NOT write implementation code. + +**Engineers** (Senior Backend Engineer, Senior Frontend Engineer) implement production code from architect specs. They receive designs and produce working code. + +This separation ensures architectural decisions are made before implementation begins. Architects and engineers may both be dispatched within the same task — the Architecture Lead sequences them. + ### Developer Team Consultation For ANY non-trivial task, you MUST consult with the developer team: 1. **Announce**: "Consulting with the developer team to [task summary]" -2. Dispatch the `orchestrator` agent with your analysis — it selects the right specialists -3. Built-in agents (code-reviewer, code-explorer, etc.) may be used alongside the team, - but the project's specialist agents must always be consulted +2. Dispatch the `orchestrator` agent with your analysis — it selects the right leads and dispatches them +3. The orchestrator handles everything: dispatches leads, leads dispatch specialists, results bubble up with audit trails 4. **Credit specialists** in your final response — state which agents contributed ### When to Use the Orchestrator @@ -138,71 +154,28 @@ review, documentation), you MUST: 1. Think about the task yourself first — understand scope, affected areas, risks 2. Dispatch the `orchestrator` agent with your analysis as context -3. Follow its dispatch plan exactly +3. Receive the orchestrator's synthesized results (includes full audit trail) +4. Present results to the user Skip the Orchestrator ONLY for trivial tasks: rename a variable, fix a typo, answer a quick factual question. -### Frontend-Last Phasing +### Dispatch Loop (Simplified) -When a plan includes frontend agents (Frontend Architect, Frontend QA) AND backend/design -agents, always run backend/design first: -- **Phase 1**: Backend Architect, DB Architect, UI/UX Designer, Design Auditor -- **Phase 2**: Frontend Architect, Frontend QA (with Phase 1 outputs as context) +1. Dispatch orchestrator with task context +2. Orchestrator handles everything internally (dispatches leads, collects results, resolves conflicts) +3. Receive orchestrator's final synthesis (includes recursive audit trail of all agent calls) +4. Present results to user with team credit summary -Frontend depends on API contracts from backend and specs from design. Running them later -prevents rework. If only frontend agents are needed, they run in Phase 1 normally. - -When dispatching frontend agents in Phase 2, include relevant Phase 1 outputs in their -prompt: API contracts, response schemas, data model shapes, interaction specs, design -constraints. Summarize each to key decisions (~200 words max), not raw output. - -### Dispatch Loop - -After receiving the Orchestrator's plan: - -1. Dispatch all Phase 1 agents (in parallel when the plan says parallel). When dispatching, - include any specialist memory context the Orchestrator specified in "SPECIALIST MEMORY TO INCLUDE" - and any relevant past decisions from "RELEVANT PAST DECISIONS". -2. Collect results from all Phase 1 agents -3. For each agent result, check for "## Handoff Requests" sections -4. If handoffs exist: - a. Dispatch the requested agents with the context provided in the handoff - b. Collect handoff results - c. Re-invoke the original agent with continuation context (see Continuation Format) - d. Check the continuation result for NEW handoff requests -5. Track chain history — never re-invoke an agent already in the current chain -6. Max chain depth: 3. If exceeded, stop and present partial results to the user. -7. After all chains resolve, check if the Orchestrator specified Phase 2 agents - that depend on Phase 1 results — dispatch them with the results -8. Repeat until all phases complete -9. Synthesize all agent outputs into a coherent response - -### Continuation Format - -When re-invoking an agent after their handoff is fulfilled: - -"Continue your work on: - -Your previous analysis (summarized to key points): - - -Handoff results: - - -Resume your Continuation Plan." - -### Context Triggers - -After each agent returns, check their output against the Orchestrator's -"CONTEXT TRIGGERS TO WATCH" list. If a trigger fires, dispatch the -specified agent with the relevant finding as context. +You no longer need to: process handoffs, track chain history, enforce depth limits, +re-invoke agents in continuation mode, dispatch individual specialists, or manage phasing. +The orchestrator → lead → specialist hierarchy handles all of this. ### Conflict Handling -If two agents' outputs contradict each other: -- If one has clear domain authority → use their recommendation -- If ambiguous → present both to the user with your analysis +If the orchestrator reports unresolved conflicts between leads: +- Present both perspectives to the user with your analysis +- Let the user decide on trade-offs that affect their product ## Compact Instructions