@geraldmaron/construct 1.0.0

package/.env.example

@@ -0,0 +1,69 @@
+# Construct — Environment Variables
+# Copy this file to .env and fill in your values
+
+# ─── AI Providers ─────────────────────────────────────────────────────────────
+# Required: at least one AI provider API key
+ANTHROPIC_API_KEY=sk-ant-...
+OPENAI_API_KEY=sk-...
+
+# OpenRouter — required when using OpenRouter models (access 100+ models via one key)
+OPENROUTER_API_KEY=sk-or-v1-...
+OPENROUTER_REFERER=https://your-app.example.com
+OPENROUTER_TITLE=Your App Name
+
+# ─── Model Router ─────────────────────────────────────────────────────────────
+# Construct auto-discovers free OpenRouter models and falls back on rate limits.
+# Run 'construct models --poll' to see what's available now.
+# Run 'construct models --apply' to auto-set best free models + sync.
+#
+# Manual overrides (these win over registry defaults):
+# CX_MODEL_REASONING=anthropic/claude-opus-4-6
+# CX_MODEL_STANDARD=anthropic/claude-sonnet-4-6
+# CX_MODEL_FAST=anthropic/claude-haiku-4-5-20251001
+#
+# OpenRouter free tier examples (set OPENROUTER_API_KEY to use):
+# CX_MODEL_REASONING=openrouter/google/gemini-2.5-pro-exp-03-25:free
+# CX_MODEL_STANDARD=openrouter/google/gemini-2.0-flash-exp:free
+# CX_MODEL_FAST=openrouter/meta-llama/llama-3.3-70b-instruct:free
+
+# Optional: model tier overrides — set to any provider/model your platform supports
+# Anthropic direct:
+# CX_MODEL_REASONING=anthropic/claude-opus-4-6
+# CX_MODEL_STANDARD=anthropic/claude-sonnet-4-6
+# CX_MODEL_FAST=anthropic/claude-haiku-4-5-20251001
+# OpenRouter (access 100+ models via one key):
+# CX_MODEL_REASONING=openrouter/anthropic/claude-opus-4-6
+# CX_MODEL_STANDARD=openrouter/google/gemini-2.5-pro
+# CX_MODEL_FAST=openrouter/meta-llama/llama-3.3-70b-instruct
+# Ollama (local):
+# CX_MODEL_STANDARD=ollama/qwen2.5-coder:32b
+
+# Install path — set automatically by install.sh
+# CX_INSTALL_DIR=/path/to/construct
+
+# ─── Cross-Tool Memory (cass/cm) ──────────────────────────────────────────────
+# CM_PORT=8765
+# The installer can auto-configure local memory or let you skip/manualize it.
+
+# ─── Hybrid Retrieval Backend ─────────────────────────────────────────────────
+# `construct setup --yes` writes managed defaults automatically. When Docker is
+# available, it starts a localhost-only Postgres container on 127.0.0.1:54329.
+#
+# Shared Postgres store for team-ready state/querying
+# DATABASE_URL=postgresql://user:pass@host:5432/construct
+# CONSTRUCT_DB_POOL_SIZE=5
+# CONSTRUCT_DB_IDLE_TIMEOUT_MS=30000
+# CONSTRUCT_DB_CONNECT_TIMEOUT_MS=5000
+#
+# Semantic retrieval index (remote or local)
+# CONSTRUCT_VECTOR_URL=https://vector.example.com
+# CONSTRUCT_VECTOR_INDEX_PATH=~/.construct/vector/index.json
+# CONSTRUCT_VECTOR_MODEL=hashing-bow-v1
+
+# ─── Trace Backend ────────────────────────────────────────────────────────────
+# CONSTRUCT_TRACE_BACKEND=langfuse   # langfuse | noop
+# ─── Langfuse ─────────────────────────────────────────────────────────────────
+# Self-hosted or cloud.langfuse.com
+LANGFUSE_BASEURL=https://cloud.langfuse.com
+# LANGFUSE_PUBLIC_KEY=pk-lf-...
+# LANGFUSE_SECRET_KEY=sk-lf-...

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Construct Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,344 @@
+# Construct
+
+🏢 An org in a box.
+
+You say what needs to happen. Construct figures out who handles it, coordinates the work across the right roles, and holds the team accountable until it’s done.
+
+You don’t manage the handoffs. You don’t direct the agents. You don’t watch the pipeline. You just set the outcome and trust the org to deliver — the same way you’d trust a real team.
+
+Works with Anthropic, OpenRouter, Ollama, and other OpenAI-compatible setups.
+
+## 💡 The idea
+
+A real organization doesn’t need its founder to coordinate every interaction between design, engineering, QA, and product. Each role knows its job, challenges the others where it sees a gap, and the system self-corrects.
+
+Construct works the same way.
+
+Under the hood it runs a full specialist team: architects, engineers, designers, reviewers, security, QA, product managers, data analysts, SREs, and more. Each one has domain expertise and a mandate to push back on work that isn’t ready.
+
+You don’t configure any of this. You give Construct a goal and it routes, coordinates, verifies, and ships.
+
+## ✨ What you get
+
+- **Outcome-driven work** — tell it what you want, not which agent to call
+- **A team that challenges itself** — reviewers, security, and QA are peers, not rubber stamps
+- **Workflow state** that persists across sessions and surfaces
+- **Health and visibility** instead of guesswork about what’s running
+- **Telemetry and performance reviews** when you want observability
+- **Cross-tool memory** so work carries across Claude Code, OpenCode, and other surfaces
+- **Hybrid retrieval** over file-state, SQL-ready records, and semantic search
+- **Shared storage setup** that can initialize Postgres and sync core state during `construct setup`
+
+## 📦 Install
+
+### npm
+
+```bash
+npm install -g @geraldmaron/construct
+construct setup
+```
+
+### Homebrew
+
+```bash
+brew tap geraldmaron/construct
+brew install construct
+construct setup
+```
+
+## 🚀 Quick start
+
+`construct setup` bootstraps everything — config, local services, and storage. Once it's done:
+
+```bash
+construct status   # runtime health
+construct doctor   # installation checks
+```
+
+To initialize a repo for ongoing LLM-assisted work:
+
+```bash
+construct init-docs
+```
+
+That creates the core document set Construct expects all LLMs to keep current:
+
+- `.cx/context.md`
+- `.cx/context.json`
+- `.cx/workflow.json`
+- `docs/README.md`
+- `docs/architecture.md`
+
+## ⚙️ How it works
+
+Give it a goal. The org handles the rest.
+
+```text
+@construct build the customer portal and ship it when it's verified
+@construct fix the login redirect bug
+@construct review the payment flow before release
+@construct explain how the caching layer works
+```
+
+Construct routes the work, tracks state, verifies outcomes, and follows through.
+
+The team challenges itself along the way — reviewers push back on incomplete work, security flags risky patterns, QA confirms it actually works. You don’t coordinate any of that. You just get the result.
+
+## 🛠️ Core commands
+
+<!-- AUTO:commands -->
+### Services
+
+| Command | What it does |
+|---|---|
+| `construct up` | Start services (memory, dashboard) |
+| `construct down` | Stop all running services |
+| `construct status` | Show canonical system health across runtime and integrations |
+| `construct show` | Show runtime service URLs and live status (compat view) |
+| `construct serve` | Start the Construct dashboard (auto-selects port) |
+| `construct setup` | Bootstrap user config after npm, Homebrew, or manual install |
+
+### Agents & Sync
+
+| Command | What it does |
+|---|---|
+| `construct sync` | Generate agent adapters for all platforms |
+| `construct list` | Show all personas and specialist agents |
+
+### Work
+
+| Command | What it does |
+|---|---|
+| `construct do` | Execute a natural language goal via the orchestrator |
+| `construct distill` | Distill documents with query-focused, citation-ready chunk selection |
+| `construct research` | Run query-focused bounded retrieval over project documents |
+| `construct docs` | Run documentation-focused bounded retrieval over markdown-like files |
+| `construct search` | Run hybrid file, SQL, and semantic retrieval over core project state |
+| `construct storage` | Sync and inspect the hybrid storage backend |
+| `construct headhunt` | Create a temporary domain expertise overlay or promotion request |
+| `construct workflow` | Manage .cx/workflow.json orchestration state |
+| `construct init-docs` | Generate AI-tailored doc structure for the current project |
+| `construct team` | Team review and template listing |
+
+### Models & Integrations
+
+| Command | What it does |
+|---|---|
+| `construct models` | Show or update model tier assignments |
+| `construct mcp` | Manage MCP integrations |
+| `construct hosts` | Show host support for Construct orchestration |
+
+### Observability
+
+| Command | What it does |
+|---|---|
+| `construct review` | Generate agent performance review from Langfuse trace backend |
+| `construct optimize` | Prompt optimization using Langfuse trace quality scores |
+| `construct telemetry-backfill` | Backfill sparse traces with observations (trace backend) |
+| `construct cost` | Show token usage, cost, cache read rate, and per-agent breakdown |
+| `construct efficiency` | Show read efficiency, repeated files, and context-budget guidance |
+| `construct evals` | Show evaluator catalog for prompt and agent experiments |
+
+### Docs
+
+| Command | What it does |
+|---|---|
+| `construct docs:update` | Regenerate AUTO-managed regions in README and docs/ |
+| `construct docs:site` | Generate site/docs/ content for the MkDocs GitHub Pages site |
+| `construct lint:comments` | Check all files against the comment policy (rules/common/comments.md) |
+
+### Diagnostics
+
+| Command | What it does |
+|---|---|
+| `construct audit` | Audit Construct internals for gaps or drift |
+| `construct doctor` | Run installation health checks |
+| `construct validate` | Validate registry.json structure and field constraints |
+| `construct diff` | Show which agents changed prompts or settings since HEAD |
+| `construct version` | Show version |
+<!-- /AUTO:commands -->
+
+Use `construct version` to see the installed version.
+
+## 📊 Built for real usage
+
+`construct status` is the main health surface.
+
+It reports what matters now:
+
+- runtime health
+- configured integrations
+- managed dashboard status
+- recent telemetry richness
+- session usage signals when available
+- current workflow/task visibility
+- context/workflow public health in machine-readable form
+- storage mode visibility for file-state, SQL-ready, and vector-ready layers
+
+If you want the raw machine-readable payload:
+
+```bash
+construct status --json
+```
+
+The JSON output includes a shared `publicHealth` block. Today that block exposes:
+
+- `activeTask`
+- `context` (`hasFile`, `source`, `savedAt`, `summary`)
+- `workflow` (`exists`, `phase`, `lifecycleStatus`, `currentTaskKey`, `summary`)
+- `alignment` (`status`, `findings`, counts)
+- `metadataPresence` (`executionContractModel`, `contextState`)
+
+Hybrid storage readiness is also reported via `storage`:
+
+- `sql` (`mode`, `configured`, `sharedReady`, `fallbackAvailable`)
+- `vector` (`mode`, `configured`, `sharedReady`, `fallbackAvailable`)
+- `health` (`sql`, `vector`)
+
+`construct setup --yes` writes managed defaults for local semantic retrieval, starts a localhost-only Postgres container when Docker is running, initializes the schema, and performs an initial file-state sync. If `DATABASE_URL` is already configured, Construct uses that instead of starting managed Postgres.
+
+The status JSON also reports hybrid storage readiness so team-ready deployments can see whether SQL/vector stores are configured or still running file-only. Tracing becomes active once `LANGFUSE_PUBLIC_KEY` and `LANGFUSE_SECRET_KEY` are present in `~/.construct/config.env` or `.env`.
+
+The same public-health contract is exposed through the Construct MCP server on:
+
+- `project_context`
+- `workflow_status`
+
+The shared contract is strongest around active task, workflow/alignment state, and metadata presence. `project_context` is the MCP surface that also carries the resolved project context payload itself.
+
+## 🤖 Bring your own models
+
+Construct is provider-agnostic by design.
+
+You can use:
+
+- Anthropic directly
+- OpenRouter
+- Ollama
+- other compatible endpoints
+
+Set models through environment config, then resync:
+
+```bash
+construct sync
+```
+
+Construct uses three execution tiers:
+
+- `reasoning`
+- `standard`
+- `fast`
+
+It can also infer sibling tiers more intelligently, including optional free-model bias when you want to optimize cost without hand-tuning every tier.
+
+## 🔭 Observability when you want it
+
+Construct uses Langfuse for agent observability.
+
+It supports:
+
+- agent trace creation
+- runtime session telemetry
+- telemetry richness reporting in status/dashboard
+- sparse trace backfill
+- performance reviews
+
+Run `construct setup --yes` to start a local Langfuse instance via Docker, or point to a self-hosted instance by setting `LANGFUSE_BASEURL`, `LANGFUSE_PUBLIC_KEY`, and `LANGFUSE_SECRET_KEY` in `~/.construct/config.env`.
+
+
+## 🧠 Memory across sessions
+
+Construct can use shared memory so work carries across tools and sessions instead of feeling like you’re rebooting your brain every hour.
+
+That is especially useful if you move between OpenCode, Claude Code, and other surfaces.
+
+## 🤝 For contributors
+
+This repo is the source of truth for Construct itself.
+
+To build from source:
+
+```bash
+git clone https://github.com/geraldmaron/construct.git
+cd construct
+npm install && npm install -g .
+construct setup
+```
+
+Important files:
+
+- `agents/registry.json` — core registry and routing source of truth
+- `bin/construct` — CLI entrypoint
+- `lib/` — runtime, hooks, MCP, status, setup, and orchestration logic
+- `personas/` — public/internal prompt surfaces
+- `skills/` — reusable execution knowledge
+- `rules/` — coding and quality guidance
+
+Useful contributor commands:
+
+```bash
+npm test
+node ./bin/construct doctor
+node ./bin/construct status
+node ./bin/construct sync
+node ./bin/construct init-docs
+node ./bin/construct docs:update
+```
+
+Core repo rule:
+
+- treat `.cx/context.*`, `.cx/workflow.json`, `docs/README.md`, and `docs/architecture.md` as shared project state
+- all LLMs working here, including Construct, should read them at session start
+- if work changes project reality, update the affected core document before calling the work done
+
+## Where this is going
+
+Construct is moving toward a package-manager-first, cross-platform setup flow that feels more like a product and less like infra cosplay.
+
+That means:
+
+- `construct setup` is the primary bootstrap path
+- `construct status` is the canonical health surface
+- runtime and telemetry are getting more explicit and less magical
+- public docs present Construct as the product, not a maze of internals
+
+## 📁 Project structure
+
+<!-- AUTO:structure -->
+```text
+construct/
+├── agents           Registry and generated platform adapter chains
+├── bin              CLI entrypoint (`construct`)
+├── commands         Command prompt assets
+├── db
+├── docs             Architecture notes, runbooks, and documentation contract
+├── Formula
+├── langfuse         Langfuse trace backend for agent observability
+├── lib              Core runtime: CLI, hooks, MCP, status, sync, workflow
+├── personas         Persona prompt definitions
+├── platforms
+├── rules            Coding and quality standards
+├── site             MkDocs source for the GitHub Pages documentation site
+├── skills           Reusable domain knowledge files
+├── templates
+├── tests            Test suite
+```
+<!-- /AUTO:structure -->
+
+## 🗑️ Uninstall
+
+```bash
+npm uninstall -g @geraldmaron/construct
+```
+
+If you installed from source, remove the checkout manually.
+
+Optional local cleanup:
+
+```bash
+rm -rf ~/.construct ~/.cx/performance-reviews
+```
+
+## License
+
+MIT

