ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/expansion-packs/bmad-javascript-fullstack/data/agent-responsibility-matrix.md

15 KiB
Raw Blame History

Agent Responsibility Matrix

Clear boundaries defining what each agent owns, preventing duplication and token waste through overlapping work.

Core Principle

Each decision has ONE owner. When multiple agents could handle a task, this matrix defines who does what and when to hand off.

Responsibility Ownership

Solution Architect

OWNS:

  • Overall system architecture and patterns
  • Technology stack selection (which frameworks/databases/platforms)
  • High-level API strategy (REST vs GraphQL vs tRPC - the choice itself)
  • System-wide architectural patterns (monolith vs microservices vs JAMstack)
  • Infrastructure and deployment architecture
  • Security architecture (overall approach, not implementation details)
  • Database technology selection (SQL vs NoSQL, which database)
  • Integration architecture (how systems connect)
  • Scalability and performance strategy
  • Cross-cutting concerns (logging, monitoring, error handling strategy)

DOES NOT OWN:

  • Detailed API endpoint specifications (delegates to API Developer)
  • Component implementation details (delegates to React/Node Developers)
  • Specific TypeScript type definitions (delegates to TypeScript Expert)
  • Detailed database schema (reviews, but delegates to specialists)
  • Implementation-level security patterns (delegates to specialists)

HANDOFF TO:

  • API Developer: "We're using REST API. Here's the authentication approach and high-level resources. Create detailed endpoint specifications."
  • React Developer: "We're using Next.js App Router with Zustand. Here's the component architecture. Implement components."
  • Node Backend Developer: "We're using Fastify with Prisma and PostgreSQL. Here's the layered architecture. Implement services."

TOKEN BUDGET: 2,000-4,000 per architecture phase OUTPUT: Architecture documents, stack decisions, pattern selections (comprehensive, high-quality) CONTEXT: Load technology/architecture guides, create checkpoints for delegation

API Developer

OWNS:

  • Detailed API endpoint specifications (all routes, methods, parameters)
  • Request/response schemas and data models
  • API versioning strategy implementation
  • OpenAPI/GraphQL schema definitions
  • API documentation and examples
  • Endpoint-level security specifications (which endpoints need auth)
  • Pagination, filtering, sorting patterns
  • API error response formats

DOES NOT OWN:

  • API style selection (REST vs GraphQL - Architect decides)
  • Backend implementation (delegates to Node Backend Developer)
  • Frontend API integration (delegates to React Developer)
  • Overall authentication architecture (Architect decides, API Developer specifies endpoints)

RECEIVES FROM:

  • Solution Architect: API style choice, authentication approach, high-level resources
  • Analyst: Data requirements, user needs

HANDOFF TO:

  • Node Backend Developer: "Here's the complete API spec. Implement these endpoints following the specification."
  • React Developer: "Here's the API contract. Integrate these endpoints on the frontend."

TOKEN BUDGET: 1,000-2,000 per API design phase OUTPUT: API specifications, endpoint documentation, schemas (detailed, complete, production-ready) CONTEXT: Load api-implementation-patterns (relevant section only), checkpoint from architect

React Developer

OWNS:

  • React component implementation
  • Component-level state management
  • Hooks and custom hooks
  • Frontend routing implementation
  • UI/UX implementation
  • Client-side form validation
  • Frontend performance optimization
  • Accessibility implementation
  • CSS/styling implementation

