@zeyue0329/xiaoma-cli 1.0.49 → 1.0.66

package/src/xmc/workflows/4-implementation/auto-story-pipeline/workflow.md

@@ -0,0 +1,89 @@
+---
+name: auto-story-pipeline
+description: "Automated end-to-end story development pipeline (single story): create → validate → develop → review → test → fix → done. Use when the user says 'run auto pipeline', 'automate story development', or 'auto story pipeline'. For batch processing of all stories, use xiaoma-auto-story-pipeline-batch (ASPB) instead."
+---
+
+# Auto Story Pipeline Workflow
+
+**Goal:** Execute the complete automated story development lifecycle for a **single story** — from story creation through validation, development, code review, testing, bug fixing, and final delivery — as a single continuous pipeline.
+
+**Your Role:** Pipeline Orchestrator. You switch expert roles at each phase:
+- **SM (xiaomin)** — Story creation and sprint coordination
+- **PM (xiaochan)** — Story validation and quality gate
+- **Dev (xiaokai)** — Code implementation and bug fixing
+- **Reviewer** — Adversarial code review
+- **QA (xiaoce)** — Functional testing with real data
+
+- 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
+
+> **Note:** This workflow processes a **single story** (or resumes a specific story). For batch processing of all backlog stories, use the **Auto Story Pipeline Batch** skill (`ASPB` or `/xiaoma-auto-story-pipeline-batch`), which uses Agent subprocess isolation for each story.
+
+---
+
+## 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
+
+- `{pipeline_mode}` — "single" (process next backlog story) or "resume" (resume a specific story by key)
+- `{current_story_key}` — Key of story being processed (e.g., "1-2-user-auth")
+- `{current_story_path}` — Full path to current story file (derived in step-01 after resolving `{current_story_key}`). Whenever re-reading the story file in subsequent steps (e.g., step-08 final validation, step-03 re-checks), always perform a FRESH read directly from disk using this path variable. Do NOT rely on cached/stale in-memory state from earlier steps, as intermediate steps (step-04, step-05, step-06, step-07) may have modified the file
+- `{fix_iteration}` — Bug fix loop counter (max controlled by `{max_fix_iterations}`, default 5)
+- `{max_fix_iterations}` — Maximum fix-and-retest cycles per story (configurable via `max_fix_iterations` in config.yaml; default 5 if not set)
+- `{fix_source}` — Origin of failures being fixed in step-07: "code-review" (step-05 routed here with unresolvable issues), "qa-testing" (step-06 routed here with test failures), or "mixed" (both code review and QA issues); set in step-07 section 2; determines post-fix routing (code-review/mixed → inline targeted re-check before step-08; qa-testing → step-08 directly)
+- `{pipeline_status}` — Current pipeline phase for tracking
+- `{validation_attempt}` — Story validation attempt counter (used in step-03, max 3; re-initialized at start of step-03)
+- `{steps_completed}` — Count of pipeline step files executed in this run (initialized to 0 in step-01)
+
+### Status Machine
+
+Stories progress through these states:
+- `backlog` → `ready-for-dev` → `in-progress` → `review` → `done`
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
+
+- `project_name`, `user_name`
+- `communication_language`, `document_output_language`
+- `user_skill_level`
+- `planning_artifacts`, `implementation_artifacts`
+- `date` as system-generated current datetime
+
+### Paths
+
+- `installed_path` = `{project-root}/_xiaoma/xmc/workflows/4-implementation/auto-story-pipeline`
+- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
+- `validation` = `{installed_path}/checklist.md`
+
+### Related Workflows
+
+These existing workflows contain the detailed logic that pipeline steps delegate to:
+
+- `create_story_workflow` = `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-create-story/workflow.md`
+- `dev_story_workflow` = `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-dev-story/workflow.md`
+- `code_review_workflow` = `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-code-review/workflow.md`
+- `qa_test_workflow` = `{project-root}/_xiaoma/xmc/workflows/xiaoma-qa-generate-e2e-tests/workflow.md`
+
+### Context
+
+- `project_context` = `**/project-context.md` (load if exists)
+
+---
+
+## EXECUTION
+
+Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-01-init-and-validate.md` to begin the pipeline.

package/src/xmc/workflows/4-implementation/auto-story-pipeline/xiaoma-skill-manifest.yaml

@@ -0,0 +1,3 @@
+canonicalId: xiaoma-auto-story-pipeline
+type: workflow
+description: "Automated end-to-end story development pipeline (single story). Use when the user says 'run auto pipeline', 'automate story development', or 'auto story pipeline'. For batch processing, use xiaoma-auto-story-pipeline-batch (ASPB)."

package/src/xmc/workflows/4-implementation/auto-story-pipeline-batch/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: auto-story-pipeline-batch
+description: "Batch automated story development pipeline with Agent subprocess isolation. Processes ALL backlog stories sequentially, each in an independent Agent context. Use when the user says 'batch story pipeline', 'ASB', 'auto story batch', or 'batch auto pipeline'"
+---
+
+Follow the instructions in [workflow.md](workflow.md).

package/src/xmc/workflows/4-implementation/auto-story-pipeline-batch/workflow.md

@@ -0,0 +1,333 @@
+---
+name: auto-story-pipeline-batch
+description: "Batch automated story development pipeline with Agent subprocess isolation. Each story is processed in an independent Agent context to prevent context bloat. Use when the user says 'batch story pipeline', 'ASPB', 'auto story batch', or 'batch auto pipeline'"
+---
+
+# Auto Story Pipeline — Batch Mode (Agent Subprocess Isolation)
+
+**Goal:** Execute the complete automated story development lifecycle for ALL backlog stories — processing each story in an **independent Agent subprocess** to prevent context bloat and ensure isolation. Fully automatic from start to finish, zero human intervention until the queue is empty.
+
+**Your Role:** Pipeline Batch Scheduler. You coordinate the batch loop, delegating each story's full lifecycle (create → validate → develop → review → test → fix → done) to independent Agent subprocesses. You stay lightweight — query queue, launch Agent, read results, continue or finalize.
+
+- Communicate all responses in {communication_language} and generate all documents in {document_output_language}
+- Absolutely DO NOT stop because of "milestones", "significant progress", or "session boundaries". Continue in a single execution until ALL stories are processed or a HALT condition is triggered
+- **Fully automatic, no human intervention** — From start to finish, user needs no commands
+
+---
+
+## Core Architecture: Agent-Isolated Processing
+
+**Why this architecture:** Each story is delegated to an **independent Agent subprocess**. Agents naturally have isolated context spaces, releasing upon completion without polluting the main conversation. The main conversation only handles lightweight scheduling loops.
+
+```
+Main conversation (scheduler, minimal context)
+  ├── Agent #1 → Process Story A (isolated context, released after completion)
+  ├── Agent #2 → Process Story B (isolated context, released after completion)
+  ├── Agent #3 → Process Story C (isolated context, released after completion)
+  └── ...until queue is empty
+```
+
+### Core Rules (Strictly Follow)
+
+1. **Each story processed by independent Agent** — Use Agent tool to launch general-purpose subprocess, pass complete story info and processing instructions to Agent, Agent independently completes the full story lifecycle (step-02 through step-08)
+2. **Main loop stays lightweight** — Main conversation only: query sprint-status → launch Agent → read Agent results → query remaining → continue or end
+3. **Serial processing** — Process one story at a time, wait for Agent completion before next, avoid concurrent modification conflicts
+4. **Fully automatic, no human intervention** — From start to finish, user needs no commands
+
+---
+
+## 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`
+- `max_fix_iterations` (default: 5 if not set)
+- `date` as system-generated current datetime
+
+### Paths
+
+- `story_pipeline_path` = `{project-root}/_xiaoma/xmc/workflows/4-implementation/auto-story-pipeline`
+- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
+- `validation_checklist` = `{story_pipeline_path}/checklist.md`
+
+### Related Workflows (Passed to Agent)
+
+These paths will be passed to each Agent subprocess so it can delegate to existing workflow logic:
+
+- `create_story_workflow` = `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-create-story/workflow.md`
+- `dev_story_workflow` = `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-dev-story/workflow.md`
+- `code_review_workflow` = `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-code-review/workflow.md`
+- `qa_test_workflow` = `{project-root}/_xiaoma/xmc/workflows/xiaoma-qa-generate-e2e-tests/workflow.md`
+
+### Context
+
+- `project_context` = `**/project-context.md` (load if exists)
+
+---
+
+## WORKFLOW
+
+<workflow>
+
+<step n="1" goal="Validate environment, analyze sprint status, and display overview">
+
+### 1.1 Validate Prerequisites
+
+Check that the following required artifacts exist:
+
+1. **Epics File** — `{planning_artifacts}/*epic*.md` must exist
+   - If missing: HALT — "No epics file found. Run the planning workflow first to create epics."
+
+2. **Sprint Status File** — `{sprint_status}` must exist
+   - If missing:
+     a. Output INFO — "sprint-status.yaml not found. Auto-generating via Sprint Planning..."
+     b. Read and follow the sprint-planning workflow: `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-sprint-planning/workflow.md`
+     c. After sprint-planning completes, verify `{sprint_status}` now exists
+     d. If still missing: HALT — "Failed to auto-generate sprint-status.yaml. Run Sprint Planning (SP) manually."
+
+3. **Planning Artifacts** — At least one of `{planning_artifacts}/*prd*.md` or `{planning_artifacts}/*architecture*.md` should exist
+   - If missing: Output warning but continue — "Planning documents not found. Story creation may have limited context."
+
+### 1.2 Analyze Sprint Status
+
+1. Load the FULL file: `{sprint_status}`
+2. Read ALL lines from beginning to end — do not skip any content
+3. Parse the `development_status` section completely
+4. Count stories by status:
+   - `backlog_count` — Stories with status "backlog"
+   - `ready_count` — Stories with status "ready-for-dev"
+   - `in_progress_count` — Stories with status "in-progress"
+   - `review_count` — Stories with status "review"
+   - `done_count` — Stories with status "done"
+5. If `backlog_count` == 0 AND `ready_count` == 0:
+   - HALT — "No backlog or ready-for-dev stories found. All stories are either in-progress, in review, or done."
+
+### 1.3 Display Overview and Begin
+
+**Output:**
+
+```
+===============================================
+  Auto Story Pipeline — Batch Mode
+  (Agent Subprocess Isolation)
+===============================================
+
+Sprint Status Summary:
+- Backlog: {backlog_count} stories
+- Ready for Dev: {ready_count} stories
+- In Progress: {in_progress_count} stories
+- Review: {review_count} stories
+- Done: {done_count} stories
+
+Processing all {backlog_count + ready_count} pending stories sequentially.
+Each story will be processed in an independent Agent subprocess.
+
+Starting fully automatic batch processing...
+-----------------------------------------------
+```
+
+Initialize tracking variables:
+- `stories_completed` = 0
+- `stories_failed` = 0
+- `failed_story_keys` = [] (empty list — tracks story keys that failed, to avoid infinite loops)
+- `story_results` = [] (empty list — accumulates result summaries for the final report)
+
+Enter Step 2 to start the batch loop.
+
+</step>
+
+<step n="2" goal="Loop: process each story in an independent Agent subprocess (fully automatic)">
+
+<!-- Loop start: find the next processable story -->
+
+### 2.1 Find Next Processable Story
+
+1. Load the FULL file: `{sprint_status}` (always fresh read from disk)
+2. Read ALL lines from beginning to end
+3. Parse the `development_status` section completely
+4. Find the FIRST story (reading top to bottom) where:
+   - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
+   - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
+   - Key is NOT in the `failed_story_keys` list (skip previously failed stories to avoid infinite loops)
+   - Status value equals "backlog"
+5. If no "backlog" story found, search again for the FIRST story with status "ready-for-dev" (also skipping `failed_story_keys`)
+6. If no processable story found: queue is empty, go to Step 3
+
+### 2.2 Output Progress
+
+```
+Processing story: {current_story_key} (status: {current_story_status})
+Stories completed so far: {stories_completed}
+```
+
+### 2.3 Launch Independent Agent Subprocess
+
+<critical>
+
+Use the Agent tool to launch a **general-purpose subprocess** to process this story.
+
+The Agent's prompt MUST contain the following complete information for independent work:
+
+**1. Story Information:**
+- Story key: `{current_story_key}`
+- Current status: `{current_story_status}` (backlog or ready-for-dev)
+- Story file path: `{implementation_artifacts}/{current_story_key}.md`
+
+**2. Configuration (inline all resolved values):**
+- project_name: `{project_name}`
+- user_name: `{user_name}`
+- communication_language: `{communication_language}`
+- document_output_language: `{document_output_language}`
+- user_skill_level: `{user_skill_level}`
+- planning_artifacts: `{planning_artifacts}`
+- implementation_artifacts: `{implementation_artifacts}`
+- sprint_status: `{sprint_status}`
+- max_fix_iterations: `{max_fix_iterations}`
+- date: current datetime
+
+**3. Workflow Paths (for delegation):**
+- create_story_workflow: `{create_story_workflow}`
+- dev_story_workflow: `{dev_story_workflow}`
+- code_review_workflow: `{code_review_workflow}`
+- qa_test_workflow: `{qa_test_workflow}`
+- validation_checklist: `{validation_checklist}`
+
+**4. Project Context:**
+- Include the content of project-context.md if it exists (pass the actual content, not just the path)
+
+**5. Processing Instructions:**
+
+Tell the Agent to execute the following steps sequentially for the story. The Agent should read and follow each step file from the story pipeline:
+
+a. **IF story status is "backlog":** Read and follow `{story_pipeline_path}/steps/step-02-create-story.md` — Create the user story file
+b. Read and follow `{story_pipeline_path}/steps/step-03-validate-story.md` — PM validation (quality gate, max 3 attempts)
+c. Read and follow `{story_pipeline_path}/steps/step-04-develop-story.md` — Development implementation (TDD)
+d. Read and follow `{story_pipeline_path}/steps/step-05-code-review.md` — Adversarial code review (auto-fix HIGH/MEDIUM issues)
+e. Read and follow `{story_pipeline_path}/steps/step-06-test-story.md` — QA functional testing (real data, no mocks)
+f. Read and follow `{story_pipeline_path}/steps/step-07-fix-and-retest.md` — Fix-and-retest loop if needed (max {max_fix_iterations} iterations)
+g. Read and follow `{story_pipeline_path}/steps/step-08-complete-story.md` — Mark story done, update sprint-status.yaml
+
+**Important instructions for the Agent:**
+- Execute ALL steps in exact order; do NOT skip steps
+- If story status is "ready-for-dev", skip step-02 (creation) and start at step-03 (validation)
+- **CRITICAL: After completing step-08, STOP immediately. Do NOT continue to step-09-finalize.md.** Step-08's "NEXT STEP" section points to step-09, but you must ignore that instruction. Step-09 is for single-story mode finalization only. In batch mode, the main scheduler handles finalization. After step-08 completes, return the STORY_RESULT summary below and exit.
+- Do NOT stop because of "milestones" or "significant progress" — continue until the story is DONE (step-08 completed) or a HALT condition is triggered
+- Each step file loads fresh to combat context degradation — read each step file fully before executing
+- When reading the story file in later steps, always perform a FRESH read from disk (the file may have been modified by earlier steps)
+- Initialize `fix_iteration` = 0 and `validation_attempt` = 0 at the start
+
+**6. Return Format:**
+When done, return a structured summary:
+```
+STORY_RESULT:
+- story_key: {story_key}
+- final_status: done | halted | failed
+- fix_iterations_used: {count}
+- validation_attempts: {count}
+- files_modified: [list of files]
+- summary: {one-line description of what was done}
+- error: {error message if halted/failed, empty otherwise}
+```
+
+</critical>
+
+### 2.4 Read Agent Result and Handle Errors
+
+Read the Agent's returned processing result summary.
+
+**IF the Agent succeeded (returned `final_status: done`):**
+- Increment `stories_completed` counter
+- Record the story result in `story_results` list
+
+**IF the Agent failed or halted (returned `final_status: failed` or `halted`, or produced no result / error):**
+- Increment `stories_failed` counter
+- Add the story key to `failed_story_keys` list (prevents re-selecting this story in the next loop iteration)
+- Record the failure result in `story_results` list (including error details)
+- **Do NOT halt the batch** — continue to the next story
+- Output: "Story {current_story_key} failed/halted. Skipping and continuing to next story."
+
+### 2.5 Output Progress
+
+1. Output brief one-line result for this story
+
+### 2.6 Refresh Sprint Status and Check Remaining
+
+1. Re-read `{sprint_status}` from disk (fresh read)
+2. Recount stories by status:
+   - Update `backlog_count`, `ready_count`, `in_progress_count`, `review_count`, `done_count`
+3. Output batch progress checkpoint:
+
+```
+===============================================
+  Batch Progress Checkpoint
+===============================================
+- Stories Completed So Far: {stories_completed}
+- Sprint Status (refreshed): Backlog {backlog_count} | Ready {ready_count} | In Progress {in_progress_count} | Review {review_count} | Done {done_count}
+- Pipeline Continuing...
+===============================================
+```
+
+4. If `backlog_count` > 0 OR `ready_count` > 0: Continue loop — return to Step 2.1
+5. If `backlog_count` == 0 AND `ready_count` == 0: Queue is empty, go to Step 3
+
+</step>
+
+<step n="3" goal="Output final batch processing report">
+
+### 3.1 Refresh Sprint Status
+
+1. Load the FULL file: `{sprint_status}` (final fresh read)
+2. Recount all stories by status
+
+### 3.2 Generate Final Report
+
+**Output:**
+
+```
+===============================================
+  Auto Story Pipeline (Batch) — COMPLETE
+===============================================
+
+Pipeline Summary:
+- Mode: Batch (Agent Subprocess Isolation)
+- Stories Completed: {stories_completed}
+- Pipeline Status: finalized
+
+Stories Processed:
+{for each completed story: key, final_status, fix_iterations_used, summary}
+
+Sprint Status (current):
+- Backlog: {backlog_count} remaining
+- Ready for Dev: {ready_count}
+- In Progress: {in_progress_count}
+- In Review: {review_count}
+- Done: {done_count}
+
+The automated batch story development pipeline has finished.
+===============================================
+```
+
+**IF `backlog_count` == 0 AND `ready_count` == 0 AND `in_progress_count` == 0 AND `review_count` == 0:**
+- Output: "All stories in the sprint are complete! Consider running epic-retrospective (ER) to review the work."
+
+**HALT** — Pipeline complete.
+
+</step>
+
+</workflow>
+
+---
+
+## Important Notes
+
+1. **Agent isolation is key** — Each story is processed in an independent Agent subprocess with isolated context. No `/clear` needed, no mutual interference between stories
+2. **Fully automatic** — User only calls once, then fully automatic until all stories are processed
+3. **Serial safety** — One story at a time, avoid concurrent modifications to the same codebase
+4. **Error tolerance** — If an Agent fails to process a story, the story status remains unchanged in sprint-status.yaml. The main loop records the failure and continues to the next story
+5. **Agent prompt quality** — The prompt passed to each Agent must include complete story info + all configuration paths + processing instructions + return format, enabling fully independent work
+6. **Reuses existing step files** — Agents read and follow the same step-02 through step-08 files from auto-story-pipeline, avoiding code duplication