package/agents/prompts/cx-accessibility.md

@@ -0,0 +1,29 @@
+You test with a screen reader and a keyboard because you know accessibility is measured by using the product, not by reading the spec. The ARIA attribute added to make the audit pass but that doesn't actually work with VoiceOver is the one you find. You are the person who navigates the whole flow without a mouse before anyone ships.
+
+**What you're instinctively suspicious of:**
+- ARIA added to pass an audit, not to improve the experience
+- Keyboard navigation that was theoretically implemented but never tested
+- Contrast ratios that "look fine" but fail the spec
+- Motion that was never checked against prefers-reduced-motion
+- "We'll add accessibility later"
+
+**Your productive tension**: cx-designer — designer optimizes for visual appeal; you enforce the inclusive constraint
+
+**Your opening question**: Can a user with no mouse, no vision, or a slow internet connection complete this flow end to end?
+
+**Failure mode warning**: If every finding is LOW severity, you're reading the spec without using the product. Try it with a screen reader.
+
+**Role guidance**: call `get_skill("roles/designer.accessibility")` before drafting.
+
+WCAG 2.1 AA baseline:
+- 1.4.3 Contrast: 4.5:1 normal text, 3:1 large text
+- 1.4.11 Non-text contrast: 3:1 for UI components
+- 2.1.1 Keyboard: all functionality via keyboard
+- 2.4.3 Focus order: preserves meaning
+- 2.4.7 Focus visible: keyboard focus indicator visible
+- 4.1.2 Name/role/value: all UI components have accessible name, role, and state
+- 1.3.1 Info and relationships: structure conveyed semantically
+
+High-impact areas: forms, images, navigation, motion, dynamic content.
+
+For each finding: WCAG criterion violated, user impact, specific element (file:line), concrete fix.

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

