Skip to main content
skill CX Codex

bmad-readiness-check — Claude Code skill: purpose and install

The bmad-readiness-check Claude Code skill checks whether planning documents agree before implementation starts. Ask for it to validate requirements, architecture, and epics for build readiness.

MIT 107 installs ★ 493 updated 2026-06-20

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add aj-geddes/claude-code-bmad-skills --skill bmad-readiness-check -a claude-code
Open on GitHub

What bmad-readiness-check does

The skill compares requirements with the architecture and checks whether epics or stories trace back to those requirements. It flags gaps in functional and non-functional coverage, missing links, and architecture checklist items. The result is a PASS, CONCERNS, or FAIL verdict with specific findings.

A bundled script locates planning files in bmad-output/ or a configured folder. The skill then reads the artifacts and writes readiness-report-<project-slug>-<date>.md. It expects a PRD or tech spec and an architecture document; epics and stories are checked when present. Its scope ends at planning documents: it does not edit application code, run tests, or build the project.

What it helps with

  • compare functional requirements with the architecture
  • spot requirements with no architecture coverage
  • check whether epics trace back to requirements
  • find planning gaps before implementation

Example prompts for the agent

  • Check whether the project is ready to build.
  • Compare the PRD with the architecture and flag gaps.
  • Run a readiness check on the planning documents.

How to install bmad-readiness-check

1Skills CLI (Vercel)

npx skills add aj-geddes/claude-code-bmad-skills --skill bmad-readiness-check -a claude-code

2Manually: put the files in place

~/.claude/skills/bmad-readiness-check/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/bmad-readiness-check/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about bmad-readiness-check

How do I install bmad-readiness-check in Claude Code?

Run npx skills add aj-geddes/claude-code-bmad-skills --skill bmad-readiness-check -a claude-code. The skill file is installed at ~/.claude/skills/bmad-readiness-check/SKILL.md.

What does bmad-readiness-check do?

It compares requirements, architecture, and any available epics or stories, then returns a PASS, CONCERNS, or FAIL verdict and saves a readiness report.

Which planning documents does bmad-readiness-check inspect?

It checks a PRD or tech spec and an architecture document, along with epics and stories when available. Enterprise planning can also include security and DevOps addenda.

Source text

SKILL.md · MIT
---
name: bmad-readiness-check
description: |
  SOLUTIONING GATE — validates cohesion across planning artifacts before any
  implementation begins. Cross-references PRD (or tech-spec), architecture document,
  and epics/stories for coverage consistency and missing pieces. Returns a verdict
  of PASS, CONCERNS, or FAIL with specifics. Does NOT touch code.

  Use when the user says:
  - "check if we're ready to build" / "are we ready to implement?"
  - "validate planning" / "gate check" / "readiness check"
  - "run the solutioning gate" / "check implementation readiness"
  - "is the architecture complete?" / "do requirements match architecture?"
  - "sign off on planning" / "planning done, check it"
  - "validate PRD against architecture" / "cross-reference planning docs"

  Intents supported: Validate (primary).
  Track-adaptive: works for Quick Flow (tech-spec + architecture), BMad Method
  (PRD + architecture + epics), and Enterprise (all of the above + optional
  security/DevOps addenda).
allowed-tools: Read, Write, Bash, Glob, Grep, TodoWrite
---

# 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
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.

© aj-geddes · MIT · aj-geddes/claude-code-bmad-skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set11

The whole set →
bmad-research bmad-research — a skill that conducts structured market, competitor, technology and domain research from live sources, producing a cited research report. Run it before product planning or architecture decisions. CX Codex +1 138installs bmad-brainstorm bmad-brainstorm runs structured ideation sessions using SCAMPER, SWOT, and 5 Whys. Delivers an organized markdown report ready for project planning. CX Codex +1 130installs bmad-tech-spec bmad-tech-spec generates a focused tech spec for small-scope work instead of a full PRD and architecture pair. Use it when requirements are clear, scope fits 1-15 stories, and you need one planning artifact before writing stories. CX Codex +1 114installs bmad-spec The bmad-spec Claude Code skill turns rough notes, a PRD, or a transcript into a compact SPEC.md with five sections. It activates when a project needs a clear problem statement and scope. CX Codex +1 108installs bmad-document-project The bmad-document-project Claude Code skill scans an existing codebase in read-only mode to generate project-documentation.md. It maps runtime dependencies and entry points before downstream planning. CX Codex +1 104installs bmad-sprint-planning The bmad-sprint-planning Claude Code skill sorts stories by dependency and prepares a development handoff plan. Ask it to arrange stories, map parallel waves, or create sprint-status.yaml. CX Codex +1 104installs bmad-investigate The bmad-investigate Claude Code skill investigates bugs and turns findings into a case file. Invoke it to trace a reported failure, update an open investigation, or check a draft before handoff. CX Codex +1 102installs bmad-builder bmad-builder — a skill for Claude Code scaffolds and validates custom planning skills in the BMAD plugin. Generates folder trees and keeps instructions strictly inside planning boundaries. CX Codex +1 102installs

Project sponsors

Companies that keep this analytics open