ma-agents 3.6.2 → 3.9.0

package/_bmad-output/implementation-artifacts/done/17-8-rework-sprint-status-display.md

@@ -1,285 +0,0 @@
-# Story 17.8: Rework Sprint Status Display
-
-Status: review
-
-<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
-
-## Story
-
-As a **Project Manager**,
-I want sprint status to show real sprint definitions with their assigned items and capacity usage,
-So that I can see at a glance what's in each sprint and how much capacity remains.
-
-## Acceptance Criteria
-
-1. **Given** the sprint-status workflow is invoked,
-   **When** the status is displayed,
-   **Then** it shows:
-   ```
-   Sprint 3 (active) — 4/6 items
-     * 5-5-explicit-parameter-passing [story] — in-progress
-     * 5-6-fix-space-in-path-bug [story] — backlog
-     * BUG-path-spaces [bug, high] — ready-for-dev
-     * 15-1-bump-bmad-method [story] — backlog
-
-   Backlog — 12 unassigned items
-     1. 15-2-restructure-extension-module [story]
-     2. 15-3-convert-custom-agents [story]
-     ...
-   ```
-
-2. **Given** done items have been cleaned up (Story 17.6),
-   **When** the sprint status is viewed,
-   **Then** done items do NOT appear in the sprint or backlog sections,
-   **And** a summary line shows: "X items completed this sprint".
-
-3. **Given** the `sprint-status.yaml` file is generated,
-   **When** it is written,
-   **Then** it only contains non-done items in `development_status`,
-   **And** sprint metadata is included in the header comments.
-
-## Tasks / Subtasks
-
-- [x] Task 1: Rework sprint-status-view SKILL.md (AC: #1, #2)
-  - [x] 1.1: Rewrite `lib/bmad-extension/skills/sprint-status-view/SKILL.md` — replace the entire workflow with the new model. The current workflow reads from `sprint-plan-*.yaml` and `sprint-status.yaml` — the new version reads from `sprints/sprint-*.yaml`, `backlog.yaml`, and `bug-*.md`.
-  - [x] 1.2: Update YAML frontmatter (keep existing triggers: "sprint status view", "view sprint status")
-  - [x] 1.3: Implement new workflow steps:
-
-    **Step 1: Run cleanup pre-step**
-    - Suggest: "Consider running `/cleanup-done` first to archive completed items."
-    - Do NOT auto-invoke cleanup — just advise
-
-    **Step 2: Load all data sources**
-    - Glob `_bmad-output/implementation-artifacts/sprints/sprint-*.yaml` for sprint definitions
-    - Read `_bmad-output/implementation-artifacts/backlog.yaml` for item details and priorities
-    - Glob `_bmad-output/implementation-artifacts/bug-*.md` for bug metadata (fallback if not in backlog)
-    - Read `_bmad-output/implementation-artifacts/sprint-status.yaml` for story status (fallback if not in backlog)
-    - If no sprint files AND no backlog: display "No sprint data found. Run `/add-sprint` and `/generate-backlog` first." and exit
-
-    **Step 3: Display each sprint (AC: #1)**
-    - Sort sprints: `active` first, then `planning`, then `closed`
-    - For each non-closed sprint:
-      - Display sprint header: `{name} ({status}) — {items_count}/{capacity} items`
-      - Display start/end dates if present
-      - For each item in sprint `items` array:
-        - Look up item in backlog.yaml for title, type, status, severity
-        - If item not in backlog (data inconsistency): show raw ID with warning
-        - Display with type tag: `[story]` or `[bug, {severity}]`
-        - Display current status
-      - Show capacity bar: `Capacity: {used}/{total} ({remaining} remaining)`
-      - If over capacity: show warning
-    - For closed sprints: show collapsed summary only — "{name} (closed) — {completed_count} items completed"
-
-    **Step 4: Display completed items summary (AC: #2)**
-    - Count items that are in sprint files but have status `done` (not yet cleaned up)
-    - Count items in `done/` directory that were in this sprint (historical — may not be trackable if already archived)
-    - Display: "Completed this sprint: {count} items" per active/planning sprint
-    - If items with `done` status still exist in sprint files: display "Run `/cleanup-done` to archive {count} completed items"
-
-    **Step 5: Display unassigned backlog (AC: #1)**
-    - From backlog.yaml, filter items where `sprint` is `null`
-    - Sort by priority ascending
-    - Display: "Backlog — {count} unassigned items"
-    - Show top 15 items with: Priority, ID, Title, Type, Status, Severity (for bugs)
-    - If more than 15: show "... and {remaining} more items"
-
-    **Step 6: Offer next actions**
-    - Options:
-      1. Show full unassigned backlog
-      2. Assign items to sprint — `/add-to-sprint`
-      3. Remove items from sprint — `/remove-from-sprint`
-      4. Reprioritize backlog — `/prioritize-backlog`
-      5. Create new sprint — `/add-sprint`
-      6. Archive done items — `/cleanup-done`
-      7. Exit
-
-- [x] Task 2: Rework sprint-status.yaml generation (AC: #3)
-  - [x] 2.1: Add a new step to the sprint-status-view SKILL.md (or create a separate internal protocol) that regenerates `sprint-status.yaml` from the current data sources:
-    - Read `backlog.yaml` for all items with their current statuses
-    - Read `sprints/sprint-*.yaml` for sprint membership
-    - Generate `development_status` section containing ONLY non-done items
-    - Preserve epic keys and retrospective keys from the existing file
-    - Include sprint metadata in header comments:
-      ```yaml
-      # Sprint Status — derived from backlog.yaml + sprint files
-      # Generated: {ISO timestamp}
-      # Active sprint: sprint-{id} ({name})
-      # Backlog items: {count}
-      ```
-    - Write to `sprint-status.yaml`, preserving STATUS DEFINITIONS comment block
-  - [x] 2.2: The regeneration should happen at the END of the sprint-status-view workflow (after display), so the YAML file reflects what was just shown
-  - [x] 2.3: Sprint-status.yaml is now officially a **derived file** — this story makes it generated, not manually maintained
-
-- [x] Task 3: Update sprint-status-template.yaml (AC: #3)
-  - [x] 3.1: Update `_bmad/bmm/4-implementation/bmad-sprint-planning/sprint-status-template.yaml` to include a note that sprint-status.yaml is now derived
-  - [x] 3.2: **Wait** — do NOT modify bmm core files. Instead, document in guardrails that the template is superseded by the generation logic in sprint-status-view
-
-- [x] Task 4: Update module-help.csv (AC: #1)
-  - [x] 4.1: Update the `sprint-status-view` row in `lib/bmad-extension/module-help.csv`:
-    - Update `description` to: "View sprint status with capacity, items, and backlog. Regenerates sprint-status.yaml."
-
-- [x] Task 5: Sync or remove legacy workflow.md
-  - [x] 5.1: `lib/bmad-extension/workflows/sprint-status-view/workflow.md` is a legacy copy. Either:
-    - Delete it if SKILL.md is the sole source of truth
-    - Or add a redirect note
-
-- [x] Task 6: Update guardrails (AC: #3)
-  - [x] 6.1: Add to `sprint-management-guardrails.md`:
-    - Sprint-Status.yaml Derivation section: document that it's now generated from backlog.yaml + sprint files
-    - Document that manual edits to sprint-status.yaml will be overwritten on next generation
-    - Document the generation trigger: `/sprint-status-view` regenerates the file after display
-
-- [x] Task 7: Verify (AC: #1, #2, #3)
-  - [x] 7.1: Verify sprint display reads from `sprints/sprint-*.yaml` and `backlog.yaml` (not `sprint-plan-*.yaml`)
-  - [x] 7.2: Verify done items do NOT appear in sprint or backlog display sections
-  - [x] 7.3: Verify completed items summary count is shown
-  - [x] 7.4: Verify sprint-status.yaml is regenerated with only non-done items
-  - [x] 7.5: Verify STATUS DEFINITIONS comment block is preserved in generated sprint-status.yaml
-  - [x] 7.6: Verify sprint metadata is in header comments
-  - [x] 7.7: Verify unassigned backlog shows items sorted by priority
-  - [x] 7.8: Verify closed sprints show collapsed summary only
-
-## Dev Notes
-
-### Architecture Compliance
-
-- **SKILL.md is the authoritative file:** `lib/bmad-extension/skills/sprint-status-view/SKILL.md` is resolved by `skill:sprint-status-view`
-- **Extension module pattern:** Modifications stay in `lib/bmad-extension/skills/sprint-status-view/`
-- **Derived file pattern:** `sprint-status.yaml` becomes a generated file — produced from backlog.yaml + sprint files
-- **Display format:** Output must work well for both human reading and LLM parsing (per epics.md technical note)
-
-### Data Flow
-
-```
-READ:  sprints/sprint-*.yaml → sprint definitions, items, capacity, status
-READ:  backlog.yaml → item details (title, type, status, priority, sprint, severity)
-READ:  bug-*.md → fallback bug metadata
-READ:  sprint-status.yaml → fallback story status, epic/retro keys to preserve
-
-WRITE: sprint-status.yaml → regenerated with non-done items only + sprint metadata headers
-```
-
-### sprint-status.yaml Becomes Derived
-
-| Aspect | Current (Manual) | New (Derived) |
-|---|---|---|
-| Source of truth | Manually maintained | Generated from backlog.yaml + sprint files |
-| Contains | All items including done | Only non-done items |
-| Epic statuses | Manually set | Computed from story statuses |
-| Generation trigger | Manual/sprint-planning | `/sprint-status-view` + `/sprint-planning` |
-| Backward compat | N/A | Preserves STATUS DEFINITIONS block, epic keys, retro keys |
-
-### Display Format (AC: #1)
-
-```
-=== Sprint 3 (active) — 4/6 items ===
-Start: 2026-04-01 | End: 2026-04-14
-
-  * 5-5-explicit-parameter-passing [story] — in-progress
-  * 5-6-fix-space-in-path-bug [story] — ready-for-dev
-  * BUG-path-spaces [bug, high] — ready-for-dev
-  * 15-1-bump-bmad-method [story] — backlog
-
-Capacity: 4/6 (2 remaining)
-Completed this sprint: 0 items
-
-=== Sprint 2 (closed) — 5 items completed ===
-
-=== Backlog — 12 unassigned items ===
-  1. 15-2-restructure-extension-module [story] — backlog
-  2. 15-3-convert-custom-agents [story] — backlog
-  3. BUG-auth-timeout [bug, medium] — backlog
-  ... and 9 more items
-```
-
-### What Changes from Current sprint-status-view
-
-| Aspect | Current (Epic 12) | New (Epic 17) |
-|---|---|---|
-| Sprint source | `sprint-plan-*.yaml` | `sprints/sprint-*.yaml` |
-| Item details | Inferred from key + sprint-status.yaml + bug-*.md | `backlog.yaml` (single source) |
-| Status source | sprint-status.yaml | backlog.yaml status field |
-| Done handling | Shows all items | Hides done items, shows count |
-| Backlog display | From sprint-status.yaml unassigned | From backlog.yaml where sprint is null |
-| YAML regeneration | Not generated | sprint-status.yaml regenerated after display |
-| Sprint metadata | Not shown | Included in header comments |
-
-### Impact on Other Epic 17 Stories
-
-- **17.1 (Sprint Entity):** Reads sprint files created by this format
-- **17.2 (Flat Backlog):** Reads backlog.yaml as primary data source
-- **17.6 (Done Item Cleanup):** Pre-step cleans done items before this displays
-- **17.7 (Prioritization):** Backlog section shows items in priority order set by 17.7
-
-### Critical Guardrails (Story-Specific)
-
-- Do NOT modify any files under `_bmad/bmm/workflows/` or `_bmad/core/`
-- Do NOT add npm dependencies
-- Do NOT modify `lib/installer.js`, `lib/agents.js`, or `bin/cli.js`
-- Do NOT read from `sprint-plan-*.yaml` (old format) — use `sprints/sprint-*.yaml`
-- ALWAYS preserve STATUS DEFINITIONS comment block when regenerating sprint-status.yaml
-- ALWAYS preserve epic keys and retrospective keys in sprint-status.yaml
-- Done items MUST NOT appear in sprint or backlog display sections
-- Sprint-status.yaml regeneration MUST happen after display (not before — display shows latest state)
-- Closed sprints show collapsed summary only — do not expand item lists
-- **Modify SKILL.md, not just workflow.md** — SKILL.md is the file invoked by skill resolution
-
-### Project Structure Notes
-
-- **Files to modify (primary):**
-  - `lib/bmad-extension/skills/sprint-status-view/SKILL.md` — complete rewrite to new model **(authoritative)**
-  - `lib/bmad-extension/skills/sprint-status-view/bmad-skill-manifest.yaml` — verify/update description
-  - `lib/bmad-extension/module-help.csv` — update sprint-status-view description
-  - `_bmad-output/implementation-artifacts/sprint-management-guardrails.md` — document derived sprint-status.yaml
-- **Files to modify (cleanup):**
-  - `lib/bmad-extension/workflows/sprint-status-view/workflow.md` — delete or add redirect note
-- **Files modified at runtime:**
-  - `_bmad-output/implementation-artifacts/sprint-status.yaml` — regenerated with non-done items
-- **Files NOT to touch:**
-  - `_bmad/bmm/4-implementation/bmad-sprint-planning/sprint-status-template.yaml` (bmm core)
-  - `_bmad/bmm/4-implementation/bmad-sprint-status/workflow.md` (bmm core)
-  - Any files under `_bmad/core/` or `lib/installer.js`
-
-### References
-
-- [Source: _bmad-output/planning-artifacts/epics.md#Epic 17, Story 17.8] — Story requirements and acceptance criteria
-- [Source: _bmad-output/planning-artifacts/prd.md#FR71] — Sprint status shows real sprint definitions with assigned items
-- [Source: _bmad-output/planning-artifacts/prd.md#FR130] — Done items removed from sprint status file
-- [Source: _bmad-output/planning-artifacts/prd.md#NFR19] — Menu + slash command invocation
-- [Source: _bmad-output/implementation-artifacts/17-1-sprint-entity-model.md] — Sprint YAML schema
-- [Source: _bmad-output/implementation-artifacts/17-2-flat-backlog-model.md] — Backlog YAML schema
-- [Source: _bmad-output/implementation-artifacts/17-6-done-item-cleanup.md] — Done item archive process
-- [Source: lib/bmad-extension/skills/sprint-status-view/SKILL.md] — Current workflow to rewrite
-- [Source: lib/bmad-extension/module-help.csv] — Workflow registration (skill:sprint-status-view)
-- [Source: _bmad-output/implementation-artifacts/done/12-4-sprint-status-assigned-items.md] — Original Epic 12 story
-
-### Git Intelligence
-
-Recent commits show Epic 15/16 patterns:
-- Conventional commit format: `feat(epic-17): story 17-8 rework sprint status display`
-- Complete SKILL.md rewrites are acceptable when the model fundamentally changes
-
-## Change Log
-
-- 2026-03-30: Story implemented — rewrote sprint-status-view SKILL.md for new sprint+backlog model with sprint-status.yaml regeneration.
-
-## Dev Agent Record
-
-### Agent Model Used
-
-Claude Opus 4.6 (1M context)
-
-### Debug Log References
-
-None — clean implementation.
-
-### Completion Notes List
-
-Rewrote sprint-status-view SKILL.md for new sprint+backlog model with sprint-status.yaml regeneration. Replaced legacy workflow.md with redirect. Updated module-help.csv description. Updated guardrails with derived sprint-status.yaml documentation.
-
-### File List
-
-- `lib/bmad-extension/skills/sprint-status-view/SKILL.md` (rewritten)
-- `lib/bmad-extension/workflows/sprint-status-view/workflow.md` (replaced with redirect)
-- `lib/bmad-extension/module-help.csv` (modified)
-- `sprint-management-guardrails.md` (modified)

package/_bmad-output/implementation-artifacts/done/2-1-cpp-coding-standards-skill.md

@@ -1,188 +0,0 @@
-# Story 2.1: Create C++ Best Practices Skill
-
-Status: done
-
-<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
-
-## Story
-
-As a **C++ engineer**,
-I want a C++ coding standards and best practices skill available in ma-agents,
-So that my AI coding agent follows our organization's C++ methodology consistently.
-
-## Acceptance Criteria
-
-1. **Given** the C++ skill directory exists at `skills/cpp-best-practices/`
-   **When** the skill is listed via `npx ma-agents list`
-   **Then** it appears with description referencing C++ standards and tags including "cpp"
-   **And** `skill.json` contains valid metadata including `applies_when` conditions for C++ contexts
-
-2. **Given** the C++ skill is installed to any supported agent
-   **When** the agent receives the skill content
-   **Then** it contains C++ coding standards, naming conventions, memory management patterns, and best practices
-   **And** the content is applicable to modern C++ (C++17/20/23)
-   **And** cross-references to domain-specific C++ skills are informational (e.g., "if installed, see...")
-
-3. **Given** the skill directory contains `skill.json` and `SKILL.md`
-   **When** installed across multiple agents
-   **Then** the `SKILL.md` canonical content is used (no agent-specific templates exist for this skill)
-   **And** the installed content is identical across all target agents
-
-## Tasks / Subtasks
-
-- [x] Task 1: Create skill directory and metadata (AC: #1)
-  - [x] 1.1: Create directory `skills/cpp-best-practices/`
-  - [x] 1.2: Create `skill.json` with all required fields (see skill.json Schema section below). Must include `applies_when` array for skill discovery and `always_load: true` (this is the umbrella C++ skill).
-  - [x] 1.3: Verify `npx ma-agents list` shows the new skill with correct metadata
-- [x] Task 2: Author SKILL.md content (AC: #2)
-  - [x] 2.1: Write C++ coding standards covering: naming conventions, code organization, modern C++ idioms. Target practical density — prioritize high-value rules over exhaustive coverage. If content naturally exceeds 500 lines, use `references/` directory for supplementary material.
-  - [x] 2.2: Include memory management best practices — cross-reference existing `cpp-memory-handling` skill using informational language ("if the `cpp-memory-handling` skill is installed, it provides detailed RAII/smart pointer patterns"). Do NOT assume sibling skills are co-installed.
-  - [x] 2.3: Include modern C++ patterns: structured bindings, std::optional, std::variant, constexpr, concepts (C++20), ranges (C++20), modules awareness (C++20/23)
-  - [x] 2.4: Include error handling patterns: exceptions vs error codes, std::expected (C++23), noexcept guidelines
-  - [x] 2.5: Include build and compilation guidelines: warning levels, sanitizers, compiler flags. Cross-reference `cmake-best-practices` skill for CMake-specific guidance.
-  - [x] 2.6: Cross-reference all 6 existing C++ related skills using conditional language (see Dev Notes — Relationship to Existing C++ Skills)
-  - [x] 2.7: Optionally create `examples/` directory with representative code samples, consistent with peer C++ skills which all include `examples/`
-- [x] Task 3: Verify installation across agents (AC: #3)
-  - [x] 3.1: Install to at least 2 different agents (e.g., claude-code and cursor)
-  - [x] 3.2: Verify installed content is identical across agents (SKILL.md fallback is the only path)
-  - [x] 3.3: Verify `generateSkillsManifest()` produces correct MANIFEST.yaml entries — check that `applies_when` conditions and `always_load` flag are present in the generated manifest
-
-## Dev Notes
-
-### Architecture Compliance
-
-- **Skill schema contract:** Every skill MUST have `skill.json` (metadata SSoT) + `SKILL.md` (canonical content). Optional directories: `examples/`, `references/`, `scripts/`, `hooks/`, `assets/`. [Source: architecture.md#Data-Architecture]
-- **Directory naming:** `kebab-case` for skill directories [Source: architecture.md#Naming-Patterns]
-- **No installer changes needed:** Adding a new skill requires ONLY the skill package files — the installer discovers skills by scanning the `skills/` directory via `listSkills()`. [Source: architecture.md#Extensibility-Model, NFR14]
-- **Template resolution:** `<agent-name>.md` (highest) -> `generic.md` -> `SKILL.md` (lowest/fallback). Templates are flat files at the skill root — there is NO `templates/` subdirectory. For this skill, `SKILL.md` alone is sufficient.
-
-### Relationship to Existing C++ Skills
-
-**6** C++ related skills already exist in the library:
-
-| Existing Skill | Focus | `always_load` | Relationship |
-|---------------|-------|--------------|-------------|
-| `cpp-memory-handling` | RAII, smart pointers, no raw new/delete | false | Deep-dive — cross-reference |
-| `cpp-const-correctness` | Const semantics | false | Deep-dive — cross-reference |
-| `cpp-concurrency-safety` | Thread safety patterns | false | Deep-dive — cross-reference |
-| `cpp-modern-composition` | Composition over inheritance | **true** | Deep-dive — cross-reference |
-| `cpp-robust-interfaces` | Interface design patterns | false | Deep-dive — cross-reference |
-| `cmake-best-practices` | CMake build system | **true** | Build — cross-reference from Task 2.5 |
-
-**This skill is the umbrella** — it covers broad C++ coding standards and naming conventions, while referencing the domain-specific skills for deeper coverage. It should NOT duplicate content from existing skills.
-
-**Cross-reference pattern:** Because sibling skills may not be co-installed, use conditional language:
-```markdown
-> For detailed memory management patterns, see the `cpp-memory-handling` skill if installed.
-> It covers RAII, smart pointer selection, and ownership transfer patterns.
-```
-This ensures the reference is still informative even when the referenced skill is absent.
-
-### skill.json Schema
-
-Follow the pattern from existing skills (e.g., `cpp-memory-handling/skill.json`). The `applies_when` field is **critical** — it tells the manifest generator and planning instruction when to load this skill:
-```json
-{
-  "name": "C++ Best Practices",
-  "description": "Comprehensive C++ coding standards covering naming conventions, modern C++ idioms (C++17/20/23), error handling, and build guidelines. Cross-references domain-specific C++ skills for deep-dives.",
-  "version": "1.0.0",
-  "author": "ma-agents",
-  "tags": ["c++", "cpp", "coding-standards", "best-practices", "modern-cpp", "c++17", "c++20", "c++23"],
-  "applies_when": [
-    "writing c++ code",
-    "creating new c++ files or classes",
-    "reviewing c++ code style or conventions",
-    "setting up a c++ project"
-  ],
-  "always_load": true
-}
-```
-
-**Note on `category` field:** The architecture specifies `category` as part of the skill.json schema, but NO existing skill in the codebase uses it and `listSkills()` doesn't read or filter by it. Omitted here to match actual runtime behavior. If category support is added later, it can be backfilled.
-
-**Note on `always_load: true`:** This is the umbrella C++ skill. Peer skills like `cpp-modern-composition` and `cmake-best-practices` already use `always_load: true`. As the primary entry point for C++ guidance, this skill should also auto-load to ensure AI agents always have baseline C++ standards available.
-
-### SKILL.md Content Pattern
-
-Follow the **policy-based pattern** used by existing C++ skills (e.g., `cpp-memory-handling/SKILL.md`):
-- Lead with language context and scope
-- Use numbered policies with **Rule** -> **Action** format
-- Include tables for mappings (e.g., naming convention table)
-- Cross-reference sibling skills using conditional language (see above)
-- Existing C++ skills all include an `examples/` directory — consider adding one for consistency
-- Target practical density over exhaustive coverage — if content exceeds 500 lines, split supplementary material to `references/`
-- **No YAML frontmatter** — metadata comes from skill.json only
-
-### Modern C++ Coverage Priorities
-
-The skill content must be applicable to **C++17/20/23** per AC #2. Key areas:
-
-**C++17:** structured bindings, `std::optional`, `std::variant`, `if constexpr`, fold expressions, `std::filesystem`
-**C++20:** concepts, ranges, coroutines, modules, `std::format`, three-way comparison (`<=>`)
-**C++23:** `std::expected`, `std::print`, deducing this, `std::flat_map`/`std::flat_set`
-
-### Critical Guardrails
-
-- **No installer code changes** — only skill package files [Source: architecture.md, NFR14]
-- **kebab-case** directory name: `cpp-best-practices` [Source: architecture.md#Naming-Patterns]
-- **snake_case** keys in skill.json [Source: architecture.md#JSON/YAML-Fields]
-- **No emoji** in SKILL.md content [Source: architecture.md#Format-Patterns]
-- **Do not duplicate** content from existing C++ skills — cross-reference with conditional language instead
-- **Must include `applies_when`** in skill.json — without it, the skill won't appear in generated MANIFEST.yaml with load conditions, making it effectively invisible to automatic skill selection
-
-### Project Structure Notes
-
-- New directory: `skills/cpp-best-practices/`
-- New files: `skill.json`, `SKILL.md`
-- Optional: `examples/` directory (all peer C++ skills include one)
-- Optional: `references/` directory if content exceeds 500 lines
-- No changes to any existing files or modules
-
-### References
-
-- [Source: _bmad-output/planning-artifacts/epics.md#Epic-2] — Epic 2 story definitions
-- [Source: _bmad-output/planning-artifacts/prd.md#FR36] — FR36: Functionally equivalent behavior across agents
-- [Source: _bmad-output/planning-artifacts/prd.md#FR39] — FR39: Skill authoring format
-- [Source: _bmad-output/planning-artifacts/architecture.md#Data-Architecture] — Skill schema contract
-- [Source: _bmad-output/planning-artifacts/architecture.md#Extensibility-Model] — Template resolution priority
-- [Source: _bmad-output/planning-artifacts/architecture.md#Naming-Patterns] — Naming conventions
-- [Source: skills/cpp-memory-handling/] — Existing C++ memory handling skill (reference pattern for skill.json with applies_when)
-- [Source: skills/cmake-best-practices/] — Existing CMake skill (6th C++ related skill, uses always_load: true)
-- [Source: skills/python-security-skill/] — Representative policy-based skill pattern
-- [Source: lib/installer.js `function listSkills`] — Skill discovery mechanism
-- [Source: lib/installer.js `function generateSkillsManifest`] — MANIFEST.yaml generation (consumes applies_when, always_load)
-
-## Dev Agent Record
-
-### Agent Model Used
-
-claude-sonnet-4-6
-
-### Debug Log References
-
-None — implementation was straightforward. Skill package only (no installer code changes per guardrail NFR14).
-
-### Completion Notes List
-
-- Created `skills/cpp-best-practices/` with `skill.json` and `SKILL.md`
-- `skill.json` includes `applies_when` array (4 conditions) and `always_load: true`
-- `SKILL.md` covers 10 sections: naming conventions, code organization, memory management (cross-ref cpp-memory-handling), modern C++ idioms (C++17/20/23), const-correctness (cross-ref cpp-const-correctness), error handling, class design (cross-ref cpp-modern-composition + cpp-robust-interfaces), concurrency (cross-ref cpp-concurrency-safety), build guidelines (cross-ref cmake-best-practices), general code quality
-- All 6 existing C++ sibling skills cross-referenced using conditional language
-- `examples/` directory created with `naming-and-organization.md` and `modern-idioms.md` (consistent with peer C++ skills)
-- Installed to claude-code and cursor; `diff` confirms identical SKILL.md content across both agents
-- `npx ma-agents list` shows skill with correct description and tags including "cpp"
-- MANIFEST.yaml verified: `applies_when` and `always_load: true` present
-- All 9 existing tests pass — no regressions
-
-### File List
-
-- `skills/cpp-best-practices/skill.json` (new)
-- `skills/cpp-best-practices/SKILL.md` (new)
-- `skills/cpp-best-practices/examples/naming-and-organization.md` (new)
-- `skills/cpp-best-practices/examples/modern-idioms.md` (new)
-
-Note: `.claude/` and `.cursor/` installed copies are derived outputs generated by `npx ma-agents install` and are gitignored — not tracked here.
-
-### Change Log
-
-- 2026-03-19: Created C++ Best Practices umbrella skill (Story 2.1) — new skill package in `skills/cpp-best-practices/` with 10-section SKILL.md covering naming, modern C++17/20/23 idioms, error handling, and build guidelines; cross-references all 6 existing C++ domain skills using conditional language; installed to claude-code and cursor agents.