ma-agents 3.6.2 → 3.9.0

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

@@ -1,229 +0,0 @@
-# Story 21.3: `.roomodes` Template with BMAD Mode File-Regex Restrictions
-
-Status: Review
-
-## 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
-
-> Acceptance criteria marked **(gap-fill)** are additions made by the story author to make the epic's AC operational and testable. They do not contradict the epic; they refine the "how" where the epic only stated the "what". Open questions are flagged inline rather than resolved by author guesswork.
-
-1. **Template file exists.** A new file at the pinned path `lib/templates/roomodes.template.yaml` (new; path pinned per `_bmad-output/planning-artifacts/epics.md:3994`) is present and defines exactly four `customModes` entries:
-   - `bmad-pm` — read + edit restricted to `\.md$`
-   - `bmad-architect` — read + edit restricted to `\.(md|xml|drawio)$`
-   - `bmad-techlead` — read + edit restricted to `\.(md|json|yaml|yml)$`
-   - `bmad-dev` — read + edit + command (full access; no `fileRegex` group restriction on edit)
-   Each mode includes a `roleDefinition`, `whenToUse`, and `customInstructions` block whose text aligns with the BMAD phase descriptions in the source playbook (`optimizing-local-llm-coding-agents-bmad.md`, referenced by the epic intro at `_bmad-output/planning-artifacts/epics.md` lines 3886–3895).
-2. **(gap-fill) `customInstructions` reuses universal composer output.** The `customInstructions` content for each of the four modes incorporates the universal text-vs-file and BMAD phase-discipline rules. Per canonical decision A, the template itself contains NO placeholders and the merger (`mergeRoomodes`) does NOT call `composeInstructionBlock`. Instead, `lib/installer.js` (the stamper) is the sole owner of invoking `composeInstructionBlock({ profile, projectRoot })` (21.2-owned) exactly once per artifact; the installer performs `{{UNIVERSAL_BLOCK}}` substitution on the loaded template text AFTER composition and passes the already-composed template string into `mergeRoomodes` as input. Modes do NOT duplicate rule text. The Roo Code `MANIFEST.yaml` path used by `composeInstructionBlock` is the same `path.relative(projectRoot, path.join(agent.getProjectPath(), 'MANIFEST.yaml')).replace(/\\/g, '/')` already computed in `updateAgentInstructions` (`lib/installer.js` line ~408) for the `roo-code` agent entry (`lib/agents.js` lines 140–163; `getProjectPath()` returns `<projectRoot>/.roo/skills`).
-3. **Roo Code agent gains `extraInstructionTemplates`.** The `roo-code` entry in `lib/agents.js` (lines 140–163) gains a new optional field:
-   ```js
-   extraInstructionTemplates: [
-     { template: 'roomodes.template.yaml', target: '.roomodes', merger: 'yaml-customModes' }
-   ]
-   ```
-   No other agent entry is modified. The field is read only by the new `extraInstructionTemplates` processing path described in AC #4; absence on other agents is a no-op.
-4. **(gap-fill) Installer (stamper) wires the extra template.** A new processing pass in `lib/installer.js` (sibling to `updateAgentInstructions`, named `applyExtraInstructionTemplates(agent, projectRoot)` — new; the stamper per decision B) iterates `agent.extraInstructionTemplates` and, for each entry: (a) loads the raw template from `lib/templates/<template>`; (b) calls the composer `composeInstructionBlock({ profile: getProfile(projectRoot) || 'standard', projectRoot })` ONCE and substitutes `{{UNIVERSAL_BLOCK}}` in the template string (caller-side substitution per decision A); (c) dispatches on `merger`. For `'yaml-customModes'`, the stamper invokes the merger `mergeRoomodes(existingYaml, composedTemplateYaml)` (new) — passing the already-composed string as input — and writes the result to `<projectRoot>/<target>` atomically (temp-file + rename, mirroring the json-merge pattern at `lib/installer.js` lines ~395–398). If an existing target file is overwritten, the stamper creates a backup named `<target>.backup-<ISO-8601-timestamp>` (21.2-owned format; see Dependencies → Upstream).
-5. **YAML merger contract — `mergeRoomodes(existingYaml, templateYaml)`** (new — located in `lib/merge/roomodes.js` (new file). The epic technical note allows `lib/installer.js` placement "or a new `lib/merge/roomodes.js` if size warrants"; author resolution: separate file, because it owns YAML parse/serialize plus slug-collision logic and is large enough to warrant isolation). Per decision A, the merger is a pure splicer: it receives the already-composed template string as `templateYaml` and MUST NOT call `composeInstructionBlock`. Contract:
-   - Input: two strings (existing file content, already-composed template content). `existingYaml` may be empty/undefined when the file does not exist. `templateYaml` is the composer output from the stamper — no further substitution is performed here.
-   - Parse both as YAML using `js-yaml` (design decision; see Dev Notes → Library and pattern references).
-   - Output: a serialized YAML string whose `customModes` array contains every entry from `existingYaml.customModes` whose `slug` is NOT in the ma-agents-owned set (`bmad-pm`, `bmad-architect`, `bmad-techlead`, `bmad-dev`), followed by all four entries from `templateYaml.customModes`.
-   - All other top-level YAML keys from `existingYaml` are preserved unchanged (FR176 — "preserves user content outside ma-agents-owned slugs").
-   - Pure function — no I/O.
-6. **Slug-collision warning.** When `mergeRoomodes` discovers an existing entry whose slug matches one of the four ma-agents-owned slugs, it emits a single console warning per colliding slug naming the slug verbatim (e.g., `WARNING: .roomodes slug "bmad-architect" overwritten by ma-agents template`). The user entry is replaced; the ma-agents version wins (per epic AC — "colliding slugs are overwritten with the ma-agents version (with a console warning naming the slug)" at `epics.md` line 3987).
-7. **Fresh install creates `.roomodes`.** Given the Roo Code agent is selected in `npx ma-agents install`, when the installer runs and `<projectRoot>/.roomodes` does not exist, the file is written at the project root containing exactly the four ma-agents BMAD `customModes` entries (no user entries to preserve).
-8. **Re-install preserves user `customModes`.** Given `<projectRoot>/.roomodes` already exists with user-defined `customModes` whose slugs do NOT collide with the four ma-agents slugs, when the installer runs, those entries are preserved in their original order and the four ma-agents entries are present (FR176). YAML key ordering for preserved user entries is best-effort — comment preservation is NOT required (see Open question on `js-yaml` round-trip behavior).
-9. **NFR47 application-layer enforcement contract.** Given a user is in `bmad-architect` mode in Roo Code after install, when the agent attempts to edit a `.ts` or `.py` file, Roo Code rejects the edit with `FileRestrictionError`. **Verification scope for this story:** unit/integration tests assert that the generated `.roomodes` `fileRegex` patterns for `bmad-architect` (and the other three modes) reject `.ts`/`.py` paths via direct regex match — the actual `FileRestrictionError` is raised by Roo Code at runtime. The end-to-end Roo Code launch is out of scope (epic technical note at `epics.md` line 4152 explicitly limits NFR47 to the regex-contract level).
-10. **(gap-fill) NFR46 idempotency.** Two consecutive installs in the same project state produce byte-identical `.roomodes` content, including stable ordering of `customModes` entries (preserved-user entries first in their original order, then the four ma-agents entries in the canonical order `bmad-pm`, `bmad-architect`, `bmad-techlead`, `bmad-dev`). YAML serialization options (indent width, quote style, line width) are pinned in the merger so re-runs do not produce whitespace drift.
-11. **(gap-fill) NFR44 profile isolation — standard profile.** When `getProfile(projectRoot) === 'standard'` (or undefined), the rendered `.roomodes` `customInstructions` strings MUST NOT contain the literals `/no_think`, `str_replace_editor`, or `~/.claude/`. Verified by direct grep assertion in tests. On-prem-specific augmentation of `customInstructions` is deferred to Story 21.6 (epic technical note at line 4074 — "the `customInstructions` block per Roo Code mode … gets the on-prem rules appended when profile=on-prem").
-12. **(gap-fill) NFR18 additive JSON-merge — not regressed.** This story does NOT touch the OpenCode `opencode.json::instructions[]` json-merge path in `updateAgentInstructions` (`lib/installer.js` lines ~365–405). The `extraInstructionTemplates` pipeline is sibling and orthogonal. Existing OpenCode tests must continue to pass.
-13. **(gap-fill) Roo Code is not installed → no `.roomodes` write.** When the Roo Code agent is not selected in the wizard / direct-install, `applyExtraInstructionTemplates` is not invoked for it and `<projectRoot>/.roomodes` is not created or modified by ma-agents.
-14. **(gap-fill) Markdown rules instruction file unchanged in shape.** Roo Code's existing markdown injection target `.roo/rules/00-ma-agents.md` (registered at `lib/agents.js` line 161) continues to receive the universal block via Story 21.2's `updateAgentInstructions` path. This story adds `.roomodes` alongside; it does not relocate or remove the markdown rules file.
-
-> **Design decision (was Open question):** YAML library is **`js-yaml`**. Verified via `npm ls js-yaml` in `D:\Code\agents` on 2026-04-15: `js-yaml@4.1.1` is present transitively via `bmad-method@6.2.2`. Because transitive availability is not a stable contract, 21.3 adds `js-yaml` as a **direct installer dependency** (promote to `dependencies` in `package.json`, pinning `^4.1.1` to match the transitive version already in the tree). Comment-preserving libraries (`yaml` from eemeli) are heavier and unnecessary — comments inside ma-agents-owned slugs are overwritten by definition; comments on user entries are best-effort lost on rewrite (called out in AC #8).
-
-> **Design decision (was Open question):** Installer call site is **`lib/installer.js`** — the single stamper owner per canonical decision A. The install loop invokes `applyExtraInstructionTemplates(agent, projectRoot)` immediately after `updateAgentInstructions(agent, projectRoot)` for each selected agent. Both wizard and direct-install paths flow through this single loop (no separate branch in `bin/cli.js` invokes the extra-templates pipeline independently).
-
-> **Design decision (was Open question):** Roo Code `.roomodes` schema shape is the **authoritative shape cited in the `roo-code` entry in `lib/agents.js` (lines 140–163)** — that entry (registered by Story 18.1) is the source of truth for ma-agents' Roo Code integration. The template comment header links back to `lib/agents.js` rather than to a moving upstream URL. Schema fields used: `slug`, `name`, `roleDefinition`, `whenToUse`, `customInstructions`, `groups` (with `["edit", { fileRegex, description }]` tuple form).
-
-## Tasks / Subtasks
-
-- [ ] **Task 1: Create the YAML template** (AC #1, #11)
-  - [ ] 1.1 Create `lib/templates/roomodes.template.yaml` (new; pinned path per `epics.md:3994`) with four `customModes` entries: `bmad-pm`, `bmad-architect`, `bmad-techlead`, `bmad-dev`. Each mode's `groups` array MUST encode the `fileRegex` per AC #1 (`bmad-pm`: `\.md$`; `bmad-architect`: `\.(md|xml|drawio)$`; `bmad-techlead`: `\.(md|json|yaml|yml)$`; `bmad-dev`: full access).
-  - [ ] 1.2 Each mode's `customInstructions` field contains a `{{UNIVERSAL_BLOCK}}` sentinel and inline phase-specific text (e.g., "PM mode — discovery and PRD only") wrapping the sentinel. The template contains NO other placeholders. Per decision A, substitution happens in the stamper (`lib/installer.js`) AFTER `composeInstructionBlock` runs; the merger never touches the sentinel and never calls the composer.
-  - [ ] 1.3 Verify by inspection (and by the Task 5 NFR44 test) that the static template text contains none of `/no_think`, `str_replace_editor`, or `~/.claude/`. Those strings are only legal in the on-prem layer (Story 21.6).
-
-- [ ] **Task 2: Implement `mergeRoomodes` (merger) and wire it into the stamper** (AC #4, #5, #6, #10)
-  - [ ] 2.1 Create `lib/merge/roomodes.js` (new) exporting `mergeRoomodes(existingYaml, templateYaml, options)` — a pure splicer. Use `js-yaml`. Pin `js-yaml`'s `dump` options (`indent: 2`, `lineWidth: -1`, `noRefs: true`, `quotingType: '"'`) so output is deterministic across runs (NFR46). The merger MUST NOT import or call `composeInstructionBlock`; it treats `templateYaml` as opaque pre-composed input (decision A).
-  - [ ] 2.2 Slug-collision logic: build the ma-agents-owned set `['bmad-pm', 'bmad-architect', 'bmad-techlead', 'bmad-dev']`; filter user entries by `slug not in set`; for each filtered-out user entry, emit one warning line via `console.warn` naming the slug.
-  - [ ] 2.3 Add `applyExtraInstructionTemplates(agent, projectRoot)` to `lib/installer.js` (new stamper function). Iterate `agent.extraInstructionTemplates || []`. For each entry: (i) load raw template from `lib/templates/<template>`; (ii) call composer ONCE: `composed = rawTemplate.replace('{{UNIVERSAL_BLOCK}}', composeInstructionBlock({ profile: getProfile(projectRoot) || 'standard', projectRoot }))`; (iii) dispatch on `merger`. For `'yaml-customModes'`: read `<projectRoot>/<target>` if present, call `mergeRoomodes(existingYaml, composed)`, write atomically (temp + rename — pattern at `lib/installer.js` lines ~395–398). When overwriting an existing target, write a backup to `<target>.backup-<ISO-8601-timestamp>` (format owned by 21.2).
-  - [ ] 2.4 Export `mergeRoomodes` from `lib/merge/roomodes.js` and `applyExtraInstructionTemplates` from `lib/installer.js` so Story 21.9 tests can consume them directly.
-  - [ ] 2.5 Promote `js-yaml` to a direct `dependencies` entry in `package.json` pinned to `^4.1.1` (matches version already present transitively via `bmad-method@6.2.2`).
-
-- [ ] **Task 3: Wire into the install loop** (AC #4, #7, #13)
-  - [ ] 3.1 In the install loop in `lib/installer.js` where each selected agent has `updateAgentInstructions(agent, projectRoot)` invoked, add a follow-on `await applyExtraInstructionTemplates(agent, projectRoot)` call. Both wizard and direct-install paths flow through this single loop (per decision A; no separate branch in `bin/cli.js`).
-  - [ ] 3.2 Confirm that absence of `extraInstructionTemplates` on every other agent is a no-op (loop early-exits when the array is empty/undefined).
-
-- [ ] **Task 4: Register `extraInstructionTemplates` on Roo Code** (AC #3)
-  - [ ] 4.1 In `lib/agents.js` lines 140–163, add the `extraInstructionTemplates` array per AC #3 to the `roo-code` entry only.
-  - [ ] 4.2 Do not modify any other agent entry.
-
-- [ ] **Task 5: Unit and integration tests** — see Testing section below.
-
-- [ ] **Task 6: Documentation touch-up** (no new files)
-  - [ ] 6.1 If an existing doc covers per-tool injection, append a one-paragraph note pointing to `.roomodes`. If no existing doc covers this surface, skip — Story 21.8 introduces broader Epic 21 documentation.
-
-## Dev Notes
-
-### Architecture compliance
-
-- **Decision P3-3 (Local-LLM / On-Prem Agent Tuning Profile)** — `_bmad-output/planning-artifacts/architecture.md` lines 1888–1919. The "rejected" alternative explicitly cited at line 1919 — "Generate per-tool config purely via prompt instruction (no `.roomodes`)" — was rejected precisely because Roo Code's `fileRegex` is application-layer enforcement that the prompt cannot replicate. This story is the implementation of the accepted alternative.
-
-- **NFR44 (byte-identity for standard profile)** — `_bmad-output/planning-artifacts/epics.md` lines 264, 471. Standard-profile rendered `.roomodes` `customInstructions` MUST NOT contain `/no_think`, `str_replace_editor`, or `~/.claude/`. AC #11 is the contract; Test 5.5 enforces it. On-prem `customInstructions` augmentation is Story 21.6's surface.
-
-- **NFR46 (idempotency)** — `epics.md` lines 471, 4144 (item c). Two consecutive installs produce byte-identical `.roomodes`. AC #10 is the contract; Test 5.6 enforces it. The merger pins YAML `dump` options to eliminate whitespace drift.
-
-- **NFR47 (Roo Code application-layer fileRegex enforcement)** — `_bmad-output/planning-artifacts/prd.md` line 809; `epics.md` lines 264, 4144 (item e), 4152. Verified at the regex-contract level only; full Roo Code launch is out of scope (epic explicit). Test 5.7 asserts each mode's `fileRegex` against representative file paths.
-
-- **NFR18 (additive JSON-merge for OpenCode)** — Not in scope here. AC #12 is a non-regression contract; this story's pipeline is sibling to the json-merge path and does not touch it.
-
-- **FR176 (additive `.roomodes` slug isolation)** — `epics.md` line 254; `prd.md` line 706. AC #5, #8 implement; Test 5.8 verifies.
-
-### Verified source-tree surface
-
-| File | Exists? | Role in this story |
-|------|---------|--------------------|
-| `lib/profile.js` | verified (Story 21.1, lines 29–43) | Consumed via `getProfile(projectRoot)` inside `applyExtraInstructionTemplates` |
-| `lib/installer.js` | verified | Add `applyExtraInstructionTemplates`; consume `composeInstructionBlock` (Story 21.2, AC #3); reuse atomic-write pattern from lines ~395–398 |
-| `lib/agents.js` | verified | Add `extraInstructionTemplates` field to the `roo-code` entry only (lines 140–163). The Roo Code entry's `instructionFiles` (`['.roo/rules/00-ma-agents.md']`) is unchanged (AC #14) |
-| `lib/templates/roomodes.template.yaml` | **new** | Template source (AC #1) |
-| `lib/merge/roomodes.js` | **new** | YAML merger (AC #5) |
-| `lib/templates/instruction-block-universal.template.md` | **new (Story 21.2)** | Source for `{{UNIVERSAL_BLOCK}}` expansion via `composeInstructionBlock` |
-| `lib/templates/instruction-block-onprem.template.md` | **new (Story 21.6)** | Append-only on-prem layer; consumed transitively when profile=on-prem; this story must not break when missing |
-| `test/roomodes.test.js` | **new** | Unit + integration tests (see Testing section) |
-| `test/profile.test.js` | verified (Story 21.1) | Reference for test framework, temp-dir isolation pattern |
-| `_bmad-output/implementation-artifacts/21-2-universal-instruction-block-expansion.md` | verified | Upstream story — `composeInstructionBlock` signature pinned there |
-
-### Composition pattern reuse (composer / merger / stamper roles — decision B)
-
-- **Composer** = `composeInstructionBlock({ profile, projectRoot })` — 21.2-owned, the single source of truth for text-vs-file and BMAD phase-discipline content. Called exactly once per artifact by the stamper.
-- **Merger** = `mergeRoomodes(existingYaml, templateYaml)` — 21.3-owned. Pure splicer: YAML parse, slug filter, splice, serialize. Receives the already-composed template string as input. MUST NOT call the composer.
-- **Stamper** = `lib/installer.js` (`applyExtraInstructionTemplates` for this story; `updateAgentInstructions` for the markdown/JSON paths) — the single orchestrator that loads templates, calls the composer, performs `{{UNIVERSAL_BLOCK}}` substitution, and invokes per-artifact mergers.
-
-Story 21.6 will extend the composer's on-prem layer transparently — this story's code path requires no signature change when 21.6 lands.
-
-### Library and pattern references
-
-- **YAML library** — `js-yaml` (verified present at `4.1.1` transitively via `bmad-method@6.2.2`; promoted to direct dependency by this story — Task 2.5).
-- **Atomic write pattern** — `lib/installer.js` lines ~395–398 (`fs.outputFile(tmpPath, ...)` then `fs.rename(tmpPath, filePath)`).
-- **Roo Code agent entry** — `lib/agents.js` lines 140–163 (the only entry receiving `extraInstructionTemplates`).
-- **Roo Code instruction file (markdown rules)** — `.roo/rules/00-ma-agents.md`, `lib/agents.js` line 161; left untouched by this story (AC #14).
-- **Manifest-path computation** — reuse the `path.relative(projectRoot, path.join(agentProjectPath, 'MANIFEST.yaml')).replace(/\\/g, '/')` formula (`lib/installer.js` line 408) for cross-platform path consistency.
-
-## Dependencies
-
-### Upstream (blocking)
-
-- **Story 21.1 (done)** — `lib/profile.js::getProfile(projectRoot)` is consumed by `applyExtraInstructionTemplates` to pick the profile passed into `composeInstructionBlock`. Verified at `lib/profile.js` lines 29–43.
-- **Story 21.2 (Ready)** — owns **(a)** `composeInstructionBlock({ profile, projectRoot })` exported from `lib/installer.js` (the composer; single source of truth for universal text-vs-file / BMAD phase-discipline content embedded in each mode's `customInstructions`), and **(b)** the **backup filename format** `<target>.backup-<ISO-8601-timestamp>` used by the stamper whenever an existing artifact is overwritten. This story MUST land after 21.2 to avoid duplicating rule text and to reuse the backup-filename contract.
-- **Epic 18 Story 18.1 (done at code level)** — `roo-code` agent entry in `lib/agents.js` (lines 140–163). Verified present per epic cross-cutting note at `epics.md` line 4230.
-
-### Downstream (consumers of this story's surface)
-
-- **Story 21.4 (`AGENTS.md` for OpenCode)** — consumes the `extraInstructionTemplates` field convention and the per-agent stamper `applyExtraInstructionTemplates` delivered by this story. Story 21.4 adds a new entry `{ template: 'agents-md.template.md', target: 'AGENTS.md', merger: 'markdown-markers' }` to the OpenCode agent and reuses this story's stamper unchanged; if the `markdown-markers` merger was not registered by 21.3, 21.4 extends the dispatcher.
-- **Story 21.6 (On-Prem Layered Guardrails)** — appends on-prem rules to each mode's `customInstructions` via the same `composeInstructionBlock` call signature (no signature change). Also potentially adds on-prem-only mode-level notes per epic technical note at line 4074. This story's `applyExtraInstructionTemplates` design must accommodate Story 21.6 by re-running the merger when the on-prem template appears (no special branch required if `composeInstructionBlock` already conditionalizes internally — verified via Story 21.2 AC #3).
-- **Story 21.9 (Tests and Validation)** — adds the cross-cutting `.roomodes` slug-collision integration test and the NFR47 enforcement contract test as listed in `epics.md` line 4144 (items d and e). This story's tests are the unit-level subset; Story 21.9 adds the integration-level coverage.
-- **Story 21.10 (Profile Reconfigure)** — re-stamps `.roomodes` when profile flips. Reuses `applyExtraInstructionTemplates` and `mergeRoomodes`. Story 21.10 also relies on AC #6's slug-collision warning to detect the `RoomodesSlugDivergenceError` referenced at `epics.md` line 4180.
-- **Story 21.11 (Profile Uninstall)** — removes the four ma-agents-owned slugs while preserving user entries — reuses the slug-set constant from `lib/merge/roomodes.js` (export it as `MA_AGENTS_OWNED_SLUGS`).
-
-## Testing
-
-**Framework and isolation:** Match the pattern in `test/profile.test.js` (Story 21.1) — node's built-in test runner, `os.tmpdir()` + `fs.mkdtempSync` per-test temporary project roots, never mutate the repo's own `.ma-agents.json` or `lib/templates/`. Use the real `lib/profile.js` (`setProfile(tmpRoot, 'standard' | 'on-prem')`) against the tmp project root.
-
-New test file: `test/roomodes.test.js` (new).
-
-**Unit tests for `mergeRoomodes`:**
-
-- 5.1 Empty/undefined `existingYaml` → output contains exactly the four ma-agents-owned `customModes` in canonical order.
-- 5.2 `existingYaml` with two non-colliding user entries → output contains both user entries (preserving original order) followed by the four ma-agents entries.
-- 5.3 `existingYaml` with one colliding `bmad-architect` entry → user's entry dropped, replaced by ma-agents version, exactly one warning emitted naming the slug `bmad-architect`.
-- 5.4 `existingYaml` with non-`customModes` top-level keys → those keys preserved in output (FR176).
-- 5.5 NFR44 grep assertion: `mergeRoomodes` output for profile=standard contains none of `/no_think`, `str_replace_editor`, `~/.claude/`.
-- 5.6 NFR46 idempotency: calling `mergeRoomodes` twice with identical inputs returns byte-identical strings (same YAML serialization options, same ordering).
-- 5.7 NFR47 regex contract: for each mode's `fileRegex`, assert via `new RegExp(fileRegex).test(...)`:
-  - `bmad-pm` accepts `notes.md`, rejects `app.ts`, rejects `script.py`.
-  - `bmad-architect` accepts `arch.md`, `diagram.drawio`, `model.xml`; rejects `app.ts`, `script.py`.
-  - `bmad-techlead` accepts `config.yaml`, `package.json`, `notes.md`; rejects `app.ts`, `script.py`.
-  - `bmad-dev` accepts everything (no group-level `fileRegex` restriction on edit).
-- 5.8 Slug-set export: `lib/merge/roomodes.js` exports the canonical `MA_AGENTS_OWNED_SLUGS` constant for downstream consumption (Stories 21.10, 21.11).
-
-**Integration tests for `applyExtraInstructionTemplates`:**
-
-- 5.9 Fresh install in tmp project with profile=standard, Roo Code selected: `<tmpRoot>/.roomodes` is created with the four ma-agents entries; no `/no_think` or other on-prem strings present.
-- 5.10 Re-install in tmp project where `<tmpRoot>/.roomodes` already contains a user entry `slug: my-custom-mode`: that entry is preserved alongside the four ma-agents entries; second consecutive install produces byte-identical file content (NFR46).
-- 5.11 Roo Code NOT selected: `<tmpRoot>/.roomodes` is not created or modified by ma-agents (AC #13).
-- 5.12 OpenCode-only selection: `opencode.json::instructions[]` json-merge path still functions unchanged (NFR18 non-regression — AC #12).
-
-**Test data isolation:** Stub the absence of `lib/templates/instruction-block-onprem.template.md` — Story 21.6 has not landed yet, so the on-prem layer must gracefully fall back to universal-only per Story 21.2 AC #3. Tests must NOT depend on Story 21.6 being delivered.
-
-**Coverage note:** Story 21.9 adds (a) the cross-tool standard-profile-vs-baseline byte test, (b) the on-prem profile must-have-both-layers test, (c) the cross-cutting slug-collision integration test, and (d) the NFR47 enforcement contract end-to-end. Do not duplicate (c) and (d) here — keep this story's tests at the unit/per-merger level.
-
-## Out of Scope
-
-- On-prem layer additions to `customInstructions` per mode (Story 21.6, epic technical note at line 4074).
-- `AGENTS.md` template for OpenCode (Story 21.4).
-- `.clinerules` template extension for Cline (Story 21.5).
-- BMAD persona phase prefix in customize-loader (Story 21.7).
-- vLLM deployment doc and README on-prem section (Story 21.8).
-- End-to-end Roo Code launch verifying `FileRestrictionError` at the IDE layer (`epics.md` line 4152 explicitly limits NFR47 to regex-contract testing).
-- Profile-reconfigure backup / `RoomodesSlugDivergenceError` flow (Story 21.10).
-- Profile-uninstall slug removal flow (Story 21.11).
-- Bumping `manifestVersion` — already at `1.2.0` from Story 21.1; not touched here.
-- Modifying the OpenCode json-merge path or any other agent's instruction injection.
-
-## Change Log
-
-- 2026-04-15: Story created (Epic 21, Story 21.3). ACs structured with explicit (gap-fill) flags per the epic's AC scope. Three Open questions raised inline (YAML library choice, install-loop call site, Roo Code `customModes` schema version) rather than guessed. NFR44/NFR46/NFR47/NFR18 and FR176 citations made explicit. Verified source-tree surface table distinguishes existing vs. new paths. Status set to Ready.
-- 2026-04-15 (adversarial-review resolution): Applied canonical decisions A/B/C. (P1 #9) AC #1 pins template path `lib/templates/roomodes.template.yaml` per `epics.md:3994`. (P1 #3) Three Open questions resolved inline as design decisions: YAML library = `js-yaml` (verified `js-yaml@4.1.1` via `npm ls js-yaml` — transitively present through `bmad-method@6.2.2`; promoted to direct dependency, Task 2.5); installer call site = `lib/installer.js` (single stamper owner); Roo Code schema = authoritative shape cited in `lib/agents.js` roo-code entry. (P1 #4) Merger (`mergeRoomodes`) no longer calls `composeInstructionBlock`; it receives the composed string as input — stamper owns composer invocation and substitution. (P1 #10) Terminology normalized to composer/merger/stamper throughout. (Decision C) Backup filename `<target>.backup-<ISO-8601-timestamp>` cited as 21.2-owned in Upstream dependencies. All Tasks are unconditional; Status remains Ready.
-- 2026-04-15: Story 21.3 implemented — `lib/templates/roomodes.template.yaml`, `lib/merge/roomodes.js` (pure splicer with `MA_AGENTS_OWNED_SLUGS` export), `applyExtraInstructionTemplates` stamper in `lib/installer.js`, `extraInstructionTemplates` field on roo-code agent only, `js-yaml@^4.1.1` promoted to direct dep, 12 new tests in `test/roomodes.test.js`. Indent-preserving `{{UNIVERSAL_BLOCK}}` substitution keeps YAML block scalars valid after expansion. Status Ready → Review.
-- 2026-04-15 (rebase integration onto PR #45 / Story 21.4): consolidated parallel dispatcher. 21.3's `applyExtraInstructionTemplates` was merged into 21.4's canonical `stampExtraInstructionTemplates` by adding a `yaml-customModes` branch (with indent-preserving `{{UNIVERSAL_BLOCK}}` substitution and Story 21.2 backup semantics). Orphan function deleted. Explicit sibling call-site in the install loop removed — `updateAgentInstructions` already invokes the dispatcher. `test/roomodes.test.js` updated to import `stampExtraInstructionTemplates`. All 12 roomodes tests + the full suite still pass. No AC coverage weakened.
-
-## Dev Agent Record
-
-### Agent Model Used
-Claude Opus 4.6 (1M context) — bmad-dev-story + bmad-review-adversarial-general + bmad-review-edge-case-hunter flow.
-
-### Completion Notes
-- Template at `lib/templates/roomodes.template.yaml` ships four modes with `fileRegex` per AC #1. The template comment header explicitly disclaims containing the sentinel literally, and the sentinel appears exactly four times — one per mode's `customInstructions` block scalar.
-- Stamper substitutes `{{UNIVERSAL_BLOCK}}` with indent preservation (per-sentinel leading whitespace captured via regex and prepended to every line of the composed universal block). This keeps the YAML block-scalar indent valid after expansion without requiring the composer to know its caller's layout.
-- `mergeRoomodes` is a pure splicer — no `composeInstructionBlock` import. It preserves non-`customModes` top-level keys (FR176), emits one `console.warn` per colliding slug with the slug cited verbatim, and pins `js-yaml` dump options for byte-identity across runs (NFR46).
-- `applyExtraInstructionTemplates` is wired into the install loop siblings to `updateAgentInstructions` (both install and remove paths). Uninstall path is intentionally NOT wired — Story 21.11 owns profile-uninstall slug removal (uses `MA_AGENTS_OWNED_SLUGS` export).
-- Canonical backup format from Story 21.2 (`buildBackupFilename`) is reused — no new format invented.
-
-### Adversarial Review Findings (self-review)
-
-| # | Layer | Severity | Finding | Disposition |
-|---|-------|----------|---------|-------------|
-| 1 | Cynical | P1 | Naive `{{UNIVERSAL_BLOCK}}` replace would break YAML block-scalar indentation because the composed content contains colons and multi-line markdown | **Fixed** — regex-based indent-preserving substitution in the stamper + mirrored in test helper |
-| 2 | Cynical | P1 | `js-yaml` declared as `^4.1.0` but story pins `^4.1.1`; SemVer floor lower than required | **Fixed** — bumped to `^4.1.1` |
-| 3 | Cynical | P2 | Uninstall-path `updateAgentInstructions` call site not paired with `applyExtraInstructionTemplates` | **Out of scope** — story 21.11 owns profile-uninstall slug removal |
-| 4 | Edge-case | P1 | `parseYaml` on malformed YAML previously called `console.warn` silently. Now throws with label `existing`/`template` so failures surface with context | **Fixed** — descriptive Error thrown |
-| 5 | Edge-case | P1 | Empty `templateYaml.customModes` could produce `.roomodes` with zero modes | **Fixed** — merger throws if template has no modes |
-| 6 | Edge-case | P2 | Malformed user entries (null, non-object, missing slug) could crash the Set lookup | **Fixed** — defensive slug extraction; non-object and slug-less entries pass through unchanged (they cannot collide) |
-| 7 | Edge-case | P2 | `MA_AGENTS_OWNED_SLUGS` mutability would let downstream consumers corrupt the canonical order | **Fixed** — exported as `Object.freeze([...])`; test 5.8 asserts immutability |
-| 8 | Edge-case | P2 | Backup could clobber prior same-second run | **Inherited fix** — reuses `buildBackupFilename` which already appends `.N` tiebreaker (Story 21.2) |
-
-All P0/P1 findings resolved. P2 "out of scope" items deferred to Stories 21.10/21.11 per spec.
-
-### File List
-- CREATED: `lib/templates/roomodes.template.yaml` (four ma-agents-owned modes with fileRegex per AC #1)
-- CREATED: `lib/merge/roomodes.js` (pure splicer + `MA_AGENTS_OWNED_SLUGS` export)
-- CREATED: `test/roomodes.test.js` (12 tests, all passing)
-- MODIFIED: `lib/installer.js` (post-rebase: `yaml-customModes` branch integrated into Story 21.4's `stampExtraInstructionTemplates` dispatcher; no parallel function)
-- MODIFIED: `lib/agents.js` (roo-code `extraInstructionTemplates` field)
-- MODIFIED: `package.json` (js-yaml `^4.1.1` direct dep; test script entry)
-- MODIFIED: `package-lock.json` (js-yaml direct lock entry)
-- MODIFIED: `_bmad-output/implementation-artifacts/21-3-roomodes-template-bmad-modes.md` (Status → Review; Dev Agent Record / File List / Change Log)

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

@@ -1,275 +0,0 @@
-# Story 21.4: Expanded `AGENTS.md` Template for OpenCode
-
-Status: Review
-
-## 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
-
-> Acceptance criteria marked **(gap-fill)** are additions made by the story author to make the epic's AC operational and testable. They do not contradict the epic; they refine the "how" where the epic only stated the "what".
-
-1. **AGENTS.md template file exists.** A new template `lib/templates/agents-md.template.md` (new) is present and contains:
-   - The same text-vs-file rules defined in the universal block source `lib/templates/instruction-block-universal.template.md` (new, Story 21.2) — specifically the keyword-trigger tables (file-action: `create`, `write`, `generate`, `build`, `implement`; text-response: `what do you think`, `how should we`, `discuss`, `opinion`), the "if unsure, respond in text" default, the "never create `response.md` or `output.md` as a reply" rule, and the "confirm file paths before writing" rule.
-   - A "never create files in `~/.claude/` or any user home directory" rule — universal for AGENTS.md regardless of profile (per epic: OpenCode + any model should respect it).
-   - A BMAD phase declaration section listing the four phases (Discovery/PM, Architecture, Tech Lead/Stories, Implementation) with phase-specific behavior rules consistent with the universal block's BMAD phase discipline rule.
-   - A project BMAD output structure section whose concrete path values are produced by the composer (21.2) at install time; the template itself is static text (see AC #2).
-
-2. **(gap-fill) Template is static text — no placeholders.** Per canonical decision A, `lib/templates/agents-md.template.md` is STATIC TEXT and contains NO `{{...}}` placeholders. The composer `composeInstructionBlock({ profile, projectRoot }): string` (21.2-owned; see Upstream) is the single owner of universal-rules content and of any path/manifest resolution. Substitution, if any, is the caller's responsibility AFTER composition. Directory and manifest paths that were previously listed as template placeholders (`{{PLANNING_DIR}}`, `{{ARCHITECTURE_DIR}}`, `{{STORIES_DIR}}`, `{{MANIFEST_PATH}}`) are handled by the composer and/or resolved by the stamper caller — NOT by the template file itself.
-
-3. **(gap-fill) Universal-rules source of truth via the composer.** The installer (stamper) in `lib/installer.js` calls `composeInstructionBlock({ profile, projectRoot })` exactly once per artifact and writes the composed string into the `AGENTS.md` MA-AGENTS marker block via the `markdown-markers` merger. The merger receives the composed string as input — it does NOT perform placeholder substitution. Because `agents-md.template.md` is static text (AC #2), there is a single authoritative source for universal-rules wording across Stories 21.3–21.5 (no drift). If the composer is not yet available (Story 21.2 not merged), Story 21.4 is blocked (see Dependencies).
-
-4. **Installer registration via `extraInstructionTemplates`.** The OpenCode agent entry in `lib/agents.js` (line ~224–246, `id: 'opencode'`) gains a new optional field:
-
-   ```
-   extraInstructionTemplates: [
-     { template: 'agents-md.template.md', target: 'AGENTS.md', merger: 'markdown-markers' }
-   ]
-   ```
-
-   This reuses the `extraInstructionTemplates` field introduced by Story 21.3 for Roo Code's `.roomodes`. The installer (`lib/installer.js`, per-agent install loop) reads `extraInstructionTemplates` and stamps each entry. Story 21.4 does NOT re-define the processor — it consumes the processor delivered by Story 21.3.
-
-5. **(gap-fill) `markdown-markers` merger.** The `merger: 'markdown-markers'` dispatch key resolves to the same marker-wrap logic already used by `updateAgentInstructions` in `lib/installer.js` (markers `<!-- MA-AGENTS-START -->` / `<!-- MA-AGENTS-END -->` — HTML-comment shape, lines ~424–459). The merger consumes the composed string produced by `composeInstructionBlock({ profile, projectRoot })` (per AC #3) and writes it into the marker block. Anchor shape is fixed to the existing HTML-comment marker pair — no alternative shape is considered (matches the current `lib/installer.js` implementation the story reuses unchanged per epics.md:4229). On write:
-   - If the target file (`AGENTS.md`) does not exist, the installer creates it with only the marker block + stamped content between markers, a leading comment `<!-- Generated by ma-agents. Edit outside the MA-AGENTS-START/END markers to preserve your changes. -->`, and a trailing newline.
-   - If the target file exists with markers, content inside markers is replaced; content outside is preserved byte-for-byte (**NFR5 additive-only contract; NFR46 idempotency**).
-   - If the target file exists without markers, the marker block is appended at end-of-file separated by one blank line; existing content preserved.
-   - Story 21.2's upgrade-safety drift detection (backup + warning) is inherited unchanged.
-
-6. **OpenCode JSON-merge append of `AGENTS.md`.** The existing `injectionStrategy.position === 'json-merge'` branch in `lib/installer.js` (lines ~365–405) already appends a ma-agents-prefixed string to `opencode.json::instructions[]`. In addition, this story adds one more entry: the literal string `"AGENTS.md"` is appended to `opencode.json::instructions[]` if not already present. The entry is a plain string (no `[ma-agents]` prefix) because it is a file-path reference OpenCode resolves against the project root — not a ma-agents-owned instruction body. Duplicate detection compares by string equality against existing entries in `instructions[]`. Other keys in `opencode.json` are untouched (**NFR18 additive-only JSON merge**).
-
-7. **(gap-fill) `AGENTS.md` entry is user-owned after first install.** Because the `"AGENTS.md"` entry has no `[ma-agents]` prefix (AC #6), the existing `isMaEntry` filter in `lib/installer.js` (lines ~372–374) does NOT match it. Consequence: once appended, the entry is treated as user-owned — a subsequent install will NOT re-append (de-duplicated by string equality) and will NOT remove the entry if the user later removes OpenCode from the agent set. This is intentional: the `AGENTS.md` file may continue to exist and be loaded even if ma-agents is uninstalled. Story 21.11 (Profile Uninstall) is responsible for removing the entry on explicit uninstall.
-
-8. **Idempotency (NFR46).** Two consecutive installs with the same profile and project state produce:
-   - Byte-identical content between `AGENTS.md`'s marker lines.
-   - An `opencode.json::instructions[]` array whose length and element order is unchanged (the ma-agents-prefixed entry from Story 21.2 is replaced in place, the `"AGENTS.md"` entry is not duplicated, user entries preserved).
-   - No new `.backup-<timestamp>` files when no hand-edit drift is detected.
-
-9. **Profile isolation (NFR44).** The rendered `AGENTS.md` content for a standard-profile install MUST NOT contain the strings `/no_think`, `str_replace_editor`, or `~/.claude/` **inside the universal section or the BMAD phase declaration section**. Exception: the "never create files in `~/.claude/` or any user home directory" rule (AC #1) is a non-negotiable universal safety rule per the epic and legitimately contains the literal `~/.claude/`. NFR44's intent — "standard profile is byte-identical to pre-Epic-21 for output that did not previously contain local-LLM-specific tokens" — is preserved because AGENTS.md is a new artifact and therefore has no pre-Epic-21 baseline to diverge from. Story 21.6 appends on-prem-only content (reasoning-mode, `/no_think`, `str_replace_editor` references) within the same marker block only when `profile === 'on-prem'`.
-
-10. **(gap-fill) Path stamping resolution.** The three directory values referenced by the `## Project BMAD Output Structure` section (planning, architecture, stories) are resolved by the composer (21.2) and/or the stamper caller AFTER composition; since the template itself is static text (AC #2), no placeholder substitution occurs inside the template. Resolution precedence:
-    a. If `_bmad/bmm/config.yaml` exists at the project root AND contains explicit `planning_artifacts`, `architecture_artifacts`, and `implementation_artifacts` fields, use those values (relative to project root, forward-slash-normalized).
-    b. Otherwise, fall back to the repository's documented defaults: `_bmad-output/planning-artifacts/`, `_bmad-output/planning-artifacts/` (architecture currently co-located), `_bmad-output/implementation-artifacts/`.
-    c. Resolution happens once per install, cached, and reused for the marker-block render. The resolved values are logged once at the same verbosity as the Story 21.1 `Using profile: ...` line.
-
-    > **Dev Note (precedence rule, resolved):** When both `_bmad/bmm/config.yaml` and an ad-hoc `_bmad-output/` tree exist, `_bmad/bmm/config.yaml` is authoritative. This matches the BMAD-create-story workflow config loader at `.claude/skills/bmad-create-story/workflow.md` lines 20–27, which declares `_bmad/bmm/config.yaml` as the canonical source for `planning_artifacts` and `implementation_artifacts`. Verified against the repo's own `_bmad/bmm/config.yaml`, which defines `planning_artifacts: "_bmad-output/planning-artifacts"` and `implementation_artifacts: "_bmad-output/implementation-artifacts"` — i.e. the config values and the documented defaults agree here, but the config file wins by rule whenever they diverge. No project-level `architecture.md` override was found that pins a different precedence.
-
-11. **(gap-fill) Upgrade-safety: hand-edit detection.** Before overwriting content inside the markers in `AGENTS.md`, the installer compares existing in-marker content against what would be rendered for the project's current resolved profile, using the exact same drift detection, backup-filename format, and warning format pinned in Story 21.2 AC #10. Per canonical decision C, the backup filename format is `<target>.backup-<ISO-8601-timestamp>` (21.2-owned — cite Story 21.2 as the upstream source of this format). This story does not redefine the format; it inherits it. The `<target>` is `AGENTS.md` at project root.
-
-12. **(gap-fill) OpenCode agent instructionFiles remains `opencode.json`.** This story does NOT change `lib/agents.js` line ~244 (`instructionFiles: ['opencode.json']`). The `AGENTS.md` file is written via `extraInstructionTemplates` only. Rationale: `instructionFiles[]` is the existing contract read by `updateAgentInstructions` for marker-wrap-or-JSON-merge stamping; AGENTS.md is a sibling output and must not be funneled through the existing single-file dispatch.
-
-> **Open question:** The epic treats OpenCode's "auto-loading of AGENTS.md" as a given. OpenCode's current behavior is: `AGENTS.md` at project root is NOT auto-loaded unless listed in `opencode.json::instructions[]`. AC #6 appends it to `instructions[]` which makes auto-loading explicit. If a future OpenCode version auto-discovers `AGENTS.md` without the `instructions[]` entry, AC #6's append becomes redundant but not harmful. Flagged for the implementing dev to confirm against the installed OpenCode version referenced in `lib/agents.js` and the tests in `test/opencode-*.test.js`.
-
-> **Anchor shape (resolved):** Story 21.4 reuses the existing HTML-comment marker pair `<!-- MA-AGENTS-START -->` / `<!-- MA-AGENTS-END -->` in `lib/installer.js` (`updateAgentInstructions`, lines ~424–459) unchanged — this matches the existing implementation the story reuses per epics.md:4229. No alternative marker shape is considered. Story 21.4 creates `## Critical Behavior Rules` inside the marker block with the universal "never write to `~/.claude/`" rule as its first entry; Story 21.6 appends on-prem rules after that entry.
-
-## Tasks / Subtasks
-
-- [ ] **Task 1: Create `lib/templates/agents-md.template.md` (STATIC TEXT, no placeholders)** (AC #1, #2, #3, #9)
-  - [ ] 1.1 Create `lib/templates/agents-md.template.md` (new) as static text with NO `{{...}}` placeholders (canonical decision A). Structure: (a) leading generated-by comment, (b) `# Project Agent Instructions` H1, (c) `## Universal Rules` section — its body is provided at install time by the composer output written into the MA-AGENTS marker block; the template itself contains the section heading and static framing text only, (d) `## Critical Behavior Rules` section containing the "never create files in `~/.claude/` or any user home directory" rule (stable anchor for Story 21.6), (e) `## BMAD Phase Declaration` section with the four phases and phase-specific rules, (f) `## Project BMAD Output Structure` section — path and manifest resolution is performed by the composer (21.2) and/or by the stamper caller AFTER composition; the template contains static framing text only.
-  - [ ] 1.2 Verify by inspection that no string in the template matches `/no_think` or `str_replace_editor`. The single permitted `~/.claude/` occurrence is inside the Critical Behavior Rules "never create files in `~/.claude/`" sentence (AC #9 exception).
-
-- [ ] **Task 2: Add `extraInstructionTemplates` to OpenCode agent entry** (AC #4)
-  - [ ] 2.1 In `lib/agents.js` (line ~224–246), add the `extraInstructionTemplates` field per AC #4 to the OpenCode entry. Do NOT modify `instructionFiles: ['opencode.json']` (AC #12).
-
-- [ ] **Task 3: Consume Story 21.3's `extraInstructionTemplates` processor** (AC #4, #5)
-  - [ ] 3.1 Confirm Story 21.3's processor dispatches on `merger` values. If `markdown-markers` is not already registered, extend the dispatcher in `lib/installer.js` to handle it by delegating to the existing marker-wrap logic (`updateAgentInstructions`'s markdown branch — factor the marker-wrap into a helper if duplication is the alternative).
-  - [ ] 3.2 Per canonical decision A: the stamper calls `composeInstructionBlock({ profile, projectRoot })` exactly once per artifact and passes the composed string to the `markdown-markers` merger as input. The merger does NOT perform `{{...}}` substitution — the template is static text (AC #2). Any path/manifest substitution, if ever required post-composition, is the stamper caller's responsibility AFTER composition.
-
-- [ ] **Task 4: Path resolution helper** (AC #10)
-  - [ ] 4.1 Add a small helper (new) — `resolveBmadOutputDirs(projectRoot)` in `lib/installer.js` (new function) or, if size warrants, `lib/bmad-output-paths.js` (new) — implementing the AC #10 precedence. Read once per install, memoize via module-level `Map<projectRoot, dirs>` to keep `composeInstructionBlock`-style parity.
-  - [ ] 4.2 Log the resolved paths once, using the format `Resolved BMAD output dirs: planning=<...>, architecture=<...>, stories=<...>`.
-
-- [ ] **Task 5: Wire JSON-merge append of `"AGENTS.md"` to `opencode.json::instructions[]`** (AC #6, #7, #8, #12)
-  - [ ] 5.1 In `lib/installer.js` json-merge branch (lines ~365–405), after the existing ma-agents-prefixed string is emplaced, append the literal string `"AGENTS.md"` to `data[targetKey]` if and only if no existing element in the array is `=== 'AGENTS.md'`.
-  - [ ] 5.2 Confirm the `isMaEntry` filter (lines ~372–374) does not match `"AGENTS.md"` (string prefix check only) — this is the intentional behavior for AC #7.
-  - [ ] 5.3 Confirm no other keys in `opencode.json` are read or written (NFR18).
-
-- [ ] **Task 6: Unit and integration tests** — see Testing section below.
-
-- [ ] **Task 7: Documentation touch-up** (no new files)
-  - [ ] 7.1 If an existing doc already describes OpenCode stamping (likely `docs/` or the README section introduced by Story 21.8), append a one-sentence reference to `AGENTS.md`. Otherwise skip — Story 21.8 will cover it.
-
-## Dev Notes
-
-### Architecture compliance
-
-- **Decision P3-3 (Local-LLM / On-Prem Agent Tuning Profile)** — OpenCode parallel to Roo Code's `.roomodes` for application-layer guidance. OpenCode lacks file-regex enforcement (no `FileRestrictionError`), so reliance on prompt + plan-mode discipline is the available leverage. This story installs the prompt-layer half; NFR47 (fileRegex) does not apply to OpenCode.
-
-- **NFR44 (byte-identity for standard profile)** — `AGENTS.md` is a new artifact and has no pre-Epic-21 baseline to diverge from. The NFR44 contract that applies here is the narrower one: standard-profile rendered output MUST NOT contain `/no_think` or `str_replace_editor`. The literal `~/.claude/` is permitted only inside the "never create files in `~/.claude/`" safety rule because that rule is universal per the epic (line 4012). See AC #9 for the full contract.
-
-- **NFR46 (idempotency)** — Two consecutive installs with identical inputs must produce byte-identical marker-block content in `AGENTS.md` AND must not duplicate the `"AGENTS.md"` entry in `opencode.json::instructions[]`. The composer-output route inherits Story 21.2's Task 3.3 insert/replace whitespace normalization. The `isMaEntry`-bypassed string-equality dedup in Task 5.1 is what prevents `instructions[]` duplication.
-
-- **NFR47 (Roo Code fileRegex enforcement)** — Not applicable to OpenCode. Story 21.3 handles NFR47 for Roo Code.
-
-- **NFR18 (additive JSON-merge for OpenCode)** — The existing json-merge path already implements additive merge for `opencode.json::instructions[]` (Epic 9). Task 5.1 extends it with one additional append (`"AGENTS.md"`) using string-equality de-dup rather than prefix match. No other keys are touched. This is a strict superset of the NFR18 contract already satisfied for the ma-agents-prefixed entry.
-
-### Verified source-tree surface
-
-| File | Exists? | Role in this story |
-|------|---------|--------------------|
-| `lib/agents.js` | verified (OpenCode entry at lines 224–246, `instructionFiles: ['opencode.json']` at 244, `injectionStrategy: { position: 'json-merge', targetKey: 'instructions' }` at 245) | MODIFY — add `extraInstructionTemplates` to OpenCode entry |
-| `lib/installer.js` | verified (`MA_AGENTS_SOURCE` const line 9, json-merge branch lines 365–405, `isMaEntry` at 372–374) | MODIFY — json-merge branch extension (Task 5); path-resolution helper (Task 4); `markdown-markers` merger dispatch (Task 3.1, if not delivered by Story 21.3) |
-| `lib/profile.js` | verified (Story 21.1, exports `getProfile`, `setProfile`, `resolveProfile`) | Read-only — consumed via `getProfile(projectRoot)` inside `composeInstructionBlock` upstream |
-| `lib/templates/project-context.template.md` | verified | Reference pattern (unrelated — `agents-md.template.md` is static text per canonical decision A, no placeholder substitution) |
-| `lib/templates/instruction-block-universal.template.md` | **new (Story 21.2)** | Source of truth consumed by `composeInstructionBlock` upstream |
-| `lib/templates/instruction-block-onprem.template.md` | **new (Story 21.6)** | Consumed transitively through `composeInstructionBlock` when profile=on-prem |
-| `lib/templates/agents-md.template.md` | **new** | Template source (AC #1, #2, #3) |
-| `lib/templates/roomodes.template.yaml` | **new (Story 21.3)** | Unrelated target; the `extraInstructionTemplates` processor this story consumes is delivered alongside it |
-| `test/agents-md.test.js` | **new** | Unit + integration tests (see Testing section) |
-| `test/opencode-json-merge.test.js` | verified | Existing json-merge baseline tests — this story adds a sibling test file rather than extending these |
-| `test/profile.test.js` | verified | Reference for test framework, tmp-dir isolation pattern |
-
-### Stamper/merger site map (for reviewers)
-
-- **`extraInstructionTemplates` processing** (delivered by Story 21.3, extended here): per-agent loop reads each entry, loads `lib/templates/<template>`, calls the composer (21.2) to produce the composed string, dispatches to `merger` — `yaml-customModes` (Story 21.3) or `markdown-markers` (this story). Per canonical decision A, the merger receives the composed string as input; no placeholder substitution occurs.
-- **JSON-merge stamping** (`lib/installer.js` lines 365–405, this story's Task 5): OpenCode gets TWO `instructions[]` entries after this story — the existing `[ma-agents]` prefixed string AND the plain `"AGENTS.md"` literal.
-- **Markdown marker-wrap (merger)** (`lib/installer.js` lines 407–459): not invoked for OpenCode — OpenCode's `instructionFiles` is `opencode.json`, not a markdown file. `AGENTS.md` reaches the marker-wrap logic via the `markdown-markers` merger dispatch, NOT via `updateAgentInstructions`.
-
-### Library and pattern references
-
-- **Composer (21.2-owned):** `composeInstructionBlock({ profile, projectRoot }): string` is the single owner of universal-rules composition. The stamper in `lib/installer.js` calls it once per artifact. The `agents-md.template.md` source contains no `{{...}}` placeholders (canonical decision A).
-- **Markdown markers:** reuse `<!-- MA-AGENTS-START -->` / `<!-- MA-AGENTS-END -->` verbatim; same regex as `updateAgentInstructions`. Anchor shape fixed — no alternative shape.
-- **Backup filename format (21.2-owned, canonical decision C):** `<target>.backup-<ISO-8601-timestamp>` — cite Story 21.2 as the upstream source; matches Stories 21.10, 21.11 transitively.
-- **Manifest-path computation:** `path.relative(projectRoot, path.join(agent.getProjectPath(), 'MANIFEST.yaml')).replace(/\\/g, '/')` — already present in `lib/installer.js` json-merge branch, line 369.
-- **`isMaEntry`:** existing filter at `lib/installer.js` lines 372–374. NOT extended here. Intentional (AC #7).
-
-### Composition pattern (how this story fits Stories 21.3–21.6)
-
-```
-extraInstructionTemplates processor (Story 21.3)
-  ├── merger: 'yaml-customModes' → .roomodes (Story 21.3)
-  └── merger: 'markdown-markers' → AGENTS.md (this story), .clinerules (Story 21.5 — if it uses the same processor)
-
-composeInstructionBlock (Story 21.2)
-  └── invoked once per artifact by the stamper; the composed string is passed to the 'markdown-markers' merger as input (no placeholder substitution — template is static text)
-      ├── universal template (Story 21.2)
-      └── on-prem template (Story 21.6, conditional on profile)
-```
-
-Story 21.6 extends the on-prem layer by (a) appending on-prem content inside `composeInstructionBlock`'s output (transparent to this story), and (b) appending a phase-aware on-prem block directly under the `## Critical Behavior Rules` anchor in `agents-md.template.md` — see Open question in AC #11 about Story 21.6 anchoring expectations.
-
-### Out of scope
-
-- On-prem template content appended to `AGENTS.md` (Story 21.6).
-- BMAD persona phase prefix in customize-loader (Story 21.7).
-- vLLM deployment documentation and README on-prem section (Story 21.8).
-- `.roomodes` template and `yaml-customModes` merger (Story 21.3).
-- `.clinerules` template (Story 21.5).
-- Profile-reconfigure flow that re-stamps `AGENTS.md` (Story 21.10).
-- Profile-uninstall removal of the `"AGENTS.md"` entry from `opencode.json::instructions[]` (Story 21.11).
-- Bumping `manifestVersion` — already at `1.2.0` (Story 21.1) and not touched here.
-- NFR44 byte-comparison integration test against pre-Epic-21 baseline (Story 21.9).
-
-## Dependencies
-
-### Upstream (blocking)
-
-- **Story 21.1 (done)** — `lib/profile.js` `getProfile(projectRoot)` consumed transitively via `composeInstructionBlock`.
-- **Story 21.2 (Ready)** — owns TWO deliverables consumed by this story (cited as upstream per canonical decisions A and C):
-  - The composer `composeInstructionBlock({ profile, projectRoot }): string` in `lib/installer.js` — sole source of the universal-rules content written into the AGENTS.md MA-AGENTS marker block. The stamper (this story, single owner in `lib/installer.js`) calls the composer exactly once per artifact and passes the composed string to the `markdown-markers` merger.
-  - The canonical backup-filename format `<target>.backup-<ISO-8601-timestamp>` (21.2-owned) — inherited verbatim by AC #11.
-  Story 21.4 cannot land before 21.2 without duplicating the universal-rules wording (drift risk) or the backup format.
-- **Story 21.3 (Ready)** — delivers the `extraInstructionTemplates` field convention on `lib/agents.js` entries AND the per-agent processor in `lib/installer.js`. Story 21.4 reuses both. If Story 21.3 lands without the `markdown-markers` merger, this story's Task 3.1 adds it.
-- **Epic 9 (done)** — `opencode.json` additive JSON-merge pattern in `updateAgentInstructions` (lines 365–405) is extended unchanged for the `AGENTS.md` append. NFR18 already satisfied by that code; this story must not regress it.
-
-### Downstream (consumers of this story's surface)
-
-- **Story 21.5** — may share the `markdown-markers` merger for `.clinerules` (if Story 21.5 routes through `extraInstructionTemplates` rather than the existing `updateAgentInstructions` path). Story 21.4 does not pre-commit Story 21.5 to that routing — Story 21.5 decides.
-- **Story 21.6** — appends on-prem content (reasoning-mode, `/no_think`) inside the `## Critical Behavior Rules` section of `agents-md.template.md` (see Open question in AC #11). Requires the section anchor to exist.
-- **Story 21.9** — tests verifying NFR44 (absence of `/no_think`, `str_replace_editor` in standard-profile `AGENTS.md`), NFR46 (idempotency), NFR18 (JSON-merge not regressed for the dual-entry case).
-- **Story 21.10** — re-stamps `AGENTS.md` on `reconfigure`, reusing the same backup format.
-- **Story 21.11** — on `uninstall --profile-artifacts`, removes the `"AGENTS.md"` entry from `opencode.json::instructions[]` AND the file itself (with backup).
-
-## Testing
-
-**Framework and isolation:** Match the pattern in `test/profile.test.js` (Story 21.1) and `test/opencode-json-merge.test.js` (Epic 9) — node's built-in test runner, `os.tmpdir()` + `fs.mkdtempSync` per-test temporary project roots, never mutate the repo's own `.ma-agents.json`, `lib/templates/`, or `opencode.json`.
-
-New test file: `test/agents-md.test.js` (new).
-
-**Unit tests:**
-
-- 6.1 Template is loaded verbatim from disk as static text — assert the source contains NO `{{...}}` placeholders (AC #2, canonical decision A).
-- 6.2 The stamper invokes `composeInstructionBlock({ profile, projectRoot })` exactly once per artifact and passes the resulting string to the `markdown-markers` merger (AC #3). Assert single invocation via a spy or call-count instrumentation permitted by the test harness (do not stub the real module — wrap via a local test double per `test/profile.test.js` conventions).
-- 6.3 The composed string produced by `composeInstructionBlock({ profile: 'standard', projectRoot })` appears byte-for-byte inside the MA-AGENTS marker block of the rendered `AGENTS.md` (AC #3).
-- 6.4 NFR44 assertion: standard-profile rendered output does not contain `/no_think` or `str_replace_editor`. The single permitted `~/.claude/` occurrence is the Critical Behavior Rules sentence (AC #9 exception) — asserted by verifying exactly one match and that it appears within the expected sentence.
-- 6.5 Path-resolution precedence (AC #10): with `_bmad/bmm/config.yaml` present → config values win; absent → documented defaults used; tmp project covers both cases.
-
-**Integration tests (within this story — full end-to-end lives in Story 21.9):**
-
-- 6.6 Fresh install selecting OpenCode writes `AGENTS.md` at project root with stamped paths, universal rules, Critical Behavior Rules section, BMAD phase declaration, and output-structure section (AC #1, #5 create case).
-- 6.7 `opencode.json::instructions[]` after fresh install contains BOTH the ma-agents-prefixed string AND `"AGENTS.md"`, in that order; other keys in `opencode.json` untouched (AC #6, AC #12 NFR18).
-- 6.8 Re-install (idempotency — AC #8, NFR46):
-  - `AGENTS.md` marker-block content byte-identical.
-  - `opencode.json::instructions[]` unchanged (length and order): the ma-agents entry is replaced in place; the `"AGENTS.md"` entry is not duplicated.
-  - No `.backup-*` files created when no drift.
-- 6.9 Pre-existing `AGENTS.md` with user content outside markers: user content preserved byte-for-byte; marker-block content replaced (AC #5 merge case).
-- 6.10 Pre-existing `AGENTS.md` without markers: marker block appended at EOF separated by one blank line; existing content preserved (AC #5 no-markers case).
-- 6.11 Upgrade-safety drift (AC #11): hand-edited marker block → behavior matches Story 21.2 AC #10 (interactive confirm; `--yes` emits verbatim WARNING; backup file at `<target>.backup-<timestamp>` contains only the marker region including markers).
-- 6.12 User already has `"AGENTS.md"` in `opencode.json::instructions[]` before install → install does NOT append a duplicate (string-equality de-dup — AC #6).
-- 6.13 User entry `{ "path": "AGENTS.md" }` (object form, not string) in `instructions[]` before install → install appends the string `"AGENTS.md"` (not considered a duplicate because the existing entry is not `=== 'AGENTS.md'`). Decision rationale captured in test comment referencing AC #6's "string equality" contract.
-
-**Test data isolation:** All tests create a tmp project with a stub `.ma-agents.json` written via `setProfile(tmpRoot, 'standard' | 'on-prem')` (Story 21.1 API). Do not stub `lib/profile.js`, `lib/installer.js`, or `lib/agents.js` — use the real modules against the tmp project root.
-
-**Coverage note:** Story 21.9 adds (a) standard-profile vs. on-prem-profile NFR44 absence-of-strings byte-check, (b) dual-layer content presence for on-prem, (c) NFR18 full `opencode.json` round-trip across profiles. Do not duplicate those here.
-
-## Out of Scope
-
-(See Dev Notes → Out of scope above — summarized for quick reference.)
-
-- On-prem-specific additions to `AGENTS.md` (Story 21.6).
-- BMAD persona phase prefix in customize-loader (Story 21.7).
-- vLLM deployment documentation and README on-prem section (Story 21.8).
-- `.roomodes` template and `yaml-customModes` merger (Story 21.3).
-- `.clinerules` template (Story 21.5).
-- Profile-reconfigure re-stamping flow (Story 21.10).
-- Profile-uninstall removal of `"AGENTS.md"` entry and file (Story 21.11).
-
-## Change Log
-
-- 2026-04-14: Story created (Epic 21, Story 21.4) — initial draft.
-- 2026-04-15: Story rewritten in Story 21.2 "Ready" shape — gap-fills flagged explicitly (AC #2, #3, #5, #7, #10, #11, #12); NFR44/NFR46/NFR47/NFR18 citations made explicit in Dev Notes; Dependencies section split into upstream/downstream; Testing section expanded; verified source-tree surface table added distinguishing existing vs. new paths; injection-site map added; three Open questions raised inline rather than invented as ACs; Out of Scope promoted to its own top-level section. Status set to Ready.
-- 2026-04-15: Story 21.4 implemented — AGENTS.md template, markdown-markers merger, extraInstructionTemplates processor, OpenCode wiring, BMAD-output-dirs resolver. 14 new tests (all green); full npm test suite green. Status Ready → Review.
-- 2026-04-15: Adversarial-review findings resolved. Applied canonical decisions A/B/C: (A) `agents-md.template.md` is STATIC TEXT with no `{{...}}` placeholders; composer `composeInstructionBlock({ profile, projectRoot }): string` is 21.2-owned and called once per artifact by the stamper in `lib/installer.js` (single owner); mergers consume the composed string. (B) Terminology normalized to composer / merger / stamper — "injection function" and "marker-injection" removed. (C) Backup filename format `<target>.backup-<ISO-8601-timestamp>` cited as 21.2-owned. Marker-shape Open question closed: story reuses the existing HTML-comment marker pair `<!-- MA-AGENTS-START -->` / `<!-- MA-AGENTS-END -->` from `lib/installer.js::updateAgentInstructions` unchanged (confirmed by reading `lib/installer.js`; no `mergeOpencodeJson()` symbol exists — logic is the json-merge branch of `updateAgentInstructions`). ACs #2, #3, #5 rewritten accordingly; Testing 6.1–6.3 rewritten to assert static-text template + single composer invocation. Status moved to Draft pending upstream 21.2 and 21.3 landings (see blockers).
-
-## Dev Agent Record
-
-### Agent Model Used
-Claude Opus 4.6 (1M context) — bmad-dev-story + inline adversarial-review + edge-case-hunter flow.
-
-### Completion Notes List
-- `lib/templates/agents-md.template.md` ships as STATIC TEXT with zero `{{...}}` placeholders (AC #2, canonical decision A). Sections: H1 "Project Agent Instructions", "## Universal Rules" (MA-AGENTS markers), "## Critical Behavior Rules" (`~/.claude/` rule anchor for Story 21.6), "## BMAD Phase Declaration" (4 phases), "## Project BMAD Output Structure".
-- `extraInstructionTemplates` field added to the OpenCode entry in `lib/agents.js` (AC #4). `instructionFiles: ['opencode.json']` left unchanged (AC #12).
-- New helper `markdownMarkersMerger(targetPath, templateBody, composedBlock, {yesMode})` implements AC #5 (fresh-create / in-place-replace / no-marker-append) and inherits Story 21.2's `handleMarkerBlockDrift` + canonical backup filename format (AC #11).
-- New helper `stampExtraInstructionTemplates(agent, projectRoot, {yesMode})` dispatches on `merger`: currently handles `markdown-markers`; unknown mergers (e.g. `yaml-customModes` for Story 21.3) log a warning and skip so the processor is forward-compatible. Composer is invoked exactly once per entry (canonical composer contract).
-- New helper `resolveBmadOutputDirs(projectRoot)` implements AC #10 precedence with a minimal line-scan YAML reader for `_bmad/bmm/config.yaml`. Memoized per projectRoot; logs resolved values once per root.
-- JSON-merge branch of `updateAgentInstructions` extended (AC #6): after emplacing the `[ma-agents]` entry, each `extraInstructionTemplates` target whose merger is `markdown-markers` is appended to `instructions[]` as a plain string if not already present by strict `===` equality. The `isMaEntry` filter was NOT extended (AC #7) — the literal `"AGENTS.md"` is user-owned after first install.
-- Markdown branch of `updateAgentInstructions` also invokes `stampExtraInstructionTemplates` so Stories 21.3/21.5 can drop `extraInstructionTemplates` on non-JSON agents without further installer changes.
-- NFR44 preserved: rendered standard-profile AGENTS.md contains zero `/no_think` or `str_replace_editor` occurrences; `~/.claude/` appears exactly once, inside the Critical Behavior Rules sentence (AC #9 exception). Verified by test 6.4.
-- Canonical composer contract respected: `composeInstructionBlock({ profile, projectRoot })` is called once per stamped artifact; `{{MANIFEST_PATH}}` substitution is applied AFTER composition (Story 21.2 AC #3).
-
-### Adversarial Review Findings (inline — P0/P1 dispositions)
-
-| # | Layer | Severity | Finding | Disposition |
-|---|-------|----------|---------|-------------|
-| 1 | Cynical | P1 | Template prose originally contained literal `<!-- MA-AGENTS-START -->` / `<!-- MA-AGENTS-END -->` text inside a backtick code-span — on first write, `emptyMarkerPair` regex matched the prose pair first, corrupting the file | **Fixed** — rewrote prose to describe markers without literal HTML comment syntax |
-| 2 | Cynical | P1 | `markdownMarkersMerger` skips write when in-marker content is byte-identical — could leave stale OUTSIDE-markers framing text drifted from template on re-install | **Accepted by design (AC #5)** — content outside markers is user territory; ma-agents only owns the marker block on re-install |
-| 3 | Cynical | P1 | JSON-merge `extraJsonEntries` dedup filters against `userEntries` only (post-filter); OK because `[ma-agents]` entries are stripped first and `"AGENTS.md"` has no prefix | **No issue** — verified by test 6.8 (idempotency) and 6.12 (pre-existing literal) |
-| 4 | Cynical | P2 | `stampExtraInstructionTemplates` NOT invoked on JSON-merge parse-error path | **Accepted** — if `opencode.json` is corrupt we should not stamp side-files that reference it |
-| 5 | Cynical | P2 | `resolveBmadOutputDirs` log-once Set is process-lifetime; test runs create many tmp dirs | **Accepted** — bounded to tmp dir count within a single test process; acceptable |
-| 6 | Edge-case | P1 | YAML scalar scanner is regex-based; skips quoted multi-line or folded scalars | **Accepted** — AC #10 fields are flat scalars; verified against repo's own `_bmad/bmm/config.yaml` |
-| 7 | Edge-case | P1 | Malformed `extraInstructionTemplates` entry (missing field) | **Handled** — explicit guard warns and skips |
-| 8 | Edge-case | P1 | Object-form `{ path: 'AGENTS.md' }` pre-existing entry is NOT dedup-matched; installer appends the string literal | **Accepted by design (AC #6 string-equality contract)** — codified in test 6.13 |
-| 9 | Edge-case | P1 | Pre-existing AGENTS.md without markers — the "append at EOF" branch computes trailing-whitespace-stripped base then adds block | **Handled** — test 6.10 asserts content byte-preserved; re-install hits the marker-regex branch and is idempotent |
-| 10 | Edge-case | P1 | No-markers append on subsequent install would NOT hit the "append at EOF" branch because markers ARE now present from first append | **By design** — two-stage convergence is the documented behavior |
-
-All P0/P1 findings resolved or accepted with documented rationale.
-
-### File List
-- CREATED: `lib/templates/agents-md.template.md`
-- CREATED: `test/agents-md.test.js` (14 tests, all passing)
-- MODIFIED: `lib/agents.js` (OpenCode entry: added `extraInstructionTemplates` field)
-- MODIFIED: `lib/installer.js` (`resolveBmadOutputDirs`, `markdownMarkersMerger`, `stampExtraInstructionTemplates`, JSON-merge branch extension for `AGENTS.md` literal append, wiring into `updateAgentInstructions` for both branches, new exports)
-- MODIFIED: `package.json` (added `test/agents-md.test.js` to npm test script)
-- MODIFIED: `_bmad-output/implementation-artifacts/21-4-agents-md-template-opencode.md` (Status → Review; Dev Agent Record / File List / Change Log)