Teach and apply the BMAD (Breakthrough Method for Agile AI-Driven Development) methodology for AI-driven software development. Covers the full 4-phase lifecycle: Analysis, Planning, Solutioning, and Implementation with 8 specialized agent personas. Use when: user mentions BMAD, wants AI-driven development workflow, needs PRD or architecture document, wants sprint planning with AI agents, asks about documentation-first development, needs implementation readiness gate, wants to scaffold a project with agent-as-code patterns, says "new project", "set up development workflow", "create stories from PRD", "check implementation readiness", or "run a sprint".
From jm-adknpx claudepluginhub javimontano/jm-adk-alfaThis skill is limited to using the following tools:
agents/guardian.mdagents/lead.mdagents/specialist.mdagents/support.mdevals/evals.jsonknowledge/body-of-knowledge.mdknowledge/knowledge-graph.mdprompts/meta.mdprompts/primary.mdprompts/variations/deep.mdprompts/variations/quick.mdreferences/agent-as-code.mdreferences/anti-patterns-catalog.mdreferences/artifact-flow-chain.mdreferences/bmad-lite.mdreferences/brownfield-patterns.mdreferences/conflict-resolution-protocol.mdreferences/customization-guide.mdreferences/enterprise-governance.mdreferences/greenfield-patterns.mdSearches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
BMAD is a documentation-first, agent-driven software development framework. Each of 4 sequential phases produces artifacts that become mandatory context for the next. Code is a downstream derivative of specifications. [EXPLICIT]
The 4-phase model:
Quick Flow: Barry agent bypasses phases 1-3 for changes ≤3 story points with no architectural impact.
BMAD is:
BMAD is NOT:
| # | Decision | Rationale | Alternatives Rejected |
|---|---|---|---|
| D1 | Documentation-first over code-first | AI agents perform better with structured context than with ambiguous verbal instructions [EVIDENCIA: references/methodology-overview.md] | Code-first with retroactive docs — leads to specification drift |
| D2 | 4-phase sequential model | Progressive context accumulation prevents rework; each phase narrows the solution space [EVIDENCIA: references/artifact-flow-chain.md] | Parallel phases — causes misalignment between artifacts |
| D3 | Agent-as-code (YAML personas) | Reproducible agent behavior; version-controlled with Git [EVIDENCIA: references/agent-as-code.md] | Free-form prompting — inconsistent results across sessions |
| D4 | Mandatory readiness gate before Phase 4 | Implementation without validated specs produces 3-5x rework [INFERENCIA] | Optional gate — teams skip it under pressure, then pay later |
| D5 | HALT-sharded workflow steps | Prevents AI from reading ahead and conflating steps [EVIDENCIA: references/schemas.md] | Single-file workflows — AI skips steps or blends context |
| D6 | Quick Flow bypass for small changes | Full BMAD ceremony for ≤3-point changes creates overhead exceeding value [INFERENCIA] | Always full flow — impractical for bug fixes |
| D7 | Brownfield entry at Phase 2-3 | Existing codebases already have implicit analysis; forcing Phase 1 wastes effort [EVIDENCIA: references/brownfield-patterns.md] | Always start at Phase 1 — redundant for established projects |
| Dimension | What | Start here |
|---|---|---|
| DECLARE | Set up BMAD: install, configure, define agents, create workflows | Section 4 |
| USE | Operate BMAD: run workflows, produce artifacts, manage gates | Section 5-7 |
| APPLY | Apply BMAD in real projects: greenfield, brownfield, enterprise | Section 8 |
Reference Index: Section 10. [EXPLICIT]
1. Run: python scripts/init_project.py <project-name> --greenfield
2. Activate Mary (Analyst) → produce product-brief.md
3. Follow phase-by-phase workflow in workflows/full-flow/
1. Identify your current phase (1-4)
2. Read the corresponding prompt: prompts/phase-N-to-M-handoff.md
3. Activate the phase agent and produce the required artifact
1. Activate Barry (Quick Flow) agent
2. Follow workflows/quick-flow/ (triage → implement → verify)
3. No PRD/architecture needed — story-level documentation only
Run the init script to scaffold a BMAD project: [EXPLICIT]
python scripts/init_project.py <project-name> [--greenfield|--brownfield]
This creates: [EXPLICIT]
<project-name>/
├── .bmad/
│ ├── project-context.md # Project constitution (from template)
│ ├── agents/ # Custom agent definitions
│ └── config.yaml # BMAD configuration
├── planning_artifacts/ # PRD, UX spec, product brief
├── architecture/ # Architecture docs, ADRs
├── epics/ # Epic definitions
├── stories/ # User stories
├── sprints/ # Sprint status and plans
└── project-knowledge/ # Codebase documentation (brownfield)
The project-context.md file is your project's constitution. Every workflow loads it automatically. Create from template: [EXPLICIT]
templates/project-context.md.tmplreferences/project-context-guide.mdKey sections: Vision, Tech Stack, Constraints, Conventions, Team, Links. [EXPLICIT]
Agents are defined as YAML files with persona, menu, and prompts. To create a custom agent: [EXPLICIT]
python scripts/scaffold_agent.py <agent-name> --role "<role description>"
Agent YAML structure — see references/agent-as-code.md: [EXPLICIT]
metadata:
id: agent-code
name: Display Name
icon: emoji
persona:
role: Professional title
identity: Background and personality
communication_style: How the agent speaks
principles: [Core beliefs]
menu:
- trigger: "XX"
description: Workflow name
workflow: path/to/workflow
Workflows are sharded into step files for sequential execution. To scaffold a new workflow: [EXPLICIT]
python scripts/scaffold_workflow.py <workflow-name> --steps 5
This creates step-01-init.md through step-05-name.md with HALT commands preventing AI read-ahead. See references/schemas.md for the step file schema. [EXPLICIT]
Agent: Mary (Analyst) — agents/mary-analyst.md | Goal: Explore problem space before committing to planning.
| Workflow | Output | Required |
|---|---|---|
| Brainstorming | brainstorming-report.md | Optional |
| Research (domain/market/technical) | Research findings | Optional |
| Create Product Brief | product-brief.md | Yes |
Procedure:
references/phase-1-analysis.md for detailed guidanceproduct-brief.md in planning_artifacts/Failure Recovery:
[ASSUMPTION] with Low confidence, proceed with explicit risk acknowledgment in brief. Flag to John/PM that these assumptions must be validated before PRD is finalized.Transition: Use prompts/phase-1-to-2-handoff.md to hand off to Phase 2.
Agents: John (PM) + Sally (UX) — agents/john-pm.md, agents/sally-ux.md
Goal: Define what to build and for whom.
Workflows:
| Workflow | Output | Required |
|---|---|---|
| Create PRD | PRD.md | Yes |
| Create UX Design | ux-spec.md | Yes (if UI) |
Procedure:
references/phase-2-planning.mdproduct-brief.md as input contexttemplates/prd.md.tmpl
Failure Recovery:
Transition: Use prompts/phase-2-to-3-handoff.md.
Agents: Winston (Architect) + Bob (Scrum Master) — agents/winston-architect.md, agents/bob-scrum-master.md
Goal: Decide how to build it and break work into implementable stories.
Workflows:
| Workflow | Output | Required |
|---|---|---|
| Create Architecture | architecture.md + ADRs | Yes |
| Create Epics & Stories | epics/.md, stories/.md | Yes |
| Check Implementation Readiness | Gate: PASS/CONCERNS/FAIL | Yes |
Procedure:
references/phase-3-solutioning.mdtemplates/architecture-doc.md.tmpltemplates/epic.md.tmpltemplates/user-story.md.tmplFailure Recovery:
Transition: Only proceed if gate returns PASS. Use prompts/phase-3-to-4-handoff.md.
Agents: Amelia (Developer) + Quinn (QA) — agents/amelia-developer.md, agents/quinn-qa.md
Goal: Build it, one story at a time, with continuous validation.
Workflows:
| Workflow | Output | Required |
|---|---|---|
| Sprint Planning | sprint-status.yaml | Yes |
| Create Story | story-[slug].md (detailed) | Per story |
| Dev Story | Working code + tests | Per story |
| Code Review | Approval or revision | Per story |
| Retrospective | Lessons learned | Per sprint |
Procedure:
references/phase-4-implementation.mdscripts/generate_sprint_status.pyprompts/sprint-kickoff-prompt.mdtemplates/code-review-checklist.md.tmplprompts/retrospective-prompt.mdFailure Recovery:
Agent: Barry (Quick Flow Dev) — agents/barry-quick-flow.md
When to use: Bug fixes, small features in established codebases, prototypes, single-story changes.
Procedure:
references/quick-flow.mdtemplates/code-review-checklist.md.tmplEach phase's output becomes mandatory input for the next: [EXPLICIT]
product-brief.md ──→ PRD.md ──→ architecture.md ──→ epics/*.md ──→ stories/*.md ──→ Code
(Phase 1) (Phase 2) (Phase 3) (Phase 3) (Phase 4) (Phase 4)
Rules:
Validate the chain:
python scripts/check_artifact_flow.py <project-root>
This reports: broken references, orphaned artifacts, missing cross-links. [EXPLICIT]
See references/artifact-flow-chain.md for the full dependency model. [EXPLICIT]
The gate is a mandatory checkpoint before Phase 4. It validates that planning and solutioning artifacts are complete and aligned. Run with python scripts/validate_prd.py <project-root>. Output: PASS / CONCERNS / FAIL. See references/implementation-gate-details.md for the 13 validation steps, gate result actions, FAIL remediation routing, and agent roster. [EXPLICIT]
| Factor | Greenfield | Brownfield |
|---|---|---|
| Start phase | Phase 1 (Analysis) | Phase 2 or 3 (skip brief) |
| Init flag | --greenfield | --brownfield |
| Extra step | None | Run Document Project workflow first |
| project-context.md | Created from scratch | Generated from codebase scan |
| Key reference | references/greenfield-patterns.md | references/brownfield-patterns.md |
For multi-team BMAD adoption, see references/enterprise-governance.md: [EXPLICIT]
For solo developers or projects ≤2 weeks, see references/bmad-lite.md: [EXPLICIT]
See references/customization-guide.md: [EXPLICIT]
references/integration-patterns.md| Need | Tool |
|---|---|
| Lint all artifacts | scripts/lint_artifacts.py <project-root> |
| Diagnose project health | scripts/diagnose_project.py <project-root> |
| Troubleshoot a stalled workflow | references/troubleshooting.md |
| Resolve inter-agent conflicts | references/conflict-resolution-protocol.md |
| Measure BMAD effectiveness | references/metrics-framework.md |
| Identify anti-patterns | references/anti-patterns-catalog.md |
Standalone checklists for quick operational verification: [EXPLICIT]
| Checklist | Use when |
|---|---|
checklists/phase-1-complete.md | Before handing off from Mary to John |
checklists/phase-2-complete.md | Before handing off from John/Sally to Winston/Bob |
checklists/phase-3-complete.md | Before running the 13-step gate |
checklists/sprint-ready.md | Before starting a sprint |
checklists/story-ready.md | Before picking up a story for development |
checklists/story-done.md | Before marking a story as complete |
checklists/quick-flow-triage.md | Before starting a quick flow |
11 agents across 4 phases: Mary (Analyst, Phase 1), John (PM, Phase 2), Sally (UX, Phase 2), Winston (Architect, Phase 3), Bob (Scrum Master, Phase 3-4), Amelia (Developer, Phase 4), Quinn (QA, Phase 4), Barry (Quick Flow, any phase), Orchestrator (meta-router), Gate Reviewer (impartial evaluator), Retro Facilitator. See references/implementation-gate-details.md for the full roster with conflict resolution rules.
| Need | Read |
|---|---|
| BMAD theory, principles, glossary | references/methodology-overview.md |
| Phase 1 deep guide | references/phase-1-analysis.md |
| Phase 2 deep guide | references/phase-2-planning.md |
| Phase 3 deep guide | references/phase-3-solutioning.md |
| Phase 4 deep guide | references/phase-4-implementation.md |
| Quick Flow guide | references/quick-flow.md |
| Agent YAML spec | references/agent-as-code.md |
| project-context.md guide | references/project-context-guide.md |
| Artifact dependency model | references/artifact-flow-chain.md |
| 13-step gate spec | references/implementation-readiness-gate.md |
| Context engineering | references/progressive-context.md |
| Existing codebase adoption | references/brownfield-patterns.md |
| New project patterns | references/greenfield-patterns.md |
| Multi-team/enterprise | references/enterprise-governance.md |
| Adapting BMAD | references/customization-guide.md |
| YAML/JSON schemas | references/schemas.md |
| Troubleshooting stalled workflows | references/troubleshooting.md |
| CI/CD, Git hooks, IDE integration | references/integration-patterns.md |
| KPIs and effectiveness measurement | references/metrics-framework.md |
| Inter-agent conflict resolution | references/conflict-resolution-protocol.md |
| Anti-pattern catalog (27 entries) | references/anti-patterns-catalog.md |
| Simplified BMAD for solo devs | references/bmad-lite.md |
.tmpl files) exist and are accessible at templates/ relative to the skill directoryExample invocations: [EXPLICIT]
| Scenario | Handling |
|---|---|
| Empty or minimal input | Request clarification before proceeding |
| Conflicting requirements | Flag conflicts explicitly, propose resolution |
| Out-of-scope request | Redirect to appropriate skill or escalate |