BMAD Readiness Check
"Planning ends here." This skill is the gate between Solutioning and Implementation. It validates that the planning corpus is internally consistent — requirements are covered by architecture, epics trace back to requirements, and nothing critical is missing — before a single line of code is written.
The output is a readiness-report.md with a clear PASS / CONCERNS / FAIL
verdict and actionable specifics.
Workflow
Use TodoWrite to track: Load Artifacts → Cross-Reference → Quality Checks → Generate Report → Display Verdict.
Step 1 — Locate Planning Artifacts
Run the bundled existence check:
bash "${CLAUDE_PLUGIN_ROOT}/skills/bmad-readiness-check/scripts/readiness-check.sh" <output-folder>
The script checks for required artifact files and prints a PASS / CONCERNS / FAIL pre-flight verdict. Read its output; it will also print artifact paths for you to load in Step 2.
Default search root is bmad-output/ (or the user-configured outputFolder).
If the user supplies a custom path, pass it as the argument.
Step 2 — Load and Parse Artifacts
Read each artifact the script located:
Requirements document (PRD or tech-spec):
- Extract labelled Functional Requirements (FR-001, FR-002 …) or requirement bullets if not labelled.
- Extract Non-Functional Requirements (NFR-001 … or named sections: Performance, Security, Scalability, Reliability, Maintainability).
- Note epic count and high-level scope statements.
Architecture document:
- Extract system components and their responsibilities.
- Locate FR traceability matrix or explicit FR-to-component mappings.
- Locate NFR coverage sections.
- Note technology stack decisions and trade-off notes.
Epics / stories (if present):
- Count epics and stories.
- For each epic, identify which PRD requirement(s) it references.
Record a baseline:
Baseline
- FRs found: N
- NFRs found: N
- Epics found: N (0 if Quick Flow)
- Stories found: N (0 if not yet decomposed)
Step 3 — Cross-Reference Checks
3a. FR → Architecture Coverage
For each FR, search the architecture document for the FR identifier AND for the subject matter of the requirement. Mark:
- Covered — FR explicitly addressed, component assigned.
- Implied — subject matter covered but not explicitly linked.
- Missing — no evidence of coverage.
3b. NFR → Architecture Coverage
For each NFR category, check for a dedicated architecture section or explicit strategy:
- Performance: caching, response-time targets, async patterns.
- Security: auth/authz model, encryption, secrets management.
- Scalability: horizontal/vertical strategy, load balancing.
- Reliability: failover, backup, uptime targets.
- Others as present.
Mark each: Addressed / Partial / Missing.
3c. Epic → FR Traceability (BMad Method / Enterprise tracks)
For each epic, verify it references at least one FR or PRD section. Flag orphan epics (no traceable requirement).
3d. Architecture Quality Spot-Checks
Verify the architecture document contains:
- Architectural pattern stated and justified
- Component responsibilities and interfaces defined
- Data model / entity relationships
- API design or service contracts
- Technology choices with rationale
- Trade-offs documented
- Assumptions and constraints listed
Step 4 — Compute Verdict
Apply these thresholds (adapted from BMAD Method v6 gate criteria, expressed as PASS / CONCERNS / FAIL):
| Criterion | PASS | CONCERNS | FAIL |
|---|---|---|---|
| FR coverage (covered + implied) | ≥ 90 % | 80–89 % | < 80 % |
| NFR coverage (addressed + partial) | ≥ 90 % | 80–89 % | < 80 % |
| Architecture quality checks | ≥ 80 % | 70–79 % | < 70 % |
| Blocker issues (critical gaps) | 0 | have mitigation | unmitigated |
| Epic traceability (if applicable) | all linked | ≥ 80 % linked | < 80 % |
Overall verdict rule:
- PASS — all criteria at PASS threshold, no blockers.
- CONCERNS — one or more criteria in CONCERNS band, blockers have mitigation plans. Proceed with caution; address concerns during story refinement.
- FAIL — any criterion below CONCERNS threshold, or any unmitigated blocker. Do not proceed to story creation until issues are resolved.
Step 5 — Generate Report
Write the readiness report using the template:
${CLAUDE_PLUGIN_ROOT}/skills/bmad-readiness-check/templates/readiness-report.template.md
Save to: <outputFolder>/readiness-report-<project-slug>-<date>.md
Use the Write tool. Fill all {{placeholder}} fields from your analysis.
Step 6 — Display Verdict
Print a concise summary to the user:
Readiness Check Complete
Artifact Coverage
FR coverage: XX %
NFR coverage: XX %
Architecture quality: XX %
Verdict: PASS | CONCERNS | FAIL
<One-sentence rationale>
Report saved: <file path>
Then give a concrete Next Step recommendation:
- PASS → Proceed to epic/story decomposition
(
/bmad-planning-orchestrator:bmad-epics-and-stories). - CONCERNS → Proceed with caution; list the open items the story author must carry forward as Dev Notes.
- FAIL → List the top 3–5 required fixes; re-run readiness check after addressing them.
Scope Boundary
This skill validates planning documents only. It does not:
- Write application code.
- Run tests, linters, or build tools.
- Review pull requests or diffs.
- Execute coverage or velocity metrics.
When the verdict is PASS or CONCERNS, hand off to your dev tools via the story files produced by the epic/story skill.
Persona Note
This gate is traditionally owned by Winston (System Architect) in the BMAD Method. The skill is a workflow, not a character, but Winston's voice — thorough, systematic, quality-focused — should guide the tone of the report.
Part of the BMAD Planning & Orchestrator plugin — a Claude Code harness for the BMAD Method by the BMAD Code Organization (https://github.com/bmad-code-org/BMAD-METHOD). Implements the spirit of
bmad-check-implementation-readiness. All methodology credit belongs to the BMAD Code Organization.