@zeyue0329/xiaoma-cli 1.0.49 → 1.0.66

package/src/xmc/workflows/5-full-pipeline/auto-full-pipeline/steps/step-05-finalize.md

@@ -0,0 +1,194 @@
+---
+name: "step-05-finalize"
+description: "Generate unified completion report across both phases, validate all artifacts, and provide final summary"
+nextStepFile: null
+---
+
+# Step 5 of 5: Finalize Full Pipeline
+
+**Goal:** Validate all output artifacts from both phases, generate a unified completion report, and provide a comprehensive summary of the entire requirements-to-delivery pipeline execution.
+
+**Role:** Master Pipeline Orchestrator
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Validate All Artifacts
+
+Check that ALL expected output files exist from both phases:
+
+**Phase 1 — Requirements Artifacts:**
+
+1. `{planning_artifacts}/requirements-analysis.md`
+2. `{planning_artifacts}/current-architecture-analysis.md`
+3. `{planning_artifacts}/prd.md`
+4. `{planning_artifacts}/epics.md`
+5. `{planning_artifacts}/architecture.md`
+6. `{planning_artifacts}/pipeline-status.json`
+
+**Phase 2 — Sprint Planning Artifact:**
+
+7. `{implementation_artifacts}/sprint-status.yaml`
+
+**Phase 3 — Development Artifacts:**
+
+8. Story files at `{implementation_artifacts}/*.md` (one per story)
+
+For each missing artifact, log a warning. If PRD, Epics, or sprint-status.yaml are missing, this is a critical failure.
+
+### 2. Run Completion Checklist
+
+Load and evaluate: `{project-root}/_xiaoma/xmc/workflows/5-full-pipeline/auto-full-pipeline/checklist.md`
+
+Mark each item as passed or failed based on artifact verification and phase status tracking.
+
+### 3. Gather Final Statistics
+
+**From sprint-status.yaml (fresh read from disk):**
+
+- Total epics
+- Total stories
+- Stories by status (done, backlog, in-progress, review)
+- Epics completed (all stories done)
+
+**From pipeline tracking:**
+
+- Phase 1 iterations: `{analysis_iteration}`, `{architecture_iteration}`, `{validation_iteration}`
+- Phase 3 stories completed: `{stories_completed}`
+- Phase 3 total fix iterations across all stories
+
+### 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.
+
+**Output:**
+
+```
+═══════════════════════════════════════════════════════════════
+  Auto Full Pipeline — COMPLETE
+═══════════════════════════════════════════════════════════════
+
+Project: {project_name}
+Date: {date}
+Master Steps Completed: {full_steps_completed}/5
+
+Phase 1 — Requirements Analysis          [{phase_1_status}]
+  ├─ Requirements Analysis                ✅/❌
+  ├─ Architecture Analysis                ✅/❌
+  ├─ PRD                                  ✅/❌
+  ├─ PRD Validation                       ✅/❌
+  ├─ Epics & Stories                      ✅/❌
+  └─ Architecture Design                  ✅/❌
+
+Phase 2 — Sprint Planning Bridge          [{phase_2_status}]
+  └─ sprint-status.yaml                   ✅/❌
+
+Phase 3 — Story Development               [{phase_3_status}]
+  ├─ Stories Completed: {done_count}/{total_story_count}
+  ├─ Epics Completed: {completed_epic_count}/{total_epic_count}
+  └─ Total Fix Iterations: {total_fix_iterations}
+
+Pipeline Status: {full_pipeline_status}
+═══════════════════════════════════════════════════════════════
+```
+
+### 5. Generate Machine-Readable Status File
+
+Write to: `{implementation_artifacts}/full-pipeline-status.json`
+
+```json
+{
+  "pipeline": "auto-full-pipeline",
+  "date": "{date}",
+  "project": "{project_name}",
+  "status": "{full_pipeline_status}",
+  "master_steps_completed": 5,
+  "phases": {
+    "requirements": {
+      "status": "{phase_1_status}",
+      "artifacts": {
+        "requirements_analysis": "{planning_artifacts}/requirements-analysis.md",
+        "architecture_analysis": "{planning_artifacts}/current-architecture-analysis.md",
+        "prd": "{planning_artifacts}/prd.md",
+        "epics": "{planning_artifacts}/epics.md",
+        "architecture": "{planning_artifacts}/architecture.md"
+      },
+      "iterations": {
+        "analysis": "{analysis_iteration}",
+        "architecture": "{architecture_iteration}",
+        "validation": "{validation_iteration}"
+      }
+    },
+    "sprint_planning": {
+      "status": "{phase_2_status}",
+      "artifact": "{implementation_artifacts}/sprint-status.yaml"
+    },
+    "development": {
+      "status": "{phase_3_status}",
+      "stories_completed": "{done_count}",
+      "stories_total": "{total_story_count}",
+      "epics_completed": "{completed_epic_count}",
+      "epics_total": "{total_epic_count}",
+      "total_fix_iterations": "{total_fix_iterations}"
+    }
+  }
+}
+```
+
+### 6. Provide Next Steps
+
+**If all stories completed ({phase_3_status} == "success"):**
+
+```
+🎉 All stories developed and delivered!
+
+🔜 Recommended Next Steps:
+  1. Review all implemented code and tests
+  2. Run epic-retrospective (ER) for completed epics
+  3. Consider deployment and release planning
+```
+
+**If partial completion ({phase_3_status} == "partial"):**
+
+```
+⚠️ Pipeline completed with {remaining_count} stories remaining.
+
+🔜 Recommended Next Steps:
+  1. Review escalation reports for blocked stories
+  2. Run /xiaoma-auto-story-pipeline-batch to resume remaining stories
+  3. Use /xiaoma-correct-course (CC) if scope changes are needed
+```
+
+**If development failed ({phase_3_status} == "failed"):**
+
+```
+❌ Story development phase failed.
+
+🔜 Recommended Next Steps:
+  1. Check story pipeline logs for error details
+  2. Verify epics and architecture are well-formed
+  3. Run /xiaoma-auto-story-pipeline-batch manually to diagnose
+```
+
+### 7. Pipeline Complete
+
+**Pipeline execution is COMPLETE. HALT.**
+
+---
+
+## SUCCESS METRICS
+
+- All 3 phases completed successfully
+- All planning artifacts verified
+- All stories developed and marked "done"
+- Machine-readable full-pipeline-status.json generated
+- Unified completion report generated
+- Next steps provided
+
+## FAILURE MODES
+
+- Missing critical artifacts from any phase
+- Partial story completion not properly reported
+- Not providing next steps for partial/failed completions
+- Not generating machine-readable status file

