@zeyue0329/xiaoma-cli 1.12.0 → 1.15.0

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

@@ -2,13 +2,14 @@
 name: "step-07-create-architecture"
 description: "Architect role creates technical architecture design by delegating to create-architecture workflow"
 nextStepFile: "./step-08-finalize.md"
+kind: "orchestrator"
 ---
 
 # Step 7 of 8: Create Architecture Design
 
 **Goal:** Design the technical architecture for the new features/requirements, integrating with the existing codebase architecture. Delegates to the existing create-architecture workflow.
 
-**Role:** Architect (xiaojia) — Technical Architect + Systems Design Expert
+**Role:** Architect (xiaojia) — System Architect + Technical Design Leader
 
 ---
 
@@ -18,7 +19,7 @@ nextStepFile: "./step-08-finalize.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 design an architecture that integrates new requirements cleanly with the existing system
 - Focus on incremental, pragmatic design that respects existing patterns
 
@@ -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-architecture/workflow.md` is readable
+1. Check that `skill:xiaoma-create-architecture` is readable
 2. If workflow is missing:
-   - HALT — "Required workflow not found: `{project-root}/_xiaoma/xmc/workflows/3-solutioning/xiaoma-create-architecture/workflow.md`. Verify XiaoMa installation is complete."
+   - HALT — "Required workflow not found: `skill:xiaoma-create-architecture`. Verify XiaoMa installation is complete."
 
 ### 4. Execute Architecture Design (Delegate)
 
@@ -52,8 +53,9 @@ Invoke the `xiaoma-create-architecture` skill to design the technical architectu
 - This is running in **automated pipeline mode** — do NOT pause for user input
 - The create-architecture workflow has 9 step files: init → (continue) → context → starter → decisions → patterns → structure → validation → complete
 - **IMPORTANT DISTINCTION:** Step 3 of this pipeline creates `current-architecture-analysis.md` (analysis of the *existing* codebase), NOT `architecture.md` (the *new* design document). Therefore `architecture.md` should NOT already exist when step-07 runs. If `architecture.md` IS found unexpectedly (e.g., from a prior partial run), treat it as a stale artifact and let the workflow overwrite/recreate it fresh
-- Step 1 (init) of create-architecture detects existing workflow state — if `architecture.md` already exists unexpectedly, it may branch to step-01b-continue.md — in that case, automatically select **O (Overwrite)** to start fresh
-- Step 1b (continue) presents a menu with R/C/O/X options — if reached due to a stale artifact, automatically select **O (Overwrite)** for a clean pipeline run
+  - When a stale `architecture.md` is detected and overwritten: Append to `{run_warnings}`: `[step-07] Stale architecture.md from a prior partial run was detected and overwritten — verify the new architecture.md is consistent with the just-validated PRD and epics.md` (see workflow.md "Warning Prefix-Tag Convention")
+- Step 1 (init) of create-architecture detects existing workflow state — if `architecture.md` already exists unexpectedly, it may branch to step-01b-continue.md — in that case, automatically select **X (Start over)** to discard the stale document and start fresh
+- Step 1b (continue) presents a menu with R/C/O/X options — note that **[O] = "Overview of all remaining steps" (it does NOT overwrite)** and **[X] = "Start over (will overwrite existing work)"**. If reached due to a stale artifact, automatically select **X (Start over)**; when it then asks "This will delete all existing architectural decisions. Are you sure? (y/n)", automatically answer **y** for a clean pipeline run
 - When ANY step presents a menu with **[C] Continue**, automatically select **C** to proceed to the next step
 - Step 1 asks user to confirm discovered documents — automatically confirm and select **C**
 - When the workflow asks for architectural decisions, make pragmatic choices based on the existing architecture analysis
@@ -68,6 +70,7 @@ After create-architecture workflow completes:
 
 1. Verify `{planning_artifacts}/architecture.md` exists
 2. Verify the architecture addresses all epics from the PRD
+   - If any epic lacks an architectural section / addressing: Append to `{run_warnings}`: `[step-07] Architecture missing coverage for epic(s): {uncovered_epic_list} — advisory; pipeline continues but architecture.md may need a manual coverage pass before Phase 3` (see workflow.md "Warning Prefix-Tag Convention")
 3. Verify it accounts for existing system patterns and conventions
 4. Verify it includes implementation guidance
 
@@ -87,7 +90,7 @@ If architecture creation failed:
 
 ## NEXT STEP
 
-**NEXT:** Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/1-analysis/auto-requirements-pipeline/steps/step-08-finalize.md`
+**NEXT:** Read fully and follow: `./steps/step-08-finalize.md`
 
 ---
 

