← Back to KB Index
BMAD Library — Behavioural Model–Driven Agent Design
bmad-library.md
**Date Compiled** 2026-04-28
**Type** source — bmad
**Related Questions** agent-design, factory-patterns, modular-agents
**Related Articles** [[kelly-handbook-multi-agent]], [[kelly-handbook-software-factory]], [[kelly-tweets-bmad]]

BMAD Library — Behavioural Model–Driven Agent Design

BMAD is Kelly's framework for designing specialized, composable agents using behavioural models. Each agent is defined not by its model or vendor, but by its role, trigger conditions, workflow, and output contracts. Agents are organized into tiers by function — research, build, and quality — with named orchestrators coordinating pools of specialized sub-agents.

The core principle: make every agent's identity, inputs, and outputs explicit so they can be composed reliably into pipelines without ambiguity about who does what and when.

CIS Tier — Research and Discovery

Context → Information → Synthesis

The CIS pipeline is the research engine. Every research task follows three phases:

  1. **Context** — What do we know already? What's the market like? Who are the competitors?
  2. **Information** — What do we need to know? Search Reddit, App Store, reviews. Find real pain points.
  3. **Synthesis** — What does it all mean? Score the opportunity. Write the summary with a gate decision.

CIS sub-agents run in parallel. After they complete, Mary (the Analyst) synthesizes all outputs into a final research summary.

Research Lead — Orchestrator (CIS)

The Research Lead owns the full research pipeline. It is the named agent that Research Lead agents report to.

Role: Orchestrate all research and discovery tasks — find opportunities, validate pain points, produce actionable research summaries with clear gate decisions.

Triggers:

Workflow:

1. Read intake.md to understand what we're researching 2. Determine which CIS agents to spawn (parallel):    - New product idea: Carson + Victor + Maya    - Technical problem: Dr. Quinn + Mary    - Market opportunity: Victor + Mary    - Improvement/feature: Maya + Mary 3. Spawn sub-agents with specific tasks 4. Wait for completion 5. Spawn Mary (Analyst) to synthesize all outputs 6. Write research-summary.md with gate decision 7. Report back to Kelly Router

Output Artifacts:

FileDescription
`evidence.md`Research findings, sources, data
`decision-log.md`Key decisions made during research
`research-summary.md`Final summary with gate: READY / NOT-READY

Gate Criteria (READY requires all):

Escalation: Log failure → retry once → escalate to Kelly Router with diagnostics.

Maya — Design Thinking Coach

Type: Sub-agent (Research)

Spawned by: Research Lead

Purpose: Apply design thinking to understand user needs deeply

Task:

  1. Read intake.md to understand the problem space
  2. Research user pain points through: 1-star app reviews (gold), Reddit discussions, forum complaints
  3. Identify: core user problems, emotional context (frustration, confusion, pain), current workarounds users employ
  4. Synthesize into user personas and jobs-to-be-done
  5. Save to `research-artifacts/maya-design.md`

Guidelines: Focus on emotional and functional pain points. Look for patterns across multiple sources. Consider edge cases and power users. Don't assume — let users tell you what they need.

Victor — Innovation Strategist

Type: Sub-agent (Research)

Spawned by: Research Lead

Purpose: Analyze market opportunities and competitive landscape

Task:

  1. Read intake.md to understand the problem space
  2. Research existing solutions and competitors
  3. Identify market gaps and opportunities
  4. Assess: market size and growth, competitive landscape, barriers to entry, potential differentiators
  5. Save to `research-artifacts/victor-market.md`

Guidelines: Use data where available (reviews, downloads, pricing). Be objective about competition — don't dismiss them. Look for underserved segments or features. Consider timing and market readiness.

BMM Tier — Build and Manage

Build & Manage Methodology

BMM is the implementation engine. It transforms approved research into working code through structured planning and disciplined execution.

Project Lead — Orchestrator (BMM)

The Project Lead owns the full planning and implementation pipeline. It is the named agent that Project Lead agents report to.

Role: Orchestrate all planning and implementation tasks — take approved research and turn it into working code, managing the full implementation lifecycle.

Triggers:

Workflow:

1. Read research-summary.md to understand what we're building 2. Create planning artifacts (product-brief, prd, architecture, ux-design) 3. Run design gate (must pass before coding) 4. Spawn implementation sub-agents 5. Validate implementation 6. Write implementation-summary.md 7. Report to Kelly Router for testing phase

Output Artifacts:

Planning phase (planning-artifacts/):

FileDescription
`product-brief.md`Executive summary — what and why
`prd.md`Full product requirements
`architecture.md`Technical design
`ux-design.md`User experience specs
`planning-summary.md`Gate: PASS / FAIL

Implementation phase (implementation-artifacts/{project-name}/):

FileDescription
`{project-name}/`Source code
`implementation-summary.md`What was built

Design Gate Criteria (must pass before coding):

Sprint Structure: Break work into user-story sized chunks — Completable in 1–2 hours, testable, deliverable independently.

Escalation: Log failure → retry once with different approach → escalate to Kelly Router with diagnostics.

Amelia — Developer

Type: Sub-agent (Implementation)

Spawned by: Project Lead

Purpose: Write actual code — production-quality implementation

Task:

  1. Read architecture.md and prd.md to understand what to build
  2. Create the project structure
  3. Write all necessary code (models, views, services, helpers)
  4. Ensure code compiles
  5. Report progress to Project Lead

Code Standards:

Git Setup:

  1. Initialize git in the project folder
  2. Add .gitignore (secrets, logs, node_modules, .env)
  3. Commit with meaningful messages
  4. Commit regularly as you build

Cross-Cutting Patterns

Several patterns span all three tiers:

Named Agents vs Sub-Agents

Every tier has a named orchestrator (Research Lead, Project Lead, Test Lead) that coordinates a pool of sub-agents. Named agents report to the Kelly Router; sub-agents are spawned by their named agent. Named agents do not execute tasks directly — they orchestrate.

Gate-Based Progression

Every phase ends with a gate:

No phase proceeds until its gate passes. Gates are objective (28/40 score for CIS; checklist criteria for BMM/TEA).

Escalation Pattern

All three named agents follow the same escalation pattern:

  1. Log failure to `/clawd/logs/escalations.log`
  2. Retry once with a different approach
  3. Escalate to Kelly Router with diagnostics (what's blocked, what's working, recommended path forward)

Artifact Contracts

Each agent has explicit output contracts — files they produce and where. This makes pipeline output predictable and auditable. Artifacts are written to project-specific directories (research-artifacts/, planning-artifacts/, implementation-artifacts/, test-artifacts/).

Kelly Router as the Top-Level Orchestrator

The Kelly Router sits above all named agents. It receives operator input, assigns work to named agents (Research Lead, Project Lead, Test Lead), and receives their reports. It owns the final release decision.

Parallel + Sequential Hybrid

CIS sub-agents run in parallel (Carson, Maya, Dr. Quinn, Victor all do their work simultaneously), then Mary synthesizes sequentially after they complete. BMM phases run sequentially (planning → implementation). TEA runs a structured sequential audit.

No Placeholders Rule

Amelia's code standards explicitly prohibit placeholder code — real implementation only. This extends to the wider factory: research outputs, design specs, and test reports should be complete, not skeletal.

dark-factory-kb · https://dark-factory-kb.pages.dev