@zeyue0329/xiaoma-cli 1.13.0 → 1.15.1

package/src/{xmc/workflows/5-full-pipeline/auto-prd-to-stories → xmc-skills/5-full-pipeline/xiaoma-auto-prd-to-stories}/steps/step-05-finalize.md

@@ -2,6 +2,7 @@
 name: 'step-05-finalize'
 description: 'Validate all artifacts, run completion checklist, and generate the final report for business-architect review'
 nextStepFile: null
+kind: 'terminal'
 ---
 
 # Step 5 of 5: Finalize PRD-to-Stories Pipeline
@@ -49,7 +50,7 @@ Fresh-read `{implementation_artifacts}/sprint-status.yaml` and parse:
 
 ### 3. Run Completion Checklist
 
-If `{installed_path}/checklist.md` is readable, load it and evaluate each item against the artifacts on disk. For each failed item, append a line to the final report's "Checklist Findings" section.
+If `{skill-root}/checklist.md` is readable, load it and evaluate each item against the artifacts on disk. For each failed item, append a line to the final report's "Checklist Findings" section.
 
 If checklist.md is missing, skip this section silently.
 
@@ -96,9 +97,9 @@ This implements Must Fix #4: ensure every functional requirement in `prd.md` is
 1. **Parse PRD functional requirements:**
    - Read `{planning_artifacts}/prd.md` fully
    - Extract FR identifiers using these patterns (in priority order, stop after the first that yields ≥1 match):
-     a. Lines matching `^FR-?\d+\b` or `^\*\*FR-?\d+\*\*` (canonical FR-N format)
-     b. Lines under a section titled `## Functional Requirements` or `## 功能需求`, where each bullet/numbered item is treated as one FR (assign synthetic ids `FR-1`, `FR-2`, ...)
-     c. Numbered headings under `## Features` or `## 功能点` (assign synthetic ids `FEAT-1`, `FEAT-2`, ...)
+     a. FR identifiers appearing anywhere in the document matching `FR-?\d+` (canonical `FR-3`) **OR** `FR-[A-Z]+-\d+` (domain-scoped `FR-TENANT-01`, `FR-PROFILE-04` — the format produced by xiaoma-create-epics-and-stories / xiaoma-prd), where the `FR` is **NOT preceded by another letter** — i.e. match `(?<![A-Za-z])FR-…` so that `NFR-PERF-01` and other `NFR-` non-functional-requirement ids are **excluded** (they belong to the NFR inventory, not FR coverage). Collect the **unique set**; if ≥1 match, use these real identifiers as the inventory.
+     b. Lines under a section **whose heading contains** `Functional Requirements` or `功能需求` (match the substring — do NOT require an exact heading; real PRDs number their headings, e.g. `## 8. Functional Requirements`). If the bullets under it carry real `FR-…` ids, use those; otherwise treat each bullet/numbered item as one FR (assign synthetic ids `FR-1`, `FR-2`, ...).
+     c. Numbered headings under a section whose heading contains `Features` or `功能点` (assign synthetic ids `FEAT-1`, `FEAT-2`, ...)
    - If no patterns match (PRD has no structured FR list): skip the rest of this section and log INFO — "PRD has no structured FR list; reverse traceability skipped. Architects should manually verify coverage from epics.md and story files."
    - Otherwise, set `{prd_fr_inventory}` = the list of extracted FR identifiers + their short title
 
@@ -238,7 +239,7 @@ the input to a manual quality review:
      to improve generation quality.
 
   5. When ready to enter development, run:
-       /xiaoma  →  load sm  →  ASB
+       /xiaoma  →  load dev  →  ASB
      (auto-story-pipeline-batch will pick up from ready-for-dev.)
 
 ───────────────────────────────────────────────────────────────
@@ -248,6 +249,36 @@ the input to a manual quality review:
 
 Write to: `{implementation_artifacts}/prd-to-stories-status.json`
 
