bmad-method 6.8.1-next.9 → 6.9.0

package/src/bmm-skills/3-solutioning/bmad-architecture/scripts/tests/test_lint_spine.py

@@ -0,0 +1,270 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["pytest>=8.0"]
+# ///
+"""Tests for lint_spine.py. Run: uv run --with pytest pytest scripts/tests/test_lint_spine.py
+
+The spine under test: a clean spine lints empty; the linter catches exactly the
+mechanical defects a prompt is unreliable at — literal placeholders, AD-n id breakage,
+AD-n blocks missing required fields, and unpinned Stack versions.
+"""
+import importlib.util
+import json
+import re
+import sys
+from pathlib import Path
+
+import pytest
+
+_SPEC = importlib.util.spec_from_file_location(
+    "lint_spine", Path(__file__).resolve().parent.parent / "lint_spine.py"
+)
+lint_spine = importlib.util.module_from_spec(_SPEC)
+sys.modules["lint_spine"] = lint_spine
+_SPEC.loader.exec_module(lint_spine)
+
+
+CLEAN = """---
+name: 'Demo'
+---
+
+## Invariants & Rules
+
+### AD-1 — single write path
+
+- **Binds:** all
+- **Prevents:** divergent mutation
+- **Rule:** state changes only through the command bus
+
+### AD-2 — layered deps `[ADOPTED]`
+
+- **Binds:** all
+- **Prevents:** import cycles
+- **Rule:** ui -> app -> domain, never backward
+
+```mermaid
+flowchart LR
+  A --> B{decision}
+```
+
+## Stack
+
+| Name | Version |
+| --- | --- |
+| fastapi | 0.115 |
+| pydantic | 2.9 |
+"""
+
+
+def cats(result):
+    return sorted(f["category"] for f in result["findings"])
+
+
+def test_clean_spine_passes():
+    result = lint_spine.lint(CLEAN)
+    assert result["ok"] is True
+    assert result["total_findings"] == 0
+
+
+def test_mermaid_braces_not_flagged():
+    # the {decision} node lives in a fenced block and must not read as a template token
+    result = lint_spine.lint(CLEAN)
+    assert "placeholder" not in cats(result)
+
+
+def test_placeholder_markers_caught():
+    text = CLEAN.replace("the command bus", "TBD")
+    result = lint_spine.lint(text)
+    assert "placeholder" in cats(result)
+
+
+def test_similar_to_caught():
+    text = CLEAN.replace("import cycles", "similar to AD-1")
+    result = lint_spine.lint(text)
+    assert any("cross-reference" in f["detail"] for f in result["findings"])
+
+
+def test_unfilled_template_token_caught():
+    text = CLEAN.replace("single write path", "{decision}")
+    result = lint_spine.lint(text)
+    assert any(f["category"] == "placeholder" for f in result["findings"])
+
+
+def test_duplicate_ad_id_caught():
+    text = CLEAN.replace("### AD-2 — layered deps `[ADOPTED]`", "### AD-1 — layered deps")
+    result = lint_spine.lint(text)
+    assert "ad_id" in cats(result)
+
+
+def test_non_monotonic_ad_id_caught():
+    text = CLEAN.replace("### AD-2 — layered deps `[ADOPTED]`", "### AD-5 — layered deps").replace(
+        "### AD-1 — single write path", "### AD-9 — single write path"
+    )
+    result = lint_spine.lint(text)
+    assert any("non-monotonic" in f["detail"] for f in result["findings"])
+
+
+def test_missing_field_caught():
+    text = CLEAN.replace("- **Rule:** state changes only through the command bus\n", "")
+    result = lint_spine.lint(text)
+    assert any(f["category"] == "ad_fields" and "rule" in f["detail"] for f in result["findings"])
+
+
+def test_unpinned_dep_caught():
+    text = CLEAN.replace("| fastapi | 0.115 |", "| fastapi |  |")
+    result = lint_spine.lint(text)
+    assert "version_pin" in cats(result)
+
+
+def test_placeholder_version_caught():
+    text = CLEAN.replace("| fastapi | 0.115 |", "| fastapi | {pin} |")
+    result = lint_spine.lint(text)
+    assert any(f["category"] == "version_pin" and "fastapi" in f["detail"] for f in result["findings"])
+
+
+def test_no_stack_section_ok():
+    text = CLEAN.split("## Stack")[0]
+    result = lint_spine.lint(text)
+    assert "version_pin" not in cats(result)
+
+
+def test_stack_skeleton_row_not_version_pinned():
+    # a leftover {token} name is the placeholder pass's job, not a double-reported version_pin
+    text = CLEAN.replace("| fastapi | 0.115 |", "| {language / framework} | {pinned version} |")
+    result = lint_spine.lint(text)
+    assert "version_pin" not in cats(result)
+
+
+def test_stack_html_comment_not_parsed_as_row():
+    text = CLEAN.replace("## Stack\n", "## Stack\n\n<!-- SEED — verified current 2026-06 -->\n")
+    result = lint_spine.lint(text)
+    assert "version_pin" not in cats(result)
+
+
+def test_template_token_is_low_severity():
+    # a bare {token} can be legitimate brace prose; it is flagged, but low (not high) so the
+    # mechanical pass stays near-zero false-positive
+    text = CLEAN.replace("single write path", "{decision}")
+    result = lint_spine.lint(text)
+    toks = [f for f in result["findings"] if f["category"] == "placeholder" and "template token" in f["detail"]]
+    assert toks and all(f["severity"] == "low" for f in toks)
+
+
+def test_no_frontmatter_body_still_scanned():
+    text = "## Invariants\n\n### AD-1 — x\n\n- **Binds:** all\n- **Prevents:** drift\n- **Rule:** TBD\n"
+    result = lint_spine.lint(text)
+    assert "placeholder" in cats(result)  # TBD caught even with no frontmatter
+
+
+def test_frontmatter_value_with_dashes_not_truncated():
+    # a value containing '---' must not be read as the closing fence (line-exact close)
+    text = ("---\nname: 'x'\nscope: 'phase 1 --- phase 2'\n---\n\n"
+            "## Stack\n\n| Name | Version |\n| --- | --- |\n| fastapi |  |\n")
+    result = lint_spine.lint(text)
+    assert any(f["category"] == "version_pin" for f in result["findings"])  # read past the inline ---
+
+
+def test_ad_heading_in_fence_not_counted():
+    text = (
+        "---\nname: 'x'\n---\n\n"
+        "### AD-1 — real\n\n- **Binds:** all\n- **Prevents:** drift\n- **Rule:** do x\n\n"
+        "## Docs\n\n```text\n### AD-2 — illustrative only, no fields\n```\n"
+    )
+    result = lint_spine.lint(text)
+    assert result["ok"] is True  # the fenced AD-2 is not a live AD → no ad_fields/ad_id finding
+
+
+def test_stack_table_flags_only_the_unpinned_row():
+    text = ("---\nname: 'x'\n---\n\n## Stack\n\n| Name | Version |\n| --- | --- |\n"
+            "| fastapi | 0.115 |\n| redis |  |\n")
+    result = lint_spine.lint(text)
+    pins = [f for f in result["findings"] if f["category"] == "version_pin"]
+    assert len(pins) == 1 and "redis" in pins[0]["detail"]
+
+
+def test_stack_table_all_pinned_ok():
+    text = ("---\nname: 'x'\n---\n\n## Stack\n\n| Name | Version |\n| --- | --- |\n"
+            "| fastapi | 0.115 |\n")
+    result = lint_spine.lint(text)
+    assert "version_pin" not in cats(result)
+
+
+def test_fenced_stack_rows_not_parsed():
+    # an illustrative fenced table under ## Stack must not be read as live rows (fences are
+    # blanked first, like every other pass) — a blank-version row inside a fence is not a finding
+    text = ("---\nname: 'x'\n---\n\n## Stack\n\n| Name | Version |\n| --- | --- |\n"
+            "| fastapi | 0.115 |\n\n```text\n| example |  |\n```\n")
+    result = lint_spine.lint(text)
+    assert "version_pin" not in cats(result)
+
+
+def test_fenced_stack_heading_not_live():
+    # a `## Stack` heading shown inside a code fence is not the live Stack section
+    text = ("---\nname: 'x'\n---\n\n## Docs\n\n```md\n## Stack\n\n| foo |  |\n```\n")
+    result = lint_spine.lint(text)
+    assert "version_pin" not in cats(result)
+
+
+def test_renamed_stack_heading_still_scanned():
+    # the heading match is word-boundary, so a varied `## Stack` heading still counts
+    text = ("---\nname: 'x'\n---\n\n## Stack & Versions\n\n| Name | Version |\n| --- | --- |\n"
+            "| redis |  |\n")
+    result = lint_spine.lint(text)
+    pins = [f for f in result["findings"] if f["category"] == "version_pin"]
+    assert len(pins) == 1 and "redis" in pins[0]["detail"]
+
+
+def test_reordered_columns_pair_name_to_version():
+    # Version-then-Name header: the unpinned row must still be flagged by its real name
+    text = ("---\nname: 'x'\n---\n\n## Stack\n\n| Version | Name |\n| --- | --- |\n"
+            "| 0.115 | fastapi |\n|  | redis |\n")
+    result = lint_spine.lint(text)
+    pins = [f for f in result["findings"] if f["category"] == "version_pin"]
+    assert len(pins) == 1 and "redis" in pins[0]["detail"]
+
+
+def test_placeholder_line_number_is_absolute():
+    # a TBD after a multi-line fence reports its real file line (fence blanked, not collapsed)
+    text = (
+        "---\nname: 'x'\n---\n\n"
+        "## A\n\n"
+        "```text\nf1\nf2\nf3\n```\n\n"
+        "TBD here\n"
+    )
+    result = lint_spine.lint(text)
+    ph = next(f for f in result["findings"] if "TBD" in f["detail"])
+    n = int(re.search(r"line (\d+)", ph["location"]).group(1))
+    assert n == 13
+
+
+def test_missing_spine_file_reports_error(tmp_path, capsys):
+    rc = lint_spine.main(["--workspace", str(tmp_path)])
+    out = json.loads(capsys.readouterr().out)
+    assert rc == 0 and out["ok"] is False and "not found" in out["error"]
+
+
+def test_frontmatter_unfilled_token_caught():
+    # an unfilled {scope}/{paradigm}/{date} in frontmatter is part of the contract and must lint
+    text = "---\nname: 'x'\nscope: '{what this spine governs}'\n---\n\n## Invariants\n"
+    result = lint_spine.lint(text)
+    fm = [f for f in result["findings"] if f["category"] == "placeholder" and "frontmatter" in f["detail"]]
+    assert fm and any("template token" in f["detail"] for f in fm)
+
+
+def test_frontmatter_tbd_caught():
+    text = "---\nname: 'x'\nstatus: TBD\n---\n\n## Invariants\n"
+    result = lint_spine.lint(text)
+    assert any(f["category"] == "placeholder" and "frontmatter" in f["detail"] and "TBD" in f["detail"]
+               for f in result["findings"])
+
+
+def test_unreadable_spine_returns_error_not_crash(tmp_path, capsys):
+    # a spine that exists but can't be UTF-8 decoded must yield error JSON + exit 0, not a traceback
+    (tmp_path / lint_spine.SPINE).write_bytes(b"\xff\xfe bad bytes not utf-8")
+    rc = lint_spine.main(["--workspace", str(tmp_path)])
+    out = json.loads(capsys.readouterr().out)
+    assert rc == 0 and out["ok"] is False and "could not read" in out["error"]
+
+
+if __name__ == "__main__":
+    sys.exit(pytest.main([__file__, "-q"]))

