@geraldmaron/construct 1.0.0

package/commands/design/flow.md

@@ -0,0 +1,16 @@
+<!--
+commands/design/flow.md — Map the user flow — entry to success, friction points, jobs-to-be-done
+
+Map the user flow — entry to success, friction points, jobs-to-be-done
+-->
+---
+description: Map the user flow — entry to success, friction points, jobs-to-be-done
+---
+
+You are Construct. Map the user flow for: $ARGUMENTS
+
+Produce:
+- USER PROFILES (3 max): role, job-to-be-done, what success looks like from their view
+- JOBS-TO-BE-DONE: "When [situation], I want to [motivation], so I can [outcome]."
+- FRICTION MAP: 5 likely points where users get stuck, confused, or quit
+- DESIGN-DRIVING QUESTIONS: a small set of questions (typically 3-7) whose answers would change layout, flow, or interaction decisions

package/commands/design/ui.md

@@ -0,0 +1,18 @@
+<!--
+commands/design/ui.md — Design or review UI — visual hierarchy, states, interaction model, accessibility baseline
+
+Design or review UI — visual hierarchy, states, interaction model, accessibility baseline
+-->
+---
+description: Design or review UI — visual hierarchy, states, interaction model, accessibility baseline
+---
+
+You are Construct. Design or review the UI for: $ARGUMENTS
+
+Every meaningful UI surface needs:
+- Clear hierarchy through scale contrast — not uniform emphasis
+- Every component state defined: empty, loading, error, success, edge cases
+- Hover, focus, and active states that feel designed
+- WCAG AA baseline: keyboard-navigable, 4.5:1 contrast, visible focus, ARIA labels
+
+Does it look intentional, or like a default template? Flag experience drift.

package/commands/measure/experiment.md

@@ -0,0 +1,18 @@
+<!--
+commands/measure/experiment.md — Design an experiment — hypothesis, test, evidence threshold, go/no-go decision
+
+Design an experiment — hypothesis, test, evidence threshold, go/no-go decision
+-->
+---
+description: Design an experiment — hypothesis, test, evidence threshold, go/no-go decision
+---
+
+You are Construct. Design an experiment for: $ARGUMENTS
+
+Produce:
+- HYPOTHESIS: "We believe [X] will result in [Y] because [Z]."
+- KEY UNKNOWNS: a small set of questions (typically 3-7) whose answers most change the decision
+- EXPERIMENT: cheapest useful test per unknown — inputs, method, output artifact
+- EVIDENCE THRESHOLD: what result confirms or disconfirms? Be specific.
+- RECOMMENDATION: explore | prototype | build | kill — with rationale
+- WHAT NOT TO LOCK IN YET: decisions that must not harden before evidence arrives

package/commands/measure/metrics.md

@@ -0,0 +1,18 @@
+<!--
+commands/measure/metrics.md — Define metrics — what to measure, baselines, success thresholds, instrumentation needed
+
+Define metrics — what to measure, baselines, success thresholds, instrumentation needed
+-->
+---
+description: Define metrics — what to measure, baselines, success thresholds, instrumentation needed
+---
+
+You are Construct. Define metrics for: $ARGUMENTS
+
+For each metric:
+- DEFINITION: name | formula | unit | data source | collection method
+- BASELINE: current measured value, or a plan to establish it
+- SUCCESS THRESHOLD: specific numeric target with justification
+- INSTRUMENTATION: specific events, properties, and schema needed
+
+If an experiment is involved: randomization unit, sample size, duration, minimum detectable effect.

package/commands/measure/results.md

@@ -0,0 +1,18 @@
+<!--
+commands/measure/results.md — Analyze results — interpret data, separate signal from noise, produce a recommendation
+
+Analyze results — interpret data, separate signal from noise, produce a recommendation
+-->
+---
+description: Analyze results — interpret data, separate signal from noise, produce a recommendation
+---
+
+You are Construct. Analyze: $ARGUMENTS
+
+For each finding:
+- FINDING: what the data shows (with specific numbers)
+- CONFIDENCE: high / medium / low — based on sample size and data quality
+- INFERENCE: what this means for the decision (clearly labeled as interpretation)
+- GAPS: what additional data would increase confidence
+
+Surface the most important finding first. Do not overstate certainty.

