# Agent-issue template

Every issue intended for a dev agent should follow this shape. The `dev-task.sh`
wrapper reads `Model:` to pick the model and ignores the rest of the headings;
they're for the agent and for any auditor that later reviews the PR.

```markdown
## Goal

<One paragraph. State what the agent must produce, not how.>

## Done criteria

- [ ] <Specific, verifiable check — file exists / endpoint returns X / test passes>
- [ ] <…>

## Hints

<Freeform context. Constraints, things to NOT do, references to existing code.>

## Model

sonnet
```

## Rules of thumb

- **Scope tight.** An issue should fit in 30 min of agent time. If it feels
  like a full feature, decompose it into 2–3 smaller issues with `depends_on`.
- **Done criteria are how the auditor checks the PR.** If a criterion can't
  be verified mechanically (or by reading the diff), it's the wrong shape.
- **Don't tell the agent how**, tell it what the result must look like. Hints
  are for constraints (e.g. "no new dependencies", "match existing style").
- **Pick `opus` only when the task involves design tradeoffs.** Routine
  scaffolding, CRUD endpoints, and well-specified refactors are sonnet work.
- **Avoid taste calls.** "Make the UI look good" is not an agent task; "use
  Tailwind utility classes for spacing" is.

## Anti-patterns

- ❌ "Refactor the whole repo for clarity"  (no criterion — no PR will satisfy this)
- ❌ "Write a TODO app"                       (too broad — decompose)
- ❌ "Improve performance"                    (no measurable target)
- ✅ "Add GET /todos endpoint returning 2 hardcoded items as JSON"
- ✅ "Replace bcrypt with argon2id in auth/password.ts; existing tests must still pass"