package/src/bmm-skills/3-solutioning/bmad-create-architecture/SKILL.md

@@ -1,74 +1,30 @@
 ---
 name: bmad-create-architecture
-description: 'Create architecture solution design decisions for AI agent consistency. Use when the user says "lets create architecture" or "create technical architecture" or "create a solution design"'
+description: 'DEPRECATED — consolidated into bmad-architecture create intent - this skill will be removed in v7 in favor of `bmad-architecture`.'
 ---
 
-# Architecture Workflow
+# DEPRECATED — forwards to bmad-architecture (create intent)
 
-**Goal:** Create comprehensive architecture decisions through collaborative step-by-step discovery that ensures AI agents implement consistently.
-
-**Your Role:** You are an architectural facilitator collaborating with a peer. This is a partnership, not a client-vendor relationship. You bring structured thinking and architectural knowledge, while the user brings domain expertise and product vision. Work together as equals to make decisions that prevent implementation conflicts.
-
-## Conventions
-
-- Bare paths (e.g. `steps/step-01-init.md`) resolve from the skill root.
-- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
-- `{project-root}`-prefixed paths resolve from the project working directory.
-- `{skill-name}` resolves to the skill directory's basename.
-
-## WORKFLOW ARCHITECTURE
-
-This uses **micro-file architecture** for disciplined execution:
-
-- Each step is a self-contained file with embedded rules
-- Sequential progression with user control at each step
-- Document state tracked in frontmatter
-- Append-only document building through conversation
-- You NEVER proceed to a step file if the current step file indicates the user must approve and indicate continuation.
+This skill was consolidated into `bmad-architecture`. It is retained as a thin compatibility shim so existing invocations by name and `_bmad/custom/bmad-create-architecture.toml` override files keep working. New work should invoke `bmad-architecture` directly — it detects create / update / validate intent from the conversation.
 
 ## On Activation
 
