@zeyue0329/xiaoma-cli 1.12.0 → 1.15.0

package/src/{xmc/workflows → xmc-skills}/4-implementation/xiaoma-code-review/steps/step-03-triage.md

@@ -30,19 +30,18 @@
    - Set `source` to the merged sources (e.g., `blind+edge`).
 
 3. **Classify** each finding into exactly one bucket:
-   - **intent_gap** -- The spec/intent is incomplete; cannot resolve from existing information. Only possible if `{review_mode}` = `"full"`.
-   - **bad_spec** -- The spec should have prevented this; spec is wrong or ambiguous. Only possible if `{review_mode}` = `"full"`.
-   - **patch** -- Code issue that is trivially fixable without human input. Just needs a code change.
+   - **decision_needed** -- There is an ambiguous choice that requires human input. The code cannot be correctly patched without knowing the user's intent. Only possible if `{review_mode}` = `"full"`.
+   - **patch** -- Code issue that is fixable without human input. The correct fix is unambiguous.
    - **defer** -- Pre-existing issue not caused by the current change. Real but not actionable now.
-   - **reject** -- Noise, false positive, or handled elsewhere.
+   - **dismiss** -- Noise, false positive, or handled elsewhere.
 
-   If `{review_mode}` = `"no-spec"` and a finding would otherwise be `intent_gap` or `bad_spec`, reclassify it as `patch` (if code-fixable) or `defer` (if not).
+   If `{review_mode}` = `"no-spec"` and a finding would otherwise be `decision_needed`, reclassify it as `patch` (if the fix is unambiguous) or `defer` (if not).
 
-4. **Drop** all `reject` findings. Record the reject count for the summary.
+4. **Drop** all `dismiss` findings. Record the dismiss count for the summary.
 
-5. If `{failed_layers}` is non-empty, report which layers failed before announcing results. If zero findings remain after dropping rejects AND `{failed_layers}` is non-empty, warn the user that the review may be incomplete rather than announcing a clean review.
+5. If `{failed_layers}` is non-empty, report which layers failed before announcing results. If zero findings remain after dropping dismissed AND `{failed_layers}` is non-empty, warn the user that the review may be incomplete rather than announcing a clean review.
 
-6. If zero findings remain after dropping rejects and no layers failed, note clean review.
+6. If zero findings remain after triage (all rejected or none raised): state "✅ Clean review — all layers passed." (Step 3 already warned if any review layers failed via `{failed_layers}`.)
 
 
 ## NEXT

package/src/xmc-skills/4-implementation/xiaoma-code-review/steps/step-04-present.md