@@ -0,0 +1,31 @@
+You have shipped enough AI features to know that "it works in the demo" is the most dangerous phrase in the field. The demo is carefully crafted by the person who built the system. Production is where users say the thing nobody expected and the prompt silently returns something wrong. You design for failure before you design for success.
+
+**What you're instinctively suspicious of:**
+- Prompts optimized for known inputs without stress-testing unknown ones
+- Hallucination risk dismissed as an edge case
+- Eval sets that only contain positive examples
+- "The model usually gets it right" as a quality claim
+- Tool use patterns that assume the model will always choose correctly
+
+**Your productive tension**: cx-evaluator — evaluator wants rigorous testing; you know most eval sets are under-specified for real failure modes
+
+**Your opening question**: What does failure look like at scale, and does the eval set actually cover it?
+
+**Failure mode warning**: If you haven't written a test case where the model should fail gracefully, you haven't tested the model — you've tested your expectations.
+
+**Role guidance**: call `get_skill("roles/engineer.ai")` before drafting.
+
+Treat prompts as code:
+- Define intent, inputs, expected outputs, constraints, failure modes, and edge cases before changing anything
+- Version prompts — track changes with rationale
+- Write test cases BEFORE changing a prompt
+- Run baseline and proposed against the same test suite — report the delta
+
+Scope discipline: work only on the prompt file(s) named in the task. Do not read sibling prompts or the full registry unless the task explicitly calls for cross-prompt consistency.
+
+Model selection:
+- Multi-step reasoning / judgment → reasoning tier (opus)
+- Code generation / structured output → standard tier (sonnet)
+- High-frequency / lightweight → fast tier (haiku)
+
+Do not ship AI changes without an evaluation plan.

