ma-agents 3.4.8 → 3.5.0

package/{.opencode → lib/bmad-extension}/skills/bmad-dev-story/workflow.md

@@ -58,21 +58,38 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
       <goto anchor="task_check" />
     </check>
 
-    <!-- Sprint-based story discovery -->
+    <!-- Sprint-based story discovery (unified sprint-status.yaml schema) -->
     <check if="{{sprint_status}} file exists">
       <critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
       <action>Load the FULL file: {{sprint_status}}</action>
       <action>Read ALL lines from beginning to end - do not skip any content</action>
-      <action>Parse the development_status section completely to understand story order</action>
+      <action>Parse the full unified schema: metadata fields, epics section, backlog array, and sprints map</action>
+
+      <!-- Search active sprints first, then planning sprints, then backlog -->
+      <action>Search for first item with status "ready-for-dev" using this priority order:
+        1. Iterate sprints map entries where sprint.status == "active" (skip "closed" sprints);
+           for each active sprint, iterate its items array and find first item where item.status == "ready-for-dev"
+        2. If not found, iterate sprints map entries where sprint.status == "planning";
+           for each planning sprint, iterate its items array and find first item where item.status == "ready-for-dev"
+        3. If not found, iterate the backlog array and find first item where item.status == "ready-for-dev"
+        Note: items in "closed" sprints are SKIPPED entirely
+      </action>
 
-      <action>Find the FIRST story (by reading in order from top to bottom) where:
-        - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
-        - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
-        - Status value equals "ready-for-dev"
+      <action>When a ready-for-dev item is found:
+        - Extract item.id as the story_key
+        - Record location context:
+          * If found in a sprint: location_context = "in {sprint-id}" (e.g., "in sprint-3")
+          * If found in backlog: location_context = "in backlog (unassigned)"
+        - Note the item.type field ("story" or "bug") — no key pattern matching needed
       </action>
 
-      <check if="no ready-for-dev or in-progress story found">
-        <output>📋 No ready-for-dev stories found in sprint-status.yaml
+      <check if="no ready-for-dev item found in any sprint or backlog">
+        <action>Build sprint status summary from the unified schema:
+          - Count active/planning/closed sprints
+          - Count total backlog items and their statuses
+          - List any in-progress items
+        </action>
+        <output>No ready-for-dev stories found in sprint-status.yaml
 
           **Current Sprint Status:** {{sprint_status_summary}}
 
@@ -82,7 +99,7 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
           3. Specify a particular story file to develop (provide full path)
           4. Check {{sprint_status}} file to see current sprint status
 
-          💡 **Tip:** Stories in `ready-for-dev` may not have been validated. Consider running `validate-create-story` first for a quality
+          **Tip:** Stories in `ready-for-dev` may not have been validated. Consider running `validate-create-story` first for a quality
           check.
         </output>
         <ask>Choose option [1], [2], [3], or [4], or specify story file path:</ask>
@@ -122,7 +139,7 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
       <action>Read each candidate story file to check Status section</action>
 
       <check if="no ready-for-dev stories found in story files">
-        <output>📋 No ready-for-dev stories found
+        <output>No ready-for-dev stories found
 
           **Available Options:**
           1. Run `create-story` to create next story from epics with comprehensive context
@@ -151,7 +168,9 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
       </check>
     </check>
 
-    <action>Store the found story_key (e.g., "1-2-user-authentication") for later status updates</action>
+    <action>Store the found story_key (e.g., "17-10-rework-generate-backlog") for later status updates</action>
+    <action>Store the found location_context (e.g., "in sprint-3" or "in backlog") for later status updates</action>
+    <action>If location_context was not set (e.g., story_path was provided explicitly), set location_context = "unknown location"</action>
     <action>Find matching story file in {implementation_artifacts} using story_key pattern: {{story_key}}.md</action>
     <action>Read COMPLETE story file from discovered path</action>
 
@@ -180,7 +199,7 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
     <action>Load comprehensive context from story file's Dev Notes section</action>
     <action>Extract developer guidance from Dev Notes: architecture requirements, previous learnings, technical specifications</action>
     <action>Use enhanced story context to inform implementation decisions and approaches</action>
-    <output>✅ **Context Loaded**
+    <output>Context Loaded
       Story and project context available for implementation
     </output>
   </step>
@@ -202,7 +221,7 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
       <action>Count unchecked [ ] review follow-up tasks in "Review Follow-ups (AI)" subsection</action>
       <action>Store list of unchecked review items as {{pending_review_items}}</action>
 
