@zeyue0329/xiaoma-cli 1.13.0 → 1.15.1

package/src/{xmc/workflows/5-full-pipeline/auto-full-pipeline → xmc-skills/5-full-pipeline/xiaoma-auto-full-pipeline}/steps/step-03-bridge-sprint-planning.md

@@ -2,13 +2,14 @@
 name: "step-03-bridge-sprint-planning"
 description: "Bridge phase: auto-run sprint planning to generate sprint-status.yaml from epics, connecting requirements analysis output to story development input"
 nextStepFile: "./step-04-run-story-pipeline.md"
+kind: "bridge"
 ---
 
 # Step 3 of 5: Bridge — Sprint Planning
 
 **Goal:** Generate `sprint-status.yaml` from the epics produced in Phase 1. This bridges the requirements analysis output to the story development pipeline input. Without this step, the story pipeline cannot determine which stories to process.
 
-**Role:** SM (xiaomin) — Scrum Master generating sprint tracking
+**Role:** Dev (xiaokai) — Sprint-Planning (SP) mode generating sprint tracking
 
 ---
 
@@ -42,7 +43,7 @@ Also check for sharded epics format (safety net only — the auto-requirements-p
 
 ### 3. Execute Sprint Planning Workflow
 
-Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-sprint-planning/workflow.md`
+Read fully and follow: `skill:xiaoma-sprint-planning`
 
 **Critical Full Pipeline Mode Instructions:**
 
@@ -58,19 +59,71 @@ Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/4-implementation/xi
 - When the workflow outputs "Next Steps" guidance at the end, **ignore it** — the next steps are handled by THIS full pipeline automatically
 - **Complete ALL steps without stopping**
 
-### 4. Verify Sprint Status Output
+**Capture errors:** record any HALT message or fatal error emitted by the sprint-planning workflow into `{sprint_planning_error}` (empty string if none).
+
+### 4. Verify Sprint Status Output (with Bridge-Failure Fallback)
 
 After sprint planning completes, verify:
 
-1. **Sprint Status File** — `{implementation_artifacts}/sprint-status.yaml` must exist
-   - If missing: HALT — "Sprint planning failed to generate sprint-status.yaml. Check epics format and retry."
+1. **Sprint Status File** — `{implementation_artifacts}/sprint-status.yaml` must exist.
 
 2. **Content Validation** — Read the generated file and verify:
    - Contains `development_status:` section
    - Contains at least one story entry (not just epic entries)
    - Valid YAML syntax
 
-3. **Count Stories** — Parse and count:
+3. **Bridge-Failure Fallback (preserves Phase 1 work; allows resume):**
+
+   If `{implementation_artifacts}/sprint-status.yaml` is missing OR fails content validation, **do NOT silently HALT**. Phase 1 has already produced expensive artifacts (PRD, epics, architecture); losing the run context here would force re-running Phase 1. Instead:
+
+   a. Write a structured failure marker to `{implementation_artifacts}/bridge-failure.json` (atomic temp-file-then-rename):
+
+      ```json
+      {
+        "pipeline": "auto-full-pipeline",
+        "stage": "step-03-bridge-sprint-planning",
+        "date": "{date}",
+        "failure_reason": "sprint-status.yaml missing or invalid after sprint-planning workflow returned",
+        "sprint_planning_error": "{sprint_planning_error}",
+        "validation_signals": {
+          "file_exists": false_or_true,
+          "yaml_valid": false_or_true,
+          "has_development_status": false_or_true,
+          "story_entries_present": false_or_true
+        },
+        "phase_1_artifacts_preserved": {
+          "prd": "{planning_artifacts}/prd.md",
+          "epics": "{planning_artifacts}/epics.md",
+          "architecture": "{planning_artifacts}/architecture.md",
+          "pipeline_status": "{planning_artifacts}/pipeline-status.json"
+        },
+        "recovery_instructions": [
+          "1. Inspect epics.md for malformed epic/story structure (most common cause).",
+          "2. Run /xiaoma-sprint-planning (SP) manually with the same epics.md to reproduce the error in isolation.",
+          "3. Once sprint-status.yaml is healthy, re-run auto-full-pipeline; step-01 resume detection will skip Phase 1 (artifacts intact) and proceed directly to Phase 3."
+        ]
+      }
+      ```
+
+   b. Set `{phase_2_status}` = "failed"; do NOT advance `{phase_3_status}`.
+
+   c. HALT with this exact user-facing message — **be specific about resume mechanics**, since the value of preserving Phase 1 is wasted if the user thinks they must restart:
+
+      ```
+      ❌ Phase 2 (Sprint Planning Bridge) failed.
+
+      Sprint planning produced no usable sprint-status.yaml. Failure marker written to:
+        {implementation_artifacts}/bridge-failure.json
+
+      ✅ Phase 1 artifacts are preserved (PRD, epics, architecture, pipeline-status.json).
+
+      🔄 Recovery:
+        1. Fix the underlying cause (likely malformed epics.md — see bridge-failure.json for details).
+        2. Run /xiaoma-sprint-planning (SP) manually to confirm sprint-status.yaml generates cleanly.
+        3. Re-run /xiaoma-auto-full-pipeline. Resume detection in step-01 will skip Phase 1 and pick up at Phase 2.
+      ```
+
+4. **Count Stories** (only if validation passed) — Parse and count:
    - Total epics
    - Total stories
    - Stories in "backlog" status (should be all stories for a fresh run)
@@ -114,6 +167,7 @@ Proceeding to Phase 3 — Story Development Pipeline (batch mode)...
 ## FAILURE MODES
 
 - Epics file missing or unreadable
-- Sprint planning workflow fails
-- Generated sprint-status.yaml is malformed or empty
-- No story entries found in sprint status
+- Sprint planning workflow fails — but instead of bare HALT, a structured `bridge-failure.json` marker is written and Phase 1 artifacts are preserved for resume
+- Generated sprint-status.yaml is malformed or empty — same fallback path
+- No story entries found in sprint status — same fallback path
+- Failing to write `bridge-failure.json` atomically (would leave a half-written marker; use temp-file-then-rename)

package/src/{xmc/workflows/5-full-pipeline/auto-full-pipeline → xmc-skills/5-full-pipeline/xiaoma-auto-full-pipeline}/steps/step-04-run-story-pipeline.md

@@ -2,6 +2,7 @@
 name: "step-04-run-story-pipeline"
 description: "Execute the auto-story-pipeline-batch to develop, review, test, and deliver all stories using Agent subprocess isolation"
 nextStepFile: "./step-05-finalize.md"
+kind: "orchestrator"
 ---
 
 # Step 4 of 5: Execute Story Development Pipeline (Batch)
@@ -42,7 +43,7 @@ Delegating to auto-story-pipeline-batch...
 
 ### 2. Execute Auto Story Pipeline Batch
 
-Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/4-implementation/auto-story-pipeline-batch/workflow.md`
+Read fully and follow: `skill:xiaoma-auto-story-pipeline-batch`
 
 **Critical Full Pipeline Mode Instructions:**
 

package/src/{xmc/workflows/5-full-pipeline/auto-full-pipeline → xmc-skills/5-full-pipeline/xiaoma-auto-full-pipeline}/steps/step-05-finalize.md

@@ -2,6 +2,7 @@
 name: "step-05-finalize"
 description: "Generate unified completion report across both phases, validate all artifacts, and provide final summary"
 nextStepFile: null
+kind: "terminal"
 ---
 
 # Step 5 of 5: Finalize Full Pipeline
@@ -39,7 +40,7 @@ For each missing artifact, log a warning. If PRD, Epics, or sprint-status.yaml a
 
 ### 2. Run Completion Checklist
 
-Load and evaluate: `{project-root}/_xiaoma/xmc/workflows/5-full-pipeline/auto-full-pipeline/checklist.md`
+Load and evaluate: `./checklist.md`
 
 Mark each item as passed or failed based on artifact verification and phase status tracking.
 
@@ -58,6 +59,19 @@ Mark each item as passed or failed based on artifact verification and phase stat
 - Phase 3 stories completed: `{stories_completed}`
 - Phase 3 total fix iterations across all stories
 
+**From sub-pipeline status JSON files (fresh read from disk; tolerate missing files):**
+
+- Phase 1 — `{planning_artifacts}/pipeline-status.json`:
+  - Capture `readiness_status` (one of `ready` / `gaps` / `blocked` / `not_checked`) — set `{phase_1_readiness}` accordingly; default to `not_checked` if file or field absent.
+  - Append every entry from its `warnings[]` to the master warnings list with prefix `[phase-1] `. Note (compatibility): auto-requirements-pipeline now emits prefix-tagged entries (each beginning with a `[step-NN]` tag from its own dictionary — see `auto-requirements-pipeline/workflow.md` "Warning Prefix-Tag Convention"), so the aggregated form here will be `[phase-1] [step-NN] <description>`. Do NOT strip the inner `[step-NN]` tag — the additive wrap is intentional and downstream consumers can pattern-match on either depth. Entries from older runs (pre-L-series) that lack the inner tag still wrap correctly and remain readable.
+- Phase 3 — per-story `{implementation_artifacts}/story-pipeline-status.{story_key}.json` archives (written by auto-story-pipeline-batch section 2.4b):
+  - **Preferred path:** Read `{implementation_artifacts}/batch-pipeline-status.json` (written by ASPB section 3.3). Take its `archived_status_files[]` field — a guaranteed-complete list of every per-story status JSON written during the batch. Read each file and aggregate.
+  - **Fallback path:** If `batch-pipeline-status.json` is missing (older ASPB / single-story mode), look for the single canonical `{implementation_artifacts}/story-pipeline-status.json` written by auto-story-pipeline/step-09 (best-effort snapshot of the LAST story only — accept this limitation and log INFO that aggregation is partial).
+  - For each file, append every entry from its `warnings[]` with prefix `[phase-3:{story_key}] ` to the master warnings list.
+  - Sum `fix_iterations_used` across all available status files into `{total_fix_iterations}` (overrides the rougher in-memory estimate above when available).
+  - Also read `{implementation_artifacts}/batch-pipeline-status.json` `failed_story_keys[]`; for each failed story emit a synthetic warning `[phase-3:{story_key}] story halted/failed during batch — see story file or archive for details.` so failures surface in the master warning list even if no per-story `warnings[]` was populated.
+- De-duplicate the master warnings list (preserve first occurrence) and cap at 100 entries; if truncated, append a final summary entry `"... ({n_more} more warnings truncated)"`.
+
 ### 4. Generate Unified Completion Report
 
 Set `{full_steps_completed}` = 5 and `{full_pipeline_status}` = "complete" now, before printing, so the report reflects the final accurate values.
@@ -107,6 +121,7 @@ Write to: `{implementation_artifacts}/full-pipeline-status.json`
   "phases": {
     "requirements": {
       "status": "{phase_1_status}",
+      "readiness_status": "{phase_1_readiness}",
       "artifacts": {
         "requirements_analysis": "{planning_artifacts}/requirements-analysis.md",
         "architecture_analysis": "{planning_artifacts}/current-architecture-analysis.md",
@@ -132,10 +147,19 @@ Write to: `{implementation_artifacts}/full-pipeline-status.json`
       "epics_total": "{total_epic_count}",
       "total_fix_iterations": "{total_fix_iterations}"
     }
-  }
+  },
+  "warnings": [
+    "{aggregated_warning_1}",
+    "{aggregated_warning_2}"
+  ]
 }
 ```
 
+Notes for serialization:
+- `readiness_status` is sourced from Phase 1's `pipeline-status.json`. If that file or field is missing, write the literal string `"not_checked"`.
+- `warnings` is the aggregated, de-duplicated list assembled in section 3 (with `[phase-1] ` / `[phase-3:{story_key}] ` prefixes preserved). Write `[]` if empty.
+- Use temp-file-then-rename for the write (write to `full-pipeline-status.json.tmp`, then atomic rename) to avoid partial writes.
+
 ### 6. Provide Next Steps
 
 **If all stories completed ({phase_3_status} == "success"):**
@@ -182,7 +206,9 @@ Write to: `{implementation_artifacts}/full-pipeline-status.json`
 - All 3 phases completed successfully
 - All planning artifacts verified
 - All stories developed and marked "done"
-- Machine-readable full-pipeline-status.json generated
+- Machine-readable full-pipeline-status.json generated with aggregated warnings and `readiness_status` from Phase 1
+- Sub-pipeline status JSON files (Phase 1 `pipeline-status.json`, Phase 3 `story-pipeline-status.json`) consumed when available
+- Atomic temp-file-then-rename write used for `full-pipeline-status.json`
 - Unified completion report generated
 - Next steps provided
 
@@ -192,3 +218,4 @@ Write to: `{implementation_artifacts}/full-pipeline-status.json`
 - Partial story completion not properly reported
 - Not providing next steps for partial/failed completions
 - Not generating machine-readable status file
+- Silently dropping sub-pipeline warnings (Phase 1 / Phase 3) — the aggregated `warnings[]` must reflect all upstream signals

package/src/{xmc/workflows/5-full-pipeline/auto-full-pipeline → xmc-skills/5-full-pipeline/xiaoma-auto-full-pipeline}/workflow.md

@@ -12,9 +12,9 @@ description: "Fully automated requirements-to-delivery pipeline: requirements an
 - **Phase 1 — Requirements Analysis** (delegates to auto-requirements-pipeline)
   - Analyst (xiaofen) → Architect (xiaojia) → PM (xiaochan) → Architect (xiaojia)
 - **Phase 2 — Bridge** (sprint planning)
-  - SM (xiaomin) — Generate sprint tracking from epics
+  - Dev (xiaokai) — Generate sprint tracking from epics
 - **Phase 3 — Story Development** (delegates to auto-story-pipeline-batch)
-  - SM (xiaomin) → PM (xiaochan) → Dev (xiaokai) → Reviewer → QA (xiaoce)
+  - Dev (xiaokai) → PM (xiaochan) → Dev (xiaokai) → Reviewer → Dev (xiaokai)
 
 - Communicate all responses in {communication_language} and generate all documents in {document_output_language}
 - Execute ALL steps in exact order; do NOT skip steps
@@ -91,11 +91,10 @@ Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
 
 ### Paths
 
-- `installed_path` = `{project-root}/_xiaoma/xmc/workflows/5-full-pipeline/auto-full-pipeline`
-- `requirements_pipeline` = `{project-root}/_xiaoma/xmc/workflows/1-analysis/auto-requirements-pipeline/workflow.md`
-- `sprint_planning_workflow` = `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-sprint-planning/workflow.md`
-- `story_pipeline_batch` = `{project-root}/_xiaoma/xmc/workflows/4-implementation/auto-story-pipeline-batch/workflow.md`
-- `validation` = `{installed_path}/checklist.md`
+- `requirements_pipeline` = `skill:xiaoma-auto-requirements-pipeline`
+- `sprint_planning_workflow` = `skill:xiaoma-sprint-planning`
+- `story_pipeline_batch` = `skill:xiaoma-auto-story-pipeline-batch`
+- `validation` = `{skill-root}/checklist.md`
 
 ### Context
 
@@ -105,4 +104,4 @@ Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
 
 ## EXECUTION
 
-Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/5-full-pipeline/auto-full-pipeline/steps/step-01-init-and-validate.md` to begin the pipeline.
+Read fully and follow: `./steps/step-01-init-and-validate.md` to begin the pipeline.