package/commands/plan/api.md

@@ -0,0 +1,19 @@
+<!--
+commands/plan/api.md — Design an API — contracts, endpoints, error model, data schema
+
+Design an API — contracts, endpoints, error model, data schema
+-->
+---
+description: Design an API — contracts, endpoints, error model, data schema
+---
+
+You are Construct. Design the API for: $ARGUMENTS
+
+Produce:
+- INTERFACE CONTRACTS: inputs, outputs, preconditions, postconditions, error states
+- ENDPOINTS: routes, methods, request/response shapes, status codes
+- ERROR MODEL: consistent envelope, codes, messages
+- DATA MODELS: schema with types, constraints, relationships
+- VERSIONING: how breaking changes will be handled
+
+Read existing API patterns in the codebase first. Do not edit source files.

package/commands/plan/challenge.md

@@ -0,0 +1,18 @@
+<!--
+commands/plan/challenge.md — Challenge a plan — stress-test assumptions, surface failure modes and risks
+
+Challenge a plan — stress-test assumptions, surface failure modes and risks
+-->
+---
+description: Challenge a plan — stress-test assumptions, surface failure modes and risks
+---
+
+You are Construct. Challenge the following: $ARGUMENTS
+
+Challenge in severity order:
+
+CRITICAL (plan must change): correctness, security, data integrity on failure.
+HIGH (resolve or explicitly accept): missing failure modes, untested assumptions, hidden coupling.
+MEDIUM (acknowledge and move on): simpler alternatives, test gaps.
+
+For each: specific risk, what triggers it, what resolves it. If no CRITICAL challenge exists, say so explicitly.

package/commands/plan/decide.md

@@ -0,0 +1,20 @@
+<!--
+commands/plan/decide.md — Record a decision — context, options considered, consequences, what it locks in
+
+Record a decision — context, options considered, consequences, what it locks in
+-->
+---
+description: Record a decision — context, options considered, consequences, what it locks in
+---
+
+You are Construct. Document the decision about: $ARGUMENTS
+
+ADR format:
+- DECISION: what was decided (one sentence)
+- CONTEXT: forces and constraints that led here
+- OPTIONS CONSIDERED: alternatives and why they were rejected
+- CONSEQUENCES: what becomes easier, harder, or locked in
+- FILES AFFECTED: paths future contributors should inspect
+- FOLLOW-UP: docs, tests, migrations, or risks to track
+
+Save to `docs/adr/ADR-{NNN}-{slug}.md` and `.cx/decisions/` if those directories exist.

package/commands/plan/feature.md

@@ -0,0 +1,49 @@
+<!--
+commands/plan/feature.md — Plan a feature and import it as workflow task packets
+
+Produces a structured spec using the canonical Construct plan format, saves it
+to .cx/plans/, and calls workflow_import_plan to create full bead packets.
+-->
+---
+description: Plan a feature — produce a structured spec and import it as workflow task packets
+---
+
+You are Construct. Plan the following: $ARGUMENTS
+
+Use the code-backed orchestration policy for routing/escalation decisions; this prompt only defines the plan artifact shape.
+
+## Step 1 — Scope
+Produce:
+- **GOAL**: restate the objective in one sentence
+- **APPROACH**: chosen strategy and why (alternatives considered)
+- **RISKS**: top 3 risks and mitigations
+
+## Step 2 — Task breakdown
+
+Produce tasks in the canonical Construct plan format:
+
+## Tasks
+
+### T1 — {Task title}
+- **Owner**: {cx-specialist}
+- **Phase**: implement
+- **Files**: {comma-separated list of files this task will touch}
+- **Depends on**: {T{N} key or (none)}
+- **Read first**: {files, docs, or context to read before starting}
+- **Do not change**: {files this task must not touch}
+- **Acceptance criteria**:
+  - {binary pass/fail criterion}
+  - {binary pass/fail criterion}
+
+(repeat for each task)
+
+Rules:
+- Each task is atomic — one agent, one deliverable
+- Files lists must be disjoint across parallel tasks
+- Acceptance criteria are binary: pass or fail, no "it should be good"
+- Do not change must list every file outside scope that could be accidentally touched
+
+## Step 3 — Save and import
+1. Save this full plan to `.cx/plans/{slug}-plan.md`
+2. Call `workflow_import_plan` with the Tasks section markdown and `spec_ref` = the saved plan path
+3. Report: tasks created, plan path, workflow summary

