Skip to content

Commit 384c4c3

Browse files
Cobus GreylingCobus Greyling
Cobus Greyling
authored and
Cobus Greyling
committed
feat: implement all 17 loop-engineering improvements
- loop-audit v1.3.0: unit tests, CHANGELOG, release workflow - loop-init scaffold CLI for all five patterns and three tools - Complete starters: dependency-sweeper, post-merge-cleanup, Claude/Codex L2 variants - Daily triage dogfood workflow; PR audit comments in CI - Registry JSON schema validation; expanded registry metadata - Docs: pattern-picker, anti-patterns, multi-loop, SECURITY.md - MCP connector cookbook; loop-run-log and loop-budget templates - Three new failure stories; showcase and README updates - Primitives matrix appendix for Cursor/Windsurf/Aider
1 parent 37922a9 commit 384c4c3

70 files changed

Lines changed: 2521 additions & 129 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/audit.yml‎

Lines changed: 38 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
name: Loop Readiness Audit (dogfood)
22

3+
permissions:
4+
contents: read
5+
pull-requests: write
6+
37
on:
48
push:
59
branches: [main]
@@ -21,11 +25,11 @@ jobs:
2125
cache: 'npm'
2226
cache-dependency-path: tools/loop-audit/package-lock.json
2327

24-
- name: Build & run loop-audit on the reference + starters
28+
- name: Build, test & run loop-audit on the reference + starters
2529
run: |
2630
cd tools/loop-audit
2731
npm ci
28-
npm run build
32+
npm test
2933
echo "=== Audit of repo root ==="
3034
node dist/cli.js ../../ || true
3135
echo ""
@@ -54,3 +58,35 @@ jobs:
5458
process.exit(0); // do not fail the whole job on parse issues
5559
}
5660
')
61+
62+
- name: Comment PR with loop readiness score
63+
if: github.event_name == 'pull_request'
64+
uses: actions/github-script@v7
65+
with:
66+
script: |
67+
const fs = require('fs');
68+
let data;
69+
try {
70+
data = JSON.parse(fs.readFileSync('/tmp/audit.json', 'utf8'));
71+
} catch (e) {
72+
core.setFailed('Could not read audit JSON for PR comment');
73+
return;
74+
}
75+
const recs = (data.recommendations || []).slice(0, 5);
76+
const body = [
77+
'## Loop Readiness Audit',
78+
'',
79+
`**Score:** ${data.score}/100 (**${data.level}**)`,
80+
'',
81+
data.assessment,
82+
'',
83+
recs.length ? '### Top suggestions\n' + recs.map(r => `- ${r}`).join('\n') : '_No suggestions — looking good._',
84+
'',
85+
'<sub>Posted by `audit.yml` · [loop-audit docs](https://github.com/cobusgreyling/loop-engineering/tree/main/tools/loop-audit)</sub>',
86+
].join('\n');
87+
await github.rest.issues.createComment({
88+
owner: context.repo.owner,
89+
repo: context.repo.repo,
90+
issue_number: context.issue.number,
91+
body,
92+
});

