ma-agents 3.5.0 → 3.5.2

package/_bmad-output/implementation-artifacts/19-3-graph-emission-create-architecture-epics.md

@@ -0,0 +1,179 @@
+# Story 19.3: Graph Emission — `create-architecture` and `create-epics-and-stories`
+
+Status: ready-for-dev
+
+## Story
+
+As a **Chief Architect** and **Product Manager**,
+I want the `create-architecture` and `create-epics-and-stories` skills to emit traceability edges to the knowledge graph automatically,
+so that every architectural decision and every epic traces back to the PRD sections that motivated it.
+
+## Acceptance Criteria
+
+1. **Given** the `create-architecture` skill completes generation of `_bmad-output/planning-artifacts/architecture.md`
+   **When** emission runs
+   **Then** the architecture file is registered as file-id `arch` with `pointer_type: "relative_path"`
+   **And** one node is emitted per `##` heading in architecture.md (type: `architecture`)
+   **And** for each architecture decision section (headings matching `## Decision` or `## P[0-9]` patterns), an `implements` edge is emitted: `{ from: "arch#<decision-slug>", to: "prd#relevant-fr-section", type: "implements", label: "implements PRD requirement", created_by: <user>, agent: <agent-id>, created_at: <timestamp> }`
+
+2. **Given** the `create-architecture` skill is run when PRD nodes do not yet exist in the graph
+   **When** an edge references a PRD node that is not yet in `nodes`
+   **Then** a stub node is emitted for the referenced PRD heading so the edge is not orphaned
+   **And** the stub node carries `type: "prd"` and the correct `file` and `anchor` fields
+
+3. **Given** the `create-epics-and-stories` skill completes updating `_bmad-output/planning-artifacts/epics.md`
+   **When** emission runs
+   **Then** the epics file is registered as file-id `epics` with `pointer_type: "relative_path"`
+   **And** one node is emitted per epic heading (type: `epic`) — headings matching `## Epic [0-9]+:` pattern
+   **And** for each epic, a `derives-from` edge is emitted to the PRD Functional Requirements node: `{ from: "epics#epic-N-name", to: "prd#functional-requirements", type: "derives-from", ... }`
+   **And** where an epic was informed by an architecture decision, an `informed-by` edge is also emitted: `{ from: "epics#epic-N-name", to: "arch#<decision-slug>", type: "informed-by", ... }`
+
+4. **Given** emission runs for `create-architecture` or `create-epics-and-stories`
+   **When** the same skill runs a second time (re-run)
+   **Then** all emissions are idempotent — no duplicate nodes or edges are added
+
+## Tasks / Subtasks
+
+### Task 1: Add emission to `create-architecture` (AC: 1, 2, 4)
+
+Both the IDE skill and BMAD extension skill must be updated (see Dev Notes on two pipelines).
+
+- [ ] 1.1 Locate: `skills/bmad-create-architecture/SKILL.md` and `lib/bmad-extension/skills/bmad-create-architecture/SKILL.md`
+- [ ] 1.2 Add final silent step after artifact write:
+  - Scan `architecture.md` for `## ` headings; derive anchors with `headingToAnchor()`
+  - Identify decision headings: match `^## Decision` or `^## P\d+-\d+` (e.g., `## P3-1: BMAD Knowledge Graph`)
+  - For each decision heading, infer the target PRD FR section. Strategy:
+    - If the decision section body contains explicit FR references (e.g., `FR141`), map to `prd#functional-requirements` (the broad FR section as the canonical target)
+    - If no explicit FR found, still emit to `prd#functional-requirements` as default
+  - Build emission: all architecture nodes + `implements` edges for decision nodes + stub PRD nodes if PRD nodes are absent
+- [ ] 1.3 Stub node format (when PRD node does not yet exist):
+  ```javascript
+  { id: "prd#functional-requirements", file: "prd", anchor: "functional-requirements", title: "Functional Requirements", type: "prd" }
+  ```
+- [ ] 1.4 Edge format for architecture decisions:
+  ```javascript
+  {
+    from: "arch#<decision-slug>",
+    to: "prd#functional-requirements",
+    type: "implements",
+    label: "implements PRD requirement",
+    created_by: "<user from config>",
+    agent: "bmad-create-architecture",
+    created_at: new Date().toISOString()
+  }
+  ```
+
+### Task 2: Add emission to `create-epics-and-stories` (AC: 3, 4)
+
+Both the IDE skill and BMAD extension skill must be updated.
+
+- [ ] 2.1 Locate: `skills/bmad-create-epics-and-stories/SKILL.md` and `lib/bmad-extension/skills/bmad-create-epics-and-stories/SKILL.md`
+- [ ] 2.2 Add final silent step after artifact write:
+  - Scan `epics.md` for epic headings matching `^## Epic [0-9]+:` pattern
+  - For each epic heading, derive anchor; emit node with `type: "epic"`
+  - Emit `derives-from` edge to `prd#functional-requirements` for each epic
+  - For epics that reference architecture decisions (scan epic body for `Decision P\d+-\d+` or `arch#` patterns), emit `informed-by` edges to the relevant `arch#<decision-slug>` node
+- [ ] 2.3 Edge formats:
+  ```javascript
+  // derives-from edge
+  { from: "epics#<epic-slug>", to: "prd#functional-requirements", type: "derives-from", label: "derives from PRD requirements", created_by: "<user>", agent: "bmad-create-epics-and-stories", created_at: <timestamp> }
+  // informed-by edge (only when architecture decision referenced in epic body)
+  { from: "epics#<epic-slug>", to: "arch#<decision-slug>", type: "informed-by", label: "informed by architecture decision", created_by: "<user>", agent: "bmad-create-epics-and-stories", created_at: <timestamp> }
+  ```
+
+### Task 3: Verify idempotency and stub node correctness (AC: 2, 4)
+
+- [ ] 3.1 Run emission twice; confirm node/edge counts are identical on both runs
+- [ ] 3.2 Verify stub PRD nodes created by this skill are accepted (not duplicated) when Story 19.2 later emits the real PRD nodes (they share the same `id`; `emitToGraph` deduplicates by id with title update allowed)
+
+## Dev Notes
+
+### CRITICAL: Two Deployment Pipelines
+
+Same constraint as Story 19.2. For each skill, update BOTH:
+1. `skills/<skill-name>/SKILL.md` — IDE source
+2. `lib/bmad-extension/skills/<skill-name>/SKILL.md` — BMAD extension source
+
+Do NOT edit installed copies.
+
+### Prerequisite: Story 19.1 Must Be Complete
+
+Requires `lib/knowledge-graph/emit.js`. Do not begin until Story 19.1 is done. Stories 19.2, 19.3, and 19.4 can proceed in parallel once 19.1 is done.
+
+### Decision Heading Detection
+
+The architecture document uses two patterns for decision headings:
+- `## Decision P3-1: BMAD Knowledge Graph` — matches `^## .*P\d+-\d+` or `^## Decision`
+- Both patterns should be detected for forward compatibility
+
+Current architecture decisions in the file:
+- `P2-1` through `P2-11`, `P3-1` — use pattern `## Decision P[0-9]+-[0-9]+:` or abbreviated `## P[0-9]+-[0-9]+:`
+
+Scan for both `^## Decision` and `^## P\d` to be safe.
+
+### Epic Heading Detection
+
+The epics file uses: `^## Epic [0-9]+:` (e.g., `## Epic 19: BMAD Knowledge Graph (Phase 3)`)
+
+For each matched heading, `headingToAnchor()` produces the node anchor:
+- `"Epic 19: BMAD Knowledge Graph (Phase 3)"` → `"epic-19-bmad-knowledge-graph-phase-3"`
+
+### Stub Nodes for Orphan Edge Prevention (AC: 2)
+
+When an `implements` or `informed-by` edge references a node that does not yet exist (e.g., PRD not yet emitted, or architecture not yet emitted), the emitting skill adds a stub node. The `emitToGraph()` function from Story 19.1 handles this naturally — just include the stub in the `nodes` array of the emission payload. If the real node is later emitted by its own skill, the `title` field is updated (Story 19.1 allows title updates on existing nodes).
+
+### `informed-by` Edge — The Non-Hierarchical Edge
+
+`informed-by` is the key non-hierarchical edge type. It records influence without asserting derivation or implementation. An epic can be simultaneously `derives-from` a PRD requirement AND `informed-by` an architecture decision — both edges are valid and coexist.
+
+Detection strategy for `informed-by` edges in epics:
+- Scan epic section body (from heading to next `##` heading) for architecture decision references
+- Patterns to match: `Decision P\d+-\d+`, `arch#`, or explicit architecture decision names
+
+### User Identity for Provenance
+
+Read `created_by` from BMAD config `_bmad/bmm/config.yaml` field `user_name`, or fall back to `"unknown"`. The `agent` field is a static string identifying the skill: `"bmad-create-architecture"` or `"bmad-create-epics-and-stories"`.
+
+### File Structure Reference
+
+```
+skills/
+├── bmad-create-architecture/
+│   └── SKILL.md    ← MODIFY
+└── bmad-create-epics-and-stories/
+    └── SKILL.md    ← MODIFY
+
+lib/bmad-extension/skills/
+├── bmad-create-architecture/
+│   └── SKILL.md    ← MODIFY
+└── bmad-create-epics-and-stories/
+    └── SKILL.md    ← MODIFY
+```
+
+No new files are created by this story.
+
+### Project Structure Notes
+
+- This story touches 4 SKILL.md files (2 skills × 2 pipelines).
+- No new skills, no new directories, no module-help.csv changes.
+- Emission logic added as a silent final step in each skill's workflow.
+
+### References
+
+- Story 19.1: `_bmad-output/implementation-artifacts/19-1-knowledge-graph-core-library.md`
+- Architecture Decision P3-1: `_bmad-output/planning-artifacts/architecture.md#decision-p3-1-bmad-knowledge-graph`
+- Skill emission table in architecture: architecture.md section "Skills that emit (and what they emit)"
+- FRs: FR149, FR150, FR151, FR152
+- Edge type vocabulary: `implements`, `derives-from`, `informed-by`
+
+## 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/19-4-graph-emission-create-story-remaining.md

