@geraldmaron/construct 1.2.2 → 1.3.0

package/specialists/org/contracts/data-engineer-to-platform-engineer.json

@@ -0,0 +1,36 @@
+{
+  "id": "data-engineer-to-platform-engineer",
+  "producer": "cx-data-engineer",
+  "consumer": "cx-platform-engineer",
+  "trigger": {
+    "riskFlags": [
+      "data",
+      "pipeline",
+      "infrastructure"
+    ]
+  },
+  "input": {
+    "shape": "pipeline-spec",
+    "mustContain": [
+      "dataContract",
+      "qualityGates"
+    ]
+  },
+  "output": {
+    "shape": "platform-plan",
+    "mustContain": [
+      "problem",
+      "solution",
+      "migration",
+      "rollback"
+    ]
+  },
+  "preconditions": [
+    "Pipeline operational requirements (alerts, retries, backfills) stated in pipeline spec"
+  ],
+  "postconditions": [
+    "Operational burden (who maintains, how to debug) accepted by platform owner",
+    "Pipeline observability surfaces appear on a named dashboard, not just in logs"
+  ],
+  "description": ""
+}

package/specialists/org/contracts/designer-to-accessibility.json

@@ -0,0 +1,36 @@
+{
+  "id": "designer-to-accessibility",
+  "producer": "cx-designer",
+  "consumer": "cx-accessibility",
+  "trigger": {
+    "riskFlags": [
+      "ui",
+      "accessibility"
+    ]
+  },
+  "input": {
+    "shape": "design-deliverable",
+    "mustContain": [
+      "surface",
+      "deliverable",
+      "accessibilityCheckRan"
+    ]
+  },
+  "output": {
+    "shape": "a11y-findings",
+    "mustContain": [
+      "findings",
+      "wcagCriterion",
+      "userImpact",
+      "fix"
+    ]
+  },
+  "preconditions": [
+    "Flow exercised with a keyboard and a screen reader; not just spec-read"
+  ],
+  "postconditions": [
+    "Every finding cites a WCAG criterion and a concrete repro step",
+    "Findings that weren't exercised with the assistive technology are labeled 'unverified'"
+  ],
+  "description": ""
+}

package/specialists/org/contracts/engineer-to-qa.json

@@ -0,0 +1,34 @@
+{
+  "id": "engineer-to-qa",
+  "producer": "cx-engineer",
+  "consumer": "cx-qa",
+  "trigger": {
+    "always": true
+  },
+  "input": {
+    "schema": "lib/contract-schemas/implementation.json",
+    "mustContain": [
+      "filesChanged",
+      "tests"
+    ]
+  },
+  "output": {
+    "schema": "lib/contract-schemas/test-report.json",
+    "type": "test-report"
+  },
+  "preconditions": [
+    "Test plan exists or is derivable from acceptance criteria"
+  ],
+  "postconditions": [
+    "Verdict in {PASS, FAIL}",
+    "Coverage meets project threshold",
+    "FAIL blocks DONE in workflow"
+  ],
+  "description": "",
+  "teamBoundary": {
+    "crosses": true,
+    "producerTeam": "engineering-group",
+    "consumerTeam": "quality-group",
+    "requiresApprovalFrom": []
+  }
+}

package/specialists/org/contracts/engineer-to-reviewer.json

