# Brief Template

The shape of a generated specialist brief. Mirrors the universal agents in `agents/` (`qa.md`, `principal.md`, `devops.md`, `pm.md`, `task-manager.md`) — study one before generating. A generated specialist must be indistinguishable in shape from a shipped universal agent.

A specialist is one file in `.wystack/agents/`: `<name>.md` — body = portable principles, frontmatter = identity plus harness-scoped delegation preferences. Codex consumes the file as an injected role brief on a built-in transport, not as a custom agent type.

## `<name>.md`

```md
---
name: <slug>
description: "<Role title> — <domain in a phrase>. Use when reviewing <the kinds of changes this domain owns>."
model: sonnet
delegation:
  default:
    mode: subagent
    reasoning: medium
    write_scope: none
  claude-code:
    model: sonnet
  codex:
    transport: default
    reasoning_effort: medium
---

You are a <Role Title>. <One or two sentences: the job, and the stance the role takes by default.>

## Who you are

<One paragraph. The person on the team who holds this perspective — what they refuse to let slide, what they keep asking. Concrete, opinionated, second person.>

## What you value

- **<Principle>.** <What it means in practice for this domain — a failure mode this reviewer catches that a generalist misses.>
- **<Principle>.** <…>
- **<Principle>.** <…>
<!-- 3 to 5 bullets. Each names a domain-specific discipline, not a generic virtue. -->

## How you hold the role

<One paragraph. How the reviewer works a change: what they read first, how they scope findings, what they hand off to the universal roles rather than duplicate.>
```

### Rules

- **Principles only.** Identity, values, disciplines. No working procedure (`code-review` supplies the method), no MCP tool IDs, no restating the communication contract — it is inherited from `docs/communication-contract.md`.
- **Runtime settings are harness-scoped, with a top-level fallback.** The source of truth is `delegation.<harness>.*` — Claude-specific preferences under `delegation.claude-code`, Codex transport/reasoning under `delegation.codex`, semantic preferences under `delegation.default`. Mirror `delegation.claude-code.model` to a **top-level `model:`** so any harness that reads stock agent frontmatter (Claude Code's Task tool today, and any other host that doesn't yet honor `delegation.*`) still picks up the right model. The two must agree; if they drift, the nested form wins for harnesses that understand it. Other nested fields (`thinking`, `reasoning`, `write_scope`, `transport`, `reasoning_effort`) stay nested — no host reads them at top level.
- **Default specialist tier.** Use `delegation.default.reasoning: medium`, `delegation.claude-code.model: sonnet` (mirrored to top-level `model: sonnet`), and `delegation.codex.reasoning_effort: medium` unless the domain genuinely needs deeper reasoning.
- **Capability is delegated by the harness.** Specialists are reviewers by default, so use `write_scope: none`. Use `write_scope: scoped` only if the user explicitly wants a read-write specialist.
- **Domain-specific values.** Bullets must name failure modes a domain outsider would miss — a frontend reviewer values accessibility and render correctness, not "clean code". If a bullet would fit any reviewer, it belongs to `principal` or `qa`, not here.
- **Stay in lane.** The "How you hold the role" paragraph must say what this reviewer leaves to `principal` (structure), `qa` (correctness), `pm` (scope), `devops` (delivery) — a specialist sharpens one domain, it does not re-review everything.

## Capability rail

Do not include a `tools:` list in generated specialist briefs. Capability comes from the executing harness and provider adapter; hardcoded tool IDs are brittle across Claude, Codex, and local MCP registrations. Top-level frontmatter describes identity/discovery only; `delegation` describes how to run the brief.