@zeyue0329/xiaoma-cli 1.12.0 → 1.13.0

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

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

@@ -0,0 +1,143 @@
+---
+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'
+---
+
+# 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
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Announce Phase Entry
+
+**Output:**
+
+```
+═══════════════════════════════════════════════════
+  Phase 2 of 3 — Sprint Planning Bridge
+═══════════════════════════════════════════════════
+
+Switching role to SM (xiaomin)...
+Generating sprint-status.yaml from epics...
+This bridges epics → per-story file generation.
+───────────────────────────────────────────────────
+```
+
+### 2. Verify Epics Input
+
+Confirm `{planning_artifacts}/epics.md` exists and is readable (should always pass since Phase 1 verified this, but re-check for fresh context loading):
+
+- If missing: HALT — "epics.md not found. Phase 1 may have failed. Cannot generate sprint status."
+
+Also check for sharded epics format (safety net only — Phase 1 produces a single `epics.md` file, not a sharded format):
+
+- If `{planning_artifacts}/epics.md` not found, check for `{planning_artifacts}/epics/index.md`
+- 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
+
+Adopt the SM (xiaomin) persona:
+
+- You are xiaomin, the Technical Scrum Master + Story Preparation Specialist
+- 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`
+
+**Critical Pipeline Mode Instructions:**
+
+- **FULLY AUTOMATED:** Do NOT pause for user input
+- The sprint planning workflow is a **single-file workflow** (`workflow.md`) containing 5 inline `<step>` blocks (not separate step files):
+  1. Parse epic files and extract all work items
+  2. Build sprint status structure (epic-N, story keys, retrospective entries)
+  3. Apply intelligent status detection (check for existing story files)
+  4. Generate `{implementation_artifacts}/sprint-status.yaml`
+  5. Validate and report totals
+- Execute ALL 5 inline steps sequentially within the single workflow file
+- For fresh runs (no pre-existing story files), all stories should default to `backlog` status
+- For re-runs (pre-existing story files detected by step 3 of sprint-planning), stories with files on disk will be promoted to `ready-for-dev` — this is the intended idempotency behavior
+- 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
+
+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."
+
+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:
+   - `{epic_count}` — Number of `epic-N` entries
+   - `{story_count}` — Total story keys matching `<digit>-<digit>-*`
+   - `{backlog_count}` — Stories with status `backlog`
+   - `{ready_count}` — Stories with status `ready-for-dev` (pre-existing files)
+
+If `{backlog_count}` == 0 AND `{ready_count}` == 0:
+
+- HALT — "No processable stories found in sprint-status.yaml. Both backlog and ready-for-dev queues are empty."
+
+### 6. Update Master Pipeline State
+
+- `{phase_2_status}` = "success"
+- `{prd_to_stories_status}` = "stories-phase"
+- `{steps_completed}` = 3
+
+### 7. Output Phase 2 Summary
+
+**Output:**
+
+```
+───────────────────────────────────────────────────
+  ✅ Phase 2 Complete — Sprint Planning Bridge
+───────────────────────────────────────────────────
+
+Sprint Status: {implementation_artifacts}/sprint-status.yaml
+  Total Epics: {epic_count}
+  Total Stories: {story_count}
+  Stories in Backlog: {backlog_count}
+  Stories already Ready-for-Dev (pre-existing files): {ready_count}
+
+Phase 2 Status: {phase_2_status}
+Master Step: 3/5
+
+Proceeding to Phase 3 — Batch Story File Generation...
+───────────────────────────────────────────────────
+```
+
+**Auto-Proceed:** YES — Do NOT wait for user input. Immediately proceed to step-04.
+
+---
+
+## 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`
+
+---
+
+## SUCCESS METRICS
+
+- sprint-status.yaml generated with valid YAML
+- All epics and stories from epics.md represented
+- Story counts tallied for Phase 3 batch loop
+- Phase 2 status set to "success"
+
+## 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