@@ -0,0 +1,190 @@
+# Story 19.4: Graph Emission — `create-story`, `validate-prd`, `dev-story`, `bmad-sprint-planning`
+
+Status: ready-for-dev
+
+## Story
+
+As a **Developer** and **QA Engineer**,
+I want individual story files and validation artifacts to emit traceability edges automatically,
+so that the knowledge graph captures the full SDLC chain from PRD through architecture through epics through stories through implementation.
+
+## Acceptance Criteria
+
+1. **Given** the `create-story` skill generates a story file (e.g., `_bmad-output/implementation-artifacts/17-9-unified-sprint-status-schema.md`)
+   **When** emission runs
+   **Then** the story file is registered in the `files` table with `pointer_type: "relative_path"` and a file-id derived from the story number (e.g., `story-17-9`)
+   **And** a node is emitted for the story root heading (type: `story`)
+   **And** a `traces-to` edge is emitted from the story node to its parent epic node: `{ from: "story-<epic>-<num>#<story-slug>", to: "epics#epic-<N>-<name>", type: "traces-to", ... }`
+   **And** if the story's technical notes reference architecture decisions (e.g., `Decision P3-1`, `arch#`), `informed-by` edges are emitted from the story node to the relevant architecture nodes
+
+2. **Given** the `validate-prd` skill completes a validation report
+   **When** emission runs
+   **Then** the validation report file is registered with file-id `validation-<date>` (e.g., `validation-2026-04-07`)
+   **And** a `validates` edge is emitted from the validation report node to `prd#functional-requirements`: `{ type: "validates", label: "PRD validation report <date>", created_by: <user>, agent: "bmad-validate-prd", created_at: <timestamp> }`
+
+3. **Given** `dev-story` completes implementation guidance for a story
+   **When** emission runs
+   **Then** a `refines` edge is emitted from the story node to `arch#implementation-notes` (or the most relevant architecture section found by scanning the dev-story output)
+   **And** if no architecture section is identifiable, the edge target defaults to the story's own epic node
+
+4. **Given** `bmad-sprint-planning` completes sprint plan generation
+   **When** emission runs
+   **Then** sprint plan nodes are emitted with `type: "sprint"`
+   **And** `derives-from` edges connect sprint nodes to the relevant epic nodes referenced in the sprint plan
+
+5. **Given** any of the 4 skills runs a second time on the same project
+   **When** emission runs
+   **Then** all emissions are idempotent — no duplicate nodes or edges added
+
+## Tasks / Subtasks
+
+### Task 1: Add emission to `create-story` (AC: 1, 5)
+
+Both IDE skill and BMAD extension skill must be updated.
+
+- [ ] 1.1 Locate: `skills/bmad-create-story/SKILL.md` and `lib/bmad-extension/skills/bmad-create-story/SKILL.md`
+- [ ] 1.2 Add final silent step after story file write:
+  - Derive `storyFileId` from the story key: `story-<epic_num>-<story_num>` (e.g., `story-19-1`)
+  - Register story file in `files`: `{ pointer: "_bmad-output/implementation-artifacts/<filename>.md", title: "<story title>", pointer_type: "relative_path" }`
+  - Emit story root node: `{ id: "<storyFileId>#<story-heading-anchor>", file: "<storyFileId>", anchor: "<story-heading-anchor>", title: "<story title>", type: "story" }`
+  - Emit `traces-to` edge to parent epic node: `{ from: "<storyFileId>#<story-heading-anchor>", to: "epics#<epic-slug>", type: "traces-to", label: "implements epic", ... }`
+  - Scan story's Dev Notes section for `Decision P\d+-\d+` or `arch#` patterns; emit `informed-by` edges to matched architecture nodes
+- [ ] 1.3 Epic node slug derivation: scan `epics.md` for `## Epic <N>:` heading and apply `headingToAnchor()` to get the target anchor. Or construct `"epic-<N>-<name>"` from the epic title in the story key.
+
+### Task 2: Add emission to `validate-prd` (AC: 2, 5)
+
+- [ ] 2.1 Locate: `skills/bmad-validate-prd/SKILL.md` and `lib/bmad-extension/skills/bmad-validate-prd/SKILL.md`
+- [ ] 2.2 Add final silent step after validation report write:
+  - Derive date string from current date (ISO format, date portion only): e.g., `2026-04-07`
+  - File-id: `validation-<date>`
+  - Infer the validation report path from the skill's output path (typically `_bmad-output/planning-artifacts/validation-report-prd-<date>.md`)
+  - Emit `validates` edge: `{ from: "validation-<date>#validation-summary", to: "prd#functional-requirements", type: "validates", label: "PRD validation report <date>", created_by: <user>, agent: "bmad-validate-prd", created_at: <timestamp> }`
+
+### Task 3: Add emission to `dev-story` (AC: 3, 5)
+
+- [ ] 3.1 Locate: `skills/bmad-dev-story/SKILL.md` and `lib/bmad-extension/skills/bmad-dev-story/SKILL.md`
+- [ ] 3.2 Add final silent step after dev notes written:
+  - Identify the story being worked on (story key from context)
+  - The story node should already exist in the graph from `create-story` (Story 19.1 step). Re-emit is safe (idempotent).
+  - Scan the dev-story output for architecture section references; prefer the most specific match
+  - Emit `refines` edge: `{ from: "<storyFileId>#<story-heading-anchor>", to: "arch#<best-arch-section>", type: "refines", label: "dev implementation of story", created_by: <user>, agent: "bmad-dev-story", created_at: <timestamp> }`
+  - If no architecture section identifiable, use the epic node as fallback target
+
+### Task 4: Add emission to `bmad-sprint-planning` (AC: 4, 5)
+
+- [ ] 4.1 Locate: `skills/bmad-sprint-planning/SKILL.md` and `lib/bmad-extension/skills/bmad-sprint-planning/SKILL.md`
+- [ ] 4.2 Add final silent step after sprint plan output:
+  - Sprint plan file-id: `sprint-plan-<sprint-number>` (e.g., `sprint-plan-1`)
+  - Emit sprint plan node: `{ id: "sprint-plan-<N>#sprint-plan", file: "sprint-plan-<N>", anchor: "sprint-plan", title: "Sprint <N> Plan", type: "sprint" }`
+  - For each epic referenced in the sprint plan, emit `derives-from` edge: `{ from: "sprint-plan-<N>#sprint-plan", to: "epics#<epic-slug>", type: "derives-from", label: "sprint covers epic", ... }`
+
+### Task 5: Verify all 4 skills emit correctly (AC: 1–5)
+
+- [ ] 5.1 Trace through a full emission sequence: create-prd → create-architecture → create-epics-and-stories → create-story → validate-prd → dev-story → bmad-sprint-planning
+- [ ] 5.2 Verify the resulting `knowledge-graph.json` has no duplicate nodes or edges
+- [ ] 5.3 Verify `meta` counts match actual array/object sizes
+
+## Dev Notes
+
+### CRITICAL: Two Deployment Pipelines (Same Pattern as 19.2, 19.3)
+
+For each of the 4 skills, update BOTH:
+1. `skills/<skill-name>/SKILL.md` — IDE source
+2. `lib/bmad-extension/skills/<skill-name>/SKILL.md` — BMAD extension source
+
+Do NOT edit installed copies at `.claude/skills/` or `_bmad/extensions/ma-agents-skills/skills/`.
+
+### Prerequisite: Story 19.1 Must Be Complete
+
+Stories 19.2, 19.3, and 19.4 can proceed in parallel once 19.1 is done. This story does NOT depend on 19.2 or 19.3 completing first — they all independently wire in to the same `emitToGraph()` utility.
+
+### The 7 Emitting Skills — Full Inventory
+
+| Skill | Story | Edge Types Emitted |
+|-------|-------|--------------------|
+| `bmad-create-prd` | 19.2 | (none — seeds nodes only) |
+| `bmad-create-architecture` | 19.3 | `implements` |
+| `bmad-create-epics-and-stories` | 19.3 | `derives-from`, `informed-by` |
+| `bmad-create-story` | **19.4** | `traces-to`, `informed-by` |
+| `bmad-validate-prd` | **19.4** | `validates` |
+| `bmad-dev-story` | **19.4** | `refines` |
+| `bmad-sprint-planning` | **19.4** | `derives-from` |
+
+### Story File-ID Convention
+
+File-id format: `story-<epic_num>-<story_num>`
+- Story key `19-1-knowledge-graph-core-library` → file-id `story-19-1`
+- Story key `17-9-unified-sprint-status-schema` → file-id `story-17-9`
+
+This is derived directly from the story file path: `_bmad-output/implementation-artifacts/<epic_num>-<story_num>-*.md`
+
+### Story Heading Anchor
+
+The story root heading is `# Story <epic>.<story_num>: <title>`. Apply `headingToAnchor()`:
+- `"Story 19.1: Knowledge Graph Core Library (emitToGraph)"` → `"story-191-knowledge-graph-core-library-emittograph"`
+
+Use the file-id as the node's `file` field, not `story`.
+
+### Epic Slug Lookup
+
+To construct the `traces-to` edge target `"epics#<epic-slug>"`, apply `headingToAnchor()` to the epic heading from `epics.md` (e.g., `"Epic 19: BMAD Knowledge Graph (Phase 3)"` → `"epic-19-bmad-knowledge-graph-phase-3"`).
+
+The story's epic number is known from its story key (first number). Scan `epics.md` for `## Epic <N>:` to find the exact heading text and derive the anchor.
+
+### Validation Report File Path
+
+The `validate-prd` skill outputs files like `_bmad-output/planning-artifacts/validation-report-prd-<date>.md`. The file-id `validation-<date>` is derived from the output path. Anchor for the validation node: `headingToAnchor("Validation Summary")` → `"validation-summary"` (or the actual first `##` heading in the report).
+
+### `refines` Edge for dev-story
+
+The `refines` edge captures that a dev-story execution added implementation guidance to the story's context. The source is the story node (already exists from `create-story` emission). The target is the most relevant architecture section. If none found, use the epic node as fallback.
+
+### Sprint Plan Node Registration
+
+`bmad-sprint-planning` does not write a persistent sprint plan file in the current architecture (it writes to `sprint-status.yaml`). For graph emission, use `sprint-status.yaml` as the sprint plan file:
+- File-id: `sprint-status`
+- Pointer: `_bmad-output/implementation-artifacts/sprint-status.yaml`
+- Emit one `sprint` node per sprint entry found in `sprint-status.yaml`
+- Emit `derives-from` edges for epics covered by active/current sprint
+
+### Error Handling
+
+Same as Stories 19.2/19.3: wrap all `emitToGraph()` calls in try/catch. Emission failures are non-critical — log to stderr, do not abort the skill or show error to user.
+
+### File Structure Reference
+
+```
+skills/
+├── bmad-create-story/SKILL.md          ← MODIFY
+├── bmad-validate-prd/SKILL.md          ← MODIFY
+├── bmad-dev-story/SKILL.md             ← MODIFY
+└── bmad-sprint-planning/SKILL.md       ← MODIFY
+
+lib/bmad-extension/skills/
+├── bmad-create-story/SKILL.md          ← MODIFY
+├── bmad-validate-prd/SKILL.md          ← MODIFY
+├── bmad-dev-story/SKILL.md             ← MODIFY
+└── bmad-sprint-planning/SKILL.md       ← MODIFY
+```
+
+No new files created (8 existing SKILL.md files modified).
+
+### References
+
+- Story 19.1: `_bmad-output/implementation-artifacts/19-1-knowledge-graph-core-library.md`
+- Architecture skill emission table: `_bmad-output/planning-artifacts/architecture.md#skills-that-emit-and-what-they-emit`
+- Architecture Decision P3-1: `_bmad-output/planning-artifacts/architecture.md#decision-p3-1-bmad-knowledge-graph`
+- Epic 19 cross-epic notes: `_bmad-output/planning-artifacts/epics.md#epic-19--cross-epic-notes`
+- FRs: FR149, FR150, FR151, FR152
+
+## 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/19-5-open-graph-skill.md