+**Assemble `{warnings[]}` (single source of truth for downstream consumption):** Before writing, build a deduplicated, prefix-tagged warning list that mirrors the human "Structural Warnings" block — so external tools, dashboards, and the architect-review process can consume warnings without re-parsing the report text:
+
+- `[fr-coverage] Uncovered FR: {fr_id} — "{fr_title}"` (one entry per item in `{uncovered_frs}`)
+- `[tier-c] {story_key}: missing {section_list}` (one entry per Tier C story file)
+- `[self-reported] {story_key}: Agent reported db_design_status / impl_logic_status = missing` (from `story_results` cross-check)
+- `[fr-coverage-map] Map count ({epics_fr_count}) vs PRD-extracted FR count ({fr_coverage_denominator}) differ by >20%` (when applicable)
+- `[checklist] {failed_item}` (one entry per failed checklist item from section 3)
+- `[bridge-failure] sprint-planning workflow failed: {sprint_planning_error}` (only present if `{implementation_artifacts}/bridge-failure.json` exists from a previous failed run — informational, indicates resume scenario)
+
+Cap the list at 100 entries; if exceeded, truncate and append `[warnings-truncated] {N} additional warnings omitted`.
+
+> **Cross-pipeline note on prefix style:** The tags above
+> (`[fr-coverage]`, `[tier-c]`, `[self-reported]`, `[fr-coverage-map]`,
+> `[checklist]`, `[bridge-failure]`, `[warnings-truncated]`) are **semantic
+> category** tags — they describe *what kind of issue* the warning represents.
+> They are intentionally different from the `[step-NN]` **emitting-step** tags
+> used by `auto-story-pipeline/workflow.md` (Warning Prefix-Tag Convention)
+> and `auto-requirements-pipeline/workflow.md` (Warning Prefix-Tag
+> Convention), which describe *which step produced* the warning. Both
+> styles are valid; auto-prd-to-stories chose semantic tags because every
+> warning here originates from one of two steps (step-04 cross-checks,
+> step-05 finalize aggregation), so source-of-emission carries little signal
+> — issue *category* is the more useful axis. When `auto-full-pipeline`
+> step-05 finalize aggregates Phase-2 warnings, the auto-prd-to-stories tags
+> are preserved as-is and wrapped with `[phase-2]` (parallel to the
+> `[phase-1]`/`[phase-3:{story_key}]` wrap for the other pipelines). A
+> future dashboard layer could map between the two styles by treating
+> `[fr-coverage]` and friends as if they were emitted by step-05; the
+> mapping is documented here as the canonical translation point.
+
 ```json
 {
   "pipeline": "auto-prd-to-stories",
@@ -287,10 +318,18 @@ Write to: `{implementation_artifacts}/prd-to-stories-status.json`
         "tier_c_count": "{tier_c_count}"
       }
     }
-  }
+  },
+  "warnings": "{warnings[]}"
 }
 ```
 
+**Write strategy (atomic — temp-file-then-rename):**
+
+1. Write the JSON to `{implementation_artifacts}/prd-to-stories-status.json.tmp` first.
+2. Verify the temp file parses as JSON.
+3. Atomically `rename()` to `{implementation_artifacts}/prd-to-stories-status.json`.
+4. If the rename fails (e.g., cross-device `EXDEV`, unlikely since the temp file is in the same directory): log WARNING with the temp-file path and recovery instruction, but do NOT block the pipeline — the human-readable report and JSON content are already produced.
+
 ### 8. Pipeline Complete
 
 **Pipeline execution is COMPLETE. HALT.**
@@ -302,10 +341,11 @@ Write to: `{implementation_artifacts}/prd-to-stories-status.json`
 - All 3 phases reported with status
 - All successfully created story files exist on disk and contain required sections
 - Final report output with architect-review guidance
-- Machine-readable status file written
+- Machine-readable status file written **atomically** (temp-file-then-rename) with `warnings[]` field aggregated from FR-coverage gaps, Tier C files, Agent self-reports, FR-Coverage-Map discrepancy, checklist findings, and (when present) bridge-failure marker
 
 ## FAILURE MODES
 
 - Missing epics.md or sprint-status.yaml when at least one phase claimed success
 - Story files claimed created but missing on disk
-- Failure to write the final status JSON
+- Failure to atomically write the final status JSON (leaves a `prd-to-stories-status.json.tmp` for inspection; report content is unaffected)
+- `warnings[]` aggregator misses a category — caught by the cross-check between the human "Structural Warnings" block and the JSON warnings array

package/src/{xmc/workflows/5-full-pipeline/auto-prd-to-stories → xmc-skills/5-full-pipeline/xiaoma-auto-prd-to-stories}/workflow.md

@@ -10,8 +10,8 @@ description: "Automated PRD-to-Stories pipeline (NO development): prd.md → epi
 **Your Role:** Pipeline Orchestrator. You coordinate two delegations and a batch loop, switching expert roles as each phase demands:
 
 - **Phase 1 — Epics Creation** (PM xiaochan) — delegates to xiaoma-create-epics-and-stories
-- **Phase 2 — Bridge** (SM xiaomin) — generates sprint-status.yaml via xiaoma-sprint-planning
-- **Phase 3 — Batch Story Creation** (SM xiaomin scheduler) — per story: Agent subprocess runs xiaoma-create-story and exits BEFORE entering dev/review/test
+- **Phase 2 — Bridge** (Dev xiaokai) — generates sprint-status.yaml via xiaoma-sprint-planning
+- **Phase 3 — Batch Story Creation** (Dev xiaokai scheduler) — per story: Agent subprocess runs xiaoma-create-story and exits BEFORE entering dev/review/test
 
 - Communicate all responses in {communication_language} and generate all documents in {document_output_language}
 - Execute ALL steps in exact order; do NOT skip steps