-### Step 1: Resolve the Workflow Block
-
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
-
-**If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
-
-1. `{skill-root}/customize.toml` — defaults
-2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides
-3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides
-
-Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.
-
-### Step 2: Execute Prepend Steps
-
-Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding.
-
-### Step 3: Load Persistent Facts
-
-Treat every entry in `{workflow.persistent_facts}` as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim.
-
-### Step 4: Load Config
-
-Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
-- Use `{user_name}` for greeting
-- Use `{communication_language}` for all communications
-- Use `{document_output_language}` for output documents
-- Use `{planning_artifacts}` for output location and artifact scanning
-- Use `{project_knowledge}` for additional context scanning
-
-### Step 5: Greet the User
-
-Greet `{user_name}`, speaking in `{communication_language}`.
+1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. This picks up any `{project-root}/_bmad/custom/bmad-create-architecture.toml` and `bmad-create-architecture.user.toml` overrides for the legacy fields (`activation_steps_prepend`, `activation_steps_append`, `persistent_facts`, `on_complete`).
 
-### Step 6: Execute Append Steps
+2. Load `{project-root}/_bmad/bmm/config.yaml` (and `config.user.yaml` if present) to resolve `{user_name}` and `{communication_language}`.
 
-Execute each entry in `{workflow.activation_steps_append}` in order.
+3. Emit a deprecation notice to the user in `{communication_language}`:
 
-Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
+   > Notice: `bmad-create-architecture` is deprecated and will be removed in a future release. It now forwards to `bmad-architecture` with create intent. To silence this notice and access the full new customization surface (`spine_template`, `spine_output_path`, `run_folder_pattern`, `doc_standards`, `external_sources`, `external_handoffs`, `finalize_reviewers`), migrate `_bmad/custom/bmad-create-architecture.toml` to `_bmad/custom/bmad-architecture.toml` and invoke `bmad-architecture` directly next time. Customization fields that were in this version still remain in the new version and will be respected if present in `_bmad/custom/bmad-architecture.toml`, but the new version also supports additional fields that you can take advantage of by migrating.
 
-## Execution
+4. Invoke `bmad-architecture` with the following context. Pass these as the activating context so `bmad-architecture` honors them instead of resolving its own customization from scratch:
 
-Read fully and follow: `./steps/step-01-init.md` to begin the workflow.
+   - **Intent:** `create` — skip `bmad-architecture`'s usual intent detection step.
+   - **Pre-resolved legacy customization** — use these in place of resolving from `bmad-architecture`'s own `customize.toml` for the four legacy fields. For everything else (`spine_template`, `spine_output_path`, `run_folder_pattern`, `doc_standards`, `external_sources`, `external_handoffs`, `finalize_reviewers`), use `bmad-architecture`'s own defaults and overrides as normal:
+     - `activation_steps_prepend` = the resolved value from step 1
+     - `activation_steps_append` = the resolved value from step 1
+     - `persistent_facts` = the resolved value from step 1
+     - `on_complete` = the resolved value from step 1
+   - **Original user input:** forward whatever the user said when invoking this skill verbatim.
 
-**Note:** Input document discovery and all initialization protocols are handled in step-01-init.md.
+   `bmad-architecture` takes the workflow from here. Do not execute any further steps in this shim.

package/src/bmm-skills/4-implementation/bmad-retrospective/SKILL.md

@@ -350,6 +350,7 @@ Amelia (Developer): "I found our retrospectives from Epic {{prev_epic_num}}. Let
 
     **Action Item Follow-Through:**
     - For each action item from Epic {{prev_epic_num}} retro, check if it was completed
+    - Cross-check the action_items section in {sprint_status_file} (if present) for Epic {{prev_epic_num}} entries and their current status
     - Look for evidence in current epic's story records
     - Mark each action item: ✅ Completed, ⏳ In Progress, ❌ Not Addressed
 
@@ -1403,6 +1404,19 @@ Amelia (Developer): "See you all when prep work is done. Meeting adjourned!"
 <action>Find development_status key "epic-{{epic_number}}-retrospective"</action>
 <action>Verify current status (typically "optional" or "pending")</action>
 <action>Update development_status["epic-{{epic_number}}-retrospective"] = "done"</action>
+<action>Append each Epic {{epic_number}} action item to the action_items section, creating the section after development_status if missing. One entry per item:</action>
+
+```yaml
+action_items:
+  - epic: {{epic_number}}
+    action: "{{action_description}}"
+    owner: "{{owner}}"
+    status: open
+```
+
+<action>Quote action and owner values so punctuation (e.g., "#") cannot break YAML parsing</action>
+
+<action>Update Epic {{prev_epic_num}} action_items entries based on Step 4 follow-through: ✅ Completed → done, ⏳ In Progress → in-progress, ❌ Not Addressed → keep existing status (do not modify)</action>
 <action>Update last_updated field to current date</action>
 <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
 
@@ -1412,6 +1426,7 @@ Amelia (Developer): "See you all when prep work is done. Meeting adjourned!"
 
 Retrospective key: epic-{{epic_number}}-retrospective
 Status: {{previous_status}} → done
+Action items recorded: {{action_count}}
 </output>
 </check>
 

package/src/bmm-skills/4-implementation/bmad-sprint-planning/SKILL.md

