diff --git a/.agents/review/README.md b/.agents/review/README.md new file mode 100644 index 0000000..b00a5b9 --- /dev/null +++ b/.agents/review/README.md @@ -0,0 +1,102 @@ +# AI review + +The author of a pull request reviews the branch with an AI agent before asking people to review it, fixes what the review finds or dismisses it with a reason, and says so in the pull request's "AI Review" section. The people who review the pull request then look at what an AI cannot judge, and do not run it through an AI themselves ("Working with it" below). + +It works the same in every agent: the same prompts, the same record. The reviewers always start in a fresh context, without the conversation that produced the change, on a model no weaker than the author's ("Fresh reviewers" in `review.md`). The agent that wrote the change only takes their findings and settles them with the user. + +These files come from the `ai-review` pack of your organisation's engineering-assets hub. + +| File | What | +|---|---| +| [`review.md`](review.md) | the review: scope, directions, verifying and ranking findings, the record | +| [`directions/`](directions/) | one prompt per direction: what to look for and what counts as evidence | +| [`pure-refactor.md`](pure-refactor.md) | a check that a change claimed to keep behaviour keeps it | +| [`check.py`](check.py) | says whether the branch's review covers its last commit; a pre-push hook runs it | + +## Directions + +| Direction | Looks for | +|---|---| +| [Correctness](directions/correctness.md) | logic errors, edge inputs, swallowed and unnoticed errors, races, transactions, resources | +| [Security](directions/security.md) | secrets, injection, access checks, data exposure, insecure defaults, new dependencies | +| [Performance](directions/performance.md) | N+1 and unbounded queries, blocking calls in async code, work that grows with the data | +| [Design & Style](directions/design.md) | why each new thing exists, what already exists, layers, simplicity, naming, comments | +| [Tests](directions/tests.md) | new behaviour without a test, tests that check nothing, tests bent to fit | +| [Compatibility](directions/compatibility.md) | API and schema contracts, migrations, rollout, stored data, configuration, flags, stale docs | + +A repository adds its own focus areas in a `## Review` section of `.agents/project.md`, one line each: `- : `. A name that is none of the directions above becomes a direction of its own, with its own line in the pull request. + +## Running it + +The agent runs the review by itself once the last change of a task is committed (`AGENTS.md`), so nobody has to remember. Unlike the starter review, it is not read-only: it writes the record in `local/`, and the agent then fixes the findings the user agrees with. By hand: + +| Agent | Review | Pure-refactor check | +|---|---|---| +| Claude Code | `/review-change` | `/review-change pure-refactor` | +| Codex | `$review-change` | `$review-change pure-refactor` | +| Cursor | `/review-change` | `/review-change pure-refactor` | +| OpenCode | "review my branch" | "check that my branch keeps behaviour" | +| any chat | paste `review.md`, the direction files and `git diff ...HEAD` (`` as in `review.md`) | paste `pure-refactor.md` and the diff | + +The request may name directions (`/review-change security performance`), ask for `full` (the whole branch again, not a follow-up over the changes since the last review), or give `staged`, `working` or a path. + +The skill is `.agents/skills/review-change/`, where Codex, Cursor and OpenCode find it. In Claude Code, `/review-change` of the `claude` pack follows it whenever this directory exists, and the `reviewer` subagent is the fresh reviewer it starts for each direction. + +## The record + +Every run updates the branch's one record, `local/reviews/.md` (`local/` is gitignored): the commit the last complete run covered, the reviewers' model, the result per direction and each finding with its status: fixed, dismissed with the reason, or open. The next run reviews only what changed since that commit and does not bring back what was dismissed. The format is in [`review.md`](review.md). + +## In the pull request + +The description ends with an "AI Review" section, built from the record and nothing else, in the language `.agents/project.md` names for pull requests. With the `claude` pack, `/pr` adds it. Put the section into the repository's pull request template, so that people see it is expected: + +```markdown +#### AI Review + +Commit `a1b2c3d`, Claude Opus 5.5 + +- [x] Correctness - 2 fixed +- [x] Security - no findings +- [x] Performance - 1 fixed, 1 dismissed +- [x] Design & Style - 3 fixed +- [x] Tests - no findings +- [x] Compatibility - not applicable: no API, schema or configuration change + +
Dismissed (1) + +- `src/keys.py:42` - N+1 when loading keys: the list holds at most 5 keys +
+``` + +- The first line is the record's `commit` (short sha) and `model`. When the user declined a follow-up over later fixes, it adds ", fixes after it not reviewed again". +- One line per direction of the record, in its order and under its name, the repository's own directions and Pure-refactor check included. A direction that was not run is unchecked: `- [ ] Tests - not run`. +- The block of dismissed findings lists each dismissed blocking or should-fix finding with its reason; no dismissed findings, no block. Nits never go there, and a finding about a secret names its place and kind, never the value. + +## Working with it + +- **The AI review is the author's job.** Before the pull request is opened for review (a draft opened only so that CI runs is not), the author reviews the branch, fixes what the review finds or dismisses it with a reason, and fills the "AI Review" section. A pull request without it, or with its boxes unchecked, is not ready for review. After the fixes, and after changes made in review, the author runs a follow-up on the new commits: it checks the fixes and the lines they touched, not the whole branch again. Commits that only fix findings may go without one: the author's call, and the section says so. +- **People review what an AI cannot judge**: does the change solve the task, are the model and the contracts right, is the rollout plan right, what does it do to its neighbours, will the next person understand it, and are the dismissed findings fair. +- **No AI-generated comments on someone else's pull request.** Do not run a colleague's change through an AI and post what it says. Using an AI to understand the code is fine; the comment is your own. +- **A bug the AI review should have caught** gets a review thread that starts with `ai-miss:`. Besides the fix, the author turns the miss into a rule where the review reads it, and links it in the reply: a line in the `Review` section of `.agents/project.md` if it is about this repository, otherwise a pull request or an issue to the hub on `packs/ai-review/.agents/review/directions/`. + +## Wiring + +Optional, once per repository, in its own files, in a pull request merged after the sync pull request that brings `.agents/review/`: until then the hook finds no script and fails every push. `check.py` needs Python 3.9 or later and only its standard library, so it runs in a repository of any language. + +- A pre-push hook in `.pre-commit-config.yaml`. It never blocks a push, since unfinished branches are pushed to run CI, and only says when the review is missing or behind the branch: + + ```yaml + - repo: local + hooks: + - id: ai-review + name: ai review + entry: python .agents/review/check.py + language: python + pass_filenames: false + always_run: true + verbose: true + stages: [pre-push] + ``` + +- The way the repository installs its hooks installs `pre-push` too. Plain `pre-commit install` does once `default_install_hook_types` lists it (with `commit-msg` where a hook needs it); a README or Makefile that names hook types needs `--hook-type pre-push`. Where `pre-push` was not installed before, `default_stages: [pre-commit]` keeps the other hooks on commit instead of running them again on push; a repository whose hooks already run on push keeps them as they are. Hooks that declare their own stages, such as `trailing-whitespace` and `end-of-file-fixer` from pre-commit-hooks, run on push as well. After the change, everyone installs the hooks once more. +- Without pre-commit, a `.git/hooks/pre-push` that runs `python .agents/review/check.py` does the same for one clone, but it checks the checked-out branch, which a plain `git push` pushes; pre-commit tells it the branch being pushed. diff --git a/.agents/review/check.py b/.agents/review/check.py new file mode 100644 index 0000000..fcbc82a --- /dev/null +++ b/.agents/review/check.py @@ -0,0 +1,234 @@ +""" +Tells whether the AI review of a branch covers its last commit, from the record the review writes to +local/reviews/.md (see README.md next to this file). + + check.py say whether the review is missing or behind the branch; always exit 0 + check.py --strict the same, but exit 1 unless the branch is reviewed up to its last commit + check.py --refresh when a rebase left the reviewed changes as they were under new commits, + move the record's commit to them + +As the pre-push hook it checks the branch being pushed and never blocks the push: unfinished branches +are pushed to run CI. By hand it checks the branch checked out. + +Only the standard library: it runs from pre-commit in a repository of any language. +""" + +from __future__ import annotations + +import argparse +import codecs +import hashlib +import os +import re +import shutil +import subprocess +import sys +from dataclasses import dataclass +from pathlib import Path + +RECORDS = Path("local", "reviews") +COMMIT = re.compile(r"^commit:[ \t]*([0-9a-f]{7,64})[ \t]*(?=\r?$)", re.MULTILINE) +# agents write the record in UTF-8; PowerShell 5.1 redirection writes UTF-16 +BOMS = ((codecs.BOM_UTF16_LE, "utf-16"), (codecs.BOM_UTF16_BE, "utf-16"), (codecs.BOM_UTF8, "utf-8-sig")) +# the diffs are read by this script, not a person: no colour, external diff or textconv a config may turn on +PLAIN_DIFF = ("diff", "--no-color", "--no-ext-diff", "--no-textconv") +HUNK_LINES = re.compile(rb"^@@ -\d+(?:,\d+)? \+\d+(?:,\d+)? @@") +HOW = ( + "run it in your agent (/review-change, $review-change; .agents/review/README.md)" + " before opening or updating the pull request" +) + +REVIEWED, BEHIND, SKIPPED = "reviewed", "behind", "skipped" + + +@dataclass(frozen=True) +class Branch: + name: str + head: str + base: str | None + top: Path + + +@dataclass(frozen=True) +class Record: + path: Path + text: str + codec: str | None + + +def main() -> int: + parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) + parser.add_argument( + "--strict", action="store_true", help="exit 1 unless the branch is reviewed up to its last commit" + ) + parser.add_argument( + "--refresh", action="store_true", help="move the record's commit to the same changes under new commits" + ) + args = parser.parse_args() + + try: + status, message = check(refresh=args.refresh) + except Exception as error: # noqa: BLE001, RUF100 - the hook must never block a push, so a broken check only says so + status, message = BEHIND, f"AI review: the check failed: {error!r}" + if status == SKIPPED and not args.strict: + return 0 + sys.stdout.write(message + "\n") + return 1 if args.strict and status != REVIEWED else 0 + + +def check(*, refresh: bool) -> tuple[str, str]: + branch, skipped = branch_to_check() + if branch is None: + return SKIPPED, skipped + relative = RECORDS / f"{branch.name}.md" + path = branch.top / relative + if not path.is_file(): + return BEHIND, f"AI review of {branch.name}: not run yet; {HOW}" + record = Record(path, *read_record(path)) + reviewed, missing = reviewed_commit(record.text, relative) + if reviewed is None: + return BEHIND, f"AI review of {branch.name}: {missing}; {HOW}" + if reviewed == branch.head: + return REVIEWED, f"AI review: {branch.name} is reviewed up to its last commit" + if git("merge-base", "--is-ancestor", reviewed, branch.head) is not None: + return since_review(branch, reviewed) + return after_rewrite(branch, reviewed, record, refresh=refresh) + + +def branch_to_check() -> tuple[Branch | None, str]: + """The branch to check, or none and why it is skipped.""" + top = git("rev-parse", "--show-toplevel") + if top is None: + return None, "AI review: not in a git work tree, or git is missing" + name, head = pushed_branch() + if name is None or head is None: + return None, "AI review: no branch to check (detached HEAD)" + base = base_ref() + if name in default_names(base): + return None, f"AI review: {name} is the default branch" + return Branch(name, head, base, Path(top)), "" + + +def reviewed_commit(text: str, relative: Path) -> tuple[str | None, str]: + """The commit the record names, or none and what is wrong with the record.""" + found = COMMIT.search(text) + if found is None: + return None, f"{relative.as_posix()} names no commit" + reviewed = git("rev-parse", "--verify", "--quiet", f"{found.group(1)}^{{commit}}") + if reviewed is None: + return None, f"the reviewed commit {found.group(1)[:8]} is not in this clone" + return reviewed, "" + + +def since_review(branch: Branch, reviewed: str) -> tuple[str, str]: + changed = branch_files_changed(reviewed, branch.head, branch.base) + if not changed: + return REVIEWED, f"AI review: {branch.name} is reviewed; nothing of its own changed since {reviewed[:8]}" + return ( + BEHIND, + f"AI review of {branch.name}: {len(changed)} file(s) changed since the review at {reviewed[:8]}; {HOW}", + ) + + +def after_rewrite(branch: Branch, reviewed: str, record: Record, *, refresh: bool) -> tuple[str, str]: + # a rebase keeps the reviewed changes under new commits: compare the changes, not the commits + if branch.base is None or not same_changes(reviewed, branch.head, branch.base): + return ( + BEHIND, + f"AI review of {branch.name}: rewritten since the review at {reviewed[:8]}, with other changes; {HOW}", + ) + if refresh and record.codec is not None: + record.path.write_bytes(COMMIT.sub(f"commit: {branch.head}", record.text, count=1).encode(record.codec)) + return ( + REVIEWED, + f"AI review: {branch.name} carries the reviewed changes; the record now names {branch.head[:8]}", + ) + return REVIEWED, f"AI review: {branch.name} carries the changes reviewed at {reviewed[:8]} under new commits" + + +def pushed_branch() -> tuple[str | None, str | None]: + local = os.environ.get("PRE_COMMIT_LOCAL_BRANCH") + if local: + # pre-commit's pre-push: the branch being pushed and its sha, which need not be the checked-out ones + head = os.environ.get("PRE_COMMIT_TO_REF") or git("rev-parse", "--verify", "--quiet", local) + if not local.startswith("refs/heads/"): + # `git push origin HEAD` names no branch: it is the checked-out one when the shas agree + if head is None or head != git("rev-parse", "--verify", "--quiet", "HEAD"): + return None, None + local = git("symbolic-ref", "--quiet", "HEAD") + if not local: + return None, None + return local.removeprefix("refs/heads/"), head + ref = git("symbolic-ref", "--quiet", "HEAD") + if not ref: + return None, None + return ref.removeprefix("refs/heads/"), git("rev-parse", "--verify", "--quiet", ref) + + +def base_ref() -> str | None: + named = git("symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD") + candidates = [named] if named else ["origin/master", "origin/main"] + return next((ref for ref in candidates if git("rev-parse", "--verify", "--quiet", ref)), None) + + +def default_names(base: str | None) -> set[str]: + names = {"master", "main"} + if base: + names.add(base.split("/", 1)[-1]) + return names + + +def read_record(path: Path) -> tuple[str, str | None]: + """The record's text and the codec to write it back with; no codec when it is not UTF-8 or UTF-16.""" + raw = path.read_bytes() + for bom, codec in BOMS: + if raw.startswith(bom): + return raw.decode(codec, errors="replace"), codec + try: + return raw.decode("utf-8"), "utf-8" + except UnicodeDecodeError: + return raw.decode("utf-8", errors="replace"), None + + +def same_changes(reviewed: str, head: str, base: str) -> bool: + before = changes_id(reviewed, base) + return before is not None and before == changes_id(head, base) + + +def changes_id(commit: str, base: str) -> str | None: + fork = git("merge-base", base, commit) + if fork is None: + return None + diff = run(*PLAIN_DIFF, fork, commit) + if not diff: + return None + # on a new base the same changes differ only in blob ids and line numbers; whitespace and context + # lines still count, so a re-indented or moved line is a change to review again + lines = [HUNK_LINES.sub(b"@@", line) for line in diff.split(b"\n") if not line.startswith(b"index ")] + return hashlib.sha256(b"\n".join(lines)).hexdigest() + + +def branch_files_changed(reviewed: str, head: str, base: str | None) -> set[str]: + changed = set((git(*PLAIN_DIFF, "--name-only", reviewed, head) or "").splitlines()) + if base is None: + return changed + # a merge of the default branch brings other people's changes: only the branch's own files count + own = set((git(*PLAIN_DIFF, "--name-only", f"{base}...{head}") or "").splitlines()) + return changed & own + + +def git(*args: str) -> str | None: + output = run(*args) + return None if output is None else output.decode("utf-8", errors="replace").strip() + + +def run(*args: str) -> bytes | None: + executable = shutil.which("git") + if not executable: + return None + result = subprocess.run([executable, *args], capture_output=True, check=False) # noqa: S603, RUF100 + return result.stdout if result.returncode == 0 else None + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/.agents/review/directions/compatibility.md b/.agents/review/directions/compatibility.md new file mode 100644 index 0000000..e496d61 --- /dev/null +++ b/.agents/review/directions/compatibility.md @@ -0,0 +1,22 @@ +# Compatibility + +What does the change do to those who already depend on this code: the clients of its API, other services, the data already stored, the running deployments and those who keep them up, the people who read the docs? A change can be right and still break them on the day it ships. + +## Look for + +- **API and messages**: a field removed, renamed or retyped, a new required field, a changed default, status code or error format, a message or event schema others consume. Who consumes it: see the docs and the repository's notes for agents. If the change breaks a contract, ask whether the breaks already planned for it (work in progress in those notes, TODOs and deprecation notices on that contract) ship in the same release, each in a pull request of its own, so that its clients migrate once. +- **Database**: a migration without a working downgrade, a data migration that goes wrong on real data, a lock or a rewrite of a large table, `NOT NULL` without a default on a filled table, code that cannot run against both the old and the new schema while the rollout is under way. A migration over a large table is a question: how long does it take on data of production size? A downgrade left empty on purpose, with a warning, where the repository's guidelines allow it, is no finding. +- **Rollout**: the old and the new version run side by side during the rollout: a request, message or task made by one and handled by the other; a deploy order the change depends on, between services or with the migration: ask for it. +- **Stored and cached data**: keys, serialised objects and files written by the old version that the new one must still read, and the other way round during a rollback. +- **Configuration**: a new required setting without a default, an environment variable or flag renamed or removed, deployment values (Helm, Compose) not changed along with it. +- **Behaviour**: a risky change visible to users or other services without the feature flag the repository's guidelines ask for, unless the pull request says why it needs none. A flag on a change that is not risky is a finding too: it is a second code path for nothing. +- **Docs**: `docs/`, the README or the public docs that the change makes wrong; the changelog, if the repository keeps one. +- **Dependencies**: an upgrade whose changelog lists breaking changes the code still relies on. + +## Evidence + +Name who breaks and when: "the billing service reads `tier` from this response; after the rename it gets `null` until it is redeployed". If an order of rollout or a flag avoids it, say which. For a rollout, name the two versions and what passes between them: "an old worker reads the task the new one queued and fails on the field `priority`". + +## Not here + +Bugs inside the change and failures nobody would notice (Correctness), the security of a new contract (Security), a migration without a test (Tests). diff --git a/.agents/review/directions/correctness.md b/.agents/review/directions/correctness.md new file mode 100644 index 0000000..e287724 --- /dev/null +++ b/.agents/review/directions/correctness.md @@ -0,0 +1,22 @@ +# Correctness + +Does the changed code do what it means to, for every input and state it will meet? You are looking for bugs: results that are wrong, failures that are silent, state that is never cleaned up. + +Read each changed function in full, its callers (search for them) and the code it calls. For every branch the change adds or alters, ask what input reaches it and what comes out. + +## Look for + +- **Logic**: an inverted or incomplete condition, an off-by-one, the wrong variable or field, a branch that can never run, a loop that stops too early or never, a default argument or a module-level value shared and mutated between calls. +- **Inputs**: `None`, empty, zero, negative, very large, duplicates, unicode, a missing key; time zones and naive datetimes, float rounding of money or counts, string and number coercion, an enum value the code does not handle. +- **Errors**: an exception swallowed or caught too broadly, a fallback or default that hides missing data, an error turned into success or into the wrong status, a lost cause (`raise ... from`), a retry of something that is not idempotent: "Fail loudly" in `AGENTS.md` and the guidelines on errors. A new failure nobody would notice in production: no error log where it fails, no metric or alert where the team already watches the neighbouring path. Never ask for a metric or alert by default; a temporary one for a launch carries a TODO with its issue and the condition to remove it. +- **Concurrency**: a check and an act that another request or task can come between, mutable state shared across requests, a missing `await`, a task started and never awaited, cancelled or kept, a lock held while awaiting a slow call, cleanup that does not run on cancellation or when the client disconnects. For every changed write path, run two of its requests at once in your head, and run it against every other path that writes the same rows or keys: a lost update (a counter or balance read and written back), a duplicate that ends as a server error instead of a conflict, two transactions locking the same rows in opposite order (a deadlock). +- **Transactions and resources**: writes that must succeed together made outside one transaction, a commit in the wrong place, a side effect (an HTTP call, a message) inside a transaction that may roll back, a connection, file, response or stream not closed on every path, an outgoing call without a timeout. +- **Contracts within the code**: a function that now returns, raises or accepts something else while its callers were not changed; a renamed field still read under its old name. + +## Evidence + +A finding names the scenario: "a request with `model=None` reaches `x.py:40`, which returns 200 with an empty body", "the call at `y.py:12` times out; nothing logs it and no metric counts it". Without a scenario you can state, it is a question to the author at most ("what happens when ...?"), and only when the code makes the case plausible. + +## Not here + +Slowness (Performance), attacks (Security), missing tests (Tests), API and schema compatibility and what passes between the old and the new version during a rollout (Compatibility), style (Design & Style). diff --git a/.agents/review/directions/design.md b/.agents/review/directions/design.md new file mode 100644 index 0000000..8696a6f --- /dev/null +++ b/.agents/review/directions/design.md @@ -0,0 +1,22 @@ +# Design & Style + +Is the change the simplest code that fits this repository? Read it the way a person reads a file, top to bottom, against `AGENTS.md`, the repository's `CONTRIBUTING.md` if it has one, every guideline in `.agents/guidelines/` for the areas the scope touches, and the conventions in `.agents/project.md`. You owe the change nothing: every addition has to justify itself in the diff. + +## Look for + +- **Why it exists**: of every new class, function, parameter, configuration key, flag, metric, test and dependency, ask what problem it solves now, who asked for it and where it is used (search for it). "Might be useful later" is a reason to remove it. +- **What already exists**: a helper, fixture, pattern or library function that does the same: find it and cite it. +- **Where it sits**: the right module and layer, the direction of imports, a decision made once rather than the same check at several levels. +- **How simple it is**: an abstraction with a single implementation, indirection without a second use, clever code where plain code reads better. +- **Special cases**: a fix that adds a hook or a branch for one object (`if provider == "x"`): how do the other objects here solve the same problem? One object's special case is often a general rule that is missing. +- **How it reads**: names that say what a thing is, consistency with the neighbouring code, comments only where the code cannot say why it is done this way or what breaks if it changes; a comment that retells the code is noise. + +## Evidence + +Cite the rule the finding rests on (`AGENTS.md`, `CONTRIBUTING.md` or the guideline, with its section) or the existing code, as `path:line`. Taste without either is no finding. + +Besides the findings, list every new public thing in the scope with the reason found for it in the diff or its context, or "no reason found": the report's "Justify or remove". + +## Not here + +Bugs (Correctness), speed (Performance), what the tests cover (Tests). diff --git a/.agents/review/directions/performance.md b/.agents/review/directions/performance.md new file mode 100644 index 0000000..fd589ec --- /dev/null +++ b/.agents/review/directions/performance.md @@ -0,0 +1,18 @@ +# Performance + +Will the change be slow, heavy, or hold others up under the load it will see? Judge against reality: how big the data is and how often the path runs. "Optimise only with a measurement in hand" holds for the review too: a finding states the scale that makes it matter. + +## Look for + +- **Database**: a query in a loop (N+1), a query without a limit or pagination on a table that grows, a filter or an order without an index (check the migrations), whole rows or tables loaded where a few columns or a count would do, a long transaction holding locks while it calls out. +- **Async code**: blocking calls on the event loop (a synchronous HTTP or database client, file IO, `time.sleep`, heavy parsing or hashing of large payloads); independent awaits run one after another on a hot path; concurrency without a bound (`gather` over input of any size). +- **Algorithms and memory**: quadratic work over collections that can grow, the same work repeated in a loop, a whole stream or file read into memory, a cache, queue or list without a bound, a client or connection created per request instead of reused. +- **Network**: calls in a loop that the other side can take as one batch, a payload far larger than its consumer needs. + +## Evidence + +A finding says how big or how often: "`list_keys` runs a query per service; a tenant has up to 2 000 services, so one page load makes 2 000 queries". Without a scale that makes the cost real, it is no finding; a micro-optimisation is a nit at most. + +## Not here + +Whether the result is right (Correctness), locks a migration takes during a rollout (Compatibility). diff --git a/.agents/review/directions/security.md b/.agents/review/directions/security.md new file mode 100644 index 0000000..e313034 --- /dev/null +++ b/.agents/review/directions/security.md @@ -0,0 +1,23 @@ +# Security + +Can someone read, change or break what they should not through this change, or does it leave a secret where it does not belong? For each input the change handles, ask who controls it: a client, another service, an operator's configuration, a file from outside. + +## Look for + +- **Secrets**: a key, token, password or connection string in code, configuration, tests, fixtures, logs, error messages or URLs; a secret given a default value; a new setting that holds a secret but is not handled as one the way the repository handles the others. +- **Injection**: SQL, shell commands or templates built from strings; a file path joined from input (traversal); a URL fetched from input (SSRF); `pickle`, `yaml.load`, `eval` and the like on data from outside; a regular expression on input that can backtrack for long. +- **Access**: a new endpoint, handler or job without the authentication its neighbours have; an object read or changed by id without checking that it belongs to the caller; a check on one path and not on another that reaches the same data; a role or privilege taken from input. +- **Exposure**: personal data, tokens or keys in logs, metric labels or traces; a response or an export carrying internal fields; a stack trace or internal error text sent to a client; a new table, column or bucket holding secrets that roles granted "read everything" can read. +- **Defaults**: debug or verbose modes on, CORS or allowed hosts open to all, TLS verification off, permissive file modes, a timeout or a size limit removed. +- **Crypto**: a hand-made scheme, a fast hash for passwords or keys, a token compared with `==` instead of in constant time, `random` where `secrets` is meant. +- **Dependencies**: a new dependency: is it needed, maintained, pinned, from the registry the repository uses, and what can it do on install and at run time? + +## Evidence + +A finding about a secret names where it is and what kind it is, never its value, not even in part: the finding goes to the record and may go to the pull request description. + +A finding names the attacker and the gain: "any authenticated caller reads another tenant's keys by changing `tenant_id` in `GET /keys`". A pattern that only looks risky, where you can show the input never comes from outside, is no finding. + +## Not here + +Bugs without an attacker (Correctness), dependencies the diff does not add or change. diff --git a/.agents/review/directions/tests.md b/.agents/review/directions/tests.md new file mode 100644 index 0000000..714cd8d --- /dev/null +++ b/.agents/review/directions/tests.md @@ -0,0 +1,18 @@ +# Tests + +Would the tests catch it if the change broke? Read the tests the change adds or alters together with the code they cover, and `.agents/guidelines/testing.md` where the repository has it. + +## Look for + +- **Behaviour without a test**: every new or changed behaviour, the error paths and the edge cases the code handles included, has a test that fails without the change: revert it in your head. A bug fix has a test that reproduces the bug; one that mocks out the code the fix changed, or asserts what the old code did as well, passes without the fix and reproduces nothing. A new migration is run by the repository's migration tests (upgrade, downgrade, upgrade again), where it has them. +- **What a test checks**: behaviour through the public interface rather than private details; an assertion on the result rather than only "no exception" or `assert result`; the exact value wherever it is known. +- **Changed tests**: an assertion, fixture or expected value changed in an existing test: is the new behaviour intended and said so? Otherwise the test was bent to fit the code. +- **Setup**: existing fixtures and factories reused rather than copied; no real network calls; nothing that depends on the time, the order of tests, randomness or sleeps. + +## Evidence + +Name the behaviour without a test and the case to add: "`x.py:40` returns 409 on a duplicate name; no test sends a duplicate". Code without logic of its own needs no test of its own. + +## Not here + +Whether the code itself is right (Correctness). diff --git a/.agents/review/pure-refactor.md b/.agents/review/pure-refactor.md new file mode 100644 index 0000000..c5325c0 --- /dev/null +++ b/.agents/review/pure-refactor.md @@ -0,0 +1,52 @@ +# Pure-refactor check + +Run it on a refactoring before the pull request is opened, and on any branch whose description claims that behaviour does not change: a move, a rename, a dependency swap. How to run it in each agent is in [README.md](README.md). + +Verify that the change on this branch keeps behaviour everywhere. Assume it does not until you have traced every path. + +## Scope + +`git diff ...HEAD` plus untracked files unless told otherwise, with `` as [review.md](review.md) defines it. Read every changed file in full, old and new, and find every caller of every changed function, including references by string: registries, entry points, configuration, templates, dynamic lookups. Behaviour most often changes at a call site the diff does not show. + +## Structure + +Split the diff into slices small enough to trace completely: a module, a class, a group of related functions. Run one sub-agent per slice, all in parallel, started as "Fresh reviewers" in [review.md](review.md) says: fresh contexts, a model no weaker than this session's. Each sub-agent traces its slice only: it starts no sub-agents and edits nothing. If your agent has no sub-agents, the check runs in a new session as that section says, with the words "you are the fresh reviewer of `.agents/review/pure-refactor.md`: report only, edit nothing". Such a session is the reviewer itself: it starts no one, works through the slices one at a time, writing each slice's result down before the next, does the report step itself and returns the report; you add it to the record. + +For every slice, compare the old code with the new, path by path, and answer with evidence: + +- **Interface:** the same importable names and module paths, parameter names (callers may pass them by keyword), configuration keys and environment variables, command-line flags, routes, and names in stored data and events? +- **Inputs:** the same accepted arguments, types, defaults and validation? The same behaviour on `None`, empty and boundary values? +- **Outputs:** the same return values and types, the same shape and order of collections, the same serialised form (field names, aliases, missing versus null, number and date formats)? +- **Errors:** the same exceptions for the same conditions, the same error codes and messages reaching callers, the same log level and event? +- **Side effects:** the same writes to storage, the same outgoing requests (payload, headers, order, retries, timeouts), the same metrics and their labels, the same logging context? +- **Order and timing:** the same order of operations wherever it can be observed: transaction boundaries, when a lock is taken, when a stream yields, when a task starts? +- **Removed or added code:** does anything that ran before no longer run? Does anything run now that did not before (a validation, a default, a log, a conversion)? +- **Tests:** were tests changed? A changed assertion or fixture in a change that claims to keep behaviour is a behaviour change until shown otherwise. + +A slice's result is either "no behaviour change - traced " or a list of differences, each as `path:line - old behaviour → new behaviour - how it is observable`. + +## Report + +One more fresh sub-agent, as for the meta-review in [review.md](review.md), gets the slices' results, not your opinion of them. It merges them, verifies each difference at the cited lines, drops what it cannot confirm, and reports in priority order, naming the models the check ran on: + +``` +## Pure-refactor check: , + +### Behaviour changes (blocking: the change does not keep behaviour) +- `path:line` - . Observable as . + +### Probable changes (could not trace fully) +- `path:line` - - + +### Verified unchanged +- - traced + +### Verdict + - one line. +``` + +No compliments, no summary of the restructuring itself. If a difference is intended, say so and name where the author states it: an intended change nobody stated is still a finding. + +## Record + +Add the result to the branch's review record (`local/reviews/.md`, see "After the report" in [review.md](review.md)) as the direction "Pure-refactor check": "no behaviour change", or each difference as a finding with its status. A behaviour change is blocking; a probable change is should fix until it is traced. It is a partial run: it never moves the record's `commit`. The pull request's "AI Review" section then carries it as a line of its own. diff --git a/.agents/review/review.md b/.agents/review/review.md new file mode 100644 index 0000000..952f522 --- /dev/null +++ b/.agents/review/review.md @@ -0,0 +1,140 @@ +# Review + +You are reviewing a branch for its author before it becomes a pull request. The author owns the outcome: each finding is fixed or dismissed with a reason, and the pull request says which. The people who review the pull request will not hunt for what you were meant to find, so miss nothing you can confirm and report nothing you cannot. + +The rules are in `AGENTS.md`, in the repository's `CONTRIBUTING.md` if it has one, in `.agents/guidelines/` where the repository has them and in `.agents/project.md`. This prompt does not repeat them; the files in `directions/` say how to apply them. + +## Scope + +`` is the repository's default branch as the remote has it: `git symbolic-ref --short refs/remotes/origin/HEAD`, else `origin/master` or `origin/main`, whichever exists. `` is `local/reviews/.md`, one per branch: every run updates it, none starts a new one. + +- By default, the changes since the last review. First run `python .agents/review/check.py --refresh` (`python3` where `python` is not on the path): after a rebase that left the reviewed changes as they were, it moves the record's `commit` to `HEAD`. Then, if `` exists and its `commit` is an ancestor of `HEAD`, the scope is the files the branch changed since then, those of `git diff --name-only HEAD` that are also in `git diff --name-only ...HEAD`: + - no merge of `` since `` (`git log --merges ..HEAD` is empty): `git diff HEAD -- `; + - a merge of `` since: `git diff ...HEAD -- `, so that other people's changes in the same files stay out of the review. + + Otherwise the whole branch, `git diff ...HEAD`. Untracked files belong to the scope either way. Nothing changed since the last review: say so and stop. + + A run over the changes since the last review is a follow-up: it checks that the findings in `` are settled in the code and raises new findings, blocking and should fix only, no nits, only on the lines changed since `` (those of `git diff HEAD -- ` that are in the scope) and on the code whose behaviour they change, such as an unchanged caller of a changed function. The rest of the files is read for context, not reviewed again: otherwise every round finds something new and the rounds never end. +- `full` in the request: the whole branch, still with the findings already in ``. +- `staged`: `git diff --staged`; `working`: `git diff` and `git status --short`; a path: that file or directory against ``. +- A commit range, another branch or someone else's pull request: that diff, reviewed the same way, but the run writes no record and fixes nothing: it is not the author's review of their own branch, and what it finds goes to the user only. +- Leave out what nobody reviews: lock files, generated and vendored code, minified bundles, binary files. Name what was left out in the report. + +Read every changed file in full, not just the hunks, together with the callers, tests and helpers next to it: most findings are about what the change does not fit with. Search and cite the location instead of guessing. + +## Directions + +The files in `directions/`, listed in the table of [README.md](README.md), and the `Review` section of `.agents/project.md`, if the repository has one: a line `- : ` adds a focus area to that direction; a name that is no direction here makes a direction of its own. A request that names directions runs only those. + +First decide, for each direction, whether the scope gives it anything to look at: a change to docs only gives Performance nothing; a change that touches no API, schema, configuration, stored format or documented behaviour gives Compatibility nothing. Such a direction is "not applicable", with the reason in a few words, and is not run. When unsure, run it. + +## Fresh reviewers + +The review is done in fresh contexts, never in the session that wrote the change: a reviewer who knows why the code was written this way stops seeing what is wrong with it. You, the agent of that session, only start the reviewers, take their report and settle it with the user ("After the report"). + +If your request says that you are the fresh reviewer of this prompt, you are not that agent: start no reviewers, review every applicable direction yourself, one after another, then do the meta-review, and return the report and the record's content. Edit nothing and write no record; skip "After the report". + +- One fresh sub-agent per direction, all in parallel; for a small scope, a few dozen changed lines, one fresh sub-agent for all directions. Never a fork or any agent that inherits this conversation. In Claude Code, the `reviewer` subagent of the `claude` pack is such a reviewer. +- Every reviewer, the meta-review included, runs on this session's model or a stronger one: a fresh context, not a weaker model. Agents may hand sub-agents a lighter model of their own accord (a built-in agent, a default model for sub-agents in the settings), so name the model when you start each reviewer. Each reviewer names in its report the model it ran on, and the record's `model` is taken from these reports, never from your own. A reviewer that ran on a weaker model is named: in `model` by the run that sets it, next to its direction's result by a partial run. +- No sub-agents in your agent: ask the user to run the review in a new session of their agent, on this session's model (a new chat, `claude -p --model `, `codex exec -m `, `opencode run -m /`), with the same request and the words "you are the fresh reviewer of `.agents/review/review.md`: report only, edit nothing". That session did not write the change, so it is the reviewer itself (above); you write `` from the report and the record's content it returns. +- A reviewer's brief holds only what is listed below. Not what the change is for, how it was built, what was tried, which findings you expect or which you think are settled: the reviewer reads the code as the pull request's reviewer will. + +Each direction gets: + +- its file from `directions/`, `AGENTS.md`, `CONTRIBUTING.md` if the repository has one, `.agents/project.md` and the guidelines in `.agents/guidelines/` for the areas the scope touches; +- the scope as the git command that produces it, not a copy of the diff; +- for a follow-up, that it is one, with its rule from "Scope" and the command for the lines changed since ``; +- its focus areas from `.agents/project.md`; +- the findings already in `` with their status. A dismissed finding comes back only when the code it was about changed or there is new evidence; a fixed one only when the fix does not hold; an open one whenever it is still there; +- the report format and the severities below; +- that it reviews this direction only: it starts no reviewers, edits nothing and writes no record, whatever `AGENTS.md` says about running a review; +- the request to end its report with the model it runs on. + +A scope too large to read completely at once is reviewed module by module within the direction, writing the findings down after each module. + +A direction reports each finding as `path:line - defect or question - why it matters - fix`, with its severity (blocking, should fix or nit), and ends with one line: how many findings, or "no findings - checked ". + +## Meta-review + +One more fresh sub-agent (the same one for a small scope) gets the scope and the directions' findings with the models they named, not your opinion of them, names its own model too, and then: + +- Reviews what no direction sees: the diff as a whole against the rules for changes in `AGENTS.md` and the repository's `CONTRIBUTING.md`: a second task in the diff, files that do not belong (`local/`, debug leftovers, generated files, agent reports), unrelated formatting. +- Verifies each finding against the code and drops what it cannot confirm at the cited line. A finding without the evidence its direction asks for (a failure scenario, an attacker, a scale, a rule) is dropped too. In a follow-up, so are nits and findings outside what its rule in "Scope" allows. +- Drops a finding that needs a particular configuration only when it can see every place that sets it (deployment values, the repository's notes for agents) and none does, and neither the change nor its flag turns it on; it says where it checked. When the setting may come from a place it cannot read, such as a secret store or CI variables, it keeps the finding as a question to the author about its value there. +- Merges duplicates: the same defect found by two directions is one finding, under the direction its fix belongs to. Groups repeats ("same in 6 more places: a.py:10, b.py:22, ..."). +- Ranks by consequence, not by direction. Data lost or corrupted, a security hole, a swallowed exception, a layer leak, new behaviour without a test, a risky change without a flag, a breaking change without a plan: blocking. A real problem of limited reach: should fix. Naming, wording, formatting: nit. +- Treats "it already was like that" as no defence for code the diff touches, and as a reason to leave code the diff does not touch alone. + +## Report + +``` +## AI review: at ( | ...>), + +### Blocking +- Correctness · `path/to/file.py:42` - . . → + +### Should fix +- ... + +### Nits +- `nit:` Design & Style · `path:line` - ... + +### Justify or remove +- `ClassName` (file) - + +### Directions +- Correctness - 1 blocking, 1 should fix +- Security - no findings +- Performance - not applicable: docs only + +### Verdict + - one line on why. +``` + +- Every finding has a location and a fix. +- Phrase it as a reviewer would: "why do we need X?", "where is this used?", "what happens when Y is None?", a question the author answers with code or with a removal. +- No compliments, no retelling of what the change does. Left-out files, if any, go on one line under the title. + +## After the report + +Only for the author's review of the checked-out branch: not for a range, another branch or a pull request ("Scope"), and not for a fresh reviewer. + +From here on it is you, the agent that wrote the change: you know why it is the way it is, and you judge what in the report is valid. The user decides what is dismissed; you do the work. + +1. Update `` right after the report, or create it with its directories; if git does not ignore it (`git check-ignore -q ` fails), stop and tell the user instead. The new findings start as "open". +2. Fix the blocking and should-fix findings, except where the fix is a choice the user should make. Ask the user about those and about every finding you think is wrong. A dismissal needs the user's yes and a reason in one line that someone else can judge ("the list holds at most 5 keys", not "not needed"). Nits: fix them or let them go; a nit let go is never listed as dismissed. Update each finding's status in `` as it is settled. +3. Once the fixes are committed, run one follow-up (see "Scope") unless the user says the fixes need none: it checks the fixes and the lines they touched. Whether another round follows the follow-up's own fixes is the user's call: report what it found and ask, never loop on your own. + +The record: + +```markdown +--- +commit: +model: +--- + +| Direction | Result | +| --- | --- | +| Correctness | 2 fixed | +| Security | no findings | +| Performance | 1 fixed, 1 dismissed | +| Design & Style | 3 fixed | +| Tests | no findings | +| Compatibility | not applicable: no API, schema or configuration change | + +1. Blocking · Correctness · `path:line` - → + Status: fixed in +2. Should fix · Performance · `path:line` - → + Status: dismissed - +3. Nit · Design & Style · `path:line` - → + Status: let go +``` + +- `commit` is the `HEAD` a complete run reviewed: a default or `full` run of every applicable direction. Only such a run sets it, when it writes the record after its report; fixes and status changes never move it, so the next run reviews the fixes. A partial run (named directions, `staged`, `working`, a path, the pure-refactor check) adds its findings and results but leaves `commit` as it is; on a branch without a record it writes one without `commit`. +- `model` goes with `commit`: the run that sets one sets the other, to the model its reviewers named, or for reviewers on different models `Claude Opus 5.5; Security on Claude Sonnet 5.5`. +- Directions in the order of the table in [README.md](README.md), then the repository's own, then Pure-refactor check if it ran. +- A result is "no findings", "not applicable: ", "not run" (left out by the request) or the counts of fixed, dismissed and open findings over all runs; nits let go are not counted. A later "not applicable" or "not run" never replaces counts or "no findings"; "not applicable" replaces "not run". +- Findings keep their numbers from run to run; new ones are appended. A status is "open", "fixed in ", "dismissed - " or, for a nit only, "let go". +- A finding about a secret names where it is and what kind it is, never its value: the record is kept, and the dismissed findings go to the pull request description. + +`python .agents/review/check.py` compares the record's `commit` with the branch; the pull request's "AI Review" section is built from the record ([README.md](README.md)). diff --git a/.agents/skills/commit/SKILL.md b/.agents/skills/commit/SKILL.md new file mode 100644 index 0000000..cdb184a --- /dev/null +++ b/.agents/skills/commit/SKILL.md @@ -0,0 +1,20 @@ +--- +name: commit +description: Commit changes by the project's conventions - the docs checked against the diff, the diff against the rules, the formatter run, the message confirmed by the user. +--- + +# Commit + +Work from the repository root, the directory that holds `.agents/`. Commit what the request names; with nothing named, what is staged; if nothing is staged, the changes to tracked files, after asking about new files. + +## Flow + +1. **Changes.** `git status` and the diff of what goes into the commit. Nothing to commit: say so and stop. +2. **Docs first.** Check the diff against `docs/`, the README and the examples: names renamed or removed but still mentioned, logic described differently, new concepts and changed contracts, configuration, commands or processes not documented. With a large diff or large docs, give each area to a sub-agent in parallel, if your agent has them. A mismatch: fix the docs first and commit them together with the code. +3. **Rules.** Walk the diff against `AGENTS.md`, the repository's `CONTRIBUTING.md` if it has one and the guideline in `.agents/guidelines/` for each area it touches. Stop and report instead of committing when it breaks them, in particular: files that do not belong in the repository (local notes, generated output, secrets), a second task in the same diff, debugging leftovers. +4. **Format.** Run the format command from `.agents/project.md` on what you commit; if the profile and the repository name none, ask. Report what the lint command reports, if there is one. +5. **Message.** By the commit convention in the profile. Without one, Conventional Commits: `(): ` in the imperative, at most 72 characters, with the issue from the branch name as the scope where the project does that, and a body that says why when the summary cannot. Types: `feat`, `fix`, `perf` (an optimisation is `perf`, not `feat`), `refactor`, `test`, `docs`, `chore` (never for a change that belongs in release notes). +6. **Confirm.** Show the message and the files, and commit only after the user's yes; change it as they say. +7. **Commit.** Do not amend, rebase or push unless asked. No AI attribution: no `Co-Authored-By` for an agent, no "Generated with" lines. + +Finish with the commit's short hash and subject. diff --git a/.agents/skills/implement/SKILL.md b/.agents/skills/implement/SKILL.md new file mode 100644 index 0000000..f89cc05 --- /dev/null +++ b/.agents/skills/implement/SKILL.md @@ -0,0 +1,37 @@ +--- +name: implement +description: Implement a task in the code - a bug fix, a feature or a refactoring - from understanding it to the report, with a review at the end. Use when the user hands over such a task, not for an edit within a task already under way. +--- + +# Implement + +Work from the repository root, the directory that holds `.agents/`. The rules are in `AGENTS.md`, the repository's `CONTRIBUTING.md` if it has one, `.agents/project.md` and the guidelines in `.agents/guidelines/` for the areas the task touches: read them first. This skill adds only the order of the work and what they do not say. + +## 1. Understand the task + +1. Look for the same flaw elsewhere in the repository (the same cause, not only the same symptom) and propose one fix for all of it. +2. Find everything the change touches: callers, tests, docs, configuration, deployment values and the other services that read the contract. + +## 2. Agree on the shape + +1. A change beyond a few lines: before writing code, show its shape (the contract or public API, the files it adds or changes, a sketch) and wait for the answer. A spec agreed as `.agents/skills/spec/SKILL.md` says already gives the shape. +2. Where there is a choice, give the options with how the neighbouring code and other projects solve the same problem (read their code, not their docs), and say which one you prefer and why. +3. A fix or a refactoring the task needs first goes to a pull request of its own, merged before the main change. + +## 3. Write the change + +- Work on the branch the user names; on the default branch, create one first as `.agents/skills/new-branch/SKILL.md` says, in a worktree when another agent works in this clone. +- The same flaw elsewhere is part of the task once the user agreed to the wider fix in step 2. +- A bug fix starts with the test that reproduces it, run on the unfixed code: locally, or, when the tests run in CI, committed and pushed alone to the branch's pull request after the user's yes. A draft opened for that gets a title by the profile's format and a one-line description; `.agents/skills/pr/SKILL.md` writes the full one when the work is done. +- Configuration and tests change in the same step as the code they follow, not at the end. +- After a rename or a move, search for the old name in code, tests, docs and configuration. + +## 4. Verify + +1. Run the format, lint and test commands as `AGENTS.md` says. Where the tests run only in CI, or the user asked to leave them to CI, say so: they run in step 2 instead. +2. Commit as `.agents/skills/commit/SKILL.md` says. If the tests are left to CI, push after the user's yes to the branch's pull request (a draft if none is open yet) and read the pipeline. +3. Review the branch: with `.agents/review/`, follow `.agents/review/review.md` and settle the findings as it says; otherwise follow `.agents/prompts/review.md` and fix with the user what it finds. + +## 5. Report + +End with a short report that stands on its own: what changed, how it was verified (what you ran and what it printed), what is left and the next step. diff --git a/.agents/skills/new-branch/SKILL.md b/.agents/skills/new-branch/SKILL.md new file mode 100644 index 0000000..acedfa8 --- /dev/null +++ b/.agents/skills/new-branch/SKILL.md @@ -0,0 +1,28 @@ +--- +name: new-branch +description: Create a branch for a task from the latest default branch (or the base the request names), named by the project's convention - type, issue, short description - in this clone or in a worktree of its own, so that agents can work on several tasks in parallel. +--- + +# New branch + +Work from the repository root, the directory that holds `.agents/`. Read the branch convention, the issue format and the default branch in `.agents/project.md`; where it names none, find them as `AGENTS.md` says ("Before you start"). + +## Flow + +1. **Where.** In this clone, unless the caller or the user asks for a worktree: a directory of its own on the new branch, so that another agent keeps working in this clone meanwhile. +2. **Uncommitted changes** (this clone only; a worktree leaves this clone as it is): if `git status` shows any, stop and say so: they have to be committed or stashed first. +3. **Base.** The branch the request names as the base, else the default branch. `git fetch origin`: the new branch starts from `origin/`, so nothing else in this clone changes. +4. **Issue.** Ask the user for the issue, unless the request names it. Check it against the issue format in the profile; ask again if it does not fit. A repository without a tracker skips this step. +5. **Description.** Ask what the task is, unless the request says, and derive from it: + - the type: `feat` (new functionality), `fix` (a bug), `perf` (speed or resources), `refactor` (restructuring without a behaviour change), `chore` (maintenance, dependencies, configuration), `test`, `docs`; ask when it is ambiguous; + - a short description: three to five words, lowercase, with hyphens. +6. **Confirm.** Show the branch name by the profile's convention and, for a worktree, its path: next to this clone, `../-` (`` is this clone's directory name), unless the profile or the user names another place. Create it only after the user's yes; change it as they say. +7. **Create.** + - This clone: `git switch -c origin/`. + - Worktree: if the path exists, stop and say so. Otherwise `git worktree add -b origin/`; from then on every command runs in that directory. Tell the user: files git ignores (`.env`, `local/`) are not in the worktree, so copy from this clone what the app and the tests need; test infrastructure on the machine (containers, ports, a test database) is shared by every worktree, and two test runs on it at once break each other; once the pull request is merged, `git worktree remove `. + +## Convention + +Without one in the profile: `/-`, such as `fix/123-empty-email`, or `/` without a tracker. + +Do not push the branch. If a git command fails, show the error and stop. Finish with the branch name, the commit it starts from and, for a worktree, its path. diff --git a/.agents/skills/pr/SKILL.md b/.agents/skills/pr/SKILL.md new file mode 100644 index 0000000..7aa82f1 --- /dev/null +++ b/.agents/skills/pr/SKILL.md @@ -0,0 +1,37 @@ +--- +name: pr +description: Write the pull request (merge request on GitLab) title and description for the current branch from its commits and diff, short and about why, with the AI Review section where the repository has the AI review; open it after the user's yes. +--- + +# Pull request + +Work from the repository root, the directory that holds `.agents/`. `` is the target branch the request names, else the default branch as the remote has it (`git symbolic-ref --short refs/remotes/origin/HEAD`, else `origin/master` or `origin/main`); the pull request targets it. Read `.agents/project.md` for the title format, the language of pull requests and how they refer to issues. + +## Before writing + +1. **Committed.** Everything belongs to the branch: no uncommitted changes. The project's checks pass, or the user knows which fail. +2. **Docs.** Check `git diff ...HEAD` against `docs/`, the README, the examples and the changelog: names renamed or removed but still mentioned, logic described differently, what users need to know and nobody wrote. With a large diff or large docs, give each area to a sub-agent in parallel, if your agent has them. A mismatch: stop and fix the docs on this branch first. +3. **Rules.** Check the diff against the rules for changes in `AGENTS.md` and the repository's `CONTRIBUTING.md`: one purpose, a size a person can review, an honest type, no files that do not belong. Where the guidelines ask for a feature flag on a risky change, check that it has one, and that a change that is not risky has none. On a violation, stop: say what to fix and write nothing. +4. **Review.** With `.agents/review/`: run `python .agents/review/check.py --strict --refresh` (`python3` where `python` is not on the path). Unless it reports the branch reviewed, review it as `.agents/review/review.md` says and settle the findings first. One exception: when only commits that the record lists as "fixed in" came after the review, ask whether to run a follow-up over them; if the user declines, the AI Review section says so. Stop while `local/reviews/.md` still has an open blocking or should-fix finding. + +## Title + +By the profile's format, in its language. Without one: `(): `, with the issue from the branch name, or `: ` without a tracker. One main change, without versions or secondary details: release notes are built from titles. The type is honest: `perf` for an optimisation, `feat` or `fix` for anything users see, `chore` only for what they do not. + +## Description + +In the profile's language, by the repository's template if it has one (`.github/pull_request_template.md`, `.gitlab/merge_request_templates/`). Without one: + +- the issue link, from the issue tracker in the profile or from the user; none without a tracker; +- **why**, in one or two sentences: the problem, not the list of changes; +- **what is included**: one short sentence per change, usually three to six; an API change shows an example request and response; +- only when it applies: the approach (the decisions the diff does not show, and what was rejected) for a larger change; measurements (one table, with the environment and the load) for a claimed effect on speed, memory or cost; the rollout (what breaks, the migration, the deploy order) when clients or operators must react or the schema changes; +- with `.agents/review/`: the "AI Review" section, built from the review record as `.agents/review/README.md` says. + +Short: no sections beyond these, no retelling of the diff, no list of files, no linter output, no list of tests run. A check by hand the repository asks for, such as on a staging environment, is one line of what was verified. No AI attribution. + +## Open it + +Show the title and the description and wait for the user's yes. Then push the branch and open the pull request with the forge's command-line tool (`gh`, `glab` or `tea`), or give the text ready to paste. After changes made in review, write the description again, with the AI Review section after a follow-up. + +Never merge, approve or assign reviewers unless asked. diff --git a/.agents/skills/review-change/SKILL.md b/.agents/skills/review-change/SKILL.md new file mode 100644 index 0000000..ea19ba2 --- /dev/null +++ b/.agents/skills/review-change/SKILL.md @@ -0,0 +1,10 @@ +--- +name: review-change +description: AI review of the current branch by directions - correctness, security, performance, design and style, tests, compatibility - or, with pure-refactor, a check that a change keeps behaviour. Run it yourself as soon as a task is done, before opening a pull request, and on request. +--- + +# Review a change + +The review lives in `.agents/review/`; this skill only picks the prompt. Work from the repository root, the directory that holds `.agents/`. + +`pure-refactor` in the request: [pure-refactor.md](../../review/pure-refactor.md); otherwise [review.md](../../review/review.md). Read it in full and follow it exactly, with the rest of the request as its scope and directions. diff --git a/.agents/skills/spec/SKILL.md b/.agents/skills/spec/SKILL.md new file mode 100644 index 0000000..320f4c0 --- /dev/null +++ b/.agents/skills/spec/SKILL.md @@ -0,0 +1,52 @@ +--- +name: spec +description: An interactive session that plans a task before any code - the problem first, then the code, then a spec saved where the project keeps specs, local/specs/ by default. +--- + +# Spec + +Work from the repository root, the directory that holds `.agents/`. An interactive session that ends in a spec. No code is written in it: only questions, reading and planning. It goes on until the user says it is done ("save", "done", "that's it"). + +## 1. What: the problem + +1. Ask what the task is, unless the request says; let the user describe it freely. +2. Ask, rather than assume, until it is clear: the problem it solves and for whom, the behaviour expected, the edge cases and errors, the constraints and dependencies. +3. Agree on the scope: what is in, and what is explicitly out. +4. Sum it up and ask whether it captures the task. Move on only on a yes; with new requirements or a "not quite", stay here. + +If the user wants to skip to the code, bring them back to the problem first. When the discussion stalls, sum up what is clear and ask what is missing. + +## 2. How: the plan + +5. Read the code: the files involved, the patterns to follow, what to create or change. Use sub-agents if your agent has them. +6. Build the plan step by step, with the files you found. Where there is a choice, give the options and your preference. +7. Go through it with the user and change it as they say. The user may go back to step 1 at any time ("wait", "actually..."): follow. + +## 3. Save + +8. When the user says the plan is complete (if unsure, ask whether to save), offer two or three names for the spec, such as `auth-refactor`, and take theirs if they type one. +9. Save it where `.agents/project.md` says specs go. Without a place there, a spec is a working note, not a repository document: `local/specs/.md`. If git does not ignore that path (`git check-ignore -q local/specs/.md` fails), ask where to save it instead. +10. Show the path and sum up what the spec holds. + +```markdown +# Spec: + +## Context +Why this is needed, the problem it solves. + +## Task +What has to be done: the requirements from step 1. + +## Out of scope +The boundaries agreed in step 1. + +## Plan +Step by step, with the files from step 2. + +## Success criteria +Testable statements ("the tests for X pass") and what a user can do afterwards. +``` + +Keep it balanced: concrete enough to work from, short enough to read in a few minutes. Ask open questions in chat; offer choices only when there are two to four concrete ones. + +Do not start implementing until the user approves the spec. diff --git a/.claude/agents/reviewer.md b/.claude/agents/reviewer.md index 2bc8bf1..e754440 100644 --- a/.claude/agents/reviewer.md +++ b/.claude/agents/reviewer.md @@ -7,7 +7,7 @@ tools: Read, Grep, Glob, Bash You review code changes in this repository. You never edit files, commit or push. 1. Read `.agents/project.md` for the project's conventions and commands. Where the profile is blank, find the facts in the repository as `AGENTS.md` says ("Before you start"), and say which ones you found there. -2. Follow the prompt the request names: `.agents/prompts/pure-refactor.md` for a check that behaviour is kept, `.agents/prompts/review.md` otherwise. If the request gives you one slice of a larger change, review that slice completely and read the rest of the change only for context; the whole-change part of the prompt is left to the caller. +2. Follow the prompt the request names: `.agents/prompts/pure-refactor.md` for a check that behaviour is kept, `.agents/prompts/review.md` otherwise. If the request gives you one slice of a larger change, review that slice completely and read the rest of the change only for context; the whole-change part of the prompt is left to the caller. When the request hands you a file from `.agents/review/directions/`, the meta-review of `.agents/review/review.md`, or a slice or the report step of `.agents/review/pure-refactor.md`, that file and the request are your brief: follow them, and end your report with the model you run on. When the repository has `.agents/review/` and the request names no such file, you are the fresh reviewer of `.agents/review/review.md` (or `pure-refactor.md` for a check that behaviour is kept): every direction, then the meta-review, and return the report and the record's content without writing it. 3. Work out what to review from the request. If it names nothing, review the current branch against the default branch, plus uncommitted and untracked changes. -4. Use Bash only to read: `git diff`, `git log`, `git show`, and the project's lint or test commands when you were asked to run them. +4. Use Bash only to read: `git diff`, `git log`, `git show`, `git status`, `git ls-files`, and the project's lint or test commands when you were asked to run them. 5. Report as the prompt says, with the file and line of every finding. diff --git a/.claude/skills/commit/SKILL.md b/.claude/skills/commit/SKILL.md index a59389f..8bdf30f 100644 --- a/.claude/skills/commit/SKILL.md +++ b/.claude/skills/commit/SKILL.md @@ -5,6 +5,8 @@ disable-model-invocation: true argument-hint: "[what to commit, or a hint for the message]" --- +If the repository has `.agents/skills/implement/` (the `workflow` pack), follow `.agents/skills/commit/SKILL.md` with the request "$ARGUMENTS" instead of the steps below. + Commit $ARGUMENTS. With nothing named, commit what is staged; if nothing is staged, ask what to include. 1. Read the commit conventions in `.agents/project.md`. If it names none, use Conventional Commits: `type(scope): summary` in the imperative, at most 72 characters, and a body that says why. diff --git a/.claude/skills/implement/SKILL.md b/.claude/skills/implement/SKILL.md new file mode 100644 index 0000000..e8d46aa --- /dev/null +++ b/.claude/skills/implement/SKILL.md @@ -0,0 +1,6 @@ +--- +name: implement +description: Implement a task in the code - a bug fix, a feature or a refactoring - from understanding it to the report, with a review at the end. Use when the user hands over such a task, not for an edit within a task already under way. +--- + +Follow `.agents/skills/implement/SKILL.md`, the same for every agent, with the request: $ARGUMENTS diff --git a/.claude/skills/new-branch/SKILL.md b/.claude/skills/new-branch/SKILL.md index c600a69..2538282 100644 --- a/.claude/skills/new-branch/SKILL.md +++ b/.claude/skills/new-branch/SKILL.md @@ -5,6 +5,8 @@ disable-model-invocation: true argument-hint: "" --- +If the repository has `.agents/skills/implement/` (the `workflow` pack), follow `.agents/skills/new-branch/SKILL.md` with the request "$ARGUMENTS" instead of the steps below. + Create a branch for: $ARGUMENTS 1. Read the branch convention and the default branch in `.agents/project.md`. If it names no convention, use `/-` in lowercase with hyphens, such as `fix/123-empty-email`. diff --git a/.claude/skills/pr/SKILL.md b/.claude/skills/pr/SKILL.md index c84d24b..e739a1d 100644 --- a/.claude/skills/pr/SKILL.md +++ b/.claude/skills/pr/SKILL.md @@ -5,12 +5,14 @@ disable-model-invocation: true argument-hint: "[target branch, or notes for the description]" --- +If the repository has `.agents/skills/implement/` (the `workflow` pack), follow `.agents/skills/pr/SKILL.md` with the request "$ARGUMENTS" instead of the steps below. + Open a pull request for the current branch. $ARGUMENTS 1. Read `.agents/project.md` for the default branch, the language of pull requests and how they refer to issues. -2. Make sure everything is committed and the project's checks pass. Report what fails and ask before going on. +2. Make sure everything is committed and the project's checks pass. Report what fails and ask before going on. If the repository has `.agents/review/`, run `python .agents/review/check.py --strict --refresh` (`python3` where `python` is not on the path); unless it reports the branch reviewed, run `/review-change` and settle its findings first, and stop while the review record (`local/reviews/.md`) still has an open blocking or should-fix finding. 3. Check that the documentation is still true: search the docs, the README, the examples and the changelog for what the branch renames, removes or changes, and for what it adds that users will need to know. If something is stale or missing, say what and offer to fix it on this branch; after a fix is committed, go back to step 2. -4. Write the title in the project's format. Write the description from the commits and the diff: what changes and why, how it was tested, risks and how to roll back, and the issue it resolves. Fill in the repository's template if it has one (`.github/pull_request_template.md`, `.gitlab/merge_request_templates/`). +4. Write the title in the project's format. Write the description from the commits and the diff: what changes and why, how it was tested, risks and how to roll back, and the issue it resolves. Fill in the repository's template if it has one (`.github/pull_request_template.md`, `.gitlab/merge_request_templates/`). With `.agents/review/`, end the description with the "AI Review" section, built from the review record as `.agents/review/README.md` says. 5. Show the title and description and wait for the user's approval. Then push the branch and open the pull request with the forge's command-line tool (`gh`, `glab` or `tea`), or tell the user how to open it. Never merge, approve or assign reviewers unless asked. diff --git a/.claude/skills/review-change/SKILL.md b/.claude/skills/review-change/SKILL.md index 4dbd946..195d490 100644 --- a/.claude/skills/review-change/SKILL.md +++ b/.claude/skills/review-change/SKILL.md @@ -1,9 +1,11 @@ --- name: review-change description: Review a change for bugs, security problems, compatibility, unjustified additions and missing tests, using the project's review checklist; with pure-refactor, check that a change keeps behaviour. Use when the user asks for a review, a second look at a diff, branch, commit range or pull request, or whether a refactoring keeps behaviour. -argument-hint: "[branch, commit range, files or pull request] [pure-refactor]" +argument-hint: "[branch, commit range, files or pull request] [pure-refactor] [full|staged|working] [direction...]" --- +If the repository has `.agents/review/`, follow `.agents/review/pure-refactor.md` when the arguments say `pure-refactor`, `.agents/review/review.md` otherwise, with the request "$ARGUMENTS", instead of the steps below: it reviews by directions in fresh `reviewer` subagents, writes the branch's review record and settles the findings with the user. + Review the change that $ARGUMENTS names, leaving out the word `pure-refactor`. With nothing named, review the current branch against the default branch, plus uncommitted and untracked changes. 1. Pick the prompt: `.agents/prompts/pure-refactor.md` when the arguments say `pure-refactor` or the user asks whether behaviour is kept, `.agents/prompts/review.md` otherwise. Read it in full and follow it, including its report. @@ -11,4 +13,4 @@ Review the change that $ARGUMENTS names, leaving out the word `pure-refactor`. W 3. Split the change into slices as the prompt says. For a small change, one slice, review it yourself. For more, read only what splitting and the whole-change checks need (`git diff --stat`, the description, the docs it may affect) and give each slice to a `reviewer` subagent, all in parallel. Name in each request the prompt, the slice, and how to get the whole change: a range, or "uncommitted and untracked changes". 4. Merge what the subagents return. With `review.md`, do its whole-change step yourself. Check every finding at the line it cites, then report as the prompt says. -Do not edit files. +Without `.agents/review/`, do not edit files. diff --git a/.claude/skills/spec/SKILL.md b/.claude/skills/spec/SKILL.md index b6ec4e9..75bbcaf 100644 --- a/.claude/skills/spec/SKILL.md +++ b/.claude/skills/spec/SKILL.md @@ -5,6 +5,8 @@ disable-model-invocation: true argument-hint: "" --- +If the repository has `.agents/skills/implement/` (the `workflow` pack), follow `.agents/skills/spec/SKILL.md` with the request "$ARGUMENTS" instead of the steps below. + Write a spec for: $ARGUMENTS 1. Read `.agents/project.md` and the code the change will touch. Ask the user for what the repository cannot tell you: goals, constraints, deadlines. diff --git a/AGENTS.md b/AGENTS.md index ab3ec47..fa682ba 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,8 +7,9 @@ Instructions for AI coding agents working in this repository. People may find th 1. Read `.agents/project.md`, the project profile. It has the commands to install, format, lint, test and run the project, the issue tracker, the branch and commit conventions, and the language of pull requests. Where it differs from this file, the profile wins: it is this repository's own. The profile may still be the hub's blank skeleton, or leave a fact out. Then find the fact in the repository: the commands in the build and dependency files (`Makefile`, `pyproject.toml`, `package.json`, `go.mod` and the like), the CI workflows, `CONTRIBUTING.md` and the README; the default branch and the commit style in git (`git symbolic-ref refs/remotes/origin/HEAD`, `git log`). Tell the user which facts you found and where, never invent a command you did not find, and offer to write them into the profile in a pull request of its own. -2. Read the code you are about to change and the code that calls it. Do not guess what a function does from its name. -3. If the task is unclear, or turns out bigger than it looked, stop and ask. Say what you understood and what you plan to do. +2. If the repository has `CONTRIBUTING.md`, read it and follow it: the team's rules for code, git and pull requests, which go beyond "How to work" below. +3. Read the code you are about to change and the code that calls it. Do not guess what a function does from its name. +4. If the task is unclear, or turns out bigger than it looked, stop and ask. Say what you understood and what you plan to do. ## How to work @@ -37,8 +38,18 @@ Instructions for AI coding agents working in this repository. People may find th This file and some others come from your organisation's engineering-assets hub, which updates them through pull requests. Keep facts about this project in `.agents/project.md`, which belongs to this repository. If a shared file does not suit this repository, change it here: it then becomes this repository's own and the hub stops updating it. To stop receiving a file altogether, list it under `ignore` in the opt-in file (`.engineering-assets.yml`). +## Repository knowledge + +If the repository has `.agents/knowledge/`, it holds what agents learned here and would otherwise ask again: which services, resources and teams are for what, how to reach the environments, the team's decisions, work in progress, silent traps. Start from its `INDEX.md` and from your own gitignored `local.md`, whose path `python .agents/knowledge/index.py --local` prints (`python3` where `python` is not on the path); read, verify and record entries as its `README.md` says. + +## Workflows + +If the repository has `.agents/skills/implement/` (the `workflow` pack), the skills in `.agents/skills/` are the workflows: a task in the code follows `implement` (from understanding it to the report), and `new-branch`, `commit`, `pr` and `spec` run when the user asks for them. + ## Prompts - Reviewing a change: follow `.agents/prompts/review.md`. - Before refactoring: answer `.agents/prompts/refactor-check.md`. - Checking that a change keeps behaviour, such as a refactoring: follow `.agents/prompts/pure-refactor.md`. + +If the repository has `.agents/review/`, a review and a check that a change keeps behaviour follow `.agents/review/README.md` instead: an AI review by directions that the author runs before a pull request. Run it yourself once the last change of a task is committed (where you do not commit on your own, ask the user to commit first), settle its findings with the user, and only then call the task done or open the pull request. diff --git a/CLAUDE.md b/CLAUDE.md index b7fb17c..bac889d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,6 +7,6 @@ The instructions for every coding agent are in AGENTS.md, and the facts about th ## Claude Code -- Skills: `/review-change` for a review, `/review-change pure-refactor` to check that a change keeps behaviour; `/spec` before a larger change; `/new-branch`, `/commit` and `/pr`, which change the repository or the forge, run only when you invoke them. -- The `reviewer` subagent reviews a change, or one slice of a large one, in a context of its own; `/review-change` runs one per slice in parallel. +- Skills: `/review-change` for a review, `/review-change pure-refactor` to check that a change keeps behaviour; `/spec` before a larger change; `/new-branch`, `/commit` and `/pr`, which change the repository or the forge, run only when you invoke them. With the `workflow` pack (`.agents/skills/implement/`) they follow the skills of the same name in `.agents/skills/`, and `/implement` takes a task from understanding it to the report. With `.agents/knowledge/`, `/knowledge` reads, verifies and records the repository's knowledge. +- The `reviewer` subagent reviews a change, or one slice of a large one, in a context of its own; `/review-change` runs one per slice in parallel. With `.agents/review/` (the `ai-review` pack), `/review-change` runs one per direction instead and keeps a review record, and `/pr` adds its "AI Review" section. - `.claude/settings.json` only denies access to secrets. Keep your own permissions in `.claude/settings.local.json`, which is not committed. diff --git a/local/.gitignore b/local/.gitignore new file mode 100644 index 0000000..a07f80b --- /dev/null +++ b/local/.gitignore @@ -0,0 +1,4 @@ +# local/ stays on this machine: AI review records (local/reviews/), experiments, +# one-off scripts, notes. Only this file is committed. +* +!.gitignore