package/src/{xmc/workflows/5-full-pipeline/auto-prd-to-stories → xmc-skills/5-full-pipeline/xiaoma-auto-prd-to-stories}/checklist.md

@@ -41,3 +41,7 @@ Use this checklist to validate the PRD-to-Stories pipeline completed successfull
 - [ ] **Phase Boundary Summaries Output** — End-of-phase state snapshots logged for context-recovery
 - [ ] **Final Report Generated** — step-05 produced a unified completion report listing all artifacts and counts
 - [ ] **Artifact Consistency** — `sprint-status.yaml` story keys match story files on disk one-to-one (allowing for documented failures)
+- [ ] **Machine-Readable Status Written** — `{implementation_artifacts}/prd-to-stories-status.json` exists, parses as valid JSON, and contains all required top-level fields (`pipeline`, `date`, `project`, `status`, `master_steps_completed`, `input`, `phases`, `warnings`)
+- [ ] **Atomic Status Write** — `prd-to-stories-status.json` was written via temp-file-then-rename (no leftover `.tmp` file in `{implementation_artifacts}/`)
+- [ ] **Warnings Aggregated in Status JSON** — Structural Warnings from the human report (FR-coverage gaps, Tier C entries, self-reported missing subsections, FR-Coverage-Map discrepancies, checklist findings) are also present in `prd-to-stories-status.json#warnings` with prefix tags
+- [ ] **Bridge-Failure Marker (if Phase 2 failed)** — When `{phase_2_status} == "failed"`, `{implementation_artifacts}/bridge-failure.json` exists with the schema documented in step-03 (failure_reason, sprint_planning_error, validation_signals, phase_1_artifacts_preserved, recovery_instructions). When `{phase_2_status} == "success"`, this file should NOT exist (or is leftover from a prior failed run and is documented in `warnings[]`).