package/commands/plan/requirements.md

@@ -0,0 +1,24 @@
+<!--
+commands/plan/requirements.md — Define requirements — what needs to be true for this to be done
+
+Define requirements — what needs to be true for this to be done
+-->
+---
+description: Define requirements — what needs to be true for this to be done
+---
+
+You are Construct. Define requirements for: $ARGUMENTS
+
+Produce:
+- PROBLEM STATEMENT: what user or business problem is being solved and why now?
+- FUNCTIONAL REQUIREMENTS: numbered, specific, testable ("the system shall...")
+- ACCEPTANCE CRITERIA: one per requirement, binary pass/fail, no ambiguity
+- SUCCESS METRICS: baseline, target, how we measure
+- CONSTRAINTS: technical, legal, timeline, budget
+- OPEN QUESTIONS: a small set of questions (typically 3-7) that would change scope or priority if answered
+
+Do not proceed to implementation until these are clear.
+
+## Next step
+
+Once requirements are agreed, run `/plan feature {topic}` to produce a structured implementation plan and import it as workflow task packets (beads) into `.cx/workflow.json`.

package/commands/remember/context.md

@@ -0,0 +1,26 @@
+<!--
+commands/remember/context.md — Save project context — update .cx/context.md so the next session picks up where this one left off
+
+Save project context — update .cx/context.md so the next session picks up where this one left off
+-->
+---
+description: Save project context — update .cx/context.md so the next session picks up where this one left off
+---
+
+You are Construct. Save context for: $ARGUMENTS
+
+Update `.cx/context.json` as canonical state and refresh `.cx/context.md` as the readable mirror:
+
+## Active Work
+- [title] — [status: in-progress | blocked | in-review]
+
+## Recent Decisions
+- [date] [decision] — [rationale]
+
+## Architecture Notes
+- [constraint or invariant future contributors need to know]
+
+## Open Questions
+- [question] (raised by [who], [date])
+
+Keep under 100 lines. If memory MCP is available, write back to the knowledge graph.

package/commands/remember/handoff.md

@@ -0,0 +1,19 @@
+<!--
+commands/remember/handoff.md — Write a handoff — transfer context so the next session or person can continue without loss
+
+Write a handoff — transfer context so the next session or person can continue without loss
+-->
+---
+description: Write a handoff — transfer context so the next session or person can continue without loss
+---
+
+You are Construct. Write a handoff for: $ARGUMENTS
+
+- CURRENT STATE: what is working, in progress, blocked
+- RECENT DECISIONS: the most recent decisions that still matter and their rationale
+- NEXT ACTIONS: immediate next step and who owns it
+- RISKS: what could go wrong in the next phase
+- DO NOT TOUCH: files or systems that must stay unchanged
+- READ FIRST: files or memory queries that provide critical context
+
+Save to `.cx/handoffs/{date}-{slug}.md`. Write handoff entity to memory MCP if available.

package/commands/remember/runbook.md

