Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.
TypeScript agentic-aiai-agentsai-codinganthropicautomationclaudeclaude-codecodexcoding-agentsdevops-automationdevtoolsgithub-actionsgrokllmloop-engineeringmcpprompt-engineering
Add npm-ready loop-audit, Claude/Codex starters, and L3 dogfooding
Cobus Greyling37922a9a267e
diff --git a/.github/workflows/audit.yml b/.github/workflows/audit.ymlindex 904e262..f22b25f 100644--- a/.github/workflows/audit.yml+++ b/.github/workflows/audit.yml@@ -44,11 +44,9 @@ jobs:try {const data = JSON.parse(fs.readFileSync("/tmp/audit.json", "utf8"));console.log("Reference score: " + data.score);- // The reference repo is the *source* of starters/skills, not a running project.- // It will naturally score lower until we decide to dogfood a .grok/ or STATE at root.- // Keep a low bar here; the value is that the audit *runs* and surfaces findings.- if (data.score < 25) {- console.error("Reference score critically low. Consider adding LOOP.md state signals or .github improvements.");+ // Reference repo dogfoods L2: STATE.md, skills/, AGENTS.md, LOOP.md gates.+ if (data.score < 58) {+ console.error("Reference score below L2 threshold (58). Restore dogfood signals: STATE.md, skills/, AGENTS.md.");process.exit(2);}} catch (e) {diff --git a/.gitignore b/.gitignoreindex 380f16e..706332c 100644--- a/.gitignore+++ b/.gitignore@@ -30,8 +30,9 @@ build/!tools/loop-audit/dist/*.egg-info/-# State files that should not be committed in examples+# State files that should not be committed in consumer projects (reference repo dogfoods STATE.md)STATE.md+!STATE.mdstate.json*.state@@ -40,5 +41,9 @@ state.json!starters/**/.grok/!starters/**/.grok/**.claude/+!starters/**/.claude/+!starters/**/.claude/**.codex/+!starters/**/.codex/+!starters/**/.codex/***.sessiondiff --git a/AGENTS.md b/AGENTS.mdnew file mode 100644index 0000000..f86e5a3--- /dev/null+++ b/AGENTS.md@@ -0,0 +1,39 @@+# AGENTS.md — loop-engineering reference++Conventions for humans and loops maintaining this repository.++## Build & verify++```bash+# Loop readiness audit CLI+cd tools/loop-audit && npm ci && npm run build+node dist/cli.js ../.. # audit repo root+node dist/cli.js ../.. --suggest # show copy commands for gaps++# Before/after demo (scores an empty dir → starter → L2)+bash scripts/before-after-demo.sh+```++CI runs `validate-patterns` and `audit` on every push/PR (see `.github/workflows/`).++## Review norms++- Patterns and starters must stay **tool-agnostic in intent**; tool-specific paths live under `examples/` and per-tool starters.+- Never auto-merge changes to `docs/primitives*.md`, `tools/loop-audit/src/`, or showcase assets without human review.+- Failure stories in `stories/` should include token cost, root cause, and remediation — not just wins.+- New patterns require an entry in `patterns/registry.yaml`.++## Loop operation (this repo)++- **Daily triage**: `loop-triage` skill → `STATE.md` (report-only, L1).+- **Fixes**: only via PR with human review; `minimal-fix` + `loop-verifier` for assisted changes (L2).+- **Isolation**: use git worktrees for any unattended code-change experiments (see `LOOP.md`).++## Test commands++This repo has no application test suite. Quality gates:++```bash+cd tools/loop-audit && npm run build && node dist/cli.js ../../+bash scripts/before-after-demo.sh+```\ No newline at end of filediff --git a/LOOP.md b/LOOP.mdindex 2241246..796a2ff 100644--- a/LOOP.md+++ b/LOOP.md@@ -30,11 +30,23 @@ The goal of this repo is to be the canonical, copyable, high-signal collection o- The `validate-patterns.yml` + `audit.yml` workflows in `.github/workflows/` are the beginning of dogfooding these patterns.- Future: a sweeper that reacts to failing validate/audit runs with minimal doc or link fixes.+## Worktrees++- Any unattended code-change experiment (dependency sweeper, PR babysitter fixes) runs in an **isolated git worktree** per attempt.+- One worktree per fix; discard after verifier REJECT or human escalation.+- Starters document worktree usage per tool — see `starters/minimal-loop-claude/LOOP.md` and `starters/minimal-loop-codex/LOOP.md`.++## Connectors (MCP)++- **MCP not required** for L1 daily triage on this reference repo.+- Optional: GitHub MCP for issue/PR discovery when moving to L2 PR babysitter.+- Scope connectors to read + comment until the loop is trusted.+## Safety & Gates (this repo)- No auto-merge on main for anything except the most trivial dependency patches (and even those are behind allowlist + verifier today).- Denylist for this reference: anything touching the showcase HTML/CSS, the core primitives docs, or the audit scoring logic without human review.-- All state that would be "live" lives in `.example` files or is maintained by the workflows (never committed live STATE).+- Live loop state: `STATE.md` at repo root (dogfooded). Starters still ship `.example` files for consumers.## How to run the loops here (for contributors / the maintainer)diff --git a/README.md b/README.mdindex 9c627b5..3eacfc1 100644--- a/README.md+++ b/README.md@@ -33,8 +33,8 @@ A loop is a recursive goal: you define a purpose and the AI iterates (often with| [Primitives Matrix](docs/primitives-matrix.md) | Grok vs Claude Code vs Codex — **bookmark this** || [Loop Design Checklist](docs/loop-design-checklist.md) | Ship readiness rubric || [Patterns](patterns/README.md) | PR babysitter, daily triage, CI sweeper, post-merge |-| [Starters](starters/minimal-loop/) | Clone-and-run kits |-| [loop-audit](tools/loop-audit/) | Loop Readiness Score CLI |+| [Starters](starters/) | Clone-and-run kits (Grok, Claude Code, Codex) |+| [loop-audit](tools/loop-audit/) | Loop Readiness Score CLI — `npx @cobusgreyling/loop-audit` || [Stories](stories/) | Real wins and honest failures |## Why This Matters@@ -94,15 +94,22 @@ Machine-readable index: [patterns/registry.yaml](patterns/registry.yaml)## Getting Started (5 minutes)```bash-# 1. Clone this repo or copy a starter into your project+# 1. Pick a starter for your tool+# Grok:cp -r starters/minimal-loop/.grok/skills/loop-triage .grok/skills/+# Claude Code:+cp -r starters/minimal-loop-claude/.claude/skills/loop-triage .claude/skills/+# Codex:+cp -r starters/minimal-loop-codex/.codex/skills/loop-triage .codex/skills/cp starters/minimal-loop/STATE.md.example STATE.md-# 2. Audit readiness-cd tools/loop-audit && npm install && npm run build-node dist/cli.js /path/to/your/project+# 2. Audit readiness (no clone required)+npx @cobusgreyling/loop-audit . --suggest-# 3. Start report-only (Grok)+# 3. See scores climb: empty → L1 → L2+bash scripts/before-after-demo.sh++# 4. Start report-only (Grok example)/loop 1d Run loop-triage. Update STATE.md. No auto-fix in week one.```diff --git a/STATE.md b/STATE.mdnew file mode 100644index 0000000..f0cd839--- /dev/null+++ b/STATE.md@@ -0,0 +1,20 @@+# Loop State — loop-engineering reference++Last run: not yet automated (maintainer or daily triage loop updates this)++## High Priority (loop is acting or waiting on human)++- Dogfood L2 on the reference repo itself (STATE, skills, AGENTS.md, audit gate ≥ 58).+- Publish `@cobusgreyling/loop-audit` to npm for `npx` installs.++## Watch List++- Add more contributor-submitted failure stories.+- Expand Claude Code / Codex starters beyond daily triage.++## Recent Noise (ignored this run)++—++---+Run log: Initialized for reference-repo dogfooding. See `LOOP.md` for cadence and gates.\ No newline at end of filediff --git a/docs/primitives-matrix.md b/docs/primitives-matrix.mdindex d9af956..f4db382 100644--- a/docs/primitives-matrix.md+++ b/docs/primitives-matrix.md@@ -60,4 +60,14 @@ You do not need to pick one forever. A well-designed loop transfers:3. Document the **verification split** (who checks whom)4. Map scheduling to your current TUI or Action-See [examples/](../examples/) for the same pattern implemented across tools.\ No newline at end of file+See [examples/](../examples/) for the same pattern implemented across tools.++## Copy-paste starters (Daily Triage, L1)++| Tool | Starter |+|------|---------|+| Grok | [starters/minimal-loop](../starters/minimal-loop/) |+| Claude Code | [starters/minimal-loop-claude](../starters/minimal-loop-claude/) |+| Codex | [starters/minimal-loop-codex](../starters/minimal-loop-codex/) |++Audit after copying: `npx @cobusgreyling/loop-audit . --suggest`\ No newline at end of filediff --git a/examples/README.md b/examples/README.mdindex a6c4c06..9b9656b 100644--- a/examples/README.md+++ b/examples/README.md@@ -9,4 +9,12 @@ Same patterns, different tools. Skills and state schemas are shared; only schedu| Codex App | [codex/](./codex/) || GitHub Actions | [github-actions/](./github-actions/) |-Start with [primitives-matrix.md](../docs/primitives-matrix.md) to map capabilities.\ No newline at end of file+Start with [primitives-matrix.md](../docs/primitives-matrix.md) to map capabilities.++**Copy-paste starters** (L1 daily triage):++| Tool | Starter |+|------|---------|+| Grok | [starters/minimal-loop](../starters/minimal-loop/) |+| Claude Code | [starters/minimal-loop-claude](../starters/minimal-loop-claude/) |+| Codex | [starters/minimal-loop-codex](../starters/minimal-loop-codex/) |\ No newline at end of filediff --git a/scripts/before-after-demo.sh b/scripts/before-after-demo.shnew file mode 100755index 0000000..27193e5--- /dev/null+++ b/scripts/before-after-demo.sh@@ -0,0 +1,56 @@+#!/usr/bin/env bash+# Demonstrates loop readiness scores: empty project → L1 starter → L2 (+ verifier).+set -euo pipefail++ROOT="$(cd "$(dirname "$0")/.." && pwd)"+AUDIT="$ROOT/tools/loop-audit/dist/cli.js"+TMP="$(mktemp -d)"+trap 'rm -rf "$TMP"' EXIT++if [[ ! -f "$AUDIT" ]]; then+ echo "Building loop-audit..."+ (cd "$ROOT/tools/loop-audit" && npm ci --silent && npm run build --silent)+fi++run_audit() {+ local label="$1"+ local path="$2"+ echo ""+ echo "══════════════════════════════════════════════════"+ echo "$label"+ echo "══════════════════════════════════════════════════"+ node "$AUDIT" "$path" || true+}++echo "Loop Readiness — before/after demo"+echo "Temp project: $TMP"++# Stage 0: empty directory+run_audit "Stage 0 — empty project (baseline)" "$TMP"++# Stage 1: copy Grok minimal-loop starter (L1)+mkdir -p "$TMP/.grok/skills"+cp -r "$ROOT/starters/minimal-loop/.grok/skills/loop-triage" "$TMP/.grok/skills/"+cp "$ROOT/starters/minimal-loop/STATE.md.example" "$TMP/STATE.md"+cp "$ROOT/starters/minimal-loop/LOOP.md" "$TMP/LOOP.md"+run_audit "Stage 1 — after minimal-loop starter (L1 report-only)" "$TMP"++# Stage 2: add verifier + AGENTS.md (L2)+mkdir -p "$TMP/.grok/skills/loop-verifier"+cp "$ROOT/templates/SKILL.md.verifier" "$TMP/.grok/skills/loop-verifier/SKILL.md"+cat > "$TMP/AGENTS.md" <<'EOF'+# AGENTS.md++## Test commands+npm test+npm run lint+EOF+run_audit "Stage 2 — after verifier + AGENTS.md (L2 assisted)" "$TMP"++echo ""+echo "Done. Copy a starter for your tool:"+echo " Grok: cp -r starters/minimal-loop/.grok/skills/loop-triage .grok/skills/"+echo " Claude Code: cp -r starters/minimal-loop-claude/.claude/skills/loop-triage .claude/skills/"+echo " Codex: cp -r starters/minimal-loop-codex/.codex/skills/loop-triage .codex/skills/"+echo ""+echo "Audit your project: npx @cobusgreyling/loop-audit . --suggest"\ No newline at end of filediff --git a/skills/loop-triage/SKILL.md b/skills/loop-triage/SKILL.mdnew file mode 100644index 0000000..6ca6e91--- /dev/null+++ b/skills/loop-triage/SKILL.md@@ -0,0 +1,46 @@+---+name: loop-triage+description: >+ Triage recent changes, CI failures, issues, and conversations.+ Produces a concise, actionable findings report suitable for a loop to consume.+ Writes structured output to a state file or Linear board.+user_invocable: true+---++# Loop Triage Skill++You are an expert engineering triage agent. Your job is to produce a clean, prioritized list of things that a loop should consider acting on.++## Inputs (the loop will provide these)+- Recent CI / test failures (last 24h)+- Open issues / Linear tickets assigned to the team+- Recent commits on main (last 24–48h)+- Any Slack / chat threads the loop has visibility into+- The current state file (what the loop already knows about)++## Output Format++Produce a markdown report with these sections:++### 1. High-Priority Items (act on these)+- Clear, one-line description+- Why it matters (impact, risk, or customer pain)+- Suggested next action for the loop (e.g. "draft minimal fix in isolated worktree")+- Rough effort estimate++### 2. Watch Items (monitor, do not act yet)+- Same format but lower urgency++### 3. Noise / Ignore+- Brief list of things the loop looked at and decided were not worth action++### 4. State Updates+- Any facts the loop should remember for the next run (e.g. "PR #1234 now has 2 approvals")++## Rules++- Be brutally concise. The loop (and the human reading the state) will thank you.+- Only put something in "High-Priority" if a reasonable engineer would want to know about it today.+- When in doubt, put it in Watch or Noise rather than creating work.+- Never propose architectural overhauls during triage — this skill is for signal, not invention.+- Respect the project's existing skills and conventions (they will be provided in context).\ No newline at end of filediff --git a/skills/loop-verifier/SKILL.md b/skills/loop-verifier/SKILL.mdnew file mode 100644index 0000000..935d3bb--- /dev/null+++ b/skills/loop-verifier/SKILL.md@@ -0,0 +1,48 @@+---+name: loop-verifier+description: >+ Independent verification agent for loop-produced changes. Finds reasons to+ reject. Runs tests. Confirms diff scope. Use after minimal-fix or any+ implementer sub-agent — never in the same role as the implementer.+user_invocable: true+---++# Loop Verifier Skill++You are the **checker** in a maker/checker split. Your job is to **reject** unless evidence is strong.++## Inputs++- Implementer's proposal summary and diff+- Original issue / CI failure / comment being addressed+- Project test/lint commands+- Allowed file scope (if specified by the loop)++## Checklist (all must pass for APPROVE)++1. **Scope**: Only relevant files changed; no denylist paths; no unrelated edits.+2. **Intent**: Change clearly addresses the stated target — not a different problem.+3. **Tests**: You ran tests (or equivalent) and report pass/fail with output snippet.+4. **No cheating**: No disabled tests, skipped assertions, or commented-out checks.+5. **Risk**: For medium+ risk, recommend human review even if tests pass.++## Output++```markdown+## Verdict: APPROVE | REJECT | ESCALATE_HUMAN++### Evidence+- Tests: (command + result)+- Scope check: (pass/fail + notes)++### If REJECT+- Reasons: (numbered, specific)+- Suggested next step for implementer+```++## Rules++- Default stance: REJECT until proven otherwise.+- Do not trust implementer's claim that tests passed — run them.+- If you cannot run tests (env issue) → ESCALATE_HUMAN.+- Be concise. The loop and human read this under time pressure.\ No newline at end of filediff --git a/skills/minimal-fix/SKILL.md b/skills/minimal-fix/SKILL.mdnew file mode 100644index 0000000..025d50b--- /dev/null+++ b/skills/minimal-fix/SKILL.md@@ -0,0 +1,52 @@+---+name: minimal-fix+description: >+ Produce the smallest possible code change that fixes a specific, well-scoped+ issue (CI failure, reviewer comment, typo). Use only when the fix target is+ explicit. Never refactor unrelated code.+user_invocable: true+---++# Minimal Fix Skill++You fix **one specific problem** with the **smallest diff** that could work.++## Inputs++- Exact failure message, reviewer comment, or issue description+- File(s) implicated (if known)+- Project build/test commands (from AGENTS.md or project skills)+- Path denylist (from loop safety policy — never edit `.env`, `auth/`, `payments/`, secrets)++## Process++1. Reproduce or confirm the failure locally if possible.+2. Identify the minimal root cause — not symptoms in distant files.+3. Change only what is required. No drive-by refactors.+4. Run tests/lint relevant to the change.+5. Summarize: what changed, why, what you ran.++## Output++```markdown+## Minimal Fix Proposal++### Target+(one sentence)++### Diff summary+(files + what changed)++### Verification run+(command + result)++### Risks / human review needed?+(yes/no + why)+```++## Rules++- One problem per invocation. Multiple failures → escalate or triage first.+- Respect denylist paths — escalate instead of editing.+- Prefer worktree isolation when the loop runs unattended.+- Do not mark your own work done — the verifier decides.\ No newline at end of filediff --git a/starters/README.md b/starters/README.mdindex 9809ec8..4f392a4 100644--- a/starters/README.md+++ b/starters/README.md@@ -2,15 +2,31 @@Clone-and-run scaffolds. Copy into your project — do not submodule the whole repo unless you want the docs too.+## Daily Triage (L1 report-only)++| Starter | Tool | Path |+|---------|------|------|+| [minimal-loop](./minimal-loop/) | Grok | `.grok/skills/` |+| [minimal-loop-claude](./minimal-loop-claude/) | Claude Code | `.claude/skills/` + `.claude/agents/` |+| [minimal-loop-codex](./minimal-loop-codex/) | Codex | `.codex/skills/` + `.codex/agents/` |++## Other patterns (L2 assisted)+| Starter | Pattern | Readiness ||---------|---------|-----------|-| [minimal-loop](./minimal-loop/) | Daily Triage | L1 report-only || [pr-babysitter](./pr-babysitter/) | PR Babysitter | L2 assisted || [ci-sweeper](./ci-sweeper/) | CI Sweeper | L2 assisted || [dependency-sweeper](./dependency-sweeper/) | Dependency Sweeper | L2 assisted |After copying, run:+```bash+npx @cobusgreyling/loop-audit .+npx @cobusgreyling/loop-audit . --suggest+```++Or from a clone:+```bashnode tools/loop-audit/dist/cli.js .```\ No newline at end of filediff --git a/starters/minimal-loop-claude/.claude/agents/loop-verifier.md b/starters/minimal-loop-claude/.claude/agents/loop-verifier.mdnew file mode 100644index 0000000..bdbbaf6--- /dev/null+++ b/starters/minimal-loop-claude/.claude/agents/loop-verifier.md@@ -0,0 +1,35 @@+---+name: loop-verifier+description: Independent checker for loop-produced changes. Rejects unless tests pass and scope is minimal. Never implement fixes.+model: inherit+---++You are the **checker** in a maker/checker split. Your job is to **reject** unless evidence is strong.++## Checklist (all must pass for APPROVE)++1. **Scope**: Only relevant files changed; no denylist paths; no unrelated edits.+2. **Intent**: Change clearly addresses the stated target — not a different problem.+3. **Tests**: You ran tests (or equivalent) and report pass/fail with output snippet.+4. **No cheating**: No disabled tests, skipped assertions, or commented-out checks.+5. **Risk**: For medium+ risk, recommend human review even if tests pass.++## Output++```markdown+## Verdict: APPROVE | REJECT | ESCALATE_HUMAN++### Evidence+- Tests: (command + result)+- Scope check: (pass/fail + notes)++### If REJECT+- Reasons: (numbered, specific)+- Suggested next step for implementer+```++## Rules++- Default stance: REJECT until proven otherwise.+- Do not trust the implementer's claim that tests passed — run them.+- If you cannot run tests (env issue) → ESCALATE_HUMAN.\ No newline at end of filediff --git a/starters/minimal-loop-claude/.claude/skills/loop-triage/SKILL.md b/starters/minimal-loop-claude/.claude/skills/loop-triage/SKILL.mdnew file mode 100644index 0000000..6ca6e91--- /dev/null+++ b/starters/minimal-loop-claude/.claude/skills/loop-triage/SKILL.md@@ -0,0 +1,46 @@+---+name: loop-triage+description: >+ Triage recent changes, CI failures, issues, and conversations.+ Produces a concise, actionable findings report suitable for a loop to consume.+ Writes structured output to a state file or Linear board.+user_invocable: true+---++# Loop Triage Skill++You are an expert engineering triage agent. Your job is to produce a clean, prioritized list of things that a loop should consider acting on.++## Inputs (the loop will provide these)+- Recent CI / test failures (last 24h)+- Open issues / Linear tickets assigned to the team+- Recent commits on main (last 24–48h)+- Any Slack / chat threads the loop has visibility into+- The current state file (what the loop already knows about)++## Output Format++Produce a markdown report with these sections:++### 1. High-Priority Items (act on these)+- Clear, one-line description+- Why it matters (impact, risk, or customer pain)+- Suggested next action for the loop (e.g. "draft minimal fix in isolated worktree")+- Rough effort estimate++### 2. Watch Items (monitor, do not act yet)+- Same format but lower urgency++### 3. Noise / Ignore+- Brief list of things the loop looked at and decided were not worth action++### 4. State Updates+- Any facts the loop should remember for the next run (e.g. "PR #1234 now has 2 approvals")++## Rules++- Be brutally concise. The loop (and the human reading the state) will thank you.+- Only put something in "High-Priority" if a reasonable engineer would want to know about it today.+- When in doubt, put it in Watch or Noise rather than creating work.+- Never propose architectural overhauls during triage — this skill is for signal, not invention.+- Respect the project's existing skills and conventions (they will be provided in context).\ No newline at end of filediff --git a/starters/minimal-loop-claude/LOOP.md b/starters/minimal-loop-claude/LOOP.mdnew file mode 100644index 0000000..05cbf10--- /dev/null+++ b/starters/minimal-loop-claude/LOOP.md@@ -0,0 +1,32 @@+# Loop Configuration — Minimal Triage (Claude Code)++## Active Loops++| Pattern | Cadence | Status | Command |+|---------|---------|--------|---------|+| Daily Triage | 1d | L1 report-only | `/loop 1d Run $loop-triage` |++## Human Gates++- No auto-fix until L2 checklist complete+- All high-risk paths: human review required (see docs/safety.md denylist)++## Worktrees++- Use `isolation: worktree` when spawning implementer sub-agents (L2+).+- One worktree per fix attempt; discard after verifier REJECT.++## Connectors (MCP)++- MCP optional for L1 report-only loops.+- For L2+: GitHub MCP to read CI/issues; scope connectors to read + comment only until trusted.++## Budget++- Max sub-agent spawns per run: 0 (L1)+- Review STATE.md daily++## Links++- Pattern: [daily-triage](../../patterns/daily-triage.md)+- Checklist: [loop-design-checklist](../../docs/loop-design-checklist.md)\ No newline at end of filediff --git a/starters/minimal-loop-claude/README.md b/starters/minimal-loop-claude/README.mdnew file mode 100644index 0000000..abbd0d8--- /dev/null+++ b/starters/minimal-loop-claude/README.md@@ -0,0 +1,42 @@+# Minimal Loop Starter — Claude Code++Clone this into your project root to run a **report-only daily triage loop** (L1 readiness).++## Quick Start++1. Copy files into your repo:++ ```bash+ cp -r starters/minimal-loop-claude/.claude/skills/loop-triage .claude/skills/+ cp starters/minimal-loop-claude/.claude/agents/loop-verifier.md .claude/agents/+ cp starters/minimal-loop-claude/STATE.md.example STATE.md+ cp starters/minimal-loop-claude/LOOP.md .+ ```++2. Customize `STATE.md` project name.++3. Start the loop (Claude Code):++ ```bash+ /loop 1d Run $loop-triage. Read STATE.md first. Append high-priority and watch items. Update Last run timestamp. Do not auto-fix anything in week one.+ ```++4. Read `STATE.md` each morning for 1–2 weeks. Tune the triage skill.++5. When triage quality is good, add `minimal-fix` from `templates/SKILL.md.minimal-fix` and enable small auto-wins with the verifier agent (`isolation: worktree` on implementer tasks).++## What's Included++| File | Purpose |+|------|---------|+| `STATE.md.example` | State spine template |+| `.claude/skills/loop-triage/SKILL.md` | Triage skill |+| `.claude/agents/loop-verifier.md` | Checker sub-agent for L2+ |+| `LOOP.md` | Loop config doc for your team |++## Next Steps++- [Loop Design Checklist](../../docs/loop-design-checklist.md)+- [Daily Triage pattern](../../patterns/daily-triage.md)+- [Claude Code example](../../examples/claude-code/daily-triage.md)+- Run `npx @cobusgreyling/loop-audit .` for readiness score\ No newline at end of filediff --git a/starters/minimal-loop-claude/STATE.md.example b/starters/minimal-loop-claude/STATE.md.examplenew file mode 100644index 0000000..1168b1e--- /dev/null+++ b/starters/minimal-loop-claude/STATE.md.example@@ -0,0 +1,12 @@+# Loop State — My Project++Last run: never++## High Priority (loop is acting or waiting on human)++## Watch List++## Recent Noise (ignored this run)++---+Run log: —\ No newline at end of filediff --git a/starters/minimal-loop-codex/.codex/agents/verifier.toml b/starters/minimal-loop-codex/.codex/agents/verifier.tomlnew file mode 100644index 0000000..b297c16--- /dev/null+++ b/starters/minimal-loop-codex/.codex/agents/verifier.toml@@ -0,0 +1,15 @@+name = "verifier"+description = "Rejects loop fixes unless tests pass and scope is minimal. Never implements fixes."+instructions = """+You are the checker in a maker/checker split. Default stance: REJECT until proven otherwise.++Checklist (all must pass for APPROVE):+1. Scope — only relevant files; no denylist paths+2. Intent — addresses the stated target+3. Tests — you ran them and report pass/fail with output+4. No cheating — no disabled tests or skipped assertions+5. Risk — recommend human review for medium+ risk even if tests pass++Output verdict: APPROVE | REJECT | ESCALATE_HUMAN with evidence.+"""+reasoning_effort = "high"\ No newline at end of filediff --git a/starters/minimal-loop-codex/.codex/skills/loop-triage/SKILL.md b/starters/minimal-loop-codex/.codex/skills/loop-triage/SKILL.mdnew file mode 100644index 0000000..6ca6e91--- /dev/null+++ b/starters/minimal-loop-codex/.codex/skills/loop-triage/SKILL.md@@ -0,0 +1,46 @@+---+name: loop-triage+description: >+ Triage recent changes, CI failures, issues, and conversations.+ Produces a concise, actionable findings report suitable for a loop to consume.+ Writes structured output to a state file or Linear board.+user_invocable: true+---++# Loop Triage Skill++You are an expert engineering triage agent. Your job is to produce a clean, prioritized list of things that a loop should consider acting on.++## Inputs (the loop will provide these)+- Recent CI / test failures (last 24h)+- Open issues / Linear tickets assigned to the team+- Recent commits on main (last 24–48h)+- Any Slack / chat threads the loop has visibility into+- The current state file (what the loop already knows about)++## Output Format++Produce a markdown report with these sections:++### 1. High-Priority Items (act on these)+- Clear, one-line description+- Why it matters (impact, risk, or customer pain)+- Suggested next action for the loop (e.g. "draft minimal fix in isolated worktree")+- Rough effort estimate++### 2. Watch Items (monitor, do not act yet)+- Same format but lower urgency++### 3. Noise / Ignore+- Brief list of things the loop looked at and decided were not worth action++### 4. State Updates+- Any facts the loop should remember for the next run (e.g. "PR #1234 now has 2 approvals")++## Rules++- Be brutally concise. The loop (and the human reading the state) will thank you.+- Only put something in "High-Priority" if a reasonable engineer would want to know about it today.+- When in doubt, put it in Watch or Noise rather than creating work.+- Never propose architectural overhauls during triage — this skill is for signal, not invention.+- Respect the project's existing skills and conventions (they will be provided in context).\ No newline at end of filediff --git a/starters/minimal-loop-codex/LOOP.md b/starters/minimal-loop-codex/LOOP.mdnew file mode 100644index 0000000..60dc7f3--- /dev/null+++ b/starters/minimal-loop-codex/LOOP.md@@ -0,0 +1,32 @@+# Loop Configuration — Minimal Triage (Codex)++## Active Loops++| Pattern | Cadence | Status | Automation prompt |+|---------|---------|--------|-------------------|+| Daily Triage | 1d | L1 report-only | `Run $loop-triage. Read STATE.md. Report only.` |++## Human Gates++- No auto-fix until L2 checklist complete+- All high-risk paths: human review required (see docs/safety.md denylist)++## Worktrees++- Codex provides a built-in worktree per thread — use it for L2+ fix attempts.+- One fix per worktree; verifier subagent must APPROVE before proposing a PR.++## Connectors (MCP)++- MCP optional for L1 report-only loops.+- For L2+: GitHub connector to read CI/issues; write scope limited to comments until trusted.++## Budget++- Max sub-agent spawns per run: 0 (L1)+- Review STATE.md daily + Codex Triage inbox++## Links++- Pattern: [daily-triage](../../patterns/daily-triage.md)+- Checklist: [loop-design-checklist](../../docs/loop-design-checklist.md)\ No newline at end of filediff --git a/starters/minimal-loop-codex/README.md b/starters/minimal-loop-codex/README.mdnew file mode 100644index 0000000..82c265a--- /dev/null+++ b/starters/minimal-loop-codex/README.md@@ -0,0 +1,49 @@+# Minimal Loop Starter — Codex++Clone this into your project root to run a **report-only daily triage loop** (L1 readiness).++## Quick Start++1. Copy files into your repo:++ ```bash+ cp -r starters/minimal-loop-codex/.codex/skills/loop-triage .codex/skills/+ cp starters/minimal-loop-codex/.codex/agents/verifier.toml .codex/agents/+ cp starters/minimal-loop-codex/STATE.md.example STATE.md+ cp starters/minimal-loop-codex/LOOP.md .+ ```++2. Customize `STATE.md` project name.++3. Create an **Automation** in the Codex app (Automations tab):++ | Field | Value |+ |-------|--------|+ | Cadence | Daily (e.g. `1d`) |+ | Environment | Local checkout or background worktree |+ | Prompt | See below |++ ```+ Run $loop-triage. Read STATE.md first. Append high-priority and watch items.+ Update Last run timestamp. Week 1: report only — do not modify source files.+ ```++4. Review findings in the Codex Triage inbox + `STATE.md` for 1–2 weeks.++5. When triage quality is good, add `minimal-fix` from `templates/` and enable small auto-wins with the verifier subagent in an isolated worktree.++## What's Included++| File | Purpose |+|------|---------|+| `STATE.md.example` | State spine template |+| `.codex/skills/loop-triage/SKILL.md` | Triage skill |+| `.codex/agents/verifier.toml` | Checker sub-agent for L2+ |+| `LOOP.md` | Loop config doc for your team |++## Next Steps++- [Loop Design Checklist](../../docs/loop-design-checklist.md)+- [Daily Triage pattern](../../patterns/daily-triage.md)+- [Codex example](../../examples/codex/daily-triage.md)+- Run `npx @cobusgreyling/loop-audit .` for readiness score\ No newline at end of filediff --git a/starters/minimal-loop-codex/STATE.md.example b/starters/minimal-loop-codex/STATE.md.examplenew file mode 100644index 0000000..1168b1e--- /dev/null+++ b/starters/minimal-loop-codex/STATE.md.example@@ -0,0 +1,12 @@+# Loop State — My Project++Last run: never++## High Priority (loop is acting or waiting on human)++## Watch List++## Recent Noise (ignored this run)++---+Run log: —\ No newline at end of filediff --git a/starters/minimal-loop/README.md b/starters/minimal-loop/README.mdindex 91dc784..7b4b768 100644--- a/starters/minimal-loop/README.md+++ b/starters/minimal-loop/README.md@@ -29,8 +29,13 @@ Clone this into your project root to run a **report-only daily triage loop** (L1| `.grok/skills/loop-triage/SKILL.md` | Triage skill || `LOOP.md` | Loop config doc for your team |+## Other tools++- Claude Code: [minimal-loop-claude](../minimal-loop-claude/)+- Codex: [minimal-loop-codex](../minimal-loop-codex/)+## Next Steps- [Loop Design Checklist](../../docs/loop-design-checklist.md)- [Daily Triage pattern](../../patterns/daily-triage.md)-- Run `node tools/loop-audit/dist/cli.js .` for readiness score\ No newline at end of file+- Run `npx @cobusgreyling/loop-audit .` for readiness score\ No newline at end of filediff --git a/tools/loop-audit/README.md b/tools/loop-audit/README.mdindex 1347956..c5a7324 100644--- a/tools/loop-audit/README.md+++ b/tools/loop-audit/README.md@@ -4,6 +4,15 @@ CLI that scores a project's **Loop Readiness** (0–100) and suggests next steps## Install & Run+**npm (recommended):**++```bash+npx @cobusgreyling/loop-audit .+npx @cobusgreyling/loop-audit . --suggest+```++**From this repo:**+```bashcd tools/loop-auditnpm install@@ -11,10 +20,12 @@ npm run buildnode dist/cli.js /path/to/your/project```-Or from repo root after build:+## Before/after demo++See scores climb from empty → L1 starter → L2 verifier:```bash-node tools/loop-audit/dist/cli.js starters/minimal-loop+bash scripts/before-after-demo.sh```## Options@@ -23,20 +34,28 @@ node tools/loop-audit/dist/cli.js starters/minimal-looploop-audit . # human-readable (default)loop-audit . --json # machine-readableloop-audit . --md # markdown report-loop-audit . --suggest # show copy-from-template commands for what's missing (highly recommended)+loop-audit . --suggest # copy-from-template commands (all tools)```Exit code `2` if score < 40 (useful for CI gates once your project is loop-ready).-The reference repo itself now ships `.github/workflows/audit.yml` that runs this on the starters + root on every PR/push.+## Publish to npm-## Signals Checked (v1.1+)+Maintainers:++```bash+cd tools/loop-audit+npm run build+npm publish --access public+```++## Signals Checked (v1.2+)| Signal | Notes ||-------------------------|-------|| State file | STATE.md or pattern-specific || Triage skill | loop-triage / ci-triage / pr-review-triage etc. |-| Verifier skill | maker/checker split |+| Verifier skill | maker/checker split (skills or Claude/Codex agents) || LOOP.md / config | Cadence, limits, handoff || AGENTS.md / CLAUDE.md | Project conventions || Safety docs | safety.md + LOOP.md mentions of gates |@@ -45,8 +64,6 @@ The reference repo itself now ships `.github/workflows/audit.yml` that runs this| Worktree evidence | Isolation patterns in docs || patterns/registry.yaml | Machine index for tooling |-Weights favor state + triage + verifier + safety + .github dogfooding.-## Levels| Level | Meaning |diff --git a/tools/loop-audit/dist/auditor.js b/tools/loop-audit/dist/auditor.jsindex 9588376..6c291a6 100644--- a/tools/loop-audit/dist/auditor.js+++ b/tools/loop-audit/dist/auditor.js@@ -46,6 +46,24 @@ async function findSkills(root) {found.push('root-skill');}}+ // Claude Code agents and Codex subagents can host the verifier role+ const agentDirs = [+ path.join(root, '.claude', 'agents'),+ path.join(root, '.codex', 'agents'),+ ];+ for (const dir of agentDirs) {+ if (!(await fileExists(dir)))+ continue;+ const entries = await readdir(dir, { withFileTypes: true });+ for (const e of entries) {+ if (!e.isFile())+ continue;+ const base = e.name.replace(/\.(md|toml)$/i, '');+ if (base.includes('verifier') || base === 'loop-verifier') {+ found.push('loop-verifier');+ }+ }+ }return found;}export function computeScore(signals) {@@ -117,9 +135,7 @@ export async function auditProject(target) {// New expanded signalsconst githubDir = await fileExists(path.join(root, '.github'));const hasWorkflows = await fileExists(path.join(root, '.github', 'workflows'));- const safetyDoc = SAFETY_FILES.some(async (f) => await fileExists(path.join(root, f))) ||- await fileExists(path.join(root, 'docs', 'safety.md'));- // simple presence (note: async in .some is not awaited perfectly but good enough for heuristic)+ // Proper safety doc detectionlet safetyDocPresent = false;for (const f of SAFETY_FILES) {if (await fileExists(path.join(root, f))) {@@ -134,7 +150,14 @@ export async function auditProject(target) {/MCP|mcp server|plugins & connectors/i.test(loopMdContent);// Light evidence of worktree usage (common in patterns/starters/LOOP)let worktreeEvidence = false;- const candidateMd = ['LOOP.md', 'patterns/pr-babysitter.md', 'starters/minimal-loop/LOOP.md', 'docs/operating-loops.md'];+ const candidateMd = [+ 'LOOP.md',+ 'patterns/pr-babysitter.md',+ 'starters/minimal-loop/LOOP.md',+ 'starters/minimal-loop-claude/LOOP.md',+ 'starters/minimal-loop-codex/LOOP.md',+ 'docs/operating-loops.md',+ ];for (const c of candidateMd) {try {const p = path.join(root, c);@@ -166,21 +189,21 @@ export async function auditProject(target) {};if (!signals.stateFile.present) {findings.push({ level: 'fail', message: 'No state file (STATE.md or pattern-specific state).' });- recommendations.push('Copy starters/minimal-loop/STATE.md.example to STATE.md');+ recommendations.push('Copy starters/minimal-loop/STATE.md.example (or -claude / -codex variant) to STATE.md');}else {findings.push({ level: 'ok', message: `State file(s): ${statePaths.join(', ')}` });}if (!signals.triage.present) {findings.push({ level: 'warn', message: 'No triage skill detected.' });- recommendations.push('Install loop-triage from templates/ or starters/minimal-loop/');+ recommendations.push('Install loop-triage from starters/minimal-loop, minimal-loop-claude, or minimal-loop-codex');}else {findings.push({ level: 'ok', message: 'Triage skill present.' });}if (!signals.verifier.present) {findings.push({ level: 'warn', message: 'No loop-verifier skill — maker/checker split incomplete.' });- recommendations.push('Add templates/SKILL.md.verifier as .grok/skills/loop-verifier/SKILL.md');+ recommendations.push('Add verifier: .grok/skills/loop-verifier, .claude/agents/loop-verifier.md, or .codex/agents/verifier.toml');}else {findings.push({ level: 'ok', message: 'Verifier skill present.' });diff --git a/tools/loop-audit/dist/cli.js b/tools/loop-audit/dist/cli.jsindex 16b7c27..2db2f5a 100644--- a/tools/loop-audit/dist/cli.js+++ b/tools/loop-audit/dist/cli.js@@ -26,7 +26,8 @@ Exit codes:Examples:loop-audit .loop-audit starters/minimal-loop --suggest- node tools/loop-audit/dist/cli.js . --json+ npx @cobusgreyling/loop-audit . --json+ bash scripts/before-after-demo.sh`);process.exit(0);}@@ -42,12 +43,20 @@ try {console.log('\n=== Suggested actions (copy & customize) ===');console.log('From the root of this repo (or after cloning the reference):');console.log('');- console.log(' # Minimal L1 daily triage');+ console.log(' # Minimal L1 daily triage — pick your tool');+ console.log(' # Grok:');console.log(' cp -r starters/minimal-loop/.grok/skills/loop-triage .grok/skills/');- console.log(' cp starters/minimal-loop/STATE.md.example STATE.md');+ console.log(' # Claude Code:');+ console.log(' cp -r starters/minimal-loop-claude/.claude/skills/loop-triage .claude/skills/');+ console.log(' cp starters/minimal-loop-claude/.claude/agents/loop-verifier.md .claude/agents/');+ console.log(' # Codex:');+ console.log(' cp -r starters/minimal-loop-codex/.codex/skills/loop-triage .codex/skills/');+ console.log(' cp starters/minimal-loop-codex/.codex/agents/verifier.toml .codex/agents/');+ console.log(' # All tools:');+ console.log(' cp starters/minimal-loop/STATE.md.example STATE.md # or -claude / -codex variant');console.log(' cp starters/minimal-loop/LOOP.md .');console.log('');- console.log(' # Maker/checker verifier');+ console.log(' # Maker/checker verifier (Grok / generic skills dir)');console.log(' mkdir -p .grok/skills/loop-verifier');console.log(' cp templates/SKILL.md.verifier .grok/skills/loop-verifier/SKILL.md');console.log('');diff --git a/tools/loop-audit/package-lock.json b/tools/loop-audit/package-lock.jsonindex 2712ce0..54e7018 100644--- a/tools/loop-audit/package-lock.json+++ b/tools/loop-audit/package-lock.json@@ -1,12 +1,12 @@{"name": "loop-audit",- "version": "1.0.0",+ "version": "1.1.0","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "loop-audit",- "version": "1.0.0",+ "version": "1.1.0","bin": {"loop-audit": "dist/cli.js"},diff --git a/tools/loop-audit/package.json b/tools/loop-audit/package.jsonindex 8302b38..be74bce 100644--- a/tools/loop-audit/package.json+++ b/tools/loop-audit/package.json@@ -1,20 +1,50 @@{- "name": "loop-audit",- "version": "1.1.0",+ "name": "@cobusgreyling/loop-audit",+ "version": "1.2.0","description": "Loop Readiness Score — audit a project for loop engineering readiness (L0-L3). Supports --suggest for copy commands.","type": "module","bin": {"loop-audit": "./dist/cli.js"},+ "files": [+ "dist",+ "README.md"+ ],"scripts": {"build": "tsc",+ "prepublishOnly": "npm run build","start": "node dist/cli.js","audit": "npm run build && node dist/cli.js",- "audit:suggest": "npm run build && node dist/cli.js . --suggest"+ "audit:suggest": "npm run build && node dist/cli.js . --suggest",+ "demo": "bash ../../scripts/before-after-demo.sh"},"engines": {"node": ">=18"},+ "keywords": [+ "loop-engineering",+ "ai-agents",+ "coding-agents",+ "claude-code",+ "codex",+ "grok",+ "readiness",+ "audit"+ ],+ "author": "Cobus Greyling",+ "license": "MIT",+ "repository": {+ "type": "git",+ "url": "git+https://github.com/cobusgreyling/loop-engineering.git",+ "directory": "tools/loop-audit"+ },+ "homepage": "https://cobusgreyling.github.io/loop-engineering/",+ "bugs": {+ "url": "https://github.com/cobusgreyling/loop-engineering/issues"+ },+ "publishConfig": {+ "access": "public"+ },"devDependencies": {"@types/node": "^20.0.0","typescript": "^5.0.0"diff --git a/tools/loop-audit/src/auditor.ts b/tools/loop-audit/src/auditor.tsindex 8cfabbb..203fe8d 100644--- a/tools/loop-audit/src/auditor.ts+++ b/tools/loop-audit/src/auditor.ts@@ -78,6 +78,24 @@ async function findSkills(root: string): Promise<string[]> {if (e.isFile() && e.name === 'SKILL.md') found.push('root-skill');}}++ // Claude Code agents and Codex subagents can host the verifier role+ const agentDirs = [+ path.join(root, '.claude', 'agents'),+ path.join(root, '.codex', 'agents'),+ ];+ for (const dir of agentDirs) {+ if (!(await fileExists(dir))) continue;+ const entries = await readdir(dir, { withFileTypes: true });+ for (const e of entries) {+ if (!e.isFile()) continue;+ const base = e.name.replace(/\.(md|toml)$/i, '');+ if (base.includes('verifier') || base === 'loop-verifier') {+ found.push('loop-verifier');+ }+ }+ }+return found;}@@ -159,7 +177,14 @@ export async function auditProject(target: string): Promise<AuditResult> {// Light evidence of worktree usage (common in patterns/starters/LOOP)let worktreeEvidence = false;- const candidateMd = ['LOOP.md', 'patterns/pr-babysitter.md', 'starters/minimal-loop/LOOP.md', 'docs/operating-loops.md'];+ const candidateMd = [+ 'LOOP.md',+ 'patterns/pr-babysitter.md',+ 'starters/minimal-loop/LOOP.md',+ 'starters/minimal-loop-claude/LOOP.md',+ 'starters/minimal-loop-codex/LOOP.md',+ 'docs/operating-loops.md',+ ];for (const c of candidateMd) {try {const p = path.join(root, c);@@ -190,21 +215,21 @@ export async function auditProject(target: string): Promise<AuditResult> {if (!signals.stateFile.present) {findings.push({ level: 'fail', message: 'No state file (STATE.md or pattern-specific state).' });- recommendations.push('Copy starters/minimal-loop/STATE.md.example to STATE.md');+ recommendations.push('Copy starters/minimal-loop/STATE.md.example (or -claude / -codex variant) to STATE.md');} else {findings.push({ level: 'ok', message: `State file(s): ${statePaths.join(', ')}` });}if (!signals.triage.present) {findings.push({ level: 'warn', message: 'No triage skill detected.' });- recommendations.push('Install loop-triage from templates/ or starters/minimal-loop/');+ recommendations.push('Install loop-triage from starters/minimal-loop, minimal-loop-claude, or minimal-loop-codex');} else {findings.push({ level: 'ok', message: 'Triage skill present.' });}if (!signals.verifier.present) {findings.push({ level: 'warn', message: 'No loop-verifier skill — maker/checker split incomplete.' });- recommendations.push('Add templates/SKILL.md.verifier as .grok/skills/loop-verifier/SKILL.md');+ recommendations.push('Add verifier: .grok/skills/loop-verifier, .claude/agents/loop-verifier.md, or .codex/agents/verifier.toml');} else {findings.push({ level: 'ok', message: 'Verifier skill present.' });}diff --git a/tools/loop-audit/src/cli.ts b/tools/loop-audit/src/cli.tsindex 6567773..bfd89f2 100644--- a/tools/loop-audit/src/cli.ts+++ b/tools/loop-audit/src/cli.ts@@ -28,7 +28,8 @@ Exit codes:Examples:loop-audit .loop-audit starters/minimal-loop --suggest- node tools/loop-audit/dist/cli.js . --json+ npx @cobusgreyling/loop-audit . --json+ bash scripts/before-after-demo.sh`);process.exit(0);}@@ -43,12 +44,20 @@ try {console.log('\n=== Suggested actions (copy & customize) ===');console.log('From the root of this repo (or after cloning the reference):');console.log('');- console.log(' # Minimal L1 daily triage');+ console.log(' # Minimal L1 daily triage — pick your tool');+ console.log(' # Grok:');console.log(' cp -r starters/minimal-loop/.grok/skills/loop-triage .grok/skills/');- console.log(' cp starters/minimal-loop/STATE.md.example STATE.md');+ console.log(' # Claude Code:');+ console.log(' cp -r starters/minimal-loop-claude/.claude/skills/loop-triage .claude/skills/');+ console.log(' cp starters/minimal-loop-claude/.claude/agents/loop-verifier.md .claude/agents/');+ console.log(' # Codex:');+ console.log(' cp -r starters/minimal-loop-codex/.codex/skills/loop-triage .codex/skills/');+ console.log(' cp starters/minimal-loop-codex/.codex/agents/verifier.toml .codex/agents/');+ console.log(' # All tools:');+ console.log(' cp starters/minimal-loop/STATE.md.example STATE.md # or -claude / -codex variant');console.log(' cp starters/minimal-loop/LOOP.md .');console.log('');- console.log(' # Maker/checker verifier');+ console.log(' # Maker/checker verifier (Grok / generic skills dir)');console.log(' mkdir -p .grok/skills/loop-verifier');console.log(' cp templates/SKILL.md.verifier .grok/skills/loop-verifier/SKILL.md');console.log('');