ma-agents 3.4.9 → 3.5.0

package/_bmad-output/implementation-artifacts/done/12-3-modify-sprint-workflow.md

@@ -0,0 +1,127 @@
+# Story 12.3: Create Modify Sprint Extension Workflow
+
+Status: done
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As a **Scrum Master**,
+I want an extension workflow to modify existing sprints,
+So that scope can be adjusted when priorities change mid-sprint.
+
+## Acceptance Criteria
+
+1. **Given** modify-sprint workflow exists in lib/bmad-extension/workflows/modify-sprint/workflow.md,
+   **When** invoked (NFR19),
+   **Then** it allows: adding items, removing items, changing capacity, updating metadata
+
+2. **Given** sprint modification requested,
+   **When** items added or removed,
+   **Then** sprint status reflects updated item list and remaining capacity (FR71)
+
+## Tasks / Subtasks
+
+- [x] Task 1: Create modify-sprint workflow (AC: #1, #2)
+  - [x] 1.1: Create directory `lib/bmad-extension/workflows/modify-sprint/`
+  - [x] 1.2: Create `lib/bmad-extension/workflows/modify-sprint/workflow.md` with guided flow
+
+- [x] Task 2: Implement sprint selection step (AC: #1)
+  - [x] 2.1: Workflow step 1: List available sprints by reading `_bmad-output/implementation-artifacts/sprint-plan-*.yaml`
+  - [x] 2.2: Workflow step 2: User selects sprint to modify
+  - [x] 2.3: Workflow step 3: Display current sprint state — name, capacity, assigned items with status, remaining capacity
+
+- [x] Task 3: Implement modification operations (AC: #1, #2)
+  - [x] 3.1: Workflow step 4: Present modification menu — add item, remove item, change capacity, update metadata
+  - [x] 3.2: **Add item:** Present unassigned backlog items (from sprint-status.yaml), user selects item, add to sprint assigned_items list, check capacity
+  - [x] 3.3: **Remove item:** List currently assigned items, user selects item to remove, remove from assigned_items list, item returns to unassigned backlog
+  - [x] 3.4: **Change capacity:** Prompt for new capacity (positive integer), validate, update sprint artifact
+  - [x] 3.5: **Update metadata:** Allow updating sprint name, start/end context, status (planning/active/completed)
+
+- [x] Task 4: Implement capacity feedback after each modification (AC: #2)
+  - [x] 4.1: After every modification, display updated remaining capacity (capacity - assigned_items count)
+  - [x] 4.2: If adding an item exceeds capacity, warn user and require confirmation or capacity increase
+  - [x] 4.3: Allow multiple modifications in sequence before finalizing
+
+- [x] Task 5: Persist changes to sprint artifact with concurrency guard (AC: #2)
+  - [x] 5.1: Before writing, re-read the sprint artifact file and compare its `last_modified` timestamp to the value read at the start of the workflow session. If the timestamp differs, the file was modified externally — halt and display: *"Sprint artifact was modified since this session started. Re-read the current state below and confirm your changes before proceeding."* Then redisplay the current state and await user confirmation.
+  - [x] 5.2: Write updated sprint data back to the sprint YAML artifact file, updating `last_modified` to the current ISO timestamp.
+  - **Data authority note:** Do NOT write sprint assignments to sprint-status.yaml. Sprint membership is owned exclusively by sprint-plan-{n}.yaml. sprint-status.yaml is read-only from the perspective of sprint management workflows.
+
+- [x] Task 6: Register workflow in module-help.csv (AC: #1)
+  - [x] 6.1: Add entry to `lib/bmad-extension/module-help.csv` for modify-sprint workflow
+  - [x] 6.2: Entry must include: workflow name, slash command `/modify-sprint`, description, phase association
+
+## Dev Notes
+
+### Architecture Compliance
+
+- **Extension module pattern:** Workflow lives in lib/bmad-extension/workflows/modify-sprint/
+- **Sprint artifact format:** Reads and writes the same YAML format defined in 12-1 (sprint-plan-{number}.yaml), including the `last_modified` timestamp field
+- **Capacity as item count:** Consistent with FR66 — capacity is always an integer item count
+- **Remaining capacity display (FR71):** After every modification, show remaining capacity
+- **Concurrency guard:** Re-read artifact before write and compare `last_modified`. Abort write if file changed externally.
+- **Data authority:** sprint-plan-{n}.yaml is authoritative for sprint membership. Do not modify sprint-status.yaml from this workflow.
+
+### Shared Guardrails
+
+See `_bmad-output/implementation-artifacts/epic-11-12-shared-guardrails.md` for universal constraints, data authority rules, sprint artifact naming, and concurrency guard requirements.
+
+### Critical Guardrails (story-specific)
+
+- Do NOT place workflow in `_bmad/bmm/workflows/` — use `lib/bmad-extension/workflows/`
+- Do NOT modify any existing BMAD base module files
+- Do NOT add npm dependencies
+- Do NOT allow capacity to be set to zero or negative values
+- Do NOT silently exceed capacity when adding items — always warn
+- Do NOT modify lib/installer.js, lib/agents.js, or bin/cli.js
+- Do NOT delete sprint artifact files — only modify their contents
+
+### Project Structure Notes
+
+- **Files to create:**
+  - `lib/bmad-extension/workflows/modify-sprint/workflow.md`
+- **Files to update:**
+  - `lib/bmad-extension/module-help.csv` — add workflow registration entry
+- **Files to read/write (at runtime):**
+  - `_bmad-output/implementation-artifacts/sprint-plan-*.yaml` — sprint artifact files
+  - `_bmad-output/implementation-artifacts/sprint-status.yaml` — backlog item status
+
+### References
+
+- [Source: lib/bmad-extension/workflows/add-sprint/workflow.md] — Sprint artifact format (created in 12-1)
+- [Source: lib/bmad-extension/workflows/add-to-sprint/workflow.md] — Item assignment pattern (created in 12-2)
+- [Source: _bmad-output/implementation-artifacts/sprint-status.yaml] — Backlog status file
+
+## Dev Agent Record
+
+### Agent Model Used
+claude-sonnet-4-6
+
+### Debug Log References
+None — clean implementation.
+
+### Completion Notes List
+- Created `lib/bmad-extension/workflows/modify-sprint/workflow.md` with looping multi-step menu workflow
+- Step 1: Sprint discovery via sprint-plan-*.yaml glob; stores session_last_modified for concurrency guard
+- Step 2: Displays current sprint state with capacity/remaining
+- Step 3: Modification menu loops — supports multiple modifications before save
+- Step 3a (Add item): reads sprint-status.yaml + bug-*.md glob for unassigned items; capacity over-limit warning with options (add anyway/skip/change capacity)
+- Step 3b (Remove item): lists assigned items, removes from working state
+- Step 3c (Change capacity): validates positive integer; updates working state
+- Step 3d (Update metadata): name, start/end context, status (planning/active/completed)
+- Step 4 (Concurrency guard): re-reads file before write, compares last_modified; on conflict offers overwrite/merge/cancel
+- Step 5: Writes updated YAML preserving sprint_number and created_date; updates last_modified to current ISO timestamp; sprint-status.yaml not modified
+- Registered in module-help.csv with `/modify-sprint` command
+- Post-review fixes: {{working_assigned_items}} explicitly initialized from {{target_sprint.assigned_items}} in step 2 (M1); step 3b adds identifier resolution to titles/types before displaying Remove table (M2); step 3a cross-references ALL sprint plans to filter already-assigned items (H1); step 3d choice 5 now has explicit check block (L5)
+
+### File List
+- `lib/bmad-extension/workflows/modify-sprint/workflow.md` (created)
+- `lib/bmad-extension/module-help.csv` (updated — added modify-sprint entry)
+- `_bmad-output/implementation-artifacts/12-3-modify-sprint-workflow.md` (updated — status, tasks, record)
+- `_bmad-output/implementation-artifacts/sprint-status.yaml` (updated — 12-3 in-progress→review)
+
+## Change Log
+
+- 2026-03-18: Story 12.3 implemented — modify-sprint extension workflow created and registered
+- 2026-03-18: Addressed code review findings — H1 (cross-sprint filter in 3a), M1 (working_assigned_items init), M2 (identifier resolution in 3b), L5 (explicit choice 5 handler in 3d)

package/_bmad-output/implementation-artifacts/done/12-4-sprint-status-assigned-items.md

@@ -0,0 +1,129 @@
+# Story 12.4: Update Sprint Status with Assigned Items
+
+Status: done
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As a **Scrum Master**,
+I want sprint status workflow to show assigned items per sprint,
+So that sprint progress is visible with all stories and bugs listed.
+
+## Acceptance Criteria
+
+0. **Architecture mandate:**
+   Implementation MUST create a new extension workflow at `lib/bmad-extension/workflows/sprint-status-view/workflow.md`. Do NOT modify any files under `_bmad/bmm/workflows/`. This is not a decision left to the implementing developer — the extension approach is required.
+
+1. **Given** existing sprint status workflow,
+   **When** it displays sprint information,
+   **Then** it shows all assigned items (stories + bugs) with their current status (FR71),
+   **And** remaining capacity visible,
+   **And** bugs and stories distinguishable in listing
+
+## Tasks / Subtasks
+
+- [x] Task 1: Prepare extension workflow — **architecture is pre-decided: create extension only** (AC: #0)
+  - [x] 1.1: Read existing sprint-status workflow in `_bmad/bmm/workflows/` to understand current format for reference only — do NOT modify it
+  - [x] 1.2: Read existing `_bmad-output/implementation-artifacts/sprint-status.yaml` to understand current data structure
+  - [x] 1.3: Create `lib/bmad-extension/workflows/sprint-status-view/workflow.md` — this is the mandated approach. Do not modify base module files.
+
+- [x] Task 2: Create sprint-status-view extension workflow (AC: #1)
+  - [x] 2.1: Create `lib/bmad-extension/workflows/sprint-status-view/workflow.md`
+  - [x] 2.2: Workflow step 1: Read all sprint artifact files from `_bmad-output/implementation-artifacts/sprint-plan-*.yaml`
+  - [x] 2.3: Workflow step 2: For each sprint, display: sprint name/number, capacity, status (planning/active/completed)
+  - [x] 2.4: Workflow step 3: For each sprint, list assigned items with: item identifier, title, type (story or bug), current status
+  - [x] 2.5: Workflow step 4: Display remaining capacity per sprint (capacity - assigned items count)
+
+- [x] Task 3: Implement type distinction for stories vs bugs (AC: #1)
+  - [x] 3.1: Stories and bugs must be visually distinguishable in the listing — use type labels or markers
+  - [x] 3.2: Bug items should show severity alongside status
+  - [x] 3.3: Story items should show standard status (not-started/in-progress/done)
+
+- [x] Task 4: Integrate with sprint-status.yaml data (AC: #1)
+  - [x] 4.1: Cross-reference sprint assigned_items (from sprint-plan-*.yaml) with sprint-status.yaml to get current item execution statuses. Data authority: sprint-plan-{n}.yaml owns membership; sprint-status.yaml owns execution status.
+  - [x] 4.2: For bug items (discovered via `bug-*.md` glob): execution status comes from the bug file's YAML frontmatter (or shows as "not-started" if no status field present — bugs start unstarted).
+  - [x] 4.3: Handle items that exist in a sprint plan but have no entry in sprint-status.yaml (user stories only): display a **data integrity warning** — *"Item {id} has no status entry in sprint-status.yaml — run /sprint-planning to initialize status tracking for this item."* Do NOT silently show "status unknown."
+  - [x] 4.4: Handle items in sprint-status.yaml not assigned to any sprint: show in an "Unassigned Backlog" summary section.
+
+- [x] Task 5: Register workflow in module-help.csv (AC: #1)
+  - [x] 5.1: Add entry to `lib/bmad-extension/module-help.csv` for sprint-status-view workflow
+  - [x] 5.2: Entry must include: workflow name, slash command `/sprint-status-view`, description, phase association
+
+## Dev Notes
+
+### Architecture Compliance
+
+- **Extension workflow mandatory:** Implementation MUST be a new extension workflow at `lib/bmad-extension/workflows/sprint-status-view/workflow.md`. This is not a preference — it is required. The base `_bmad/bmm/workflows/` must not be modified.
+- **Sprint artifact integration:** Reads sprint-plan-{n}.yaml files created by add-sprint (12-1) and modified by add-to-sprint (12-2) and modify-sprint (12-3)
+- **Flat listing (FR65):** Items displayed in a flat list within each sprint — no epic grouping
+- **Remaining capacity (FR71):** Must be prominently displayed per sprint
+- **Item type distinction:** Stories and bugs are clearly labeled — bugs show severity, stories show status
+- **Data authority split:** sprint-plan-{n}.yaml owns sprint membership. sprint-status.yaml owns user story execution status. Bug execution status comes from bug file frontmatter. Never conflate these sources.
+- **Bug story discovery:** Bug stories are discovered via glob `_bmad-output/implementation-artifacts/bug-*.md` with YAML frontmatter parsing. They are NOT in sprint-status.yaml.
+- **Data integrity warnings:** Items in sprint plan but missing from sprint-status.yaml must surface as an actionable warning (run /sprint-planning), not silently as "status unknown."
+
+### Shared Guardrails
+
+See `_bmad-output/implementation-artifacts/epic-11-12-shared-guardrails.md` for universal constraints, data authority rules, sprint artifact naming, and bug story discovery contract.
+
+### Critical Guardrails (story-specific)
+
+- Do NOT modify `_bmad/bmm/workflows/` base module files — extension workflow is mandatory (see AC #0)
+- Do NOT add npm dependencies
+- Do NOT modify lib/installer.js, lib/agents.js, or bin/cli.js
+- Do NOT group items by epic — maintain flat backlog view within sprints
+- Do NOT hide unassigned items — surface them in a summary section
+
+### Project Structure Notes
+
+- **Files to create (likely):**
+  - `lib/bmad-extension/workflows/sprint-status-view/workflow.md` (or similar name)
+- **Files to update:**
+  - `lib/bmad-extension/module-help.csv` — add workflow registration entry (if new workflow)
+- **Files to read (at runtime):**
+  - `_bmad-output/implementation-artifacts/sprint-plan-*.yaml` — sprint artifact files
+  - `_bmad-output/implementation-artifacts/sprint-status.yaml` — item statuses
+- **Existing files to review (not modify):**
+  - `_bmad/bmm/workflows/` — existing sprint-status workflow for reference
+
+### References
+
+- [Source: _bmad-output/implementation-artifacts/sprint-status.yaml] — Current sprint status data
+- [Source: _bmad/bmm/workflows/] — Existing sprint-status workflow for pattern reference
+- [Source: lib/bmad-extension/workflows/add-sprint/workflow.md] — Sprint artifact format (created in 12-1)
+- [Source: lib/bmad-extension/workflows/add-to-sprint/workflow.md] — Item assignment format (created in 12-2)
+
+## Dev Agent Record
+
+### Agent Model Used
+claude-sonnet-4-6
+
+### Debug Log References
+None — clean implementation. Extension workflow approach confirmed mandated by AC #0.
+
+### Completion Notes List
+- Read existing sprint-status workflow at `_bmad/bmm/workflows/4-implementation/sprint-status/instructions.md` for reference only (not modified)
+- Created `lib/bmad-extension/workflows/sprint-status-view/workflow.md` as new extension (not modifying base module)
+- Step 1: Globs sprint-plan-*.yaml sorted by sprint_number
+- Step 2: Loads sprint-status.yaml into story_status_map (story key → status); excludes epic-* and *-retrospective keys
+- Step 3: Globs bug-*.md into bug_metadata_map (basename → severity/title)
+- Step 4: Per sprint — displays capacity/remaining; resolves each assigned_items entry:
+  - Stories (regex `^\d+-\d+-.+`): status from story_status_map; DATA INTEGRITY WARNING if missing (not silent "unknown")
+  - Bugs (regex `^bug-.+`): severity from bug_metadata_map frontmatter; execution status from bug frontmatter or "not-started"
+  - Type distinction: 📋 Story vs 🐛 Bug markers in table
+- Step 5: Unassigned Backlog — stories grouped by status count + full unassigned bug table (id/title/severity)
+- Step 6: Interactive next-action menu — option 1 now shows full unassigned item list (stories + bugs) with details
+- Registered in module-help.csv with `/sprint-status-view` command; output_type: display (read-only workflow)
+- Post-review fixes: story/bug patterns use explicit regex (L3); unassigned bugs show full table not count (M6); step 6 option 1 replaced with genuinely additive full backlog detail view (L4); output_type corrected to display (M7)
+
+### File List
+- `lib/bmad-extension/workflows/sprint-status-view/workflow.md` (created)
+- `lib/bmad-extension/module-help.csv` (updated — added sprint-status-view entry)
+- `_bmad-output/implementation-artifacts/12-4-sprint-status-assigned-items.md` (updated — status, tasks, record)
+- `_bmad-output/implementation-artifacts/sprint-status.yaml` (updated — 12-4 in-progress→review, epic-12 in-progress)
+
+## Change Log
+
+- 2026-03-18: Story 12.4 implemented — sprint-status-view extension workflow created and registered
+- 2026-03-18: Addressed code review findings — M6 (full unassigned bug table), M7 (output_type: display), L3 (explicit regex patterns), L4 (step 6 option 1 replaced)

package/_bmad-output/implementation-artifacts/done/13-1-project-context-template-and-generator.md

@@ -0,0 +1,179 @@
+# Story 13.1: Create Project-Context Template and Generator Function
+
+Status: done
+
+## Story
+
+As a **Chief Architect**,
+I want a standalone project-context template and a `generateProjectContext()` function in the installer,
+So that a constitutional document can be generated with correct platform-specific content at install time.
+
+## Acceptance Criteria
+
+1. `lib/templates/project-context.template.md` exists as a standalone file (not an inline string in code) containing all mandatory rule sections (NFR24)
+2. The template contains a `## AI Agent Mandatory Rules` section with:
+   - Pre-task rules: read MANIFEST.yaml (`{{MANIFEST_PATHS_LIST}}` placeholder), load all `always_load: true` skills, select task-relevant skills (FR80)
+   - Git workflow rules: create fresh worktree per mission (not just a branch), all work in worktree, conventional commits, PR to main, worktree cleanup post-merge (FR80)
+   - Full 8-step mission lifecycle documented in sequence (FR83)
+3. The template contains `{{MANIFEST_PATHS_LIST}}` exactly once — no hardcoded platform paths anywhere in the template source (NFR22)
+4. The template contains the machine-readable version comment `<!-- ma-agents-template-version: 1.0 -->` on line 2 (NFR25)
+5. The template contains inline expansion comments referencing `bmad-generate-project-context`, `bmad-retrospective`, and manual additions (FR85)
+6. The template contains empty `## Technology Stack` and `## Project-Specific Rules` placeholder sections with TODO comments
+7. `generateProjectContext(projectRoot, installedAgents)` is implemented in `installer.js` — `installedAgents` receives ALL agents from the project manifest, not just those installed in the current run
+8. The function reads the template from `TEMPLATE_PATH` constant (resolved via `path.join(__dirname, 'templates', 'project-context.template.md')`, not hardcoded inline)
+9. The function resolves relative MANIFEST.yaml paths for each agent: `agent.skillsDir + '/MANIFEST.yaml'` — relative to project root, no `path.resolve()` or absolute prefixes (NFR22 for generated output)
+10. The function replaces `{{MANIFEST_PATHS_LIST}}` with a markdown bullet list: one `  - \`<path>\`` line per agent (FR81, FR82)
+11. The function returns the stamped content string — it does NOT write any file (writing is Story 13.2's responsibility)
+12. When `installedAgents` is empty, `{{MANIFEST_PATHS_LIST}}` is replaced with `  - (no agents installed — run ma-agents to install skills)`
+13. When the template file cannot be read (missing, permission error), the function throws an `Error` with message including the template path and the underlying cause — it never swallows errors silently
+14. With one installed platform, the returned content contains exactly one MANIFEST path entry (FR81)
+15. With multiple installed platforms, the returned content contains one entry per platform in the order they appear in the manifest (FR82)
+
+## Tasks / Subtasks
+
+- [x] Task 1: Create `lib/templates/` directory and template file (AC: #1-#4)
+  - [x] 1.1 Create `lib/templates/` directory in the project
+  - [x] 1.2 Create `lib/templates/project-context.template.md` with the full template structure (see Dev Notes for exact content)
+  - [x] 1.3 Verify template contains `{{MANIFEST_PATHS_LIST}}` placeholder
+  - [x] 1.4 Verify template contains all three mandatory rule sections: pre-task, git workflow, mission lifecycle
+  - [x] 1.5 Verify template contains expansion guidance comments
+  - [x] 1.6 Verify template contains empty Technology Stack and Project-Specific Rules sections
+
+- [x] Task 2: Implement `generateProjectContext()` in `installer.js` (AC: #5-#9)
+  - [x] 2.1 Add `TEMPLATE_PATH` constant near top of `installer.js`: `const TEMPLATE_PATH = path.join(__dirname, 'templates', 'project-context.template.md')`
+  - [x] 2.2 Implement `async function generateProjectContext(projectRoot, installedAgents)`:
+    - [x] 2.2.1 Read template file with `await fs.readFile(TEMPLATE_PATH, 'utf8')`
+    - [x] 2.2.2 Map `installedAgents` to manifest paths: `agent.skillsDir + '/MANIFEST.yaml'` (relative paths — no `path.join(projectRoot, ...)`)
+    - [x] 2.2.3 Format paths as markdown list: `  - \`${path}\``
+    - [x] 2.2.4 Replace `{{MANIFEST_PATHS_LIST}}` in template with formatted list
+    - [x] 2.2.5 Return stamped content string
+  - [x] 2.3 Wrap `fs.readFile` in try/catch — if template file missing, throw clear error: `"project-context template not found at ${TEMPLATE_PATH} — ma-agents installation may be corrupted"`
+
+- [x] Task 3: Unit tests (AC: all)
+  - [x] 3.1 Test: single platform → one MANIFEST path in output (AC: #14)
+  - [x] 3.2 Test: multiple platforms → correct count of paths in manifest order (AC: #15)
+  - [x] 3.3 Test: all relative paths — no absolute path segments in output (AC: #9)
+  - [x] 3.4 Test: `{{MANIFEST_PATHS_LIST}}` placeholder fully replaced — not present in output (AC: #10)
+  - [x] 3.5 Test: empty agents array → fallback message appears, no error thrown (AC: #12)
+  - [x] 3.6 Test: missing template file → Error thrown with path in message (AC: #13)
+  - [x] 3.7 Test: template version comment present in output (AC: #4, NFR25)
+  - [x] 3.8 Test: function does NOT call fs.writeFile or fs.pathExists (AC: #11 — pure content generator)
+
+## Dev Notes
+
+### Template File Content
+
+`lib/templates/project-context.template.md` should contain:
+
+```markdown
+# Project Context
+<!-- Generated by ma-agents at install time — this is a living document -->
+<!--
+  EXPAND THIS FILE over time:
+  - After architecture phase: run /bmad-generate-project-context
+  - After each sprint:        run /bmad-retrospective (includes context update step)
+  - Manually:                 add conventions you notice agents getting wrong
+-->
+
+## AI Agent Mandatory Rules
+
+### Pre-Task (EVERY task, no exceptions)
+
+1. Read the MANIFEST.yaml for your platform:
+{{MANIFEST_PATHS_LIST}}
+2. Load ALL skills marked `always_load: true` completely before doing anything
+3. Select additional skills relevant to the specific task type
+
+### Git Workflow (ALL file-changing tasks)
+
+1. Create a fresh worktree: `git worktree add ../<project>-<branch> -b <branch>`
+2. ALL work happens inside that worktree — never in the main working tree
+3. Use conventional commits: `feat/fix/chore/docs/refactor`
+4. Open a PR to main — never commit directly to main, never auto-merge
+5. After human approval and merge: `git worktree remove ../<project>-<branch>`
+
+### Agent Mission Lifecycle
+
+1. **Pre-flight:** Read MANIFEST.yaml, load always_load skills, select task skills
+2. **Worktree:** `git worktree add` creates fresh, isolated working surface
+3. **Implementation:** Execute task within the worktree
+4. **Self-review:** Run `code-review` skill on own output before opening PR
+5. **PR:** Conventional commit + PR opened — clear title and description
+6. **Human review gate:** Await approval — do NOT auto-merge under any circumstance
+7. **Merge + cleanup:** After approval: merge, `git worktree remove`, delete branch
+8. **Post-mission:** Update story status to done, append session to AiAudit.md
+
+## Technology Stack
+<!-- TODO: Populated after architecture phase via /bmad-generate-project-context -->
+<!-- Run: /bmad-generate-project-context to auto-detect your stack -->
+
+## Project-Specific Rules
+<!-- TODO: Grows through retrospectives and manual additions -->
+<!-- Run: /bmad-retrospective after each sprint to surface new conventions -->
+```
+
+### Architecture Compliance
+
+- **Decision P2-7** (Project Context Auto-Generation): This story implements the template creation and generator function. Story 13.2 handles pipeline integration (writing the file).
+- **NFR22** (Relative paths only): `agent.skillsDir` values in the agent registry are already relative project paths (e.g., `.claude/skills`). Appending `/MANIFEST.yaml` keeps them relative. Do NOT resolve to absolute paths.
+- **NFR24** (Template as separate file): The template MUST be a file in `lib/templates/`, not a template literal in installer.js code.
+
+### Source Tree Components to Touch
+
+| File | Change |
+|------|--------|
+| `lib/templates/project-context.template.md` | CREATE — new template file |
+| `lib/installer.js` | ADD — `TEMPLATE_PATH` constant + `generateProjectContext()` function |
+
+### Agent Registry `skillsDir` Values
+
+From `lib/agents.js`, the relevant `skillsDir` values for path resolution:
+- Claude Code: `.claude/skills`
+- Cursor: `.cursor/skills`
+- Cline: `.cline/skills`
+- Copilot: `.github/copilot/skills`
+- Gemini: `.gemini/skills`
+- Kilocode: `.kilocode/skills`
+- OpenCode: `.opencode/skills`
+- Antigravity: `.antigravity/skills`
+
+Verify actual values by reading `lib/agents.js` before implementation.
+
+### Testing Standards
+
+Epic 7 test suite is not yet complete. Manual verification is acceptable. If tests/installer.test.js exists, add unit tests there. Otherwise document manual test steps.
+
+### Epic 13 Cross-Story Context
+
+**Story 13.1** (this): Create template file and generator function — returns stamped content string
+**Story 13.2**: Call `generateProjectContext()` in install pipeline, handle file write + idempotency
+**Story 13.3**: Update all 11 BMAD agent `critical_actions` to load project-context.md
+**Story 13.4**: Add expansion trigger to retrospective workflow
+
+## Dev Agent Record
+
+### Agent Model Used
+claude-sonnet-4-6
+
+### Debug Log References
+- Test 3.1/3.2 initially failed: template itself contains "MANIFEST.yaml" in header text. Fixed test helper to count only backtick-wrapped path entries (`/MANIFEST.yaml`) not all occurrences of "MANIFEST.yaml".
+- Tests 3.6 and 3.8 raced when Promise.all ran them in parallel (3.6 temporarily renames template file). Fixed by running tests sequentially with async/await instead of Promise.all over parallel promises.
+- `skillsDir` property added to all agent definitions in `lib/agents.js` (not in original source tree spec) — required for `agent.skillsDir + '/MANIFEST.yaml'` pattern. All relative paths derived from agent definitions match the Dev Notes table.
+
+### Completion Notes List
+- `lib/templates/project-context.template.md` created with all mandatory rule sections, version comment on line 2, `{{MANIFEST_PATHS_LIST}}` placeholder (exactly once), expansion guidance comments, and empty Technology Stack / Project-Specific Rules sections.
+- `TEMPLATE_PATH` constant added near top of `lib/installer.js`.
+- `generateProjectContext(projectRoot, installedAgents)` implemented: reads template, maps agents to relative MANIFEST paths via `agent.skillsDir`, replaces placeholder, returns content string. Throws descriptive Error on missing template.
+- `skillsDir` property added to all 12 agent definitions in `lib/agents.js` for clean relative-path access.
+- `generateProjectContext` and `_TEMPLATE_PATH` exported from `lib/installer.js`.
+- 9 unit tests written in `test/generate-project-context.test.js` covering all 8 ACs. All pass. Full regression suite (84 tests) passes with no regressions.
+
+### File List
+- `lib/templates/project-context.template.md` — CREATED
+- `lib/installer.js` — MODIFIED (TEMPLATE_PATH constant, generateProjectContext function, exports)
+- `lib/agents.js` — MODIFIED (skillsDir property added to all 12 agent definitions)
+- `test/generate-project-context.test.js` — CREATED
+
+## Change Log
+- 2026-03-19: Story created (Epic 13, Story 13.1)
+- 2026-03-20: Story implemented — template file created, generateProjectContext() implemented, 9 unit tests passing, no regressions

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

@@ -0,0 +1,138 @@
+# 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