Add a custom specialist

You want a cx-performance-auditor for your project (or any other specialist that doesn't ship in the default 28). This walks the full flow: registry entry, prompt, model tier, contract wiring, sync to every editor, smoke test.

The shape of a specialist

Every specialist has four pieces:

1. An entry in specialists/org: declares name, role, model tier, capability list, and (optionally) skills allowlist.
2. A prompt file at specialists/prompts/cx-<name>.md: defines the specialist's voice, decision authority, and operating boundaries.
3. (Optional) An entry in specialists/contracts.json: typed input/output for handoffs from other specialists.
4. (Optional) A role manifest entry in specialists/role-manifests.json: for personas that should also operate as an organizational role (with fences, allowed bd labels, event ownership).

For a basic specialist, only the first two are required.

Step 1: Add the registry entry

Open specialists/org and add an object to the agents array:

{
  "name": "performance-auditor",
  "role": "Performance and resource-efficiency specialist",
  "model_tier": "reasoning",
  "description": "Identifies hotspots, suggests optimizations, validates with measurements. Pushes back when an apparent fix masks a real cost.",
  "promptFile": "specialists/prompts/cx-performance-auditor.md",
  "platforms": ["claude", "opencode", "codex"]
}

Field notes:

• name: without the cx- prefix. The prefix is added automatically when adapters are generated.
• role: a one-line role definition. This is what other specialists see when they consider whether to route work to you.
• model_tier: reasoning (deep, slow), standard (everyday), or fast (cheap, quick lookups). The tier→model mapping lives in models at the top of registry.json and can be remapped per-project.
• platforms: optional allowlist. Omit to mirror to every editor. Use to scope a specialist to a subset of surfaces.

Step 2: Write the prompt

Create specialists/prompts/cx-performance-auditor.md. The prompt is the specialist's full operating instructions. Look at specialists/prompts/cx-engineer.md or cx-security.md for shape.

Minimum structure:

# cx-performance-auditor

You are the performance and resource-efficiency specialist on the Construct team.

## What you own

- Hotspot detection in CPU, memory, and IO paths
- Validating optimization claims with measurements, not intuition
- Pushing back when a fix masks a deeper cost

## How you decide

- When asked for an opinion, lead with the measurement that would change your mind.
- When asked to optimize, ask for a baseline benchmark before suggesting changes.
- When you see a fix that doesn't validate against a benchmark, flag it as `next:cx-reviewer` for empirical confirmation.

## How you talk

Direct. Numeric. Skeptical of plausible-sounding explanations.

## When the role framework dispatches you

You receive `next:cx-performance-auditor` handoffs from any specialist. Read the originating context, identify the smallest meaningful measurement, and report findings + a recommended next action (continue, escalate, defer).

The prompt is the most consequential file. Iterate on it. Test by addressing the specialist directly in your editor: @cx-performance-auditor look at lib/storage/sync.mjs and flag perf risks.

Step 3: Sync to every editor

construct sync

This writes the adapter files into every installed editor's expected location:

• ~/.claude/agents/cx-performance-auditor.md
• ~/.config/opencode/opencode.json (entry added)
• ~/.codex/agents/cx-performance-auditor.toml

Verify with cross-surface parity:

construct doctor
# expect: Cross-surface adapter parity (claude: ok (N/N) · opencode: ok (N/N) · codex: ok (N/N))

Drift (e.g., one surface missing the new specialist) means sync didn't reach that adapter: usually a permissions issue or the editor's config dir doesn't exist yet.

Step 4: Smoke test

Open your editor and address the new specialist directly:

@cx-performance-auditor what's the worst-case latency for the embedding pipeline?

If you get a reasonable response, the prompt is doing its job.

For the routing test: ask construct (the persona) something performance-shaped:

@construct review lib/storage/vector-client.mjs for performance risks.

construct should consider the specialist chain and dispatch to cx-performance-auditor. If the orchestration policy doesn't route to your specialist, check the prompt's "What you own" section: that's the signal Construct uses for routing.

(Optional) Step 5: Add contracts and role manifest

If your specialist needs to receive structured handoffs from other specialists, add entries to:

• specialists/contracts.json: declares producer → consumer contracts with required input fields and postconditions. See existing contracts for shape.
• specialists/role-manifests.json: declares the role's fence (allowed paths, allowed bd labels), event ownership (which events route to this role), and approval-required actions.

These are required for the role framework to dispatch your specialist on event-driven triggers (e.g., a perf.regression event auto-routing to cx-performance-auditor). For a specialist that's only addressed by name, you can skip.

Common gotchas

• Specialist name conflicts with a built-in. If you try cx-engineer (already exists), construct sync will either reject or merge silently depending on the registry config. Pick a name that doesn't collide.
• Prompt is too vague. A specialist that doesn't push back on bad ideas isn't pulling its weight. The prompt should encode a specific point of view.
• Wrong model tier. A reasoning specialist used for everyday quick checks burns cost. A fast specialist used for architectural decisions misses nuance. Pick the tier that matches the work.
• Skills allowlist mismatch. If your specialist needs lib/skills/<skill> access, declare it in the registry entry or the specialist will skip the skill.

Reference

• Specialist registry source: specialists/org
• Prompt examples: specialists/prompts/
• Contract definitions: specialists/contracts.json
• Concepts → Agents and personas: the model behind one-persona, many-specialists.