@zeyue0329/xiaoma-cli 1.15.1 → 1.16.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@zeyue0329/xiaoma-cli",
-  "version": "1.15.1",
+  "version": "1.16.0",
   "description": "XiaoMa Universal AI Agent Framework",
   "keywords": [
     "agile",

package/src/xmc-skills/4-implementation/xiaoma-agent-dev/customize.toml

@@ -129,3 +129,13 @@ skill = "xiaoma-auto-full-pipeline"
 code = "APS"
 description = "Auto PRD-to-Stories: from an existing prd.md, generate epics + per-story detailed files"
 skill = "xiaoma-auto-prd-to-stories"
+
+[[agent.menu]]
+code = "BR"
+description = "Resolve a single bug end-to-end: intake, root-cause, fix, verify, close with a fix report"
+skill = "xiaoma-bug-resolve"
+
+[[agent.menu]]
+code = "BB"
+description = "Bug Resolve Batch: drain ALL pending bugs from the queue using Agent subprocess isolation"
+skill = "xiaoma-bug-resolve-batch"

package/src/xmc-skills/4-implementation/xiaoma-bug-resolve/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: xiaoma-bug-resolve
+description: "Resolve a single bug end-to-end: intake from a defect platform, a bug-queue file, or the user's description; root-cause analysis; real-defect vs false-positive verdict; minimal-scope fix; verification with tests or browser automation; fix report plus status write-back. Use when the user says 'resolve bug', 'fix bug', 'fix test bug', 'BR', or '处理bug'."
+---
+
+Follow the instructions in [workflow.md](workflow.md).

package/src/xmc-skills/4-implementation/xiaoma-bug-resolve/customize.toml

@@ -0,0 +1,67 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for xiaoma-bug-resolve. Mirrors the
+# agent customization shape under the [workflow] namespace.
+# Override in {project-root}/_xiaoma/custom/xiaoma-bug-resolve.toml
+# (team, committed) or xiaoma-bug-resolve.user.toml (personal).
+
+[workflow]
+
+# --- Configurable below. Overrides merge per XiaoMa structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+# Steps to run before the standard activation (config load, source resolution).
+# Overrides append. Use for pre-flight loads, compliance checks, etc.
+
+activation_steps_prepend = []
+
+# Steps to run after activation but before the workflow begins.
+# Overrides append.
+
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run: coding
+# standards, architecture constraints, known fragile areas. Each entry is
+# either a literal sentence or a `file:` reference (globs supported).
+# Overrides append.
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# Bug intake source. "auto" picks: platform when platform_spec is non-empty,
+# else file when bug_list_file exists, else interactive.
+# Explicit values: "interactive" | "file" | "platform"
+
+bug_source = "auto"
+
+# File mode: the bug-queue file (format: see workflow.md appendix).
+
+bug_list_file = "{implementation_artifacts}/bug-queue.md"
+
+# Platform mode: free-form instructions teaching the workflow how to operate
+# your defect platform (queue query, detail fetch, status write-back, scope
+# filter, data-verification tools). Contract and a complete MySQL-MCP example:
+# workflow.md appendix "Platform Spec Contract".
+
+platform_spec = ""
+
+# Frontend base URL for browser-automation verification of interaction bugs.
+# Can also be passed per-run as a `testUrl=...` arg. Empty = ask when needed.
+
+test_url = ""
+
+# Max fix-verify iterations before halting with a report.
+
+max_fix_iterations = 3
+
+# Subdirectory under {implementation_artifacts} where fix reports land.
+
+fix_report_subdir = "bug-fixes"
+
+# Executed after the closure summary. Override wins. Use for post-fix
+# automation: notify a channel, link the report to a ticket, trigger CI.
+# Leave empty for no custom post-completion behavior.
+
+on_complete = ""

package/src/xmc-skills/4-implementation/xiaoma-bug-resolve/workflow.md

@@ -0,0 +1,265 @@
+---
+name: bug-resolve
+description: "Single-bug resolution workflow: intake from a defect platform, a bug-queue file, or the user's description; root-cause analysis; real-defect vs false-positive verdict; minimal-scope fix; verification; fix report and status write-back."
+---
+
+# Bug Resolve Workflow
+
+**Goal:** Take ONE bug from intake to closure — locate the root cause, judge whether it is a real defect or a false positive,
+apply a minimal-scope fix, verify it, write a fix report, and update the bug's status at its source.
+
+**Your Role:** You are a senior full-stack engineer handling defect resolution. You pinpoint root causes precisely, write
+surgical fixes, and prove them with verification evidence. You never guess: every verdict cites `path:line` evidence.
+
+- Communicate all responses in {communication_language} and generate all documents in {document_output_language}
+- The user invoked this skill to get a bug FIXED. Present your analysis, then proceed to the fix without waiting for
+  ceremony — pause only at the decision points marked below
+
+---
+
+## INITIALIZATION
+
+### Resolve the Workflow Block
+
+Run: `node {project-root}/_xiaoma/scripts/resolve_customization.js --skill {skill-root} --key workflow`
+
+If the script fails, perform the merge manually: read `{skill-root}/customize.toml`, then overlay
+`{project-root}/_xiaoma/custom/xiaoma-bug-resolve.toml` and `xiaoma-bug-resolve.user.toml` (scalars: override wins;
+arrays: append).
+
+Then:
+
+1. Execute each entry in `{workflow.activation_steps_prepend}` in order.
+2. Treat each entry in `{workflow.persistent_facts}` as foundational context. `file:` prefixes are paths or globs under
+   `{project-root}` (load contents); other entries are facts verbatim.
+3. Execute each entry in `{workflow.activation_steps_append}` in order.
+
+### Load Config
+
+Load `{project-root}/_xiaoma/xmc/config.yaml` and resolve: `user_name`, `communication_language`,
+`document_output_language`, `implementation_artifacts`, `project_knowledge`, and `date` as system-generated current
+datetime. If `{implementation_artifacts}` is unresolved, fall back to `.` (the project root) and surface the fallback.
+
+Set `{max_fix_iterations}` = `{workflow.max_fix_iterations}` (default 3) and `{fix_report_dir}` =
+`{implementation_artifacts}/{workflow.fix_report_subdir}`. Initialize `fix_iteration` = 0.
+
+### Resolve the Bug Source Mode
+
+Determine `{bug_source}` from `{workflow.bug_source}`:
+
+- `"platform"` — an external defect platform operated per `{workflow.platform_spec}` (see the Platform Spec Contract
+  appendix). If the spec is empty, HALT: "bug_source is 'platform' but platform_spec is empty — configure it in
+  `_xiaoma/custom/xiaoma-bug-resolve.toml`."
+- `"file"` — a bug-queue file at `{workflow.bug_list_file}` (see the Bug-Queue File Format appendix). If the file does
+  not exist, fall through to `interactive` and tell the user which path was checked.
+- `"interactive"` — the bug comes from the user: their description, an error log, a stack trace, or an issue reference.
+- `"auto"` (default) — pick the first that applies: `platform_spec` non-empty → `platform`; `{workflow.bug_list_file}`
+  exists → `file`; otherwise → `interactive`.
+
+### Parse Args
+
+Optional args: a bug ID (platform/file mode — resolve that specific bug instead of the oldest pending one) or free text
+(interactive mode — treat as the bug description). `testUrl=...` and `authToken=...` tokens override
+`{workflow.test_url}` and supply credentials for browser verification.
+
+---
+
+## WORKFLOW
+
+<workflow>
+
+<step n="1" goal="Intake: acquire exactly one bug and its complete context">
+
+**Platform mode:** Query the pending-bug queue per the platform spec (apply the spec's scope filter if it declares
+one). Pick the bug matching the args bug ID, or the oldest pending bug. Fetch its full record. If the queue is empty,
+tell the user there is nothing to process and stop.
+
+**File mode:** Parse `{workflow.bug_list_file}`. Pick the entry matching the args bug ID, or the first entry with
+status `pending`. If none, tell the user the queue is empty and stop.
+
+**Interactive mode:** Collect from args and conversation: symptom description, reproduction steps, expected vs actual
+behavior, error logs / stack traces / failing test names, affected page or module. Ask only for what is missing and
+truly needed to start.
+
+Output a bug summary: ID (or a short slug agreed with the user), title, severity (if known), type (frontend / backend /
+data / infra), reproduction steps, error evidence.
+
+Set `{slug}` = the bug ID when one exists, otherwise a short descriptive name, sanitized to lowercase alphanumeric with
+hyphens.
+
+</step>
+
+<step n="2" goal="Root-cause analysis and verdict">
+
+1. Map the bug to code regions using every available signal: module / page URL → component or route; stack trace →
+   exact file and line; failing API → controller / service / data access chain; error text → grep target.
+2. Explore in parallel (use Explore subagents for broad sweeps; keep raw file dumps out of the main context): the
+   implicated frontend components, the backend call chain, recent `git log` for the touched area, and existing tests
+   covering it.
+3. Reproduce when feasible: a failing test, a script, or browser automation against `{test_url}` following the
+   reproduction steps. A confirmed reproduction upgrades the verdict's confidence; say so when reproduction is not
+   feasible.
+4. Reach ONE verdict:
+   - **Real defect** — the code is wrong; cite the defective `path:line` and explain the mechanism.
+   - **False positive** — the code is correct; the report stems from a wrong test expectation, bad test data, or an
+     environment issue. Cite the evidence proving correctness.
+   - **Need more info** — state exactly what evidence is missing and how to obtain it. In interactive use, ask the
+     user. When running as a delegated subprocess (batch mode), do NOT guess: report verdict `blocked` and stop.
+5. Present the verdict: root cause (`path:line`), mechanism, and — for real defects — the fix plan (files to change and
+   how). For false positives, skip to Step 5.
+
+</step>
+
+<step n="3" goal="Fix (real defects only)">
+
+- Apply the fix with Edit, strictly scoped to the defect: no drive-by refactoring, no unrelated cleanup.
+- Follow the project's conventions: CLAUDE.md, `project-context.md`, and `{workflow.persistent_facts}`.
+- When the project has a test setup, add or extend a regression test that fails on the old code and passes on the fix.
+- List every modified file with a one-line summary of the change.
+
+</step>
+
+<step n="4" goal="Verify the fix">
+
+Run every verification lane that applies, in this order:
+
+1. **Tests** — discover the project's test command (package.json scripts, Makefile, CI config, project-context.md) and
+   run the suite scoped to the affected area, plus the new regression test.
+2. **Data layer** — if the fix changes a query or data logic and the platform spec declares a data-verification tool,
+   execute the corrected logic through it and compare against expectations.
+3. **Browser** — for bugs involving page interaction, when `{test_url}` is configured or provided: drive the page with
+   the available browser automation tooling (Playwright MCP or equivalent), follow the original reproduction steps, and
+   confirm the expected behavior. If the bug is interaction-related but no `{test_url}` is available, ask for it once
+   (interactive) or record the gap (batch); never block on it.
+4. If nothing can be executed locally (no test setup, no URL, no data tool), say so explicitly and downgrade the
+   closure claim to "fix applied, verification pending deployment".
+
+If verification FAILS: return to Step 3 with the failure evidence. Increment `fix_iteration`; when it exceeds
+`{max_fix_iterations}`, HALT — present the remaining failure, the attempts made, and hand back to the user (interactive)
+or report verdict `failed` (batch).
+
+Summarize the verification evidence: commands run, results, screenshots or response snippets where relevant.
+
+</step>
+
+<step n="5" goal="Close: fix report and status write-back">
+
+1. Write the fix report to `{fix_report_dir}/{slug}-fix.md` (create the directory if needed):
+
+   ```markdown
+   # Bug Fix Report: {slug}
+
+   | Field | Value |
+   | --- | --- |
+   | Bug ID / Title | ... |
+   | Source | platform / file / interactive |
+   | Verdict | real-defect / false-positive |
+   | Severity | ... |
+   | Date | {date} |
+
+   ## Root Cause
+
+   {mechanism, defective path:line citations}
+
+   ## Fix
+
+   {modified files with per-file change summary; regression test added}
+
+   ## Verification
+
+   {lanes run and their evidence; explicit gaps if any}
+
+   ## Residual Risk / Follow-ups
+
+   {anything the next engineer should know; empty if none}
+   ```
+
+   For false positives, the Fix section instead documents why the code is correct and what in the report was wrong
+   (test expectation, data, environment).
+
+2. Write the status back to the source:
+   - **Platform mode:** execute the spec's status write-back — `fixed` for verified real defects, `false-positive` for
+     misreports. Re-query to confirm the update took effect.
+   - **File mode:** update the bug's entry in `{workflow.bug_list_file}` — status to `fixed` or `false-positive`, plus
+     the report path.
+   - **Interactive mode:** nothing to write back; the report is the artifact.
+
+3. Output the closure summary: verdict, modified files, verification result, report path.
+
+4. **Platform / file mode:** report how many pending bugs remain. If more than one remains, mention that
+   `xiaoma-bug-resolve-batch` (menu code BB) can drain the whole queue automatically.
+
+5. Execute `{workflow.on_complete}` if non-empty.
+
+</step>
+
+</workflow>
+
+---
+
+## Appendix: Platform Spec Contract
+
+`{workflow.platform_spec}` is a free-form instruction block (TOML multi-line string) that teaches this workflow how to
+operate your defect platform through the tools available in the session (typically MCP tools). A usable spec answers:
+
+1. **Queue query** — how to list pending bugs, oldest first: exact tool name plus the query or call template.
+2. **Detail fetch** — how to fetch one bug's complete record by ID, and what the key fields mean (title, reproduction
+   steps, error logs, module, page URL, severity).
+3. **Status write-back** — how to mark a bug `fixed` and `false-positive` (and any other states the platform tracks).
+4. **Scope filter** *(optional)* — the field that isolates this project's bugs when the platform hosts several projects
+   (e.g. a JIRA project ID). If batch processing MUST be scope-filtered, the spec must say "scope is REQUIRED" — the
+   batch scheduler enforces it.
+5. **Data verification** *(optional)* — extra tools for verifying business data while reproducing or verifying (e.g. a
+   business-database query tool).
+
+### Example: an AI-test-platform defect library over a MySQL MCP tool
+
+```toml
+platform_spec = """
+Defect platform: AI test platform, MySQL defect library via the `mcp__dev-mysql__mysql_query` tool.
+Table `t_defect_info`; status enum: 0=new, 1=verified, 2=fixed, 3=false-positive; soft delete flag `is_del`.
+Scope is REQUIRED for batch: every SELECT/UPDATE/COUNT must carry AND jira_id = '<scope>' (JIRA project ID).
+
+Queue query (oldest first):
+  SELECT defect_id, title, severity, defect_type, module_path, discover_time
+  FROM t_defect_info WHERE is_del = 0 AND defect_status = 0 [AND jira_id = '<scope>']
+  ORDER BY create_time ASC;
+
+Detail fetch:
+  SELECT * FROM t_defect_info WHERE defect_id = '<id>' AND is_del = 0;
+  Key fields: steps (reproduction), error_front (frontend log), error_apis (API errors), url (page).
+
+Status write-back (re-select afterwards to confirm):
+  fixed:          UPDATE t_defect_info SET defect_status = 2 WHERE defect_id = '<id>' [AND jira_id = '<scope>'] AND is_del = 0;
+  false-positive: UPDATE t_defect_info SET defect_status = 3 WHERE defect_id = '<id>' [AND jira_id = '<scope>'] AND is_del = 0;
+
+Data verification: business Oracle DB via `mcp__business-oracle__execute_query` for validating query logic and data.
+"""
+```
+
+Adapt tool names, table, and fields to your environment; paste the result into
+`{project-root}/_xiaoma/custom/xiaoma-bug-resolve.toml` under `[workflow]`.
+
+## Appendix: Bug-Queue File Format
+
+`{workflow.bug_list_file}` is a markdown file owned by the team — any tracker export or hand-written list works. One
+`##` section per bug:
+
+```markdown
+# Bug Queue
+
+## BUG-001: Search returns no results for partial keywords
+
+- status: pending <!-- pending | fixed | false-positive | blocked -->
+- severity: high
+- module: search
+- steps: open /search, type "auth", press Enter
+- expected: items whose names contain "auth"
+- actual: empty list; works only on exact match
+- evidence: logs/search-20260610.log
+```
+
+The workflow reads the first `pending` entry (or the args-specified ID) and, at closure, rewrites that entry's
+`status` line and appends `- report: {fix_report_dir}/{slug}-fix.md`. `blocked` is a human-set parking value: the
+workflow itself only ever writes `fixed` or `false-positive` (a blocked verdict leaves the entry `pending`), and it
+never picks entries whose status is anything other than `pending`.

