@geraldmaron/construct 1.1.1 → 1.2.0

package/skills/docs/user-research-workflow.md

@@ -0,0 +1,40 @@
+---
+name: docs-user-research-workflow
+description: "Use when: cx-ux-researcher synthesizes user evidence — interviews, support tickets, session replay, surveys, or field notes."
+inputs: [user-research, interview-data]
+artifactType: evidence-brief
+toneDefault: pedagogical
+toneAllowed: [pedagogical, direct, friendly]
+verificationBar: "Observed behavior weighted over self-report; sample size stated; no invented quotes."
+---
+# User Research Workflow
+
+Use when: cx-ux-researcher gathers or synthesizes **user** evidence. Do not use for CVE lookups, API version facts, or repo structure — use `docs/research-workflow` (cx-researcher) or `docs/codebase-research-workflow` (cx-explorer) instead.
+
+Follow [rules/common/research.md](../../rules/common/research.md) and call `get_skill("roles/researcher.ux")` before drafting.
+
+## Steps
+
+1. **Clarify the user question**: who specifically, what behavior or friction, falsifiable claim.
+2. **Check internal user evidence**: `.cx/knowledge/external/`, customer profiles, evidence briefs, support exports, ingested transcripts.
+3. **Choose source classes** (user-primary):
+
+   | Source | Class | Notes |
+   |---|---|---|
+   | Interview transcript | primary | Direct quotes with participant id, not name |
+   | Support ticket / chat | primary | Link ticket id; preserve ambiguity |
+   | Session replay / analytics | primary | State segment and timeframe |
+   | Survey (structured) | secondary | Note response rate and bias |
+   | Sales / CS summary | secondary | Trace to underlying tickets when possible |
+
+4. **Sampling**: state segment, N, recruitment method. Behavioral claims need ≥5 per segment unless exploratory (flag as low confidence).
+5. **Validity**: name the weakest validity threat (internal/external/construct/conclusion) per `roles/researcher.ux` — that threat is where the finding is most likely wrong.
+6. **Inter-rater reliability**: when themes are coded from qualitative data, two coders code a sample independently; report agreement (or Cohen's κ when N permits). Persistent disagreement means the codebook is unfinished — fix the codebook before shipping themes.
+7. **Tone**: default `pedagogical`; override via `.cx/brand-voice.json` if present.
+8. **Output**: `get_template("evidence-brief")` or `signal-brief` when threshold not met; store under `.cx/knowledge/internal/evidence-briefs/`.
+
+## Verification bar
+
+- No invented customer names, quotes, or ticket ids.
+- Findings describe problems, not prescribed UI solutions.
+- cx-ux-researcher must **not** cite blog posts for API version or security claims.

package/skills/operating/orchestration-reference.md

@@ -52,7 +52,7 @@ Do not duplicate skill internals inside agent prompts. Reference the relevant sk
 Every producer→consumer pair has an explicit contract in `specialists/contracts.json`, loaded via `lib/specialist-contracts.mjs`. Specialists call the MCP tool `agent_contract` at the start of a handoff to see:
 
 - `input.mustContain`: fields the packet must carry
-- `input.schema`: JSON schema (when applicable) from `lib/schemas/`
+- `input.schema`: JSON schema (when applicable) from `lib/contract-schemas/`
 - `preconditions`: what must be true before work starts
 - `output.schema` / `output.shape`: expected return shape
 - `postconditions`: what must be true before marking DONE

package/skills/roles/architect.md

@@ -58,6 +58,10 @@ Load this before drafting. These are the failure modes that separate strong role
 **Why it fails**: the team now owns the maintenance of both the product and a worse version of an existing tool.
 **Counter-move**: survey existing tools honestly. If building, articulate exactly what the existing tools fail to do.
 
+## Methodology
+
+**Experimental design (cx-rd-lead).** Before committing build capacity to an R&D bet, state the falsifiable hypothesis, the minimum detectable effect size that would change the decision, and the power analysis: given expected variance and α, what N (users, runs, or samples) is required to detect that effect? An under-powered study that returns "no difference" is inconclusive, not negative evidence — name the required N and whether the planned study meets it. Report effect sizes with confidence intervals, not only p-values or pass/fail.
+
 ## Self-check before shipping
 
 - [ ] Requirements are stated before tech choices
@@ -68,3 +72,4 @@ Load this before drafting. These are the failure modes that separate strong role
 - [ ] Scaling assumptions are named and tied to the business plan
 - [ ] Migration path is explicit with phases and rollback points
 - [ ] Build-vs-buy is justified when building
+- [ ] R&D bets state minimum detectable effect size and required N (power analysis)

package/skills/roles/operator.docs.md

@@ -37,6 +37,10 @@ Additional failure modes on top of the operator core.
 **Why it fails**: rot is guaranteed; questions route to Slack instead of the doc.
 **Counter-move**: every doc declares an owner (person or role). Ownership appears in the header.
 
+## Methodology
+
+**Per-doc-type tone from the manifest.** Before editing a typed artifact, resolve tone from `specialists/artifact-manifest.json` (`toneDefault`, `toneAllowed`) and the profile definitions in `specialists/tone-profiles.json`. Projects override per type via `.cx/brand-voice.json`. `construct artifact validate <path> --type=<type>` reports the resolved tone — match it unless the user explicitly requests a different allowed profile.
+
 ## Self-check before shipping
 - [ ] Last-reviewed date present and fresh
 - [ ] One canonical source per concept; duplicates redirect

package/skills/routing.md

@@ -120,7 +120,9 @@ Read the matching skill file before responding when the user's request matches t
 | Trigger Keywords | Skill File | Description |
 |---|---|---|
 | init docs, create docs structure, set up documentation, docs scaffold, documentation init | `skills/docs/init-docs.md` | Initialize required project-state docs and documentation structure |
-| research X, investigate X, find evidence, gather evidence | `skills/docs/research-workflow.md` | Research workflow: question to .cx/research/ file |
+| research X, investigate X, find evidence, gather evidence, CVE, vendor docs, market data | `skills/docs/research-workflow.md` | External research workflow (cx-researcher) |
+| user research, interview synthesis, support tickets, UX evidence, field notes | `skills/docs/user-research-workflow.md` | User research workflow (cx-ux-researcher) |
+| map codebase, explore repo structure, dependency graph, hot path | `skills/docs/codebase-research-workflow.md` | Codebase research workflow (cx-explorer) |
 | 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/ |
@@ -129,7 +131,7 @@ Read the matching skill file before responding when the user's request matches t
 | 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 |
-| init project, new project setup, join project, set up doc structure | `skills/docs/init-project.md` | Project initialization via construct init-docs |
+| 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/artifact-manifest.json

@@ -0,0 +1,480 @@
+{
+  "$schema": "./artifact-manifest.schema.json",
+  "version": 1,
+  "description": "Single source of truth for document types: template, owners, workflow skill, tone, structure, visuals, and release gates.",
+  "artifacts": {
+    "prd": {
+      "template": "templates/docs/prd.md",
+      "primaryOwners": ["cx-product-manager"],
+      "workflowSkill": "docs/prd-workflow",
+      "toneDefault": "decision-forcing-direct",
+      "toneAllowed": ["decision-forcing-direct", "executive-concise"],
+      "structureRequirements": ["Problem", "Goals", "Success metrics", "Risks and mitigations"],
+      "visualRequirements": [
+        { "id": "prd-user-flow", "check": "artifact-has-mermaid", "diagram": "flowchart" },
+        { "id": "prd-metrics-table", "check": "artifact-table-has-columns", "columns": ["Metric", "Baseline", "Target"] }
+      ],
+      "researchProfile": "user",
+      "releaseGate": {
+        "structuralLint": true,
+        "citationLint": true,
+        "proseMinimum": 3,
+        "requiredReviewers": ["cx-devil-advocate"],
+        "optionalReviewers": ["cx-ux-researcher"]
+      }
+    },
+    "prd-platform": {
+      "template": "templates/docs/prd-platform.md",
+      "primaryOwners": ["cx-product-manager"],
+      "workflowSkill": "docs/prd-workflow",
+      "toneDefault": "decision-forcing-direct",
+      "toneAllowed": ["decision-forcing-direct", "executive-concise"],
+      "structureRequirements": ["Problem", "Goals and non-goals", "Success metrics", "Risks and mitigations"],
+      "visualRequirements": [
+        { "id": "prd-platform-flow", "check": "artifact-has-mermaid", "diagram": "flowchart" },
+        { "id": "prd-platform-metrics", "check": "artifact-table-has-columns", "columns": ["Metric", "Baseline", "Target"] }
+      ],
+      "researchProfile": "external",
+      "releaseGate": {
+        "structuralLint": true,
+        "citationLint": true,
+        "proseMinimum": 3,
+        "requiredReviewers": ["cx-devil-advocate", "cx-architect"],
+        "optionalReviewers": []
+      }
+    },
+    "prd-business": {
+      "template": "templates/docs/prd-business.md",
+      "primaryOwners": ["cx-product-manager", "cx-business-strategist"],
+      "workflowSkill": "docs/prd-workflow",
+      "toneDefault": "executive-concise",
+      "toneAllowed": ["executive-concise", "decision-forcing-direct"],
+      "structureRequirements": ["The bet", "Market thesis", "Problem and opportunity", "Strategic goals", "Alternatives rejected"],
+      "researchProfile": "market",
+      "releaseGate": {
+        "structuralLint": true,
+        "citationLint": true,
+        "proseMinimum": 3,
+        "requiredReviewers": ["cx-devil-advocate"],
+        "optionalReviewers": ["cx-business-strategist"]
+      }
+    },
+    "meta-prd": {
+      "template": "templates/docs/meta-prd.md",
+      "primaryOwners": ["cx-product-manager", "cx-docs-keeper"],
+      "workflowSkill": "docs/prd-workflow",
+      "toneDefault": "decision-forcing-direct",
+      "toneAllowed": ["decision-forcing-direct"],
+      "structureRequirements": ["Problem", "Goals", "Principles", "Failure modes and mitigations", "Rollout"],
+      "researchProfile": "external",
+      "releaseGate": {
+        "structuralLint": true,
+        "citationLint": true,
+        "proseMinimum": 3,
+        "requiredReviewers": ["cx-devil-advocate", "cx-reviewer"],
+        "optionalReviewers": []
+      }
+    },
+    "adr": {
+      "template": "templates/docs/adr.md",
+      "primaryOwners": ["cx-architect", "cx-rd-lead"],
+      "workflowSkill": "docs/adr-workflow",
+      "toneDefault": "decision-forcing-direct",
+      "toneAllowed": ["decision-forcing-direct"],
+      "structureRequirements": ["Problem", "Decision", "Rejected alternatives", "Consequences", "Reversibility"],
+      "visualRequirements": [
+        { "id": "adr-context-diagram", "check": "artifact-has-mermaid", "diagram": "flowchart" }
+      ],
+      "researchProfile": "external",
+      "releaseGate": {
+        "structuralLint": true,
+        "citationLint": true,
+        "proseMinimum": 2,
+        "requiredReviewers": ["cx-devil-advocate", "cx-reviewer"],
+        "optionalReviewers": ["cx-architect"]
+      }
+    },
+    "rfc": {
+      "template": "templates/docs/rfc.md",
+      "primaryOwners": ["cx-architect"],
+      "workflowSkill": "docs/prd-workflow",
+      "toneDefault": "decision-forcing-direct",
+      "toneAllowed": ["decision-forcing-direct"],
+      "structureRequirements": ["Summary", "Motivation", "Proposed design", "Risks", "Verification"],
+      "visualRequirements": [
+        { "id": "rfc-sequence-diagram", "check": "artifact-has-mermaid", "diagram": "sequenceDiagram" }
+      ],
+      "researchProfile": "external",
+      "releaseGate": {
+        "structuralLint": true,
+        "citationLint": true,
+        "proseMinimum": 3,
+        "requiredReviewers": ["cx-devil-advocate", "cx-reviewer"],
+        "optionalReviewers": []
+      }
+    },
+    "rfc-platform": {
+      "template": "templates/docs/rfc-platform.md",
+      "primaryOwners": ["cx-architect"],
+      "workflowSkill": "docs/prd-workflow",
+      "toneDefault": "decision-forcing-direct",
+      "toneAllowed": ["decision-forcing-direct"],
+      "structureRequirements": ["Summary", "Motivation", "Proposed contract", "Risks", "Verification"],
+      "visualRequirements": [
+        { "id": "rfc-platform-sequence", "check": "artifact-has-mermaid", "diagram": "sequenceDiagram" }
+      ],
+      "researchProfile": "external",
+      "releaseGate": {
+        "structuralLint": true,
+        "citationLint": true,
+        "proseMinimum": 3,
+        "requiredReviewers": ["cx-devil-advocate", "cx-reviewer"],
+        "optionalReviewers": []
+      }
+    },
+    "research-brief": {
+      "template": "templates/docs/research-brief.md",
+      "primaryOwners": ["cx-researcher", "cx-ux-researcher", "cx-explorer"],
+      "workflowSkill": "docs/research-workflow",
+      "toneDefault": "direct",
+      "toneAllowed": ["direct", "pedagogical"],
+      "structureRequirements": ["Sources", "Findings", "Confidence summary", "Recommendation"],
+      "researchProfile": "external",
+      "releaseGate": {
+        "structuralLint": true,
+        "citationLint": true,
+        "proseMinimum": 2,
+        "requiredReviewers": [],
+        "optionalReviewers": ["cx-reviewer"]
+      }
+    },
+    "evidence-brief": {
+      "template": "templates/docs/evidence-brief.md",
+      "primaryOwners": ["cx-product-manager", "cx-researcher", "cx-ux-researcher"],
+      "workflowSkill": "docs/evidence-ingest-workflow",
+      "toneDefault": "direct",
+      "toneAllowed": ["direct", "executive-concise"],
+      "structureRequirements": ["Sources", "What we observed", "Confidence", "Recommendation"],
+      "researchProfile": "user",
+      "releaseGate": {
+        "structuralLint": true,
+        "citationLint": true,
+        "proseMinimum": 2,
+        "requiredReviewers": [],
+        "optionalReviewers": ["cx-devil-advocate"]
+      }
+    },
+    "signal-brief": {
+      "template": "templates/docs/signal-brief.md",
+      "primaryOwners": ["cx-researcher", "cx-product-manager"],
+      "workflowSkill": "docs/evidence-ingest-workflow",
+      "toneDefault": "direct",
+      "toneAllowed": ["direct"],
+      "structureRequirements": ["Signal", "Evidence", "Counter-signal", "What would make this actionable"],
+      "researchProfile": "user",
+      "releaseGate": {
+        "structuralLint": true,
+        "citationLint": true,
+        "proseMinimum": 1,
+        "requiredReviewers": [],
+        "optionalReviewers": []
+      }
+    },
+    "runbook": {
+      "template": "templates/docs/runbook.md",
+      "primaryOwners": ["cx-sre", "cx-operations"],
+      "workflowSkill": "docs/runbook-workflow",
+      "toneDefault": "blameless",
+      "toneAllowed": ["blameless", "direct"],
+      "structureRequirements": ["Alert trigger", "Symptoms", "Impact", "Severity and response", "Diagnostic steps", "Remediation", "Rollback", "Escalation"],
+      "visualRequirements": [
+        { "id": "runbook-diagnostic-flowchart", "check": "artifact-has-mermaid", "diagram": "flowchart" }
+      ],
+      "researchProfile": null,
+      "releaseGate": {
+        "structuralLint": true,
+        "citationLint": false,
+        "proseMinimum": 2,
+        "requiredReviewers": [],
+        "optionalReviewers": ["cx-sre"]
+      }
+    },
+    "incident-report": {
+      "template": "templates/docs/incident-report.md",
+      "primaryOwners": ["cx-sre", "cx-operations"],
+      "workflowSkill": "docs/runbook-workflow",
+      "toneDefault": "blameless",
+      "toneAllowed": ["blameless"],
+      "structureRequirements": ["Summary", "Severity rationale", "Impact", "Timeline", "Trigger", "Root cause", "Contributing factors", "Action items"],
+      "visualRequirements": [
+        { "id": "incident-timeline-table", "check": "artifact-table-has-columns", "columns": ["Time (UTC)", "Event"] }
+      ],
+      "researchProfile": null,
+      "releaseGate": {
+        "structuralLint": true,
+        "citationLint": false,
+        "proseMinimum": 2,
+        "requiredReviewers": [],
+        "optionalReviewers": ["cx-devil-advocate"]
+      }
+    },
+    "postmortem": {
+      "template": "templates/docs/postmortem.md",
+      "primaryOwners": ["cx-sre"],
+      "workflowSkill": "docs/runbook-workflow",
+      "toneDefault": "blameless",
+      "toneAllowed": ["blameless"],
+      "structureRequirements": ["Summary", "Severity rationale", "Impact", "Timeline", "Trigger", "Root cause", "Contributing factors", "Action items"],
+      "visualRequirements": [
+        { "id": "postmortem-timeline-table", "check": "artifact-table-has-columns", "columns": ["Time (UTC)", "Event"] }
+      ],
+      "researchProfile": null,
+      "releaseGate": {
+        "structuralLint": true,
+        "citationLint": false,
+        "proseMinimum": 2,
+        "requiredReviewers": [],
+        "optionalReviewers": []
+      }
+    },
+    "strategy": {
+      "template": "templates/docs/strategy.md",
+      "primaryOwners": ["cx-business-strategist", "cx-product-manager"],
+      "workflowSkill": "docs/strategy-workflow",
+      "toneDefault": "executive-concise",
+      "toneAllowed": ["executive-concise", "decision-forcing-direct"],
+      "structureRequirements": ["Vision", "Bets", "Non-bets", "North Star Metric", "Metrics", "Milestones", "Risks"],
+      "visualRequirements": [
+        { "id": "strategy-bet-matrix", "check": "artifact-table-has-columns", "columns": ["Metric", "Type (leading/lagging)", "Baseline", "Target", "Owner"] }
+      ],
+      "researchProfile": "market",
+      "releaseGate": {
+        "structuralLint": true,
+        "citationLint": true,
+        "proseMinimum": 2,
+        "requiredReviewers": ["cx-devil-advocate"],
+        "optionalReviewers": ["cx-business-strategist"]
+      }
+    },
+    "memo": {
+      "template": "templates/docs/memo.md",
+      "primaryOwners": ["cx-docs-keeper", "cx-business-strategist"],
+      "workflowSkill": "docs/memo-and-decision-capture",
+      "toneDefault": "executive-concise",
+      "toneAllowed": ["executive-concise", "friendly", "decision-forcing-direct"],
+      "structureRequirements": ["TL;DR", "Context", "Argument", "Recommendation", "Risks and tradeoffs", "Decision requested"],
+      "researchProfile": null,
+      "releaseGate": {
+        "structuralLint": true,
+        "citationLint": true,
+        "proseMinimum": 2,
+        "requiredReviewers": [],
+        "optionalReviewers": []
+      }
+    },
+    "prfaq": {
+      "template": "templates/docs/prfaq.md",
+      "primaryOwners": ["cx-product-manager", "cx-business-strategist"],
+      "workflowSkill": "docs/prfaq-workflow",
+      "toneDefault": "friendly",
+      "toneAllowed": ["friendly", "executive-concise"],
+      "structureRequirements": ["Problem statement", "Press release", "External FAQ", "Internal FAQ", "Evidence appendix"],
+      "visualRequirements": [
+        { "id": "prfaq-customer-flow", "check": "artifact-has-mermaid", "diagram": "flowchart" }
+      ],
+      "researchProfile": "user",
+      "releaseGate": {
+        "structuralLint": true,
+        "citationLint": true,
+        "proseMinimum": 3,
+        "requiredReviewers": ["cx-devil-advocate"],
+        "optionalReviewers": ["cx-ux-researcher"]
+      }
+    },
+    "one-pager": {
+      "template": "templates/docs/one-pager.md",
+      "primaryOwners": ["cx-product-manager", "cx-business-strategist"],
+      "workflowSkill": "docs/prd-workflow",
+      "toneDefault": "executive-concise",
+      "toneAllowed": ["executive-concise"],
+      "structureRequirements": ["Problem", "Proposal", "Why now", "Success measure", "Cost", "Asks"],
+      "visualRequirements": [
+        { "id": "one-pager-success-table", "check": "artifact-table-has-columns", "columns": ["Measure", "Baseline", "Target", "By when"] }
+      ],
+      "researchProfile": "market",
+      "releaseGate": {
+        "structuralLint": true,
+        "citationLint": true,
+        "proseMinimum": 2,
+        "requiredReviewers": ["cx-devil-advocate"],
+        "optionalReviewers": []
+      }
+    },
+    "customer-profile": {
+      "template": "templates/docs/customer-profile.md",
+      "primaryOwners": ["cx-product-manager", "cx-docs-keeper"],
+      "workflowSkill": "docs/customer-profile-workflow",
+      "toneDefault": "direct",
+      "toneAllowed": ["direct", "friendly"],
+      "structureRequirements": ["Snapshot", "Active pain points", "Open asks", "Evidence links"],
+      "visualRequirements": [
+        { "id": "customer-profile-open-asks", "check": "artifact-table-has-columns", "columns": ["Ask", "First raised", "Status"] }
+      ],
+      "researchProfile": "user",
+      "releaseGate": {
+        "structuralLint": true,
+        "citationLint": true,
+        "proseMinimum": 1,
+        "requiredReviewers": [],
+        "optionalReviewers": []
+      }
+    },
+    "backlog-proposal": {
+      "template": "templates/docs/backlog-proposal.md",
+      "primaryOwners": ["cx-product-manager"],
+      "workflowSkill": "docs/backlog-proposal-workflow",
+      "toneDefault": "direct",
+      "toneAllowed": ["direct"],
+      "structureRequirements": ["Source evidence", "Proposed changes", "Duplicate and conflict check", "Approval request"],
+      "researchProfile": "user",
+      "releaseGate": {
+        "structuralLint": true,
+        "citationLint": true,
+        "proseMinimum": 1,
+        "requiredReviewers": [],
+        "optionalReviewers": []
+      }
+    },
+    "test-plan": {
+      "template": "templates/docs/test-plan.md",
+      "primaryOwners": ["cx-qa", "cx-test-automation"],
+      "workflowSkill": "devops/testing",
+      "toneDefault": "direct",
+      "toneAllowed": ["direct"],
+      "structureRequirements": ["Scope", "Test strategy", "Coverage", "Key scenarios", "Entry and exit criteria"],
+      "visualRequirements": [
+        { "id": "test-plan-coverage-table", "check": "artifact-table-has-columns", "columns": ["Scenario", "Type", "Priority"] }
+      ],
+      "researchProfile": "codebase",
+      "releaseGate": {
+        "structuralLint": true,
+        "citationLint": false,
+        "proseMinimum": 2,
+        "requiredReviewers": [],
+        "optionalReviewers": ["cx-qa"]
+      }
+    },
+    "qa-strategy": {
+      "template": "templates/docs/qa-strategy.md",
+      "primaryOwners": ["cx-qa"],
+      "workflowSkill": "devops/testing",
+      "toneDefault": "direct",
+      "toneAllowed": ["direct"],
+      "structureRequirements": ["Scope", "Test strategy", "Coverage", "Key scenarios", "Entry and exit criteria"],
+      "researchProfile": "codebase",
+      "releaseGate": {
+        "structuralLint": true,
+        "citationLint": false,
+        "proseMinimum": 2,
+        "requiredReviewers": [],
+        "optionalReviewers": []
+      }
+    },
+    "changelog": {
+      "template": "templates/docs/changelog-entry.md",
+      "primaryOwners": ["cx-docs-keeper", "cx-release-manager"],
+      "workflowSkill": "docs/memo-and-decision-capture",
+      "toneDefault": "direct",
+      "toneAllowed": ["direct", "friendly"],
+      "structureRequirements": [],
+      "researchProfile": null,
+      "releaseGate": {
+        "structuralLint": false,
+        "citationLint": false,
+        "proseMinimum": 1,
+        "requiredReviewers": [],
+        "optionalReviewers": []
+      }
+    },
+    "architecture-overview": {
+      "template": "templates/docs/adr.md",
+      "primaryOwners": ["cx-architect"],
+      "workflowSkill": "docs/adr-workflow",
+      "toneDefault": "pedagogical",
+      "toneAllowed": ["pedagogical", "decision-forcing-direct"],
+      "structureRequirements": ["Problem", "Decision", "Consequences"],
+      "researchProfile": "codebase",
+      "releaseGate": {
+        "structuralLint": true,
+        "citationLint": true,
+        "proseMinimum": 2,
+        "requiredReviewers": ["cx-reviewer"],
+        "optionalReviewers": []
+      }
+    },
+    "system-design": {
+      "template": "templates/docs/adr.md",
+      "primaryOwners": ["cx-architect"],
+      "workflowSkill": "docs/adr-workflow",
+      "toneDefault": "pedagogical",
+      "toneAllowed": ["pedagogical"],
+      "structureRequirements": ["Problem", "Decision", "Consequences"],
+      "researchProfile": "codebase",
+      "releaseGate": {
+        "structuralLint": true,
+        "citationLint": true,
+        "proseMinimum": 2,
+        "requiredReviewers": ["cx-reviewer"],
+        "optionalReviewers": []
+      }
+    },
+    "security-review": {
+      "template": "templates/docs/security-audit-report.md",
+      "primaryOwners": ["cx-security"],
+      "workflowSkill": "quality-gates/verify-security",
+      "toneDefault": "direct",
+      "toneAllowed": ["direct"],
+      "structureRequirements": ["Executive summary", "Findings", "Remediation priority"],
+      "researchProfile": "compliance",
+      "releaseGate": {
+        "structuralLint": true,
+        "citationLint": true,
+        "proseMinimum": 2,
+        "requiredReviewers": ["cx-devil-advocate"],
+        "optionalReviewers": []
+      }
+    },
+    "threat-model": {
+      "template": "templates/docs/security-audit-report.md",
+      "primaryOwners": ["cx-security"],
+      "workflowSkill": "security/threat-intel",
+      "toneDefault": "direct",
+      "toneAllowed": ["direct"],
+      "structureRequirements": ["Executive summary", "Findings", "Remediation priority"],
+      "researchProfile": "compliance",
+      "releaseGate": {
+        "structuralLint": true,
+        "citationLint": true,
+        "proseMinimum": 2,
+        "requiredReviewers": ["cx-devil-advocate"],
+        "optionalReviewers": []
+      }
+    },
+    "product-intelligence-report": {
+      "template": "templates/docs/product-intelligence-report.md",
+      "primaryOwners": ["cx-product-manager", "cx-business-strategist"],
+      "workflowSkill": "docs/product-intelligence-workflow",
+      "toneDefault": "executive-concise",
+      "toneAllowed": ["executive-concise", "direct"],
+      "structureRequirements": ["Executive readout", "Evidence base", "Themes", "Customer asks", "Product implications", "Recommended actions", "Gaps and risks"],
+      "researchProfile": "user",
+      "releaseGate": {
+        "structuralLint": true,
+        "citationLint": true,
+        "proseMinimum": 3,
+        "requiredReviewers": [],
+        "optionalReviewers": ["cx-devil-advocate"]
+      }
+    }
+  }
+}

package/specialists/artifact-manifest.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://geraldmaron.github.io/construct/specialists/artifact-manifest.schema.json",
+  "title": "Construct artifact capability manifest",
+  "type": "object",
+  "required": ["version", "artifacts"],
+  "additionalProperties": false,
+  "properties": {
+    "version": { "type": "integer", "minimum": 1 },
+    "description": { "type": "string" },
+    "artifacts": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/artifactEntry" }
+    }
+  },
+  "$defs": {
+    "visualRequirement": {
+      "type": "object",
+      "required": ["id", "check"],
+      "properties": {
+        "id": { "type": "string" },
+        "check": { "type": "string", "enum": ["artifact-has-mermaid", "artifact-table-has-columns"] },
+        "diagram": { "type": "string" },
+        "columns": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "releaseGate": {
+      "type": "object",
+      "properties": {
+        "structuralLint": { "type": "boolean" },
+        "citationLint": { "type": "boolean" },
+        "proseMinimum": { "type": "integer", "minimum": 0 },
+        "requiredReviewers": { "type": "array", "items": { "type": "string" } },
+        "optionalReviewers": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "artifactEntry": {
+      "type": "object",
+      "required": ["template", "primaryOwners", "toneDefault", "releaseGate"],
+      "properties": {
+        "template": { "type": "string" },
+        "primaryOwners": { "type": "array", "items": { "type": "string" } },
+        "workflowSkill": { "type": ["string", "null"] },
+        "toneDefault": { "type": "string" },
+        "toneAllowed": { "type": "array", "items": { "type": "string" } },
+        "structureRequirements": { "type": "array", "items": { "type": "string" } },
+        "visualRequirements": { "type": "array", "items": { "$ref": "#/$defs/visualRequirement" } },
+        "researchProfile": { "type": ["string", "null"] },
+        "releaseGate": { "$ref": "#/$defs/releaseGate" }
+      }
+    }
+  }
+}