@zeyue0329/xiaoma-cli 1.12.0 → 1.15.0

package/src/xmc-skills/2-plan-workflows/xiaoma-edit-prd/customize.toml

@@ -0,0 +1,42 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for xiaoma-edit-prd. Mirrors the
+# agent customization shape under the [workflow] namespace.
+
+[workflow]
+
+# --- Configurable below. Overrides merge per XiaoMa structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+# Steps to run before the standard activation (config load, greet).
+# Overrides append. Use for pre-flight loads, compliance checks, etc.
+
+activation_steps_prepend = []
+
+# Steps to run after greet but before the workflow begins.
+# Overrides append. Use for context-heavy setup that should happen
+# once the user has been acknowledged.
+
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run
+# (standards, compliance constraints, stylistic guardrails).
+# Distinct from the runtime memory sidecar — these are static context
+# loaded on activation. Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "All PRDs must include a regulatory-risk section."
+#   - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/standards.md"
+#     (glob patterns are supported; the file's contents are loaded and treated as facts).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# Scalar: executed when the workflow reaches Step E-4 (Complete & Validate) and the
+# user exits via [S] Summary or [X] Exit — not on [V] Validate (which chains to
+# xiaoma-validate-prd) or [E] Edit More (which loops back). Override wins.
+# Leave empty for no custom post-completion behavior.
+
+on_complete = ""

