Proposal: Change Set–level workflows and UX for BMAD Method (OpenSpec-style feature layer)

[yusuftok]

1. Background and current limitation

BMAD/BMM today has a very strong project‑level spine:

• bmm-workflow-status.yaml + workflow-status:
  • Track which method workflows (document‑project, PRD, architecture, epics & stories, sprint‑planning, dev‑story, etc.) are done/pending.
  • Answer project‑level “Where am I / what should I do next?” very well.
• Implementation phase is sprint‑ and story‑centric:
  • sprint-status.yaml tracks epics and stories across sprints.
  • Agents (PM, Analyst, Architect, SM, Dev, Quick Flow Solo Dev) have menus wired to the right project‑level workflows.

What is missing today is a first‑class, feature / change‑set level view of the method:

• There is no explicit concept of a Change Set or feature package that:
  • Groups analysis, PRD delta, architecture delta, epics/stories, and implementation status for a specific change.
• There is no “Where am I?” at Change Set level:
  • You cannot easily ask “For this feature/change, which BMM phases are done, how many stories are done, what’s next?”.
• Parallel features are only visible indirectly:
  • sprint-status.yaml can contain stories for multiple features, but there’s no stable key to group them beyond epics.
  • You can’t maintain clean, per‑feature workspaces and then merge them back into Source of Truth in a deterministic way.
• UX‑wise:
  • Agents expose strong project‑level flows, but they don’t surface a clear, repeatable feature/change set layer that mirrors the project method.

In practical terms, BMAD is great at “project spine + sprints + stories”, but there’s no explicit OpenSpec‑style “source + change + apply” story for features.

2. Goals

The proposal is to add an optional, additive Change Set layer on top of BMM that:

1. Introduces a feature/change Set concept that works alongside existing project‑level workflows.
2. Cleanly separates:
   • Project‑level Source of Truth (SoT) docs (PRD, architecture, epics, sprint-status, workflow-status),
   • From Change Set artifacts (scoped analysis/PRD/architecture/epics/stories/status for a given feature).
3. Provides a deterministic Apply/Merge workflow:
   • At the end of a Change Set, merge accepted deltas into SoT with a recorded main‑branch commit SHA.
4. Supports parallel work:
   • Multiple Change Sets in the same project,
   • Multiple agents working concurrently on different Change Sets,
   • No global “single active change set” stored in config.
5. Keeps everything zero‑breaking:
   • If no Change Set context is used, BMAD behaves exactly as today.

3. Concept and data model

At a high level:

• {output_folder} remains the project‑level BMAD docs root (often docs/).
• Under it, we introduce a new subtree:

{output_folder}/
prd/...
architecture/...
epics/...
sprint-status.yaml
bmm-workflow-status.yaml
...
changes/
index.yaml
{change-id-1}/
changeset.config.yaml
changeset-status.yaml
... (feature-level outputs)
{change-id-2}/
...
archive/
{change-id-x}/...

Key files:

• changes/index.yaml
  • Catalog of all Change Sets:
    • id, slug, title, status, owner, tags,
    • Paths to changeset.config.yaml / changeset-status.yaml.
  • Derived from the per‑Change Set config/status files; can be regenerated.
• changes/{id}/changeset.config.yaml
  • Static/semi‑static configuration and context:
    • changeset_id, slug, title,
    • context_type: changeset, project_root, Change Set specific output_folder,
    • project_level, planning_track,
    • workflows relevant to this Change Set (e.g. document‑project, create‑prd, create‑architecture, create‑epics‑and‑stories),
    • source_refs (PRD sections, architecture sections, epic ids) that will be impacted.
• changes/{id}/changeset-status.yaml
  • Dynamic state:
    • status: draft | in-progress | ready-for-apply | applying | applied | abandoned,
    • phase_status mirroring BMM phases: analysis, planning, solutioning, implementation,
    • epic_links, story_links, sot_refs,
    • lifecycle:
      • applied_in_commit (required for applied),
      • applied_scope per corpus (none | partial | full).
• sprint-status.yaml
  • Stories extended with a change_id field:
    • Each story belongs to at most one Change Set.
    • A Change Set can span multiple stories and multiple sprints.
    • This is how implementation progress for a Change Set is derived.

4. Engine integration (workflow.xml)

The BMAD core workflow engine (core/tasks/workflow.xml) gets an optional Change Set context layer:

• At the very start of Step 1:
  • Detect changeset-context (parameter) or session‑level active_changeset.
  • If present:
    • Compute {changeset_path},
    • Load {changeset_path}/changeset.config.yaml,
    • Expose changeset.* variables,
    • Set working_in_changeset = true.
  • If not present:
    • Continue with current project‑level behavior.
• During config resolution:
  • Phase 1: load project config from config_source (unchanged).
  • Phase 1.5 (new, if working_in_changeset):
    • Override {output_folder} with changeset.output_folder.
    • All other variables resolve from project‑level config unless explicitly overridden.
  • Phases 2–4: unchanged.

This means:

• Existing BMM workflows (PRD, architecture, epics/stories, sprint‑planning, dev‑story, Quick Flow, etc.) can be “scoped” to a Change Set just by running them with a changeset-context.
• No separate “Change Set versions” of every workflow are required.

5. New BMM workflows for Change Sets

Four small BMM workflows implement the Change Set lifecycle at method level:

1. changeset-init
   • Initialize a new Change Set under {output_folder}/changes/{change-id}/:
     • Ask for slug (+ optional title/description/track info),
     • Compute changeset_id,
     • Create changeset.config.yaml + changeset-status.yaml,
     • Ensure changes/index.yaml exists and append this Change Set.
2. changeset-switch
   • Switch session context between:
     • Project‑level (no Change Set),
     • A specific Change Set (by id or menu from index.yaml).
   • Maintains session‑level active_changeset only:
     • Never writes any global “active change set” into project config.
3. changeset-status
   • For a given Change Set:
     • Load changeset-status.yaml (+ changeset.config.yaml),
     • If sprint-status.yaml exists:
       • Filter stories by change_id,
       • Derive stories_total/done/in_progress/blocked,
       • Update phase_status.implementation and last_synced_from_sprint_status_at.
   • Outputs:
     • Human‑readable summary: status, phases, implementation metrics, lifecycle.
     • Template outputs for other workflows/agents:
       • change_id, changeset_status, changeset_phase_status, changeset_lifecycle,
       • stories_* counts,
       • recommended_workflows: list of { id, agent, alt_agent?, command, reason }.
   • Functionally acts as the Change Set router, analogous to workflow-status at project level.
4. changeset-apply
   • Apply a Change Set to SoT when ready:
     • Validate status and phase_status,
     • Use source_refs to find affected PRD/architecture/epics sections,
     • Load SoT docs + Change Set delta docs,
     • Guide a human‑in‑the‑loop merge,
     • Ask for main‑branch commit SHA (applied_in_commit),
     • Update changeset-status.yaml and changes/index.yaml,
     • Optionally move to changes/archive/.

These workflows are small and contained; they don’t change the behavior of existing BMM flows unless explicitly invoked.

6. Agent & UX integration

The Change Set layer is surfaced through existing BMM agents rather than entirely new personas. In the prototype, I wired it as follows:

• High‑priority Change Set–aware agents:
  • PM, Analyst, Architect, UX Designer,
  • SM, Dev, Quick Flow Solo Dev.
• Agent menus (conceptually):
  • PM / Analyst / Architect:
    • changeset-init – Start a new feature Change Set.
    • changeset-switch – Switch between project context and a Change Set.
    • changeset-status – Show lifecycle + phase + story progress.
    • changeset-apply – Apply a ready Change Set to SoT (PM/Architect oriented).
  • UX Designer:
    • changeset-switch, changeset-status (works within Change Sets created by PM/Analyst/Architect).
  • SM:
    • changeset-switch, changeset-status (so sprint planning / story creation can respect Change Set context).
  • Dev:
    • changeset-switch, changeset-status (execute stories under the right Change Set).
  • Quick Flow Solo Dev:
    • changeset-init, changeset-switch, changeset-status, changeset-apply.
    • Rationale:
      • Quick Flow track is explicitly designed so that a solo developer can take a small feature from idea to production.
      • In this mode, it’s reasonable for the Quick Flow dev to also run changeset-apply, with the usual safety nets (confirmations, commit SHA capture).
• UX-wise, this gives:
  • A project-level “Where am I?” via workflow-status + bmm-workflow-status.yaml.
  • A Change Set–level “Where am I?” via changeset-status + changeset-status.yaml + sprint-status.yaml + changes/index.yaml.