‎.github/workflows/daily-triage.yml‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
name: Daily Triage (dogfood)
2+
3+
on:
4+
schedule:
5+
- cron: '0 8 * * 1-5'
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: write
10+
issues: write
11+
12+
jobs:
13+
triage:
14+
runs-on: ubuntu-latest
15+
steps:
16+
- uses: actions/checkout@v4
17+
18+
- uses: actions/setup-node@v4
19+
with:
20+
node-version: '20'
21+
cache: 'npm'
22+
cache-dependency-path: tools/loop-audit/package-lock.json
23+
24+
- name: Build loop-audit
25+
run: |
26+
cd tools/loop-audit
27+
npm ci
28+
npm run build
29+
30+
- name: Run reference audit
31+
id: audit
32+
run: |
33+
cd tools/loop-audit
34+
node dist/cli.js ../.. --json > /tmp/audit.json
35+
SCORE=$(node -e "console.log(JSON.parse(require('fs').readFileSync('/tmp/audit.json','utf8')).score)")
36+
LEVEL=$(node -e "console.log(JSON.parse(require('fs').readFileSync('/tmp/audit.json','utf8')).level)")
37+
echo "score=$SCORE" >> "$GITHUB_OUTPUT"
38+
echo "level=$LEVEL" >> "$GITHUB_OUTPUT"
39+
40+
- name: Check workflow health
41+
id: workflows
42+
run: |
43+
FAILING=0
44+
for wf in validate-patterns audit; do
45+
STATUS=$(gh run list --workflow="${wf}.yml" --limit 1 --json conclusion -q '.[0].conclusion' 2>/dev/null || echo "unknown")
46+
echo "${wf}: ${STATUS}"
47+
if [ "$STATUS" = "failure" ]; then FAILING=$((FAILING + 1)); fi
48+
done
49+
echo "failing=$FAILING" >> "$GITHUB_OUTPUT"
50+
env:
51+
GH_TOKEN: ${{ github.token }}
52+
53+
- name: Update STATE.md
54+
run: |
55+
DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
56+
SCORE="${{ steps.audit.outputs.score }}"
57+
LEVEL="${{ steps.audit.outputs.level }}"
58+
FAILING="${{ steps.workflows.outputs.failing }}"
59+
cat > STATE.md <<EOF
60+
# Loop State — loop-engineering reference
61+
62+
Last run: ${DATE} (automated daily-triage workflow)
63+
64+
## High Priority (loop is acting or waiting on human)
65+
66+
- Maintain loop readiness score ≥ 58 (current: **${SCORE}**, level **${LEVEL}**).
67+
- Publish \`@cobusgreyling/loop-audit\` to npm if not yet live (enables \`npx\` installs).
68+
$([ "$FAILING" -gt 0 ] && echo "- **${FAILING}** dogfood workflow(s) failing — investigate CI.")
69+
70+
## Watch List
71+
72+
- Expand contributor failure stories (dependency sweeper, multi-loop).
73+
- Complete Claude Code / Codex starters for all L2 patterns.
74+
- Run \`loop-init\` on a fresh project and verify scaffold output.
75+
76+
## Recent Noise (ignored this run)
77+
78+
—
79+
80+
---
81+
Run log: Updated by \`.github/workflows/daily-triage.yml\`. See \`LOOP.md\` for cadence and gates.
82+
EOF
83+
84+
- name: Commit STATE.md if changed
85+
run: |
86+
git config user.name "loop-engineering-bot"
87+
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
88+
git add STATE.md
89+
git diff --staged --quiet || git commit -m "chore(loop): daily triage update STATE.md [automated]"
90+
git push || echo "No push needed or nothing to commit"
91+
92+
- name: Open weekly loop report issue (Mondays)
93+
if: github.event.schedule == '0 8 * * 1-5' && format('{0}', github.run_attempt) == '1'
94+
run: |
95+
DAY=$(date -u +%u)
96+
if [ "$DAY" != "1" ]; then echo "Not Monday — skip issue"; exit 0; fi
97+
EXISTING=$(gh issue list --label "loop-report" --state open --limit 1 --json number -q '.[0].number' 2>/dev/null || true)
98+
if [ -n "$EXISTING" ] && [ "$EXISTING" != "null" ]; then
99+
echo "Open loop-report issue #$EXISTING exists"
100+
exit 0
101+
fi
102+
gh label create "loop-report" --color "3ee8c5" --description "Weekly loop triage report" 2>/dev/null || true
103+
gh issue create \
104+
--title "Loop report — week of $(date -u +%Y-%m-%d)" \
105+
--label "loop-report" \
106+
--body "## Automated daily triage summary
107+
108+
- Loop readiness: **${{ steps.audit.outputs.score }}** (${{ steps.audit.outputs.level }})
109+
- See updated \`STATE.md\` on main
110+
- Review high-priority items and close or re-prioritize
111+
112+
_Generated by daily-triage workflow. Human reviews and decides actions._"
113+
env:
114+
GH_TOKEN: ${{ github.token }}

‎.github/workflows/release-loop-audit.yml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
name: Release loop-audit
2+
3+
on:
4+
push:
5+
tags:
6+
- 'loop-audit-v*'
7+
8+
permissions:
9+
contents: read
10+
id-token: write
11+
12+
jobs:
13+
test-and-publish:
14+
runs-on: ubuntu-latest
15+
steps:
16+
- uses: actions/checkout@v4
17+
18+
- uses: actions/setup-node@v4
19+
with:
20+
node-version: '20'
21+
registry-url: 'https://registry.npmjs.org'
22+
cache: 'npm'
23+
cache-dependency-path: tools/loop-audit/package-lock.json
24+
25+
- name: Install, build, test
26+
working-directory: tools/loop-audit
27+
run: |
28+
npm ci
29+
npm run build
30+
npm test
31+
32+
- name: Publish to npm
33+
working-directory: tools/loop-audit
34+
run: npm publish --access public
35+
env:
36+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

‎.github/workflows/release-loop-init.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: Release loop-init
2+
3+
on:
4+
push:
5+
tags:
6+
- 'loop-init-v*'
7+
8+
permissions:
9+
contents: read
10+
id-token: write
11+
12+
jobs:
13+
publish:
14+
runs-on: ubuntu-latest
15+
steps:
16+
- uses: actions/checkout@v4
17+
18+
- uses: actions/setup-node@v4
19+
with:
20+
node-version: '20'
21+
registry-url: 'https://registry.npmjs.org'
22+
23+
- name: Build & publish
24+
working-directory: tools/loop-init
25+
run: |
26+
npm install
27+
npm run build
28+
npm publish --access public
29+
env:
30+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

‎.github/workflows/validate-patterns.yml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,4 +39,11 @@ jobs:
3939
run: |
4040
test -f templates/pattern-template.md || (echo "Missing pattern-template.md"; exit 1)
4141
test -f templates/STATE.md.template || (echo "Missing STATE template"; exit 1)
42+
test -f templates/loop-run-log.md.template || (echo "Missing loop-run-log template"; exit 1)
43+
test -f templates/loop-budget.md.template || (echo "Missing loop-budget template"; exit 1)
4244
echo "Templates present ✓"
45+
46+
- name: Validate registry.yaml schema
47+
run: |
48+
npm install --no-save yaml@2
49+
node scripts/validate-registry.mjs

‎CONTRIBUTING.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -50,8 +50,10 @@ Also add an entry to `patterns/registry.yaml`.
5050
- Failures are first-class content
5151
- Tool-agnostic by default; tool-specific in labeled sections
5252

53-
## Questions
53+
## Community
5454

55-
Open an issue with label `question` or `pattern-request`.
55+
- **Questions**: open an issue with label `question` or `pattern-request`
56+
- **Discussions**: enable GitHub Discussions on the repo for pattern Q&A (recommended for maintainers)
57+
- **Security**: see [SECURITY.md](./SECURITY.md) — do not file public issues for exploitable vulnerabilities
5658

5759
Thank you for helping make this the go-to reference for loop engineering.

‎LOOP.md‎

Lines changed: 36 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,71 +1,68 @@
11
# LOOP.md — Loop Engineering Reference
22

3-
This file documents how the **loop-engineering** reference repository itself is (or will be) operated with loop engineering patterns.
3+
This file documents how the **loop-engineering** reference repository is operated with loop engineering patterns.
44

5-
The goal of this repo is to be the canonical, copyable, high-signal collection of patterns, starters, and tooling. It should therefore eat its own dogfood aggressively.
5+
The goal of this repo is to be the canonical, copyable, high-signal collection of patterns, starters, and tooling. It eats its own dogfood aggressively.
66

7-
## Intended Loops (phased)
7+
## Active Loops
88

9-
### Daily Triage (L1 → L2)
10-
- Cadence: 1d (or 2h during active development)
11-
- Skill: loop-triage (from `starters/minimal-loop`)
12-
- State: STATE.md (or this file + issues)
13-
- Current phase: Report-only. Human reviews the report each day and decides what to action.
9+
### Daily Triage (L1 — automated + report)
10+
- Cadence: 1d weekdays (`/.github/workflows/daily-triage.yml`)
11+
- Skill: `loop-triage` (from `skills/` and `starters/minimal-loop`)
12+
- State: `STATE.md` (updated by workflow; human reviews weekly issue)
13+
- Phase: Report-only. Human reviews and decides actions.
1414
- Handoff: Design decisions, large refactors, new pattern acceptance.
1515

16-
### PR Babysitter (future, L2)
17-
- Cadence: 10–15m during active hours
18-
- Uses the `pr-babysitter` starter + worktrees for any suggested fixes.
19-
- Will live primarily in the GitHub Actions + comments on PRs.
20-
- Strong verifier + explicit allowlist for auto-merge (very small safe changes only).
16+
### PR Babysitter (L2 — assisted, manual trigger)
17+
- Cadence: 10–15m during active hours (maintainer `/loop` or future Action)
18+
- Starter: `starters/pr-babysitter` (Grok, Claude Code, Codex)
19+
- Worktrees for suggested fixes; verifier required; no auto-merge by default.
2120

22-
### Dependency Sweeper (L2, just added)
21+
### Dependency Sweeper (L2 — patch-only)
2322
- Cadence: 6h–1d
24-
- New pattern + starter added in this iteration.
25-
- Focus: patch + low-risk CVE only for the first 30 days.
26-
- Verifier = full `npm ci && npm test` (or the build that exists) in worktree.
27-
- Human gate on anything that touches core packages or majors.
23+
- Starter: `starters/dependency-sweeper`
24+
- Patch + low-risk CVE only for first 30 days
25+
- Verifier = full `npm ci && npm test` in worktree
26+
- Human gate on majors and denylisted packages
2827

2928
### CI Sweeper / Post-Merge (opportunistic)
30-
- The `validate-patterns.yml` + `audit.yml` workflows in `.github/workflows/` are the beginning of dogfooding these patterns.
31-
- Future: a sweeper that reacts to failing validate/audit runs with minimal doc or link fixes.
29+
- `validate-patterns.yml` + `audit.yml` dogfood pattern validation and readiness scoring
30+
- `audit.yml` posts loop readiness scores on PRs
31+
- Future: sweeper reacting to failing validate/audit runs
32+
33+
## Multi-loop coordination
34+
35+
See [docs/multi-loop.md](docs/multi-loop.md). Priority: CI Sweeper → PR Babysitter → Dependency Sweeper → Post-Merge → Daily Triage (report).
3236

3337
## Worktrees
3438

35-
- Any unattended code-change experiment (dependency sweeper, PR babysitter fixes) runs in an **isolated git worktree** per attempt.
39+
- Any unattended code-change experiment runs in an **isolated git worktree** per attempt.
3640
- One worktree per fix; discard after verifier REJECT or human escalation.
37-
- Starters document worktree usage per tool — see `starters/minimal-loop-claude/LOOP.md` and `starters/minimal-loop-codex/LOOP.md`.
3841

3942
## Connectors (MCP)
4043

41-
- **MCP not required** for L1 daily triage on this reference repo.
42-
- Optional: GitHub MCP for issue/PR discovery when moving to L2 PR babysitter.
43-
- Scope connectors to read + comment until the loop is trusted.
44+
- Optional for L1 daily triage — see [examples/mcp/](examples/mcp/)
45+
- GitHub MCP read-only for issue/PR discovery
46+
- Scope connectors to read + comment until the loop is trusted
4447

4548
## Safety & Gates (this repo)
4649

47-
- No auto-merge on main for anything except the most trivial dependency patches (and even those are behind allowlist + verifier today).
48-
- Denylist for this reference: anything touching the showcase HTML/CSS, the core primitives docs, or the audit scoring logic without human review.
49-
- Live loop state: `STATE.md` at repo root (dogfooded). Starters still ship `.example` files for consumers.
50-
51-
## How to run the loops here (for contributors / the maintainer)
50+
- No auto-merge on main except trivial dependency patches (allowlist + verifier)
51+
- Denylist: showcase HTML/CSS, core primitives docs, audit scoring logic without human review
52+
- Live loop state: `STATE.md` at repo root
5253

53-
See the individual pattern docs and the GitHub Actions.
54-
55-
Quick local check:
54+
## How to run locally
5655

5756
```bash
5857
node tools/loop-audit/dist/cli.js . --suggest
58+
npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok # after npm publish
59+
bash scripts/before-after-demo.sh
5960
```
6061

61-
After changes to patterns, starters, or docs, the `validate-patterns` + `audit` workflows will run automatically on PRs.
62-
6362
## Evolution
6463

65-
We will raise the L level of this repo itself over time and record the journey in `stories/`.
66-
67-
Current target for the reference: solid L2 with excellent observability and zero "I had to hand-hold the loop for an hour" stories.
64+
Journey recorded in `stories/`. Target: solid L2 with excellent observability.
6865

6966
---
7067

71-
*This file is both documentation and the seed for the loops that will maintain the reference.*
68+
*This file is both documentation and the seed for the loops that maintain the reference.*

0 commit comments

Comments
 (0)