package/src/xmc-skills/1-analysis/xiaoma-auto-requirements-pipeline/steps/step-08-finalize.md

@@ -0,0 +1,184 @@
+---
+name: "step-08-finalize"
+description: "Generate completion report, validate all artifacts, and provide next-step guidance"
+nextStepFile: null
+kind: "terminal"
+---
+
+# Step 8 of 8: Finalize Pipeline
+
+**Goal:** Validate all output artifacts exist, generate a completion report, and provide guidance on next steps.
+
+**Role:** Pipeline Orchestrator
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Validate All Artifacts
+
+Check that ALL required output files exist:
+
+1. **Requirements Analysis** — `{planning_artifacts}/requirements-analysis.md`
+2. **Architecture Analysis** — `{planning_artifacts}/current-architecture-analysis.md`
+3. **PRD** — `{planning_artifacts}/prd.md`
+4. **Epics** — `{planning_artifacts}/epics.md`
+5. **Architecture Design** — `{planning_artifacts}/architecture.md`
+
+For each missing artifact, log a warning. If PRD or Epics are missing, this is a critical failure.
+
+For each missing non-critical artifact (i.e., requirements-analysis.md, current-architecture-analysis.md, architecture.md), also append to `{run_warnings}`: `[step-08] Expected artifact missing at finalize: {artifact_path} — pipeline declared complete but downstream consumers may receive partial planning context` (see workflow.md "Warning Prefix-Tag Convention"). Critical missing artifacts (prd.md, epics.md) trigger the HALT path and do not need an additional `[step-08]` append since the pipeline does not write `pipeline-status.json` on HALT.
+
+### 2. Run Completion Checklist
+
+Load and evaluate: `./checklist.md`
+
+Mark each item as passed or failed based on artifact verification.
+
+### 2.4. Traceability Verification
+
+**Goal:** Provide a lightweight cross-document traceability check that surfaces orphaned requirements/features before the pipeline declares complete. This complements (does not replace) the optional readiness check in section 2.5 — which is a deeper, multi-document audit — and gives a verdict even when the readiness skill is not installed.
+
+**Procedure (best-effort; surfacing-only, never halts):**
+
+1. Re-read `{req_file_path}`, `{planning_artifacts}/prd.md`, `{planning_artifacts}/epics.md`, and `{planning_artifacts}/architecture.md` from disk (fresh reads — do not rely on cached state from earlier steps).
+2. Extract requirement/feature identifiers using best-effort heuristics:
+   - `req.md` → distinct top-level functional requirements (e.g., `FR-`, `REQ-`, numbered list items in a "Requirements" section)
+   - `prd.md` → declared features (often in a "Features" or "Functional Requirements" section)
+   - `epics.md` → epic→story tree (story → AC mapping)
+   - `architecture.md` → covered subsystems / components referenced by epic number
+3. For each source identifier in `req.md`, attempt to find at least one downstream reference (PRD feature → epic → story → architecture coverage).
+4. For each PRD feature, attempt to find at least one covering epic.
+5. For each epic, verify at least one story exists with non-empty acceptance criteria (this duplicates the step-06 in-flight check but re-asserts at finalize against the on-disk state).
+6. For any orphan (requirement with no PRD feature, PRD feature with no epic, epic with no story, epic not addressed by architecture):
+   - Append to `{run_warnings}` using the canonical prefix: `[step-08] Traceability orphan detected: {orphan_kind} {orphan_id} has no downstream coverage in {next_artifact}` (see workflow.md "Warning Prefix-Tag Convention").
+   - Continue — do NOT halt. The downstream readiness check (section 2.5) and `auto-story-pipeline` step-01 are responsible for gating execution.
+7. If the identifier extraction is unreliable (e.g., the documents do not use a consistent ID scheme), append to `{run_warnings}` exactly one summary entry: `[step-08] Traceability verification skipped due to missing identifier conventions in source documents — manual review recommended` and proceed. This avoids generating false-positive orphan warnings on documents that simply do not use identifier conventions.
+
+**Why this lives at step-08:** The checklist.md lists "Requirements Traceability", "Epic Coverage", "Story Completeness", and "No Orphaned Requirements" under Quality Validation, but prior versions of this step never executed these checks — they were aspirational. This section makes them operational without introducing a separate gating step (which would inflate the pipeline to 9 steps and break the documented `N/8` rendering in section 3). The check is intentionally best-effort and surface-only so it remains useful even on greenfield projects where ID conventions are still being established.
+
+### 2.5. Optional Implementation Readiness Check
+
+If `skill:xiaoma-check-implementation-readiness` exists (verified non-blocking in step-01), invoke the `xiaoma-check-implementation-readiness` skill to perform a cross-document alignment audit:
+
+- **Inputs:** `{planning_artifacts}/prd.md`, `{planning_artifacts}/epics.md`, `{planning_artifacts}/architecture.md`, `{planning_artifacts}/current-architecture-analysis.md`
+- **CRITICAL PIPELINE MODE INSTRUCTIONS:** This is running in automated pipeline mode — do NOT pause for user input. When any step presents a menu, automatically select **C (Continue)** to proceed.
+- **Output:** Capture the readiness verdict (READY / GAPS / BLOCKED) and any flagged gaps. Record this verdict for the completion report.
+- **If verdict is BLOCKED:** Set `{readiness_status}` = "blocked" and add the blockers to the `warnings` array (section 4). Do NOT halt the pipeline — readiness check is advisory; the human reviewer decides whether to proceed.
+  - For each blocker reported by the readiness check, append to `{run_warnings}`: `[step-08] Implementation-readiness BLOCKED: {blocker_description}` (see workflow.md "Warning Prefix-Tag Convention")
+- **If verdict is GAPS:** Set `{readiness_status}` = "gaps"; proceed.
+  - For each gap reported, append to `{run_warnings}`: `[step-08] Implementation-readiness GAPS: {gap_description}`
+- **If verdict is READY:** Set `{readiness_status}` = "ready"; proceed (no append needed).
+- **If the skill is not installed:** Set `{readiness_status}` = "not_checked" and continue.
+  - This branch was already flagged at step-01 (see workflow.md prefix-tag dictionary `[step-01]` row); do NOT double-append here.
+
+### 3. Generate Completion Report
+
+Set `{steps_completed}` = 8 and `{pipeline_status}` = "complete" now, before printing, so the report reflects the final accurate values.
+
+**Output:**
+
+```
+═══════════════════════════════════════════════════
+  Auto Requirements Pipeline — COMPLETE
+═══════════════════════════════════════════════════
+
+Project: {project_name}
+Date: {date}
+Steps Completed: {steps_completed}/8
+
+📄 Output Artifacts:
+  ✅/❌ {planning_artifacts}/requirements-analysis.md
+  ✅/❌ {planning_artifacts}/current-architecture-analysis.md
+  ✅/❌ {planning_artifacts}/prd.md
+  ✅/❌ {planning_artifacts}/epics.md
+  ✅/❌ {planning_artifacts}/architecture.md
+
+Pipeline Status: {pipeline_status}
+Implementation Readiness: {readiness_status}
+
+═══════════════════════════════════════════════════
+```
+
+### 4. Generate Machine-Readable Status File
+
+Write machine-readable status to: `{planning_artifacts}/pipeline-status.json`
+
+**Warnings serialization (consumer of `{run_warnings}`)**: Read the `{run_warnings}` accumulator as built up by step-01 through step-07 plus this step's section 1, section 2.4, and section 2.5 appends. Write the list **as-is** into the JSON `warnings[]` field below — do not strip prefix tags, do not reorder, do not de-duplicate. Empty list serializes as `[]`. The auto-full-pipeline's `step-05-finalize` later wraps each entry with `[phase-1]` when aggregating into `full-pipeline-status.json`, so the original `[step-NN]` tag must be preserved here. See workflow.md "Warning Prefix-Tag Convention" for the canonical prefix dictionary.
+
+*(Historical note: prior versions of this step said "collect all halts and warnings recorded during the pipeline run" but did not specify a concrete accumulator. The L-series refit introduces `{run_warnings}` as the single source of truth, mirroring the I-series convention in auto-story-pipeline. Steps 01–07 are the producers; this step is the sole consumer for the success path. Hard-HALT paths (e.g., a delegated workflow missing in step-01, PRD validation exceeded max iterations in step-05) MAY append a `[step-NN]` entry before halting, per workflow.md Rules item 5, but those entries are not consumed because this step never executes when an earlier hard HALT fires.)*
+
+```json
+{
+  "pipeline": "auto-requirements-pipeline",
+  "date": "{date}",
+  "project": "{project_name}",
+  "status": "complete",
+  "readiness_status": "{readiness_status}",
+  "steps_completed": 8,
+  "artifacts": {
+    "requirements_analysis": "{planning_artifacts}/requirements-analysis.md",
+    "architecture_analysis": "{planning_artifacts}/current-architecture-analysis.md",
+    "prd": "{planning_artifacts}/prd.md",
+    "epics": "{planning_artifacts}/epics.md",
+    "architecture": "{planning_artifacts}/architecture.md"
+  },
+  "iterations": {
+    "analysis": {analysis_iteration},
+    "architecture": {architecture_iteration},
+    "validation": {validation_iteration}
+  },
+  "warnings": {run_warnings}
+}
+```
+
+The `warnings` field is the full `{run_warnings}` list rendered as a JSON array of strings (i.e., expand `{run_warnings}` in-place as a JSON array — do NOT wrap the placeholder in quotes). If no warnings were captured, the list is empty and the field serializes as `[]`. Example concrete value (success path with three prefix-tagged warnings):
+
+```json
+"warnings": [
+  "[step-01] No src/ directory found at project root — architecture analysis (step-03) may produce a sparse current-architecture-analysis.md",
+  "[step-02] Requirements-analysis quality self-check exceeded max retries (3 iterations) — proceeding with remaining gaps documented under 'Known Limitations' in requirements-analysis.md",
+  "[step-08] Implementation-readiness GAPS: prd.md acceptance criterion AC-FR-3.2 has no matching epic story"
+]
+```
+
+This enables downstream tools (including the Auto Story Pipeline) to check pipeline status programmatically. The Auto Story Pipeline's step-01 section 1 ("Requirements Pipeline Status") reads the `status` field only — it surfaces a non-blocking WARNING and continues when `status != "complete"`, and never reads `readiness_status`. The `readiness_status` field is consumed separately by `auto-full-pipeline/step-05-finalize.md` (and `auto-full-pipeline/step-01-init-and-validate.md`) when this pipeline runs inside the full pipeline.
+
+### 5. Provide Next Steps
+
+**Output:**
+
+```
+🔜 Recommended Next Steps:
+
+1. Review generated artifacts in {planning_artifacts}/
+2. Run Sprint Planning (SP) to organize stories into sprints
+3. Run Auto Story Pipeline to begin implementation
+
+Available commands:
+  - SP (Sprint Planning) — Organize epics/stories into sprints
+  - ASP (Auto Story Pipeline) — Automated story development lifecycle
+```
+
+### 6. Pipeline Complete
+
+**Pipeline execution is COMPLETE. HALT.**
+
+---
+
+## SUCCESS METRICS
+
+- All 5 output artifacts verified
+- Machine-readable `pipeline-status.json` generated
+- Completion report generated
+- Next steps provided
+- Pipeline status set to "complete"
+- `{run_warnings}` serialized as-is into `pipeline-status.json.warnings[]` with `[step-NN]` prefix tags preserved (empty list `[]` is valid); the field is downstream-aggregator-ready for `auto-full-pipeline`'s `[phase-1]` wrap
+
+## FAILURE MODES
+
+- Missing critical artifacts (PRD, Epics)
+- Not providing completion report
+- Not suggesting next steps
+- Silently dropping `{run_warnings}` (writing `warnings: []` when the accumulator had entries) — would defeat the L-series prefix-tag plumbing and disrupt the downstream `[phase-1]` aggregation in `auto-full-pipeline/step-05-finalize`
+- Stripping prefix tags from individual warning strings — downstream consumers pattern-match on `[step-NN]` and `[phase-1]` prefixes, so removing them breaks the aggregation contract

