@zeyue0329/xiaoma-cli 1.12.0 → 1.15.0

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-skills/5-full-pipeline/xiaoma-auto-prd-to-stories/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: xiaoma-auto-prd-to-stories
+description: "Automated PRD-to-Stories pipeline (NO development): prd.md → epics → sprint-status → per-story detailed files. Stops before dev/review/QA so business architects can evaluate user-story quality. Use when the user says 'PRD 转故事', 'auto prd to stories', or 'APS'"
+---
+
+Follow the instructions in [workflow.md](workflow.md).

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

@@ -0,0 +1,47 @@
+# Auto PRD-to-Stories Pipeline Completion Checklist
+
+Use this checklist to validate the PRD-to-Stories pipeline completed successfully. This pipeline stops BEFORE development, so only planning + sprint-status + per-story files are in scope.
+
+## Phase 1 — Epics Creation Validation
+
+- [ ] **Input PRD Present** — `{planning_artifacts}/prd.md` exists and was readable at pipeline start
+- [ ] **Epics Created** — `{planning_artifacts}/epics.md` exists with full epic/story breakdown
+- [ ] **PRD Coverage** — Every major functional requirement in `prd.md` is covered by at least one epic
+- [ ] **Story Granularity** — Every epic contains at least one user story
+- [ ] **Acceptance Criteria Present** — Every story has BDD-formatted acceptance criteria (Given/When/Then)
+
+## Phase 2 — Sprint Planning Bridge Validation
+
+- [ ] **Sprint Status Generated** — `{implementation_artifacts}/sprint-status.yaml` exists with valid YAML
+- [ ] **All Epics Represented** — Every epic from `epics.md` has an `epic-N` entry in sprint status
+- [ ] **All Stories Represented** — Every story from `epics.md` has a `N-N-kebab-name` entry in sprint status
+
+## Phase 3 — Per-Story File Generation Validation
+
+- [ ] **One File Per Story** — Every story key in sprint-status.yaml has a corresponding `{implementation_artifacts}/{story_key}.md` file (excluding failed keys)
+- [ ] **Top-Level Sections Present** — Every story file contains: `Status`, `Story`, `Acceptance Criteria`, `Tasks / Subtasks`, `Dev Notes`
+- [ ] **Dev Notes Detailed-Design Subsections Present** — Every story file's `Dev Notes` contains these three mandatory subsections (per the step-04 Detailed Design Output Contract):
+  - [ ] `Functional Requirements Addressed` — lists FR/feature references from prd.md or epics.md
+  - [ ] `Data Model & Database Design` — concrete tables/fields/constraints/indexes OR an explicit `TBD by architect` line with reason
+  - [ ] `Implementation Logic` — concrete interface signatures / algorithm / state machine / error handling OR an explicit `TBD by architect` line with reason
+- [ ] **No Silent Omissions** — No story file contains a Dev Notes subsection that is only a heading with no body content
+- [ ] **Story Status Correct** — Every successfully created story file has `Status: ready-for-dev`
+- [ ] **No Stories Beyond ready-for-dev** — No story file shows status `in-progress`, `review`, or `done` (this pipeline never enters those states)
+- [ ] **Failed Stories Documented** — Any story key in `failed_story_keys` has its failure recorded in the final report with an error reason
+
+## Cross-Phase Traceability Validation
+
+- [ ] **FR Coverage Map Filled** — `epics.md` contains a `### FR Coverage Map` section with concrete `FR-N → Epic X / Story X.Y` mappings (not raw `{{placeholder}}`)
+- [ ] **FR Reverse Traceability** — Every functional requirement extracted from `prd.md` is referenced by at least one story file (verified by step-05's reverse-traceability check). Uncovered FRs are documented in Structural Warnings.
+
+## Pipeline-Level Validation
+
+- [ ] **All 5 Master Steps Executed** — Steps 1–5 completed without HALT (or HALT properly reported)
+- [ ] **No Dev/Review/Test Side Effects** — No code files modified outside `{planning_artifacts}` and `{implementation_artifacts}`
+- [ ] **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-skills/5-full-pipeline/xiaoma-auto-prd-to-stories/steps/step-01-init-and-validate.md

@@ -0,0 +1,156 @@
+---
+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
+
+**Goal:** Verify the input `prd.md` exists, all delegated sub-workflows are accessible, and initialize master pipeline state variables.
+
+**Role:** Pipeline Orchestrator
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Load Configuration
+
+Read config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
+
+- `project_name`, `user_name`
+- `communication_language`, `document_output_language`
+- `user_skill_level`
+- `planning_artifacts`, `implementation_artifacts`
+- `date` as system-generated current datetime
+
+**HALT if config not found:** "XiaoMa config not found at `{project-root}/_xiaoma/xmc/config.yaml`. Run `npx @zeyue0329/xiaoma-cli install` first."
+
+### 2. Validate Required Input
+
+**Input PRD** — `{planning_artifacts}/prd.md` must exist and be readable.
+
+- If missing: HALT — "No PRD document found at `{planning_artifacts}/prd.md`. This pipeline requires a pre-existing PRD as input. Either:
+  1. Place your PRD at `{planning_artifacts}/prd.md`, OR
+  2. Run the full auto-requirements-pipeline (AR) first to generate a PRD from a requirements document."
+
+- Read the first 20 lines of `prd.md` to extract document title and confirm it is non-empty. If empty: HALT — "prd.md exists but is empty."
+
+### 3. Validate Sub-Workflow Paths
+
+Check that all delegated sub-workflows are readable:
+
+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** — `skill:xiaoma-sprint-planning`
+   - If missing: HALT — "xiaoma-sprint-planning workflow not found. Verify XiaoMa installation is complete."
+
+3. **Create Story** — `skill:xiaoma-create-story`
+   - If missing: HALT — "xiaoma-create-story workflow not found. Verify XiaoMa installation is complete."
+
+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)
+
+Scan for pre-existing output artifacts from prior runs:
+
+- `{planning_artifacts}/epics.md`
+- `{implementation_artifacts}/sprint-status.yaml`
+- `{implementation_artifacts}/*.md` matching pattern `<digit>-<digit>-*.md` (per-story files)
+
+If any exist, log INFO — "Pre-existing artifact found: {filename}. The pipeline is idempotent: `xiaoma-sprint-planning` will smart-detect existing story files and `xiaoma-create-story` skips stories already at `ready-for-dev`."
+
+Also informational scan for optional context (NOT required for this pipeline, but if present they enrich story Dev Notes):
+
+- `{planning_artifacts}/requirements-analysis.md`
+- `{planning_artifacts}/current-architecture-analysis.md`
+- `{planning_artifacts}/architecture.md`
+- `{planning_artifacts}/*ux*.md`
+
+Set pipeline-level flag `{architecture_absent}`:
+
+- If NONE of `{planning_artifacts}/architecture.md`, `{planning_artifacts}/current-architecture-analysis.md`, or any `{planning_artifacts}/*architecture*.md` exists: set `{architecture_absent}` = `true`
+- Otherwise: set `{architecture_absent}` = `false`
+
+If `{architecture_absent}` == `true`: log INFO — "No architecture documents found. Story Dev Notes will be derived solely from prd.md + epics.md. The Data Model subsection of each story will be flagged 'TBD by architect' wherever no schema clues exist in those sources."
+
+This flag is consumed by step-04 — it is passed into every Agent subprocess so each story-creation Agent knows whether to expect architectural context or to default the Data Model subsection to `TBD by architect`.
+
+### 5. Initialize Master Pipeline State Variables
+
+- `{prd_to_stories_status}` = "initialized"
+- `{steps_completed}` = 1
+- `{phase_1_status}` = "pending"
+- `{phase_2_status}` = "pending"
+- `{phase_3_status}` = "pending"
+- `{stories_created}` = 0
+- `{stories_failed}` = 0
+- `{failed_story_keys}` = []
+- `{story_results}` = []
+- `{architecture_absent}` = set by Section 4's scan above (`true` or `false`)
+- Ensure `{planning_artifacts}/` directory exists
+- Ensure `{implementation_artifacts}/` directory exists
+
+### 6. Load Context
+
+- Load `project_context` = `**/project-context.md` (if exists)
+
+### 7. Output Environment Summary
+
+**Output:**
+
+```
+═══════════════════════════════════════════════════
+  Auto PRD-to-Stories Pipeline — INITIALIZED
+═══════════════════════════════════════════════════
+
+Project: {project_name}
+User: {user_name}
+Date: {date}
+Language: {communication_language} / {document_output_language}
+
+📋 Input PRD: {planning_artifacts}/prd.md
+📂 Planning Artifacts: {planning_artifacts}/
+📂 Implementation Artifacts: {implementation_artifacts}/
+
+Pipeline Phases (stops BEFORE development):
+  ⬜ Phase 1 — Create Epics (PM xiaochan, delegates to xiaoma-create-epics-and-stories)
+  ⬜ 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
+
+⚠️  This pipeline does NOT enter development, code-review, or testing.
+   Output is the input to a manual quality review by business architects.
+
+Master Step: 1/5
+═══════════════════════════════════════════════════
+```
+
+**Auto-Proceed:** YES — Do NOT wait for user input. Proceed to step-02.
+
+---
+
+## NEXT STEP
+
+**NEXT:** Read fully and follow: `./steps/step-02-create-epics.md`
+
+---
+
+## SUCCESS METRICS
+
+- Config loaded and all variables resolved
+- `prd.md` exists and is non-empty
+- All three delegated sub-workflows accessible
+- Master state variables initialized
+- Environment summary output
+
+## FAILURE MODES
+
+- Missing `prd.md` (cannot proceed without input)
+- Missing XiaoMa config (installation incomplete)
+- Missing sub-workflow files (installation incomplete)
+- Directory creation failures

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

