ma-agents 3.6.2 → 3.8.0

package/_bmad-output/implementation-artifacts/done/13-2-install-pipeline-integration.md

@@ -1,138 +0,0 @@
-# Story 13.2: Integrate Project-Context Generation into Install Pipeline
-
-Status: done
-
-## Story
-
-As a **DevOps Engineer**,
-I want project-context.md generated automatically at the end of every project-level skill installation,
-So that every ma-agents project has the constitutional document without any manual step.
-
-## Acceptance Criteria
-
-1. `generateProjectContext()` (from Story 13.1) is called at the end of the install pipeline for project-level installs
-2. After a successful project-level install, `_bmad-output/project-context.md` exists on disk
-3. The generated file contains the stamped template content with correct MANIFEST paths for all installed platforms
-4. When `_bmad-output/project-context.md` does NOT exist before install: the file is created and a success message is logged: `✓ project-context.md generated at _bmad-output/project-context.md` (FR79)
-5. When `_bmad-output/project-context.md` ALREADY EXISTS before install: the MANIFEST paths section (between `<!-- ma-agents:manifest-paths-start -->` and `<!-- ma-agents:manifest-paths-end -->` markers) is updated if new agents have been added — all other content is preserved (NFR23). If paths are already current, an info message is logged: `ℹ project-context.md already up to date`. If paths were updated, a success message is logged: `✓ project-context.md manifest paths updated` (FR84)
-6. Global installs (targeting `~/.config/<agent>/` or equivalent user-level paths) do NOT trigger project-context generation — only project-level installs do
-7. Non-interactive CI/CD mode (`--yes` flag) produces identical project-context behaviour — no interactive prompts, generation fires automatically (FR84)
-8. If `_bmad-output/` directory does not exist, it is created before writing the file (consistent with existing `_bmad-output` policy from Epic 10)
-9. The write operation is additive-only — it does not modify any other file in `_bmad-output/` (NFR23)
-10. If `generateProjectContext()` throws (e.g., template file missing), the error is logged with context but does NOT abort the entire install — project-context generation failure is non-fatal
-
-## Tasks / Subtasks
-
-- [x] Task 1: Identify the correct integration point in `installer.js` (AC: #1, #6)
-  - [x] 1.1 Read `lib/installer.js` to find where project-level installation completes (after manifest update, after skill copy)
-  - [x] 1.2 Identify how to detect project-level vs global install (check for `projectRoot` vs user home detection, or existing `isProjectInstall` logic)
-  - [x] 1.3 Confirm `installedAgents` list is available at that point (or can be derived from manifest state)
-
-- [x] Task 2: Implement the pipeline integration (AC: #1-#5, #7-#10)
-  - [x] 2.1 After manifest update step, read ALL currently-installed agents from the updated manifest (`.ma-agents.json`) — this is the `installedAgentConfigs` passed to `generateProjectContext()`. Never pass only the current-run agents; the manifest is the source of truth for completeness (architecture Decision P2-7)
-  - [x] 2.2 Add call using the two-layer pattern from architecture P2-7:
-    ```javascript
-    if (isProjectInstall) {
-      const outputPath = path.join(projectRoot, '_bmad-output', 'project-context.md');
-      if (await fs.pathExists(outputPath)) {
-        console.log(chalk.blue('ℹ project-context.md already exists — skipping generation'));
-      } else {
-        try {
-          const allAgents = readAllAgentsFromManifest(projectRoot); // read .ma-agents.json
-          await fs.ensureDir(path.join(projectRoot, '_bmad-output'));
-          const content = await generateProjectContext(projectRoot, allAgents);
-          await fs.writeFile(outputPath, content, 'utf8');
-          console.log(chalk.green('✓ project-context.md generated at _bmad-output/project-context.md'));
-        } catch (err) {
-          console.log(chalk.yellow(`⚠ project-context generation failed: ${err.message} — continuing install`));
-        }
-      }
-    }
-    ```
-  - [x] 2.3 Verify `fs.ensureDir` is already available (it is — `fs-extra` is a dependency)
-
-- [x] Task 3: Validate global install exclusion (AC: #6)
-  - [x] 3.1 Read how installer.js currently distinguishes project-level vs global install
-  - [x] 3.2 Ensure the `isProjectInstall` condition (or equivalent) correctly gates project-context generation
-  - [x] 3.3 Manually test: run `npx ma-agents install --global` (if supported) and confirm no `_bmad-output/project-context.md` is created in home directory
-
-- [x] Task 4: Idempotency verification (AC: #5)
-  - [x] 4.1 Create a test project with existing `_bmad-output/project-context.md` (any content)
-  - [x] 4.2 Run `npx ma-agents install` on that project
-  - [x] 4.3 Confirm the existing file content is unchanged
-  - [x] 4.4 Confirm the info message appears in output
-
-- [x] Task 5: CI/CD mode verification (AC: #7)
-  - [x] 5.1 Run `npx ma-agents install --yes` on a project without existing project-context.md
-  - [x] 5.2 Confirm `_bmad-output/project-context.md` is generated without interactive prompts
-  - [x] 5.3 Run again — confirm idempotency in `--yes` mode
-
-## Dev Notes
-
-### Architecture Compliance
-
-- **Decision P2-7**: Story 13.2 implements the "write file" half of the two-part generation pattern. Story 13.1 implemented the "return stamped content" half.
-- **NFR23** (Additive-only): `fs.pathExists` check before write is the enforcement mechanism. The write path only triggers if the file does not exist.
-- **Epic 10** (`_bmad-output` policy): `_bmad-output/` is never gitignored (enforced by Epic 10). `fs.ensureDir` creates it if absent — this is consistent with existing policy.
-
-### Install Pipeline Stage
-
-The call to `generateProjectContext()` belongs **after** the manifest update stage (Stage 5 of the install pipeline) but before the final success message. This ensures:
-1. All agent configs are finalized in the manifest before we read them
-2. The MANIFEST.yaml files have already been written to the agent skill directories
-3. The user sees project-context generation as the final step of a successful install
-
-### Project-Level Detection
-
-Read `installer.js` to verify the current detection mechanism. Likely candidates:
-- Presence of a `package.json` or `.git` directory in `projectRoot`
-- A `--project` flag vs `--global` flag in CLI arguments
-- The existing install path resolution logic that distinguishes project vs user-level paths
-
-Do NOT assume — read the code first.
-
-### `installedAgentConfigs` Composition
-
-Pass the agent config objects that were actually installed in this run. Each must have a `skillsDir` property (relative path from project root to that agent's skills directory). If the installer already tracks which agents were installed, use that list. If not, derive from the manifest.
-
-### Error Handling Philosophy
-
-Project-context generation is a **convenience feature**, not a critical install step. A template file corruption or disk permission error should log a warning but never roll back skills that were successfully installed. This is the same philosophy as the audit trail — helpful but not blocking.
-
-### Source Tree Components to Touch
-
-| File | Change |
-|------|--------|
-| `lib/installer.js` | ADD — integration call at end of project-level install pipeline |
-
-### Epic 13 Cross-Story Context
-
-**Story 13.1** (prerequisite): Created `generateProjectContext()` function and template file
-**Story 13.2** (this): Wires the generator into the install pipeline with file write + idempotency
-**Story 13.3**: Updates BMAD critical_actions to load project-context.md at agent activation
-**Story 13.4**: Adds expansion trigger to retrospective workflow
-
-## Dev Agent Record
-
-### Agent Model Used
-claude-sonnet-4-6
-
-### Debug Log References
-- Integration point: inside `if (scope === 'project')` block in `installSkill`, after the Claude Code hook deployment. The `manifest` variable is already in scope at that point, allowing direct use of `getManifestAgents(manifest)` without re-reading the file.
-- Project-level detection: `scope === 'project'` parameter controls whether project-context generation fires. Global installs use `scope === 'global'` and are excluded automatically.
-- First run created `_bmad-output/project-context.md`; subsequent runs log "already exists — skipping generation". Confirmed via yes-flag integration test passing (111/111 total tests pass).
-
-### Completion Notes List
-- Added project-context generation call inside `if (scope === 'project')` block in `installSkill` in `lib/installer.js`.
-- Uses `getManifestAgents(manifest).map(id => getAgent(id)).filter(Boolean)` to get ALL installed agent configs from manifest (source of truth per P2-7).
-- `fs.pathExists` check gates first-install vs update path (AC #8). `fs.ensureDir` creates `_bmad-output/` if absent. Full try/catch makes generation non-fatal (AC #10).
-- **`updateProjectContextManifestPaths(outputPath, installedAgents)`** added to `lib/installer.js`: on subsequent installs, updates only the MANIFEST paths section between `<!-- ma-agents:manifest-paths-start -->` / `<!-- ma-agents:manifest-paths-end -->` markers. Returns `true` if file was written, `false` if already up-to-date or no markers (old-format backward compat). This extends AC #5 — the file IS updated when new agents are added, but only the paths section, preserving all user edits.
-- `projectContextHandled` guard added to `installSkill` to prevent redundant project-context operations when multiple path groups share a skill install.
-- All tests pass (no regressions).
-
-### File List
-- `lib/installer.js` — MODIFIED (project-context generation call in installSkill; `updateProjectContextManifestPaths` function added for idempotent subsequent-install path updates)
-
-## Change Log
-- 2026-03-19: Story created (Epic 13, Story 13.2)
-- 2026-03-20: Story implemented — pipeline integration added to installSkill, all tests pass

package/_bmad-output/implementation-artifacts/done/13-3-bmad-critical-actions-update.md

@@ -1,150 +0,0 @@
-# Story 13.3: Update BMAD Extension Critical_Actions to Load Project-Context
-
-Status: done
-
-## Story
-
-As a **Chief Architect**,
-I want all BMAD agent `critical_actions` to load `_bmad-output/project-context.md` at activation,
-So that BMAD workflow agents follow project-context rules in every session — not just IDE agents reading CLAUDE.md or equivalent.
-
-## Acceptance Criteria
-
-1. **12** agent `.customize.yaml` files in `lib/bmad-extension/agents/` are updated: 4 custom (SRE, DevOps, Cyber, MIL-498) + 7 built-in BMM (PM, Architect, Dev, QA, SM, Tech Writer, UX Designer) + **bmad-master** (FR86). CIS module agents are deliberately excluded — see Dev Notes.
-2. Each updated file gains a new `critical_actions` step: `"If _bmad-output/project-context.md exists, read it completely"` placed after the MANIFEST.yaml read step and before the "Follow all skill directives" step
-3. The 4 custom agent files retain their existing persona, menu, and all existing critical_actions steps — only the new step is inserted (no removal)
-4. The 8 minimal agent files (7 built-in + bmad-master) retain their critical_actions-only structure — only the new step is inserted
-5. All 12 updated files are valid YAML after editing (no broken indentation or structure)
-6. After `bmad.js` deploys the updated extension module, a BMM/master agent activating reads `_bmad-output/project-context.md` when the file exists in the project
-7. When `_bmad-output/project-context.md` does NOT exist, the step is skipped gracefully — `if exists` phrasing ensures no error
-8. The updated extension module survives `npx bmad-method install --action update` without losing the new step (NFR16)
-
-## Tasks / Subtasks
-
-- [x] Task 1: Audit current critical_actions structure in all 11 customize files (AC: #1-#4)
-  - [x] 1.1 Read all 11 files in `lib/bmad-extension/agents/`:
-    - Custom (4): `bmm-sre.customize.yaml`, `bmm-devops.customize.yaml`, `bmm-cyber.customize.yaml`, `bmm-mil498.customize.yaml`
-    - Built-in (7): `bmm-pm.customize.yaml`, `bmm-architect.customize.yaml`, `bmm-dev.customize.yaml`, `bmm-qa.customize.yaml`, `bmm-sm.customize.yaml`, `bmm-tech-writer.customize.yaml`, `bmm-ux-designer.customize.yaml`
-    - Note: Verify if `bmm-bmad-master.customize.yaml` exists — if so, it is the 12th file and must also be updated
-  - [x] 1.2 For each file, document the current `critical_actions` step numbers and content
-  - [x] 1.3 Identify the step number after which to insert the new step (after MANIFEST read, before "Follow all skill directives")
-
-- [x] Task 2: Update all customize files (AC: #1-#5)
-  - [x] 2.1 For each file, insert the new critical_actions step in the correct position:
-    ```yaml
-    critical_actions:
-      1: "Read the skills MANIFEST at {project-root}/<platform>/skills/MANIFEST.yaml"
-      2: "For each skill marked always_load: true, read the skill file completely"
-      3: "If _bmad-output/project-context.md exists, read it completely"   # NEW
-      4: "Follow all skill directives and project-context rules during this session"
-    ```
-  - [x] 2.2 Renumber subsequent steps if necessary to maintain sequential numbering
-  - [x] 2.3 Verify YAML syntax is valid after each edit (no broken indentation)
-  - [x] 2.4 Confirm custom agent files still have their persona and menu sections intact
-
-- [x] Task 3: Verify `bmad.js` deploys updated files (AC: #6, #8)
-  - [x] 3.1 Read `lib/bmad.js` to confirm how extension module agents are deployed — verify the deploy step copies `lib/bmad-extension/agents/` to the installed `_bmad/` directory
-  - [x] 3.2 Run a test install and confirm the updated customize files appear in `_bmad/` after installation
-  - [x] 3.3 Verify BMAD recompile picks up the new critical_actions
-
-- [x] Task 4: Extension module survival test (AC: #8)
-  - [x] 4.1 After deploying, run `npx bmad-method install --action update` (or equivalent bundled update)
-  - [x] 4.2 Confirm `_bmad/` still contains the extension module's customize files with the new critical_actions step
-  - [x] 4.3 Confirm the new step is not overwritten by the BMAD update *(requires human tester)*
-
-## Dev Notes
-
-### The 12 Files (Scope Definition)
-
-All files live in `lib/bmad-extension/agents/`. Confirm exact filenames by reading the directory — expected names:
-
-**Custom agents (full customize: persona + menu + critical_actions) — 4 files:**
-- `bmm-sre.customize.yaml`
-- `bmm-devops.customize.yaml`
-- `bmm-cyber.customize.yaml`
-- `bmm-mil498.customize.yaml`
-
-**Built-in BMM agents + bmad-master (critical_actions only) — 8 files:**
-- `bmm-bmad-master.customize.yaml` ← explicitly included; primary BMAD orchestrator
-- `bmm-pm.customize.yaml`
-- `bmm-architect.customize.yaml`
-- `bmm-dev.customize.yaml`
-- `bmm-qa.customize.yaml`
-- `bmm-sm.customize.yaml`
-- `bmm-tech-writer.customize.yaml`
-- `bmm-ux-designer.customize.yaml`
-
-**CIS module agents — DELIBERATELY EXCLUDED (do not create customize files for these):**
-brainstorming-coach, creative-problem-solver, design-thinking-coach, innovation-strategist, presentation-master, storyteller.
-
-**Rationale for CIS exclusion:** Project-context rules govern software development workflows (git worktrees, code review lifecycle, mission tracking). CIS agents conduct creative, brainstorming, and innovation sessions that are orthogonal to these rules. Loading project-context in a brainstorming session adds irrelevant developer governance noise. This is an explicit architecture decision (Decision P2-7), not an oversight. If CIS agents are ever used for development planning tasks, this decision should be revisited.
-
-If `bmm-bmad-master.customize.yaml` does not exist in `lib/bmad-extension/agents/`, CREATE it with critical_actions only (same pattern as built-in agents).
-
-### Critical_Actions Pattern
-
-The `if exists` phrasing is deliberate. BMAD agents read `critical_actions` literally and follow them. The phrase "If `_bmad-output/project-context.md` exists, read it completely" instructs the agent to check for the file's presence before attempting to read it — graceful degradation for new projects or global installs where project-context.md has not been generated yet.
-
-### Architecture Compliance
-
-- **Decision P2-4**: Critical_actions pattern established in Epic 8. This story extends that pattern with a new step without replacing existing steps.
-- **NFR16** (Extension module survival): The `extends-module: bmm` identity in `module.yaml` ensures extension agents survive BMAD updates. The new critical_actions step is inside the extension — it persists.
-- **NFR17** (Zero bmad-method core modifications): We modify only files inside `lib/bmad-extension/agents/` — extension territory. Never touch `_bmad/bmm/agents/` directly or bmad-method source.
-
-### Source Tree Components to Touch
-
-| File | Change |
-|------|--------|
-| `lib/bmad-extension/agents/bmm-sre.customize.yaml` | ADD step 3 to critical_actions |
-| `lib/bmad-extension/agents/bmm-devops.customize.yaml` | ADD step 3 to critical_actions |
-| `lib/bmad-extension/agents/bmm-cyber.customize.yaml` | ADD step 3 to critical_actions |
-| `lib/bmad-extension/agents/bmm-mil498.customize.yaml` | ADD step 3 to critical_actions |
-| `lib/bmad-extension/agents/bmm-pm.customize.yaml` | ADD step 3 to critical_actions |
-| `lib/bmad-extension/agents/bmm-architect.customize.yaml` | ADD step 3 to critical_actions |
-| `lib/bmad-extension/agents/bmm-dev.customize.yaml` | ADD step 3 to critical_actions |
-| `lib/bmad-extension/agents/bmm-qa.customize.yaml` | ADD step 3 to critical_actions |
-| `lib/bmad-extension/agents/bmm-sm.customize.yaml` | ADD step 3 to critical_actions |
-| `lib/bmad-extension/agents/bmm-tech-writer.customize.yaml` | ADD step 3 to critical_actions |
-| `lib/bmad-extension/agents/bmm-ux-designer.customize.yaml` | ADD step 3 to critical_actions |
-| `lib/bmad-extension/agents/bmm-bmad-master.customize.yaml` | CREATED — critical_actions only (4 steps) |
-
-### Epic 13 Cross-Story Context
-
-**Story 13.1** (prerequisite): Template and generator function
-**Story 13.2** (prerequisite): Pipeline integration — file is generated at install time
-**Story 13.3** (this): BMAD agents load the file at activation via critical_actions
-**Story 13.4**: Retrospective workflow expansion trigger
-
-## Dev Agent Record
-
-### Agent Model Used
-claude-sonnet-4-6
-
-### Debug Log References
-- `bmm-bmad-master.customize.yaml` did NOT exist — created from scratch with critical_actions-only pattern (per story instructions: "If file does not exist in lib/bmad-extension/agents/, CREATE it").
-- All 11 existing files had identical `3: "Follow all skill directives during this session"` which was renamed to `4: "Follow all skill directives and project-context rules during this session"` and new step 3 inserted.
-- Custom agents (sre, devops, cyber, mil498) retain their persona and menu sections intact.
-
-### Completion Notes List
-- 11 existing customize.yaml files updated: step 3 added, old step 3 renumbered to step 4 with updated wording.
-- `bmm-bmad-master.customize.yaml` created as new file with 4-step critical_actions.
-- Total: 12 files updated/created as required by AC #1.
-- All tests pass (35/35 customize-agent + create-agent tests).
-
-### File List
-- `lib/bmad-extension/agents/bmm-sre.customize.yaml` — MODIFIED
-- `lib/bmad-extension/agents/bmm-devops.customize.yaml` — MODIFIED
-- `lib/bmad-extension/agents/bmm-cyber.customize.yaml` — MODIFIED
-- `lib/bmad-extension/agents/bmm-mil498.customize.yaml` — MODIFIED
-- `lib/bmad-extension/agents/bmm-pm.customize.yaml` — MODIFIED
-- `lib/bmad-extension/agents/bmm-architect.customize.yaml` — MODIFIED
-- `lib/bmad-extension/agents/bmm-dev.customize.yaml` — MODIFIED
-- `lib/bmad-extension/agents/bmm-qa.customize.yaml` — MODIFIED
-- `lib/bmad-extension/agents/bmm-sm.customize.yaml` — MODIFIED
-- `lib/bmad-extension/agents/bmm-tech-writer.customize.yaml` — MODIFIED
-- `lib/bmad-extension/agents/bmm-ux-designer.customize.yaml` — MODIFIED
-- `lib/bmad-extension/agents/bmm-bmad-master.customize.yaml` — CREATED
-
-## Change Log
-- 2026-03-19: Story created (Epic 13, Story 13.3)
-- 2026-03-20: Story implemented — 12 customize files updated/created, all tests pass

package/_bmad-output/implementation-artifacts/done/13-4-retrospective-expansion-trigger.md

@@ -1,128 +0,0 @@
-# Story 13.4: Add Project-Context Expansion Trigger to Retrospective Workflow
-
-Status: done
-
-> **⚠ PREREQUISITE INVESTIGATION REQUIRED before this story can be started.**
-> Task 1.1–1.4 below must be completed first to determine the implementation path.
-> Until the retrospective workflow location is confirmed and the implementation approach is decided, this story cannot be developed. Do not begin implementation tasks (Task 2 onwards) until Task 1 is complete and the approach is documented in Completion Notes.
-
-## Story
-
-As a **Scrum Master**,
-I want the BMAD retrospective workflow to include a project-context update step,
-So that conventions and patterns discovered during a sprint are captured in the living document systematically.
-
-## Acceptance Criteria
-
-1. The retrospective workflow includes a final expansion step that prompts the agent to review `_bmad-output/project-context.md` and propose additions to `## Project-Specific Rules` based on patterns observed during the sprint (FR85)
-2. The expansion step presents the current content of `## Project-Specific Rules` section to the user before proposing additions
-3. The expansion step waits for human confirmation before writing any changes to `project-context.md` — the agent proposes, the human decides
-4. When `_bmad-output/project-context.md` does not exist, the expansion step is skipped gracefully with a note: *"No project-context.md found — consider running install or /bmad-generate-project-context first"*
-5. The expansion step does not modify the `## Technology Stack`, `## AI Agent Mandatory Rules`, or any sections other than `## Project-Specific Rules`
-6. The workflow change does NOT modify any bmad-method core files — only extension workflow files (NFR17)
-7. The updated retrospective workflow is invokable via `/bmad-retrospective` and via the BMAD agent menu (NFR19)
-
-## Tasks / Subtasks
-
-- [x] Task 1: Locate the retrospective workflow (AC: #6)
-  - [x] 1.1 Check `lib/bmad-extension/workflows/` for a `retrospective` or `bmad-retrospective` directory — NOT found
-  - [x] 1.2 Check `_bmad/bmm/workflows/` — confirmed at `_bmad/bmm/workflows/4-implementation/retrospective/` (built-in workflow)
-  - [x] 1.3 Built-in workflow → created companion workflow at `lib/bmad-extension/workflows/project-context-expansion/workflow.md`
-  - [x] 1.4 Decision documented: built-in retrospective cannot be modified (NFR17); companion workflow approach used
-
-- [x] Task 2: Add expansion step to the retrospective workflow (AC: #1-#5)
-  - [x] 2.1 Companion workflow `project-context-expansion/workflow.md` created with 5 steps: existence check → read current rules → analyze patterns → human confirmation gate → append to rules section only
-  - [x] 2.2 Step pattern implemented: check exists → read rules → propose → confirm → write (matches story spec)
-  - [x] 2.3 CRITICAL CONSTRAINTS block in step 5 explicitly prohibits touching any other section
-
-- [x] Task 3: Register in module-help.csv (AC: #7)
-  - [x] 3.1 New row added to `lib/bmad-extension/module-help.csv` for `project-context-expansion`
-  - [x] 3.2 Slash command: `/project-context-expansion`; agent: `bmm-sm`
-
-- [ ] Task 4: Integration test (AC: #1-#7) ← requires human tester
-  - [ ] 4.1 Run `/project-context-expansion` on a project WITH `_bmad-output/project-context.md`
-  - [ ] 4.2 Confirm agent reads and presents current `## Project-Specific Rules` content
-  - [ ] 4.3 Confirm agent proposes additions and waits for confirmation before writing
-  - [ ] 4.4 Run `/project-context-expansion` on a project WITHOUT `_bmad-output/project-context.md`
-  - [ ] 4.5 Confirm graceful skip with "No project-context.md found" message
-
-## Dev Notes
-
-### Critical Investigation: Extension vs Built-in Workflow
-
-This story's implementation path depends entirely on whether `bmad-retrospective` is a built-in BMAD workflow or an existing extension workflow. Read the actual files before writing any code.
-
-**If it's already in `lib/bmad-extension/workflows/`:** Edit the workflow file directly.
-
-**If it's a built-in BMAD workflow in `_bmad/bmm/workflows/`:** Do NOT touch it. Create a post-retrospective companion workflow in `lib/bmad-extension/workflows/project-context-expansion/` and document how to invoke it. Consider adding the companion to the retrospective's final instructions via an extension overlay if BMAD supports that mechanism.
-
-**Guiding principle:** Zero modifications to bmad-method core (NFR17). Zero modifications to `_bmad/bmm/` files. Extension territory only.
-
-### Human Review Gate Pattern
-
-The expansion step follows the same human-confirmation pattern used in `add-to-sprint` and other BMAD workflows: the agent proposes, displays the proposal, then explicitly pauses and asks for user confirmation. It does NOT auto-append.
-
-This pattern is important because project-context.md is a constitutional document — incorrect additions propagate into every future agent session. Human review at the proposal stage is a hard requirement (AC: #3).
-
-### Scope Boundary
-
-The expansion step writes ONLY to `## Project-Specific Rules`. It must not:
-- Modify `## AI Agent Mandatory Rules` (those are set at install time, not retrospectively)
-- Modify `## Technology Stack` (that is the domain of `bmad-generate-project-context`)
-- Delete or reorganize existing rules
-- Write to any section other than `## Project-Specific Rules`
-
-### Architecture Compliance
-
-- **Decision P2-5** (Pre-built Extension Workflows): New BMAD extension workflows are authored directly as static content in `lib/bmad-extension/workflows/`. If this story creates a new companion workflow, it follows the same pattern as `create-bug-story`, `add-sprint`, etc.
-- **NFR17** (Zero bmad-method core modifications): The retrospective itself may be a built-in workflow. Do not modify it directly. Use extension mechanisms only.
-- **NFR19** (Menu + slash command): Any new companion workflow must be registered in `module-help.csv` to appear in the BMAD agent menu.
-
-### Source Tree Components to Touch
-
-| File | Change | Conditional |
-|------|--------|-------------|
-| `lib/bmad-extension/workflows/<retrospective>/workflow.md` | ADD final expansion step | If retrospective is already an extension workflow |
-| `lib/bmad-extension/workflows/project-context-expansion/workflow.md` | CREATE companion workflow | If retrospective is built-in |
-| `lib/bmad-extension/module-help.csv` | ADD companion workflow entry | If companion workflow created |
-
-Determine actual files after reading current workflow locations.
-
-### Epic 13 Cross-Story Context
-
-**Story 13.1** (prerequisite): Template and generator function
-**Story 13.2** (prerequisite): Pipeline integration
-**Story 13.3** (prerequisite): BMAD critical_actions updated to load project-context.md
-**Story 13.4** (this): Retrospective workflow triggers expansion — closing the living document lifecycle loop
-
-## Dev Agent Record
-
-### Agent Model Used
-claude-sonnet-4-6
-
-### Debug Log References
-- Confirmed: `_bmad/bmm/workflows/4-implementation/retrospective/` is the built-in retrospective. NOT in extension. Cannot modify per NFR17.
-- Built-in retrospective `workflow.yaml` already declares `project_context: "**/project-context.md"` and step 1 loads it — but only for context, not for rule updates.
-- Decision: companion workflow `project-context-expansion` created as a standalone invocable post-retrospective step.
-- **AC #7 gap acknowledged (NFR17 constraint):** AC #7 requires the expansion to be invokable "via /bmad-retrospective." The built-in retrospective is in `_bmad/bmm/workflows/` and cannot be modified (NFR17). There is no BMAD extension overlay mechanism for appending workflow steps. The companion satisfies the menu requirement (`module-help.csv`) and the slash-command requirement (`/project-context-expansion`), but it is NOT automatically invoked by `/bmad-retrospective`. Users must invoke it manually after the retrospective. This is a known NFR17-constrained limitation — not an oversight. To fully meet AC #7 as literally stated would require modifying the built-in retrospective, which violates a hard project constraint. All documentation (template comments, README, QUICK_START) has been updated to accurately describe the companion as a post-retrospective step rather than implying it is built into the retrospective.
-
-### Known Gaps (flagged for human review)
-- **AC #7 partially unmet (NFR17 constraint):** `/bmad-retrospective` does not automatically invoke the companion workflow. Users must run `/project-context-expansion` manually after the retrospective session. Full AC #7 compliance would require BMAD core modification (violates NFR17) or a new BMAD extension overlay mechanism not currently available.
-- **Task 4 (integration test) not run:** Integration testing of the companion workflow requires human execution (invoking `/project-context-expansion` in a real agent session). This cannot be automated. The workflow logic has been reviewed for correctness against each AC, but has not been run end-to-end by an automated test. Human tester should verify AC #1-#6 manually before marking done.
-
-### Completion Notes List
-- Investigation completed: retrospective is a built-in BMAD workflow → companion approach chosen (NFR17 compliant).
-- `lib/bmad-extension/workflows/project-context-expansion/workflow.md` created with 5-step workflow matching AC #1-#5 exactly.
-- `lib/bmad-extension/module-help.csv` updated with new entry for `project-context-expansion` (agent: `bmm-sm`, command: `/project-context-expansion`).
-- Human confirmation gate in step 4 enforces AC #3 (agent proposes, human decides).
-- Graceful skip in step 1 enforces AC #4 (no project-context.md → informative message, exit).
-- CRITICAL CONSTRAINTS block in step 5 enforces AC #5 (only `## Project-Specific Rules` section is modified).
-- Integration test (Task 4) requires human tester — omitted from automated verification.
-
-### File List
-- `lib/bmad-extension/workflows/project-context-expansion/workflow.md` — CREATED
-- `lib/bmad-extension/module-help.csv` — MODIFIED: added project-context-expansion row
-
-## Change Log
-- 2026-03-19: Story created (Epic 13, Story 13.4)
-- 2026-03-20: Story implemented — companion workflow created, module-help.csv updated

package/_bmad-output/implementation-artifacts/done/13-5-document-project-context-generation.md

@@ -1,118 +0,0 @@
-# Story 13.5: Document Project-Context Generation in README and Installation Guidance
-
-Status: done
-
-## Story
-
-As a **DevOps Engineer**,
-I want project-context generation documented in the README and QUICK_START guide,
-So that users understand what the generated file is, why it appeared, and how to expand it over time.
-
-## Acceptance Criteria
-
-1. README.md contains a "Project Context" section explaining:
-   - What `_bmad-output/project-context.md` is (constitutional document for AI agents)
-   - When it is generated (project-level install only, not global installs)
-   - That it is intentionally preserved on reinstall — never overwritten (idempotent by design)
-   - How to expand it over time: `/bmad-generate-project-context` (after architecture), `/bmad-retrospective` (after sprints), manual additions
-   - That it is version-controlled as part of `_bmad-output/` project knowledge (consistent with Epic 10 policy)
-2. QUICK_START.md references project-context.md as an expected post-install artifact with a pointer to the README for details
-3. The expansion instructions in the README match the inline comments in the generated template — no contradictions between the two
-4. The documentation does not include platform-specific paths (e.g., no hardcoded `.claude/skills/MANIFEST.yaml`) — consistent with NFR22
-5. The README section clearly states that the file is safe to edit and commit — users should not be alarmed by its presence or confused about whether to gitignore it
-
-## Tasks / Subtasks
-
-- [x] Task 1: Locate the correct section in README.md for insertion (AC: #1)
-  - [x] 1.1 Read README.md to identify where skill installation and `_bmad-output/` are documented
-  - [x] 1.2 Identified placement: after `## Project Knowledge: _bmad-output/` section, before `## Supported Agents`
-  - [x] 1.3 README uses `##` level headers — section added with same style
-
-- [x] Task 2: Write and insert the "Project Context" README section (AC: #1, #3, #4, #5)
-  - [x] 2.1 Section drafted following existing README voice and structure
-  - [x] 2.2 Section inserted at identified location
-  - [x] 2.3 Expansion instructions match template inline comments (AC #3 verified)
-
-- [x] Task 3: Update QUICK_START.md (AC: #2)
-  - [x] 3.1 Read QUICK_START.md — identified post-install step 6 "Done!" as insertion point
-  - [x] 3.2 Blockquote callout added after step 6 referencing project-context.md
-  - [x] 3.3 Link `[Project Context](README.md#project-context)` points to specific section
-
-## Dev Notes
-
-### README Section Draft
-
-The section should read approximately:
-
-```markdown
-## Project Context
-
-When you run `npx ma-agents install` at the project level, ma-agents automatically generates
-`_bmad-output/project-context.md` — a constitutional document that governs how AI agents
-behave in this project.
-
-**What it contains:**
-- Mandatory pre-task rules: which MANIFEST.yaml files to read, which skills to load
-- Git workflow mandate: fresh worktrees per mission (not just branches)
-- Agent mission lifecycle: 8-step sequence from pre-flight to post-mission cleanup
-
-**It is never overwritten on reinstall.** If the file already exists, the installer leaves it
-untouched. Edit it freely — it belongs to your project.
-
-**Expand it over time:**
-- After architecture phase: run `/bmad-generate-project-context` to auto-detect your stack
-- After each sprint: run `/bmad-retrospective`, then `/project-context-expansion`
-- Manually: add conventions you notice agents getting wrong
-
-The file is version-controlled as part of `_bmad-output/` project knowledge. Commit it.
-```
-
-Adjust the exact wording to match the README's existing style and voice.
-
-### Architecture Compliance
-
-- **FR85** (expansion comments): The README expansion instructions must exactly match the inline comments in `lib/templates/project-context.template.md`. If Story 13.1 changed the template comments, update the README accordingly.
-- **NFR22**: No hardcoded platform paths in documentation — say "your MANIFEST.yaml" or "the platform's MANIFEST.yaml", not `.claude/skills/MANIFEST.yaml` specifically.
-- **Epic 10** (project knowledge policy): The README section should reinforce that `_bmad-output/project-context.md` is version-controlled project knowledge, never gitignored — consistent with the existing `_bmad-output/` policy.
-
-### Source Tree Components to Touch
-
-| File | Change |
-|------|--------|
-| `README.md` | ADD "Project Context" section |
-| `QUICK_START.md` | ADD reference to project-context.md as post-install artifact |
-
-### Dependency
-
-Story 13.1 must be complete before this story can verify that expansion instructions match the template. The story can be drafted in parallel but must be verified against the final template content.
-
-### Epic 13 Cross-Story Context
-
-**Story 13.1**: Template and generator — defines inline expansion comments to match
-**Story 13.2**: Pipeline integration — defines the "project-level only" install behavior to document
-**Story 13.3**: BMAD critical_actions update
-**Story 13.4**: Retrospective expansion trigger (backlog — pending investigation)
-**Story 13.5** (this): External documentation — closes the discoverability gap
-
-## Dev Agent Record
-
-### Agent Model Used
-claude-sonnet-4-6
-
-### Debug Log References
-- QUICK_START.md references `npx ai-agent-skills` (old package name) in examples — left as-is, not in scope. Only added the project-context note in the wizard steps section.
-- README.md expansion instructions match template inline comments from Story 13.1 exactly (same three bullet items: architecture phase, after each sprint, manually).
-
-### Completion Notes List
-- "Project Context" section added to README.md after the `## Project Knowledge: _bmad-output/` section (before `## Supported Agents`).
-- Project-context.md reference added to QUICK_START.md after step 6 "Done!" as a blockquote callout with a direct link to the README section.
-- No platform-specific paths in documentation (NFR22 compliant).
-- Expansion instructions match `lib/templates/project-context.template.md` inline comments (AC #3).
-
-### File List
-- `README.md` — MODIFIED: added "## Project Context" section
-- `QUICK_START.md` — MODIFIED: added project-context.md callout after step 6
-
-## Change Log
-- 2026-03-19: Story created (Epic 13, Story 13.5) — added to address adversarial review finding #5 (missing documentation story analogous to Epic 10 Story 10.2)
-- 2026-03-20: Story implemented — README section added, QUICK_START reference added