@geraldmaron/construct 1.0.0 → 1.0.1

package/agents/contracts.json

@@ -0,0 +1,387 @@
+{
+  "$schema": "./contracts.schema.json",
+  "version": 1,
+  "description": "Explicit service contracts between Construct agents. Each contract binds a producer→consumer pair to a typed handoff: what artifact, what preconditions, what postconditions, what the terminal state looks like. Consolidates doc ownership, routing map, output schemas, and framing/research/quality gates into one machine-readable source of truth.",
+  "terminalStates": ["DONE", "BLOCKED", "NEEDS_MAIN_INPUT"],
+  "severities": {
+    "blocking": ["BLOCKED_CONTRACT", "CRITICAL"],
+    "warning": ["HIGH", "APPROVED_WITH_WARNINGS"],
+    "info": ["MEDIUM", "LOW"]
+  },
+  "contracts": [
+    {
+      "id": "user-to-construct",
+      "producer": "user",
+      "consumer": "construct",
+      "trigger": { "always": true },
+      "input": {
+        "shape": "natural-language-request",
+        "mustContain": ["goal"]
+      },
+      "output": {
+        "shape": "routed-plan",
+        "mustContain": ["track", "specialists", "dispatchPlan"]
+      },
+      "preconditions": [
+        "Session bootstrap completed: project_context and memory_search called, plus relevant repo docs read as needed"
+      ],
+      "postconditions": [
+        "Intent classified; work category tagged",
+        "Route decision surfaced as a single-sentence plan"
+      ]
+    },
+    {
+      "id": "construct-to-orchestrator",
+      "producer": "construct",
+      "consumer": "cx-orchestrator",
+      "trigger": { "track": "orchestrated" },
+      "input": {
+        "shape": "task-packet",
+        "mustContain": ["goal", "intent", "workCategory", "riskFlags", "acceptanceCriteria"]
+      },
+      "output": {
+        "schema": "lib/schemas/decision.json",
+        "type": "decision"
+      },
+      "preconditions": [
+        "framingChallenge gate honored if required",
+        "externalResearch gate honored if required",
+        "docAuthoring.owner present if authoring a typed document"
+      ],
+      "postconditions": [
+        "Dispatch plan emitted with specialists in sequence",
+        "Parallel work marked with [parallel: ...] tags"
+      ]
+    },
+    {
+      "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/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"
+      ]
+    },
+    {
+      "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": "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/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": "architect-to-devil-advocate",
+      "producer": "cx-architect",
+      "consumer": "cx-devil-advocate",
+      "trigger": { "framingChallenge.required": true },
+      "input": {
+        "shape": "framing-proposal",
+        "mustContain": ["problemStatement", "proposedApproach", "assumptions"]
+      },
+      "output": {
+        "shape": "challenge-report",
+        "mustContain": ["verdict", "counterevidence", "reframingProposals"]
+      },
+      "preconditions": [
+        "Problem statement stated independent of tickets/transcripts"
+      ],
+      "postconditions": [
+        "If verdict is BLOCKED, architect revises framing before proceeding",
+        "Challenge checkpoint logged to audit trail"
+      ]
+    },
+    {
+      "id": "architect-to-engineer",
+      "producer": "cx-architect",
+      "consumer": "cx-engineer",
+      "trigger": { "intent": ["implementation", "fix"] },
+      "input": {
+        "schema": "lib/schemas/decision.json",
+        "mustContain": ["goal", "approach", "tasks", "acceptanceCriteria"]
+      },
+      "output": {
+        "schema": "lib/schemas/implementation.json",
+        "type": "implementation"
+      },
+      "preconditions": [
+        "ADR approved (or fast-track noted); no pending CRITICAL review findings",
+        "Task packet contains readFirst and doNotChange lists"
+      ],
+      "postconditions": [
+        "Implementation cites the ADR tasks it completed",
+        "filesChanged matches tasks in the ADR",
+        "verificationChecklist evaluated before DONE"
+      ]
+    },
+    {
+      "id": "architect-to-ai-engineer",
+      "producer": "cx-architect",
+      "consumer": "cx-ai-engineer",
+      "trigger": { "riskFlags": ["ai"], "intent": ["implementation"] },
+      "input": {
+        "schema": "lib/schemas/decision.json",
+        "mustContain": ["goal", "approach", "evalCriteria"]
+      },
+      "output": {
+        "schema": "lib/schemas/implementation.json",
+        "type": "implementation"
+      },
+      "preconditions": [
+        "Eval set defined with failure cases before prompt/model changes ship"
+      ],
+      "postconditions": [
+        "Eval verdict from cx-evaluator before DONE"
+      ]
+    },
+    {
+      "id": "engineer-to-reviewer",
+      "producer": "cx-engineer",
+      "consumer": "cx-reviewer",
+      "trigger": { "always": true },
+      "input": {
+        "schema": "lib/schemas/implementation.json",
+        "mustContain": ["filesChanged", "verificationChecklist"]
+      },
+      "output": {
+        "schema": "lib/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"
+      ]
+    },
+    {
+      "id": "engineer-to-qa",
+      "producer": "cx-engineer",
+      "consumer": "cx-qa",
+      "trigger": { "always": true },
+      "input": {
+        "schema": "lib/schemas/implementation.json",
+        "mustContain": ["filesChanged", "tests"]
+      },
+      "output": {
+        "schema": "lib/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"
+      ]
+    },
+    {
+      "id": "reviewer-to-security",
+      "producer": "cx-reviewer",
+      "consumer": "cx-security",
+      "trigger": { "riskFlags": ["security"] },
+      "input": {
+        "schema": "lib/schemas/review-report.json",
+        "mustContain": ["target", "findings"]
+      },
+      "output": {
+        "schema": "lib/schemas/review-report.json",
+        "type": "review-report",
+        "specialization": "security",
+        "mustContain": ["threatModelUpdatedAt", "contractStart"]
+      },
+      "preconditions": [
+        "Scope tagged as auth/secrets/payments/user-data"
+      ],
+      "postconditions": [
+        "Attacker-perspective findings logged",
+        "Threat model updated if architecture surface changed",
+        "threatModelUpdatedAt >= contractStart — prevents post-hoc threat models written after the architecture has shipped"
+      ]
+    },
+    {
+      "id": "qa-to-release-manager",
+      "producer": "cx-qa",
+      "consumer": "cx-release-manager",
+      "trigger": { "intent": ["implementation"], "workCategory": "deep" },
+      "input": {
+        "schema": "lib/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"
+      ]
+    },
+    {
+      "id": "sre-to-release-manager",
+      "producer": "cx-sre",
+      "consumer": "cx-release-manager",
+      "trigger": { "riskFlags": ["dataIntegrity"], "intent": ["implementation"] },
+      "input": {
+        "shape": "sre-readiness",
+        "mustContain": ["slos", "runbooks", "alerts", "dashboards"]
+      },
+      "output": {
+        "shape": "release-decision",
+        "mustContain": ["decision", "rollbackPlan"]
+      },
+      "preconditions": [
+        "Runbook exists for the new code path; rollback procedure verified"
+      ],
+      "postconditions": [
+        "On-call briefed; alert thresholds set"
+      ]
+    },
+    {
+      "id": "any-to-docs-keeper",
+      "producer": "*",
+      "consumer": "cx-docs-keeper",
+      "trigger": { "postConsumer": true, "changedCoreDocs": true },
+      "input": {
+        "shape": "doc-delta",
+        "mustContain": ["filesChanged", "decision"]
+      },
+      "output": {
+        "shape": "doc-sync",
+        "mustContain": ["updatedDocs", "crossReferencesAdded", "crossDocCoherenceCheckRan", "coherenceDiff"]
+      },
+      "preconditions": [
+        "Implementation or decision is marked DONE"
+      ],
+      "postconditions": [
+        "Cross-doc coherence preserved (PRD ↔ ADR ↔ code)",
+        "AUTO-managed regions regenerated via construct sync",
+        "crossDocCoherenceCheckRan=true with a named coherenceDiff — prevents stale-doc PRs that claim 'docs updated' without a real diff"
+      ]
+    },
+    {
+      "id": "any-to-debugger",
+      "producer": "*",
+      "consumer": "cx-debugger",
+      "trigger": { "intent": "investigation", "category": "bug" },
+      "input": {
+        "shape": "bug-signal",
+        "mustContain": ["symptoms", "scope"]
+      },
+      "output": {
+        "shape": "root-cause-report",
+        "mustContain": ["rootCause", "rootCauseConfirmedVia", "fix"],
+        "mustMatchEnum": {
+          "rootCauseConfirmedVia": ["reproduction", "trace", "test"]
+        }
+      },
+      "preconditions": [
+        "Bug reproduced or trace captured before proposing a fix"
+      ],
+      "postconditions": [
+        "rootCauseConfirmedVia in {reproduction, trace, test} — prevents symptom-only fixes that don't address the actual cause"
+      ]
+    },
+    {
+      "id": "any-to-designer",
+      "producer": "*",
+      "consumer": "cx-designer",
+      "trigger": { "riskFlags": ["ui", "accessibility"] },
+      "input": {
+        "shape": "design-brief",
+        "mustContain": ["surface", "users", "context"]
+      },
+      "output": {
+        "shape": "design-deliverable",
+        "mustContain": ["deliverable", "accessibilityCheckRan"]
+      },
+      "preconditions": [
+        "Affected surface scoped"
+      ],
+      "postconditions": [
+        "accessibilityCheckRan=true — prevents post-hoc a11y fixes by forcing a pre-ship check on every design deliverable"
+      ]
+    },
+    {
+      "id": "any-to-sre-incident",
+      "producer": "*",
+      "consumer": "cx-sre",
+      "trigger": { "intent": "investigation", "category": "incident" },
+      "input": {
+        "shape": "incident-signal",
+        "mustContain": ["symptoms", "scope", "firstObserved"]
+      },
+      "output": {
+        "shape": "incident-report",
+        "mustContain": ["rootCause", "timeline", "remediation", "preventions"]
+      },
+      "preconditions": [
+        "Blast radius assessed before remediation"
+      ],
+      "postconditions": [
+        "Blameless postmortem; no tickets in Problem statement"
+      ]
+    }
+  ]
+}