package/src/{xmc/workflows/5-full-pipeline/auto-prd-to-stories → xmc-skills/5-full-pipeline/xiaoma-auto-prd-to-stories}/steps/step-01-init-and-validate.md

@@ -2,6 +2,7 @@
 name: 'step-01-init-and-validate'
 description: 'Validate prd.md and sub-workflow paths, initialize PRD-to-Stories pipeline state variables, and prepare for execution'
 nextStepFile: './step-02-create-epics.md'
+kind: 'init'
 ---
 
 # Step 1 of 5: Initialize and Validate Environment
@@ -40,16 +41,16 @@ Read config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
 
 Check that all delegated sub-workflows are readable:
 
-1. **Create Epics & Stories** — `{project-root}/_xiaoma/xmc/workflows/3-solutioning/xiaoma-create-epics-and-stories/workflow.md`
+1. **Create Epics & Stories** — `skill:xiaoma-create-epics-and-stories`
    - If missing: HALT — "xiaoma-create-epics-and-stories workflow not found. Verify XiaoMa installation is complete."
 
-2. **Sprint Planning** — `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-sprint-planning/workflow.md`
+2. **Sprint Planning** — `skill:xiaoma-sprint-planning`
    - If missing: HALT — "xiaoma-sprint-planning workflow not found. Verify XiaoMa installation is complete."
 
