# Project subagents

The project-level Claude Code subagents live in `./agents/`. They are intentionally few and have distinct ownership:

| Agent | Purpose | Write access | Default model | Default effort |
| --- | --- | --- | --- | --- |
| `opus-orchestrator` | frames, routes, and accepts verified work | no | Opus | `high` |
| `scout` | maps code and constraints | no | Haiku | `low` |
| `planner` | produces a minimal testable plan | no | Opus | `high` |
| `builder` | implements a named, scoped change | yes | Sonnet | `medium` |
| `lexai-extension-dev` | LexAI-specific implementation (entrypoints, LLM proxy, key handling, selection/replace, Gitea/CWS release) | yes | Sonnet | `medium` |
| `ux-ui-designer` | design specs before user-facing builds; reviews after | `docs/DESIGN_SYSTEM.md` + `docs/design/**` only | Sonnet | `medium` |
| `ux-psychologist` | behavioral-psychology audit of implemented flows; dark-pattern screen | no (findings only) | Sonnet | `medium` |
| `verifier` | independently checks acceptance tests | no direct file tools | Haiku | `low` |
| `critic` | adversarial review for high-risk work | no direct file tools | Opus | `high` |
| `gauntlet-critic` | referees gauntlet rounds: real artifact vs reference bar, fresh eyes every round | no (verdict and gap only) | Opus | `high` |
| `security-auditor` | authn/authz, secrets, injection, deps, attack surface | `docs/attacksurface.md` only | Opus | `high` |
| `learning-steward` | turns proven mistakes into guardrails/evals | only lesson and eval artifacts | Haiku | `low` |
| `system-steward` | improves agents, skills, and role memory from evidence | operating artifacts only | Opus | `medium` |
| `integrator` | combines independent named changes | yes | Sonnet | `medium` |

## Use

Run Opus as the main session when the work needs coordination:

```powershell
claude --agent opus-orchestrator
```

**Effort is a second dial.** `low` · `medium` · `high` · `xhigh` set how much the agent thinks — independent of model tier, and independent of how long its answer runs. Use effort, not model escalation, as the first cost and latency lever; raise it one step at a high-risk gate rather than adding an extra review pass. Keep thinking enabled: it can only be disabled at `high` effort or below, and forcing it off at `xhigh` fails the request. The defaults above are starting points — sweep them on real tasks before trusting them. Full routing rationale lives in `CLAUDE.md` → Model routing.

`opus`, `sonnet`, and `haiku` are version-flexible Claude Code aliases. They resolve to the newest enabled version for the current provider and account; this avoids leaving the project pinned to an obsolete model ID.

For a one-off specialist, invoke it in a normal Claude Code session, for example:

```text
@scout Map the code paths and tests relevant to [task]. Do not modify files.
@builder Implement the approved task contract for [task] in [paths].
@lexai-extension-dev Implement [task] in entrypoints/ respecting the message contract and key-handling rules.
@verifier Verify [task] against these acceptance tests: [tests].
@security-auditor Audit [change/component] for authz, injection, secrets, and attack-surface exposure.
@gauntlet-critic Referee [part] against docs/REFERENCE_BAR.md. Inspect the artifact only; return verdict, biggest gap, evidence, stop signal.
@learning-steward Review this verified failure and decide the smallest durable prevention.
@system-steward Improve the relevant project agent or skill only from this evidence: [evidence].
```

For LexAI code (anything under `entrypoints/` or `src/`), prefer `lexai-extension-dev` over the generic `builder` — it knows the message contract, snapshot pattern, and key-handling rules. Use `builder` for repo-agnostic changes (config, tooling, docs). Use no more than one implementer on the same files. For low-risk, isolated work, use a normal Claude Code session instead of adding coordination overhead. When a unit waits on an owner decision, park only that unit (`docs/PROGRESS.md` → *Waiting on you*) and keep independent lanes moving — at most one agent idles on an answer.

## Memory and skills

Opus, Planner, Builder, UX/UI Designer, UX Psychologist, Verifier, Critic, Learning Steward, Integrator, and System Steward use project-scoped role memory. It is committed under `.claude/agent-memory/` when Claude Code creates it, so the team can review it. Opus also uses Claude Code Auto Memory for session continuity. Shared durable knowledge lives in `docs/MEMORY.md` (see the memory protocol in `CLAUDE.md`); role memory stays role-specific. `gauntlet-critic` is deliberately stateless — no role memory — so every round gets genuinely fresh eyes; durable gauntlet lessons belong to the Learning Steward and `docs/GAUNTLET.md`, never to the referee.

- `/resume-project` rebuilds verified working state after a new session, interruption, or compaction.
- `/memory-sync` consolidates durable knowledge into `docs/MEMORY.md`, dedupes, and enforces context caps (owner: Learning Steward).
- `/design-spec` and `/design-review` bracket every user-facing change (owner: UX/UI Designer).
- `/ux-psych-audit` evaluates implemented journeys through behavioral-psychology lenses — friction, motivation, framing, trust (owner: UX Psychologist).
- `/continuous-improvement` evaluates a proven workflow failure and sends agent/skill improvements to System Steward only when justified.
- `/dev-loop` runs a bounded autonomous maintenance loop (triage → one bounded task → full landing gates → clean stop).
- `/gauntlet-loop` runs reference-benchmarked improvement rounds (concrete bar → build → fresh-eyes referee → close the single biggest gap → repeat until parity, diminishing returns, or budget).
- `/attack-surface` and `/prompt-injection-audit` keep security coverage current; `/self-model-audit` keeps the operator/project model honest.
