ma-agents 3.4.9 → 3.5.1

package/_bmad-output/implementation-artifacts/19-7-llm-writability-validation-tests.md

@@ -0,0 +1,280 @@
+# Story 19.7: LLM-Writability Contract Validation and Integration Tests
+
+Status: ready-for-dev
+
+## Story
+
+As a **Chief Architect**,
+I want the knowledge graph JSON format validated against the LLM-writability contract and covered by integration tests,
+so that we can verify that any LLM can extend the graph by copying existing patterns, and that the additive-only semantics are enforced.
+
+## Acceptance Criteria
+
+1. **Given** a `knowledge-graph.json` file with one existing node and one existing edge
+   **When** an LLM is instructed to add a new node and a new edge by copying the existing patterns (no external schema provided)
+   **Then** the resulting JSON is valid and passes `emitToGraph()` ingestion without errors
+   **And** the existing node and edge are preserved unchanged (NFR40)
+
+2. **Given** `emitToGraph()` is called with a node id that already exists in `nodes`
+   **When** the function completes
+   **Then** `nodes` contains exactly one entry with that id (no duplicate)
+   **And** the original node's fields are unchanged (except `title` which may be updated)
+
+3. **Given** `emitToGraph()` is called with an edge `(from, to, type)` triple that already exists
+   **When** the function completes
+   **Then** `edges` contains exactly one entry with that triple (no duplicate)
+   **And** the original edge's provenance (created_by, agent) is unchanged
+
+4. **Given** a graph with 500 nodes and 1000 edges
+   **When** `emitToGraph()` adds one new node and one new edge
+   **Then** the operation completes in under 1 second
+
+5. **Given** the full emission sequence is run (all 7 skills emit in order)
+   **When** the resulting `knowledge-graph.json` is inspected
+   **Then** all emitted nodes are present
+   **And** all emitted edges are present with correct provenance
+   **And** `meta.file_count`, `meta.node_count`, `meta.edge_count` are accurate
+
+## Tasks / Subtasks
+
+### Task 1: Set up test directory structure (AC: 1–5)
+
+Story 19.7 integration tests follow the existing Node.js test runner pattern. Epic 7 (Test Suite) is on hold, so these tests use the existing Node.js test runner directly (no Jest, no Vitest — plain Node.js `assert` and test runner, or whichever lightweight pattern is already in use in the repo).
+
+- [ ] 1.1 Create directory `tests/knowledge-graph/`
+- [ ] 1.2 Create `tests/knowledge-graph/fixtures/` for test fixture files
+- [ ] 1.3 Check existing test files in the repo (e.g., `tests/` root) to identify the test runner pattern in use — do NOT introduce a new test framework; replicate the existing pattern exactly
+
+### Task 2: Test — additive-only semantics (AC: 1, 2, 3)
+
+- [ ] 2.1 Create `tests/knowledge-graph/emit.test.js`:
+  - **Test: first call creates valid structure**
+    - Use a temp directory; call `emitToGraph(tmpDir, minimalPayload)`
+    - Verify file is created, has `meta`, `files`, `nodes`, `edges` sections
+    - Verify `meta.node_count` and `meta.edge_count` match array lengths
+
+  - **Test: duplicate node is rejected (AC: 2)**
+    - Seed graph with node `{ id: "prd#test", ... }`
+    - Call `emitToGraph()` again with the same node id but different title
+    - Verify `nodes` has exactly 1 entry with that id
+    - Verify title is updated (expected behavior per Story 19.1: title updates are allowed)
+
+  - **Test: duplicate edge is rejected (AC: 3)**
+    - Seed graph with edge `{ from: "prd#a", to: "prd#b", type: "implements", created_by: "original", ... }`
+    - Call `emitToGraph()` again with same `(from, to, type)` but different `created_by`
+    - Verify `edges` has exactly 1 entry with that triple
+    - Verify `created_by` is unchanged (provenance preserved — only `created_at`/`agent` can update)
+
+  - **Test: existing entries preserved (AC: 1, 2, 3 — NFR40)**
+    - Seed graph with 3 nodes and 2 edges
+    - Call `emitToGraph()` with 2 new nodes and 1 new edge
+    - Verify total: 5 nodes, 3 edges
+    - Verify all original entries are byte-identical to their initial values
+
+### Task 3: Test — LLM-writability contract (AC: 1)
+
+- [ ] 3.1 Create `tests/knowledge-graph/fixtures/llm-seed.json` — a minimal valid `knowledge-graph.json` with exactly 1 node and 1 edge (following the exact schema structure from `architecture.md` Decision P3-1)
+- [ ] 3.2 Create `tests/knowledge-graph/llm-writability.test.js`:
+  - **Test: copy-pattern extension produces valid JSON**
+    - Load `fixtures/llm-seed.json`
+    - Programmatically "extend" it by copying the pattern (add a new node entry and new edge entry following the exact same field structure)
+    - Write the extended JSON back to a temp file
+    - Call `emitToGraph(tmpDir, emptyEmission)` on the extended file — verify no errors thrown
+    - Verify total node/edge counts are correct
+  - **Test: valid structure can be round-tripped**
+    - Read `fixtures/llm-seed.json`, parse, serialize as `JSON.stringify(graph, null, 2)`, parse again — verify no data loss
+
+### Task 4: Test — performance (AC: 4)
+
+- [ ] 4.1 Add to `tests/knowledge-graph/emit.test.js`:
+  - **Test: large graph performance**
+    - Generate a fixture graph with 500 nodes and 1000 edges programmatically (use a helper function, not a fixture file — 500-node JSON fixture would be large)
+    - Write to temp dir
+    - Measure time of `emitToGraph()` adding 1 node and 1 edge
+    - Assert elapsed < 1000ms (using `Date.now()` before/after)
+
+### Task 5: Test — full emission sequence (AC: 5)
+
+- [ ] 5.1 Create `tests/knowledge-graph/sequence.test.js`:
+  - **Test: sequential emission produces correct final graph**
+    - Simulate the 7-skill emission sequence using `emitToGraph()` directly (no actual skills invoked — just the payloads each skill would emit)
+    - Use representative payloads:
+      1. PRD seeding: 3 PRD nodes, 0 edges
+      2. Architecture: 2 arch nodes, 2 `implements` edges to PRD nodes
+      3. Epics: 2 epic nodes, 2 `derives-from` edges + 1 `informed-by` edge
+      4. Story: 1 story node, 1 `traces-to` edge + 1 `informed-by` edge
+      5. Validate-prd: 1 validation node, 1 `validates` edge
+      6. Dev-story: 1 `refines` edge (story → arch)
+      7. Sprint-planning: 1 sprint node, 1 `derives-from` edge
+    - Verify final graph:
+      - `meta.node_count == 9` (3+2+2+1+1)
+      - `meta.edge_count == 8` (2+3+2+1+1) (approximately — adjust to actual test payload)
+      - All emitted nodes present
+      - All emitted edges present with correct provenance fields
+
+### Task 6: Test — VSCode detection (AC — Story 19.5)
+
+- [ ] 6.1 Create `tests/knowledge-graph/vscode-detection.test.js`:
+  - **Test: VSCODE_PID env var triggers VSCode path**
+    - Set `process.env.VSCODE_PID = "12345"` before running detection logic
+    - Verify detection returns `true`
+    - Restore `process.env` after test
+  - **Test: TERM_PROGRAM=vscode triggers VSCode path**
+    - Set `process.env.TERM_PROGRAM = "vscode"`
+    - Verify detection returns `true`
+  - **Test: neither env var set returns false**
+    - Ensure both env vars are unset; verify detection returns `false`
+  - Extract detection logic from `lib/bmad-extension/skills/open-graph/SKILL.md` into a testable helper function `lib/bmad-extension/skills/open-graph/detect-env.js`
+
+## Dev Notes
+
+### CRITICAL: Test Framework — Use Existing Pattern
+
+Epic 7 (Test Suite Foundation) is on hold. Do NOT introduce Jest, Vitest, Mocha, or any new test framework. Check if any test files already exist in `tests/` and replicate their exact pattern.
+
+If no test infrastructure exists: use Node.js built-in `node:test` module (available from Node.js 18+) and `node:assert`. This requires no npm installation.
+
+Pattern to check first:
+- Look for any `*.test.js` files in the repo
+- Look for `test` script in `package.json`
+
+### Prerequisite: All of Stories 19.1–19.6 Must Be Complete
+
+This story validates the complete Epic 19 implementation. It depends on:
+- `lib/knowledge-graph/emit.js` (Story 19.1)
+- `lib/bmad-extension/skills/open-graph/` (Stories 19.5, 19.6)
+
+### Test Directory Convention
+
+Tests live in `tests/knowledge-graph/` following the expectation from the Epic 19 cross-epic notes. Temp directories for all file I/O in tests:
+```javascript
+import { mkdtempSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+let tmpDir;
+setup(() => { tmpDir = mkdtempSync(join(tmpdir(), 'kg-test-')); });
+teardown(() => { rmSync(tmpDir, { recursive: true, force: true }); });
+```
+
+### LLM-Writability Fixture (Task 3)
+
+The fixture `tests/knowledge-graph/fixtures/llm-seed.json` must be a minimal but complete example:
+```json
+{
+  "meta": {
+    "schema_version": "1.0",
+    "project": "test-project",
+    "generated_at": "2026-04-07T10:00:00Z",
+    "last_updated": "2026-04-07T10:00:00Z",
+    "file_count": 1,
+    "node_count": 1,
+    "edge_count": 1
+  },
+  "files": {
+    "prd": {
+      "pointer": "_bmad-output/planning-artifacts/prd.md",
+      "title": "Product Requirements Document",
+      "pointer_type": "relative_path"
+    }
+  },
+  "nodes": [
+    {
+      "id": "prd#functional-requirements",
+      "file": "prd",
+      "anchor": "functional-requirements",
+      "title": "Functional Requirements",
+      "type": "prd"
+    }
+  ],
+  "edges": [
+    {
+      "from": "arch#decision-test",
+      "to": "prd#functional-requirements",
+      "type": "implements",
+      "label": "implements requirement",
+      "created_by": "test-user",
+      "agent": "test-agent",
+      "created_at": "2026-04-07T10:00:00Z"
+    }
+  ]
+}
+```
+
+This fixture is intentionally minimal so that an LLM reading it has exactly one example to copy.
+
+### Performance Test Helper (Task 4)
+
+Generate the 500-node / 1000-edge test graph programmatically:
+```javascript
+function generateLargeGraph(nodeCount, edgeCount) {
+  const nodes = Array.from({ length: nodeCount }, (_, i) => ({
+    id: `prd#node-${i}`, file: 'prd', anchor: `node-${i}`, title: `Node ${i}`, type: 'prd'
+  }));
+  const edges = Array.from({ length: edgeCount }, (_, i) => ({
+    from: `prd#node-${i % nodeCount}`,
+    to: `prd#node-${(i + 1) % nodeCount}`,
+    type: 'implements',
+    label: `edge ${i}`,
+    created_by: 'test', agent: 'test', created_at: new Date().toISOString()
+  }));
+  // ... build and write graph to temp dir
+}
+```
+
+### `detect-env.js` Extraction (Task 6)
+
+The VSCode detection logic from SKILL.md should be extracted to a testable Node.js module:
+```javascript
+// lib/bmad-extension/skills/open-graph/detect-env.js
+function detectVSCode() {
+  return process.env.TERM_PROGRAM === 'vscode' || process.env.VSCODE_PID !== undefined;
+}
+module.exports = { detectVSCode };
+```
+
+This makes it importable by tests without executing the `execSync` open command.
+
+### File Structure Created by This Story
+
+```
+tests/
+└── knowledge-graph/
+    ├── fixtures/
+    │   └── llm-seed.json              ← NEW (LLM-writability test fixture)
+    ├── emit.test.js                   ← NEW (additive semantics + performance tests)
+    ├── llm-writability.test.js        ← NEW (copy-pattern extension tests)
+    ├── sequence.test.js               ← NEW (full emission sequence test)
+    └── vscode-detection.test.js       ← NEW (env var detection tests)
+
+lib/bmad-extension/skills/open-graph/
+└── detect-env.js                      ← NEW (extracted detection logic for testability)
+```
+
+### Project Structure Notes
+
+- No SKILL.md files modified by this story.
+- No new skills registered.
+- The `detect-env.js` extraction from Story 19.5's SKILL.md is a minor refactor to enable testability.
+- If no `tests/` directory exists, create it. Add a `test` script to `package.json` if one does not exist: `"test": "node --test tests/**/*.test.js"` (Node.js 18+ built-in runner).
+
+### References
+
+- Story 19.1: `_bmad-output/implementation-artifacts/19-1-knowledge-graph-core-library.md` — `emitToGraph()` behavior under test
+- Architecture LLM-writability contract: `_bmad-output/planning-artifacts/architecture.md#llm-writability-contract-nfr39`
+- Architecture additive-only semantics: `_bmad-output/planning-artifacts/architecture.md#nfr40-additive-only-emission`
+- Epics cross-epic notes on testing: `_bmad-output/planning-artifacts/epics.md#epic-19--cross-epic-notes`
+- NFRs: NFR39 (LLM-writability), NFR40 (additive-only)
+- FR: FR152 (no duplicates, provenance preservation)
+
+## Dev Agent Record
+
+### Agent Model Used
+
+_to be filled by dev agent_
+
+### Debug Log References
+
+### Completion Notes List
+
+### File List