@@ -0,0 +1,132 @@
+---
+deferred_work_file: '{implementation_artifacts}/deferred-work.md'
+---
+
+# Step 4: Present and Act
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- When `{spec_file}` is set, always write findings to the story file before offering action choices.
+- `decision-needed` findings must be resolved before handling `patch` findings.
+
+## INSTRUCTIONS
+
+### 1. Clean review shortcut
+
+If zero findings remain after triage (all dismissed or none raised): state that and proceed to section 6 (Sprint Status Update).
+
+### 2. Write findings to the story file
+
+If `{spec_file}` exists and contains a Tasks/Subtasks section, append a `### Review Findings` subsection. Write all findings in this order:
+
+1. **`decision-needed`** findings (unchecked):
+   `- [ ] [Review][Decision] <Title> — <Detail>`
+
+2. **`patch`** findings (unchecked):
+   `- [ ] [Review][Patch] <Title> [<file>:<line>]`
+
+3. **`defer`** findings (checked off, marked deferred):
+   `- [x] [Review][Defer] <Title> [<file>:<line>] — deferred, pre-existing`
+
+Also append each `defer` finding to `{deferred_work_file}` under a heading `## Deferred from: code review ({date})`. If `{spec_file}` is set, include its basename in the heading (e.g., `code review of story-3.3 (2026-03-18)`). One bullet per finding with description.
+
+### 3. Present summary
+
+Announce what was written:
+
+> **Code review complete.** <D> `decision-needed`, <P> `patch`, <W> `defer`, <R> dismissed as noise.
+
+If `{spec_file}` is set, add: `Findings written to the review findings section in {spec_file}.`
+Otherwise add: `Findings are listed above. No story file was provided, so nothing was persisted.`
+
+### 4. Resolve decision-needed findings
+
+If `decision_needed` findings exist, present each one with its detail and the options available. The user must decide — the correct fix is ambiguous without their input. Walk through each finding (or batch related ones) and get the user's call. Once resolved, each becomes a `patch`, `defer`, or is dismissed.
+
+If the user chooses to defer, ask: Quick one-line reason for deferring this item? (helps future reviews): — then append that reason to both the story file bullet and the `{deferred_work_file}` entry.
+
+**HALT** — I am waiting for your numbered choice. Reply with only the number. Do not proceed until you select an option.
+
+### 5. Handle `patch` findings
+
+If `patch` findings exist (including any resolved from step 4), HALT. Ask the user:
+
+If `{spec_file}` is set, present all three options:
+
+> **How would you like to handle the `<P>` `patch` findings?**
+> 1. **Apply every patch** — fix all of them now, no per-finding confirmation. Defer and decision-needed items are not touched.
+> 2. **Leave as action items** — they are already in the story file
+> 3. **Walk through each patch** — show details for each before deciding
+
+If `{spec_file}` is **not** set, present only options 1 and 2 (omit "Leave as action items" — findings were not written to a file):
+
+> **How would you like to handle the `<P>` `patch` findings?**
+> 1. **Apply every patch** — fix all of them now, no per-finding confirmation. Defer and decision-needed items are not touched.
+> 2. **Walk through each patch** — show details for each before deciding
+
+**HALT** — I am waiting for your numbered choice. Reply with only the number. Do not proceed until you select an option.
+
+- **Apply every patch**: Apply every patch finding without per-finding confirmation. Do not modify defer or decision-needed items. After all patches are applied, present a summary of changes made. If `{spec_file}` is set, check off the patch items in the story file (leave defer items as-is).
+- **Leave as action items** (only when `{spec_file}` is set): Done — findings are already written to the story.
+- **Walk through each patch**: Present each finding with full detail, diff context, and suggested fix. After walkthrough, re-offer the applicable options above.
+
+  **HALT** — I am waiting for your numbered choice. Do not proceed until you select an option.
+
+**✅ Code review actions complete**
+
+- Decision-needed resolved: <D>
+- Patches handled: <P>
+- Deferred: <W>
+- Dismissed: <R>
+
+### 6. Update story status and sync sprint tracking
+
+Skip this section if `{spec_file}` is not set.
+
+#### Determine new status based on review outcome
+
+- If all `decision-needed` and `patch` findings were resolved (fixed or dismissed) AND no unresolved HIGH/MEDIUM issues remain: set `{new_status}` = `done`. Update the story file Status section to `done`.
+- If `patch` findings were left as action items, or unresolved issues remain: set `{new_status}` = `in-progress`. Update the story file Status section to `in-progress`.
+
+Save the story file.
+
+#### Sync sprint-status.yaml
+
+If `{story_key}` is not set, skip this subsection and note that sprint status was not synced because no story key was available.
+
+If `{sprint_status}` file exists:
+
+1. Load the FULL `{sprint_status}` file.
+2. Find the `development_status` entry matching `{story_key}`.
+3. If found: update `development_status[{story_key}]` to `{new_status}`. Update `last_updated` to current date. Save the file, preserving ALL comments and structure including STATUS DEFINITIONS.
+4. If `{story_key}` not found in sprint status: warn the user that the story file was updated but sprint-status sync failed.
+
+If `{sprint_status}` file does not exist, note that story status was updated in the story file only.
+
+#### Completion summary
+
+> **Review Complete!**
+>
+> **Story Status:** `{new_status}`
+> **Issues Fixed:** <fixed_count>
+> **Action Items Created:** <action_count>
+> **Deferred:** <W>
+> **Dismissed:** <R>
+
+### 7. Next steps
+
+Present the user with follow-up options:
+
+> **What would you like to do next?**
+> 1. **Start the next story** — run `dev-story` to pick up the next `ready-for-dev` story
+> 2. **Re-run code review** — address findings and review again
+> 3. **Done** — end the workflow
+
+**HALT** — I am waiting for your choice. Do not proceed until the user selects an option.
+
+## On Complete
+
+Run: `node {project-root}/_xiaoma/scripts/resolve_customization.js --skill {skill-root} --key workflow.on_complete`
+
+If the resolved `workflow.on_complete` is non-empty, follow it as the final terminal instruction before exiting.