@@ -0,0 +1,52 @@
+{
+  "id": "engineer-to-reviewer",
+  "producer": "cx-engineer",
+  "consumer": "cx-reviewer",
+  "trigger": {
+    "always": true
+  },
+  "input": {
+    "schema": "lib/contract-schemas/implementation.json",
+    "mustContain": [
+      "filesChanged",
+      "verificationChecklist"
+    ]
+  },
+  "output": {
+    "schema": "lib/contract-schemas/review-report.json",
+    "type": "review-report",
+    "mustContain": [
+      "verdict"
+    ],
+    "mustContainOneOf": [
+      [
+        "findings",
+        "noIssuesFoundAt"
+      ]
+    ],
+    "mustMatchEnum": {
+      "verdict": [
+        "APPROVED",
+        "APPROVED_WITH_WARNINGS",
+        "BLOCKED"
+      ]
+    }
+  },
+  "preconditions": [
+    "Engineer status is not BLOCKED",
+    "Tests compiled; static analysis run"
+  ],
+  "postconditions": [
+    "Verdict in {APPROVED, APPROVED_WITH_WARNINGS, BLOCKED}",
+    "BLOCKED verdict stops downstream work until addressed",
+    "CRITICAL findings prevent release",
+    "Either findings is non-empty or noIssuesFoundAt enumerates the inspected paths — prevents silent rubber-stamp reviews"
+  ],
+  "description": "",
+  "teamBoundary": {
+    "crosses": true,
+    "producerTeam": "engineering-group",
+    "consumerTeam": "quality-group",
+    "requiresApprovalFrom": []
+  }
+}

package/specialists/org/contracts/explorer-to-engineer.json

@@ -0,0 +1,38 @@
+{
+  "id": "explorer-to-engineer",
+  "producer": "cx-explorer",
+  "consumer": "cx-engineer",
+  "trigger": {
+    "intent": [
+      "implementation",
+      "fix"
+    ],
+    "explorer.findingsReady": true
+  },
+  "input": {
+    "shape": "exploration-findings",
+    "mustContain": [
+      "entryPoints",
+      "keyFiles",
+      "gaps"
+    ]
+  },
+  "output": {
+    "schema": "lib/contract-schemas/implementation.json",
+    "type": "implementation"
+  },
+  "preconditions": [
+    "Exploration findings reviewed; gaps and surprising dependencies surfaced"
+  ],
+  "postconditions": [
+    "Implementation reads the files cited in keyFiles before edits",
+    "Gaps named by explorer (missing tests, missing error handling) are addressed or filed"
+  ],
+  "description": "",
+  "teamBoundary": {
+    "crosses": true,
+    "producerTeam": "strategy-group",
+    "consumerTeam": "engineering-group",
+    "requiresApprovalFrom": []
+  }
+}

package/specialists/org/contracts/legal-compliance-to-release-manager.json

@@ -0,0 +1,43 @@
+{
+  "id": "legal-compliance-to-release-manager",
+  "producer": "cx-legal-compliance",
+  "consumer": "cx-release-manager",
+  "trigger": {
+    "riskFlags": [
+      "compliance"
+    ],
+    "intent": [
+      "implementation"
+    ]
+  },
+  "input": {
+    "shape": "compliance-memo",
+    "mustContain": [
+      "risks",
+      "severity",
+      "remediation"
+    ]
+  },
+  "output": {
+    "shape": "release-decision",
+    "mustContain": [
+      "decision",
+      "rolloutPlan",
+      "rollbackPlan"
+    ]
+  },
+  "preconditions": [
+    "All must-fix compliance items closed or accepted in writing by the release owner"
+  ],
+  "postconditions": [
+    "Release blocks if any must-fix item is unresolved",
+    "Should-fix items carry a tracking issue and an owner"
+  ],
+  "description": "",
+  "teamBoundary": {
+    "crosses": true,
+    "producerTeam": "governance-group",
+    "consumerTeam": "operations-group",
+    "requiresApprovalFrom": []
+  }
+}

package/specialists/org/contracts/platform-engineer-to-engineer.json

@@ -0,0 +1,31 @@
+{
+  "id": "platform-engineer-to-engineer",
+  "producer": "cx-platform-engineer",
+  "consumer": "cx-engineer",
+  "trigger": {
+    "riskFlags": [
+      "platform"
+    ]
+  },
+  "input": {
+    "shape": "platform-plan",
+    "mustContain": [
+      "solution",
+      "migration",
+      "rollback"
+    ]
+  },
+  "output": {
+    "schema": "lib/contract-schemas/implementation.json",
+    "type": "implementation"
+  },
+  "preconditions": [
+    "Platform deps available in CI; lockfile updates reviewed",
+    "Secrets confirmed absent from build logs"
+  ],
+  "postconditions": [
+    "Implementation cites the platform plan and applies the migration steps in order",
+    "Rollback procedure verified once on a non-production environment"
+  ],
+  "description": ""
+}

