@geraldmaron/construct 1.2.2 → 1.3.0

package/skills/ai/prompt-optimizer.md

@@ -6,7 +6,7 @@ artifactType: prompt
 ---
 # Prompt Auto-Optimization Loop
 
-Construct's prompt improvement system uses telemetry traces and quality scores as the feedback signal, Claude as the optimizer, and the agent registry (`specialists/registry.json`) as the deployment layer. This is a closed loop: production data → failure analysis → improved prompt → staging → promotion.
+Construct's prompt improvement system uses telemetry traces and quality scores as the feedback signal, Claude as the optimizer, and the modular org registry (`specialists/org/`, assembled at runtime via `loadRegistry()`) as the deployment layer. This is a closed loop: production data → failure analysis → improved prompt → staging → promotion.
 
 ## Running the optimizer
 
@@ -34,7 +34,7 @@ The optimizer requires Python 3.12+ (`pip3` must be available). It will auto-ins
 
 ## Step 1: Gather signal
 
-Retrieve the current production prompt for the target agent from `specialists/registry.json` (or the corresponding `promptFile` if using extracted prompts).
+Retrieve the current production prompt for the target agent from the specialist entry under `specialists/org/specialists/` (or the corresponding `promptFile` if using extracted prompts).
 
 Then retrieve recent traces via the telemetry backend REST API:
 
@@ -76,7 +76,7 @@ Write an improved prompt that directly addresses the diagnosed failures. Rules:
 
 ## Step 4: Push to staging
 
-Update the agent's prompt in `specialists/registry.json` (or the corresponding `promptFile`) with a staging marker comment. Tag the version by writing to `.cx/decisions/prompt-staging-{agent}-{date}.md`.
+Update the agent's prompt in `specialists/org/specialists/<agent>.json` (or the corresponding `promptFile`) with a staging marker comment. Tag the version by writing to `.cx/decisions/prompt-staging-{agent}-{date}.md`.
 
 Log the candidate prompt as a span attribute on a test run batch using `cx_trace`. Tag spans with `promptVersion: staging-{timestamp}` and score them with `cx_score` as traces complete.
 

package/skills/brand/output-vibe.md