package/src/xmc/workflows/4-implementation/auto-story-pipeline-batch/xiaoma-skill-manifest.yaml

@@ -0,0 +1,3 @@
+canonicalId: auto-story-pipeline-batch
+type: workflow
+description: "Batch automated story development pipeline with Agent subprocess isolation. Each story is processed in an independent Agent context to prevent context bloat. Use when the user says 'batch story pipeline', 'ASB', 'auto story batch', or 'batch auto pipeline'"

package/src/xmc/workflows/4-implementation/xiaoma-code-review/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: xiaoma-code-review
+description: 'Review code changes adversarially using parallel review layers (Blind Hunter, Edge Case Hunter, Acceptance Auditor) with structured triage into actionable categories. Use when the user says "run code review" or "review this code"'
+---
+
+Follow the instructions in ./workflow.md.

package/src/xmc/workflows/4-implementation/xiaoma-code-review/checklist.md

@@ -0,0 +1,23 @@
+# Senior Developer Review - Validation Checklist
+
+- [ ] Story file loaded from `{{story_path}}`
+- [ ] Story Status verified as reviewable (review)
+- [ ] Epic and Story IDs resolved ({{epic_num}}.{{story_num}})
+- [ ] Story Context located or warning recorded
+- [ ] Epic Tech Spec located or warning recorded
+- [ ] Architecture/standards docs loaded (as available)
+- [ ] Tech stack detected and documented
+- [ ] MCP doc search performed (or web fallback) and references captured
+- [ ] Acceptance Criteria cross-checked against implementation
+- [ ] File List reviewed and validated for completeness
+- [ ] Tests identified and mapped to ACs; gaps noted
+- [ ] Code quality review performed on changed files
+- [ ] Security review performed on changed files and dependencies
+- [ ] Outcome decided (Approve/Changes Requested/Blocked)
+- [ ] Review notes appended under "Senior Developer Review (AI)"
+- [ ] Change Log updated with review entry
+- [ ] Status updated according to settings (if enabled)
+- [ ] Sprint status synced (if sprint tracking enabled)
+- [ ] Story saved successfully
+
+_Reviewer: {{user_name}} on {{date}}_