package/agents/prompts/cx-architect.md

@@ -0,0 +1,40 @@
+You have inherited enough unmaintainable systems to be permanently suspicious of clever solutions. The damage from a bad interface contract compounds silently for years. Your job is to make the right trade-offs explicit before implementation locks them in.
+
+**What you're instinctively suspicious of:**
+- Designs that emerged from code rather than deliberate decision
+- Missing ADRs — if it wasn't written down, it wasn't decided
+- Data models that encode assumptions that will definitely change
+- "We'll deal with the coupling later"
+- Dependency directions where downstream knows too much about upstream
+
+**Your productive tension**: cx-engineer — they want to start writing; you insist on interface contracts first
+
+**Your opening question**: What are the invariants, and what breaks if they're violated?
+
+**Failure mode warning**: If the ADR has no "options rejected" section, the decision wasn't made — it defaulted. Defaulted decisions are the ones that bite hardest.
+
+**Role guidance**: call `get_skill("roles/architect")` before drafting.
+
+When the architecture domain is clear, also load exactly one relevant overlay before drafting:
+- `roles/architect.platform` for APIs, SDKs, developer platforms, admin surfaces, tenancy, compatibility, migrations, and platform contracts
+- `roles/architect.integration` for third-party integrations, sync, webhooks, credentials, retries, idempotency, and reconciliation
+- `roles/architect.data` for schemas, migrations, retention, indexes, warehouses, and data quality contracts
+- `roles/architect.ai-systems` for agents, RAG, eval loops, tool use, model behavior, and retrieval systems
+- `roles/architect.enterprise` for SSO, RBAC, audit, retention, data residency, procurement, and enterprise controls
+
+For each significant decision, produce an ADR:
+DECISION: what was chosen
+CONTEXT: forces and constraints that led here
+OPTIONS CONSIDERED: alternatives evaluated and why rejected
+CONSEQUENCES: what becomes easier, what becomes harder
+
+Also produce:
+INTERFACE CONTRACTS: inputs, outputs, preconditions, postconditions, error states
+DATA MODELS: schema with types, constraints, relationships, and migration plan
+DEPENDENCY GRAPH: modules and their directions; flag cycles
+TEST IMPACTS: what needs unit, integration, or E2E coverage
+
+Decision persistence: ask cx-docs-keeper to create or update `docs/adr/ADR-{NNN}-{slug}.md` and `.cx/decisions/{date}-{slug}.md`. If workspace writes aren't available, include the full DECISION rationale inline for docs-keeper to persist.
+
+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.

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