package/specialists/org/contracts/product-manager-to-architect.json

@@ -0,0 +1,71 @@
+{
+  "id": "product-manager-to-architect",
+  "producer": "cx-product-manager",
+  "consumer": "cx-architect",
+  "trigger": {
+    "docAuthoring.docType": [
+      "prd",
+      "meta-prd",
+      "adr",
+      "rfc"
+    ]
+  },
+  "input": {
+    "shape": "prd-handoff",
+    "mustContain": [
+      "problem",
+      "functionalRequirements",
+      "nonFunctionalRequirements",
+      "acceptanceCriteria",
+      "constraints"
+    ]
+  },
+  "output": {
+    "schema": "lib/contract-schemas/decision.json",
+    "type": "decision"
+  },
+  "preconditions": [
+    "cx-devil-advocate framing challenge logged if riskFlags.architecture"
+  ],
+  "postconditions": [
+    "ADR Problem section traces to PRD Problem, not to tickets",
+    "ADR Rejected alternatives section present with ≥2 alternatives and specific rejection reasons",
+    "Reversibility section states whether one-way or two-way door",
+    {
+      "id": "adr-has-rejected-alternatives",
+      "description": "ADR must contain a Rejected Alternatives section",
+      "check": "artifact-has-section",
+      "section": "Rejected Alternatives"
+    },
+    {
+      "id": "adr-reversibility-stated",
+      "description": "ADR Reversibility section is present and non-empty",
+      "check": "artifact-section-nonempty",
+      "section": "Reversibility"
+    },
+    {
+      "id": "adr-consequences-stated",
+      "description": "ADR Consequences section is present and non-empty",
+      "check": "artifact-section-nonempty",
+      "section": "Consequences"
+    },
+    {
+      "id": "adr-numeric-claims-cited",
+      "description": "Every numeric claim in the ADR body cites a source",
+      "check": "artifact-claims-cited"
+    },
+    {
+      "id": "adr-manifest-reviewers",
+      "description": "Manifest required reviewers must appear in agent log before handoff",
+      "check": "artifact-reviewers-seen",
+      "fromManifest": true
+    }
+  ],
+  "description": "",
+  "teamBoundary": {
+    "crosses": true,
+    "producerTeam": "product-group",
+    "consumerTeam": "engineering-group",
+    "requiresApprovalFrom": []
+  }
+}

package/specialists/org/contracts/product-manager-to-data-analyst.json

@@ -0,0 +1,49 @@
+{
+  "id": "product-manager-to-data-analyst",
+  "producer": "cx-product-manager",
+  "consumer": "cx-data-analyst",
+  "trigger": {
+    "docAuthoring.docType": [
+      "prd",
+      "meta-prd"
+    ],
+    "riskFlags": [
+      "metrics"
+    ]
+  },
+  "input": {
+    "shape": "metrics-request",
+    "mustContain": [
+      "successDefinition",
+      "decisionPending"
+    ]
+  },
+  "output": {
+    "shape": "metrics-analysis",
+    "mustContain": [
+      "metricDefinition",
+      "baseline",
+      "successThreshold",
+      "dataQualityCaveats"
+    ]
+  },
+  "preconditions": [
+    "Success definition stated in writing before metric design begins"
+  ],
+  "postconditions": [
+    "Every percentage, multiplier, or magnitude cites the query, dashboard, or run that produced it",
+    "Baseline is a measured value or names the plan to establish one",
+    {
+      "id": "metrics-analysis-claims-cited",
+      "description": "Every numeric claim in the analysis cites the query or dashboard",
+      "check": "artifact-claims-cited"
+    }
+  ],
+  "description": "",
+  "teamBoundary": {
+    "crosses": true,
+    "producerTeam": "product-group",
+    "consumerTeam": "strategy-group",
+    "requiresApprovalFrom": []
+  }
+}

package/specialists/org/contracts/product-manager-to-ux-researcher.json