-3. **Create Story** — `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-create-story/workflow.md`
+3. **Create Story** — `skill:xiaoma-create-story`
    - If missing: HALT — "xiaoma-create-story workflow not found. Verify XiaoMa installation is complete."
 
-4. **Checklist** — `{installed_path}/checklist.md` must be readable for step-05 self-check.
+4. **Checklist** — `{skill-root}/checklist.md` must be readable for step-05 self-check.
    - If missing: Output WARNING — "checklist.md not found; final self-check will be skipped."
 
 ### 4. Check Existing Artifacts (Informational)
@@ -117,8 +118,8 @@ Language: {communication_language} / {document_output_language}
 
 Pipeline Phases (stops BEFORE development):
   ⬜ Phase 1 — Create Epics (PM xiaochan, delegates to xiaoma-create-epics-and-stories)
-  ⬜ Phase 2 — Sprint Planning Bridge (SM xiaomin, delegates to xiaoma-sprint-planning)
-  ⬜ Phase 3 — Batch Create Story Files (SM xiaomin, N Agent subprocesses)
+  ⬜ Phase 2 — Sprint Planning Bridge (Dev xiaokai, delegates to xiaoma-sprint-planning)
+  ⬜ Phase 3 — Batch Create Story Files (Dev xiaokai, N Agent subprocesses)
 
 Finalization: Step 5 — Unified completion report for business-architect review
 
