@zeyue0329/xiaoma-cli 1.12.0 → 1.15.0

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

@@ -0,0 +1,351 @@
+---
+name: 'step-05-finalize'
+description: 'Validate all artifacts, run completion checklist, and generate the final report for business-architect review'
+nextStepFile: null
+kind: 'terminal'
+---
+
+# 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 `{skill-root}/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. FR identifiers appearing anywhere in the document matching `FR-?\d+` (canonical `FR-3`) **OR** `FR-[A-Z]+-\d+` (domain-scoped `FR-TENANT-01`, `FR-PROFILE-04` — the format produced by xiaoma-create-epics-and-stories / xiaoma-prd), where the `FR` is **NOT preceded by another letter** — i.e. match `(?<![A-Za-z])FR-…` so that `NFR-PERF-01` and other `NFR-` non-functional-requirement ids are **excluded** (they belong to the NFR inventory, not FR coverage). Collect the **unique set**; if ≥1 match, use these real identifiers as the inventory.
+     b. Lines under a section **whose heading contains** `Functional Requirements` or `功能需求` (match the substring — do NOT require an exact heading; real PRDs number their headings, e.g. `## 8. Functional Requirements`). If the bullets under it carry real `FR-…` ids, use those; otherwise treat each bullet/numbered item as one FR (assign synthetic ids `FR-1`, `FR-2`, ...).
+     c. Numbered headings under a section whose heading contains `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 dev  →  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`
+
+**Assemble `{warnings[]}` (single source of truth for downstream consumption):** Before writing, build a deduplicated, prefix-tagged warning list that mirrors the human "Structural Warnings" block — so external tools, dashboards, and the architect-review process can consume warnings without re-parsing the report text:
+
+- `[fr-coverage] Uncovered FR: {fr_id} — "{fr_title}"` (one entry per item in `{uncovered_frs}`)
+- `[tier-c] {story_key}: missing {section_list}` (one entry per Tier C story file)
+- `[self-reported] {story_key}: Agent reported db_design_status / impl_logic_status = missing` (from `story_results` cross-check)
+- `[fr-coverage-map] Map count ({epics_fr_count}) vs PRD-extracted FR count ({fr_coverage_denominator}) differ by >20%` (when applicable)
+- `[checklist] {failed_item}` (one entry per failed checklist item from section 3)
+- `[bridge-failure] sprint-planning workflow failed: {sprint_planning_error}` (only present if `{implementation_artifacts}/bridge-failure.json` exists from a previous failed run — informational, indicates resume scenario)
+
+Cap the list at 100 entries; if exceeded, truncate and append `[warnings-truncated] {N} additional warnings omitted`.
+
+> **Cross-pipeline note on prefix style:** The tags above
+> (`[fr-coverage]`, `[tier-c]`, `[self-reported]`, `[fr-coverage-map]`,
+> `[checklist]`, `[bridge-failure]`, `[warnings-truncated]`) are **semantic
+> category** tags — they describe *what kind of issue* the warning represents.
+> They are intentionally different from the `[step-NN]` **emitting-step** tags
+> used by `auto-story-pipeline/workflow.md` (Warning Prefix-Tag Convention)
+> and `auto-requirements-pipeline/workflow.md` (Warning Prefix-Tag
+> Convention), which describe *which step produced* the warning. Both
+> styles are valid; auto-prd-to-stories chose semantic tags because every
+> warning here originates from one of two steps (step-04 cross-checks,
+> step-05 finalize aggregation), so source-of-emission carries little signal
+> — issue *category* is the more useful axis. When `auto-full-pipeline`
+> step-05 finalize aggregates Phase-2 warnings, the auto-prd-to-stories tags
+> are preserved as-is and wrapped with `[phase-2]` (parallel to the
+> `[phase-1]`/`[phase-3:{story_key}]` wrap for the other pipelines). A
+> future dashboard layer could map between the two styles by treating
+> `[fr-coverage]` and friends as if they were emitted by step-05; the
+> mapping is documented here as the canonical translation point.
+
+```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}"
+      }
+    }
+  },
+  "warnings": "{warnings[]}"
+}
+```
+
+**Write strategy (atomic — temp-file-then-rename):**
+
+1. Write the JSON to `{implementation_artifacts}/prd-to-stories-status.json.tmp` first.
+2. Verify the temp file parses as JSON.
+3. Atomically `rename()` to `{implementation_artifacts}/prd-to-stories-status.json`.
+4. If the rename fails (e.g., cross-device `EXDEV`, unlikely since the temp file is in the same directory): log WARNING with the temp-file path and recovery instruction, but do NOT block the pipeline — the human-readable report and JSON content are already produced.
+
+### 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 **atomically** (temp-file-then-rename) with `warnings[]` field aggregated from FR-coverage gaps, Tier C files, Agent self-reports, FR-Coverage-Map discrepancy, checklist findings, and (when present) bridge-failure marker
+
+## 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 atomically write the final status JSON (leaves a `prd-to-stories-status.json.tmp` for inspection; report content is unaffected)
+- `warnings[]` aggregator misses a category — caught by the cross-check between the human "Structural Warnings" block and the JSON warnings array

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