package/src/xmc-skills/4-implementation/xiaoma-bug-resolve-batch/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: xiaoma-bug-resolve-batch
+description: "Batch bug resolution with Agent subprocess isolation. Drains ALL pending bugs from the defect platform or bug-queue file, each resolved in an independent full-tool Agent context, until the queue is empty. Use when the user says 'batch resolve bugs', 'resolve all bugs', 'BB', '批量修复bug', or '循环处理bug'."
+---
+
+Follow the instructions in [workflow.md](workflow.md).

package/src/xmc-skills/4-implementation/xiaoma-bug-resolve-batch/customize.toml

@@ -0,0 +1,34 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for xiaoma-bug-resolve-batch (the scheduler).
+# Bug-source settings (platform_spec, bug_list_file, test_url, ...) live in the
+# sibling xiaoma-bug-resolve/customize.toml — configure them ONCE there; this
+# scheduler resolves and inherits them. Override this file's keys in
+# {project-root}/_xiaoma/custom/xiaoma-bug-resolve-batch.toml (team) or
+# xiaoma-bug-resolve-batch.user.toml (personal).
+
+[workflow]
+
+# --- Configurable below. Overrides merge per XiaoMa structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+# Steps to run before the scheduler initializes. Overrides append.
+
+activation_steps_prepend = []
+
+# Steps to run after initialization but before the batch loop. Overrides append.
+
+activation_steps_append = []
+
+# Persistent facts for the scheduler itself. Kept empty by default — the
+# scheduler stays lightweight; project context is passed to each Agent
+# subprocess instead. Overrides append.
+
+persistent_facts = []
+
+# Executed after the final batch report. Override wins. Use for post-batch
+# automation: notify a channel, file a summary ticket, trigger CI.
+# Leave empty for no custom post-completion behavior.
+
+on_complete = ""

