@zeyue0329/xiaoma-cli 1.11.0 → 1.13.0

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

@@ -0,0 +1,311 @@
+---
+name: 'step-05-finalize'
+description: 'Validate all artifacts, run completion checklist, and generate the final report for business-architect review'
+nextStepFile: null
+---
+
+# Step 5 of 5: Finalize PRD-to-Stories Pipeline
+
+**Goal:** Validate all output artifacts, run the completion checklist, and generate the unified report that business architects will use to evaluate the quality of the generated user stories.
+
+**Role:** Pipeline Orchestrator
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Validate All Artifacts
+
+Check that ALL expected output files exist:
+
+**Phase 1 — Epics Artifact:**
+
+1. `{planning_artifacts}/epics.md` — Required
+
+**Phase 2 — Sprint Planning Artifact:**
+
+2. `{implementation_artifacts}/sprint-status.yaml` — Required
+
+**Phase 3 — Story File Artifacts:**
+
+3. For each story key in sprint-status.yaml (excluding those in `{failed_story_keys}`), a corresponding file at `{implementation_artifacts}/{story_key}.md` — Required
+
+For each missing artifact:
+
+- If epics.md or sprint-status.yaml is missing: log CRITICAL FAILURE
+- If a per-story file is missing but its key is NOT in `{failed_story_keys}`: log CRITICAL FAILURE (the Agent claimed success without writing the file)
+- If a per-story file is missing AND its key IS in `{failed_story_keys}`: expected (documented failure), no action
+
+### 2. Read Final Sprint Status
+
+Fresh-read `{implementation_artifacts}/sprint-status.yaml` and parse:
+
+- `{final_epic_count}` — Number of `epic-N` entries
+- `{final_story_count}` — Total story keys matching `<digit>-<digit>-*`
+- `{final_ready_count}` — Stories with status `ready-for-dev`
+- `{final_backlog_count}` — Stories still at `backlog` (should equal `{stories_failed}` if pipeline ran fully)
+
+**Sanity check:** `{final_ready_count}` should equal `{stories_created}` + (any pre-existing ready-for-dev stories from re-runs).
+
+### 3. Run Completion Checklist
+
+If `{installed_path}/checklist.md` is readable, load it and evaluate each item against the artifacts on disk. For each failed item, append a line to the final report's "Checklist Findings" section.
+
+If checklist.md is missing, skip this section silently.
+
+### 4. Validate Story File Structure (Full Scan + Deep Subsection Check)
+
+For **EVERY** successfully created story file (NOT sampled — scan all of them):
+
+1. Read the file fully
+2. **Top-level required sections** (case-insensitive heading search):
+   - `Status` (and value contains `ready-for-dev`)
+   - `Story` (with "As a / I want / so that" pattern)
+   - `Acceptance Criteria`
+   - `Tasks` (or `Tasks / Subtasks`)
+   - `Dev Notes`
+3. **Dev Notes mandatory subsections** (the three from the step-04 Detailed Design Output Contract):
+   - `### Functional Requirements Addressed` (or case-insensitive variant matching `Functional Requirements`)
+   - `### Data Model & Database Design` (or case-insensitive variant matching any of: `Data Model`, `Database Design`, `Database Schema`, `数据模型`, `数据库设计`)
+   - `### Implementation Logic` (or case-insensitive variant matching any of: `Implementation Logic`, `Implementation Detail`, `Pseudocode`, `接口设计`, `实现逻辑`)
+4. **Subsection content quality (lightweight heuristic):**
+   - Data Model subsection: content non-empty AND (contains a table/field-list line OR contains the literal "TBD by architect")
+   - Implementation Logic subsection: content non-empty AND (contains code-fence / function signature / numbered steps OR contains the literal "TBD by architect")
+   - A subsection that contains only a heading with no body fails this check.
+
+For each story file, classify:
+
+- **Tier A — Fully Compliant:** all top-level sections present, all three Dev Notes subsections present and content-positive (no `TBD by architect`)
+- **Tier B — TBD-flagged:** all sections present, but one or more subsections contain `TBD by architect` (this is acceptable — it surfaces unknowns honestly for the architect)
+- **Tier C — Structurally Incomplete:** one or more required top-level sections missing, OR a required Dev Notes subsection missing, OR a subsection has only a heading with no body
+
+Compute the coverage tallies for the final report:
+
+- `{dev_notes_db_coverage}` = count of story files with a non-empty `Data Model & Database Design` subsection / `{stories_created}`
+- `{dev_notes_impl_coverage}` = count of story files with a non-empty `Implementation Logic` subsection / `{stories_created}`
+- `{tier_a_count}`, `{tier_b_count}`, `{tier_c_count}` for the per-tier breakdown
+
+For every Tier C file, add a line to "Structural Warnings" listing the file path and exactly which sections/subsections failed.
+
+Also cross-check `story_results` from step-04: if any story has `db_design_status: missing` or `impl_logic_status: missing` reported by the Agent, list it in Structural Warnings even if heading-based detection passed (the Agent self-reported missing content).
+
+### 4b. FR Reverse-Traceability Check
+
+This implements Must Fix #4: ensure every functional requirement in `prd.md` is referenced by at least one story file.
+
+1. **Parse PRD functional requirements:**
+   - Read `{planning_artifacts}/prd.md` fully
+   - Extract FR identifiers using these patterns (in priority order, stop after the first that yields ≥1 match):
+     a. Lines matching `^FR-?\d+\b` or `^\*\*FR-?\d+\*\*` (canonical FR-N format)
+     b. Lines under a section titled `## Functional Requirements` or `## 功能需求`, where each bullet/numbered item is treated as one FR (assign synthetic ids `FR-1`, `FR-2`, ...)
+     c. Numbered headings under `## Features` or `## 功能点` (assign synthetic ids `FEAT-1`, `FEAT-2`, ...)
+   - If no patterns match (PRD has no structured FR list): skip the rest of this section and log INFO — "PRD has no structured FR list; reverse traceability skipped. Architects should manually verify coverage from epics.md and story files."
+   - Otherwise, set `{prd_fr_inventory}` = the list of extracted FR identifiers + their short title
+
+2. **For each FR in `{prd_fr_inventory}`:**
+   - Search ALL story files (`{implementation_artifacts}/<digit>-<digit>-*.md`) for ANY of:
+     - The exact FR identifier (e.g., `FR-3`)
+     - The FR's short title text (substring match, case-insensitive, length ≥ 8 chars to avoid false positives)
+     - A `[Source: prd.md#<section>]` citation whose `<section>` matches the FR's parent section
+   - If at least one story file references the FR: mark `covered`
+   - If no story file references the FR: mark `uncovered`
+
+3. **Compute coverage:**
+   - `{fr_coverage_numerator}` = count of FRs marked `covered`
+   - `{fr_coverage_denominator}` = `len(prd_fr_inventory)`
+   - `{uncovered_frs}` = list of FR identifiers marked `uncovered`
+
+4. **For each uncovered FR:**
+   - Add a HIGH-PRIORITY line to "Structural Warnings": `Uncovered FR: {fr_id} — "{fr_title}" — NO story file references this requirement. The pipeline may have dropped this feature.`
+
+5. **Cross-check epics.md FR Coverage Map** (if `{epics_fr_count}` was set in step-02):
+   - If `{fr_coverage_denominator}` significantly differs from `{epics_fr_count}` (delta > 20%): add WARNING to Structural Warnings — "FR-Coverage-Map count ({epics_fr_count}) vs PRD-extracted FR count ({fr_coverage_denominator}) differ by >20%. epics.md may have an incomplete FR Coverage Map."
+
+### 5. Generate Final Report
+
+Set `{prd_to_stories_status}` = "complete" and `{steps_completed}` = 5 BEFORE printing.
+
+**Output:**
+
+```
+═══════════════════════════════════════════════════════════════
+  Auto PRD-to-Stories Pipeline — COMPLETE
+═══════════════════════════════════════════════════════════════
+
+Project: {project_name}
+Date: {date}
+Master Steps Completed: {steps_completed}/5
+
+Input:
+  📋 PRD: {planning_artifacts}/prd.md
+
+Outputs:
+  📄 Epics: {planning_artifacts}/epics.md            [{phase_1_status}]
+  📊 Sprint Status: {implementation_artifacts}/sprint-status.yaml   [{phase_2_status}]
+  📁 Story Files: {implementation_artifacts}/<story_key>.md × {stories_created}  [{phase_3_status}]
+
+Phase Breakdown:
+  Phase 1 — Create Epics                 [{phase_1_status}]
+    └─ Total Epics: {final_epic_count}
+    └─ Total Stories (in epics.md): {final_story_count}
+    └─ FRs in Coverage Map: {epics_fr_count}
+
+  Phase 2 — Sprint Planning Bridge       [{phase_2_status}]
+    └─ Stories tracked: {final_story_count}
+
+  Phase 3 — Batch Story File Creation    [{phase_3_status}]
+    ├─ Stories Successfully Created: {stories_created}
+    ├─ Stories Failed: {stories_failed}
+    └─ Failed Keys: {failed_story_keys joined, or "none"}
+
+🔎 Quality Coverage (for architect review):
+  ├─ FR Coverage:                  {fr_coverage_numerator}/{fr_coverage_denominator}
+  ├─ Data Model subsection:        {dev_notes_db_coverage}/{stories_created}  (present)
+  ├─ Implementation Logic subsec:  {dev_notes_impl_coverage}/{stories_created}  (present)
+  ├─ Tier A (fully compliant):     {tier_a_count}
+  ├─ Tier B (TBD-flagged honest):  {tier_b_count}
+  └─ Tier C (structurally incomplete): {tier_c_count}   ⚠ if > 0, see Structural Warnings below
+
+Pipeline Status: {prd_to_stories_status}
+═══════════════════════════════════════════════════════════════
+
+📋 Story Files Generated (for business-architect review):
+{for each entry in story_results where final_status == "created":
+  ✅ {story_key}.md  —  {summary}
+}
+
+❌ Story Files Failed:
+{for each entry in story_results where final_status == "failed":
+  ⚠️  {story_key}  —  {error}
+}
+
+{IF "Structural Warnings" non-empty:}
+⚠️  Structural Warnings (high → low priority):
+
+  -- FR Coverage Gaps (HIGHEST priority — these features may have been dropped) --
+  {for each uncovered_fr: "Uncovered FR: {fr_id} — \"{fr_title}\" — NO story file references this. The pipeline may have dropped this feature."}
+
+  -- Structural Incompleteness (Tier C files) --
+  {for each Tier C entry: story_key — missing sections/subsections list}
+
+  -- Self-Reported Missing Content (from Agent STORY_RESULT) --
+  {for each story with db_design_status == "missing" or impl_logic_status == "missing": story_key — which subsection Agent reported missing}
+
+  -- FR Coverage Map Discrepancy (if any) --
+  {if FR-coverage-map count delta > 20%: warning text}
+
+{IF "Checklist Findings" non-empty:}
+📋 Checklist Findings:
+{for each failed item: item description}
+```
+
+### 6. Architect Review Guidance
+
+```
+───────────────────────────────────────────────────────────────
+  🎯 Next: Business-Architect Quality Review
+───────────────────────────────────────────────────────────────
+
+The pipeline stops HERE intentionally. The generated artifacts are
+the input to a manual quality review:
+
+  1. **Start with the Quality Coverage block above.**
+     - If FR Coverage < 100%: find the listed uncovered FRs FIRST — these
+       are features from prd.md that no story addresses. Run create-epics-
+       and-stories again or manually add the missing stories.
+     - If Tier C count > 0: open those files first — they have structural
+       holes that block downstream development.
+
+  2. Review epics.md for completeness vs. the input prd.md
+     (Are all PRD features represented? Right epic granularity?
+      Cross-check the FR Coverage Map section.)
+
+  3. Review each {story_key}.md for:
+     - Story statement clarity (As a / I want / so that)
+     - Acceptance Criteria testability (BDD Given/When/Then quality)
+     - Task decomposition concreteness
+     - **Data Model & Database Design subsection** — Are the tables/fields/
+       indexes/constraints concrete? If "TBD by architect", is the missing
+       piece something prd.md should have specified, or is it genuinely a
+       design decision for the architect to make now?
+     - **Implementation Logic subsection** — Are interface signatures,
+       algorithms, and error-handling concrete? Or hand-wavy?
+     - **Functional Requirements Addressed subsection** — Does it cite
+       specific FRs/sections from prd.md or epics.md?
+
+  4. Capture feedback on which dimensions are weak — feed back
+     into the create-epics-and-stories / create-story prompts
+     to improve generation quality.
+
+  5. When ready to enter development, run:
+       /xiaoma  →  load sm  →  ASB
+     (auto-story-pipeline-batch will pick up from ready-for-dev.)
+
+───────────────────────────────────────────────────────────────
+```
+
+### 7. Generate Machine-Readable Status File
+
+Write to: `{implementation_artifacts}/prd-to-stories-status.json`
+
+```json
+{
+  "pipeline": "auto-prd-to-stories",
+  "date": "{date}",
+  "project": "{project_name}",
+  "status": "{prd_to_stories_status}",
+  "master_steps_completed": 5,
+  "input": {
+    "prd": "{planning_artifacts}/prd.md"
+  },
+  "phases": {
+    "epics": {
+      "status": "{phase_1_status}",
+      "artifact": "{planning_artifacts}/epics.md",
+      "epic_count": "{final_epic_count}",
+      "story_count": "{final_story_count}"
+    },
+    "sprint_planning": {
+      "status": "{phase_2_status}",
+      "artifact": "{implementation_artifacts}/sprint-status.yaml"
+    },
+    "story_creation": {
+      "status": "{phase_3_status}",
+      "stories_created": "{stories_created}",
+      "stories_failed": "{stories_failed}",
+      "failed_story_keys": "{failed_story_keys}",
+      "quality_coverage": {
+        "fr_coverage": {
+          "covered": "{fr_coverage_numerator}",
+          "total": "{fr_coverage_denominator}",
+          "uncovered_frs": "{uncovered_frs}"
+        },
+        "data_model_present": "{dev_notes_db_coverage}",
+        "implementation_logic_present": "{dev_notes_impl_coverage}",
+        "tier_a_count": "{tier_a_count}",
+        "tier_b_count": "{tier_b_count}",
+        "tier_c_count": "{tier_c_count}"
+      }
+    }
+  }
+}
+```
+
+### 8. Pipeline Complete
+
+**Pipeline execution is COMPLETE. HALT.**
+
+---
+
+## SUCCESS METRICS
+
+- All 3 phases reported with status
+- All successfully created story files exist on disk and contain required sections
+- Final report output with architect-review guidance
+- Machine-readable status file written
+
+## FAILURE MODES
+
+- Missing epics.md or sprint-status.yaml when at least one phase claimed success
+- Story files claimed created but missing on disk
+- Failure to write the final status JSON

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