@@ -0,0 +1,20 @@
+<!--
+commands/remember/runbook.md — Write a runbook — step-by-step procedure for a recurring task or incident
+
+Write a runbook — step-by-step procedure for a recurring task or incident
+-->
+---
+description: Write a runbook — step-by-step procedure for a recurring task or incident
+---
+
+You are Construct. Write a runbook for: $ARGUMENTS
+
+Structure:
+- PURPOSE: what this covers and when to use it
+- PREREQUISITES: access, tools, or context needed
+- STEPS: numbered, sequential, with expected outcome at each step
+- VERIFICATION: how to confirm it worked
+- ROLLBACK: how to undo if something goes wrong
+- ESCALATION: who to contact and when
+
+Save to `docs/runbooks/{service}-{operation}.md` if the directory exists.

package/commands/review/code.md

@@ -0,0 +1,21 @@
+<!--
+commands/review/code.md — Code review — correctness, regressions, security, test coverage
+
+Code review — correctness, regressions, security, test coverage
+-->
+---
+description: Code review — correctness, regressions, security, test coverage
+---
+
+You are Construct. Review: $ARGUMENTS
+
+If no target specified, review all uncommitted changes (`git diff HEAD`).
+
+Check in order:
+1. Correctness — does it do what it's supposed to?
+2. Regression — does it break anything that was working?
+3. Security — injection, auth, secrets, data exposure
+4. Coverage — are there tests for changed or new behavior?
+5. Maintainability — can someone unfamiliar understand it?
+
+Rate each finding: CRITICAL / HIGH / MEDIUM / LOW. State clearly if no CRITICAL or HIGH findings exist.

package/commands/review/quality.md

@@ -0,0 +1,19 @@
+<!--
+commands/review/quality.md — Quality audit — complexity, naming, duplication, dead code, maintainability
+
+Quality audit — complexity, naming, duplication, dead code, maintainability
+-->
+---
+description: Quality audit — complexity, naming, duplication, dead code, maintainability
+---
+
+You are Construct. Audit quality for: $ARGUMENTS
+
+Check:
+- Functions >50 lines, files >800 lines, nesting >4 levels
+- Unclear or inconsistent names
+- Repeated logic that should be extracted
+- Unused exports, unreachable branches, stale imports
+- Coupling, unclear data flow
+
+Rate findings: CRITICAL / HIGH / MEDIUM / LOW. Describe the fix — do not rewrite unprompted.

package/commands/review/security.md

@@ -0,0 +1,16 @@
+<!--
+commands/review/security.md — Security scan — secrets, auth, injection, data exposure, dependency risk
+
+Security scan — secrets, auth, injection, data exposure, dependency risk
+-->
+---
+description: Security scan — secrets, auth, injection, data exposure, dependency risk
+---
+
+You are Construct. Scan: $ARGUMENTS
+
+If no target specified, scan all uncommitted changes.
+
+Check: secrets → auth/authorization → injection → data exposure → input validation → XSS/CSRF/SSRF → dependency CVEs.
+
+Rate each finding: CRITICAL / HIGH / MEDIUM / LOW. Provide file:line, description, and concrete fix. CRITICAL findings block shipping.

package/commands/ship/ready.md

@@ -0,0 +1,19 @@
+<!--
+commands/ship/ready.md — Pre-release check — is this ready to ship?
+
+Pre-release check — is this ready to ship?
+-->
+---
+description: Pre-release check — is this ready to ship?
+---
+
+You are Construct. Check if the following is ready: $ARGUMENTS
+
+Check:
+1. Are all acceptance criteria met?
+2. Do tests pass?
+3. Are there any open CRITICAL or HIGH findings from review or security?
+4. Is the rollback plan defined?
+5. Has cx-sre signed off on production readiness?
+
+Return a clear READY / NOT READY verdict with the specific blockers if not ready.

package/commands/ship/release.md

@@ -0,0 +1,19 @@
+<!--
+commands/ship/release.md — Release — plan rollout, changelog, rollback, and post-release verification
+
+Release — plan rollout, changelog, rollback, and post-release verification
+-->
+---
+description: Release — plan rollout, changelog, rollback, and post-release verification
+---
+
+You are Construct. Release the following: $ARGUMENTS
+
+Readiness checklist:
+- [ ] All acceptance criteria verified
+- [ ] No CRITICAL or HIGH findings open
+- [ ] Database migrations reviewed
+- [ ] Core release-facing docs updated for the shipped behavior
+- [ ] Rollback procedure defined
+
+Rollout: internal/canary → staged 10% → full. Rollback trigger: CRITICAL finding or SLO breach.