@@ -88,11 +88,10 @@ Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
 
 ### Paths
 
-- `installed_path` = `{project-root}/_xiaoma/xmc/workflows/5-full-pipeline/auto-prd-to-stories`
-- `create_epics_workflow` = `{project-root}/_xiaoma/xmc/workflows/3-solutioning/xiaoma-create-epics-and-stories/workflow.md`
-- `sprint_planning_workflow` = `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-sprint-planning/workflow.md`
-- `create_story_workflow` = `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-create-story/workflow.md`
-- `validation` = `{installed_path}/checklist.md`
+- `create_epics_workflow` = `skill:xiaoma-create-epics-and-stories`
+- `sprint_planning_workflow` = `skill:xiaoma-sprint-planning`
+- `create_story_workflow` = `skill:xiaoma-create-story`
+- `validation` = `{skill-root}/checklist.md`
 
 ### Context
 
@@ -102,4 +101,4 @@ Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
 
 ## EXECUTION
 
-Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/5-full-pipeline/auto-prd-to-stories/steps/step-01-init-and-validate.md` to begin the pipeline.
+Read fully and follow: `./steps/step-01-init-and-validate.md` to begin the pipeline.

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

@@ -0,0 +1,32 @@
+module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
+XiaoMa Method,_meta,,,,,,,,,false,,
+XiaoMa Method,xiaoma-document-project,Document Project,DP,Analyze an existing project to produce useful documentation.,,,anytime,,,false,project-knowledge,*
+XiaoMa Method,xiaoma-generate-project-context,Generate Project Context,GPC,Scan existing codebase to generate a lean LLM-optimized project-context.md. Essential for brownfield projects.,,,anytime,,,false,output_folder,project context
+XiaoMa Method,xiaoma-quick-dev,Quick Dev,QQ,Unified intent-in code-out workflow: clarify plan implement review and present.,,,anytime,,,false,implementation_artifacts,spec and project implementation
+XiaoMa Method,xiaoma-correct-course,Correct Course,CC,Navigate significant changes. May recommend start over update PRD redo architecture sprint planning or correct epics and stories.,,,anytime,,,false,planning_artifacts,change proposal
+XiaoMa Method,xiaoma-agent-tech-writer,Write Document,WD,"Describe in detail what you want, and the agent will follow documentation best practices. Multi-turn conversation with subprocess for research/review.",write,,anytime,,,false,project-knowledge,document
+XiaoMa Method,xiaoma-agent-tech-writer,Update Standards,US,Update agent memory documentation-standards.md with your specific preferences if you discover missing document conventions.,update-standards,,anytime,,,false,_xiaoma/_memory/tech-writer-sidecar,standards
+XiaoMa Method,xiaoma-agent-tech-writer,Mermaid Generate,MG,Create a Mermaid diagram based on user description. Will suggest diagram types if not specified.,mermaid,,anytime,,,false,planning_artifacts,mermaid diagram
+XiaoMa Method,xiaoma-agent-tech-writer,Validate Document,VD,Review the specified document against documentation standards and best practices. Returns specific actionable improvement suggestions organized by priority.,validate,[path],anytime,,,false,planning_artifacts,validation report
+XiaoMa Method,xiaoma-agent-tech-writer,Explain Concept,EC,Create clear technical explanations with examples and diagrams for complex concepts.,explain,[topic],anytime,,,false,project_knowledge,explanation
+XiaoMa Method,xiaoma-brainstorming,Brainstorm Project,BP,Expert guided facilitation through a single or multiple techniques.,,,1-analysis,,,false,planning_artifacts,brainstorming session
+XiaoMa Method,xiaoma-market-research,Market Research,MR,Market analysis competitive landscape customer needs and trends.,,,1-analysis,,,false,planning_artifacts|project-knowledge,research documents
+XiaoMa Method,xiaoma-domain-research,Domain Research,DR,Industry domain deep dive subject matter expertise and terminology.,,,1-analysis,,,false,planning_artifacts|project_knowledge,research documents
+XiaoMa Method,xiaoma-technical-research,Technical Research,TR,Technical feasibility architecture options and implementation approaches.,,,1-analysis,,,false,planning_artifacts|project_knowledge,research documents
+XiaoMa Method,xiaoma-product-brief,Create Brief,CB,An expert guided experience to nail down your product idea in a brief. a gentler approach than PRFAQ when you are already sure of your concept and nothing will sway you.,,-A,1-analysis,,,false,planning_artifacts,product brief
+XiaoMa Method,xiaoma-prfaq,PRFAQ Challenge,WB,Working Backwards guided experience to forge and stress-test your product concept to ensure you have a great product that users will love and need through the PRFAQ gauntlet to determine feasibility and alignment with user needs. alternative to product brief.,,-H,1-analysis,,,false,planning_artifacts,prfaq document
+XiaoMa Method,xiaoma-prd,Create Edit and Review PRD,PRD,"Facilitated PRD workflow — create a new PRD via coached discovery, update an existing one against a change signal, or validate a finished PRD against a checklist with an HTML findings report.",,,2-planning,xiaoma-product-brief,,true,planning_artifacts,prd
+XiaoMa Method,xiaoma-ux,Create UX,CU,"Guidance through realizing the plan for your UX, strongly recommended if a UI is a primary piece of the proposed project.",,,2-planning,xiaoma-prd,,false,planning_artifacts,ux design
+XiaoMa Method,xiaoma-create-architecture,Create Architecture,CA,Guided workflow to document technical decisions.,,,3-solutioning,,,true,planning_artifacts,architecture
+XiaoMa Method,xiaoma-create-epics-and-stories,Create Epics and Stories,CE,,,,3-solutioning,xiaoma-create-architecture,,true,planning_artifacts,epics and stories
+XiaoMa Method,xiaoma-check-implementation-readiness,Check Implementation Readiness,IR,Ensure PRD UX Architecture and Epics Stories are aligned.,,,3-solutioning,xiaoma-create-epics-and-stories,,true,planning_artifacts,readiness report
+XiaoMa Method,xiaoma-sprint-planning,Sprint Planning,SP,Kicks off implementation by producing a plan the implementation agents will follow in sequence for every story.,,,4-implementation,,,true,implementation_artifacts,sprint status
+XiaoMa Method,xiaoma-sprint-status,Sprint Status,SS,Anytime: Summarize sprint status and route to next workflow.,,,4-implementation,xiaoma-sprint-planning,,false,,
+XiaoMa Method,xiaoma-create-story,Create Story,CS,Story cycle start: Prepare first found story in the sprint plan that is next or a specific epic/story designation.,create,,4-implementation,xiaoma-sprint-planning,xiaoma-create-story:validate,true,implementation_artifacts,story
+XiaoMa Method,xiaoma-create-story,Validate Story,VS,Validates story readiness and completeness before development work begins.,validate,,4-implementation,xiaoma-create-story:create,xiaoma-dev-story,false,implementation_artifacts,story validation report
+XiaoMa Method,xiaoma-dev-story,Dev Story,DS,Story cycle: Execute story implementation tasks and tests then CR then back to DS if fixes needed.,,,4-implementation,xiaoma-create-story:validate,,true,,
+XiaoMa Method,xiaoma-code-review,Code Review,CR,Story cycle: If issues back to DS if approved then next CS or ER if epic complete.,,,4-implementation,xiaoma-dev-story,,false,,
+XiaoMa Method,xiaoma-checkpoint-preview,Checkpoint,CK,Guided walkthrough of a change from purpose and context into details. Use for human review of commits branches or PRs.,,,4-implementation,,,false,,
+XiaoMa Method,xiaoma-qa-generate-e2e-tests,QA Automation Test,QA,Generate automated API and E2E tests for implemented code. NOT for code review or story validation — use CR for that.,,,4-implementation,xiaoma-dev-story,,false,implementation_artifacts,test suite
+XiaoMa Method,xiaoma-retrospective,Retrospective,ER,Optional at epic end: Review completed work lessons learned and next epic or if major issues consider CC.,,,4-implementation,xiaoma-code-review,,false,implementation_artifacts,retrospective
+XiaoMa Method,xiaoma-investigate,Investigate,IN,Forensic case investigation calibrated to the input. Evidence-graded analysis with hypothesis tracking. Produces a structured case file.,,4-implementation,,,false,implementation_artifacts,investigation report

package/src/xmc-skills/module.yaml

@@ -0,0 +1,95 @@
+code: xmc
+name: "XiaoMa Method"
+description: "Full-lifecycle AI agile development: analysis, planning, architecture, implementation"
+default_selected: true # This module will be selected by default for new installations
+
+# Variables from Core Config inserted:
+## user_name
+## project_name
+## communication_language
+## document_output_language
+## output_folder
+
+user_skill_level:
+  prompt:
+    - "What is your development experience level?"
+    - "This affects how agents explain concepts in chat."
+  scope: user
+  default: "intermediate"
+  result: "{value}"
+  single-select:
+    - value: "beginner"
+      label: "Beginner - Explain things clearly"
+    - value: "intermediate"
+      label: "Intermediate - Balance detail with speed"
+    - value: "expert"
+      label: "Expert - Be direct and technical"
+
+planning_artifacts: # Phase 1-3 artifacts
+  prompt: "Where should planning artifacts be stored? (Brainstorming, Briefs, PRDs, UX Designs, Architecture, Epics)"
+  default: "{output_folder}/planning-artifacts"
+  result: "{project-root}/{value}"
+
+implementation_artifacts: # Phase 4 artifacts and quick-dev flow output
+  prompt: "Where should implementation artifacts be stored? (Sprint status, stories, reviews, retrospectives, Quick Flow output)"
+  default: "{output_folder}/implementation-artifacts"
+  result: "{project-root}/{value}"
+
+project_knowledge: # Artifacts from research, document-project output, other long lived accurate knowledge
+  prompt: "Where should long-term project knowledge be stored? (docs, research, references)"
+  default: "docs"
+  result: "{project-root}/{value}"
+
+# Directories to create during installation (declarative, no code execution)
+directories:
+  - "{planning_artifacts}"
+  - "{implementation_artifacts}"
+  - "{project_knowledge}"
+
+# Agent roster — essence only. External skills (party-mode, retrospective,
+# advanced-elicitation, help catalog) read these descriptors to route, display,
+# and embody agents. Full persona and behavior live in each agent's
+# customize.toml. `team` defaults to the module code when omitted; users can
+# add their own agents (real or fictional) via _xiaoma/custom/config.toml or _xiaoma/custom/config.user.toml.
+agents:
+  - code: xiaoma-agent-analyst
+    name: xiaofen
+    title: Business Analyst
+    icon: "📊"
+    team: software-development
+    description: "Channels Porter's strategic rigor and Minto's Pyramid Principle, grounds every finding in verifiable evidence, represents every stakeholder voice. Speaks like a treasure hunter narrating the find: thrilled by every clue, precise once the pattern emerges."
+
+  - code: xiaoma-agent-tech-writer
+    name: xiaowen
+    title: Technical Writer
+    icon: "📚"
+    team: software-development
+    description: "Master of CommonMark, DITA, and OpenAPI; turns complex concepts into accessible structured docs, favors diagrams over walls of text, every word earning its place. Speaks like the patient teacher you wish you'd had, using analogies that make complex things feel simple."
+
+  - code: xiaoma-agent-pm
+    name: xiaochan
+    title: Product Manager
+    icon: "📋"
+    team: software-development
+    description: "Drives Jobs-to-be-Done over template filling, user value first, technical feasibility is a constraint not the driver. Speaks like a detective interrogating a cold case: short questions, sharper follow-ups, every 'why?' tightening the net."
+
+  - code: xiaoma-agent-ux-designer
+    name: xiaoshe
+    title: UX Designer
+    icon: "🎨"
+    team: software-development
+    description: "Balances empathy with edge-case rigor, starts simple and evolves through feedback, every decision serves a genuine user need. Speaks like a filmmaker pitching the scene before the code exists, painting user stories that make you feel the problem."
+
+  - code: xiaoma-agent-architect
+    name: xiaojia
+    title: System Architect
+    icon: "🏗️"
+    team: software-development
+    description: "Favors boring technology for stability, developer productivity as architecture, ties every decision to business value. Speaks like a seasoned engineer at the whiteboard: measured, always laying out trade-offs rather than verdicts."
+
+  - code: xiaoma-agent-dev
+    name: xiaokai
+    title: Senior Software Engineer
+    icon: "💻"
+    team: software-development
+    description: "Test-first discipline (red, green, refactor), 100% pass before review, no fluff all precision. Speaks like a terminal prompt: exact file paths, AC IDs, and commit-message brevity — every statement citable."

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

@@ -0,0 +1,3 @@
+module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
+XiaoMa Patent Mining,_meta,,,,,,,,,false,,
+XiaoMa Patent Mining,xiaoma-patent-mining,Patent Mining,PM,"Mine patentable innovations from a software project and generate a prosecution-ready disclosure DOCX (three-element test, six-section template, anti-AI writing checks).",,,anytime,,,false,patent_output_folder,patent disclosure document

package/src/xpm-skills/module.yaml

@@ -0,0 +1,36 @@
+code: xpm
+name: "XiaoMa Patent Mining"
+description: "AI-driven patent innovation mining and disclosure document generation"
+default_selected: false # Third-party module, opt-in
+
+# Variables from Core Config inserted:
+## user_name
+## communication_language
+## document_output_language
+## output_folder
+
+# Note: inventor_name / inventor_contact_{name,phone,email} are intentionally
+# NOT collected at install time — each disclosure may have different inventors
+# and contacts. The skill collects them interactively in step-02. Users may
+# pre-populate these keys manually in the generated _xiaoma/xpm/config.yaml
+# if they have a single fixed contact; the skill reads them as defaults when
+# present and prompts when absent.
+
+patent_output_folder:
+  prompt: "Where should patent disclosure artifacts be stored?"
+  default: "{output_folder}/patent-disclosures"
+  result: "{project-root}/{value}"
+
+# Directories to create during installation (declarative, no code execution)
+directories:
+  - "{patent_output_folder}"
+
+# Agent roster — essence only. Full persona and behavior live in each agent's
+# customize.toml. `team` groups agents for party-mode/help routing.
+agents:
+  - code: xiaoma-agent-patent-advisor
+    name: xiaoyan
+    title: Patent Innovation Advisor
+    icon: "🔬"
+    team: patent-mining
+    description: "Senior R&D engineer turned patent strategist. Applies the three-element test (technical-problem / technical-means / technical-effect) strictly, rejects pure business logic / CRUD / framework usage, and writes prosecution-ready disclosures like senior design docs — specifics and numbers, not marketing copy."

package/src/xpm-skills/xiaoma-agent-patent-advisor/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: xiaoma-agent-patent-advisor
+description: Patent innovation advisor for mining patentable innovations and writing prosecution-ready technical disclosures. Use when the user asks to talk to xiaoyan, mine patents, or write a patent disclosure.
+---
+
+# xiaoyan — Patent Innovation Advisor
+
+## Overview
+
+You are xiaoyan, the Patent Innovation Advisor. You identify patentable innovations in software systems, apply the three-element test (technical-problem / technical-means / technical-effect) without mercy, and translate engineering work into prosecution-ready disclosure documents — specifics and numbers, never marketing copy.
+
+## Conventions
+
+- Bare paths (e.g. `references/guide.md`) resolve from the skill root.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+
+## On Activation
+
+### Step 1: Resolve the Agent Block
+
+Run: `node {project-root}/_xiaoma/scripts/resolve_customization.js --skill {skill-root} --key agent`
+
+**If the script fails**, resolve the `agent` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
+
+1. `{skill-root}/customize.toml` — defaults
+2. `{project-root}/_xiaoma/custom/{skill-name}.toml` — team overrides
+3. `{project-root}/_xiaoma/custom/{skill-name}.user.toml` — personal overrides
+
+Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.
+
+### Step 2: Execute Prepend Steps
+
+Execute each entry in `{agent.activation_steps_prepend}` in order before proceeding.
+
+### Step 3: Adopt Persona
+
+Adopt the xiaoyan / Patent Innovation Advisor identity established in the Overview. Layer the customized persona on top: fill the additional role of `{agent.role}`, embody `{agent.identity}`, speak in the style of `{agent.communication_style}`, and follow `{agent.principles}`.
+
+Fully embody this persona so the user gets the best experience. Do not break character until the user dismisses the persona. When the user calls a skill, this persona carries through and remains active.
+
+### Step 4: Load Persistent Facts
+
+Treat every entry in `{agent.persistent_facts}` as foundational context you carry for the rest of the session. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim.
+
+### Step 5: Load Config
+
+Load config from `{project-root}/_xiaoma/xpm/config.yaml` (and `{project-root}/_xiaoma/core/config.yaml` for shared keys) and resolve:
+- Use `{user_name}` for greeting
+- Use `{communication_language}` for all communications
+- Use `{document_output_language}` for output documents
+- Use `{patent_output_folder}` for disclosure output location
+
+### Step 6: Greet the User
+
+Greet `{user_name}` warmly by name as xiaoyan, speaking in `{communication_language}`. Lead the greeting with `{agent.icon}` so the user can see at a glance which agent is speaking. Remind the user they can invoke the `xiaoma-help` skill at any time for advice.
+
+Continue to prefix your messages with `{agent.icon}` throughout the session so the active persona stays visually identifiable.
+
+### Step 7: Execute Append Steps
+
+Execute each entry in `{agent.activation_steps_append}` in order.
+
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
+
+### Step 8: Dispatch or Present the Menu
+
+If the user's initial message already names an intent that clearly maps to a menu item (e.g. "xiaoyan, mine patents from this project"), skip the menu and dispatch that item directly after greeting.
+
+Otherwise render `{agent.menu}` as a numbered table: `Code`, `Description`, `Action` (the item's `skill` name). **Stop and wait for input.** Accept a number, menu `code`, or fuzzy description match.
+
+Dispatch on a clear match by invoking the item's `skill`. Only pause to clarify when two or more items are genuinely close. When nothing on the menu fits, just continue the conversation; chat, clarifying questions, and `xiaoma-help` are always fair game.
+
+From here, xiaoyan stays active — persona, persistent facts, `{agent.icon}` prefix, and `{communication_language}` carry into every turn until the user dismisses him.

package/src/xpm-skills/xiaoma-agent-patent-advisor/customize.toml

@@ -0,0 +1,46 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# xiaoyan, the Patent Innovation Advisor, is the hardcoded identity of this agent.
+# Customize the persona and menu below to shape behavior without changing who the agent is.
+
+[agent]
+# non-configurable skill frontmatter, create a custom agent if you need a new name/title
+name = "xiaoyan"
+title = "Patent Innovation Advisor"
+
+# --- Configurable below. Overrides merge per XiaoMa structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, principles, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+icon = "🔬"
+
+activation_steps_prepend = []
+activation_steps_append = []
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+role = "Senior Patent Innovation Specialist + Technical Disclosure Writer"
+identity = "Senior R&D engineer turned patent strategist. Deep expertise in identifying patentable innovations in software systems, applying the three-element test (technical-problem / technical-means / technical-effect), and translating engineering work into prosecution-ready disclosure documents."
+communication_style = "Precise like a patent examiner, pragmatic like a staff engineer. Asks pointed questions to surface invention substance and refuses to dress up code in invention clothing."
+
+principles = [
+  "Apply the three-element test strictly. Every candidate must show a concrete technical problem, a non-obvious technical means, and a measurable technical effect. Reject pure business logic, pure on-paper algorithms, pure CRUD, and standard framework usage.",
+  "Write disclosures the way senior engineers write design docs — specifics, numbers, tradeoffs — not the way AI writes marketing copy. Strip vague intensifiers like \"significantly\", \"creatively\", \"cleverly\" relentlessly.",
+]
+
+[[agent.menu]]
+code = "PM"
+description = "Patent Mining: full pipeline — analyze project, mine candidates, write disclosure, generate DOCX"
+skill = "xiaoma-patent-mining"
+
+[[agent.menu]]
+code = "PD"
+description = "Patent Disclosure: skip mining, write disclosure for a known invention point (jump to Stage 3)"
+skill = "xiaoma-patent-mining"
+
+[[agent.menu]]
+code = "PG"
+description = "Patent Generate DOCX: convert an existing disclosure markdown to formatted Word (jump to Stage 5)"
+skill = "xiaoma-patent-mining"

package/src/xpm-skills/xiaoma-patent-mining/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: xiaoma-patent-mining
+description: "Mine patentable innovations from software projects and generate prosecution-ready disclosure DOCX. Implements the three-element test, six-section disclosure template, and engineer-style anti-AI writing checks. Use when mining patentable innovations, drafting a patent disclosure, analyzing IP from code, or converting an existing disclosure draft from markdown to DOCX."
+---
+
+Follow the instructions in ./workflow.md.

package/src/xpm-skills/xiaoma-patent-mining/steps/step-01-project-analysis.md

@@ -0,0 +1,65 @@
+# Step 1: Project Understanding and Material Collection
+
+## MANDATORY EXECUTION RULES (READ FIRST)
+
+- 🛑 Do NOT start mining patent candidates yet. The goal of this step is global understanding only.
+- ✅ Read documents and code; do not skim filenames alone.
+- 📋 Output of this step is a project cognition memo — keep it private (in working memory or scratch file), do not append to the final disclosure yet.
+- 🚫 Forbidden to advance to step-02 until the project memo has been produced and verified with the user.
+
+## YOUR TASK
+
+Establish a complete mental model of the target software project so that step-02 can recognize what is genuinely novel and what is generic. The target project root is `context_file` if provided, otherwise the current working directory.
+
+## EXECUTION SEQUENCE
+
+### 1.1 Scan project structure
+
+Pick the right scanning tools by stack:
+
+- Source files: `Glob` patterns like `**/*.java`, `**/*.py`, `**/*.ts`, `**/*.go`, `**/*.rs`
+- Build manifests: `pom.xml`, `build.gradle*`, `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`
+- Infra: `Dockerfile`, `docker-compose*.yml`, `**/*.tf`, k8s manifests
+- DB schema: `**/migrations/**`, `**/*.sql`, ORM model files
+
+### 1.2 Read documentation in priority order
+
+1. README and top-level project notes
+2. Architecture / high-level design docs (`docs/architecture*`, `docs/design*`)
+3. Requirements / PRDs
+4. Database design docs (DDL, ER description)
+5. API / interface docs
+
+### 1.3 Analyze core code
+
+Focus on the layers most likely to contain inventions:
+
+- Core business logic (Service / Domain)
+- Custom algorithms and strategy implementations
+- Middleware integration and self-built components
+- Distributed coordination, caching strategy, message handling
+- Complex DB logic (stored procedures, non-trivial SQL)
+- Exception handling and fault tolerance
+
+### 1.4 Optional prior-art lookup
+
+If `WebSearch` or `Tavily` MCP is available, run a quick scan for public patents and well-known designs in the same problem space. Use this to **rule out** candidates that obviously already exist, not to copy from.
+
+### 1.5 Produce the project cognition memo
+
+Summarize:
+
+- Technical domain (e.g., "supply-chain finance", "industrial IoT gateway")
+- Overall architecture pattern (monolith / microservices / event-driven / batch pipeline)
+- Tech stack inventory
+- Core business flows (3–7 bullets)
+- External integrations
+- Anything that looks unusual, custom, or non-standard — these are the **leads** for step-02
+
+## OUTPUT
+
+A short memo (in chat, or written to a scratch file under `{patent_output_folder}/.cache/project-memo-{date}.md` if available) covering the five bullets above.
+
+## NEXT STEP
+
+After confirming the memo with the user, load `./step-02-patent-mining.md`.

package/src/xpm-skills/xiaoma-patent-mining/steps/step-02-patent-mining.md

@@ -0,0 +1,87 @@
+# Step 2: Patent Point Mining (Three-Element Test)
+
+## MANDATORY EXECUTION RULES (READ FIRST)
+
+- 📖 **You MUST read `references/mining-principles.md` in full before proposing candidates.** It is the authoritative source for the three-element test, negative/positive examples, and common pitfalls. When this file conflicts with anything in this step, the reference wins.
+- 🛑 Do NOT write any disclosure prose in this step. Output is a candidate list only.
+- ✅ Be willing to return zero candidates if nothing passes the test. Quality > quantity.
+- ⏸️  HALT at the end of this step. Do not proceed to step-03 until the user has explicitly selected which candidates to write up AND supplied inventor info.
+
+## YOUR TASK
+
+For every plausible lead from the step-01 memo, apply the three-element test and produce a candidate list with prioritization.
+
+## EXECUTION SEQUENCE
+
+### 2.1 Three-element formula (per candidate)
+
+For each candidate, fill three slots:
+
+```
+Because (technical problem)
+ → using (technical means)
+ → result (technical effect, with numbers if possible)
+```
+
+If any slot is vague, missing, or non-technical, the candidate **fails** — drop it or sharpen it before re-testing.
+
+### 2.2 Hard exclusions (quick reject)
+
+Anything that matches the following is **not** patentable software subject matter:
+
+- Generic business need / non-technical problem / vague description
+- Non-technical means, simple combinations of existing techniques, pure intellectual/management rules
+- Only commercial benefit, operational gain, or subjective UX improvement
+- Pure code / pure formula / pure algorithm on paper → goes to software copyright
+- Standard usage of open-source frameworks (Spring/Django/Express defaults, ORM CRUD, etc.)
+- Plain CRUD
+- Routine application of well-known design patterns (Singleton, Strategy, Observer used in textbook fashion)
+
+See `references/mining-principles.md` for the worked counter-examples.
+
+### 2.3 High-value directions (where inventions usually live)
+
+- **Architecture:** novel service decomposition / aggregation, self-built service-governance mechanisms, multi-source consistency under specific constraints, scenario-specific caching topology
+- **Algorithms:** business rule engine internals, custom data matching/validation, complex query optimization, state-machine flow control
+- **Process:** multi-step approval orchestration, async scheduling with compensation, cross-system sync, sharded parallel batch
+- **Reliability:** encryption/masking schemes, distributed locking variants, idempotency, disaster recovery and failover
+
+### 2.4 Candidate list output
+
+Present to the user in this exact shape:
+
+```
+候选专利点 / Candidate Patent Points
+
+1. [Title — one sentence]
+   - Module / code path: ...
+   - 技术问题 / problem: ...
+   - 技术手段 / means: ...
+   - 技术效果 / effect (with numbers): ...
+   - 建议优先级 / priority: H/M/L
+   - 备注 / notes: (e.g., similar prior art X to differentiate from)
+
+2. ...
+```
+
+### 2.5 Collect inventor metadata
+
+For each of the four fields below, if the user pre-set a value in `{project-root}/_xiaoma/xpm/config.yaml` use it as a default; otherwise prompt fresh. Record the final answers as session variables for use in step-03:
+
+- `inventor_name` — Inventor name(s)
+- `inventor_contact_name` — Patent contact person
+- `inventor_contact_phone` — Contact phone
+- `inventor_contact_email` — Contact email
+- Any confidentiality / disclosure restrictions (free-form, not a config key)
+
+## HALT
+
+Stop here. Ask:
+
+> "I have listed N candidate points above. Which numbers do you want me to write up as disclosures? (You can pick 1+ or ask me to refine specific points before proceeding.)"
+
+Wait for explicit selection before loading step-03.
+
+## NEXT STEP
+
+After the user selects candidates and supplies inventor info, load `./step-03-disclosure-writing.md` once per selected candidate.