package/_bmad-output/implementation-artifacts/4-1-vs-agent-registry-entry.md

@@ -0,0 +1,173 @@
+# Story 4.1: Visual Studio Agent Registry Entry
+
+Status: ready-for-dev
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As a **Chief Architect**,
+I want to understand how Visual Studio exposes AI agent configuration and add VS as a supported agent,
+So that engineers can install skills into Visual Studio's AI assistant.
+
+## Acceptance Criteria
+
+1. **Given** Visual Studio has GitHub Copilot integration
+   **When** the integration mechanism is investigated
+   **Then** a technical note is produced documenting:
+   - Where VS stores AI agent instructions (file paths, config directories)
+   - What format VS expects (markdown, JSON, YAML, or other)
+   - How VS Copilot Chat extensions handle custom instructions
+   - Whether `.vs/` directory, `.editorconfig`, or another mechanism is used
+   - Platform path differences (Windows-only or cross-platform VS Code distinction)
+
+2. **Given** the research is complete
+   **When** the findings are documented
+   **Then** a clear recommendation exists for the agent registry configuration object fields
+
+3. **Given** the VS agent configuration is understood
+   **When** a new agent object is added to `lib/agents.js`
+   **Then** it includes: name, category, platform paths, instruction file, and resource map
+   **And** no changes are needed to `installer.js` or other modules (NFR13)
+
+4. **Given** the VS agent is registered
+   **When** `npx ma-agents list --agents` is run
+   **Then** Visual Studio appears in the agent list
+
+5. **Given** a skill is installed targeting the VS agent
+   **When** the install completes
+   **Then** skill content is placed in the correct VS configuration directory
+   **And** the manifest tracks the VS agent installation
+
+> **Note:** AC #5 overlaps with Story 4-2 scope. Verify basic install here; detailed template resolution and multi-agent testing belongs in 4-2.
+
+## Tasks / Subtasks
+
+- [ ] Task 1: Research Visual Studio AI agent configuration (AC: #1, #2)
+  - [ ] 1.1: Investigate GitHub Copilot in Visual Studio (not VS Code) — how custom instructions are configured
+  - [ ] 1.2: Check for `.github/copilot/copilot.md` support in VS (this is the VS Code Copilot instruction file per `lib/agents.js:79` — does VS use the same mechanism?)
+  - [ ] 1.3: Investigate VS-specific paths: `.vs/` directory, `%APPDATA%/Microsoft/VisualStudio/`, or solution-level config
+  - [ ] 1.4: Check if VS supports `.editorconfig`-adjacent AI instruction files
+  - [ ] 1.5: Document findings in `_bmad-output/implementation-artifacts/vs-agent-research.md`
+  - [ ] 1.6: Produce recommendation for agent registry object fields matching the actual schema: `id`, `name`, `version`, `category`, `description`, `getProjectPath()`, `getGlobalPath()`, `fileExtension`, `template`, `instructionFiles[]`, and optionally `resourceMap`
+- [ ] Task 2: Add VS agent to registry (AC: #3, #4)
+  - [ ] 2.1: Add agent configuration object to the agents array in `lib/agents.js` (search: `const agents = [`)
+  - [ ] 2.2: Set `id`, `name`, `version`, `category` ("ide"), `description`, `fileExtension`, `template` based on research findings
+  - [ ] 2.3: Implement `getProjectPath()` and `getGlobalPath()` functions with platform-specific paths (follow pattern from existing agents — Windows/macOS/Linux branches using `os.platform()`)
+  - [ ] 2.4: Set `instructionFiles` array based on VS's instruction file path
+  - [ ] 2.5: Add `resourceMap` only if VS uses non-standard directory names (like Cline does at `agents.js:122-125`) — otherwise omit
+  - [ ] 2.6: Verify no changes needed to `installer.js` — the installer should pick up the new agent automatically (NFR13)
+  - [ ] 2.5: Run `npx ma-agents list --agents` — verify VS appears
+- [ ] Task 3: Test skill installation to VS agent (AC: #5)
+  - [ ] 3.1: Install a skill targeting the VS agent
+  - [ ] 3.2: Verify files are placed in the correct VS configuration directory
+  - [ ] 3.3: Verify manifest tracks the VS installation
+  - [ ] 3.4: Test on Windows (VS is primarily Windows — macOS VS for Mac is deprecated)
+
+## Dev Notes
+
+### Epic Scope Note
+
+This story combines Epic 4 Story 4.1 (research) and Story 4.2 (add to registry) from the epics file into a single story. The companion story 4-2 covers template format verification — a scope not defined in the original epics. This was an intentional consolidation: research without registry implementation is incomplete, and template verification is a natural second story.
+
+### Architecture Compliance
+
+- **Adding a new agent = adding one object to the registry array.** No installer code changes needed. This is the core extensibility model. [Source: architecture.md#Extensibility-Model, NFR13]
+- **Agent registry in `agents.js`:** Pure data + path functions. Each agent is a configuration object: name, category, platform paths, instruction file, resource map. [Source: architecture.md#Module-Boundaries]
+- **Platform path centralization:** All platform awareness lives in `agents.js`. The installer uses `agents.js` for path resolution and is format-agnostic. [Source: architecture.md#Enforcement-Guidelines]
+
+### Existing Agent Registry Pattern
+
+Follow the exact pattern of existing agents. Example from the `copilot` agent in `lib/agents.js:60-80` (closest to VS):
+
+```javascript
+{
+  id: 'copilot',
+  name: 'GitHub Copilot',
+  version: '1.0.0',
+  category: 'ide',
+  description: 'GitHub Copilot Agent Mode',
+  getProjectPath: () => path.join(process.cwd(), '.github', 'copilot', 'skills'),
+  getGlobalPath: () => {
+    const platform = os.platform();
+    if (platform === 'win32') {
+      return path.join(os.homedir(), 'AppData', 'Roaming', 'GitHub Copilot', 'skills');
+    } else if (platform === 'darwin') {
+      return path.join(os.homedir(), 'Library', 'Application Support', 'GitHub Copilot', 'skills');
+    } else {
+      return path.join(os.homedir(), '.config', 'github-copilot', 'skills');
+    }
+  },
+  fileExtension: '.md',
+  template: 'generic',
+  instructionFiles: ['.github/copilot/copilot.md']
+}
+```
+
+**Note:** Only `cline` has a `resourceMap` field (maps `references` → `docs`, `assets` → `templates`). All other agents omit it. Only add `resourceMap` for VS if research shows it uses non-standard directory names.
+
+The VS agent may use the same `.github/copilot/copilot.md` path if VS and VS Code share the same Copilot instruction mechanism. Research (Task 1) will determine this.
+
+### Research Priorities
+
+**Most likely outcome:** VS uses `.github/copilot/copilot.md` (same as VS Code Copilot — see `lib/agents.js:79`). In this case:
+- The existing `copilot` agent may already cover VS
+- Or VS may need a separate entry with the same paths but a different `id`/`name` for clarity
+- Check if VS has additional instruction files beyond what VS Code supports
+
+**Alternative outcomes:**
+- VS uses `.vs/` directory for AI instructions (solution-level)
+- VS uses `%APPDATA%` paths for user-level AI config
+- VS has its own instruction format (not markdown)
+
+### Windows-Only Consideration
+
+Visual Studio is Windows-only (macOS Visual Studio for Mac was discontinued in 2024). The agent registry entry should:
+- Set platform paths for Windows only (or gracefully skip on macOS/Linux)
+- Use Windows-style paths where needed (though `path.join()` handles this automatically)
+- Consider that the `copilot` agent already handles `.github/` paths cross-platform
+
+### Phase 2 Injection Strategy (NOT YET IMPLEMENTED)
+
+**Note:** `injectionStrategy` is a Phase 2 planned feature from architecture decision P2-1. It does NOT exist in the current codebase. When Phase 2 is implemented, the VS agent may gain:
+
+```javascript
+injectionStrategy: {
+  position: 'top',
+  skipPatterns: ['---']  // skip YAML frontmatter
+}
+```
+
+For this story, focus on the current agent schema fields only. The `injectionStrategy` will be added in a separate Phase 2 epic.
+
+### Critical Guardrails
+
+- **Only modify `lib/agents.js`** — no changes to installer.js, cli.js, or bmad.js [Source: architecture.md, NFR13]
+- **Use `path.join()` for all paths** [Source: architecture.md#Enforcement-Guidelines]
+- **No `process.platform` checks outside agents.js** — use `os.platform()` inside `getProjectPath()`/`getGlobalPath()` only [Source: architecture.md#Anti-Patterns]
+- **No new npm dependencies** [Source: architecture.md#Anti-Patterns]
+
+### Project Structure Notes
+
+- Files to modify: `lib/agents.js` (add agent entry)
+- Files to create: `_bmad-output/implementation-artifacts/vs-agent-research.md` (research findings)
+- No changes to installer, CLI, or BMAD modules
+
+### References
+
+- [Source: _bmad-output/planning-artifacts/epics.md#Epic-4] — Story 4.1 and 4.2 definitions
+- [Source: _bmad-output/planning-artifacts/prd.md#IDE-Agent-Integration-Model] — VS listed as gap
+- [Source: _bmad-output/planning-artifacts/architecture.md#Extensibility-Model] — Agent registry model (NFR13)
+- [Source: _bmad-output/planning-artifacts/architecture.md#Decision-P2-1] — Injection strategy pattern
+- [Source: _bmad-output/planning-artifacts/architecture.md#Module-Boundaries] — agents.js responsibility
+- [Source: lib/agents.js] — Current agent registry (11 agents: 7 IDE + 4 BMAD)
+
+## Dev Agent Record
+
+### Agent Model Used
+
+### Debug Log References
+
+### Completion Notes List
+
+### File List

package/_bmad-output/implementation-artifacts/4-2-vs-skill-template-format.md

@@ -0,0 +1,129 @@
+# Story 4.2: Visual Studio Skill Template Format
+
+Status: ready-for-dev
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+<!-- Dependency: Story 4-1 must be completed first (research findings determine this story's implementation) -->
+
+## Story
+
+As an **engineer**,
+I want skills to install correctly into Visual Studio with proper format translation,
+So that my VS AI assistant receives the same methodology content as other agents.
+
+## Acceptance Criteria
+
+1. **Given** a skill with no VS-specific template exists
+   **When** installed to the VS agent
+   **Then** the `SKILL.md` fallback content is used (standard template resolution chain)
+   **And** the content is valid for VS's expected format
+
+2. **Given** VS requires a format different from standard markdown
+   **When** a skill needs VS-specific content
+   **Then** a `visual-studio.md` (or format-appropriate) template can be added to the skill
+   **And** the template resolution chain picks it up automatically
+
+3. **Given** skills are installed to both VS and other agents simultaneously
+   **When** the install completes
+   **Then** each agent receives the correct format (VS-specific or fallback)
+   **And** the manifest tracks both installations independently
+
+4. **Given** the VS agent has resource mapping rules
+   **When** a skill with `references/` or `assets/` is installed
+   **Then** supporting files are mapped to the correct VS directories per the resource map
+
+## Tasks / Subtasks
+
+- [ ] Task 1: Determine VS template requirements (AC: #1, #2)
+  - [ ] 1.1: Based on Story 4-1 research, determine if VS needs a format different from standard markdown
+  - [ ] 1.2: If VS uses markdown (like most agents): no template format work needed — SKILL.md fallback works
+  - [ ] 1.3: If VS needs a different format: define the template transformation requirements
+  - [ ] 1.4: Determine the template filename: likely `visual-studio.md` matching the agent registry key
+- [ ] Task 2: Define resource mapping for VS (AC: #4)
+  - [ ] 2.1: Based on Story 4-1 research, determine where VS expects supporting files (references/, assets/)
+  - [ ] 2.2: **Only if VS uses non-standard directory names**: add `resourceMap` to the VS agent entry in `lib/agents.js`. Currently only `cline` has a resourceMap (maps `references` → `docs`, `assets` → `templates` at `agents.js:122-125`). Example:
+    ```javascript
+    resourceMap: {
+      'references': 'docs',
+      'assets': 'templates'
+    }
+    ```
+  - [ ] 2.3: If VS uses standard directory names (`references/`, `assets/`), **omit `resourceMap` entirely** — do not set to null/empty (follow pattern of the other 10 agents that have no resourceMap)
+- [ ] Task 3: Test template resolution for VS (AC: #1, #2, #3)
+  - [ ] 3.1: Install a skill WITHOUT a VS template — verify SKILL.md fallback works
+  - [ ] 3.2: If VS-specific template created: install a skill WITH a VS template — verify template is used
+  - [ ] 3.3: Install skills to VS + another agent simultaneously — verify both get correct content
+  - [ ] 3.4: Verify manifest tracks VS installations correctly
+- [ ] Task 4: Create VS-specific templates for critical skills (AC: #2) — if needed
+  - [ ] 4.1: If VS needs format-specific templates, create them for high-priority skills (e.g., `git-workflow-skill`, `code-documentation`)
+  - [ ] 4.2: If VS uses standard markdown, this task is a no-op — SKILL.md fallback is sufficient
+
+## Dev Notes
+
+### Epic Scope Note
+
+This story covers template format verification — a scope not in the original epics (which defined 4.2 as "Add Visual Studio Agent to Registry"). The registry addition is handled in Story 4-1. This story focuses on ensuring the template resolution chain works correctly for the VS agent.
+
+### Architecture Compliance
+
+- **Template resolution chain:** `templates/<agent-id>.md` -> `templates/generic.md` -> `SKILL.md`. The template filename must match the agent's `id` field in `agents.js` (e.g., if VS agent has `id: 'visual-studio'`, then template is `templates/visual-studio.md`). The `template` field on the agent config specifies which template to use as default (e.g., `template: 'generic'`). [Source: architecture.md#Extensibility-Model]
+- **Adding a new agent target must not require changes to existing skills** (NFR11). The SKILL.md fallback ensures all existing skills work with VS out of the box.
+- **Resource mapping** is optional per-agent in the registry. Only `cline` currently uses it. The installer reads resourceMap from agents.js if present and remaps directory names accordingly. [Source: architecture.md#Module-Boundaries, lib/agents.js:122-125]
+
+### Dependency on Story 4-1
+
+This story **cannot be implemented** until Story 4-1's research is complete. The research determines:
+1. Whether VS needs a different format (markdown vs JSON vs other)
+2. Where VS expects skill files (directory paths)
+3. How resources (references, assets) are mapped
+4. What the template filename should be
+
+**If VS uses `.github/copilot-instructions.md`** (same as VS Code Copilot):
+- This story is minimal — the existing `copilot` agent template format already works
+- Resource mapping may already be defined in the `copilot` agent entry
+- The main work is verifying the existing template chain works for VS
+
+**If VS has a unique configuration mechanism:**
+- Template format definition is needed
+- Resource mapping must be researched and configured
+- Some skills may need VS-specific templates
+
+### Most Likely Scenario
+
+VS Copilot likely shares the `.github/copilot-instructions.md` mechanism with VS Code. In this case:
+- All existing skills work via SKILL.md fallback (no VS templates needed)
+- Skills with `copilot.md` templates work for both VS and VS Code
+- This story becomes primarily a verification/testing story
+
+### Critical Guardrails
+
+- **Do not modify existing skills** unless VS genuinely needs a different format [Source: NFR11]
+- **Only modify `lib/agents.js`** for resource mapping updates [Source: architecture.md, NFR13]
+- **Use `path.join()` for all paths** [Source: architecture.md#Enforcement-Guidelines]
+- **No new npm dependencies** [Source: architecture.md#Anti-Patterns]
+
+### Project Structure Notes
+
+- Files to modify: `lib/agents.js` (resource map update for VS agent — may already be done in 4-1)
+- Files to create: VS-specific templates in individual skills ONLY if research shows VS needs them
+- No changes to installer logic, CLI, or BMAD modules
+
+### References
+
+- [Source: _bmad-output/planning-artifacts/epics.md#Epic-4] — Story 4.2 definition
+- [Source: _bmad-output/planning-artifacts/prd.md#IDE-Agent-Integration-Model] — Agent integration points table
+- [Source: _bmad-output/planning-artifacts/architecture.md#Extensibility-Model] — Template resolution priority chain
+- [Source: _bmad-output/planning-artifacts/architecture.md#Module-Boundaries] — agents.js resource mapping
+- [Source: _bmad-output/planning-artifacts/prd.md#NFR11] — New agents don't require changes to existing skills
+- [Source: lib/agents.js] — Agent registry with resource maps
+- [Source: _bmad-output/implementation-artifacts/4-1-vs-agent-registry-entry.md] — Prerequisite story
+
+## Dev Agent Record
+
+### Agent Model Used
+
+### Debug Log References
+
+### Completion Notes List
+
+### File List