Skip to content

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.

Add npm-ready loop-audit, Claude/Codex starters, and L3 dogfooding

Cobus Greyling37922a9a267e
diff --git a/.github/workflows/audit.yml b/.github/workflows/audit.yml
index 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/.gitignore
index 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.md
state.json
*.state
@@ -40,5 +41,9 @@ state.json
!starters/**/.grok/
!starters/**/.grok/**
.claude/
+!starters/**/.claude/
+!starters/**/.claude/**
.codex/
+!starters/**/.codex/
+!starters/**/.codex/**
*.session
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 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 file
diff --git a/LOOP.md b/LOOP.md
index 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.md
index 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.md
new file mode 100644
index 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 file
diff --git a/docs/primitives-matrix.md b/docs/primitives-matrix.md
index 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 file
diff --git a/examples/README.md b/examples/README.md
index 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 file
diff --git a/scripts/before-after-demo.sh b/scripts/before-after-demo.sh
new file mode 100755
index 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 file
diff --git a/skills/loop-triage/SKILL.md b/skills/loop-triage/SKILL.md
new file mode 100644
index 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 file
diff --git a/skills/loop-verifier/SKILL.md b/skills/loop-verifier/SKILL.md
new file mode 100644
index 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 file
diff --git a/skills/minimal-fix/SKILL.md b/skills/minimal-fix/SKILL.md
new file mode 100644
index 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 file
diff --git a/starters/README.md b/starters/README.md
index 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:
+
```bash
node tools/loop-audit/dist/cli.js .
```
\ No newline at end of file
diff --git a/starters/minimal-loop-claude/.claude/agents/loop-verifier.md b/starters/minimal-loop-claude/.claude/agents/loop-verifier.md
new file mode 100644
index 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 file
diff --git a/starters/minimal-loop-claude/.claude/skills/loop-triage/SKILL.md b/starters/minimal-loop-claude/.claude/skills/loop-triage/SKILL.md
new file mode 100644
index 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 file
diff --git a/starters/minimal-loop-claude/LOOP.md b/starters/minimal-loop-claude/LOOP.md
new file mode 100644
index 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 file
diff --git a/starters/minimal-loop-claude/README.md b/starters/minimal-loop-claude/README.md
new file mode 100644
index 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 file
diff --git a/starters/minimal-loop-claude/STATE.md.example b/starters/minimal-loop-claude/STATE.md.example
new file mode 100644
index 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 file
diff --git a/starters/minimal-loop-codex/.codex/agents/verifier.toml b/starters/minimal-loop-codex/.codex/agents/verifier.toml
new file mode 100644
index 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 file
diff --git a/starters/minimal-loop-codex/.codex/skills/loop-triage/SKILL.md b/starters/minimal-loop-codex/.codex/skills/loop-triage/SKILL.md
new file mode 100644
index 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 file
diff --git a/starters/minimal-loop-codex/LOOP.md b/starters/minimal-loop-codex/LOOP.md
new file mode 100644
index 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 file
diff --git a/starters/minimal-loop-codex/README.md b/starters/minimal-loop-codex/README.md
new file mode 100644
index 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 file
diff --git a/starters/minimal-loop-codex/STATE.md.example b/starters/minimal-loop-codex/STATE.md.example
new file mode 100644
index 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 file
diff --git a/starters/minimal-loop/README.md b/starters/minimal-loop/README.md
index 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 file
diff --git a/tools/loop-audit/README.md b/tools/loop-audit/README.md
index 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:**
+
```bash
cd tools/loop-audit
npm install
@@ -11,10 +20,12 @@ npm run build
node 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-loop
loop-audit . # human-readable (default)
loop-audit . --json # machine-readable
loop-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.js
index 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 signals
const 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 detection
let 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.js
index 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.json
index 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.json
index 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.ts
index 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.ts
index 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('');