seeklink AGENTS.md

Project conventions for AI coding agents

Core model

The source of truth is the repository and git history.

Sessions, chat context, local notes, and worktrees are convenience layers only. Important state must be recoverable from repo files or git history.

Keep this file short. Add rules only when they affect agent behavior or prevent repeated mistakes.

Start of session

Before editing:

1. Read docs/current_focus.md if it exists.
2. Check branch and git status.
3. Identify relevant verification commands.
4. For non-trivial changes, state the approach before writing code.

Do not rely on chat history as project memory.

Current focus

Use docs/current_focus.md for current work state only. Keep it under 30 lines.

It should contain:

• current task;
• branch;
• next concrete step;
• open questions;
• verification commands;
• at most the latest two handoff notes.

Rewrite stale content instead of appending indefinitely.

Handoff format:

Handoff (YYYY-MM-DD, Agent, branch)

Done: Open: Next: Status: <in progress / blocked / ready for review>

Do not create changelog, backlog, task tracker, memory, or per-agent state files unless explicitly requested.

History and decisions

Commit messages are the primary history layer.

Use commit bodies to explain why non-trivial changes were made.

Use docs/decisions.md only for decisions that remain active constraints on future work. Do not create it by default.

Decision docs are appropriate when a decision:

• spans multiple commits or subsystems;
• involves external context not visible in code;
• prevents a recurring wrong choice;
• affects public API, data model, deployment, security, or product behavior.

Do not mirror every commit into decision docs.

Agents may propose decision entries, but must not create or update long-lived decision records unless the human approves the decision text.

If docs/decisions.md grows beyond roughly 10 active decisions, propose moving to docs/decisions/YYYY-MM-DD-<slug>.md ADR files.