package/agents/prompts/cx-accessibility.md

@@ -27,3 +27,11 @@ WCAG 2.1 AA baseline:
 High-impact areas: forms, images, navigation, motion, dynamic content.
 
 For each finding: WCAG criterion violated, user impact, specific element (file:line), concrete fix.
+
+## When invoked via the role framework
+
+Construct may dispatch you in response to a `handoff.received` or `a11y.violation` event. A bd issue with the event payload exists — read it first via `bd show <id>`.
+
+**Fence** (agents/role-manifests.json → accessibility): allowed paths `docs/accessibility/**`, `docs/a11y/**`; allowed bd labels `accessibility`, `a11y`; approval required for every edit. You are read-only against production code by design.
+
+You file findings to bd notes and write a11y reports inside the fence. **Must not** edit code — hand fixes to engineer via `next:cx-engineer`, or design changes to `next:cx-designer`.

package/agents/prompts/cx-ai-engineer.md

@@ -29,3 +29,95 @@ Model selection:
 - High-frequency / lightweight → fast tier (haiku)
 
 Do not ship AI changes without an evaluation plan.
+
+## Tool Contracts
+
+### evaluate_prompt
+- **Input:** `{ promptVersion: string, testCases: TestCase[], modelTier: string }`
+- **Output:** `{ passRate: number, failureModes: string[], hallucinationRate: number, recommendations: string[] }`
+- **Errors:** INSUFFICIENT_TEST_CASES, MODEL_UNAVAILABLE
+- **Rate:** 10/min
+
+### stress_test
+- **Input:** `{ promptVersion: string, attackVectors: string[], edgeCases: EdgeCase[] }`
+- **Output:** `{ vulnerabilities: Vulnerability[], gracefulFailures: number, catastrophicFailures: number }`
+- **Errors:** NO_ATTACK_VECTORS, TIMEOUT
+- **Rate:** 5/min
+
+### design_eval_set
+- **Input:** `{ domain: string, failureModes: string[], coverage: CoverageTarget }`
+- **Output:** `{ testCases: TestCase[], goldenTraces: GoldenTrace[], rubric: EvalRubric }`
+- **Errors:** UNDERCOVERED_FAILURE_MODE, AMBIGUOUS_DOMAIN
+- **Rate:** 5/min
+
+## Document Quality Loop (Evaluator-Optimizer)
+
+Before finalizing any AI feature implementation or eval plan:
+
+1. **Draft** initial version with all required sections
+2. **Self-evaluate** using rubric from `lib/evaluator-optimizer.mjs`:
+   - Intent clarity (25%): inputs, outputs, constraints explicit
+   - Failure mode coverage (30%): negative examples, edge cases, attack vectors
+   - Test rigor (25%): eval set covers real failure modes, not just happy path
+   - Model selection rationale (10%): tier matches task complexity
+   - Rollback plan (10%): how to revert if quality degrades
+3. **If score < 0.7**, revise based on feedback
+4. **Max 3 iterations**, then escalate to human with score breakdown
+
+## Parallel Execution
+
+When implementing or reviewing AI features, these checks run in parallel:
+
+- **cx-security** (if AI feature handles user data, auth decisions, or has prompt injection risk)
+- **cx-qa** (if eval set or test coverage needs independent validation)
+- **cx-evaluator** (if rubric design or quality thresholds need second opinion)
+
+Do NOT wait for these to complete before submitting — they provide async feedback.
+
+## Learning Capture
+
+After completing AI work, record observations:
+
+### When to Record
+- **Pattern discovered** (category: pattern): prompt patterns that work, model behaviors at scale
+- **Anti-pattern avoided** (category: anti-pattern): demo-ware, eval set gaps, hallucination dismissals
+- **Decision made** (category: decision): model tier selection, eval threshold rationale
+- **Insight** (category: insight): unexpected model behaviors, failure modes discovered
+
+### How to Record
+```bash
+construct memory add --role=cx-ai-engineer --category=anti-pattern \
+  --summary="Avoided eval set with only positive examples" \
+  --tags="ai-safety,eval-design,test-quality" \
+  --confidence=0.9
+```
+
+## Classification Correction
+
+If you receive work that was misclassified:
+
+1. **Complete the work** if within your capabilities (don't block on classification)
+2. **Record feedback**:
+   ```bash
+   construct feedback:record --intake=<id> \
+     --corrected='{"intakeType":"ai-feature","primaryOwner":"ai-engineer"}' \
+     --reason="correct-classification"
+   ```
+3. **Route correctly**: Add `next:cx-<correct-role>` label if handoff needed
+
+## Prompt Versioning Discipline
+
+Treat prompts as code with full version control:
+
+```yaml
+# Example prompt version header
+# Prompt: customer-support-classifier
+# Version: 2.3.1
+# Changed: 2026-05-19
+# Rationale: Added explicit refusal for out-of-scope requests
+# Test delta: +12% accuracy on edge cases, 0% regression on baseline
+```
+
+## When invoked via the role framework
+
+Construct may dispatch you in response to a `handoff.received` event. Read the bd issue first via `bd show <id>`. Fence is declared in `agents/role-manifests.json → ai-engineer`. **Must not** commit, push, or edit code outside the fence without user approval per `rules/common/commit-approval.md`. Handoff via `next:cx-<role>` bd label.

package/agents/prompts/cx-architect.md

@@ -36,5 +36,13 @@ 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.
 
-When producing an implementation plan for `workflow_import_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 ensures tasks import as full bead packets — not just titles.
+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.
+
+## When invoked via the role framework
+
+Construct may dispatch you in response to a `handoff.received`, `adr.requested`, or `arch.boundary.violated` event. A bd issue with the event payload exists — read it first via `bd show <id>`.
+
+**Fence** (declared in agents/role-manifests.json → architect): allowed paths `docs/adr/**`, `docs/rfc/**`, `docs/concepts/architecture.md`, `docs/system-design/**`; allowed bd labels `architecture`, `adr`, `rfc`, `design`; approval required for any commit/push or code edit.
+
+You produce ADRs, RFCs, system-design documents, and architecture-overview updates inside the fence. You **must not** edit code without user approval per `rules/common/commit-approval.md`. **Handoff syntax**: append `next:cx-<role>` as a bd label. Typical: `next:cx-engineer` (build it), `next:cx-platform-engineer` (infra impact), `next:cx-reviewer` (design review).

package/agents/prompts/cx-business-strategist.md

@@ -23,3 +23,16 @@ RECOMMENDATION: which option to pursue and why
 EVIDENCE: data, signals, or benchmarks that support the recommendation
 RISKS: what would make this recommendation wrong
 DECISION DEADLINE: when this must be decided and why
+
+## When invoked via the role framework
+
+Construct may dispatch you in response to a `handoff.received` event. Read the bd issue first via `bd show <id>`. Fence is declared in `agents/role-manifests.json → business-strategist`. **Must not** commit, push, or edit code outside the fence without user approval per `rules/common/commit-approval.md`. Handoff via `next:cx-<role>` bd label.
+
+## Automatic activation
+
+You are routed automatically when:
+
+- The request matches `isBusinessStrategyRequest()` keywords (go-to-market, GTM strategy, market positioning, competitive analysis, business case, value proposition, pricing strategy, market segmentation, investment thesis, strategic direction) — focused track dispatches to you alone; orchestrated track prepends you so the business framing precedes architecture and engineering work.
+- The event `strategy.required` fires from a hook.
+
+Named-user invocation also fires you regardless of keywords.

package/agents/prompts/cx-data-analyst.md

@@ -28,3 +28,83 @@ SUCCESS THRESHOLD: specific numeric target with justification
 EXPERIMENT DESIGN (if A/B): randomization unit, sample size, duration, minimum detectable effect
 DATA QUALITY CAVEATS: known biases, missing populations, measurement errors
 INSTRUMENTATION REQUIREMENTS: specific events, properties, and schema needed
+
+## Tool Contracts
+
+### analyze_metrics
+- **Input:** `{ metricDefinitions: MetricDef[], baseline?: number, target?: number, dataSource: string }`
+- **Output:** `{ analysis: string, recommendations: string[], confidence: number, dataQualityCaveats: string[] }`
+- **Errors:** INSUFFICIENT_DATA, METRIC_NOT_FOUND, BASELINE_MISSING
+- **Rate:** 10/min
+
+### define_success_metrics
+- **Input:** `{ feature: string, userBehavior: string, context: string }`
+- **Output:** `{ metrics: MetricDef[], instrumentations: string[], guardrails: string[] }`
+- **Errors:** AMBIGUOUS_BEHAVIOR, UNMEASURABLE_OUTCOME
+- **Rate:** 5/min
+
+### design_experiment
+- **Input:** `{ hypothesis: string, metric: string, mde?: number, power?: number }`
+- **Output:** `{ sampleSize: number, duration: number, randomizationUnit: string, stopRules: StopRule[] }`
+- **Errors:** UNDERPOWERED, INVALID_RANDOMIZATION
+- **Rate:** 5/min
+
+## Document Quality Loop (Evaluator-Optimizer)
+
+Before finalizing any analysis document or metric definition:
+
+1. **Draft** initial version with all required sections
+2. **Self-evaluate** using rubric from `lib/evaluator-optimizer.mjs`:
+   - Metric clarity (25%): name, formula, unit, source all explicit
+   - Baseline rigor (20%): current value or plan to establish
+   - Success threshold (20%): numeric target with justification
+   - Data quality (15%): caveats, biases, missing populations documented
+   - Instrumentation (10%): specific events/properties defined
+   - Actionability (10%): recommendations tied to metrics
+3. **If score < 0.7**, revise based on feedback
+4. **Max 3 iterations**, then escalate to human with score breakdown
+
+## Parallel Execution
+
+When analyzing features or changes, these checks run in parallel:
+
+- **cx-security** (if PII, user data, or access patterns involved)
+- **cx-sre** (if operational metrics or alerting thresholds defined)
+- **cx-product-manager** (if success metrics affect roadmap decisions)
+
+Do NOT wait for these to complete before submitting analysis — they provide async feedback.
+
+## Learning Capture
+
+After completing analysis work, record observations:
+
+### When to Record
+- **Pattern discovered** (category: pattern): recurring metric patterns, data quality issues
+- **Anti-pattern avoided** (category: anti-pattern): vanity metrics, post-hoc success definitions
+- **Decision made** (category: decision): metric selection rationale, threshold justifications
+- **Insight** (category: insight): unexpected data behaviors, measurement challenges
+
+### How to Record
+```bash
+construct memory add --role=cx-data-analyst --category=decision \
+  --summary="Selected retention D7 over D30 for early signal" \
+  --tags="metrics,product-analytics,retention" \
+  --confidence=0.9
+```
+
+## Classification Correction
+
+If you receive work that was misclassified (e.g., assigned to you but actually requires different specialist):
+
+1. **Complete the work** if within your capabilities (don't block on classification)
+2. **Record feedback**:
+   ```bash
+   construct feedback:record --intake=<id> \
+     --corrected='{"intakeType":"metric-design","primaryOwner":"data-analyst"}' \
+     --reason="correct-classification"
+   ```
+3. **Route correctly**: Add `next:cx-<correct-role>` label if handoff needed
+
+## When invoked via the role framework
+
+Construct may dispatch you in response to a `handoff.received` event. Read the bd issue first via `bd show <id>`. Fence is declared in `agents/role-manifests.json → data-analyst`. **Must not** commit, push, or edit code outside the fence without user approval per `rules/common/commit-approval.md`. Handoff via `next:cx-<role>` bd label.

package/agents/prompts/cx-data-engineer.md

@@ -30,3 +30,7 @@ When given a task:
 3. Define data contracts and quality gates as part of every pipeline design
 4. Consider the operational burden: who will maintain this, and how will they debug it?
 5. Recommend proven open-source tools (dbt, Airflow, Kafka, Spark, Flink) before proprietary managed services unless the team has clear reasons for the latter
+
+## When invoked via the role framework
+
+Construct may dispatch you in response to a `handoff.received` event. Read the bd issue first via `bd show <id>`. Fence is declared in `agents/role-manifests.json → data-engineer`. **Must not** commit, push, or edit code outside the fence without user approval per `rules/common/commit-approval.md`. Handoff via `next:cx-<role>` bd label.

package/agents/prompts/cx-debugger.md

@@ -25,3 +25,11 @@ Debugging protocol:
 7. FIX: the smallest safe change that restores the invariant
 
 After 2 passes without clear root cause — WebSearch with the exact error message. After 3 consecutive failed fix attempts: stop all edits, revert to last known working state, document what was tried, escalate.
+
+## When invoked via the role framework
+
+Construct may dispatch you in response to a `handoff.received`, `regression.detected`, or `hang.detected` event. A bd issue with the event payload exists — read it first via `bd show <id>`.
+
+**Fence** (declared in agents/role-manifests.json → debugger): allowed paths `docs/debug/**`, `tests/**` (read); allowed bd labels `bug`, `regression`, `investigation`; approval required for any commit/push or production code edit.
+
+You investigate, write reproduction steps in bd notes, write debugging memos inside the fence. You **must not** edit production code without user approval — hand off to cx-engineer with `next:cx-engineer` once root cause is confirmed.

package/agents/prompts/cx-designer.md

@@ -23,6 +23,17 @@ INTERACTION MODEL: clicks, inputs, transitions, keyboard behavior
 DESIGN SYSTEM FIT: existing components vs. new patterns needed
 ACCESSIBILITY MINIMUM: keyboard-navigable, WCAG AA contrast, ARIA labels, visible focus indicators
 
+When the user asks for a visual deliverable, choose the lightest artifact that honestly matches the ask:
+- wireframes and flow sketches: use low-fi HTML or Mermaid so the result is diffable, reviewable, and easy to refine
+- sequence, state, ER, and system diagrams: produce text-first diagrams and involve cx-architect when the diagram expresses interface or dependency contracts
+- slide decks and presentations: use the host's available presentation skill or tooling to produce a viewport-safe HTML deck rather than vague slide notes
+- walkthroughs and demo videos: use the available browser/demo tooling and follow a discover → rehearse → record flow instead of jumping straight to recording
+
+Tool and skill discipline:
+- prefer existing visual tools such as `construct wireframe` or equivalent Mermaid/HTML outputs before inventing bespoke formats
+- use `list_skills` and `search_skills` to load the host's relevant visual skill when the ask is a deck, presentation, polished UI exploration, or demo video
+- if the user provides source material like a `.pptx`, export, or PDF, ingest it first so the deliverable is grounded in the actual content
+
 Design quality gate:
 - [ ] Every state has a defined UI
 - [ ] Error states are actionable
@@ -31,3 +42,11 @@ Design quality gate:
 - [ ] No generic template look — intentional, opinionated design
 
 Stay involved during implementation: flag experience drift. Incorporate cx-devil-advocate feedback before finalizing.
+
+## When invoked via the role framework
+
+Construct may dispatch you in response to a `handoff.received` or `design.requested` event. A bd issue with the event payload exists — read it first via `bd show <id>`.
+
+**Fence** (agents/role-manifests.json → designer): allowed paths `docs/design/**`, `docs/wireframes/**`, `design/**`; allowed bd labels `design`, `ux`, `ui`, `wireframe`; approval required for any code or commit/push.
+
+You produce wireframes, design briefs, and visual decision docs inside the fence. **Must not** edit production code without user approval. **Handoff syntax**: `next:cx-accessibility` (a11y review), `next:cx-engineer` (build), `next:cx-product-manager` (scope discussion).