From a94c3a42ff29dc9d98c8212af85c94e4897a786a Mon Sep 17 00:00:00 2001 From: "slominskir-coding-agent[bot]" <335168828+slominskir-coding-agent[bot]@users.noreply.github.com> Date: Sat, 17 Oct 2026 20:07:39 -0400 Subject: [PATCH] Carry the coding-agents shared rules in AGENTS.md AGENTS.md held a hand-made copy of the starter's generic rules, from before the starter had a versioned shared block, so it lacked the rules added since: task authorization, the Prepared-by footer on issues, the review conventions, and rewording the first message. Replace those generic rules with the shared rules block of coding-agents 6.1.0, between its markers, so later releases can replace it as a whole. Keep the project's own rules after it, under Project rules: the VERSION release rule, the organization project note, which checks a pull request waits for, and the gh 2.46 note. Add a line saying the shared rules' merge requests and pipelines are pull requests and their checks here. The Development section is unchanged except for the lines the block now covers (report what you ran, add tests with each change, never use production data, never commit secrets). Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 192 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 152 insertions(+), 40 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7c581aa..f2cda7c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,9 +6,6 @@ setting it up in an agent VM and where it stands on readiness for agents. ## Development -How to check your own work here. Check each change with these commands before you call it done, -fix what fails, and report what you ran and what it returned. - - Two Gradle subprojects: `smoothness-weblib`, the library (Java classes, JSP tags, and the JavaScript and CSS under `src/main/resources/META-INF`), and `smoothness-demo`, a web app that shows it off and is how you see a library change working. @@ -25,8 +22,7 @@ fix what fails, and report what you ran and what it returned. converters use the JVM's default time zone and locale. - The unit tests are characterization tests: they record what the code does now, quirks included (such as `isSameMonth` ignoring the year). When you change behavior on purpose, change - the test that records it and say so in the pull request. Add or update tests with each change, - check that a new test fails without your fix, and never skip or weaken a test to make it pass. + the test that records it and say so in the pull request. Test servlet code with `FakeRequest` (parameters and paths only), filters with `FakeHttp` (request, response, and chain), and settings with `TestSettings.cache`, rather than a mocking library. @@ -54,7 +50,7 @@ fix what fails, and report what you ran and what it returned. created (the demo's movies and the settings). `docker compose -f build.yaml down -v` deletes it; the next `up` rebuilds it. Each clone or worktree gets its own containers, named after its directory, but needs its own ports in a `.env` (see the README); a stack uses about 4 GB of - memory. Never use production data. + memory. - Accounts (Keycloak test realm, password `password`): `jdoe` and `tbrown` are admins (`smoothness-demo-admin`); `jadams` and `jsmith` are users. A login made before Keycloak is healthy gets a session without its roles: log in again. @@ -77,57 +73,173 @@ fix what fails, and report what you ran and what it returned. new version's files. - Schema and settings changes go in `container/oracle/initdb.d`; there are no migrations, so describe the SQL that existing databases need in the pull request. -- Never commit secrets. Local port settings go in `.env`, which git ignores. +- Local port settings go in `.env`, which git ignores. + + + +## Shared rules + +These rules are the same in every project that uses them. Where this file's other sections say +otherwise, follow those. + +### Checking your work + +- Check each change with the Development section's commands before you call it done, fix what + fails, and report what you ran and what it returned. +- Verify every change with checks appropriate to its behavior and regression risk. Add or update + tests where that risk warrants them; meaningful existing coverage can suffice. For bug fixes, + show the regression test fails without the fix and passes with it when practical; explain when + this cannot be shown. For documentation or formatting, check links, examples, or formatting + as applicable. Never skip or weaken a check merely to make it pass. +- For code with thin tests, use characterization tests where they help establish a baseline: + they record existing behavior, not necessarily correct behavior. Separate them into a test-only + merge request when risk or review needs warrant it; otherwise include them with the change. +- Never use production data, and never commit secrets. -## Commit identity +### Task authorization + +- Use the request and authorization already given in the session; do not ask again for an + authorized action. “Look around and suggest improvements” means investigate, run local + checks, and report; it does not authorize implementing or publishing the suggestions. +- An implementation request such as “Fix this bug” authorizes the local changes and verification + needed to finish it. Complete them; ask before a material expansion of scope. +- Commit and push only when asked. “Create a merge request for issue #14” also authorizes + implementation, verification, commits, pushing the branch, and opening the merge request. + A local implementation request alone does not. A request to address review on that merge + request authorizes the necessary follow-up commits and pushes. +- A requested review authorizes checks and posting findings as comments. Commit and push review + fixes only when asked; follow the review conventions below. +- Releases, deployments, production data changes, and settings changes in external systems need + authorization for the action and target environment. A request to implement a change or open + a merge request alone does not give it. Follow the project's release, issue-filing, and access + rules; never approve, merge, or enable auto-merge. +- Ask only when a consequential ambiguity remains; continue independent work within the + authorized scope while waiting. + +### Commit identity Commits written by an agent must say so. Before committing, check that the repository-local -identity (never `--global`) is that of the GitHub App bot you push with, so GitHub links the -commits to it and squash commits show the same name. Never commit under a person's name or -email. Name the agent and model in a trailer: keep the one your tool adds (such as +identity (never `--global`) is the bot's whose token you push with, so the Git host links the +commits to it and squash commits show the same name: + +```bash +git config user.name "" # e.g. " agent VM[bot]" +git config user.email "" +``` + +On GitLab, `glab api user` shows the bot's `name` and `username`, and the address is +`@noreply.` (for example `project_…_bot_…@noreply.code.jlab.org`). Never commit +under a person's name or email. Name the agent and model in a trailer on every agent-written +commit, including follow-up and reviewer commits: keep the one your tool adds (such as `Co-Authored-By`), or else add `Assisted-by: :`. -## Commits +### Commits - Imperative summary line, then a body explaining what changed and why. -- Squash merges use the commit messages: write the first one for `main`. +- Trailers come last, in one paragraph: the release trailers this file asks for, if any (such as + `Changelog:`), then tool-required ones, with no blank line between them. Git reads trailers + only from the last paragraph; check with + `git log -1 --format=%B | git interpret-trailers --parse`. +- The squash commit message template uses the first commit's message: write it for `main`, and + put release trailers on it only. Later commits, including a reviewer's, retain agent/model + attribution trailers but omit release trailers. Keep the first message current for the whole + change, preserving its attribution and adding any distinct agent/model attribution from later + commits so the squash credits them too. - Commit and push only when asked. -## Branches and pull requests +### Branches and merge requests - Start each task on a new branch from an up-to-date `main`; target `main`. Work only in your own clone or worktree. -- Label every pull request `source::ai`, and make the person who reviews it both reviewer and - assignee (ask for their username if you don't know it). In gh 2.46, `gh pr edit` fails; add - labels and retarget with `gh api` (see the coding-agents Git workflow guide's tool notes). -- You cannot add items to the JeffersonLab organization's project: when you report back, list - the pull requests and issues you opened, so the person can add them to the period's project. -- Never change `VERSION` unless asked: a change to it on `main` releases the project (tag, GitHub - release with the demo war, the weblib on Maven Central, the docs, the demo Docker image, and a - deploy to JLab's test server). When asked, open a pull request that changes only `VERSION`, - and write any upgrade steps in its description for the maintainer to add to the release. -- A person reviews and merges, and merged branches are deleted; never merge, approve, or enable - auto-merge yourself. -- Before pushing to a pull request's branch, check that it is still open: commits pushed after it - merged never reach `main`, so put them in a new pull request. -- To build on a pull request still in review, branch from its branch and target that branch, +- Label every merge request `source::ai`, and make the person who reviews it both reviewer and + assignee (ask for their username if you don't know it). +- Delete the source branch on merge. A person reviews and merges; never merge, approve, or + enable auto-merge yourself. +- Before pushing to a merge request's branch, check that it is still open: commits pushed after + it merged never reach `main`, so put them in a new merge request. +- To build on a merge request still in review, branch from its branch and target that branch, saying so in the description. Once the first merges, check that yours now targets `main`, and - retarget it if not. -- Describe what changed, any deployment steps, and the checks you ran, including what you could - not run. Add a short Decisions part when the person questioned or changed something, or when - alternatives were dropped. -- After pushing, wait for the pull request's checks to finish before reporting it ready (`build` - and `integration` from CI, and CodeQL; `integration` takes about 5 minutes); - `gh pr checks --watch` waits. Read failed jobs' logs and fix the - cause; never skip or weaken a check to pass it. Report how they ended, and say if one failed - for a reason outside your change. + retarget it if not: GitHub retargets it only if the merged branch was deleted. +- Describe what changed, any deployment steps, and the checks you ran. Add a short Decisions + part: what the person questioned or changed during the session, which alternatives were + dropped and why, and any second opinion that changed something. +- After pushing, wait for the merge request's pipeline to finish before reporting it ready. Read + failed jobs' logs and fix the cause; never skip or weaken a check to pass it. Report how it + ended, with its link, and say if it failed for a reason outside your change. On GitLab, + `glab mr view -F json | jq '.head_pipeline | {sha, status, web_url}'` shows it; plain + `glab ci status` can miss merge request pipelines, and `--live` waits only in a terminal. - Name the issue a change is for in the commit body: `Fixes #`, or `Part of #` if some of it stays open. Work you were asked to do needs no issue. +- For another GitLab project's issue or merge request, prefer `project#123` or + `project!456` with no space, when it resolves correctly from the current context. Check + the rendered link's destination before publishing. Otherwise use the full namespace path + or full URL; GitLab can display the URL as a reference. An explicit Markdown link can + use a concise label. `project #123` and + `project !456` link the bare number to the current project. Apply this to descriptions, + comments, commit messages, and documentation. + +### Issues + - For something outside your task (another project, code another agent is working on, or a change that needs a decision), don't fix it in passing: offer to open an issue, labeled `source::ai` and assigned to the person you work with, with what you found, the evidence, and a suggested fix. -- When asked to address a review, reply in each thread with what you changed, and push new - commits rather than rewriting ones already reviewed; the reviewer resolves the threads. +- File issues as the bot with `source::ai`, and end their descriptions (including planning + issues) with a plain-text `Prepared-by: :` footer, such as + `Prepared-by: OpenAI Codex:`, + `Prepared-by: Anthropic Claude Code:`, or + `Prepared-by: Google Gemini:`. Use the specific model identifier + when known; otherwise use the known model family (for example `GPT-6`), omitting unknown + variant or version details. Use `unavailable` only when neither is known; never guess. + Preserve existing footers; + for substantive analysis, proposed-change, or acceptance-criteria updates, append your own + if that vendor, agent, and model are not already credited. Routine metadata or formatting + edits need no new footer. +- When asked to plan work for other agents: check claims before filing, list draft issues before + filing them, make each one self-contained with "Done when" and what not to do, say which can + start now and which are blocked or share files, and ask before filing anything + security-sensitive (file it confidential). + +### Review + +- When asked to address a review, reply in each thread with what you changed, and push content + fixes as new commits; the reviewer resolves the threads. The author may reword only the first + message when its description, release metadata, or attribution needs updating. Coordinate + with anyone working on the branch, save the old tip, and keep the base, patches, and commit + order unchanged. Rewording changes descendant IDs too: check `git range-diff` between the old + and new series for only the intended message change, and `git diff HEAD` for no tree + change. Push with `--force-with-lease=refs/heads/:`; stop if the lease + fails. Report the old/new tips and message changes so the reviewer can compare patches. +- When asked to review a merge request, leave comments by default without asking which mode to + use. Commit and push fixes only when asked; coordinate with the author before pushing if they + are still working on the branch. Add one commit per recommendation on top of the author's + (never rewrite theirs), retaining your agent/model attribution but omitting release trailers + on follow-up commits. Then post one comment listing each commit, what you tested, that the + author must pull, and any first-message update needed for the whole change or squash + attribution. Never approve, merge, or resolve threads. - When the person corrects you on something any agent here should know, propose adding it to - this file, or better a check that catches it. Keep one developer's preferences out of it. + this file's project rules, or better a check that catches it. Keep one developer's preferences + out of it. + + + +## Project rules + +### GitHub + +This project is on GitHub: where the shared rules say merge request, read pull request, and for +its pipeline, its checks: `build` and `integration` from CI, and CodeQL (`integration` takes +about 5 minutes; `gh pr checks --watch` waits). In gh 2.46, `gh pr edit` fails; add +labels and retarget with `gh api` (see the coding-agents Git workflow guide's tool notes). + +### Releases + +Never change `VERSION` unless asked: a change to it on `main` releases the project (tag, GitHub +release with the demo war, the weblib on Maven Central, the docs, the demo Docker image, and a +deploy to JLab's test server). When asked, open a pull request that changes only `VERSION`, and +write any upgrade steps in its description for the maintainer to add to the release. + +### GitHub organization project + +You cannot add items to the project: when you report back, list the pull requests and issues you +opened, so the person can add them to the period's project.