@geraldmaron/construct 1.2.1 → 1.2.3

package/skills/operating/orchestration-reference.md

@@ -17,7 +17,7 @@ Construct is the underlying orchestration system for the **current project**. Tr
 The two task-shaped surfaces are siblings, not duplicates:
 
 - **`.cx/workflow.json`**: single project-wide workflow file. Holds the cross-cutting task ledger and intent / category metadata. Drives `workflow_status` and `project_context` MCP tools.
-- **`.cx/task-graphs/<id>.json`**: per-incoming-signal plan generated by `construct graph from-intake <intake-id>`. One graph per triaged inbox file, one node per persona in the recommendedChain, evidence records gating `done`. See [Concepts → Intake and triage](/concepts/intake-and-triage).
+- **`.cx/task-graphs/<id>.json`**: per-incoming-signal plan generated by `construct graph from-intake <intake-id>`. One graph per triaged inbox file, one node per persona in the recommendedChain, evidence records gating `done`. See [Concepts → Intake and triage](/guides/concepts/intake-and-triage).
 
 A signal that becomes durable cross-session work crosses over: the graph nodes are executed, the resulting work is tracked in `.cx/workflow.json` and in beads. The intake queue and task graphs are how new signals enter the loop; the workflow ledger and beads are how durable work is carried.
 

package/skills/routing.md

@@ -126,11 +126,11 @@ Read the matching skill file before responding when the user's request matches t
 | product intelligence, customer notes, field notes, product signals, customer profile, evidence brief, signal brief, backlog proposal | `skills/docs/product-intelligence-workflow.md` | Product Intelligence workflow: evidence to product artifacts |
 | strategy, product strategy, strategic bet, non-bet, north star, time horizon, competitive positioning | `skills/docs/strategy-workflow.md` | Product strategy: read, update, and reason about the strategy store |
 | ingest evidence, ingest customer notes, ingest Slack thread, ingest support ticket, normalize field notes | `skills/docs/evidence-ingest-workflow.md` | Evidence ingest workflow: raw source to .cx/knowledge/ |
-| write a PRD, create requirements, spec out, requirements document, Meta PRD, platform PRD | `skills/docs/prd-workflow.md` | PRD workflow: requirements to docs/prd/ or docs/meta-prd/ |
+| write a PRD, create requirements, spec out, requirements document, Meta PRD, platform PRD | `skills/docs/prd-workflow.md` | PRD workflow: requirements to docs/specs/prd/ or docs/meta-prd/ |
 | write a PRFAQ, working backwards doc, press release FAQ | `skills/docs/prfaq-workflow.md` | PRFAQ workflow: launch narrative from PRD or evidence |
 | create Jira proposal, update Linear, backlog proposal, issue proposal | `skills/docs/backlog-proposal-workflow.md` | Backlog proposal workflow: approval-gated issue tracker changes |
-| record this decision, create an ADR, architecture decision | `skills/docs/adr-workflow.md` | ADR workflow: decision to docs/adr/ file |
-| write a runbook, document this operation, operational procedure | `skills/docs/runbook-workflow.md` | Runbook workflow: operation to docs/runbooks/ file |
+| record this decision, create an ADR, architecture decision | `skills/docs/adr-workflow.md` | ADR workflow: decision to docs/decisions/adr/ file |
+| write a runbook, document this operation, operational procedure | `skills/docs/runbook-workflow.md` | Runbook workflow: operation to docs/operations/runbooks/ file |
 | init project, new project setup, join project, set up doc structure | `skills/docs/init-project.md` | Project initialization via `construct init --docs-preset=*` |
 
 ## Routing Rules

package/specialists/prompts/cx-architect.md

@@ -61,7 +61,7 @@ DATA MODELS: schema with types, constraints, relationships, and migration plan
 DEPENDENCY GRAPH: modules and their directions; flag cycles
 TEST IMPACTS: what needs unit, integration, or E2E coverage
 