@@ -0,0 +1,157 @@
+---
+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
+
+**Goal:** Break down the input `prd.md` into epics and user stories using the existing `xiaoma-create-epics-and-stories` workflow. Produces `{planning_artifacts}/epics.md`.
+
+**Role:** PM (xiaochan) — Product Manager + Requirements Specialist
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Announce Phase Entry
+
+**Output:**
+
+```
+═══════════════════════════════════════════════════
+  Phase 1 of 3 — Create Epics from PRD
+═══════════════════════════════════════════════════
+
+Switching role to PM (xiaochan)...
+Delegating to xiaoma-create-epics-and-stories workflow.
+───────────────────────────────────────────────────
+```
+
+### 2. Switch to PM Role
+
+Adopt the PM (xiaochan) persona:
+
+- You are xiaochan, the Product Manager + Requirements Specialist
+- Your purpose is to break down the input PRD into well-structured epics and user stories
+- Communication style: Precise, structured, stakeholder-aware
+- Focus on complete feature coverage and actionable story granularity
+
+### 3. Load Required Context
+
+Load these artifacts in order:
+
+1. **PRIMARY SOURCE** — Read the FULL file from beginning to end
+   - File: `{planning_artifacts}/prd.md` (validated in step-01)
+   - Requirement: Complete read, no skipping
+
+2. **OPTIONAL SECONDARY SOURCES** — Read each fully IF the file exists; if not present, SKIP silently
+   - File: `{planning_artifacts}/requirements-analysis.md` — Optional
+   - File: `{planning_artifacts}/current-architecture-analysis.md` — Optional
+   - File: `{planning_artifacts}/architecture.md` — Optional
+
+   **Note:** Unlike the auto-requirements-pipeline's step-06 which treats these as required, this pipeline treats them as opportunistic enrichment. The new workflow's contract is "PRD-only input is sufficient."
+
+### 4. Verify Workflow Prerequisites
+
+Before delegating, verify the required workflow exists:
+
+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."
+
+### 5. Execute Epic and Story Creation (Delegate)
+
+Invoke the `xiaoma-create-epics-and-stories` skill to create the epic breakdown.
+
+**CRITICAL PIPELINE MODE INSTRUCTIONS:**
+
+- This is running in **automated pipeline mode** — do NOT pause for user input
+- The create-epics-and-stories workflow has 4 step files: validate-prerequisites → design-epics → create-stories → final-validation
+- When ANY step presents a menu with **[C] Continue**, automatically select **C** to proceed to the next step
+- Step 1 (validate-prerequisites) will ask the user to confirm discovered documents and extracted requirements — automatically confirm and continue
+- Step 1 asks "Do these extracted requirements accurately represent what needs to be built?" — auto-confirm YES and select **C**
+- When the workflow asks for user decisions on epic boundaries or story granularity, make reasonable decisions based on the PRD content
+- Ensure every PRD feature is covered by at least one epic
+- Each epic should have well-defined user stories with BDD acceptance criteria (Given/When/Then)
+- Output file MUST be: `{planning_artifacts}/epics.md`
+
+### 6. Verify Epic Output
+
+After create-epics-and-stories workflow completes:
+
+1. Verify `{planning_artifacts}/epics.md` exists and is non-empty
+2. Verify all PRD features are covered by at least one epic (sanity check)
+3. Verify each epic has at least one user story
+4. Verify stories have acceptance criteria (look for "Given"/"When"/"Then" or equivalent)
+5. **FR Coverage Map post-condition (CRITICAL):**
+   - Search `epics.md` for a section heading matching `### FR Coverage Map` (or `## FR Coverage Map`)
+   - The section MUST exist and MUST contain at least one non-placeholder mapping line (something like `FR-N → Epic X / Story X.Y`, NOT a raw `{{requirements_coverage_map}}` placeholder)
+   - **Why:** the underlying create-epics-and-stories template includes this section but the LLM occasionally skips filling it in. Without a populated coverage map, step-05's reverse-traceability check loses its anchor and the architect cannot easily verify "no PRD feature was dropped".
+   - If the section is missing OR contains an unfilled `{{...}}` placeholder:
+     - **First retry:** Re-invoke the create-epics-and-stories workflow with an explicit instruction: "The previous run left `### FR Coverage Map` empty or as a placeholder. You MUST extract every FR/feature from prd.md and produce concrete `FR-N → Epic X / Story X.Y` mappings."
+     - If the second run also fails to populate it: do NOT HALT — instead, log WARNING and continue. step-05 will fall back to grepping FR references inside story files and report any uncovered FRs as Structural Warnings.
+6. Also extract a tally for step-05:
+   - `{epics_fr_count}` = number of distinct FR-style references in the FR Coverage Map (e.g., `FR-1`, `FR-2`, … or `PRD §x.y` patterns). Save this for step-05's denominator.
+
+If epic creation failed at the file-level (epics.md missing or unreadable):
+
+- **Retry once:** Re-invoke the workflow with the same instructions
+- If still fails after retry: HALT — "Epic and story creation failed twice. Check `prd.md` for completeness and structural clarity before re-running."
+
+### 7. Output Phase 1 Summary
+
+Count epics and stories from generated `epics.md`:
+
+- `{epic_count}` = number of "## Epic N:" headings
+- `{story_count}` = number of "### Story N.N:" headings
+
+**Output:**
+
+```
+───────────────────────────────────────────────────
+  ✅ Phase 1 Complete — Epics Created
+───────────────────────────────────────────────────
+
+Output: {planning_artifacts}/epics.md
+  Total Epics: {epic_count}
+  Total Stories: {story_count}
+
+Phase 1 Status: success
+Master Step: 2/5
+
+Proceeding to Phase 2 — Sprint Planning Bridge...
+───────────────────────────────────────────────────
+```
+
+### 8. Pipeline Status Update
+
+- `{phase_1_status}` = "success"
+- `{prd_to_stories_status}` = "bridge-phase"
+- `{steps_completed}` = 2
+
+**Auto-Proceed:** YES — Do NOT wait for user input. Immediately proceed to step-03.
+
+---
+
+## NEXT STEP
+
+**NEXT:** Read fully and follow: `./steps/step-03-bridge-sprint-planning.md`
+
+---
+
+## SUCCESS METRICS
+
+- `{planning_artifacts}/epics.md` created with complete epic breakdown
+- All PRD features covered by at least one epic
+- Each epic has user stories with BDD acceptance criteria
+- Story dependencies identified (where applicable)
+
+## FAILURE MODES
+
+- PRD features not fully covered by epics
+- Stories missing acceptance criteria
+- Epic boundaries too broad or too narrow
+- Workflow not writing output file
+- Two consecutive failures of the delegated workflow