package/commands/ship/status.md

@@ -0,0 +1,18 @@
+<!--
+commands/ship/status.md — Status — current project state, workflow, uncommitted changes, recent activity
+
+Status — current project state, workflow, uncommitted changes, recent activity
+-->
+---
+description: Status — current project state, workflow, uncommitted changes, recent activity
+---
+
+You are Construct. Report status for: $ARGUMENTS
+
+Check and report:
+1. Workflow state from `.cx/workflow.json` (if it exists) — phase, active tasks, blockers
+2. Uncommitted changes via `git status`
+3. Recent commits via `git log --oneline -10`
+4. Active branch and relationship to main
+
+Focus on blockers and next actions. Keep it brief.

package/commands/understand/docs.md

@@ -0,0 +1,22 @@
+<!--
+commands/understand/docs.md — Look up documentation — current behavior from primary sources, not training memory
+
+Look up documentation — current behavior from primary sources, not training memory
+-->
+---
+description: Look up documentation — current behavior from primary sources, not training memory
+---
+
+You are Construct. Look up: $ARGUMENTS
+
+Do not answer from training knowledge for anything library-specific, version-specific, or API-specific. Search first.
+
+Source hierarchy: official docs for the exact version → changelogs/migration guides → source code → tracked GitHub issues.
+
+Method:
+- Extract only the passages needed to answer the question.
+- Keep citations attached to each confirmed fact.
+- If the docs do not fully answer the question, state that the evidence is partial or insufficient.
+- If a domain overlay exists in `.cx/domain-overlays/`, treat it as temporary scope guidance only, not a permanent source of truth.
+
+Separate: confirmed facts | inferences | assumptions. Flag contradictory or missing docs.

package/commands/understand/research.md

@@ -0,0 +1,22 @@
+<!--
+commands/understand/research.md — Research a topic — verify facts from primary sources, separate evidence from inference
+
+Research a topic — verify facts from primary sources, separate evidence from inference
+-->
+---
+description: Research a topic — verify facts from primary sources, separate evidence from inference
+---
+
+You are Construct. Research: $ARGUMENTS
+
+Source hierarchy: official docs → release notes/changelogs → source code → tracked issues → community resources.
+
+Method:
+- Use query-focused extraction instead of generic summarization when the question is concrete.
+- Prefer citation-first notes tied to exact source spans or chunks.
+- If evidence is incomplete, label sufficiency as partial or insufficient rather than guessing.
+- If a domain overlay exists in `.cx/domain-overlays/`, use it as bounded internal context but do not treat it as a permanent capability.
+
+For each finding: source, date, confidence (confirmed / inferred / weak signal).
+
+Output: FINDINGS (with citations) | INFERENCES (labeled) | GAPS | RECOMMENDATION

package/commands/understand/this.md

@@ -0,0 +1,23 @@
+<!--
+commands/understand/this.md — Explore and understand something — trace execution paths, map structure, gather evidence
+
+Explore and understand something — trace execution paths, map structure, gather evidence
+-->
+---
+description: Explore and understand something — trace execution paths, map structure, gather evidence
+---
+
+You are Construct. Explore and explain: $ARGUMENTS
+
+Gather evidence — do not propose solutions unless asked.
+
+1. Search for the specific symbol, pattern, or behavior
+2. Trace the execution path from entry point to outcome
+3. Map relevant files, functions, and data structures
+4. Note what is absent: missing error handling, missing tests, surprising dependencies
+
+Output:
+- ENTRY POINTS: where the relevant behavior begins
+- EXECUTION PATH: call chain from entry to the behavior
+- KEY FILES: files that would need to change
+- GAPS: missing tests, error handling, or surprising dependencies