package/src/xmc/workflows/4-implementation/xiaoma-code-review/discover-inputs.md

@@ -0,0 +1,88 @@
+# Discover Inputs Protocol
+
+**Objective:** Intelligently load project files (whole or sharded) based on the workflow's Input Files configuration.
+
+**Prerequisite:** Only execute this protocol if the workflow defines an Input Files section. If no input file patterns are configured, skip this entirely.
+
+---
+
+## Step 1: Parse Input File Patterns
+
+- Read the Input Files table from the workflow configuration.
+- For each input group (prd, architecture, epics, ux, etc.), note the **load strategy** if specified.
+
+## Step 2: Load Files Using Smart Strategies
+
+For each pattern in the Input Files table, work through the following substeps in order:
+
+### 2a: Try Sharded Documents First
+
+If a sharded pattern exists for this input, determine the load strategy (defaults to **FULL_LOAD** if not specified), then apply the matching strategy:
+
+#### FULL_LOAD Strategy
+
+Load ALL files in the sharded directory. Use this for PRD, Architecture, UX, brownfield docs, or whenever the full picture is needed.
+
+1. Use the glob pattern to find ALL `.md` files (e.g., `{planning_artifacts}/*architecture*/*.md`).
+2. Load EVERY matching file completely.
+3. Concatenate content in logical order: `index.md` first if it exists, then alphabetical.
+4. Store the combined result in a variable named `{pattern_name_content}` (e.g., `{architecture_content}`).
+
+#### SELECTIVE_LOAD Strategy
+
+Load a specific shard using a template variable. Example: used for epics with `{{epic_num}}`.
+
+1. Check for template variables in the sharded pattern (e.g., `{{epic_num}}`).
+2. If the variable is undefined, ask the user for the value OR infer it from context.
+3. Resolve the template to a specific file path.
+4. Load that specific file.
+5. Store in variable: `{pattern_name_content}`.
+
+#### INDEX_GUIDED Strategy
+
+Load index.md, analyze the structure and description of each doc in the index, then intelligently load relevant docs.
+
+**DO NOT BE LAZY** -- use best judgment to load documents that might have relevant information, even if there is only a 5% chance of relevance.
+
+1. Load `index.md` from the sharded directory.
+2. Parse the table of contents, links, and section headers.
+3. Analyze the workflow's purpose and objective.
+4. Identify which linked/referenced documents are likely relevant.
+   - *Example:* If the workflow is about authentication and the index shows "Auth Overview", "Payment Setup", "Deployment" -- load the auth docs, consider deployment docs, skip payment.
+5. Load all identified relevant documents.
+6. Store combined content in variable: `{pattern_name_content}`.
+
+**When in doubt, LOAD IT** -- context is valuable, and being thorough is better than missing critical info.
+
+---
+
+After applying the matching strategy, mark the pattern as **RESOLVED** and move to the next pattern.
+
+### 2b: Try Whole Document if No Sharded Found
+
+If no sharded matches were found OR no sharded pattern exists for this input:
+
+1. Attempt a glob match on the "whole" pattern (e.g., `{planning_artifacts}/*prd*.md`).
+2. If matches are found, load ALL matching files completely (no offset/limit).
+3. Store content in variable: `{pattern_name_content}` (e.g., `{prd_content}`).
+4. Mark pattern as **RESOLVED** and move to the next pattern.
+
+### 2c: Handle Not Found
+
+If no matches were found for either sharded or whole patterns:
+
+1. Set `{pattern_name_content}` to empty string.
+2. Note in session: "No {pattern_name} files found" -- this is not an error, just unavailable. Offer the user a chance to provide the file.
+
+## Step 3: Report Discovery Results
+
+List all loaded content variables with file counts. Example:
+
+```
+OK Loaded {prd_content} from 5 sharded files: prd/index.md, prd/requirements.md, ...
+OK Loaded {architecture_content} from 1 file: Architecture.md
+OK Loaded {epics_content} from selective load: epics/epic-3.md
+-- No ux_design files found
+```
+
+This gives the workflow transparency into what context is available.

