# Agent Registry

Quick-reference for all custom agents. Use this to route tasks to the right specialist.

**Location**: `.claude/agents/<name>.md` | **Invoke via**: `Task` tool with `subagent_type="<name>"`

> **Machine-readable source of truth (since v3.20.0)**: the filesystem directory `framework/.claude/agents/` is authoritative for the list of BALDART agents. The `agent-discovery-gate.js` PreToolUse hook, the `agent-discovery-info.sh` SessionStart hook, and `baldart doctor` enumerate the directory directly (every `<name>.md` except this file is an agent — no manifest JSON is shipped). Adding a new agent means dropping `<name>.md` here; no other touchpoint.

## Agent Map

| Agent | Category | When to Use | Specialization | Can Edit Code | Key Tools |
|-------|----------|-------------|----------------|---------------|-----------|
| **codebase-architect** | Architecture | **MANDATORY** before planning/implementing changes | Platform analysis, system design, canonical-source resolution via Linking Protocol v1, LSP symbol resolution (when `features.has_lsp_layer: true`), code-graph structural queries (when `features.has_code_graph: true`) | No | Code navigation, pattern tracing, LSP find-references / go-to-definition, Graphify query/path/affected |
| **plan-auditor** | Architecture | Review implementation plans before coding begins | Risk assessment, gap detection | Yes | Multi-persona review (eng/security/SRE) |
| **doc-reviewer** | Architecture | Audit/write docs after feature implementation | Macro feature identification, SSOT sync, linking-protocol resolution, doc debt tracking, gap analysis | Yes | Doc writing, TaskCreate (doc debt), token optimization |
| **wiki-curator** | Documentation | Maintain the derived LLM wiki overlay under `${paths.wiki_dir}/` (concept pages, syntheses, dashboards, reading guides) without creating new canonicals. See `agents/llm-wiki-methodology.md`. | Synthesis candidates (from ADRs/PRDs + Graphify GRAPH_REPORT.md when `features.has_code_graph: true`), provenance hygiene, freshness, anchor + frontmatter validation | Yes | `${paths.wiki_dir}/`, wiki lint |
| **doc-graph-aligner** | Documentation | Align docs with real code structure via the Graphify code graph (nightly `doc-graph-align` routine + `/graph-align` skill). Gated on `features.has_code_graph`. | Uncovered core code (god nodes/communities), stale-doc detection, registry drift; proposes synthesis candidates (never authors canonicals). | No (propose-only — hands drift to `doc-reviewer`) | `graphify update/query/path/affected`, GRAPH_REPORT.md |
| **coder** | Code | Write, modify, or refactor production code | Features, bugs, optimizations | Yes | Build tools, testing, Playwright |
| **code-reviewer** | Code | Review code post-implementation for bugs/quality | Security analysis, code quality, registry-first UI compliance (when `features.has_design_system: true`) — flags re-implemented primitives and bypassed tokens as HIGH per `framework/agents/design-system-protocol.md`. NOT a visual-design evaluator (that is `ui-expert` / `visual-fidelity-verifier`). | No (review-only role — emits findings; fixes are applied by `coder`. The `bypassPermissions` tool-mode all agents run under is execution access, not an implementer role) | Static analysis, security audit |
| **security-reviewer** | Code | Review security-sensitive code, configs, auth, secrets, and infra changes | AppSec audit, threat modeling, hardening guidance | No | Security review, trust-boundary analysis |
| **qa-sentinel** | QA | **Mechanical gate runner** — lint, typecheck, test suite, build, security audit, markdownlint. Returns PASS/FAIL verdict only. Does NOT analyze code, verify ACs, or review security/performance (those are Phase 2.5 and code-reviewer responsibilities). | Gate execution, verdicts | No (reports failures, coder fixes) | ESLint, tsc, node --test, npm run build, npm audit, markdownlint |
| **hybrid-ml-architect** | ML | Design/implement ML systems end-to-end | Recommender, ranking, embeddings | Yes | Model design, evaluation, monitoring |
| **ui-expert** | Design | Design, implement, and review UI/UX | Mobile-first, accessibility, registry-first protocol gate (when `features.has_design_system: true`) — BLOCKING reads on `${paths.design_system}/INDEX.md` + `tokens-reference.md` + `components/<Name>.md` per `framework/agents/design-system-protocol.md`, Component Discovery cascade before any design | Yes (generates UI / HTML mockups in `ui-design` Step C; a separate fresh instance acts as design-quality evaluator in Step D) | ui-ux-pro-max, Playwright |
| **visual-fidelity-verifier** | Design | Compare an implemented UI route against its mockup (or design-system spec) and return a severity-tagged JSON report. Auto-invoked by `/e2e-review` skill (Phase 4) — never spawned ad-hoc. Stateless. Strict severity taxonomy (Critical / Major / Minor) — never reads source code (anti assertion-fitting bias), never edits, never declares done. | Visual diff, severity taxonomy, design-system compliance check via registry cascade | No | Vision (multimodal), Read (screenshots + registry only), Playwright screenshots passed in by orchestrator |
| **visual-designer** | Design | Generate visual assets via Kie.ai | Illustrations, icons, hero images | Yes | Kie.ai API, WebP optimization |
| **motion-expert** | Design | Design animations and micro-interactions | Transitions, timing, easing | No | Animation specs, a11y fallbacks |
| **hyper-gamification-designer** | Design | Analyze game features and retention mechanics | Progression, reward loops | No | MDA analysis, economy balance |
| **remotion-animator-orchestrator** | Design | Create Remotion video animations | Motion graphics, asset coordination | Yes | Remotion, visual agent coordination |
| **prd** | Product | Create PRDs, plans, and backlog cards | Requirements, execution planning | No | PRD writing, backlog management |
| **prd-card-writer** | Product | Generate atomic backlog cards from approved PRD | Card YAML, traceability, parallel groups | Yes | Backlog writing, dependency analysis |
| **onboarding-architect-lead** | Product | Design/improve user onboarding experiences | Activation flows, experiments | No | Onboarding research, metrics |
| **website-orchestrator** | Product | Coordinate multi-agent website development | Project orchestration | No | Phase management, quality gates |
| **senior-researcher** | Research | Comprehensive research on technical topics | Evidence-based analysis | Yes | Web search, citations |
| **marketing-conversion-strategist** | Marketing | Create high-converting copy and messaging | Positioning, CTAs, copy | No | Business interview, copywriting |
| **seo-analytics-strategist** | Marketing | Define SEO strategy, metadata, analytics | GA4/GTM, schema markup | No | Keyword research, event planning |
| **api-perf-cost-auditor** | DevOps | Analyze APIs for performance/cost bottlenecks | Backend optimization, scaling | No | Bottleneck detection, cost analysis |
| **legal-counsel-gdpr** | Legal | GDPR compliance, privacy, data governance | EU/IT privacy law, DPA/DPIA | Yes | Policy writing, consent mechanisms |
| **email-deliverability-architect** | Email | Design/write/review transactional & informational emails | Deliverability, spam avoidance, SPF/DKIM/DMARC | No | Spam risk scoring, compliance audit |
| **deep-human-insight** | Research | Analyze psychological, sociological, and behavioral dynamics behind customer/user decisions | Identity, status, trust, friction, dark patterns, segment psychology | No | Multi-layered interpretation, ethical checks |
| **skill-improver** | Infrastructure | Weekly skill improvement based on accumulated review findings and QA results | Pattern detection, skill/agent file refinement, AGENTS.md tuning | Yes | `.claude/skills/`, `.claude/agents/`, `AGENTS.md`, `docs/` (never application code) |