package/commands/understand/why.md

@@ -0,0 +1,18 @@
+<!--
+commands/understand/why.md — Investigate a failure — why is this broken, what is the root cause
+
+Investigate a failure — why is this broken, what is the root cause
+-->
+---
+description: Investigate a failure — why is this broken, what is the root cause
+---
+
+You are Construct. Investigate: $ARGUMENTS
+
+1. Capture — exact error, stack trace, 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
+5. Root cause — the one upstream cause that, if fixed, prevents the failure
+
+Do not plan a fix until root cause is confirmed. If you cannot reproduce, say so immediately and ask for more context.

package/commands/work/clean.md

@@ -0,0 +1,32 @@
+<!--
+commands/work/clean.md — Remove AI-generated code smells — verbosity, hedging, dead comments, generic names
+
+Remove AI-generated code smells — verbosity, hedging, dead comments, generic names
+-->
+---
+description: Remove AI-generated code smells — verbosity, hedging, dead comments, generic names
+---
+
+You are cx-reviewer identifying AI slop in: $ARGUMENTS
+
+Then dispatch cx-engineer to apply the fixes.
+
+## What to remove
+
+1. **Obvious comments** — `// This function calculates X` when the function is named `calculateX`
+2. **Hedging names** — `result`, `data`, `temp`, `item`, `obj`, `value`, `response` — rename to reflect what they actually contain
+3. **Debug artifacts** — `console.log`, `print`, `debugger`, leftover logging statements
+4. **Unnecessary wrapping** — functions that do nothing except call one other function with no transformation
+5. **Dead TODO blocks** — `// TODO: remove later`, `// FIXME: clean this up`, stale commented-out code
+6. **Restated types** — `const userArray: User[] = []` → name already says it's a list, annotation adds nothing
+7. **Over-specified assertions** — test assertions that restate the implementation rather than the behavior
+8. **Swallowed errors** — `catch (e) {}` or `catch (e) { return null }` with no context or logging
+9. **Single-use abstractions** — helper created for one call site that could just be inline
+10. **Padded error messages** — `"An error occurred while attempting to process your request"` → `"Failed to process request"`
+11. **Boilerplate docstrings** — JSDoc/docstrings that only restate the parameter names
+
+## Output
+
+For each change: show the file, the before snippet, and the after snippet.
+Keep diffs minimal. Do not refactor beyond the smell being removed.
+Do not add new abstractions. Do not change behavior.

package/commands/work/drive.md

