@zeyue0329/xiaoma-cli 1.13.0 → 1.15.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@zeyue0329/xiaoma-cli",
-  "version": "1.13.0",
+  "version": "1.15.0",
   "description": "XiaoMa Universal AI Agent Framework",
   "keywords": [
     "agile",
@@ -18,32 +18,43 @@
   },
   "license": "MIT",
   "author": "Zeyue",
-  "main": "tools/cli/xiaoma-cli.js",
+  "main": "tools/installer/xiaoma-cli.js",
   "bin": {
     "xiaoma": "tools/xiaoma-npx-wrapper.js",
     "xiaoma-cli": "tools/xiaoma-npx-wrapper.js"
   },
+  "files": [
+    "src",
+    "tools",
+    "LICENSE"
+  ],
   "scripts": {
-    "flatten": "node tools/flattener/main.js",
+    "emit:step-kinds-doc": "node tools/validate-step-schemas.js --emit-doc",
     "format:check": "prettier --check \"**/*.{js,cjs,mjs,json,yaml}\"",
     "format:fix": "prettier --write \"**/*.{js,cjs,mjs,json,yaml}\"",
     "format:fix:staged": "prettier --write",
-    "install:xiaoma": "node tools/cli/xiaoma-cli.js install",
+    "install:xiaoma": "node tools/installer/xiaoma-cli.js install",
     "lint": "eslint . --ext .js,.cjs,.mjs,.yaml --max-warnings=0",
     "lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
     "lint:md": "markdownlint-cli2 \"**/*.md\"",
     "prepare": "command -v husky >/dev/null 2>&1 && husky || exit 0",
-    "quality": "npm run format:check && npm run lint && npm run lint:md && npm run validate:schemas && npm run test:schemas && npm run test:install && npm run validate:refs",
-    "rebundle": "node tools/cli/bundlers/bundle-web.js rebundle",
-    "test": "npm run test:schemas && npm run test:refs && npm run test:install && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
-    "test:coverage": "c8 --reporter=text --reporter=html npm run test:schemas",
-    "test:install": "node test/test-installation-components.js",
+    "quality": "npm run format:check && npm run lint && npm run lint:md && npm run validate:skills && npm run test:step-schemas && npm run test:install && npm run test:resolvers && npm run validate:refs && npm run validate:warnings-samples && npm run validate:trigger-emit-bidi && npm run validate:routing-consistency && npm run validate:step-schemas:strict && npm run validate:step-kinds-doc",
+    "test": "npm run quality",
+    "test:coverage": "c8 --reporter=text --reporter=html npm run test:step-schemas",
+    "test:install": "node test/test-installer-smoke.js",
     "test:refs": "node test/test-file-refs-csv.js",
-    "test:schemas": "node test/test-agent-schema.js",
+    "test:resolvers": "node test/test-resolvers.js",
+    "test:step-schemas": "node test/test-step-schema.js",
     "validate:refs": "node tools/validate-file-refs.js --strict",
-    "validate:schemas": "node tools/validate-agent-schema.js",
-    "xiaoma:install": "node tools/cli/xiaoma-cli.js install",
-    "xiaoma:uninstall": "node tools/cli/xiaoma-cli.js uninstall"
+    "validate:routing-consistency": "node tools/validate-frontmatter-prose-routing.js",
+    "validate:skills": "node tools/validate-skills.js --strict",
+    "validate:step-kinds-doc": "node tools/validate-step-schemas.js --check-doc",
+    "validate:step-schemas": "node tools/validate-step-schemas.js",
+    "validate:step-schemas:strict": "node tools/validate-step-schemas.js --strict-kind",
+    "validate:trigger-emit-bidi": "node tools/validate-trigger-column-vs-emits.js",
+    "validate:warnings-samples": "node tools/validate-warnings-samples.js --strict",
+    "xiaoma:install": "node tools/installer/xiaoma-cli.js install",
+    "xiaoma:uninstall": "node tools/installer/xiaoma-cli.js uninstall"
   },
   "lint-staged": {
     "*.{js,cjs,mjs}": [
@@ -88,7 +99,6 @@
     "eslint-plugin-unicorn": "^60.0.0",
     "eslint-plugin-yml": "^1.18.0",
     "husky": "^9.1.7",
-    "jest": "^30.2.0",
     "lint-staged": "^16.1.1",
     "markdownlint-cli2": "^0.19.1",
     "prettier": "^3.7.4",

package/src/core-skills/module-help.csv

@@ -0,0 +1,13 @@
+module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
+Core,_meta,,,,,,,,,false,,
+Core,xiaoma-brainstorming,Brainstorming,BSP,Use early in ideation or when stuck generating ideas.,,,anytime,,,false,{output_folder}/brainstorming,brainstorming session
+Core,xiaoma-party-mode,Party Mode,PM,Orchestrate multi-agent discussions when you need multiple perspectives or want agents to collaborate.,,,anytime,,,false,,
+Core,xiaoma-help,XiaoMa Help,BH,,,,anytime,,,false,,
+Core,xiaoma-index-docs,Index Docs,ID,Use when LLM needs to understand available docs without loading everything.,,,anytime,,,false,,
+Core,xiaoma-shard-doc,Shard Document,SD,Use when doc becomes too large (>500 lines) to manage effectively.,,[path],anytime,,,false,,
+Core,xiaoma-editorial-review-prose,Editorial Review - Prose,EP,Use after drafting to polish written content.,,[path],anytime,,,false,report located with target document,three-column markdown table with suggested fixes
+Core,xiaoma-editorial-review-structure,Editorial Review - Structure,ES,Use when doc produced from multiple subprocesses or needs structural improvement.,,[path],anytime,,,false,report located with target document,
+Core,xiaoma-review-adversarial-general,Adversarial Review,AR,"Use for quality assurance or before finalizing deliverables. Code Review in other modules runs this automatically, but also useful for document reviews.",,[path],anytime,,,false,,
+Core,xiaoma-review-edge-case-hunter,Edge Case Hunter Review,ECH,Use alongside adversarial review for orthogonal coverage — method-driven not attitude-driven.,,[path],anytime,,,false,,
+Core,xiaoma-spec,Spec,SP,"Use to distill any intent input (brief, PRD, transcript, brain dump, design folder, mixed multi-source) into a succinct, no-fluff SPEC.md contract + companions that downstream work derives from. Locks the WHAT before the HOW. Works for software, game design, research, editorial, policy, business, anything intent-bearing. Validation mode also available.",,[path],anytime,,,false,{output_folder}/specs/spec-{slug},SPEC.md + companion files
+Core,xiaoma-customize,XiaoMa Customize,BC,"Use when you want to change how an agent or workflow behaves — add persistent facts, swap templates, insert activation hooks, or customize menus. Scans what's customizable, picks the right scope (agent vs workflow), writes the override to _xiaoma/custom/, and verifies the merge. No TOML hand-authoring required.",,,anytime,,,false,{project-root}/_xiaoma/custom,TOML override files

package/src/{core → core-skills}/module.yaml

@@ -1,16 +1,24 @@
 code: core
 name: "XiaoMa Core Module"
+description: "Shared utilities across modules"
 
 header: "XiaoMa Core Configuration"
 subheader: "Configure the core settings for your XiaoMa installation.\nThese settings will be used across all installed xiaoma skills, workflows, and agents."
 
 user_name:
   prompt: "What should agents call you? (Use your name or a team name)"
+  scope: user
   default: "XiaoMa"
   result: "{value}"
 
+project_name:
+  prompt: "What is your project called?"
+  default: "{directory_name}"
+  result: "{value}"
+
 communication_language:
   prompt: "What language should agents use when chatting with you?"
+  scope: user
   default: "English"
   result: "{value}"
 

package/src/{core/skills/xiaoma-advanced-elicitation/workflow.md → core-skills/xiaoma-advanced-elicitation/SKILL.md}

@@ -1,8 +1,9 @@
 ---
-agent_party: '{project-root}/_xiaoma/_config/agent-manifest.csv'
+name: xiaoma-advanced-elicitation
+description: 'Push the LLM to reconsider, refine, and improve its recent output. Use when user asks for deeper critique or mentions a known deeper critique method, e.g. socratic, first principles, pre-mortem, red team.'
 ---
 
-# Advanced Elicitation Workflow
+# Advanced Elicitation
 
 **Goal:** Push the LLM to reconsider, refine, and improve its recent output.
 
@@ -34,7 +35,13 @@ When invoked from another prompt or process:
 
 ### Step 1: Method Registry Loading
 
-**Action:** Load and read `./methods.csv` and `{agent_party}`
+**Action:** Load `./methods.csv` for elicitation methods. If party-mode may participate, resolve the agent roster via:
+
+```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`.
 
 #### CSV Structure
 

package/src/core-skills/xiaoma-advanced-elicitation/methods.csv

@@ -0,0 +1,70 @@
+num,category,method_name,description,output_pattern
+1,advanced,Tree of Thoughts,Explore multiple reasoning paths simultaneously then evaluate and select the best - perfect for complex problems with multiple valid approaches,paths → evaluation → selection
+2,advanced,Graph of Thoughts,Model reasoning as an interconnected network of ideas to reveal hidden relationships - ideal for systems thinking and discovering emergent patterns,nodes → connections → patterns
+3,advanced,Thread of Thought,Maintain coherent reasoning across long contexts by weaving a continuous narrative thread - essential for RAG systems and maintaining consistency,context → thread → synthesis
+4,advanced,Self-Consistency Validation,Generate multiple independent approaches then compare for consistency - crucial for high-stakes decisions where verification matters,approaches → comparison → consensus
+5,advanced,Meta-Prompting Analysis,Step back to analyze the approach structure and methodology itself - valuable for optimizing prompts and improving problem-solving,current → analysis → optimization
+6,advanced,Reasoning via Planning,Build a reasoning tree guided by world models and goal states - excellent for strategic planning and sequential decision-making,model → planning → strategy
+7,advanced,Chain-of-Thought Scaffolding,Force explicit intermediate reasoning steps before any conclusion — prevents intuitive leaps that skip flawed logic,premise → step → step → conclusion
+8,advanced,Few-Shot Exemplar Priming,Provide 2-3 worked examples of the desired reasoning pattern before the real task — aligns output format and depth through demonstration,examples → pattern recognition → application
+9,collaboration,Stakeholder Round Table,Convene multiple personas to contribute diverse perspectives - essential for requirements gathering and finding balanced solutions across competing interests,perspectives → synthesis → alignment
+10,collaboration,Expert Panel Review,Assemble domain experts for deep specialized analysis - ideal when technical depth and peer review quality are needed,expert views → consensus → recommendations
+11,collaboration,Debate Club Showdown,Two personas argue opposing positions while a moderator scores points - great for exploring controversial decisions and finding middle ground,thesis → antithesis → synthesis
+12,collaboration,User Persona Focus Group,Gather your product's user personas to react to proposals and share frustrations - essential for validating features and discovering unmet needs,reactions → concerns → priorities
+13,collaboration,Time Traveler Council,Past-you and future-you advise present-you on decisions - powerful for gaining perspective on long-term consequences vs short-term pressures,past wisdom → present choice → future impact
+14,collaboration,Cross-Functional War Room,Product manager + engineer + designer tackle a problem together - reveals trade-offs between feasibility desirability and viability,constraints → trade-offs → balanced solution
+15,collaboration,Mentor and Apprentice,Senior expert teaches junior while junior asks naive questions - surfaces hidden assumptions through teaching,explanation → questions → deeper understanding
+16,collaboration,Good Cop Bad Cop,Supportive persona and critical persona alternate - finds both strengths to build on and weaknesses to address,encouragement → criticism → balanced view
+17,collaboration,Improv Yes-And,Multiple personas build on each other's ideas without blocking - generates unexpected creative directions through collaborative building,idea → build → build → surprising result
+18,collaboration,Customer Support Theater,Angry customer and support rep roleplay to find pain points - reveals real user frustrations and service gaps,complaint → investigation → resolution → prevention
+19,collaboration,Six Thinking Hats,Rotate through six modes (facts - feelings - caution - optimism - creativity - process) to ensure a group covers every angle without crosstalk,white → red → black → yellow → green → blue
+20,collaboration,Delphi Method,Experts give independent estimates - see anonymized results - then revise — converges on calibrated group judgment while avoiding anchoring bias,independent estimates → reveal → revise → converge
+21,competitive,Red Team vs Blue Team,Adversarial attack-defend analysis to find vulnerabilities - critical for security testing and building robust solutions,defense → attack → hardening
+22,competitive,Shark Tank Pitch,Entrepreneur pitches to skeptical investors who poke holes - stress-tests business viability and forces clarity on value proposition,pitch → challenges → refinement
+23,competitive,Code Review Gauntlet,Senior devs with different philosophies review the same code - surfaces style debates and finds consensus on best practices,reviews → debates → standards
+24,core,First Principles Analysis,Strip away assumptions to rebuild from fundamental truths - breakthrough technique for innovation and solving impossible problems,assumptions → truths → new approach
+25,core,5 Whys Deep Dive,Repeatedly ask why to drill down to root causes - simple but powerful for understanding failures,why chain → root cause → solution
+26,core,Socratic Questioning,Use targeted questions to reveal hidden assumptions and guide discovery - excellent for teaching and self-discovery,questions → revelations → understanding
+27,core,Critique and Refine,Systematic review to identify strengths and weaknesses then improve - standard quality check for drafts,strengths/weaknesses → improvements → refined
+28,core,Explain Reasoning,Walk through step-by-step thinking to show how conclusions were reached - crucial for transparency,steps → logic → conclusion
+29,core,Expand or Contract for Audience,Dynamically adjust detail level and technical depth for target audience - matches content to reader capabilities,audience → adjustments → refined content
+30,core,Second-Order Thinking,Think beyond immediate consequences to anticipate cascading effects and long-term implications - essential for strategic decisions where first-order solutions create hidden downstream problems,action → consequences → second-order effects → informed choice
+31,core,Inversion Analysis,Flip the problem by asking what would guarantee failure instead of how to succeed - reveals hidden obstacles and blind spots by approaching challenges from the opposite direction,goal → invert → failure paths → avoidance → solution
+32,core,Problem Decomposition,Break a complex problem into independent sub-problems - solve each - then reassemble — essential when a task is too large or tangled to tackle whole,whole → parts → solutions → reassembly
+33,core,Analogy Mapping,Find a well-understood parallel domain and transfer its structure to the current problem — unlocks insight by borrowing proven mental models,source domain → mapping → target insight
+34,core,Steelmanning,Construct the strongest possible version of an opposing argument before responding — builds credibility and catches blind spots that strawmanning misses,opposing view → strongest form → honest rebuttal
+35,creative,SCAMPER Method,Apply seven creativity lenses (Substitute/Combine/Adapt/Modify/Put/Eliminate/Reverse) - systematic ideation for product innovation,S→C→A→M→P→E→R
+36,creative,Reverse Engineering,Work backwards from desired outcome to find implementation path - powerful for goal achievement and understanding endpoints,end state → steps backward → path forward
+37,creative,What If Scenarios,Explore alternative realities to understand possibilities and implications - valuable for contingency planning and exploration,scenarios → implications → insights
+38,creative,Random Input Stimulus,Inject unrelated concepts to spark unexpected connections - breaks creative blocks through forced lateral thinking,random word → associations → novel ideas
+39,creative,Exquisite Corpse Brainstorm,Each persona adds to the idea seeing only the previous contribution - generates surprising combinations through constrained collaboration,contribution → handoff → contribution → surprise
+40,creative,Genre Mashup,Combine two unrelated domains to find fresh approaches - innovation through unexpected cross-pollination,domain A + domain B → hybrid insights
+41,creative,Constraint Injection,Deliberately add an artificial limitation (budget - time - technology) to force novel solutions — creativity thrives under pressure,add constraint → forced creativity → remove constraint → evaluate
+42,creative,Morphological Analysis,List independent parameters of a problem - enumerate options for each - then systematically combine — ensures you don't miss non-obvious configurations,parameters → options grid → combinations → evaluation
+43,framing,Abstraction Laddering,"Move up (""why?"") for strategic clarity or down (""how?"") for tactical detail — ensures you're solving at the right altitude",concrete ↔ abstract → right level
+44,framing,Reframe the Question,Challenge whether the stated problem is the real problem — often the question itself is wrong and a better framing unlocks an easy answer,stated problem → reframe → true problem → solution
+45,framing,Stakeholder Lens Rotation,Serially adopt each stakeholder's world-view to see the same situation differently — reveals whose needs are being overlooked,perspective A → B → C → gaps found
+46,learning,Feynman Technique,Explain complex concepts simply as if teaching a child - the ultimate test of true understanding,complex → simple → gaps → mastery
+47,learning,Active Recall Testing,Test understanding without references to verify true knowledge - essential for identifying gaps,test → gaps → reinforcement
+48,learning,Deliberate Practice Loop,Identify a specific sub-skill - drill it with immediate feedback - adjust - repeat — targeted improvement beats general repetition,isolate → drill → feedback → adjust → repeat
+49,philosophical,Occam's Razor Application,Find the simplest sufficient explanation by eliminating unnecessary complexity - essential for debugging,options → simplification → selection
+50,philosophical,Trolley Problem Variations,Explore ethical trade-offs through moral dilemmas - valuable for understanding values and difficult decisions,dilemma → analysis → decision
+51,research,Literature Review Personas,Optimist researcher + skeptic researcher + synthesizer review sources - balanced assessment of evidence quality,sources → critiques → synthesis
+52,research,Thesis Defense Simulation,Student defends hypothesis against committee with different concerns - stress-tests research methodology and conclusions,thesis → challenges → defense → refinements
+53,research,Comparative Analysis Matrix,Multiple analysts evaluate options against weighted criteria - structured decision-making with explicit scoring,options → criteria → scores → recommendation
+54,research,Source Triangulation,Require at least three independent source types (quantitative - qualitative - expert) before accepting a claim — guards against single-source bias,claim → source A → source B → source C → confidence rating
+55,retrospective,Hindsight Reflection,Imagine looking back from the future to gain perspective - powerful for project reviews,future view → insights → application
+56,retrospective,Lessons Learned Extraction,Systematically identify key takeaways and actionable improvements - essential for continuous improvement,experience → lessons → actions
+57,risk,Pre-mortem Analysis,Imagine future failure then work backwards to prevent it - powerful technique for risk mitigation before major launches,failure scenario → causes → prevention
+58,risk,Failure Mode Analysis,Systematically explore how each component could fail - critical for reliability engineering and safety-critical systems,components → failures → prevention
+59,risk,Challenge from Critical Perspective,Play devil's advocate to stress-test ideas and find weaknesses - essential for overcoming groupthink,assumptions → challenges → strengthening
+60,risk,Identify Potential Risks,Brainstorm what could go wrong across all categories - fundamental for project planning and deployment preparation,categories → risks → mitigations
+61,risk,Chaos Monkey Scenarios,Deliberately break things to test resilience and recovery - ensures systems handle failures gracefully,break → observe → harden
+62,risk,Assumption Audit,Explicitly list every assumption underlying a plan - rate each by confidence and impact - then stress-test the weakest — prevents building on shaky foundations,list → rate → stress-test → shore up
+63,risk,Cascading Failure Simulation,Trace how one component's failure propagates through dependencies — reveals hidden coupling and single points of failure,trigger failure → trace propagation → find amplifiers → decouple
+64,technical,Architecture Decision Records,Multiple architect personas propose and debate architectural choices with explicit trade-offs - ensures decisions are well-reasoned and documented,options → trade-offs → decision → rationale
+65,technical,Rubber Duck Debugging Evolved,Explain your code to progressively more technical ducks until you find the bug - forces clarity at multiple abstraction levels,simple → detailed → technical → aha
+66,technical,Algorithm Olympics,Multiple approaches compete on the same problem with benchmarks - finds optimal solution through direct comparison,implementations → benchmarks → winner
+67,technical,Security Audit Personas,Hacker + defender + auditor examine system from different threat models - comprehensive security review from multiple angles,vulnerabilities → defenses → compliance
+68,technical,Performance Profiler Panel,Database expert + frontend specialist + DevOps engineer diagnose slowness - finds bottlenecks across the full stack,symptoms → analysis → optimizations
+69,technical,Boundary & Edge Case Sweep,Systematically test extremes - zeros - nulls - maximums - and type mismatches — catches the failures that happy-path thinking always misses,inputs → boundaries → edge cases → failures found

package/src/{core/skills → core-skills}/xiaoma-brainstorming/steps/step-03-technique-execution.md

@@ -7,7 +7,7 @@
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
 - ✅ YOU ARE A CREATIVE FACILITATOR, engaging in genuine back-and-forth coaching
-- 🎯 AIM FOR 100+ IDEAS before suggesting organization - quantity unlocks quality (quality must grow as we progress)
+- 🎯 AIM FOR 100+ COLLABORATIVE IDEAS before suggesting organization - quantity unlocks quality, but do not batch-generate ideas to satisfy the count
 - 🔄 DEFAULT IS TO KEEP EXPLORING - only move to organization when user explicitly requests it
 - 🧠 **THOUGHT BEFORE INK (CoT):** Before generating each idea, you must internally reason: "What domain haven't we explored yet? What would make this idea surprising or 'uncomfortable' for the user?"
 - 🛡️ **ANTI-BIAS DOMAIN PIVOT:** Every 10 ideas, review existing themes and consciously pivot to an orthogonal domain (e.g., UX -> Business -> Physics -> Social Impact).
@@ -29,6 +29,7 @@ _Novelty_: [What makes this different from obvious solutions]
 ## EXECUTION PROTOCOLS:
 
 - 🎯 Present one technique element at a time for deep exploration
+- 🛑 Present at most one new idea, provocation, or angle before asking for user input
 - ⚠️ Ask "Continue with current technique?" before moving to next technique
 - 💾 Document insights and ideas using the **IDEA FORMAT TEMPLATE**
 - 📖 Follow user's creative energy and interests within technique structure
@@ -171,7 +172,7 @@ Before moving to next technique element:
 - **Switch techniques** for a fresh perspective?
 - Or are you feeling like we've **thoroughly explored** this space?
 
-Remember: The goal is quantity first - we can organize later. What feels right?"
+Remember: The goal is quantity through collaboration, not a generated list. What feels right?"
 
 **IMPORTANT:** Default to continuing exploration. Only suggest organization if:
 
@@ -292,7 +293,7 @@ After final technique element:
 
 **HALT — wait for user selection before proceeding.**
 
-**Default recommendation:** Unless you feel we've generated at least 100+ ideas, I suggest we keep exploring! The best insights often come after the obvious ideas are exhausted.
+**Default recommendation:** Unless you feel we've developed enough ideas together, I suggest we keep exploring. The best insights often come after the obvious ideas are exhausted.
 
 ### 8. Handle Menu Selection
 
@@ -362,7 +363,7 @@ When user selects 'C', append the content directly to `{brainstorming_session_ou
 
 ## SUCCESS METRICS:
 
-✅ Minimum 100 ideas generated before organization is offered
+✅ Substantial collaborative idea volume before organization is offered
 ✅ User explicitly confirms readiness to conclude (not AI-initiated)
 ✅ Multiple technique exploration encouraged over single-technique completion
 ✅ True back-and-forth facilitation rather than question-answer format
@@ -376,6 +377,7 @@ When user selects 'C', append the content directly to `{brainstorming_session_ou
 ## FAILURE MODES:
 
 ❌ Offering organization after only one technique or <20 ideas
+❌ Batch-generating idea lists instead of facilitating dialogue
 ❌ AI initiating conclusion without user explicitly requesting it
 ❌ Treating technique completion as session completion signal
 ❌ Rushing to document rather than staying in generative mode

package/src/{core/skills → core-skills}/xiaoma-brainstorming/workflow.md

@@ -12,7 +12,7 @@ context_file: '' # Optional context file path for project-specific guidance
 
 **Anti-Bias Protocol:** LLMs naturally drift toward semantic clustering (sequential bias). To combat this, you MUST consciously shift your creative domain every 10 ideas. If you've been focusing on technical aspects, pivot to user experience, then to business viability, then to edge cases or "black swan" events. Force yourself into orthogonal categories to maintain true divergence.
 
-**Quantity Goal:** Aim for 100+ ideas before any organization. The first 20 ideas are usually obvious - the magic happens in ideas 50-100.
+**Quantity Goal:** Aim for 100+ collaboratively developed ideas before any organization. This is a session goal, not a request to generate a large list. Ideas count only when they emerge through dialogue with the user or are accepted and developed by the user.
 
 ---
 

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

@@ -0,0 +1,111 @@
+---
+name: xiaoma-customize
+description: Authors and updates customization overrides for installed XiaoMa skills. Use when the user says 'customize xiaoma', 'override a skill', 'change agent behavior', or 'customize a workflow'.
+---
+
+# XiaoMa Customize
+
+Translate the user's intent into a correctly-placed TOML override file under `{project-root}/_xiaoma/custom/` for a customizable agent or workflow skill. Discover, route, author, write, verify.
+
+Scope v1: per-skill `[agent]` overrides (`xiaoma-agent-<role>.toml` / `.user.toml`) and per-skill `[workflow]` overrides (`xiaoma-<workflow>.toml` / `.user.toml`). Central config (`{project-root}/_xiaoma/custom/config.toml`) is out of scope — point users at the How to Customize XiaoMa guide.
+
+When the target's `customize.toml` doesn't expose what the user wants, say so plainly. Don't invent fields.
+
+## Preflight
+
+- No `{project-root}/_xiaoma/` → XiaoMa isn't installed. Say so, stop.
+- `{project-root}/_xiaoma/scripts/resolve_customization.js` missing → continue, but Step 6 verify falls back to manual merge.
+- Both present → proceed.
+
+## Activation
+
+Load `_xiaoma/config.toml` and `_xiaoma/config.user.toml` from `{project-root}` for `user_name` (default `XiaoMa`) and `communication_language` (default `English`). Greet. If the user's invocation already names a target skill AND a specific change, jump to Step 3.
+
+## Step 1: Classify intent
+
+- **Directed** — specific skill + specific change → Step 3.
+- **Exploratory** — "what can I customize?" → Step 2.
+- **Audit/iterate** — wants to review or change something already customized → Step 2, lead with skills that have existing overrides; read the existing override in Step 3 before composing.
+- **Cross-cutting** — could live on multiple surfaces → Step 3, choose agent vs workflow explicitly with the user.
+
+## Step 2: Discovery
+
+```
+node {skill-root}/scripts/list_customizable_skills.js --project-root {project-root}
+```
+
+Use `--extra-root <path>` (repeatable) if the user has skills installed in additional locations.
+
+Group the returned `agents` and `workflows` for the user; for each show name, description, whether `has_team_override` or `has_user_override` is true. Surface any `errors[]`. For audit/iterate intents, lead with already-overridden entries.
+
+Empty list: show `scanned_roots`, ask whether skills live elsewhere (offer `--extra-root`); otherwise stop.
+
+## Step 3: Determine the right surface
+
+Read the target's `customize.toml`. Top-level `[agent]` or `[workflow]` block defines the surface.
+
+If a team or user override already exists, read it first and summarize what's already overridden before composing.
+
+**Cross-cutting intent — walk both surfaces with the user:**
+- Every workflow a given agent runs → agent surface (e.g. `xiaoma-agent-pm.toml` with `persistent_facts`, `principles`).
+- One workflow only → workflow surface (e.g. `xiaoma-prd.toml` with `activation_steps_prepend`).
+- Several specific workflows → multiple workflow overrides in sequence, not an agent override.
+
+**Single-surface heuristic:**
+- Workflow-level: template swap, output path, step-specific behavior, or a named scalar already exposed (`*_template`, `on_complete`). Surgical, reliable.
+- Agent-level: persona, communication style, org-wide facts, menu changes, behavior that should apply to every workflow the agent dispatches.
+
+When ambiguous, present both with tradeoff, recommend one, let the user decide.
+
+Intent outside the exposed surface (step logic, ordering, anything not in `customize.toml`): say so; offer `activation_steps_prepend`/`append` or `persistent_facts` as approximations, or recommend `xiaoma-builder` to create a custom skill.
+
+## Step 4: Compose the override
+
+Translate plain-English into TOML against the target's `customize.toml` fields. If an existing override was read, frame the change as additive.
+
+Merge semantics:
+- **Scalars** (`icon`, `role`, `*_template`, `on_complete`) — override wins.
+- **Append arrays** (`persistent_facts`, `activation_steps_prepend`/`append`, `principles`) — team/user entries append in order.
+- **Keyed arrays of tables** (menu items with `code` or `id`) — matching keys replace, new keys append.
+
+Overrides are sparse: only the fields being changed. Never copy the whole `customize.toml`.
+
+**Template swap** (`*_template` scalar): offer to copy the default template to `{project-root}/_xiaoma/custom/{skill-name}-{purpose}-template.md`, point the override at the new path, offer to help edit it.
+
+## Step 5: Team or user placement
+
+Under `{project-root}/_xiaoma/custom/`:
+- `{skill-name}.toml` — team, committed. Policies, org conventions, compliance.
+- `{skill-name}.user.toml` — user, gitignored. Personal tone, private facts, shortcuts.
+
+Default by character (policy → team, personal → user), confirm before writing.
+
+## Step 6: Show, confirm, write, verify
+
+1. Show the full TOML. If the file exists, show a diff. Never silently overwrite.
+2. Wait for explicit yes.
+3. Write. Create `{project-root}/_xiaoma/custom/` if needed.
+4. Verify:
+   ```
+   node {project-root}/_xiaoma/scripts/resolve_customization.js --skill <install-path> --key <agent-or-workflow>
+   ```
+   Show the merged output, point out the changed fields.
+
+   **Resolver missing or fails:** read whichever layers exist — `<install-path>/customize.toml` (base), `{project-root}/_xiaoma/custom/{skill-name}.toml` (team), `{project-root}/_xiaoma/custom/{skill-name}.user.toml` (user) — apply base → team → user with the same merge rules (scalars override, tables deep-merge, `code`/`id`-keyed arrays merge by key, all other arrays append), describe how the changed fields resolve.
+
+   **Verify shows override didn't land** (field unchanged, merge conflict, file not picked up): re-enter Step 4 with the verify output as context. Usually wrong field name, wrong merge mode (scalar vs array), or wrong scope.
+5. Summarize what changed, where the file lives, how to iterate. Remind the user to commit team overrides.
+
+## Complete when
+
+- Override file written (or user explicitly aborted).
+- User has seen resolver output (or manual fallback merge summary).
+- User has acknowledged the summary.
+
+Otherwise the skill isn't done — finish or tell the user they're exiting incomplete.
+
+## When this skill can't help
+
+- **Central config** (`{project-root}/_xiaoma/custom/config.toml`) — see the How to Customize XiaoMa guide.
+- **Step logic, ordering, behavior not in `customize.toml`** — open a feature request, or use `xiaoma-builder` to create a custom skill. Offer to help with either.
+- **Skills without a `customize.toml`** — not customizable.

package/src/core-skills/xiaoma-customize/scripts/list_customizable_skills.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+/**
+ * Enumerate customizable XiaoMa skills installed alongside this one.
+ *
+ * Node port of the original Python helper (no Python runtime dependency).
+ * Uses the vendored TOML parser shipped with the resolvers (../../../scripts/toml.js
+ * once installed under _xiaoma/scripts/, or the sibling copy during dev).
+ *
+ * Scans a skills directory (default: this script's skill root, three parents up),
+ * finds every sibling dir with a `customize.toml`, classifies each by its
+ * top-level [agent]/[workflow] blocks, reads the SKILL.md frontmatter
+ * description, and checks for existing overrides in {project-root}/_xiaoma/custom/.
+ *
+ * Output: JSON to stdout. errors[] is non-fatal (exit 0). Exit 2 for invocation
+ * errors (e.g. missing --project-root).
+ *
+ * Usage:
+ *   node list_customizable_skills.js --project-root <dir> [--skills-root <dir>] [--extra-root <dir>]...
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Resolve the vendored TOML parser: prefer a sibling under the install's
+// _xiaoma/scripts/ (../../../scripts/toml.js relative to this skill), else the
+// repo's src/scripts/toml.js during development.
+function loadTomlModule() {
+  const candidates = [
+    path.join(__dirname, '..', '..', '..', 'scripts', 'toml.js'), // installed: _xiaoma/<module>/.../scripts/toml.js
+    path.join(__dirname, '..', '..', '..', '..', 'scripts', 'toml.js'),
+    path.join(process.cwd(), 'src', 'scripts', 'toml.js'),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return require(c);
+  }
+  // Last resort: a tiny inline shim is not provided; surface a clear error.
+  throw new Error('toml.js parser not found alongside the customization scripts');
+}
+const toml = loadTomlModule();
+
+const SURFACE_KEYS = ['agent', 'workflow'];
+const FRONTMATTER_RE = /^---\s*\n([\s\S]*?)\n---\s*\n/;
+
+function defaultSkillsRoot() {
+  // Layout: {skills_root}/xiaoma-customize/scripts/list_customizable_skills.js
+  return path.resolve(__dirname, '..', '..');
+}
+
+function readFrontmatterDescription(skillMd) {
+  if (!fs.existsSync(skillMd) || !fs.statSync(skillMd).isFile()) return '';
+  let text;
+  try {
+    text = fs.readFileSync(skillMd, 'utf8');
+  } catch {
+    return '';
+  }
+  const m = FRONTMATTER_RE.exec(text);
+  if (!m) return '';
+  for (const line of m[1].split('\n')) {
+    const stripped = line.trim();
+    if (stripped.startsWith('description:')) {
+      let value = stripped.slice('description:'.length).trim();
+      if ((value.startsWith("'") && value.endsWith("'")) || (value.startsWith('"') && value.endsWith('"'))) {
+        value = value.slice(1, -1);
+      }
+      return value;
+    }
+  }
+  return '';
+}
+
+function loadCustomize(tomlPath) {
+  try {
+    return toml.parse(fs.readFileSync(tomlPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function scanSkills(skillsRoots, projectRoot) {
+  const agents = [];
+  const workflows = [];
+  const errors = [];
+  const scannedRoots = [];
+  const seenNames = new Set();
+  const customDir = path.join(projectRoot, '_xiaoma', 'custom');
+
+  for (const root of skillsRoots) {
+    if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+      errors.push(`skills root does not exist: ${root}`);
+      continue;
+    }
+    scannedRoots.push(root);
+    const entries = fs
+      .readdirSync(root)
+      .map((e) => path.join(root, e))
+      .filter((p) => fs.statSync(p).isDirectory())
+      .sort();
+    for (const skillDir of entries) {
+      const customizeToml = path.join(skillDir, 'customize.toml');
+      if (!fs.existsSync(customizeToml) || !fs.statSync(customizeToml).isFile()) continue;
+      const data = loadCustomize(customizeToml);
+      if (data === null) {
+        errors.push(`failed to parse ${customizeToml}`);
+        continue;
+      }
+      const skillName = path.basename(skillDir);
+      if (seenNames.has(skillName)) continue;
+      seenNames.add(skillName);
+
+      const description = readFrontmatterDescription(path.join(skillDir, 'SKILL.md'));
+      const teamOverride = path.join(customDir, `${skillName}.toml`);
+      const userOverride = path.join(customDir, `${skillName}.user.toml`);
+      const entryBase = {
+        name: skillName,
+        install_path: skillDir,
+        skills_root: root,
+        description,
+        has_team_override: fs.existsSync(teamOverride),
+        has_user_override: fs.existsSync(userOverride),
+        team_override_path: teamOverride,
+        user_override_path: userOverride,
+      };
+      const surfacesFound = SURFACE_KEYS.filter((k) => k in data);
+      if (surfacesFound.length === 0) {
+        errors.push(`no [agent] or [workflow] block in ${customizeToml}`);
+        continue;
+      }
+      for (const surface of surfacesFound) {
+        const entry = { ...entryBase, surface };
+        if (surface === 'agent') agents.push(entry);
+        else workflows.push(entry);
+      }
+    }
+  }
+  return { project_root: projectRoot, scanned_roots: scannedRoots, custom_dir: customDir, agents, workflows, errors };
+}
+
+function parseArgs(argv) {
+  const out = { projectRoot: null, skillsRoot: null, extraRoot: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--project-root') out.projectRoot = argv[++i];
+    else if (a === '--skills-root') out.skillsRoot = argv[++i];
+    else if (a === '--extra-root') out.extraRoot.push(argv[++i]);
+  }
+  return out;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.projectRoot) {
+    process.stderr.write('error: --project-root is required\n');
+    process.exit(2);
+  }
+  const projectRoot = path.resolve(args.projectRoot);
+  if (!fs.existsSync(projectRoot) || !fs.statSync(projectRoot).isDirectory()) {
+    process.stderr.write(`error: project-root does not exist or is not a directory: ${projectRoot}\n`);
+    process.exit(2);
+  }
+  const primary = args.skillsRoot ? path.resolve(args.skillsRoot) : defaultSkillsRoot();
+  const roots = [];
+  for (const root of [primary, ...args.extraRoot.map((p) => path.resolve(p))]) {
+    if (!roots.includes(root)) roots.push(root);
+  }
+  const result = scanSkills(roots, projectRoot);
+  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+}
+
+main();

package/src/{core/skills → core-skills}/xiaoma-distillator/resources/distillate-format-reference.md

@@ -172,7 +172,7 @@ parts: 1
 - Deferred: CI/CD integration, telemetry for module authors, air-gapped enterprise install, zip bundle integrity verification (checksums/signing), deeper non-technical platform integrations
 
 ## Current Installer (migration context)
-- Entry: `tools/cli/xiaoma-cli.js` (Commander.js) → `tools/cli/installers/lib/core/installer.js`
+- Entry: `tools/installer/xiaoma-cli.js` (Commander.js) → `tools/installer/core/installer.js`
 - Platforms: `platform-codes.yaml` (~20 platforms with target dirs, legacy dirs, template types, special flags)
 - Manifests: CSV files (skill/workflow/agent-manifest.csv) are current source of truth, not JSON
 - External modules: `external-official-modules.yaml` (CIS, GDS, TEA, WDS) from npm with semver

package/src/{core/skills → core-skills}/xiaoma-distillator/scripts/analyze_sources.py

@@ -9,7 +9,7 @@ detects document types from naming conventions, and suggests groupings for
 related documents (e.g., a brief paired with its discovery notes).
 
 Accepts: file paths, folder paths (scans recursively for .md/.txt/.yaml/.yml/.json),
-or glob patterns. Skips node_modules, .git, __pycache__, .venv, _bmad-output.
+or glob patterns. Skips node_modules, .git, __pycache__, .venv, _xiaoma-output.
 
 Output JSON structure:
   status: "ok" | "error"
@@ -40,7 +40,7 @@ INCLUDE_EXTENSIONS = {".md", ".txt", ".yaml", ".yml", ".json"}
 # Directories to skip when scanning folders
 SKIP_DIRS = {
     "node_modules", ".git", "__pycache__", ".venv", "venv",
-    ".claude", "_bmad-output", ".cursor", ".vscode",
+    ".claude", "_xiaoma-output", ".cursor", ".vscode",
 }
 
 # Approximate chars per token for estimation

package/src/{core/skills/xiaoma-editorial-review-prose/workflow.md → core-skills/xiaoma-editorial-review-prose/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: xiaoma-editorial-review-prose
+description: 'Clinical copy-editor that reviews text for communication issues. Use when user says review for prose or improve the prose'
+---
+
 # Editorial Review - Prose
 
 **Goal:** Review text for communication issues that impede comprehension and output suggested fixes in a three-column table.

package/src/{core/skills/xiaoma-editorial-review-structure/workflow.md → core-skills/xiaoma-editorial-review-structure/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: xiaoma-editorial-review-structure
+description: 'Structural editor that proposes cuts, reorganization, and simplification while preserving comprehension. Use when user requests structural review or editorial review of structure'
+---
+
 # Editorial Review - Structure
 
 **Goal:** Review document structure and propose substantive changes to improve clarity and flow -- run this BEFORE copy editing.