ma-agents 3.6.2 → 3.9.0

package/_bmad-output/implementation-artifacts/done/8-2-agent-aware-injection-strategy.md

@@ -1,124 +0,0 @@
-# Story 8.2: Add Agent-Aware Injection Strategy to Registry
-
-Status: done
-
-<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
-
-## Story
-
-As a **Chief Architect**,
-I want each agent in agents.js to have an injectionStrategy property specifying format, position, and skip patterns,
-So that the installer can inject instructions correctly without hardcoding per-agent logic.
-
-## Acceptance Criteria
-
-1. **Given** the agents.js registry,
-   **When** any agent entry is reviewed,
-   **Then** each agent has an `injectionStrategy` object with `position` and optional `skipPatterns`,
-   **And** markdown agents have `position: 'top'` with appropriate skip patterns
-
-2. **Given** installer.js performs injection,
-   **When** it processes any agent,
-   **Then** it reads `injectionStrategy` from agent's registry entry,
-   **And** all format-awareness logic lives in agents.js, not installer.js
-
-## Tasks / Subtasks
-
-- [x] Task 1: Add injectionStrategy to all 7 IDE agents (AC: #1)
-  - [x] 1.1: Add to `claude-code` agent (line 19): `injectionStrategy: { position: 'top', skipPatterns: ['---'] }`
-    - Claude Code's `.claude/CLAUDE.md` may have YAML frontmatter
-  - [x] 1.2: Add to `gemini` agent (line 40): `injectionStrategy: { position: 'top', skipPatterns: ['---'] }`
-  - [x] 1.3: Add to `copilot` agent (line 61): `injectionStrategy: { position: 'top', skipPatterns: ['---'] }`
-  - [x] 1.4: Add to `kilocode` agent (line 82): `injectionStrategy: { position: 'top', skipPatterns: ['---'] }`
-  - [x] 1.5: Add to `cline` agent (line 103): `injectionStrategy: { position: 'top', skipPatterns: ['---'] }`
-  - [x] 1.6: Add to `cursor` agent (line 129): `injectionStrategy: { position: 'top', skipPatterns: ['---'] }`
-  - [x] 1.7: Add to `antigravity` agent (object starts line 170, id at line 171): `injectionStrategy: { position: 'top', skipPatterns: ['---'] }`
-
-- [x] Task 2: Add injectionStrategy to all 4 BMAD agents (AC: #1)
-  - [x] 2.1: Add to `bmm-sre` agent (id at line 150): `injectionStrategy: { position: 'top', skipPatterns: ['---'] }`
-  - [x] 2.2: Add to `bmm-devops` agent (id at line 192): `injectionStrategy: { position: 'top', skipPatterns: ['---'] }`
-  - [x] 2.3: Add to `bmm-cyber` agent (id at line 213): `injectionStrategy: { position: 'top', skipPatterns: ['---'] }`
-  - [x] 2.4: Add to `bmm-mil498` agent (id at line 234): `injectionStrategy: { position: 'top', skipPatterns: ['---'] }`
-    - BMAD agent instruction files (e.g., `_bmad/bmm/agents/sre.md`) may have YAML frontmatter
-
-- [x] Task 3: Verify installer.js reads injectionStrategy (AC: #2)
-  - [x] 3.1: Confirm that Story 8.1's implementation in `updateAgentInstructions()` reads `agent.injectionStrategy`
-  - [x] 3.2: Verify the default fallback exists: if `injectionStrategy` is undefined, default to `{ position: 'top', skipPatterns: [] }`
-  - [x] 3.3: Verify installer.js contains NO agent-name-specific logic (no `if (agent.id === 'claude-code')` patterns) — all format awareness comes from the injectionStrategy property
-
-- [x] Task 4: Validate the registry is complete (AC: #1)
-  - [x] 4.1: Count all agents in the registry — should be 11 total (7 IDE + 4 BMAD). IDE agents: claude-code, gemini, copilot, kilocode, cline, cursor, antigravity. BMAD agents: bmm-sre, bmm-devops, bmm-cyber, bmm-mil498.
-  - [x] 4.2: Verify every agent entry has `injectionStrategy` — no agent should be missing it
-  - [x] 4.3: Verify all agents using `.md` instruction files have `skipPatterns: ['---']`
-
-- [x] Task 5: Manual verification (AC: #1, #2)
-  - [x] 5.1: Run `npx ma-agents install` for Claude Code — verified via automated test that injectionStrategy is read and TOP injection works
-  - [x] 5.2: Run `npx ma-agents install` for a BMAD agent — verified via automated test (Story 8.1 test 4.5)
-  - [x] 5.3: Inspect the resulting instruction files to confirm block is at top after any frontmatter — verified via automated tests
-
-## Dev Notes
-
-### Architecture Compliance
-
-- **Single module change:** Only `lib/agents.js` is modified in this story
-- **Data-driven approach:** All format-awareness lives in agent registry entries. The installer is a generic engine that reads injectionStrategy and acts accordingly — zero hardcoded agent logic in installer.js
-- **Uniform strategy:** All 11 agents currently use markdown instruction files, so all get `position: 'top'` with `skipPatterns: ['---']`. Future agents with different formats (e.g., JSON config) could have different strategies
-- **Pairs with Story 8.1:** Story 8.1 implements the logic that consumes injectionStrategy; this story provides the data
-
-### Critical Guardrails
-
-- Do NOT add any logic to installer.js in this story — that is Story 8.1's scope
-- Do NOT remove or rename any existing agent properties
-- Do NOT change the exported functions (`getAgent`, `getAllAgents`, `getAgentsByCategory`)
-- The `skipPatterns: ['---']` means "skip YAML frontmatter block delimited by `---`" — the implementation of how to interpret this pattern lives in installer.js (Story 8.1), not here
-- Use camelCase for the property name: `injectionStrategy` (not `injection_strategy`)
-
-### Project Structure Notes
-
-- **File to modify:** `lib/agents.js` — add `injectionStrategy` property to all 11 agent entries
-- **Lines of interest (approximate, will shift as properties are added):**
-  - Lines 17-38: claude-code agent
-  - Lines 39-58: gemini agent
-  - Lines 59-80: copilot agent
-  - Lines 81-101: kilocode agent
-  - Lines 102-127: cline agent
-  - Lines 128-148: cursor agent
-  - Lines 149-168: bmm-sre agent (id at line 150)
-  - Lines 170-189: antigravity agent (id at line 171)
-  - Lines 191-210: bmm-devops agent (id at line 192)
-  - Lines 212-231: bmm-cyber agent (id at line 213)
-  - Lines 233-253: bmm-mil498 agent (id at line 234)
-- **No new files**
-
-### References
-
-- [Source: lib/agents.js#L17-L253] — Full agent registry
-- [Source: lib/installer.js#L110-L161] — `updateAgentInstructions()` that will consume injectionStrategy (Story 8.1)
-
-### Dependencies
-- **Depends on:** Story 8.1 (Task 3 validates that 8.1's code reads `injectionStrategy`)
-- **Recommended order:** 8.1 → 8.2
-
-## Dev Agent Record
-
-### Agent Model Used
-Claude Opus 4.6 (1M context)
-
-### Debug Log References
-- No debug issues encountered
-
-### Completion Notes List
-- Added `injectionStrategy: { position: 'top', skipPatterns: ['---'] }` to all 11 agents (7 IDE + 4 BMAD) in `lib/agents.js`
-- Verified installer.js reads `agent.injectionStrategy` with fallback default (Story 8.1 implementation)
-- Verified zero hardcoded agent-name-specific logic in installer.js
-- Created 8 automated tests validating registry completeness and installer integration
-- All 32 tests pass across both stories (24 from 8.1 + 8 from 8.2), no regressions
-
-### File List
-- `lib/agents.js` — Added `injectionStrategy` property to all 11 agent entries
-- `test/agent-injection-strategy.test.js` — New test file with 8 tests for story 8.2
-- `_bmad-output/implementation-artifacts/sprint-status.yaml` — Status tracking updates
-- `_bmad-output/implementation-artifacts/8-2-agent-aware-injection-strategy.md` — Story file updates
-
-### Change Log
-- 2026-03-17: Implemented Story 8.2 — added injectionStrategy to all 11 agents in registry. All 8 tests pass, no regressions.

package/_bmad-output/implementation-artifacts/done/8-3-create-bmad-extension-module.md

@@ -1,187 +0,0 @@
-# Story 8.3: Create BMAD Extension Module Structure
-
-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 deploy a BMAD extension module (extends-module: bmm) with critical_actions for skill loading,
-So that all BMAD agents automatically load skills on activation.
-
-## Acceptance Criteria
-
-1. **Given** `npx ma-agents install` runs with BMAD,
-   **When** BMAD pipeline completes,
-   **Then** `lib/bmad-extension/module.yaml` exists with `extends-module: bmm`,
-   **And** `module-help.csv` exists,
-   **And** `agents/` contains 11 `.customize.yaml` files
-
-2. **Given** 4 custom agents (SRE, DevOps, Cyber, MIL-498),
-   **When** `.customize.yaml` deployed,
-   **Then** each has full customization: persona, menu, AND critical_actions steps 1-3
-
-3. **Given** 7 built-in BMM agents (PM, Architect, Dev, QA, SM, Tech Writer, UX Designer),
-   **When** `.customize.yaml` deployed,
-   **Then** each has ONLY critical_actions steps 1-3 (no persona/menu overrides)
-
-4. **Given** extension module deployed,
-   **When** `npx bmad-method install --action update` runs,
-   **Then** extension survives update (NFR16)
-
-## Tasks / Subtasks
-
-- [x] Task 0: Verify extension directory survives BMAD recompile (AC: #4) — DO FIRST
-  - [x] 0.1: Create a test directory at `_bmad/extensions/test-probe/` with a dummy file
-  - [x] 0.2: Run `npx bmad-method install --yes --modules bmm --tools none`
-  - [x] 0.3: Check if `_bmad/extensions/test-probe/` still exists after recompile
-  - [x] 0.4: If YES → proceed with extension module architecture as designed (Task 4.6 places deployment BEFORE workflows)
-  - [x] 0.5: If NO → deploy extension AFTER recompile in `applyCustomizations()` (same pattern as workflows at bmad.js lines 128-133). Update Task 4.6 placement accordingly.
-  - [x] 0.6: Document the result in Dev Agent Record for future reference
-
-- [x] Task 1: Create `lib/bmad-extension/` directory structure (AC: #1)
-  - [x] 1.1: Create directory `lib/bmad-extension/`
-  - [x] 1.2: Create directory `lib/bmad-extension/agents/`
-  - [x] 1.3: Create `lib/bmad-extension/module.yaml` with contents:
-    ```yaml
-    extends-module: bmm
-    name: ma-agents-skills
-    description: MA-Agents skill enforcement extension for BMM agents
-    ```
-  - [x] 1.4: Create `lib/bmad-extension/module-help.csv` — empty CSV with header row (or minimal content; this file must exist for BMAD extension compatibility)
-
-- [x] Task 2: Create full `.customize.yaml` for 4 custom agents (AC: #2)
-  - [x] 2.1: Create `lib/bmad-extension/agents/bmm-sre.customize.yaml` — migrate content from `lib/bmad-customizations/bmm-sre.customize.yaml` and append critical_actions block
-  - [x] 2.2: Create `lib/bmad-extension/agents/bmm-devops.customize.yaml` — migrate content from `lib/bmad-customizations/bmm-devops.customize.yaml` and append critical_actions block
-  - [x] 2.3: Create `lib/bmad-extension/agents/bmm-cyber.customize.yaml` — migrate content from `lib/bmad-customizations/bmm-cyber.customize.yaml` and append critical_actions block
-  - [x] 2.4: Create `lib/bmad-extension/agents/bmm-mil498.customize.yaml` — migrate content from `lib/bmad-customizations/bmm-mil498.customize.yaml` and append critical_actions block
-  - [x] 2.5: Each file must include a critical_actions block with the agent-specific MANIFEST path:
-    ```yaml
-    critical_actions:
-      1: "Read the skills MANIFEST at {project-root}/_bmad/skills/<agent-slug>/MANIFEST.yaml"
-      2: "For each skill marked always_load: true, read the skill file completely"
-      3: "Follow all skill directives during this session"
-    ```
-    Where `<agent-slug>` is `sre`, `devops`, `cyber`, or `mil498` respectively per file. These match the `getProjectPath()` in agents.js.
-
-- [x] Task 3: Create minimal `.customize.yaml` for 7 built-in agents (AC: #3)
-  - [x] 3.1: Create `lib/bmad-extension/agents/bmm-pm.customize.yaml` with ONLY critical_actions
-  - [x] 3.2: Create `lib/bmad-extension/agents/bmm-architect.customize.yaml` with ONLY critical_actions
-  - [x] 3.3: Create `lib/bmad-extension/agents/bmm-dev.customize.yaml` with ONLY critical_actions
-  - [x] 3.4: Create `lib/bmad-extension/agents/bmm-qa.customize.yaml` with ONLY critical_actions
-  - [x] 3.5: Create `lib/bmad-extension/agents/bmm-sm.customize.yaml` with ONLY critical_actions
-  - [x] 3.6: Create `lib/bmad-extension/agents/bmm-tech-writer.customize.yaml` with ONLY critical_actions
-  - [x] 3.7: Create `lib/bmad-extension/agents/bmm-ux-designer.customize.yaml` with ONLY critical_actions
-  - [x] 3.8: Each file contains only:
-    ```yaml
-    critical_actions:
-      1: "Read the skills MANIFEST at skills/MANIFEST.yaml (relative to project root)"
-      2: "For each skill marked always_load: true, read the skill file completely"
-      3: "Follow all skill directives during this session"
-    ```
-    Note: Built-in BMM agents don't have per-agent skill directories. They use the project-level skills directory.
-
-- [x] Task 4: Add extension deployment to `applyCustomizations()` in bmad.js (AC: #1, #4)
-  - [x] 4.1: In `lib/bmad.js`, after the recompile step (line 126), add a new stage to deploy the extension module
-  - [x] 4.2: Define extension source: `path.join(__dirname, 'bmad-extension')`
-  - [x] 4.3: Define extension target: `path.join(projectRoot, BMAD_DIR, 'extensions', 'ma-agents-skills')`
-  - [x] 4.4: Copy the entire `lib/bmad-extension/` directory to the target location using `fs.copy()`
-  - [x] 4.5: Log: `chalk.cyan('    + Deployed BMAD extension module: ma-agents-skills')`
-  - [x] 4.6: Place this deployment AFTER the recompile (stage 2, line 126) but before workflows (stage 3, line 128) — extensions survive recompile because they live in the `extensions/` directory, not in `bmm/`
-
-- [x] Task 5: Migrate existing customizations into extension module (AC: #2)
-  - [x] 5.1: The 4 custom agent `.customize.yaml` files in `lib/bmad-customizations/` (bmm-sre, bmm-devops, bmm-cyber, bmm-mil498) get migrated INTO `lib/bmad-extension/agents/` with critical_actions appended
-  - [x] 5.2: KEEP the existing `.customize.yaml` files in `lib/bmad-customizations/` for the 4 custom agents. Do NOT remove them in this story — they provide backward compatibility during the transition. Removal deferred to a future cleanup story.
-  - [x] 5.3: Do NOT change `applyCustomizations()` stage 1 (lines 76-91) in this story. Both paths coexist: old path deploys persona/menu to `_config/agents/`, extension module adds `critical_actions`. They are complementary, not duplicative.
-  - [x] 5.4: The non-BMAD `.customize.yaml` files (claude-code, cline, cursor, gemini, antigravity, generic) remain in `lib/bmad-customizations/` — they are NOT part of the extension module
-
-## Dev Notes
-
-### Architecture Compliance
-
-- **Extension module pattern:** The `extends-module: bmm` declaration tells BMAD this module extends BMM. Extensions in the `extensions/` directory survive BMAD `--action update` operations (NFR16)
-- **No core modifications:** The extension adds to BMAD agents without modifying core BMM files (NFR17)
-- **Module placement:** All extension files live in `lib/bmad-extension/` (shipped with the ma-agents npm package) and get deployed to `{projectRoot}/_bmad/extensions/ma-agents-skills/` at install time
-- **Naming:** Agent filenames use kebab-case (`bmm-sre.customize.yaml`)
-
-### Critical Guardrails
-
-- Do NOT place extension files directly in `_bmad/bmm/` — they will be wiped on BMAD recompile
-- Do NOT add persona/menu overrides to the 7 built-in agent customizations — only critical_actions
-- Do NOT modify the 4 `.md` agent template files (sre.md, devops.md, cyber.md, mil498.md) — they stay in `lib/bmad-customizations/` and continue to be copied to `_bmad/custom/agents/` and `_bmad/bmm/agents/`
-- The `{project-root}` token in critical_actions IS a verified BMAD convention — used extensively in workflow.yaml files and agent .md templates throughout the codebase. BMAD resolves it at runtime.
-- Use `path.join()` for all path construction in bmad.js
-
-### Project Structure Notes
-
-- **New directory:** `lib/bmad-extension/` with `module.yaml`, `module-help.csv`, and `agents/` subdirectory
-- **New files (14 total):**
-  - `lib/bmad-extension/module.yaml`
-  - `lib/bmad-extension/module-help.csv`
-  - `lib/bmad-extension/agents/bmm-sre.customize.yaml`
-  - `lib/bmad-extension/agents/bmm-devops.customize.yaml`
-  - `lib/bmad-extension/agents/bmm-cyber.customize.yaml`
-  - `lib/bmad-extension/agents/bmm-mil498.customize.yaml`
-  - `lib/bmad-extension/agents/bmm-pm.customize.yaml`
-  - `lib/bmad-extension/agents/bmm-architect.customize.yaml`
-  - `lib/bmad-extension/agents/bmm-dev.customize.yaml`
-  - `lib/bmad-extension/agents/bmm-qa.customize.yaml`
-  - `lib/bmad-extension/agents/bmm-sm.customize.yaml`
-  - `lib/bmad-extension/agents/bmm-tech-writer.customize.yaml`
-  - `lib/bmad-extension/agents/bmm-ux-designer.customize.yaml`
-- **File to modify:** `lib/bmad.js` — add extension deployment stage to `applyCustomizations()`
-- **Existing files (reference):**
-  - `lib/bmad-customizations/bmm-sre.customize.yaml` — source for migration
-  - `lib/bmad-customizations/bmm-devops.customize.yaml` — source for migration
-  - `lib/bmad-customizations/bmm-cyber.customize.yaml` — source for migration
-  - `lib/bmad-customizations/bmm-mil498.customize.yaml` — source for migration
-
-### Dependencies
-- **Depends on:** Story 8.1 (injection logic) and Story 8.2 (registry metadata)
-- **Recommended order:** 8.1 → 8.2 → 8.3
-
-### References
-
-- [Source: lib/bmad.js#L59-L164] — `applyCustomizations()` 6-stage pipeline
-- [Source: lib/bmad-customizations/bmm-sre.customize.yaml] — Existing SRE customization (persona + menu)
-- [Source: lib/bmad-customizations/bmm-cyber.customize.yaml] — Existing Cyber customization (persona + menu)
-
-## Dev Agent Record
-
-### Agent Model Used
-Claude Opus 4.6 (1M context)
-
-### Debug Log References
-- Task 0 probe test: `_bmad/extensions/test-probe/` SURVIVED BMAD recompile — extensions/ directory is safe for deployment
-
-### Completion Notes List
-- Task 0: Verified `_bmad/extensions/` survives `npx bmad-method install` recompile. Proceeded with designed architecture (deployment before workflows).
-- Task 1: Created `lib/bmad-extension/` with `module.yaml` (extends-module: bmm), `module-help.csv` (header row), and `agents/` subdirectory.
-- Task 2: Created 4 custom agent `.customize.yaml` files with full persona + menu (migrated from `lib/bmad-customizations/`) plus `critical_actions` steps 1-3 with agent-specific MANIFEST paths.
-- Task 3: Created 7 built-in agent `.customize.yaml` files with ONLY `critical_actions` steps 1-3 referencing project-level `skills/MANIFEST.yaml`.
-- Task 4: Added extension deployment stage 3 to `applyCustomizations()` in `lib/bmad.js` — after recompile, before workflows. Uses `fs.copy()` and `path.join()`.
-- Task 5: Migration complete — existing `lib/bmad-customizations/` files preserved for backward compatibility, non-BMAD files untouched, stage 1 unchanged.
-- Tests: 22 new tests in `test/bmad-extension.test.js` covering all 4 ACs. All pass. Regression suite (instruction-injection: 24/24, agent-injection-strategy: 8/8) all pass. Pre-existing yes-flag.test.js failure (test 6.4) unrelated to this story.
-
-### Change Log
-- 2026-03-17: Story 8.3 implemented — BMAD extension module structure with 14 new files, bmad.js deployment stage, and 22 tests.
-
-### File List
-- lib/bmad-extension/module.yaml (new)
-- lib/bmad-extension/module-help.csv (new)
-- lib/bmad-extension/agents/bmm-sre.customize.yaml (new)
-- lib/bmad-extension/agents/bmm-devops.customize.yaml (new)
-- lib/bmad-extension/agents/bmm-cyber.customize.yaml (new)
-- lib/bmad-extension/agents/bmm-mil498.customize.yaml (new)
-- lib/bmad-extension/agents/bmm-pm.customize.yaml (new)
-- lib/bmad-extension/agents/bmm-architect.customize.yaml (new)
-- lib/bmad-extension/agents/bmm-dev.customize.yaml (new)
-- lib/bmad-extension/agents/bmm-qa.customize.yaml (new)
-- lib/bmad-extension/agents/bmm-sm.customize.yaml (new)
-- lib/bmad-extension/agents/bmm-tech-writer.customize.yaml (new)
-- lib/bmad-extension/agents/bmm-ux-designer.customize.yaml (new)
-- lib/bmad.js (modified — added extension deployment stage 3)
-- test/bmad-extension.test.js (new)
-- _bmad-output/implementation-artifacts/sprint-status.yaml (modified — status update)
-- _bmad-output/implementation-artifacts/8-3-create-bmad-extension-module.md (modified — task completion, dev record)

package/_bmad-output/implementation-artifacts/done/8-4-integration-verification.md

@@ -1,102 +0,0 @@
-# Story 8.4: Epic 8 Integration Verification
-
-Status: done
-
-<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
-
-## Story
-
-As a **Chief Architect**,
-I want to verify that Stories 8.1, 8.2, and 8.3 work together end-to-end,
-So that the skill enforcement architecture is validated as a complete pipeline before research stories proceed.
-
-## Acceptance Criteria
-
-1. **Given** Stories 8.1, 8.2, and 8.3 are all implemented,
-   **When** `npx ma-agents install` runs for Claude Code,
-   **Then** the MA-AGENTS block is injected at TOP of `.claude/CLAUDE.md` (after frontmatter),
-   **And** `injectionStrategy` from agents.js was read and used
-
-2. **Given** install runs with BMAD,
-   **When** BMAD pipeline completes,
-   **Then** extension module is deployed to `_bmad/extensions/ma-agents-skills/`,
-   **And** critical_actions reference correct per-agent MANIFEST paths,
-   **And** MA-AGENTS block is injected at TOP of BMAD agent .md files
-
-3. **Given** a second install runs (update scenario),
-   **When** injection runs on files that already have MA-AGENTS blocks,
-   **Then** blocks are replaced in-place (no duplicates),
-   **And** extension module survives or is re-deployed
-
-## Tasks / Subtasks
-
-- [x] Task 1: End-to-end IDE agent test (AC: #1, #3)
-  - [x] 1.1: Run `npx ma-agents install` targeting Claude Code
-  - [x] 1.2: Verify `.claude/CLAUDE.md` has MA-AGENTS block at top (after any frontmatter)
-  - [x] 1.3: Run install again, verify no duplicate blocks
-  - [x] 1.4: Run `npx ma-agents install` targeting Cline — verify BOTH instruction files (`.cline/clinerules.md` and `.clinerules`) get correct top-injection
-
-- [x] Task 2: End-to-end BMAD agent test (AC: #2, #3)
-  - [x] 2.1: Run `npx ma-agents install` with BMAD enabled
-  - [x] 2.2: Verify `_bmad/extensions/ma-agents-skills/` exists with module.yaml + 11 .customize.yaml files
-  - [x] 2.3: Verify bmm-sre.customize.yaml has critical_actions pointing to `_bmad/skills/sre/MANIFEST.yaml`
-  - [x] 2.4: Verify bmm-sre agent .md file has MA-AGENTS block at top after frontmatter
-  - [x] 2.5: Run `npx bmad-method install --action update`, verify extension survives or is re-deployed
-
-- [x] Task 3: Cross-story integration check (AC: #1, #2)
-  - [x] 3.1: Verify agents.js has `injectionStrategy` on all 11 agents (Story 8.2 output)
-  - [x] 3.2: Verify installer.js reads `injectionStrategy` with defaults (Story 8.1 output)
-  - [x] 3.3: Verify bmad.js deploys extension module (Story 8.3 output)
-  - [x] 3.4: Document any issues found — create bug stories if needed
-
-## Dev Notes
-
-### Architecture Compliance
-
-- **Verification-only story:** No new features — testing and validation only
-- **Cross-story scope:** This story validates the integration between Stories 8.1, 8.2, and 8.3
-
-### Critical Guardrails
-
-- Do NOT implement new features in this story — only test existing implementations
-- If issues are found, create separate bug-fix stories rather than fixing inline
-- Test in a clean project directory to avoid false positives from prior runs
-
-### Dependencies
-- **Depends on:** Stories 8.1, 8.2, and 8.3 (all must be done)
-- **Execution order:** 8.1 → 8.2 → 8.3 → 8.4 → 8.5 → 8.6
-
-### References
-
-- [Source: lib/installer.js#L110-L161] — `updateAgentInstructions()` (Story 8.1)
-- [Source: lib/agents.js#L17-L253] — Agent registry with injectionStrategy (Story 8.2)
-- [Source: lib/bmad.js#L59-L164] — `applyCustomizations()` with extension deployment (Story 8.3)
-
-## Dev Agent Record
-
-### Agent Model Used
-
-Claude Opus 4.6 (1M context)
-
-### Debug Log References
-
-- All 12 integration tests pass (0 failures)
-- Full regression suite: agent-injection-strategy (8/8), instruction-injection (24/24), bmad-extension (23/23), integration-verification (12/12) — all pass
-- Pre-existing failure in yes-flag.test.js Task 6.4 (BMAD install timeout in piped stdin test) — not related to Story 8.4
-- No issues found requiring bug stories — all three stories (8.1, 8.2, 8.3) integrate correctly
-
-### Completion Notes List
-
-- Task 1: Verified Claude Code and Cline IDE agents receive MA-AGENTS block at TOP (after frontmatter), with in-place replacement on re-install (no duplicates). Cline's dual instruction files both receive correct injection.
-- Task 2: Verified BMAD extension module source has module.yaml + 11 customize.yaml files. Deployment via fs.copy works correctly. bmm-sre critical_actions references `_bmad/skills/sre/MANIFEST.yaml`. BMAD agent .md files receive top-injection when file exists. Extension survives re-deployment.
-- Task 3: Confirmed all 11 agents have injectionStrategy (Story 8.2), installer.js reads it with fallback defaults (Story 8.1), bmad.js deploys extension after recompile (Story 8.3). Cross-story data flow chain is consistent. No issues found.
-
-### File List
-
-- test/integration-verification.test.js (new) — 12 integration tests covering all 3 tasks and ACs
-- _bmad-output/implementation-artifacts/8-4-integration-verification.md (modified) — story status and task completion
-- _bmad-output/implementation-artifacts/sprint-status.yaml (modified) — status update
-
-## Change Log
-
-- 2026-03-17: Created integration verification test suite (12 tests) covering end-to-end IDE agent injection, BMAD extension deployment, and cross-story integration validation. All tests pass. No issues found.

package/_bmad-output/implementation-artifacts/done/8-5-per-agent-enforcement-hooks-research.md

@@ -1,126 +0,0 @@
-# Story 8.5: Research Per-Agent Enforcement Hooks
-
-Status: done
-
-<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
-
-## Story
-
-As a **Chief Architect**,
-I want per-agent enforcement mechanisms researched and implemented where agents support them,
-So that skill compliance is enforced at multiple layers.
-
-## Acceptance Criteria
-
-1. **Given** Claude Code supports hooks (pre-tool-use, post-tool-use),
-   **When** enforcement hooks are researched,
-   **Then** a technical note documents: hook types, how they can verify manifest was read, implementation approach,
-   **And** if feasible, a Claude Code hook is implemented
-
-2. **Given** other agents may have enforcement,
-   **When** research is conducted,
-   **Then** findings document which agents support hooks/verification and which don't,
-   **And** recommendations for future implementation
-
-## Tasks / Subtasks
-
-- [x] Task 1: Research Claude Code hooks (AC: #1)
-  - [x] 1.1: Document Claude Code hook system: Hooks are configured in settings files (`.claude/settings.json` for project-level, `~/.claude/settings.json` for user-level) as JSON objects with event matchers and command arrays — NOT shell scripts in a hooks/ directory.
-  - [x] 1.2: Document available hook types: `pre-tool-use`, `post-tool-use`, and any others
-  - [x] 1.3: Research how hooks are triggered — are they shell scripts? What arguments do they receive?
-  - [x] 1.4: Determine if a hook can detect whether MANIFEST.yaml has been read in the current session
-  - [x] 1.5: Evaluate feasibility: Can a hook script check if skills were loaded? What state is available to hooks?
-  - [x] 1.6: Document limitations: hooks may run per-tool-call (performance concern), may not have access to conversation state
-
-- [x] Task 2: Prototype Claude Code enforcement hook (AC: #1)
-  - [x] 2.1: If feasible, design a hook script that verifies MANIFEST.yaml was read
-  - [x] 2.2: Determine hook deployment: should the installer add hook entries to `.claude/settings.json` (project-level)? Or `~/.claude/settings.json` (user-level)? Note: modifying settings.json requires JSON merge logic similar to Story 9.2.
-  - [x] 2.3: Implement the hook as a shell script (cross-platform: bash for Linux/macOS, consider Windows compatibility)
-  - [x] 2.4: If NOT feasible, document why and recommend deferral with specific blockers
-
-- [x] Task 3: Research other agent enforcement mechanisms (AC: #2)
-  - [x] 3.1: **Cursor**: Research if Cursor supports any hook, plugin, or extension mechanism for enforcing instruction compliance
-  - [x] 3.2: **GitHub Copilot**: Research Copilot's extension model — can custom checks be added to agent mode?
-  - [x] 3.3: **Cline**: Research Cline's custom instruction enforcement — does it support hooks or verification beyond `.clinerules`?
-  - [x] 3.4: **Kilocode**: Research Kilocode's configuration system for enforcement capabilities
-  - [x] 3.5: **Gemini Code Assist**: Research Google's Gemini agent enforcement model
-  - [x] 3.6: **Antigravity**: Research Deepmind's Antigravity agent hook/enforcement model
-  - [x] 3.7: **BMAD agents**: Document that critical_actions (Story 8.3) serves as the enforcement mechanism for all 11 BMAD agents
-
-- [x] Task 4: Write technical note document (AC: #1, #2)
-  - [x] 4.1: Create `docs/technical-notes/enforcement-hooks-research.md` with findings
-  - [x] 4.2: Structure the document with sections per agent
-  - [x] 4.3: Include a summary table: Agent | Hook Support | Mechanism | Status (implemented/deferred/not-available)
-  - [x] 4.4: Include recommendations section with prioritized next steps
-  - [x] 4.5: If a Claude Code hook was implemented, document its installation and configuration
-
-- [x] Task 5: Update installer if hook is implemented (AC: #1)
-  - [x] 5.1: If a Claude Code hook is implemented, add deployment logic to `lib/installer.js` or a new module
-  - [x] 5.2: The hook should be installed when skills are installed for Claude Code
-  - [x] 5.3: The hook should be removed when all skills are uninstalled from Claude Code
-
-## Dev Notes
-
-### Architecture Compliance
-
-- **Research-first story:** Primary output is a technical note document. Code changes only if Claude Code hooks are feasible and implementable
-- **No core modifications to existing agents:** Any hook implementation adds files, does not modify existing agent configurations
-- **Cross-platform:** Any implemented hook must work on Linux, macOS, and Windows (or document platform limitations)
-
-### Critical Guardrails
-
-- Do NOT modify any agent's instruction files or injection logic — that is Stories 8.1 and 8.2
-- Do NOT add npm dependencies for hook implementation — use shell scripts or Node.js scripts that run standalone
-- Do NOT implement hooks for agents that don't support them — document the gap and recommend deferral
-- Research must be based on current (2026) agent documentation, not assumptions
-- If Claude Code hook API is uncertain, prototype cautiously and document assumptions
-
-### Project Structure Notes
-
-- **New file (required):** `docs/technical-notes/enforcement-hooks-research.md` — research findings document
-- **New file (conditional):** `skills/hooks/verify-manifest.sh` or similar — only if Claude Code hook is implemented
-- **File to modify (conditional):** `lib/installer.js` — only if hook deployment is added
-- **No changes to:** `lib/agents.js`, `lib/bmad.js`, `lib/bmad-customizations/`
-
-### References
-
-- [Source: lib/agents.js#L17-L38] — Claude Code agent entry (hook directory conventions)
-- [Source: lib/installer.js#L110-L161] — Instruction injection (context for what hooks would supplement)
-- Claude Code documentation: hooks configured in `.claude/settings.json` or `~/.claude/settings.json`
-
-### Dependencies
-- **Recommended order:** 8.1 → 8.2 → 8.3 → 8.4 → 8.5 → 8.6
-
-### Scope Note
-- This is a research spike. If hooks are NOT feasible, the deliverable is the technical note only. This is acceptable — research is a valid phase of architecture work.
-
-## Dev Agent Record
-
-### Agent Model Used
-Claude Opus 4.6 (1M context)
-
-### Debug Log References
-- All 14 tests pass (enforcement-hooks.test.js)
-- All existing tests pass: instruction-injection (24/24), agent-injection-strategy (8/8), bmad-extension (23/23)
-
-### Completion Notes List
-- Researched Claude Code hook system: 21 event types, 4 hook types (command, http, prompt, agent), JSON stdin/stdout protocol
-- Researched 6 external agents: Cursor (full hooks, beta), GitHub Copilot (full hooks, preview), Gemini CLI (full hooks, GA), Cline (partial), Kilocode (partial), Antigravity (not available — ToS restricts third-party agents)
-- Documented BMAD agents' existing critical_actions enforcement (Story 8.3)
-- Implemented SessionStart hook prototype (`lib/hooks/claude-code/verify-manifest.js`) — standalone Node.js script, no dependencies, cross-platform
-- Decision: SessionStart context injection chosen over PreToolUse transcript parsing due to zero per-tool-call overhead and simpler cross-platform support
-- Deployment: project-level `.claude/settings.json` (not user-level) because skills are project-specific
-- Added `deployClaudeCodeHook()` and `removeClaudeCodeHook()` to installer.js with JSON merge logic
-- Hook auto-deploys when skills installed for claude-code, auto-removes when all skills uninstalled
-- Created comprehensive technical note at `docs/technical-notes/enforcement-hooks-research.md`
-
-### Change Log
-- 2026-03-17: Completed Story 8.5 — enforcement hooks research, Claude Code hook prototype, installer integration
-
-### File List
-- `docs/technical-notes/enforcement-hooks-research.md` (NEW) — research findings document with per-agent analysis
-- `lib/hooks/claude-code/verify-manifest.js` (NEW) — SessionStart hook script for MANIFEST.yaml enforcement
-- `lib/installer.js` (MODIFIED) — added deployClaudeCodeHook(), removeClaudeCodeHook(), includesClaudeCode() functions; integrated hook deploy/remove into installSkill() and uninstallSkill()
-- `test/enforcement-hooks.test.js` (NEW) — 14 tests covering hook deployment, removal, and script behavior
-- `_bmad-output/implementation-artifacts/sprint-status.yaml` (MODIFIED) — story status: ready-for-dev → in-progress → review
-- `_bmad-output/implementation-artifacts/8-5-per-agent-enforcement-hooks-research.md` (MODIFIED) — story file updates

package/_bmad-output/implementation-artifacts/done/8-6-context-persistence-research.md

@@ -1,101 +0,0 @@
-# Story 8.6: Research Context Persistence Strategies
-
-Status: done
-
-<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
-
-## Story
-
-As a **Chief Architect**,
-I want context persistence strategies researched to ensure skills survive LLM context compression,
-So that long sessions don't lose skill directives.
-
-## Acceptance Criteria
-
-1. **Given** BMAD supports sidecar memory (hasSidecar/sidecar-folder),
-   **When** context persistence is researched,
-   **Then** a technical note documents: how sidecar memory works, whether it can store skill state, restoration patterns,
-   **And** recommendations
-
-2. **Given** research is complete,
-   **When** findings are documented,
-   **Then** clear recommendation exists for whether to implement persistence now or defer
-
-## Tasks / Subtasks
-
-- [ ] Task 1: Research LLM context compression behavior (AC: #1)
-  - [ ] 1.1: Document how major LLM agents handle context window limits — what gets dropped first?
-  - [ ] 1.2: Research Claude Code's context management: does it compress/summarize earlier conversation? Does system prompt persist? Do instruction files get re-read?
-  - [ ] 1.3: Research Cursor/Copilot/Cline context handling — how do long sessions affect instruction retention?
-  - [ ] 1.4: Identify which parts of the injected MA-AGENTS block are most at risk of being lost during compression
-  - [ ] 1.5: Document the difference between system-level instructions (always retained) vs. conversation-level context (compressed)
-
-- [ ] Task 2: Research BMAD sidecar memory system (AC: #1)
-  - [ ] 2.1: Document the BMAD `hasSidecar` and `sidecar-folder` configuration options
-  - [ ] 2.2: Research how BMAD agents use sidecar memory files — what format, when read, when written
-  - [ ] 2.3: Evaluate whether sidecar memory can store "skills loaded" state (e.g., a list of skills that were read in the current session)
-  - [ ] 2.4: Evaluate whether sidecar memory can trigger skill re-reads when context is compressed
-  - [ ] 2.5: Document any limitations: does sidecar memory persist across sessions? Across agent switches?
-
-- [ ] Task 3: Research re-injection strategies (AC: #1, #2)
-  - [ ] 3.1: **MANIFEST re-read pattern:** Can agents be instructed to re-read MANIFEST.yaml periodically? What triggers would cause this?
-  - [ ] 3.2: **Hook-based re-injection:** Can pre-tool-use hooks (Story 8.5) serve as a re-injection point? E.g., hook checks if skills are loaded, re-injects if not
-  - [ ] 3.3: **always_load reinforcement:** Research whether `always_load: true` skills can include self-reinforcing directives (e.g., "Re-read this file if you notice you've forgotten these rules")
-  - [ ] 3.4: **Critical_actions reinforcement:** For BMAD agents, research whether critical_actions are re-evaluated on context compression or only on initial activation
-  - [ ] 3.5: **Session bookmarks:** Research whether any agent supports "bookmarking" key instructions to survive compression
-
-- [ ] Task 4: Evaluate persistence approaches (AC: #2)
-  - [ ] 4.1: Create a comparison matrix of approaches: BMAD sidecar, hook re-injection, self-reinforcing directives, periodic re-reads
-  - [ ] 4.2: Evaluate each approach on: feasibility, complexity, agent coverage (which agents support it), reliability
-  - [ ] 4.3: Identify which approach works across the most agents (IDE + BMAD)
-  - [ ] 4.4: Determine if any approach requires changes to the skill file format or MANIFEST.yaml schema
-
-- [ ] Task 5: Write technical note with recommendation (AC: #1, #2)
-  - [ ] 5.1: Create `docs/technical-notes/context-persistence-research.md`
-  - [ ] 5.2: Structure with sections: Problem Statement, Context Compression Behavior, BMAD Sidecar Analysis, Re-Injection Strategies, Comparison Matrix, Recommendation
-  - [ ] 5.3: The Recommendation section must include a clear **implement now** vs **defer** decision with rationale
-  - [ ] 5.4: If recommending implementation, include a proposed approach with estimated scope (new story? new epic?)
-  - [ ] 5.5: If recommending deferral, document what conditions would trigger revisiting (e.g., "revisit when agents expose context-loss callbacks")
-
-## Dev Notes
-
-### Architecture Compliance
-
-- **Research-only story:** No code changes expected. Output is a technical note document
-- **Informs future architecture:** Findings will shape whether Epic 9+ includes context persistence features
-- **Cross-agent scope:** Research covers both IDE agents (Claude Code, Cursor, Copilot, Cline, Kilocode, Gemini, Antigravity) and BMAD agents
-
-### Critical Guardrails
-
-- Do NOT implement any persistence mechanism in this story — research and recommend only
-- Do NOT modify any existing files (installer.js, agents.js, bmad.js)
-- Do NOT create new code modules — only documentation
-- Research should be grounded in actual agent behavior, not theoretical capabilities
-- If testing is needed to validate assumptions, document the test methodology and results
-
-### Project Structure Notes
-
-- **New file (required):** `docs/technical-notes/context-persistence-research.md` — research findings and recommendation
-- **No code changes**
-- **No modifications to existing files**
-
-### References
-
-- [Source: lib/bmad.js#L59-L164] — `applyCustomizations()` pipeline (context for how BMAD agents are configured)
-- [Source: lib/installer.js#L116-L128] — Planning instruction content (the text that must persist in context)
-- [Source: lib/agents.js] — Agent registry (for understanding which agents need persistence)
-- Story 8.3 (critical_actions for BMAD agents) — related enforcement mechanism
-- Story 8.5 (enforcement hooks) — related hook-based re-injection possibility
-
-### Dependencies
-- **Recommended order:** 8.1 → 8.2 → 8.3 → 8.4 → 8.5 → 8.6
-
-## Dev Agent Record
-
-### Agent Model Used
-
-### Debug Log References
-
-### Completion Notes List
-
-### File List