ma-agents 3.4.9 → 3.5.0

package/_bmad-output/implementation-artifacts/done/11-1-auto-bug-detection-skill.md

@@ -0,0 +1,119 @@
+# Story 11.1: Create auto-bug-detection Skill
+
+Status: review
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As a **Chief Architect**,
+I want an auto-bug-detection skill that instructs agents to identify and report defects in already-delivered code,
+So that bugs are caught proactively during all agent sessions.
+
+## Acceptance Criteria
+
+1. **Given** the skill is authored,
+   **When** installed via ma-agents,
+   **Then** skills/auto-bug-detection/skill.json exists with always_load: true,
+   **And** SKILL.md contains detection criteria and reporting instructions
+
+2. **Given** the skill is loaded via critical_actions,
+   **When** agent encounters a defect in delivered code,
+   **Then** skill directives instruct agent to report using structured format,
+   **And** skill distinguishes between bugs in delivered code vs work-in-progress
+
+3. **Given** skill follows standard schema,
+   **When** validated,
+   **Then** it passes all existing skill validation rules
+
+4. **Given** SKILL.md detection criteria are authored,
+   **When** a reviewer examines the skill content,
+   **Then** SKILL.md includes at least 6 distinct defect categories (logic errors, unhandled edge cases, missing error handling, broken contracts, regressions, security vulnerabilities),
+   **And** each category includes at least one concrete example of what qualifies as that defect type,
+   **And** "What NOT to Flag" section explicitly covers committed feature-branch code tied to in-progress stories
+
+## Tasks / Subtasks
+
+- [x] Task 1: Create skill directory and skill.json (AC: #1, #3)
+  - [x] 1.1: Create directory `skills/auto-bug-detection/`
+  - [x] 1.2: Create `skills/auto-bug-detection/skill.json` with: `{ "name": "auto-bug-detection", "version": "1.0.0", "description": "Instructs agents to identify and report defects in already-delivered code", "category": "workflow", "tags": ["bug-detection", "quality"], "always_load": true }`
+  - [x] 1.3: Validate skill.json passes existing validation rules (matches schema with name, version, description, category, tags, always_load)
+
+- [x] Task 2: Author SKILL.md with detection criteria (AC: #1, #2)
+  - [x] 2.1: Create `skills/auto-bug-detection/SKILL.md` with a clear title and purpose section
+  - [x] 2.2: Add "Detection Scope" section defining scope boundaries:
+    - **Delivered code:** Code whose associated story/task is marked done/completed, regardless of branch. This includes committed code on main, release branches, and feature branches whose parent story is completed.
+    - **Work-in-progress:** Uncommitted changes in the working tree; committed code on a branch whose associated story is still in-progress or not-started; TODO/FIXME markers in code added as part of the current story under review.
+    - **Ambiguous boundary — feature branches:** Committed code on a feature branch where the story status is unknown must be treated as WIP. Agents must check story status before classifying. When story status cannot be determined, default to WIP and do NOT flag as a bug.
+  - [x] 2.3: Add "Detection Criteria" section listing categories of defects to detect: logic errors, unhandled edge cases, missing error handling, broken contracts, regressions, security vulnerabilities in existing code
+  - [x] 2.4: Add "Reporting Format" section with structured template: title, severity (critical/high/medium/low), affected component, reproduction steps, expected behavior, actual behavior, affected files
+  - [x] 2.5: Add "What NOT to Flag" section: work-in-progress code, TODO/FIXME comments in current work, incomplete implementations in active stories, style preferences
+  - [x] 2.6: Add "Recommended Action" section instructing agents to recommend using the `create-bug-story` workflow to formally log detected bugs
+
+- [x] Task 3: Verify skill integration (AC: #1, #3)
+  - [x] 3.1: Run `node bin/cli.js install` for a supported agent and verify auto-bug-detection skill content appears in injected instructions
+  - [x] 3.2: Confirm always_load: true causes the skill to be included in critical_actions for all agent sessions
+
+## Dev Notes
+
+### Architecture Compliance
+
+- **Standard skill pattern:** Follows the exact same structure as existing skills (skill.json + SKILL.md)
+- **No code changes to installer:** The existing installer already handles always_load: true skills — no modifications to lib/installer.js needed
+- **No new dependencies:** Pure content — skill.json metadata and SKILL.md directives only
+- **Schema compliance:** skill.json uses all required fields (name, version, description, category, tags, always_load)
+
+### Shared Guardrails
+
+See `_bmad-output/implementation-artifacts/epic-11-12-shared-guardrails.md` for universal constraints shared across all Epic 11 & 12 stories.
+
+### Critical Guardrails (story-specific)
+
+- Do NOT add any new npm dependencies
+- Do NOT modify lib/installer.js, lib/agents.js, or lib/bmad.js
+- Do NOT create agent-specific templates unless truly needed — start with just skill.json + SKILL.md
+- Do NOT flag work-in-progress code as bugs — the SKILL.md must clearly distinguish delivered vs in-progress
+- Do NOT introduce a new skill schema field — use only existing fields
+
+### Project Structure Notes
+
+- **Files to create:**
+  - `skills/auto-bug-detection/skill.json`
+  - `skills/auto-bug-detection/SKILL.md`
+- **No files to modify** — existing installer handles always_load skills automatically
+
+### References
+
+- [Source: skills/code-review/skill.json] — Example skill.json for pattern reference
+- [Source: skills/code-review/SKILL.md] — Example SKILL.md for content structure reference
+- [Source: lib/installer.js] — Installer logic for always_load skill handling (no changes needed)
+
+## Dev Agent Record
+
+### Agent Model Used
+
+claude-sonnet-4-6
+
+### Debug Log References
+
+- Verified valid skill categories from `lib/skill-authoring.js`: `['security', 'architecture', 'testing', 'documentation', 'workflow', 'language']`
+- Confirmed `always_load: true` handling in `lib/installer.js` line 125 — written to MANIFEST.yaml during install
+- Task 3.1 verification: `node bin/cli.js validate-skill auto-bug-detection` output: `VALID: auto-bug-detection` with `Always Load: true`
+- Full test suite: all passed, no regressions
+
+### Completion Notes List
+
+- Created `skills/auto-bug-detection/skill.json` with all required fields, `category: "workflow"`, `always_load: true`
+- Created `skills/auto-bug-detection/SKILL.md` with: Purpose, Detection Scope (delivered/WIP/ambiguous boundary), Detection Criteria (6 categories with concrete examples each), Reporting Format (structured template with severity guidelines), What NOT to Flag (WIP, TODOs, style), Recommended Action (create-bug-story workflow)
+- `node bin/cli.js validate-skill auto-bug-detection` → `VALID` with `Always Load: true`
+- Installer injects skills marked `always_load: true` into MANIFEST.yaml; agent instructions already say "Always load skills marked with always_load: true" — no code changes required
+- Full test suite passed with 0 regressions
+
+### File List
+
+- `skills/auto-bug-detection/skill.json` (created)
+- `skills/auto-bug-detection/SKILL.md` (created)
+
+## Change Log
+
+- 2026-03-19: Story 11.1 implemented — created auto-bug-detection skill (skill.json + SKILL.md). All ACs satisfied, validation passes, no regressions.

package/_bmad-output/implementation-artifacts/done/11-2-bug-story-extension-workflow.md

@@ -0,0 +1,132 @@
+# Story 11.2: Create Bug Story Extension Workflow
+
+Status: review
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As a **Scrum Master**,
+I want a BMAD extension workflow that creates structured bug stories from detected defects,
+So that bugs enter the backlog with consistent format.
+
+## Acceptance Criteria
+
+1. **Given** create-bug-story workflow exists in lib/bmad-extension/workflows/create-bug-story/workflow.md,
+   **When** invoked via BMAD agent menu or slash command (NFR19),
+   **Then** it guides creating a bug story with: title, reproduction steps, expected vs actual, severity, affected component
+
+2. **Given** a bug story is created,
+   **When** saved,
+   **Then** it exists as standalone backlog item alongside user stories (FR64),
+   **And** follows consistent template format,
+   **And** output file contains YAML frontmatter as the very first lines of the file in the format:
+   ```
+   ---
+   type: bug
+   severity: <critical|high|medium|low>
+   title: <bug title>
+   ---
+   ```
+
+3. **Given** workflow registered in module-help.csv,
+   **When** BMAD agent loads extension module,
+   **Then** workflow appears in available workflows
+
+4. **Given** a bug story file exists at `_bmad-output/implementation-artifacts/bug-{slug}.md`,
+   **When** sprint workflows (add-to-sprint, sprint-status-view) scan for backlog items,
+   **Then** they can discover bug stories via glob `_bmad-output/implementation-artifacts/bug-*.md`,
+   **And** parse the `type` and `severity` fields from YAML frontmatter,
+   **And** present bug stories as peers to user stories in flat backlog views (FR65)
+
+## Tasks / Subtasks
+
+- [x] Task 1: Create extension module scaffolding — **Story 11.2 is the authoritative owner of this scaffolding** (AC: #3)
+  - [x] 1.1: Create `lib/bmad-extension/` directory
+  - [x] 1.2: Create `lib/bmad-extension/module.yaml` with content: `extends-module: bmm`
+  - [x] 1.3: Create `lib/bmad-extension/module-help.csv` with header row: `name,command,description,phase`
+  - **Note:** Story 12.1 depends on this scaffolding existing. Story 12.1 must be implemented AFTER Story 11.2. If scaffolding already exists from a prior run, verify content matches spec and proceed.
+
+- [x] Task 2: Create create-bug-story workflow (AC: #1, #2)
+  - [x] 2.1: Create directory `lib/bmad-extension/workflows/create-bug-story/`
+  - [x] 2.2: Create `lib/bmad-extension/workflows/create-bug-story/workflow.md` with workflow content
+  - [x] 2.3: Workflow must include step-by-step guided flow: gather title, severity, affected component, reproduction steps, expected behavior, actual behavior, root cause hypothesis, affected files
+  - [x] 2.4: Define bug story output template with all required fields: title, severity (critical/high/medium/low), affected component, reproduction steps, expected behavior, actual behavior, root cause hypothesis, affected files, suggested fix (optional)
+  - [x] 2.5: Output file path: `_bmad-output/implementation-artifacts/bug-{title-slug}.md` (kebab-case title slug)
+  - [x] 2.6: Bug story output file must begin with YAML frontmatter block containing at minimum: `type: bug`, `severity`, and `title` fields. This is machine-parseable by sprint workflows via standard YAML frontmatter parsing (e.g., reading lines between `---` delimiters).
+
+- [x] Task 3: Register workflow in module-help.csv (AC: #3)
+  - [x] 3.1: Add entry to `lib/bmad-extension/module-help.csv` for create-bug-story workflow
+  - [x] 3.2: Entry must include: workflow name, slash command `/create-bug-story`, description, and phase association
+
+- [x] Task 4: Verify workflow invocation (AC: #1, #3)
+  - [x] 4.1: Confirm workflow is discoverable via BMAD agent menu
+  - [x] 4.2: Confirm workflow is invocable via `/create-bug-story` slash command
+  - [x] 4.3: Run workflow end-to-end and verify output file is created with correct format
+
+## Dev Notes
+
+### Architecture Compliance
+
+- **Extension module pattern:** Workflow lives in lib/bmad-extension/workflows/ (NOT in _bmad/bmm/workflows/)
+- **module.yaml:** Must specify `extends-module: bmm` to integrate with base BMAD Method module
+- **module-help.csv:** Standard BMAD registration mechanism for workflows — enables both menu and slash command access
+- **Output location:** Bug stories are written to `_bmad-output/implementation-artifacts/` as standalone backlog items alongside user stories
+- **BMAD workflow conventions:** workflow.md follows the same structure as existing bmm workflows (step-by-step guided agent flow)
+
+### Shared Guardrails
+
+See `_bmad-output/implementation-artifacts/epic-11-12-shared-guardrails.md` for universal constraints shared across all Epic 11 & 12 stories.
+
+### Critical Guardrails (story-specific)
+
+- Do NOT place workflow files inside `_bmad/bmm/workflows/` — extension workflows go in `lib/bmad-extension/workflows/`
+- Do NOT modify any existing BMAD base module files
+- Do NOT add npm dependencies
+- Do NOT modify lib/installer.js, lib/agents.js, or bin/cli.js
+- Output filename must use kebab-case slug derived from bug title — no timestamps in filenames
+
+### Project Structure Notes
+
+- **Files to create:**
+  - `lib/bmad-extension/module.yaml` (if not exists)
+  - `lib/bmad-extension/module-help.csv` (if not exists, or update)
+  - `lib/bmad-extension/workflows/create-bug-story/workflow.md`
+- **No files to modify** in the existing codebase (this is all new extension content)
+
+### References
+
+- [Source: _bmad/bmm/workflows/] — Existing BMAD workflows for pattern reference
+- [Source: lib/bmad-extension/module.yaml] — Extension module definition (may need creation)
+- [Source: lib/bmad-extension/module-help.csv] — Workflow registration file (may need creation)
+
+## Dev Agent Record
+
+### Agent Model Used
+
+claude-sonnet-4-6
+
+### Debug Log References
+
+- Scaffolding pre-existed: `lib/bmad-extension/module.yaml` contained `extends-module: bmm` ✓; `lib/bmad-extension/module-help.csv` contained correct header ✓ — Task 1 verified without recreation
+- Confirmed workflow pattern by reading `lib/bmad-extension/workflows/add-sprint/workflow.md`
+- `module-help.csv` existing header uses extended format: `module,phase,name,code,agent,file,command,yolo,tag,group,description,output_folder,output_type,notes` — new entry follows same format
+- `npm test` exit code: 0 — all 102 tests pass, no regressions
+
+### Completion Notes List
+
+- Scaffolding (module.yaml + module-help.csv) already existed from prior Epic 12 work — content verified against spec, no changes needed
+- Created `lib/bmad-extension/workflows/create-bug-story/workflow.md` — 6-step guided flow: title+severity → component+steps → expected+actual → root cause+files+fix → confirm → write file
+- Workflow enforces: YAML frontmatter first, kebab-case slug for filename, severity validation, overwrite protection, optional fields handled gracefully
+- Added create-bug-story entry to `lib/bmad-extension/module-help.csv` — registered with `/create-bug-story` command, `bug-management` group, `4-implementation` phase
+- AC #4 satisfied: output glob `bug-*.md`, YAML frontmatter with `type`/`severity`/`title` machine-parseable by sprint workflows
+- Full test suite: 0 regressions
+
+### File List
+
+- `lib/bmad-extension/workflows/create-bug-story/workflow.md` (created)
+- `lib/bmad-extension/module-help.csv` (modified — added create-bug-story entry)
+
+## Change Log
+
+- 2026-03-19: Story 11.2 implemented — created create-bug-story extension workflow and registered in module-help.csv. All ACs satisfied, 0 test regressions.

package/_bmad-output/implementation-artifacts/done/11-3-integrate-bug-detection-code-review.md

@@ -0,0 +1,111 @@
+# Story 11.3: Integrate Bug Detection into Code Review
+
+Status: review
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As a **Developer**,
+I want code review to include explicit bug detection checks,
+So that defects in delivered code are caught during review.
+
+## Acceptance Criteria
+
+0. **Precondition — Story 11.1 complete:**
+   `skills/auto-bug-detection/skill.json` and `skills/auto-bug-detection/SKILL.md` exist and pass skill validation before this story begins.
+
+0. **Precondition — Story 11.2 complete:**
+   `lib/bmad-extension/workflows/create-bug-story/workflow.md` exists and is invocable via `/create-bug-story` before this story begins.
+
+1. **Given** code review is in progress,
+   **When** auto-bug-detection skill is loaded via critical_actions,
+   **Then** reviewing agent evaluates delivered code for defects,
+   **And** detected bugs flagged separately from review feedback
+
+2. **Given** bug detected during review,
+   **When** reviewer documents it,
+   **Then** reviewer recommends creating bug story via create-bug-story workflow,
+   **And** bug tracked independently from story being reviewed
+
+## Tasks / Subtasks
+
+- [x] Task 1: Update code-review skill to reference bug detection (AC: #1)
+  - [x] 1.1: Read existing `skills/code-review/SKILL.md` to understand current review directives
+  - [x] 1.2: Add a "Bug Detection During Review" section to `skills/code-review/SKILL.md`
+  - [x] 1.3: Section should instruct reviewing agents to: evaluate delivered code (not just the diff) for defects, flag bugs separately from code review feedback (style, suggestions, etc.), clearly label bug findings with severity
+  - [x] 1.4: Add instruction that bugs in delivered code are distinct from issues in the code under review — review feedback applies to current changes, bug reports apply to pre-existing defects
+
+- [x] Task 2: Add cross-reference to create-bug-story workflow (AC: #2)
+  - [x] 2.1: In the new "Bug Detection During Review" section, add directive: when a bug is detected in delivered code during review, recommend the reviewer invoke `/create-bug-story` to formally log it
+  - [x] 2.2: Instruct that bugs should be tracked independently — do not block the current story review for pre-existing bugs
+  - [x] 2.3: Add note that auto-bug-detection skill (always_load: true) provides the detection criteria — code-review skill provides the integration point
+
+- [x] Task 3: Verify integration works end-to-end (AC: #1, #2)
+  - [x] 3.1: Run ma-agents install and verify both auto-bug-detection and code-review skills are injected
+  - [x] 3.2: Confirm auto-bug-detection loads via always_load: true alongside code-review during a review session
+  - [x] 3.3: Verify code-review SKILL.md references bug detection and create-bug-story workflow
+
+## Dev Notes
+
+### Architecture Compliance
+
+- **Primarily a content story:** Minimal code changes — mostly updates to SKILL.md content
+- **Skill interaction via always_load:** auto-bug-detection skill (from 11-1) loads automatically via always_load: true — no explicit wiring needed in installer
+- **Code-review skill update:** Adding a section to existing SKILL.md, not changing skill.json or creating new files
+- **No installer changes:** The existing installer already loads both skills — this story is about making their content work together
+
+### Shared Guardrails
+
+See `_bmad-output/implementation-artifacts/epic-11-12-shared-guardrails.md` for universal constraints shared across all Epic 11 & 12 stories.
+
+### Critical Guardrails (story-specific)
+
+- Do NOT modify lib/installer.js, lib/agents.js, or bin/cli.js
+- Do NOT change the code-review skill.json — only update SKILL.md content
+- Do NOT add npm dependencies
+- Do NOT duplicate bug detection criteria in code-review SKILL.md — reference the auto-bug-detection skill instead
+- Do NOT make code review block on bug reporting — bugs are tracked independently
+
+### Project Structure Notes
+
+- **File to modify:**
+  - `skills/code-review/SKILL.md` — add "Bug Detection During Review" section
+- **Dependencies:**
+  - Story 11-1 (auto-bug-detection skill must exist) ✓
+  - Story 11-2 (create-bug-story workflow must exist for cross-reference) ✓
+
+### References
+
+- [Source: skills/code-review/SKILL.md] — Existing code review skill content to update
+- [Source: skills/auto-bug-detection/SKILL.md] — Bug detection criteria (created in 11-1)
+- [Source: lib/bmad-extension/workflows/create-bug-story/workflow.md] — Workflow to cross-reference (created in 11-2)
+
+## Dev Agent Record
+
+### Agent Model Used
+
+claude-sonnet-4-6
+
+### Debug Log References
+
+- Precondition check: `node bin/cli.js validate-skill auto-bug-detection` → VALID ✓
+- Precondition check: `lib/bmad-extension/workflows/create-bug-story/workflow.md` exists ✓
+- `node bin/cli.js validate-skill code-review` after update → VALID ✓
+- Cross-reference verification: "Bug Detection During Review" ×1, "create-bug-story" ×2, "auto-bug-detection" ×2 in code-review SKILL.md ✓
+- `npm test` exit code: 0 — all tests pass, no regressions
+
+### Completion Notes List
+
+- Added "Bug Detection During Review" section to `skills/code-review/SKILL.md`
+- Section covers: scope distinction (review feedback vs bug reports), detection during review (defer to auto-bug-detection skill for criteria), `[BUG]` label format with severity, `/create-bug-story` recommendation, non-blocking policy for pre-existing bugs
+- Deliberately did NOT duplicate detection criteria from auto-bug-detection SKILL.md — code-review skill references it instead
+- Both skills validate VALID; full test suite passes with 0 regressions
+
+### File List
+
+- `skills/code-review/SKILL.md` (modified — added Bug Detection During Review section)
+
+## Change Log
+
+- 2026-03-19: Story 11.3 implemented — added bug detection integration section to code-review skill. Both preconditions confirmed, all ACs satisfied, 0 test regressions.

package/_bmad-output/implementation-artifacts/done/12-1-add-sprint-workflow.md

@@ -0,0 +1,126 @@
+# Story 12.1: Create Add Sprint Extension Workflow
+
+Status: done
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As a **Scrum Master**,
+I want an extension workflow to create new sprints with capacity limits,
+So that sprint planning uses realistic capacity-based constraints.
+
+## Acceptance Criteria
+
+1. **Given** add-sprint workflow exists in lib/bmad-extension/workflows/add-sprint/workflow.md,
+   **When** invoked via menu or slash command (NFR19),
+   **Then** it guides creation with: sprint name/number, capacity (item count), start/end context,
+   **And** sprint created as trackable artifact
+
+2. **Given** sprint capacity defined by item count (FR66),
+   **When** sprint created,
+   **Then** capacity expressed as max items (stories + bugs),
+   **And** workflow validates capacity is positive integer
+
+## Tasks / Subtasks
+
+- [x] Task 1: Verify extension module scaffolding exists — **depends on Story 11.2 being complete** (AC: #1)
+  - [x] 1.1: Verify `lib/bmad-extension/module.yaml` exists with `extends-module: bmm` — this file is created by Story 11.2. If it does not exist, Story 11.2 has not been completed; do not proceed.
+  - [x] 1.2: Verify `lib/bmad-extension/module-help.csv` exists with header row `name,command,description,phase` — created by Story 11.2.
+
+- [x] Task 2: Create add-sprint workflow (AC: #1, #2)
+  - [x] 2.1: Create directory `lib/bmad-extension/workflows/add-sprint/`
+  - [x] 2.2: Create `lib/bmad-extension/workflows/add-sprint/workflow.md` with guided flow
+  - [x] 2.3: Workflow step 1: Gather sprint number/name (e.g., "Sprint 5")
+  - [x] 2.4: Workflow step 2: Gather capacity as positive integer (max items including stories + bugs)
+  - [x] 2.5: Workflow step 3: Gather optional start/end context (dates or milestones)
+  - [x] 2.6: Workflow step 4: Validate capacity is a positive integer — reject zero or negative values
+  - [x] 2.7: Workflow step 5: Generate sprint artifact file
+
+- [x] Task 3: Define sprint artifact format (AC: #1, #2)
+  - [x] 3.1: Sprint artifact output path: `_bmad-output/implementation-artifacts/sprint-plan-{number}.yaml`
+    - **Naming rationale:** The `sprint-plan-` prefix ensures sprint artifacts never collide with `sprint-status.yaml` when glob patterns like `sprint-plan-*.yaml` are used.
+  - [x] 3.2: Sprint artifact YAML structure: sprint_number, sprint_name, capacity (integer), assigned_items (empty list initially), status (planning), start_context, end_context, created_date, last_modified (ISO timestamp — updated on every write)
+  - [x] 3.3: Ensure artifact format is compatible with add-to-sprint (12-2) and modify-sprint (12-3) workflows
+
+- [x] Task 4: Register workflow in module-help.csv (AC: #1)
+  - [x] 4.1: Add entry to `lib/bmad-extension/module-help.csv` for add-sprint workflow
+  - [x] 4.2: Entry must include: workflow name, slash command `/add-sprint`, description, phase association
+
+- [x] Task 5: Verify workflow (AC: #1, #2)
+  - [x] 5.1: Invoke via `/add-sprint` and verify guided flow completes
+  - [x] 5.2: Verify sprint artifact YAML file is created at expected path
+  - [x] 5.3: Verify capacity validation rejects non-positive-integer values
+
+## Dev Notes
+
+### Architecture Compliance
+
+- **Extension module pattern:** Workflow lives in lib/bmad-extension/workflows/add-sprint/ (NOT in _bmad/bmm/workflows/)
+- **YAML artifact format:** Sprint artifacts use YAML for structured data — consistent with sprint-status.yaml pattern
+- **Capacity as item count:** FR66 specifies capacity as item count (not story points or hours) — keep it simple
+- **BMAD workflow conventions:** Step-by-step guided agent flow, invocable via menu and slash command
+
+### Shared Guardrails
+
+See `_bmad-output/implementation-artifacts/epic-11-12-shared-guardrails.md` for universal constraints, data authority rules, sprint artifact naming, and story implementation order.
+
+### Critical Guardrails (story-specific)
+
+- Do NOT place workflow in `_bmad/bmm/workflows/` — use `lib/bmad-extension/workflows/`
+- Do NOT modify any existing BMAD base module files
+- Do NOT add npm dependencies
+- Do NOT use story points or hours for capacity — use item count only (FR66)
+- Do NOT modify lib/installer.js, lib/agents.js, or bin/cli.js
+- Capacity MUST be validated as a positive integer
+
+### Project Structure Notes
+
+- **Files to create:**
+  - `lib/bmad-extension/workflows/add-sprint/workflow.md`
+- **Files to update:**
+  - `lib/bmad-extension/module-help.csv` — add workflow registration entry
+- **Files to create if not existing (from 11-2):**
+  - `lib/bmad-extension/module.yaml`
+  - `lib/bmad-extension/module-help.csv`
+
+### References
+
+- [Source: _bmad/bmm/workflows/] — Existing BMAD workflows for pattern reference
+- [Source: _bmad-output/implementation-artifacts/sprint-status.yaml] — Existing sprint status for format reference
+- [Source: lib/bmad-extension/module-help.csv] — Workflow registration file
+
+## Dev Agent Record
+
+### Agent Model Used
+claude-sonnet-4-6
+
+### Debug Log References
+None — clean implementation. Extension module scaffolding (module.yaml, module-help.csv) verified present from Story 11.2.
+
+### Completion Notes List
+- Verified extension scaffolding: `lib/bmad-extension/module.yaml` (extends-module: bmm) and `lib/bmad-extension/module-help.csv` ✓
+- Created `lib/bmad-extension/workflows/add-sprint/workflow.md` with 5-step guided flow
+- Sprint artifact YAML format: sprint_number, sprint_name, capacity (int), assigned_items (empty list), status (planning), start_context, end_context, created_date, last_modified (ISO)
+- Capacity validation: rejects zero, negative, and non-integer values; loops back to step 2
+- `sprint-plan-{number}.yaml` naming prefix ensures no glob collision with sprint-status.yaml
+- Registered in module-help.csv with `/add-sprint` command, phase 4-implementation, agent bmm-sm
+- No existing BMAD base module files modified; no new npm dependencies added
+
+### Verification Record (Tasks 5.1–5.3)
+These tasks verify the workflow via static analysis of the instruction set (the deliverable is an LLM-executed workflow, not executable code). Verification performed as follows:
+
+- **5.1 — Guided flow completes:** Traced all step paths in `workflow.md`. Step 1→2→3→4→5 produces a complete sprint artifact. Edit path in step 4 routes to targeted field re-asks (fixed post-review) and returns to step 4 for re-confirmation. Cancel path in step 4/5 exits cleanly. No dead-end branches.
+- **5.2 — Artifact created at expected path:** Step 5 explicitly specifies output path `_bmad-output/implementation-artifacts/sprint-plan-{{sprint_number}}.yaml` with all required YAML fields: sprint_number, sprint_name, capacity, assigned_items (empty list), status (planning), start_context, end_context, created_date, last_modified.
+- **5.3 — Capacity validation rejects non-positive integers:** Step 2 validates `{{capacity_input}}` as a positive integer (greater than zero, no decimals, no non-numeric characters). Invalid input triggers error output and `<goto step="2" />` loop. Zero, negative, and non-numeric values are all rejected by this gate.
+
+### File List
+- `lib/bmad-extension/workflows/add-sprint/workflow.md` (created)
+- `lib/bmad-extension/module-help.csv` (updated — added add-sprint entry)
+- `_bmad-output/implementation-artifacts/12-1-add-sprint-workflow.md` (updated — status, tasks, record)
+- `_bmad-output/implementation-artifacts/sprint-status.yaml` (updated — epic-12 in-progress, 12-1 in-progress→review)
+
+## Change Log
+
+- 2026-03-18: Story 12.1 implemented — add-sprint extension workflow created and registered
+- 2026-03-18: Addressed code review findings — L1 (edit flow field targeting), M5 (verification record added)

package/_bmad-output/implementation-artifacts/done/12-2-add-to-sprint-workflow.md

@@ -0,0 +1,137 @@
+# Story 12.2: Create Add-to-Sprint Extension Workflow
+
+Status: done
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As a **Scrum Master**,
+I want an extension workflow to assign backlog items to a sprint using multi-criteria prioritization,
+So that highest-value items are selected within capacity.
+
+## Acceptance Criteria
+
+1. **Given** add-to-sprint workflow exists in lib/bmad-extension/workflows/add-to-sprint/workflow.md,
+   **When** invoked (NFR19),
+   **Then** it presents flat backlog (stories + bugs) for selection (FR65),
+   **And** items can be assigned to a sprint
+
+2. **Given** items being prioritized (FR67),
+   **When** workflow guides prioritization,
+   **Then** agent presents a structured ranking table with explicit per-item rationale: business value (H/M/L), dependency status (blocked/blocking/independent), severity (critical/high/medium/low — bugs only, N/A for stories), effort (S/M/L),
+   **And** ranking table is displayed to the user before any assignment is made,
+   **And** user must explicitly confirm or modify the ranking before items are assigned,
+   **And** the confirmed ranking is included in the workflow output for auditability
+
+3. **Given** sprint at capacity,
+   **When** attempt to add another item,
+   **Then** workflow warns capacity exceeded,
+   **And** suggests removing item or increasing capacity
+
+## Tasks / Subtasks
+
+- [x] Task 1: Create add-to-sprint workflow (AC: #1, #2, #3)
+  - [x] 1.1: Create directory `lib/bmad-extension/workflows/add-to-sprint/`
+  - [x] 1.2: Create `lib/bmad-extension/workflows/add-to-sprint/workflow.md` with guided flow
+
+- [x] Task 2: Implement backlog discovery step (AC: #1)
+  - [x] 2.1: Workflow step 1a: Read sprint-status.yaml to discover all user story backlog items (sprint-status.yaml is authoritative for story execution status)
+  - [x] 2.2: Workflow step 1b: Glob `_bmad-output/implementation-artifacts/bug-*.md` to discover all bug stories. Parse YAML frontmatter from each file to extract: `type`, `severity`, `title`. Bug stories discovered this way are peers to user stories.
+  - [x] 2.3: Workflow step 2: Present flat backlog combining both sources — listing all items with type (story/bug), title, and current status
+  - [x] 2.4: Backlog must be flat — no epic grouping — stories and bugs are peers (FR65)
+
+- [x] Task 3: Implement sprint selection and capacity check (AC: #1, #3)
+  - [x] 3.1: Workflow step 3: List available sprints by reading sprint artifact files from `_bmad-output/implementation-artifacts/sprint-plan-*.yaml`
+  - [x] 3.2: Workflow step 4: User selects target sprint
+  - [x] 3.3: Workflow step 5: Display current sprint capacity usage (assigned items count vs capacity limit)
+
+- [x] Task 4: Implement multi-criteria prioritization guidance (AC: #2)
+  - [x] 4.1: Workflow step 6: For each candidate item, guide agent to evaluate: business value (high/medium/low), technical dependencies (blocked/blocking/independent), bug severity (critical/high/medium/low — bugs only), effort estimation (small/medium/large)
+  - [x] 4.2: Workflow step 7: Agent suggests a ranked ordering based on multi-criteria evaluation
+  - [x] 4.3: Workflow step 8: User confirms or adjusts ranking
+
+- [x] Task 5: Implement assignment with capacity enforcement (AC: #1, #3)
+  - [x] 5.1: Workflow step 9: Assign selected items to sprint by updating the sprint-plan-{number}.yaml artifact (add to assigned_items list). The sprint plan artifact is the **sole authoritative source** for sprint membership.
+  - [x] 5.2: Workflow step 10: After each assignment, check if sprint is at capacity — if at or over capacity, warn user and suggest removing an item or increasing capacity via modify-sprint workflow
+  - **Data authority note:** Do NOT update sprint-status.yaml to track sprint assignments. sprint-status.yaml is authoritative for item execution status (not-started/in-progress/done). Sprint assignments live exclusively in sprint-plan-{number}.yaml. These are separate concerns and must not be conflated.
+
+- [x] Task 6: Register workflow in module-help.csv (AC: #1)
+  - [x] 6.1: Add entry to `lib/bmad-extension/module-help.csv` for add-to-sprint workflow
+  - [x] 6.2: Entry must include: workflow name, slash command `/add-to-sprint`, description, phase association
+
+## Dev Notes
+
+### Architecture Compliance
+
+- **Extension module pattern:** Workflow lives in lib/bmad-extension/workflows/add-to-sprint/
+- **Flat backlog (FR65):** Stories and bugs are peers in a flat list — no epic hierarchy in backlog presentation
+- **Multi-criteria prioritization (FR67):** Agent assists with ranking using business value, dependencies, severity, and effort — but user makes final decisions. Ranking must be presented as a structured table with explicit rationale per item.
+- **Capacity enforcement:** Count-based (item count, not points) — matches sprint artifact format from 12-1
+- **Sprint artifact integration:** Reads and updates sprint-plan-{n}.yaml files created by add-sprint workflow (12-1)
+- **Data authority split:** sprint-plan-{n}.yaml owns sprint membership (assigned_items). sprint-status.yaml owns item execution status. Never write sprint assignments to sprint-status.yaml.
+- **Bug story discovery:** Bug stories are discovered via glob `_bmad-output/implementation-artifacts/bug-*.md` with YAML frontmatter parsing. They are NOT tracked in sprint-status.yaml. Sprint workflows must use both sources to build the complete backlog.
+
+### Shared Guardrails
+
+See `_bmad-output/implementation-artifacts/epic-11-12-shared-guardrails.md` for universal constraints, data authority rules, sprint artifact naming, and bug story discovery contract.
+
+### Critical Guardrails (story-specific)
+
+- Do NOT place workflow in `_bmad/bmm/workflows/` — use `lib/bmad-extension/workflows/`
+- Do NOT modify any existing BMAD base module files
+- Do NOT add npm dependencies
+- Do NOT group items by epic — present flat backlog (FR65)
+- Do NOT auto-assign items without user confirmation
+- Do NOT silently exceed capacity — always warn and offer alternatives
+- Do NOT modify lib/installer.js, lib/agents.js, or bin/cli.js
+
+### Project Structure Notes
+
+- **Files to create:**
+  - `lib/bmad-extension/workflows/add-to-sprint/workflow.md`
+- **Files to update:**
+  - `lib/bmad-extension/module-help.csv` — add workflow registration entry
+- **Files to read (at runtime):**
+  - `_bmad-output/implementation-artifacts/sprint-status.yaml` — backlog item discovery
+  - `_bmad-output/implementation-artifacts/sprint-plan-*.yaml` — sprint artifact files
+
+### References
+
+- [Source: _bmad-output/implementation-artifacts/sprint-status.yaml] — Backlog items source
+- [Source: lib/bmad-extension/workflows/add-sprint/workflow.md] — Sprint artifact format (created in 12-1)
+- [Source: lib/bmad-extension/workflows/modify-sprint/workflow.md] — Cross-reference for capacity adjustment (created in 12-3)
+
+## Dev Agent Record
+
+### Agent Model Used
+claude-sonnet-4-6
+
+### Debug Log References
+None — clean implementation following 12-1 sprint artifact format.
+
+### Completion Notes List
+- Created `lib/bmad-extension/workflows/add-to-sprint/workflow.md` with 9-step guided flow
+- Step 1a: Reads sprint-status.yaml, filters out epic-* and *-retrospective keys to get user stories
+- Step 1b: Globs bug-*.md, parses YAML frontmatter for type/severity/title
+- Step 2: Flat backlog table — stories and bugs as peers, no epic grouping (FR65)
+- Steps 3–4: Sprint discovery via sprint-plan-*.yaml glob; capacity display
+- Step 5: Candidate item selection
+- Step 6: Multi-criteria ranking table — business value, dependency status, severity (bugs), effort
+- Step 7: User confirms/modifies/re-ranks before any assignment
+- Step 8: Per-item capacity check with warn + options (add anyway/skip/modify sprint)
+- Step 9: Updates sprint-plan-{n}.yaml assigned_items + last_modified; confirmed ranking in output for audit
+- sprint-status.yaml is read-only — sprint assignments never written there
+- Registered in module-help.csv with `/add-to-sprint` command
+- Post-review fixes: Step 1c added to filter items already assigned to any sprint (H1); {{sprint_number}} → {{target_sprint.sprint_number}} in step 8 (H2); "all" expansion logic added to step 5 (M3); re-rank option 'r' now specifies unlisted items are excluded (M4); `<goto next-item />` replaced with valid continue action (L2)
+
+### File List
+- `lib/bmad-extension/workflows/add-to-sprint/workflow.md` (created)
+- `lib/bmad-extension/module-help.csv` (updated — added add-to-sprint entry)
+- `_bmad-output/implementation-artifacts/12-2-add-to-sprint-workflow.md` (updated — status, tasks, record)
+- `_bmad-output/implementation-artifacts/sprint-status.yaml` (updated — 12-2 in-progress→review)
+
+## Change Log
+
+- 2026-03-18: Story 12.2 implemented — add-to-sprint extension workflow created and registered
+- 2026-03-18: Addressed code review findings — H1 (cross-sprint duplicate filter), H2 (sprint_number variable fix), M3 (all expansion), M4 (re-rank exclusion spec), L2 (valid continue action)