-Decision persistence: ask cx-docs-keeper to create or update `docs/adr/ADR-{NNN}-{slug}.md` and `.cx/decisions/{date}-{slug}.md`. If workspace writes aren't available, include the full DECISION rationale inline for docs-keeper to persist.
+Decision persistence: ask cx-docs-keeper to create or update `docs/decisions/adr/ADR-{NNN}-{slug}.md` and `.cx/decisions/{date}-{slug}.md`. If workspace writes aren't available, include the full DECISION rationale inline for docs-keeper to persist.
 
 When producing an implementation plan, use the canonical task format:
 `### T{N}: {title}` sections with **Owner**, **Phase**, **Files**, **Depends on**, **Read first**, **Do not change**, and **Acceptance criteria** fields. This keeps `plan.md` and tracker-linked task slices explicit and preserves the single-writer boundary for each file.

package/specialists/prompts/cx-docs-keeper.md

@@ -72,7 +72,7 @@ Memory write-back: after updating docs, call `create_entities` or `add_observati
 
 Maintenance: keep `.cx/context.md` under 100 lines. Summarize and archive older entries. Check for documentation drift before work is declared complete.
 
-Doc structure: skills at skills/docs/ define the workflow for each doc type. Product Intelligence working artifacts live under .cx/knowledge/. Research: .cx/research/{slug}.md. ADRs: docs/adr/ADR-{NNN}-{slug}.md. PRDs: docs/prd/{date}-{slug}.md. Meta PRDs: docs/meta-prd/{date}-{slug}.md. Runbooks: docs/runbooks/{service}-{operation}.md. Always use the matching template as the starting structure.
+Doc structure: skills at skills/docs/ define the workflow for each doc type. Product Intelligence working artifacts live under .cx/knowledge/. Research: .cx/research/{slug}.md. ADRs: docs/decisions/adr/ADR-{NNN}-{slug}.md. PRDs: docs/specs/prd/{date}-{slug}.md. Meta PRDs: docs/meta-prd/{date}-{slug}.md. Runbooks: docs/operations/runbooks/{service}-{operation}.md. Always use the matching template as the starting structure.
 
 ## Document Quality Loop (Evaluator-Optimizer)
 

package/specialists/prompts/cx-researcher.md

@@ -68,7 +68,7 @@ When querying search engines or paper indexes, always filter or sort by date: ne
 
 ### Step 4: Check internal evidence
 
-Before going external, search: `.cx/research/`, `.cx/knowledge/`, `docs/prd/`, `docs/meta-prd/`, ADRs, runbooks, and ingested artifacts. If a prior research brief exists for the topic, cite and extend it rather than redoing the search from scratch.
+Before going external, search: `.cx/research/`, `.cx/knowledge/`, `docs/specs/prd/`, `docs/meta-prd/`, ADRs, runbooks, and ingested artifacts. If a prior research brief exists for the topic, cite and extend it rather than redoing the search from scratch.
 
 ### Step 5: Verify every URL
 

package/specialists/prompts/cx-sre.md

@@ -100,7 +100,7 @@ Every alert MUST include:
 Alert: service_error_rate
 Trigger: error_rate > 1% for 5m
 Severity: critical
-Runbook: docs/runbooks/service-error-rate.md
+Runbook: docs/operations/runbooks/service-error-rate.md
 Immediate Action: Check error logs, verify dependencies
 Escalation: On-call SRE → Service owner → Incident commander
 Rollback: If deployment-related, revert to last known good

package/specialists/role-manifests.json

@@ -6,7 +6,7 @@
       "events": ["push_gate.fail", "service.down", "mcp.unhealthy.persistent", "edit_loop.stuck"],
       "severityImmediate": ["service.down"],
       "fence": {
-        "allowedPaths": ["docs/runbooks/**", "docs/incidents/**", "docs/postmortems/**"],
+        "allowedPaths": ["docs/operations/runbooks/**", "docs/runbooks/**", "docs/operations/incidents/**", "docs/incidents/**", "docs/postmortems/**"],
         "allowedBdLabels": ["incident", "sre", "reliability"],
         "allowedCommands": ["bd create", "bd note", "bd update", "bd link", "bd label"],
         "approvalRequired": ["commit", "push", "edit:lib/**", "edit:bin/**", "edit:specialists/**"]
@@ -86,7 +86,7 @@
       "events": ["handoff.received", "adr.requested", "arch.boundary.violated"],
       "severityImmediate": [],
       "fence": {
-        "allowedPaths": ["docs/adr/**", "docs/rfc/**", "docs/concepts/architecture.md", "docs/system-design/**"],
+        "allowedPaths": ["docs/decisions/adr/**", "docs/adr/**", "docs/decisions/rfc/**", "docs/rfc/**", "docs/guides/concepts/architecture.md", "docs/concepts/architecture.md", "docs/system-design/**"],
         "allowedBdLabels": ["architecture", "adr", "rfc", "design"],
         "allowedCommands": ["bd create", "bd note", "bd update", "bd label"],
         "approvalRequired": ["commit", "push", "edit:lib/**", "edit:bin/**", "edit:specialists/**"]
@@ -112,7 +112,7 @@
       "events": ["handoff.received", "release.candidate", "version.bump.needed"],
       "severityImmediate": [],
       "fence": {
-        "allowedPaths": ["docs/releases/**", "CHANGELOG.md"],
+        "allowedPaths": ["docs/operations/releases/**", "docs/releases/**", "CHANGELOG.md"],
         "allowedBdLabels": ["release", "version", "shipping"],
         "allowedCommands": ["bd create", "bd note", "bd update", "bd label"],
         "approvalRequired": ["commit", "push", "edit:package.json", "edit:lib/**", "edit:bin/**"]
@@ -125,7 +125,7 @@
       "events": ["handoff.received", "backlog.stale", "prd.requested"],
       "severityImmediate": [],
       "fence": {
-        "allowedPaths": ["docs/prd/**", "docs/meta-prd/**", "docs/prfaq/**", "docs/one-pager/**", ".cx/knowledge/**"],
+        "allowedPaths": ["docs/specs/prd/**", "docs/prd/**", "docs/meta-prd/**", "docs/prfaq/**", "docs/one-pager/**", ".cx/knowledge/**"],
         "allowedBdLabels": ["product", "prd", "backlog", "feature"],
         "allowedCommands": ["bd create", "bd note", "bd update", "bd label", "bd priority"],
         "approvalRequired": ["commit", "push", "edit:lib/**", "edit:bin/**"]
@@ -197,7 +197,7 @@
       "events": ["handoff.received", "research.requested", "evidence.requested"],
       "severityImmediate": [],
       "fence": {
-        "allowedPaths": ["docs/research/**", ".cx/research/**", "docs/evidence-briefs/**", "docs/signal-briefs/**"],
+        "allowedPaths": ["docs/notes/research/**", "docs/research/**", ".cx/research/**", "docs/evidence-briefs/**", "docs/signal-briefs/**"],
         "allowedBdLabels": ["research", "evidence", "investigation"],
         "allowedCommands": ["bd create", "bd note", "bd update", "bd label"],
         "approvalRequired": ["commit", "push", "edit:lib/**", "edit:bin/**"]
@@ -210,7 +210,7 @@
     "explorer": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/explorations/**", ".cx/explorations/**"], "allowedBdLabels": ["exploration", "spike"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["exploration"], "docTypes": ["memo"] }, "handoffCandidates": ["engineer", "architect", "researcher"], "killSwitchEnv": "CONSTRUCT_ROLE_EXPLORER" },
     "operations": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/ops/**", "docs/operations/**"], "allowedBdLabels": ["ops", "operations"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["ops"], "docTypes": ["memo", "runbook"] }, "handoffCandidates": ["sre", "platform-engineer", "release-manager"], "killSwitchEnv": "CONSTRUCT_ROLE_OPERATIONS" },
     "orchestrator": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/**", "plan.md", ".cx/context.md"], "allowedBdLabels": ["orchestration", "workflow", "dispatch"], "allowedCommands": ["bd create", "bd note", "bd update", "bd label", "bd link"], "approvalRequired": ["commit", "push", "edit:lib/**", "edit:bin/**", "edit:specialists/**"] }, "outputs": { "bdLabels": ["orchestration", "dispatch"], "docTypes": ["memo"] }, "handoffCandidates": ["product-manager", "architect", "engineer", "security", "qa", "sre"], "killSwitchEnv": "CONSTRUCT_ROLE_ORCHESTRATOR" },
-    "rd-lead": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/research/**", "docs/experiments/**", ".cx/experiments/**"], "allowedBdLabels": ["rd", "research", "experiment"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["rd"], "docTypes": ["memo", "research-brief"] }, "handoffCandidates": ["researcher", "architect", "ai-engineer"], "killSwitchEnv": "CONSTRUCT_ROLE_RD_LEAD" },
+    "rd-lead": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/notes/research/**", "docs/research/**", "docs/experiments/**", ".cx/experiments/**"], "allowedBdLabels": ["rd", "research", "experiment"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["rd"], "docTypes": ["memo", "research-brief"] }, "handoffCandidates": ["researcher", "architect", "ai-engineer"], "killSwitchEnv": "CONSTRUCT_ROLE_RD_LEAD" },
     "legal-compliance": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/legal/**", "docs/compliance/**", "docs/security/**", ".cx/knowledge/**"], "allowedBdLabels": ["legal", "compliance", "privacy"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["legal", "compliance"], "docTypes": ["memo"] }, "handoffCandidates": ["security", "product-manager"], "killSwitchEnv": "CONSTRUCT_ROLE_LEGAL_COMPLIANCE" },
     "devil-advocate": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/critiques/**"], "allowedBdLabels": ["critique", "devil-advocate"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["critique"], "docTypes": ["memo"] }, "handoffCandidates": ["architect", "product-manager", "engineer"], "killSwitchEnv": "CONSTRUCT_ROLE_DEVIL_ADVOCATE" }
   }

package/templates/docs/README.md

@@ -0,0 +1,125 @@
+# Doc Templates & Role Anti-Patterns
+
+See `../prompt-surfaces.md` for the canonical public-vs-internal prompt surface model. This document covers only templates and internal role overlays.
+
+Construct specialists produce standard documents (PRDs, ADRs, runbooks, memos, etc.) from shared templates, and they self-check against shared role anti-patterns. Both can be overridden per-project.
+
+## Templates
+
+Shipped templates live in [`templates/docs/`](../../templates/docs/):
+
+| Layer | Path | Purpose |
+|---|---|---|
+| Specialist source | `templates/docs/{name}.md` | Canonical shape for `get_template()` MCP |
+| Init lane starters | `docs/{lane}/templates/` | Copied into downstream projects by `construct init --docs-preset=*` |
+| Project override | `.cx/templates/docs/{name}.md` | Per-project template override at fetch time |
+
+Do not duplicate starters at `docs/{lane}/_template.md` — lane READMEs link only to `./templates/`.
+
+| Template | Produced by | Purpose |
+|---|---|---|
+| `prd.md` | cx-product-manager | Product requirements doc |
+| `meta-prd.md` | cx-product-manager, cx-docs-keeper | Requirements for product operating systems, agent workflows, document standards, and evaluation loops |
+| `prfaq.md` | cx-product-manager, cx-business-strategist | Working-backwards press release and FAQ |
+| `evidence-brief.md` | cx-product-manager, cx-ux-researcher, cx-researcher | Product evidence synthesis before decisions |
+| `signal-brief.md` | cx-product-manager, cx-researcher | Weak or emerging product signal preservation |
+| `customer-profile.md` | cx-product-manager, cx-docs-keeper | Durable customer/account product memory |
+| `product-intelligence-report.md` | cx-product-manager, cx-business-strategist | Cross-source product intelligence synthesis |
+| `backlog-proposal.md` | cx-product-manager | Approval-gated external tracker proposal |
+| `memo.md` | cx-business-strategist | Strategy memo (~1 page) |
+| `one-pager.md` | cx-product-manager, cx-business-strategist | Executive one-pager |
+| `adr.md` | cx-architect, cx-rd-lead | Architecture decision record |
+| `research-brief.md` | cx-researcher, cx-ux-researcher, cx-explorer | Research findings |
+| `runbook.md` | cx-sre, cx-operations | Operational runbook |
+| `incident-report.md` | cx-sre, cx-operations, cx-release-manager | Post-mortem |
+
+### How specialists use them
+
+Each specialist prompt points to the template via an MCP call:
+
+```markdown
+**Template**: call `get_template("prd")` when drafting a product PRD, or `get_template("meta-prd")` when drafting a Meta PRD, ...
+```
+
+The `get_template(name)` MCP tool (see [`lib/mcp/server.mjs`](../../lib/mcp/server.mjs)) resolves:
+
+1. `.cx/templates/docs/{name}.md`: **project override** (preferred if present)
+2. `templates/docs/{name}.md`: **shipped default** (fallback)
+
+Use `list_templates` to see both shipped and overridden names.
+
+### Overriding a template
+
+Drop a file at `.cx/templates/docs/{name}.md` inside your project. That's it: next time a specialist drafts that doc type, they'll pick up your version. No sync, no restart.
+
+Example: reshape the PRD to lead with success metrics:
+
+```bash
+mkdir -p .cx/templates/docs
+cp templates/docs/prd.md .cx/templates/docs/prd.md
+# edit .cx/templates/docs/prd.md to your shape
+```
+
+Ask Construct for a PRD; it'll follow the new shape.
+
+## Role Anti-Patterns
+
+Each specialist is cognitively rooted in a **role** (product-manager, engineer, architect, etc.) with a core set of failure modes to avoid. Flavored specialists extend the core with an overlay.
+
+Core roles live in [`skills/roles/`](../../skills/roles/):
+
+| Core role | Flavors | Applied to |
+|---|---|---|
+| `engineer` | `engineer.ai`, `engineer.data`, `engineer.platform` | cx-engineer, cx-ai-engineer, cx-data-engineer, cx-platform-engineer |
+| `reviewer` | `reviewer.devil-advocate`, `reviewer.evaluator`, `reviewer.trace` | cx-reviewer, cx-devil-advocate, cx-evaluator, cx-trace-reviewer |
+| `researcher` | `researcher.ux`, `researcher.explorer` | cx-researcher, cx-ux-researcher, cx-explorer |
+| `operator` | `operator.sre`, `operator.release`, `operator.docs` | cx-sre, cx-release-manager, cx-operations, cx-docs-keeper |
+| `product-manager` | `product-manager.product`, `product-manager.platform`, `product-manager.enterprise`, `product-manager.ai-product`, `product-manager.growth`, `product-manager.business-strategy` | cx-product-manager, cx-business-strategist |
+| `designer` | `designer.accessibility` | cx-designer, cx-accessibility |
+| `security` | `security.legal-compliance` | cx-security, cx-legal-compliance |
+| `qa` | `qa.test-automation` | cx-qa, cx-test-automation |
+| `architect` |: | cx-architect, cx-rd-lead |
+| `debugger` |: | cx-debugger |
+| `data-analyst` |: | cx-data-analyst |
+| `orchestrator` |: | cx-orchestrator |
+
+### How they're loaded
+
+Unlike templates, role anti-patterns are **inlined at sync time** (not fetched at runtime). The specialist source prompt carries a marker:
+
+```markdown
+**Anti-patterns**: call `get_skill("roles/engineer.ai")` before drafting.
+```
+
+`construct sync` (via [`lib/role-preload.mjs`](../../lib/role-preload.mjs)) replaces that line with the full core role body + flavor overlay under `## Role anti-patterns`. The content is always present in the final platform prompt: no runtime dependency, no chance for the model to skip the pre-work.
+
+### Editing or adding roles
+
+- **Edit a role**: change the file under `skills/roles/`, then run `construct sync` to propagate to all platforms.
+- **Add a flavor**: create `skills/roles/{core}.{flavor}.md` with YAML frontmatter:
+  ```yaml
+  ---
+  role: {core}.{flavor}
+  applies_to: [cx-...]
+  inherits: {core}
+  version: 1
+  ---
+  ```
+  Update the corresponding `cx-*.md` source prompt to reference the new flavor name, then `construct sync`.
+- **No project-level override for roles** today: roles are platform-wide and curated. If you need per-project role overrides, open a request.
+
+## Verification
+
+After editing either surface, run:
+
+```bash
+npm test                 # tests/agent-prompts.test.mjs covers both
+node scripts/sync-agents.mjs   # regenerate platform adapters
+construct doctor         # health check
+```
+
+Spot-check propagation:
+
+```bash
+grep -l "## Role anti-patterns" ~/.claude/agents/cx-*.md
+```

