walkup/AGENTS.md

AGENTS.md

This file gives general operating guidance for coding agents working in this repository.

Core Principles

• Prefer simple, maintainable solutions over clever ones.
• Preserve existing behavior unless the task explicitly requires a change.
• Make the smallest reasonable change that fully solves the problem.
• Keep code readable: clear names, straightforward control flow, and minimal indirection.
• Treat tests, types, and linting as part of the implementation, not as optional cleanup.
• Work in small, coherent increments that can be verified and committed cleanly.

Before Making Changes

• Inspect the relevant files and local patterns before editing.
• Identify the narrowest safe change surface.
• Check whether there are existing tests, scripts, or conventions to follow.
• Do not assume missing context; infer from the codebase first.

Repo State Preflight

• Before starting work, inspect git status --short.
• Treat pre-existing dirty files as user-owned by default.
• Do not include pre-existing user edits in agent commits unless explicitly approved.
• If requested work overlaps with user-owned uncommitted files, pause and ask how to proceed.
• Encourage the user to commit or stash their work before continuing when appropriate.

Implementation Guidance

• Match the style and structure already used in the repository.
• Avoid broad refactors unless necessary to complete the task.
• Add comments only where intent would otherwise be unclear.
• Prefer explicit, simple code over premature abstraction.
• Keep public APIs, file layouts, and naming stable unless the task calls for a change.

Testing Expectations

• Create or update tests for every non-trivial behavior change.
• Prefer tests that prove user-visible or contract-level behavior.
• Run relevant tests frequently while working.
• After each meaningful change, run the smallest test scope that gives fast feedback.
• Before finishing, run broader verification for the touched area.
• If a change cannot be tested automatically, state that clearly.

Safety Rules

• Never overwrite or revert user changes unless explicitly asked.
• Avoid destructive commands unless clearly requested.
• Call out assumptions when they materially affect behavior.
• If you find unrelated problems, note them separately.

Verification

• Run the smallest relevant verification after making changes.
• If tests or checks cannot be run, say so explicitly.
• Verify both the happy path and the most likely failure path when possible.

Documentation

• Re-read AGENTS.md, PLAN.md, and relevant files in docs/ before planning or implementing.
• Update docs/ when behavior, structure, or standards change.
• Update PLAN.md when work is completed, deferred, or split into follow-up work.
• Do not consider work complete until code and docs are aligned.

Commit Discipline

• Commit work in logical, reviewable increments.
• Prefer a commit after each completed unit of work that passes verification.
• Keep commits focused; avoid mixing unrelated changes.
• Use clear commit messages describing behavior or intent.
• Do not commit broken work unless explicitly requested.

Branch Discipline

• Do new feature work on a dedicated branch.
• Use a distinct branch per feature, fix, or scoped task.
• Start new work from dev unless specified otherwise.
• Keep branch names descriptive and scoped.
• Do not carry unrelated uncommitted changes across branches.
• Merge completed feature branches into dev after verification.
• Reserve main for release-ready code.

AI Metadata

• Keep purely agent-only working notes on the ai branch unless specified otherwise.
• Do not mix AI metadata commits with application feature commits.
• If a file is required for active repo guidance, keep it in the working branch.

Agent Identity

• Use a dedicated Git author identity for AI-created commits.
• Default agent identity:
  • Name: Codex
  • Email: codex@local
• Prefer per-commit identity flags:
  • git -c user.name="Codex" -c user.email="codex@local" commit ...
• Do not change the user's global Git identity.

Commit Ownership

• The user and agents use separate Git identities.
• Only agent-authored changes should be included in agent commits.
• Do not include pre-existing user edits in agent commits unless explicitly approved.
• If overlap exists, pause and ask before proceeding.

Release And Versioning

• Treat dev as the active integration branch.
• Merge dev into main only for releases.
• Bump versions only during release preparation unless instructed otherwise.
• Keep version changes grouped into release commits.
• Tag releases from main when applicable.

Communication

• Be concise and concrete.
• Summarize what changed, why, and how it was verified.
• Surface risks, tradeoffs, and follow-up work clearly.

Scope

• This file is intentionally general.
• Add stack-specific or workflow-specific guidance as the repository grows.