1# AGENTS.md
 2
 3cooked-mcp is a simple, idiomatic MCP server for https://cooked.wiki's API.
 4
 5## Commands
 6
 7```bash
 8mise run check # Executes all of mise run fix, yaml:fmt, tidy, yaml:lint, lint, vuln, build, and test:quiet. All are individually runnable with `mise run <task>` and parallelisable with `mise run task:a ::: task:b`
 9mise run fix # Runs multiple formatters through golangci-lint
10mise run build # Builds ./cmd/cooked-mcp into cooked-mcp
11```
12
13## Workflow
14
15- We use jujutsu (`jj`). When reading diffs, use `--git` for git-style diffs.
16  Before starting work, run `jj status`. If the new work is different from the
17	working copy, run `jj new -m "area: imperative, kernel-style change
18	description"`. We use imperative, kernel-style commits with prefixes for
19	areas/subsystems like `routing: frontend: desc of routing and frontend
20	changes`. Fill out change description bodies for non-trivial commits.
21
22- Use `mise` for project tooling and tasks. `mise run check` before ending your
23  turn. While iterating on `check` output, use narrower tasks such as `mise run
24	fix`/`mise run test` or combined and parallelised like `mise run lint :::
25	test` as necessary. Do not use direct commands like `gofmt`; use mise tasks.
26
27- Use `acai` and keep the project spec-first. Behaviour requirements live in
28  `features/cooked-mcp/*.feature.yaml`; reference full ACIDs in tests and
29	important implementation comments. `acai push` requires Git to be attached to
30	the implementation branch; after moving the `main` jj bookmark, use `git
31	switch -f main` if Git is still detached at the old commit. After `acai
32	push`, update completed statuses with `acai set-status @payload.json
33	--product cooked-mcp --impl main --json`; the payload is a JSON object keyed
34	by full ACID, e.g. `{"core.TOKEN.1": {"status": "completed"}}`. Do not add
35  comments.
36
37	- Update or confirm the relevant acai spec before implementation. List the
38	  full ACIDs the slice intends to satisfy and reconcile unclear intent before
39    writing code.
40
41- Follow red/green TDD. Write failing tests first, then implement so they're
42  green. Do not smoke test unless I tell you to. Rely on and maintain and
43  expand our tests instead.
44
45- If smoke testing reveals a gap, it means we need better automated tests.
46  Close the gap by adding or improving tests so the same issue gets caught
47  automatically in the future.
48
49- Work in tiny slices that are independently verifiable. Keep unrelated
50  documentation or AGENTS.md edits separate from feature changes.