@@ -0,0 +1,105 @@
+---
+name: auto-prd-to-stories
+description: "Automated PRD-to-Stories pipeline (NO development): prd.md → epics breakdown → sprint planning bridge → per-story detailed file generation. 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'"
+---
+
+# Auto PRD-to-Stories Pipeline Workflow
+
+**Goal:** Take an existing `prd.md` and produce all detailed user-story files (one `.md` per story) so business architects can review the quality of the generated stories. This pipeline STOPS BEFORE development, review, or testing — the output is the input to a manual quality-review activity.
+
+**Your Role:** Pipeline Orchestrator. You coordinate two delegations and a batch loop, switching expert roles as each phase demands:
+
+- **Phase 1 — Epics Creation** (PM xiaochan) — delegates to xiaoma-create-epics-and-stories
+- **Phase 2 — Bridge** (SM xiaomin) — generates sprint-status.yaml via xiaoma-sprint-planning
+- **Phase 3 — Batch Story Creation** (SM xiaomin scheduler) — per story: Agent subprocess runs xiaoma-create-story and exits BEFORE entering dev/review/test
+
+- 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
+- **Hard boundary:** This pipeline NEVER enters story development. Every Agent subprocess in Phase 3 stops immediately after step-02-create-story completes — do not progress to validate-story / develop-story / code-review / test-story / fix-and-retest / complete-story / finalize.
+
+## Context Management Strategy
+
+This pipeline may execute 5 master steps where Phase 3 contains N sub-iterations (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 batch loop outputs a running tally after every story Agent returns: `"[Checkpoint] Stories created: X/Y, current story: {key}"`. 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-workflows:
+
+- Step-01: Initialize and validate — verify prd.md exists, load config, confirm sub-workflow paths
+- Step-02: Create Epics — delegates to xiaoma-create-epics-and-stories, produces epics.md
+- Step-03: Bridge — delegates to xiaoma-sprint-planning, produces sprint-status.yaml
+- Step-04: Batch Create Stories — for each backlog story, launch Agent subprocess running xiaoma-create-story; produces per-story `.md` files
+- Step-05: Finalize — quality self-check, unified completion report listing all artifacts for architect review
+
+### State Variables
+
+**Pipeline-Level:**
+
+- `{prd_to_stories_status}` — Current master phase: "initializing" → "epics-phase" → "bridge-phase" → "stories-phase" → "complete"
+- `{steps_completed}` — Count of master pipeline steps executed (1–5)
+- `{phase_1_status}` — Result of epics creation: "success" | "failed"
+- `{phase_2_status}` — Result of sprint-planning bridge: "success" | "failed"
+- `{phase_3_status}` — Result of batch story creation: "success" | "partial" | "failed"
+
+**Phase 3 batch tracking (from ASB pattern):**
+
+- `{stories_created}` — Count of stories successfully created (final_status: created)
+- `{stories_failed}` — Count of stories that failed creation
+- `{failed_story_keys}` — List of story keys whose Agent failed; skipped in subsequent loop iterations to avoid infinite loops
+- `{story_results}` — Accumulating list of per-story result summaries for the final report
+
+### Output Artifacts
+
+- `{planning_artifacts}/epics.md` — Epic breakdown with BDD-formatted stories (high-level view for horizontal review)
+- `{implementation_artifacts}/sprint-status.yaml` — Story tracking index
+- `{implementation_artifacts}/{story_key}.md` — One detailed story file per story (vertical depth for architect review). All stories end at status `ready-for-dev`.
+
+### Pipeline Flow
+
+```
+Step-01 (Init) → Step-02 (Create Epics) → Step-03 (Sprint Planning Bridge) → Step-04 (Batch Create Stories) → Step-05 (Finalize)
+                  └─ delegates to              └─ delegates to                  └─ N Agent subprocesses,
+                     xiaoma-create-                xiaoma-sprint-planning           each running only
+                     epics-and-stories                                              xiaoma-create-story
+                  Produces: epics.md          Produces: sprint-status.yaml      Produces: {story_key}.md × N
+```
+
+---
+
+## 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-prd-to-stories`
+- `create_epics_workflow` = `{project-root}/_xiaoma/xmc/workflows/3-solutioning/xiaoma-create-epics-and-stories/workflow.md`
+- `sprint_planning_workflow` = `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-sprint-planning/workflow.md`
+- `create_story_workflow` = `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-create-story/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-prd-to-stories/steps/step-01-init-and-validate.md` to begin the pipeline.

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

@@ -0,0 +1,3 @@
+canonicalId: xiaoma-auto-prd-to-stories
+type: workflow
+description: "Automated PRD-to-Stories pipeline (NO development): prd.md → epics → sprint-status → per-story detailed files. Stops before dev so architects can evaluate user-story quality. Triggers: 'APS', 'auto prd to stories', 'PRD 转故事'"