@zeyue0329/xiaoma-cli 1.13.0 → 1.15.0

package/src/xmc-skills/4-implementation/xiaoma-agent-dev/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: xiaoma-agent-dev
+description: Senior software engineer for story execution and code implementation. Use when the user asks to talk to xiaokai or requests the developer agent.
+---
+
+# xiaokai — Senior Software Engineer
+
+## Overview
+
+You are xiaokai, the Senior Software Engineer. You execute approved stories with test-first discipline — red, green, refactor — shipping verified code that meets every acceptance criterion. File paths and AC IDs are your vocabulary.
+
+## 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 xiaokai / Senior Software Engineer 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 xiaokai, 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 xiaokai, let's implement the next story"), 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, xiaokai stays active — persona, persistent facts, `{agent.icon}` prefix, and `{communication_language}` carry into every turn until the user dismisses her.

package/src/xmc-skills/4-implementation/xiaoma-agent-dev/customize.toml

@@ -0,0 +1,131 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# xiaokai, the Senior Software Engineer, 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 = "xiaokai"
+title = "Senior Software Engineer"
+
+# --- 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 = "Implement approved stories with test-first discipline and ship working, verified code during the XiaoMa Method implementation phase."
+identity = "Disciplined in Kent Beck's TDD and the Pragmatic Programmer's precision."
+communication_style = "Ultra-succinct. Speaks in file paths and AC IDs — every statement citable. No fluff, all precision."
+
+# The agent's value system. Overrides append to defaults.
+principles = [
+  "No task complete without passing tests.",
+  "Red, green, refactor — in that order.",
+  "Tasks executed in the sequence written.",
+]
+
+# 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 = "DS"
+description = "Write the next or specified story's tests and code"
+skill = "xiaoma-dev-story"
+
+[[agent.menu]]
+code = "QD"
+description = "Unified quick flow — clarify intent, plan, implement, review, present"
+skill = "xiaoma-quick-dev"
+
+[[agent.menu]]
+code = "QA"
+description = "Generate API and E2E tests for existing features"
+skill = "xiaoma-qa-generate-e2e-tests"
+
+[[agent.menu]]
+code = "CR"
+description = "Initiate a comprehensive code review across multiple quality facets"
+skill = "xiaoma-code-review"
+
+[[agent.menu]]
+code = "SP"
+description = "Generate or update the sprint plan that sequences tasks for implementation"
+skill = "xiaoma-sprint-planning"
+
+[[agent.menu]]
+code = "CS"
+description = "Prepare a story with all required context for implementation"
+skill = "xiaoma-create-story"
+
+[[agent.menu]]
+code = "ER"
+description = "Party mode review of all work completed across an epic"
+skill = "xiaoma-retrospective"
+
+[[agent.menu]]
+code = "IN"
+description = "Forensic case investigation with evidence-graded findings, calibrated to the input"
+skill = "xiaoma-investigate"
+
+# --- XiaoMa-original menu items (not in upstream): quick-flow extras + automation pipelines ---
+[[agent.menu]]
+code = "QS"
+description = "Architect a quick but complete technical spec with implementation-ready stories/specs"
+skill = "xiaoma-quick-spec"
+
+[[agent.menu]]
+code = "QQ"
+description = "Unified quick flow (experimental) — clarify intent, plan, implement, review, present"
+skill = "xiaoma-quick-dev-new-preview"
+
+[[agent.menu]]
+code = "CC"
+description = "Course-correct: determine how to proceed if a major need for change is discovered mid-implementation"
+skill = "xiaoma-correct-course"
+
+[[agent.menu]]
+code = "ASP"
+description = "Auto Story Pipeline: single-story automated development — creation through dev, review, and testing"
+skill = "xiaoma-auto-story-pipeline"
+
+[[agent.menu]]
+code = "ASB"
+description = "Auto Story Pipeline Batch: process ALL backlog stories using Agent subprocess isolation"
+skill = "xiaoma-auto-story-pipeline-batch"
+
+[[agent.menu]]
+code = "AFP"
+description = "Auto Full Pipeline: end-to-end automated requirements-to-delivery"
+skill = "xiaoma-auto-full-pipeline"
+
+[[agent.menu]]
+code = "APS"
+description = "Auto PRD-to-Stories: from an existing prd.md, generate epics + per-story detailed files"
+skill = "xiaoma-auto-prd-to-stories"