@@ -135,7 +136,7 @@ Master Step: 1/5
 
 ## NEXT STEP
 
-**NEXT:** Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/5-full-pipeline/auto-prd-to-stories/steps/step-02-create-epics.md`
+**NEXT:** Read fully and follow: `./steps/step-02-create-epics.md`
 
 ---
 

package/src/{xmc/workflows/5-full-pipeline/auto-prd-to-stories → xmc-skills/5-full-pipeline/xiaoma-auto-prd-to-stories}/steps/step-02-create-epics.md

@@ -2,6 +2,7 @@
 name: 'step-02-create-epics'
 description: 'Phase 1 — PM role creates epics and stories from prd.md by delegating to create-epics-and-stories workflow'
 nextStepFile: './step-03-bridge-sprint-planning.md'
+kind: 'orchestrator'
 ---
 
 # Step 2 of 5: Create Epics and Stories
@@ -56,7 +57,7 @@ Load these artifacts in order:
 
 Before delegating, verify the required workflow exists:
 
-1. Check that `{project-root}/_xiaoma/xmc/workflows/3-solutioning/xiaoma-create-epics-and-stories/workflow.md` is readable
+1. Check that `skill:xiaoma-create-epics-and-stories` is readable
 2. If workflow is missing:
    - HALT — "Required workflow not found: `xiaoma-create-epics-and-stories`. Verify XiaoMa installation is complete."
 
@@ -136,7 +137,7 @@ Proceeding to Phase 2 — Sprint Planning Bridge...
 
 ## NEXT STEP
 
-**NEXT:** Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/5-full-pipeline/auto-prd-to-stories/steps/step-03-bridge-sprint-planning.md`
+**NEXT:** Read fully and follow: `./steps/step-03-bridge-sprint-planning.md`
 
 ---
 

package/src/{xmc/workflows/5-full-pipeline/auto-prd-to-stories → xmc-skills/5-full-pipeline/xiaoma-auto-prd-to-stories}/steps/step-03-bridge-sprint-planning.md

@@ -2,13 +2,14 @@
 name: 'step-03-bridge-sprint-planning'
 description: 'Phase 2 bridge: auto-run sprint planning to generate sprint-status.yaml from epics, connecting epics output to per-story creation input'
 nextStepFile: './step-04-batch-create-stories.md'
+kind: 'bridge'
 ---
 
 # Step 3 of 5: Bridge — Sprint Planning
 
 **Goal:** Generate `sprint-status.yaml` from the epics produced in Phase 1. This bridges the epic breakdown to the per-story file generation in Phase 3. Without this step, Phase 3 cannot determine which stories to process.
 