package/src/xmc-skills/1-analysis/xiaoma-auto-requirements-pipeline/workflow.md

@@ -0,0 +1,140 @@
+---
+name: auto-requirements-pipeline
+description: "Automated end-to-end requirements analysis pipeline: requirements analysis → architecture analysis → PRD creation → PRD validation → epic+story creation → architecture design → finalize. Use when the user says 'auto requirements', 'run requirements pipeline', or 'AR'"
+---
+
+# Auto Requirements Pipeline Workflow
+
+**Goal:** Execute the complete automated requirements analysis lifecycle — from requirements document (req.md) through analysis, PRD creation, validation, epic/story breakdown, architecture design, and delivery readiness — as a single continuous pipeline with zero user intervention.
+
+**Your Role:** Pipeline Orchestrator. You switch expert roles at each phase:
+
+- **Analyst (xiaofen)** — Requirements analysis and deep research
+- **Architect (xiaojia)** — Architecture analysis and design
+- **PM (xiaochan)** — PRD creation, validation, and epic/story breakdown
+
+- 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
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for focused execution across a long-running pipeline:
+
+- Each step loads fresh to prevent context loss in long sessions
+- State persists via variables passed between steps
+- Sequential progression through pipeline phases with conditional branching
+- Role switching at each phase boundary
+
+### State Variables
+
+- `{req_file_path}` — Path to the requirements document (default: `{planning_artifacts}/req.md`)
+- `{pipeline_status}` — Current pipeline phase for tracking
+- `{steps_completed}` — Count of steps completed in this pipeline run
+- `{validation_iteration}` — PRD validation loop counter (used in step-05, max 3)
+- `{max_validation_iterations}` — PRD validation retry limit (set in step-05, default 3; higher than analysis/architecture limits because PRD validation delegates to the full 14-step validate-prd workflow)
+- `{analysis_iteration}` — Requirements analysis quality-retry counter (used in step-02, max 2 retries)
+- `{architecture_iteration}` — Architecture analysis quality-retry counter (used in step-03, max 2 retries)
+- `{readiness_status}` — Implementation-readiness verdict produced by step-08 section 2.5 (advisory). One of: `ready`, `gaps`, `blocked`, `not_checked`. Serialized into `pipeline-status.json.readiness_status` by step-08 section 4.
+- `{run_warnings}` — Ordered list of prefix-tagged warning strings accumulated across the run (initialized to `[]` in step-01 section 4). Each emitting step (step-01, step-02, step-03, step-05, step-06, step-07, plus step-08's own readiness/validation gates — step-04 create-prd is a pure-delegate orchestrator with no emitter; see prefix-tag table and cross-pipeline style note below) appends to this list using the canonical prefix tags defined in the "Warning Prefix-Tag Convention" section below. Serialized into `pipeline-status.json.warnings[]` by step-08 section 4. Empty list `[]` is a valid value.
+
+### Warning Prefix-Tag Convention
+
+All warnings emitted during a pipeline run are tagged with a `[step-NN]` prefix so downstream consumers (the auto-story-pipeline step-01 status reader, `auto-full-pipeline/step-05-finalize`'s `[phase-1]` aggregation, dashboards, CI integrations) can filter and aggregate them uniformly. This convention is the **single source of truth** for the auto-requirements-pipeline — `auto-full-pipeline/step-05-finalize.md` (`[phase-1]` aggregation) and the auto-story-pipeline's gating read of `pipeline-status.json` both reference this table.
+
+| Prefix tag | Emitting step | Trigger examples |
+|---|---|---|
+| `[step-01]` | step-01 init-and-validate | `src/` directory missing (limited architecture analysis); optional `xiaoma-check-implementation-readiness` workflow not installed (readiness gate will be skipped in step-08) |
+| `[step-02]` | step-02 requirements-analysis | Quality self-check exceeded `{analysis_iteration}` > 2; proceeded with remaining gaps logged under "Known Limitations" in `requirements-analysis.md` |
+| `[step-03]` | step-03 architecture-analysis | Quality self-check exceeded `{architecture_iteration}` > 2; proceeded with remaining gaps logged under "Key Observations and Constraints" in `current-architecture-analysis.md` |
+| `[step-05]` | step-05 validate-prd | Validation iteration N failed but max not yet reached (advisory only — terminal HALT at iteration > 3 is a hard stop); escalation A/B/C/D dispatched after 3 iterations |
+| `[step-06]` | step-06 create-epics | Epic coverage incomplete relative to PRD features (advisory — step continues after best-effort completion); epic(s) with zero stories (advisory — Phase 3 will skip those epics); story/stories missing acceptance criteria (advisory — downstream auto-story-pipeline step-03 validation will likely flag these) |
+| `[step-07]` | step-07 create-architecture | Architecture missing coverage for one or more epics (advisory — step continues after best-effort completion); stale `architecture.md` found and overwritten |
+| `[step-08]` | step-08 finalize | Missing non-critical artifact; readiness verdict `BLOCKED` or `GAPS` (the "readiness skill not installed → verdict downgraded to `not_checked`" branch is owned by `[step-01]` above and is intentionally NOT re-emitted here — see step-08 section 2.5 "If the skill is not installed" branch for the `do NOT double-append here` directive); traceability orphan detected (requirement/PRD-feature/epic/story with no downstream coverage — see step-08 section 2.4); traceability verification skipped due to missing identifier conventions in source documents |
+
+**Rules:**
+
+1. Each warning string starts with exactly one prefix tag enclosed in square brackets, followed by a single space, followed by a short human-readable description.
+2. Warnings are append-only within a run — no step retracts a warning emitted by an earlier step.
+3. step-08 section 4 writes the full list as-is into `pipeline-status.json.warnings[]`; `auto-full-pipeline/step-05-finalize` later wraps each entry with `[phase-1]` when aggregating into `full-pipeline-status.json` (no double-prefixing — the wrap is added, the original tag preserved).
+4. Free-form WARNING output to the user terminal is unchanged; the prefix tag is added when the warning is **also** appended to `{run_warnings}`. Steps may emit user-visible WARNINGs without appending to `{run_warnings}` for purely conversational hints.
+5. Hard HALTs (e.g., missing delegated workflow in step-01; PRD validation exceeded `{max_validation_iterations}` in step-05) MAY append a `[step-NN]` entry BEFORE halting so that any future partial-status snapshot writer can capture the cause; in the current pipeline these append entries are not consumed because step-08 never executes when a hard HALT fires earlier, but the appends remain for forward compatibility (mirrors the auto-story-pipeline convention).
+
+**Cross-pipeline style note:** The `[step-NN]` tags above are **emitting-step** tags (axis: *which step produced the warning*). The sibling pipeline `auto-prd-to-stories` (`5-full-pipeline/auto-prd-to-stories/steps/step-05-finalize.md` §7) uses **semantic-category** tags instead (`[fr-coverage]` / `[tier-c]` / `[self-reported]` / `[fr-coverage-map]` / `[checklist]` / `[bridge-failure]` / `[warnings-truncated]`) — axis: *what kind of issue is reported*. Both styles are sanctioned; the choice is driven by pipeline shape. auto-requirements-pipeline has 7 distinct emitting steps (step-04 create-prd is a pure-delegate orchestrator with no emitter — see the prefix-tag table above which lists rows for step-01/02/03/05/06/07/08 only) so emitting-step tags carry useful filtering signal; auto-prd-to-stories has effectively 2 emitting steps so semantic tags carry more signal. A future dashboard layer that aggregates across all pipelines should treat both vocabularies as first-class and document the mapping at the dashboard side, not require either pipeline to switch styles. Mirrors the same note in `auto-story-pipeline/workflow.md`.
+
+### Output Artifacts
+
+All outputs are written to `{planning_artifacts}/`:
+
+- `requirements-analysis.md` — Deep requirements analysis report
+- `current-architecture-analysis.md` — Existing codebase architecture analysis
+- `prd.md` — Product Requirements Document
+- `epics.md` — Epic and story breakdown
+- `architecture.md` — Technical architecture design
+- `pipeline-status.json` — Machine-readable pipeline completion status
+
+### Step Ordering Rationale
+
+The pipeline orders steps as: requirements analysis → existing-architecture analysis → PRD → validate PRD → epics & stories → new architecture → finalize.
+
+**Why epics (step-06) come before new architecture (step-07):** Epics and stories provide concrete feature decomposition that informs architectural decisions (e.g., service boundaries, data flow, transactional units). The architecture in step-07 is the *solution* design and benefits from knowing the full set of stories it must support. The *existing* architecture analysis in step-03 is intentionally placed before PRD creation so that PRD constraints reflect what is already in place.
+
+If your project is genuinely greenfield with no existing code, step-03's output will be sparse — that is expected and acceptable; step-07 will design from scratch using the PRD and epics.
+
+### Architecture Document Types (Important Distinction)
+
+This pipeline produces TWO different architecture documents:
+
+1. **current-architecture-analysis.md** (Step 3 output)
+   - Analysis of the EXISTING codebase
+   - Generated by Architect (xiaojia) analyzing current system patterns
+   - Used as context for designing new features that integrate cleanly
+   - Describes what IS
+
+2. **architecture.md** (Step 7 output)
+   - Technical design for NEW features/requirements
+   - Generated by Architect (xiaojia) designing the solution
+   - References current architecture analysis as context
+   - Describes what SHOULD BE
+
+When step-07 runs, it may find a stale `architecture.md` from a prior pipeline run — in that case, the step explicitly overwrites it (see step-07 section 4).
+
+---
+
+## 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
+
+- `validation` = `{skill-root}/checklist.md`
+
+### Related Workflows
+
+These existing workflows contain the detailed logic that pipeline steps delegate to:
+
+- `create_prd_workflow` = `skill:xiaoma-prd` *(invoked with **create** intent — `xiaoma-prd` is the consolidated PRD skill: create / update / validate)*
+- `validate_prd_workflow` = `skill:xiaoma-prd` *(invoked with **validate** intent — same skill, validate mode)*
+- `create_epics_workflow` = `skill:xiaoma-create-epics-and-stories`
+- `create_architecture_workflow` = `skill:xiaoma-create-architecture`
+
+### 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/1-analysis/xiaoma-auto-requirements-pipeline/xiaoma-skill-manifest.yaml

@@ -0,0 +1,24 @@
+canonicalId: xiaoma-auto-requirements-pipeline
+type: workflow
+description: "Automated end-to-end requirements analysis pipeline: requirements analysis → architecture analysis → PRD creation → PRD validation → epic+story creation → architecture design → finalize. Use when the user says 'auto requirements', 'run requirements pipeline', or 'AR'"
+# Additional metadata (advisory, non-normative — used by discovery tooling and downstream registries)
+agents:
+  - analyst # xiaofen — owns step-02 (requirements analysis)
+  - architect # xiaojia — owns step-03 (current architecture) and step-07 (new architecture)
+  - pm # xiaochan — owns step-04 (PRD), step-05 (validate), step-06 (epics & stories)
+phase: 1-analysis
+step_count: 8
+prerequisites:
+  - "{planning_artifacts}/req.md exists (user-authored requirements document)"
+  - "_xiaoma/xmc/config.yaml present (XiaoMa installation)"
+  - "Delegated workflows installed: xiaoma-prd (create + validate intents), xiaoma-create-epics-and-stories, xiaoma-create-architecture"
+outputs:
+  - "{planning_artifacts}/requirements-analysis.md"
+  - "{planning_artifacts}/current-architecture-analysis.md"
+  - "{planning_artifacts}/prd.md"
+  - "{planning_artifacts}/epics.md"
+  - "{planning_artifacts}/architecture.md"
+  - "{planning_artifacts}/pipeline-status.json"
+downstream:
+  - xiaoma-auto-story-pipeline # Reads pipeline-status.json + epics.md to drive implementation
+  - xiaoma-sprint-planning # Organizes generated stories into sprints

package/src/xmc-skills/1-analysis/xiaoma-document-project/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: xiaoma-document-project
+description: 'Document brownfield projects for AI context. Use when the user says "document this project" or "generate project docs"'
+---
+
+# Document Project Workflow
+
+**Goal:** Document brownfield projects for AI context.
+
+**Your Role:** Project documentation specialist.
+
+## Conventions
+
+- Bare paths (e.g. `instructions.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 Workflow Block
+
+Run: `node {project-root}/_xiaoma/scripts/resolve_customization.js --skill {skill-root} --key workflow`
+
+**If the script fails**, resolve the `workflow` 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 `{workflow.activation_steps_prepend}` in order before proceeding.
+
+### Step 3: Load Persistent Facts
+
+Treat every entry in `{workflow.persistent_facts}` as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim.
+
+### Step 4: 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 5: Greet the User
+
+Greet `{user_name}` (if you have not already), speaking in `{communication_language}`.
+
+### Step 6: Execute Append Steps
+
+Execute each entry in `{workflow.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.
+
+## Execution
+
+Read fully and follow: `./instructions.md`

package/src/xmc-skills/1-analysis/xiaoma-document-project/customize.toml

@@ -0,0 +1,41 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for xiaoma-document-project. Mirrors the
+# agent customization shape under the [workflow] namespace.
+
+[workflow]
+
+# --- Configurable below. Overrides merge per XiaoMa structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+# Steps to run before the standard activation (config load, greet).
+# Overrides append. Use for pre-flight loads, compliance checks, etc.
+
+activation_steps_prepend = []
+
+# Steps to run after greet but before the workflow begins.
+# Overrides append. Use for context-heavy setup that should happen
+# once the user has been acknowledged.
+
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run
+# (standards, compliance constraints, stylistic guardrails).
+# Distinct from the runtime memory sidecar — these are static context
+# loaded on activation. Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "All briefs must include a regulatory-risk section."
+#   - 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",
+]
+
+# Scalar: executed when the workflow reaches its terminal stage, after
+# the main output has been delivered. Override wins. Leave empty for
+# no custom post-completion behavior.
+
+on_complete = ""

package/src/{xmc/workflows → xmc-skills/1-analysis}/xiaoma-document-project/workflows/deep-dive-instructions.md

@@ -291,6 +291,7 @@ These comprehensive docs are now ready for:
 
 Thank you for using the document-project workflow!
 </action>
+<action>Run: `node {project-root}/_xiaoma/scripts/resolve_customization.js --skill {skill-root} --key workflow.on_complete` — if the resolved value is non-empty, follow it as the final terminal instruction before exiting.</action>
 <action>Exit workflow</action>
 </action>
 </step>

package/src/{xmc/workflows → xmc-skills/1-analysis}/xiaoma-document-project/workflows/full-scan-instructions.md

@@ -1103,5 +1103,6 @@ When ready to plan new features, run the PRD workflow and provide this index as
   </action>
 
 <action>Display: "State file saved: {{project_knowledge}}/project-scan-report.json"</action>
+<action>Run: `node {project-root}/_xiaoma/scripts/resolve_customization.js --skill {skill-root} --key workflow.on_complete` — if the resolved value is non-empty, follow it as the final terminal instruction before exiting.</action>
 
 </workflow>