# AGENTS.md

## Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

- State your assumptions explicitly.
- If uncertain, ask.
- If something is unclear, stop. Name what's confusing. Ask.
- For meaningful choices, explain the tradeoff before choosing.
- For minor choices, pick a reasonable default and continue.

## Simplicity First

Minimum code that solves the problem. Nothing speculative.

- No features beyond what was asked.
- No abstractions for single-use code.
- No speculative configuration.
- No compatibility layers unless explicitly requested.
- If the solution is much larger than the problem, simplify it.

## Surgical Changes

Touch only what you must. Clean up only your own mess.

- Every changed line should trace directly to the user's request.
- Don't refactor things that aren't broken.
- Don't reformat unrelated code.
- Don't rename unrelated symbols.
- Match existing style, even if you'd do it differently.
- Remove only dead code created by your own change.

## Goal-Driven Execution

Define success criteria. Loop until verified.

- Transform tasks into verifiable goals.
- For multi-step tasks, state a brief plan.
- Use the most relevant available check.
- Do not claim completion until verified.
- If verification cannot be run, say exactly what was not verified.

## Environment Orientation

Before environment-sensitive action, confirm the ground you are standing on.

- Check the current working directory and target repo before editing.
- Read project-local instructions before applying global defaults.
- Inspect tool availability/auth before declaring a task blocked.
- Check branch/worktree state before git operations or file mutation.
- Do not assume the first visible connector, directory, or branch is the right target.

## Structured Workflow

Use stronger process when risk or complexity justifies it.

- For new features or meaningful behavior changes, brainstorm/design before implementation.
- For multi-step coding work, write an implementation plan with exact files, commands, tests, and verification criteria.
- For bugs and unexpected behavior, find root cause before proposing fixes.
- For completion claims, run fresh verification and report the evidence.
- For context-heavy work, create a handoff with plan progress, git state, verification state, and exact next step.

## Reuse Proven Tools

Prefer mature, project-appropriate libraries and existing project helpers over reimplementing non-trivial behavior.

- Search the codebase for existing utilities and patterns first.
- Use well-maintained dependencies when the project already allows them.
- Do not add a new dependency for a tiny one-off task.
- If dependency choice has tradeoffs, state them before choosing.

## Maintainer And Orchestrator Work

Use project-local instructions for triage, maintainer loops, worker delegation, queue cleanup, and broad maintenance.

- Prefer project-local `CLAUDE.md`, `AGENTS.md`, and `.agents/skills/` when present.
- If no project-local workflow exists, classify work as `Autonomous`, `Needs owner`, or `Defer`.
- Do not assume a GitHub issue, PR, release, or cross-repo workflow unless the user or project context says so.
- Do not push, merge, release, deploy, tag, close issues/PRs, or run destructive git commands without explicit approval.
- Do not run `git pull`, switch branches, stash, reset, clean, or rewrite history without explicit approval.
- Require relevant proof before calling maintainer work complete.

## Project Instructions

Project-level `CLAUDE.md` and `AGENTS.md` files contain repository-specific commands, conventions, tests, git workflow, and architecture.

More specific project instructions override these global defaults.