@@ -0,0 +1,48 @@
+---
+name: brand-output-vibe
+description: Use when drafting or exporting customer-facing artifacts (PRD, deck, brief, runbook). Sets typography, prose rhythm, sketch diagrams, and export consistency.
+inputs: [artifact-draft, export-target]
+artifactType: style-guide
+---
+
+# Output vibe (construct-modern)
+
+Apply this skill before drafting or exporting any customer-facing artifact (PRD, deck, brief, runbook, video script). User instructions always win; this sets the default feel.
+
+## Typography and color
+
+- Sans: Space Grotesk (400–700). Mono: JetBrains Mono for code, IDs, and tables.
+- Monochrome ink ramp only for page furniture: near-black body (`#23272e`), muted labels (`#565c66`), hairline rules (`#e3e4e8`). Color belongs in diagrams and data, not chrome.
+- Do not stamp "Construct" on external deliverables unless the user asks.
+
+## Prose rhythm
+
+- Lead with a short declarative paragraph, then structure (headings, one compact table, selective bullets).
+- Avoid bullet walls; never more than seven bullets in a row without a prose bridge.
+- Rare em dashes; prefer commas or parentheses.
+
+## Diagrams (sketch-forward)
+
+- Prefer hand-drawn / sketch aesthetic over rigid box-and-arrow clipart.
+- In Mermaid, open with a sketch theme block:
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#fafafa', 'primaryBorderColor': '#565c66', 'lineColor': '#23272e', 'fontFamily': 'Space Grotesk'}}}%%
+flowchart LR
+  User --> Product
+```
+
+- For high-touch user flows, an Excalidraw embed (`*.excalidraw` beside the doc) is acceptable when Mermaid feels too mechanical.
+- Every flowchart shows at least one non-happy path (error, escalation, or rollback).
+
+## Tables and metrics
+
+- Use tables for metrics, acceptance criteria, and comparisons — not for narrative.
+- Pin baselines and targets; cite sources or mark `[unverified]`.
+
+## Export parity
+
+- PDF/HTML/PPTX inherit the same fonts and ink ramp from distribution templates.
+- No stock clip-art icons; use simple line icons or typographic labels.
+
+When invoked at the start of a workflow skill, restate which vibe choices apply to this artifact type in one sentence, then proceed.

package/skills/docs/adr-workflow.md

@@ -30,3 +30,6 @@ Use when: an architectural decision is made that affects the system structure, d
 ## Cross-referencing
 - If this ADR supersedes another: update the old ADR's status field
 - If this ADR depends on another: add a References link
+## Release gate
+
+Run `construct artifact validate <path> --type=<type>` before marking the artifact approved.

package/skills/docs/backlog-proposal-workflow.md

@@ -21,3 +21,6 @@ Use when: product evidence should create or update Jira, Linear, GitHub Issues,
 ## Rules
 
 Never write externally from weak evidence without making the risk explicit. Never create duplicate issues when an existing issue can be updated.
+## Release gate
+
+Run `construct artifact validate <path> --type=<type>` before marking the artifact approved.

package/skills/docs/codebase-research-workflow.md

@@ -5,13 +5,13 @@ inputs: [repository-path]
 artifactType: research-brief
 toneDefault: pedagogical
 toneAllowed: [pedagogical, direct]
-verificationBar: "Every claim cites file:line or command output; no assumed architecture."
+verificationBar: "Every load-bearing claim cites a verifiable primary source; label inference confidence; satisfy template structure requirements."
 ---
 # Codebase Research Workflow
 
 Use when: cx-explorer investigates **this repository** — structure, dependencies, behavior. Not for external vendor research or user interviews.
 
-Call `get_skill("roles/researcher.explorer")` and `get_skill("exploration/repo-map")` before deep dives.
+Call `get_skill("roles/researcher")` and `get_skill("exploration/repo-map")` before deep dives.
 
 ## Steps
 
@@ -38,3 +38,6 @@ Call `get_skill("roles/researcher.explorer")` and `get_skill("exploration/repo-m
 - Every architectural claim traceable to file:line.
 - Unknown paths marked `[unverified]` until read.
 - cx-explorer must **not** answer product prioritization or user preference questions.
+## Release gate
+
+Run `construct artifact validate <path> --type=<type>` before marking the artifact approved.

package/skills/docs/customer-profile-workflow.md

@@ -24,3 +24,6 @@ Profiles are product memory, not CRM records. Keep only information needed for p
 ## Retrieval
 
 Customer profiles are indexed by hybrid retrieval. Future PRDs, PRFAQs, evidence briefs, and backlog proposals should search them before drafting.
+## Release gate
+
+Run `construct artifact validate <path> --type=<type>` before marking the artifact approved.

package/skills/docs/document-ingest-workflow.md

@@ -54,3 +54,6 @@ construct ingest ./data/export.xlsx --out=./notes/export.md
 ## Rules
 
 Do not overwrite an existing markdown artifact unless the user explicitly asks for replacement. Prefer creating a suffixed filename instead. Keep original source files untouched.
+## Release gate
+
+Run `construct artifact validate <path> --type=<type>` before marking the artifact approved.

package/skills/docs/evidence-ingest-workflow.md

@@ -3,7 +3,7 @@ name: docs-evidence-ingest-workflow
 description: "Use when: the user pastes customer notes, Slack threads, support tickets, sales notes, research snippets, RFCs, analytics summaries, or competitor signals."
 inputs: [signal, document]
 artifactType: evidence-brief
-verificationBar: "Every load-bearing claim cites a verifiable source; label inference confidence; satisfy template structure requirements."
+verificationBar: "Observed behavior weighted over self-report; sample size stated; no invented quotes; every load-bearing claim cites a verifiable source."
 ---
 # Evidence Ingest Workflow
 
@@ -34,3 +34,6 @@ Always preserve:
 ## Storage
 
 Files in `.cx/knowledge/` are indexed by Construct's hybrid retrieval path. The vector layer makes them semantically retrievable for future PRDs and Meta PRDs.
+## Release gate
+
+Run `construct artifact validate <path> --type=<type>` before marking the artifact approved.

package/skills/docs/init-project.md

@@ -37,7 +37,7 @@ docs/                   ← human-readable project documentation
 1. Treat `.cx/context.md`, `.cx/context.json`, `.cx/workflow.json`, `docs/README.md`, and `docs/architecture.md` as required project state.
 2. Read them at the start of every meaningful session.
 3. Update them whenever work changes active reality: decisions, workflow phase, architecture assumptions, or documentation contract.
-4. Run `construct dashboard` to see the project in the dashboard.
+4. Run `construct status` to review the project's current state (workflow phase, core docs, uncommitted changes).
 
 ## For cx-docs-keeper
 At session start, check the core docs set. If missing, suggest running `construct init --docs-preset=lean` (or `construct init --docs-preset=full` for the full lane set).

package/skills/docs/prd-workflow.md

@@ -39,7 +39,7 @@ Style constraint: do not produce a wall of bullets. Use paragraphs for reasoning
    | `meta-prd` | `docs/meta-prd/{YYYY-MM-DD}-{slug}.md` |
    | `rfc` | `docs/decisions/rfc/{YYYY-MM-DD}-{slug}.md` |
    | `rfc-platform` | `docs/decisions/rfc/{YYYY-MM-DD}-{slug}.md` |
-5. **cx-devil-advocate** runs the FMEA challenge pass (`roles/reviewer.devil-advocate`) on the draft; highest-RPN failure modes need a mitigation or explicit accept-with-rationale before ship. Their specialist id must appear in `.cx/agent-log.jsonl` (manifest `releaseGate.requiredReviewers` for PRD-family types).
+5. **cx-devil-advocate** runs the FMEA challenge pass (`roles/devil-advocate`) on the draft; highest-RPN failure modes need a mitigation or explicit accept-with-rationale before ship. Their specialist id must appear in `.cx/agent-log.jsonl` (manifest `releaseGate.requiredReviewers` for PRD-family types).
 6. **cx-docs-keeper** updates `.cx/context.md` with a link to the PRD
 
 Run `construct artifact validate <path> --type=<type>` before marking the artifact approved.

package/skills/docs/prfaq-workflow.md

@@ -27,3 +27,6 @@ Use when: the user asks for a PRFAQ, working-backwards doc, launch narrative, or
 ## Approval
 
 Stop before marking a PRFAQ approved or publishing it as a document of record.
+## Release gate
+
+Run `construct artifact validate <path> --type=<type>` before marking the artifact approved.

package/skills/docs/product-intelligence-workflow.md

@@ -2,7 +2,7 @@
 name: docs-product-intelligence-workflow
 description: "Use when: the request involves customer evidence, PM synthesis, product requirements, PRDs, PRFAQs, customer profiles, product signals, or backlog proposals."
 inputs: [signal, evidence-brief]
-artifactType: prd
+artifactType: product-intelligence
 verificationBar: "Every load-bearing claim cites a verifiable source; label inference confidence; satisfy template structure requirements."
 ---
 # Product Intelligence Workflow
@@ -73,3 +73,6 @@ Stop and ask the primary persona before:
 Product Intelligence output must cite evidence, distinguish observation from inference, name confidence, and avoid a wall of bullets. Keep em dashes rare. Use paragraphs for reasoning, tables for comparisons, and bullets for scanability.
 
 For time-sensitive or externally sourced claims, include the date basis. For load-bearing claims, prefer two independent sources unless one authoritative primary source is enough.
+## Release gate
+
+Run `construct artifact validate <path> --type=<type>` before marking the artifact approved.

package/skills/docs/product-signal-workflow.md

@@ -61,3 +61,6 @@ After grouping evidence, check `.cx/knowledge/decisions/strategy/` for any decla
 | PRFAQ | `docs/prfaq/` |
 | Meta PRD | `docs/meta-prd/` |
 | Backlog proposal | pending approval gate: do not file until explicit user approval |
+## Release gate
+
+Run `construct artifact validate <path> --type=<type>` before marking the artifact approved.

package/skills/docs/research-workflow.md

@@ -18,7 +18,14 @@ Follow [rules/common/research.md](../../rules/common/research.md) as the default
 1. **Clarify the question**: one specific, falsifiable question the research must answer.
 2. **Apply recency discipline**: search from the most recent year backward. For fast-moving domains, treat sources older than 12 months as presumptively stale unless confirmed.
 3. **Check internal evidence first**: `.cx/research/`, `.cx/knowledge/`, PRDs, ADRs, runbooks before going external.
-4. **Choose authoritative starting points** (external primary only):
+4. **Choose the tool path by intent, not habit**:
+
+   - Construct itself → `knowledge_search`
+   - Current repo / attached files / ingested artifacts → local evidence first
+   - Library / framework / API / cloud docs → Context7 when available, otherwise web-search and fetch official docs directly
+   - Everything else → domain-primary sources first, web search only as the locator
+
+5. **Choose authoritative starting points** (external primary only):
 
    | Domain | Starting points |
    |---|---|
@@ -28,11 +35,11 @@ Follow [rules/common/research.md](../../rules/common/research.md) as the default
    | Cloud / API / SDK | Official vendor docs for exact version, changelog, migration guide |
    | Regulatory | Primary regulation text, official agency guidance |
 
-5. **Source hierarchy**: primary → secondary → tertiary (tertiary never alone for load-bearing claims).
-6. **Verify every URL** before citing. Mark unconfirmed as `[unverified]`.
-7. **Tone**: resolve from artifact manifest (`direct`). See `specialists/tone-profiles.json`.
-8. **Structure** with `get_template("research-brief")`; write to `.cx/research/{topic-slug}.md`.
-9. **Reference** the research doc in the requesting agent's output.
+6. **Source hierarchy**: primary → secondary → tertiary (tertiary never alone for load-bearing claims).
+7. **Verify every URL** before citing. Mark unconfirmed as `[unverified]`.
+8. **Tone**: resolve from artifact manifest (`direct`). See `specialists/tone-profiles.json`.
+9. **Structure** with `get_template("research-brief")`; write to `.cx/research/{topic-slug}.md`.
+10. **Reference** the research doc in the requesting agent's output.
 
 ## Distribution (publish pipeline)
 

package/skills/docs/runbook-workflow.md

@@ -24,3 +24,6 @@ Use when: creating operational procedures for services, alerts, or recurring ope
 ## Review cadence
 - Runbooks should be tested (table-top or live) at least quarterly
 - Update `Last updated` field after each use or review
+## Release gate
+
+Run `construct artifact validate <path> --type=<type>` before marking the artifact approved.

package/skills/docs/strategy-workflow.md

@@ -36,3 +36,6 @@ Given a product signal or PRD, check:
 |---|---|---|
 | User-global | `~/.cx/strategy.md` | No: local only |
 | Project-local | `.cx/strategy.md` | Yes: source of truth for this repo |
+## Release gate
+
+Run `construct artifact validate <path> --type=<type>` before marking the artifact approved.

package/skills/docs/user-research-workflow.md

@@ -5,13 +5,13 @@ inputs: [user-research, interview-data]
 artifactType: evidence-brief
 toneDefault: pedagogical
 toneAllowed: [pedagogical, direct, friendly]
-verificationBar: "Observed behavior weighted over self-report; sample size stated; no invented quotes."
+verificationBar: "Observed behavior weighted over self-report; sample size stated; no invented quotes; every load-bearing claim cites a verifiable source."
 ---
 # User Research Workflow
 
 Use when: cx-ux-researcher gathers or synthesizes **user** evidence. Do not use for CVE lookups, API version facts, or repo structure — use `docs/research-workflow` (cx-researcher) or `docs/codebase-research-workflow` (cx-explorer) instead.
 
-Follow [rules/common/research.md](../../rules/common/research.md) and call `get_skill("roles/researcher.ux")` before drafting.
+Follow [rules/common/research.md](../../rules/common/research.md) and call `get_skill("roles/ux-researcher")` before drafting.
 
 ## Steps
 
@@ -28,7 +28,7 @@ Follow [rules/common/research.md](../../rules/common/research.md) and call `get_
    | Sales / CS summary | secondary | Trace to underlying tickets when possible |
 
 4. **Sampling**: state segment, N, recruitment method. Behavioral claims need ≥5 per segment unless exploratory (flag as low confidence).
-5. **Validity**: name the weakest validity threat (internal/external/construct/conclusion) per `roles/researcher.ux` — that threat is where the finding is most likely wrong.
+5. **Validity**: name the weakest validity threat (internal/external/construct/conclusion) per `roles/ux-researcher` — that threat is where the finding is most likely wrong.
 6. **Inter-rater reliability**: when themes are coded from qualitative data, two coders code a sample independently; report agreement (or Cohen's κ when N permits). Persistent disagreement means the codebook is unfinished — fix the codebook before shipping themes.
 7. **Tone**: default `pedagogical`; override via `.cx/brand-voice.json` if present.
 8. **Output**: `get_template("evidence-brief")` or `signal-brief` when threshold not met; store under `.cx/knowledge/internal/evidence-briefs/`.
@@ -38,3 +38,6 @@ Follow [rules/common/research.md](../../rules/common/research.md) and call `get_
 - No invented customer names, quotes, or ticket ids.
 - Findings describe problems, not prescribed UI solutions.
 - cx-ux-researcher must **not** cite blog posts for API version or security claims.
+## Release gate
+
+Run `construct artifact validate <path> --type=<type>` before marking the artifact approved.

package/skills/operating/orchestration-reference.md

@@ -118,7 +118,7 @@ If you reason about the same decision across two consecutive turns without a new
 
 ## Speculation rule
 
-When choosing between named options (SDK vs SDK, library vs library, pattern vs pattern), the answer comes from `context7_query-docs`, `WebFetch`, the user, or an explicit default: never from internal reasoning rounds alone.
+When choosing between named options (SDK vs SDK, library vs library, pattern vs pattern), the answer comes from the appropriate evidence path: Context7 for library/framework/API docs when available, direct fetch/search of official docs otherwise, local repo evidence when the question is project-local, the user, or an explicit default. Never from internal reasoning rounds alone.
 
 ## Dispatch-first test
 

package/skills/roles/{engineer.ai.md → ai-engineer.md}

@@ -3,12 +3,12 @@ name: roles-engineer-ai
 description: Surfaces anti-patterns, failure modes, and counter-moves specific to the Engineer — AI role. Use when reviewing or generating work by cx-ai-engineer, or when an agent is acting in the Engineer — AI role.
 inputs: [code-diff, prompt]
 artifactType: role-guidance
-role: engineer.ai
+role: ai-engineer
 applies_to:
   - cx-ai-engineer
 inherits: engineer
 version: 2
-profiles:
+scopes:
   - rnd
 cap: 1
 ---

package/skills/roles/architect.ai-systems.md

@@ -8,7 +8,7 @@ applies_to:
   - cx-architect
 inherits: architect
 version: 2
-profiles:
+scopes:
   - rnd
 cap: 1
 ---

package/skills/roles/architect.data.md

@@ -8,7 +8,7 @@ applies_to:
   - cx-architect
 inherits: architect
 version: 2
-profiles:
+scopes:
   - rnd
 cap: 1
 ---

package/skills/roles/architect.enterprise.md

@@ -8,7 +8,7 @@ applies_to:
   - cx-architect
 inherits: architect
 version: 2
-profiles:
+scopes:
   - rnd
 cap: 1
 ---

package/skills/roles/architect.integration.md

@@ -8,7 +8,7 @@ applies_to:
   - cx-architect
 inherits: architect
 version: 2
-profiles:
+scopes:
   - rnd
 cap: 1
 ---

package/skills/roles/architect.md

@@ -9,7 +9,7 @@ applies_to:
   - cx-rd-lead
 inherits: null
 version: 2
-profiles:
+scopes:
   - rnd
 cap: 1
 ---

package/skills/roles/architect.platform.md

@@ -8,7 +8,7 @@ applies_to:
   - cx-architect
 inherits: architect
 version: 2
-profiles:
+scopes:
   - rnd
 cap: 1
 ---

package/skills/roles/{product-manager.business-strategy.md → business-strategist.md}

@@ -3,12 +3,12 @@ name: roles-product-manager-business-strategy
 description: Surfaces anti-patterns, failure modes, and counter-moves specific to the Product Manager — Business Strategy role. Use when reviewing or generating work by cx-business-strategist, or when an agent is acting in the Product Manager — Business Strategy role.
 inputs: [strategy-doc, competitive-analysis]
 artifactType: guidance
-role: product-manager.business-strategy
+role: business-strategist
 applies_to:
   - cx-business-strategist
-inherits: product-manager
+inherits: null
 version: 2
-profiles:
+scopes:
   - rnd
 cap: 1
 ---

package/skills/roles/data-analyst.experiment.md

@@ -8,7 +8,7 @@ applies_to:
   - cx-data-analyst
 inherits: data-analyst
 version: 2
-profiles:
+scopes:
   - rnd
 cap: 1
 ---

package/skills/roles/data-analyst.md

@@ -8,7 +8,7 @@ applies_to:
   - cx-data-analyst
 inherits: null
 version: 2
-profiles:
+scopes:
   - rnd
 cap: 1
 ---

package/skills/roles/data-analyst.product-intelligence.md

@@ -9,7 +9,7 @@ applies_to:
   - cx-product-manager
 inherits: data-analyst
 version: 2
-profiles:
+scopes:
   - rnd
 cap: 1
 ---

package/skills/roles/data-analyst.product.md

@@ -8,7 +8,7 @@ applies_to:
   - cx-data-analyst
 inherits: data-analyst
 version: 2
-profiles:
+scopes:
   - rnd
 cap: 1
 ---

package/skills/roles/data-analyst.telemetry.md

@@ -9,7 +9,7 @@ applies_to:
   - cx-sre
 inherits: data-analyst
 version: 2
-profiles:
+scopes:
   - rnd
 cap: 1
 ---

package/skills/roles/{engineer.data.md → data-engineer.md}

@@ -3,12 +3,12 @@ name: roles-engineer-data
 description: Surfaces anti-patterns, failure modes, and counter-moves specific to the Engineer — Data role. Use when reviewing or generating work by cx-data-engineer, or when an agent is acting in the Engineer — Data role.
 inputs: [code-diff, data-pipeline]
 artifactType: role-guidance
-role: engineer.data
+role: data-engineer
 applies_to:
   - cx-data-engineer
 inherits: engineer
 version: 2
-profiles:
+scopes:
   - rnd
 cap: 1
 ---

package/skills/roles/data-engineer.pipeline.md

@@ -6,9 +6,9 @@ artifactType: role-guidance
 role: data-engineer.pipeline
 applies_to:
   - cx-data-engineer
-inherits: engineer.data
+inherits: data-engineer
 version: 2
-profiles:
+scopes:
   - rnd
 cap: 1
 ---

package/skills/roles/data-engineer.vector-retrieval.md

@@ -7,9 +7,9 @@ role: data-engineer.vector-retrieval
 applies_to:
   - cx-data-engineer
   - cx-ai-engineer
-inherits: engineer.data
+inherits: data-engineer
 version: 2
-profiles:
+scopes:
   - rnd
 cap: 1
 ---

package/skills/roles/data-engineer.warehouse.md

@@ -6,9 +6,9 @@ artifactType: role-guidance
 role: data-engineer.warehouse
 applies_to:
   - cx-data-engineer
-inherits: engineer.data
+inherits: data-engineer
 version: 2
-profiles:
+scopes:
   - rnd
 cap: 1
 ---

package/skills/roles/debugger.md

@@ -8,7 +8,7 @@ applies_to:
   - cx-debugger
 inherits: null
 version: 2
-profiles:
+scopes:
   - rnd
 cap: 1
 ---

package/skills/roles/designer.accessibility.md

@@ -8,7 +8,7 @@ applies_to:
   - cx-accessibility
 inherits: designer
 version: 2
-profiles:
+scopes:
   - rnd
 cap: 1
 ---

package/skills/roles/designer.md

@@ -9,7 +9,7 @@ applies_to:
   - cx-accessibility
 inherits: null
 version: 2
-profiles:
+scopes:
   - rnd
 cap: 1
 ---

package/skills/roles/{reviewer.devil-advocate.md → devil-advocate.md}

@@ -3,12 +3,12 @@ name: roles-reviewer-devil-advocate
 description: Surfaces anti-patterns, failure modes, and counter-moves specific to the Reviewer — Devil Advocate role. Use when reviewing or generating work by cx-devil-advocate, or when an agent is acting in the Reviewer — Devil Advocate role.
 inputs: [plan, proposal]
 artifactType: guidance
-role: reviewer.devil-advocate
+role: devil-advocate
 applies_to:
   - cx-devil-advocate
 inherits: reviewer
 version: 2
-profiles:
+scopes:
   - rnd
 cap: 1
 ---

package/skills/roles/{operator.docs.md → docs-keeper.md}

@@ -3,12 +3,12 @@ name: roles-operator-docs
 description: Surfaces anti-patterns, failure modes, and counter-moves specific to the Operator — Docs role. Use when reviewing or generating work by cx-docs-keeper, or when an agent is acting in the Operator — Docs role.
 inputs: [docs, runbook]
 artifactType: role-guidance
-role: operator.docs
+role: docs-keeper
 applies_to:
   - cx-docs-keeper
-inherits: operator
+inherits: operations
 version: 2
-profiles:
+scopes:
   - rnd
 cap: 1
 ---

package/skills/roles/engineer.md

@@ -1,17 +1,14 @@
 ---
 name: roles-engineer
-description: Surfaces anti-patterns, failure modes, and counter-moves specific to the Engineer role. Use when reviewing or generating work by cx-engineer, cx-ai-engineer, cx-data-engineer, cx-platform-engineer, or when an agent is acting in the Engineer role.
+description: Surfaces anti-patterns, failure modes, and counter-moves specific to the Engineer role. Use when reviewing or generating work by cx-engineer, or when an agent is acting in the Engineer role.
 inputs: [code-diff, task-context]
 artifactType: role-guidance
 role: engineer
 applies_to:
   - cx-engineer
-  - cx-ai-engineer
-  - cx-data-engineer
-  - cx-platform-engineer
 inherits: null
 version: 2
-profiles:
+scopes:
   - rnd
 cap: 1
 ---
@@ -68,7 +65,7 @@ Load this before drafting. These are the failure modes that separate strong role
 ### 10. Speculating across thinking turns
 **Symptom**: reasoning about which library, pattern, or abstraction to use across multiple thinking turns without reading code, calling docs, or asking.
 **Why it fails**: guesses compound; the eventual choice is made from context the model built about itself, not from the codebase or the library.
-**Counter-move**: two unproductive passes is the cap. Next step is a targeted read, a docs lookup (`context7_query-docs`/`WebFetch`), a NEEDS_MAIN_INPUT packet, or a default with a noted assumption.
+**Counter-move**: two unproductive passes is the cap. Next step is a targeted read, the appropriate docs/evidence lookup path (Context7 for library docs when available, direct official-doc fetch otherwise), a NEEDS_MAIN_INPUT packet, or a default with a noted assumption.
 
 ### 11. Unbounded file reads
 **Symptom**: reading files with large `limit` values without checking size first, or offset reads that fail with "out of range".
@@ -118,4 +115,3 @@ Shortcut: `npm run release:check`.
 **Effective Action**: Before modifying a function, read the full file and grep for callers with `grep -r 'functionName' src/`...
 **Evidence**: Score 0.89, used 8 times, 2 projects
 *Last reinforced: 2026-05-04*
-

package/skills/roles/{reviewer.evaluator.md → evaluator.md}

@@ -3,12 +3,12 @@ name: roles-reviewer-evaluator
 description: Surfaces anti-patterns, failure modes, and counter-moves specific to the Reviewer — Evaluator role. Use when reviewing or generating work by cx-evaluator, or when an agent is acting in the Reviewer — Evaluator role.
 inputs: [model-output, eval-set]
 artifactType: guidance
-role: reviewer.evaluator
+role: evaluator
 applies_to:
   - cx-evaluator
 inherits: reviewer
 version: 2
-profiles:
+scopes:
   - rnd
 cap: 1
 ---

package/skills/roles/{researcher.explorer.md → explorer.md}

@@ -3,12 +3,12 @@ name: roles-researcher-explorer
 description: Surfaces anti-patterns, failure modes, and counter-moves specific to the Researcher — Explorer role. Use when reviewing or generating work by cx-explorer, or when an agent is acting in the Researcher — Explorer role.
 inputs: [repo, task-context]
 artifactType: guidance
-role: researcher.explorer
+role: explorer
 applies_to:
   - cx-explorer
 inherits: researcher
 version: 2
-profiles:
+scopes:
   - rnd
 cap: 1
 ---