BMAD Support

The SPECLAN Plugin for Claude Code converts between BMAD-METHOD and SPECLAN in both directions. Three commands handle the bridge: one imports BMAD artifacts into SPECLAN, two export SPECLAN specs back to BMAD format.

This page covers what maps to what, how each command works, and how to set up a project that uses both frameworks together.

What Is BMAD-METHOD?

BMAD-METHOD is an AI-driven agile framework that organizes development through specialized agent personas. A PM agent ("John") facilitates PRD creation through collaborative interviews. An Architect agent ("Winston") documents technical decisions. A QA agent and UX Designer handle their respective domains. Each agent runs structured, step-by-step workflows that produce planning artifacts: Product Briefs, PRDs with measurable Functional Requirements, Architecture Documents, Epics with User Stories and BDD Acceptance Criteria.

BMAD excels at the discovery and planning phase -- turning a vague product idea into precise, measurable specifications through facilitated agent conversations.

SPECLAN picks up where BMAD's planning phase ends. It manages the lifecycle after planning -- status transitions (draft through released), change request tracking for locked specs, traceability across your hierarchy, and AI prime context for implementation agents.

The philosophy: plan with BMAD, govern with SPECLAN.

How BMAD and SPECLAN Map to Each Other

When you convert between BMAD and SPECLAN, concepts map as follows:

BMAD Concept	SPECLAN Entity	Notes
Success Criteria (User, Business, Technical)	Goals (`G-###`)	Each measurable outcome becomes a Goal
PRD Capability Areas	Parent Features (`F-####`)	Top-level grouping preserved
Functional Requirements (`FR#`)	Requirements (`R-####`)	`[Actor] can [capability]` format retained, acceptance criteria converted
Epic Stories / User Stories	Child Features (`F-####`)	User Story format preserved in description
BDD Acceptance Criteria (`Given/When/Then`)	Acceptance Criteria checkboxes (`- [ ]`)	Each step becomes a checkbox item
Non-Functional Requirements	NFR Features (`F-####`)	Measurable thresholds preserved
Product Scope phases (MVP, Growth, Vision)	Scope tags on Features	Phase boundaries maintained
Architecture Requirements (`AR#`)	Requirements under Architecture Features	Captured from Architecture Documents
UX Requirements (`UX#`)	Requirements under UX Features	Captured from Epics document

Non-Obvious Mappings

FR Coverage Map authority. When both a PRD and an Epics document exist, the converter uses BMAD's FR Coverage Map -- the authoritative table that assigns each Functional Requirement to an Epic -- rather than guessing from section headings. This produces more accurate Feature groupings.

Developer-infrastructure reclassification. Functional Requirements where the actor is "Project" or "Build system" rather than a user (for example, FR8: Project can lint and format code automatically) are not user-facing behavior. The converter reclassifies these as NFRs under a Code Quality feature, keeping your spec hierarchy focused on what users experience.

Implementation stripping. BMAD artifacts often include technology names, architecture patterns, and file paths -- useful during planning, but not appropriate for specifications that define what rather than how. The converter strips implementation-specific language during import. A requirement like "Use PostgreSQL for data persistence" becomes "The system persists data reliably" -- the architecture decision lives in your Architecture Document, not in your spec.

Prerequisites

You need two things installed before using the BMAD conversion commands.

BMAD-METHOD

Install BMAD's agent skills into your project:

npx bmad-method install

This creates the _bmad/ directory with BMAD's agent personas and workflow templates. You only need this for planning with BMAD agents and for the /speclan:to-bmad command. The other two commands (from-bmad and to-bmad-prd) work without BMAD skills installed.

SPECLAN Plugin

Install the plugin through the cc-marketplace:

/plugin marketplace add thlandgraf/cc-marketplace
/plugin install speclan@digital-dividend-marketplace

See the plugin overview for detailed installation instructions and scope options.

Importing BMAD Artifacts (`/speclan:from-bmad`)

This command reads your BMAD planning artifacts and builds the corresponding SPECLAN hierarchy.

What It Reads

The converter looks in your _bmad-output/planning-artifacts/ directory for:

PRD -- Capability Areas, Functional Requirements, Non-Functional Requirements, Success Criteria, Product Scope
Epics document -- Epic Stories, User Stories, BDD Acceptance Criteria, FR Coverage Map, Architecture-derived requirements (AR#), UX-derived requirements (UX#)
Architecture Document -- Architecture requirements and decisions

You do not need all three. The converter works with whatever artifacts it finds -- a PRD alone is enough.

What It Produces

The converter builds a SPECLAN hierarchy from the BMAD artifacts:

speclan/
  goals/
    G-001-user-success.md           # from Success Criteria
    G-002-business-success.md
  features/
    F-1234-user-management/         # from Capability Area
      F-1234-user-management.md
      requirements/
        R-5678-user-registration/   # from FR1
          R-5678-user-registration.md
      F-2345-registration-flow/     # from Epic Story
        F-2345-registration-flow.md
    F-9012-nfr-performance/         # from NFR category
      F-9012-nfr-performance.md

All imported entities land at status: review, giving you a chance to inspect the conversion before approving anything.

Provenance Tracking

Each imported entity carries a provenance field in its frontmatter that links back to the original BMAD source:

provenance:
  source: bmad
  file: _bmad-output/planning-artifacts/prd.md
  ref: "FR3"

This field serves two purposes:

Traceability -- you can always trace a SPECLAN entity back to the BMAD artifact it came from
Re-import deduplication -- when you re-run /speclan:from-bmad after updating your BMAD artifacts, the converter matches existing entities by their provenance rather than creating duplicates. New content is merged; your manual edits to descriptions or acceptance criteria are preserved.

Running the Import

/speclan:from-bmad

The converter discovers your BMAD artifacts automatically. After it finishes, review the generated hierarchy:

/speclan:ask show all features

Check that the mapping makes sense for your project. You can adjust entity titles, descriptions, and parent-child relationships before transitioning anything to approved.

ID Generation

SPECLAN generates its own IDs (G-###, F-####, R-####) during import -- it does not reuse BMAD's FR# or Epic numbering. IDs are random and collision-checked against your existing spec repository. The original BMAD identifiers are preserved in the provenance field.

Exporting to BMAD

Two commands export SPECLAN specifications to BMAD format. Which one you use depends on whether you have BMAD installed and how you want the output produced.

Decision Guide

	`/speclan:to-bmad`	`/speclan:to-bmad-prd`
Requires BMAD skills	Yes	No
How it works	Feeds specs into BMAD's PM agent workflow	Generates PRD directly from spec data
Output style	BMAD-native, follows BMAD templates	BMAD-standard format, built by SPECLAN
Best for	Teams already running BMAD workflows	Quick PRD export without BMAD installation
Traceability	Links back to SPECLAN source files	Links back to SPECLAN source files
Quality checks	BMAD's own validation	Implementation leak detection, NFR measurement verification

`/speclan:to-bmad` -- Export via BMAD's Native PM Workflow

This command feeds your approved SPECLAN specifications into BMAD's PM agent workflow. It invokes /bmad-bmm-create-prd, and the PM agent -- "John" -- runs its full step-by-step PRD creation process using your specs as input.

The result is a BMAD-native PRD that follows BMAD's own templates and validation rules, with traceability links back to your SPECLAN source files.

/speclan:to-bmad

Use this when your team already runs BMAD workflows and you want the PRD to feel native to that ecosystem.

Requirement: BMAD skills must be installed in your project (_bmad/ directory must exist). If they are not, the command tells you to run npx bmad-method install first.

`/speclan:to-bmad-prd` -- Standalone PRD Export

No BMAD installation required. This command reads your approved SPECLAN specifications and generates a complete BMAD-standard PRD directly:

Executive Summary derived from your Goals and their vision statements
Success Criteria mapped from Goal measurable outcomes
User Journeys reconstructed from your Scenario entities
Functional Requirements with FR# numbering, grouped by Capability Area
Non-Functional Requirements with measurement methods and testable thresholds
Product Scope with phase boundaries from your Feature scope tags

/speclan:to-bmad-prd

The output includes a quality check pass that catches two categories of problems:

Implementation leaks -- technology names, architecture patterns, file paths, or framework references that do not belong in a PRD. These are flagged so you can decide whether to remove them or keep them intentionally.
NFR measurement methods -- Non-Functional Requirements with subjective or vague thresholds (like "fast" or "reliable") are flagged. Each NFR should have a concrete, testable measurement method.

Use this when you need a BMAD-format PRD for handoff or documentation but do not want to install BMAD's full agent ecosystem.

The Bridge Workflow

Here is how a full round-trip looks in practice.

1. Plan with BMAD

Start by running BMAD's PM agent to create your planning artifacts:

/bmad-bmm-create-prd

The PM agent walks you through collaborative interviews to produce a PRD with Functional Requirements, NFRs, and Success Criteria. Then decompose it into Epics and Stories. Optionally, run the Architect agent for technical decisions.

When planning is done, your _bmad-output/planning-artifacts/ directory contains the PRD, Epics document, and Architecture Document.

2. Import to SPECLAN

/speclan:from-bmad

The converter reads your BMAD artifacts and builds the SPECLAN hierarchy. Everything lands at review status. Walk through the imported entities, adjust anything that needs refinement, and transition to approved when you are satisfied:

Transition all review features under F-1234 to approved

3. Govern with SPECLAN

Now you are in SPECLAN's world. Implement against structured specs with full lifecycle tracking:

Transition features to in-development when work starts
Create change requests when approved specs need modification
Track progress through under-test to released
Use /speclan:ask to check project health at any point

4. Export Back

When stakeholders need an updated PRD -- for a review, a handoff, or a new planning cycle -- generate one from your current approved specs:

/speclan:to-bmad-prd

The exported PRD reflects the current state of your specifications, including any changes made through change requests since the original import.

Troubleshooting

No _bmad/ directory found (for /speclan:to-bmad) The /speclan:to-bmad command requires BMAD skills to be installed. Run:

npx bmad-method install

The other two commands (from-bmad and to-bmad-prd) do not require BMAD skills.

No planning artifacts found (for /speclan:from-bmad) The converter looks in _bmad-output/planning-artifacts/ for your PRD, Epics, and Architecture documents. If this directory is empty or missing, run BMAD's planning workflow first (/bmad-bmm-create-prd) to generate the artifacts.

Missing BMAD skills (for /speclan:to-bmad) If the BMAD skills directory exists but the PM workflow is not available, your BMAD installation may be incomplete. Reinstall with npx bmad-method install.

Naming conflicts during import If the converter encounters an entity with the same provenance reference as an existing SPECLAN entity, it updates the existing entity rather than creating a duplicate. If you see unexpected merges, check the provenance field in the affected entity's frontmatter to verify the source mapping is correct.

No approved specs for export Both export commands (to-bmad and to-bmad-prd) require at least some specifications at approved status or beyond. If all your specs are still in draft or review, transition them through the status lifecycle first.

Implementation language appearing in imported specs The converter strips obvious implementation references (technology names, file paths, architecture patterns) during import. If implementation language still appears in your imported specs, edit the descriptions manually -- the converter is conservative and does not remove language it is not confident is implementation-specific.