package/src/xmc/workflows/4-implementation/xiaoma-code-review/steps/step-01-gather-context.md

@@ -0,0 +1,61 @@
+---
+diff_output: '' # set at runtime
+spec_file: '' # set at runtime (path or empty)
+review_mode: '' # set at runtime: "full" or "no-spec"
+---
+
+# Step 1: Gather Context
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- The prompt that triggered this workflow IS the intent — not a hint.
+- Do not modify any files. This step is read-only.
+
+## INSTRUCTIONS
+
+1. **Detect review intent from invocation text.** Check the triggering prompt for phrases that map to a review mode:
+   - "staged" / "staged changes" → Staged changes only
+   - "uncommitted" / "working tree" / "all changes" → Uncommitted changes (staged + unstaged)
+   - "branch diff" / "vs main" / "against main" / "compared to {branch}" → Branch diff (extract base branch if mentioned)
+   - "commit range" / "last N commits" / "{sha}..{sha}" → Specific commit range
+   - "this diff" / "provided diff" / "paste" → User-provided diff (do not match bare "diff" — it appears in other modes)
+   - When multiple phrases match, prefer the most specific match (e.g., "branch diff" over bare "diff").
+   - **If a clear match is found:** Announce the detected mode (e.g., "Detected intent: review staged changes only") and proceed directly to constructing `{diff_output}` using the corresponding sub-case from instruction 3. Skip to instruction 4 (spec question).
+   - **If no match from invocation text, check sprint tracking.** Look for a sprint status file (`*sprint-status*`) in `{implementation_artifacts}` or `{planning_artifacts}`. If found, scan for any story with status `review`. Handle as follows:
+     - **Exactly one `review` story:** Suggest it: "I found story {{story-id}} in `review` status. Would you like to review its changes? [Y] Yes / [N] No, let me choose". If confirmed, use the story context to determine the diff source (branch name derived from story slug, or uncommitted changes). If declined, fall through to instruction 2.
+     - **Multiple `review` stories:** Present them as numbered options alongside a manual choice option. Wait for user selection. Then use the selected story's context to determine the diff source as in the single-story case above, and proceed to instruction 3.
+   - **If no match and no sprint tracking:** Fall through to instruction 2.
+
+2. HALT. Ask the user: **What do you want to review?** Present these options:
+   - **Uncommitted changes** (staged + unstaged)
+   - **Staged changes only**
+   - **Branch diff** vs a base branch (ask which base branch)
+   - **Specific commit range** (ask for the range)
+   - **Provided diff or file list** (user pastes or provides a path)
+
+3. Construct `{diff_output}` from the chosen source.
+   - For **branch diff**: verify the base branch exists before running `git diff`. If it does not exist, HALT and ask the user for a valid branch.
+   - For **commit range**: verify the range resolves. If it does not, HALT and ask the user for a valid range.
+   - For **provided diff**: validate the content is non-empty and parseable as a unified diff. If it is not parseable, HALT and ask the user to provide a valid diff.
+   - For **file list**: validate each path exists in the working tree. Construct `{diff_output}` by running `git diff HEAD -- <path1> <path2> ...`. If any paths are untracked (new files not yet staged), use `git diff --no-index /dev/null <path>` to include them. If the diff is empty (files have no uncommitted changes and are not untracked), ask the user whether to review the full file contents or to specify a different baseline.
+   - After constructing `{diff_output}`, verify it is non-empty regardless of source type. If empty, HALT and tell the user there is nothing to review.
+
+4. Ask the user: **Is there a spec or story file that provides context for these changes?**
+   - If yes: set `{spec_file}` to the path provided, verify the file exists and is readable, then set `{review_mode}` = `"full"`.
+   - If no: set `{review_mode}` = `"no-spec"`.
+
+5. If `{review_mode}` = `"full"` and the file at `{spec_file}` has a `context` field in its frontmatter listing additional docs, load each referenced document. Warn the user about any docs that cannot be found.
+
+6. Sanity check: if `{diff_output}` exceeds approximately 3000 lines, warn the user and offer to chunk the review by file group.
+   - If the user opts to chunk: agree on the first group, narrow `{diff_output}` accordingly, and list the remaining groups for the user to note for follow-up runs.
+   - If the user declines: proceed as-is with the full diff.
+
+### CHECKPOINT
+
+Present a summary before proceeding: diff stats (files changed, lines added/removed), `{review_mode}`, and loaded spec/context docs (if any). HALT and wait for user confirmation to proceed.
+
+
+## NEXT
+
+Read fully and follow `./step-02-review.md`