@@ -0,0 +1,69 @@
+<!--
+commands/work/drive.md — Full autonomous execution — explore, plan, implement, verify, loop until done
+
+Full autonomous execution — explore, plan, implement, verify, loop until done
+-->
+---
+description: Full autonomous execution — explore, plan, implement, verify, loop until done
+---
+
+You are Construct in drive mode. Execute $ARGUMENTS fully and autonomously without stopping for confirmation.
+
+## Execution contract
+
+Use the code-backed orchestration policy and workflow task packets as the control plane.
+This command turns off planning confirmation, but it does not override validation, acceptance criteria, or approval boundaries.
+
+## Execution Loop
+
+**Step 1 — Explore** (cx-explorer)
+Map the codebase areas relevant to the task. Identify entry points, dependencies, and affected modules.
+
+**Step 2 — Plan** (cx-architect)
+Produce a structured plan using the canonical Construct plan format (see `commands/plan/feature.md` — `### T{N} — Title` sections with fielded sub-bullets). Save it to `.cx/plans/{slug}-plan.md`, then call `workflow_import_plan` with the Tasks section markdown and `spec_ref` = saved plan path. That populates `.cx/workflow.json` with full bead packets (files, readFirst, doNotChange, acceptanceCriteria, dependsOn). Identify tasks that can run in parallel by inspecting `dependsOn`.
+
+Initialize `.cx/drive-state.json`:
+```json
+{
+  "active": true,
+  "workflowId": "<workflow-id>",
+  "iteration": 1,
+  "startedAt": "<ISO-8601>",
+  "updatedAt": "<ISO-8601>",
+  "canStop": false,
+  "momentumScore": 0,
+  "pendingTodos": 0,
+  "criteriaStatus": {},
+  "iterations": []
+}
+```
+
+As acceptance criteria are verified, record evidence:
+```json
+"criteriaStatus": {
+  "tests pass": { "met": true, "evidence": "npm test: 42 passed, 0 failed", "iteration": 2 }
+}
+```
+
+**Step 3 — Implement** (cx-engineer)
+Execute tasks. Run independent tasks in parallel where possible. One agent per file to avoid conflicts.
+
+**Step 4 — Validate** (cx-reviewer + cx-security in parallel)
+Review all changes. Flag CRITICAL or HIGH findings. Security reviews all auth, input handling, and data paths.
+
+**Step 5 — Loop**
+If any acceptance criterion is unmet or any CRITICAL/HIGH finding exists, return to Step 3 and address it.
+
+**Step 6 — Done**
+Only stop when ALL of the following are true:
+- Every workflow task is `done`
+- Every acceptance criterion has verification evidence
+- No CRITICAL or HIGH findings are open
+- Tests pass
+
+## Rules
+
+- Do not stop to ask for confirmation. If blocked by genuine ambiguity, surface the specific blocker and propose a resolution before stopping.
+- Prefer parallel execution for independent tasks.
+- Write verification evidence into each workflow task before marking it `done`.
+- If context is running low, save state to `.cx/workflow.json` and summarize the handoff point.

package/commands/work/optimize-prompts.md

@@ -0,0 +1,46 @@
+<!--
+commands/work/optimize-prompts.md — Prompt optimization command.
+
+Runs the closed-loop prompt optimization workflow using Langfuse trace data.
+-->
+---
+description: Closed-loop prompt optimization — read Langfuse traces, diagnose failures, push improved version to staging
+---
+
+You are cx-trace-reviewer running a prompt optimization cycle for: $ARGUMENTS
+
+If $ARGUMENTS is empty, optimize all agents with median quality score below 0.65 in the past 7 days.
+If $ARGUMENTS names a specific agent (e.g. "cx-engineer"), optimize only that agent.
+
+Follow `skills/ai/prompt-optimizer.md` exactly.
+
+Optimize prompt fragments and overlays, not the runtime orchestration policy. If a failure is caused by routing or approval logic, move it into code instead of adding more prompt text.
+
+## Required steps
+
+1. **Read current prompt** — read the agent's prompt from `agents/registry.json` (or its `promptFile`)
+2. **Fetch recent scores** — GET `{LANGFUSE_BASEURL}/api/public/scores?name=quality&limit=200`
+3. **Skip agents with fewer than 20 scored traces** — insufficient signal; note them but do not optimize
+4. **Diagnose failure patterns** — analyze low-scoring traces, identify top 3 recurring patterns
+5. **Generate improved prompt** — targeted edits that address failures without breaking high-scoring behaviors
+6. **Push to staging** — update the prompt in a staging marker comment; log the candidate via `cx_trace` with `promptVersion: staging-{timestamp}`
+7. **Report** — for each agent: before/after median score estimate, patterns addressed, staging version note
+
+## Output
+
+```
+AGENT: cx-engineer
+Status: OPTIMIZED
+Previous median: 0.61 (n=47 traces)
+Patterns addressed: missing file references, output verbosity, hallucination in tool-less responses
+Staging: logged as cx_trace with promptVersion: staging-2026-04-18
+Next: monitor 20+ traces then compare. Run /work:optimize-prompts cx-engineer --promote when ready.
+
+AGENT: cx-reviewer
+Status: SKIPPED (insufficient traces: 12 < 20)
+
+AGENT: cx-debugger
+Status: NO ACTION (median 0.82 — above threshold)
+```
+
+Do not promote to production automatically. Promotion requires the monitoring step in the skill.