# AGENTS.md This repository is Mina, a local-first personal finance system implemented in Go. ## Project Documentation - `VISION.md`: product destination and product character. Mandatory read at the beginning of any work. Use it to guide tradeoffs; do not treat it as a backlog or implementation-status document. Never change it unless specifically instructed. - `SCOPE.md`: durable product boundaries — what is in and out relative to the vision. Read before planning, creating or refining Kata issues, or deciding whether work belongs in Mina. A claimed Kata issue or committed plan owns concrete implementation scope, so routine implementation does not require rereading `SCOPE.md` unless scope is ambiguous. Never change it unless specifically instructed. - `PROJECT_STATE.md`: concise implemented reality. Read when checking what exists now. Update only when user-visible progress against the vision is made; do not update for refactors or internal API changes. - Kata: shared issue ledger for future work, priorities, dependencies, and ownership. It replaces roadmap phasing; do not use documentation as a parallel backlog. - `docs/plans/completed/`: immutable historical plans. Never edit completed plans, including their commands or examples, unless the user explicitly requests changes to those plans. - `docs/architecture.md`: backend technical system design, hard rules, and package boundaries. Mandatory read at the beginning of any work. Never change it unless specifically instructed. - `docs/frontend-architecture.md`: frontend technical system design, hard rules, and package boundaries. Mandatory read before frontend or `internal/webui` work; it is not required for backend-only work. - `docs/webui-design.md`: ground truth for web UI UX — pages, content, interaction and display rules. Mandatory read before planning or changing UI screens or user-facing web UI behavior. - `docs/webui-theme-arcade-cabinet.md`: ground truth for the Arcade Cabinet web UI theme. Mandatory read before web UI theme or styling changes. - Domain semantics docs in `docs/`: ground truth for cross-cutting product behavior named by each document; read the owning semantic doc before planning or changing that behavior. - `api/openapi.yaml`: REST transport contract. Read before planning or changing REST behavior. - Package/module docs for backend and frontend: local technical contracts, side effects, ownership boundaries, and invariants. Read the relevant package docs before changing a package. Use the `write-package-docs` skill for every package touched by the work. Exported Go APIs that cross package boundaries must be documented in code. - All docs must stay short. Prefer bullets, with one liners. Prefer replacing old statements to adding net new. Link to owning docs instead of repeating details. - Do not manually wrap prose: keep each paragraph and bullet item on one physical line, and run `just prose-fmt` before finishing your work. - Documentation is evergreen. Never keep history, migration notes, or references to previous doc/code states. ## Infra & Dev Practices - Project-related environment issues: diagnose and fix them yourself — e.g. kill stale `mina` dev/test server processes holding project ports (18080/18081, `just dev`), remove leftover project processes or artifacts, then retry. Stop and ask only for failures outside the project's scope (shell, Go toolchain, OS-level breakage). - The Justfile is the only owner of developer recipes. Run formatting, tests, checks, hooks, and scripts through `just`. - `scripts/` contains repo scripts, not product code. Manual benchmark recipes are never agent-required checks and must not be run unless the user explicitly asks. - Do not invoke `gofmt`, `go test`, `prek`, or other recipe internals directly unless debugging the recipe itself. - Run `just pre-commit` for configured pre-commit checks; the Justfile owns the details. - Do not add test code under `internal/tools/**`. Validate internal tool changes with manual smoke checks, `just pre-commit`, and review. - Custom lint rules: import-boundary rules live in `.golangci.yml` depguard config; non-import architecture rules live in `internal/tools/archlint`. - Write idiomatic Go. Keep dependencies small and explicit. Use package-level boundaries instead of generic abstraction layers until a real boundary exists. - Do not create redundant layers, and multiple defensive layers that do the same thing. E.g. if service does validation, do not repeat the same validation at other layers! - Do not recreate what project dependnecy already implements. Always prefer capabilities provided by the library! - Keep side effects isolated at explicit boundaries: filesystem, database, subprocesses, network listeners, clocks, and terminal I/O. - Keep model packages data-focused. Put validation, persistence, and transport mapping in owning packages. - Keep router/handler code thin. Domain behavior belongs in services/use-case packages. - Keep commits small and self-contained. Finish and verify one task before starting another. ## Development Workflow - Complete authorized, in-scope work using repository evidence and reasonable assumptions for routine choices. Ask only when a missing decision materially changes the result; in unattended sessions, report the blocker and complete independent authorized work. - User instructions take precedence over skill guidance. If a skill blocks progress, identify the exact file and instruction and explain the conflict rather than inferring an approval requirement. For every commit: - For application code changes, run `just pre-commit`, `just test` during developement and before committing. - For code changes that touch CLI, real-network REST, process startup, JSON-over-HTTP behavior, run `just test-integration` before commit. - For changes that touch frontend runtime behavior, embedded UI assets, browser behavior, or JSON-over-HTTP behavior used by the frontend, run `just test-frontend-e2e` before commit. - Do not run tests or broad validation for pure documentation changes, or for tooling/developer-recipe changes that do not touch application code. - For changes that alter implicit contracts, side effects, ownership boundaries, or invariants that are not obvious from API docs update the relevant package docs in the same commit. - When working from a plan document, follow its verification workflow verbatim; its review-loop invocation must use `just review-loop --plan ""`. - Otherwise, run `just review-loop --goal ""` at the end of your work. Rebase sessions are exempt and must not run review-loop.