From 844cc8137f84f92166650b8f04e228d6d10e8611 Mon Sep 17 00:00:00 2001 From: Daniil Date: Sun, 22 Mar 2026 11:02:52 +0300 Subject: [PATCH] docs: separate Architecture Lead from Backend Architect, add implementation engineers Architecture Lead is now a pure system-level coordinator (NEW agent), Backend Architect stays as Tier 2 specialist. Added Senior Backend Engineer and Senior Frontend Engineer as implementation specialists. Total agent count: 20 (16 existing + 4 new). Co-Authored-By: Claude Opus 4.6 (1M context) --- .../2026-03-22-agent-hierarchy-design.md | 84 +++++++++++++------ 1 file changed, 57 insertions(+), 27 deletions(-) diff --git a/docs/superpowers/specs/2026-03-22-agent-hierarchy-design.md b/docs/superpowers/specs/2026-03-22-agent-hierarchy-design.md index f2dd87c..385e0a4 100644 --- a/docs/superpowers/specs/2026-03-22-agent-hierarchy-design.md +++ b/docs/superpowers/specs/2026-03-22-agent-hierarchy-design.md @@ -29,19 +29,22 @@ The current agent system uses a hub-and-spoke topology: the orchestrator dispatc ### Team Hierarchy -17 agents (16 existing + 1 new Quality Lead). 4 tiers. 3 sub-teams + 2 staff. +20 agents (16 existing + 4 new: Architecture Lead, Quality Lead, Senior Backend Engineer, Senior Frontend Engineer). 4 tiers. 3 sub-teams + 2 staff. -Two existing agents are promoted to lead roles (Backend Architect → Architecture Lead, Product Strategist → Product Lead). Their agent files are renamed; their domain expertise is retained; lead coordination responsibilities are added. +One existing agent is promoted to a lead role (Product Strategist → Product Lead). Four new agents are created: Architecture Lead, Quality Lead, Senior Backend Engineer, Senior Frontend Engineer. Backend Architect remains unchanged as a Tier 2 specialist. ``` Tier 0: ORCHESTRATOR (Tech Lead) │ - ├── Tier 1: ARCHITECTURE LEAD (Backend Architect, promoted + renamed) + ├── Tier 1: ARCHITECTURE LEAD (NEW — pure system architect + coordinator) + │ ├── Tier 2: Backend Architect (unchanged) │ ├── Tier 2: Frontend Architect │ ├── Tier 2: DB Architect - │ └── Tier 2: Remotion Engineer + │ ├── Tier 2: Remotion Engineer + │ ├── Tier 2: Senior Backend Engineer (NEW — implements backend code) + │ └── Tier 2: Senior Frontend Engineer (NEW — implements frontend code) │ - ├── Tier 1: QUALITY LEAD (NEW agent) + ├── Tier 1: QUALITY LEAD (NEW — QA strategy + coordinator) │ ├── Tier 2: Frontend QA │ ├── Tier 2: Backend QA │ ├── Tier 2: Security Auditor @@ -59,11 +62,36 @@ Tier 0: ORCHESTRATOR (Tech Lead) ### Role Changes -**Backend Architect → Architecture Lead.** File renamed: `backend-architect.md` → `architecture-lead.md`. Memory directory renamed: `.claude/agents-memory/backend-architect/` → `.claude/agents-memory/architecture-lead/`. The `subagent_type` for dispatch becomes `"architecture-lead"`. Retains all backend/FastAPI/Python expertise. Gains coordination responsibility for cross-service architecture. Operates in dual mode (see below). +**Architecture Lead (NEW).** Pure system architect and coordinator. Does NOT retain Backend Architect expertise — it operates at the system level, understanding how all services interact but not doing deep implementation in any one. Expertise in: +- **Cross-service architecture** — understanding the full data flow: Frontend → Backend API → Dramatiq → Remotion → S3 → WebSocket +- **API contract design** — defining the interfaces between services, ensuring contracts are consistent and complete +- **System decomposition** — breaking architectural tasks into specialist-scoped sub-tasks for Backend Architect, Frontend Architect, DB Architect, Remotion Engineer +- **Architectural trade-off analysis** — evaluating approaches across performance, maintainability, security, and developer experience +- **Frontend-last phasing** — sequencing backend/DB work before frontend work within its sub-team (see Frontend-Last Phasing section) -**Product Strategist → Product Lead.** File renamed: `product-strategist.md` → `product-lead.md`. Memory directory renamed accordingly. Retains all product/growth expertise. Gains coordination of the "why and what" sub-team: UX design, documentation, ML model decisions. +Always operates in coordinator mode. When the orchestrator needs deep backend expertise, it dispatches Backend Architect directly (through the Architecture Lead), not the Architecture Lead in "specialist mode." -**Quality Lead (NEW).** Senior QA/verification coordinator with expertise in: +**Backend Architect (UNCHANGED).** Remains a Tier 2 specialist under Architecture Lead. Retains all Python/FastAPI/service-layer expertise. No changes to its domain knowledge or responsibilities — only hierarchy context is added (lead: Architecture Lead, tier: 2). Focuses on architecture, design, and API contracts — does NOT write implementation code. + +**Senior Backend Engineer (NEW).** Implementation specialist for the backend. Writes production Python/FastAPI code based on architectural specs from Backend Architect and DB Architect. Expertise in: +- **FastAPI implementation** — endpoints, dependency injection, Pydantic schemas, middleware +- **SQLAlchemy async** — models, repositories, migrations, complex queries +- **Dramatiq tasks** — background job implementation, error handling, retries +- **Service layer patterns** — business logic, cross-module coordination +- Receives architectural specs and API contracts as input, produces working code as output +- Follows the project's module pattern exactly: `models.py`, `schemas.py`, `repository.py`, `service.py`, `router.py` + +**Senior Frontend Engineer (NEW).** Implementation specialist for the frontend. Writes production Next.js/React/TypeScript code based on architectural specs from Frontend Architect and design specs from UI/UX Designer. Expertise in: +- **Next.js 16 / React 19** — App Router, Server Components, client components, data fetching +- **FSD architecture** — strict layer boundaries, module-aware features, barrel exports +- **Component implementation** — Radix Themes, SCSS Modules, responsive layouts, animations +- **State management** — TanStack Query for server state, Redux for client state, form handling +- Receives component tree designs and interaction specs as input, produces working code as output +- Enforces FSD import rules: `pages → widgets → features → entities → shared` + +**Product Strategist → Product Lead.** File renamed: `product-strategist.md` → `product-lead.md`. Memory directory renamed accordingly. Retains all product/growth expertise. Gains coordination of the "why and what" sub-team: UX design, documentation, ML model decisions. Operates in dual mode: coordinator mode (default) for sub-team orchestration, specialist mode when the orchestrator needs direct product/growth analysis. The orchestrator signals mode via `MODE: coordinator` or `MODE: specialist` in the dispatch context. If omitted, coordinator mode is assumed. + +**Quality Lead (NEW).** Senior QA/verification coordinator. Always operates in coordinator mode. Expertise in: - **Risk-based test strategy** — analyzing code changes to determine what kinds of testing are needed (unit, integration, E2E, security, performance) and at what coverage level - **Quality synthesis** — combining outputs from multiple QA/audit agents into a unified quality assessment with prioritized findings - **Test gap analysis** — identifying what isn't covered, what edge cases are missing, what failure modes haven't been considered @@ -79,15 +107,15 @@ Decision framework for dispatching sub-team: ### Lead Dual-Mode Operation -Promoted leads (Architecture Lead, Product Lead) retain deep specialist expertise AND gain coordination responsibilities. The orchestrator signals which mode to use via the dispatch context: +Only the Product Lead has dual-mode operation, since it is a promoted specialist (Product Strategist) that retains domain expertise alongside coordination responsibilities. -**Coordinator mode** (default for leads): "Decompose this task for your sub-team, dispatch the right specialists, synthesize results." The lead acts as a manager — scoping, dispatching, synthesizing. It does not do deep specialist work itself. +**Coordinator mode** (default): "Decompose this task for your sub-team, dispatch the right specialists, synthesize results." The lead acts as a manager — scoping, dispatching, synthesizing. -**Specialist mode** (explicit tag): "Answer this as a backend/product specialist — do NOT dispatch your sub-team." The lead acts as an individual contributor, using its domain expertise directly. Used when the orchestrator needs the lead's specific expertise, not coordination. +**Specialist mode** (explicit tag): "Answer this as a product/growth specialist — do NOT dispatch your sub-team." The lead acts as an individual contributor. Used when the orchestrator needs direct product analysis. The orchestrator includes `MODE: coordinator` or `MODE: specialist` in the dispatch context. If omitted, coordinator mode is assumed. -The Quality Lead always operates in coordinator mode — it has no specialist domain beyond QA strategy. +Architecture Lead and Quality Lead are pure coordinators — they always operate in coordinator mode and have no specialist mode. ### What "Lead" Means @@ -365,30 +393,32 @@ The main session no longer: processes individual handoffs, tracks chain history, Execute in this sequence to ensure each layer is ready before the layer above uses it: -1. **Create Quality Lead** — `.claude/agents/quality-lead.md` +1. **Create new agents** — `.claude/agents/architecture-lead.md`, `.claude/agents/quality-lead.md`, `.claude/agents/senior-backend-engineer.md`, `.claude/agents/senior-frontend-engineer.md` 2. **Update team protocol** — add dispatch protocol, context object, guardrails, audit trail format, hierarchy definition to `.claude/agents-shared/team-protocol.md` -3. **Update specialist agents** — add hierarchy context (lead identity, tier, dispatch protocol reference) to all 11 specialist agent files -4. **Rename and update lead agents** — rename `backend-architect.md` → `architecture-lead.md`, `product-strategist.md` → `product-lead.md`; add lead coordination responsibilities and dual-mode behavior +3. **Update specialist agents** — add hierarchy context (lead identity, tier, dispatch protocol reference) to all existing specialist agent files +4. **Rename and update Product Lead** — rename `product-strategist.md` → `product-lead.md`; add lead coordination responsibilities and dual-mode behavior 5. **Update staff agents** — add hierarchy context (staff role, direct-to-orchestrator) to DevOps and Debug Specialist -6. **Update orchestrator** — shift to lead-level dispatch, remove individual specialist routing, add dual-mode dispatch for leads -7. **Update CLAUDE.md** — simplify dispatch loop to orchestrator-only model, update agent team description and count -8. **Rename memory directories** — `.claude/agents-memory/backend-architect/` → `.claude/agents-memory/architecture-lead/`, `.claude/agents-memory/product-strategist/` → `.claude/agents-memory/product-lead/` +6. **Update orchestrator** — shift to lead-level dispatch, remove individual specialist routing, add dual-mode dispatch for Product Lead +7. **Update CLAUDE.md** — simplify dispatch loop to orchestrator-only model, update agent team description and count to 20, document architect-vs-engineer role split +8. **Rename memory directories** — `.claude/agents-memory/product-strategist/` → `.claude/agents-memory/product-lead/` +9. **Create memory directories** — `.claude/agents-memory/architecture-lead/`, `.claude/agents-memory/quality-lead/`, `.claude/agents-memory/senior-backend-engineer/`, `.claude/agents-memory/senior-frontend-engineer/` ### Files to Create +- `.claude/agents/architecture-lead.md` — new Architecture Lead agent with system architecture, cross-service decomposition, frontend-last phasing - `.claude/agents/quality-lead.md` — new Quality Lead agent with QA strategy, dispatch framework, synthesis protocol +- `.claude/agents/senior-backend-engineer.md` — new implementation agent for Python/FastAPI code +- `.claude/agents/senior-frontend-engineer.md` — new implementation agent for Next.js/React/TypeScript code ### Files to Rename -- `.claude/agents/backend-architect.md` → `.claude/agents/architecture-lead.md` - `.claude/agents/product-strategist.md` → `.claude/agents/product-lead.md` -- `.claude/agents-memory/backend-architect/` → `.claude/agents-memory/architecture-lead/` - `.claude/agents-memory/product-strategist/` → `.claude/agents-memory/product-lead/` ### Files to Modify -- `.claude/agents-shared/team-protocol.md` — add dispatch protocol, context object, guardrails, audit trail format, hierarchy definition, update team roster -- `.claude/agents/orchestrator.md` — shift to lead-level dispatch, add direct Agent dispatch of leads, simplify pipeline, add dual-mode dispatch tagging -- `.claude/agents/architecture-lead.md` (post-rename) — add lead coordination, dual-mode operation, frontend-last phasing rules, sub-team definition +- `.claude/agents-shared/team-protocol.md` — add dispatch protocol, context object, guardrails, audit trail format, hierarchy definition, update team roster to 20 agents +- `.claude/agents/orchestrator.md` — shift to lead-level dispatch, add direct Agent dispatch of leads, simplify pipeline, add dual-mode dispatch tagging for Product Lead - `.claude/agents/product-lead.md` (post-rename) — add lead coordination, dual-mode operation, sub-team definition -- `.claude/agents/frontend-architect.md` — add hierarchy context (lead: Architecture Lead, tier: 2), dispatch protocol reference +- `.claude/agents/backend-architect.md` — add hierarchy context (lead: Architecture Lead, tier: 2), clarify architect-only role (no implementation) +- `.claude/agents/frontend-architect.md` — add hierarchy context (lead: Architecture Lead, tier: 2), clarify architect-only role - `.claude/agents/db-architect.md` — add hierarchy context (lead: Architecture Lead, tier: 2) - `.claude/agents/remotion-engineer.md` — add hierarchy context (lead: Architecture Lead, tier: 2) - `.claude/agents/frontend-qa.md` — add hierarchy context (lead: Quality Lead, tier: 2) @@ -401,9 +431,9 @@ Execute in this sequence to ensure each layer is ready before the layer above us - `.claude/agents/ml-ai-engineer.md` — add hierarchy context (lead: Product Lead, tier: 2) - `.claude/agents/devops-engineer.md` — add hierarchy context (staff, tier: 1, direct to orchestrator) - `.claude/agents/debug-specialist.md` — add hierarchy context (staff, tier: 1, direct to orchestrator) -- `CLAUDE.md` — simplify dispatch loop to orchestrator-only, update agent count to 17, update team description +- `CLAUDE.md` — simplify dispatch loop to orchestrator-only, update agent count to 20, update team description ### Files Unchanged -- `.claude/agents-memory/` contents — memory files stay, only directories rename +- `.claude/agents-memory/` existing contents — memory files stay, only product-strategist directory renames - Individual agent domain expertise — unchanged, only communication protocol and hierarchy context added -- All agent tools — unchanged (all agents already have the Agent tool) +- All existing agent tools — unchanged (all agents already have the Agent tool)