ma-agents 3.4.9 → 3.5.0

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

@@ -0,0 +1,285 @@
+# 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

@@ -0,0 +1,188 @@
+# 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.