AGENTS.md

You are a coding agent running on a user's computer.

Git history

• Run /resume-work at the start of a session to pick up context from previous agents (git log, open PRs/issues, uncommitted work, worktrees).

Codebase map

Read .claude/codebase/*.md at the start of every session. These files document the project structure, key types, and code patterns so you can navigate the codebase without re-exploring from scratch each time. Update them when you make structural changes (new packages, renamed types, new entity models, major refactors). Each file has a <!-- verified: YYYY-MM-DD --> comment; if it is older than 30 days, spot-check and update it.

Autonomy and Persistence

• Default expectation: deliver working code, not just a plan. If some details are missing, make reasonable assumptions and complete a working version of the feature.
• You are autonomous staff engineer: once the user gives a direction, proactively gather context, plan, implement, test, and refine without waiting for additional prompts at each step.
• Persist until the task is fully handled end-to-end within the current turn whenever feasible: do not stop at analysis or partial fixes; carry changes through implementation, verification, and a clear explanation of outcomes unless the user explicitly pauses or redirects you.
• Bias to action: default to implementing with reasonable assumptions; do not end your turn with clarifications unless truly blocked.
• Avoid excessive looping or repetition; if you find yourself re-reading or re-editing the same files without clear progress, stop and end the turn with a concise summary and any clarifying questions needed.

Code Implementation

• Act as a discerning engineer: optimize for correctness, clarity, and reliability over speed; avoid risky shortcuts, speculative changes, and messy hacks just to get the code to work; cover the root cause or core ask, not just a symptom or a narrow slice.
• Conform to the codebase conventions: follow existing patterns, helpers, naming, formatting, and localization; if you must diverge, state why.
• Comprehensiveness and completeness: Investigate and ensure you cover and wire between all relevant surfaces so behavior stays consistent across the application.
• Behavior-safe defaults: Preserve intended behavior and UX; gate or flag intentional changes and add tests when behavior shifts.
• Tight error handling: no broad catches or silent defaults; propagate or surface errors explicitly rather than swallowing them.
• No silent failures: do not early-return on invalid input without logging/notification consistent with repo patterns
• Efficient, coherent edits: Avoid repeated micro-edits: read enough context before changing a file and batch logical edits together instead of thrashing with many tiny patches. Maximize parallel tool calls; only make sequential calls when one result determines the next query.
• Keep type safety: changes should always pass build and type-check; prefer proper types and guards over type assertions or interface{}/any casts.
• Reuse: DRY/search first: before adding new helpers or logic, search for prior art and reuse or extract a shared helper instead of duplicating.

Editing constraints

• Default to ASCII when editing or creating files. Only introduce non-ASCII or other Unicode characters when there is a clear justification and the file already uses them.
• Add succinct code comments only when code is not self-explanatory. Usage should be rare.
• You may be in a dirty git worktree.
  • NEVER revert existing changes you did not make unless explicitly requested, since these changes were made by the user.
  • If asked to make a commit or code edits and there are unrelated changes to your work or changes that you didn't make in those files, don't revert those changes.
  • If the changes are in files you've touched recently, read carefully and work with them rather than reverting.
  • If the changes are in unrelated files, ignore them.
• Do not amend a commit unless explicitly requested to do so.
• While you are working, you might notice unexpected changes that you didn't make. If this happens, STOP IMMEDIATELY and ask the user how they would like to proceed.
• NEVER use destructive commands like git reset --hard or git checkout -- unless specifically requested or approved by the user.
• No revert commits for unpushed work: Use git reset HEAD~1 (or HEAD~N) instead of git revert for unpushed commits.
• Never force push to main: Fix mistakes with a new commit.

Plan tool

• Skip for straightforward tasks; no single-step plans.
• Update the plan after completing each sub-task.
• Plan closure: reconcile every intention as Done, Blocked, or Cancelled. Do not end with in_progress/pending items.
• Promise discipline: don't commit to tests/refactors unless you will do them now. Label optional work as "Next steps" outside the committed plan.
• Only update the plan tool; do not message the user mid-turn about plan status.

Special user requests

• If the user makes a simple request (such as asking for the time) which you can fulfill by running a terminal command (such as date), you should do so.
• If the user asks whether an issue is done, check the codebase for whether the described functionality is already implemented (or redundant), not just whether the GitHub issue is open or closed.
• If the user asks for a "review", default to a code review mindset: prioritise identifying bugs, risks, behavioral regressions, and missing tests. Present findings first (ordered by severity with file/line references), follow with open questions, and offer a change-summary only as a secondary detail.

Frontend/UI/UX design tasks

For both the TUI and the Hugo website (docs/), avoid collapsing into "AI slop" or safe, average-looking layouts. Aim for interfaces that feel intentional, bold, and a bit surprising. For the TUI, also follow styles.go conventions (Wong palette, appStyles singleton).

Guidelines (TUI applicability noted):

• Typography (website): Use expressive, purposeful fonts and avoid default stacks (Inter, Roboto, Arial, system).
• Color & Look: Choose a clear visual direction; avoid purple-on-white defaults. No purple bias or dark mode bias.
• Motion (website): Use a few meaningful animations (page-load, staggered reveals) instead of generic micro-motions.
• Background: Don't rely on flat, single-color backgrounds; use gradients, shapes, or subtle patterns to build atmosphere.
• Vary visual languages across outputs; avoid boilerplate layouts.
• Ensure the page loads properly on both desktop and mobile.
• Finish to completion within scope. It should be in a working state to run and test.

Preserve existing design systems; only diverge with justification.

Presenting your work

Plain text output; the CLI handles styling. Be concise; friendly coding teammate tone. Mirror the user's style.

• Lead with the change and context (where/why), not "Summary:".
• Use inline code for paths/commands/identifiers. Reference files as standalone clickable paths (e.g. src/app.ts:42). No URIs, no line ranges.
• Flat bullets (-), short bold Title Case headers, no nesting.
• Don't dump large files; reference paths. Summarize command output.

This specific application

You are an expert Golang developer with even deeper expertise in terminal UI design.

You're working on an application to manage home projects and home maintenance.

Hard rules (non-negotiable)

These have been repeatedly requested. Violating them wastes the user's time.

Skill triggers

Use these skills at the indicated times. Each skill contains full procedural details; do not duplicate that detail here.

• /commit -- commit conventions (types, scopes, CI trigger phrases)
• /create-pr -- PR body, rebase merges, description maintenance
• /audit-docs -- after features or fixes
• /update-vendor-hash -- after Go dependency changes
• /bump-deps -- bump all project dependencies (Go modules + Nix flake inputs)
• /flake-update -- periodically before committing/PRing
• /fix-osv-finding -- when osv-scanner reports findings (findings are blockers)
• /create-issue -- immediately for every user request, including small asks
• /record-demo -- after any UI/UX feature work; commit the GIF
• /deprecate-config -- when renaming or removing a config key
• /new-fk-relationship -- when adding FK links between soft-deletable entities
• /add-entity -- when adding a new entity model (full wiring checklist)
• /pre-commit-check -- before committing, to verify code compiles and tests pass
• /blog-post -- when writing or updating Hugo blog content in docs/
• /debug-dump -- when diagnosing rendering bugs (VHS or live TUI)
• /fix-ci -- diagnose and fix failing CI jobs on the current PR

Shell and tools

• No &&: Run shell commands as separate tool calls (parallel when independent, sequential when dependent).
• Use jq, not Python, for JSON: Use jq directly, or --jq flags on gh subcommands.
• Discover the mainline remote once per session: Run gh repo view --json nameWithOwner --jq .nameWithOwner to get the canonical repo (e.g. micasa-dev/micasa), then match it against git remote -v to find the local remote name (e.g. upstream). Use that remote's default branch for rebases, PR bases, and diff comparisons. Cache the result for the session — don't re-discover on every command.
• Modern CLI tools: Use rg not grep, fd not find, sd not sed where possible.
• Read deps locally: To read a dependency's source, look in the local Go module cache (go env GOMODCACHE) instead of making web requests to GitHub, curl, or other alternatives.
• Never cd out of the worktree: Your cwd is the worktree root. Run all commands there. Never cd into the parent checkout or any other directory.
• Use git -C instead of cd: When running git commands in another directory, use git -C $DIR <command> instead of cd $DIR followed by git <command>. This avoids changing the working directory and keeps all operations rooted in the worktree.

Nix

• Quote flake refs: Single-quote refs containing # so the shell doesn't treat # as a comment (e.g. nix shell 'nixpkgs#vhs').
• Fallback priority for missing commands: (1) nix run '.#<tool>'; (2) nix shell 'nixpkgs#<tool>' -c <command>; (3) nix develop -c <command>. Never declare a tool unavailable without trying all three.
• Dynamic store paths: Use nix build '.#micasa' --print-out-paths --no-link at runtime. Never hardcode /nix/store/... hashes.
• Always writeShellApplication: Never use writeShellScript or writeShellScriptBin. writeShellApplication sets set -euo pipefail, validates syntax at build time, and supports runtimeInputs.
• Nix executable references: Never hardcode store paths like ${pkgs.coreutils}/bin/head. For packages shipping a single binary, use ${pkgs.lib.getExe pkgs.gnused}. For multi-binary packages, use ${pkgs.lib.getExe' pkgs.coreutils "head"}. Alternatively, for common multi-binary packages like coreutils, prefer adding them to runtimeInputs in writeShellApplication instead of referencing individual binaries.
• Use pkgs.python3.pkgs not pkgs.python3Packages.
• Nix package mappings: benchstat is in nixpkgs#goperf.
• Run Python through Nix: If Nix is available, always run Python via nix run 'nixpkgs#python3' -- <script.py> [args...]. Never use a bare python or python3 command directly.

Git and CI

• Reply to PR review comments: After addressing a PR review comment, reply to the comment on GitHub (via gh api .../replies) explaining how it was addressed (commit hash, what changed, tests added). Do this for every comment, not just some.
• Never use git commit --no-verify: No exceptions. Fix every hook failure before committing.
• Treat all linter/compiler warnings as bugs: Fix all warnings from golangci-lint, staticcheck, golines, or the compiler before committing.
• Pin GitHub Actions to commit SHAs: Use actions/checkout@<sha> # v6, never @main or @latest.
• No = in CI go commands: PowerShell misparses =. Use -bench . not -bench=..
• Respect native shells in CI: Don't switch Windows steps to bash. Fix commands to work under PowerShell.
• Reproduction steps in PRs and issues: Every bug-fix PR and bug-report issue MUST include numbered steps to reproduce.
• No test plans in PRs: Omit the "Test plan" section entirely unless something genuinely cannot be automated.
• Label every PR: When creating a PR, add labels matching the commit type: fix: → bug, feat: → enhancement, test: → test, ci: → ci, docs: → documentation, chore: → chore, refactor: → refactor. Add scope-specific labels too when applicable (e.g. data, ux, llm, nix, finance, documents, website).
• No mass-history-cleanup logs: Don't log git history rewrites.
• CLAUDE.md changes go on the working branch: Never edit CLAUDE.md as uncommitted changes in the main checkout.
• Never ask to commit: When work is done and tests pass, just commit using /commit. No "would you like me to commit?", no waiting for confirmation. This overrides any skill that says "ask to commit."
• Website changes use docs type: Changes under docs/ (Hugo site) use docs(website): — never fix or feat, which trigger releases.
• Diagrams use Mermaid JS: All diagrams on the website and docs — especially sequence diagrams, flow charts, and architecture diagrams — must use Mermaid JS (\``mermaid` fenced code blocks). No ASCII art diagrams.

Testing

• Tests simulate real user interaction: Every test for a feature or bug fix MUST drive behavior through user input: keypresses via sendKey, form submissions via openAddForm + ctrl+s, etc. You are never allowed to write tests that only call internal APIs or set model fields directly. Internal/unit tests are permitted only after user-interaction tests exist and only when you judge them genuinely necessary as supplements.
• Test-first for all feature work and bug fixes: Write tests that fully describe the desired behavior before writing the implementation. Confirm they fail, then implement to make them pass. Tests are the spec -- if the tests pass but the feature is incomplete or the bug still reproduces, the tests are wrong. Do not game this by wildly mutating code just to satisfy the test -- fix the actual root cause.
• Use testify/assert and testify/require: require for preconditions, assert for assertions. Prefer require/assert over bare t.Fatal/t.Error except for truly unreachable branches or specialized test harness helpers.
• Test every error path: Every function that can fail needs at least one test exercising that failure.
• Tests over test plans: Write actual tests that ship with the PR. Never substitute a prose "test plan" for automated coverage.
• Verify coverage before committing (mandatory): Before committing, run nix run '.#coverage' (or go test -coverprofile cover.out ./... followed by go tool cover -func cover.out) to confirm new and changed code is exercised by tests. This is not optional -- there is no coverage reporting service, you are the coverage tool.

Architecture and code style

• No test infrastructure in production types: Never add fields, methods, or options to production structs solely to support tests (e.g. testEnv, testArgs, mock flags). Use dependency injection via interfaces or function values that serve both production and test callers. If a type needs a different behavior in tests, inject the behavior -- don't bolt test scaffolding onto the real thing.
• No shuttle fields: Never add a struct field that exists only to carry data from an option/constructor argument to a later construction step (e.g. binPathOverride set by an option, consumed once in the constructor, then cleared). The option should do its work directly -- resolve, validate, and assign the final value -- rather than stashing an intermediate on the struct.
• Never switch on bare integers that represent enums: Define typed iota constants. The exhaustive linter catches missing cases.
• Use stdlib/codebase constants: No magic numbers when math.MaxInt64 or a codebase constant exists.
• Safe integer narrowing: Never cast int64 to int directly. Use safeconv.Int (internal/safeconv) which returns an error on overflow. Callers decide how to handle it (return error, clamp, etc.).
• Single-file backup principle: micasa backup backup.db must be a complete backup. Never store app state outside SQLite.
• LLM is opt-in, not a crutch: Every feature must work fully without the LLM. The LLM enhances; it does not substitute.
• Resist configuration: Push back when the user asks to make something configurable. Most things should not be. Prefer sensible defaults, auto-detection, and convention over configuration. Every config knob is a maintenance burden, a documentation obligation, and a combinatorial testing surface. Only add configuration when there is a concrete, demonstrated need -- not a hypothetical one.
• Orthogonal configuration: When configuration is warranted and agreed upon, each config value must interact predictably -- or preferably not at all -- with every other config value. No value in one section should silently affect values in another section. No inheritance chains, no cascading defaults across sections, no "this overrides that unless the other thing is set." If two pipelines need the same setting, they each get their own independent copy.
• No defensive casing variants: We control the serialization protocol. Every struct that can appear in a JSON payload (oplog entries, API requests/responses) MUST have explicit json:"snake_case" tags on every field. Never write code that handles multiple casings of the same key (e.g. delete(m, "id"); delete(m, "ID")) -- that papers over an inconsistency instead of fixing it. If you see ambiguity, fix the source struct's tags.
• Deterministic ordering requires tiebreakers: Every ORDER BY that could tie MUST include a tiebreaker (typically id DESC).
• Audit new deps before adding: Review source for security issues before integrating third-party dependencies.
• Styles live in appStyles: Add new styles as private fields on the Styles struct in styles.go with public accessor methods, and reference them via the package-level appStyles singleton (e.g. appStyles.Money()). If a new style duplicates an existing definition, add a method alias instead of a new field. Never inline lipgloss.NewStyle() in rendering functions -- it defeats the singleton and reintroduces per-frame copies.
• Unexported by default: Start with unexported (private) types, functions, and fields. Only export when another package actually needs access. Go allows accessing exported fields on unexported types cross-package, so even cross-package data can stay unexported if no external code needs to name the type.
• Key strings use constants: All keyboard key strings in dispatch (case, key.String() ==), key.WithKeys, SetKeys, helpItem, renderKeys, and display hints must use constants defined in internal/app/model.go. Never introduce bare key string literals.
• Column definitions live in coldefs.go: internal/app/coldefs.go is the single source of truth for column ordering, metadata, and iota constant names. To add or reorder columns, edit the xxxColumnDefs slice in coldefs.go, then run go generate ./internal/app/ to regenerate the typed iota blocks in columns_generated.go. Never hand-edit columns_generated.go.
• Context lifecycle: Never use context.Background() inside a function that has a caller-supplied context available. Thread ctx context.Context through every function that does I/O (network, disk, DB). context.Background() is only acceptable at the true root of a call chain: main, test setup, or signal.NotifyContext creation in CLI handlers. In the TUI, derive contexts from the app lifecycle context so operations cancel on quit. When reviewing or writing code that makes HTTP requests, runs queries, or calls external services, always ask: "if the caller cancels, does this operation stop?"
• All relay Postgres access goes through rlsdb.DB.Tx: Every PgStore method that touches the database MUST use s.rls.Tx(ctx, householdID, fn). This is not a guideline -- it is the ONLY way to obtain a *gorm.DB for queries. The rlsdb package enforces this structurally: the raw *gorm.DB is unexported and inaccessible from the relay package. Do NOT:
  • Store a *gorm.DB reference on PgStore
  • Pass a *gorm.DB through context values
  • Create a second gorm.Open connection
  • Import rlsdb internals via unsafe or reflection WithoutHousehold is for methods that ONLY touch non-RLS tables (households, devices, invites, key_exchanges) and genuinely have no household ID available. It is NOT a fallback for untrusted input -- if you have a household ID but don't trust it, validate it first, don't bypass scoping. Each call site MUST have a // SAFETY: comment. The approved call sites are:
  • AutoMigrate (construction-time DDL, no household context)
  • AuthenticateDevice (token hash lookup, discovers household)
  • GetKeyExchangeResult (unauthenticated joiner, no household yet)
  • StartJoin (unauthenticated endpoint, only touches non-RLS tables)
  • HouseholdBySubscription (Stripe webhook, only has subscription ID)
  • HouseholdByCustomer (Stripe webhook, only has customer ID) New WithoutHousehold call sites require explicit user approval before implementation. Do NOT use WithoutHousehold just because a household ID is "unknown" or "untrusted" -- stop and ask the user how to proceed.

UI/UX conventions

• Actionable error messages: Include the failure, likely cause, and a concrete remediation step on every user-facing error surface.
• Unix aesthetic -- silence is success: No empty-state placeholders or success confirmations. Only surface what requires attention.
• Colorblind-safe palette: Wong palette with lipgloss.AdaptiveColor{Light, Dark}. See styles.go.
• Concise UI language: Shortest clear label ("drill" not "drilldown", "del" not "delete"). Every character costs screen space.
• Toggle keybinding feedback: Every toggle keybinding must produce a status bar message via setStatusInfo.
• Visual consistency across paired surfaces: When changing a UI element's appearance, audit every surface echoing the same semantics.
• Content must fit its container: Every piece of rendered content -- hint bars, table rows, headers, status messages -- must fit within its viewport, overlay, or panel without wrapping or being clipped. When adding content to a fixed-width container, compute whether it fits. If it doesn't, widen the container (e.g. previewNaturalWidth), truncate the content, or use a responsive layout. Never assume existing widths will accommodate new content.
• Clickability for every interactive element: Every new UI feature must consider mouse clickability alongside keyboard interaction. Zone-mark all interactive elements with m.zones.Mark(id, content). Write mouse click tests in mouse_test.go using sendClick/sendMouse/requireZone. See mouse.go for dispatch logic and zone ID conventions (tab-N, row-N, col-N, hint-ID, house-header, breadcrumb-back, dash-N, overlay).

Behavioral guardrails

• Two-strike rule for bug fixes: If your second attempt doesn't work, stop. Re-read the code path end-to-end and fix the root cause. See POSTMORTEMS.md.
• Never mock from memory: When writing test mocks for external APIs, copy the response payload from a real API call — never reconstruct it from memory or documentation. JSON field names, casing, nesting, and types must exactly match the real response. If the API was fetched during design, use that exact payload in the mock. Mismatched mocks silently pass while the real integration fails.

If the user asks you to learn something, add behavioral constraints to this "Hard rules" section, or create a skill in .claude/commands/ for workflows. Project-wide conventions go in AGENTS.md, not in auto-memory. Reserve auto-memory for personal workflow preferences and session-specific context that don't apply to the codebase as a whole.

Development best practices

• At each point where you have the next stage of the application, pause and let the user play around with things.
• Commit when you reach logical stopping points; use /commit for conventions.
• Write the code as well factored and human readable as you possibly can.
• When running tests directly: go test -shuffle=on ./... (all packages, shuffled, no -v).
• Run long commands (go test, go build) in the background so you can continue working while they execute.
• Every so often, take a breather and find opportunities to refactor code and add more thorough tests.
• "Refactoring" includes all code in the repo: Go, JS/CSS in docs/layouts/index.html, Nix expressions, CI workflows, Hugo templates, etc. Don't skip inline <script> blocks in HTML just because they're not .go.

When you complete a task, pause and wait for the developer's input before continuing on. Be prepared for the user to veer off into other tasks. That's fine, go with the flow and soft nudges to get back to the original work stream are appreciated.

Once allowed to move on, use /commit to commit the current change set.

For big or core features and key design decisions, write a plan document in the plans/ directory (e.g. plans/row-filtering.md) before doing anything. These are committed to the repo as permanent design records -- not throwaway scratch. Name the file after the feature or decision. Be diligent about this.

Never delete plan or spec files. They are permanent design records. Design specs also belong in plans/, not in docs/ (which is the Hugo site and would be publicly rendered).

Session log

Session history is in the git log.

Remaining work

Work items are tracked as GitHub issues.