package/templates/docs/construct_guide.md

@@ -33,11 +33,10 @@ Generated tooling (`.construct/`, `.claude/`, `.cx/`, `plan.md`) is gitignored;
 
 ## Where to drop information you want Construct to use
 
-Three intake paths, ordered by formality:
+Two intake paths, ordered by formality:
 
-1. **`.cx/inbox/`** — drop a file here (URL, screenshot, paste, anything). The embed daemon watches the directory; when a file lands, it ingests it into the local knowledge base within a second or two and writes a triage packet to `.cx/intake/pending/` describing the new content, its classification (intake type, stage, owner persona, recommended chain), its suggested docs lane, and existing docs that overlap. The agent surfaces pending items at the next session start and you can ask it to process them.
-2. **`docs/intake/`** — for proper intake batches (research notes, evidence from a meeting, raw source material). Has a template. Survives in git history.
-3. **`AGENTS.md`**: for rules and conventions you want the agent to follow every time. "We prefer functional components. Don't introduce new dependencies without flagging." Read at session start.
+1. **`inbox/`** — the single canonical drop zone. Drop a file here (URL, screenshot, paste, anything). The embed daemon watches the directory; when a file lands, it ingests it into the local knowledge base within a second or two and writes a triage packet to `.cx/intake/pending/` describing the new content, its classification (intake type, stage, owner persona, recommended chain), its suggested docs lane, and existing docs that overlap. The agent surfaces pending items at the next session start and you can ask it to process them. For large or slowly-written files, stage under `inbox/.staging/` and rename in so the watcher never sees a half-written file.
+2. **`AGENTS.md`**: for rules and conventions you want the agent to follow every time. "We prefer functional components. Don't introduce new dependencies without flagging." Read at session start.
 
 For URLs or quick notes, the easiest path is to drop a file into `~/Downloads` and run:
 

