bmad-speckit-sdd-flow 1.0.3 → 1.1.0

package/README.md

@@ -7,7 +7,7 @@ English | [简体中文](README.zh-CN.md)
 </p>
 
 <h3 align="center">
-  Governed Spec-Driven AI Delivery for Cursor and Claude Code
+  Governed Spec-Driven AI Delivery for Cursor, Claude Code, and Codex
 </h3>
 
 <p align="center">
@@ -79,6 +79,7 @@ This is the verified off-repo path for the published package contract.
 npx --yes --package bmad-speckit-sdd-flow@latest bmad-speckit version
 npx --yes --package bmad-speckit-sdd-flow@latest bmad-speckit-init . --agent claude-code --full --no-package-json
 npx --yes --package bmad-speckit-sdd-flow@latest bmad-speckit-init . --agent cursor --full --no-package-json
+npx --yes --package bmad-speckit-sdd-flow@latest bmad-speckit-init . --agent codex --full --no-package-json
 npx --yes --package bmad-speckit-sdd-flow@latest bmad-speckit check
 npx --yes --package bmad-speckit-sdd-flow@latest bmad-speckit dashboard-status
 ```

package/_bmad/_config/bmads-runtime.yaml

@@ -0,0 +1,193 @@
+schemaVersion: bmads-runtime/v1
+
+contracts:
+  governance: _bmad/_config/orchestration-governance.contract.yaml
+  dispatch: scripts/orchestration-dispatch-contract.ts
+  stageMapping: _bmad/_config/stage-mapping.yaml
+
+entry:
+  canonicalCommand: bmads
+  aliases:
+    - bmad-speckit
+    - $bmads
+    - /bmads
+    - $bmad-speckit
+    - /bmad-speckit
+  advisory:
+    bmadHelpCommand: bmad-help
+    message: Run bmad-help for full BMAD Method workflow guidance.
+
+layers:
+  - id: layer_1
+    name: Product Definition
+    stages:
+      - id: prd
+        governanceStage: prd
+        requiredGovernanceSignalsFrom: orchestration-governance.contract.yaml
+        recommendedWorkflows:
+          - bmad-bmm-create-product-brief
+          - bmad-bmm-create-prd
+          - bmad-bmm-validate-prd
+        evidence:
+          completionMarker: _bmad-output/runtime/context/layer_1-prd.complete.json
+          primaryArtifacts:
+            - _bmad-output/planning-artifacts/{branch}/prd.md
+            - _bmad-output/planning-artifacts/prd.md
+            - _bmad-output/planning-artifacts/product-brief-*.md
+        next:
+          layer: layer_2
+          stage: arch
+
+  - id: layer_2
+    name: Architecture
+    stages:
+      - id: arch
+        governanceStage: arch
+        requiredGovernanceSignalsFrom: orchestration-governance.contract.yaml
+        recommendedWorkflows:
+          - bmad-bmm-create-architecture
+          - bmad-bmm-validate-architecture
+        evidence:
+          primaryArtifacts:
+            - _bmad-output/planning-artifacts/{branch}/architecture.md
+            - _bmad-output/planning-artifacts/architecture.md
+            - docs/architecture/**
+        next:
+          layer: layer_3
+          stage: epics
+
+  - id: layer_3
+    name: Epic And Story Planning
+    stages:
+      - id: epics
+        governanceStage: epics
+        requiredGovernanceSignalsFrom: orchestration-governance.contract.yaml
+        recommendedWorkflows:
+          - bmad-bmm-create-epics-and-stories
+          - bmad-bmm-sprint-planning
+        evidence:
+          primaryArtifacts:
+            - _bmad-output/planning-artifacts/{branch}/epics.md
+            - _bmad-output/planning-artifacts/epics.md
+        next:
+          layer: layer_3
+          stage: story_create
+      - id: story_create
+        governanceStage: story_create
+        requiredGovernanceSignalsFrom: orchestration-governance.contract.yaml
+        recommendedWorkflows:
+          - bmad-bmm-create-epics-and-stories
+          - bmad-bmm-check-implementation-readiness
+          - bmad-bmm-sprint-planning
+          - bmad-bmm-create-story
+        evidence:
+          primaryArtifacts:
+            - _bmad-output/sprint-status.yaml
+            - docs/stories/**
+        next:
+          layer: layer_4
+          stage: specify
+
+  - id: layer_4
+    name: Speckit Implementation
+    stages:
+      - id: specify
+        governanceStage: specify
+        requiredGovernanceSignalsFrom: orchestration-governance.contract.yaml
+        recommendedWorkflows:
+          - speckit-workflow
+        dispatch:
+          taskType: document
+          hosts: [cursor, claude, codex]
+        next:
+          layer: layer_4
+          stage: plan
+      - id: plan
+        governanceStage: plan
+        requiredGovernanceSignalsFrom: orchestration-governance.contract.yaml
+        recommendedWorkflows:
+          - speckit-workflow
+        dispatch:
+          taskType: document
+          hosts: [cursor, claude, codex]
+        next:
+          layer: layer_4
+          stage: gaps
+      - id: gaps
+        governanceStage: gaps
+        requiredGovernanceSignalsFrom: orchestration-governance.contract.yaml
+        recommendedWorkflows:
+          - speckit-workflow
+        dispatch:
+          taskType: audit
+          hosts: [cursor, claude, codex]
+        next:
+          layer: layer_4
+          stage: tasks
+      - id: tasks
+        governanceStage: tasks
+        requiredGovernanceSignalsFrom: orchestration-governance.contract.yaml
+        recommendedWorkflows:
+          - speckit-workflow
+        dispatch:
+          taskType: document
+          hosts: [cursor, claude, codex]
+        next:
+          layer: layer_4
+          stage: implement
+      - id: implement
+        governanceStage: implement
+        requiredGovernanceSignalsFrom: orchestration-governance.contract.yaml
+        recommendedWorkflows:
+          - speckit-workflow
+        dispatch:
+          taskType: implement
+          hosts:
+            - cursor
+            - claude
+            - codex
+        next:
+          layer: layer_5
+          stage: post_audit
+
+  - id: layer_5
+    name: Closeout
+    stages:
+      - id: post_audit
+        governanceStage: post_audit
+        requiredGovernanceSignalsFrom: orchestration-governance.contract.yaml
+        recommendedWorkflows:
+          - bmad-code-reviewer-lifecycle
+        dispatch:
+          taskType: audit
+          hosts: [cursor, claude, codex]
+        next:
+          layer: layer_5
+          stage: pr_review
+      - id: pr_review
+        governanceStage: post_audit
+        requiredGovernanceSignalsFrom: orchestration-governance.contract.yaml
+        gates:
+          required:
+            - pr_topology_closed
+        next:
+          layer: layer_5
+          stage: release_gate
+      - id: release_gate
+        governanceStage: post_audit
+        requiredGovernanceSignalsFrom: orchestration-governance.contract.yaml
+        gates:
+          required:
+            - release_gate
+            - quality_gate
+            - sprint_audit
+        next:
+          layer: layer_5
+          stage: delivery_truth_gate
+      - id: delivery_truth_gate
+        governanceStage: post_audit
+        requiredGovernanceSignalsFrom: orchestration-governance.contract.yaml
+        gates:
+          required:
+            - delivery_truth_gate
+            - long_run_development_evidence

package/_bmad/_config/main-agent-quality-gate.thresholds.json

@@ -0,0 +1,46 @@
+{
+  "version": 1,
+  "gateId": "main-agent-quality-gate",
+  "maxTodoStubs": 0,
+  "maxForbiddenTodoMarkers": 0,
+  "maxMissingKeyPaths": 0,
+  "requiredKeyPaths": [
+    "scripts/main-agent-orchestration.ts",
+    "scripts/main-agent-unified-ingress.ts",
+    "scripts/main-agent-codex-worker-adapter.ts",
+    "scripts/main-agent-release-gate.ts",
+    "scripts/main-agent-delivery-truth-gate.ts",
+    "scripts/main-agent-quality-gate.ts",
+    "scripts/main-agent-chaos-scenarios.ts",
+    "_bmad/_config/orchestration-governance.contract.yaml",
+    "_bmad-output/runtime/governance/user_story_mapping.json",
+    "tests/acceptance/main-agent-release-gate-contract.test.ts",
+    "tests/acceptance/main-agent-delivery-truth-gate.test.ts",
+    "tests/acceptance/governance-rerun-gate-closure.test.ts",
+    "tests/acceptance/main-agent-host-matrix-pr-orchestration.test.ts",
+    "tests/acceptance/sprint-status-authorized-update.test.ts",
+    "docs/ops/main-agent-capability-traceability-matrix.md"
+  ],
+  "requiredAcceptanceTests": [
+    "tests/acceptance/main-agent-quality-gate-thresholds.test.ts",
+    "tests/acceptance/main-agent-release-gate-contract.test.ts",
+    "tests/acceptance/main-agent-delivery-truth-gate.test.ts",
+    "tests/acceptance/governance-rerun-gate-closure.test.ts",
+    "tests/acceptance/main-agent-host-matrix-pr-orchestration.test.ts",
+    "tests/acceptance/main-agent-run-loop-e2e.test.ts",
+    "tests/acceptance/main-agent-codex-agent-parity.test.ts",
+    "tests/acceptance/main-agent-codex-worker-adapter-e2e.test.ts",
+    "tests/acceptance/main-agent-unified-ingress-e2e.test.ts"
+  ],
+  "requiredCodexProofPaths": [
+    "tests/acceptance/main-agent-codex-agent-parity.test.ts",
+    "tests/acceptance/main-agent-codex-worker-adapter-e2e.test.ts",
+    "tests/acceptance/main-agent-codex-consumer-five-layer-e2e.test.ts",
+    "tests/acceptance/reviewer-codex-noop-guard.test.ts",
+    "tests/acceptance/reviewer-rollout-rollback-proof.test.ts"
+  ],
+  "forbiddenTodoMarkers": [
+    "failTodo('main-agent-quality-gate'",
+    "TODO implementation not completed"
+  ]
+}

package/_bmad/_config/orchestration-governance.contract.yaml

@@ -0,0 +1,210 @@
+version: 1
+contract_id: orchestration-governance
+owner: main-agent-orchestration
+status: draft
+updated_at: "2026-04-26T13:23:00+08:00"
+
+description: >
+  Single strategy source for main-agent orchestration governance.
+  Main loop must read this contract for signal policy and stage gate requirements.
+
+sources_of_truth:
+  strategy_contract: "_bmad/_config/orchestration-governance.contract.yaml"
+  runtime_index: "_bmad-output/runtime/governance/user_story_mapping.json"
+  runtime_index_schema: "_bmad-output/runtime/governance/user_story_mapping.schema.json"
+
+consumption_rules:
+  main_loop_must_read:
+    - strategy_contract
+    - runtime_index
+  forbidden_strategy_sources:
+    - ad_hoc_markdown_rules
+    - inline_hardcoded_signal_thresholds
+    - duplicated_yaml_contracts
+
+signals:
+  - id: p0_journey_coverage
+    category: delivery_readiness
+    severity_default: block
+    description: P0 journeys must be covered and mapped to executable task chains.
+    required_evidence:
+      - journey_coverage_matrix
+      - mapped_journey_task_chain
+  - id: smoke_e2e_readiness
+    category: test_readiness
+    severity_default: block
+    description: Critical journeys must have runnable smoke/E2E proof.
+    required_evidence:
+      - smoke_test_entry
+      - smoke_execution_output
+  - id: evidence_proof_chain
+    category: evidence_integrity
+    severity_default: block
+    description: Claims must be backed by command output and persistent artifacts.
+    required_evidence:
+      - command_output_summary
+      - artifact_paths
+  - id: cross_document_traceability
+    category: traceability
+    severity_default: warn
+    description: Requirement/plan/tasks/test references must be mutually traceable.
+    required_evidence:
+      - requirement_to_story_link
+      - story_to_test_link
+  - id: orchestration_governance_completeness
+    category: control_plane_integrity
+    severity_default: warn
+    description: Main loop must execute full control steps without bypass.
+    required_evidence:
+      - inspect_dispatch_ingest_sequence
+      - gates_loop_state_transition
+      - closeout_gate_chain
+
+stage_requirements:
+  prd:
+    required_signals:
+      - p0_journey_coverage
+      - cross_document_traceability
+  arch:
+    required_signals:
+      - p0_journey_coverage
+      - cross_document_traceability
+  epics:
+    required_signals:
+      - p0_journey_coverage
+      - cross_document_traceability
+  story_create:
+    required_signals:
+      - p0_journey_coverage
+      - cross_document_traceability
+  story_audit:
+    required_signals:
+      - evidence_proof_chain
+      - cross_document_traceability
+  specify:
+    required_signals:
+      - p0_journey_coverage
+      - cross_document_traceability
+  plan:
+    required_signals:
+      - p0_journey_coverage
+      - smoke_e2e_readiness
+      - cross_document_traceability
+  gaps:
+    required_signals:
+      - p0_journey_coverage
+      - smoke_e2e_readiness
+      - evidence_proof_chain
+  tasks:
+    required_signals:
+      - p0_journey_coverage
+      - smoke_e2e_readiness
+      - cross_document_traceability
+  implement:
+    required_signals:
+      - p0_journey_coverage
+      - smoke_e2e_readiness
+      - evidence_proof_chain
+      - orchestration_governance_completeness
+    signal_overrides:
+      orchestration_governance_completeness: warn
+  post_audit:
+    required_signals:
+      - evidence_proof_chain
+      - cross_document_traceability
+      - orchestration_governance_completeness
+    signal_overrides:
+      orchestration_governance_completeness: block
+  epic_create:
+    required_signals:
+      - p0_journey_coverage
+      - cross_document_traceability
+  epic_complete:
+    required_signals:
+      - smoke_e2e_readiness
+      - evidence_proof_chain
+      - orchestration_governance_completeness
+    signal_overrides:
+      orchestration_governance_completeness: block
+
+mapping_contract:
+  required_fields:
+    - requirementId
+    - sourceType
+    - epicId
+    - storyId
+    - flow
+    - sprintId
+    - allowedWriteScope
+    - status
+  consistency_rules:
+    - requirement_to_flow_must_exist
+    - requirement_to_story_must_be_unique_per_active_status
+    - changed_files_must_fit_allowed_write_scope
+    - flow_phase_must_match_orchestration_state
+    - sprint_id_must_be_present
+    - reroute_must_deactivate_previous_active_mapping
+    - closeout_must_write_back_mapping_status
+
+gate_policy:
+  missing_required_signal: block
+  missing_required_mapping_field: block
+  mapping_consistency_violation: block
+  warn_threshold:
+    max_warn_signals_before_block: 2
+
+adaptive_intake_governance_gate:
+  gate_name: adaptive_intake_governance_gate
+  applies_to_flows:
+    - story
+    - bugfix
+    - standalone_tasks
+  trigger_points:
+    - on_new_requirement_intake
+    - on_reroute
+    - before_closeout
+  match_scoring:
+    domain_fit: 0.30
+    dependency_fit: 0.25
+    sprint_fit: 0.20
+    risk_fit: 0.15
+    readiness_fit: 0.10
+  decision_thresholds:
+    min_confidence_for_auto_match: 0.70
+    min_confidence_for_warn: 0.55
+  consistency_dimensions:
+    mapping_consistency:
+      required:
+        - requirement_to_story_unique_active
+        - flow_to_story_type_consistent
+        - allowed_write_scope_consistent
+    lifecycle_consistency:
+      required:
+        - orchestration_state_aligned_with_mapping_status
+        - reroute_history_consistent
+        - closeout_result_written_back
+    sprint_consistency:
+      required:
+        - sprint_id_valid
+        - backlog_sync_record_present
+        - capacity_overflow_requires_replan
+  verdict_policy:
+    any_required_check_fail: block
+    warn_if_confidence_below_auto_match: true
+    pass_requires:
+      - mapping_consistency
+      - lifecycle_consistency
+      - sprint_consistency
+
+observability_targets:
+  match_precision_at_1:
+    target: 0.80
+  reroute_recovery_rate:
+    target: 0.90
+  sprint_sync_latency_minutes:
+    target_max: 30
+  mapping_conflict_rate:
+    target_max: 0.05
+  governance_bypass_count:
+    target: 0
+

package/_bmad/_config/stage-mapping.yaml

@@ -1,27 +1,26 @@
-# BMAD Layer → 阶段（表 A）、阶段 → 评分环节（表 B）、触发模式表
-# Architecture §3、§4、§10.3；Story 3.1 产出
+# BMAD layer to stage mapping, scoring phase mapping, and trigger modes.
+# Keep this file ASCII-safe: do not write it through PowerShell text pipelines.
 
 version: "1.0"
 
-# 表 A：BMAD Layer → 阶段
 layer_to_stages:
   layer_1:
-    name: 产品定义层
-    stages: [prd, arch]
+    name: Product Definition Layer
+    stages: [prd]
   layer_2:
-    name: Epic/Story 规划层
-    stages: [epics]
+    name: Architecture Layer
+    stages: [arch]
   layer_3:
-    name: Story 开发层
-    stages: [story]
+    name: Epic/Story Planning Layer
+    stages: [epics, story]
   layer_4:
-    name: 技术实现层
+    name: Technical Implementation Layer
     stages: [specify, plan, gaps, tasks, implement]
   layer_5:
-    name: 收尾层
-    stages: [post_impl, pr_review]
+    name: Closeout Layer
+    stages: [post_impl, pr_review, release_gate, delivery_truth_gate]
+    closeout_stages: [post_audit, pr_review, release_gate, delivery_truth_gate]
 
-# 表 B：阶段 → 评分环节（1–6）
 stage_to_phase:
   prd: [1]
   arch: [1, 2]
@@ -34,28 +33,28 @@ stage_to_phase:
   implement: [2, 3, 4, 5, 6]
   post_impl: [2, 3, 4, 5, 6]
   pr_review: [6]
+  release_gate: [6]
+  delivery_truth_gate: [6]
 
-# 触发模式表（Architecture §10.3）
 trigger_modes:
   - event: stage_audit_complete
     trigger: auto
-    scope: 该 stage 对应环节
+    scope: matching stage scoring phases
   - event: story_status_change
     trigger: auto
     configurable: true
-    scope: 环节 1–6
+    scope: phases 1-6
   - event: mr_created
     trigger: auto
     configurable: true
-    scope: 环节 2–6
+    scope: phases 2-6
   - event: epic_pending_acceptance
     trigger: manual_or_auto
-    scope: 环节 6、Epic 综合
+    scope: phase 6 and epic synthesis
   - event: user_explicit_request
     trigger: manual
-    scope: 全环节
+    scope: all phases
 
-# Runtime Governance: (flow, stage) → scoring trigger_stage_id（与 scoring-trigger-modes call_mapping.stage 逐字对齐）
 runtime_flow_stage_to_trigger_stage:
   story:
     specify: speckit_1_2
@@ -65,6 +64,9 @@ runtime_flow_stage_to_trigger_stage:
     implement: speckit_5_2
     story_audit: bmad_story_stage2
     post_audit: bmad_story_stage4
+    pr_review: bmad_story_stage6
+    release_gate: bmad_story_stage6
+    delivery_truth_gate: bmad_story_stage6
   bugfix:
     specify: speckit_1_2
     plan: speckit_2_2

package/_bmad/bmm/agents/architect.md

@@ -49,8 +49,8 @@ You must fully embody this agent's persona and follow all activation instruction
   <menu>
     <item cmd="MH or fuzzy match on menu or help">[MH] Redisplay Menu Help</item>
     <item cmd="CH or fuzzy match on chat">[CH] Chat with the Agent about anything</item>
-    <item cmd="CA or fuzzy match on create-architecture" exec="{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/workflow.md">[CA] Create Architecture: Guided Workflow to document technical decisions to keep implementation on track</item>
-    <item cmd="IR or fuzzy match on implementation-readiness" exec="{project-root}/_bmad/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md">[IR] Implementation Readiness: Ensure the PRD, UX, and Architecture and Epics and Stories List are all aligned</item>
+    <item cmd="CA or fuzzy match on create-architecture" exec="{project-root}/_bmad/bmm/workflows/3-solutioning/bmad-create-architecture/SKILL.md">[CA] Create Architecture: Guided Workflow to document technical decisions to keep implementation on track</item>
+    <item cmd="IR or fuzzy match on implementation-readiness" exec="{project-root}/_bmad/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/SKILL.md">[IR] Implementation Readiness: Ensure the PRD, UX, and Architecture and Epics and Stories List are all aligned</item>
     <item cmd="PM or fuzzy match on party-mode" exec="{project-root}/_bmad/core/workflows/party-mode/workflow.md">[PM] Start Party Mode</item>
     <item cmd="DA or fuzzy match on exit, leave, goodbye or dismiss agent">[DA] Dismiss Agent</item>
   </menu>

package/_bmad/bmm/agents/pm.md

@@ -68,7 +68,7 @@ You must fully embody this agent's persona and follow all activation instruction
     <item cmd="CP or fuzzy match on create-prd" exec="{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/workflow-create-prd.md">[CP] Create PRD: Expert led facilitation to produce your Product Requirements Document</item>
     <item cmd="VP or fuzzy match on validate-prd" exec="{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/workflow-validate-prd.md">[VP] Validate PRD: Validate a Product Requirements Document is comprehensive, lean, well organized and cohesive</item>
     <item cmd="EP or fuzzy match on edit-prd" exec="{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/workflow-edit-prd.md">[EP] Edit PRD: Update an existing Product Requirements Document</item>
-    <item cmd="CE or fuzzy match on epics-stories" exec="{project-root}/_bmad/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.md">[CE] Create Epics and Stories: Create the Epics and Stories Listing, these are the specs that will drive development</item>
+    <item cmd="CE or fuzzy match on epics-stories" exec="{project-root}/_bmad/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/SKILL.md">[CE] Create Epics and Stories: Create the Epics and Stories Listing, these are the specs that will drive development</item>
     <item cmd="IR or fuzzy match on implementation-readiness" exec="{project-root}/_bmad/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md">[IR] Implementation Readiness: Ensure the PRD, UX, and Architecture and Epics and Stories List are all aligned</item>
     <item cmd="CC or fuzzy match on correct-course" workflow="{project-root}/_bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml">[CC] Course Correction: Use this so we can determine how to proceed if major need for change is discovered mid implementation</item>
     <item cmd="PM or fuzzy match on party-mode" exec="{project-root}/_bmad/core/workflows/party-mode/workflow.md">[PM] Start Party Mode</item>

package/_bmad/bmm/agents/sm.md

@@ -25,6 +25,12 @@ You must fully embody this agent's persona and follow all activation instruction
 
       <menu-handlers>
               <handlers>
+          <handler type="exec">
+        When menu item or handler has: exec="path/to/file.md":
+        1. Read fully and follow the file at that path
+        2. Process the complete file and follow all instructions within it
+        3. If there is data="some/path/data-foo.md" with the same item, pass that data path to the executed file as context.
+      </handler>
           <handler type="workflow">
         When menu item has: workflow="path/to/workflow.yaml":
 
@@ -59,8 +65,8 @@ You must fully embody this agent's persona and follow all activation instruction
   <menu>
     <item cmd="MH or fuzzy match on menu or help">[MH] Redisplay Menu Help</item>
     <item cmd="CH or fuzzy match on chat">[CH] Chat with the Agent about anything</item>
-    <item cmd="SP or fuzzy match on sprint-planning" workflow="{project-root}/_bmad/bmm/workflows/4-implementation/sprint-planning/workflow.yaml">[SP] Sprint Planning: Generate or update the record that will sequence the tasks to complete the full project that the dev agent will follow</item>
-    <item cmd="CS or fuzzy match on create-story" workflow="{project-root}/_bmad/bmm/workflows/4-implementation/create-story/workflow.yaml">[CS] Context Story: Prepare a story with all required context for implementation for the developer agent</item>
+    <item cmd="SP or fuzzy match on sprint-planning" exec="{project-root}/_bmad/bmm/workflows/4-implementation/bmad-sprint-planning/SKILL.md">[SP] Sprint Planning: Generate or update the record that will sequence the tasks to complete the full project that the dev agent will follow</item>
+    <item cmd="CS or fuzzy match on create-story" exec="{project-root}/_bmad/bmm/workflows/4-implementation/bmad-create-story/SKILL.md">[CS] Context Story: Prepare a story with all required context for implementation for the developer agent</item>
     <item cmd="ER or fuzzy match on epic-retrospective" workflow="{project-root}/_bmad/bmm/workflows/4-implementation/retrospective/workflow.yaml" data="{project-root}/_bmad/_config/agent-manifest.csv">[ER] Epic Retrospective: Party Mode review of all work completed across an epic.</item>
     <item cmd="CC or fuzzy match on correct-course" workflow="{project-root}/_bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml">[CC] Course Correction: Use this so we can determine how to proceed if major need for change is discovered mid implementation</item>
     <item cmd="PM or fuzzy match on party-mode" exec="{project-root}/_bmad/core/workflows/party-mode/workflow.md">[PM] Start Party Mode</item>

package/_bmad/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/SKILL.md

@@ -3,4 +3,5 @@ name: bmad-check-implementation-readiness
 description: 'Validate PRD, UX, Architecture and Epics specs are complete. Use when the user says "check implementation readiness".'
 ---
 
-Follow the instructions in ./workflow.md.
+Load and follow the official branch-scoped workflow at `../check-implementation-readiness/workflow.md`.
+Do not use the legacy flat-path workflow in this directory as the canonical execution path.

package/_bmad/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/steps/step-01-document-discovery.md

@@ -1,5 +1,5 @@
 ---
-outputFile: '{planning_artifacts}/implementation-readiness-report-{{date}}.md'
+outputFile: '{planning_artifacts}/{branch}/implementation-readiness-report-{{date}}.md'
 ---
 
 # Step 1: Document Discovery
@@ -68,8 +68,8 @@ Search for each document type using these patterns:
 
 #### C. Epics & Stories Documents
 
-- Whole: `{planning_artifacts}/*epic*.md`
-- Sharded: `{planning_artifacts}/*epic*/index.md` and related files
+- Whole: `{planning_artifacts}/{branch}/epics.md`
+- Sharded: `{planning_artifacts}/{branch}/epics/index.md` and related files
 
 #### D. UX Design Documents
 

package/_bmad/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/steps/step-02-prd-analysis.md

@@ -1,6 +1,6 @@
 ---
-outputFile: '{planning_artifacts}/implementation-readiness-report-{{date}}.md'
-epicsFile: '{planning_artifacts}/*epic*.md' # Will be resolved to actual file
+outputFile: '{planning_artifacts}/{branch}/implementation-readiness-report-{{date}}.md'
+epicsFile: '{planning_artifacts}/{branch}/epics.md' # Canonical whole-file path; fall back to legacy flat or sharded discovery only when missing
 ---
 
 # Step 2: PRD Analysis

package/_bmad/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/steps/step-06-final-assessment.md

@@ -1,10 +1,12 @@
 ---
-outputFile: '{planning_artifacts}/implementation-readiness-report-{{date}}.md'
-remediationArtifactFile: '{planning_artifacts}/implementation-readiness-remediation-{{date}}.md'
+outputFile: '{planning_artifacts}/{branch}/implementation-readiness-report-{{date}}.md'
+remediationArtifactFile: '{planning_artifacts}/{branch}/implementation-readiness-remediation-{{date}}.md'
 ---
 
 # Step 6: Final Assessment
 
+> Legacy compatibility step only. Canonical readiness outputs are branch-scoped under `{planning_artifacts}/{branch}/`.
+
 ## STEP GOAL:
 
 To provide a comprehensive summary of all findings and give the report a final polish, ensuring clear recommendations and overall readiness status.

package/_bmad/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/workflow.md

@@ -1,5 +1,7 @@
 # Implementation Readiness
 
+> Legacy compatibility surface only. The canonical execution path is `../check-implementation-readiness/workflow.md`. The canonical readiness outputs are branch-scoped under `{planning_artifacts}/{branch}/`.
+
 **Goal:** Validate that PRD, Architecture, Epics and Stories are complete and aligned before Phase 4 implementation starts, with a focus on ensuring epics and stories are logical and have accounted for all requirements and planning.
 The final assessment produces both the readiness report and a governance remediation artifact for blocker-driven follow-up.
 

package/_bmad/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/SKILL.md

@@ -3,4 +3,5 @@ name: bmad-create-epics-and-stories
 description: 'Break requirements into epics and user stories. Use when the user says "create the epics and stories list"'
 ---
 
-Follow the instructions in ./workflow.md.
+Load and follow the official branch-scoped workflow at `../create-epics-and-stories/workflow.md`.
+Do not use the legacy flat-path workflow in this directory as the canonical execution path.