ma-agents 3.4.9 → 3.5.1

package/_bmad-output/implementation-artifacts/done/9-1-register-opencode-agent.md

@@ -0,0 +1,73 @@
+# Story 9.1: Register OpenCode Agent in Registry
+
+Status: review
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As a **Chief Architect**,
+I want OpenCode added to agents.js as the 12th agent with JSON injection strategy,
+So that the installer can target OpenCode using the same config-driven pattern.
+
+## Acceptance Criteria
+
+1. **Given** the agents.js registry, **When** the OpenCode agent entry is added, **Then** it includes: `id: 'opencode'`, `name: 'OpenCode'`, `category: 'ide'`, `getProjectPath()` returning `path.join(process.cwd(), '.opencode', 'skills')`, `getGlobalPath()` with per-platform paths under `.opencode`, `instructionFiles: ['opencode.json']`, **And** `injectionStrategy` is `{ position: 'json-merge', targetKey: 'instructions' }`.
+2. **Given** the installer runs with `--agent opencode`, **When** agent resolution occurs, **Then** OpenCode is found and processed like any other agent, **And** no code changes to installer.js were needed (NFR13).
+
+## Tasks / Subtasks
+
+- [x] Add OpenCode agent object to agents array in lib/agents.js (AC: #1)
+  - [x] Define agent entry with `id: 'opencode'`, `name: 'OpenCode'`, `version: '1.0.0'`, `category: 'ide'`, `description: 'OpenCode AI Assistant'`
+  - [x] Implement `getProjectPath()` returning `path.join(process.cwd(), '.opencode', 'skills')` — this fulfils the epics spec's `configDir: '.opencode'` / `skillsDir: '.opencode/skills'` requirement using the function-based pattern canonical to agents.js
+  - [x] Implement `getGlobalPath()` following the same per-platform pattern as existing agents (win32 → AppData/Roaming, darwin → Library/Application Support, linux → ~/.config), using `.opencode` as the root directory
+  - [x] Set `fileExtension: '.md'` — this is the extension for deployed skill template files, NOT for the instruction config file. OpenCode skill assets are markdown documents; the instruction config file is declared separately via `instructionFiles`. The `.md` value is correct here.
+  - [x] Set `template: 'generic'`
+  - [x] Set `instructionFiles: ['opencode.json']` — canonical plural-array form as consumed by `updateAgentInstructions()` in installer.js line 111. **Note:** the epics spec uses singular `instructionFile`, but the codebase field is `instructionFiles` (array). The array form is authoritative; use it.
+  - [x] Set `injectionStrategy: { position: 'json-merge', targetKey: 'instructions' }` — **CRITICAL:** `position` must be exactly the string `'json-merge'`. Any typo silently falls through to the wrong code path with no runtime error. Double-check spelling before committing.
+- [x] Write unit test verifying the new agent object conforms to required schema: id (string), name (string), category (string), getProjectPath (function), getGlobalPath (function), fileExtension (string), template (string), instructionFiles (non-empty array of strings), injectionStrategy.position (string), injectionStrategy.targetKey (string) — all fields present and correctly typed (AC: #1)
+- [x] Test that `--agent opencode` resolves correctly through existing installer logic (AC: #2)
+- [x] Verify no changes to installer.js are required for agent resolution (AC: #2)
+
+## Dev Notes
+
+### Architecture Compliance
+- NFR13: Config-driven registry pattern. Adding an agent must only require a new entry in agents.js; no installer.js changes for resolution.
+- Agent structure must follow the exact same shape as existing agents. Reference entries: `claude-code` (lines 18-38 of agents.js) and `antigravity` (lines 171-190 of agents.js).
+- `antigravity` is the Google Deepmind Antigravity Agent (`id: 'antigravity'`, `category: 'ide'`). It appears before OpenCode in the array. Do not assert on absolute agent positions — the registry order may change as agents are added.
+- The `injectionStrategy` field is new — it is NOT present on any existing agent. It will be read by the JSON merge logic added in Stories 9.2, 9.3, and 9.4 in installer.js.
+- `version: '1.0.0'` follows the convention used by existing agents (except `bmm-mil498` which is `'2.0.0'`). This field is informational only — installer.js does not read or validate it. Use `'1.0.0'`.
+
+### Critical Guardrails
+- Do NOT modify installer.js for this story — agent resolution must work via existing config-driven patterns
+- Do NOT hardcode agent names anywhere in the installer
+- Do NOT change the structure of existing agent entries
+- Do NOT assert on total agent count in tests — the count changes as agents are added/removed and is not a stable invariant for this story's behavior
+
+### Project Structure Notes
+- Modify: `lib/agents.js` — add one new agent object to the agents array
+- No new files created
+
+### References
+- [Source: lib/agents.js lines 18-38 — claude-code entry for exact structure reference]
+- [Source: lib/agents.js lines 171-190 — antigravity entry: `id='antigravity'`, `name='Antigravity'`, Google Deepmind Antigravity Agent, `category='ide'`, uses getProjectPath/getGlobalPath functions, `fileExtension='.md'`, `template='generic'`, `instructionFiles=['.antigravity/antigravity.md']`]
+- [Source: lib/installer.js#L111 — `if (!agent.instructionFiles || agent.instructionFiles.length === 0) return;` — confirms `instructionFiles` (plural array) is the canonical field name]
+
+## Dev Agent Record
+
+### Agent Model Used
+claude-sonnet-4-6
+
+### Debug Log References
+None — implementation was straightforward with no debugging required.
+
+### Completion Notes List
+- Added opencode agent as the 12th entry in lib/agents.js immediately after the `antigravity` entry, with all required fields: id, name, version, category, description, getProjectPath, getGlobalPath (per-platform win32/darwin/linux), fileExtension, template, instructionFiles, and injectionStrategy with position `json-merge` and targetKey `instructions`.
+- Created test/opencode-agent.test.js with 19 unit tests covering full schema validation and registry resolution via getAgent() and getAllAgents().
+- Updated test/agent-injection-strategy.test.js to accommodate the new opencode agent: relaxed exact agent count assertion, made skipPatterns check conditional on non-json-merge strategy, and updated position check to skip json-merge agents.
+- No changes to installer.js were required — the opencode agent resolves via the existing config-driven getAgent() lookup pattern (NFR13 compliant).
+
+### File List
+- lib/agents.js
+- test/opencode-agent.test.js
+- test/agent-injection-strategy.test.js

package/_bmad-output/implementation-artifacts/done/9-2-json-merge-injection.md

@@ -0,0 +1,91 @@
+# Story 9.2: JSON Injection — Create opencode.json When Absent
+
+Status: review
+
+depends-on: 9-1-register-opencode-agent
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As a **Chief Architect**,
+I want the installer to create opencode.json from scratch when it does not yet exist,
+So that OpenCode receives skill instructions on first install without requiring any manual setup.
+
+## Acceptance Criteria
+
+1. **Given** no opencode.json exists in the project root, **When** the installer runs for the OpenCode agent, **Then** a new opencode.json is created containing an `instructions` array whose entries are ma-agents-owned objects (shape: `{ "_source": "ma-agents", "text": "<instruction text>" }`), **And** the file is valid JSON with 2-space indentation, **And** the file contains no other keys.
+
+## Tasks / Subtasks
+
+- [x] Define the named constant `MA_AGENTS_SOURCE = 'ma-agents'` at the top of lib/installer.js (AC: #1)
+  - [x] Use this constant everywhere `'ma-agents'` appears — never use the bare string literal
+- [x] In `updateAgentInstructions()` (installer.js line 110), add a conditional branch that routes to JSON merge logic when `agent.injectionStrategy?.position === 'json-merge'` (AC: #1)
+  - [x] Guard: if `injectionStrategy.position` is not exactly `'json-merge'`, do not enter the JSON path — fall through to existing markdown logic unchanged
+- [x] Implement the file-absent creation path (AC: #1)
+  - [x] Check if the target file (resolved from `agent.instructionFiles[0]` relative to `projectRoot`) exists using `fs.existsSync()`
+  - [x] If file does NOT exist: build a fresh JSON object `{ instructions: [] }`
+  - [x] Append ma-agents instruction entries to `instructions` — each entry must be an object: `{ "_source": MA_AGENTS_SOURCE, "text": "<generated instruction text>" }`
+  - [x] Write the resulting object to the target path using `JSON.stringify(data, null, 2)` via `fs.outputFile()`
+- [x] Write fixture-based unit test for the creation path (AC: #1)
+  - [x] Fixture: directory with no opencode.json present
+  - [x] Assert: file created, is valid JSON, contains `instructions` array, every entry has `_source === 'ma-agents'` and a non-empty `text` string
+  - [x] Assert: no extra top-level keys in the written JSON
+
+## Dev Notes
+
+### Named Constant — CRITICAL
+Define once at the top of installer.js:
+```js
+const MA_AGENTS_SOURCE = 'ma-agents';
+```
+Use `MA_AGENTS_SOURCE` in every comparison and every object literal that sets `_source`. A mismatched string literal across filter logic, generation logic, and tests will cause silent ownership detection failures.
+
+### Entry Format
+Each ma-agents-managed instruction entry is a structured object, NOT a plain string:
+```json
+{ "_source": "ma-agents", "text": "<instruction content>" }
+```
+Detection logic (used in Stories 9.3 and 9.4) checks `entry._source === MA_AGENTS_SOURCE`. This is safe against any user instruction that happens to contain the string `'ma-agents'` — user plain-string entries will never match an object property check.
+
+### Architecture Compliance
+- NFR18: Additive-only JSON merge — only the `instructions` key is written on creation; no other keys added.
+- No new npm dependencies — use built-in `JSON.parse` / `JSON.stringify` and `fs-extra` (already a project dependency).
+- Do NOT add `configDir` or `skillsDir` as code fields — path resolution uses `agent.getProjectPath()` as per the existing pattern in `updateAgentInstructions()`.
+- Stories 9.3 (merge path) and 9.4 (error path) add the remaining branches to this same conditional block. Architect the branch structure so those cases can be added cleanly alongside this one.
+
+### Critical Guardrails
+- Do NOT modify the existing markdown injection code path — this is a new parallel branch for `json-merge` strategy only
+- Do NOT use `'ma-agents'` as a bare string literal anywhere — always use `MA_AGENTS_SOURCE`
+- Do NOT restructure `updateAgentInstructions()` — add the conditional path alongside existing logic
+
+### Project Structure Notes
+- Modify: `lib/installer.js` — `updateAgentInstructions()` at line 110, add `json-merge` branch and `MA_AGENTS_SOURCE` constant
+- No new files created
+- Test fixture: directory with no opencode.json
+
+### References
+- [Source: lib/installer.js#L110 — `updateAgentInstructions()` function]
+- [Source: lib/installer.js#L111 — `agent.instructionFiles` array consumption pattern]
+- [Source: lib/installer.js#L130-146 — existing MA-AGENTS-START/END markdown marker system — do not modify]
+- [Source: lib/agents.js — OpenCode agent entry with `injectionStrategy` field from Story 9-1]
+
+## Dev Agent Record
+
+### Agent Model Used
+claude-sonnet-4-6
+
+### Debug Log References
+None — implementation was straightforward, all 12 new tests passed on first run alongside all 51 existing tests.
+
+### Completion Notes List
+- Added `MA_AGENTS_SOURCE = 'ma-agents'` constant at top of `lib/installer.js` after `MANIFEST_VERSION`
+- Added `json-merge` branch at the top of `updateAgentInstructions()`, before the existing markdown injection code; the branch exits via `return` so markdown logic is completely untouched
+- File-absent path creates `{ instructions: [{ _source: MA_AGENTS_SOURCE, text: <planning instruction> }] }` using the same instruction text formula as the markdown path (relative MANIFEST.yaml path)
+- File-present path is a no-op `return` per Story 9.3 placeholder requirement
+- Exported `MA_AGENTS_SOURCE` as `_MA_AGENTS_SOURCE` for test consumption
+- 12 new tests in `test/opencode-json-injection.test.js` covering: file creation, valid JSON, instructions array, non-empty entries, `_source` equality, non-empty text, no extra top-level keys, 2-space indentation, MANIFEST.yaml reference, constant value, markdown fallthrough guard, and file-present no-op
+
+### File List
+- `lib/installer.js` — added `MA_AGENTS_SOURCE` constant, `json-merge` branch in `updateAgentInstructions()`, exported `_MA_AGENTS_SOURCE`
+- `test/opencode-json-injection.test.js` — new test file with 12 fixture-based unit tests

package/_bmad-output/implementation-artifacts/done/9-3-json-merge-existing.md

@@ -0,0 +1,113 @@
+# Story 9.3: JSON Injection — Merge Into Existing opencode.json
+
+Status: review
+
+depends-on: 9-2-json-merge-injection
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As a **Chief Architect**,
+I want the installer to merge skill instructions into an existing opencode.json without destroying user configuration,
+So that re-running the installer on a project that already has opencode.json updates ma-agents entries while leaving everything else untouched (NFR18).
+
+## Acceptance Criteria
+
+1. **Given** an existing valid opencode.json that contains an `instructions` array with a mix of user-owned entries and ma-agents-owned entries (identified by `_source === MA_AGENTS_SOURCE`), and additional top-level JSON keys, **When** the installer runs for the OpenCode agent, **Then** all user-owned instruction entries (those without `_source === MA_AGENTS_SOURCE`) are preserved in their original positions, **And** all previous ma-agents entries are removed and replaced with fresh ones appended at the end of the `instructions` array, **And** all other top-level JSON keys (not `instructions`) have semantically identical values in the output (object structure and values preserved; 2-space indentation is the normalized output format), **And** the write is performed atomically (write to a temp file, then rename over the target).
+
+## Tasks / Subtasks
+
+- [x] Implement the file-present merge path in the `json-merge` branch of `updateAgentInstructions()` (AC: #1)
+  - [x] When `fs.existsSync(filePath)` is true and JSON parsing succeeds (see Story 9.4 for the parse-failure path): proceed with merge
+  - [x] Read file content with `fs.readFile(filePath, 'utf-8')`
+  - [x] Parse with `JSON.parse()` — if parse throws, delegate to the Story 9.4 error path
+  - [x] If parsed object has no `instructions` key, initialize it as an empty array before merging (do not error or skip — create the key)
+  - [x] Filter the existing `instructions` array: keep entries where `entry._source !== MA_AGENTS_SOURCE` (user entries), discard entries where `entry._source === MA_AGENTS_SOURCE` (stale ma-agents entries)
+  - [x] Append fresh ma-agents entries (objects of shape `{ "_source": MA_AGENTS_SOURCE, "text": "<instruction text>" }`) to the preserved user entries
+  - [x] Reassign `data.instructions` to the merged array; leave all other top-level keys on `data` untouched
+  - [x] Perform atomic write: serialize with `JSON.stringify(data, null, 2)`, write to `filePath + '.tmp'`, then `fs.rename(tmpPath, filePath)`
+- [x] Write fixture-based unit test for the merge path (AC: #1)
+  - [x] Fixture: opencode.json with 2 user entries (plain string and object without `_source`), 1 stale ma-agents entry (`_source: 'ma-agents'`), and 1 unrelated top-level key (`"theme": "dark"`)
+  - [x] Assert: user entries preserved (count = 2, original values intact)
+  - [x] Assert: stale ma-agents entry removed; fresh ma-agents entries appended
+  - [x] Assert: `theme` key present in output with value `"dark"` unchanged
+  - [x] Assert: output is valid JSON
+  - [x] Assert: no `.tmp` file left on disk after successful write
+
+## Dev Notes
+
+### Named Constant — CRITICAL
+Use the `MA_AGENTS_SOURCE` constant defined in Story 9.2. Never use `'ma-agents'` as a bare string literal. Every ownership check must reference the constant:
+```js
+entry._source !== MA_AGENTS_SOURCE  // keep user entries
+entry._source === MA_AGENTS_SOURCE  // identify ma-agents entries to replace
+```
+
+### Entry Format
+Ma-agents instruction entries are structured objects:
+```json
+{ "_source": "ma-agents", "text": "<instruction content>" }
+```
+User entries may be plain strings or objects with any other shape. The filter must only remove entries where `_source === MA_AGENTS_SOURCE` — no other entries may be touched.
+
+### Missing `instructions` Key Behavior
+If a valid opencode.json exists but has no `instructions` key, treat it as if `instructions` is an empty array:
+```js
+if (!Array.isArray(data.instructions)) data.instructions = [];
+```
+Then proceed normally with merge. Do not emit an error or skip the file.
+
+### Atomic Write
+Do not write directly to the target file. Use:
+```js
+const tmpPath = filePath + '.tmp';
+await fs.outputFile(tmpPath, JSON.stringify(data, null, 2), 'utf-8');
+await fs.rename(tmpPath, filePath);
+```
+A crash between write and rename leaves a `.tmp` file that can be inspected. A crash during direct write corrupts the production file. Always use the temp-rename pattern.
+
+### JSON Formatting
+`JSON.stringify(data, null, 2)` normalizes indentation to 2 spaces. This is the documented output format — "preserved exactly" in AC #1 means all non-instructions keys have semantically identical values (same keys, same values, same nesting). Whitespace and key ordering are not guaranteed to match the original. This is a known trade-off given the no-new-npm-deps constraint.
+
+### Architecture Compliance
+- NFR18: Additive-only merge — only `instructions` key contents change; all other keys pass through unmodified.
+- NFR7: Read-validate-write pattern — read → parse → validate → modify → atomic write.
+- No new npm dependencies.
+
+### Critical Guardrails
+- Do NOT remove or modify any entry where `entry._source !== MA_AGENTS_SOURCE`
+- Do NOT write directly to the target file — always use atomic temp-rename
+- Do NOT use `'ma-agents'` as a bare string — always use `MA_AGENTS_SOURCE`
+- Do NOT modify the existing markdown injection code path
+
+### Project Structure Notes
+- Modify: `lib/installer.js` — extend the `json-merge` branch started in Story 9.2, adding the file-present merge sub-path
+- No new files created
+- Test fixture: opencode.json with mixed entries and extra top-level keys
+
+### References
+- [Source: lib/installer.js#L110 — `updateAgentInstructions()` function]
+- [Source: lib/installer.js#L130-146 — existing markdown marker system — do not modify]
+- [Source: lib/agents.js — OpenCode agent entry with `injectionStrategy` from Story 9-1]
+- [Source: Story 9.2 — `MA_AGENTS_SOURCE` constant definition and entry shape]
+- [Source: Story 9.4 — error path that handles JSON.parse failure for this same file-present branch]
+
+## Dev Agent Record
+
+### Agent Model Used
+claude-sonnet-4-6
+
+### Debug Log References
+None — implementation was straightforward.
+
+### Completion Notes List
+- Replaced the `return` placeholder in the file-present branch of the `json-merge` section in `updateAgentInstructions()` with full merge logic
+- Merge logic: reads existing JSON, initializes `instructions` array if absent, filters out stale `MA_AGENTS_SOURCE` entries while preserving all user entries, appends fresh ma-agents entries, performs atomic write via temp-file-then-rename pattern
+- Created `test/opencode-json-merge.test.js` with 10 fixture-based tests covering: user entry preservation, stale entry removal, fresh entry append order, extra top-level key preservation, valid JSON output, no leftover .tmp file, missing instructions key initialization, and idempotent re-runs
+- Updated Story 9.2 test 9.2.12 from a placeholder "does not overwrite" assertion to the now-correct merge behavior assertion
+
+### File List
+- `lib/installer.js` — implemented file-present merge path in `updateAgentInstructions()` json-merge branch
+- `test/opencode-json-merge.test.js` — new test file with 10 Story 9.3 tests
+- `test/opencode-json-injection.test.js` — updated test 9.2.12 to reflect actual merge behavior

package/_bmad-output/implementation-artifacts/done/9-4-json-error-handling.md

@@ -0,0 +1,90 @@
+# Story 9.4: JSON Injection — Handle Invalid opencode.json Gracefully
+
+Status: review
+
+depends-on: 9-3-json-merge-existing
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As a **Chief Architect**,
+I want the installer to recover gracefully when opencode.json contains invalid JSON,
+So that a corrupt or hand-edited config file does not abort the entire install run and all other agents continue to be processed.
+
+## Acceptance Criteria
+
+1. **Given** an existing opencode.json that contains invalid JSON (i.e., `JSON.parse()` throws a `SyntaxError`), **When** the installer attempts injection for the OpenCode agent, **Then** a clear human-readable error message is logged to the console identifying the file path and the parse error, **And** the file is NOT modified (byte-identical to the original after the run), **And** the installer continues processing all remaining agents in the queue without re-throwing the error.
+
+## Tasks / Subtasks
+
+- [x] Wrap the `JSON.parse()` call in the `json-merge` branch with a `try/catch` block (AC: #1)
+  - [x] On `catch (err)`: log a clear error message including the file path and `err.message`, e.g.: `console.error(\`[ma-agents] ERROR: Could not parse ${filePath} — ${err.message}. File not modified.\`)`
+  - [x] On catch: `return` from the current iteration without writing anything to disk
+  - [x] Do NOT re-throw the error — the outer caller must continue processing subsequent agents
+- [x] Verify that the `return` on error exits only the current agent's instruction update, not the entire install loop (AC: #1)
+  - [x] Trace the call site of `updateAgentInstructions()` in installer.js to confirm the loop continues after a non-throwing return
+- [x] Write fixture-based unit test for the error path (AC: #1)
+  - [x] Fixture A: opencode.json containing `"not valid json {{{"` (corrupt file)
+  - [x] Assert: file content is byte-identical after the installer run (file NOT modified)
+  - [x] Assert: console.error was called with a message containing the file path and a description of the parse failure
+  - [x] Assert: the installer processes at least one additional agent after the OpenCode error (continuation verified)
+  - [x] Fixture B (continuation test): install list `[opencode, someOtherAgent]` where opencode.json is corrupt — assert `someOtherAgent`'s instruction file IS updated successfully
+
+## Dev Notes
+
+### Named Constant — CRITICAL
+Use the `MA_AGENTS_SOURCE` constant defined in Story 9.2. This story does not use `MA_AGENTS_SOURCE` directly in logic but must not introduce a new `'ma-agents'` string literal in any log messages (use the constant or a descriptive label):
+```js
+console.error(`[ma-agents] ERROR: Could not parse ${filePath} — ${err.message}. File not modified.`);
+```
+
+### Error Message Requirements
+The error message must include:
+1. The full file path (so the user can locate and fix the file)
+2. The parse error message from `err.message` (so the user knows what is wrong)
+3. A statement that the file was NOT modified (so the user does not think their data was lost)
+
+### Non-Fatal Contract
+`updateAgentInstructions()` must not throw for the parse-failure case. The caller iterates over agents; a thrown error would abort the loop. The `catch` block must log and `return`, never `throw`.
+
+### Continuation Test Importance
+AC #1 requires verifying that subsequent agents are processed. The test in Fixture B is the only way to confirm the non-fatal contract is actually honored — do not skip it. A missing continuation test means the "non-fatal" claim is unverified.
+
+### Architecture Compliance
+- NFR7: Read-validate-write — if validation (parse) fails, no write occurs. This story enforces the "validate" gate.
+- No new npm dependencies.
+
+### Critical Guardrails
+- Do NOT re-throw the caught error
+- Do NOT modify the file in the error path — not even to add a comment or a backup
+- Do NOT use bare string `'ma-agents'` in log messages if `MA_AGENTS_SOURCE` is in scope — use the constant
+- Do NOT modify the existing markdown injection code path
+
+### Project Structure Notes
+- Modify: `lib/installer.js` — add `try/catch` around `JSON.parse()` in the `json-merge` branch established by Stories 9.2 and 9.3
+- No new files created
+- Test fixtures: corrupt opencode.json; multi-agent install list with corrupt opencode as first agent
+
+### References
+- [Source: lib/installer.js#L110 — `updateAgentInstructions()` function]
+- [Source: Story 9.2 — `MA_AGENTS_SOURCE` constant and `json-merge` branch entry point]
+- [Source: Story 9.3 — merge path where `JSON.parse()` is called; this story wraps that call in try/catch]
+
+## Dev Agent Record
+
+### Agent Model Used
+claude-sonnet-4-6
+
+### Debug Log References
+None — implementation was straightforward with no unexpected issues.
+
+### Completion Notes List
+- Wrapped `JSON.parse(content)` and subsequent merge logic in a `try/catch` in the `json-merge` branch of `updateAgentInstructions()` in `lib/installer.js`
+- On `catch (err)`: logs `[ma-agents] ERROR: Could not parse ${filePath} — ${err.message}. File not modified.` and returns without any write
+- The catch block does NOT re-throw — the outer install loop continues processing remaining agents
+- All 6 new tests pass: 4 Fixture A tests (corrupt file unchanged, error logged with file path, error describes parse failure, no .tmp file left) and 2 Fixture B tests (continuation: subsequent markdown agent IS updated; non-fatal: no throw)
+
+### File List
+- `lib/installer.js` — added try/catch around JSON.parse in the json-merge file-present branch (lines 185-203)
+- `test/opencode-json-error.test.js` — new test file with 6 tests covering Fixture A (corrupt file) and Fixture B (continuation)

package/_bmad-output/implementation-artifacts/epic-11-12-shared-guardrails.md

@@ -0,0 +1,53 @@
+# Epic 11 & Epic 12 — Shared Guardrails
+
+All stories in Epic 11 and Epic 12 inherit the following guardrails. Individual story specs reference this file rather than repeating these rules verbatim.
+
+## Universal Constraints
+
+- Do NOT add any new npm dependencies
+- Do NOT modify `lib/installer.js`, `lib/agents.js`, or `bin/cli.js`
+- Do NOT modify any files under `_bmad/bmm/workflows/` or `_bmad/core/` — extensions go in `lib/bmad-extension/`
+- Do NOT place extension workflows anywhere other than `lib/bmad-extension/workflows/`
+
+## Data Authority Rules (Epic 12)
+
+| Concern | Authoritative Source | Read By |
+|---|---|---|
+| Sprint membership (which items are in which sprint) | `sprint-plan-{n}.yaml` | 12.2, 12.3, 12.4 |
+| User story execution status (not-started/in-progress/done) | `sprint-status.yaml` | 12.2, 12.4 |
+| Bug story metadata (type, severity, title) | `bug-{slug}.md` YAML frontmatter | 12.2, 12.4 |
+
+**Never write sprint assignments to sprint-status.yaml.** These are separate concerns.
+
+## Sprint Artifact Naming (Epic 12)
+
+- Sprint artifacts: `_bmad-output/implementation-artifacts/sprint-plan-{number}.yaml`
+- Sprint discovery glob: `sprint-plan-*.yaml` (never `sprint-*.yaml` — that pattern matches sprint-status.yaml)
+- Sprint artifacts include a `last_modified` ISO timestamp field, updated on every write
+
+## Bug Story File Contract (Epic 11 → Epic 12 integration)
+
+Bug stories created by `create-bug-story` (11.2) are discovered by sprint workflows (12.2, 12.4) via:
+
+1. Glob: `_bmad-output/implementation-artifacts/bug-*.md`
+2. YAML frontmatter parsing — required fields: `type: bug`, `severity`, `title`
+
+Bug stories are **not** tracked in sprint-status.yaml. They are peers to user stories in the flat backlog (FR65).
+
+## Extension Module Scaffolding Ownership
+
+Story **11.2** is the sole owner of:
+- `lib/bmad-extension/module.yaml`
+- `lib/bmad-extension/module-help.csv`
+
+Stories 12.1–12.4 depend on Story 11.2 having been completed. They verify scaffolding exists; they do not re-create it.
+
+## Story Implementation Order
+
+```
+11.1 → 11.2 → 11.3 (blocked until 11.1 + 11.2 done)
+             ↓
+           12.1 (depends on 11.2 scaffolding)
+             ↓
+           12.2 → 12.3 → 12.4
+```