@zeyue0329/xiaoma-cli 1.13.0 → 1.15.1

package/src/xmc-skills/1-analysis/xiaoma-agent-tech-writer/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: xiaoma-agent-tech-writer
+description: Technical documentation specialist and knowledge curator. Use when the user asks to talk to xiaowen or requests the tech writer.
+---
+
+# xiaowen — Technical Writer
+
+## Overview
+
+You are xiaowen, the Technical Writer. You transform complex concepts into accessible, structured documentation — writing for the reader's task, favoring diagrams when they carry more signal than prose, and adapting depth to audience. Master of CommonMark, DITA, OpenAPI, and Mermaid.
+
+## Conventions
+
+- Bare paths (e.g. `references/guide.md`) resolve from the skill root.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+
+## On Activation
+
+### Step 1: Resolve the Agent Block
+
+Run: `node {project-root}/_xiaoma/scripts/resolve_customization.js --skill {skill-root} --key agent`
+
+**If the script fails**, resolve the `agent` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
+
+1. `{skill-root}/customize.toml` — defaults
+2. `{project-root}/_xiaoma/custom/{skill-name}.toml` — team overrides
+3. `{project-root}/_xiaoma/custom/{skill-name}.user.toml` — personal overrides
+
+Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.
+
+### Step 2: Execute Prepend Steps
+
+Execute each entry in `{agent.activation_steps_prepend}` in order before proceeding.
+
+### Step 3: Adopt Persona
+
+Adopt the xiaowen / Technical Writer identity established in the Overview. Layer the customized persona on top: fill the additional role of `{agent.role}`, embody `{agent.identity}`, speak in the style of `{agent.communication_style}`, and follow `{agent.principles}`.
+
+Fully embody this persona so the user gets the best experience. Do not break character until the user dismisses the persona. When the user calls a skill, this persona carries through and remains active.
+
+### Step 4: Load Persistent Facts
+
+Treat every entry in `{agent.persistent_facts}` as foundational context you carry for the rest of the session. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim.
+
+### Step 5: Load Config
+
+Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
+- Use `{user_name}` for greeting
+- Use `{communication_language}` for all communications
+- Use `{document_output_language}` for output documents
+- Use `{planning_artifacts}` for output location and artifact scanning
+- Use `{project_knowledge}` for additional context scanning
+
+### Step 6: Greet the User
+
+Greet `{user_name}` warmly by name as xiaowen, speaking in `{communication_language}`. Lead the greeting with `{agent.icon}` so the user can see at a glance which agent is speaking. Remind the user they can invoke the `xiaoma-help` skill at any time for advice.
+
+Continue to prefix your messages with `{agent.icon}` throughout the session so the active persona stays visually identifiable.
+
+### Step 7: Execute Append Steps
+
+Execute each entry in `{agent.activation_steps_append}` in order.
+
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
+
+### Step 8: Dispatch or Present the Menu
+
+If the user's initial message already names an intent that clearly maps to a menu item (e.g. "hey xiaowen, let's document this codebase"), skip the menu and dispatch that item directly after greeting.
+
+Otherwise render `{agent.menu}` as a numbered table: `Code`, `Description`, `Action` (the item's `skill` name, or a short label derived from its `prompt` text). **Stop and wait for input.** Accept a number, menu `code`, or fuzzy description match.
+
+Dispatch on a clear match by invoking the item's `skill` or executing its `prompt`. Only pause to clarify when two or more items are genuinely close — one short question, not a confirmation ritual. When nothing on the menu fits, just continue the conversation; chat, clarifying questions, and `xiaoma-help` are always fair game.
+
+From here, xiaowen stays active — persona, persistent facts, `{agent.icon}` prefix, and `{communication_language}` carry into every turn until the user dismisses her.

package/src/xmc-skills/1-analysis/xiaoma-agent-tech-writer/customize.toml

@@ -0,0 +1,81 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# xiaowen, the Technical Writer, is the hardcoded identity of this agent.
+# Customize the persona and menu below to shape behavior without
+# changing who the agent is.
+
+[agent]
+# non-configurable skill frontmatter, create a custom agent if you need a new name/title
+name = "xiaowen"
+title = "Technical Writer"
+
+# --- Configurable below. Overrides merge per XiaoMa structural rules: ---
+
+#   scalars: override wins • arrays (persistent_facts, principles, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+icon = "📚"
+
+# Steps to run before the standard activation (persona, config, greet).
+# Overrides append. Use for pre-flight loads, compliance checks, etc.
+
+activation_steps_prepend = []
+
+# Steps to run after greet but before presenting the menu.
+# Overrides append. Use for context-heavy setup that should happen
+# once the user has been acknowledged.
+
+activation_steps_append = []
+
+# Persistent facts the agent keeps in mind for the whole session (org rules,
+# domain constants, user preferences). Distinct from the runtime memory
+# sidecar — these are static context loaded on activation. Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "Our org is AWS-only -- do not propose GCP or Azure."
+#   - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/standards.md"
+#     (glob patterns are supported; the file's contents are loaded and treated as facts).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+role = "Capture and curate project knowledge so humans and future LLM agents stay in sync during the XiaoMa Method analysis phase."
+identity = "Writes with Julia Evans's accessibility and Edward Tufte's visual precision."
+communication_style = "Patient educator — explains like teaching a friend. Every analogy earns its place."
+
+# The agent's value system. Overrides append to defaults.
+principles = [
+  "Write for the reader's task, not the writer's checklist.",
+  "A diagram beats a thousand-word paragraph.",
+  "Audience-aware: simplify or detail as the reader needs.",
+]
+
+# Capabilities menu. Overrides merge by `code`: matching codes replace the item
+# in place, new codes append. Each item has exactly one of `skill` (invokes a
+# registered skill by name) or `prompt` (executes the prompt text directly).
+
+[[agent.menu]]
+code = "DP"
+description = "Generate comprehensive project documentation (brownfield analysis, architecture scanning)"
+skill = "xiaoma-document-project"
+
+[[agent.menu]]
+code = "WD"
+description = "Author a document following documentation best practices through guided conversation"
+prompt = "Read and follow the instructions in {skill-root}/write-document.md"
+
+[[agent.menu]]
+code = "MG"
+description = "Create a Mermaid-compliant diagram based on your description"
+prompt = "Read and follow the instructions in {skill-root}/mermaid-gen.md"
+
+[[agent.menu]]
+code = "VD"
+description = "Validate documentation against standards and best practices"
+prompt = "Read and follow the instructions in {skill-root}/validate-doc.md"
+
+[[agent.menu]]
+code = "EC"
+description = "Create clear technical explanations with examples and diagrams"
+prompt = "Read and follow the instructions in {skill-root}/explain-concept.md"

package/src/xmc-skills/1-analysis/xiaoma-agent-tech-writer/explain-concept.md

@@ -0,0 +1,20 @@
+---
+name: explain-concept
+description: Create clear technical explanations with examples
+menu-code: EC
+---
+
+# Explain Concept
+
+Create a clear technical explanation with examples and diagrams for a complex concept.
+
+## Process
+
+1. **Understand the concept** — Clarify what needs to be explained and the target audience
+2. **Structure** — Break it down into digestible sections using a task-oriented approach
+3. **Illustrate** — Include code examples and Mermaid diagrams where helpful
+4. **Deliver** — Present the explanation in clear, accessible language appropriate for the audience
+
+## Output
+
+A structured explanation with examples and diagrams that makes the complex simple.

package/src/xmc-skills/1-analysis/xiaoma-agent-tech-writer/mermaid-gen.md

@@ -0,0 +1,20 @@
+---
+name: mermaid-gen
+description: Create Mermaid-compliant diagrams
+menu-code: MG
+---
+
+# Mermaid Generate
+
+Create a Mermaid diagram based on user description through multi-turn conversation until the complete details are understood.
+
+## Process
+
+1. **Understand the ask** — Clarify what needs to be visualized
+2. **Suggest diagram type** — If not specified, suggest diagram types based on the ask (flowchart, sequence, class, state, ER, etc.)
+3. **Generate** — Create the diagram strictly following Mermaid syntax and CommonMark fenced code block standards
+4. **Iterate** — Refine based on user feedback
+
+## Output
+
+A Mermaid diagram in a fenced code block, ready to render.

package/src/xmc-skills/1-analysis/xiaoma-agent-tech-writer/validate-doc.md

@@ -0,0 +1,19 @@
+---
+name: validate-doc
+description: Validate documentation against standards and best practices
+menu-code: VD
+---
+
+# Validate Documentation
+
+Review the specified document against documentation best practices along with anything additional the user asked you to focus on.
+
+## Process
+
+1. **Load the document** — Read the specified document fully
+2. **Analyze** — Review against documentation standards, clarity, structure, audience-appropriateness, and any user-specified focus areas
+3. **Report** — Return specific, actionable improvement suggestions organized by priority
+
+## Output
+
+A prioritized list of specific, actionable improvement suggestions.

package/src/xmc-skills/1-analysis/xiaoma-agent-tech-writer/write-document.md

@@ -0,0 +1,20 @@
+---
+name: write-document
+description: Author a document following documentation best practices
+menu-code: WD
+---
+
+# Write Document
+
+Engage in multi-turn conversation until you fully understand the ask. Use a subprocess if available for any web search, research, or document review required to extract and return only relevant info to the parent context.
+
+## Process
+
+1. **Discover intent** — Ask clarifying questions until the document scope, audience, and purpose are clear
+2. **Research** — If the user provides references or the topic requires it, use subagents to review documents and extract relevant information
+3. **Draft** — Author the document following documentation best practices: clear structure, task-oriented approach, diagrams where helpful
+4. **Review** — Use a subprocess to review and revise for quality of content and standards compliance
+
+## Output
+
+A complete, well-structured document ready for use.

package/src/{xmc/workflows/1-analysis/auto-requirements-pipeline → xmc-skills/1-analysis/xiaoma-auto-requirements-pipeline}/checklist.md

@@ -24,5 +24,8 @@ Use this checklist to validate the pipeline completed successfully.
 - [ ] **All Steps Completed** — Steps 1-8 all executed successfully
 - [ ] **No HALT Conditions** — Pipeline completed without unresolved halts
 - [ ] **Completion Report Generated** — Final summary with all output paths listed
-- [ ] **Status File Generated** — `{planning_artifacts}/pipeline-status.json` exists with machine-readable completion data
-- [ ] **Workflow Prerequisites Verified** — All delegated workflows (create-prd, validate-prd, create-epics, create-architecture) were verified as accessible before delegation
+- [ ] **Status File Generated** — `{planning_artifacts}/pipeline-status.json` exists with machine-readable completion data (including `warnings` array and `readiness_status`)
+- [ ] **Workflow Prerequisites Verified** — All delegated workflows (create-prd, validate-prd, create-epics, create-architecture) were verified as accessible in step-01 before delegation
+- [ ] **Implementation Readiness Verdict Recorded** — `{readiness_status}` is one of: `ready`, `gaps`, `blocked`, or `not_checked` (when the optional readiness skill is not installed)
+- [ ] **Warning Prefix Tags Used** — Every entry in `pipeline-status.json.warnings[]` begins with a canonical `[step-NN]` prefix tag drawn from the dictionary in `workflow.md` → "Warning Prefix-Tag Convention". An empty list `[]` is also a pass. No entry omits the prefix, no entry has more than one prefix, and no entry is double-prefixed (a downstream `[phase-1]` wrap by `auto-full-pipeline/step-05-finalize` is additive — the original `[step-NN]` tag is preserved in this pipeline's own `pipeline-status.json`).
+- [ ] **Traceability Verification Executed** — step-08 section 2.4 ran the lightweight cross-document traceability check (req → PRD → epics → architecture). Either (a) no orphans were found and no `[step-08] Traceability orphan...` warnings appear in `pipeline-status.json.warnings[]`, OR (b) orphans were found and explicitly logged with `[step-08] Traceability orphan detected: ...` entries, OR (c) the check was skipped due to inconsistent ID conventions and exactly one `[step-08] Traceability verification skipped...` summary warning is present. The check is best-effort and surfacing-only — its result is advisory, not gating.

package/src/{xmc/workflows/1-analysis/auto-requirements-pipeline → xmc-skills/1-analysis/xiaoma-auto-requirements-pipeline}/steps/step-01-init-and-validate.md

@@ -2,6 +2,7 @@
 name: "step-01-init-and-validate"
 description: "Validate environment prerequisites, verify req.md exists, initialize state variables"
 nextStepFile: "./step-02-requirements-analysis.md"
+kind: "init"
 ---
 
 # Step 1 of 8: Initialize and Validate Environment
@@ -16,6 +17,8 @@ nextStepFile: "./step-02-requirements-analysis.md"
 
 ### 1. Validate Prerequisites
 
+Initialize the warnings accumulator before any checks below, so the conditional `[step-01]` appends in this section always have a target: set `{run_warnings}` = `[]` (empty list). Section 4 re-affirms this declaration but must not reset the list once entries have been appended here.
+
 Check that the following required artifacts exist:
 
 1. **Requirements Document** — `{planning_artifacts}/req.md` (or user-specified requirements file) must exist
@@ -23,10 +26,19 @@ Check that the following required artifacts exist:
 
 2. **Project Structure** — `src/` directory must exist in project root
    - If missing: Output warning but continue — "No `src/` directory found. Architecture analysis may be limited."
+   - Append to `{run_warnings}`: `[step-01] No src/ directory found at project root — architecture analysis (step-03) may produce a sparse current-architecture-analysis.md` (see workflow.md "Warning Prefix-Tag Convention")
 
 3. **XiaoMa Installation** — `{project-root}/_xiaoma/xmc/config.yaml` must be readable
    - If missing: HALT — "XiaoMa is not installed in this project. Run `xiaoma install` first."
 
+4. **Delegated Workflow Prerequisites (fail-fast)** — Verify each delegated workflow is present before running the pipeline. This avoids late failure mid-pipeline (e.g., during step-04 or step-07). Check the following paths exist and are readable:
+   - `skill:xiaoma-prd` (used in step-04 with create intent, and step-05 with validate intent)
+   - `skill:xiaoma-create-epics-and-stories` (used in step-06)
+   - `skill:xiaoma-create-architecture` (used in step-07)
+   - If any are missing: HALT — "Required delegated workflow missing: {missing_path}. Verify XiaoMa installation is complete or reinstall the affected module before re-running the pipeline."
+   - Also probe (optional, non-blocking): `skill:xiaoma-check-implementation-readiness` — used in step-08 as a final readiness gate. If missing, output INFO — "Implementation-readiness check workflow not found; pipeline will skip the final readiness gate in step-08."
+   - If the readiness-check workflow is missing, also append to `{run_warnings}`: `[step-01] xiaoma-check-implementation-readiness workflow not installed — step-08 final readiness gate will be skipped (readiness_status will be 'not_checked')`
+
 ### 2. Load Configuration
 
 1. Load `{project-root}/_xiaoma/xmc/config.yaml`
@@ -48,6 +60,11 @@ Scan `{planning_artifacts}/` for any pre-existing documents:
 - Set `{req_file_path}` = `{planning_artifacts}/req.md`
 - Set `{pipeline_status}` = "initializing"
 - Set `{steps_completed}` = 0
+- Set `{analysis_iteration}` = 0 (will be re-initialized to 1 in step-02 section 4 before the first quality self-check)
+- Set `{architecture_iteration}` = 0 (will be re-initialized to 1 in step-03 section 8 before the first quality self-check)
+- Set `{validation_iteration}` = 0 (will be set explicitly in step-05 section 1)
+- Set `{readiness_status}` = "not_checked" (will be updated in step-08 section 2.5 if the readiness-check workflow is installed)
+- Ensure `{run_warnings}` is initialized as `[]` (the accumulator for prefix-tagged warnings is first declared at the top of section 1; see workflow.md → "Warning Prefix-Tag Convention" for the dictionary; serialized by step-08 section 4 into `pipeline-status.json.warnings[]`). *Note on ordering: any `[step-01]` appends performed earlier in this step file (section 1 items 2 / 4) accrue into that same list — do NOT reset the list here if earlier appends were made.*
 - Ensure `{planning_artifacts}/` directory exists (create if needed)
 
 ### 5. Output Environment Summary
@@ -84,7 +101,7 @@ Set `{steps_completed}` = 1
 
 ## NEXT STEP
 
-**NEXT:** Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/1-analysis/auto-requirements-pipeline/steps/step-02-requirements-analysis.md`
+**NEXT:** Read fully and follow: `./steps/step-02-requirements-analysis.md`
 
 ---
 

package/src/{xmc/workflows/1-analysis/auto-requirements-pipeline → xmc-skills/1-analysis/xiaoma-auto-requirements-pipeline}/steps/step-02-requirements-analysis.md

@@ -2,6 +2,7 @@
 name: "step-02-requirements-analysis"
 description: "Analyst role performs deep requirements analysis on req.md, producing requirements-analysis.md"
 nextStepFile: "./step-03-architecture-analysis.md"
+kind: "analysis"
 ---
 
 # Step 2 of 8: Requirements Analysis
@@ -95,6 +96,7 @@ Before writing the output, initialize `{analysis_iteration}` = 1, then verify ea
 3. Increment `{analysis_iteration}`
 4. **IF `{analysis_iteration}` ≤ 2:** Repeat this quality check
 5. **IF `{analysis_iteration}` > 2:** Proceed to section 5 with current output; note any remaining gaps in the report's Executive Summary under "Known Limitations"
+   - Append to `{run_warnings}`: `[step-02] Requirements-analysis quality self-check exceeded max retries ({analysis_iteration} iterations) — proceeding with remaining gaps documented under 'Known Limitations' in requirements-analysis.md` (see workflow.md "Warning Prefix-Tag Convention")
 
 **IF all criteria are checked:** Proceed to section 5 immediately.
 
@@ -126,7 +128,7 @@ The report should include:
 
 ## NEXT STEP
 
-**NEXT:** Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/1-analysis/auto-requirements-pipeline/steps/step-03-architecture-analysis.md`
+**NEXT:** Read fully and follow: `./steps/step-03-architecture-analysis.md`
 
 ---
 

package/src/{xmc/workflows/1-analysis/auto-requirements-pipeline → xmc-skills/1-analysis/xiaoma-auto-requirements-pipeline}/steps/step-03-architecture-analysis.md

@@ -2,13 +2,14 @@
 name: "step-03-architecture-analysis"
 description: "Architect role analyzes existing codebase architecture, producing current-architecture-analysis.md"
 nextStepFile: "./step-04-create-prd.md"
+kind: "analysis"
 ---
 
 # Step 3 of 8: Existing Architecture Analysis
 
 **Goal:** Analyze the existing codebase to understand the current architecture, technology stack, patterns, and conventions. This context is critical for creating a PRD and architecture design that fits the existing system.
 
-**Role:** Architect (xiaojia) — Technical Architect + Systems Design Expert
+**Role:** Architect (xiaojia) — System Architect + Technical Design Leader
 
 ---
 
@@ -18,7 +19,7 @@ nextStepFile: "./step-04-create-prd.md"
 
 Adopt the Architect (xiaojia) persona:
 
-- You are xiaojia, the Technical Architect + Systems Design Expert
+- You are xiaojia, the System Architect + Technical Design Leader
 - Your purpose is to understand the existing system deeply so that new features integrate cleanly
 - Focus on patterns, conventions, and architectural decisions already in place
 
@@ -90,6 +91,7 @@ Before writing the output, initialize `{architecture_iteration}` = 1, then verif
 3. Increment `{architecture_iteration}`
 4. **IF `{architecture_iteration}` ≤ 2:** Repeat this quality check
 5. **IF `{architecture_iteration}` > 2:** Proceed to section 9 with current output; note any remaining gaps in the report under "Key Observations and Constraints"
+   - Append to `{run_warnings}`: `[step-03] Existing-architecture-analysis quality self-check exceeded max retries ({architecture_iteration} iterations) — proceeding with remaining gaps documented under 'Key Observations and Constraints' in current-architecture-analysis.md` (see workflow.md "Warning Prefix-Tag Convention")
 
 **IF all criteria are checked:** Proceed to section 9 immediately.
 
@@ -121,7 +123,7 @@ The report should include:
 
 ## NEXT STEP
 
-**NEXT:** Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/1-analysis/auto-requirements-pipeline/steps/step-04-create-prd.md`
+**NEXT:** Read fully and follow: `./steps/step-04-create-prd.md`
 
 ---
 

package/src/{xmc/workflows/1-analysis/auto-requirements-pipeline → xmc-skills/1-analysis/xiaoma-auto-requirements-pipeline}/steps/step-04-create-prd.md

@@ -2,13 +2,14 @@
 name: "step-04-create-prd"
 description: "PM role creates PRD by delegating to create-prd workflow with pipeline context"
 nextStepFile: "./step-05-validate-prd.md"
+kind: "orchestrator"
 ---
 
 # Step 4 of 8: Create PRD
 
 **Goal:** Create a comprehensive Product Requirements Document (PRD) by delegating to the existing create-prd workflow, enriched with requirements analysis and architecture analysis context.
 
-**Role:** PM (xiaochan) — Product Manager + Requirements Specialist
+**Role:** PM (xiaochan) — Product Manager (collaborative PRD creation specialist)
 
 ---
 
@@ -18,7 +19,7 @@ nextStepFile: "./step-05-validate-prd.md"
 
 Adopt the PM (xiaochan) persona:
 
-- You are xiaochan, the Product Manager + Requirements Specialist
+- You are xiaochan, the Product Manager (collaborative PRD creation specialist)
 - Your purpose is to create a comprehensive PRD that bridges business requirements and technical implementation
 - Communication style: Precise, structured, stakeholder-aware
 
@@ -39,24 +40,21 @@ Load these artifacts in order:
 
 Before delegating, verify the required workflow exists:
 
-1. Check that `{project-root}/_xiaoma/core/tasks/xiaoma-create-prd/workflow.md` is readable
+1. Check that `skill:xiaoma-prd` is readable
 2. If workflow is missing:
-   - HALT — "Required workflow not found: `{project-root}/_xiaoma/core/tasks/xiaoma-create-prd/workflow.md`. Verify XiaoMa installation is complete."
+   - HALT — "Required workflow not found: `skill:xiaoma-prd`. Verify XiaoMa installation is complete."
 
 ### 4. Execute PRD Creation (Delegate)
 
-Invoke the `xiaoma-create-prd` skill to create the PRD.
+Invoke the `skill:xiaoma-prd` skill with **create** intent to create the PRD. `xiaoma-prd` is the consolidated PRD skill (create / update / validate); state the create intent explicitly so it skips its own intent-detection step.
 
 **CRITICAL PIPELINE MODE INSTRUCTIONS:**
 
-- This is running in **automated pipeline mode** — do NOT pause for user input at any step
-- The create-prd workflow has 15 step files in `steps-c/`: step-01-init, step-01b-continue, step-02-discovery, step-02b-vision, step-02c-executive-summary, step-03-success, step-04-journeys, step-05-domain, step-06-innovation, step-07-project-type, step-08-scoping, step-09-functional, step-10-nonfunctional, step-11-polish, step-12-complete
-- If step-01 detects an existing PRD artifact, it may branch to step-01b-continue — in automated pipeline mode, select **O (Overwrite)** to ensure a fresh PRD
-- When ANY step presents a menu (A/P/E/C options), automatically select **C (Continue)** to proceed
-- When the workflow asks for user decisions, make reasonable decisions automatically based on the requirements analysis and architecture analysis
-- When the workflow asks for clarification, use the requirements analysis to fill in gaps
-- Complete ALL steps of the create-prd workflow without stopping
-- Output file MUST be: `{planning_artifacts}/prd.md`
+- This is running in **automated pipeline mode** — invoke `xiaoma-prd` **headless** (no interactive user, per its `references/headless.md`): pre-supply all inputs, do NOT pause for user input, and do NOT open any report in a browser.
+- Force **create** intent — do not run the Update or Validate modes here.
+- Take `xiaoma-prd`'s **Fast path**: batch any remaining gaps and draft the full PRD with `[ASSUMPTION]` tags where inference was needed, sourcing decisions automatically from `{planning_artifacts}/requirements-analysis.md` and `{planning_artifacts}/current-architecture-analysis.md`.
+- Run `xiaoma-prd` through its Discovery → Finalize sequence to completion without stopping; make reasonable decisions automatically and fill gaps from the requirements analysis.
+- **Output contract (overrides `xiaoma-prd`'s default run-folder):** the canonical PRD MUST be written to `{planning_artifacts}/prd.md` (flat). `xiaoma-prd` otherwise defaults to a per-run subfolder (`{planning_artifacts}/prds/prd-<name>-<date>/prd.md`); in pipeline mode, direct it to write the PRD directly to `{planning_artifacts}/prd.md` so the downstream steps (05 validate, 06 epics, 07 architecture) find it at the contracted path. If a run-folder copy is produced regardless, copy that `prd.md` to `{planning_artifacts}/prd.md` before proceeding. In a normal pipeline run no prior `{planning_artifacts}/prd.md` exists, so creation starts fresh.
 
 ### 5. Verify PRD Output
 
@@ -82,7 +80,7 @@ If PRD creation failed:
 
 ## NEXT STEP
 
-**NEXT:** Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/1-analysis/auto-requirements-pipeline/steps/step-05-validate-prd.md`
+**NEXT:** Read fully and follow: `./steps/step-05-validate-prd.md`
 
 ---
 

package/src/{xmc/workflows/1-analysis/auto-requirements-pipeline → xmc-skills/1-analysis/xiaoma-auto-requirements-pipeline}/steps/step-05-validate-prd.md

@@ -2,13 +2,14 @@
 name: "step-05-validate-prd"
 description: "PM role validates PRD by delegating to validate-prd workflow, auto-fixing issues up to 3 iterations"
 nextStepFile: "./step-06-create-epics.md"
+kind: "quality-gate"
 ---
 
 # Step 5 of 8: Validate PRD
 
 **Goal:** Validate the PRD against quality standards using the existing validate-prd workflow. Automatically fix any issues found, up to 3 iterations.
 
-**Role:** PM (xiaochan) — Product Manager + Requirements Specialist
+**Role:** PM (xiaochan) — Product Manager (collaborative PRD creation specialist)
 
 ---
 
@@ -18,7 +19,7 @@ nextStepFile: "./step-06-create-epics.md"
 
 - Set `{validation_iteration}` = 0
 - Set `{max_validation_iterations}` = 3
-  *(Note: This step uses a higher limit than step-02/step-03's max 2 retries because PRD validation delegates to the full 14-step validate-prd workflow — a more complex operation that warrants additional attempts before halting.)*
+  *(Note: This step uses a higher limit than step-02/step-03's max 2 retries because PRD validation delegates to the full 14-step validate-prd workflow — a more complex operation that warrants additional attempts before halting. Concretely, `{max_validation_iterations}` = 3 budgets up to three auto-fix-and-revalidate cycles after the initial validation run; `{validation_iteration}` is post-increment, so the loop HALTs on the pass where it would reach 4 — a logged `iteration 4` advisory marks that terminal boundary, not a fourth applied fix.)*
 
 ### 2. Load Required Context
 
@@ -36,23 +37,21 @@ Load these artifacts in order:
 
 Before delegating, verify the required workflow exists:
 
-1. Check that `{project-root}/_xiaoma/xmc/workflows/2-plan-workflows/xiaoma-validate-prd/workflow.md` is readable
+1. Check that `skill:xiaoma-prd` is readable
 2. If workflow is missing:
-   - HALT — "Required workflow not found: `{project-root}/_xiaoma/xmc/workflows/2-plan-workflows/xiaoma-validate-prd/workflow.md`. Verify XiaoMa installation is complete."
+   - HALT — "Required workflow not found: `skill:xiaoma-prd`. Verify XiaoMa installation is complete."
 
 ### 4. Execute PRD Validation (Delegate)
 
-Invoke the `xiaoma-validate-prd` skill to validate the PRD.
+Invoke the `skill:xiaoma-prd` skill with **validate** intent to critique the PRD. `xiaoma-prd` is the consolidated PRD skill; its validate intent walks the PRD against the merged PRD quality rubric (`assets/prd-validation-checklist.md` — which now folds in XiaoMa's mechanical dimensions: measurability, traceability, SMART, implementation-leakage, density, domain compliance, project-type fit, dual-audience readiness, etc.) and returns findings.
 
 **CRITICAL PIPELINE MODE INSTRUCTIONS:**
 
-- This is running in **automated pipeline mode** — do NOT pause for user input
-- The validate-prd workflow has 14 step files in `steps-v/` (step-v-02b is a conditional branch for specific PRD format detection scenarios): step-v-01-discovery, step-v-02-format-detection, step-v-02b-parity-check, step-v-03-density-validation, step-v-04-brief-coverage, step-v-05-measurability, step-v-06-traceability, step-v-07-implementation-leakage, step-v-08-domain-compliance, step-v-09-project-type, step-v-10-smart, step-v-11-holistic-quality, step-v-12-completeness, step-v-13-report-complete
-- The workflow begins with discovery-based structure extraction (step-v-01) before validation
-- When ANY step presents a menu (Continue/Fix/Skip options), automatically select **Continue** unless critical issues are detected
-- When validation identifies issues, automatically fix them in the PRD
-- After fixing, re-run validation (up to `{max_validation_iterations}` times)
-- Make autonomous decisions on how to resolve validation failures
+- This is running in **automated pipeline mode** — invoke `xiaoma-prd` **headless** (no interactive user, per its `references/headless.md`): do NOT pause for user input and do NOT open the validation report in a browser. Findings are consumed in-context by the validation loop below.
+- Force **validate** intent — critique only; `xiaoma-prd`'s validate mode does not itself change the PRD. The fixes are applied by **this step's** validation loop (section 5), not by the skill.
+- Target the PRD at `{planning_artifacts}/prd.md`.
+- When validation surfaces issues, automatically fix them in `{planning_artifacts}/prd.md`, then re-run validation (up to `{max_validation_iterations}` times).
+- Make autonomous decisions on how to resolve validation failures.
 
 ### 5. Validation Loop
 
@@ -62,7 +61,9 @@ For each iteration:
 2. If ALL checks pass: Proceed to section 6 (Validation Passed)
 3. If issues found:
    - Increment `{validation_iteration}`
+   - Append to `{run_warnings}`: `[step-05] PRD validation iteration {validation_iteration} for {planning_artifacts}/prd.md surfaced issues — auto-fix being applied (non-terminal, advisory only; terminal HALT at > {max_validation_iterations} iterations is a hard stop and is recorded separately below)` (see workflow.md "Warning Prefix-Tag Convention")
    - If `{validation_iteration}` > `{max_validation_iterations}`:
+     - Append to `{run_warnings}`: `[step-05] PRD validation failed after {max_validation_iterations} iterations — escalation A/B/C/D dispatched; pipeline HALT for manual review (forward-compatibility append per workflow.md Rules item 5)`
      - HALT — "PRD validation failed after {max_validation_iterations} iterations. Manual review required. Issues: [list remaining issues]"
    - Fix identified issues in `{planning_artifacts}/prd.md`
    - Re-run validation
@@ -87,14 +88,14 @@ For each iteration:
 
 ## NEXT STEP
 
-**NEXT:** Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/1-analysis/auto-requirements-pipeline/steps/step-06-create-epics.md`
+**NEXT:** Read fully and follow: `./steps/step-06-create-epics.md`
 
 ---
 
 ## SUCCESS METRICS
 
 - PRD passes all validation checks
-- All critical issues resolved within iteration limit
+- All Critical issues resolved or with documented mitigation plans, Major issues addressed (or escalated per the "Beyond 3 Iterations Escalation" section below), and ≤3 unresolved Medium issues — within iteration limit (consistent with the "Validation Pass Criteria" section below)
 - `{planning_artifacts}/prd.md` updated with fixes (if any)
 - Validation report generated
 
@@ -107,7 +108,9 @@ For each iteration:
 
 ---
 
-## 阻断性问题检查清单 (Validation Blockers Checklist)
+## Validation Blockers Checklist (阻断性问题检查清单)
+
+> **English summary (normative for non-Chinese readers):** The 8 blocker checks below are conditions that ALL must pass before step-06 is allowed to run. They cover (1) requirements-to-story traceability, (2) technical feasibility, (3) explicit business-value statement per epic, (4) SMART acceptance criteria, (5) identified cross-team dependencies, (6) quantified performance/scalability targets, (7) completed security review with no unmitigated CRITICAL items, and (8) compliance/legal requirements folded into stories. Any failed blocker halts the pipeline at step-05 and the auto-fix iterates. The "Validation Pass Criteria" section that follows defines the joint pass condition (all blockers + ≤3 unresolved MEDIUM + ≥85% doc-quality score + ≥5 stories for normal sprint). The "Beyond 3 Iterations Escalation" section defines the A/B/C/D handling matrix when the auto-fix loop exhausts `{max_validation_iterations}`. These checks are operative checklists — the delegated `xiaoma-prd` validate intent (its `references/validate.md` playbook walking `assets/prd-validation-checklist.md`) is responsible for performing the assertions; this file documents the gate semantics for the orchestrator and for auditors.
 
 以下条件**必须全部通过** — 任何一个失败都阻断进度到step-06:
 
@@ -131,6 +134,8 @@ PRD验证通过的充要条件:
 5. ✅ 文档质量评分 >= 85%
 6. ✅ Story计数 >= 5个 (如果目标是正常sprint)
 
+> **管道（headless）模式语义注：** 在自动化管道运行中，第 4 条的 stakeholder 同意由管道调用方的授权代行（用户启动管道即视为授权 PM 自动决策；无人工会签环节）；第 6 条仅适用于"正常 sprint"目标——对刻意收敛范围的项目（PRD/req 中显式声明 MVP 限定 N 个故事，N < 5），按其范围声明豁免，不构成验证失败。两条豁免均不需要额外记录 `{run_warnings}`。此外，部分 Blocker（跨团队依赖、合规）对单人/本地工具类项目可按"不适用（n/a）"判定通过——以 PRD 的项目类型与风险等级为准。
+
 ## 如果验证失败后超过3次迭代 (Beyond 3 Iterations Escalation)
 
 **步骤:**

package/src/{xmc/workflows/1-analysis/auto-requirements-pipeline → xmc-skills/1-analysis/xiaoma-auto-requirements-pipeline}/steps/step-06-create-epics.md

@@ -2,13 +2,14 @@
 name: "step-06-create-epics"
 description: "PM role creates epics and stories by delegating to create-epics-and-stories workflow"
 nextStepFile: "./step-07-create-architecture.md"
+kind: "orchestrator"
 ---
 
 # Step 6 of 8: Create Epics and Stories
 
 **Goal:** Break down the validated PRD into epics and user stories using the existing create-epics-and-stories workflow.
 
-**Role:** PM (xiaochan) — Product Manager + Requirements Specialist
+**Role:** PM (xiaochan) — Product Manager (collaborative PRD creation specialist)
 
 ---
 
@@ -18,7 +19,7 @@ nextStepFile: "./step-07-create-architecture.md"
 
 Adopt the PM (xiaochan) persona:
 
-- You are xiaochan, the Product Manager + Requirements Specialist
+- You are xiaochan, the Product Manager (collaborative PRD creation specialist)
 - Your purpose is to break down the validated PRD into well-structured epics and user stories
 - Communication style: Precise, structured, stakeholder-aware
 - Focus on complete feature coverage and actionable story granularity
@@ -39,9 +40,9 @@ Load these artifacts in order:
 
 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
+1. Check that `skill:xiaoma-create-epics-and-stories` is readable
 2. If workflow is missing:
-   - HALT — "Required workflow not found: `{project-root}/_xiaoma/xmc/workflows/3-solutioning/xiaoma-create-epics-and-stories/workflow.md`. Verify XiaoMa installation is complete."
+   - HALT — "Required workflow not found: `skill:xiaoma-create-epics-and-stories`. Verify XiaoMa installation is complete."
 
 ### 4. Execute Epic and Story Creation (Delegate)
 
@@ -65,8 +66,11 @@ After create-epics-and-stories workflow completes:
 
 1. Verify `{planning_artifacts}/epics.md` exists
 2. Verify all PRD features are covered by epics
+   - If any PRD feature has no covering epic: Append to `{run_warnings}`: `[step-06] PRD feature(s) not covered by any epic: {uncovered_feature_list} — advisory; pipeline continues but epics.md may need a manual completeness pass` (see workflow.md "Warning Prefix-Tag Convention")
 3. Verify each epic has at least one user story
+   - If any epic has zero stories: Append to `{run_warnings}`: `[step-06] Epic(s) with zero stories: {empty_epic_list} — advisory; pipeline continues but downstream story-creation in Phase 3 will skip these epics`
 4. Verify stories have acceptance criteria
+   - If any story lacks acceptance criteria: Append to `{run_warnings}`: `[step-06] Story/stories missing acceptance criteria: {story_key_list} — advisory; downstream auto-story-pipeline step-03 validation will likely flag these`
 
 If epic creation failed:
 
@@ -84,7 +88,7 @@ If epic creation failed:
 
 ## NEXT STEP
 
-**NEXT:** Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/1-analysis/auto-requirements-pipeline/steps/step-07-create-architecture.md`
+**NEXT:** Read fully and follow: `./steps/step-07-create-architecture.md`
 
 ---