Bidirectional BMAD ↔ SPECLAN conversion — mapping reference and round-trip behavior

[thlandgraf]

I build a spec management tool called SPECLAN (full disclosure: I'm the creator) and I just shipped bidirectional conversion between BMAD artifacts and SPECLAN's entity hierarchy. Thought it was worth sharing the mapping decisions here since some of them required interpretation of BMAD's structure that the community might have opinions on.

Context: SPECLAN manages specifications as a tree of Markdown files with YAML frontmatter in Git — goals, features, requirements, acceptance criteria — with status lifecycle tracking (draft through released) and change request management. BMAD and SPECLAN solve adjacent problems: BMAD produces structured planning artifacts through agent-facilitated workflows, SPECLAN governs what happens after planning — which specs are approved, what changed, what's ready for implementation.

The conversion is implemented as a Claude Code plugin (open source) — three skill commands handle the bridge.

Import (/speclan:from-bmad)

The converter reads your _bmad-output/planning-artifacts/ directory and maps 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
Epic Stories / User Stories	Child Features (F-####)	User Story format preserved in description
BDD Acceptance Criteria (Given/When/Then)	AC 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	From Architecture Documents
UX Requirements (UX#)	Requirements under UX Features	From Epics document

A few non-obvious decisions in the mapping:

FR Coverage Map authority. When both a PRD and an Epics document exist, the converter uses BMAD's FR Coverage Map — the table that maps each FR to its Epic — rather than guessing which requirements belong where from section headings. This felt like the right default since the Coverage Map is BMAD's own authoritative grouping.

Developer-infrastructure reclassification. FRs where the actor is "Project" or "Build system" (e.g., FR8: Project can lint and format code automatically) are not user-facing behavior. The converter reclassifies these as NFRs under a Code Quality feature. The reasoning: the spec hierarchy should represent what users experience, and build tooling requirements are closer to NFRs than FRs.

Implementation stripping. BMAD artifacts often contain technology names, architecture patterns, and file paths — useful context during planning, but specifications should 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 stays in your Architecture Document where it belongs.

Provenance tracking

Every imported entity carries a provenance field in its frontmatter:

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

This enables re-import: if you update your BMAD artifacts and run the import again, the converter matches existing entities by provenance rather than creating duplicates. Manual edits you made in SPECLAN survive the re-import. All imported entities land at status: review so you can inspect the conversion before approving anything.

Export

Going the other direction, /speclan:to-bmad feeds approved specs into BMAD's own PM workflow (/bmad-bmm-create-prd). The PM agent produces a BMAD-native PRD following BMAD templates, with traceability links back to SPECLAN source files. There's also /speclan:to-bmad-prd for a standalone BMAD-format PRD without needing BMAD installed — useful for handoff or documentation.

Round-trip

The full workflow is: plan with BMAD, import to SPECLAN (review status), govern lifecycle in SPECLAN (approve, develop, track changes), export back when stakeholders need an updated PRD. IDs are regenerated (SPECLAN uses its own patterns) but provenance maintains the link to BMAD source artifacts.

I'm especially interested in feedback on the mapping decisions — particularly the FR Coverage Map authority choice and the developer-infrastructure reclassification. If any of these feel wrong to BMAD practitioners, I'd rather adjust them now.