package/src/xmc-skills/2-plan-workflows/xiaoma-prd/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: xiaoma-prd
+description: Create, update, or validate a PRD. Use when the user wants help producing, editing, or validating a PRD.
+---
+# XiaoMa PRD
+
+You are a master facilitator and coach helping the user create, edit, or validate a high quality PRD scoped to the level and rigor appropriate to their stated needs. Fight the urge to do the thinking for them unless they put you into Fast path.
+
+## Conventions
+
+- Bare paths resolve from skill root; `{skill-root}` is this skill's install dir; `{project-root}` is the project working dir.
+- `{workflow.<name>}` resolves to fields in `customize.toml`'s `[workflow]` table (overrides win per XiaoMa merge rules).
+- `{doc_workspace}` is the bound run folder.
+- **File roles.** `.decision-log.md` is canonical memory and audit trail — every decision, change, and override (including headless overrides) is recorded there as the conversation unfolds. `addendum.md` preserves user-contributed depth that belongs in a downstream document (architecture, solution design, UX spec) or earned a place but does not fit the PRD itself — rejected-alternative rationale, options-considered matrices, mechanism/transport decisions, technical-how, in-depth personas, sizing data. Capture to the addendum *during* the conversation when the user volunteers such content — do not wait for finalize. Audit and override information never goes in the addendum.
+
+## On Activation
+
+1. Resolve customization: `node {project-root}/_xiaoma/scripts/resolve_customization.js --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults.
+2. Run `{workflow.activation_steps_prepend}`. Treat `{workflow.persistent_facts}` as foundational context (entries prefixed `file:` are loaded). `{workflow.external_sources}` is an org-configured registry of internal tools (knowledge bases, MCP tools); consult them alongside generic web research on the same triggers, org tools preferred when their directive matches. Research itself fires during Discovery — see **Research subagents**.
+3. Load `{project-root}/_xiaoma/xmc/config.yaml` (+ `config.user.yaml` if present). Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`. Missing keys → neutral defaults; never block.
+4. If headless, follow `references/headless.md` for the whole run. Otherwise greet the user **by name** using `{user_name}` and **in their language** using `{communication_language}` — and stay in `{communication_language}` for every turn for the entire run, not just the greeting. In the greeting, let the user know that at any point they can invoke `xiaoma-party-mode` for multi-agent perspectives or `xiaoma-advanced-elicitation` for deeper exploration on a specific section. Then scan for misroute on the first message: if the signal points elsewhere (game → XiaoMa GDS; express build → `xiaoma-quick-dev`; one-pager → `xiaoma-product-brief`; vet product idea → `xiaoma-prfaq`; agent skill or custom agent → `xiaoma-workflow-builder`), suggest they might want the other options before continuing.
+5. Detect intent: **Create** (no PRD), **Update** (existing PRD), **Validate** (critique only). If ambiguous, ask. For Create intent, before binding a fresh workspace, scan `{workflow.prd_output_path}` for prior in-progress runs (folders matching `{workflow.run_folder_pattern}` whose `prd.md` frontmatter `status` is not `final`); if any exist, offer to resume rather than starting over.
+
+Run `{workflow.activation_steps_append}`.
+
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
+
+## Intent Modes
+
+**Create.** Bind `{doc_workspace}` to `{workflow.prd_output_path}/{workflow.run_folder_pattern}/`. Write `prd.md` with YAML frontmatter (title, status, created, updated — initial `status: draft`), and create the `.decision-log.md` skeleton at the workspace root so subsequent decisions land in a known file. Tell the user the path. Run `## Discovery`, then `## Finalize`.
+
+**Update.** Reconcile the PRD with a change signal. Source-extract against PRD, addendum, `.decision-log.md`, and original inputs (extract, don't ingest). If `.decision-log.md` is missing, spawn a one-time bootstrap subagent to reverse-engineer a thin log from the PRD before continuing. Surface conflicts with prior decisions before applying. Then `## Finalize`.
+
+**Validate** (or *analyze*). Critique without changing. Load `references/validate.md`.
+
+## Discovery
+
+Order: **Brain dump → Stakes calibration → Working mode → mode-scoped work.** Get to working mode fast — two or three turns, not ten. Users in a hurry must not be held hostage by upstream probing.
+
+**Brain dump.** Always the first move, even when the user opens with paragraphs of context (that is intake, not the dump). Ask for verbal context *and* any existing inputs they want you to read — product brief, research, customer transcripts, competitive analysis, prior PRD draft, design docs. Paths or paste; big docs are fine, you will subagent-extract. A simple "anything else?" surfaces what they almost forgot.
+
+**Research subagents (default).** During Discovery, spawn web-research subagents to ground the picture: what exists in the space, how comparables position themselves, current landscape. Subagent does the search; parent receives a digest.
+
+**Elicitation, not direction.** Discovery pulls the user's vision out; it does not insert yours. Open-ended "tell me about X" beats multiple choice. When you find yourself naming wedges, picking MVP cuts, or proposing phases, stop — you have crossed from elicitation into authoring. Hand the pen back. Infer-and-confirm ("I'm assuming X works like Y — right?") is fine; quizzing the user through a tree of LLM-shaped choices is not.
+
+**Stakes calibration.** One short probe before working mode: hobby / internal / launch — enough to calibrate rigor and section depth. Audience, Existing inputs, and Downstream depth fill in inside the chosen mode, not upstream of the choice.
+
+**Working mode.** Offer the choice in the user's language:
+
+- **Fast path** — I batch remaining gaps into one or two consolidated questions, then draft the full PRD with `[ASSUMPTION]` tags where I inferred. You review and we iterate. The initial quality depends on how much you gave me upfront.
+- **Coaching path** — we walk PM-thinking sections together. Once chosen, I ask which entry point fits: **Vision + Features** (capability-first — for enterprise, dev products, internal tools, anyone who thinks in features), **Journey-led** (user-first — for consumer, UX-heavy, multi-stakeholder products; journeys with named protagonists carry persona context inline, no standalone persona section), or *let me suggest* based on what I heard. The chosen entry sets the section order.
+
+The workspace persists; stop and resume freely.
+
+**Concern scan.** As you read what the user gave you, name the concerns this product actually carries — compliance, integration density, operational SLAs, hardware constraints, public-API contracts, monetization, data governance, whatever applies. The list is open; recognize what's there, do not classify into a fixed shape. These concerns drive which template sections to pull in from the Adapt-In Menu and which to invent when no cluster names them.
+
+**Form-factor.** If not stated in sources, probe — mobile / web / desktop / multi-surface / hardware / API.
+
+**User Journeys are captured, not authored.** When UJs are warranted (consumer / multi-stakeholder B2B / meaningful UX — drop or downscale for internal tooling with a single operator role, regulatory-only updates, hobby/solo, pure technical PRDs), prompt the user to narrate a real session with a named protagonist (Mary, mom of three — not "the user") — what the person does, in what order, where it lands — then structure the answer into UJ-N form and confirm. Persona context lives inline at the moments that matter; no standalone persona section.
+
+## PRD Discipline
+
+**Shape.** Features grouped; FRs nested with globally numbered stable IDs. Cross-cutting NFRs in their own section; skip traceability matrices. Capabilities, not implementation — tech choices live in `addendum.md`. Treat `{workflow.prd_template}` as expert prior knowledge, not a checklist. The **Essential Spine** is the expected default — present it unless the product genuinely doesn't need a section, and when you drop one, do so for a reason a reviewer would agree with. The **Adapt-In Menu** is conditional: pull in the clusters the product's concerns need to best define the requirements. When the product carries a concern the menu doesn't name, invent the section — name it well, decide what belongs in it, place it where it serves the reader or the PRD. Reorder and combine for readability. Never include a section because it appears; never skip a concern because no template section covered it. Counter-metrics named when Success Metrics exist.
+
+**Extract, don't ingest.** Source documents go to subagents for extraction; the parent assembles from extracts. Only load source documents into the parent context wholesale when no subagents are available.
+
+**Length scales with stakes.** Hobby / solo PRDs aim for about two pages. Internal tools land around five to eight. Launch and chain-top PRDs run as long as their FRs and concerns require. Whatever the length, detail that doesn't earn its place in the PRD's main narrative belongs in `addendum.md` — moving overflow there is correct; padding the PRD to look thorough is not.
+
+## Reviewer Gate
+
+Used by the Validate intent and at Finalize step 3.
+
+Assemble the menu: rubric walker against `{workflow.validation_checklist_template}` (the PRD quality rubric) + each entry in `{workflow.finalize_reviewers}` + any ad-hoc reviewers the artifact warrants. Stakes-calibrated — hobby/solo may run quietly or skip; higher stakes get the explicit all/subset/skip menu.
+
+Dispatch entries as parallel subagents against `prd.md` (and `addendum.md` if present) using the standard prefix convention (`skill:` / `file:` / plain text). Each writes its full review to `{doc_workspace}/review-{slug}.md` and returns ONLY a compact summary (verdict, top 2-5 findings, file path) — the parent never holds full review text. The rubric walker uses the prompt and output format in `references/validate.md`. If subagents are unavailable, run sequentially: write the file *before* anything else, then flush the review from working context.
+
+Surface findings tiered, never dumped. Lead with a one-sentence gate verdict, then walk critical + high findings; medium/low roll into a single tail ("plus N more in {file}"). Read the full `review-{slug}.md` only when the user drills into a specific finding. Per finding: autofix, discuss, defer to open items, or ignore.
+
+Under Validate intent, the parent additionally runs the synthesis pipeline in `references/validate.md` — folding every selected reviewer's output into a single HTML + markdown report and opening the HTML.
+
+## Finalize
+
+Tell the user the sequence in one sentence, then walk it. Polish goes last so it does not redo work after reviewer fixes.
+
+1. **Decision log audit.** Walk `.decision-log.md` with the user; each entry captured in PRD, in addendum, or set aside.
+2. **Input reconciliation.** Subagent per user-supplied input against `prd.md` + `addendum.md`. Each writes its extract to `{doc_workspace}/reconcile-{slug}.md` and returns ONLY a compact summary (input name, gaps 2-5, file path). Surface gaps — especially qualitative ideas (tone, voice, feel) the FR structure silently drops. Must happen before polish.
+3. **Reviewer pass.** Run `## Reviewer Gate`. Resolve before polish.
+4. **Triage open items.** All Open Questions, `[ASSUMPTION]` tags, `[NOTE FOR PM]` callouts. Phase-blockers (would make the PRD unsafe for UX/architecture/epics) surfaced one at a time and resolved; non-blockers deferred with owner + revisit condition logged to `.decision-log.md`. If phase-blocker count is high, flag it.
+5. **Polish.** Apply `{workflow.doc_standards}` to `prd.md` and `addendum.md` in declared order (structural passes before prose — prose should not polish soon-to-be-cut text). Parallelize across documents, sequential within.
+6. **External handoffs.** Execute `{workflow.external_handoffs}`; surface returned URLs/IDs. Skip and flag unavailable tools.
+7. **Close.** Set `prd.md` frontmatter `status: final` and `updated` to `{date}` so future invocations distinguish this PRD from in-progress drafts. Record finalization to `.decision-log.md`. Share artifact paths. Common next: `xiaoma-ux`, `xiaoma-create-architecture`, `xiaoma-create-epics-and-stories`; invoke `xiaoma-help` for authoritative routing.
+8. Run `{workflow.on_complete}` if non-empty.

package/src/xmc-skills/2-plan-workflows/xiaoma-prd/assets/headless-schemas.md

@@ -0,0 +1,76 @@
+# Headless Mode JSON Schemas
+
+Every headless run ends with one of these payloads. Omit keys for artifacts not produced.
+
+## Common fields
+
+- `status` — `"complete"`, `"blocked"`, or `"partial"`
+- `intent` — `"create"`, `"update"`, or `"validate"` (matches the detected intent)
+- `reason` — required when `status` is `"blocked"`; one-sentence explanation
+- `assumptions` — array of inferred values that were not directly confirmed by inputs
+- `open_questions` — array of items that need a human decision before the artifact can be considered final
+
+## Create
+
+```json
+{
+  "status": "complete",
+  "intent": "create",
+  "prd": "{doc_workspace}/prd.md",
+  "addendum": "{doc_workspace}/addendum.md",
+  "decision_log": "{doc_workspace}/.decision-log.md",
+  "open_questions": [],
+  "assumptions": [],
+  "external_handoffs": [
+    {"directive": "Confluence upload", "tool": "corp:confluence_upload", "url": "https://confluence.corp/PROD/123", "status": "ok"}
+  ]
+}
+```
+
+## Update
+
+```json
+{
+  "status": "complete",
+  "intent": "update",
+  "prd": "{doc_workspace}/prd.md",
+  "decision_log": "{doc_workspace}/.decision-log.md",
+  "changes_summary": "1-3 sentences describing what changed and why",
+  "conflicts_with_prior_decisions": [],
+  "open_questions": [],
+  "external_handoffs": [
+    {"directive": "Confluence upload", "tool": "corp:confluence_upload", "url": "https://confluence.corp/PROD/123", "status": "ok"}
+  ]
+}
+```
+
+## Validate
+
+```json
+{
+  "status": "complete",
+  "intent": "validate",
+  "validation_report": "{doc_workspace}/validation-report.md",
+  "findings_summary": {
+    "critical": 0,
+    "high": 0,
+    "medium": 0,
+    "low": 0
+  },
+  "offer_to_update": true
+}
+```
+
+`validation_report` is always written for Validate intent — the path here is required, not optional.
+
+## Blocked
+
+```json
+{
+  "status": "blocked",
+  "intent": "update",
+  "reason": "Change signal ambiguous — could be a scope expansion or a clarification; no inferred direction"
+}
+```
+
+Always include the intent (best-guess if not certain) and a one-sentence `reason`.

package/src/xmc-skills/2-plan-workflows/xiaoma-prd/assets/prd-template.md

@@ -0,0 +1,165 @@
+# PRD Template
+
+## Essential Spine *(almost always present)*
+
+```markdown
+---
+title: {Product Name}
+created: {YYYY-MM-DD}
+updated: {YYYY-MM-DD}
+---
+
+# PRD: {Product Name}
+*Working title — confirm.*
+
+## 0. Document Purpose
+[1 paragraph: who this PRD is for (PM, stakeholders, downstream workflow owners), how it's structured (Glossary-anchored vocabulary, features grouped with FRs nested, assumptions tagged inline and indexed). If UX work or other inputs already exist, name them here and reference where they live — this PRD builds on them, it does not duplicate.]
+
+## 1. Vision
+[2-3 paragraphs: what this is, what it does for the user, why it matters. Compelling enough to stand alone.]
+
+## 2. Target User
+
+### 2.1 Jobs To Be Done
+[Bulleted. Emotional, social, functional, contextual — whichever apply. Even "this is for me as the builder" is a valid framing for a hobby project.]
+
+### 2.2 Non-Users (v1) *(add when the audience boundary is non-obvious)*
+[Who this is explicitly not for in v1.]
+
+### 2.3 Key User Journeys
+*Named-persona narratives the product enables. Numbered globally as UJ-1 through UJ-N. FRs reference journeys by ID inline ("realizes UJ-3"); SMs may also cross-reference. If a UX doc already exists, mirror its UJ IDs here and point to the source.*
+
+**Default shape:** a named scene with entry state, path, climax, and resolution. Each beat forces specificity the team would otherwise leave implicit — auth assumptions, screen order, what tells the user value landed. Read together as a short narrative; the example below shows the form.
+
+- **UJ-1. {One-line title — persona doing the thing.}**
+  - **Persona + context:** one line, grounded enough to explain the *why*.
+  - **Entry state:** authenticated? which surface? coming from where?
+  - **Path:** 3-5 concrete beats — taps, screens, decisions.
+  - **Climax:** the moment value is delivered and how the user knows.
+  - **Resolution:** state they're left in, what's next.
+  - **Edge case** *(optional)*: one real failure mode and what the user does next.
+
+  *Written out, that becomes:*
+  > **UJ-3. Priya checks the trip damage before she's even home.**
+  > Priya, budgeting on a single income with a new baby, finishes a grocery run and gets in the car. Already authenticated via biometric on a previous session. She opens the app, taps the FAB camera, and scans the receipt. The app OCRs the total and shows a single-screen overlay: this trip $84.20, weekly cap $250, $172.10 remaining, three days left in the week. She closes the app and drives home. **Edge case:** if she scanned a receipt earlier today, the app asks whether this replaces or adds to that trip before counting it against the cap.
+
+- **UJ-2. ...**
+
+**Scope dial:**
+- **Lighter** — hobby/solo, library/CLI, or when the UJ is essentially a JTBD restated: a single sentence works (`{Persona}, {context}, {what they do and why}.`).
+- **Heavier** — auth, multi-device handoff, complex navigation, or anything feeding downstream UX/architecture: add a numbered Flow, an Edge cases list, and a capability → FR mapping (`The system must {capability}. → FR-N`).
+
+## 3. Glossary
+*Downstream workflows and readers must use these terms exactly. FRs, UJs, and SMs use Glossary terms verbatim; introducing a synonym anywhere in the PRD is a discipline violation. If §4 introduces a new domain noun, add it to the Glossary in the same pass.*
+
+- **Term** — Definition. Relationships to other Glossary terms. Cardinality where relevant.
+- **Term** — ...
+
+[Every domain noun the rest of the document uses. Defined once. No synonyms anywhere else in the PRD.]
+
+## 4. Features
+*Each subsection is a coherent feature: behavioral description first, FRs nested under it, optional feature-specific NFRs and notes. FRs are numbered globally (FR-1 through FR-N) so downstream artifacts have stable references even if features get reorganized. Reference user journeys by ID inline ("realizes UJ-2") where the chain matters.*
+
+### 4.1 {Feature Name}
+**Description:** [Behavioral narrative — how this feature works, who uses it, the user experience, edge cases. Realizes UJ-X, UJ-Y. Use Glossary terms exactly. Embed inline `[ASSUMPTION: ...]` tags where you inferred without confirmation.]
+
+**Functional Requirements:**
+
+#### FR-1: {Short capability name}
+
+[Actor] can [capability] [under conditions]. Realizes UJ-X.
+
+**Consequences (testable):**
+- {Specific testable condition, e.g. "System returns HTTP 429 when request rate exceeds 100/sec per merchant."}
+- {Another testable condition.}
+
+**Out of Scope:** *(optional — what this FR explicitly does NOT cover)*
+- {bound}
+
+#### FR-2: ...
+
+**Feature-specific NFRs:** *(only if any apply uniquely to this feature)*
+- Performance / security / accessibility / etc. specific to this feature.
+
+**Notes:** *(optional — open questions specific to this feature, `[NOTE FOR PM]` callouts)*
+
+### 4.2 {Feature Name}
+...
+
+## 5. Non-Goals (Explicit)
+[Bulleted. What this product is *not* and what it will *not* do in v1. Does outsized work for downstream readers and workflows — prevents the "let me also add this nearby thing" failure mode at every level (epic, ticket, code). Inline `[NON-GOAL for MVP]` callouts within §4 Features cover deferred items within features; this section captures the broader "we are not building X / we are not becoming Y" statements.]
+
+## 6. MVP Scope
+
+### 6.1 In Scope
+[Bulleted, crisp.]
+
+### 6.2 Out of Scope for MVP
+[Bulleted. Each item with a one-line reason if the reason matters. Mark items deferred to v2/v3 explicitly. Add `[NOTE FOR PM]` callouts where a deferred item is emotionally load-bearing — flags it for revisit if timeline permits.]
+
+## 7. Success Metrics
+
+*Each SM cross-references the FR(s) it validates. Counter-metrics counterbalance specific primary or secondary metrics.*
+
+**Primary**
+- **SM-1**: Metric — definition, target. Validates FR-X, FR-Y.
+
+**Secondary**
+- **SM-2**: Metric — definition, target. Validates FR-Z.
+
+**Counter-metrics (do not optimize)**
+- **SM-C1**: Metric — why this should *not* be optimized. Counterbalances SM-1.
+
+[Length scales with stakes. Hobby/utility PRD: a single sentence may be enough ("Success: I use this weekly and don't abandon it after a month"). Public launch / enterprise: full quantitative breakdown with measurement methods. Counter-metrics are as load-bearing as primary metrics — they prevent the architect from optimizing the wrong thing and the dev from gaming the wrong target.]
+
+## 8. Open Questions
+[Numbered. Things still unknown — they become future tickets or follow-up research, not silent gaps.]
+
+## 9. Assumptions Index
+*Every `[ASSUMPTION]` from the document, surfaced for explicit confirmation:*
+- Inline assumption from §X.Y — short description.
+- ...
+```
+
+---
+
+## Adapt-In Menu *(add the clusters the product calls for)*
+
+### Cross-cutting quality and shape *(most non-trivial PRDs)*
+- **Cross-Cutting NFRs** — system-wide non-functional requirements not tied to a single feature (performance, security, reliability, observability). Add when system-wide quality attributes are meaningful.
+- **Constraints and Guardrails** — Safety, Privacy, Cost. Subsection per cluster. Add when any of these are real concerns.
+- **Why Now** — add when timing is load-bearing (a market shift, a technology enabler, a regulatory deadline). Drop when timing is incidental.
+
+### Consumer / branded products
+- **Aesthetic and Tone** — visual references, anti-references, voice/tone for any product-generated text.
+- **Information Architecture** — top-level surfaces, navigation, screens.
+- **Monetization** — free vs. paid, pricing assumptions, ads policy.
+- **Platform** — web, mobile, PWA, native, v1 vs. v2+.
+
+### Enterprise initiatives
+- **Stakeholders and Approvals** — who must sign off, at what stage.
+- **Risk and Mitigations** — operational, security, business, reputational risk register.
+- **ROI / Business Case** — quantified benefit, cost, payback period.
+- **Operational Requirements** — SLAs, RTO/RPO, support tier, on-call expectations.
+- **Integration and Dependencies** — SSO, existing enterprise systems, data sources, downstream consumers.
+- **Rollout and Change Management** — phased rollout plan, training, internal communication.
+- **Data Governance** — residency, sovereignty, classification, retention.
+- **Audit Trail / Decision Provenance** — formal documentation requirements for regulated environments.
+
+### Regulated domains
+- **Compliance and Regulatory** — HIPAA, PCI-DSS, GDPR, SOX, SOC 2, Section 508 / WCAG 2.1 AA, FedRAMP, etc. — whichever apply. If any item needs depth, add a `[NOTE FOR PM]` callout to revisit or move to an addendum.
+
+### Developer products (libraries, APIs, CLIs, SDKs)
+- **API Contracts / Public Surface** — endpoint shapes, breaking change policy.
+- **Versioning and Deprecation Policy**.
+- **Performance Budgets** — latency, throughput, resource use.
+- **Language / Runtime Targets and Dependency Policy**.
+
+### Embedded / hardware
+- **Hardware Constraints** — memory, power, form factor.
+- **Deployment and Update Mechanism** — OTA, manual, image-based.
+- **Environmental and Reliability Requirements**.
+
+### Small-scope all-inclusive *(use when scope is 1-2 stories' worth and the user wants a single captured artifact — chosen during the Right-skill check in Discovery)*
+- **Stories** — story-level specs listed inline at the end of the doc. Each story: *"As a [persona], I can [action] [under conditions]. Acceptance: [testable criteria]."* Numbered Story-1, Story-2, ... for reference. Pair with very lean §1 Vision, §2 Target User (often just JTBD + one UJ), §3 Glossary (handful of terms), §4 Features (often a single feature), §6 MVP Scope (in/out very tight). The whole doc fits on a page or two and captures intent + implementable stories in one place. If the user doesn't want the captured artifact at all, `xiaoma-quick-dev` is the better path — this cluster is only for "I want a doc *and* the stories."
+

package/src/xmc-skills/2-plan-workflows/xiaoma-prd/assets/prd-validation-checklist.md

@@ -0,0 +1,217 @@
+# PRD Quality Rubric
+
+A judgment rubric for the validator subagent. Walk the PRD with these dimensions in mind and write substantive findings — not box-ticking. The goal is a review that tells the user whether this PRD is _good_, not whether it has the right section headers.
+
+This rubric folds XiaoMa's mechanical quality standard (the retired `xiaoma-validate-prd` rubric) into the holistic judgment frame. Some dimensions are forgiving and stakes-calibrated; others are unforgiving and downstream-critical. **Measurability, Traceability, SMART (FR/NFR), and Domain Compliance are the dimensions that silently break downstream work** — story creation, architecture, and regulatory sign-off all source-extract from them. Judge those hardest. Be specific everywhere — cite locations, quote phrases, name what's missing. Abstract criticism is failure of nerve.
+
+Most PRDs do not need every dimension scrutinized equally. Calibrate to the agreed stakes, the PRD's shape (consumer product, internal tool, regulatory update, technical capability spec), and what the PRD itself is trying to do.
+
+## How to use this rubric
+
+1. Read the full PRD (and addendum.md if present) before writing anything.
+2. For each dimension below, form a judgment — _strong / adequate / thin / broken_ — backed by specifics from the PRD.
+3. Write findings only where they add information. A `strong` dimension may need no findings; a `broken` one needs concrete, fixable ones.
+4. Severity ranks impact on the PRD's usefulness, not how easy the fix is. A vague Vision statement is _critical_ even though it's a one-paragraph fix; a glossary drift might be _low_ even though it appears in many places. The unforgiving dimensions (Measurability, Traceability, SMART, Domain Compliance) bias toward _blocker/critical_ when they break, because downstream consumers cannot route around them.
+5. Mark a dimension _n/a_ when the PRD's shape genuinely doesn't need it (e.g. Project-Type Fit for a one-off internal note) and say why — don't penalize a PRD for skipping work it didn't need.
+6. The overall verdict is your synthesis — 2–3 sentences that name what holds up and what's at risk. Earn it with the dimension judgments.
+
+## Output format
+
+Write findings to `{doc_workspace}/review-rubric.md`:
+
+```markdown
+# PRD Quality Review — {prd_name}
+
+## Overall verdict
+
+[2–3 sentences. What holds up, what's at risk. Earned by the dimension judgments below.]
+
+## Decision-readiness — [strong | adequate | thin | broken]
+
+[1–3 paragraphs of judgment with specific PRD locations.]
+
+### Findings
+
+- **[blocker|critical|high|medium|low]** [Title] (§ location) — [Note]. _Fix:_ [suggested fix].
+
+## Substance over theater — [verdict]
+
+...
+
+(repeat for each dimension; mark n/a dimensions explicitly with a one-line reason)
+
+## Mechanical notes
+
+[Glossary drift, ID continuity, broken cross-refs, Assumptions Index roundtrip, frontmatter completeness. Lighter weight — these matter for downstream but don't drive the overall verdict.]
+```
+
+## The dimensions
+
+### 1. Decision-readiness
+
+Can a decision-maker act on this PRD? Are the trade-offs surfaced honestly, or has the PRD smoothed everything to neutral? Would someone pushing back find their objection acknowledged or dodged?
+
+Look for:
+
+- Decisions that are stated as decisions, not buried as "considerations."
+- Trade-offs named with what was given up, not just what was chosen.
+- Open Questions that are actually open — not rhetorical questions with an answer in the next sentence.
+- `[NOTE FOR PM]` callouts at real tensions, not at safe checkpoints.
+
+Red flag: a PRD where every choice "balances" everything, every NFR is "important," every persona "values" the product.
+
+### 2. Substance over theater
+
+Is the content earned, or is it furniture? Distinguish:
+
+- **Persona theater** — Personas that don't drive a single decision in the PRD. More than four personas. Personas whose only function is to make the PRD look thorough.
+- **Innovation theater** — claimed novelty that isn't novel. Differentiation sections written because the template had one, not because Discovery surfaced something.
+- **NFR theater** — copied boilerplate ("system must be scalable / secure / reliable") without product-specific thresholds.
+- **Vision theater** — a Vision statement that could swap into any PRD in this category without change.
+
+Flag what reads like furniture, even if it's well-written furniture.
+
+### 3. Information density
+
+Is every line carrying weight, or is the PRD padded with slogans and connective filler? This is where a polished-looking document hides an empty one.
+
+What good looks like: a concrete Executive Summary anchored in metrics rather than aspiration; dense FR/NFR bullets; almost no marketing fluff.
+
+What broken looks like: a slogan-driven summary, and roughly eight or more fluff phrases per hundred lines. Detection signals — phrases like "打造", "业界领先", "一站式", "赋能", "数字化转型", "智能化", "全方位", or English equivalents like "the system will allow", "it is important to note", "in order to". A handful across a long PRD is _thin_; a summary that reads like a pitch deck is _broken_. The fix is concrete: rewrite the Executive Summary around real metrics and cut the connective filler.
+
+### 4. Strategic coherence
+
+Does the PRD have a thesis? Do the features serve a unified arc, or is it a list of capabilities someone wanted?
+
+Look for:
+
+- A stated thesis the PRD bets on (problem framing, user insight, market move).
+- Feature prioritization that follows from the thesis — not from "what's easy first."
+- Success Metrics that validate the thesis, not metrics that just measure activity (DAU/MAU when the thesis is about engagement quality is a tell).
+- Counter-metrics named when Success Metrics exist.
+- Coherent MVP scope kind — problem-solving, experience, platform, or revenue — with scope logic that matches.
+
+Red flag: a PRD that reads as a backlog with section headings.
+
+### 5. Brief coverage
+
+Did the PRD actually consume its upstream inputs, or did it quietly drop them? Every "required" field from the product brief / upstream input contract should map into a PRD section.
+
+What good looks like: every required upstream field is represented somewhere in the PRD; no orphaned `TBD` markers standing in for content that was supposed to be carried forward.
+
+What broken looks like: required brief fields that never made it in, or a pile of unresolved `TBD: <field>` markers. One or two open TBDs on a draft is _adequate_; missing required inputs is _broken_ because the PRD is answering a different question than the one it was commissioned for. The fix is to complete the missing fields or convert each TBD into a real decision or an explicit `[ASSUMPTION]`.
+
+### 6. Measurability
+
+Would an engineer reading this PRD know what "done" looks like for each FR, and what threshold each NFR must hit? This is one of the unforgiving, downstream-critical dimensions — story creation leans on it hardest. Be unforgiving here.
+
+What good looks like: every FR phrased as a capability a named actor can perform ("[Actor] can [capability]"); every NFR carrying a metric, a threshold, a measurement method, and a window (e.g. "p95 latency < 200ms under 1k concurrent users, measured at the API gateway").
+
+What broken looks like: FRs and NFRs leaning on subjective adjectives — "easy", "fast", "simple", "intuitive", "user-friendly", "responsive", "quick", "efficient", or Chinese equivalents like "快速", "易用", "简单", "高效", "流畅", "稳定", "良好", "显著", "多个", "若干" — without numbers behind them. Any NFR with no measurement method, or any NFR that is a bare subjective adjective, drags the dimension toward _broken_. Flag "system handles X gracefully", "reasonable performance", "user-friendly" — every one. For non-functional sections (UX, performance, security), demand bounds, not adjectives. The fix is to add baseline + target + measurement + window per NFR and rewrite subjective FRs around verifiable outcomes.
+
+### 7. SMART (FR / NFR)
+
+Beyond raw measurability, is each requirement Specific, Measurable, Attainable, Relevant, and Traceable — and is it _atomic_? Compound requirements are the main failure mode here and the main reason a clean-looking FR explodes into ambiguity at story-creation time. This is one of the unforgiving, downstream-critical dimensions.
+
+What good looks like: one actor, one verb, one object per FR; NFRs that are individually attainable and tied to a real need.
+
+What broken looks like: compound FRs that smuggle multiple actions behind connectives — "且", "并", "同时", "以及", "并且", or "and … and" — or a single FR spanning two or more data objects. More than a few compound or unattainable requirements is _broken_. The fix is to split compound FRs along Actor / Verb / Object / Channel axes so each becomes independently testable and traceable.
+
+### 8. Implementation leakage
+
+Is the PRD describing _what_ and _why_, or has it leaked into _how_? Technology proper nouns in the problem, vision, journey, and functional sections are a tell that solutioning has bled upstream into the product definition.
+
+What good looks like: capability-level language throughout the vision, success criteria, user journeys, and functional requirements — no library, framework, datastore, or protocol names where a capability belongs.
+
+What broken looks like: terms such as Redis, PostgreSQL, MongoDB, MySQL, Kafka, RabbitMQ, JWT, OAuth, WebSocket, React, Vue, Angular, Spring, Django, Express, Docker, Kubernetes, AWS, GCP, Azure, gRPC, or GraphQL appearing inside the vision, success-criteria, journey, or functional sections. A leak or two confined to an explicitly technical Project-Type section is tolerable; any leak in vision / success / journeys / FRs is a real problem. The fix is to restate the leaked term as a capability, or relocate genuinely load-bearing technical facts to the Non-Functional / Project-Type sections.
+
+### 9. Done-ness clarity
+
+Would an engineer know what "done" looks like beyond the per-FR metrics — at the acceptance level?
+
+Look for:
+
+- FRs with at least one testable consequence each — a verifiable condition or measurable outcome.
+- Acceptance criteria implied or explicit. Sometimes the FR's consequences carry this; sometimes the PRD genuinely needs an Acceptance section.
+- For non-functional sections (UX, performance, security): bounds, not adjectives.
+
+This complements Measurability — Measurability judges whether each requirement is stated in verifiable terms; Done-ness judges whether the PRD as a whole tells the team when to stop.
+
+### 10. Scope honesty
+
+Are omissions explicit, or is the reader meant to infer them?
+
+Look for:
+
+- A Non-Goals section where it would do real work — and `[NON-GOAL for MVP]` callouts where omissions could be silently assumed.
+- `[ASSUMPTION: …]` tags on inferences the user didn't directly confirm, indexed at the end.
+- `[NOTE FOR PM]` callouts at deferred decisions and unresolved tensions.
+- De-scoping proposed honestly, not done silently.
+
+Open-items density: count Open Questions + `[ASSUMPTION]` + `[NOTE FOR PM]` callouts relative to stakes. High counts on a low-stakes PRD is fine; high counts on a green-light-to-build PRD is a blocker.
+
+### 11. Domain compliance
+
+For regulated or high-complexity domains, are the domain-specific sections present and substantive — or has the PRD treated a regulated product like a generic CRUD app? This is one of the unforgiving, downstream-critical dimensions: a missing regulatory section is not a style issue, it is a liability.
+
+Detect the domain from frontmatter or §1 signals and check it against `assets/domain-complexity.csv`. For any domain that file marks **high** complexity — healthcare, fintech, govtech, aerospace, automotive, legaltech, insuretech, energy, process_control, building_automation — the `special_sections` named for that domain (e.g. `clinical_requirements`, `regulatory_pathway`, `compliance_matrix`, `safety_certification`, `functional_safety`, `life_safety`) must each be present and substantive, not stubbed.
+
+What good looks like: every required special section for the detected domain present and meaningfully filled; regulatory landscape and industry terminology addressed.
+
+What broken looks like: a high-complexity domain with two or more required special sections missing, labeled N/A without justification, or reduced to a one-line stub. A single missing section is _thin_; multiple missing on a healthcare or fintech PRD is _broken_. The fix is to expand the domain section per the `special_sections` column in `assets/domain-complexity.csv` and consult domain research for the regulatory landscape.
+
+### 12. Project-type fit
+
+Does the PRD cover the sections its project type requires, and skip the ones that don't apply — or has it been forced into a one-size-fits-all template?
+
+Detect the project type from frontmatter or §1 signals and check it against `assets/project-types.csv`. Each type names its `required_sections` (e.g. `tenant_model` and `rbac_matrix` for `saas_b2b`; `endpoint_specs` and `auth_model` for `api_backend`; `platform_reqs` and `store_compliance` for `mobile_app`) and its `skip_sections` (areas that should be explicitly marked N/A rather than padded).
+
+What good looks like: every required section for the detected type covered substantively; skip-sections marked N/A on purpose rather than filled with filler.
+
+What broken looks like: two or more required sections missing for the detected type, or required areas reduced to a sentence. One thin required section is _thin_; multiple missing is _broken_. The fix is to expand the Project-Type section per the `required_sections` column in `assets/project-types.csv`.
+
+### 13. Downstream usability
+
+If this PRD feeds UX, architecture, or story creation, can those workflows source-extract from it cleanly? Traceability is the load-bearing part of this dimension and one of the unforgiving, downstream-critical ones.
+
+Look for:
+
+- A complete traceability chain: Vision (§1) → Success Criteria (§2) → User Journey (§4) → FR (§8), with a Traceability Matrix carrying a row per FR and no empty mapping cells. Orphan FRs — capabilities that map to no journey and no success criterion — are the headline failure.
+- Glossary present; every domain noun used identically across FRs, UJs, and Success Metric definitions.
+- FR / UJ / SM IDs contiguous, unique, and cross-references that resolve.
+- Each section makes sense pulled out alone — cross-references via Glossary terms, not "see above."
+- UJs each have a named protagonist; no floating UJs.
+
+A missing or mostly-empty Traceability Matrix, or more than a fifth of FRs with no upstream linkage, is _broken_. For standalone PRDs (no downstream consumers), this dimension matters less — say so and mark it accordingly.
+
+### 14. Dual-audience readiness
+
+Can the PRD be both skimmed by a busy stakeholder and precisely extracted by a downstream tool? This is the lightest of the rigor dimensions — informational rather than gating — but worth a note when it slips.
+
+What good looks like: each section opens with a one-to-two-sentence summary; cross-references use full IDs (`FR-AREA-NN`) rather than vague descriptors like "the auth feature above"; no forward references; lists live in real list blocks, not buried in prose.
+
+What broken looks like: sections with no summary opener, cross-references by vague description, or forward references that force linear reading. A couple of slips is _adequate_; pervasive vague cross-referencing is _thin_. The fix is to give each section a summary opener and rewrite cross-references with full FR IDs.
+
+### 15. Shape fit
+
+Has the PRD been forced into a shape that doesn't match the product? This dimension governs how hard to push the others — it tells you which dimensions are load-bearing for _this_ PRD.
+
+- Consumer product / multi-stakeholder B2B / meaningful UX → UJs with named protagonists are load-bearing.
+- Internal tool, single-operator role → capability spec shape; UJs may be overhead; SMs may be operational rather than user-facing.
+- Regulatory or compliance update → constraint traceability is non-negotiable; UJs may be irrelevant.
+- Hobby / solo → rigor light, substance bar still applies.
+- Brownfield → existing-code references must be accurate; new UJs and existing UJs must be distinguished.
+- Chain-top (feeds UX → architecture → stories) → downstream usability and traceability matter more; standalone PRDs can be lighter on those.
+
+Flag PRDs that are over-formalized (UJ density for a single-operator tool) or under-formalized (consumer product with no UJs).
+
+## Mechanical notes
+
+Cover these as a tail section, not a primary dimension. They matter for downstream but don't drive the verdict on whether the PRD is good.
+
+- Glossary drift (case, plural, synonyms across the PRD).
+- ID continuity (gaps, duplicates, unresolved cross-references).
+- Assumptions Index roundtrip (every inline `[ASSUMPTION]` indexed; index entries all appear inline).
+- UJ protagonist naming (each UJ has a named protagonist carrying context inline).
+- Required sections present for the agreed stakes and product type.
+- Frontmatter completeness (densityLevel / domainTier / projectType / version present; no residual `{{...}}` placeholders).