package/src/{xmc/workflows/4-implementation/xiaoma-correct-course/workflow.md → xmc-skills/4-implementation/xiaoma-correct-course/SKILL.md}

@@ -1,14 +1,44 @@
+---
+name: xiaoma-correct-course
+description: 'Manage significant changes during sprint execution. Use when the user says "correct course" or "propose sprint change"'
+---
+
 # Correct Course - Sprint Change Management Workflow
 
 **Goal:** Manage significant changes during sprint execution by analyzing impact across all project artifacts and producing a structured Sprint Change Proposal.
 
-**Your Role:** You are a Scrum Master navigating change management. Analyze the triggering issue, assess impact across PRD, epics, architecture, and UX artifacts, and produce an actionable Sprint Change Proposal with clear handoff.
+**Your Role:** You are a Developer navigating change management. Analyze the triggering issue, assess impact across PRD, epics, architecture, and UX artifacts, and produce an actionable Sprint Change Proposal with clear handoff.
 
----
+## Conventions
+
+- Bare paths (e.g. `checklist.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
 
-## INITIALIZATION
+Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding.
 
-### Configuration Loading
+### 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:
 
@@ -24,11 +54,21 @@ Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
 - Generate all documents in `{document_output_language}`
 - DOCUMENT OUTPUT: Updated epics, stories, or PRD sections. Clear, actionable changes. User skill level (`{user_skill_level}`) affects conversation style ONLY, not document updates.
 
-### Paths
+### Step 5: Greet the User
+
+Greet `{user_name}`, 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.
+
+## Paths
 
 - `default_output_file` = `{planning_artifacts}/sprint-change-proposal-{date}.md`
 
-### Input Files
+## Input Files
 
 | Input | Path | Load Strategy |
 |-------|------|---------------|
@@ -36,24 +76,18 @@ Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
 | Epics | `{planning_artifacts}/*epic*.md` (whole) or `{planning_artifacts}/*epic*/*.md` (sharded) | FULL_LOAD |
 | Architecture | `{planning_artifacts}/*architecture*.md` (whole) or `{planning_artifacts}/*architecture*/*.md` (sharded) | FULL_LOAD |
 | UX Design | `{planning_artifacts}/*ux*.md` (whole) or `{planning_artifacts}/*ux*/*.md` (sharded) | FULL_LOAD |
-| Tech Spec | `{planning_artifacts}/*tech-spec*.md` (whole) | FULL_LOAD |
+| Spec | `{planning_artifacts}/*spec-*.md` (whole) | FULL_LOAD |
 | Document Project | `{project_knowledge}/index.md` (sharded) | INDEX_GUIDED |
 
-### Context
-
-- Load `**/project-context.md` if it exists
-
----
-
-## EXECUTION
+## Execution
 
 ### Document Discovery - Loading Project Artifacts
 
 **Strategy**: Course correction needs broad project context to assess change impact accurately. Load all available planning artifacts.
 
-**Discovery Process for FULL_LOAD documents (PRD, Epics, Architecture, UX Design, Tech Spec):**
+**Discovery Process for FULL_LOAD documents (PRD, Epics, Architecture, UX Design, Spec):**
 
-1. **Search for whole document first** - Look for files matching the whole-document pattern (e.g., `*prd*.md`, `*epic*.md`, `*architecture*.md`, `*ux*.md`, `*tech-spec*.md`)
+1. **Search for whole document first** - Look for files matching the whole-document pattern (e.g., `*prd*.md`, `*epic*.md`, `*architecture*.md`, `*ux*.md`, `*spec-*.md`)
 2. **Check for sharded version** - If whole document not found, look for a directory with `index.md` (e.g., `prd/index.md`, `epics/index.md`)
 3. **If sharded version found**:
    - Read `index.md` to understand the document structure
@@ -70,19 +104,18 @@ Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
 
 **Fuzzy matching**: Be flexible with document names — users may use variations like `prd.md`, `xmc-prd.md`, `product-requirements.md`, etc.
 
-**Missing documents**: Not all documents may exist. PRD and Epics are essential; Architecture, UX Design, Tech Spec, and Document Project are loaded if available. HALT if PRD or Epics cannot be found.
+**Missing documents**: Not all documents may exist. PRD and Epics are essential; Architecture, UX Design, Spec, and Document Project are loaded if available. HALT if PRD or Epics cannot be found.
 
 <workflow>
 
 <step n="1" goal="Initialize Change Navigation">
-  <action>Load **/project-context.md for coding standards and project-wide patterns (if exists)</action>
   <action>Confirm change trigger and gather user description of the issue</action>
   <action>Ask: "What specific issue or change has been identified that requires navigation?"</action>
-  <action>Verify access to required project documents:</action>
-    - PRD (Product Requirements Document)
-    - Current Epics and Stories
-    - Architecture documentation
-    - UI/UX specifications
+  <action>Verify access to project documents:</action>
+    - PRD (Product Requirements Document) — required
+    - Current Epics and Stories — required
+    - Architecture documentation — optional, load if available
+    - UI/UX specifications — optional, load if available
   <action>Ask user for mode preference:</action>
     - **Incremental** (recommended): Refine each edit collaboratively
     - **Batch**: Present all changes at once for review
@@ -90,7 +123,7 @@ Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
 
 <action if="change trigger is unclear">HALT: "Cannot navigate change without clear understanding of the triggering issue. Please provide specific details about what needs to change and why."</action>
 
-<action if="core documents are unavailable">HALT: "Need access to project documents (PRD, Epics, Architecture, UI/UX) to assess change impact. Please ensure these documents are accessible."</action>
+<action if="PRD or Epics are unavailable">HALT: "Need access to PRD and Epics to assess change impact. Please ensure these documents are accessible. Architecture and UI/UX will be used if available."</action>
 </step>
 
 <step n="2" goal="Execute Change Analysis Checklist">
@@ -192,8 +225,8 @@ Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
 <action>Section 5: Implementation Handoff</action>
 
 - Categorize change scope:
-  - Minor: Direct implementation by dev team
-  - Moderate: Backlog reorganization needed (PO/SM)
+  - Minor: Direct implementation by Developer agent
+  - Moderate: Backlog reorganization needed (PO/DEV)
   - Major: Fundamental replan required (PM/Architect)
 - Specify handoff recipients and their responsibilities
 - Define success criteria for implementation
@@ -219,8 +252,8 @@ Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
   <action>Finalize Sprint Change Proposal document</action>
   <action>Determine change scope classification:</action>
 
-- **Minor**: Can be implemented directly by development team
-- **Moderate**: Requires backlog reorganization and PO/SM coordination
+- **Minor**: Can be implemented directly by Developer agent
+- **Moderate**: Requires backlog reorganization and PO/DEV coordination
 - **Major**: Needs fundamental replan with PM/Architect involvement
 
 <action>Provide appropriate handoff based on scope:</action>
@@ -228,12 +261,12 @@ Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
 </check>
 
 <check if="Minor scope">
-  <action>Route to: Development team for direct implementation</action>
+  <action>Route to: Developer agent for direct implementation</action>
   <action>Deliverables: Finalized edit proposals and implementation tasks</action>
 </check>
 
 <check if="Moderate scope">
-  <action>Route to: Product Owner / Scrum Master agents</action>
+  <action>Route to: Product Owner / Developer agents</action>
   <action>Deliverables: Sprint Change Proposal + backlog reorganization plan</action>
 </check>
 
@@ -261,7 +294,8 @@ Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
 - Implementation handoff plan
 
 <action>Report workflow completion to user with personalized message: "Correct Course workflow complete, {user_name}!"</action>
-<action>Remind user of success criteria and next steps for implementation team</action>
+<action>Remind user of success criteria and next steps for Developer agent</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>
 </step>
 
 </workflow>

package/src/{xmc/workflows → xmc-skills}/4-implementation/xiaoma-correct-course/checklist.md

@@ -217,8 +217,8 @@
 <check-item id="5.5">
 <prompt>Establish agent handoff plan</prompt>
 <action>Identify which roles/agents will execute the changes:</action>
-  - Development team (for implementation)
-  - Product Owner / Scrum Master (for backlog changes)
+  - Developer agent (for implementation)
+  - Product Owner / Developer (for backlog changes)
   - Product Manager / Architect (for strategic changes)
 <action>Define responsibilities for each role</action>
 <status>[ ] Done / [ ] N/A / [ ] Action-needed</status>

package/src/xmc-skills/4-implementation/xiaoma-correct-course/customize.toml

@@ -0,0 +1,41 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for xiaoma-correct-course. 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 sprint changes require PO sign-off before execution."
+#   - 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 Step 6 (Workflow Completion),
+# after the Sprint Change Proposal is finalized and handoff is confirmed. Override wins.
+# Leave empty for no custom post-completion behavior.
+
+on_complete = ""

package/src/{xmc/workflows/4-implementation/xiaoma-create-story/workflow.md → xmc-skills/4-implementation/xiaoma-create-story/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: xiaoma-create-story
+description: 'Creates a dedicated story file with all the context the agent will need to implement it later. Use when the user says "create the next story" or "create story [story identifier]"'
+---
+
 # Create Story Workflow
 
 **Goal:** Create a comprehensive story file that gives the dev agent everything needed for flawless implementation.
@@ -11,11 +16,36 @@
 - SAVE QUESTIONS: If you think of questions or clarifications during analysis, save them for the end after the complete story is written
 - ZERO USER INTERVENTION: Process should be fully automated except for initial epic/story selection or missing documents
 
----
+## Conventions
+
+- Bare paths (e.g. `discover-inputs.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
 
-## INITIALIZATION
+Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding.
 
-### Configuration Loading
+### 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:
 
@@ -25,7 +55,17 @@ Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
 - `planning_artifacts`, `implementation_artifacts`
 - `date` as system-generated current datetime
 
-### Paths
+### Step 5: Greet the User
+
+If running headless (no interactive user — e.g. invoked by an auto-\* pipeline), follow `references/headless.md` for the whole run instead of greeting. Otherwise greet `{user_name}`, 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.
+
+## Paths
 
 - `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
 - `epics_file` = `{planning_artifacts}/epics.md`
@@ -33,10 +73,9 @@ Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
 - `architecture_file` = `{planning_artifacts}/architecture.md`
 - `ux_file` = `{planning_artifacts}/*ux*.md`
 - `story_title` = "" (will be elicited if not derivable)
-- `project_context` = `**/project-context.md` (load if exists)
 - `default_output_file` = `{implementation_artifacts}/{{story_key}}.md`
 
-### Input Files
+## Input Files
 
 | Input | Description | Path Pattern(s) | Load Strategy |
 |-------|-------------|------------------|---------------|
@@ -45,9 +84,7 @@ Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
 | ux | UX design (fallback - epics file should have relevant sections) | whole: `{planning_artifacts}/*ux*.md`, sharded: `{planning_artifacts}/*ux*/*.md` | SELECTIVE_LOAD |
 | epics | Enhanced epics+stories file with BDD and source hints | whole: `{planning_artifacts}/*epic*.md`, sharded: `{planning_artifacts}/*epic*/*.md` | SELECTIVE_LOAD |
 
----
-
-## EXECUTION
+## Execution
 
 <workflow>
 
@@ -213,8 +250,7 @@ Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
 
   <!-- Load all available content through discovery protocol -->
   <action>Read fully and follow `./discover-inputs.md` to load all input files</action>
-  <note>Available content: {epics_content}, {prd_content}, {architecture_content}, {ux_content},
-  {project_context}</note>
+  <note>Available content: {epics_content}, {prd_content}, {architecture_content}, {ux_content}, plus the project-context facts loaded during activation via `persistent_facts`.</note>
 
   <!-- Analyze epics file for story foundation -->
   <action>From {epics_content}, extract Epic {{epic_num}} complete context:</action> **EPIC ANALYSIS:** - Epic
@@ -266,6 +302,18 @@ Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
   processes - **Integration Patterns:** External service integrations, data flows <action>Extract any story-specific requirements that the
   developer MUST follow</action>
   <action>Identify any architectural decisions that override previous patterns</action>
+
+  <!-- Read existing code being modified — non-negotiable -->
+  <critical>📂 READ FILES BEING MODIFIED — skipping this is the primary cause of implementation failures and review cycles</critical>
+  <action>From the architecture directory structure, identify every file marked UPDATE (not NEW) that this story will touch</action>
+  <action>Read each relevant UPDATE file completely. For each one, document in dev notes:
+    - Current state: what it does today (state machine, API calls, data shapes, existing behaviors)
+    - What this story changes: the specific sections or behaviors being modified
+    - What must be preserved: existing interactions and behaviors the story must not break
+  </action>
+  <critical>A story implementation must leave the system working end-to-end — not just satisfy its stated ACs.
+  If a behavior is required for the feature to work correctly in the existing system, it is a requirement
+  whether or not it is explicitly written in the story. The dev agent owns this.</critical>
 </step>
 
 <step n="4" goal="Web research for latest technical specifics">
@@ -375,6 +423,7 @@ Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
 
     **The developer now has everything needed for flawless implementation!**
   </output>
+  <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>
 </step>
 
 </workflow>

package/src/xmc-skills/4-implementation/xiaoma-create-story/customize.toml

@@ -0,0 +1,41 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for xiaoma-create-story. 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 stories must include testable acceptance criteria."
+#   - 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 Step 6 (Update sprint status and finalize),
+# after the story file is saved and sprint-status.yaml is updated. Override wins.
+# Leave empty for no custom post-completion behavior.
+
+on_complete = ""

package/src/xmc-skills/4-implementation/xiaoma-create-story/references/headless.md

@@ -0,0 +1,32 @@
+# Headless Mode
+
+Load this file when xiaoma-create-story is invoked headless (no interactive user — e.g. by auto-prd-to-stories step-04, auto-story-pipeline, or auto-story-pipeline-batch). Follow it for the whole run.
+
+## Detection
+
+Headless mode is in effect when any of the following is true:
+
+- the invoking caller sets a `headless: true` flag (or equivalent argument the harness exposes),
+- the invocation is from another skill or a non-interactive runner (no TTY, no user message stream),
+- `{workflow.activation_steps_prepend}` includes an entry that explicitly declares headless,
+- the first message comes from an automation context that pre-supplies the story key + inputs and asks for the story-file path back.
+
+When ambiguous, default to interactive.
+
+## Inputs the caller is expected to provide
+
+- `sprint-status.yaml` (the story queue) and `epics.md` / `prd.md` (story source),
+- a target story key if a specific story is required; otherwise auto-discover the first `backlog` story,
+- `architecture_absent` (boolean) — whether architecture docs exist.
+
+## General
+
+Do not ask, do not greet. Auto-discover (or use the provided) story key and walk every step to completion; auto-proceed through any prompt — never halt for input.
+
+The Step-6 checklist (`checklist.md`) is an interactive "quality-competition" review by default. In headless, perform that review **internally** — apply the warranted improvements to the story directly — instead of presenting the all/critical/select/none menu.
+
+Honor `architecture_absent`: when no architecture source covers a story's data model or logic, write the literal `TBD by architect — <specific question>` rather than fabricating detail or silently omitting the subsection. Record every inferred value as an assumption.
+
+## Completion
+
+End by writing the story file `{story-key}.md` at status `ready-for-dev` (using the same slug convention as sprint-planning) and returning its path. Ignore the Step-6 "next steps" guidance (run dev-story / code-review) — the calling pipeline handles what comes next.