package/src/xmc-skills/4-implementation/xiaoma-bug-resolve-batch/workflow.md

@@ -0,0 +1,277 @@
+---
+name: bug-resolve-batch
+description: "Batch bug resolution scheduler with Agent subprocess isolation. Drains all pending bugs from the defect platform or bug-queue file, each resolved in an independent full-tool Agent context."
+---
+
+# Bug Resolve — Batch Mode (Agent Subprocess Isolation)
+
+**Goal:** Process ALL pending bugs in the queue — each one resolved end-to-end (analyze → fix → verify → close) in an
+**independent Agent subprocess** — fully automatic from start to finish, zero human intervention until the queue is
+empty.
+
+**Your Role:** Bug Batch Scheduler. You coordinate the loop and delegate each bug's full lifecycle to an independent
+Agent subprocess. You stay lightweight — query queue, launch Agent, read results, continue or finalize.
+
+- Communicate all responses in {communication_language} and generate all documents in {document_output_language}
+- Absolutely DO NOT stop because of "milestones", "significant progress", or "session boundaries". Continue in a single
+  execution until ALL bugs are processed or a HALT condition is triggered
+- **Fully automatic, no human intervention** — from start to finish, the user needs no commands
+
+---
+
+## Core Architecture: Agent-Isolated Processing
+
+Each bug is delegated to an **independent Agent subprocess**. Agents naturally have isolated context spaces, releasing
+upon completion without polluting the main conversation — no `/clear` needed. The main conversation only handles the
+lightweight scheduling loop.
+
+```text
+Main conversation (scheduler, minimal context)
+  ├── Agent #1 → Resolve Bug A (isolated context, released after completion)
+  ├── Agent #2 → Resolve Bug B (isolated context, released after completion)
+  ├── Agent #3 → Resolve Bug C (isolated context, released after completion)
+  └── ...until the queue is empty
+```
+
+### Core Rules (Strictly Follow)
+
+1. **Each bug processed by an independent Agent** — Use the Agent tool to launch a **general-purpose subprocess with
+   FULL tool-execution capability** (the complete tool set: file read/write/edit, shell/command execution, and test
+   running — **NOT** a restricted or read-only subagent such as an explore/plan/search-only type). Pass complete bug
+   info and processing instructions; the Agent independently completes analyze → fix → verify → close
+2. **Main loop stays lightweight** — the scheduler only: queries the queue → launches an Agent → reads results →
+   queries remaining → continues or ends
+3. **Serial processing** — one bug at a time; wait for Agent completion before the next, avoiding concurrent
+   modification conflicts
+4. **Scope is a hard isolation boundary** — when a scope filter is in effect, EVERY queue query, detail fetch, and
+   status write-back (scheduler-side and Agent-side) must carry it
+
+---
+
+## INITIALIZATION
+
+### Resolve Configuration
+
+1. **Single-bug workflow block** (the single source of truth for bug-source settings):
+   run `node {project-root}/_xiaoma/scripts/resolve_customization.js --skill {skill-root}/../xiaoma-bug-resolve --key workflow`
+   → yields `bug_source`, `bug_list_file`, `platform_spec`, `test_url`, `max_fix_iterations`, `fix_report_subdir`, and
+   the sibling's `persistent_facts` (project knowledge destined for every Agent subprocess — resolve `file:` entries
+   to their contents now, keep literal entries verbatim).
+2. **Own workflow block:** run the same script with `--skill {skill-root}` → yields this scheduler's
+   `activation_steps_*`, `persistent_facts`, `on_complete`. Execute prepend steps, load facts, execute append steps.
+3. Load `{project-root}/_xiaoma/xmc/config.yaml` and resolve: `user_name`, `communication_language`,
+   `document_output_language`, `implementation_artifacts`, `project_knowledge`, and `date` as system-generated current
+   datetime.
+
+If the resolver script fails, perform the merges manually (customize.toml + `_xiaoma/custom/<skill-name>.toml` +
+`<skill-name>.user.toml`; scalars override, arrays append).
+
+### Paths
+
+- `single_bug_workflow` = `{skill-root}/../xiaoma-bug-resolve/workflow.md` (the sibling single-bug skill — each Agent
+  subprocess follows its Step 2–5 procedure)
+- `batch_status_file` = `{implementation_artifacts}/bug-batch-status.json`
+
+### Parse Args
+
+This scheduler accepts at most ONE positional token: the **scope filter** (e.g. a JIRA project ID isolating this
+project's bugs on a shared platform). Rules:
+
+- A token containing `=` is NOT a scope — treat scope as not provided and tell the user (key=value args such as
+  `testUrl=...` belong to the single-bug skill, not to batch mode). If args contain more than one token, HALT and
+  explain that batch mode takes a single scope token only.
+- If `{platform_spec}` declares "scope is REQUIRED" and no scope token was provided: HALT —
+  "This platform requires a scope filter. Re-run as: `/xiaoma-bug-resolve-batch <scope>` (e.g. a JIRA project ID)."
+- When a scope is in effect, it is a hard constraint inherited by every query and every Agent subprocess.
+- File mode ignores scope (a bug-queue file is already project-local).
+
+---
+
+## WORKFLOW
+
+<workflow>
+
+<step n="1" goal="Validate the source is batchable and display the queue overview">
+
+1. Resolve the bug source exactly as the single-bug workflow does (`auto`: platform_spec non-empty → platform; else
+   bug_list_file exists → file). **Interactive is not batchable** — if neither platform nor file resolves, HALT:
+   "Batch mode needs a queue: configure platform_spec or create {bug_list_file}. For a single described bug, use
+   xiaoma-bug-resolve (BR)."
+2. Query queue statistics (scope-filtered when in effect): pending / fixed / false-positive counts.
+3. If pending == 0: go to Step 3 (final report).
+4. List the pending bugs (ID, title, severity, module) oldest first.
+5. Output the overview — include the scope line whenever a scope is in effect:
+
+   ```text
+   ===============================================
+     Bug Resolve — Batch Mode
+     (Agent Subprocess Isolation)
+   ===============================================
+   Scope: {scope or "—"}
+   Pending: {pending} | Fixed: {fixed} | False-positive: {false_positive}
+
+   Processing all {pending} bugs sequentially, each in an
+   independent Agent subprocess. Starting now...
+   -----------------------------------------------
+   ```
+
+6. Initialize tracking: `bugs_fixed` = 0, `bugs_false_positive` = 0, `bugs_failed` = 0, `failed_bug_keys` = [],
+   `bug_results` = [].
+
+</step>
+
+<step n="2" goal="Loop: resolve each bug in an independent Agent subprocess (fully automatic)">
+
+### 2.1 Find the Next Pending Bug
+
+Query the queue fresh (scope-filtered when in effect), oldest first, skipping any key in `failed_bug_keys`. If no
+processable bug remains, go to Step 3. Fetch the bug's complete record (platform detail fetch / full file entry).
+
+Output: `Processing bug: {bug_key} — {title}`
+
+### 2.2 Launch the Independent Agent Subprocess
+
+<critical>
+
+Use the Agent tool to launch a **general-purpose subprocess with FULL tool-execution capability** to resolve this bug.
+This subprocess **MUST** have the complete tool set enabled — file read/write/edit, shell/command execution, and test
+execution — because it runs the entire bug lifecycle (analyze → fix → verify → close). Do **NOT** delegate to a
+restricted or read-only subagent (e.g. an explore-, plan-, or search-only type): such agents cannot edit files or run
+commands, so the lifecycle would fail. When the host tool exposes a subagent-type selector, choose the type whose
+toolset is the full/unrestricted set (in Claude Code this is the `general-purpose` type).
+
+The Agent's prompt MUST contain, so it can work fully independently:
+
+**1. Bug record:** every field fetched in 2.1 (ID, title, reproduction steps, error logs, module, page URL, severity,
+type) — pass actual content, not references. **Plus the scope value as a hard constraint when in effect: every
+platform query and status write-back must carry it.**
+
+**2. Configuration (inline all resolved values):** `communication_language`, `document_output_language`,
+`implementation_artifacts`, `max_fix_iterations`, `fix_report_subdir`, `test_url`, the resolved bug-source mode, and —
+verbatim — `platform_spec` (platform mode) or the `bug_list_file` path (file mode).
+
+**3. Procedure:** read `{single_bug_workflow}` and execute its Step 2 (root-cause analysis and verdict), Step 3 (fix —
+real defects only), Step 4 (verify), and Step 5 items 1–3 ONLY (fix report, status write-back, closure summary — skip
+items 4–5: queue reporting and `on_complete` belong to this scheduler). Intake (Step 1) is already done — the record
+above is authoritative. Operating constraints:
+
+- You are running unattended: never wait for a user. Where the single-bug workflow says "ask the user", instead record
+  the gap; if the verdict cannot be reached without missing evidence, return verdict `blocked` — do NOT guess
+- Fix strictly within the defect's scope; follow project conventions (CLAUDE.md, project-context.md)
+- Track every file you modify. If you finish with verdict `blocked` or `failed`, restore the files you modified to
+  their pre-run state (leave files that already had unrelated local changes alone) and say so in `error` — the next
+  bug must start from a clean tree
+- Write the fix report and execute the status write-back exactly as Step 5 specifies (status updates carry the scope
+  when in effect)
+
+**4. Project context:** include the content of `project-context.md` if it exists (actual content, not just the path),
+plus the sibling `persistent_facts` resolved during INITIALIZATION (file contents inlined, literal entries verbatim).
+
+**5. Return format** — when done, return exactly:
+
+```text
+BUG_RESULT:
+- bug_key: {bug_key}
+- verdict: fixed | false-positive | blocked | failed
+- files_modified: [list of files, empty for false-positive/blocked]
+- report_file: {path to the fix report, empty if not written}
+- verification: {one-line verification outcome or gap}
+- summary: {one-line description of what was done}
+- error: {message if blocked/failed, empty otherwise}
+```
+
+</critical>
+
+### 2.3 Read the Agent Result and Handle Errors
+
+- `verdict: fixed` → increment `bugs_fixed`
+- `verdict: false-positive` → increment `bugs_false_positive`
+- `verdict: blocked`, `failed`, or no parseable BUG_RESULT → increment `bugs_failed`, append the bug key to
+  `failed_bug_keys` (prevents re-selecting it this run — its source status stays pending, so a later run can retry),
+  output `Bug {bug_key} blocked/failed — skipping and continuing.` — do NOT halt the batch
+- Append the result to `bug_results`; output a one-line result for this bug
+
+### 2.4 Refresh and Continue
+
+Re-query the queue statistics (fresh, scope-filtered when in effect) and output a checkpoint:
+
+```text
+--- Batch checkpoint: fixed {bugs_fixed} | false-positive {bugs_false_positive} | failed {bugs_failed} | remaining {pending} ---
+```
+
+If a processable bug remains (pending minus `failed_bug_keys`): return to 2.1. Otherwise go to Step 3.
+
+</step>
+
+<step n="3" goal="Final report and machine-readable batch status">
+
+1. Query the final queue state (scope-filtered when in effect).
+2. Write `{batch_status_file}` atomically (write `.tmp`, then rename):
+
+   ```json
+   {
+     "pipeline": "bug-resolve-batch",
+     "date": "{date}",
+     "scope": "{scope_or_empty}",
+     "source_mode": "platform|file",
+     "bugs_fixed": 0,
+     "bugs_false_positive": 0,
+     "bugs_failed": 0,
+     "failed_bug_keys": [],
+     "bug_results": [
+       {
+         "bug_key": "...",
+         "verdict": "fixed|false-positive|blocked|failed",
+         "files_modified": ["..."],
+         "report_file": "...",
+         "verification": "...",
+         "summary": "...",
+         "error": ""
+       }
+     ]
+   }
+   ```
+
+   If the batch is halted early, still write this file — the partial run is auditable.
+
+3. Output the final report:
+
+   ```text
+   ===============================================
+     Bug Resolve Batch — COMPLETE
+   ===============================================
+   Scope: {scope or "—"}
+
+   Fixed: {bugs_fixed}
+   False-positive: {bugs_false_positive}
+   Blocked/Failed (skipped, still pending at source): {bugs_failed}
+   Remaining pending: {pending}
+
+   Details:
+   | Bug | Verdict | Files | Report |
+   |-----|---------|-------|--------|
+   | ... | ...     | ...   | ...    |
+
+   Batch status: {batch_status_file}
+   ===============================================
+   ```
+
+4. If `bugs_failed` > 0: list each failed/blocked bug with its `error` and what evidence or access would unblock it.
+5. Execute `{workflow.on_complete}` if non-empty. **HALT** — batch complete.
+
+</step>
+
+</workflow>
+
+---
+
+## Important Notes
+
+1. **Agent isolation is key** — each bug runs in an independent subprocess with isolated context; bugs never interfere
+2. **Serial safety** — one bug at a time avoids concurrent modifications to the same codebase
+3. **No infinite retries** — blocked/failed bugs go into `failed_bug_keys` and are skipped for the rest of THIS run;
+   their source status remains pending so the next run (or a human) can pick them up with fresh context
+4. **Scope discipline** — on shared defect platforms, running without the required scope would pull other projects'
+   bugs and mis-edit code and statuses; that is why the platform spec can make scope mandatory
+5. **Agent prompt quality** — each subprocess prompt must carry the complete bug record + resolved config + the
+   platform spec or file path + the return format, so it can work with zero callbacks

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

@@ -29,4 +29,6 @@ XiaoMa Method,xiaoma-code-review,Code Review,CR,Story cycle: If issues back to D
 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
+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
+XiaoMa Method,xiaoma-bug-resolve,Bug Resolve,BR,Resolve one bug end-to-end: intake from defect platform / bug-queue file / user description then root-cause fix verify and close with a fix report.,,,4-implementation,,,false,implementation_artifacts,fix report
+XiaoMa Method,xiaoma-bug-resolve-batch,Bug Resolve Batch,BB,Drain ALL pending bugs sequentially with Agent subprocess isolation until the queue is empty.,,,4-implementation,xiaoma-bug-resolve,,false,implementation_artifacts,fix reports and batch status