102 lines
4.7 KiB
Markdown
102 lines
4.7 KiB
Markdown
# Agent Policy
|
|
|
|
**Base Policy Version:** 1.3
|
|
|
|
**Last Updated**: 2026-09-28
|
|
**Upstream Source:** [Standard Repository Policies agents](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/agents.md)
|
|
|
|
## Purpose
|
|
|
|
Agents must read and follow these rules.
|
|
|
|
## Implementation Discipline
|
|
|
|
**KEY PRINCIPLES:** Write the simplest idiomatic code that satisfies the user's
|
|
request. Do not implicitly strengthen requirements, restrictions, or guarantees
|
|
beyond what the user actually requested.
|
|
|
|
**Keep implementation machinery proportionate.** Use straightforward,
|
|
idiomatic code and introduce only the machinery needed to support the requested
|
|
behavior and flexibility. Optimize for conceptual simplicity and
|
|
maintainability, not for the fewest lines, fewest options, or narrowest product
|
|
surface.
|
|
|
|
**Do not invent restrictions.** Do not reject, prohibit, constrain, cap,
|
|
harden, or otherwise narrow behavior unless required by the user, an explicit
|
|
repository contract, or an unavoidable correctness constraint. Preserve
|
|
operator and caller choice where policy has not been established. If an
|
|
additional restriction appears advisable, present it as a decision rather than
|
|
silently implementing it.
|
|
|
|
**Do not invent guarantees.** Do not strengthen public contracts, guarantees,
|
|
or invariants beyond those expressly requested by the user.
|
|
|
|
**Use the standard library.** For example: in almost every case, the best
|
|
approach to copying files is to use the standard library. Writing custom code to
|
|
implement power-loss protection at the application level, or to guard against
|
|
bad actors with privileged and concurrent access to the host's filesystem,
|
|
is wasteful, unnecessary, and not idiomatic. Stick to the simple, standard, and
|
|
idiomatic approach unless another path is expressly requested by the user.
|
|
|
|
**An implementation detail is not repository policy.** Tests and documentation
|
|
must not elevate incidental behavior into a durable guarantee or restriction
|
|
unless that behavior was expressly selected as part of the contract.
|
|
|
|
## Codebase Discovery
|
|
|
|
This project uses codebase-memory-mcp to maintain a knowledge graph of the
|
|
codebase. Always prefer its graph tools over grep, glob, or file search for code discovery.
|
|
If the project is not indexed, run `index_repository` first.
|
|
|
|
Use this order:
|
|
|
|
1. `search_graph` to find functions, classes, routes, and variables by pattern.
|
|
2. `trace_path` to trace callers and callees.
|
|
3. `get_code_snippet` to read a specific function or class.
|
|
4. `query_graph` for complex graph queries.
|
|
5. `get_architecture` for the high-level project summary.
|
|
|
|
Fall back to grep or glob for string literals, error messages, configuration
|
|
values, non-code files, or when the graph tools return insufficient results.
|
|
|
|
Examples:
|
|
|
|
- Find a handler: `search_graph(name_pattern=".*OrderHandler.*")`.
|
|
- Find callers: `trace_path(function_name="OrderHandler", direction="inbound")`.
|
|
- Read source: `get_code_snippet(qualified_name="pkg/orders.OrderHandler")`.
|
|
|
|
## Git Commit Policy
|
|
|
|
By default, commit each completed, nonempty unit of work using a
|
|
concise, plain-English message describing what changed. This policy is standing
|
|
authorization to create those local commits; a separate user request is not
|
|
required. An explicit user instruction to leave work uncommitted takes precedence.
|
|
|
|
A unit of work is a focused, reviewable outcome, including its relevant tests and
|
|
documentation.
|
|
Complete the appropriate validation before committing. If work is incomplete or
|
|
validation is blocked, report that state accurately.
|
|
|
|
Before committing:
|
|
|
|
1. Run `git status --short` and review the relevant diff, including any staged
|
|
changes. Identify changes that predate the current unit of work.
|
|
2. Exclude secrets, local environment files, generated junk, and unrelated changes.
|
|
3. Stage only the files or hunks belonging to the completed unit. Use `git add .`
|
|
only when every included change belongs to that unit. Preserve unrelated
|
|
staged and unstaged work.
|
|
4. Review `git diff --staged` and run appropriate checks for the change. Reuse
|
|
successful checks for unchanged content.
|
|
5. Review `git log --oneline -n 10` and use
|
|
`git commit -m "<concise plain-English commit message>"`.
|
|
6. Report the commit identifier and any remaining uncommitted work.
|
|
|
|
If the unit cannot be safely separated from pre-existing work, leave it uncommitted
|
|
and explain the overlap rather than silently including that work. If a commit
|
|
fails, preserve the changes and report the failure; do not bypass hooks.
|
|
|
|
Default commit authorization does not authorize pushing, publishing, amending,
|
|
resetting, reverting, or rewriting history. Those actions require a separate user
|
|
instruction. Do not use `git commit -a` or `git commit --no-verify` to bypass the
|
|
staging and validation discipline above.
|