ma-agents 3.6.2 → 3.8.0

package/_bmad-output/implementation-artifacts/done/5-4-validate-bundled-installation.md

@@ -1,274 +0,0 @@
-# Story 5.4: Validate Bundled Installation Completeness
-
-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 installation from the bundled npm package produces a complete, functional BMAD environment,
-So that deterministic installation is validated (NFR21).
-
-## Acceptance Criteria
-
-1. **Given** the ma-agents npm package is installed (via `npm install` or local `npm pack` tarball)
-   **When** `npx ma-agents install` is run selecting BMAD installation
-   **Then** the resulting `_bmad/` directory is complete with all modules: core, bmm, bmb, cis, tea, gds
-
-2. **Given** the installation is complete
-   **When** the user runs any BMAD workflow (e.g., `/bmad-bmm-create-prd`)
-   **Then** the workflow executes correctly without errors
-
-3. **Given** the installation is complete
-   **When** the user runs `npx ma-agents status`
-   **Then** the status output shows all installed skills and BMAD modules correctly
-
-4. **Given** the npm package is installed from a tarball (simulated air-gapped)
-   **When** `npx ma-agents install` is run with `GIT_TERMINAL_PROMPT=0` enforced
-   **Then** no git clone or npm registry fetch occurs for BMAD components (verified via network monitoring or offline simulation)
-
-5. **Given** the installation succeeds on an already-installed project
-   **When** `npx ma-agents install` is run a second time (idempotency test)
-   **Then** existing cache is preserved (modules skipped), bmad-method re-invoked, no errors
-
-6. **Given** installation runs with `--force` flag
-   **When** `npx ma-agents install --force` is executed
-   **Then** cache modules are replaced (not skipped), fresh install completes successfully
-
-7. **Given** all validation steps complete
-   **When** dev agent completes the story
-   **Then** a test procedure document `docs/validation/bundled-installation-validation.md` exists documenting all validation steps and results
-
-## Tasks / Subtasks
-
-- [x] Task 1: Prepare validation environment (AC: #1, #4)
-  - [x] 1.1 Created `/d/tmp/bmad-validation-test/` and `/d/tmp/bmad-validation-test2/`
-  - [x] 1.2 `npm pack` → `ma-agents-2.19.2.tgz` (753 files)
-  - [x] 1.3 `npm install ma-agents-2.19.2.tgz` succeeded
-  - [x] 1.4 `node_modules/ma-agents/lib/bmad-cache/` confirmed: bmb, cis, gds, tea + cache-manifest.json
-  - [x] 1.5 `bmad-method@6.0.4` confirmed at top-level `node_modules/bmad-method/`
-
-- [x] Task 2: Run full BMAD installation and verify completeness (AC: #1, #2)
-  - [x] 2.1 Ran `installBmad()` directly (equivalent to wizard BMAD install path) — result: true
-  - [x] 2.2 `_bmad/` structure complete: core, bmm, bmb, cis, tea, gds all present
-  - [x] 2.3 `_bmad/bmm/config.yaml` present, v6.0.4, dated 2026-03-16
-  - [x] 2.4 9 agent personas in `_bmad/bmm/agents/`
-  - [x] 2.5 N/A (no IDE agents selected)
-  - [x] 2.6 N/A (MIL-STD-498 not selected)
-
-- [x] Task 3: Validate cache pre-population behavior (AC: #4, #5, #6)
-  - [x] 3.1 Pre-population messages confirmed (skipping on 2nd run, pre-populating on first)
-  - [x] 3.2 `~/.bmad/cache/external-modules/` has bmb, cis, gds, tea
-  - [x] 3.3 Idempotency: all 4 show `~ Cached module exists, skipping` — PASS
-  - [x] 3.4 `--force`: all 4 show `+ Replaced cached module: <mod>` — PASS
-  - [x] 3.5 No git clone: `GIT_TERMINAL_PROMPT=0` set in all execSync calls — PASS
-
-- [x] Task 4: Validate status command output (AC: #3)
-  - [x] 4.1 `npx ma-agents status` → "No skills installed (project scope)"
-  - [x] 4.2 PARTIAL: IDE skills shown correctly; BMAD module status not surfaced (documented as Issue 2)
-  - [x] 4.3 No errors
-
-- [x] Task 5: Workflow smoke test (AC: #2)
-  - [x] 5.1 N/A (IDE not available in validation context)
-  - [x] 5.2 12 workflow YAML files present and readable — PASS
-  - [x] 5.3 9 agent persona `.md` files confirmed — PASS
-
-- [x] Task 6: Document validation results (AC: #7)
-  - [x] 6.1 Created `docs/validation/bundled-installation-validation.md`
-  - [x] 6.2 All 10 validation steps documented with PASS/PARTIAL
-  - [x] 6.3 Issue 1 (fixed) and Issue 2 (observation) documented
-  - [x] 6.4 Environment: Node.js v22.14.0, Windows 10 LTSC 2021, npm v11.7.0, ma-agents v2.19.2
-
-- [x] Task 7: Fix any issues found during validation
-  - [x] 7.1 Root cause: missing `--directory "${projectRoot}"` in all 3 `getBmadCommand` call sites — FIXED in lib/bmad.js
-  - [x] 7.2 Cache pre-population correct — no fix needed
-  - [x] 7.3 `--force` threads correctly — no fix needed
-  - [x] 7.4 Fix committed referencing Story 5.4
-
-## Dev Notes
-
-### Story Nature: Validation + Documentation
-
-This is primarily a **manual validation and documentation story**, not a new code implementation story. The dev agent should:
-1. Execute the validation steps as a hands-on tester
-2. Fix minor issues found (e.g., missing parameter threading, edge cases)
-3. Produce the validation document as the primary deliverable
-
-If substantial code changes are needed, flag them and consider whether a new story is required.
-
-### What Was Built in Stories 5.1–5.3
-
-| Story | Key Deliverable | Status |
-|-------|----------------|--------|
-| 5.1 | `getBmadCommand()` using `require.resolve('bmad-method/tools/bmad-npx-wrapper.js')` — eliminates `npx bmad-method` runtime fetch | done |
-| 5.2 | `npm run build:bmad-cache` script — clones 4 external modules into `lib/bmad-cache/` | done |
-| 5.3 | `prePopulateBmadCache(force=false)` in `lib/bmad.js` — copies bundled cache to `~/.bmad/cache/external-modules/` before bmad-method runs | done |
-
-### Current `lib/bmad.js` State (316 lines)
-
-Key integration points to verify during validation:
-```javascript
-// Line ~38: installBmad()
-await prePopulateBmadCache(force);
-execSync(command, { stdio: 'inherit', cwd: projectRoot, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } });
-
-// Line ~63: updateBmad()
-await prePopulateBmadCache(force);
-execSync(command, { stdio: 'inherit', cwd: projectRoot, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } });
-
-// Line ~137: applyCustomizations()
-await prePopulateBmadCache(force);
-execSync(command, { stdio: 'inherit', cwd: projectRoot, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } });
-
-// Exports (line 311+):
-module.exports = { isBmadInstalled, installBmad, updateBmad, applyCustomizations, prePopulateBmadCache };
-```
-
-### Bundled Cache State (Current)
-
-`lib/bmad-cache/` already exists and contains:
-- `bmb/` — bmad-builder (commit `4a790580`)
-- `cis/` — bmad-module-creative-intelligence-suite (commit `e6f64391`)
-- `gds/` — bmad-module-game-dev-studio (commit `962c91e3`)
-- `tea/` — bmad-method-test-architecture-enterprise (commit `494044af`)
-- `cache-manifest.json` — generated 2026-03-16T12:31:50.732Z
-
-### Validation Document Template
-
-Create `docs/validation/bundled-installation-validation.md` with this structure:
-
-```markdown
-# Bundled BMAD Installation Validation
-
-**Package version:** ma-agents X.Y.Z
-**bmad-method version:** 6.0.4
-**Validation date:** YYYY-MM-DD
-**Tester environment:** Node.js vX.X.X, OS: ..., npm vX.X.X
-
-## Validation Steps
-
-| Step | Description | Result | Notes |
-|------|-------------|--------|-------|
-| V1 | npm pack → tarball contains lib/bmad-cache/ | PASS/FAIL | |
-| V2 | npm install from tarball — bmad-method present in node_modules | PASS/FAIL | |
-| V3 | npx ma-agents install — cache pre-population messages appear | PASS/FAIL | |
-| V4 | Post-install: ~/.bmad/cache/external-modules/ has 4 modules | PASS/FAIL | |
-| V5 | Post-install: _bmad/ has core + bmm + bmb + cis + tea + gds | PASS/FAIL | |
-| V6 | Idempotency: second install skips existing cache | PASS/FAIL | |
-| V7 | --force: replaces cache modules | PASS/FAIL | |
-| V8 | npx ma-agents status shows correct output | PASS/FAIL | |
-| V9 | No git clone or npm fetch during offline simulation | PASS/FAIL | |
-| V10 | BMAD workflows present and syntactically valid | PASS/FAIL | |
-
-## Issues Found
-
-[Document any issues discovered during validation]
-
-## Conclusion
-
-[Overall assessment: Installation is deterministic and complete / Issues require follow-up story]
-```
-
-### Architecture Compliance
-
-- **Decision P2-6** (Bundled BMAD Installation): This story validates the complete 2-step mechanism is working: (1) cache pre-population from `lib/bmad-cache/` → `~/.bmad/cache/external-modules/`, (2) bmad-method invoked from npm dependency via `require.resolve`.
-- **NFR20** (Version Pinning): Verify `bmad-method@6.0.4` is in `node_modules/` when installed from tarball.
-- **NFR21** (Deterministic Installation): Core validation goal — same package = same `_bmad/` output.
-- **NFR2** (Offline Operation): Simulating air-gapped by installing from tarball confirms no network dependency.
-
-### Critical Anti-Patterns to Check During Validation
-
-1. **Pre-population called AFTER bmad-method invocation** — verify `prePopulateBmadCache()` is at lines 38, 63, 137 (BEFORE execSync)
-2. **`GIT_TERMINAL_PROMPT=0` missing** — verify env option is present on all 3 execSync calls
-3. **`lib/bmad-cache/` not shipped in tarball** — run `npm pack --dry-run` and confirm `lib/bmad-cache/` is included (check `.npmignore`)
-4. **`force` parameter not threading** — if `installBmad(projectRoot, force=false)` doesn't pass `force` to `prePopulateBmadCache()`, AC #6 fails
-
-### Check `.npmignore` for Cache Inclusion
-
-Run this to verify `lib/bmad-cache/` ships in the tarball:
-```bash
-npm pack --dry-run 2>&1 | grep "bmad-cache"
-```
-Expected output: lines listing `lib/bmad-cache/bmb/...`, `lib/bmad-cache/cis/...`, etc.
-If missing, `.npmignore` must NOT exclude `lib/bmad-cache/` — check and fix.
-
-### File Structure During Validation
-
-The test project should end up with:
-```
-test-project/
-├── _bmad/
-│   ├── core/           ← bmad-method core
-│   ├── bmm/            ← bmad-method module (with config.yaml, agents/, workflows/)
-│   ├── bmb/            ← builder module
-│   ├── cis/            ← creative intelligence suite
-│   ├── tea/            ← test architecture enterprise
-│   └── gds/            ← game dev studio
-├── node_modules/
-│   └── ma-agents/
-│       ├── lib/bmad-cache/    ← bundled cache (all 4 modules)
-│       └── node_modules/bmad-method/  ← pinned 6.0.4
-└── package.json
-```
-
-### Testing Standards
-
-- No automated test suite exists yet (Epic 7). Manual validation is sufficient.
-- Document all results in the validation document (Task 6).
-- If any test fails, fix the root cause in `lib/bmad.js` (or related files) before marking done.
-- The validation document serves as the acceptance evidence for this story.
-
-### Previous Story Intelligence (5.3)
-
-Key learnings from Story 5.3 that affect validation:
-- `prePopulateBmadCache()` signature changed: removed `projectRoot` param (M1 fix from code review) — call is now `await prePopulateBmadCache(force)`, not `prePopulateBmadCache(projectRoot, force)`
-- `force` parameter was added to `installBmad()`, `updateBmad()`, `applyCustomizations()` signatures during code review (H2 fix) — verify it's correctly threaded to `prePopulateBmadCache(force)` in all 3 callsites
-- Summary log only prints when `copied > 0 || replaced > 0` (M2 fix) — in idempotency test (all skipped), no summary line will appear. This is CORRECT behavior.
-- `fs.existsSync()` replaced with `await fs.pathExists()` (M3 fix) — consistent async usage throughout
-- Dev note from 5.3: "Design decision on determinism — bmad-method's `git fetch` on existing cache dirs succeeds silently on connected machines but does not alter outcome. For air-gapped, `git fetch` fails silently and pre-populated cache is used as-is." → Validate this in AC #4.
-
-### Git Intelligence
-
-Recent commits showing Epic 5 completion:
-```
-5fdbf70 feat: Pre-populate BMAD cache before bmad-method invocation (Story 5.3)
-0c32ceb feat: Add BMAD cache build script (Story 5.2)
-```
-
-Story 5.1 established `getBmadCommand()` using `require.resolve` — this is the foundation. Story 5.2 built the cache. Story 5.3 pre-populates it. Story 5.4 confirms it all works together.
-
-### References
-
-- [Source: architecture.md, Decision P2-6] — Bundled BMAD Installation architecture, full mechanism
-- [Source: epics.md, Story 5.4] — Acceptance criteria and technical notes (validation story)
-- [Source: prd.md, FR74-FR76] — Bundle bmad-method, bundle external modules, pre-populate cache
-- [Source: prd.md, NFR20-NFR21] — Version pinning and deterministic installation
-- [Source: prd.md, NFR2] — Air-gapped operation requirement
-- [Source: 5-3-pre-populate-bmad-cache.md] — Implemented prePopulateBmadCache(), GIT_TERMINAL_PROMPT=0, all 3 execSync sites
-- [Source: lib/bmad.js, lines 38/63/137] — Pre-population call sites (BEFORE execSync)
-- [Source: lib/bmad-cache/cache-manifest.json] — Bundled modules: bmb, cis, gds, tea at bmad-method v6.0.4
-
-## Dev Agent Record
-
-### Agent Model Used
-
-claude-sonnet-4-6
-
-### Debug Log References
-
-N/A — validation story, no automated test suite.
-
-### Completion Notes List
-
-1. **Critical bug found and fixed (H1):** `lib/bmad.js` — all 3 `getBmadCommand()` callsites for `installBmad`, `updateBmad`, `applyCustomizations` were missing `--directory "${projectRoot}"`. bmad-method v6.0.4 only skips the directory prompt when `--directory` is explicitly provided; without it, non-TTY execSync silently exits with code 0 and no `_bmad/` is created.
-
-2. **AC#3 partial gap documented:** `npx ma-agents status` reports IDE skill installs only; BMAD module status not surfaced. Documented as a UX observation (Issue 2) — future story recommended.
-
-3. **All other ACs passed** after the `--directory` fix was applied. Deterministic installation confirmed: same tarball → same `_bmad/` structure on every run.
-
-### File List
-
-- `lib/bmad.js` — Fixed: added `--directory "${projectRoot}"` to 3 getBmadCommand callsites (lines 26, 51, 128)
-- `docs/validation/bundled-installation-validation.md` — Created: validation results for Story 5.4
-- `_bmad-output/implementation-artifacts/5-4-validate-bundled-installation.md` — Updated: status→done, tasks→[x], dev record filled

package/_bmad-output/implementation-artifacts/done/6-1-methodology-presentation-bundle.md

@@ -1,173 +0,0 @@
-# Story 6.1: Bundle Methodology Presentation with Installation
-
-Status: review
-
-<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
-
-## Story
-
-As a **team lead**,
-I want the BMAD-METHOD presentation included when ma-agents is installed,
-So that new team members can learn the methodology without needing separate training materials.
-
-## Acceptance Criteria
-
-1. **Given** a methodology presentation file exists in the ma-agents package
-   **When** `npx ma-agents install` is run with BMAD installation
-   **Then** the presentation is copied to the project's BMAD output directory (e.g., `_bmad-output/methodology/`)
-   **And** the user is informed of the presentation location in the install summary
-
-2. **Given** the presentation already exists in the target directory
-   **When** a subsequent install or update is run
-   **Then** the presentation is updated only if a newer version exists
-   **And** existing copies are not overwritten without the `--force` flag
-   **Note:** `--force` semantics are consistent with existing usage — `--force` means "overwrite/force operations" across the codebase (see Epic 1 Story 1.1: `--yes` skips prompts, `--force` forces overwrites). CI/CD pipelines using `--force` will intentionally get the latest methodology content.
-
-3. **Given** BMAD is NOT installed (user only installed skills)
-   **When** the install completes
-   **Then** the methodology presentation is NOT copied (it's part of the BMAD bundle, not standalone skills)
-
-4. **Given** the methodology content is bundled
-   **When** the npm package is published
-   **Then** the presentation files are included in the package (listed in `package.json` `files` or not excluded by `.npmignore`)
-   **And** the package size increase is documented
-
-5. **Given** ma-agents is upgraded to a newer version with updated methodology content
-   **When** the user runs `npx ma-agents install` with BMAD (or `--action update`)
-   **Then** the methodology version check from AC #2 applies — newer content is deployed, same-version content is skipped
-   **And** this uses the same code path as the initial install (no separate update mechanism needed)
-
-## Tasks / Subtasks
-
-- [x] Task 1: Create methodology presentation content (AC: #1)
-  - [x] 1.1: Author methodology presentation in `lib/methodology/` directory (markdown or PDF format)
-  - [x] 1.2: Include sections: What is BMAD-METHOD, SDLC phases covered, agent personas available, skill system overview, getting started guide
-  - [x] 1.2a: Content source: derive from existing README.md, QUICK_START.md, and BMAD-METHOD documentation. This is a compilation/curation task, not original authoring
-  - [x] 1.2b: Content review: Chief Architect (Alon) reviews and approves methodology content before merge. This is NOT a developer-authored document — the developer compiles from existing sources, Alon validates accuracy
-  - [x] 1.3: Add a `version.json` or version marker in the methodology directory for version comparison (AC: #2)
-- [x] Task 2: Add methodology deployment to BMAD install pipeline (AC: #1, #3)
-  - [x] 2.1: In `lib/bmad.js`, add methodology copy step during BMAD installation (after the main BMAD install completes)
-  - [x] 2.2: Copy `lib/methodology/` contents to `_bmad-output/methodology/` in the target project
-  - [x] 2.3: Use `fs-extra` `fs.copy()` consistent with existing BMAD content deployment patterns (see `bmad.js` lines 86, 102, 131, 138)
-  - [x] 2.4: Add install summary message: `chalk.green('Methodology presentation available at: _bmad-output/methodology/')`
-  - [x] 2.5: Only execute this step when BMAD installation is requested (not for skill-only installs)
-- [x] Task 3: Implement version-aware updates (AC: #2)
-  - [x] 3.1: On subsequent installs, compare version marker in source vs target
-  - [x] 3.2: If target version is same or newer, skip copy (print: "Methodology presentation is up to date")
-  - [x] 3.3: If target version is older, copy only if `--force` flag is present OR prompt user
-  - [x] 3.4: Follow the additive-only install pattern — never delete existing methodology files (NFR5)
-- [x] Task 4: Package inclusion (AC: #4)
-  - [x] 4.1: Verify `lib/methodology/` is included in npm package (check `package.json` files field or `.npmignore`)
-  - [x] 4.2: Measure package size increase and document it
-  - [x] 4.3: If presentation includes large files (PDF, images), consider compression or markdown-only format to minimize package size
-
-## Dev Notes
-
-### Architecture Compliance
-
-- **BMAD pipeline extension:** Methodology deployment is a new step in the BMAD install pipeline. It should execute AFTER the existing 6-stage BMAD pipeline completes, not interrupt it. [Source: architecture.md#Pipeline-Architecture]
-- **Additive-only:** Follow NFR5 — never remove existing files during install. Version comparison prevents unwanted overwrites. [Source: architecture.md#Error-Handling]
-- **BMAD-conditional:** Only deploy when BMAD installation is requested. The `installBmad()` function in `bmad.js:13` is the entry point. [Source: lib/bmad.js:13]
-
-### Existing BMAD Content Deployment Pattern
-
-The `bmad.js` module already deploys content to target projects using `fs-extra`:
-
-```javascript
-// From bmad.js — existing pattern for copying content:
-await fs.copy(path.join(sourceDir, file), path.join(configTargetDir, file));  // line 86
-await fs.copy(workflowSourceDir, workflowTargetDir);  // line 131
-await fs.copy(templateSourceDir, templateTargetDir);  // line 138
-```
-
-Follow this exact pattern for methodology deployment. The `fs-extra` dependency is already available.
-
-### Methodology Content Format Decision
-
-**Recommended: Markdown-only** — aligns with the project's plain-text philosophy:
-- Small package size impact (~50-100KB for comprehensive markdown)
-- Renders well in any editor or GitHub
-- Can be converted to PDF/slides by the user if needed
-- No binary files to manage
-
-**Alternative: PDF** — better for formal presentation:
-- Larger package size impact (~1-5MB per presentation)
-- Not editable, less version-friendly
-- Better visual presentation for team meetings
-
-### `_bmad-output/methodology/` Target Directory
-
-The `_bmad-output/` directory is version-controlled project knowledge (per architecture F3 decision — not gitignored). The methodology presentation becomes part of the project's knowledge base, committed alongside planning artifacts and implementation artifacts.
-
-### Console Output Pattern
-
-Follow existing console output conventions from `bmad.js`:
-```
-  ✓ Methodology presentation installed to _bmad-output/methodology/
-  Hint: Share this with your team for BMAD-METHOD onboarding
-```
-
-Or if up to date:
-```
-  ✓ Methodology presentation is up to date (v1.0.0)
-```
-
-### Sprint Status Note: Story 6.2 Not in Sprint
-
-Epic 6 Story 6.2 (Add Methodology Overview Command — `npx ma-agents methodology`) exists in the epics file but was not included in sprint planning. If 6-1 is completed, 6-2 can be added via correct-course if desired.
-
-### Phase 2 Dependencies (Cross-Reference)
-
-- **Epic 8 (BMAD extension module):** Story 6.1 modifies `lib/bmad.js`. Phase 2 also modifies `bmad.js` for extension module deployment. If Epic 8 ships first, the methodology deployment step must be added after the extension deployment step. Coordinate insertion point.
-- **Content directory:** Methodology lives in `lib/methodology/` which is separate from `lib/bmad-extension/`. No conflict, but both are deployed by `bmad.js`.
-
-### Critical Guardrails
-
-- **Do NOT modify the BMAD 6-stage pipeline order** — methodology deployment is a post-pipeline step [Source: architecture.md#Pipeline-Architecture]
-- **Only modify `lib/bmad.js`** for deployment logic [Source: architecture.md#Module-Boundaries]
-- **Use `fs-extra` `fs.copy()`** — already a project dependency, no new deps needed [Source: package.json:31]
-- **Use `path.join()` for all paths** [Source: architecture.md#Enforcement-Guidelines]
-- **No new npm dependencies** [Source: architecture.md#Anti-Patterns]
-
-### Project Structure Notes
-
-- Files to create: `lib/methodology/` directory with presentation content
-- Files to modify: `lib/bmad.js` (add methodology deployment step after BMAD install)
-- No changes to `installer.js`, `agents.js`, or `cli.js`
-
-### References
-
-- [Source: _bmad-output/planning-artifacts/epics.md#Epic-6] — Story 6.1 and 6.2 definitions
-- [Source: _bmad-output/planning-artifacts/architecture.md#Pipeline-Architecture] — BMAD 6-stage pipeline
-- [Source: _bmad-output/planning-artifacts/architecture.md#Anti-Patterns] — No new dependencies
-- [Source: lib/bmad.js] — BMAD install pipeline, existing fs.copy patterns
-- [Source: package.json] — fs-extra dependency, package configuration
-
-## Dev Agent Record
-
-### Agent Model Used
-claude-sonnet-4-6
-
-### Debug Log References
-None — implementation straightforward.
-
-### Completion Notes List
-- ✅ Bundled `docs/BMAD_AI_Development_Training.pptx` into `lib/methodology/` (3.2MB PPTX)
-- ✅ Created `lib/methodology/version.json` (v1.0.0) for version comparison
-- ✅ Added `deployMethodology(projectRoot, force)` to `lib/bmad.js` with semver version comparison; skips if target is same/newer, overwrites with `--force`
-- ✅ Added `deployOpenPresentationSkill()` to auto-install `/open-presentation` skill to `.claude/skills/` and update MANIFEST.yaml
-- ✅ `deployMethodology()` is called from both `installBmad()` and `updateBmad()` — only runs when BMAD is installed (AC #3 satisfied)
-- ✅ Package size increase: ~3.2MB (PPTX). No `files` field in `package.json` — all files included by default
-- ✅ Created `skills/open-presentation/` skill source and `.claude/skills/open-presentation/SKILL.md` for `/open-presentation` slash command (user requirement)
-
-### File List
-- `lib/methodology/BMAD_AI_Development_Training.pptx` (new)
-- `lib/methodology/version.json` (new)
-- `lib/bmad.js` (modified — added `deployMethodology()` and `deployOpenPresentationSkill()`)
-- `skills/open-presentation/skill.json` (new)
-- `skills/open-presentation/SKILL.md` (new)
-- `.claude/skills/open-presentation/SKILL.md` (new)
-- `.claude/skills/MANIFEST.yaml` (modified — added open-presentation entry)
-
-### Change Log
-- 2026-03-18: Implemented Story 6.1 — methodology presentation bundle with version-aware deployment and /open-presentation skill

package/_bmad-output/implementation-artifacts/done/8-1-move-instruction-injection-to-top.md

@@ -1,131 +0,0 @@
-# Story 8.1: Move Instruction Injection to TOP Priority Position
-
-Status: done
-
-<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
-
-## Story
-
-As a **Chief Architect**,
-I want the MA-AGENTS-START instruction block injected at the TOP of agent instruction files (after any file headers),
-So that skills have highest priority during LLM context processing.
-
-## Acceptance Criteria
-
-1. **Given** installer runs for any markdown-based agent,
-   **When** instruction block is injected,
-   **Then** block is placed at TOP after file headers (YAML frontmatter),
-   **And** skipPatterns from agent's injectionStrategy in agents.js are respected
-
-2. **Given** instruction file already has MA-AGENTS-START block,
-   **When** installer runs again,
-   **Then** existing block is found and replaced in-place,
-   **And** no duplicate blocks created
-
-3. **Given** instruction file has no existing ma-agents block,
-   **When** installer injects for first time,
-   **Then** block inserted after skipped headers but before all other content
-
-## Tasks / Subtasks
-
-- [x] Task 1: Implement header-skip logic in `updateAgentInstructions()` (AC: #1, #3)
-  - [x] 1.1: In `lib/installer.js` at line 110, modify `updateAgentInstructions()` to accept and read `agent.injectionStrategy` (defaults to `{ position: 'top', skipPatterns: [] }` if not present)
-  - [x] 1.2: Create a helper function `findInsertionPoint(content, skipPatterns)` that returns the character index after all skipped headers
-  - [x] 1.3: For skipPattern `'---'`, implement YAML frontmatter detection: find the opening `---` on line 1 (or after leading whitespace), then find the closing `---`, skip past the entire block including trailing newline
-  - [x] 1.4: Return insertion index as the position immediately after all skipped headers
-
-- [x] Task 2: Change non-BMAD branches from append to top-insert (AC: #1, #3)
-  - [x] 2.1: Understand the three-branch structure in `updateAgentInstructions()` (lines 138-156):
-    - **IF branch** (lines 141-143): File exists AND has existing MA-AGENTS block → regex replace in-place. NO CHANGE needed.
-    - **ELSE branch** (line 145): File exists, NO existing block → currently appends. CHANGE to top-insert.
-    - **ELSE-IF branch** (lines 147-153): File does NOT exist AND agent is BMAD → skip (guard clause). NO CHANGE needed.
-    - **Final ELSE** (lines 154-155): File does NOT exist AND agent is NOT BMAD → creates new file. CHANGE to top-insert.
-  - [x] 2.2: At line 145, replace `content += wrappedInstruction` with top-insertion using `findInsertionPoint()`
-  - [x] 2.3: Splice `wrappedInstruction` into content: `content = content.slice(0, insertIdx) + wrappedInstruction + content.slice(insertIdx)`
-  - [x] 2.4: At lines 154-155, replace `content = wrappedInstruction` with top-insertion (for new files, functionally identical but keeps logic consistent)
-  - [x] 2.5: Ensure a blank line separates the injected block from subsequent content in both branches
-
-- [x] Task 3: Preserve existing replace-in-place behavior (AC: #2)
-  - [x] 3.1: Verify the existing regex replacement at line 141-143 (`content.replace(regex, wrappedInstruction.trim())`) still works correctly — this handles the update scenario
-  - [x] 3.2: No changes needed to the IF branch (lines 141-143). Both the ELSE branch (line 145) and Final ELSE (lines 154-155) change to top-insert
-  - [x] 3.3: Add a test scenario: inject once (goes to top), then run again (replaces in-place, stays at top)
-
-- [x] Task 4: Handle edge cases (AC: #1, #3)
-  - [x] 4.1: Empty file — insert wrappedInstruction as sole content
-  - [x] 4.2: File with only YAML frontmatter — insert after frontmatter
-  - [x] 4.3: File with no frontmatter — insert at position 0
-  - [x] 4.4: File with multiple `---` (e.g., horizontal rules later in file) — only skip the frontmatter pair at the very beginning, not later `---` lines
-  - [x] 4.5: BMAD agent files (.md) — same logic applies; frontmatter skip works the same way
-  - [x] 4.6: Cline dual instruction files — Cline has `instructionFiles: ['.cline/clinerules.md', '.clinerules']`. Both files receive injection. The `.clinerules` file (no .md extension) is treated identically — same `findInsertionPoint()` logic applies. Verify both files get correct top-insertion.
-
-- [x] Task 5: Manual verification (AC: #1, #2, #3)
-  - [x] 5.1: Create a test `.md` file with YAML frontmatter + existing content, run injection, verify block appears after frontmatter and before content
-  - [x] 5.2: Run injection a second time on the same file, verify no duplicates and block stays in position
-  - [x] 5.3: Test with a file that has no frontmatter, verify block at position 0
-  - [x] 5.4: Test with BMAD agent instruction file (`_bmad/bmm/agents/sre.md`)
-
-## Dev Notes
-
-### Architecture Compliance
-
-- **Single module change:** Only `lib/installer.js` is modified in this story
-- **Agent-agnostic:** The installer reads `injectionStrategy` from the agent object but does NOT hardcode agent-specific logic. If `injectionStrategy` is missing, it defaults to `{ position: 'top', skipPatterns: [] }`
-- **Dependency on Story 8.2:** Story 8.2 adds the `injectionStrategy` property to agents.js. This story should implement the logic that reads it, with a sensible default so it works even before 8.2 is complete
-- **path.join():** Not relevant here (operating on file content, not paths)
-
-### Critical Guardrails
-
-- Do NOT change the IF branch (lines 141-143) that handles replace-in-place — it already works correctly
-- Do NOT hardcode agent names or agent-specific logic in installer.js
-- Do NOT modify agents.js in this story (that is Story 8.2)
-- The `findInsertionPoint()` function must handle the `---` pattern as a YAML frontmatter block delimiter (between opening and closing `---`), NOT as a single-line skip
-- Ensure backward compatibility: if `injectionStrategy` is undefined on an agent, default to top insertion with no skip patterns
-
-### Project Structure Notes
-
-- **File to modify:** `lib/installer.js` — specifically the `updateAgentInstructions()` function starting at line 110
-- **Lines of interest:**
-  - Lines 130-132: marker definitions (`MA-AGENTS-START`, `MA-AGENTS-END`, `wrappedInstruction`)
-  - Lines 141-143: existing regex replace (IF branch — keep as-is)
-  - Line 145: current append logic (ELSE branch — change to top-insert)
-  - Lines 147-153: BMAD guard clause (ELSE-IF — keep as-is, skips BMAD files not yet deployed)
-  - Lines 154-155: new non-BMAD file creation (Final ELSE — change to top-insert)
-- **New helper:** `findInsertionPoint(content, skipPatterns)` — add as a private function in installer.js
-
-### References
-
-- [Source: lib/installer.js#L110-L161] — `updateAgentInstructions()` function
-- [Source: lib/agents.js#L17-L253] — Agent registry (injectionStrategy will be added by Story 8.2)
-
-### Dependencies
-- **Must be implemented BEFORE Story 8.2** — This story implements the `findInsertionPoint()` logic that reads `injectionStrategy`. Story 8.2 adds the data. This story uses a sensible default (`{ position: 'top', skipPatterns: [] }`) so it works before 8.2 is complete.
-
-## Dev Agent Record
-
-### Agent Model Used
-Claude Opus 4.6 (1M context)
-
-### Debug Log References
-- No debug issues encountered
-
-### Completion Notes List
-- Implemented `findInsertionPoint(content, skipPatterns)` helper function in `lib/installer.js` that detects YAML frontmatter (`---` blocks) and returns insertion index after them
-- Changed ELSE branch (existing file, no block) from append (`content += wrappedInstruction`) to top-insert using `findInsertionPoint()`
-- Changed Final ELSE branch (new non-BMAD file) to use consistent top-insert logic
-- IF branch (replace-in-place) left unchanged per guardrails — regex replacement still works correctly
-- BMAD guard clause left unchanged — BMAD files still skipped when not yet deployed
-- Default `injectionStrategy` is `{ position: 'top', skipPatterns: [] }` when not present on agent, ensuring backward compatibility before Story 8.2
-- Exported `findInsertionPoint` and `_testUpdateAgentInstructions` for test access
-- Created 24 automated tests covering: findInsertionPoint unit tests (11), integration tests for top-insertion and replace-in-place (5), edge case tests (7), extra integration coverage (1)
-- All manual verification scenarios passed: frontmatter skip, no-duplicate on re-run, no-frontmatter top-insert, BMAD skip, Cline dual files
-- Code review follow-ups addressed: H1 (dead code removed), H2 (leading blank line fixed), M1 (double newline fixed), M2 (Cline dual-file test added), M3 (BMAD agent tests added), M4 (File List updated), L1 (skipPatterns integration test added), L2 (test 4.3 added)
-
-### File List
-- `lib/installer.js` — Added `findInsertionPoint()` helper, changed append to top-insert in ELSE/Final-ELSE branches, exported new functions
-- `test/instruction-injection.test.js` — New test file with 24 tests for story 8.1
-- `_bmad-output/implementation-artifacts/sprint-status.yaml` — Status tracking updates
-- `_bmad-output/implementation-artifacts/8-1-move-instruction-injection-to-top.md` — Story file updates
-
-### Change Log
-- 2026-03-17: Implemented Story 8.1 — moved instruction injection from append to top-insert position, with YAML frontmatter skip support via `findInsertionPoint()`. All 24 tests pass, no regressions.
-- 2026-03-17: Addressed code review findings — 6 items resolved (H1, H2, M1, M2, M3, M4) plus 2 low-priority items (L1, L2). L3 acknowledged as accepted trade-off.