@@ -0,0 +1,104 @@
+---
+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** (Dev xiaokai) — generates sprint-status.yaml via xiaoma-sprint-planning
+- **Phase 3 — Batch Story Creation** (Dev xiaokai 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
+
+- `create_epics_workflow` = `skill:xiaoma-create-epics-and-stories`
+- `sprint_planning_workflow` = `skill:xiaoma-sprint-planning`
+- `create_story_workflow` = `skill:xiaoma-create-story`
+- `validation` = `{skill-root}/checklist.md`
+
+### Context
+
+- `project_context` = `**/project-context.md` (load if exists)
+
+---
+
+## EXECUTION
+
+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/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 转故事'"

package/src/xmc-skills/module-help.csv

@@ -0,0 +1,32 @@
+module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
+XiaoMa Method,_meta,,,,,,,,,false,,
+XiaoMa Method,xiaoma-document-project,Document Project,DP,Analyze an existing project to produce useful documentation.,,,anytime,,,false,project-knowledge,*
+XiaoMa Method,xiaoma-generate-project-context,Generate Project Context,GPC,Scan existing codebase to generate a lean LLM-optimized project-context.md. Essential for brownfield projects.,,,anytime,,,false,output_folder,project context
+XiaoMa Method,xiaoma-quick-dev,Quick Dev,QQ,Unified intent-in code-out workflow: clarify plan implement review and present.,,,anytime,,,false,implementation_artifacts,spec and project implementation
+XiaoMa Method,xiaoma-correct-course,Correct Course,CC,Navigate significant changes. May recommend start over update PRD redo architecture sprint planning or correct epics and stories.,,,anytime,,,false,planning_artifacts,change proposal
+XiaoMa Method,xiaoma-agent-tech-writer,Write Document,WD,"Describe in detail what you want, and the agent will follow documentation best practices. Multi-turn conversation with subprocess for research/review.",write,,anytime,,,false,project-knowledge,document
+XiaoMa Method,xiaoma-agent-tech-writer,Update Standards,US,Update agent memory documentation-standards.md with your specific preferences if you discover missing document conventions.,update-standards,,anytime,,,false,_xiaoma/_memory/tech-writer-sidecar,standards
+XiaoMa Method,xiaoma-agent-tech-writer,Mermaid Generate,MG,Create a Mermaid diagram based on user description. Will suggest diagram types if not specified.,mermaid,,anytime,,,false,planning_artifacts,mermaid diagram
+XiaoMa Method,xiaoma-agent-tech-writer,Validate Document,VD,Review the specified document against documentation standards and best practices. Returns specific actionable improvement suggestions organized by priority.,validate,[path],anytime,,,false,planning_artifacts,validation report
+XiaoMa Method,xiaoma-agent-tech-writer,Explain Concept,EC,Create clear technical explanations with examples and diagrams for complex concepts.,explain,[topic],anytime,,,false,project_knowledge,explanation
+XiaoMa Method,xiaoma-brainstorming,Brainstorm Project,BP,Expert guided facilitation through a single or multiple techniques.,,,1-analysis,,,false,planning_artifacts,brainstorming session
+XiaoMa Method,xiaoma-market-research,Market Research,MR,Market analysis competitive landscape customer needs and trends.,,,1-analysis,,,false,planning_artifacts|project-knowledge,research documents
+XiaoMa Method,xiaoma-domain-research,Domain Research,DR,Industry domain deep dive subject matter expertise and terminology.,,,1-analysis,,,false,planning_artifacts|project_knowledge,research documents
+XiaoMa Method,xiaoma-technical-research,Technical Research,TR,Technical feasibility architecture options and implementation approaches.,,,1-analysis,,,false,planning_artifacts|project_knowledge,research documents
+XiaoMa Method,xiaoma-product-brief,Create Brief,CB,An expert guided experience to nail down your product idea in a brief. a gentler approach than PRFAQ when you are already sure of your concept and nothing will sway you.,,-A,1-analysis,,,false,planning_artifacts,product brief
+XiaoMa Method,xiaoma-prfaq,PRFAQ Challenge,WB,Working Backwards guided experience to forge and stress-test your product concept to ensure you have a great product that users will love and need through the PRFAQ gauntlet to determine feasibility and alignment with user needs. alternative to product brief.,,-H,1-analysis,,,false,planning_artifacts,prfaq document
+XiaoMa Method,xiaoma-prd,Create Edit and Review PRD,PRD,"Facilitated PRD workflow — create a new PRD via coached discovery, update an existing one against a change signal, or validate a finished PRD against a checklist with an HTML findings report.",,,2-planning,xiaoma-product-brief,,true,planning_artifacts,prd
+XiaoMa Method,xiaoma-ux,Create UX,CU,"Guidance through realizing the plan for your UX, strongly recommended if a UI is a primary piece of the proposed project.",,,2-planning,xiaoma-prd,,false,planning_artifacts,ux design
+XiaoMa Method,xiaoma-create-architecture,Create Architecture,CA,Guided workflow to document technical decisions.,,,3-solutioning,,,true,planning_artifacts,architecture
+XiaoMa Method,xiaoma-create-epics-and-stories,Create Epics and Stories,CE,,,,3-solutioning,xiaoma-create-architecture,,true,planning_artifacts,epics and stories
+XiaoMa Method,xiaoma-check-implementation-readiness,Check Implementation Readiness,IR,Ensure PRD UX Architecture and Epics Stories are aligned.,,,3-solutioning,xiaoma-create-epics-and-stories,,true,planning_artifacts,readiness report
+XiaoMa Method,xiaoma-sprint-planning,Sprint Planning,SP,Kicks off implementation by producing a plan the implementation agents will follow in sequence for every story.,,,4-implementation,,,true,implementation_artifacts,sprint status
+XiaoMa Method,xiaoma-sprint-status,Sprint Status,SS,Anytime: Summarize sprint status and route to next workflow.,,,4-implementation,xiaoma-sprint-planning,,false,,
+XiaoMa Method,xiaoma-create-story,Create Story,CS,Story cycle start: Prepare first found story in the sprint plan that is next or a specific epic/story designation.,create,,4-implementation,xiaoma-sprint-planning,xiaoma-create-story:validate,true,implementation_artifacts,story
+XiaoMa Method,xiaoma-create-story,Validate Story,VS,Validates story readiness and completeness before development work begins.,validate,,4-implementation,xiaoma-create-story:create,xiaoma-dev-story,false,implementation_artifacts,story validation report
+XiaoMa Method,xiaoma-dev-story,Dev Story,DS,Story cycle: Execute story implementation tasks and tests then CR then back to DS if fixes needed.,,,4-implementation,xiaoma-create-story:validate,,true,,
+XiaoMa Method,xiaoma-code-review,Code Review,CR,Story cycle: If issues back to DS if approved then next CS or ER if epic complete.,,,4-implementation,xiaoma-dev-story,,false,,
+XiaoMa Method,xiaoma-checkpoint-preview,Checkpoint,CK,Guided walkthrough of a change from purpose and context into details. Use for human review of commits branches or PRs.,,,4-implementation,,,false,,
+XiaoMa Method,xiaoma-qa-generate-e2e-tests,QA Automation Test,QA,Generate automated API and E2E tests for implemented code. NOT for code review or story validation — use CR for that.,,,4-implementation,xiaoma-dev-story,,false,implementation_artifacts,test suite
+XiaoMa Method,xiaoma-retrospective,Retrospective,ER,Optional at epic end: Review completed work lessons learned and next epic or if major issues consider CC.,,,4-implementation,xiaoma-code-review,,false,implementation_artifacts,retrospective
+XiaoMa Method,xiaoma-investigate,Investigate,IN,Forensic case investigation calibrated to the input. Evidence-graded analysis with hypothesis tracking. Produces a structured case file.,,4-implementation,,,false,implementation_artifacts,investigation report

package/src/xmc-skills/module.yaml

@@ -0,0 +1,95 @@
+code: xmc
+name: "XiaoMa Method"
+description: "Full-lifecycle AI agile development: analysis, planning, architecture, implementation"
+default_selected: true # This module will be selected by default for new installations
+
+# Variables from Core Config inserted:
+## user_name
+## project_name
+## communication_language
+## document_output_language
+## output_folder
+
+user_skill_level:
+  prompt:
+    - "What is your development experience level?"
+    - "This affects how agents explain concepts in chat."
+  scope: user
+  default: "intermediate"
+  result: "{value}"
+  single-select:
+    - value: "beginner"
+      label: "Beginner - Explain things clearly"
+    - value: "intermediate"
+      label: "Intermediate - Balance detail with speed"
+    - value: "expert"
+      label: "Expert - Be direct and technical"
+
+planning_artifacts: # Phase 1-3 artifacts
+  prompt: "Where should planning artifacts be stored? (Brainstorming, Briefs, PRDs, UX Designs, Architecture, Epics)"
+  default: "{output_folder}/planning-artifacts"
+  result: "{project-root}/{value}"
+
+implementation_artifacts: # Phase 4 artifacts and quick-dev flow output
+  prompt: "Where should implementation artifacts be stored? (Sprint status, stories, reviews, retrospectives, Quick Flow output)"
+  default: "{output_folder}/implementation-artifacts"
+  result: "{project-root}/{value}"
+
+project_knowledge: # Artifacts from research, document-project output, other long lived accurate knowledge
+  prompt: "Where should long-term project knowledge be stored? (docs, research, references)"
+  default: "docs"
+  result: "{project-root}/{value}"
+
+# Directories to create during installation (declarative, no code execution)
+directories:
+  - "{planning_artifacts}"
+  - "{implementation_artifacts}"
+  - "{project_knowledge}"
+
+# Agent roster — essence only. External skills (party-mode, retrospective,
+# advanced-elicitation, help catalog) read these descriptors to route, display,
+# and embody agents. Full persona and behavior live in each agent's
+# customize.toml. `team` defaults to the module code when omitted; users can
+# add their own agents (real or fictional) via _xiaoma/custom/config.toml or _xiaoma/custom/config.user.toml.
+agents:
+  - code: xiaoma-agent-analyst
+    name: xiaofen
+    title: Business Analyst
+    icon: "📊"
+    team: software-development
+    description: "Channels Porter's strategic rigor and Minto's Pyramid Principle, grounds every finding in verifiable evidence, represents every stakeholder voice. Speaks like a treasure hunter narrating the find: thrilled by every clue, precise once the pattern emerges."
+
+  - code: xiaoma-agent-tech-writer
+    name: xiaowen
+    title: Technical Writer
+    icon: "📚"
+    team: software-development
+    description: "Master of CommonMark, DITA, and OpenAPI; turns complex concepts into accessible structured docs, favors diagrams over walls of text, every word earning its place. Speaks like the patient teacher you wish you'd had, using analogies that make complex things feel simple."
+
+  - code: xiaoma-agent-pm
+    name: xiaochan
+    title: Product Manager
+    icon: "📋"
+    team: software-development
+    description: "Drives Jobs-to-be-Done over template filling, user value first, technical feasibility is a constraint not the driver. Speaks like a detective interrogating a cold case: short questions, sharper follow-ups, every 'why?' tightening the net."
+
+  - code: xiaoma-agent-ux-designer
+    name: xiaoshe
+    title: UX Designer
+    icon: "🎨"
+    team: software-development
+    description: "Balances empathy with edge-case rigor, starts simple and evolves through feedback, every decision serves a genuine user need. Speaks like a filmmaker pitching the scene before the code exists, painting user stories that make you feel the problem."
+
+  - code: xiaoma-agent-architect
+    name: xiaojia
+    title: System Architect
+    icon: "🏗️"
+    team: software-development
+    description: "Favors boring technology for stability, developer productivity as architecture, ties every decision to business value. Speaks like a seasoned engineer at the whiteboard: measured, always laying out trade-offs rather than verdicts."
+
+  - code: xiaoma-agent-dev
+    name: xiaokai
+    title: Senior Software Engineer
+    icon: "💻"
+    team: software-development
+    description: "Test-first discipline (red, green, refactor), 100% pass before review, no fluff all precision. Speaks like a terminal prompt: exact file paths, AC IDs, and commit-message brevity — every statement citable."

package/src/xpm-skills/module-help.csv

@@ -0,0 +1,3 @@
+module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
+XiaoMa Patent Mining,_meta,,,,,,,,,false,,
+XiaoMa Patent Mining,xiaoma-patent-mining,Patent Mining,PM,"Mine patentable innovations from a software project and generate a prosecution-ready disclosure DOCX (three-element test, six-section template, anti-AI writing checks).",,,anytime,,,false,patent_output_folder,patent disclosure document

package/src/xpm-skills/module.yaml

@@ -0,0 +1,36 @@
+code: xpm
+name: "XiaoMa Patent Mining"
+description: "AI-driven patent innovation mining and disclosure document generation"
+default_selected: false # Third-party module, opt-in
+
+# Variables from Core Config inserted:
+## user_name
+## communication_language
+## document_output_language
+## output_folder
+
+# Note: inventor_name / inventor_contact_{name,phone,email} are intentionally
+# NOT collected at install time — each disclosure may have different inventors
+# and contacts. The skill collects them interactively in step-02. Users may
+# pre-populate these keys manually in the generated _xiaoma/xpm/config.yaml
+# if they have a single fixed contact; the skill reads them as defaults when
+# present and prompts when absent.
+
+patent_output_folder:
+  prompt: "Where should patent disclosure artifacts be stored?"
+  default: "{output_folder}/patent-disclosures"
+  result: "{project-root}/{value}"
+
+# Directories to create during installation (declarative, no code execution)
+directories:
+  - "{patent_output_folder}"
+
+# Agent roster — essence only. Full persona and behavior live in each agent's
+# customize.toml. `team` groups agents for party-mode/help routing.
+agents:
+  - code: xiaoma-agent-patent-advisor
+    name: xiaoyan
+    title: Patent Innovation Advisor
+    icon: "🔬"
+    team: patent-mining
+    description: "Senior R&D engineer turned patent strategist. Applies the three-element test (technical-problem / technical-means / technical-effect) strictly, rejects pure business logic / CRUD / framework usage, and writes prosecution-ready disclosures like senior design docs — specifics and numbers, not marketing copy."