DOES NOT OWN:

  • Framework selection (Architect decides)
  • Overall state management architecture (Architect decides, React Developer implements)
  • API endpoint design (API Developer owns)
  • Backend integration logic (uses API contract, doesn't design it)

RECEIVES FROM:

  • Solution Architect: Framework choice, state management strategy, architecture patterns
  • API Developer: API contracts and documentation
  • Designer: UI/UX designs, component specifications

HANDOFF TO:

  • None typically (React Developer is implementation leaf node)

TOKEN BUDGET: 800-1,500 per feature OUTPUT: React components, hooks, frontend features (complete, performant, accessible) CONTEXT: Load state/component guides only when making decisions, use API specs as reference

Node Backend Developer

OWNS:

  • Backend service implementation (controllers, services, repositories)
  • Business logic implementation
  • Database query implementation
  • Server-side validation
  • Background job implementation
  • Backend performance optimization
  • Error handling implementation
  • Logging and monitoring implementation

DOES NOT OWN:

  • Framework selection (Architect decides)
  • API contract design (API Developer designs, Backend implements)
  • Database technology selection (Architect decides)
  • Overall architecture patterns (Architect decides, Backend implements)

RECEIVES FROM:

  • Solution Architect: Framework choice, architecture patterns, database technology
  • API Developer: API specifications to implement

HANDOFF TO:

  • None typically (Backend Developer is implementation leaf node)

TOKEN BUDGET: 1,000-2,000 per feature OUTPUT: Backend services, endpoints, business logic (secure, performant, tested) CONTEXT: Load security/database guides only when implementing auth/complex queries, use API specs as contract

TypeScript Expert

OWNS:

  • TypeScript configuration and setup
  • Complex type definitions (generics, conditional types, mapped types)
  • Type system architecture
  • JavaScript to TypeScript migration strategy
  • Type safety improvements and refactoring
  • Shared type definitions across frontend/backend

DOES NOT OWN:

  • TypeScript adoption decision (Architect decides)
  • Component implementation (React Developer owns)
  • Backend implementation (Node Developer owns)
  • Simple interface definitions (any agent can create basic types)

CALLED IN FOR:

  • Setting up TypeScript project
  • Migrating JavaScript to TypeScript
  • Complex generic types that other agents struggle with
  • Type system refactoring and optimization

RECEIVES FROM:

  • Solution Architect: TypeScript adoption decision, strictness requirements
  • Any Agent: Request for complex type definitions

HANDOFF TO:

  • Requesting Agent: "Here are the type definitions. Use them in your implementation."

TOKEN BUDGET: 500-1,200 per task OUTPUT: Type definitions, tsconfig, migration plans (type-safe, maintainable) CONTEXT: Load TypeScript guides only for complex patterns, use role knowledge for basics

Scrum Master (SM)

OWNS:

  • Breaking architecture/features into implementable stories
  • Story acceptance criteria and DoD
  • Story effort estimation and prioritization
  • Sprint planning and backlog management
  • Story dependency management

DOES NOT OWN:

  • Technical architecture (Architect owns)
  • Technical implementation details (Developers own)
  • API design (API Developer owns)

RECEIVES FROM:

  • Solution Architect: Architecture documents, technical specifications
  • Analyst: Requirements, user needs

HANDOFF TO:

  • Developers: "Here are the stories with clear acceptance criteria. Implement in priority order."

TOKEN BUDGET: 800-1,500 per epic breakdown OUTPUT: Development stories with clear DoD (actionable, testable, estimable) CONTEXT: Use checkpoints and architecture docs as reference, don't load implementation guides

Analyst

OWNS:

  • Requirements gathering and documentation
  • User story creation (from user perspective)
  • Business goal definition
  • Stakeholder communication
  • User research and competitive analysis

DOES NOT OWN:

  • Technical architecture (Architect owns)
  • Technical feasibility (collaborates with Architect)
  • Implementation approach (Developers own)

HANDOFF TO:

  • Solution Architect: "Here are the requirements. Design the architecture."
  • Scrum Master: "Here are user needs. Break into implementable stories."

TOKEN BUDGET: 500-1,000 per requirements doc OUTPUT: Requirements documents, user stories (clear, comprehensive, testable) CONTEXT: No technical guides needed, focus on business/user domain

Decision Flowcharts

Who Designs the API?

API Design Needed
│
├─ High-Level Decision (REST vs GraphQL vs tRPC)?
│  └─ Solution Architect
│     Output: "Use REST API with JWT auth"
│     Handoff to: API Developer
│
└─ Detailed Specification (all endpoints, schemas)?
   └─ API Developer
      Output: OpenAPI spec with all routes
      Handoff to: Node Backend Developer (implement)
                  React Developer (consume)

Key: Architect decides WHAT (API style), API Developer designs HOW (endpoints), Backend implements.

Who Handles State Management?

State Management Needed
│
├─ High-Level Decision (which state solution for project)?
│  └─ Solution Architect
│     Output: "Use React Query for server state, Zustand for global client state"
│     Handoff to: React Developer
│
└─ Implementation (actual state management code)?
   └─ React Developer
      Output: Store setup, hooks, state logic

Key: Architect decides WHICH solution, React Developer implements HOW.

Who Designs Database Schema?

Database Schema Needed
│
├─ Database Technology Selection (SQL vs NoSQL, which DB)?
│  └─ Solution Architect
│     Output: "Use PostgreSQL with Prisma ORM"
│     Handoff to: Node Backend Developer or team
│
├─ High-Level Schema Design (main entities, relationships)?
│  └─ Solution Architect (in architecture doc)
│     Output: Entity relationship diagram, key tables
│     Handoff to: Node Backend Developer
│
└─ Detailed Schema (all columns, indexes, migrations)?
   └─ Node Backend Developer
      Output: Prisma schema, migrations, indexes

Key: Architect chooses tech + high-level design, Backend Developer creates detailed schema.

Who Handles Security?

Security Implementation Needed
│
├─ Security Architecture (overall approach, auth strategy)?
│  └─ Solution Architect
│     Output: "Use JWT with refresh tokens, RBAC, OWASP compliance"
│     Handoff to: Specialists
│
├─ API Security Specs (which endpoints need auth, roles)?
│  └─ API Developer
│     Output: Endpoint-level auth requirements in spec
│     Handoff to: Backend Developer
│
└─ Security Implementation (auth code, validation, middleware)?
   └─ Node Backend Developer
      Output: Auth middleware, validation, security headers

Key: Architect defines WHAT, API Developer specifies WHERE, Backend implements HOW.

Avoiding Overlap: Handoff Protocol

Bad: Overlapping Work (Token Waste)

❌ Scenario: Feature needs API endpoints

  • Solution Architect creates detailed API spec (3,000 tokens)
  • API Developer also creates detailed API spec (3,000 tokens)
  • Result: 6,000 tokens wasted, duplicate work, potential conflicts

Good: Clear Handoff (Efficient)

✅ Scenario: Feature needs API endpoints

  • Solution Architect: "Use REST API. Auth with JWT. Resources: users, posts. Delegate to API Developer for details."
  • API Developer receives: "Design REST API for users and posts with JWT auth. Here's checkpoint with architecture decisions."
  • API Developer creates detailed spec
  • Result: No duplication, 3,000 tokens saved

Handoff Pattern

Agent A (Strategic)
│
├─ Makes high-level decision
├─ Documents in checkpoint (max 100 lines)
├─ Specifies constraints and requirements
│
└─ Handoff to Agent B with:
   - Decision summary
   - Constraints
   - Artifact paths for context
   - Specific task: "You own X, design/implement Y"

Agent B (Tactical)
│
├─ Receives checkpoint (not full history)
├─ Loads ONLY relevant guides for their decision
├─ Creates detailed specification/implementation
└─ Does NOT re-decide what Agent A decided

Responsibility Anti-Patterns

❌ Anti-Pattern 1: "I'll Do Everything"

Example: Solution Architect creates detailed API spec, database schema, and component designs

  • Problem: Token waste, architect doing tactical work
  • Fix: Architect creates high-level design, delegates details to specialists

❌ Anti-Pattern 2: "Who Owns This?"

Example: Both Solution Architect and API Developer design the same API

  • Problem: Duplication, conflicting specs, token waste
  • Fix: Use responsibility matrix - Architect decides API style, API Developer designs endpoints

❌ Anti-Pattern 3: "I Need to Understand Everything"

Example: React Developer loads backend architecture, database schema, deployment strategy

  • Problem: Loading context outside their domain
  • Fix: React Developer loads only: API contract, frontend architecture, component specs

❌ Anti-Pattern 4: "Let Me Re-Decide"

Example: Backend Developer re-evaluates framework choice already made by Architect

  • Problem: Re-work, token waste on context already compressed
  • Fix: Backend Developer receives checkpoint: "Framework: Fastify. Implement services."

Token Optimization Through Clear Boundaries

Before: Unclear Boundaries

  • Solution Architect loads: everything (6,000 tokens)
  • API Developer loads: everything (6,000 tokens)
  • Both design API: duplicate work
  • Total: 12,000 tokens, duplicate work

After: Clear Boundaries

  • Solution Architect: Loads stack/architecture guides (2,500 tokens), creates checkpoint (500 tokens)
  • API Developer: Loads checkpoint + API patterns (1,200 tokens), designs detailed spec
  • Total: 4,200 tokens, no duplication
  • Savings: 65% token reduction

Quick Reference: "Who Do I Call?"

Need Call Agent They Will
Technology stack selection Solution Architect Choose frameworks, databases, tools
System architecture Solution Architect Design overall system, patterns, structure
API style decision Solution Architect Choose REST/GraphQL/tRPC
Detailed API specification API Developer Design all endpoints, schemas, docs
React component implementation React Developer Build components, hooks, state
Backend endpoint implementation Node Backend Developer Implement services, queries, business logic
Complex TypeScript types TypeScript Expert Create advanced type definitions
JS → TS migration TypeScript Expert Plan and execute migration
Requirements gathering Analyst Document requirements, user needs
Story breakdown Scrum Master Create implementable stories with DoD

Summary: Preventing Overlap

Golden Rules:

  1. One owner per decision - No duplication
  2. Strategic → Tactical handoff - Architect decides, specialists implement
  3. Checkpoints for handoff - Don't repeat full context
  4. Load only your domain - Don't load other agents' context
  5. Trust the handoff - Don't re-decide upstream decisions

Token Impact:

  • Clear boundaries → 50-70% reduction in duplicate context loading
  • Checkpoints for handoff → 80% reduction in repeated context
  • Domain-specific loading → Each agent loads only what they need

Quality Impact:

  • ✅ DOES NOT reduce output quality
  • ✅ DOES NOT limit agent responses
  • ✅ Agents still produce comprehensive, high-quality outputs
  • ✅ Prevents conflicting decisions from multiple agents
  • ✅ Clearer ownership and accountability