@zeyue0329/xiaoma-cli 1.12.0 → 1.15.0

package/src/xmc-skills/3-solutioning/xiaoma-create-architecture/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: xiaoma-create-architecture
+description: 'Create architecture solution design decisions for AI agent consistency. Use when the user says "lets create architecture" or "create technical architecture" or "create a solution design"'
+---
+
+# Architecture Workflow
+
+**Goal:** Create comprehensive architecture decisions through collaborative step-by-step discovery that ensures AI agents implement consistently.
+
+**Your Role:** You are an architectural facilitator collaborating with a peer. This is a partnership, not a client-vendor relationship. You bring structured thinking and architectural knowledge, while the user brings domain expertise and product vision. Work together as equals to make decisions that prevent implementation conflicts.
+
+## Conventions
+
+- Bare paths (e.g. `steps/step-01-init.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.
+
+## WORKFLOW ARCHITECTURE
+
+This uses **micro-file architecture** for disciplined execution:
+
+- Each step is a self-contained file with embedded rules
+- Sequential progression with user control at each step
+- Document state tracked in frontmatter
+- Append-only document building through conversation
+- You NEVER proceed to a step file if the current step file indicates the user must approve and indicate continuation.
+
+## On Activation
+
+### Step 1: Resolve the Workflow Block
+
+Run: `node {project-root}/_xiaoma/scripts/resolve_customization.js --skill {skill-root} --key workflow`
+
+**If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
+
+1. `{skill-root}/customize.toml` — defaults
+2. `{project-root}/_xiaoma/custom/{skill-name}.toml` — team overrides
+3. `{project-root}/_xiaoma/custom/{skill-name}.user.toml` — personal overrides
+
+Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.
+
+### Step 2: Execute Prepend Steps
+
+Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding.
+
+### Step 3: Load Persistent Facts
+
+Treat every entry in `{workflow.persistent_facts}` as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim.
+
+### Step 4: Load Config
+
+Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
+- Use `{user_name}` for greeting
+- Use `{communication_language}` for all communications
+- Use `{document_output_language}` for output documents
+- Use `{planning_artifacts}` for output location and artifact scanning
+- Use `{project_knowledge}` for additional context scanning
+
+### Step 5: Greet the User
+
+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.
+
+## Execution
+
+Read fully and follow: `./steps/step-01-init.md` to begin the workflow.
+
+**Note:** Input document discovery and all initialization protocols are handled in step-01-init.md.

package/src/xmc-skills/3-solutioning/xiaoma-create-architecture/customize.toml

@@ -0,0 +1,41 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for xiaoma-create-architecture. 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. "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",
+]
+
+# Scalar: executed when the workflow reaches Step 8 (Architecture Completion & Handoff),
+# after the architecture document frontmatter is updated and next-steps guidance is given.
+# Override wins. Leave empty for no custom post-completion behavior.
+
+on_complete = ""

package/src/xmc-skills/3-solutioning/xiaoma-create-architecture/references/headless.md

@@ -0,0 +1,37 @@
+# Headless Mode
+
+Load this file when xiaoma-create-architecture is invoked headless (no interactive user — e.g. by an auto-\* pipeline such as auto-requirements-pipeline step-07 or auto-full-pipeline). 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 inputs and asks for the architecture artifact path back.
+
+When ambiguous, default to interactive.
+
+## Inputs the caller is expected to provide
+
+The caller passes inputs in their first message (free-form; every field below should be present when applicable):
+
+- the `prd.md` path (or a workspace containing one) — the primary input,
+- `epics.md` if epics drive the architecture scope,
+- `current-architecture-analysis.md` if a brownfield / existing-codebase analysis exists,
+- the output location if a specific run folder is required (otherwise bind the default `{planning_artifacts}`).
+
+Anything not provided is inferred from the inputs/workspace or recorded as an assumption — do not invent technology choices, scale targets, or scope decisions to fill gaps; record them.
+
+## General
+
+Do not ask, do not greet. Complete every step using what is provided, what exists in the workspace, or what you can discover yourself. Walk all step files in order to completion; at every `[C] Continue` / approval / menu prompt, auto-select the proceed/continue option and keep going — never halt for input. The `[A] Advanced Elicitation` / `[P] Party Mode` menu options are skipped in headless (auto-select `[C]`).
+
+Record every value you inferred without caller confirmation as an assumption inside the architecture document (or its decision log), and every gap that needs a human decision as an explicit open question — rather than fabricating a confident answer.
+
+## Mode-specific overrides
+
+- **Stale artifact.** If a prior `architecture.md` already exists for this workspace, auto-select the "Start over" / overwrite option (do not prompt) and regenerate from the current PRD + epics.
+- **Greenfield input.** If no `current-architecture-analysis.md` exists (greenfield), design from the PRD + epics from scratch; do not block on the absence of an existing-codebase analysis.
+- **Completion.** End by writing `architecture.md` to the output location and returning its path. If a required input was missing and could not be inferred, still produce the best-effort artifact and mark the unresolved gaps as open questions rather than halting.

package/src/{xmc/workflows → xmc-skills}/3-solutioning/xiaoma-create-architecture/steps/step-07-validation.md

@@ -227,37 +227,39 @@ Prepare the content to append to the document:
 
 ### Architecture Completeness Checklist
 
-**✅ Requirements Analysis**
+Mark each item `[x]` only if validation confirms it; leave `[ ]` if it is missing, partial, or unverified. Any unchecked item must be reflected in the Gap Analysis above and in the Overall Status below.
 
-- [x] Project context thoroughly analyzed
-- [x] Scale and complexity assessed
-- [x] Technical constraints identified
-- [x] Cross-cutting concerns mapped
+**Requirements Analysis**
 
-**✅ Architectural Decisions**
+- [ ] Project context thoroughly analyzed
+- [ ] Scale and complexity assessed
+- [ ] Technical constraints identified
+- [ ] Cross-cutting concerns mapped
 
-- [x] Critical decisions documented with versions
-- [x] Technology stack fully specified
-- [x] Integration patterns defined
-- [x] Performance considerations addressed
+**Architectural Decisions**
 
-**✅ Implementation Patterns**
+- [ ] Critical decisions documented with versions
+- [ ] Technology stack fully specified
+- [ ] Integration patterns defined
+- [ ] Performance considerations addressed
 
-- [x] Naming conventions established
-- [x] Structure patterns defined
-- [x] Communication patterns specified
-- [x] Process patterns documented
+**Implementation Patterns**
 
-**✅ Project Structure**
+- [ ] Naming conventions established
+- [ ] Structure patterns defined
+- [ ] Communication patterns specified
+- [ ] Process patterns documented
 
-- [x] Complete directory structure defined
-- [x] Component boundaries established
-- [x] Integration points mapped
-- [x] Requirements to structure mapping complete
+**Project Structure**
+
+- [ ] Complete directory structure defined
+- [ ] Component boundaries established
+- [ ] Integration points mapped
+- [ ] Requirements to structure mapping complete
 
 ### Architecture Readiness Assessment
 
-**Overall Status:** READY FOR IMPLEMENTATION
+**Overall Status:** {{READY FOR IMPLEMENTATION | READY WITH MINOR GAPS | NOT READY}} (choose READY FOR IMPLEMENTATION only when all 16 checklist items are `[x]` and no Critical Gaps remain; choose NOT READY when any Critical Gap is open or any Requirements Analysis or Architectural Decisions item is unchecked; otherwise READY WITH MINOR GAPS)
 
 **Confidence Level:** {{high/medium/low}} based on validation results
 

package/src/{xmc/workflows → xmc-skills}/3-solutioning/xiaoma-create-architecture/steps/step-08-complete.md

@@ -74,3 +74,9 @@ Upon Completion of task output: offer to answer any questions about the Architec
 This is the final step of the Architecture workflow. The user now has a complete, validated architecture document ready for AI agent implementation.
 
 The architecture will serve as the single source of truth for all technical decisions, ensuring consistent implementation across the entire project development lifecycle.
+
+## 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-skills/3-solutioning/xiaoma-create-epics-and-stories/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: xiaoma-create-epics-and-stories
+description: 'Break requirements into epics and user stories. Use when the user says "create the epics and stories list"'
+---
+
+# Create Epics and Stories
+
+**Goal:** Transform PRD requirements and Architecture decisions into comprehensive stories organized by user value, creating detailed, actionable stories with complete acceptance criteria for the Developer agent.
+
+**Your Role:** In addition to your name, communication_style, and persona, you are also a product strategist and technical specifications writer collaborating with a product owner. This is a partnership, not a client-vendor relationship. You bring expertise in requirements decomposition, technical implementation context, and acceptance criteria writing, while the user brings their product vision, user needs, and business requirements. Work together as equals.
+
+## Conventions
+
+- Bare paths (e.g. `steps/step-01-validate-prerequisites.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.
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+### Core Principles
+
+- **Micro-file Design**: Each step toward the overall goal is a self-contained instruction file; adhere to one file at a time, as directed
+- **Just-In-Time Loading**: Only 1 current step file will be loaded and followed to completion - never load future step files until told to do so
+- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
+- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document
+- **Append-Only Building**: Build documents by appending content as directed to the output file
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
+6. **LOAD NEXT**: When directed, read fully and follow the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps or optimize the sequence
+- 💾 **ALWAYS** update frontmatter of output files when writing the final output for a specific step
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+
+## On Activation
+
+### Step 1: Resolve the Workflow Block
+
+Run: `node {project-root}/_xiaoma/scripts/resolve_customization.js --skill {skill-root} --key workflow`
+
+**If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
+
+1. `{skill-root}/customize.toml` — defaults
+2. `{project-root}/_xiaoma/custom/{skill-name}.toml` — team overrides
+3. `{project-root}/_xiaoma/custom/{skill-name}.user.toml` — personal overrides
+
+Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.
+
+### Step 2: Execute Prepend Steps
+
+Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding.
+
+### Step 3: Load Persistent Facts
+
+Treat every entry in `{workflow.persistent_facts}` as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim.
+
+### Step 4: Load Config
+
+Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
+- Use `{user_name}` for greeting
+- Use `{communication_language}` for all communications
+- Use `{document_output_language}` for output documents
+- Use `{planning_artifacts}` for output location and artifact scanning
+- Use `{project_knowledge}` for additional context scanning
+
+### Step 5: Greet the User
+
+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.
+
+## Execution
+
+Read fully and follow: `./steps/step-01-validate-prerequisites.md` to begin the workflow.

package/src/xmc-skills/3-solutioning/xiaoma-create-epics-and-stories/customize.toml

@@ -0,0 +1,41 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for xiaoma-create-epics-and-stories. 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 epics must deliver complete end-to-end user value."
+#   - 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 4 (Final Validation) and the
+# user confirms [C] Complete — after the epics.md is saved and xiaoma-help is invoked.
+# Override wins. Leave empty for no custom post-completion behavior.
+
+on_complete = ""

package/src/xmc-skills/3-solutioning/xiaoma-create-epics-and-stories/references/headless.md

@@ -0,0 +1,35 @@
+# Headless Mode
+
+Load this file when xiaoma-create-epics-and-stories is invoked headless (no interactive user — e.g. by an auto-\* pipeline such as auto-prd-to-stories step-02, auto-requirements-pipeline step-06, or auto-full-pipeline). 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 inputs and asks for the epics artifact path back.
+
+When ambiguous, default to interactive.
+
+## Inputs the caller is expected to provide
+
+- the `prd.md` path (or a workspace containing one) — the primary input,
+- optionally `requirements-analysis.md` and/or `current-architecture-analysis.md` for richer context.
+
+Anything not provided is inferred from the inputs/workspace or recorded as an assumption — do not invent FRs, scope, or acceptance criteria to fill gaps; record them.
+
+## General
+
+Do not ask, do not greet. Auto-confirm discovered input documents and walk every step to completion; at each `[A]pprove / [P]roceed / [C]ontinue` or document-confirmation prompt, auto-select the proceed/continue option and keep going — never halt for input. The `[A] Advanced Elicitation` / `[P] Party Mode` menu options are skipped in headless (auto-select `[C]`).
+
+Produce `epics.md` with: an Epic overview, per-epic FR coverage, BDD (Given/When/Then) acceptance criteria for every story, and an FR Coverage Map covering **every** FR in the PRD. If the PRD has no architecture/UX inputs, annotate those sections "no input this time" rather than blocking. Record every inferred value as an assumption and every gap needing a human decision as an open question.
+
+## Story titles in non-English documents
+
+When `document_output_language` is non-English (e.g. 中文), write story titles in that language, but keep them consistent: the downstream sprint-planning slug strategy converts each title to a stable ASCII key (see xiaoma-sprint-planning "Story ID Conversion Rules"), so the same story must always carry the same title.
+
+## Completion
+
+End by writing `epics.md` to the output location and returning its path.

package/src/{xmc/workflows → xmc-skills}/3-solutioning/xiaoma-create-epics-and-stories/steps/step-02-design-epics.md

@@ -55,7 +55,8 @@ Load {planning_artifacts}/epics.md and review:
 2. **Requirements Grouping**: Group related FRs that deliver cohesive user outcomes
 3. **Incremental Delivery**: Each epic should deliver value independently
 4. **Logical Flow**: Natural progression from user's perspective
-5. **🔗 Dependency-Free Within Epic**: Stories within an epic must NOT depend on future stories
+5. **Dependency-Free Within Epic**: Stories within an epic must NOT depend on future stories
+6. **Implementation Efficiency**: Consider consolidating epics that all modify the same core files into fewer epics
 
 **⚠️ CRITICAL PRINCIPLE:**
 Organize by USER VALUE, not technical layers:
@@ -74,6 +75,18 @@ Organize by USER VALUE, not technical layers:
 - Epic 3: Frontend Components (creates reusable components) - **No user value**
 - Epic 4: Deployment Pipeline (CI/CD setup) - **No user value**
 
+**❌ WRONG Epic Examples (File Churn on Same Component):**
+
+- Epic 1: File Upload (modifies model, controller, web form, web API)
+- Epic 2: File Status (modifies model, controller, web form, web API)
+- Epic 3: File Access permissions (modifies model, controller, web form, web API)
+- All three epics touch the same files — consolidate into one epic with ordered stories
+
+**✅ CORRECT Alternative:**
+
+- Epic 1: File Management Enhancement (upload, status, permissions as stories within one epic)
+- Rationale: Single component, fully pre-designed, no feedback loop between epics
+
 **🔗 DEPENDENCY RULES:**
 
 - Each epic must deliver COMPLETE functionality for its domain
@@ -82,21 +95,38 @@ Organize by USER VALUE, not technical layers:
 
 ### 3. Design Epic Structure Collaboratively
 
-**Step A: Identify User Value Themes**
+**Step A: Assess Context and Identify Themes**
+
+First, assess how much of the solution design is already validated (Architecture, UX, Test Design).
+When the outcome is certain and direction changes between epics are unlikely, prefer fewer but larger epics.
+Split into multiple epics when there is a genuine risk boundary or when early feedback could change direction
+of following epics.
+
+Then, identify user value themes:
 
 - Look for natural groupings in the FRs
 - Identify user journeys or workflows
 - Consider user types and their goals
 
 **Step B: Propose Epic Structure**
-For each proposed epic:
+
+For each proposed epic (considering whether epics share the same core files):
 
 1. **Epic Title**: User-centric, value-focused
 2. **User Outcome**: What users can accomplish after this epic
 3. **FR Coverage**: Which FR numbers this epic addresses
 4. **Implementation Notes**: Any technical or UX considerations
 
-**Step C: Create the epics_list**
+**Step C: Review for File Overlap**
+
+Assess whether multiple proposed epics repeatedly target the same core files. If overlap is significant:
+
+- Distinguish meaningful overlap (same component end-to-end) from incidental sharing
+- Ask whether to consolidate into one epic with ordered stories
+- If confirmed, merge the epic FRs into a single epic, preserving dependency flow: each story must still fit within
+  a single dev agent's context
+
+**Step D: Create the epics_list**
 
 Format the epics_list as:
 

package/src/{xmc/workflows → xmc-skills}/3-solutioning/xiaoma-create-epics-and-stories/steps/step-04-final-validation.md

@@ -90,6 +90,12 @@ Review the complete epic and story breakdown to ensure EVERY FR is covered:
 - Dependencies flow naturally
 - Foundation stories only setup what's needed
 - No big upfront technical work
+- **File Churn Check:** Do multiple epics repeatedly modify the same core files?
+  - Assess whether the overlap pattern suggests unnecessary churn or is incidental
+  - If overlap is significant: Validate that splitting provides genuine value (risk mitigation, feedback loops, context size limits)
+  - If no justification for the split: Recommend consolidation into fewer epics
+  - ❌ WRONG: Multiple epics each modify the same core files with no feedback loop between them
+  - ✅ RIGHT: Epics target distinct files/components, OR consolidation was explicitly considered and rejected with rationale
 
 ### 5. Dependency Validation (CRITICAL)
 
@@ -129,3 +135,9 @@ When C is selected, the workflow is complete and the epics.md is ready for devel
 Epics and Stories complete. Invoke the `xiaoma-help` skill.
 
 Upon Completion of task output: offer to answer any questions about the Epics and Stories.
+
+## 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-skills/3-solutioning/xiaoma-generate-project-context/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: xiaoma-generate-project-context
+description: 'Create project-context.md with AI rules. Use when the user says "generate project context" or "create project context"'
+---
+
+# Generate Project Context Workflow
+
+**Goal:** Create a concise, optimized `project-context.md` file containing critical rules, patterns, and guidelines that AI agents must follow when implementing code. This file focuses on unobvious details that LLMs need to be reminded of.
+
+**Your Role:** You are a technical facilitator working with a peer to capture the essential implementation rules that will ensure consistent, high-quality code generation across all AI agents working on the project.
+
+## Conventions
+
+- Bare paths (e.g. `steps/step-01-discover.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.
+
+## WORKFLOW ARCHITECTURE
+
+This uses **micro-file architecture** for disciplined execution:
+
+- Each step is a self-contained file with embedded rules
+- Sequential progression with user control at each step
+- Document state tracked in frontmatter
+- Focus on lean, LLM-optimized content generation
+- You NEVER proceed to a step file if the current step file indicates the user must approve and indicate continuation.
+
+## On Activation
+
+### Step 1: Resolve the Workflow Block
+
+Run: `node {project-root}/_xiaoma/scripts/resolve_customization.js --skill {skill-root} --key workflow`
+
+**If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
+
+1. `{skill-root}/customize.toml` — defaults
+2. `{project-root}/_xiaoma/custom/{skill-name}.toml` — team overrides
+3. `{project-root}/_xiaoma/custom/{skill-name}.user.toml` — personal overrides
+
+Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.
+
+### Step 2: Execute Prepend Steps
+
+Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding.
+
+### Step 3: Load Persistent Facts
+
+Treat every entry in `{workflow.persistent_facts}` as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim.
+
+### Step 4: Load Config
+
+Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
+- Use `{user_name}` for greeting
+- Use `{communication_language}` for all communications
+- Use `{document_output_language}` for output documents
+- Use `{planning_artifacts}` for output location and artifact scanning
+- Use `{project_knowledge}` for additional context scanning
+
+### Step 5: Greet the User
+
+Greet `{user_name}`, 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
+
+- `output_file` = `{output_folder}/project-context.md`
+
+## Execution
+
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+Load and execute `./steps/step-01-discover.md` to begin the workflow.
+
+**Note:** Input document discovery and initialization protocols are handled in step-01-discover.md.

package/src/xmc-skills/3-solutioning/xiaoma-generate-project-context/customize.toml

@@ -0,0 +1,41 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for xiaoma-generate-project-context. 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 artifacts must follow org naming conventions."
+#   - 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 3 (Context Completion & Finalization),
+# after the project-context.md file is optimized and saved. Override wins.
+# Leave empty for no custom post-completion behavior.
+
+on_complete = ""

package/src/{xmc/workflows → xmc-skills/3-solutioning}/xiaoma-generate-project-context/steps/step-03-complete.md

@@ -276,3 +276,9 @@ Your project context will help ensure high-quality, consistent implementation ac
 This is the final step of the Generate Project Context workflow. The user now has a comprehensive, optimized project context file that will ensure consistent, high-quality implementation across all AI agents working on the project.
 
 The project context file serves as the critical "rules of the road" that agents need to implement code consistently with the project's standards and patterns.
+
+## 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.