From f0b65853c754c41ed63b5cc741dd4231aea9b657 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 3 Oct 2026 02:44:21 +0000 Subject: [PATCH] docs: point AGENTS.md at the contract The loop and the label table now have their own files. The index was repeating both. Refs #22 Co-authored-by: coreyblack --- AGENTS.md | 50 +++++++++----------------------------------------- 1 file changed, 9 insertions(+), 41 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e61bf0a..df2dede 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,7 @@ This repository is control-plane practice for the GH-600 path. The stack is bash, GitHub Actions, and Markdown. There is no application, no package manager, and no `pytest` or `npm test`. -Issue #11 is the loop contract. This file is the index an agent reads first. The checks below already enforce it. Do not invent a second process, and do not add a check unless the issue you are on asks for one. +Follow `docs/adr/agent-loop-contract.md` for how work enters, is claimed, branched, reviewed, and finished, and for the seven bans. Label meanings are in `docs/agents/triage-labels.md`. Do not invent a second process, and do not add a check unless the issue you are on asks for one. ## Commands @@ -16,51 +16,19 @@ bash .github/scripts/block-high-risk-command.sh --self-test Plan Gate (`.github/workflows/plan_gate.yml`) runs those self-tests on every pull request, then checks that pull request's body and diff. Its `GITHUB_TOKEN` is `contents: read`. -## How work moves +## Checks the contract names only in brief -1. A human adds `ready-for-agent` only when the issue body has **Goal**, **Allowed scope**, and **Success criteria**. Do not apply that label. -2. Claim by assigning yourself. Remove `ready-for-agent`. Add `in-progress`. -3. Branch from `main` only. Name it `feat/#-…`, `fix/#-…`, or `chore/#-…`. -4. Open the pull request ready for review. Include `Fixes #` or `Closes #`. Fill the plan. Stay inside the issue's Allowed scope. -5. A human merges. Merge to `main` finishes the loop. The closing keyword closes the issue. Remove `in-progress`. -6. If you cannot finish inside the scope, stop. Remove `in-progress`, add `needs-info` or `ready-for-human`, unassign yourself, and comment why. - -An Agent-plan issue is optional. Use one when Corey must approve the plan before an implementation pull request. Plan Gate reads the pull request body, not that issue. - -## Pull request plan - -| Field | Rule | -| --- | --- | -| Goal, Scope, Steps, Success criteria | Required. Plan Gate fails the pull request when one is missing or blank. | -| Risks, Rollback | Required for code changes. Optional for docs-only. Plan Gate does not read these fields. | -| Evidence | Required when a check or scan ran. Otherwise write `n/a`. | -| Review checklist | Human. Leave it for the reviewer. | - -**Scope (paths/files):** is one line of comma-separated repo paths. A changed file must equal a path or sit under it. `docs` covers `docs/02-scope-match.md`. It does not cover `docs-other/a.md`. `.` is not a path. `*` is not a path. A sentence does not cover a file it does not name. Unused paths are allowed. A rename counts the old path and the new path. The check is `docs/02-scope-match.md`. - -## When a check fails - -Revise the branch once. If that same check fails again, stop. Do not push a third time for the same failure. On the pull request, write four lines: what failed (check name and run URL), what you tried, the evidence (run URL and commit SHA), and the next step for a human. The rule is `docs/02-fail-twice.md`. - -## Do not - -1. Push or commit on `main` or `master`. -2. Merge your own pull request, including through `gh api`, `curl`, or `wget`. -3. Change rulesets or branch protection. Do not weaken or remove `CODEOWNERS`, Plan Gate, or the hook. -4. Read or print secrets. Do not commit tokens. -5. Edit a path outside the issue's Allowed scope unless a human comment widens it. Update the Scope line in the same push so the diff still matches. -6. Apply `ready-for-agent` to any issue. -7. Force-push, including `--force-with-lease` and a refspec that starts with `+`. - -`.github/hooks/block-high-risk-command.json` runs `.github/scripts/block-high-risk-command.sh` before `bash` and `powershell`. A printed `{}` means the hook has no opinion. A deny includes the reason and still exits 0. The command list and its limits are in `docs/02-hooks.md`. +- **Scope line.** `docs/02-scope-match.md`. One line of comma-separated repo paths. `.` and `*` are not paths. +- **A failed check.** `docs/02-fail-twice.md`. One revision, then stop. +- **Shell hook.** `docs/02-hooks.md`. The bans, as command text the hook denies. ## Leave these as they are -- `copilot/managed-settings.json` stays `{}`. This personal account has no enterprise MCP allow list. See `docs/03-mcp-servers-registries-allow-lists.md`. -- `agents/example-agent.md` stays commented out. Repository agents belong in `.github/agents/` and need an explicit `tools` list. Omitting `tools` grants every tool. +- `copilot/managed-settings.json` stays `{}`. See `docs/03-mcp-servers-registries-allow-lists.md`. +- `agents/example-agent.md` stays commented out. Repository agents belong in `.github/agents/` and need an explicit `tools` list. - Skills stay in `.github/skills/`. The review procedure is `.github/skills/code-review/SKILL.md`. -- Plan Gate stays traditional Actions and stays the merge check. A later agentic workflow may comment. It does not replace `require-plan`. See `docs/03-apis-and-workflows.md`. +- Plan Gate stays traditional Actions and stays the merge check. See `docs/03-apis-and-workflows.md`. ## What to build next -Open work is the checklist in issue #37. Build the first issue that is open and not blocked. Do not open a Plan Gate or hook change unless that issue asks for it. +Open work is the checklist in issue #37. Build the first issue that is open and not blocked.