orchestrator/pm/issue-template.md

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.

## 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"