@zeyue0329/xiaoma-cli 1.12.0 → 1.15.0

package/src/core-skills/xiaoma-help/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: xiaoma-help
+description: 'Analyzes current state and user query to answer XiaoMa questions or recommend the next skill(s) to use. Use when user asks for help, xiaoma help, what to do next, or what to start with in XiaoMa.'
+---
+
+# XiaoMa Help
+
+## Purpose
+
+Help the user understand where they are in their XiaoMa workflow and what to do next, and also answer broader questions when asked that could be augmented with remote sources such as module documentation sources.
+
+## Desired Outcomes
+
+When this skill completes, the user should:
+
+1. **Know where they are** — which module and phase they're in, what's already been completed
+2. **Know what to do next** — the next recommended and/or required step, with clear reasoning
+3. **Know how to invoke it** — skill name, menu code, action context, and any args that shortcut the conversation
+4. **Get offered a quick start** — when a single skill is the clear next step, offer to run it for the user right now rather than just listing it
+5. **Feel oriented, not overwhelmed** — surface only what's relevant to their current position; don't dump the entire catalog
+6. **Get answers to general questions** — when the question doesn't map to a specific skill, use the module's registered documentation to give a grounded answer
+
+## Data Sources
+
+- **Catalog**: `{project-root}/_xiaoma/_config/xiaoma-help.csv` — assembled manifest of all installed module skills
+- **Config**: `config.yaml` and `user-config.yaml` files in `{project-root}/_xiaoma/` and its subfolders — resolve `output-location` variables, provide `communication_language` and `project_knowledge`
+- **Artifacts**: Files matching `outputs` patterns at resolved `output-location` paths reveal which steps are possibly completed; their content may also provide grounding context for recommendations
+- **Project knowledge**: If `project_knowledge` resolves to an existing path, read it for grounding context. Never fabricate project-specific details.
+- **Module docs**: Rows with `_meta` in the `skill` column carry a URL or path in `output-location` pointing to the module's documentation (e.g., llms.txt). Fetch and use these to answer general questions about that module.
+
+## CSV Interpretation
+
+The catalog uses this format:
+
+```
+module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
+```
+
+**Phases** determine the high-level flow:
+- `anytime` — available regardless of workflow state
+- Numbered phases (`1-analysis`, `2-planning`, etc.) flow in order; naming varies by module
+
+**Sequencing** determines recommended ordering within and across phases (these are soft suggestions, not hard gates — see `required` for gating):
+- `preceded-by` — skills that should ideally complete before this one
+- `followed-by` — skills that should ideally run after this one
+- Format: `skill-name` for single-action skills, `skill-name:action` for multi-action skills
+
+**Required gates**:
+- `required=true` items must complete before the user can meaningfully proceed to later phases
+- A phase with no required items is entirely optional — recommend it but be clear about what's actually required next
+
+**Completion detection**:
+- Search resolved output paths for `outputs` patterns
+- Fuzzy-match found files to catalog rows
+- User may also state completion explicitly, or it may be evident from the current conversation
+
+**Descriptions carry routing context** — some contain cycle info and alternate paths (e.g., "back to DS if fixes needed"). Read them as navigation hints, not just display text.
+
+## Response Format
+
+For each recommended item, present:
+- `[menu-code]` **Display name** — e.g., "[PR] PRD"
+- Skill name in backticks — e.g., `xiaoma-prd`
+- For multi-action skills: action invocation context — e.g., "tech-writer lets create a mermaid diagram!"
+- Description if present in CSV; otherwise your existing knowledge of the skill suffices
+- Args if available
+
+**Ordering**: Show optional items first, then the next required item. Make it clear which is which.
+
+## Constraints
+
+- Present all output in `{communication_language}`
+- Recommend running each skill in a **fresh context window**
+- Match the user's tone — conversational when they're casual, structured when they want specifics
+- If the active module is ambiguous, retrieve all meta rows remote sources to find relevant info also to help answer their question