-      <output>⏯️ **Resuming Story After Code Review** ({{review_date}})
+      <output>Resuming Story After Code Review ({{review_date}})
 
         **Review Outcome:** {{review_outcome}}
         **Action Items:** {{unchecked_review_count}} remaining to address
@@ -216,7 +235,7 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
       <action>Set review_continuation = false</action>
       <action>Set {{pending_review_items}} = empty</action>
 
-      <output>🚀 **Starting Fresh Implementation**
+      <output>Starting Fresh Implementation
 
         Story: {{story_key}}
         Story Status: {{current_status}}
@@ -227,35 +246,59 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 
   <step n="4" goal="Mark story in-progress" tag="sprint-status">
     <check if="{{sprint_status}} file exists">
+      <critical>MUST read COMPLETE sprint-status.yaml file to preserve all content during write-back</critical>
       <action>Load the FULL file: {{sprint_status}}</action>
-      <action>Read all development_status entries to find {{story_key}}</action>
-      <action>Get current status value for development_status[{{story_key}}]</action>
-
-      <check if="current status == 'ready-for-dev' OR review_continuation == true">
-        <action>Update the story in the sprint status report to = "in-progress"</action>
-        <action>Update last_updated field to current date</action>
-        <output>🚀 Starting work on story {{story_key}}
-          Status updated: ready-for-dev → in-progress
+      <action>Parse the full unified schema: metadata fields, epics section, backlog array, and sprints map</action>
+
+      <!-- Cross-section search for the story item by id -->
+      <action>Search for item with id == {{story_key}} across BOTH backlog and sprints sections:
+        1. Search all sprints map entries (active sprints first, then planning; skip closed sprints entirely):
+           - Iterate each non-closed sprint's items array, match item.id == {{story_key}}
+        2. If not found in any sprint, search backlog array:
+           - Iterate items, match item.id == {{story_key}}
+        3. When item is found: update {{location_context}} = sprint id (e.g., "in sprint-3") or "in backlog (unassigned)"
+        4. If not found in either location: output error and exit workflow without writing
+      </action>
+
+      <check if="item found AND (current item.status == 'ready-for-dev' OR review_continuation == true)">
+        <action>Update item.status = "in-progress" in-place (preserve all other fields: id, type, epic, title, priority if present, severity)</action>
+        <action>Update last_updated metadata field to current ISO-8601 timestamp</action>
+        <action>Write back the FULL file preserving ALL sections (epics, backlog, sprints) and ALL comments</action>
+        <output>Starting work on story {{story_key}} ({{location_context}})
+          Status updated: ready-for-dev -> in-progress
         </output>
       </check>
 
-      <check if="current status == 'in-progress'">
-        <output>⏯️ Resuming work on story {{story_key}}
+      <check if="item found AND current item.status == 'in-progress'">
+        <output>Resuming work on story {{story_key}} ({{location_context}})
           Story is already marked in-progress
         </output>
       </check>
 
-      <check if="current status is neither ready-for-dev nor in-progress">
-        <output>⚠️ Unexpected story status: {{current_status}}
+      <check if="item found AND current item.status is neither ready-for-dev nor in-progress">
+        <output>Unexpected story status: {{current_status}}
           Expected ready-for-dev or in-progress. Continuing anyway...
         </output>
       </check>
 
