LexAI/_to_delete/opusflip-20260807/AGENTS.md

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
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:

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:

@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 with weight, evidence, and other defects.
@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.