package/src/xmc/workflows/5-full-pipeline/auto-full-pipeline/workflow.md

@@ -0,0 +1,108 @@
+---
+name: auto-full-pipeline
+description: "Fully automated requirements-to-delivery pipeline: requirements analysis → PRD → epics → architecture → sprint planning → story creation → development → code review → testing → delivery. Use when the user says 'run full pipeline', 'auto full', 'end to end', or 'AFP'"
+---
+
+# Auto Full Pipeline Workflow
+
+**Goal:** Execute the complete automated software development lifecycle — from initial requirements document through requirements analysis, PRD creation, epic/story breakdown, architecture design, sprint planning, and iterative story development with code review and testing — as a single continuous pipeline.
+
+**Your Role:** Master Pipeline Orchestrator. You coordinate two sub-pipelines and a bridge step, switching expert roles as each phase demands:
+
+- **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
+- **Phase 3 — Story Development** (delegates to auto-story-pipeline-batch)
+  - SM (xiaomin) → PM (xiaochan) → Dev (xiaokai) → Reviewer → QA (xiaoce)
+
+- Communicate all responses in {communication_language} and generate all documents in {document_output_language}
+- Execute ALL steps in exact order; do NOT skip steps
+- Absolutely DO NOT stop because of "milestones", "significant progress", or "session boundaries". Continue in a single execution until the pipeline is COMPLETE or a HALT condition is triggered
+- Each step file loads fresh to combat "lost in the middle" context degradation
+
+## Context Management Strategy
+
+This pipeline may execute 8 + 5 + 9×N steps (where N = number of stories). To maintain coherence across long sessions:
+
+1. **Phase Boundary Summaries** — At the end of each Phase (Steps 02, 03, 04), output a concise state snapshot including all master pipeline variables, artifact paths produced, and story counts. This ensures critical state survives context compression.
+2. **Story Batch Checkpoints** — During Phase 3 (Step-04), the story pipeline's step-09 (cycle check) should output a running tally after every completed story: `"[Checkpoint] Stories done: X/Y, current story: {key}, phase_3 elapsed stories: X"`. This provides recovery anchors if context is compressed mid-batch.
+3. **Fresh File Reads Over Memory** — When resuming after context compression, always re-read `sprint-status.yaml` from disk rather than relying on in-memory state. The file on disk is the source of truth for story statuses.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** with delegation to existing sub-pipelines:
+
+- Step-01: Initialize and validate — unified prerequisite check
+- Step-02: Execute auto-requirements-pipeline — produces PRD, epics, architecture
+- Step-03: Bridge — auto-run sprint-planning to generate sprint-status.yaml
+- Step-04: Execute auto-story-pipeline-batch — develop all stories using Agent subprocess isolation
+- Step-05: Finalize — unified completion report across both phases
+
+### State Variables
+
+**Pipeline-Level:**
+
+- `{full_pipeline_status}` — Current master phase: "initializing" → "requirements-phase" → "bridge-phase" → "development-phase" → "complete"
+- `{full_steps_completed}` — Count of master pipeline steps executed (1–5)
+- `{phase_1_status}` — Result of requirements pipeline: "success" | "success (resumed)" | "failed"
+- `{phase_2_status}` — Result of sprint planning bridge: "success" | "success (resumed)" | "failed"
+- `{phase_3_status}` — Result of story pipeline: "success" | "partial" | "failed"
+- `{resume_from_step}` — Step to resume from: 2 (fresh), 3 (skip Phase 1), or 4 (skip Phase 1+2)
+
+**Inherited from auto-requirements-pipeline (Phase 1):**
+
+- `{req_file_path}` — Path to requirements document
+- `{pipeline_status}` — Requirements pipeline phase tracking
+- `{steps_completed}` — Requirements pipeline step counter
+- `{validation_iteration}`, `{analysis_iteration}`, `{architecture_iteration}` — Retry counters
+
+**Inherited from auto-story-pipeline-batch (Phase 3):**
+
+- Story processing is delegated to independent Agent subprocesses via auto-story-pipeline-batch
+- Each story runs in isolated context — see auto-story-pipeline-batch/workflow.md for details
+- `{backlog_count}`, `{ready_count}`, `{in_progress_count}`, `{review_count}`, `{done_count}` — Status counts (refreshed after batch completion)
+
+### Pipeline Flow
+
+```
+Step-01 (Init) → Step-02 (Requirements Pipeline) → Step-03 (Sprint Planning Bridge) → Step-04 (Story Pipeline) → Step-05 (Finalize)
+                  ├─ 8 sub-steps internally           │                                  ├─ 9 sub-steps internally
+                  └─ Produces: PRD, epics,             │                                  └─ Produces: implemented stories,
+                     architecture, pipeline-status      │                                     passing tests, done statuses
+                                                        └─ Produces: sprint-status.yaml
+```
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load 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
+
+### 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`
+
+### Context
+
+- `project_context` = `**/project-context.md` (load if exists)
+
+---
+
+## 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.

