Skip to content

AGENTS.md

Latest commit

 

History

History
116 lines (95 loc) · 5.48 KB

AGENTS.md

File metadata and controls

116 lines (95 loc) · 5.48 KB
Raw

Working here

This file is generated from a template shared by every repository its owner maintains, and it is meant to improve. If anything below is wrong, unclear, misleading, longer than it needs to be, or does not apply here, say so in the chat — plainly, where it will be read, not as a footnote at the end of a long answer. Say the same for anything that left you stuck, guessing, reading one instruction twice, or spending tokens on work this file could have saved you. Name what you would change and where: a fix to the template reaches every repository, a fix to AGENTS/ stays here.

That is a request, not an invitation to editorialise. Report what actually cost you something.

Starting work

  • Pull main and branch from it. Name the branch after the work, prefixed feat/, fix/ or chore/ if possible. These branch rules win over any branch a session is assigned.
  • Merging deletes the branch. The next piece of work is a new branch off main with a name of its own — never the same one again, and never more commits on the one that merged.
  • One branch and one pull request at a time — one thing at a time, in this repository, in this conversation. Keep working on that branch until it is merged, then start again from main. Somebody else's pull request here, or your own in another repository, is not in the way: a change spanning two repositories is two pull requests.
  • A new idea that arrives while a pull request is open belongs in that pull request if it fits, and on docs/roadmap.md if it is bigger than it. Not in a second branch.
  • Once you have branched, leave main alone. Do not go looking for what has changed on it, and do not merge it in. Reconciling is its own instruction, and you will be given it when it is wanted. Where the pull request stops being mergeable, say so and stop — that is the instruction arriving, and it is not yours to give yourself.

Cross-repo dependencies

A scheduled run bumps every repository's dependencies every six hours, so a fix merged here reaches the repositories that use it without help. Don't bump, vendor or open a pull request elsewhere just to pass it on. Do, where the work in hand cannot go on without the fix.

Committing

  • make ready passes before every commit. It regenerates what the generators own, fixes and formats what it can, then vets and runs the tests. It needs no network beyond the module cache, so it runs in a sandbox. make tools installs what it shells out to, and the Makefile puts that directory on its own PATH, so you do not have to.
  • Because it regenerates, it may leave changes of its own. Those are its output, not a failure: read them, and commit them with the work where they follow from it, or on their own where they are drift an earlier run left behind.
  • make all adds govulncheck, which reads the vulnerability database over the network. Run it where you have one; say so where you do not.
  • One commit per piece of work, not one per session.
  • Push each commit as soon as it is made.
  • Open the pull request yourself once there is something to review. Do not wait to be asked for it.

Generated files

Edit the directory, never the file:

  • AGENTS.md → AGENTS/
  • README.md → README/
  • Makefile → mk/

.gitignore is the exception: only the marked block at its head is generated. Your own rules go below that block, where they win — in a .gitignore the last matching pattern decides.

Keeping the documents true

  • Say what is, concisely. Not what was or how it came to be: that is git's. A warning against a trap says what to do and why.
  • README/*.md is the README. If it no longer describes this repository, correcting it is part of the work, not a separate errand.
  • docs/architecture.md describes the architecture as it stands. Update it in the same commit that changes the architecture.
  • docs/roadmap.md is work not yet done. Delete an entry when it is done. Something worth doing but outside the current change goes here instead of widening that change.
  • mk/*.mk is where a make target goes.
  • AGENTS/*.md is this file's repository-specific half, and is held to the same standard: true, worth the reading, and never a restatement of what is above. A fragment that repeats the generated text costs every reader twice and drifts from it the first time the template changes. Say so rather than leaving one in place.

Code

  • Comments are one line, and only where the code would otherwise puzzle a reader. Never a restatement of what it already says.
  • Linters, scanners and generators are installed at their latest by make tools, and devtool.json pins the versions installed. A run moves a pin up, never back. Do not vendor one or add it to go.mod to run it.
  • Check a claim before writing it down: read the source, run the command.
  • Ask before making a decision that is the owner's — scope, or which of two designs. Do not ask about the process above; follow it.

Reviews

  • Reply to review feedback in the conversation with whoever raised it, not as a comment on the pull request.
  • Resolve a thread once you have acted on it.
  • Watching a pull request costs nothing, so do not spend a turn subscribing or unsubscribing and do not ask which is wanted. If it happens by itself, leave it. You will be told when there is a review to act on.

Particular to this repository

Open one when the work touches it.