Skip to content

Commit 893313f

Browse files
AetherAI3dbarr5claude
authored
feat(contrib): make the loop contract machine-checked and the way in obvious (#5)
The catalog grew to 21 loops with nothing checking that a loop file actually follows the contract it claims to. Frontmatter, section order, and README coverage were conventions held up by review attention alone, and a contributor had 18 lines of CONTRIBUTING.md and no way to know whether their file was correct before opening a PR. - tools/validate_loops.py: standard-library validator for the PROTOCOL.md section 14 contract. Checks frontmatter keys and values, filename/loop-id/name agreement, all eleven sections present and in order, a fenced RUN PROMPT, duplicate ids, non-portable paths, composed-of references, README catalog coverage, and every relative markdown link in the repo. No install, so what CI runs is exactly what a contributor runs. - CI workflow running that one command on every push and pull request. - Issue forms for the three real contribution shapes: a RUN PROMPT that broke, an improvement to an existing loop, and a new loop proposal. The bug form asks which agent and model, because "it did not work" is otherwise unreproducible; it also asks whether the loop exceeded its risk class, which jumps the queue. - Pull request template carrying the run notes and the safety boundary. - CONTRIBUTING.md rewritten into a path: pick a contribution, the contract in short, the five safety requirements and why each exists, how to test a prompt, and permission to say "not run, docs only" instead of ticking a box falsely. Stale claims fixed along the way: the loop-cards title said "The 15 Agentic Loops" while shipping 21, and the README catalog table listed only the base 15 with 16-21 reachable through prose alone. PROTOCOL.md section 14 now documents read-only→branch, which four shipped loops already use, plus the parenthetical scope-note and composed-of forms the catalog relies on. The DBarr3-to-AetherAI3 badge and footer links are deliberately left alone here; PR #6 owns that change, and duplicating it would only conflict. Co-authored-by: DBarr3 <lilbenxo@gmail.com> Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
1 parent 5cb1b5c commit 893313f

11 files changed

Lines changed: 845 additions & 15 deletions

File tree

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
blank_issues_enabled: true
2+
contact_links:
3+
- name: Read the loop contract first
4+
url: https://github.com/AetherAI3/agentic-loops/blob/master/PROTOCOL.md
5+
about: Every loop shares one execution protocol. Section 14 is the file template.
6+
- name: How to contribute a loop
7+
url: https://github.com/AetherAI3/agentic-loops/blob/master/CONTRIBUTING.md
8+
about: The full path from idea to merged loop, including the local validator.

‎.github/ISSUE_TEMPLATE/loop-improvement.yml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
name: Improve an existing loop
2+
description: Tighten an exit criterion, add a missed bug class, or sharpen an adversarial persona.
3+
title: "[LOOP-NN]: "
4+
labels: ["enhancement"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
This is the highest-value contribution to the catalog and the easiest one
10+
to start with. A loop improves when a real failure mode motivated it.
11+
12+
- type: input
13+
id: loop
14+
attributes:
15+
label: Which loop
16+
placeholder: LOOP-10 (skills/LOOP-10-ai-security.md)
17+
validations:
18+
required: true
19+
20+
- type: dropdown
21+
id: kind
22+
attributes:
23+
label: What kind of change
24+
options:
25+
- Missed bug class - the loop should look for something it does not
26+
- Weak exit criteria - the loop can pass while the problem is still there
27+
- Soft adversary - the reviewer persona accepts findings it should attack
28+
- Failure routing - a failure lands in the wrong class or dead-ends
29+
- Portability - the loop assumes a stack, tool, or layout not everyone has
30+
- Wording - the RUN PROMPT is ambiguous enough that agents diverge
31+
validations:
32+
required: true
33+
34+
- type: textarea
35+
id: failure
36+
attributes:
37+
label: What failure mode motivated this?
38+
description: >
39+
The concrete thing that got through, or the false positive that wasted a
40+
review. "It would be better if" without a failure behind it is hard to
41+
act on and harder to test.
42+
validations:
43+
required: true
44+
45+
- type: textarea
46+
id: change
47+
attributes:
48+
label: Proposed change
49+
description: Which node, criterion, or persona line changes, and to what.
50+
validations:
51+
required: true
52+
53+
- type: checkboxes
54+
id: checklist
55+
attributes:
56+
label: Before you open this
57+
options:
58+
- label: The change keeps the loop inside its declared risk class, or the issue says why the class should change.
59+
required: true

‎.github/ISSUE_TEMPLATE/new-loop.yml‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
name: Propose a new loop
2+
description: Propose a new LOOP-NN for a surface the catalog does not audit yet.
3+
title: "[new loop]: "
4+
labels: ["enhancement"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
A loop is one complete audit-and-fix system in one markdown file. Before
10+
proposing one, check whether the surface is already covered by an
11+
existing loop - sharpening an existing loop is usually the better change.
12+
13+
The contract is [PROTOCOL.md](https://github.com/AetherAI3/agentic-loops/blob/master/PROTOCOL.md)
14+
section 14, and `python tools/validate_loops.py` checks it locally.
15+
16+
- type: input
17+
id: domain
18+
attributes:
19+
label: Domain
20+
description: The surface this loop audits, in the same register as the existing domains.
21+
placeholder: Data Architecture & Persistence
22+
validations:
23+
required: true
24+
25+
- type: textarea
26+
id: gap
27+
attributes:
28+
label: What does the catalog miss today?
29+
description: >
30+
Name the bug class that no current loop would find. If an existing loop
31+
is close, say which, and why extending it is worse than a new loop.
32+
validations:
33+
required: true
34+
35+
- type: dropdown
36+
id: risk
37+
attributes:
38+
label: Risk class
39+
description: PROTOCOL.md section 6. Pick the least invasive class that can still do the job.
40+
options:
41+
- read-only
42+
- read-only to branch (opens a branch only after a gate)
43+
- branch-mutating
44+
- infra-touching
45+
validations:
46+
required: true
47+
48+
- type: textarea
49+
id: dag
50+
attributes:
51+
label: Sketch the Execution DAG
52+
description: Numbered nodes, with the parallelizable ones marked.
53+
placeholder: |
54+
1. Scope capture
55+
2. [P] Static scan
56+
3. [P] Runtime probe
57+
4. Findings merge
58+
5. Adversarial verification + AUDIT-ARTIFACT
59+
validations:
60+
required: true
61+
62+
- type: textarea
63+
id: adversary
64+
attributes:
65+
label: Who is the hostile reviewer?
66+
description: >
67+
Every loop has an adversarial persona whose job is to break the loop's
68+
own findings. A vague adversary is the most common reason a loop reports
69+
confident nonsense. Name the persona and what it attacks.
70+
placeholder: >
71+
A platform SRE who assumes every green check is a check that never ran,
72+
and demands the run id and timestamp for each one.
73+
validations:
74+
required: true
75+
76+
- type: textarea
77+
id: exit
78+
attributes:
79+
label: Quantitative exit criteria
80+
description: >
81+
Numbers, not adjectives. PROTOCOL.md section 12 - a FAIL with an artifact
82+
beats a silent success.
83+
validations:
84+
required: true
85+
86+
- type: checkboxes
87+
id: checklist
88+
attributes:
89+
label: Before you open this
90+
options:
91+
- label: This loop would run on any repo with no edits beyond the target.
92+
required: true
93+
- label: I have read PROTOCOL.md section 14 and can fill in every section.
94+
required: true

‎.github/ISSUE_TEMPLATE/run-prompt-bug.yml‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
name: A loop did not work as written
2+
description: A RUN PROMPT failed, stalled, or did something the loop file does not describe.
3+
title: "[LOOP-NN]: "
4+
labels: ["bug"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Loops are prompts, so "it did not work" depends heavily on which agent
10+
ran it. The agent and the point it broke are the two things that make
11+
this reproducible.
12+
13+
- type: input
14+
id: loop
15+
attributes:
16+
label: Which loop
17+
description: The loop id and file.
18+
placeholder: LOOP-01 (skills/LOOP-01-backend-api.md)
19+
validations:
20+
required: true
21+
22+
- type: input
23+
id: agent
24+
attributes:
25+
label: Which agent, and which model
26+
description: The coding agent you pasted the RUN PROMPT into.
27+
placeholder: Claude Code, Opus 4.6
28+
validations:
29+
required: true
30+
31+
- type: textarea
32+
id: expected
33+
attributes:
34+
label: What the loop file says should happen
35+
description: Quote the node, exit criterion, or gate you were relying on.
36+
validations:
37+
required: true
38+
39+
- type: textarea
40+
id: actual
41+
attributes:
42+
label: What actually happened
43+
description: >
44+
Where it diverged. If the agent stopped at a node, name the node number.
45+
Trim transcripts to the decisive part.
46+
validations:
47+
required: true
48+
49+
- type: dropdown
50+
id: severity
51+
attributes:
52+
label: Did it stay inside its risk class?
53+
description: >
54+
A read-only loop that wrote files, or a branch-mutating loop that touched
55+
the default branch, is a safety bug and jumps the queue.
56+
options:
57+
- "Yes - it stayed inside its declared risk class"
58+
- "No - it exceeded its risk class"
59+
- "Not sure"
60+
validations:
61+
required: true
62+
63+
- type: textarea
64+
id: scope
65+
attributes:
66+
label: Target shape
67+
description: >
68+
Language, framework, and rough size of the repo you pointed it at. No
69+
need for a name or a link - a loop that only works on one stack is the
70+
bug we are looking for.
71+
validations:
72+
required: false

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
## What changes, and what failure made it necessary
2+
3+
<!--
4+
A loop changes because something got through, something false-alarmed, or
5+
something was unrunnable on a normal repo. Name it. "Improved wording" without a
6+
motivating failure is hard to review and impossible to regression-test.
7+
-->
8+
9+
## Validation
10+
11+
- [ ] `python tools/validate_loops.py` passes locally (no install needed).
12+
- [ ] I ran the changed `RUN PROMPT` against a real repo with a real agent, and the run is described below.
13+
14+
**Agent and model used:**
15+
**Target shape (language, framework, rough size):**
16+
**What the run produced:**
17+
18+
<!--
19+
If you could not run it, say so here rather than leaving it blank - a
20+
documentation-only change does not need a run, and pretending otherwise costs
21+
the next reviewer more than admitting it.
22+
-->
23+
24+
## Safety boundary
25+
26+
- [ ] The loop stays inside its declared `risk-class`, or this PR changes the class deliberately and says so.
27+
- [ ] Nothing merges to a default branch without operator approval.
28+
- [ ] No project-specific paths, hostnames, tool names, or infrastructure assumptions were introduced.
29+
30+
## For a new loop only
31+
32+
- [ ] `loop-id` and `name` match the filename.
33+
- [ ] All eleven sections from PROTOCOL.md section 14 are present, in order.
34+
- [ ] The `RUN PROMPT` is a fenced block that works verbatim.
35+
- [ ] The loop is added to the README catalog table.

‎.github/workflows/validate.yml‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
name: Validate loops
2+
3+
on:
4+
push:
5+
branches: [master]
6+
pull_request:
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
12+
jobs:
13+
contract:
14+
name: Loop contract
15+
runs-on: ubuntu-latest
16+
steps:
17+
- uses: actions/checkout@v4
18+
19+
- uses: actions/setup-python@v5
20+
with:
21+
python-version: "3.12"
22+
23+
# No install step on purpose. The validator is standard library only, so
24+
# what CI runs is exactly what a contributor runs on a fresh clone.
25+
- name: Validate every loop against PROTOCOL.md section 14
26+
run: python tools/validate_loops.py

0 commit comments

Comments
 (0)