[RFC]: Support BMAD as an alternative workflow

### Summary

Collaborative AI-DLC claims its methodology is data, not code: blocks are imported and composed into workflows, and the engine is methodology-mechanism-agnostic. This RFC proposes proving that claim by authoring a second, non-AI-DLC methodology — **BMAD** ([BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD)) — as an alternative workflow (`bmad-v1`) in the Default tenant. BMAD's skills, agents, sized planning paths, and per-unit build loop map onto our existing block types (Stage, Agent, Scope, Rule, Sensor, Artifact) with mostly data authoring. **We treat the requirement-to-code traceability graph as a first-class requirement of the port, not an optional extra** — so a small, additive extension to the artifact extractor registry is in scope from the start, alongside the data authoring. A later, genuinely optional enhancement adds true per-unit parallelism beyond what BMAD itself prescribes. The deliverable is both a working demo of methodology-agnosticism and a documented mapping others can follow to onboard further methodologies. This RFC is written against BMAD's own documentation; the notable finding is that BMAD is *less* linear-DAG-shaped and *more* persona- and module-centric than a first glance suggests, which sharpens both the mapping and its honest limits.

### Motivation

- **Substantiate the core architectural claim.** Our docs state the AI-DLC methodology "is not hard-coded... it is imported as data — a library of building blocks." Today the only shipped baseline is `aidlc-v2`. Hosting a genuinely different, well-known methodology is the strongest possible evidence — for enterprise customers evaluating the platform — that they can bring or tailor their own process.
- **Exercise the extensibility surface for real.** Authoring `bmad-v1` end-to-end surfaces exactly which parts of block/workflow authoring are pure data and which are still AI-DLC-shaped, turning implicit assumptions into a tracked list.
- **BMAD is a good fit and an instructive contrast.** It shares our spine (spec → decompose → build per unit → review) yet differs in philosophy (LLM-as-executor, durable personas, ordered-not-parallel stories, multi-module), so the mapping teaches us where our engine is opinionated.

### Detailed design

### What BMAD is (relevant shape, per its docs)

BMAD ships as markdown **skills** an LLM reads and obeys — there is no runtime engine; ordering and HALTs are prose instructions. Relevant objects:

- **Skills** — named workflows/tasks producing typed documents. Two implementation skills matter and are **distinct**: `bmad-build` is the *interactive, human-checkpointed* single-unit skill; `bmad-build-auto` is the *unattended worker* for one session-sized unit. Neither iterates a backlog — the docs are explicit: *"`bmad-build` handles one unit. It does not own the backlog, pick the next story"* and *"Build Auto does not choose the next story, repeat across a backlog, coordinate epics, or run a retrospective."* Backlog dispatch is an orchestrator/human role.
- **Agents** — durable, named personas: Mary (Analyst), John (PM), Winston (Architect), Sally (UX), Amelia (Dev). Identity is *immutable by design* (`agent.name`/`agent.title` are not overridable; renaming requires forking the skill). Paige (Technical Writer) is documented but on hiatus; a full Test Architect (Murat) ships in the separate **TEA** module.
- **Modules** — BMAD is **multi-module** (`core`, `bmm`, plus official add-ons `tea`, `cis`, `gds`, and `bmb` the BMad Builder that authors new modules). Our port targets the **`bmm`** module (the Agile method); the others are out of scope.
- **Sized planning paths** ([Size follows the intent](https://docs.bmad-method.org/plan/choose-a-planning-path/#size-follows-the-intent)) — same implementation unit, more shared context as work grows: **well-defined/one-session** (`bmad-spec` → one build), **epic** (`bmad-spec` → Story Breakdown → build per story → retrospective), **project** (full planning → `bmad-spec` per epic → stories → per-epic retrospective).
- **The machine coordination contract is the spec `status` frontmatter**: `draft / ready-for-dev / in-progress / in-review / done / blocked`, with a fixed resume-routing table (`ready-for-dev`→implement, `in-review`→review, `blocked`→halt). Orchestrators are told to read `status` rather than infer success from chat.

### Convergences (map cleanly, pure data)

| BMAD | Collaborative AI-DLC | Notes |
| --- | --- | --- |
| `bmm` module | A **Workflow** (`bmad-v1`, Default tenant) | One workflow, versioned/pinned per intent |
| Skill (workflow) | **Stage** block | Skill instructions become the stage `body` |
| Agent persona | **Agent** block, set as stage `leadAgent` | Mary/John/Winston/Sally/Amelia (per-stage, see divergences) |
| Planning phases (Analysis→Planning→Solutioning) | Workflow **phase tree** nodes | Inline phases |
| **Sized paths** (well-defined / epic / project) | Three **Scope** blocks + per-stage `EXECUTE/SKIP` membership | The pivotal convergence — see below |
| `bmad-build-auto` "one unattended unit" | The per-unit body of a construction stage | The *worker*; the loop is the engine's job |
| Spec `status` lifecycle | Per-unit lane state | `draft/ready-for-dev/in-progress/in-review/done/blocked` map onto lane states + resume entry points |
| Five BMAD sign-off gates (below) | `humanValidation: required` gates | Direct, high-fidelity match on the human axis |
| `bmad-review` routed findings | Stage `reviewer` (emits dispositions, not pass/fail) | See semantics below |
| `bmad-retrospective` verdict | A **fan-in stage** with a real gate verdict | `accepted / accepted-with-open-items / rejected` |
| Elicitation checkpoints | agent `ask_question` + gates | Park at zero compute |
| `customize.toml` base→team→user overrides | **Rule** blocks (layered org→team→project) | Partial — behavior tweaks, not identity/structure |

**Scopes are the pivotal convergence.** BMAD's "size follows the intent — every path uses the same implementation unit; larger work adds shared context and repeats it" is exactly our scope model: **one workflow projected through a scope decides which stages `EXECUTE`**. Three scopes — `change`, `epic`, `project` — map onto the three BMAD paths, so one `bmad-v1` workflow serves a one-session change through a greenfield project with no branching workflows.

**Five human sign-off gates map directly onto our human-validation axis.** BMAD's "Plan inside an organization" names five gates, each blocking something specific — a near-perfect fit for `humanValidation: required` stages: (1) **PRFAQ verdict** → blocks writing the PRD; (2) **PRD validate** → blocks design/architecture; (3) **architecture spine review** → blocks writing specs; (4) **readiness gate** (`bmad-sprint-planning`, PASS/CONCERNS/FAIL) → blocks generating sprint tracking / entering construction; (5) **retrospective verdict** → blocks starting the next epic.

**Review semantics — corrected.** `bmad-review`/`bmad-code-review` does **not** emit a numeric pass/fail verdict. It runs four parallel lenses (`blind-hunter`, `edge-case-hunter`, `verification-gap`, `acceptance-auditor`), then triages each finding to **patch**, **defer**, or **decision needed** — and *"decision needed"* (the only human gate it raises) is used **only when a spec is present**. So model it as a **reviewer that emits dispositions**, with a conditional human gate — not an unconditional verdict. The one skill that emits a branchable verdict is `bmad-retrospective` (`accepted / accepted-with-open-items / rejected`, with `rejected` forced by any unfinished story, human-overridable).

### Divergences (philosophy or code)

1. **Stories are an ordered list, not a dependency DAG — this is the load-bearing correction.** BMAD's `stories.yaml` is an **ordered inventory**; its optional `bmad-loop` orchestrator is *"a linear scheduler: it does not infer a dependency graph. Arrange the list so each story's prerequisites appear first."* There are no `depends_on` edges. BMAD's genuine **parallelism unit is the epic** (several engineers each take an epic; *"the architecture spine is what makes that safe"*), and *"engineering still implements one Build session at a time."* Consequence: our `forEach: unit-of-work` fan-out, which schedules a **dependency DAG** of concurrent per-unit lanes, is **richer than BMAD prescribes**. Mapping stories to unit lanes is valid, but the per-unit *dependency DAG and concurrency* would be a **collaborative-ai-dlc addition on top of BMAD**, not a faithful mapping of an existing BMAD structure. The core deliverable therefore runs BMAD stories as an **ordered sequence** (single lane, topological by list position), which is the honest mapping; per-unit parallelism is an optional enhancement we consciously layer on.
2. **Durable personas are a first-class BMAD feature we do not replicate.** BMAD identity is immutable, name-addressable across turns, and `bmad-party-mode` runs multiple personas as *independent, mutually-aware reasoners with cross-session memory* (explicitly, *"one model voicing five personas tends to make them agree; separate agents keep their reasoning independent"*). We attach a persona **per stage** as `leadAgent` — no durable cross-stage chat identity, no party-mode. This is a real, deliberate loss (not a non-issue), acceptable for a *workflow-level* methodology-agnosticism demo but worth stating plainly.
3. **Engine vs. no engine.** We compile a topologically-ordered plan and the engine owns flow, git, gates, sensors, and lane scheduling; BMAD trusts the LLM to obey prose and delegates dispatch to a human/orchestrator. Porting *gains* enforcement and *loses* BMAD's free-form latitude.
4. **Non-linear analysis tools.** BMAD's "get to a well-defined intent" tools (`brainstorming`, `forge-idea`, `deep-recon`, `product-brief`, `prfaq`) run in any order and none build. We model them as `execution: CONDITIONAL`, human-gated Analysis stages selected per intent (via scope membership / *Compose with AI*) — imposing explicit selection where BMAD leaves it ad hoc.
5. **Artifact traceability (handled in scope, not deferred).** By default BMAD artifacts (`SPEC.md`, `stories.yaml`, `sprint-status.yaml`, `ARCHITECTURE-SPINE.md`) would land as flat markdown sections with no typed graph nodes/edges. Because traceability is a core requirement of this port, the deliverable **extends the extraction registry** (`lambda/shared/artifact-extractors.js`) so these derive typed nodes and edges (requirement → story → unit → code → review) — additive to, and not disturbing, the existing AI-DLC extractors.
6. **AI-DLC-shaped constants.** Fan-out is hardcoded to `forEach: 'unit-of-work'` consuming an artifact literally named `unit-of-work-dependency` (`lambda/shared/v2-execution-plan.js`); `PHASE_ORDER` in `lambda/shared/block-mappers.js` is fixed; the seed importer (`buildFromFiles`) expects the `awslabs/aidlc-workflows` layout.

### Proposed workflow shape (`bmad-v1`)

Phases **Analysis → Planning → Solutioning → Construction**, ~13 stages, 5 agent blocks, 3 scopes. Construction runs stories as an **ordered sequence** by default (see divergence 1).

| Stage (BMAD skill) | Phase | Lead role | Produces | Execution | change / epic / project |
| --- | --- | --- | --- | --- | --- |
| brainstorming | Analysis | Analyst | `brainstorm.md` | CONDITIONAL | – / – / opt |
| forge-idea | Analysis | Analyst | `forged-idea.md` | CONDITIONAL | – / – / opt |
| deep-recon | Analysis | Analyst | `research.md` | CONDITIONAL | – / opt / opt |
| product-brief | Analysis | Analyst | `brief.md` | CONDITIONAL | – / opt / opt |
| prfaq | Analysis | Analyst | `prfaq.md` + verdict **gate** | CONDITIONAL | – / – / opt |
| prd | Planning | Product Manager | `prd.md` + validate **gate** | CONDITIONAL | – / opt / EXECUTE |
| ux | Planning | UX Designer | `DESIGN.md`, `EXPERIENCE.md` | CONDITIONAL | – / opt / opt |
| spec | Planning | Developer | `SPEC.md` (+ `stories.yaml` on breakdown) | EXECUTE | EXECUTE / EXECUTE / EXECUTE |
| architecture | Solutioning | Architect | `ARCHITECTURE-SPINE.md` + spine-review **gate** | CONDITIONAL | – / opt / EXECUTE |
| epics-and-stories | Solutioning | Product Manager | epics + `stories.yaml` (ordered) | CONDITIONAL | – / EXECUTE / EXECUTE |
| sprint-planning | Solutioning | Developer | `sprint-status.yaml` + readiness **gate** (PASS/CONCERNS/FAIL) | CONDITIONAL | – / EXECUTE / EXECUTE |
| build | Construction | Developer | code per unit (worker = `bmad-build-auto`; foundational units use `bmad-build`) | per-story, ordered | EXECUTE (once) / per story / per story |
| retrospective | Construction | Developer | `RETROSPECTIVE.md` + verdict **gate** (accepted/…/rejected) | CONDITIONAL | – / EXECUTE / EXECUTE |

The `change` scope collapses to `spec → build` (straight from spec to build); `epic` adds story breakdown + per-story build + retro; `project` adds full planning + architecture. Per-unit **lane state uses BMAD's `status` values** and honors its resume entry points.

### Delivery plan

**Core deliverable — the `bmad-v1` workflow with traceability.** Two parts, done together:

- **(1) Author the methodology as data** — `bmad-v1` + all `bmm` blocks via the building-blocks/workflows API. Construction runs stories as an **ordered sequence** (topological by list position, matching BMAD). Wire the five sign-off gates on the human axis; model review as a reviewer emitting dispositions; model retrospective as a fan-in verdict gate.
- **(2) Preserve requirement-to-code traceability** — extend `lambda/shared/artifact-extractors.js` with `Epic`/`Story`/`SprintStatus` (and any other BMAD-specific) extractors so BMAD artifacts derive typed graph nodes and edges (requirement → story → unit → code → review) instead of landing as flat markdown. This is a **required** part of the port: the traceability graph is a headline platform capability and must survive a methodology swap, which is itself the strongest proof that traceability is methodology-independent. The change is additive (new artifact types; existing AI-DLC extraction untouched).

Known losses that remain and are accepted for this demo: per-stage (non-durable) personas, no party-mode, and single-lane (non-parallel) construction.

**Optional enhancement — true per-unit parallelism.** If we want concurrent per-unit lanes *beyond* what BMAD prescribes (BMAD is epic-parallel, story-sequential), have `epics-and-stories` emit a real dependency artifact — either reusing the `unit-of-work-dependency` name to drive the existing `forEach` fan-out, or generalizing the `UNIT_*` constants and `PHASE_ORDER`. This is explicitly an enhancement over BMAD, not a fidelity fix, and can follow the core deliverable.

### Alternatives considered

- **Model stories as a per-unit dependency DAG with parallel lanes by default.** Rejected as the default: BMAD prescribes an *ordered list* and epic-level (not story-level) parallelism, so a per-story DAG would misrepresent the methodology. Kept as an opt-in enhancement, clearly labelled as our addition.
- **Ship BMAD via its own seed importer.** Rejected: `buildFromFiles` is shaped for the `aidlc-workflows` layout and BMAD skills are prose-for-an-LLM, not our block frontmatter. Authoring blocks directly via the existing API is the intended custom-methodology path.
- **A separate workflow per BMAD size.** Rejected: duplicates stages, risks config drift; scopes exist precisely to project one workflow onto sizes, matching BMAD's "same unit" framing.
- **Replicate durable personas + party-mode + multi-module.** Out of scope: faithfully reproducing immutable name-addressable identities, independent-reasoner party-mode with cross-session memory, and BMAD's module system is a large platform change orthogonal to demonstrating *workflow-level* methodology-agnosticism. We document the loss rather than engineer around it.
- **Do nothing / keep AI-DLC only.** Rejected: leaves the methodology-agnostic claim unproven for evaluators.

### Breaking changes

None for existing users. `bmad-v1` and its blocks live in the **Default tenant** alongside `aidlc-v2`; the SYSTEM baseline is untouched and running intents pin their own workflow version. No API, schema, or migration changes for the data authoring.

The core deliverable touches one shared file — `lambda/shared/artifact-extractors.js` — but only additively: new BMAD artifact types register alongside the existing AI-DLC ones, and AI-DLC extraction is unchanged and must stay green under the existing tests. The optional per-unit-parallelism enhancement, if pursued, touches `v2-execution-plan.js` / `block-mappers.js` (the `UNIT_*` constants and `PHASE_ORDER`) and must preserve current AI-DLC behavior under regression tests before it can be considered non-breaking.

### Open questions

**Construction ordering:** ship the core deliverable as a strict ordered sequence (faithful to BMAD), or pull the optional per-unit-parallelism enhancement into the first milestone because per-unit lanes are a headline platform capability worth showing off?
- **Scope granularity:** are three scopes (`change`/`epic`/`project`) the right cut, or should a `bugfix`-like small scope be distinct from `change`?
- **Agent tiers:** which of our `judgment`/`balanced`/`templated` tiers do the five roles (Analyst / Product Manager / Architect / UX Designer / Developer) map to, and do any warrant a `modelOverride`? (BMAD skills expose Fast vs. Coaching modes that hint at tier.)
- **Persona fidelity:** is per-stage `leadAgent` an acceptable representation of BMAD's durable personas for the demo, or do we want a follow-up RFC exploring durable persona identity as a platform feature?
- **Review/gate mapping:** does our reviewer axis cleanly express BMAD's *disposition* model (patch/defer/decision-needed) and the spec-conditional human gate, or do we approximate it as reviewer + human gate?
- **Retrospective fan-in:** does the existing reviewer/gate machinery cover the epic-level "verify stories together, weight the seams" step, or is a dedicated fan-in stage type needed?
- **Extractor coverage:** which BMAD artifacts warrant typed extractors beyond `Epic`/`Story`/`SprintStatus` (e.g. the architecture spine's stable decision IDs → `Decision` nodes; capability IDs in `SPEC.md` → `Requirement` nodes), to get the fullest requirement-to-code graph?
- **Naming/attribution:** BMAD is trademarked/third-party — confirm acceptable framing and attribution for shipping a `bmad-v1` sample workflow (and which BMAD version the port pins to).

Start by reading lambda/shared/artifact-extractors.js, lambda/shared/v2-execution-plan.js, lambda/shared/block-mappers.js, and the seed importer's buildFromFiles path. Define the bmad-v1 workflow and its ordered construction flow, add typed extraction for the named BMAD artifacts without disturbing existing extractors, and document the mapping and its limits.

Written by the indexing model from the issue text.