# AGENTS.md

cooked-mcp is a simple, idiomatic MCP server for https://cooked.wiki's API.

## Commands

```bash
mise 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`
mise run fix # Runs multiple formatters through golangci-lint
mise run build # Builds ./cmd/cooked-mcp into cooked-mcp
```

## Workflow

- We use jujutsu (`jj`). When reading diffs, use `--git` for git-style diffs.
  Before starting work, run `jj status`. If the new work is different from the
	working copy, run `jj new -m "area: imperative, kernel-style change
	description"`. We use imperative, kernel-style commits with prefixes for
	areas/subsystems like `routing: frontend: desc of routing and frontend
	changes`. Fill out change description bodies for non-trivial commits.

- Use `mise` for project tooling and tasks. `mise run check` before ending your
  turn. While iterating on `check` output, use narrower tasks such as `mise run
	fix`/`mise run test` or combined and parallelised like `mise run lint :::
	test` as necessary. Do not use direct commands like `gofmt`; use mise tasks.

- Use `acai` and keep the project spec-first. Behaviour requirements live in
  `features/cooked-mcp/*.feature.yaml`; reference full ACIDs in tests and
	important implementation comments. `acai push` requires Git to be attached to
	the implementation branch; after moving the `main` jj bookmark, use `git
	switch -f main` if Git is still detached at the old commit. After `acai
	push`, update completed statuses with `acai set-status @payload.json
	--product cooked-mcp --impl main --json`; the payload is a JSON object keyed
	by full ACID, e.g. `{"core.TOKEN.1": {"status": "completed"}}`. Do not add
  comments.

	- Update or confirm the relevant acai spec before implementation. List the
	  full ACIDs the slice intends to satisfy and reconcile unclear intent before
    writing code.

- Follow red/green TDD. Write failing tests first, then implement so they're
  green. Do not smoke test unless I tell you to. Rely on and maintain and
  expand our tests instead.

- If smoke testing reveals a gap, it means we need better automated tests.
  Close the gap by adding or improving tests so the same issue gets caught
  automatically in the future.

- Work in tiny slices that are independently verifiable. Keep unrelated
  documentation or AGENTS.md edits separate from feature changes.