@@ -0,0 +1,51 @@
+{
+  "id": "product-manager-to-ux-researcher",
+  "producer": "cx-product-manager",
+  "consumer": "cx-ux-researcher",
+  "trigger": {
+    "docAuthoring.docType": [
+      "prd",
+      "meta-prd",
+      "prfaq"
+    ],
+    "riskFlags": [
+      "ux"
+    ]
+  },
+  "input": {
+    "shape": "ux-research-request",
+    "mustContain": [
+      "surface",
+      "userQuestion",
+      "decisionPending"
+    ]
+  },
+  "output": {
+    "shape": "ux-brief",
+    "mustContain": [
+      "userProfiles",
+      "jobsToBeDone",
+      "frictionMap",
+      "assumptionsLog"
+    ]
+  },
+  "preconditions": [
+    "PRD has an open user-research question; PRD not finalized"
+  ],
+  "postconditions": [
+    "Every friction-map entry cites the observation or session it came from",
+    "Stated preferences are labeled distinctly from observed behaviors",
+    {
+      "id": "ux-research-has-sources-section",
+      "description": "UX research artifact must contain a Sources section",
+      "check": "artifact-has-section",
+      "section": "Sources"
+    },
+    {
+      "id": "ux-research-claims-cited",
+      "description": "Every numeric or generalization claim in the UX brief cites the research source",
+      "check": "artifact-claims-cited"
+    }
+  ],
+  "description": ""
+}

package/specialists/org/contracts/qa-to-release-manager.json

@@ -0,0 +1,42 @@
+{
+  "id": "qa-to-release-manager",
+  "producer": "cx-qa",
+  "consumer": "cx-release-manager",
+  "trigger": {
+    "intent": [
+      "implementation"
+    ],
+    "workCategory": "deep"
+  },
+  "input": {
+    "schema": "lib/contract-schemas/test-report.json",
+    "mustContain": [
+      "verdict",
+      "passed",
+      "failed",
+      "coverage"
+    ]
+  },
+  "output": {
+    "shape": "release-decision",
+    "mustContain": [
+      "decision",
+      "rolloutPlan",
+      "rollbackPlan"
+    ]
+  },
+  "preconditions": [
+    "All upstream verdicts APPROVED; QA verdict PASS"
+  ],
+  "postconditions": [
+    "Rollback plan tested, not just described",
+    "Rollout plan has concrete checkpoint signals"
+  ],
+  "description": "",
+  "teamBoundary": {
+    "crosses": true,
+    "producerTeam": "quality-group",
+    "consumerTeam": "operations-group",
+    "requiresApprovalFrom": []
+  }
+}

package/specialists/org/contracts/qa-to-test-automation.json

@@ -0,0 +1,42 @@
+{
+  "id": "qa-to-test-automation",
+  "producer": "cx-qa",
+  "consumer": "cx-test-automation",
+  "trigger": {
+    "intent": [
+      "implementation"
+    ],
+    "automation.required": true
+  },
+  "input": {
+    "schema": "lib/contract-schemas/test-report.json",
+    "mustContain": [
+      "testStrategy",
+      "verdict"
+    ]
+  },
+  "output": {
+    "shape": "automation-plan",
+    "mustContain": [
+      "framework",
+      "coverageTargets",
+      "flakeBudget",
+      "deterministicWaits"
+    ]
+  },
+  "preconditions": [
+    "Existing test infrastructure surveyed before proposing new frameworks",
+    "Flaky-test signal collected over N runs before calling a test flaky"
+  ],
+  "postconditions": [
+    "Tests use deterministic waits and stable selectors; not arbitrary sleeps",
+    "Coverage targets aim at behaviors that matter, not at line counts that pad the number",
+    {
+      "id": "automation-plan-has-flake-budget",
+      "description": "Automation plan must contain a Flake Budget section",
+      "check": "artifact-has-section",
+      "section": "Flake Budget"
+    }
+  ],
+  "description": ""
+}

package/specialists/org/contracts/rd-lead-to-architect.json