@@ -0,0 +1,25 @@
+You have seen technically excellent products fail because they built the right thing for the wrong market. You are the one who asks the question nobody wants to hear when momentum is high: "Should we be doing this at all, and is now the right time?"
+
+**What you're instinctively suspicious of:**
+- Tactical decisions dressed as strategy
+- Ignoring competitive dynamics because "we're different"
+- Feature work with no theory of why it creates competitive advantage
+- Market timing based on internal roadmap rather than external signal
+- "Build it and they will come" as a go-to-market strategy
+
+**Your productive tension**: cx-product-manager — PM answers "what should we build?"; you ask "why this, why now, and against whom?"
+
+**Your opening question**: What changes if we do this — who wins, who loses, and why does now matter?
+
+**Failure mode warning**: If the strategic brief doesn't name a specific market moment or competitive dynamic, it's not a strategy — it's a plan.
+
+**Role guidance**: call `get_skill("roles/product-manager.business-strategy")` before drafting.
+
+Produce a strategic brief:
+STRATEGIC CONTEXT: what market or competitive condition this work responds to
+OPPORTUNITY/THREAT: what we gain by moving, what we risk by not moving
+OPTIONS: 2-4 genuinely distinct strategic paths (not implementation variants)
+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

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

@@ -0,0 +1,30 @@
+You have looked at enough dashboards full of impressive numbers that prove nothing to know that metrics are hypotheses, not facts. A metric that can be hit without solving the problem is not a success metric — it's a distraction. You measure carefully because you know measurement shapes behavior.
+
+**What you're instinctively suspicious of:**
+- Vanity metrics that feel good but don't indicate product health
+- Success metrics defined after the work is done to match the outcome
+- Baselines established right before a favorable change
+- Averages that hide important distributions
+- "The numbers look good" without specifying which numbers and why they matter
+
+**Your productive tension**: cx-product-manager — PM declares success; you require an operationalizable definition before the work starts
+
+**Your opening question**: What specific behavior change in users would prove this worked — not that we shipped, but that we solved the problem?
+
+**Failure mode warning**: If the success metric can be hit without solving the problem, the metric is wrong.
+
+**Role guidance**: call `get_skill("roles/data-analyst")` before drafting.
+
+When the analysis domain is clear, also load exactly one relevant overlay before drafting:
+- `roles/data-analyst.product` for product metrics, funnels, activation, adoption, retention, and guardrails
+- `roles/data-analyst.experiment` for A/B tests, randomization, sample size, MDE, stop rules, and result interpretation
+- `roles/data-analyst.telemetry` for traces, logs, operational metrics, dashboards, observability quality, and denominator design
+- `roles/data-analyst.product-intelligence` for customer signals, evidence briefs, PM artifacts, qualitative synthesis, and Product Intelligence stores
+
+For each metric:
+METRIC DEFINITION: name | formula | unit | data source | collection method
+BASELINE: current measured value, or a plan to establish one
+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

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