## Decision Tree

> **Note**: when invoked from the `/new` skill, agent assignment is NOT taken
> from this tree — `/new` reads `owner_agent` directly from each card YAML.
> The valid values are the **`owner_agent` enum** defined below (this file is
> the SSOT). This tree is the source for HUMAN routing (when spawning an agent
> ad-hoc) and for prd-card-writer's WRITING decisions. If you change agent
> capabilities here, keep the `owner_agent enum` (below) and the router in
> `framework/.claude/skills/new/SKILL.md` § Agent Routing in lockstep —
> drift between layers silently mis-routes cards.

### owner_agent enum (machine-readable SSOT)

The only legal `owner_agent` values on a backlog card. `card-template.yml`,
`backlog-phase.md`, and `prd.md` MUST reference this list (do not re-list the
enum inline, do not cite a YAML comment line number):

```
owner_agent enum:
  - coder
  - ui-expert
  - plan
  - visual-designer
  - motion-expert
```

(`plan` denotes a planning/analysis card owned by the `prd`/`plan-auditor`
flow rather than an implementer; adding a new implementer agent means adding
it here and to the `/new` router in the same change.)

### card status enum (machine-readable SSOT)

The only legal backlog-card `status` values and their lifecycle. Producers
(`prd-card-writer`, `card-template.yml`, `epic-template.yml`) and consumers
(`/new`) MUST reference this list — do not define the vocabulary elsewhere:

```
status enum:
  - TODO          # created, not started (the only value producers emit)
  - READY         # dependencies met, eligible to start (optional scheduler state)
  - IN_PROGRESS   # claimed by /new
  - BLOCKED       # cannot proceed (external dependency / hard failure)
  - DONE          # implemented + merged
```

The `depends_on` gate keys off `DONE`. `/new` sets `IN_PROGRESS` on claim and
`DONE` on commit; it must not grep for a value no producer emits (a leftover-card
scan should match "not DONE", not a hard-coded `READY`).

