From 3b8698ffe6ef31e122f814971ed9f5ea9ce8c123 Mon Sep 17 00:00:00 2001 From: Don Kackman Date: Sun, 13 Sep 2026 13:19:56 -0500 Subject: [PATCH 1/2] feat(docs): add Agent Loop documentation and update ticket template reference --- .github/ISSUE_TEMPLATE/mcp-ticket.md | 4 +- README.md | 1 + docs/AGENT_LOOP.md | 86 ++++++++++++++++++++++++++++ 3 files changed, 90 insertions(+), 1 deletion(-) create mode 100644 docs/AGENT_LOOP.md diff --git a/.github/ISSUE_TEMPLATE/mcp-ticket.md b/.github/ISSUE_TEMPLATE/mcp-ticket.md index d22c4b91..2011ba07 100644 --- a/.github/ISSUE_TEMPLATE/mcp-ticket.md +++ b/.github/ISSUE_TEMPLATE/mcp-ticket.md @@ -1,10 +1,12 @@ --- name: MCP agent-loop ticket -about: Filed by the implementer/tester agent loop (see the iterate repo's CLAUDE.md) — not for human bug reports, use "Bug report" for those. +about: Filed by the implementer/tester agent loop (see docs/AGENT_LOOP.md) — not for human bug reports, use "Bug report" for those. title: "" labels: ["owner:implementer"] --- + + **tool/endpoint:** which MCP tool or method this concerns **repro:** exact call made (tool name + params, or command run) diff --git a/README.md b/README.md index ef382219..12a62a8a 100644 --- a/README.md +++ b/README.md @@ -220,3 +220,4 @@ frame interpolation and more. - [Security](docs/SECURITY.md) — Security model - [Testing](docs/TESTING.md) — Running the test suite - [Releasing](docs/RELEASING.md) — Cutting a release from a version tag +- [Agent Loop](docs/AGENT_LOOP.md) — What the automated implementer/tester ticket labels mean, for anyone joining an Issue diff --git a/docs/AGENT_LOOP.md b/docs/AGENT_LOOP.md new file mode 100644 index 00000000..600ece0b --- /dev/null +++ b/docs/AGENT_LOOP.md @@ -0,0 +1,86 @@ +# Agent Loop + +Some of the Issues in this repo are worked by an automated implementer/tester +agent loop, not a human. It lives in a separate repo +([`dkackman/iterate`](https://github.com/dkackman/iterate) — private) that +drives two Claude Code agents in strict alternation against this repo's +Issues. Nothing about running the loop lives here; this page exists so that +anyone who opens or comments on one of its Issues — a human, or another +agent joining in — knows how to act on it correctly. + +## The two roles + +- **Implementer** — has this repo checked out and SSH access to the box + running the MCP server. Reproduces, fixes, deploys, and hands the ticket + back. Never verifies its own fix. +- **Tester** — talks to the MCP server only as a protocol client (MCP tool + calls), no source checkout, no shell/SSH access to the server box. Its job + is independent verification: it re-runs the original repro over MCP and + either confirms the fix or bounces the ticket back. + +That asymmetry — the only role that can mark an issue verified is the one +with no ability to patch around a bug — is the entire point of the loop. A +human or third agent joining in should preserve it: don't fix and verify the +same ticket yourself. + +A third, standalone **regression agent** periodically runs a growing suite +of scripted MCP calls (`regression-suite-*.md` in the `iterate` repo) against +the live server and files/comments on Issues for anything that regresses. It +doesn't participate in the implementer/tester handoff. + +## Reading a ticket + +Tickets use the **MCP agent-loop ticket** issue template. Two label +families carry all the state — check both before acting: + +- **`owner:*`** — exactly one of `owner:implementer` / `owner:tester` / + `owner:don` at a time: whoever is expected to act on it next. If you're + not that owner, leave the issue alone beyond reading it (or the specific + handoff comment/label a role prompt allows). +- **`status:*`** — where the ticket is in its lifecycle: + - *(no status label)* — open, ready for the implementer to reproduce. + - `status:fixed-pending-verify` — implementer has fixed and deployed; + waiting on the tester to re-run the repro over MCP. + - `status:verified` — tester confirmed the fix over MCP; issue is closed + as `completed`. + - `status:needs-info` — a question bounce; whoever is asked needs to + answer before work continues. + - `status:needs-approval` (+ `owner:don`) — parked for the human. The + implementer uses this for anything beyond a rename-level change + (engine behavior, breaking syntax). Neither agent touches a parked + issue. + +Two built-in GitHub labels close a ticket without a fix: + +- **`wontfix`** — the implementer's call, with a reason in a comment; issue + closed as `not planned`. The tester may reopen once with new evidence; a + second `wontfix` is final. +- **`duplicate`** — closed as `not planned`, with a comment naming the + issue it duplicates (`duplicate of #NN`). A closed issue is still + canonical for duplicate detection — the implementer checks + `gh issue list --state all` before starting work, not just open issues. + +`breaking-change` marks an Issue whose fix changed the MCP interface, so the +tester adjusts its calls instead of filing the change as a new bug. + +## If you want to participate + +Whether you're a human or another agent: + +- Only touch an issue that's currently owned by you (or, for a human, one + parked with `owner:don`). +- When you hand a ticket to the next owner, swap the `owner:*` label and + say what you did in a comment — the next actor has no memory of this + session, only the issue thread. +- Keep implementer and tester roles separate. If you're fixing code, don't + also close the issue as verified — that requires an independent MCP call + from someone who didn't write the patch. +- Reference the issue number in any commit that fixes it + (`fix(mcp): #42 - ...`), and work on a branch merged to `develop`, never + `master`. +- Only the tester (or an equivalently independent verifier) closes an issue + as `completed`/`status:verified`, and only after a real MCP call + reproduces the fix — not by reading the diff. + +See the `iterate` repo's `CLAUDE.md` for the full protocol this is +summarized from, including how the automated loop itself is run. From 94a6f3d83f30b0591a8ffcffd50caae8108170e5 Mon Sep 17 00:00:00 2001 From: Don Kackman Date: Sun, 13 Sep 2026 13:26:32 -0500 Subject: [PATCH 2/2] docs: point issue template's label explanation at docs/AGENT_LOOP.md Avoid two partial, driftable descriptions of the owner/status label scheme in one repo. Co-Authored-By: Claude Sonnet 5 --- .github/ISSUE_TEMPLATE/mcp-ticket.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/mcp-ticket.md b/.github/ISSUE_TEMPLATE/mcp-ticket.md index 2011ba07..cfc4799b 100644 --- a/.github/ISSUE_TEMPLATE/mcp-ticket.md +++ b/.github/ISSUE_TEMPLATE/mcp-ticket.md @@ -5,8 +5,6 @@ title: "" labels: ["owner:implementer"] --- - - **tool/endpoint:** which MCP tool or method this concerns **repro:** exact call made (tool name + params, or command run) @@ -16,10 +14,8 @@ labels: ["owner:implementer"] **actual:**