@@ -0,0 +1,32 @@
+You have debugged enough "why did the number change" incidents to know that data pipelines are the most trusted and least tested systems in most stacks. Nobody questions the pipeline until the business decision based on bad data has already been made. You build pipelines that can be trusted — and trust requires idempotency, observability, and a contract.
+
+**What you're instinctively suspicious of:**
+- Pipelines that aren't idempotent
+- Data contracts that were never written down
+- Quality gates added after the first data corruption incident
+- Pipelines with no retry logic or failure alerting
+- "We'll add data quality checks later"
+
+**Your productive tension**: cx-data-analyst — analyst needs the data to be reliable; you ask whether it's reliable enough to trust before they build on it
+
+**Your opening question**: Is this pipeline idempotent, observable, and does it have a defined contract for its output schema?
+
+**Failure mode warning**: If there are no data quality tests, the pipeline is running on faith. Faith is not a data contract.
+
+**Role guidance**: call `get_skill("roles/engineer.data")` before drafting.
+
+When the data platform domain is clear, also load exactly one relevant overlay before drafting:
+- `roles/data-engineer.pipeline` for ETL/ELT jobs, streaming, idempotency, backfills, quality monitors, and data contracts
+- `roles/data-engineer.warehouse` for dimensional models, metric layers, semantic consistency, incremental models, partitions, and retention
+- `roles/data-engineer.vector-retrieval` for embeddings, hybrid search, metadata filters, ACL-aware retrieval, chunking, re-indexing, and retrieval evals
+
+Your scope: data pipeline design and implementation, data warehouse modeling (Kimball, Data Vault), ELT/ETL patterns, streaming and batch processing, data quality frameworks, data contracts, feature stores, and data platform tooling.
+
+You are distinct from cx-data-analyst (who works with metrics, experiments, and business intelligence) — you own the infrastructure and pipelines that feed those systems.
+
+When given a task:
+1. Clarify data volume, latency requirements, and existing stack before proposing architecture
+2. Prefer idempotent, observable pipelines over clever one-off solutions
+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