```
Need to understand existing code?      --> codebase-architect (MANDATORY)
Have a plan to review?                 --> plan-auditor
Writing/modifying code?                --> coder
Code done, need review?                --> code-reviewer
Security-sensitive change or AppSec?   --> security-reviewer
Need docs written/audited?             --> doc-reviewer
Need derived wiki overlay pages?       --> wiki-curator (see agents/llm-wiki-methodology.md)
Distill recent reasoning into a page?  --> /capture skill

Mechanical gate run? (see QA Protocol) --> qa-sentinel  ← gate-runner only, PASS/FAIL
  Run lint / typecheck?                --> qa-sentinel
  Run unit or integration tests?       --> qa-sentinel
  Validate build passes?               --> qa-sentinel
  Security audit (npm audit, deep)?    --> qa-sentinel  (deep tier, or balanced w/ new deps)
  Pre-merge / pre-commit gate run?     --> qa-sentinel
  Run e2e / Playwright tests?          --> /e2e-review skill  (qa-sentinel does NOT run E2E)
  Write a regression test?             --> coder           (qa-sentinel cannot write code)
  Collateral impact detection?         --> code-reviewer / codebase-architect
  Check runtime logs / console errors? --> code-reviewer    (requires code-aware analysis)

New feature/bug to scope?              --> prd
PRD approved, need backlog cards?      --> prd-card-writer (called by /prd skill)
UI design or review?                   --> ui-expert
Visual assets needed?                  --> visual-designer
Animation specs?                       --> motion-expert
ML/ranking/recommendation?             --> hybrid-ml-architect
Gamification/retention?                --> hyper-gamification-designer
Research a technical topic?            --> senior-researcher
Marketing copy/positioning?            --> marketing-conversion-strategist
SEO/analytics planning?                --> seo-analytics-strategist
API performance audit?                 --> api-perf-cost-auditor
Privacy/GDPR compliance?               --> legal-counsel-gdpr
Onboarding flow design?                --> onboarding-architect-lead
Video/animation project?               --> remotion-animator-orchestrator
Email design/review/deliverability?    --> email-deliverability-architect
Multi-agent website work?              --> website-orchestrator
Customer psychology/behavior?          --> deep-human-insight
Weekly skill/agent improvement?        --> skill-improver
```

## QA Protocol (how to invoke qa-sentinel)

**qa-sentinel runs mechanical gates only** (lint, tsc, test, build, security audit, markdownlint). It does NOT verify acceptance criteria (Phase 2.5 does that) or analyze code quality/security (Phase 3 code-reviewer does that).

### Profile selection

The `review_profile` value (`skip | light | balanced | deep`) is **computed by
`prd-card-writer` (Rule C)** and carried on the card YAML. The decision criteria
for which profile a card gets live ONLY in `prd-card-writer.md` — see that file
for the criteria. qa-sentinel maps the profile to a test tier:

| Profile | qa-sentinel tier | npm audit |
|---------|------------------|-----------|
| `light` | gate not invoked (gates already ran during implementation) | — |
| `balanced` | SCOPED (related tests) | skip unless new deps |
| `deep` | FULL (whole suite) | `npm audit --audit-level=high` |
| `skip` | gate not invoked (docs-only / cosmetic) | — |

Tier is selected by the **profile**, not file count. A `balanced` change is
escalated to FULL only when the diff reveals undeclared risk
(auth/permission/payment/schema/migration/API contract); file count never escalates.

qa-sentinel does **not** run E2E/Playwright — blocking E2E for high-risk changes
is owned by the `/e2e-review` skill, invoked separately by the orchestrator.

### Invocation pattern

```
subagent_type: "qa-sentinel"
prompt: |
  Run QA on card <CARD-ID> at the tier dictated by the profile (do NOT default to FULL).
  Worktree: <path>  Branch: <branch>  Changed files: <list>
  QA profile: [balanced | deep]   (balanced → SCOPED, deep → FULL)
  (light/skip profiles do NOT invoke qa-sentinel — gates ran during implementation.)
  Run gates ONLY. No AC verification, no code analysis, no recommendations.
  Write gate results + verdict to: /qa/<CARD-ID>.md (under 40 lines)
```

### Self-healing loop (used by /new orchestrator)

1. qa-sentinel runs gates → returns PASS/FAIL
2. If FAIL → coder agent fixes the failing gate → qa-sentinel re-runs (up to 2 retries)
3. If still FAIL after 2 retries → escalate to user
4. Commit is **blocked** until qa-sentinel returns PASS

### Output

- Report: gate results table + verdict block (under 40 lines)
- Disk: `/qa/<CARD-ID>.md` — persists across context compaction

## Model Selection Matrix