package/src/{core/skills/xiaoma-index-docs/workflow.md → core-skills/xiaoma-index-docs/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: xiaoma-index-docs
+description: 'Generates or updates an index.md to reference all docs in the folder. Use if user requests to create or update an index of all files in a specific folder'
+---
+
 # Index Docs
 
 **Goal:** Generate or update an index.md to reference all docs in a target folder.

package/src/core-skills/xiaoma-party-mode/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: xiaoma-party-mode
+description: 'Orchestrates group discussions between installed XiaoMa agents, enabling natural multi-agent conversations where each agent is a real subagent with independent thinking. Use when user requests party mode, wants multiple agent perspectives, group discussion, roundtable, or multi-agent conversation about their project.'
+---
+
+# Party Mode
+
+Facilitate roundtable discussions where XiaoMa agents participate as **real subagents** — each spawned independently via the Agent tool so they think for themselves. You are the orchestrator: you pick voices, build context, spawn agents, and present their responses. In the default subagent mode, never generate agent responses yourself — that's the whole point. In `--solo` mode, you roleplay all agents directly.
+
+## Why This Matters
+
+The whole point of party mode is that each agent produces a genuinely independent perspective. When one LLM roleplays multiple characters, the "opinions" tend to converge and feel performative. By spawning each agent as its own subagent process, you get real diversity of thought — agents that actually disagree, catch things the others miss, and bring their authentic expertise to bear.
+
+## Arguments
+
+Party mode accepts optional arguments when invoked:
+
+- `--model <model>` — Force all subagents to use a specific model (e.g. `--model haiku`, `--model opus`). When omitted, choose the model that fits the round: use a faster model (like `haiku`) for brief or reactive responses, and the default model for deep or complex topics. Match model weight to the depth of thinking the round requires.
+- `--solo` — Run without subagents. Instead of spawning independent agents, roleplay all selected agents yourself in a single response. This is useful when subagents aren't available, when speed matters more than independence, or when the user just prefers it. Announce solo mode on activation so the user knows responses come from one LLM.
+
+## On Activation
+
+1. **Parse arguments** — check for `--model` and `--solo` flags from the user's invocation.
+
+2. Load config from `{project-root}/_xiaoma/core/config.yaml` and resolve:
+  - Use `{user_name}` for greeting
+  - Use `{communication_language}` for all communications
+
+3. **Resolve the agent roster** by running:
+
+    ```bash
+    node {project-root}/_xiaoma/scripts/resolve_config.js --project-root {project-root} --key agents
+    ```
+
+    The resolver merges four layers in order: `_xiaoma/config.toml` (installer base, team-scoped), `_xiaoma/config.user.toml` (installer base, user-scoped), `_xiaoma/custom/config.toml` (team overrides), and `_xiaoma/custom/config.user.toml` (personal overrides). Each entry under `agents` is keyed by the agent's `code` and carries `name`, `title`, `icon`, `description`, `module`, and `team`. Build an internal roster of available agents from those fields.
+
+4. **Load project context** — search for `**/project-context.md`. If found, hold it as background context that gets passed to agents when relevant.
+
+5. **Welcome the user** — briefly introduce party mode (mention if solo mode is active). Show the full agent roster (icon + name + one-line role) so the user knows who's available. Ask what they'd like to discuss.
+
+## The Core Loop
+
+For each user message:
+
+### 1. Pick the Right Voices
+
+Choose 2-4 agents whose expertise is most relevant to what the user is asking. Use your judgment — you know each agent's role and identity from the manifest. Some guidelines:
+
+- **Simple question**: 2 agents with the most relevant expertise
+- **Complex or cross-cutting topic**: 3-4 agents from different domains
+- **User names specific agents**: Always include those, plus 1-2 complementary voices
+- **User asks an agent to respond to another**: Spawn just that agent with the other's response as context
+- **Rotate over time** — avoid the same 2 agents dominating every round
+
+### 2. Build Context and Spawn
+
+For each selected agent, spawn a subagent using the Agent tool. Each subagent gets:
+
+**The agent prompt** (built from the resolved roster entry):
+```
+You are {name} ({title}), a XiaoMa agent in a collaborative roundtable discussion.
+
+## Your Persona
+{icon} {name} — {description}
+
+## Discussion Context
+{summary of the conversation so far — keep under 400 words}
+
+{project context if relevant}
+
+## What Other Agents Said This Round
+{if this is a cross-talk or reaction request, include the responses being reacted to — otherwise omit this section}
+
+## The User's Message
+{the user's actual message}
+
+## Guidelines
+- Respond authentically as {name}. Your voice, ethos, and speech pattern all come from the description above — embody them fully.
+- Start your response with: {icon} **{name}:**
+- Speak in {communication_language}.
+- Scale your response to the substance — don't pad. If you have a brief point, make it briefly.
+- Disagree with other agents when your perspective tells you to. Don't hedge or be polite about it.
+- If you have nothing substantive to add, say so in one sentence rather than manufacturing an opinion.
+- You may ask the user direct questions if something needs clarification.
+- Do NOT use tools. Just respond with your perspective.
+```
+
+**Spawn all agents in parallel** — put all Agent tool calls in a single response so they run concurrently. If `--model` was specified, use that model for all subagents. Otherwise, pick the model that matches the round — faster/cheaper models for brief takes, the default for substantive analysis.
+
+**Solo mode** — if `--solo` is active, skip spawning. Instead, generate all agent responses yourself in a single message, staying faithful to each agent's persona. Keep responses clearly separated with each agent's icon and name header.
+
+### 3. Present Responses
+
+Present each agent's full response to the user — distinct, complete, and in their own voice. The user is here to hear the agents speak, not to read your synthesis of what they think. Whether the responses came from subagents or you generated them in solo mode, the rule is the same: each agent's perspective gets its own unabridged section. Never blend, paraphrase, or condense agent responses into a summary.
+
+The format is simple: each agent's response one after another, separated by a blank line. No introductions, no "here's what they said", no framing — just the responses themselves.
+
+After all agent responses are presented in full, you may optionally add a brief **Orchestrator Note** — flagging a disagreement worth exploring, or suggesting an agent to bring in next round. Keep this short and clearly labeled so it's not confused with agent speech.
+
+### 4. Handle Follow-ups
+
+The user drives what happens next. Common patterns:
+
+| User says... | You do... |
+|---|---|
+| Continues the general discussion | Pick fresh agents, repeat the loop |
+| "xiaojia, what do you think about what xiaoshe said?" | Spawn just xiaojia with xiaoshe's response as context |
+| "Bring in xiaokai on this" | Spawn xiaokai with a summary of the discussion so far |
+| "I agree with xiaochan, let's go deeper on that" | Spawn xiaochan + 1-2 others to expand on xiaochan's point |
+| "What would xiaofen and xiaokai think about xiaojia's approach?" | Spawn xiaofen and xiaokai with xiaojia's response as context |
+| Asks a question directed at everyone | Back to step 1 with all agents |
+
+The key insight: you can spawn any combination at any time. One agent, two agents reacting to a third, the whole roster — whatever serves the conversation. Each spawn is cheap and independent.
+
+## Keeping Context Manageable
+
+As the conversation grows, you'll need to summarize prior rounds rather than passing the full transcript to each subagent. Aim to keep the "Discussion Context" section under 400 words — a tight summary of what's been discussed, what positions agents have taken, and what the user seems to be driving toward. Update this summary every 2-3 rounds or when the topic shifts significantly.
+
+## When Things Go Sideways
+
+- **Agents are all saying the same thing**: Bring in a contrarian voice, or ask a specific agent to play devil's advocate by framing the prompt that way.
+- **Discussion is going in circles**: Summarize the impasse and ask the user what angle they want to explore next.
+- **User seems disengaged**: Ask directly — continue, change topic, or wrap up?
+- **Agent gives a weak response**: Don't retry. Present it and let the user decide if they want more from that agent.
+
+## Exit
+
+When the user says they're done (any natural phrasing — "thanks", "that's all", "end party mode", etc.), give a brief wrap-up of the key takeaways from the discussion and return to normal mode. Don't force exit triggers — just read the room.

package/src/{core/skills/xiaoma-review-adversarial-general/workflow.md → core-skills/xiaoma-review-adversarial-general/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: xiaoma-review-adversarial-general
+description: 'Perform a Cynical Review and produce a findings report. Use when the user requests a critical review of something'
+---
+
 # Adversarial Review (General)
 
 **Goal:** Cynically review content and produce findings.

package/src/{core/skills/xiaoma-review-edge-case-hunter/workflow.md → core-skills/xiaoma-review-edge-case-hunter/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: xiaoma-review-edge-case-hunter
+description: 'Walk every branching path and boundary condition in content, report only unhandled edge cases. Orthogonal to adversarial review - method-driven not attitude-driven. Use when you need exhaustive edge-case analysis of code, specs, or diffs.'
+---
+
 # Edge Case Hunter Review
 
 **Goal:** You are a pure path tracer. Never comment on whether code is good or bad; only list missing handling.

package/src/{core/skills/xiaoma-shard-doc/workflow.md → core-skills/xiaoma-shard-doc/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: xiaoma-shard-doc
+description: 'Splits large markdown documents into smaller, organized files based on level 2 (default) sections. Use if the user says perform shard document'
+---
+
 # Shard Document
 
 **Goal:** Split large markdown documents into smaller, organized files based on level 2 sections using `npx @kayvan/markdown-tree-parser`.

package/src/core-skills/xiaoma-spec/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: xiaoma-spec
+description: Distill any intent input into the SPEC kernel + companions — the canonical, preservation-validated machine contract for downstream work. Use when the user says "create a spec", "distill this into a spec", "validate this spec", or "update the spec".
+---
+
+# XiaoMa Spec
+## Overview
+
+Canonical transformer for the XiaoMa spec-kernel ecosystem. Takes any intent input — vague idea, brain dump, PRD, GDD, RFC, brief, Slack thread, customer email, meeting transcript, mockups, mixed multi-source — and produces **SPEC.md** carrying the five-field kernel (Why, Capabilities, Constraints, Non-goals, Success signal) plus companion files for load-bearing content that does not fit or would bloat the kernel with expansive line-item detail. Together they are the machine contract every downstream XiaoMa skill consumes.
+
+Multiple skills may call to update the same spec over time.
+
+## Conventions
+
+- Bare paths (e.g. `assets/spec-template.md`) resolve from the skill root.
+- `{skill-root}` is this skill's install dir; `{project-root}` is the working dir.
+- `{workflow.<name>}` resolves to fields in `customize.toml`.
+
+## On Activation
+
+1. Resolve customization: `node {project-root}/_xiaoma/scripts/resolve_customization.js --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly.
+2. Run `{workflow.activation_steps_prepend}`. Treat `{workflow.persistent_facts}` as foundational context (`file:` entries are loaded).
+3. Load `{project-root}/_xiaoma/core/config.yaml` (and `config.user.yaml` if present), root level and `xmc` section. Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`.
+4. Detect mode. **Headless** when any of: no TTY, programmatic caller (another skill or non-interactive runner), or the first message pre-supplies all inputs and asks for an artifact path back. **Interactive** otherwise. In interactive mode, greet by `{user_name}` in `{communication_language}`, stay in that language, and mention that `xiaoma-party-mode` and `xiaoma-advanced-elicitation` are available for deeper exploration on any field.
+
+Run `{workflow.activation_steps_append}`.
+
+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.
+
+## Workspace
+
+The spec is **always a folder** named `{workflow.spec_output_path}/{workflow.run_folder_pattern}`, resolving by default to `{output_folder}/specs/spec-{slug}/`.
+
+`{slug}` describes the thing being specced, not the input shape:
+
+- Source artifact already carries a slug (e.g., `prd-foo-bar-2026-05-23/`): inherit (`foo-bar`).
+- Sparse, in-chat, or multi-source input: interactive asks; headless caller provides it as part of the input. If absent and underivable, headless blocks with `error_code: "missing_slug"`.
+- Same slug = same folder. A second invocation with the same `{slug}` lands at the existing spec folder and updates in place, preserving capability IDs.
+
+**No input.** Interactive: ask the user to share a file path, paste content, explain the idea in detail, or point to a source. Headless: respond with JSON containing `error_code: "insufficient_intent"`.
+
+Inside the spec folder:
+
+```
+<spec-folder>/
+  SPEC.md                  ← uppercase, the kernel
+  <companion-1>.md         ← optional, content-typed (e.g. glossary.md)
+  <companion-2>.md
+  .decision-log.md         ← canonical memory for this spec
+```
+
+## The Operation
+
+Read the input and its ancillary linked materials. If there is no input, follow the no-input branch in **Workspace** (ask or block). If a prior `SPEC.md` exists at the target folder, read it too — the operation becomes an update. Preserve capability IDs; new capabilities get the next unused `CAP-N`; never reuse retired IDs. Otherwise this is a create.
+
+When the input is structured and pre-sorted (a PRD with an addendum, a GDD, a brief produced by an upstream XiaoMa skill), trust the authored separation: lift kernel-fitting content into SPEC.md, lift overflow into appropriately-named companions. When the input is mixed (a brain dump, a transcript, an RFC, a customer email), do the sorting yourself: walk each claim, apply the three-lens load-bearing test (Spec Law rule 7), and route to the kernel field or a companion.
+
+Distill the input into the five-field kernel using `{workflow.spec_template}` as the skeleton. When input is rich, extract directly — no elicitation. When input is sparse, choose: **express** (best-effort distill, every gap becomes an `open_questions[]` entry) or **guided** (walk the five fields with the user one at a time). Headless defaults to express and logs the choice. Interactive asks.
+
+Write lean from the first pass: every sentence must earn its place. Decoration costs tokens and dilutes downstream readers.
+
+If the input is genuinely too thin to distill (e.g. "an app for hikers" with no surrounding context), stop and suggest `xiaoma-prd` (or sibling ceremony skill). This skill distills; it does not coach.
+
+## Load-bearing
+
+A claim is **load-bearing** if any consumer (downstream skill, implementing agent, verification pass) would change a decision without it.
+
+## Companions
+
+When load-bearing content does not fit the five-field kernel, it lives in a companion. The kernel cites it; the companion holds it. Companions are part of the contract; every consumer reads `companions:` in SPEC.md frontmatter to discover them. Companions follow the same lean discipline as SPEC.md (Spec Law rule 8).
+
+**Spawn a companion when the content needs more than one kernel-shape line:** multi-item catalogs (per-entity matrices like archetypes, drinks, modes, routes), tables, diagrams (always), editorial voice rules, long-form reference material the kernel cites by name (glossary, brownfield notes, project conventions). Single-line decision-benders stay in Constraints; intent+success pairs stay in Capabilities. If a kernel field is starting to bullet into sub-bullets, the content has outgrown the kernel and wants a companion.
+
+Companions are either:
+
+- **Spec-authored** companions are written by xiaoma-spec and live as **siblings of SPEC.md** (e.g., `glossary.md`, `patron-archetypes.md`). xiaoma-spec owns them and may edit them on update operations.
+- **Adopted** companions are load-bearing artifacts written by an upstream skill that downstream still needs to read. xiaoma-spec references them into `companions:` by relative path but does NOT edit them (e.g., a `DESIGN.md` or `EXPERIENCE.md` from a UX run, an integration partner's API spec). The originating skill owns them.
+
+Two rules govern companions:
+
+1. **Name spec-authored companions for the content type they hold.** `glossary.md`, `<entity-class>.md` (e.g. `patron-archetypes.md`, `medication-routes.md`, `flight-modes.md`), `stack.md`, `conventions.md`, `brownfield.md`, `architecture-diagrams.md`, `state-machines.md`, `failure-modes.md`, `compliance-references.md`. The principle: "a reader should know what is inside before opening it." Adopted companions keep whatever name their originating skill gave them.
+2. **Diagrams always land in a companion**, regardless of size. SPEC.md kernel holds prose only. Mermaid blocks, ASCII diagrams, and image references all live in a companion (e.g. `architecture-diagrams.md`), with sibling image files referenced from there.
+
+Pre-existing project-wide docs (e.g. `project-context.md`) that downstream needs are listed as **adopted companions**, never duplicated into SPEC.md or a spec-authored companion.
+
+## Spec Law
+
+Every spec must satisfy these eight rules. The operation aims for them; the self-validate sweep enforces them.
+
+1. **Each capability has both `intent` and `success`.** Missing either = not a capability.
+2. **Intents describe WHAT, not HOW.** Implementation prescription belongs in a companion (stack, conventions).
+3. **Constraints actually bend design decisions.** A "constraint" that rules nothing out is decoration.
+4. **Non-goals are explicit.** At least one. Absence means downstream skills fill the vacuum.
+5. **Success signal is concrete enough to test or demonstrate against.** "Users love it" doesn't qualify.
+6. **Capability IDs are stable and unique.** Never reused, never renumbered.
+7. **Preservation.** Every load-bearing source claim lands in SPEC.md or a companion. Wrapper ceremony does not.
+8. **Lean prose.** Every sentence carries load-bearing content. Cut decoration, hedges, backstory, throat-clearing. Applies to SPEC.md, companions, and `.decision-log.md`.
+
+## Self-Validate
+
+After every create or update, sweep the resulting artifact in **two passes** before presenting.
+
+**Pass 1 — Coherence.** Judge the spec against Spec Law rules 1–6 and 8. For anything that fails or feels weak, attempt to fix it without inventing content the input did not support. Calls made without direct confirmation become `assumptions[]`; gaps that could not be filled become `open_questions[]`.
+
+**Pass 2 — Preservation.** Walk the source claim by claim. Confirm each load-bearing claim landed in SPEC.md or a companion. Wrapper-ceremony drops are logged under "Wrapper-only content" so the drop is on the record, not silent.
+
+Append a one-paragraph verdict to `.decision-log.md` covering both passes. In interactive mode, review the verdict with the user. In headless mode, `.decision-log.md` is one of the files returned, so the caller (or its downstream LLM) reads the verdict there.
+
+## Spec with no change signal
+
+When the user points the skill at an existing spec folder (or its SPEC.md) with no change signal, offer to review assumptions or open questions, or determine what they want to do.
+
+## Output
+
+**Interactive** — share the spec folder path conversationally. Name the capability count, the companions produced, and the verdict in one or two sentences. If `assumptions[]` or `open_questions[]` are non-empty, list them (short — one line each) and invite the user to walk through them. Make clear that addressing them can update the source input (if it was a file), the spec, or both — whichever combination the user prefers. Do not dump JSON or present a wall of output.
+
+**Headless** — return JSON per `assets/headless-schemas.md`.
+
+Run `{workflow.on_complete}` if set.
+
+## After Spec is Output
+
+Any update to spec regarding assumptions, open questions, or other changes should be appended to that source's decision log also and offer to update the source.
+
+## Frontmatter conventions
+
+- `companions:` array of `.md` files downstream MUST read alongside SPEC.md to have the full contract. Paths may point inside the spec folder (spec-authored companions like `glossary.md`) or outside it (adopted companions like `../planning-artifacts/ux-designs/ux-foo-bar-2026-05-23/DESIGN.md`). The split between spec-authored and adopted is implicit by path; downstream treats both the same.
+- `sources:` array of paths to files that were **fully absorbed** into the SPEC, with no remaining downstream value (e.g., a PRD whose every load-bearing claim is now in the kernel). Listed for audit and for xiaoma-spec to re-read on update. Downstream does NOT read these. Files that downstream still needs to read belong in `companions:`, not here.
+- **Do not list** decision logs, README files, organizational artifacts, or any operational record of how upstream skills produced their artifacts. Those are not source content; they are process metadata that downstream consumers don't need.

package/src/core-skills/xiaoma-spec/assets/headless-schemas.md

@@ -0,0 +1,33 @@
+# Headless JSON Response
+
+The default invocation is headless: input goes in, JSON comes out. The contract is intentionally tiny — return the outcome and the files touched. Anything else a caller needs is inside those files (SPEC.md, companions, `.decision-log.md`).
+
+## Success
+
+```json
+{
+  "status": "complete",
+  "files": [
+    "_xiaoma-output/specs/spec-quarter-drop/SPEC.md",
+    "_xiaoma-output/specs/spec-quarter-drop/glossary.md",
+    "_xiaoma-output/specs/spec-quarter-drop/.decision-log.md"
+  ]
+}
+```
+
+`files` lists every file written or modified in this run, in any order. The spec folder, kernel filename, decision log location, capabilities, companions, and verdict are all readable from those files; no need to re-encode them in the response.
+
+## Blocked
+
+```json
+{
+  "status": "blocked",
+  "error_code": "insufficient_intent",
+  "reason": "Input was a one-line idea with no surrounding context; too thin to distill. Suggest xiaoma-prd to draw the vision out first."
+}
+```
+
+Defined `error_code` values:
+
+- `insufficient_intent` — input too thin to distill into a kernel.
+- `missing_slug` — input is sparse or multi-source and no slug was provided by the caller or derivable from a source path.

package/src/core-skills/xiaoma-spec/assets/spec-template.md

@@ -0,0 +1,49 @@
+---
+id: SPEC-{slug}
+companions: []     # files downstream MUST read alongside SPEC.md. Paths may point inside the spec folder (spec-authored) or outside it (adopted from an upstream skill).
+sources: []        # files fully absorbed into the SPEC (audit only; downstream does NOT read these). Never decision logs.
+---
+
+> **Canonical contract.** This SPEC and the files in `companions:` are the complete, preservation-validated contract for what to build, test, and validate. Source documents listed in frontmatter are for traceability only — consult them only if you need narrative rationale or prose color this contract intentionally omits.
+
+# {Spec Title}
+
+## Why
+
+{One paragraph naming the force behind this work. A spec can exist for any of:
+  - **a pain to solve** — a user or operator is stuck on a specific gap;
+  - **an opportunity to capture** — something newly possible we want to claim;
+  - **a vision to realize** — a thing we want to make exist because we want it to exist;
+  - **a mandate to meet** — a regulation, deprecation, deadline, or contractual obligation.
+
+Name which (or which combination) applies, who is affected, and the backdrop that makes it matter now. This is the anchor every downstream trade-off resolves against.}
+
+## Capabilities
+
+- id: CAP-1
+  intent: {One sentence. "User or system can do X to achieve Y." WHAT, not HOW.}
+  success: {Testable or demonstrable criterion. Something a test or a real demonstration can decide.}
+
+## Constraints
+
+- {A non-negotiable that bends design. If it doesn't rule anything out, it doesn't belong.}
+
+## Non-goals
+
+- {Explicit out-of-scope item. At least one. Stops downstream from filling the vacuum.}
+
+## Success signal
+
+- {One or two sentences. World-change moment, not dashboard. Concrete enough to write a test or run a demonstration against.}
+
+## Assumptions
+
+<!-- Optional. Omit this section entirely if empty. Inferred calls made without direct confirmation from the input. -->
+
+- {Statement of fact the Spec proceeded under, e.g. "Assumed mobile-first since input mentioned GPS but no platform."}
+
+## Open Questions
+
+<!-- Optional. Omit this section entirely if empty. Gaps the input did not resolve that need a human decision before downstream skills consume the Spec. -->
+
+- {Question phrased so a human can answer it, e.g. "Is offline playback in scope for CAP-2?"}

package/src/core-skills/xiaoma-spec/customize.toml

@@ -0,0 +1,53 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for xiaoma-spec.
+#
+# Override files (not edited here):
+#   {project-root}/_xiaoma/custom/xiaoma-spec.toml        (team)
+#   {project-root}/_xiaoma/custom/xiaoma-spec.user.toml   (personal)
+
+[workflow]
+
+# --- Configurable below. Overrides merge per XiaoMa structural rules: ---
+#   scalars: override wins • arrays: append
+
+# Steps to run before the standard activation (config load, greet).
+activation_steps_prepend = []
+
+# Steps to run after greet but before the operation begins.
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run.
+# Each entry is either a literal sentence, a skill prefixed with `skill:`,
+# or a `file:`-prefixed path/glob whose contents are loaded as facts.
+# Default points to a single top-level file; override in team/user TOML
+# to widen the scope (e.g. `_xiaoma/**/project-context.md`) if needed.
+persistent_facts = [
+  "file:{project-root}/project-context.md",
+]
+
+# Executed when the workflow completes. Scalar or array of instructions.
+on_complete = ""
+
+# Spec template. The five-field kernel skeleton. Override the path in
+# team/user TOML to enforce a different shape (e.g. a hypothesis field
+# for research initiatives, or a mechanics field for games).
+spec_template = "assets/spec-template.md"
+
+# Canonical filename for the kernel artifact inside the spec folder.
+# Uppercase by convention to signal "the central source of truth."
+spec_filename = "SPEC.md"
+
+# Output path for spec folders. Lands directly under {output_folder}
+# so xiaoma-spec works in core-only installs and matches the
+# long-term XiaoMa direction of grouping artifacts as siblings under
+# {output_folder}/<type>/ rather than nested inside planning vs
+# implementation folders.
+spec_output_path = "{output_folder}/specs"
+
+# Run-folder pattern inside spec_output_path. Resolved against the
+# input-derived slug at activation. Same slug = same folder, so a
+# second invocation updates the existing spec in place (capability
+# IDs preserved). Override to add {date} or other components if a
+# fresh dated history is preferred.
+run_folder_pattern = "spec-{slug}"