AGENTS.md

AGENTS.md

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

Commands

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.