package/src/xmc/workflows/5-full-pipeline/auto-full-pipeline/xiaoma-skill-manifest.yaml

@@ -0,0 +1,3 @@
+canonicalId: xiaoma-auto-full-pipeline
+type: workflow
+description: "Fully automated requirements-to-delivery pipeline: analyze → PRD → epics → architecture → sprint plan → develop → review → test → done. Use when the user says 'run full pipeline', 'auto full', 'end to end', or 'AFP'"

package/src/xmc/workflows/5-full-pipeline/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/workflows/5-full-pipeline/auto-prd-to-stories/checklist.md

@@ -0,0 +1,43 @@
+# 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)

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

@@ -0,0 +1,155 @@
+---
+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'
+---
+
+# 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** — `{project-root}/_xiaoma/xmc/workflows/3-solutioning/xiaoma-create-epics-and-stories/workflow.md`
+   - 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`
+   - 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`
+   - 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.
+   - 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 (SM xiaomin, delegates to xiaoma-sprint-planning)
+  ⬜ Phase 3 — Batch Create Story Files (SM xiaomin, 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: `{project-root}/_xiaoma/xmc/workflows/5-full-pipeline/auto-prd-to-stories/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/workflows/5-full-pipeline/auto-prd-to-stories/steps/step-02-create-epics.md

@@ -0,0 +1,156 @@
+---
+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'
+---
+
+# 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 `{project-root}/_xiaoma/xmc/workflows/3-solutioning/xiaoma-create-epics-and-stories/workflow.md` 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: `{project-root}/_xiaoma/xmc/workflows/5-full-pipeline/auto-prd-to-stories/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