package/templates/docs/persona-artifact.md

@@ -1,6 +1,6 @@
 # <Role display name>
 
-> Anchor doc for the <role-id> persona. Methodology: `docs/concepts/persona-research.md`. This file is generated by `construct profile create` and is part of the discover + frame phases. The persona is not promotable until every section below is filled from evidence, not opinion.
+> Anchor doc for the <role-id> persona. Methodology: `docs/guides/concepts/persona-research.md`. This file is generated by `construct profile create` and is part of the discover + frame phases. The persona is not promotable until every section below is filled from evidence, not opinion.
 
 ## Goals
 

package/templates/docs/prds/README.md

@@ -0,0 +1,25 @@
+---
+cx_doc_id: 019ddb68-5aeb-7c30-9c7e-0d994ab6c06b
+created_at: "2026-04-29T22:42:22.571Z"
+updated_at: "2026-04-29T22:42:22.572Z"
+generator: construct/init-docs
+body_hash: "sha256:64607fda2fa55def5dd8af0e31f88cf190f68841da0223b45f0d36db83221669"
+---
+<!--
+templates/docs/prds/README.md: lane guide for PRDs.
+
+Generated from the Construct documentation lane templates. Keep this lane focused on one document
+family. If it no longer has a distinct purpose, prune it or merge it elsewhere.
+-->
+
+# PRDs
+
+Product and capability requirement documents.
+
+## Starter templates
+
+- [_template.md](./templates/_template.md)
+- [meta-prd.template.md](./templates/meta-prd.template.md)
+- [prd-business.template.md](./templates/prd-business.template.md)
+- [prd-platform.template.md](./templates/prd-platform.template.md)
+- [prfaq.template.md](./templates/prfaq.template.md)