-**Role:** SM (xiaomin) — Scrum Master generating sprint tracking
+**Role:** Dev (xiaokai) — Sprint-Planning (SP) mode generating sprint tracking
 
 ---
 
@@ -23,7 +24,7 @@ nextStepFile: './step-04-batch-create-stories.md'
   Phase 2 of 3 — Sprint Planning Bridge
 ═══════════════════════════════════════════════════
 
-Switching role to SM (xiaomin)...
+Switching to Sprint-Planning mode (xiaokai)...
 Generating sprint-status.yaml from epics...
 This bridges epics → per-story file generation.
 ───────────────────────────────────────────────────
@@ -41,17 +42,17 @@ Also check for sharded epics format (safety net only — Phase 1 produces a sing
 - If sharded version found, proceed — the sprint planning workflow handles both formats
 - If neither format found: HALT — "No epics found in any format. Phase 1 may have failed."
 
-### 3. Switch to SM Role
+### 3. Switch to Sprint-Planning Mode
 
-Adopt the SM (xiaomin) persona:
+Adopt the Dev agent's Sprint-Planning mode:
 
-- You are xiaomin, the Technical Scrum Master + Story Preparation Specialist
+- You are xiaokai, the Dev agent applying Technical Scrum Master + Story Preparation discipline
 - Your purpose is to translate the epic breakdown into a sprint-status tracking file
 - Communication style: Crisp and checklist-driven
 
 ### 4. Execute Sprint Planning Workflow
 
-Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-sprint-planning/workflow.md`
+Read fully and follow: `skill:xiaoma-sprint-planning`
 
 **Critical Pipeline Mode Instructions:**
 
@@ -68,19 +69,71 @@ Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/4-implementation/xi
 - When the workflow outputs "Next Steps" guidance at the end, **ignore it** — the next steps are handled by THIS pipeline automatically
 - **Complete ALL steps without stopping**
 
-### 5. Verify Sprint Status Output
+**Capture errors:** record any HALT message or fatal error emitted by the sprint-planning workflow into `{sprint_planning_error}` (empty string if none). Used by the Bridge-Failure Fallback below.
+
+### 5. Verify Sprint Status Output (with Bridge-Failure Fallback)
 
 After sprint planning completes, verify:
 
-1. **Sprint Status File** — `{implementation_artifacts}/sprint-status.yaml` must exist
-   - If missing: HALT — "Sprint planning failed to generate sprint-status.yaml. Check epics format and retry."
+1. **Sprint Status File** — `{implementation_artifacts}/sprint-status.yaml` must exist.
 
 2. **Content Validation** — Read the generated file and verify:
    - Contains `development_status:` section
    - Contains at least one story entry (key matches `<digit>-<digit>-*` pattern, not just epic entries)
    - Valid YAML syntax
 
-3. **Count Stories** — Parse and count:
+3. **Bridge-Failure Fallback (preserves Phase 1 epics; allows resume):**
+
+   If `{implementation_artifacts}/sprint-status.yaml` is missing OR fails content validation, **do NOT silently HALT**. Phase 1 has already produced `epics.md`; losing the run context here would force re-running Phase 1 and re-generating epics. Instead:
+
+   a. Write a structured failure marker to `{implementation_artifacts}/bridge-failure.json` (atomic temp-file-then-rename):
+
+      ```json
+      {
+        "pipeline": "auto-prd-to-stories",
+        "stage": "step-03-bridge-sprint-planning",
+        "date": "{date}",
+        "failure_reason": "sprint-status.yaml missing or invalid after sprint-planning workflow returned",
+        "sprint_planning_error": "{sprint_planning_error}",
+        "validation_signals": {
+          "file_exists": false_or_true,
+          "yaml_valid": false_or_true,
+          "has_development_status": false_or_true,
+          "story_entries_present": false_or_true
+        },
+        "phase_1_artifacts_preserved": {
+          "prd": "{planning_artifacts}/prd.md",
+          "epics": "{planning_artifacts}/epics.md"
+        },
+        "recovery_instructions": [
+          "1. Inspect epics.md for malformed epic/story structure (most common cause).",
+          "2. Run /xiaoma-sprint-planning (SP) manually with the same epics.md to reproduce the error in isolation.",
+          "3. Once sprint-status.yaml is healthy, re-run auto-prd-to-stories; step-01 will detect epics.md exists and proceed directly to Phase 2 → 3."
+        ]
+      }
+      ```
+
+      Write strategy (atomic): write to `bridge-failure.json.tmp` first; verify JSON parses; rename to `bridge-failure.json`. Failure to write the marker is a WARNING (logged) — proceed with the HALT below regardless, since the human-readable HALT message already contains the critical information.
+
+   b. Set `{phase_2_status}` = "failed"; do NOT advance `{phase_3_status}`.
+
+   c. HALT with this exact user-facing message — **be specific about resume mechanics**, since the value of preserving Phase 1 epics is wasted if the user thinks they must restart:
+
+      ```
+      ❌ Phase 2 (Sprint Planning Bridge) failed.
+
+      Sprint planning produced no usable sprint-status.yaml. Failure marker written to:
+        {implementation_artifacts}/bridge-failure.json
+
+      ✅ Phase 1 artifact (epics.md) is preserved.
+
+      🔄 Recovery:
+        1. Fix the underlying cause (likely malformed epics.md — see bridge-failure.json for details).
+        2. Run /xiaoma-sprint-planning (SP) manually to confirm sprint-status.yaml generates cleanly.
+        3. Re-run /xiaoma-auto-prd-to-stories. step-01 already treats epics.md as informational; pipeline will skip re-creation and pick up at Phase 2.
+      ```
+
+4. **Count Stories** (only if validation passed) — Parse and count:
    - `{epic_count}` — Number of `epic-N` entries
    - `{story_count}` — Total story keys matching `<digit>-<digit>-*`
    - `{backlog_count}` — Stories with status `backlog`
@@ -124,7 +177,7 @@ Proceeding to Phase 3 — Batch Story File Generation...
 
 ## NEXT STEP
 
-**NEXT:** Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/5-full-pipeline/auto-prd-to-stories/steps/step-04-batch-create-stories.md`
+**NEXT:** Read fully and follow: `./steps/step-04-batch-create-stories.md`
 
 ---
 
@@ -138,6 +191,7 @@ Proceeding to Phase 3 — Batch Story File Generation...
 ## FAILURE MODES
 
 - Epics file missing or unreadable
-- Sprint planning workflow fails
-- Generated sprint-status.yaml is malformed or empty
-- No story entries found in sprint status
+- Sprint planning workflow fails — instead of bare HALT, a structured `bridge-failure.json` marker is written and Phase 1 `epics.md` is preserved for resume
+- Generated sprint-status.yaml is malformed or empty — same fallback path
+- No story entries found in sprint status — same fallback path (the explicit "no processable stories" HALT at the end of section 5 also routes through here when sprint-status.yaml exists but contains no story keys)
+- Failing to write `bridge-failure.json` atomically (would leave a half-written marker; use temp-file-then-rename)

package/src/{xmc/workflows/5-full-pipeline/auto-prd-to-stories → xmc-skills/5-full-pipeline/xiaoma-auto-prd-to-stories}/steps/step-04-batch-create-stories.md

@@ -2,13 +2,14 @@
 name: 'step-04-batch-create-stories'
 description: 'Phase 3 — Batch create detailed story files: for each backlog story, launch an Agent subprocess running xiaoma-create-story (and ONLY that — no dev/review/test)'
 nextStepFile: './step-05-finalize.md'
+kind: 'orchestrator'
 ---
 
 # Step 4 of 5: Batch Create Detailed Story Files
 
 **Goal:** For every backlog story in `sprint-status.yaml`, launch an independent Agent subprocess that runs `xiaoma-create-story` to produce a detailed `{story_key}.md` file. The Agent stops immediately after story creation — it does NOT enter development, code-review, or testing.
 
-**Role:** SM (xiaomin) — Pipeline Batch Scheduler
+**Role:** Dev (xiaokai) — Pipeline Batch Scheduler (Story-Preparation mode)
 
 ---
 
@@ -28,7 +29,7 @@ Main conversation (scheduler, minimal context)
 
 ### Core Rules (Strictly Follow)
 
-1. **Each story processed by independent Agent** — Use the Agent tool to launch a general-purpose subprocess, pass complete story info + paths, have the Agent run `xiaoma-create-story` end-to-end, then return a structured summary
+1. **Each story processed by independent Agent** — Use the Agent tool to launch a **general-purpose subprocess with FULL tool-execution capability** (file read/write/edit plus codebase search — **NOT** a restricted or read-only subagent such as an explore/plan/search-only type, which cannot write the story file). Pass complete story info + paths, have the Agent run `xiaoma-create-story` end-to-end, then return a structured summary
 2. **Agent must STOP after xiaoma-create-story** — Do NOT chain into any downstream step. This is enforced in the Agent prompt with explicit hard-boundary instructions
 3. **Main loop stays lightweight** — Main scheduler only: query sprint-status → launch Agent → read result → query remaining → continue or end
 4. **Serial processing** — Process one story at a time, wait for Agent completion before next, avoid concurrent modification conflicts on `sprint-status.yaml`
@@ -47,7 +48,7 @@ Main conversation (scheduler, minimal context)
   Phase 3 of 3 — Batch Create Detailed Story Files
 ═══════════════════════════════════════════════════
 
-Switching role to SM (xiaomin) batch scheduler...
+Switching to Dev (xiaokai) batch scheduler (Story-Preparation mode)...
 Using Agent subprocess isolation — each story processed independently.
 
 For each story, an independent Agent will:
@@ -103,7 +104,7 @@ Stories created so far: {stories_created} | Failed: {stories_failed}
 
 <critical>
 
-Use the **Agent tool** to launch a **general-purpose subprocess** to create this story.
+Use the **Agent tool** to launch a **general-purpose subprocess with FULL tool-execution capability** to create this story — the subprocess MUST have the complete tool set enabled (file read/write/edit plus codebase search), because it has to write the story file and update `sprint-status.yaml`. Do **NOT** delegate to a restricted or read-only subagent (e.g. an explore-, plan-, or search-only type): such agents cannot write files, so story creation would fail. When the host tool exposes a subagent-type selector, choose the full/unrestricted toolset (in Claude Code this is the `general-purpose` type). *(This grants tool **capability**; the **HARD BOUNDARY** below then narrows the Agent's **behaviour** so it does not run tests or modify source files outside the planning/implementation artifacts — capability and behavioural scope are deliberately separate.)*
 
 The Agent's prompt MUST contain the following complete information for independent work:
 
@@ -128,7 +129,7 @@ The Agent's prompt MUST contain the following complete information for independe
 
 **3. Workflow Path (single workflow, narrow scope):**
 
-- `create_story_workflow`: `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-create-story/workflow.md`
+- `create_story_workflow`: `skill:xiaoma-create-story`
 
 **4. Project Context:**
 
@@ -136,7 +137,7 @@ The Agent's prompt MUST contain the following complete information for independe
 
 **5. Processing Instructions (paste verbatim into the Agent prompt):**
 
-> You are an SM (xiaomin) story-creation specialist running in an isolated subprocess. Your one and only job is to create the detailed user-story file for `{current_story_key}` by reading and following the `xiaoma-create-story` workflow at `{create_story_workflow}`.
+> You are xiaokai, the Dev agent in Story-Preparation mode, running in an isolated subprocess. Your one and only job is to create the detailed user-story file for `{current_story_key}` by reading and following the `xiaoma-create-story` workflow at `{create_story_workflow}`.
 >
 > **Steps:**
 >
@@ -233,6 +234,7 @@ Read the Agent's returned STORY_RESULT block.
 
 **IF the Agent failed (`final_status: failed`, no STORY_RESULT block, or file-missing case above):**
 
+0. **Transient-failure retry (at most once per story, BEFORE blacklisting):** distinguish an *environment-transient* failure from a *story-level* failure. The failure is transient when BOTH hold: (a) the Agent returned no STORY_RESULT at all (stream timeout, connection drop, runner crash — as opposed to an explicit `final_status: failed` verdict), AND (b) the disk shows no partial work (story file absent at `{implementation_artifacts}/{current_story_key}.md` AND sprint-status still has the story at `backlog`). In that case the story itself was never judged — re-launch the Agent subprocess once with the same prompt, tracking `{transient_retry_used}` per story key so each story gets at most ONE such retry. If the retry succeeds, take the success branch as normal; if it also fails, or the original failure was NOT transient (explicit `failed` verdict, or partial work found on disk), fall through to the blacklist steps below. *(Rationale: mirrors the bounded-retry pattern of auto-story-pipeline step-02 section 4. Without this, a single network blip permanently drops the story — and with it every FR that only this story covers — even though nothing about the story itself was wrong.)*
 1. Increment `{stories_failed}` by 1
 2. Add `{current_story_key}` to `{failed_story_keys}` (prevents infinite re-selection)
 3. Append to `{story_results}`: `{ story_key, final_status: "failed", error }`
@@ -291,7 +293,7 @@ Proceeding to Finalization...
 
 ## NEXT STEP
 
-**NEXT:** Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/5-full-pipeline/auto-prd-to-stories/steps/step-05-finalize.md`
+**NEXT:** Read fully and follow: `./steps/step-05-finalize.md`
 
 ---