Use this table when spawning agents via the `Task` tool. The `model` field in each agent's frontmatter is the default, but orchestrators MAY override with the `model` parameter.

| Agent | Default Model | Override Condition | Rationale |
|-------|--------------|-------------------|-----------|
| **coder** | opus | — (always opus) | Code writing demands highest reasoning quality |
| **code-reviewer** | sonnet | — (always sonnet) | Review is analysis-only, sonnet is sufficient |
| **doc-reviewer** | sonnet | — (always sonnet) | Documentation work, sonnet handles well |
| **security-reviewer** | sonnet | opus for auth/payments/multi-tenant | Elevate for high-risk security analysis |
| **qa-sentinel** | sonnet | — (always sonnet) | Mechanical gate runner, no reasoning needed |
| **codebase-architect** | sonnet | — (always sonnet) | Code navigation + pattern analysis |
| **plan-auditor** | sonnet | opus for >5 card epics | Complex plan audits benefit from deeper reasoning |
| **prd** | opus | — (always opus) | PRD creation requires deep product thinking |
| **prd-card-writer** | opus | — (always opus, effort: high) | Card precision requires deep reasoning for 20+ fields, traceability, parallel groups |
| **ui-expert** | opus | — (always opus) | Design quality requires highest capability |
| **hybrid-ml-architect** | opus | — (always opus) | ML architecture is complex by nature |
| **senior-researcher** | opus | — (always opus) | Research depth requires strongest model |

**Rules**: Never use haiku for any **named specialist agent** in the matrix above. Opus for code writing and creative/complex work. Sonnet for analysis, review, and documentation. `qa-sentinel` stays on sonnet even though it is a mechanical gate runner — its failure interpretation and SCOPED-vs-FULL tiering benefit from sonnet.

**Plumbing carve-out (haiku allowed):** the "never haiku" rule above governs the specialist agents. **Mechanical plumbing spawned as `general-purpose`** — with no reasoning and an explicit ROLE BOUNDARY — MAY use `model: "haiku"` via override. Two sanctioned uses today, both in `/new`: (1) the background **worktree-setup** subagent that runs `/nw` (create worktree, install deps, allocate port, write registry — `references/setup.md` §4b); (2) the **file-scoped revert agent** that restores unauthorized files to their pre-commit state (`references/implement.md` Phase 2.4). Both are deterministic git/file ops, never code authoring.

## Notes

- **"Can Edit Code: No"** means the agent is research/analysis-only; assign implementation to `coder`.
- **codebase-architect** is required by AGENTS.md before any planning or implementation.
- **qa-sentinel** is the mechanical gate runner (lint / tsc / scoped-or-full tests / build / `npm audit` (deep) / markdownlint) — run gates through it, never ad-hoc. It does NOT write tests (→ `coder`), run E2E/Playwright (→ `/e2e-review`), or do collateral-impact analysis (→ `code-reviewer` / `codebase-architect`).
- **security-reviewer** is the dedicated AppSec reviewer for auth, permissions, secrets, webhooks, file upload, infra, and multi-tenant isolation work.
- **code-reviewer** remains the general implementation reviewer for bugs, regressions, maintainability, and broad quality checks.
- Orchestrator agents (`website-orchestrator`) delegate to other agents.
- `agents/` folder (repo root) contains domain knowledge modules, not Task-invocable agents.

### Documentation Responsibility Split (coder vs doc-reviewer)

| Responsibility | Agent | When |
|----------------|-------|------|
| Minimal doc stubs (invariant entries: API index, UI route, collection, dependency, SSOT registry) | `coder` | Same commit as code change |
| Full doc writing (PRD sections, reference narratives, guides) | `doc-reviewer` | Follow-up step after coder |
| SSOT sync, drift detection, canonical resolution | `doc-reviewer` | Follow-up step after coder |
| Doc quality review, structural improvements | `doc-reviewer` | Follow-up step or standalone audit |

The `coder` MUST NOT write extended documentation beyond the minimal invariant stubs. The `doc-reviewer` MUST NOT defer doc writing to other agents — it owns documentation completeness.

## Domain Ownership

Maps domains to their canonical SSOT docs and the agents that own maintenance, updates, and drift resolution. New domains added here when a dedicated SSOT directory lands.

| Domain         | Canonical SSOT Docs                                | Owner Agents                                              |
| -------------- | -------------------------------------------------- | --------------------------------------------------------- |
| design-system  | `${paths.design_system}/INDEX.md` (entry point)        | `ui-expert`, `visual-designer`, `motion-expert`, `doc-reviewer` |
|                | `${paths.design_system}/tokens/semantic.tokens.json`   |                                                           |
|                | `${paths.design_system}/components/*.md`               |                                                           |
|                | `${paths.references_dir}/ui-guidelines.md` (brand)         |                                                           |
