faglo/remotion_service
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: separate Architecture Lead from Backend Architect, add implementation engineers

Browse Source 
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) <noreply@anthropic.com>
This commit is contained in:
Daniil
2026-03-22 11:02:52 +03:00
parent 63894f73db
commit 844cc8137f
1 changed files with 57 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/superpowers/specs/2026-03-22-agent-hierarchy-design.md
+57 -27
View File
@@ -29,19 +29,22 @@ The current agent system uses a hub-and-spoke topology: the orchestrator dispatc
### Team Hierarchy ### 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 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: Frontend Architect
│ ├── Tier 2: DB 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: Frontend QA
│ ├── Tier 2: Backend QA │ ├── Tier 2: Backend QA
│ ├── Tier 2: Security Auditor │ ├── Tier 2: Security Auditor
@@ -59,11 +62,36 @@ Tier 0: ORCHESTRATOR (Tech Lead)
### Role Changes ### 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 - **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 - **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 - **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 ### 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 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 ### 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: 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` 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 3. **Update specialist agents** — add hierarchy context (lead identity, tier, dispatch protocol reference) to all existing 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 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 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 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 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/backend-architect/` → `.claude/agents-memory/architecture-lead/`, `.claude/agents-memory/product-strategist/` → `.claude/agents-memory/product-lead/` 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 ### 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/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 ### 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/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/` - `.claude/agents-memory/product-strategist/` → `.claude/agents-memory/product-lead/`
### Files to Modify ### 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-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 - `.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/architecture-lead.md` (post-rename) — add lead coordination, dual-mode operation, frontend-last phasing rules, sub-team definition
- `.claude/agents/product-lead.md` (post-rename) — add lead coordination, dual-mode operation, sub-team definition - `.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/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/remotion-engineer.md` — add hierarchy context (lead: Architecture Lead, tier: 2)
- `.claude/agents/frontend-qa.md` — add hierarchy context (lead: Quality 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/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/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/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 ### 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 - 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)