@@ -151,6 +151,7 @@ development_status:
 
 - If existing `{status_file}` exists and has more advanced status, preserve it
 - Never downgrade status (e.g., don't change `done` to `ready-for-dev`)
+- If existing `{status_file}` has an `action_items` section, carry it over unchanged
 
 **Status Flow Reference:**
 
@@ -194,12 +195,18 @@ development_status:
 #   - optional: Can be completed but not required
 #   - done: Retrospective has been completed
 #
+# Action Item Status:
+#   - open: Committed during a retrospective, not yet addressed
+#   - in-progress: Actively being worked on
+#   - done: Completed
+#
 # WORKFLOW NOTES:
 # ===============
 # - Epic transitions to 'in-progress' automatically when first story is created
 # - Stories can be worked in parallel if team capacity allows
 # - Developer typically creates next story after previous one is 'done' to incorporate learnings
 # - Dev moves story to 'review', then runs code-review (fresh context, different LLM recommended)
+# - Retrospective appends its action items to action_items; sprint-status surfaces open ones
 
 generated: { date }
 last_updated: { date }
@@ -215,6 +222,7 @@ development_status:
 <action>Write the complete sprint status YAML to {status_file}</action>
 <action>CRITICAL: Metadata appears TWICE - once as comments (#) for documentation, once as YAML key:value fields for parsing</action>
 <action>Ensure all items are ordered: epic, its stories, its retrospective, next epic...</action>
+<action>If the existing file had an action_items section, write it back unchanged after development_status</action>
 </step>
 
 <step n="5" goal="Validate and report">
@@ -223,7 +231,8 @@ development_status:
 - [ ] Every epic in epic files appears in {status_file}
 - [ ] Every story in epic files appears in {status_file}
 - [ ] Every epic has a corresponding retrospective entry
-- [ ] No items in {status_file} that don't exist in epic files
+- [ ] No development_status items in {status_file} that don't exist in epic files
+- [ ] action_items section (if it existed) carried over unchanged
 - [ ] All status values are legal (match state machine definitions)
 - [ ] File is valid YAML syntax
 
@@ -291,6 +300,16 @@ optional ↔ done
 - **optional**: Ready to be conducted but not required
 - **done**: Finished
 
+**Action Item Status:**
+
+```
+open → in-progress → done
+```
+
+- **open**: Committed during a retrospective, not yet addressed
+- **in-progress**: Actively being worked on
+- **done**: Completed
+
 ### Guidelines
 
 1. **Epic Activation**: Mark epic as `in-progress` when starting work on its first story

package/src/bmm-skills/4-implementation/bmad-sprint-planning/checklist.md

@@ -7,7 +7,8 @@
 - [ ] Every epic found in epic\*.md files appears in sprint-status.yaml
 - [ ] Every story found in epic\*.md files appears in sprint-status.yaml
 - [ ] Every epic has a corresponding retrospective entry
-- [ ] No items in sprint-status.yaml that don't exist in epic files
+- [ ] No development_status items in sprint-status.yaml that don't exist in epic files
+- [ ] action_items section (if it existed) carried over unchanged
 
 ### Parsing Verification
 

package/src/bmm-skills/4-implementation/bmad-sprint-planning/sprint-status-template.yaml

@@ -26,11 +26,17 @@
 #   - optional: Can be completed but not required
 #   - done: Retrospective has been completed
 #
+# Action Item Status:
+#   - open: Committed during a retrospective, not yet addressed
+#   - in-progress: Actively being worked on
+#   - done: Completed
+#
 # WORKFLOW NOTES:
 # ===============
 # - Mark epic as 'in-progress' when starting work on its first story
 # - Developer typically creates next story ONLY after previous one is 'done' to incorporate learnings
 # - Dev moves story to 'review', then Dev runs code-review (fresh context, ideally different LLM)
+# - Retrospective appends its action items to action_items; sprint-status surfaces open ones
 
 # EXAMPLE STRUCTURE (your actual epics/stories will replace these):
 
@@ -54,3 +60,10 @@ development_status:
   2-2-chat-interface: backlog
   2-3-llm-integration: backlog
   epic-2-retrospective: optional
+
+# Action items committed during retrospectives (section created by the retrospective workflow)
+action_items:
+  - epic: 1
+    action: "Add error-handling review to the code review checklist"
+    owner: "Charlie"
+    status: open

package/src/bmm-skills/4-implementation/bmad-sprint-status/SKILL.md

@@ -112,12 +112,14 @@ Run `/bmad:bmm:workflows:sprint-planning` to generate it, then rerun sprint-stat
   <action>Map legacy epic status "contexted" → "in-progress"</action>
   <action>Count epic statuses: backlog, in-progress, done</action>
   <action>Count retrospective statuses: optional, done</action>
+  <action>Parse action_items list if present. Set open_action_items = entries with status "open" or "in-progress"</action>
 
 <action>Validate all statuses against known values:</action>
 
 - Valid story statuses: backlog, ready-for-dev, in-progress, review, done, drafted (legacy)
 - Valid epic statuses: backlog, in-progress, done, contexted (legacy)
 - Valid retrospective statuses: optional, done
+- Valid action item statuses: open, in-progress, done
 
   <check if="any status is unrecognized">
     <output>
@@ -132,6 +134,7 @@ Run `/bmad:bmm:workflows:sprint-planning` to generate it, then rerun sprint-stat
 - Stories: backlog, ready-for-dev, in-progress, review, done
 - Epics: backlog, in-progress, done
 - Retrospectives: optional, done
+- Action items: open, in-progress, done
   </output>
   <ask>How should these be corrected?
   {{#each invalid_entries}}
@@ -181,6 +184,14 @@ Enter corrections (e.g., "1=in-progress, 2=backlog") or "skip" to continue witho
 
 **Next Recommendation:** /bmad:bmm:workflows:{{next_workflow_id}} ({{next_story_id}})
 
+{{#if open_action_items}}
+**Open Action Items:**
+{{#each open_action_items}}
+
+- {{action}} — {{status}} (epic {{epic}}, owner: {{owner}})
+  {{/each}}
+  {{/if}}
+
 {{#if risks}}
 **Risks:**
 {{#each risks}}
@@ -243,6 +254,7 @@ If the command targets a story, set `story_key={{next_story_id}}` when prompted.
   <template-output>epic_backlog = {{epic_backlog}}</template-output>
   <template-output>epic_in_progress = {{epic_in_progress}}</template-output>
   <template-output>epic_done = {{epic_done}}</template-output>
+  <template-output>open_action_items = {{open_action_items}}</template-output>
   <template-output>risks = {{risks}}</template-output>
   <action>Return to caller</action>
 </step>
@@ -283,6 +295,7 @@ If the command targets a story, set `story_key={{next_story_id}}` when prompted.
 - Stories: backlog, ready-for-dev, in-progress, review, done (legacy: drafted)
 - Epics: backlog, in-progress, done (legacy: contexted)
 - Retrospectives: optional, done
+- Action items (if present): open, in-progress, done
   <check if="any invalid status found">
   <template-output>is_valid = false</template-output>
   <template-output>error = "Invalid status values: {{invalid_entries}}"</template-output>

package/src/bmm-skills/module-help.csv

@@ -17,8 +17,8 @@ BMad Method,bmad-product-brief,Create Brief,CB,An expert guided experience to na
 BMad Method,bmad-prfaq,PRFAQ Challenge,WB,Working Backwards guided experience to forge and stress-test your product concept to ensure you have a great product that users will love and need through the PRFAQ gauntlet to determine feasibility and alignment with user needs. alternative to product brief.,,-H,1-analysis,,,false,planning_artifacts,prfaq document
 BMad Method,bmad-prd,Create Edit and Review PRD,PRD,"Facilitated PRD workflow — create a new PRD via coached discovery, update an existing one against a change signal, or validate a finished PRD against a checklist with an HTML findings report.",,,2-planning,bmad-product-brief,,true,planning_artifacts,prd
 BMad Method,bmad-ux,Create UX,CU,"Guidance through realizing the plan for your UX, strongly recommended if a UI is a primary piece of the proposed project.",,,2-planning,bmad-prd,,false,planning_artifacts,ux design
-BMad Method,bmad-create-architecture,Create Architecture,CA,Guided workflow to document technical decisions.,,,3-solutioning,,,true,planning_artifacts,architecture
-BMad Method,bmad-create-epics-and-stories,Create Epics and Stories,CE,,,,3-solutioning,bmad-create-architecture,,true,planning_artifacts,epics and stories
+BMad Method,bmad-architecture,Architecture,CA,Offer once requirements exist (a PRD or spec; plus UX if present) and the user is ready to move from what to how. Also offer any time independently-built parts risk diverging. Produces the architecture spine: the invariants that keep features epics and stories consistent. Comes before epics and stories and scales from a quick spine to a full architecture (brownfield: ratifies the existing codebase).,,,3-solutioning,,,true,planning_artifacts,architecture
+BMad Method,bmad-create-epics-and-stories,Create Epics and Stories,CE,,,,3-solutioning,bmad-architecture,,true,planning_artifacts,epics and stories
 BMad Method,bmad-check-implementation-readiness,Check Implementation Readiness,IR,Ensure PRD UX Architecture and Epics Stories are aligned.,,,3-solutioning,bmad-create-epics-and-stories,,true,planning_artifacts,readiness report
 BMad Method,bmad-sprint-planning,Sprint Planning,SP,Kicks off implementation by producing a plan the implementation agents will follow in sequence for every story.,,,4-implementation,,,true,implementation_artifacts,sprint status
 BMad Method,bmad-sprint-status,Sprint Status,SS,Anytime: Summarize sprint status and route to next workflow.,,,4-implementation,bmad-sprint-planning,,false,,

package/src/core-skills/bmad-brainstorming/SKILL.md

@@ -18,7 +18,7 @@ The session runs in one of three stances, chosen by the user — set explicitly
 
 ## On Activation
 
-1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, use a subagent to read `{skill-root}/customize.toml` directly with defaults.
+1. Resolve customization: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, use a subagent to read `{skill-root}/customize.toml` directly with defaults.
 2. Run each `{workflow.activation_steps_prepend}` entry. Treat each `{workflow.persistent_facts}` entry as foundational context (`file:`-prefixed entries are paths/globs under `{project-root}` — load their contents; others are facts verbatim).
 3. Load `{project-root}/_bmad/core/config.yaml` (and `config.user.yaml` if present); resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{output_folder}`, `{project_name}`, `{date}`. Missing → neutral defaults; never block.
 4. **If launched headless** (a machine signal, not a human asking for output — `references/headless.md` lists them): load `references/headless.md` and follow it for the whole run. It is the *only* context where you generate ideas yourself; never load it otherwise.
@@ -34,21 +34,19 @@ These fight your defaults, in every mode; hold them deliberately. The stance you
 - **Keep shifting the creative domain** — every 5–10 turns (or ~10 ideas when you're generating), usually by moving to the next technique.
 - **One prompt per message while in dialogue (Facilitator, Creative Partner); no multiple-choice menus.** Don't stack questions into a wall or hand a menu that invites lazy picking — both pull the user out of generating. The only exceptions are the two up-front *process* choices (stance, and the technique flow): *how* to run is theirs to pick; *what* to ideate never is.
 
-**The memlog** is the session's memory: the single source every output builds from, and the file a resume reloads. Whatever isn't in it is gone. Log every idea, decision, question, and bit of user direction — anything you'd regret losing if the window closed — one line each, the gist in the user's meaning, in time order; never edit or reorder. Skip your prompts and small talk. All writes go through `scripts/memlog.py` (atomic; don't read it back mid-session — resume is the one exception):
+**The memlog** is the session's memory: the single source every output builds from, and the file a resume reloads. Whatever isn't in it is gone. Log every idea, decision, question, and bit of user direction — anything you'd regret losing if the window closed — one line each, the gist in the user's meaning, in time order; never edit or reorder. Skip your prompts and small talk. All writes to memlog are atomic and use the script `memlog.py` invoked as follows:
 
-- `memlog.py init --workspace {doc_workspace} --field topic="<topic>" --field goal="<goal>" --field mode="<facilitator|partner|autonomous>"` — create it once topic, goal, and stance are known.
-- `memlog.py append --workspace {doc_workspace} --type <kind> --text "<one-line gist>"` — log one entry. `--type` ∈ `idea`/`insight`/`question`/`decision`/`direction`/`technique` (a switch: `--text "started <name>"`); omit for a plain note. Add `--by user`/`--by coach` to mark authorship — **required in Creative Partner mode** (renders `(idea by user)`); skip it otherwise.
-- `memlog.py set --workspace {doc_workspace} --key status --value complete` — flip status at wrap-up.
-
-(Each is `python3 {skill-root}/scripts/memlog.py …`.)
+- `uv run {project-root}/_bmad/scripts/memlog.py init --workspace {doc_workspace} --field topic="<topic>" --field goal="<goal>" --field mode="<facilitator|partner|autonomous>"` — create it once topic, goal, and stance are known.
+- `uv run {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type <kind> --text "<one-line gist>"` — log one entry. `--type` ∈ `idea`/`insight`/`question`/`decision`/`direction`/`technique` (a switch: `--text "started <name>"`); omit for a plain note. Add `--by user`/`--by coach` to mark authorship — **required in Creative Partner mode** (renders `(idea by user)`); skip it otherwise.
+- `uv run {project-root}/_bmad/scripts/memlog.py set --workspace {doc_workspace} --key status --value complete` — flip status at wrap-up.
 
 ## Run a Session
 
-Open with one compound question — **what are we brainstorming, and what's the goal or why behind it?** (plus any inputs or special requests). The why shapes technique choice and synthesis (*kids' iPhone apps to build with your own kids* vs. *to win market share* point different ways). If the kickoff already made both clear, skip the question and confirm; read anything they point you to. Derive a kebab-case `{topic_slug}` and bind `{doc_workspace} = {workflow.output_dir}/{workflow.output_folder_name}/`.
+Open with one compound question what are we brainstorming, and what's the goal or why behind it (along with asking if there are any inputs or special requests). The why shapes technique choice and synthesis (*kids' iPhone apps to build with your own kids* vs. *to win market share* point different ways). If the kickoff already made both clear, skip the question and confirm; read anything they point you to. Derive a kebab-case `{topic_slug}` and bind `{doc_workspace} = {workflow.output_dir}/{workflow.output_folder_name}/`.
 
 Now set the **stance** and the **technique batch** in one step — the composer page does both, so make it the default.
 
-**The composer page (primary).** The file is `{skill-root}/assets/brain-selector.html`. With a customized catalog (overridden `{workflow.brain_methods}` or any `{workflow.additional_techniques}`), regenerate it first: `python3 {skill-root}/scripts/brain.py --file {workflow.brain_methods} [--extra {doc_workspace}/extra-techniques.json] html --out {doc_workspace}/brain-selector.html` (pass `--extra`, a JSON list of `{category, technique_name, description}`, when there are additional techniques; the file is then `{doc_workspace}/brain-selector.html`). Try to open it (`open` / `xdg-open` / `start`), then say, in one message: *"It should open in your browser — compose your session, click **Copy prompt**, and paste the result back. If it didn't open, open `<path>` yourself, or say 'let's do it in chat'."* You can't see their browser, so never claim it opened.
+**The composer page (primary).** The file is `{skill-root}/assets/brain-selector.html`. With a customized catalog (overridden `{workflow.brain_methods}` or any `{workflow.additional_techniques}`), regenerate it first: `uv run {skill-root}/scripts/brain.py --file {workflow.brain_methods} [--extra {doc_workspace}/extra-techniques.json] html --out {doc_workspace}/brain-selector.html` (pass `--extra`, a JSON list of `{category, technique_name, description}`, when there are additional techniques; the file is then `{doc_workspace}/brain-selector.html`). Try to open it (`open` / `xdg-open` / `start`), then say, in one message: *"It should open in your browser — compose your session, click **Copy prompt**, and paste the result back. If it didn't open, open `<path>` yourself, or say 'let's do it in chat'."* You can't see their browser, so never claim it opened.
 
 Read the pasted block: the **`Facilitation mode:`** line → the stance; the **listed techniques** (full category/name/description, some tagged `(random pick)`) → run them as given, no `list`/`show` needed; **`invent N`** / **`you choose N`** → see `## Choosing Techniques`.
 
@@ -63,7 +61,7 @@ For **Facilitator** and **Creative Partner**. (In **Ideate for me** you pick and
 Most sessions arrive with a batch already composed on the page — run it as given (each technique's full text is in the paste; no `list`/`show` needed). Two parts of a paste delegate back to you:
 
 - **`invent N`** (Inventive Flow) — invent N brand-new techniques on the fly. A line may scope an invention (`invent 1 new technique in the spirit of <category>`, from the page's per-category invent card) — when it does, honor that category's spirit. Announce the order, log each one's name + description, and offer to save a keeper to `{workflow.additional_techniques}` at wrap-up.
-- **`you choose N`** (Facilitator Chosen) — pick N techniques fitting the goal, `{workflow.favorite_techniques}` first; confirm exact names with a scoped `python3 {skill-root}/scripts/brain.py --file {workflow.brain_methods} list --category <cat>`. Never pull the library whole into context.
+- **`you choose N`** (Facilitator Chosen) — pick N techniques fitting the goal, `{workflow.favorite_techniques}` first; confirm exact names with a scoped `uv run {skill-root}/scripts/brain.py --file {workflow.brain_methods} list --category <cat>`. Never pull the library whole into context.
 
 If they didn't use the page, load `references/in-chat-techniques.md` and pick the batch in chat (**3–4 is the sweet spot**).
 

package/src/core-skills/bmad-brainstorming/references/converge.md

@@ -17,7 +17,7 @@ Pick by what the decision needs:
 - **PMI (Plus / Minus / Interesting)** — when one strong candidate needs pressure-testing before commitment: list its pluses, minuses, and the merely-interesting, then judge.
 - **MoSCoW** — when scoping a build: sort into Must / Should / Could / Won't-this-time.
 
-Log the surviving directions and the reasoning with `python3 {skill-root}/scripts/memlog.py append --type decision --text "<one-line gist>"` (use `--by` in Creative Partner mode). Two or three convergence moves chained is fine (e.g. cluster → score the clusters); more than that is usually over-processing.
+Log the surviving directions and the reasoning with `uv run {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type decision --text "<one-line gist>"` (use `--by` in Creative Partner mode). Two or three convergence moves chained is fine (e.g. cluster → score the clusters); more than that is usually over-processing.
 
 ## Then finalize
 

package/src/core-skills/bmad-brainstorming/references/finalize.md

@@ -9,7 +9,7 @@ In Facilitator mode this is the one place your own creative contribution is welc
 1. **Hand them the mirror first.** Reflect a vivid sampling of *their* ideas back — deliberately include the odd, random, or buried ones from earlier, not just the recent obvious ones (in Creative Partner mode the `(... by user)` tags tell you which were theirs). Ask what they see now: conclusions, synergies, themes, the few that actually matter. Let them connect first; their own pattern-recognition is the point.
 2. **Then add the connections they would miss.** Lean in creatively — not new raw ideas, but the non-obvious links: this idea from technique one quietly solves that tension from technique four; these three are one idea wearing three hats; this wildcard is the real breakthrough.
 
-Record the insights and chosen directions with `memlog.py append --type insight`. **Then run `python3 {skill-root}/scripts/memlog.py set --workspace {doc_workspace} --key status --value complete`** — the session is done and must stop being offered for resume. Do this even if the user declines every artifact below.
+Record the insights and chosen directions with `uv run {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type insight --text "<insights + chosen directions>"`. **Then run `uv run {project-root}/_bmad/scripts/memlog.py set --workspace {doc_workspace} --key status --value complete`** — the session is done and must stop being offered for resume. Do this even if the user declines every artifact below.
 
 ## Artifacts