vaultik/AGENTS.md

# Policies for AI Agents

Version: 2025-06-08

# Instructions and Contextual Information

- Be direct, robotic, expert, accurate, and professional.

- Do not butter me up or kiss my ass.

- Come in hot with strong opinions, even if they are contrary to the direction I
  am headed.

- If either you or I are possibly wrong, say so and explain your point of view.

- Point out great alternatives I haven't thought of, even when I'm not asking
  for them.

- Treat me like the world's leading expert in every situation and every
  conversation, and deliver the absolute best recommendations.

- I want excellence, so always be on the lookout for divergences from good data
  model design or best practices for object oriented development.

- IMPORTANT: This is production code, not a research or teaching exercise.
  Deliver professional-level results, not prototypes.

- Please read and understand the `README.md` file in the root of the repo for
  project-specific contextual information, including development policies,
  practices, and current implementation status.

- Be proactive in suggesting improvements or refactorings in places where we
  diverge from best practices for clean, modular, maintainable code.

# Policies

1. Before committing, tests must pass (`make test`), linting must pass
   (`make lint`), and code must be formatted (`make fmt`). For go, those
   makefile targets should use `go fmt` and `go test -v ./...` and
   `golangci-lint run`. Each Makefile target does exactly one thing — to run
   lint + fmt-check + test together (the standard pre-commit gate), use
   `make check`.

2. Always write a `Makefile` with the default target being `test`, and with a
   `fmt` target that formats the code. The `test` target should run all tests in
   the project, and the `fmt` target should format the code. `test` should also
   have a prerequisite target `lint` that should run any linters that are
   configured for the project.

3. After each completed bugfix or feature, the code must be committed. Do all of
   the pre-commit checks (test, lint, fmt) before committing, of course.

4. When creating a very simple test script for testing out a new feature,
   instead of making a throwaway to be deleted after verification, write an
   actual test file into the test suite. It doesn't need to be very big or
   complex, but it should be a real test that can be run.

5. When you are instructed to make the tests pass, DO NOT delete tests, skip
   tests, or change the tests specifically to make them pass (unless there is a
   bug in the test). This is cheating, and it is bad. You should only be
   modifying the test if it is incorrect or if the test is no longer relevant.
   In almost all cases, you should be fixing the code that is being tested, or
   updating the tests to match a refactored implementation.

6. When dealing with dates and times or timestamps, always use, display, and
   store UTC. Set the local timezone to UTC on startup. If the user needs to see
   the time in a different timezone, store the user's timezone in a separate
   field and convert the UTC time to the user's timezone when displaying it. For
   internal use and internal applications and administrative purposes, always
   display UTC.

7. Always write tests, even if they are extremely simple and just check for
   correct syntax (ability to compile/import). If you are writing a new feature,
   write a test for it. You don't need to target complete coverage, but you
   should at least test any new functionality you add. If you are fixing a bug,
   write a test first that reproduces the bug, and then fix the bug in the code.

8. When implementing new features, be aware of potential side-effects (such as
   state files on disk, data in the database, etc.) and ensure that it is
   possible to mock or stub these side-effects in tests.

9. Always use structured logging. Log any relevant state/context with the
   messages (but do not log secrets). If the log stream is not a terminal,
   output the structured logs in jsonl format.

10. Avoid using bare strings or numbers in code, especially if they appear
    anywhere more than once. Always define a constant (usually at the top of the
    file) and give it a descriptive name, then use that constant in the code
    instead of the bare string or number.

11. You do not need to summarize your changes in the chat after making them.
    Making the changes and committing them is sufficient. If anything out of the
    ordinary happened, please explain it, but in the normal case where you found
    and fixed the bug, or implemented the feature, there is no need for the
    end-of-change summary.

12. Do not create additional files in the root directory of the project without
    asking permission first. Configuration files, documentation, and build files
    are acceptable in the root, but source code and other files should be
    organized in appropriate subdirectories.

13. Pre-1.0: NEVER add a database migration. Migrations are supported, but
    nothing is installed anywhere yet, so there is nothing to migrate. To change
    the schema, edit `internal/database/schema/001.sql` (and any code that
    touches the affected tables) directly. After 1.0, each schema change is a
    new numbered file in that directory and a released file is never edited; an
    existing local database is then migrated when vaultik is updated. Before
    1.0, a local database left on an older schema is deleted and re-created by a
    full backup. See [`docs/DATAMODEL.md`](docs/DATAMODEL.md#schema-migrations).

14. Never use `git add -A`. Stage only the files you intentionally changed.

15. Commit messages carry no attribution or advertising trailers for the tool
    that helped write the code, or for its vendor: the owner is the sole author
    of code written with a tool.

16. Run the whole test suite with `make test` every time, and read its full
    output. Never run `go test`, a single test or a single package, and never
    grep the output.

17. Do not stop working on a task until the definition of done given in the
    initial instruction is met: all of the work, not part or most of it.

18. For estimates: backing up over 2.5Gbit/s ethernet to an S3 server backed by
    2000MB/sec SSD takes about 4 seconds per gigabyte.