Spec first, then tickets

# AGENTS.md: spec first, then tickets, then code

For any change bigger than a small fix, agree a written spec with the human before writing code, then implement it
as small tickets with checkable acceptance criteria.

## When a spec is required
- New feature, new endpoint or screen, schema change, cross-module refactor, or anything estimated over ~200 lines.
- Not required: bug fixes with a failing test, copy changes, dependency bumps, one-file refactors.

## Files
- Specs: `specs/<yyyy-mm-dd>-<slug>/SPEC.md`. Tickets: `TASKS.md` in the same folder. Both committed.
- The spec is the source of truth. If implementation reveals the spec is wrong, stop, update the spec and tell the human.

## Spec rules
- Problem and goal first; the solution second. Name what is out of scope.
- Acceptance criteria are observable and testable: "GET /api/orders?status=open returns only open orders, newest first".
  Not "orders are filtered correctly".
- List open questions instead of guessing. Do not start implementation while any are unanswered.
- Keep it short: one to two screens.

## Ticket rules
- Each ticket is independently testable and small (under ~200 changed lines), lists the files it touches, and maps to
  one or more acceptance criteria.
- Mark dependencies. Tickets with no shared files and no dependency can run in parallel.
- A ticket is done when its criteria pass in a test, not when the code compiles.

Use the `write-spec` skill to draft the spec and tickets, and the `implement-spec` skill to build them.

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `write-spec`, `implement-spec`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Spec first, then tickets" v1.0.0 — https://loadout.jnw-it.com/loadouts/spec-first-tickets/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `write-spec`, `implement-spec`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Spec first, then tickets" v1.0.0 — https://loadout.jnw-it.com/loadouts/spec-first-tickets/ -->

---
name: write-spec
description: Interview the human and research the codebase to write SPEC.md and TASKS.md for a feature before any code. Use when asked to plan or build a non-trivial feature.
---

# Write a spec

1. **Research first, quietly.** Read the relevant code (delegate broad reading to a read-only subagent where available).
   Note existing patterns, data models and tests the feature must fit.
2. **Interview.** Ask the human at most five questions at a time, only ones the code cannot answer: users, edge cases,
   limits, what is out of scope. Offer a recommended answer with each question.
3. **Draft** `specs/<date>-<slug>/SPEC.md` from `references/spec-template.md`. Every acceptance criterion must be testable.
4. **Split into tickets** in `TASKS.md` (format in the template): small, file-scoped, mapped to criteria, dependencies marked.
5. **Review with the human.** Show the spec and tickets; list open questions. Change nothing in source code until the human
   approves the spec.
6. **Commit** the spec folder on its own: `docs(spec): <slug>`.

# SPEC.md template

```markdown
# <Feature name>
Status: draft | approved | done · Owner: <human> · Date: <yyyy-mm-dd>

## Problem
<who has the problem, what happens today, why it matters>

## Goal
<one or two sentences>

## Out of scope
- <explicitly not doing>

## Design
<data model changes, endpoints or screens, key decisions and the alternatives rejected>

## Acceptance criteria
- AC1: <observable, testable statement>
- AC2: ...

## Open questions
- Q1: <question> (recommended answer: <...>)
```

# TASKS.md template

```markdown
# Tasks for <feature>

- [ ] T1 <title> · covers AC1 · files: src/api/orders.ts, tests/api/orders.test.ts · depends on: none
- [ ] T2 <title> · covers AC2 · files: ... · depends on: T1
```

---
name: implement-spec
description: Build an approved SPEC.md ticket by ticket with tests for each acceptance criterion, in parallel where tickets are independent, then review against the spec. Use after a spec has been approved.
---

# Implement a spec

1. **Check approval.** `SPEC.md` status must be `approved` and open questions empty. Otherwise stop.
2. **Plan waves.** From `TASKS.md`, group tickets with no dependencies and no shared files into waves.
3. **Per ticket** (yourself, or one subagent or worktree per ticket in a wave):
   - Write the test for the ticket's acceptance criteria first and see it fail.
   - Implement until it passes; run the full test suite.
   - Tick the ticket in `TASKS.md` and commit: `feat(<slug>): T<n> <title>`.
4. **Between waves** pull in finished work and run the full suite before starting the next wave.
5. **Spec drift.** If a ticket cannot meet its criterion as written, stop that ticket, propose a spec change to the human,
   and continue only with unaffected tickets.
6. **Final review** against the spec, by a reviewer that did not write the code: every AC has a passing test, nothing out of
   scope was built. Set `Status: done` in `SPEC.md`.

Heavier frameworks exist if the team wants more structure: GitHub Spec Kit (`specify` CLI) and OpenSpec
(`npx @fission-ai/openspec`). Use them only if the repository already does; do not mix formats.