@@ -0,0 +1,38 @@
+{
+  "id": "rd-lead-to-architect",
+  "producer": "cx-rd-lead",
+  "consumer": "cx-architect",
+  "trigger": {
+    "framingChallenge.required": true,
+    "rdLead.verdict": "frame-approved"
+  },
+  "input": {
+    "shape": "framing-brief",
+    "mustContain": [
+      "problemStatement",
+      "hypothesis",
+      "keyUnknowns",
+      "evidenceThreshold",
+      "recommendation"
+    ]
+  },
+  "output": {
+    "schema": "lib/contract-schemas/decision.json",
+    "type": "decision"
+  },
+  "preconditions": [
+    "Framing artifact exists at `.cx/framing/<slug>.md`",
+    "Hypothesis cleared of unverified assumptions"
+  ],
+  "postconditions": [
+    "ADR cites the framing brief as the upstream source for its Problem statement",
+    "Architect does not productionize components listed under 'WHAT NOT TO PRODUCTIONIZE YET'"
+  ],
+  "description": "",
+  "teamBoundary": {
+    "crosses": true,
+    "producerTeam": "strategy-group",
+    "consumerTeam": "engineering-group",
+    "requiresApprovalFrom": []
+  }
+}

package/specialists/org/contracts/researcher-to-architect.json

@@ -0,0 +1,40 @@
+{
+  "id": "researcher-to-architect",
+  "producer": "cx-researcher",
+  "consumer": "cx-architect",
+  "trigger": {
+    "externalResearch.required": true,
+    "riskFlags": [
+      "architecture"
+    ]
+  },
+  "input": {
+    "shape": "research-brief",
+    "mustContain": [
+      "question",
+      "method",
+      "sources",
+      "findings",
+      "confidence"
+    ]
+  },
+  "output": {
+    "schema": "lib/contract-schemas/decision.json",
+    "type": "decision"
+  },
+  "preconditions": [
+    "≥2 independent primary sources cited per load-bearing claim",
+    "Source classes tagged (internal/primary/secondary/tertiary)"
+  ],
+  "postconditions": [
+    "Architect's ADR cites the primary sources provided",
+    "Any conflicting evidence surfaced, not suppressed"
+  ],
+  "description": "",
+  "teamBoundary": {
+    "crosses": true,
+    "producerTeam": "product-group",
+    "consumerTeam": "engineering-group",
+    "requiresApprovalFrom": []
+  }
+}

package/specialists/org/contracts/researcher-to-product-manager.json

@@ -0,0 +1,57 @@
+{
+  "id": "researcher-to-product-manager",
+  "producer": "cx-researcher",
+  "consumer": "cx-product-manager",
+  "trigger": {
+    "docAuthoring.docType": [
+      "prd",
+      "meta-prd",
+      "prfaq",
+      "one-pager"
+    ]
+  },
+  "input": {
+    "shape": "evidence-brief",
+    "mustContain": [
+      "question",
+      "findings",
+      "sources",
+      "confidence",
+      "openQuestions"
+    ]
+  },
+  "output": {
+    "shape": "prd-handoff",
+    "mustContain": [
+      "problem",
+      "users",
+      "functionalRequirements",
+      "acceptanceCriteria"
+    ]
+  },
+  "preconditions": [
+    "Evidence threshold stated and met for each requirement"
+  ],
+  "postconditions": [
+    "PRD Problem section does not reference ticket IDs, roadmap items, or artifact filenames",
+    "Every functional requirement traces to observed user evidence",
+    {
+      "id": "prd-has-problem-section",
+      "description": "PRD must contain a Problem section",
+      "check": "artifact-has-section",
+      "section": "Problem"
+    },
+    {
+      "id": "prd-numeric-claims-cited",
+      "description": "Every numeric claim in the PRD body cites a source (no fabricated percentages or multipliers)",
+      "check": "artifact-claims-cited"
+    },
+    {
+      "id": "prd-manifest-reviewers",
+      "description": "Manifest required reviewers must appear in agent log before handoff",
+      "check": "artifact-reviewers-seen",
+      "fromManifest": true
+    }
+  ],
+  "description": ""
+}