ma-agents 3.6.2 → 3.9.0

package/_bmad-output/implementation-artifacts/done/17-4-backlog-to-sprint-workflow.md

@@ -1,209 +0,0 @@
-# Story 17.4: Backlog-to-Sprint Workflow
-
-Status: review
-
-<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
-
-## Story
-
-As a **Scrum Master**,
-I want a workflow to move items from the backlog into a sprint,
-So that I can populate sprints by selecting prioritized items across epics.
-
-## Acceptance Criteria
-
-1. **Given** the backlog contains unassigned items (no `sprint` field or `sprint: null`),
-   **When** the Scrum Master invokes the assign-to-sprint workflow,
-   **Then** it displays the active or planning sprint and its current capacity usage,
-   **And** shows the top N unassigned backlog items in priority order,
-   **And** the Scrum Master selects which items to add.
-
-2. **Given** the Scrum Master selects items for the sprint,
-   **When** the items are assigned,
-   **Then** each item's `sprint` field in `backlog.yaml` is set to the sprint ID,
-   **And** the sprint file's `items` array is updated with the new IDs,
-   **And** the workflow validates that capacity is not exceeded — warns if over capacity.
-
-3. **Given** the workflow is invoked via menu or slash command,
-   **When** it executes,
-   **Then** it works identically in both invocation modes (NFR19).
-
-## Tasks / Subtasks
-
-- [x] Task 1: Rework add-to-sprint SKILL.md to use backlog + sprint model (AC: #1, #2, #3)
-  - [x] 1.1: Rewrite `lib/bmad-extension/skills/add-to-sprint/SKILL.md` — replace the entire workflow with the new model. The current workflow reads from `sprint-status.yaml` and `sprint-plan-*.yaml` — the new version reads from `backlog.yaml` and `sprints/sprint-*.yaml`.
-  - [x] 1.2: Update YAML frontmatter triggers (keep existing triggers: "add to sprint", "assign to sprint")
-  - [x] 1.3: Implement new workflow steps:
-
-    **Step 1: Load backlog and identify unassigned items**
-    - Read `_bmad-output/implementation-artifacts/backlog.yaml`
-    - Filter items where `sprint` is `null` (unassigned)
-    - Sort by `priority` ascending (highest priority first)
-    - If no unassigned items: display "All backlog items are assigned to sprints" and exit
-
-    **Step 2: Load sprints and select target**
-    - Glob `_bmad-output/implementation-artifacts/sprints/sprint-*.yaml` to find all sprint files
-    - If no sprint files found: display "No sprints exist. Run `/add-sprint` first." and exit
-    - Read each sprint file; extract: id, name, status, capacity, items count
-    - Display sprints table sorted by status (`active` first, then `planning`, then `closed`)
-    - If exactly one `active` sprint exists: auto-select it, confirm with user
-    - If no `active` sprint but `planning` sprints exist: prompt user to select
-    - Closed sprints are shown but not selectable
-
-    **Step 3: Display sprint capacity and unassigned items**
-    - Calculate: assigned = length of sprint.items, remaining = capacity - assigned
-    - Display sprint capacity bar
-    - Display top 20 unassigned backlog items (or all if fewer than 20) with columns: #, ID, Title, Type, Priority, Severity (bugs only)
-    - If remaining capacity <= 0: warn "Sprint is at capacity" but allow override
-
-    **Step 4: Select items to assign**
-    - Prompt: "Select items to add (comma-separated numbers, 'all' for all shown, or 'q' to cancel)"
-    - If 'q': exit without changes
-    - Validate selections are valid numbers from the displayed list
-
-    **Step 5: Capacity check and assignment**
-    - For each selected item, check if adding would exceed capacity
-    - If over capacity: warn with exact count, offer [a]dd anyway / [s]kip this item / [q]uit
-    - For each confirmed item:
-      - Add item ID to sprint file's `items` array
-      - Set item's `sprint` field in `backlog.yaml` to sprint ID
-      - Update sprint file's `last_modified` timestamp
-
-    **Step 6: Persist and report**
-    - Write updated `backlog.yaml` (preserving all fields, only `sprint` changed for assigned items)
-    - Write updated sprint file (with new items and last_modified)
-    - Display summary: items assigned, new capacity usage, remaining slots
-
-- [x] Task 2: Update bmad-skill-manifest.yaml (AC: #3)
-  - [x] 2.1: Verify/update `lib/bmad-extension/skills/add-to-sprint/bmad-skill-manifest.yaml` description to reflect new model
-
-- [x] Task 3: Update module-help.csv (AC: #3)
-  - [x] 3.1: Update the `add-to-sprint` row in `lib/bmad-extension/module-help.csv`:
-    - Update `output-location` from `_bmad-output/implementation-artifacts` to `_bmad-output/implementation-artifacts` (unchanged path but now writes to both backlog.yaml and sprints/)
-    - Update `description` to: "Assign backlog items to a sprint from flat prioritized backlog."
-
-- [x] Task 4: Sync or remove legacy workflow.md (AC: #3)
-  - [x] 4.1: `lib/bmad-extension/workflows/add-to-sprint/workflow.md` is a legacy copy. Either:
-    - Delete it if SKILL.md is the sole source of truth (verify via module-help.csv `skill:add-to-sprint` resolution)
-    - Or add a redirect note: "This workflow has moved to `skills/add-to-sprint/SKILL.md`"
-
-- [x] Task 5: Update guardrails (AC: #2)
-  - [x] 5.1: Update `sprint-management-guardrails.md` Data Authority Rules:
-    - `backlog.yaml` is now written by add-to-sprint (sets `sprint` field)
-    - Sprint files under `sprints/` are now written by add-to-sprint (appends to `items` array)
-  - [x] 5.2: Document the dual-write contract: when assigning an item, BOTH `backlog.yaml` AND the sprint file must be updated atomically (within same workflow invocation). If one fails, the other must be rolled back or the user must be warned.
-
-- [x] Task 6: Verify (AC: #1, #2, #3)
-  - [x] 6.1: Trace SKILL.md — confirm all paths read from `backlog.yaml` and `sprints/sprint-*.yaml` (never from `sprint-plan-*.yaml` or `sprint-status.yaml`)
-  - [x] 6.2: Verify capacity enforcement: warn when exceeding, allow override
-  - [x] 6.3: Verify dual-write: both backlog.yaml `sprint` field and sprint file `items` array are updated
-  - [x] 6.4: Verify `last_modified` timestamp is updated on sprint file
-  - [x] 6.5: Verify item IDs in sprint `items` array follow the Item ID Format Contract from Story 17.1
-  - [x] 6.6: Verify closed sprints are not selectable as targets
-
-## Dev Notes
-
-### Architecture Compliance
-
-- **SKILL.md is the authoritative file:** `lib/bmad-extension/skills/add-to-sprint/SKILL.md` is resolved by `skill:add-to-sprint` in module-help.csv
-- **Extension module pattern:** Skill lives in `lib/bmad-extension/skills/add-to-sprint/`
-- **Dual-write pattern:** This workflow writes to TWO files per assignment — `backlog.yaml` and `sprints/sprint-{id}.yaml`. Both must be consistent.
-- **No sprint-status.yaml writes:** This workflow does NOT touch sprint-status.yaml. That file is derived (Story 17.8).
-
-### Data Flow
-
-```
-READ:  backlog.yaml → unassigned items (sprint: null)
-READ:  sprints/sprint-*.yaml → available sprints + capacity
-WRITE: backlog.yaml → set sprint field on assigned items
-WRITE: sprints/sprint-{id}.yaml → append to items array, update last_modified
-```
-
-### What Changes from Current add-to-sprint
-
-| Aspect | Current (Epic 12) | New (Epic 17) |
-|---|---|---|
-| Item source | sprint-status.yaml + bug-*.md glob | backlog.yaml (single source) |
-| Sprint source | sprint-plan-*.yaml | sprints/sprint-*.yaml |
-| Sprint discovery glob | `sprint-plan-*.yaml` | `sprints/sprint-*.yaml` |
-| Assignment tracking | Only in sprint-plan file | Both backlog.yaml and sprint file |
-| Prioritization | Multi-criteria analysis in workflow | Pre-computed priority in backlog.yaml |
-| Unassigned filter | Cross-reference all sprint files | Simple: `sprint: null` in backlog.yaml |
-
-### Impact on Other Epic 17 Stories
-
-- **17.1 (Sprint Entity):** Provides the sprint file format this story writes to
-- **17.2 (Flat Backlog):** Provides the backlog.yaml format this story reads/writes
-- **17.5 (Sprint-to-Backlog):** Inverse operation — removes items this story assigns
-- **17.6 (Done Item Cleanup):** Removes done items from both backlog and sprint files
-- **17.8 (Sprint Status Display):** Reads the sprint files this story writes
-
-### 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 modify `sprint-status.yaml` — it is derived and read-only from this workflow
-- Do NOT read from `sprint-plan-*.yaml` (old format) — use `sprints/sprint-*.yaml` exclusively
-- ALWAYS update both `backlog.yaml` AND the sprint file when assigning items
-- ALWAYS update `last_modified` on the sprint file after modification
-- Item IDs in sprint `items` array MUST follow the Item ID Format Contract: `{epic}-{story}-{slug}` for stories, `BUG-{slug}` for bugs
-- Closed sprints MUST NOT be selectable as assignment targets
-- **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/add-to-sprint/SKILL.md` — complete rewrite to new model **(authoritative)**
-  - `lib/bmad-extension/skills/add-to-sprint/bmad-skill-manifest.yaml` — verify/update description
-  - `lib/bmad-extension/module-help.csv` — update add-to-sprint description
-  - `_bmad-output/implementation-artifacts/sprint-management-guardrails.md` — update data authority rules
-- **Files to modify (cleanup):**
-  - `lib/bmad-extension/workflows/add-to-sprint/workflow.md` — delete or add redirect note
-- **Files NOT to touch:**
-  - `sprint-status.yaml` (derived, read-only)
-  - `sprint-plan-*.yaml` (old format, deprecated)
-  - Any files under `_bmad/` or `lib/installer.js`
-
-### References
-
-- [Source: _bmad-output/planning-artifacts/epics.md#Epic 17, Story 17.4] — Story requirements and acceptance criteria
-- [Source: _bmad-output/planning-artifacts/prd.md#FR69] — Workflow to move items from backlog into sprint
-- [Source: _bmad-output/planning-artifacts/prd.md#FR66] — Sprint capacity as item count
-- [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, Item ID Format Contract, capacity enforcement
-- [Source: _bmad-output/implementation-artifacts/17-2-flat-backlog-model.md] — Backlog YAML schema, sprint field contract
-- [Source: lib/bmad-extension/skills/add-to-sprint/SKILL.md] — Current workflow to rewrite
-- [Source: lib/bmad-extension/module-help.csv] — Workflow registration (skill:add-to-sprint)
-- [Source: _bmad-output/implementation-artifacts/done/12-2-add-to-sprint-workflow.md] — Original Epic 12 story for reference
-
-### Git Intelligence
-
-Recent commits show Epic 15/16 patterns:
-- Conventional commit format: `feat(epic-17): story 17-4 backlog-to-sprint workflow`
-- Complete SKILL.md rewrites are acceptable when the model fundamentally changes
-
-## Change Log
-
-- 2026-03-30: Story implemented — rewrote add-to-sprint SKILL.md for new backlog+sprint model with dual-write contract.
-
-## Dev Agent Record
-
-### Agent Model Used
-
-Claude Opus 4.6 (1M context)
-
-### Debug Log References
-
-None — clean implementation.
-
-### Completion Notes List
-
-Rewrote add-to-sprint SKILL.md for new backlog+sprint model. Replaced legacy workflow.md with redirect. Updated module-help.csv description. Updated guardrails with dual-write contract.
-
-### File List
-
-- `lib/bmad-extension/skills/add-to-sprint/SKILL.md` (rewritten)
-- `lib/bmad-extension/workflows/add-to-sprint/workflow.md` (replaced with redirect)
-- `lib/bmad-extension/module-help.csv` (modified)
-- `sprint-management-guardrails.md` (modified)

package/_bmad-output/implementation-artifacts/done/17-5-sprint-to-backlog-workflow.md

@@ -1,221 +0,0 @@
-# Story 17.5: Sprint-to-Backlog Workflow
-
-Status: review
-
-<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
-
-## Story
-
-As a **Scrum Master**,
-I want a workflow to move items from a sprint back to the backlog,
-So that I can adjust sprint scope when priorities change without losing the item.
-
-## Acceptance Criteria
-
-1. **Given** a sprint has assigned items,
-   **When** the Scrum Master invokes the remove-from-sprint workflow,
-   **Then** it displays the sprint's currently assigned items,
-   **And** the Scrum Master selects which items to remove.
-
-2. **Given** items are removed from the sprint,
-   **When** the removal completes,
-   **Then** the item's `sprint` field in `backlog.yaml` is cleared (set to `null`),
-   **And** the item is removed from the sprint file's `items` array,
-   **And** the item's status is NOT changed — it retains its current status (e.g., stays `ready-for-dev`),
-   **And** the item remains in the backlog at its current priority position.
-
-## Tasks / Subtasks
-
-- [x] Task 1: Decide implementation location (AC: #1, #2)
-  - [x] 1.1: Evaluate whether to rework the existing `modify-sprint` skill or create a new `remove-from-sprint` skill:
-    - **Option A (Recommended):** Create new `lib/bmad-extension/skills/remove-from-sprint/SKILL.md` — focused, single-purpose workflow aligned with FR129
-    - **Option B:** Add remove capability to `modify-sprint` — but modify-sprint already handles add/remove/capacity/metadata and will need its own rework for the new sprint model
-    - **Decision:** Use **Option A** — a dedicated skill is cleaner and avoids coupling the remove operation to the larger modify-sprint rework
-  - [x] 1.2: If Option A, also add a deprecation/update note to `modify-sprint` SKILL.md indicating that item removal is now handled by `/remove-from-sprint`
-
-- [x] Task 2: Create remove-from-sprint SKILL.md (AC: #1, #2)
-  - [x] 2.1: Create skill package at `lib/bmad-extension/skills/remove-from-sprint/SKILL.md` with YAML frontmatter:
-    ```yaml
-    ---
-    name: remove-from-sprint
-    description: Remove items from a sprint and return them to the unassigned backlog
-    type: skill
-    triggers:
-      - "remove from sprint"
-      - "unassign from sprint"
-    ---
-    ```
-  - [x] 2.2: Create `lib/bmad-extension/skills/remove-from-sprint/bmad-skill-manifest.yaml`
-  - [x] 2.3: Implement workflow steps:
-
-    **Step 1: Select sprint**
-    - Glob `_bmad-output/implementation-artifacts/sprints/sprint-*.yaml` to find all sprint files
-    - If no sprint files: display "No sprints exist." and exit
-    - Read each sprint file; display table: #, Sprint Name, Status, Items Count
-    - Filter to sprints with at least 1 item (empty sprints have nothing to remove)
-    - If no sprints have items: display "No sprints have assigned items." and exit
-    - Prompt user to select a sprint
-    - Store selected sprint and its `last_modified` for concurrency guard
-
-    **Step 2: Display assigned items**
-    - Read `_bmad-output/implementation-artifacts/backlog.yaml`
-    - For each item ID in the sprint's `items` array, look up details from backlog.yaml: title, type, status, priority
-    - If an item ID is in the sprint but NOT in the backlog (data inconsistency): display with warning marker and raw ID
-    - Display items table: #, ID, Title, Type, Status, Priority
-
-    **Step 3: Select items to remove**
-    - Prompt: "Select items to remove (comma-separated numbers, 'all' to remove all, or 'q' to cancel)"
-    - If 'q': exit without changes
-    - Validate selections
-
-    **Step 4: Confirm removal**
-    - Display selected items for confirmation
-    - Emphasize: "Item status will NOT change — items retain their current status"
-    - Prompt: "[y] Confirm removal / [n] Cancel / [e] Edit selection"
-    - If 'n': exit without changes
-    - If 'e': go back to Step 3
-
-    **Step 5: Concurrency guard**
-    - Re-read sprint file and check `last_modified` against stored value
-    - If changed: warn about conflict, offer [o]verwrite / [r]eload / [x]cancel (same pattern as modify-sprint)
-
-    **Step 6: Persist changes**
-    - For each confirmed item:
-      - Remove item ID from sprint file's `items` array
-      - Set item's `sprint` field in `backlog.yaml` to `null`
-      - Do NOT change item's `status` field (AC #2 — status preserved)
-    - Update sprint file's `last_modified` timestamp
-    - Write updated sprint file
-    - Write updated backlog.yaml
-    - Display summary: items removed, new sprint capacity usage
-
-- [x] Task 3: Register in module-help.csv (AC: #1)
-  - [x] 3.1: Add row to `lib/bmad-extension/module-help.csv`:
-    ```
-    ma-skills,4-implementation,Remove from Sprint,remove-from-sprint,,skill:remove-from-sprint,remove-from-sprint,false,bmm-sm,,"Remove items from a sprint and return to unassigned backlog.",_bmad-output/implementation-artifacts,"sprint plan",
-    ```
-
-- [x] Task 4: Update modify-sprint with cross-reference (AC: #1)
-  - [x] 4.1: Add note at the top of `lib/bmad-extension/skills/modify-sprint/SKILL.md`:
-    ```
-    <!-- NOTE: Item removal from sprints is now handled by /remove-from-sprint (Story 17.5).
-         The "Remove item" option in this workflow's menu is superseded.
-         This workflow will be fully reworked when converted to the new sprint model. -->
-    ```
-
-- [x] Task 5: Update guardrails (AC: #2)
-  - [x] 5.1: Add to `sprint-management-guardrails.md`: "remove-from-sprint writes to both `backlog.yaml` (clears sprint field) and `sprints/sprint-{id}.yaml` (removes from items array) — dual-write contract same as add-to-sprint"
-  - [x] 5.2: Document invariant: removing an item from a sprint NEVER changes the item's status
-
-- [x] Task 6: Verify (AC: #1, #2)
-  - [x] 6.1: Trace SKILL.md — confirm all paths read from `backlog.yaml` and `sprints/sprint-*.yaml`
-  - [x] 6.2: Verify dual-write: both backlog.yaml `sprint` field cleared and sprint file `items` array updated
-  - [x] 6.3: Verify status preservation: item status is NEVER modified by this workflow
-  - [x] 6.4: Verify concurrency guard: checks `last_modified` before writing
-  - [x] 6.5: Verify `last_modified` timestamp is updated on sprint file after removal
-  - [x] 6.6: Verify backlog priority is preserved (items stay at same priority position)
-
-## Dev Notes
-
-### Architecture Compliance
-
-- **SKILL.md is the authoritative file:** New skill at `lib/bmad-extension/skills/remove-from-sprint/SKILL.md`
-- **Extension module pattern:** Skill lives in `lib/bmad-extension/skills/remove-from-sprint/`
-- **Dual-write pattern:** Same as Story 17.4 — writes to both `backlog.yaml` and sprint file
-- **Concurrency guard:** Same pattern as `modify-sprint` — check `last_modified` before writing
-- **Status invariant:** This workflow NEVER modifies item status. This is a hard constraint from FR129.
-
-### Data Flow
-
-```
-READ:  sprints/sprint-*.yaml → sprint list with items
-READ:  backlog.yaml → item details (title, type, status, priority)
-WRITE: sprints/sprint-{id}.yaml → remove from items array, update last_modified
-WRITE: backlog.yaml → clear sprint field on removed items
-```
-
-### Inverse of Story 17.4
-
-This is the exact inverse operation of Story 17.4 (Backlog-to-Sprint):
-- 17.4: sets `sprint` field, appends to sprint `items`
-- 17.5: clears `sprint` field, removes from sprint `items`
-
-Both follow the same dual-write pattern and concurrency guard.
-
-### Impact on Other Epic 17 Stories
-
-- **17.1 (Sprint Entity):** Sprint file format this story reads/writes
-- **17.2 (Flat Backlog):** Backlog format this story reads/writes
-- **17.4 (Backlog-to-Sprint):** Inverse operation
-- **17.6 (Done Item Cleanup):** Different removal path — 17.6 removes done items permanently, 17.5 returns items to unassigned backlog
-- **17.8 (Sprint Status Display):** Reads sprint files modified by this story
-
-### 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 modify `sprint-status.yaml` — it is derived and read-only
-- Do NOT change item status when removing from sprint (FR129 — status preserved)
-- Do NOT change item priority when removing from sprint (position preserved)
-- ALWAYS update both `backlog.yaml` AND the sprint file when removing items
-- ALWAYS update `last_modified` on the sprint file after modification
-- ALWAYS check concurrency guard before writing to sprint file
-
-### Project Structure Notes
-
-- **Files to create:**
-  - `lib/bmad-extension/skills/remove-from-sprint/SKILL.md` — new skill (authoritative)
-  - `lib/bmad-extension/skills/remove-from-sprint/bmad-skill-manifest.yaml` — skill manifest
-- **Files to modify:**
-  - `lib/bmad-extension/module-help.csv` — add remove-from-sprint row
-  - `lib/bmad-extension/skills/modify-sprint/SKILL.md` — add cross-reference note only
-  - `_bmad-output/implementation-artifacts/sprint-management-guardrails.md` — document dual-write and status invariant
-- **Files NOT to touch:**
-  - `sprint-status.yaml` (derived, read-only)
-  - `sprint-plan-*.yaml` (old format, deprecated)
-  - Any files under `_bmad/` or `lib/installer.js`
-
-### References
-
-- [Source: _bmad-output/planning-artifacts/epics.md#Epic 17, Story 17.5] — Story requirements and acceptance criteria
-- [Source: _bmad-output/planning-artifacts/prd.md#FR129] — Move items from sprint back to backlog without status change
-- [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, concurrency guard pattern
-- [Source: _bmad-output/implementation-artifacts/17-2-flat-backlog-model.md] — Backlog YAML schema
-- [Source: _bmad-output/implementation-artifacts/17-4-backlog-to-sprint-workflow.md] — Inverse operation (assign to sprint)
-- [Source: lib/bmad-extension/skills/modify-sprint/SKILL.md] — Current modify-sprint with remove capability (to be superseded)
-- [Source: lib/bmad-extension/module-help.csv] — Workflow registration
-- [Source: _bmad-output/implementation-artifacts/done/12-3-modify-sprint-workflow.md] — Original Epic 12 modify-sprint story
-
-### Git Intelligence
-
-Recent commits show Epic 15/16 patterns:
-- Conventional commit format: `feat(epic-17): story 17-5 sprint-to-backlog workflow`
-- New skill creation follows: SKILL.md + bmad-skill-manifest.yaml + module-help.csv registration
-
-## Change Log
-
-- 2026-03-30: Story implemented — created remove-from-sprint skill with dual-write contract and concurrency guard.
-
-## Dev Agent Record
-
-### Agent Model Used
-
-Claude Opus 4.6 (1M context)
-
-### Debug Log References
-
-None — clean implementation.
-
-### Completion Notes List
-
-Created remove-from-sprint skill (SKILL.md + manifest). Registered in module-help.csv. Added cross-reference note to modify-sprint SKILL.md. Updated guardrails with status invariant.
-
-### File List
-
-- `lib/bmad-extension/skills/remove-from-sprint/SKILL.md` (new)
-- `lib/bmad-extension/skills/remove-from-sprint/bmad-skill-manifest.yaml` (new)
-- `lib/bmad-extension/module-help.csv` (modified)
-- `lib/bmad-extension/skills/modify-sprint/SKILL.md` (modified)
-- `sprint-management-guardrails.md` (modified)