From 2af376da52107a9f6baff90a6f7dac1f1b3944fc Mon Sep 17 00:00:00 2001 From: Corey Black Date: Fri, 9 Oct 2026 16:31:34 -0400 Subject: [PATCH] docs: add repository instructions and the agent-loop skill Keep AGENTS.md as the index and put the claim, branch, pull request, and stop procedure in the loop skill. Fixes #29 --- .github/copilot-instructions.md | 7 +++ .github/instructions/scripts.instructions.md | 10 +++++ .../instructions/workflows.instructions.md | 10 +++++ .github/skills/agent-loop/SKILL.md | 45 +++++++++++++++++++ AGENTS.md | 4 +- 5 files changed, 75 insertions(+), 1 deletion(-) create mode 100644 .github/copilot-instructions.md create mode 100644 .github/instructions/scripts.instructions.md create mode 100644 .github/instructions/workflows.instructions.md create mode 100644 .github/skills/agent-loop/SKILL.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..3df0458 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,7 @@ +# Copilot instructions + +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`. + +Read `AGENTS.md` first. Follow `.github/skills/agent-loop/SKILL.md` for the claim, branch, pull request, and stop procedure. Stay inside the issue's Allowed scope. + +Do not add an application, a test framework, or a `package.json`. Do not add a Plan Gate check or a hook pattern unless the issue you are on asks for one. Plan Gate stays a traditional workflow with `contents: read`. diff --git a/.github/instructions/scripts.instructions.md b/.github/instructions/scripts.instructions.md new file mode 100644 index 0000000..4a7504c --- /dev/null +++ b/.github/instructions/scripts.instructions.md @@ -0,0 +1,10 @@ +--- +applyTo: ".github/scripts/**" +--- + +# Script rules + +- Start each script with `set -euo pipefail`. +- Keep the self-test in the script. Run it with `--self-test`. +- A hook deny prints the reason and exits 0. A non-zero `preToolUse` exit would deny every later shell command. +- Do not add a Plan Gate check or a hook pattern unless the issue you are on asks for one. diff --git a/.github/instructions/workflows.instructions.md b/.github/instructions/workflows.instructions.md new file mode 100644 index 0000000..8d97b43 --- /dev/null +++ b/.github/instructions/workflows.instructions.md @@ -0,0 +1,10 @@ +--- +applyTo: ".github/workflows/**" +--- + +# Workflow rules + +- Plan Gate (`.github/workflows/plan_gate.yml`) stays a traditional GitHub Actions workflow and stays the merge check. +- Plan Gate keeps `permissions: contents: read`. +- A new workflow does not get write permissions. `contents: write` or `pull-requests: write` would let that workflow change the branch or the pull request and bypass Plan Gate. +- A later agentic workflow may comment. It does not replace `require-plan`. diff --git a/.github/skills/agent-loop/SKILL.md b/.github/skills/agent-loop/SKILL.md new file mode 100644 index 0000000..22bc86f --- /dev/null +++ b/.github/skills/agent-loop/SKILL.md @@ -0,0 +1,45 @@ +--- +name: agent-loop +description: Claim a ready-for-agent issue, branch from main, open a pull request inside Allowed scope, and stop after one failed check. Use when starting work from a GitHub issue in this repo. +--- + +# Agent loop + +The contract record is `docs/adr/agent-loop-contract.md`. Follow this procedure. Do not invent a second process. + +## Claim + +1. Start only when the issue body has **Goal**, **Allowed scope**, and **Success criteria**, and a human has applied `ready-for-agent`. +2. Assign yourself. Remove `ready-for-agent`. Add `in-progress`. +3. Do not apply `ready-for-agent` to any issue. + +## Branch + +Branch from `main` only. Name it `feat/#-…`, `fix/#-…`, or `chore/#-…`. Do not commit or push on `main` or `master`. + +## Pull request + +1. Open the pull request ready for review. +2. Include `Fixes #` or `Closes #`. +3. Fill **Goal**, **Scope**, **Steps**, and **Success criteria**. **Scope (paths/files):** is one line of comma-separated repo paths. A changed file must equal a path or sit under it. Stay inside the issue's Allowed scope. The rule is `docs/02-scope-match.md`. +4. For a code change, fill **Risks** and **Rollback**. For docs-only work those fields are optional. +5. When a check or scan ran, fill **Evidence**. Otherwise write `n/a`. The heading is exactly `## Evidence`. +6. Leave the review checklist for the human reviewer. + +## Stop + +Revise the branch once when a check fails. If that same check fails again, stop. Do not push a third time for the same failure. On the pull request, write what failed, what you tried, the evidence, and the next step for a human. The rule is `docs/02-fail-twice.md`. + +If you cannot finish inside the Allowed scope, remove `in-progress`, add `needs-info` or `ready-for-human`, unassign yourself, and comment why. + +## Bans + +1. Do not push or commit on `main` or `master`. +2. Do not merge your own pull request. +3. Do not change rulesets or branch protection. Do not weaken or remove `CODEOWNERS`, Plan Gate, or the hook. +4. Do not read or print secrets. Do not commit tokens. +5. Do not edit a path outside the issue's Allowed scope unless a human comment widens it. Update the Scope line in the same push. +6. Do not apply `ready-for-agent`. +7. Do not force-push. + +A human merges. Merge to `main` finishes the loop. The closing keyword closes the issue. Remove `in-progress`. diff --git a/AGENTS.md b/AGENTS.md index df2dede..0be45e8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,9 @@ 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`. -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. +This file is the index. The procedure is `.github/skills/agent-loop/SKILL.md`. The contract record is `docs/adr/agent-loop-contract.md`. Label meanings are in `docs/agents/triage-labels.md`. The shell hook is `docs/02-hooks.md`. Do not invent a second process, and do not add a check unless the issue you are on asks for one. + +Branch from `main` only. Name it `feat/#-…`, `fix/#-…`, or `chore/#-…`. ## Commands