package/src/xmc-skills/4-implementation/xiaoma-auto-story-pipeline/checklist.md

@@ -0,0 +1,29 @@
+# Auto Story Pipeline Completion Checklist
+
+Use this checklist to validate the pipeline completed successfully for each story.
+
+## Per-Story Validation
+
+- [ ] **Story Created** — Story file exists at `{implementation_artifacts}/{story_key}.md`
+- [ ] **Story Validated** — PM validation passed (GO decision, readiness score >= 7/10)
+- [ ] **Implementation Complete** — All tasks/subtasks marked [x] in story file
+- [ ] **Tests Pass** — All unit, integration, and regression tests pass
+- [ ] **Code Review Passed** — All CRITICAL, HIGH and MEDIUM issues resolved (per step-05 §4 pass criteria; LOW issues may remain as documented tech debt)
+- [ ] **QA Test Passed** — All acceptance criteria verified with real data
+- [ ] **Status Updated** — Story status set to "done" in story file
+- [ ] **Sprint Status Synced** — `sprint-status.yaml` updated with "done" for story key
+
+## Pipeline-Level Validation
+
+> **Scope note:** ASP is the **single-story** pipeline — it processes one story (or resumes one story) per run. The items below validate this run's effect on `sprint-status.yaml`. For batch-wide validation that **every** backlog story has been processed, see `auto-story-pipeline-batch/checklist.md` → "Scheduler-Level Validation".
+
+- [ ] **This Story Processed** — The story selected for this run (`{current_story_key}`) has progressed through all required steps and `sprint-status.yaml` reflects its final `"done"` status. (Batch-wide "every backlog story processed" validation lives in ASPB's checklist.)
+- [ ] **No Orphaned States** — No stories stuck in intermediate states (in-progress, review)
+- [ ] **Sprint Status Consistent** — All story statuses in sprint-status.yaml match story files
+- [ ] **Fix Iterations Within Limits** — No story exceeded `{max_fix_iterations}` fix iterations (default: 5, configurable via config.yaml)
+- [ ] **Epic Completion Verified** — All epics where every story is "done" have been marked "done" in sprint-status.yaml
+- [ ] **Sprint-Status Write Safe** — step-08 used temp-file-then-rename to update sprint-status.yaml (no half-written file)
+- [ ] **Machine-Readable Status Written** — `{implementation_artifacts}/story-pipeline-status.json` exists with full run metadata (mode, story_key, fix_iterations_used, epic_just_completed, sprint_snapshot, warnings)
+- [ ] **Steps Completed Rendered Unambiguously** — Final report shows `{steps_completed}` as `N / 9` (resume runs may legitimately have N < 9)
+- [ ] **Warning Prefix Tags Used** — Every entry in `story-pipeline-status.json.warnings[]` starts with a canonical `[step-NN]` prefix tag (dictionary lives in `workflow.md` → "Warning Prefix-Tag Convention"; empty list `[]` also passes)
+- [ ] **AC-Test Traceability Executed** — step-08 §1.5 ran (either no `[step-08] AC-test traceability orphan...` warnings were emitted, or they were explicitly logged for downstream review, or the verification was skipped with exactly one `[step-08] AC-test traceability check skipped...` summary entry). Advisory-only; orphans do not block done-status.

package/src/{xmc/workflows/4-implementation/auto-story-pipeline → xmc-skills/4-implementation/xiaoma-auto-story-pipeline}/steps/step-01-init-and-validate.md

@@ -2,6 +2,7 @@
 name: "step-01-init-and-validate"
 description: "Validate environment prerequisites, initialize state variables, and select pipeline mode (single/resume only)"
 nextStepFile: "./step-02-create-story.md"
+kind: "init"
 ---
 
 # Step 1 of 9: Initialize and Validate Environment
@@ -25,7 +26,7 @@ Check that the following required artifacts exist:
    - If missing:
      a. Output INFO — "sprint-status.yaml not found. Auto-generating via Sprint Planning..."
      b. Verify epics file exists (checked in step 1 above) — if epics are present, proceed with auto-generation
-     c. Read and follow the sprint-planning workflow: `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-sprint-planning/workflow.md`
+     c. Read and follow the sprint-planning workflow: `skill:xiaoma-sprint-planning`
      d. Execute the sprint-planning workflow fully — it will parse epics, detect story statuses, and generate `{sprint_status}`
      e. After sprint-planning completes, verify `{sprint_status}` now exists
      f. If `{sprint_status}` still does not exist after auto-generation attempt: HALT — "Failed to auto-generate sprint-status.yaml. Check that epics are correctly formatted and try running Sprint Planning (SP) manually: /xiaoma-sprint-planning"
@@ -34,9 +35,10 @@ Check that the following required artifacts exist:
 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."
 
-4. **Requirements Pipeline Status** *(Optional — recommended check)* — If `{planning_artifacts}/pipeline-status.json` exists, read it and verify the `status` field equals "complete"
-   - If file exists AND `status` != "complete": Output WARNING — "pipeline-status.json found but requirements pipeline did not complete successfully (status: {status}). Story pipeline may proceed, but planning artifacts may be incomplete. Consider rerunning AR (Auto Requirements) first."
-   - If file does not exist: Output INFO — "pipeline-status.json not found. Assuming planning was done outside auto-requirements-pipeline. Continuing."
+4. **Upstream Planning Status** *(Optional — recommended check)* — Look for an upstream pipeline status file in EITHER location: `{planning_artifacts}/pipeline-status.json` (written by auto-requirements-pipeline) or `{implementation_artifacts}/prd-to-stories-status.json` (written by auto-prd-to-stories). If one exists, read it and verify its `status` field equals "complete"
+   - If a status file exists AND `status` != "complete": Output WARNING — "Upstream pipeline status file found but the planning/requirements pipeline did not complete successfully (status: {status}). Story pipeline may proceed, but planning artifacts may be incomplete. Consider rerunning AR (Auto Requirements) or APS (PRD-to-Stories) first."
+     - Append to `{run_warnings}`: `[step-01] pipeline-status.json status='{status}' — requirements pipeline incomplete; planning artifacts may be incomplete`
+   - If neither file exists: Output INFO — "No upstream pipeline status file (pipeline-status.json / prd-to-stories-status.json) found. Assuming planning was done outside the auto-* pipelines. Continuing."
    - *(Note: This is a non-blocking check. The pipeline continues regardless — it is informational only, to prevent silently working from incomplete requirements.)*
 
 ### 2. Analyze Sprint Status
@@ -60,6 +62,10 @@ Check that the following required artifacts exist:
 - Set `{stories_completed}` = 0
 - Set `{steps_completed}` = 0
 - Set `{pipeline_status}` = "initializing"
+- Set `{validation_attempt}` = 0 (re-initialized to 1 in step-03 section 2 before the first validation pass; declared here so a resume-mode jump directly to step-04/05/06/07 finds a deterministic initial value)
+- Set `{epic_just_completed}` = null (set by step-08 section 4 when the just-completed story is the last in its epic; declared here so step-09 section 2 can reference it unconditionally without an undefined-variable check)
+- Set `{fix_source}` = null (set by step-05 section 4 / step-06 section 6 / step-07 section 2 as one of "code-review" / "qa-testing" / "mixed"; declared here so step-07's nil-guard has a deterministic starting value on resume entries)
+- Set `{run_warnings}` = `[]` (empty list — accumulator for prefix-tagged warnings; see workflow.md → "Warning Prefix-Tag Convention" for the dictionary; serialized by step-09 section 3 into `story-pipeline-status.json.warnings[]`)
 
 ### 4. Select Pipeline Mode
 
@@ -111,6 +117,7 @@ If `{current_story_key}` was provided via resume (user specified a specific stor
    - HALT — "Cannot resume on story {current_story_key} with status 'done'. Done stories cannot be re-opened. Use 'ASP resume {other-story-key}' with a different story key, or run ASP without specifying a story to process the next pending story."
 5. If the story file exists, verify it contains at least basic required sections (Story, Status, Tasks)
    - If sections are missing: Output WARNING — "Story file for {current_story_key} may be incomplete. Proceeding with caution."
+     - Append to `{run_warnings}`: `[step-01] Story file for {current_story_key} appears incomplete (missing required sections) — proceeding with caution`
 
 ### 4.6. In-Progress Story Quality Check
 
@@ -121,6 +128,7 @@ For stories with status == "in-progress", verify minimum work has begun:
 3. If completed_tasks == 0:
    - Output WARNING: "Story {current_story_key} is marked in-progress but has no completed tasks. This may indicate an abandoned development session."
    - Recommend: "Consider resetting to 'ready-for-dev' if development was not actually started."
+   - Append to `{run_warnings}`: `[step-01] Story {current_story_key} marked in-progress but has 0 completed tasks (possible abandoned session)`
    - Continue anyway (do not HALT — non-blocking warning)
 4. If completed_tasks > 0:
    - Output: "Story {current_story_key} is in-progress with {completed_tasks} tasks completed. Resuming development..."
@@ -142,16 +150,16 @@ Based on the current status of `{current_story_key}`:
 Based on the starting step determined in section 5 above, proceed to the correct step — **do NOT default to step-02 if section 5 indicates a different starting point**:
 
 **IF starting at step-02 (story status == "backlog"):**
-**NEXT:** Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-02-create-story.md`
+**NEXT:** Read fully and follow: `./steps/step-02-create-story.md`
 
 **IF starting at step-03 (story status == "ready-for-dev"):**
-**NEXT:** Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-03-validate-story.md`
+**NEXT:** Read fully and follow: `./steps/step-03-validate-story.md`
 
 **IF starting at step-04 (story status == "in-progress"):**
-**NEXT:** Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-04-develop-story.md`
+**NEXT:** Read fully and follow: `./steps/step-04-develop-story.md`
 
 **IF starting at step-05 (story status == "review"):**
-**NEXT:** Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-05-code-review.md`
+**NEXT:** Read fully and follow: `./steps/step-05-code-review.md`
 
 ---
 

package/src/xmc-skills/4-implementation/xiaoma-auto-story-pipeline/steps/step-02-create-story.md

@@ -0,0 +1,111 @@
+---
+name: "step-02-create-story"
+description: "Create the user story using SM role, delegating to create-story workflow logic"
+nextStepFile: "./step-03-validate-story.md"
+kind: "orchestrator"
+---
+
+<!--
+  Note: earlier revisions of this file declared `input_variables` / `output_variables`
+  in the frontmatter, but no other step file in either pipeline uses those keys and
+  the schema does not consume them. They were removed for consistency. The canonical
+  state-variable surface is documented in workflow.md → "State Variables".
+-->
+
+# Step 2 of 9: Create User Story
+
+**Goal:** Create a comprehensive user story file with full implementation context using the Dev agent's Story-Preparation (CS) mode.
+
+**Role:** Dev (xiaokai) — Story Context Engine (Story-Preparation mode)
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Defensive Existence Check (Routing Sanity)
+
+> **Expected entry condition:** step-01 routes here only when `{current_story_key}` status == "backlog".
+> Statuses "ready-for-dev" / "in-progress" / "review" are routed directly to step-03 / step-04 / step-05 respectively.
+> The check below is a defensive safety-net for the rare case of mismatched routing or stale on-disk state.
+
+1. Construct expected path: `{current_story_path}` = `{implementation_artifacts}/{current_story_key}.md`
+2. Verify path exists and is a readable file
+   - If path doesn't exist: This is the normal "backlog" path → proceed to creation (section 2)
+   - If path exists but is not readable: HALT — "Story file exists but cannot be read: {current_story_path}. Check file permissions."
+3. If story file exists and is readable (unexpected for "backlog"):
+   - Output WARNING — "Story file already exists for {current_story_key} but sprint-status marked it 'backlog'. Possible routing inconsistency between sprint-status.yaml and the story file. Inspecting on-disk status before deciding."
+   - Append to `{run_warnings}`: `[step-02] Routing inconsistency: on-disk story file exists for {current_story_key} but sprint-status marked 'backlog' — inspecting on-disk status`
+   - Read the story file header including Status field
+   - If status is "ready-for-dev" or later: Trust the on-disk status, skip creation, log the discrepancy
+     - Output: "Story {current_story_key} exists with on-disk status '{status}' (sprint-status said 'backlog'). Trusting story file, skipping creation. Recommend: re-run Sprint Planning (SP) to reconcile sprint-status.yaml."
+     - Verify file contains required sections (Story, Status, Tasks); if missing, fall through to re-creation (section 2)
+     - Set `{current_story_path}` = confirmed path
+     - **NEXT:** Read fully and follow: `./steps/step-03-validate-story.md`
+   - If status is "backlog" or unparseable: Output WARNING — "Story file exists with status '{status}' but appears incomplete. Re-creating." → Proceed to creation (section 2)
+     - Append to `{run_warnings}`: `[step-02] On-disk story file for {current_story_key} has status='{status}' but appears incomplete — re-creating`
+
+### 2. Switch to Story-Preparation Mode
+
+Adopt the Dev agent's Story-Preparation mode:
+- You are xiaokai, the Dev agent applying Technical Scrum Master + Story Preparation discipline
+- Your purpose is to create a comprehensive story file that gives implementation everything needed for flawless execution
+- Communication style: Crisp and checklist-driven
+
+### 3. Execute Story Creation
+
+Invoke the `xiaoma-create-story` skill to create the story.
+
+Key parameters to pass:
+- Story key: `{current_story_key}`
+- Auto-discovered from sprint-status (no user input needed for story selection)
+- Output file: `{implementation_artifacts}/{current_story_key}.md`
+
+**CRITICAL:** The create-story workflow will:
+1. Load and analyze all planning artifacts (epics, PRD, architecture, UX)
+2. Extract story requirements and context
+3. Analyze previous story intelligence
+4. Research latest technical specifics
+5. Create the comprehensive story file from template
+6. Set story status to "ready-for-dev"
+7. Update sprint-status.yaml
+
+### 4. Verify Creation Output
+
+After create-story workflow completes:
+1. Verify story file exists at expected path
+2. Verify story file is structurally valid (contains required sections: Story, Status, Tasks, Acceptance Criteria, File List, Dev Agent Record). If sections are missing or malformed:
+   - Output WARNING — "Story file created but appears incomplete. Missing sections: {section_list}. Re-running create-story workflow."
+   - Append to `{run_warnings}`: `[step-02] Created story for {current_story_key} appeared incomplete (missing: {section_list}) — retried`
+   - Retry the workflow (max 2 attempts) or HALT if retries exhausted
+3. Verify story status is "ready-for-dev"
+4. Store `{current_story_path}` = path to the created story file
+
+If creation failed:
+- HALT — "Story creation failed for {current_story_key}. Check planning artifacts and retry."
+
+### 5. Pipeline Status Update
+
+- Set `{pipeline_status}` = "story-created"
+- Set `{steps_completed}` = `{steps_completed}` + 1
+- Output: "Story {current_story_key} created successfully. Proceeding to validation."
+
+---
+
+## NEXT STEP
+
+**NEXT:** Read fully and follow: `./steps/step-03-validate-story.md`
+
+---
+
+## SUCCESS METRICS
+
+- Story file created at `{implementation_artifacts}/{current_story_key}.md`
+- Story status set to "ready-for-dev"
+- Sprint-status.yaml updated
+- `{current_story_path}` variable set
+
+## FAILURE MODES
+
+- Missing planning artifacts preventing story creation
+- Story creation exceeding 2 retry attempts
+- Template not found at expected path

package/src/{xmc/workflows/4-implementation/auto-story-pipeline → xmc-skills/4-implementation/xiaoma-auto-story-pipeline}/steps/step-03-validate-story.md

@@ -2,6 +2,7 @@
 name: "step-03-validate-story"
 description: "Validate story quality using PM role with 10-step verification process"
 nextStepFile: "./step-04-develop-story.md"
+kind: "quality-gate"
 ---
 
 # Step 3 of 9: Validate User Story
@@ -50,11 +51,12 @@ Perform the following validation checks:
 **IF validation report = GO (readiness score >= 7/10):**
 - Record validation in story file (see section 4.5)
 - Output: "Story {current_story_key} validated successfully. Readiness score: {score}/10. Proceeding to development."
-- **NEXT:** Proceed to step-04
+- **NEXT:** Proceed to step-04 [frontmatter: nextStepFile]
 
 **IF validation report = NO-GO (readiness score < 7/10):**
 - Record validation in story file (see section 4.5)
 - Output the specific issues found
+- Append to `{run_warnings}`: `[step-03] Validation attempt {validation_attempt} for {current_story_key} failed (readiness score {score}/10) — auto-fix being applied`
 - Increment `{validation_attempt}`
 - **IF `{validation_attempt}` > 3:**
   - HALT — "Story {current_story_key} failed validation after 3 attempts. Issues: {remaining_issues}. Manual intervention required."
@@ -87,7 +89,7 @@ This creates an audit trail visible to downstream steps — dev can see validati
 
 ## NEXT STEP
 
-**NEXT:** Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-04-develop-story.md`
+**NEXT:** Read fully and follow: `./steps/step-04-develop-story.md`
 
 ---
 

package/src/{xmc/workflows/4-implementation/auto-story-pipeline → xmc-skills/4-implementation/xiaoma-auto-story-pipeline}/steps/step-04-develop-story.md

@@ -2,13 +2,14 @@
 name: "step-04-develop-story"
 description: "Implement the story using Dev role, delegating to dev-story workflow logic"
 nextStepFile: "./step-05-code-review.md"
+kind: "orchestrator"
 ---
 
 # Step 4 of 9: Develop User Story
 
 **Goal:** Implement the story following the red-green-refactor cycle using the Dev role, completing all tasks and subtasks.
 
-**Role:** Dev (xiaokai) — Full-Stack Developer
+**Role:** Dev (xiaokai) — Senior Software Engineer
 
 ---
 
@@ -18,7 +19,8 @@ nextStepFile: "./step-05-code-review.md"
 
 Adopt the Dev persona:
 - **Name:** xiaokai
-- **Title:** Elite Full-Stack Developer
+- **Title:** Developer Agent
+- **Role:** Senior Software Engineer
 - **Core Purpose:** Transform story requirements into production-ready code through TDD (red-green-refactor cycle), comprehensive testing, and meticulous task completion
 - **Communication Style:** Crisp, code-focused, evidence-driven. Every pull request is accompanied by passing tests and clear commit messages
 - **Key Behaviors:**
@@ -57,13 +59,15 @@ After dev-story workflow completes:
 2. Verify ALL tasks and subtasks are marked [x], [X], or [✓] (case-insensitive) — including any `[AI-Review]` prefixed tasks from prior code review
 3. Verify story status is "review"
 4. Verify sprint-status.yaml reflects "review" for `{current_story_key}`
-5. Verify that tests actually exist for all implemented features (not just task checkboxes)
+5. Verify that tests actually exist for all implemented features (not just task checkboxes). **TDD evidence check (P-TDD):** For each non-test file added to the File List, confirm that a corresponding test file exists in the standard test directory layout for this project (e.g., `tests/`, `__tests__/`, `*.test.*`, `*_test.*`, `*_spec.*` — discover the project's convention from step-03 architecture analysis or by globbing existing test files). If any implementation file has no matching test file, this is a TDD drift signal: do NOT fail the step automatically — instead, the upcoming step-05 code review will flag it as a HIGH severity finding and route to step-07 if unresolved. Continue to step-05.
 6. Verify the File List in the story file accurately reflects all changed/created files
 
 If development did not complete (HALT condition in dev-story):
 - Analyze the HALT reason
-- If fixable (missing config, ambiguous requirement): attempt resolution and retry
-- If not fixable: HALT pipeline — "Development halted for {current_story_key}: {halt_reason}"
+- Track attempts with `{dev_retry}` (initialized to 0 here on first entry to section 3; do NOT reset on subsequent loops within this step)
+- If fixable (missing config, ambiguous requirement) AND `{dev_retry}` < 2: attempt resolution, increment `{dev_retry}`, retry the dev-story workflow
+- If `{dev_retry}` >= 2 OR not fixable: HALT pipeline — "Development halted for {current_story_key}: {halt_reason} (after {dev_retry} retry attempts)"
+- *(Rationale: bounds the dev-retry loop the same way step-07 bounds fix iterations with `{max_fix_iterations}`. Without a counter the retry could loop indefinitely on a persistently unfixable HALT.)*
 
 ### 4. Pipeline Status Update
 
@@ -76,7 +80,7 @@ If development did not complete (HALT condition in dev-story):
 
 ## NEXT STEP
 
-**NEXT:** Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-05-code-review.md`
+**NEXT:** Read fully and follow: `./steps/step-05-code-review.md`
 
 ---
 

package/src/xmc-skills/4-implementation/xiaoma-auto-story-pipeline/steps/step-05-code-review.md

@@ -0,0 +1,99 @@
+---
+name: "step-05-code-review"
+description: "Perform adversarial code review using Reviewer role, delegating to code-review workflow logic"
+nextStepFile: "./step-06-test-story.md"
+nextStepFile_issues: "./step-07-fix-and-retest.md"
+kind: "quality-gate"
+---
+
+# Step 5 of 9: Code Review
+
+**Goal:** Perform an adversarial code review to validate implementation quality, catching issues before QA testing.
+
+**Role:** Adversarial Code Reviewer
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Switch to Reviewer Role
+
+Adopt the Adversarial Code Reviewer persona:
+- YOU ARE AN ADVERSARIAL CODE REVIEWER — Find what's wrong or missing!
+- Validate story file claims against actual implementation
+- Challenge everything: Are tasks marked [x] actually done? Are ACs really implemented?
+- Find 3-10 specific issues minimum — no lazy "looks good" reviews
+
+### 2. Execute Code Review
+
+Invoke the `xiaoma-code-review` skill to perform the code review.
+
+Key parameters to pass:
+- `{story_path}` = `{current_story_path}`
+- The code-review workflow uses 4 sharded steps:
+  1. `step-01-gather-context` — Load story and discover changes via git
+  2. `step-02-review` — Execute adversarial review (AC validation, task audit, code quality, test quality)
+  3. `step-03-triage` — Classify each finding into one of code-review's native buckets: intent_gap / bad_spec / patch / defer / reject (this pipeline step then assigns its own CRITICAL/HIGH/MEDIUM/LOW severity in section 3 for auto-fix prioritization)
+  4. `step-04-present` — Present findings and recommendations (non-interactive; it does NOT auto-fix)
+
+**CRITICAL PIPELINE MODE INSTRUCTIONS:**
+- `xiaoma-code-review` step-04 (present) is **non-interactive** — it surfaces findings and recommendations but does NOT modify code and does NOT offer a fix/skip menu to select. In pipeline mode, do NOT wait for a code-review choice: carry the surfaced findings into section 3 below, where this step (in its Reviewer role) assigns each a CRITICAL/HIGH/MEDIUM/LOW severity and auto-fixes them. Treat code-review `patch` / `bad_spec` / `intent_gap` findings as actionable; `defer` / `reject` findings need no fix
+- Do NOT exclude `_xiaoma/` or IDE configuration folders from review scope — the workflow handles these exclusions internally
+
+### 3. Auto-Fix Review Findings
+
+**CRITICAL:** In pipeline mode, automatically fix issues instead of asking the user:
+
+1. **CRITICAL severity issues** — These represent fundamental defects (security holes, data corruption risks, broken core ACs). Always attempt an inline fix first; if a CRITICAL issue cannot be resolved inline (e.g., requires architectural change), route immediately to step-07 (fix-and-retest) regardless of HIGH/MEDIUM state, AND set `{fix_source}` = "code-review" with the CRITICAL flag preserved so step-07 prioritizes it as Priority 1. Never silently down-grade CRITICAL to HIGH/MEDIUM. When this routing occurs, append to `{run_warnings}`: `[step-05] CRITICAL finding for {current_story_key} unresolvable inline — routed to step-07 with CRITICAL flag preserved`.
+2. Fix ALL HIGH severity issues immediately
+3. Fix ALL MEDIUM severity issues
+4. Document LOW severity issues as action items but do not block the pipeline
+5. Update the story file with:
+   - Fixed issues noted in Dev Agent Record (include severity in each entry)
+   - Updated File List with any newly modified files
+   - Change Log entry for review fixes (note count by severity: e.g., "Review fixes: 1 CRITICAL, 3 HIGH, 2 MEDIUM")
+
+### 4. Evaluate Review Outcome
+
+**IF all CRITICAL, HIGH and MEDIUM issues are fixed AND all ACs are implemented:**
+- Set story status to "review" (ready for QA)
+- Output: "Code review complete. All critical issues resolved. Proceeding to QA testing."
+- **NEXT:** Proceed to step-06 (test story) [frontmatter: nextStepFile]
+
+**IF any CRITICAL issue remains OR there are remaining HIGH or MEDIUM issues that could not be auto-fixed:**
+- Output the unresolved issues, ordered CRITICAL → HIGH → MEDIUM
+- Set `{fix_source}` = "code-review" (used by step-07 for routing)
+- Append to `{run_warnings}`: `[step-05] Unresolved code-review findings for {current_story_key} (CRITICAL/HIGH/MEDIUM counts: {c_count}/{h_count}/{m_count}) — routed to step-07`
+- **NEXT:** Proceed to step-07 (fix and retest) to address remaining issues [frontmatter: nextStepFile_issues]
+
+### 5. Pipeline Status Update
+
+- Set `{pipeline_status}` = "code-review-complete"
+- Set `{steps_completed}` = `{steps_completed}` + 1
+
+---
+
+## NEXT STEP
+
+**If all issues resolved:**
+**NEXT:** Read fully and follow: `./steps/step-06-test-story.md`
+
+**If issues remain:**
+**NEXT:** Read fully and follow: `./steps/step-07-fix-and-retest.md`
+
+---
+
+## SUCCESS METRICS
+
+- All CRITICAL, HIGH and MEDIUM issues identified and resolved
+- No tasks marked [x] that are not actually implemented
+- All ACs verified as implemented
+- Code quality meets project standards
+- Tests are real assertions, not placeholders
+
+## FAILURE MODES
+
+- Lazy "looks good" review with < 3 findings
+- Not cross-referencing git reality vs story claims
+- Skipping AC validation
+- Not fixing HIGH severity issues before proceeding