@geraldmaron/construct 1.1.0 → 1.2.0

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" }
+      }
+    }
+  }
+}