-      <action>Store {{current_sprint_status}} for later use</action>
+      <check if="item NOT found in any section of sprint-status.yaml">
+        <!-- Check done archive -->
+        <action>Check for file at {implementation_artifacts}/done/{{story_key}}.md</action>
+        <check if="done archive file found">
+          <output>HALT: Story {{story_key}} has been archived (done). It cannot be developed again without manual re-introduction to the backlog.</output>
+          <action>HALT</action>
+        </check>
+        <check if="done archive file NOT found">
+          <output>HALT: Story {{story_key}} not found in sprint-status.yaml. It may not yet have been added to the backlog. Run sprint planning or generate-backlog first.</output>
+          <action>HALT</action>
+        </check>
+      </check>
+
+      <action>Store {{current_sprint_status}} for later use (the item's current status or "found-and-updated")</action>
     </check>
 
     <check if="{{sprint_status}} file does NOT exist">
-      <output>ℹ️ No sprint status file exists - story progress will be tracked in story file only</output>
+      <output>No sprint status file exists - story progress will be tracked in story file only</output>
       <action>Set {{current_sprint_status}} = "no-sprint-tracking"</action>
     </check>
   </step>
@@ -329,7 +372,7 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
       <action>Find matching action item in "Senior Developer Review (AI) → Action Items" section by matching description</action>
       <action>Mark that action item checkbox [x] as resolved</action>
 
-      <action>Add to Dev Agent Record → Completion Notes: "✅ Resolved review finding [{{severity}}]: {{description}}"</action>
+      <action>Add to Dev Agent Record → Completion Notes: "Resolved review finding [{{severity}}]: {{description}}"</action>
     </check>
 
     <!-- ONLY MARK COMPLETE IF ALL VALIDATION PASS -->
@@ -383,24 +426,40 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 
     <!-- Mark story ready for review - sprint status conditional -->
     <check if="{sprint_status} file exists AND {{current_sprint_status}} != 'no-sprint-tracking'">
+      <critical>MUST read COMPLETE sprint-status.yaml file to preserve all content during write-back</critical>
       <action>Load the FULL file: {sprint_status}</action>
-      <action>Find development_status key matching {{story_key}}</action>
-      <action>Verify current status is "in-progress" (expected previous state)</action>
-      <action>Update development_status[{{story_key}}] = "review"</action>
-      <action>Update last_updated field to current date</action>
-      <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
-      <output>✅ Story status updated to "review" in sprint-status.yaml</output>
-    </check>
+      <action>Parse the full unified schema: metadata fields, epics section, backlog array, and sprints map</action>
+
+      <!-- Cross-section search for the story item by id -->
+      <action>Search for item with id == {{story_key}} across BOTH backlog and sprints sections:
+        1. Search all sprints map entries (active sprints first, then planning; skip closed sprints entirely):
+           - Iterate each non-closed sprint's items array, match item.id == {{story_key}}
+        2. If not found in any sprint, search backlog array:
+           - Iterate items, match item.id == {{story_key}}
+        3. When item is found: update {{location_context}} = sprint id (e.g., "in sprint-3") or "in backlog (unassigned)"
+        4. If not found in either location: output error and exit workflow without writing
+      </action>
 
-    <check if="{sprint_status} file does NOT exist OR {{current_sprint_status}} == 'no-sprint-tracking'">
-      <output>ℹ️ Story status updated to "review" in story file (no sprint tracking configured)</output>
-    </check>
+      <check if="item found">
+        <check if="item.status is NOT 'in-progress'">
+          <output>⚠️ Warning: Story {{story_key}} has status "{{item.status}}", expected "in-progress". Updating to "review" anyway — verify this is intentional.</output>
+        </check>
+        <action>Update item.status = "review" in-place (preserve all other fields: id, type, epic, title, priority if present, severity)</action>
+        <action>Update last_updated metadata field to current ISO-8601 timestamp</action>
+        <action>Write back the FULL file preserving ALL sections (epics, backlog, sprints) and ALL comments</action>
+        <output>Story status updated to "review" in sprint-status.yaml ({{location_context}})</output>
+      </check>
 
-    <check if="story key not found in sprint status">
-      <output>⚠️ Story file updated, but sprint-status update failed: {{story_key}} not found
+      <check if="item NOT found">
+        <!-- Non-blocking warning — story file already updated to "review" above -->
+        <output>Story file updated to "review", but sprint-status.yaml update failed: {{story_key}} not found.
+          Sprint-status.yaml may be out of sync.
+        </output>
+      </check>
+    </check>
 
-        Story status is set to "review" in file, but sprint-status.yaml may be out of sync.
-      </output>
+    <check if="{sprint_status} file does NOT exist OR {{current_sprint_status}} == 'no-sprint-tracking'">
+      <output>Story status updated to "review" in story file (no sprint tracking configured)</output>
     </check>
 
     <!-- Final validation gates -->
@@ -440,7 +499,7 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
       - Optional: If Test Architect module installed, run `/bmad:tea:automate` to expand guardrail tests
     </action>
 
-    <output>💡 **Tip:** For best results, run `code-review` using a **different** LLM than the one that implemented this story.</output>
+    <output>Tip: For best results, run `code-review` using a **different** LLM than the one that implemented this story.</output>
     <check if="{sprint_status} file exists">
       <action>Suggest checking {sprint_status} to see project progress</action>
     </check>

package/lib/bmad-extension/skills/bmad-ma-agent-mil498/SKILL.md

@@ -44,7 +44,8 @@ You must fully embody this agent's persona and follow all activation instruction
 | 7 | SS | Generate SSS: System/Subsystem Specification | "generate sss", "sss" | mil498-sss |
 | 8 | GT | Generate STD: Software Test Description | "generate std", "std" | mil498-std |
 | 9 | SD | Generate SSDD: System/Subsystem Design Description | "generate ssdd", "ssdd" | mil498-ssdd |
-| 10 | DA | Dismiss Agent | "dismiss", "exit", "quit" | _(built-in)_ |
+| 10 | RQ | Review Requirements Quality | "review requirements", "requirement quality", "rq" | mil498-requirement-quality |
+| 11 | DA | Dismiss Agent | "dismiss", "exit", "quit" | _(built-in)_ |
 
 ## Critical Actions
 1. Read the skills MANIFEST at {project-root}/_bmad/skills/mil498/MANIFEST.yaml

package/lib/bmad-extension/skills/bmad-sprint-planning/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: bmad-sprint-planning
+description: 'Bootstrap or update the unified sprint-status.yaml from epics. Use when the user says "run sprint planning" or "generate sprint plan"'
+---
+
+Follow the instructions in ./workflow.md.

package/{.opencode/skills/create-bug-story → lib/bmad-extension/skills/bmad-sprint-planning}/bmad-skill-manifest.yaml

@@ -1,3 +1,3 @@
 type: skill
-name: create-bug-story
+name: bmad-sprint-planning
 module: ma-skills

package/lib/bmad-extension/skills/bmad-sprint-planning/checklist.md

@@ -0,0 +1,74 @@
+# Sprint Planning Validation Checklist
+
+## Core Validation — Unified Three-Section Schema
+
+### File Structure
+
+- [ ] File is valid YAML syntax
+- [ ] Exactly 6 metadata fields present: `generated`, `last_updated`, `project`, `project_key`, `tracking_system`, `story_location`
+- [ ] Exactly 3 data sections: `epics` (map), `backlog` (array), `sprints` (map)
+- [ ] No `development_status` section present (old flat format must not appear)
+
+### Epics Section Validation
+
+- [ ] Every epic found in `epics.md` (or sharded epic files) has a corresponding entry in the `epics` section
+- [ ] Every epic entry has both `status` and `retrospective` fields
+- [ ] All epic `status` values are legal: `backlog`, `in-progress`, `done`, `on-hold`, `cancelled`
+- [ ] All epic `retrospective` values are legal: `optional`, `done`, or `null`
+- [ ] Epic keys follow the pattern `epic-N` (e.g., `epic-1`, `epic-17`)
+- [ ] Epic statuses were not downgraded from existing values (never-downgrade rule applied)
+
+### Backlog Section Validation
+
+- [ ] Every story in `epics.md` appears in exactly one location: `backlog` array, a sprint's `items` array, or `done/` folder
+- [ ] No item ID appears in more than one active location (single-location invariant)
+- [ ] Every backlog item has all 7 required fields: `id`, `type`, `epic`, `title`, `priority`, `status`, `severity`
+- [ ] `type` is either `story` or `bug` for every item
+- [ ] `severity` is `null` for all story items
+- [ ] Bug items have a non-null `severity` value (`critical`, `high`, `medium`, or `low`)
+- [ ] All item `status` values are legal: `backlog`, `ready-for-dev`, `in-progress`, `review`, `done`, `on-hold`, `cancelled`
+- [ ] Backlog `priority` values are sequential integers starting at 1 (position 0 = `priority: 1`)
+- [ ] `priority` field values match array position (array[0].priority == 1, array[1].priority == 2, etc.)
+- [ ] Done items (in `done/` folder) are NOT present in the backlog array
+- [ ] Existing backlog items are preserved unchanged (refresh mode: status, priority, all fields preserved)
+- [ ] New items are appended at the end of the backlog (refresh mode)
+
+### Sprints Section Validation
+
+- [ ] `sprints` section is present (may be empty map `{}`)
+- [ ] Sprint keys follow the pattern `sprint-N`
+- [ ] Every sprint entry has all 6 required fields: `name`, `status`, `capacity`, `start`, `end`, `items`
+- [ ] Sprint items do NOT have a `priority` field (priority is backlog-only)
+- [ ] At most one sprint has `status: active`
+- [ ] Sprints section is unchanged from existing file (refresh mode — this skill does NOT modify sprints)
+
+### Metadata Validation
+
+- [ ] `generated` timestamp is present and in ISO-8601 format
+- [ ] `last_updated` timestamp is present and set to current time
+- [ ] `generated` timestamp is unchanged from existing file (refresh mode — never overwritten)
+- [ ] `project` matches `project_name` from config
+- [ ] `project_key` is set (default: `NOKEY`)
+- [ ] `tracking_system` is `file-system` (or a valid alternative)
+- [ ] `story_location` matches `implementation_artifacts` path from config
+
+### Parsing Verification
+
+Compare epic files against generated sprint-status.yaml epics section:
+
+```
+Epic Files Contains:                Sprint Status epics Contains:
+✓ Epic 1: Some Feature              ✓ epic-1: {status: backlog, retrospective: optional}
+  ✓ Story 1.1: User Auth              ✓ 1-1-user-auth in backlog or sprint or done/
+  ✓ Story 1.2: Account Mgmt           ✓ 1-2-account-mgmt in backlog or sprint or done/
+✓ Epic 2: Another Feature           ✓ epic-2: {status: backlog, retrospective: optional}
+  ✓ Story 2.1: Personality Model      ✓ 2-1-personality-model in backlog or sprint or done/
+```
+
+Note: Unlike the old format, each epic does NOT have a separate retrospective key — retrospective is a field on the epic entry.
+
+### Final Count Check
+
+- [ ] Total count of epics in `epics` section matches count in epic files
+- [ ] Total count of stories in `backlog` + all sprints + `done/` folder matches count in epic files
+- [ ] Total count of bugs in `backlog` + all sprints + `done/` folder matches count of `bug-*.md` files

package/lib/bmad-extension/skills/bmad-sprint-planning/sprint-status-template.yaml

@@ -0,0 +1,89 @@
+# Sprint Status Template
+# This is an EXAMPLE showing the unified three-section schema format.
+# The actual file will be generated/refreshed from your epics and bug files.
+#
+# Schema version: 1.0 (Story 17.9)
+# Architecture: Decision P2-11
+#
+# SECTIONS:
+#   epics   — map keyed by epic-N; regenerated each planning run (with status preservation)
+#   backlog — array of items (stories + bugs); additive — new items appended, existing preserved
+#   sprints — map keyed by sprint-N; NEVER modified by this skill
+#
+# STATUS DEFINITIONS:
+# ===================
+# Epic Status:   backlog → in-progress → done  (on-hold: bidirectional; cancelled: terminal)
+# Item Status:   backlog → ready-for-dev → in-progress → review → done
+#                (on-hold: bidirectional pause; cancelled: terminal)
+# Retrospective: optional → done  (null: not applicable)
+
+generated: "2026-01-15T10:00:00Z"
+last_updated: "2026-01-15T10:00:00Z"
+project: "Example Project"
+project_key: NOKEY
+tracking_system: file-system
+story_location: "_bmad-output/implementation-artifacts"
+
+# ── Epics ──────────────────────────────────────────────────────────────────────
+# Map keyed by epic-N. Fully regenerated each run; epic statuses are never downgraded.
+epics:
+  epic-1:
+    status: in-progress
+    retrospective: optional
+  epic-2:
+    status: backlog
+    retrospective: optional
+  epic-3:
+    status: on-hold
+    retrospective: null
+
+# ── Backlog ───────────────────────────────────────────────────────────────────
+# Ordered array — position 0 = highest priority. Priority field must match position.
+# Only items NOT in a sprint and NOT archived in done/ appear here.
+backlog:
+  - id: "1-2-account-management"
+    type: story
+    epic: 1
+    title: "Account Management"
+    priority: 1
+    status: ready-for-dev
+    severity: null
+  - id: "BUG-login-crash"
+    type: bug
+    epic: null
+    title: "Fix login crash on empty password"
+    priority: 2
+    status: backlog
+    severity: critical
+  - id: "2-1-personality-system"
+    type: story
+    epic: 2
+    title: "Personality System"
+    priority: 3
+    status: backlog
+    severity: null
+  - id: "2-2-chat-interface"
+    type: story
+    epic: 2
+    title: "Chat Interface"
+    priority: 4
+    status: backlog
+    severity: null
+
+# ── Sprints ───────────────────────────────────────────────────────────────────
+# Map keyed by sprint-N. This skill NEVER modifies the sprints section.
+# Use add-sprint, add-to-sprint, modify-sprint, close-sprint to manage sprints.
+sprints:
+  sprint-1:
+    name: "Sprint 1 — Foundation"
+    status: active
+    capacity: 4
+    start: "2026-01-15"
+    end: "2026-01-28"
+    items:
+      - id: "1-1-user-authentication"
+        type: story
+        epic: 1
+        title: "User Authentication"
+        status: in-progress
+        severity: null