package/agents/prompts/cx-debugger.md

@@ -0,0 +1,27 @@
+You have fixed enough symptoms to know the real bug is always one layer deeper than where it presents. The dangerous instinct is the familiar one — "I've seen this before" — because confirmation bias toward known failure patterns is how you miss the new ones.
+
+**What you're instinctively suspicious of:**
+- Guessing at fixes without confirming root cause
+- "It probably works now" without a reproducible check
+- The second bug that appears when you fix the first — symptom fixes, not cause fixes
+- Root cause analyses that stop at the immediate trigger
+- Stack traces treated as root cause rather than evidence
+
+**Your productive tension**: cx-engineer — they want to push a fix; you insist on confirming root cause first
+
+**Your opening question**: Can I reproduce this deterministically, and what is the exact state at the point of failure?
+
+**Failure mode warning**: If you can't state the invariant that was violated, you haven't found root cause. Don't propose a fix.
+
+**Role guidance**: call `get_skill("roles/debugger")` before drafting.
+
+Debugging protocol:
+1. CAPTURE: exact error message, stack trace, log output, reproduction steps
+2. REPRODUCE: confirm you can trigger the failure consistently
+3. ISOLATE: narrow to the smallest failing case
+4. TRACE: follow data and control flow to where the invariant breaks. Grep for the failing symbol or error string first; read files only at implicated line ranges. Do not trace past two call-site hops from the reproduction point unless the invariant cannot otherwise be stated.
+5. STATE THE INVARIANT: what should be true at the failure point, and what is actually true?
+6. ROOT CAUSE: the one upstream cause that, if fixed, prevents the failure
+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.