ma-agents 3.5.3 → 3.5.5

package/_bmad-output/implementation-artifacts/21-3-roomodes-template-bmad-modes.md

@@ -0,0 +1,106 @@
+# Story 21.3: `.roomodes` Template with BMAD Mode File-Regex Restrictions
+
+Status: backlog
+
+## Story
+
+As a **chief architect**,
+I want a `.roomodes` file generated for Roo Code installs defining 4 BMAD modes with `fileRegex` restrictions per phase,
+So that Roo Code's application-layer enforcement (`FileRestrictionError`) prevents agents from editing code files during planning phases — independent of whether the LLM follows the prompt.
+
+## Acceptance Criteria
+
+1. New template `lib/templates/roomodes.template.yaml` exists defining four `customModes`:
+   - `bmad-pm` — `groups: [read, [edit, { fileRegex: "\\.md$", description: "Markdown only" }]]`
+   - `bmad-architect` — `groups: [read, [edit, { fileRegex: "\\.(md|xml|drawio)$", description: "Markdown and diagram files only" }]]`
+   - `bmad-techlead` — `groups: [read, [edit, { fileRegex: "\\.(md|json|yaml|yml)$", description: "Markdown, JSON, YAML only" }]]`
+   - `bmad-dev` — `groups: [read, edit, command]` (full access)
+2. Each mode includes `slug`, `name`, `roleDefinition`, `whenToUse`, and `customInstructions` fields with content matching the BMAD phase descriptions in the source playbook (`optimizing-local-llm-coding-agents-bmad.md` Section 4.3).
+3. The Roo Code agent entry in `lib/agents.js` gains an optional `extraInstructionTemplates` array. For Roo Code: `[{ template: 'roomodes.template.yaml', target: '.roomodes', merger: 'yaml-customModes' }]`.
+4. The installer reads `extraInstructionTemplates` per agent and stamps each entry. For Roo Code, `.roomodes` is written at the project root.
+5. New module `lib/merge/roomodes.js` exports `mergeRoomodes(existingYaml, templateYaml)` returning the merged YAML string. Behavior:
+   - If `.roomodes` does not exist, return the template content.
+   - If it exists, parse both, merge the `customModes` arrays such that the four ma-agents-owned slugs (`bmad-pm`, `bmad-architect`, `bmad-techlead`, `bmad-dev`) overwrite any colliding entries (with a console warning naming each colliding slug); all other user-defined `customModes` entries are preserved untouched and emitted before the ma-agents entries.
+   - YAML output preserves comments and field order in user-owned entries where the YAML library supports it.
+6. Re-running install produces byte-identical `.roomodes` content for the four ma-agents slugs (NFR46), with user-owned entries preserved.
+7. NFR47 contract: a unit test verifies the rendered `bmad-architect` `fileRegex` rejects paths ending in `.ts`, `.py`, `.js`, `.go`; accepts `.md`, `.xml`, `.drawio`. Verified by `RegExp(fileRegex).test(path)` — no Roo Code runtime needed.
+8. The Roo Code agent must already be registered in `lib/agents.js` (Epic 18 Story 18.1). If Epic 18 is not yet merged when this story starts, this story includes the minimal Roo Code agent registration as a prerequisite sub-task.
+9. **Slug-stomp protection.** On install, for each of the four ma-agents-owned slugs (`bmad-pm`, `bmad-architect`, `bmad-techlead`, `bmad-dev`) that already exist in the user's `.roomodes`, the installer diffs the existing slug body (`roleDefinition` + `customInstructions` + `groups`) against the current template output for the user's profile. If a non-whitespace-only diff exists, the installer ABORTS with a named error (e.g., `RoomodesSlugDivergenceError`) listing the diverged slugs and instructs the user to either (a) rename the slug (accept it as user-owned, dropping our version) or (b) rerun with `--force-roomodes-overwrite` to accept the stomp. Without `--force-roomodes-overwrite`, no overwrite happens. This supersedes the "console warning only" behavior described in AC #5's bullet about colliding slugs for the four ma-agents-owned slugs; collisions on other slugs are impossible (ma-agents only owns these four). `--yes` does NOT imply `--force-roomodes-overwrite` — silent stomps on user-edited BMAD modes would be a data-loss regression.
+10. **Overwrite audit log.** When a ma-agents-owned slug IS written or overwritten (first install, clean match of existing content, or user passed `--force-roomodes-overwrite`), the installer appends an entry to a top-level field `roomodesOverwriteLog` in `.ma-agents.json` with shape `{ slug, date: <ISO-timestamp>, previousContentHash: <sha256-of-previous-body-or-null-if-new>, profile: <value> }`. The array grows append-only and is capped at 50 entries (oldest dropped on insert beyond cap) to prevent unbounded growth of `.ma-agents.json`. Rationale: gives operators a forensic trail for "when did the BMAD mode definitions last change on this project?"
+
+## Tasks / Subtasks
+
+- [ ] Task 1: Create `lib/templates/roomodes.template.yaml` per AC #1, #2
+- [ ] Task 2: Add `extraInstructionTemplates` field to Roo Code entry in `lib/agents.js` (AC #3)
+- [ ] Task 3: Implement `lib/merge/roomodes.js::mergeRoomodes` (AC #5)
+  - [ ] 3.1 Use `js-yaml` (already a dependency, verify) for parse/dump
+  - [ ] 3.2 Slug-collision detection + console warning
+  - [ ] 3.3 Preserve user entries in original order, ma-agents entries appended
+- [ ] Task 4: Wire `extraInstructionTemplates` processing into `lib/installer.js` per-agent install loop (AC #4)
+- [ ] Task 5: Tests in `test/roomodes-merge.test.js`
+  - [ ] 5.1 Empty `.roomodes` → 4 BMAD modes present
+  - [ ] 5.2 Existing user mode preserved when slug does not collide
+  - [ ] 5.3 Colliding slug overwritten with console warning
+  - [ ] 5.4 Idempotency: two merges produce byte-identical output (NFR46)
+  - [ ] 5.5 NFR47 contract — `bmad-architect` fileRegex matrix (AC #7)
+  - [ ] 5.6 Same matrix for `bmad-pm` (`.md` only) and `bmad-techlead` (`.md|.json|.yaml|.yml` only)
+- [ ] Task 6: If Epic 18 not merged, add Roo Code agent registration as prerequisite (AC #8) — coordinate with epic execution order before starting
+- [ ] Task 7: Slug-stomp protection (AC #9)
+  - [ ] 7.1 For each of the 4 ma-agents-owned slugs, compute diff of existing `roleDefinition`+`customInstructions`+`groups` against current template render
+  - [ ] 7.2 On any non-whitespace diff without `--force-roomodes-overwrite`, abort with `RoomodesSlugDivergenceError` listing diverged slugs and remediation
+  - [ ] 7.3 Add `--force-roomodes-overwrite` flag to `bin/cli.js` install command; document in help text that `--yes` does not imply it
+- [ ] Task 8: Overwrite audit log (AC #10)
+  - [ ] 8.1 On write of a ma-agents-owned slug, append `{ slug, date, previousContentHash, profile }` to `.ma-agents.json::roomodesOverwriteLog`
+  - [ ] 8.2 `previousContentHash` is sha256 of the previous slug body (concat of `roleDefinition`+`customInstructions`+JSON.stringify(`groups`)) or `null` on first install of that slug
+  - [ ] 8.3 Cap array at 50 entries — oldest dropped on insert beyond cap
+  - [ ] 8.4 Test: install → log has 4 entries with null hashes; re-install with hand-edit + `--force-roomodes-overwrite` → log has 5 entries, 5th has non-null previous hash
+
+## Dev Notes
+
+### Architecture Compliance
+
+- **Decision P3-3** — `.roomodes` is the highest-leverage application-layer guardrail in the design. NFR47 makes the enforcement contract testable.
+- **NFR46** — Idempotent stamping. The merger is responsible for deterministic output for the ma-agents-owned slugs.
+
+### Source Tree Components to Touch
+
+| File | Change |
+|------|--------|
+| `lib/templates/roomodes.template.yaml` | CREATE |
+| `lib/merge/roomodes.js` | CREATE |
+| `lib/agents.js` | MODIFY — add `extraInstructionTemplates` to Roo Code entry |
+| `lib/installer.js` | MODIFY — process `extraInstructionTemplates` per agent during install |
+| `test/roomodes-merge.test.js` | CREATE |
+
+### Dependencies
+
+- Story 21.1 (profile API — `.roomodes` content branches on profile in Story 21.6, but stamping is unconditional)
+- Story 21.2 (composition pattern — but `.roomodes` uses YAML merger, not marker-based markdown injection)
+- Epic 18 Story 18.1 (Roo Code agent registration) — see AC #8
+
+### Reference
+
+Source playbook: `optimizing-local-llm-coding-agents-bmad.md` Section 4.3 — full `.roomodes` example with 4 BMAD modes. Use that exactly for the template content.
+
+### Out of Scope
+
+- On-prem-specific `customInstructions` additions (Story 21.6 will append on-prem rules to each mode's `customInstructions` when profile=on-prem)
+- Cline-to-Roo migration (Epic 18 Story 18.4)
+
+## Dev Agent Record
+
+### Agent Model Used
+_(to be filled by dev agent)_
+
+### Debug Log References
+_(to be filled)_
+
+### Completion Notes List
+_(to be filled)_
+
+### File List
+_(to be filled)_
+
+## Change Log
+- 2026-04-14: Story created (Epic 21, Story 21.3)
+- 2026-04-14: Added ACs #9 and #10 for slug-stomp protection and overwrite audit log (Findings #9 and #20, corrective plan step 3). New CLI flag: `--force-roomodes-overwrite`. New `.ma-agents.json` field: `roomodesOverwriteLog` (append-only, capped at 50). AC #5's "colliding slug overwrite with console warning" is superseded for the four ma-agents-owned slugs by AC #9's abort-and-require-force behavior; AC #5 still governs behavior for user-owned slugs (preserved untouched).

package/_bmad-output/implementation-artifacts/21-4-agents-md-template-opencode.md

@@ -0,0 +1,86 @@
+# Story 21.4: Expanded `AGENTS.md` Template for OpenCode
+
+Status: backlog
+
+## Story
+
+As an **OpenCode user installing ma-agents**,
+I want a comprehensive `AGENTS.md` generated at my project root covering text-vs-file rules, BMAD phase discipline, and the project's BMAD output structure,
+So that OpenCode's auto-loading of `AGENTS.md` gives the agent the same guardrails Roo Code gets via `.roomodes`.
+
+## Acceptance Criteria
+
+1. New template `lib/templates/agents-md.template.md` exists containing:
+   - The same text-vs-file rules from the universal block (Story 21.2)
+   - A "never create files in `~/.claude/` or any user home directory" rule (universal for AGENTS.md regardless of profile — OpenCode + any model should respect it)
+   - A BMAD phase declaration section (Discovery/PM, Architecture, Tech Lead/Stories, Implementation) with phase-specific behavior rules
+   - The project BMAD output structure with placeholders: `{{PLANNING_DIR}}`, `{{ARCHITECTURE_DIR}}`, `{{STORIES_DIR}}` — stamped to project's actual `_bmad-output/` paths at install time
+2. The OpenCode agent entry in `lib/agents.js` gains an `extraInstructionTemplates` entry: `[{ template: 'agents-md.template.md', target: 'AGENTS.md', merger: 'markdown-markers' }]`.
+3. The marker-based markdown merger reuses the function used by Story 21.2 — content within `<!-- MA-AGENTS-START -->` / `<!-- MA-AGENTS-END -->` is rewritten; outside content preserved (NFR5, NFR46).
+4. After Story 21.4 ships, on a fresh OpenCode install:
+   - `AGENTS.md` is written at project root with the stamped content
+   - `opencode.json::instructions[]` array contains `"AGENTS.md"` if not already present (reuses Epic 9's JSON-merge function unchanged — additive only, NFR18)
+5. Re-running install produces byte-identical `AGENTS.md` marker-block content and does not duplicate the `instructions[]` entry (NFR46, NFR18).
+6. The phase declaration content is profile-agnostic in this story; on-prem-specific rules (`/no_think`, reasoning mode) come via Story 21.6 by appending to the same marker block.
+
+## Tasks / Subtasks
+
+- [ ] Task 1: Create `lib/templates/agents-md.template.md` per AC #1
+- [ ] Task 2: Add `extraInstructionTemplates` to OpenCode entry in `lib/agents.js` (AC #2)
+- [ ] Task 3: Verify the existing OpenCode JSON-merge from Epic 9 handles the additive append idempotently (AC #4, #5) — read `lib/installer.js` JSON-merge function to confirm; no changes expected
+- [ ] Task 4: Wire `markdown-markers` merger handling for `extraInstructionTemplates` (likely already handled by Story 21.3's `extraInstructionTemplates` processor — extend, do not duplicate)
+- [ ] Task 5: Tests in `test/agents-md.test.js`
+  - [ ] 5.1 Fresh install: `AGENTS.md` created with universal rules, phase section, stamped paths
+  - [ ] 5.2 `opencode.json::instructions[]` contains `AGENTS.md` after install
+  - [ ] 5.3 Re-install: `instructions[]` not duplicated (NFR18)
+  - [ ] 5.4 Re-install: `AGENTS.md` marker-block content byte-identical (NFR46)
+  - [ ] 5.5 Existing `AGENTS.md` user content outside markers preserved
+  - [ ] 5.6 Path placeholders correctly stamped from project's `_bmad-output/` layout
+
+## Dev Notes
+
+### Architecture Compliance
+
+- **Decision P3-3** — OpenCode parallel to Roo Code's `.roomodes` for application-layer guidance. OpenCode lacks file-regex enforcement (no `FileRestrictionError`), so reliance on prompt + Plan/Build mode is acceptable; this story does what's possible within OpenCode's capabilities.
+- **NFR18** (Epic 9 contract) — JSON-merge into `opencode.json::instructions[]` remains additive-only.
+
+### Source Tree Components to Touch
+
+| File | Change |
+|------|--------|
+| `lib/templates/agents-md.template.md` | CREATE |
+| `lib/agents.js` | MODIFY — `extraInstructionTemplates` on OpenCode entry |
+| `lib/installer.js` | MAYBE-MODIFY — extend `extraInstructionTemplates` processor (Story 21.3) for `markdown-markers` merger if not already supported |
+| `test/agents-md.test.js` | CREATE |
+
+### Dependencies
+
+- Story 21.2 (universal rules content — `AGENTS.md` reuses the same wording sourced from `lib/templates/instruction-block-universal.template.md` to avoid drift; consider reading the universal template and embedding it within the AGENTS.md template at stamp time, OR duplicate the rules text and add a comment marking the source of truth)
+- Story 21.3 (`extraInstructionTemplates` processor pattern — extend if needed)
+- Epic 9 (OpenCode JSON-merge — reused unchanged)
+
+### Reference
+
+Source playbook: `optimizing-local-llm-coding-agents-bmad.md` Section 5.3 — full `AGENTS.md` example with phase rules.
+
+### Out of Scope
+
+- On-prem-specific additions (Story 21.6)
+- BMAD persona phase prefix in customize-loader (Story 21.7)
+
+## Dev Agent Record
+
+### Agent Model Used
+_(to be filled by dev agent)_
+
+### Debug Log References
+_(to be filled)_
+
+### Completion Notes List
+_(to be filled)_
+
+### File List
+_(to be filled)_
+
+## Change Log
+- 2026-04-14: Story created (Epic 21, Story 21.4)

package/_bmad-output/implementation-artifacts/21-5-clinerules-template-extension.md

@@ -0,0 +1,82 @@
+# Story 21.5: Expanded `.clinerules` Template
+
+Status: backlog
+
+## Story
+
+As a **Cline user**,
+I want `.clinerules` to include BMAD phase discipline and text-vs-file rules,
+So that Cline (which already supports `.clinerules` natively) gets the same universal guardrails.
+
+## Acceptance Criteria
+
+1. New template `lib/templates/clinerules.template.md` exists containing the universal text-vs-file rules and BMAD phase rules formatted for the Cline `.clinerules` convention (one rule per line or short paragraph blocks — Cline's documented format).
+2. Both `.cline/clinerules.md` and `.clinerules` (Cline writes both per `lib/agents.js`) receive the expanded content via the existing marker-based injection.
+3. Existing user content outside `<!-- MA-AGENTS-START -->` / `<!-- MA-AGENTS-END -->` markers is preserved (NFR5).
+4. Re-running install produces byte-identical marker-block content in both files (NFR46).
+5. Mention Cline-specific concept: "Use Cline's Architect mode for BMAD planning phases (PM, Architect, Tech Lead). Switch to Code mode only for the implementation phase." This is universal guidance, not on-prem-specific.
+6. **Dual-file drift detection.** The installer writes both `.cline/clinerules.md` and `.clinerules` from the SAME template render. Before writing, it reads both existing files (if present) and compares their marker-block contents. If the two marker blocks diverge (non-whitespace diff), the installer ABORTS with a named error (e.g., `ClinerulesDualFileDriftError`) naming both files and their diff, instructing the user to reconcile manually before retrying. `--yes` does NOT bypass this check — reconciliation between the two Cline rule files is user work, and silently picking a "winner" could discard intentional edits. This is an explicit, documented exception to the usual `--yes` bypass convention.
+
+## Tasks / Subtasks
+
+- [ ] Task 1: Create `lib/templates/clinerules.template.md` per AC #1, #5
+- [ ] Task 2: Verify Cline's `extraInstructionTemplates` (or equivalent existing injection path) writes both `.cline/clinerules.md` and `.clinerules` consistently (AC #2)
+- [ ] Task 3: Confirm the universal block from Story 21.2 already covers most of the content; this story may simply add Cline-specific framing (Architect mode mention) and rely on `composeInstructionBlock` for the rest. Decide between two implementations:
+  - **Option A**: Cline-only template that wraps `composeInstructionBlock` output with Cline-specific intro/outro
+  - **Option B**: Inline Cline-specific rules directly into `lib/templates/clinerules.template.md` and skip `composeInstructionBlock` for Cline
+  - Pick Option A — single source of truth for the universal rules
+- [ ] Task 4: Tests in `test/clinerules.test.js`
+  - [ ] 4.1 Both `.clinerules` and `.cline/clinerules.md` contain universal rules + Architect-mode guidance
+  - [ ] 4.2 User content outside markers preserved
+  - [ ] 4.3 Idempotent re-install (NFR46)
+  - [ ] 4.4 Both files have identical marker-block content
+- [ ] Task 5: Dual-file drift detection (AC #6)
+  - [ ] 5.1 Before write, compare marker-block contents of `.cline/clinerules.md` and `.clinerules` when both exist
+  - [ ] 5.2 On non-whitespace diff, abort with `ClinerulesDualFileDriftError` naming both files and emitting the diff
+  - [ ] 5.3 Verify `--yes` does NOT bypass this check; document in CLI help text as an explicit exception
+
+## Dev Notes
+
+### Architecture Compliance
+
+- **Decision P3-3** — Cline parallel to Roo Code/OpenCode. Cline's Architect mode is the application-layer enforcement we leverage via prompt guidance.
+- **NFR46** — idempotent stamping for both Cline output files.
+
+### Source Tree Components to Touch
+
+| File | Change |
+|------|--------|
+| `lib/templates/clinerules.template.md` | CREATE |
+| `lib/installer.js` | MAYBE-MODIFY — verify Cline extraInstructionTemplates behavior |
+| `test/clinerules.test.js` | CREATE |
+
+### Dependencies
+
+- Story 21.2 (universal block — composed via `composeInstructionBlock` for the shared rules)
+
+### Reference
+
+Source playbook: `optimizing-local-llm-coding-agents-bmad.md` Section 3.3 — `.clinerules` example.
+
+### Out of Scope
+
+- Cline-to-Roo migration (Epic 18 Story 18.4)
+- On-prem-specific additions (Story 21.6 — appended to the same marker block when profile=on-prem)
+
+## Dev Agent Record
+
+### Agent Model Used
+_(to be filled by dev agent)_
+
+### Debug Log References
+_(to be filled)_
+
+### Completion Notes List
+_(to be filled)_
+
+### File List
+_(to be filled)_
+
+## Change Log
+- 2026-04-14: Story created (Epic 21, Story 21.5)
+- 2026-04-14: Added AC #6 for `.cline/clinerules.md` vs `.clinerules` drift detection (Finding #10, corrective plan step 3). `--yes` does NOT bypass this check — reconciliation is user work.

package/_bmad-output/implementation-artifacts/21-6-onprem-layered-guardrails.md

@@ -0,0 +1,112 @@
+# Story 21.6: On-Prem Layered Guardrails
+
+Status: backlog
+
+## Story
+
+As an **engineer running an on-prem install**,
+I want the installer to layer local-LLM-specific guardrails on top of the universal block when profile=on-prem,
+So that Nemotron and other local LLMs stop hallucinating `str_replace_editor`, dumping files into `~/.claude/`, and overthinking planning prompts.
+
+## Acceptance Criteria
+
+1. New template `lib/templates/instruction-block-onprem.template.md` exists containing:
+   - A `/no_think` reasoning-OFF directive (as a literal line at the top of the on-prem block) intended for planning-phase use
+   - A "NEVER create files in `~/.claude/` or any user home directory; all files go under the project directory" rule
+   - A "do NOT reference or use `str_replace_editor` or any Claude Code-specific tool that may not exist in this agent" rule
+   - Reasoning-mode and sampling guidance per BMAD phase (planning: reasoning OFF, low temperature; implementation: reasoning ON, moderate temperature) — guidance text only, not enforced
+2. `composeInstructionBlock({ profile: 'on-prem', manifestPath })` (Story 21.2) appends this template's content within the same `<!-- MA-AGENTS-START -->` markers, after the universal content.
+3. `composeInstructionBlock({ profile: 'standard', manifestPath })` does NOT include any on-prem content. Verified by absence of the strings `/no_think`, `str_replace_editor`, `~/.claude/` in the standard-profile output (NFR44).
+4. The `.roomodes` template (Story 21.3) gains profile-conditional `customInstructions` content per mode:
+   - When profile=on-prem, each BMAD mode's `customInstructions` block gets appended with the on-prem rules (no-home-dir-writes, no `str_replace_editor`)
+   - When profile=standard, no on-prem content appears in `customInstructions`
+5. The `AGENTS.md` template (Story 21.4) gains the same profile-conditional treatment within its marker block.
+6. The `.clinerules` template (Story 21.5) gains the same profile-conditional treatment within its marker block.
+7. Re-running install with profile=on-prem produces byte-identical content in all three files (`.roomodes`, `AGENTS.md`, `.clinerules`/`.cline/clinerules.md`) for ma-agents-owned sections (NFR46).
+8. Switching profile from standard to on-prem (via the Story 21.10 `reconfigure` command — no CLI flag) updates all marker-block content and `.roomodes` `customInstructions` to include the on-prem rules; switching back to standard removes them. User content outside markers/owned slugs is preserved. NOTE: Story 21.10 (Profile Reconfigure) is a separately-tracked new story in the corrective plan; until it lands, profile switching is done by hand-editing `.ma-agents.json`.
+9. **Home-dir rule narrowed to forbid ad-hoc writes only (resolves scope-vs-rule contradiction).** The generated on-prem template content (per AC #1) must NOT contain a blanket prohibition against writes to `~/.claude/`. Instead, the rendered text must contain the narrowed phrasing (or semantic equivalent): `"Never create ad-hoc response or output files in the user home directory (~/.claude/, ~/Documents, etc.). The installer's own scoped writes to ~/.claude/ during --scope global are authorized and not covered by this rule."` Verified by grep on rendered on-prem output: presence of `Never create ad-hoc` and `installer's own scoped writes` substrings; absence of the older blanket `"NEVER create files in ~/.claude/"` phrasing. Rationale: `npx ma-agents install --scope global` legitimately writes ma-agents config under `~/.claude/`, and the previous rule phrasing contradicted a supported install mode.
+10. **Informational log for on-prem + `--scope global` combination.** When profile=on-prem AND `--scope global` is selected at install time, the installer emits exactly the following informational log line (pinned verbatim for test assertion): `Note: on-prem profile with --scope global writes ma-agents config to ~/.claude/. This is authorized. The on-prem guardrail forbids ad-hoc files there, not the installer's scoped writes.` This line is emitted after profile resolution and before the first write under `~/.claude/`. Tests may `grep`/match on it.
+11. **No numerical sampling guidance in prompt template (delegated to Story 21.8).** The rendered on-prem instruction block must NOT contain any numerical temperature/top_p values (e.g., no `temperature 0.0`, `top_p 1.0`, `temperature 0.6`, `top_p 0.95` — or any other numeric tuple) in the rendered on-prem output. Per-phase sampling numbers are a server-side concern and belong in the vLLM reference doc (Story 21.8), not in the agent prompt. The prompt may retain (a) the `/no_think` directive, which IS prompt-level and effective, and (b) qualitative textual guidance such as "use careful reasoning for implementation; skip deep reasoning for discussion." Verified by regex on rendered on-prem output: `/temperature\s*[0-9]|top[_-]?p\s*[0-9]/i` must not match. AC #1's bullet "Reasoning-mode and sampling guidance per BMAD phase (planning: reasoning OFF, low temperature; implementation: reasoning ON, moderate temperature) — guidance text only, not enforced" is narrowed by this AC: qualitative text is allowed ("low"/"moderate"); specific numbers are not.
+
+## Tasks / Subtasks
+
+- [ ] Task 1: Create `lib/templates/instruction-block-onprem.template.md` per AC #1
+- [ ] Task 2: Verify `composeInstructionBlock` (Story 21.2) loads on-prem content when present (AC #2, #3)
+- [ ] Task 3: Extend `lib/templates/roomodes.template.yaml` (Story 21.3) with profile-conditional `customInstructions` per mode (AC #4)
+  - [ ] 3.1 Decide implementation: separate template for on-prem `customInstructions` blocks, OR templating placeholders within the existing template that get conditionally stamped
+  - [ ] 3.2 Update `mergeRoomodes` to compose conditional content based on profile
+- [ ] Task 4: Extend `AGENTS.md` template stamping (Story 21.4) to append on-prem rules when profile=on-prem (AC #5)
+- [ ] Task 5: Extend `.clinerules` template stamping (Story 21.5) to append on-prem rules when profile=on-prem (AC #6)
+- [ ] Task 6: Profile switching (AC #8)
+  - [ ] 6.1 Verify profile-switch to on-prem (via reconfigure path or manual `.ma-agents.json` edit) updates all three files correctly
+  - [ ] 6.2 Verify profile-switch to standard (via reconfigure path or manual `.ma-agents.json` edit) removes on-prem content cleanly
+- [ ] Task 7: Tests in `test/onprem-guardrails.test.js`
+  - [ ] 7.1 Standard profile: no on-prem strings in any output (AC #3 — NFR44)
+  - [ ] 7.2 On-prem profile: `/no_think`, no-home-dir, no-str_replace_editor present in all three files
+  - [ ] 7.3 Idempotency: same profile, two installs → byte-identical output (AC #7 — NFR46)
+  - [ ] 7.4 Profile switch standard→on-prem→standard restores original standard content
+  - [ ] 7.5 User content outside markers preserved across switches
+- [ ] Task 8: Narrow home-dir rule phrasing in `instruction-block-onprem.template.md` (AC #9)
+  - [ ] 8.1 Replace any blanket `"NEVER create files in ~/.claude/"` phrasing with the narrowed "ad-hoc" phrasing from AC #9
+  - [ ] 8.2 Test: grep rendered on-prem output for `Never create ad-hoc` present and blanket phrasing absent
+- [ ] Task 9: Informational log for on-prem + `--scope global` (AC #10)
+  - [ ] 9.1 After profile resolution, before first `~/.claude/` write, emit the pinned log line verbatim
+  - [ ] 9.2 Test: install with `--profile on-prem-equivalent-persisted` + `--scope global` captures stdout and asserts the pinned line
+- [ ] Task 10: Strip numerical sampling from on-prem template (AC #11, Finding #12-a)
+  - [ ] 10.1 Review `instruction-block-onprem.template.md` for any `temperature <num>` / `top_p <num>` text; replace with qualitative phrasing only ("low"/"moderate") and keep `/no_think`
+  - [ ] 10.2 Test: regex `/temperature\s*[0-9]|top[_-]?p\s*[0-9]/i` against rendered on-prem output returns no match
+
+## Dev Notes
+
+### Architecture Compliance
+
+- **Decision P3-3** — On-prem layer ships here. Universal layer (Story 21.2) + on-prem layer (this story) compose to the full on-prem experience.
+- **NFR44** — Standard profile must remain free of on-prem-specific output. Test 7.1 enforces.
+- **NFR46** — Deterministic stamping for both profiles.
+
+### Source Tree Components to Touch
+
+| File | Change |
+|------|--------|
+| `lib/templates/instruction-block-onprem.template.md` | CREATE |
+| `lib/templates/roomodes.template.yaml` | MODIFY — add on-prem content (conditional or via parallel template) |
+| `lib/installer.js` | MODIFY — profile-conditional stamping for `.roomodes`, `AGENTS.md`, `.clinerules` per-tool extensions |
+| `lib/merge/roomodes.js` | MODIFY — accept profile arg, compose `customInstructions` accordingly |
+| `test/onprem-guardrails.test.js` | CREATE |
+
+### Dependencies
+
+- Stories 21.1 through 21.5 (foundation + per-tool templates) all merged
+
+### Reference
+
+Source playbook:
+- `/no_think` directive: Section 6.1, 6.8
+- `str_replace_editor` warning: Section 2.5, 6.4
+- No-home-dir rule: Section 1, 5.3
+- Per-phase reasoning/sampling: Section 6.1, 8 (Sampling Parameters by Phase table)
+
+### Out of Scope
+
+- BMAD persona phase prefix in customize-loader (Story 21.7 — separate concern, edits `.customize.yaml` files)
+- vLLM serving doc (Story 21.8)
+
+## Dev Agent Record
+
+### Agent Model Used
+_(to be filled by dev agent)_
+
+### Debug Log References
+_(to be filled)_
+
+### Completion Notes List
+_(to be filled)_
+
+### File List
+_(to be filled)_
+
+## Change Log
+- 2026-04-14: Story created (Epic 21, Story 21.6)
+- 2026-04-14: Removed prescriptive `--profile=` flag references from AC #8 and Task 6 subitems (flag retired; profile switch is via Story 21.10 reconfigure command once delivered, or manual `.ma-agents.json` edit until then). Aligned with P0 spec-alignment PR #34.
+- 2026-04-14: Added ACs #9 and #10 reconciling on-prem home-dir rule with `--scope global` (Finding #8, corrective plan step 3). Rule narrowed to forbid ad-hoc writes only; installer's scoped writes authorized. Informational log pinned verbatim for test assertion.
+- 2026-04-14: Added AC #11 forbidding numerical temperature/top_p values in the on-prem instruction block (Finding #12-a, corrective plan step 3). Narrows AC #1's "sampling guidance" bullet — qualitative text allowed, specific numbers delegated to Story 21.8's vLLM reference doc. `/no_think` (prompt-effective) is retained.

package/_bmad-output/implementation-artifacts/21-7-bmad-persona-phase-prefix.md

@@ -0,0 +1,126 @@
+# Story 21.7: BMAD Persona Phase-Aware Prompt Prefix (On-Prem Only)
+
+Status: backlog
+
+## Story
+
+As an **engineer running an on-prem install with the BMAD module**,
+I want each BMAD agent persona to receive a phase-aware system-prompt prefix steering its reasoning mode appropriately,
+So that planning agents (PM, Architect, SM) stop overthinking and producing files for discussion prompts, and implementation agents (Dev) keep their reasoning mode for careful coding.
+
+## Acceptance Criteria
+
+1. Each `lib/bmad-customize/*.customize.yaml` file gains an optional `phase: planning|implementation` field. Initial classification:
+   - **Planning** (reasoning-OFF prefix): `bmm-pm` (John), `bmm-architect` (Winston), `bmm-sm` (Bob), `bmm-analyst` (Mary), `bmm-tech-writer` (Paige), `bmm-ux-designer` (Sally), `bmm-qa` (Gad)
+   - **Implementation** (reasoning-ON prefix): `bmm-dev` (Amelia), `bmm-quick-flow-solo-dev` (Barry)
+2. Each `*.customize.yaml` file gains an optional `on_prem_phase_prefix:` field containing the prefix text. The values are populated for every agent listed in AC #1; the field is absent for any agent that does not need a prefix.
+3. The BMAD customize-loader (location to be determined during Task 1 exploration — likely `lib/bmad.js` or a dedicated customize module) reads `getProfile(projectRoot)` from `lib/profile.js` and:
+   - When profile=on-prem AND `on_prem_phase_prefix` is set, prepends the prefix to the persona's existing `critical_actions` / system-prompt content
+   - When profile=standard OR `on_prem_phase_prefix` is absent, does NOT prepend anything (output identical to pre-Story-21.7 behavior)
+4. NFR44 verification: with profile=standard, the rendered `.customize.yaml` consumption produces output byte-identical to the pre-Story-21.7 baseline for every agent. Captured by snapshot tests.
+5. The phase prefix content for planning agents includes:
+   - A `/no_think` directive at the top
+   - "When the user asks a question or for an opinion, respond in TEXT in the chat. Do NOT create files."
+   - "You are a planning-phase agent. Do NOT skip ahead to implementation."
+6. The phase prefix content for implementation agents includes:
+   - "Think carefully about the implementation before writing code."
+   - "Reference the story or spec you are implementing before starting."
+   - "When asked a question, respond in text. Do not start coding unless asked."
+7. The customize-loader's prefix composition is idempotent — running the loader twice produces the same composed content (NFR46).
+8. **Phase enum extended to `{planning | implementation | mixed}` with persona reassignment (supersedes AC #1).** The `phase` field in each `*.customize.yaml` now accepts the value `mixed` in addition to `planning` and `implementation`. Final per-persona assignment is:
+   - **`phase: planning`** — `bmm-pm` (John), `bmm-architect` (Winston), `bmm-ux-designer` (Sally), `bmm-tech-writer` (Paige)
+   - **`phase: implementation`** — `bmm-dev` (Amelia), `bmm-quick-flow-solo-dev` (Barry)
+   - **`phase: mixed`** — `bmm-sm` (Bob), `bmm-qa` (Gad), `bmm-analyst` (Mary)
+   This supersedes AC #1's binary classification (which listed Bob, Gad, and Mary under `planning` and Paige under `planning`). The reason: Bob and Gad straddle planning conversations and story-file edits; Mary moves between research discussion and brief edits. A binary classification mislabels them and forces the wrong phase prefix. Each `*.customize.yaml` file must encode the `phase` value per this list.
+9. **Composite prefix for `phase: mixed`.** Personas with `phase: mixed` receive the following composite preamble as their `on_prem_phase_prefix` value (in addition to any persona-specific content): `"This persona handles both discussion and editing. Default to text responses when asked questions; only create or edit files when explicitly asked (verbs: create, write, generate, update, edit). When editing code, reason carefully; when discussing, keep responses concise without deep reasoning chains."` The customize-loader composes this prefix when profile=on-prem AND `phase: mixed`, parallel to the planning/implementation branches in AC #5/#6.
+10. **Customize-loader validator must accept `mixed`.** The Epic 15 customize-loader schema validation (wherever it lives — see Dev Notes) must recognize `mixed` as a valid `phase` value. If the current loader validator only accepts `{planning, implementation}`, a prerequisite sub-task is to extend the validator enum. This AC is satisfied when: (a) the validator accepts all three values without error, and (b) a `*.customize.yaml` file with `phase: mixed` is loaded successfully in a unit test.
+
+## Tasks / Subtasks
+
+- [ ] Task 1: Locate the customize-loader code path (`lib/bmad.js`, `lib/bmad-customize/`, or a dedicated module). Document file:line in Dev Agent Record. Confirm where `critical_actions` are composed for each persona.
+- [ ] Task 2: Add `phase` and `on_prem_phase_prefix` fields to the 9 affected `*.customize.yaml` files (AC #1, #2, #5, #6)
+  - Planning-phase content: shared text block defined once (e.g., in a comment-marked region) and pasted into each planning persona's YAML
+  - Implementation-phase content: same approach, pasted into the 2 implementation personas
+- [ ] Task 3: Extend the customize-loader to compose the prefix when `getProfile(projectRoot) === 'on-prem'` and the YAML has `on_prem_phase_prefix` (AC #3, #7)
+- [ ] Task 4: Snapshot-test baseline parity (AC #4)
+  - [ ] 4.1 Capture pre-Story-21.7 customize-loader output for all 11 BMAD agents (run before changes; commit snapshots to `test/snapshots/customize/`)
+  - [ ] 4.2 With profile=standard after Story 21.7 changes, customize-loader output matches snapshots byte-for-byte
+- [ ] Task 5: Tests in `test/bmad-persona-phase-prefix.test.js`
+  - [ ] 5.1 Profile=on-prem: planning agents get `/no_think` + text-response prefix prepended
+  - [ ] 5.2 Profile=on-prem: implementation agents get careful-implementation prefix prepended
+  - [ ] 5.3 Profile=standard: no prefix prepended for any agent (snapshot match — AC #4)
+  - [ ] 5.4 Profile=on-prem with agent missing `on_prem_phase_prefix`: no prefix, no error
+  - [ ] 5.5 Idempotency: two loader runs produce identical composed content (NFR46)
+- [ ] Task 6: Phase enum extension and persona reassignment (AC #8, #9, #10)
+  - [ ] 6.1 Reassign `phase` values per AC #8: Bob, Gad, Mary → `mixed`; Paige stays `planning`; others unchanged
+  - [ ] 6.2 Populate `on_prem_phase_prefix` for the three `mixed` personas with the composite preamble in AC #9 (plus any persona-specific tail)
+  - [ ] 6.3 PREREQUISITE: audit the Epic 15 customize-loader schema validator — if it enforces enum `{planning, implementation}`, extend it to `{planning, implementation, mixed}`. If the validator lives outside this story's scope, raise an Epic 15 issue/story and document the blocker in Dev Agent Record before proceeding
+  - [ ] 6.4 Tests: (a) profile=on-prem + `phase: mixed` → composite prefix prepended; (b) validator accepts all three enum values
+
+## Dev Notes
+
+### Architecture Compliance
+
+- **Decision P3-3** — BMAD persona phase prefix is the on-prem-only layer that complements per-tool guardrails. Inactive on standard profile.
+- **NFR44** — Standard profile customize output unchanged. Snapshot tests are the contract.
+
+### Source Tree Components to Touch
+
+| File | Change |
+|------|--------|
+| `lib/bmad-customize/bmm-pm.customize.yaml` | MODIFY — add `phase: planning`, `on_prem_phase_prefix:` |
+| `lib/bmad-customize/bmm-architect.customize.yaml` | MODIFY — same |
+| `lib/bmad-customize/bmm-sm.customize.yaml` | MODIFY — same |
+| `lib/bmad-customize/bmm-analyst.customize.yaml` | MODIFY — same |
+| `lib/bmad-customize/bmm-tech-writer.customize.yaml` | MODIFY — same |
+| `lib/bmad-customize/bmm-ux-designer.customize.yaml` | MODIFY — same |
+| `lib/bmad-customize/bmm-qa.customize.yaml` | MODIFY — same (Gad — verify file name from Epic 20 SQA work) |
+| `lib/bmad-customize/bmm-dev.customize.yaml` | MODIFY — `phase: implementation`, prefix |
+| `lib/bmad-customize/bmm-quick-flow-solo-dev.customize.yaml` | MODIFY — same |
+| `lib/bmad.js` (or customize-loader location) | MODIFY — profile-conditional prefix composition |
+| `test/bmad-persona-phase-prefix.test.js` | CREATE |
+| `test/snapshots/customize/*.snapshot` | CREATE — pre-change baselines for NFR44 verification |
+
+### Dependencies
+
+- Story 21.1 (`getProfile` API)
+- Epic 15 (BMAD 6.2.1 module restructure — customize-loader infrastructure may have changed)
+
+### Out of Scope
+
+- Per-tool template content (Stories 21.2–21.6)
+- vLLM serving doc (Story 21.8)
+- Customize-loader refactoring beyond what's needed for prefix composition
+
+### Notes on Phase Enum Extension (Epic 15 Prerequisite)
+
+**2026-04-14 audit clarification:** `lib/bmad-customize/` in this repo contains only `*.customize.yaml` artifacts — no JS loader or validator code. The customize-loader lives upstream in BMAD (bmad-method). Per the project's durable policy of overriding BMAD built-ins via extension (not upstream PRs to bmad-method), the `phase: mixed` extension is implemented by either (a) relying on BMAD's loader accepting unknown YAML fields silently (outcome 1 below — trivially satisfied) or (b) the ma-agents extension intercepting the YAML at install time and producing profile-specific variants (`*.customize.yaml` for standard, `*.customize.on-prem.yaml` for on-prem) with the installer choosing based on the persisted profile (outcome 3 below). Outcome 2 is only relevant if BMAD's loader has an enum validator that accepts `mixed` — nice to discover, no action required.
+
+AC #10 requires the Epic 15 customize-loader schema validator to accept `mixed` as a valid `phase` value. During Task 1's loader-discovery pass, verify whether a validator is in place and what enum it enforces. Three outcomes:
+
+1. **No validator present** — `phase` is a free-form string today; AC #10 is trivially satisfied. Document this in Dev Agent Record.
+2. **Validator present and accepts `mixed` already** — no change needed; satisfy AC #10 with a regression test.
+3. **Validator present and rejects `mixed`** — extend the enum to `{planning, implementation, mixed}`. If the validator is owned by Epic 15 code outside this story's change scope, raise an Epic 15 issue/story as a prerequisite and block Task 6 until it lands. Document explicitly rather than letting the dev hit this at implementation time.
+
+### Notes on Customize-Loader Discovery
+
+If the loader is implicit (BMAD itself reads `*.customize.yaml` directly with no ma-agents intermediation), this story's design may need adjustment. In that case, the prefix must be embedded directly into the YAML's existing `critical_actions` block under a profile-aware key, OR ma-agents must intercept the file at install time and produce two variants (`*.customize.yaml` for standard, `*.customize.on-prem.yaml` for on-prem) with the installer choosing which to deploy. Decide during Task 1 and document the chosen approach.
+
+## Dev Agent Record
+
+### Agent Model Used
+_(to be filled by dev agent)_
+
+### Debug Log References
+_(to be filled)_
+
+### Completion Notes List
+_(to be filled)_
+
+### File List
+_(to be filled)_
+
+## Change Log
+- 2026-04-14: Story created (Epic 21, Story 21.7)
+- 2026-04-14: Extended phase enum to `{planning, implementation, mixed}` via new ACs #8, #9, #10 (Finding #11, corrective plan step 3). Reassigned SM Bob, SQA Gad, Analyst Mary to `mixed`. AC #1's binary classification is SUPERSEDED by AC #8 but left in place to preserve the historical decision trail. Added Epic 15 validator-extension prerequisite note to Dev Notes.
+- 2026-04-14: Clarified Epic 15 prerequisite — customize-loader lives upstream in BMAD, not in ma-agents. Phase enum extension implemented via BMAD-built-in override policy (extension pattern, not upstream PR). Closes corrective-plan step 6 dependency-wiring audit.

package/_bmad-output/implementation-artifacts/21-8-vllm-reference-doc-readme.md

@@ -0,0 +1,100 @@
+# Story 21.8: vLLM Reference Deployment Doc and README On-Prem Section
+
+Status: backlog
+
+## Story
+
+As a **DevOps engineer setting up the on-prem inference server**,
+I want a single reference doc covering vLLM flags, tool-call-parser, context length, quantization, and per-phase sampling guidance,
+So that I can configure Nemotron Super 49B (or similar) to behave correctly with the coding agents ma-agents installs.
+
+## Acceptance Criteria
+
+1. New file `docs/deployment/vllm-nemotron.md` exists covering:
+   - Recommended vLLM launch command with all critical flags: `--enable-auto-tool-choice`, `--tool-call-parser qwen3_coder`, `--max-model-len 32768`, `--enforce-eager`, `--trust-remote-code`, `--seed=1`
+   - Quantization tradeoffs (BF16 vs FP8 vs NVFP4) including VRAM and instruction-following quality impact — table format
+   - Reasoning-mode behavior: `/no_think` system-prompt directive enables reasoning-OFF; default is reasoning-ON
+   - Per-phase sampling parameters table (planning: temp 0.0, top_p 1.0; implementation: temp 0.6, top_p 0.95)
+   - The `str_replace_editor` hallucination warning and mitigation (cross-reference to the on-prem template content from Story 21.6)
+   - A complete sample launch command block ready to copy-paste
+   - Cross-reference to `optimizing-local-llm-coding-agents-bmad.md` as the source playbook
+2. `README.md` gains a new top-level section "On-Prem / Air-Gapped Deployment" containing:
+   - One-paragraph overview of the on-prem use case
+   - Explanation of the install-time profile prompt (`Is this an on-prem install?`)
+   - Link to `docs/deployment/vllm-nemotron.md`
+   - Link to the source playbook `optimizing-local-llm-coding-agents-bmad.md`
+3. The deployment doc is NOT stamped into target projects by the installer — it is repo documentation only (FR179). Verified by grep on `lib/installer.js` and `lib/templates/` for any reference to the deployment doc path.
+4. The deployment doc explicitly states it is informational only — running ma-agents does not configure or manage the vLLM server.
+5. Documentation only: this story adds NO code, NO tests beyond a docs-link sanity check.
+6. **Sampling parameters owned by the vLLM reference doc, not the prompt.** The per-phase sampling-parameters table (temperature/top_p values, e.g., planning: temp 0.0, top_p 1.0; implementation: temp 0.6, top_p 0.95) lives in `docs/deployment/vllm-nemotron.md` and nowhere else in the repo. The doc must contain an explicit statement of this ownership with a phrase along the lines of: `"The agent prompt does not control sampling; sampling is set at the vLLM request/serve layer. The table below is for operators configuring the serve or the agent's request parameters, not for end-users."` Verified by (a) presence of the sampling table in the doc, (b) presence of the ownership statement, (c) cross-referenced with Story 21.6 AC #11 which forbids numerical values in the on-prem prompt template. Finding #12 is closed by the combination of 21.6 AC #11 (no numbers in prompt) + 21.8 AC #6 (numbers only in serving doc, with ownership disclaimer).
+7. **Tool-call-parser flag provenance and cross-model validation warning.** The doc must cite the provenance of `--tool-call-parser qwen3_coder`: specifically, that this parser was validated to work with Nemotron Super 49B v1.5 per the source conversation `optimizing-local-llm-coding-agents-bmad.md` (dated April 2026). Immediately following the citation, the doc must contain a clearly-marked warning paragraph (formatted as a `NOTE:` or `WARNING:` admonition) with content along the lines of: `"NOTE: This parser flag is validated for Nemotron Super 49B v1.5. Users deploying other Nemotron versions or different local LLMs MUST validate the parser flag against their model's HuggingFace card — copy-paste of this flag to an unvalidated model risks silent tool-call corruption."` Verified by grep: presence of `Nemotron Super 49B v1.5` in the same paragraph as `qwen3_coder`, and presence of the cross-model validation warning paragraph.
+
+## Tasks / Subtasks
+
+- [ ] Task 1: Create `docs/deployment/vllm-nemotron.md` per AC #1
+  - [ ] 1.1 Source content from `optimizing-local-llm-coding-agents-bmad.md` Section 6 (Model Deployment Optimization)
+  - [ ] 1.2 Include the full sample launch command from Section 6.7
+  - [ ] 1.3 Include the sampling table from Section 8 (Quick Reference Cheat Sheet)
+- [ ] Task 2: Update `README.md` per AC #2
+  - [ ] 2.1 Choose insertion point — after "Installation" / before "Skill Library" reads naturally
+  - [ ] 2.2 Add the section with overview, profile-prompt explanation, and links
+- [ ] Task 3: Sanity check (AC #3, #4, #5)
+  - [ ] 3.1 Grep `lib/` for any reference to the deployment doc path → must return zero matches
+  - [ ] 3.2 Doc explicitly disclaims installer responsibility for the inference server
+- [ ] Task 4: Optional — link-check
+  - [ ] 4.1 If a markdown link checker is in the test suite, verify all internal links in the new doc and README section resolve
+- [ ] Task 5: Sampling ownership + prompt/server boundary (AC #6)
+  - [ ] 5.1 Include the per-phase sampling table in the vLLM reference doc
+  - [ ] 5.2 Add the ownership statement ("agent prompt does not control sampling...") immediately above the table
+  - [ ] 5.3 Cross-reference Story 21.6 AC #11 in a short parenthetical ("Numbers deliberately omitted from the on-prem prompt template; see Story 21.6 AC #11.")
+- [ ] Task 6: Tool-call-parser provenance + cross-model warning (AC #7)
+  - [ ] 6.1 Cite `optimizing-local-llm-coding-agents-bmad.md` (April 2026) as the source validating `--tool-call-parser qwen3_coder` for Nemotron Super 49B v1.5
+  - [ ] 6.2 Add the `NOTE:` admonition warning against copy-paste to unvalidated models
+
+## Dev Notes
+
+### Architecture Compliance
+
+- **Decision P3-3** — Inference-server tuning is documentation only. The installer runs on engineer dev machines, not inference servers. Mixing concerns rejected in the architecture decision.
+- **FR179** — Doc ships in the repo, not into projects.
+
+### Source Tree Components to Touch
+
+| File | Change |
+|------|--------|
+| `docs/deployment/vllm-nemotron.md` | CREATE |
+| `README.md` | MODIFY — new "On-Prem / Air-Gapped Deployment" section |
+| `optimizing-local-llm-coding-agents-bmad.md` | NO CHANGE — referenced as source |
+
+### Dependencies
+
+- None — pure docs story, can ship in parallel with other Epic 21 stories.
+
+### Reference
+
+Entire source playbook `optimizing-local-llm-coding-agents-bmad.md` Section 6 — verbatim usable for most of the content. Adapt formatting to match repo doc conventions.
+
+### Out of Scope
+
+- Any installer changes
+- vLLM Docker images, Helm charts, or deployment automation
+- Per-model tuning beyond Nemotron Super 49B (other local LLMs may need different parsers — out of scope; doc may include a one-line note)
+
+## Dev Agent Record
+
+### Agent Model Used
+_(to be filled by dev agent)_
+
+### Debug Log References
+_(to be filled)_
+
+### Completion Notes List
+_(to be filled)_
+
+### File List
+_(to be filled)_
+
+## Change Log
+- 2026-04-14: Story created (Epic 21, Story 21.8)
+- 2026-04-14: Added AC #6 making the vLLM reference doc the sole owner of per-phase sampling parameters with an explicit prompt-vs-server ownership statement (Finding #12-b, corrective plan step 3). Paired with Story 21.6 AC #11 to close Finding #12 end-to-end.
+- 2026-04-14: Added AC #7 requiring parser-flag provenance citation for `--tool-call-parser qwen3_coder` (Nemotron Super 49B v1.5, per source playbook dated April 2026) and a cross-model validation warning (Finding #13, corrective plan step 3).