diff --git a/Agent.md b/Agent.md new file mode 100644 index 0000000..40f112c --- /dev/null +++ b/Agent.md @@ -0,0 +1,78 @@ +# Working in this repository + +Treat the repository's code, tests, documentation, build configuration, and +existing conventions as the source of truth. Read nearby files before changing +them, prefer established patterns over introducing parallel ones, and keep the +work limited to the user's request. + +## Before editing + +1. Find the repository boundary and read any more specific agent instructions. +2. Check the worktree status and preserve all pre-existing changes, including + staged changes and untracked files. +3. Identify the smallest set of files that owns the requested behavior and the + narrowest useful checks for it. +4. Note whether the change crosses repository, package, service, or public + interface boundaries. Keep independently versioned repositories separate. + +Do not perform unrelated cleanup, refactoring, dependency upgrades, formatting +sweeps, or generated-file refreshes merely because they are convenient. Never +discard, overwrite, or include unrelated user work in a commit. + +## Implementation and verification + +- Make the smallest coherent change that fully implements the requested + behavior. +- Match the surrounding architecture, naming, style, error handling, and test + organization. +- Add or update focused tests with behavior changes. Prefer the closest existing + test location over new infrastructure. +- Treat external input and process, network, filesystem, and serialization + boundaries as fallible. Return actionable errors without exposing secrets. +- Use the project's declared toolchain and lockfiles. Do not install into the + system environment or add dependencies when existing tools are sufficient. +- Run focused checks while iterating, then the relevant formatter, tests, + linter, build, and documentation checks before handoff. +- Do not claim a check passed when it was skipped, unavailable, or only partly + run. Record limitations explicitly. + +## Small, reviewable commits + +Small commits are part of the deliverable, not optional cleanup at the end. + +- Commit each completed logical change as soon as it is coherent and its + relevant checks pass. +- Give every commit one clear purpose. Do not combine a feature, unrelated + cleanup, dependency churn, and formatting changes in one commit. +- Keep every commit buildable and independently reviewable whenever the project + permits it. Tests and documentation required by a behavior change belong in + the same commit as that behavior. +- Split work at natural boundaries rather than by file count. A small coherent + cross-file change is better than several incomplete file-by-file commits. +- When multiple repositories are involved, create separate commits in each + repository. Never create a cross-repository commit or hide one repository's + incomplete state behind another's commit. +- Stage files explicitly and inspect the staged diff before committing. Never + sweep pre-existing or unrelated changes into the task commit. +- Follow the repository's existing commit-message convention. If none is + documented, use a short imperative subject describing the outcome. +- Use additive history. Do not amend, squash, rebase, reset, force-push, or + otherwise rewrite existing commits unless the user explicitly requests it. +- Do not push, publish, tag, create a release, or modify remotes unless the user + explicitly requests that external action. + +Unless the user or a higher-priority instruction says not to commit, completing +an in-scope repository change includes creating the focused commit or commits. +Do not leave finished work only in the worktree. If a coherent commit cannot be +created, explain the exact blocker instead of making a knowingly broken +checkpoint commit. + +## Handoff + +Before reporting completion: + +1. Review the final diff for accidental churn, generated artifacts, secrets, + debug output, and changes outside the requested scope. +2. Verify each created commit and check the final worktree status. +3. Report the changed behavior, checks actually run, commit IDs, and any + remaining limitations or intentionally uncommitted pre-existing work. diff --git a/README.md b/README.md index a477f02..6f1e6c1 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,12 @@ Reusable task briefs for coding agents. Each brief captures a repeatable change, its constraints, and the checks needed before handoff, so project-specific work does not have to start from an improvised prompt. +[`Agent.md`](Agent.md) is a generic repository instruction template. Its main +workflow is to preserve existing work, make narrowly scoped changes, verify +them, and record completed units in small, independently reviewable commits. +Copy it into a repository and add that project's architecture, toolchain, +commands, and domain-specific constraints. + ## Available tasks - [`ci-coverage-badges.task.md`](tasks/ci-coverage-badges.task.md) adds