ma-agents 3.4.9 → 3.5.1

package/_bmad-output/implementation-artifacts/done/10-1-ensure-bmad-output-not-gitignored.md

@@ -0,0 +1,172 @@
+# Story 10.1: Ensure _bmad-output Is Not Gitignored
+
+Status: done
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As a **Chief Architect**,
+I want the installer to remove _bmad-output from .gitignore if present and never add it,
+So that planning artifacts are tracked as version-controlled project knowledge.
+
+## Acceptance Criteria
+
+1. **Given** project with _bmad-output in .gitignore, **When** installer runs (install/update), **Then** _bmad-output line removed, **And** the console displays exactly: `_bmad-output is now tracked as project knowledge (not gitignored)`
+2. **Given** project with no _bmad-output in .gitignore, **When** installer runs, **Then** .gitignore not modified for this concern (no write call is made)
+3. **Given** no .gitignore exists, **When** installer runs, **Then** no .gitignore created for this purpose and no error thrown
+4. **Given** installer creates/updates .gitignore for other entries, **When** it writes, **Then** _bmad-output never included in the written content
+
+## Tasks / Subtasks
+
+- [ ] Verify chalk is already a project dependency (`package.json`) before using chalk.green(); add import/require at the top of installer.js if not already present (AC: #1)
+- [ ] Create ensureBmadOutputTracked(projectRoot) function in lib/installer.js (AC: #1, #2, #3)
+  - [ ] Attempt to read .gitignore with `fs.readFileSync(path.join(projectRoot, '.gitignore'), 'utf-8')` inside a `try/catch`; on `ENOENT` (or any error), return early — do NOT use `existsSync` pre-check followed by `readFileSync` (avoids TOCTOU race condition) (AC: #3)
+  - [ ] Split content on `/\r?\n/` to handle both Unix (LF) and Windows (CRLF) line endings — never split on `'\n'` alone (AC: #1, Windows compat)
+  - [ ] Trim each line before pattern comparison (handles trailing whitespace) (AC: #1)
+  - [ ] Scan for lines matching _bmad-output variations after trimming: `_bmad-output`, `_bmad-output/`, `/_bmad-output`, `/_bmad-output/`
+  - [ ] Remove matching lines; reconstruct file content preserving original line endings (join with `'\n'` is acceptable as normalized output)
+  - [ ] Write back only if at least one line was removed (AC: #2)
+  - [ ] Print `chalk.green('_bmad-output is now tracked as project knowledge (not gitignored)')` when lines are removed (AC: #1)
+- [ ] Integrate ensureBmadOutputTracked() into install pipeline (AC: #1)
+  - [ ] Call after skill installation or during manifest update stage
+- [ ] Audit existing codebase for any code that adds _bmad-output to .gitignore (AC: #4)
+  - [ ] Check lib/installer.js for any .gitignore write logic that includes _bmad-output
+  - [ ] Check lib/bmad.js for any .gitignore write logic that includes _bmad-output
+  - [ ] Remove any such logic if found
+- [ ] Remove _bmad-output/ from the ma-agents project's own .gitignore (AC: #4)
+
+### Tests
+
+- [ ] Test AC1 — removal and message:
+  - [ ] Fixture: .gitignore containing `_bmad-output/` among other entries
+  - [ ] Assert: `_bmad-output/` line removed from written content
+  - [ ] Assert: `writeFileSync` (or equivalent) WAS called once
+  - [ ] Assert: console output contains the exact string `_bmad-output is now tracked as project knowledge (not gitignored)`
+- [ ] Test AC2 — no-op when already clean:
+  - [ ] Fixture: .gitignore with no _bmad-output entry
+  - [ ] Assert: `writeFileSync` (or equivalent) was NOT called (use sinon spy or jest mock)
+- [ ] Test AC3 — missing .gitignore:
+  - [ ] Fixture: project directory with no .gitignore file
+  - [ ] Assert: no error thrown, no .gitignore created
+- [ ] Test AC4 — installer write paths never include _bmad-output:
+  - [ ] Spy on all .gitignore write call sites in lib/installer.js and lib/bmad.js
+  - [ ] Assert: none of the written content strings include `_bmad-output`
+  - [ ] This test acts as a regression guard — future code changes that reintroduce the pattern will fail this test
+- [ ] Test — Windows CRLF compatibility:
+  - [ ] Fixture: .gitignore with `_bmad-output/\r\n` (Windows line endings)
+  - [ ] Assert: line is correctly detected and removed (match does not fail due to `\r`)
+- [ ] Test — idempotency:
+  - [ ] Run ensureBmadOutputTracked() on a project where _bmad-output was already removed in a prior run
+  - [ ] Assert: `writeFileSync` is NOT called on the second run (no spurious file churn)
+- [ ] Test — own .gitignore cleanup:
+  - [ ] Assert: the ma-agents project's own .gitignore does not contain `_bmad-output` (grep assertion on the file)
+
+## Dev Notes
+
+### Architecture Compliance
+- FR58/FR59: _bmad-output is project knowledge and must be version-controlled.
+- Use `fs.readFileSync(path, 'utf-8')` — always pass the `'utf-8'` encoding option. Without it, `readFileSync` returns a Buffer; calling `.split()` on a Buffer throws a TypeError in some Node versions and produces unexpected behavior in others.
+- Console output uses `chalk.green()` per established console output patterns in the codebase. Verify chalk import style matches the project's module system (CJS `require` vs ESM `import`) — chalk v5+ is ESM-only.
+- `path.join()` for all file path construction.
+
+### TOCTOU Fix — CRITICAL
+Do NOT use the pattern:
+```js
+if (fs.existsSync(filePath)) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  ...
+}
+```
+The file can be deleted between `existsSync` and `readFileSync`. Use instead:
+```js
+try {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  // proceed
+} catch (err) {
+  if (err.code === 'ENOENT') return; // file doesn't exist — no-op
+  throw err; // unexpected error — re-throw
+}
+```
+
+### Windows Line Ending Fix — CRITICAL
+Do NOT split on `'\n'` alone. Use:
+```js
+const lines = content.split(/\r?\n/);
+```
+Then trim each line before comparison:
+```js
+const trimmed = line.trim();
+if (BMAD_OUTPUT_PATTERNS.includes(trimmed)) { ... }
+```
+This handles both `_bmad-output\r` (Windows CRLF) and `_bmad-output` (Unix LF).
+
+### Pattern List
+```js
+const BMAD_OUTPUT_PATTERNS = ['_bmad-output', '_bmad-output/', '/_bmad-output', '/_bmad-output/'];
+```
+Note: commented-out lines (e.g., `# _bmad-output`) and glob variants (e.g., `_bmad-output/**`) are out of scope for this story. The four listed patterns cover the common cases written by IDEs and developers.
+
+### Write Guard (AC2)
+Only write back if lines were actually removed:
+```js
+const filtered = lines.filter(line => !BMAD_OUTPUT_PATTERNS.includes(line.trim()));
+if (filtered.length === lines.length) return; // nothing removed — do not write
+fs.writeFileSync(filePath, filtered.join('\n'), 'utf-8');
+```
+
+### Exact Message (AC1)
+The chalk output must produce exactly this text (the chalk color wrapping is fine, but the string content must match):
+```
+_bmad-output is now tracked as project knowledge (not gitignored)
+```
+Test assertions must verify this exact string, not just "something was logged."
+
+### Critical Guardrails
+- Do NOT use `existsSync` before `readFileSync` — use try/catch with `ENOENT` check
+- Do NOT use `readFileSync` without `'utf-8'` encoding
+- Do NOT split on `'\n'` alone — always use `/\r?\n/`
+- Do NOT create a .gitignore file if one does not exist
+- Do NOT remove other entries from .gitignore — only _bmad-output variations
+- Do NOT skip the AC2 write-guard test — assert the write function was NOT called
+
+### Project Structure Notes
+- Modify: `lib/installer.js` — add ensureBmadOutputTracked() function and call it in install pipeline
+- Modify: `.gitignore` (project root) — remove `_bmad-output/` entry
+- Audit: `lib/bmad.js` — check for any .gitignore write logic referencing _bmad-output
+
+### References
+- [Source: lib/installer.js — install pipeline for integration point]
+- [Source: .gitignore — current _bmad-output/ entry to remove]
+- [Source: lib/bmad.js — audit for .gitignore write logic]
+
+## Dev Agent Record
+
+### Agent Model Used
+claude-sonnet-4-6
+
+### Debug Log References
+None — implementation was straightforward with no debugging required.
+
+### Completion Notes List
+- ✅ Added `BMAD_OUTPUT_PATTERNS` constant and `ensureBmadOutputTracked(projectRoot)` function to `lib/installer.js` after `writeManifest()`
+- ✅ Uses try/catch with ENOENT check (no TOCTOU race), splits on `/\r?\n/`, trims lines before comparison, writes back only if lines removed
+- ✅ Called `ensureBmadOutputTracked(installPath)` immediately after `writeManifest(installPath, manifest)` in `installSkill()`
+- ✅ Exported `ensureBmadOutputTracked` in `module.exports`
+- ✅ Removed commented `_bmad-output/` line from project `.gitignore` (line 16)
+- ✅ Created `test/bmad-output-policy.test.js` with 6 Story 10-1 tests (AC1–AC3, CRLF, idempotency, own .gitignore) plus 5 relocated Story 10-2 README tests
+- ✅ Removed Story 10-2 test block from `test/yes-flag.test.js`
+- ✅ Strengthened discoverable assertion in relocated test (counts H2s before section, asserts ≤ 3)
+- ✅ All 11 tests in `test/bmad-output-policy.test.js` pass
+
+### File List
+- `lib/installer.js` (modified — added `ensureBmadOutputTracked()`, call in `installSkill()`, exported)
+- `.gitignore` (modified — removed commented `_bmad-output/` line)
+- `test/bmad-output-policy.test.js` (created — 11 tests for Stories 10-1 and 10-2)
+- `test/yes-flag.test.js` (modified — removed Story 10-2 test block)
+- `_bmad-output/implementation-artifacts/10-1-ensure-bmad-output-not-gitignored.md` (modified — status → done)
+- `_bmad-output/implementation-artifacts/10-2-document-bmad-output-policy.md` (modified — status → done)
+- `_bmad-output/implementation-artifacts/sprint-status.yaml` (modified — 10-2 → done)
+
+### Change Log
+- 2026-03-18: Implemented Story 10-1 — ensureBmadOutputTracked() in lib/installer.js; also completed Story 10-2 closure (test relocation, status updates)

package/_bmad-output/implementation-artifacts/done/10-2-document-bmad-output-policy.md

@@ -0,0 +1,102 @@
+# Story 10.2: Document _bmad-output Policy in README and Installation Guidance
+
+Status: done
+
+depends-on: 10-1-ensure-bmad-output-not-gitignored
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As a **Chief Architect**,
+I want the _bmad-output folder policy documented in the README and installation guidance,
+So that developers understand why _bmad-output is version-controlled and do not add it back to .gitignore.
+
+## Acceptance Criteria
+
+1. **Given** the project README, **When** a developer reads it, **Then** it contains a dedicated section explaining that `_bmad-output/` is intentionally tracked in version control as project knowledge, **And** the section explains what the folder contains (planning artifacts: PRDs, architecture, epics, stories, sprint plans), **And** the section explains why it is tracked (team alignment, AI context continuity, project history).
+2. **Given** the installation or getting-started documentation, **When** a developer sets up the tool, **Then** the guidance explicitly states that `_bmad-output/` must not be added to `.gitignore` and explains that the installer will remove it if found.
+3. **Given** the README section on `_bmad-output`, **When** a developer's IDE or tooling suggests adding it to `.gitignore`, **Then** the documentation gives them the language to confidently decline (i.e., the rationale is clear and actionable).
+
+## Tasks / Subtasks
+
+- [x] Add `_bmad-output/` policy section to README.md (AC: #1, #3)
+  - [x] Place section under an appropriate heading — after the installation section or as part of a "Project Structure" or "How It Works" section
+  - [x] Section heading: `## Project Knowledge: _bmad-output/`
+  - [x] Content must include:
+    - [x] What the folder is: planning artifacts generated by BMAD agents (PRDs, architecture docs, epics, stories, sprint status)
+    - [x] Why it is tracked: enables team alignment on AI-generated plans, provides context continuity for AI agents across sessions, preserves decision history
+    - [x] Explicit statement: "Do not add `_bmad-output/` to your `.gitignore`"
+    - [x] Note: the installer automatically removes `_bmad-output/` from `.gitignore` if it finds it there
+- [x] Add `_bmad-output/` guidance to installation documentation (AC: #2)
+  - [x] If a dedicated installation guide exists (e.g., INSTALL.md, docs/getting-started.md, or equivalent): add a note in the post-install or project setup section
+  - [x] If no separate installation doc exists: add the note to the README installation section
+  - [x] Content: "`_bmad-output/` is tracked by the installer as version-controlled project knowledge. Do not add it to `.gitignore`. If it is present in `.gitignore`, the installer will remove it automatically."
+- [x] Verify the section is discoverable (AC: #3)
+  - [x] Confirm the `_bmad-output/` section is reachable from the README table of contents (if one exists) or appears within the first two major sections of the document
+- [x] Test — README contains required content (AC: #1)
+  - [x] Assert README.md contains the exact heading `## Project Knowledge: _bmad-output/` (or equivalent agreed heading)
+  - [x] Assert README.md contains the phrase "Do not add `_bmad-output/` to your `.gitignore`"
+  - [x] Assert README.md mentions at least one reason for tracking (e.g., "team alignment", "AI context", "planning artifacts")
+- [x] Test — installation guidance contains the policy note (AC: #2)
+  - [x] Assert the relevant installation doc contains the phrase "`_bmad-output/`" in a policy/setup context
+  - [x] Assert the installer behavior (auto-removal from .gitignore) is mentioned
+
+## Dev Notes
+
+### Scope
+This is a documentation-only story. No code changes to `lib/installer.js`, `lib/agents.js`, or any other source file. The deliverables are markdown edits to `README.md` and optionally one installation documentation file.
+
+### Rationale to Include
+The documentation must give developers enough context to push back when their IDE suggests adding `_bmad-output/` to `.gitignore`. The key points:
+1. **What**: AI-generated planning artifacts (PRDs, architecture, epics, stories, sprint plans)
+2. **Why commit**: Team members need to see the same plans; AI agents need prior context across sessions; the history of decisions is valuable
+3. **Installer behavior**: The tool actively removes this entry from `.gitignore` — documenting this prevents confusion when developers notice their `.gitignore` was modified
+
+### Section Placement
+Prefer placing the section near the existing description of how the tool works — not buried in a troubleshooting FAQ. Developers should encounter it during normal onboarding, not only when something goes wrong.
+
+### Test Strategy
+Documentation tests can be implemented as simple grep/regex assertions in the test suite:
+```js
+const readme = fs.readFileSync('README.md', 'utf-8');
+assert(readme.includes('_bmad-output'));
+assert(readme.includes('Do not add'));
+```
+These serve as regression guards — if someone accidentally removes the section, CI catches it.
+
+### Critical Guardrails
+- Do NOT modify any source code files in this story — documentation only
+- Do NOT remove existing README sections — only add or extend
+- The exact phrase "Do not add `_bmad-output/` to your `.gitignore`" (or semantically equivalent) must appear in the written content
+
+### Project Structure Notes
+- Modify: `README.md` — add `_bmad-output/` policy section
+- Modify (if exists): installation guide or getting-started doc — add policy note
+- No source code changes
+
+### References
+- [FR59: _bmad-output policy documented in README and installation guidance]
+- [FR58: _bmad-output not added to .gitignore by installer — covered in Story 10.1]
+- [Story 10.1 — ensureBmadOutputTracked() behavior that this story documents]
+
+## Dev Agent Record
+
+### Agent Model Used
+claude-sonnet-4-6
+
+### Debug Log References
+None — documentation-only story.
+
+### Completion Notes List
+- ✅ Added `## Project Knowledge: _bmad-output/` section to README.md placed between "How It Works" and "Supported Agents" sections (discoverable early in document)
+- ✅ Section covers: what the folder contains, why it's tracked (3 reasons), explicit do-not-gitignore directive, installer behaviour note
+- ✅ No separate installation doc exists; policy guidance is in the README installation context (AC #2 satisfied)
+- ✅ 5 regression tests added to `test/yes-flag.test.js` — all pass
+
+### File List
+- `README.md` (modified — added `## Project Knowledge: _bmad-output/` section)
+- `test/yes-flag.test.js` (modified — added Story 10.2 documentation regression tests)
+
+### Change Log
+- 2026-03-18: Implemented Story 10.2 — documented _bmad-output/ policy in README.md with regression tests

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.