@@ -0,0 +1,213 @@
+# Story 19.5: `open-graph` Skill
+
+Status: ready-for-dev
+
+## Story
+
+As an **Engineer**,
+I want to run `/open-graph` in any BMAD agent,
+so that the knowledge graph visualization opens in VSCode (as a webview) or in my default browser when outside VSCode — without any additional configuration.
+
+## Acceptance Criteria
+
+1. **Given** `open-graph` is invoked inside VSCode (detected via `process.env.TERM_PROGRAM === 'vscode'` or `process.env.VSCODE_PID !== undefined`)
+   **When** the skill runs
+   **Then** it generates `_bmad-output/knowledge-graph.html` (if not already current) from the JSON data
+   **And** opens the HTML file using `code "<htmlPath>"` command (opens in VSCode Simple Browser / Live Preview)
+
+2. **Given** `open-graph` is invoked outside VSCode (standard terminal)
+   **When** the skill runs
+   **Then** it generates `knowledge-graph.html` from the current JSON data
+   **And** opens it using the platform-appropriate command: `start` (Windows), `open` (macOS), `xdg-open` (Linux)
+
+3. **Given** `_bmad-output/knowledge-graph.json` does not exist
+   **When** `open-graph` is invoked
+   **Then** the skill informs the user that no knowledge graph data has been generated yet
+   **And** suggests running a BMAD planning skill (e.g., `create-prd`) to seed the graph
+
+4. **Given** `knowledge-graph.html` already exists and is newer than `knowledge-graph.json`
+   **When** `open-graph` is invoked
+   **Then** the skill skips regeneration and opens the existing HTML directly
+
+5. **Given** `open-graph` is invoked from a BMAD agent
+   **When** it runs
+   **Then** it is available as an `anytime` phase skill (not restricted to a specific workflow phase)
+   **And** it appears in the BMAD module help output
+
+## Tasks / Subtasks
+
+### Task 1: Create BMAD extension skill directory and files (AC: 1, 2, 3, 4, 5)
+
+- [ ] 1.1 Create directory: `lib/bmad-extension/skills/open-graph/`
+- [ ] 1.2 Create `lib/bmad-extension/skills/open-graph/bmad-skill-manifest.yaml`:
+  ```yaml
+  type: skill
+  name: open-graph
+  module: ma-skills
+  ```
+- [ ] 1.3 Create `lib/bmad-extension/skills/open-graph/SKILL.md` with the complete skill workflow (see Task 3)
+- [ ] 1.4 Register in `lib/bmad-extension/module-help.csv` — add row:
+  ```
+  ma-skills,anytime,Open Knowledge Graph,open-graph,,skill:open-graph,open-graph,false,,,Open the BMAD knowledge graph visualization in VSCode or browser.,_bmad-output,knowledge-graph.json,
+  ```
+
+### Task 2: Create the IDE skill source files (AC: 1, 2, 3, 4)
+
+- [ ] 2.1 Create `skills/open-graph/skill.json`:
+  ```json
+  {
+    "name": "open-graph",
+    "version": "1.0.0",
+    "description": "Open the BMAD knowledge graph visualization in VSCode or default browser",
+    "category": "workflow",
+    "tags": ["knowledge-graph", "visualization", "graph"]
+  }
+  ```
+  Note: `always_load: false` — on-demand skill, not loaded for every task.
+- [ ] 2.2 Create `skills/open-graph/SKILL.md` with the same core workflow as the BMAD extension version (may have minor phrasing differences for IDE context; logic must be identical)
+
+### Task 3: Implement `SKILL.md` workflow content (AC: 1, 2, 3, 4)
+
+Both SKILL.md files must implement the following logic:
+
+- [ ] 3.1 **Step 1 — Locate graph data:**
+  - Resolve `graphJsonPath = <projectRoot>/_bmad-output/knowledge-graph.json`
+  - If file does not exist: output `"No knowledge graph data found. Run a BMAD planning skill (e.g., create-prd, create-architecture) to generate the graph first."` and exit (AC: 3)
+
+- [ ] 3.2 **Step 2 — Check if regeneration needed:**
+  - Resolve `graphHtmlPath = <projectRoot>/_bmad-output/knowledge-graph.html`
+  - Compare mtime of `knowledge-graph.html` vs `knowledge-graph.json`:
+    - If HTML exists AND `html.mtime > json.mtime`: skip regeneration, proceed to Step 3 (AC: 4)
+    - Otherwise: call `generate-html.js` to regenerate HTML from JSON
+
+- [ ] 3.3 **Step 3 — Generate HTML (if needed):**
+  - Run `node lib/bmad-extension/skills/open-graph/generate-html.js <graphJsonPath> <graphHtmlPath>`
+  - (The `generate-html.js` script is created in Story 19.6 — this story creates a placeholder that outputs a basic diagnostic page)
+
+- [ ] 3.4 **Step 4 — Open in appropriate viewer:**
+  ```javascript
+  const isVSCode = process.env.TERM_PROGRAM === 'vscode' || process.env.VSCODE_PID !== undefined;
+  if (isVSCode) {
+    execSync(`code "${htmlPath}"`);  // opens in VSCode Simple Browser / Live Preview
+  } else {
+    const openCmd = process.platform === 'win32' ? 'start' :
+                    process.platform === 'darwin' ? 'open' : 'xdg-open';
+    execSync(`${openCmd} "${htmlPath}"`);
+  }
+  ```
+
+### Task 4: Create `generate-html.js` placeholder (AC: 1, 2 — basic version)
+
+Story 19.6 implements the full renderer. This story creates a functional placeholder so the skill works end-to-end:
+
+- [ ] 4.1 Create `lib/bmad-extension/skills/open-graph/generate-html.js` as a Node.js script that:
+  - Accepts arguments: `node generate-html.js <jsonPath> <htmlPath>`
+  - Reads `knowledge-graph.json`
+  - Writes a minimal HTML page that displays `meta.node_count`, `meta.edge_count`, and a `<pre>` dump of the JSON data
+  - This placeholder will be replaced by the full renderer in Story 19.6
+
+### Task 5: Verify deployment pipeline integration (AC: 5)
+
+- [ ] 5.1 Run `npx ma-agents` (or `node lib/cli.js`) to trigger the installer
+- [ ] 5.2 Verify IDE skill appears in installed MANIFEST.yaml (e.g., `.claude/skills/MANIFEST.yaml` includes `open-graph`)
+- [ ] 5.3 Verify BMAD extension copy exists at `_bmad/extensions/ma-agents-skills/skills/open-graph/` after BMAD install
+- [ ] 5.4 Verify `open-graph` appears in the BMAD module help output (`anytime` phase)
+
+## Dev Notes
+
+### CRITICAL: Two Deployment Pipelines
+
+This story creates files in BOTH pipelines:
+1. **IDE skill source:** `skills/open-graph/skill.json` + `skills/open-graph/SKILL.md`
+   - Deployed by `lib/installer.js` to all agent directories
+2. **BMAD extension skill source:** `lib/bmad-extension/skills/open-graph/SKILL.md` + `bmad-skill-manifest.yaml`
+   - Deployed by `lib/bmad.js` to `_bmad/extensions/ma-agents-skills/`
+
+**Reference skill for IDE pipeline:** `skills/story-status-lookup/` (working `skill.json` + `SKILL.md`)
+**Reference skill for BMAD extension:** `lib/bmad-extension/skills/add-to-sprint/` (working `SKILL.md` + `bmad-skill-manifest.yaml`)
+
+### Prerequisite: Story 19.1 Must Be Complete (for `generate-html.js`)
+
+This story creates a `generate-html.js` placeholder (Task 4) that becomes the integration point for Story 19.6. The `generate-html.js` interface must be stable: `node generate-html.js <jsonPath> <htmlPath>`.
+
+### VSCode Detection Logic (Architecture-Authoritative)
+
+```javascript
+const isVSCode = process.env.TERM_PROGRAM === 'vscode' || process.env.VSCODE_PID !== undefined;
+if (isVSCode) {
+  execSync(`code "${htmlPath}"`);
+} else {
+  const openCmd = process.platform === 'win32' ? 'start' :
+                  process.platform === 'darwin' ? 'open' : 'xdg-open';
+  execSync(`${openCmd} "${htmlPath}"`);
+}
+```
+
+This exact pattern is specified in architecture Decision P3-1. Do NOT use a different detection mechanism.
+
+### Skill Count Impact
+
+This story increases the BMAD extension module skill count from 44 to 45. The `module-help.csv` row must use phase `anytime` (not a specific workflow phase). Verify the final count in `lib/bmad-extension/module-help.csv` after adding the row.
+
+### `generate-html.js` Interface Contract
+
+The interface between SKILL.md and `generate-html.js` is:
+```
+node lib/bmad-extension/skills/open-graph/generate-html.js <jsonPath> <htmlPath>
+```
+
+Arguments:
+- `<jsonPath>`: absolute path to `knowledge-graph.json`
+- `<htmlPath>`: absolute path where `knowledge-graph.html` should be written
+
+Story 19.6 replaces the placeholder with the full interactive renderer, keeping the same interface.
+
+### `always_load: false`
+
+This is an on-demand skill. The `skill.json` must NOT include `always_load: true`. Omitting the key defaults to `false`.
+
+### File Structure Created by This Story
+
+```
+skills/
+└── open-graph/
+    ├── skill.json                 ← NEW
+    └── SKILL.md                   ← NEW
+
+lib/
+└── bmad-extension/
+    └── skills/
+        └── open-graph/
+            ├── SKILL.md           ← NEW
+            ├── bmad-skill-manifest.yaml  ← NEW
+            └── generate-html.js   ← NEW (placeholder; replaced by Story 19.6)
+```
+
+**Modified:**
+- `lib/bmad-extension/module-help.csv` ← add `open-graph` row
+
+### Project Structure Notes
+
+- Skill location `lib/bmad-extension/skills/open-graph/` follows the same pattern as all other extension skills (e.g., `lib/bmad-extension/skills/add-to-sprint/`)
+- Epic 19 cross-epic notes: `open-graph` skill requires Epic 15 (BMAD 6.2.1 module structure) to be complete. Epic 15 is done as of this writing.
+
+### References
+
+- Architecture Decision P3-1 — Layer 3: `_bmad-output/planning-artifacts/architecture.md#layer-3-open-graph-skill-and-renderer`
+- Reference IDE skill: `skills/story-status-lookup/`
+- Reference BMAD extension skill: `lib/bmad-extension/skills/add-to-sprint/`
+- `lib/bmad-extension/module-help.csv` — for phase registration pattern
+- FR: FR153 (open-graph skill, VSCode/browser detection)
+- Story 19.6: `_bmad-output/implementation-artifacts/19-6-interactive-visualization-renderer.md` — replaces `generate-html.js` placeholder
+
+## Dev Agent Record
+
+### Agent Model Used
+
+_to be filled by dev agent_
+
+### Debug Log References
+
+### Completion Notes List
+
+### File List