package/templates/docs/prds/templates/_template.md

@@ -0,0 +1,206 @@
+# PRD: {title}
+
+- **Date**: {YYYY-MM-DD}
+- **Owner**: {name}
+- **Status**: draft | in-review | approved | shipped | deprecated
+
+<!--
+Use this for a product capability, user workflow, or customer-facing requirement set.
+Use meta-prd.md instead when defining the requirements for a product system, agent,
+process, template, evaluation loop, or operating model.
+
+Before drafting, read rules/common/framing.md.
+
+Owning specialist: cx-product-manager (see rules/common/doc-ownership.md).
+Construct must route PRD authoring to cx-product-manager rather than drafting directly.
+doing so is how requirements traceability, user grounding, and external research fire.
+
+Write with a balance of short paragraphs, tables, and bullets. Bullets are for scans,
+not the whole document. Keep em dashes rare; prefer commas, periods, or parentheses.
+-->
+
+## Summary
+<!--
+One paragraph (3-5 sentences) that a busy reader can use as the whole PRD.
+What the change is, who it's for, why now, and what changes when it ships.
+No solutions in this section that aren't decided. No ticket IDs. No team names.
+-->
+
+## Background
+<!--
+Context the reader needs to evaluate this PRD without asking around.
+Include relevant prior work (linked PRDs, ADRs, RFCs), observed signals, and
+the current state of the user experience or system. State what is already
+true today so the reader can compare against the proposed change.
+
+Cite evidence: support tickets, interviews, telemetry, sales calls, research.
+Avoid roadmap-speak ("this is a Q3 priority"); state what is happening to users.
+-->
+
+## Problem
+<!--
+The specific user or business outcome that is currently blocked. One or two
+paragraphs. State the pain, not the solution.
+
+Must NOT reference:
+- Jira / Linear ticket IDs or "this came from ticket X"
+- Roadmap items, OKR line items, or quarterly goals
+- "The team decided we should build this"
+
+Must reference:
+- Observed user behavior, quantitative signals, or qualitative evidence
+- The specific outcome that is not currently achievable
+- The constraint that makes this non-trivial today
+-->
+
+## Goals
+<!--
+What success looks like, in outcome terms. Three to five goals max. Each
+goal is the *change* you want, not the activity. Order by importance.
+
+Examples:
+- Reduce p95 onboarding time from 12m to under 4m for new accounts.
+- Eliminate the manual reconciliation step our top 20 customers do every Monday.
+- Halve the support volume for "where is my data" questions.
+-->
+
+## Outcome
+<!--
+What is concretely different for users, the business, or the system once this
+ships and is adopted. This is the observable end state: written from the
+user's perspective when possible. The acceptance criteria below should be the
+falsifiable evidence that this outcome was achieved.
+
+A reader should be able to compare the current state (Background) to this
+section and see the delta in plain language.
+-->
+
+## User flow
+
+```mermaid
+flowchart TD
+  A[User starts] --> B{Current friction?}
+  B -->|Yes| C[Proposed path]
+  B -->|No| D[Existing path]
+  C --> E[Success outcome]
+  D --> E
+```
+
+## In scope and out of scope
+
+| | Description |
+|---|---|
+| **In scope** | <what this PRD covers and commits to ship> |
+| **Out of scope** | <related work explicitly deferred: name the reason> |
+| **Adjacent (deferred)** | <work that's a natural follow-up but not in this PRD> |
+
+<!--
+Be specific. "Authentication" is too vague; "OAuth login for the web dashboard,
+not for the CLI" is right. The Out of scope list is a tool for protecting
+schedule and reviewer attention: use it.
+-->
+
+## Phases
+
+<!--
+Phases are how this work ships, not how it's organized internally. Each phase
+is independently shippable and provides observable user value (or a clearly
+defined platform capability). Avoid "phase 1: backend, phase 2: frontend".
+that's a task list, not a phasing.
+
+Each phase below holds its own goal, status, functional requirements (FR),
+and non-functional requirements (NFR), with acceptance criteria written
+inline next to each requirement. Use `FR-<phase>.<n>` and `NFR-<phase>.<n>`
+so requirements can be referenced from reviews and tests.
+
+Status values: not started | in progress | shipped | deferred.
+
+NFR categories to consider: performance, reliability, security, privacy,
+accessibility, observability, compliance, cost. Numeric targets where possible.
+-->
+
+### Phase 1: <name>
+
+- **Goal**: <what this phase delivers>
+- **Status**: not started
+
+**Functional**
+
+- **FR-1.1**: <imperative statement of what the system must do>
+  - *Acceptance*: <observable, falsifiable condition a reviewer can check without asking the author>
+- **FR-1.2**: <...>
+  - *Acceptance*: <...>
+
+**Non-functional**
+
+- **NFR-1.1**: <category>: <target with number>
+  - *Acceptance*: <how this is measured and what counts as pass>
+
+### Phase 2: <name>
+
+- **Goal**: <what this phase delivers>
+- **Status**: not started
+
+**Functional**
+
+- **FR-2.1**: <...>
+  - *Acceptance*: <...>
+- **FR-2.2**: <...>
+  - *Acceptance*: <...>
+
+**Non-functional**
+
+- **NFR-2.1**: <category>: <target>
+  - *Acceptance*: <...>
+
+### Phase 3: <name>
+
+- **Goal**: <what this phase delivers>
+- **Status**: not started
+
+**Functional**
+
+- **FR-3.1**: <...>
+  - *Acceptance*: <...>
+
+**Non-functional**
+
+- **NFR-3.1**: <category>: <target>
+  - *Acceptance*: <...>
+
+## Success metrics
+<!--
+How we will know this worked in production over time, beyond the per-requirement
+acceptance criteria. Leading vs. lagging. Avoid vanity metrics.
+-->
+
+| Metric | Baseline | Target |
+|---|---|---|
+| {name} | {current} | {goal} |
+
+## Constraints
+<!--
+Budget, timeline, platform, team, legal, technical debt: anything that shapes
+the solution and isn't a requirement.
+-->
+
+## Dependencies
+<!--
+Teams, services, contracts, data sources, vendor timelines. Each dependency
+should name an owner and the date it must be ready by.
+-->
+
+## Risks and mitigations
+
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| <risk> | low / med / high | low / med / high | <how this is reduced or what we accept> |
+
+## Open questions
+
+| Question | Owner | Decision needed by |
+|---|---|---|
+| <unknown> | <name> | <YYYY-MM-DD> |
+
+## References
+<!-- Linked research, prior PRDs, ADRs, tickets, designs. -->