package/src/xmc/workflows/4-implementation/xiaoma-code-review/steps/step-02-review.md

@@ -0,0 +1,41 @@
+---
+failed_layers: '' # set at runtime: comma-separated list of layers that failed or returned empty
+---
+
+# Step 2: Review
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- The Blind Hunter subagent receives NO project context — diff only.
+- The Edge Case Hunter subagent receives diff and project read access.
+- The Acceptance Auditor subagent receives diff, spec, and context docs.
+
+## INSTRUCTIONS
+
+1. Launch parallel subagents. Each subagent gets NO conversation history from this session:
+
+   - **Blind Hunter** -- Invoke the `xiaoma-review-adversarial-general` skill in a subagent. Pass `content` = `{diff_output}` only. No spec, no project access.
+
+   - **Edge Case Hunter** -- Invoke the `xiaoma-review-edge-case-hunter` skill in a subagent. Pass `content` = `{diff_output}`. This subagent has read access to the project.
+
+   - **Acceptance Auditor** (only if `{review_mode}` = `"full"`) -- A subagent that receives `{diff_output}`, the content of the file at `{spec_file}`, and any loaded context docs. Its prompt:
+     > You are an Acceptance Auditor. Review this diff against the spec and context docs. Check for: violations of acceptance criteria, deviations from spec intent, missing implementation of specified behavior, contradictions between spec constraints and actual code. Output findings as a markdown list. Each finding: one-line title, which AC/constraint it violates, and evidence from the diff.
+
+2. **Subagent failure handling**: If any subagent fails, times out, or returns empty results, append the layer name to `{failed_layers}` (comma-separated) and proceed with findings from the remaining layers.
+
+3. If `{review_mode}` = `"no-spec"`, note to the user: "Acceptance Auditor skipped — no spec file provided."
+
+4. **Fallback** (if subagents are not available): Generate prompt files in `{implementation_artifacts}` -- one per active reviewer:
+   - `review-blind-hunter.md` (always)
+   - `review-edge-case-hunter.md` (always)
+   - `review-acceptance-auditor.md` (only if `{review_mode}` = `"full"`)
+
+   HALT. Tell the user to run each prompt in a separate session and paste back findings. When findings are pasted, resume from this point and proceed to step 3.
+
+5. Collect all findings from the completed layers.
+
+
+## NEXT
+
+Read fully and follow `./step-03-triage.md`