loop-engineering Documentation

Technical Documentation: cobusgreyling/loop-engineering

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Loop Engineering

Stop prompting. Design the loop. Get a score.

npx @cobusgreyling/loop init . --pattern daily-triage --tool claude
npx @cobusgreyling/loop doctor .

--tool defaults to claude if you omit it. Swap for grok, codex, or opencode. Week one is report-only.

You design a system that discovers work, hands it to agents, verifies results, and persists state — instead of typing the next prompt yourself.

New here? Quickstart · Refactor a project · Thin GitHub Action loop (no STATE.md required)

What do you want to do? Copy Chapter

This is a pattern library for operating agents around a codebase. It is not a “rewrite the module” button.

Full jobs table: docs/jobs.md.

Patterns Copy Chapter

Interactive picker: showcase. Index: patterns/registry.yaml.

Getting started Copy Chapter

npx @cobusgreyling/loop init . --pattern daily-triage --tool claude
npx @cobusgreyling/loop doctor .
npx @cobusgreyling/loop cost --pattern daily-triage --level L1

Empty repo → first STATE.md walkthrough: scripts/empty-to-state-demo.sh.

Roll out L1 report → L2 assisted → L3 unattended only after the verifier has been right for a week. See loop-design-checklist.

Loop Ready now weights recent runs harder than files on disk. A 30-day-old STATE.md is not L3.

Examples by tool Copy Chapter

Claude Code (including the plugin) · Grok · Codex · OpenClaw · Opencode · GitHub Actions

Operating & safety Copy Chapter

Failure modes · Anti-patterns · Safety · Operating loops · Stories (wins and failures)

Loop engineering amplifies judgment. Token costs can explode. Unattended loops make unattended mistakes. Read what the loop ships.

Help wanted Copy Chapter

Docs and small PRs: first response within 48 hours.

• Add your project to adopters
• Share a story (failures first-class)
• Live good first issue list
• Show your loop · Ask anything

See CONTRIBUTING.md.

CLI packages and companion repos (optional — not required for week one)

Unified front door: npx @cobusgreyling/loop (init · doctor · status · audit · cost). Older packages (loop-init, loop-audit, …) stay supported.

Companions exist for later: memory-engineering, harness-foundry, outerloop, fleet-engineering, goal-engineering. Do not add them until a loop has actually run.

Sources Copy Chapter

• Cobus Greyling — Loop Engineering
• Addy Osmani — Loop Engineering
• Lulla et al. 2026 — Building Blocks, Adoption, and Impact (this repo is the community reference they reviewed)
• Attribution

License Copy Chapter

MIT

Overview (`examples/README.md`) Copy Section

Examples

Same patterns, different tools. Skills and state schemas are shared; only scheduling and invocation differ.

Start with primitives-matrix.md to map capabilities.

Pattern coverage Copy Chapter

L2 patterns ship multi-tool skills inside one starter folder — see starters//.

Copy-paste starters:

L2 maker/checker split (any Hermes pattern): hermes/loop-verifier.md

Overview (`patterns/README.md`) Copy Section

Loop Patterns

Documented, reusable loop patterns that have been (or can be) run in real environments.

Each pattern answers:

• What problem it solves
• Recommended scheduling
• Required skills / state shape
• Verification approach
• Human hand-off strategy
• Tool-specific notes (Grok, Claude Code, Codex, OpenClaw, Opencode, GitHub Actions)

Pattern Registry Copy Chapter

Machine-readable index: registry.yaml

How to Use a Pattern Copy Chapter

1. Pick a pattern: pattern-picker.md
2. Scaffold with npx @cobusgreyling/loop-init . --pattern <name> --tool claude (or --tool grok / --tool opencode) or copy from starters/
3. Copy skills from templates/ if customizing beyond the starter
4. Set up scheduling (/loop, scheduler_create, GitHub Action, Codex Automation)
5. Run week one in L1 report-only mode before enabling fixes
6. Audit with npx @cobusgreyling/loop-audit . --suggest

Adding a Pattern Copy Chapter

Use templates/pattern-template.md, add an entry to registry.yaml, and open a PR. See CONTRIBUTING.md.

Overview (`starters/README.md`) Copy Section

Starters

Clone-and-run scaffolds. Copy into your project — or use loop-init:

npx @cobusgreyling/loop-init . --pattern daily-triage --tool claude
npx @cobusgreyling/loop-init . -p thin-loop
npx @cobusgreyling/loop-init . -p pr-babysitter -t grok

Daily Triage (L1 report-only) Copy Chapter

L2 assisted patterns Copy Chapter

After copying:

npx @cobusgreyling/loop-audit .
npx @cobusgreyling/loop-audit . --suggest

Overview (`stories/README.md`) Copy Section

Production Stories

Real-world loop engineering — including failures. Contribute yours via CONTRIBUTING.md.

Template for new stories:

# Title — Context
## Setup
## What Worked
## What Broke
## Metrics (if any)
## Lesson

Overview (`examples/cursor/README.md`) Copy Section

Cursor Examples

Copy-pasteable loop patterns for Cursor, using Automations (cloud cron) or manual Agent chat for scheduling and .cursor/skills/ + .cursor/rules/ for persistent skill context.

No loop-init --tool cursor yet — copy SKILL.md + STATE.md from any starter (e.g. starters/minimal-loop), then follow the example to wire scheduling.

Audit after copying:

npx @cobusgreyling/loop-audit . --suggest

Overview (`examples/github-actions/README.md`) Copy Section

GitHub Actions Examples

Includes triggers for the new Changelog Drafter pattern (daily or on tags). See changelog-drafter.yml.

Event-driven and scheduled loops without a TUI session. The refactored workflow examples in this directory use the loop-action composite action to automatically run readiness audits (loop-audit), check circuit breakers (loop-context), and isolate execution in worktrees (loop-sandbox).

Composite Action (`loop-action`) Copy Chapter

Instead of writing manual shell scripts for audits and circuit breakers in your workflows, use the tools/loop-action composite action:

- uses: cobusgreyling/loop-engineering/tools/loop-action@main
  with:
    pattern: 'daily-triage'
    level: 'L1'
    sandbox: 'false'
    command: |
      npx grok-cli run --skill .grok/skills/loop-triage/SKILL.md

Wiring Your Agent Copy Chapter

Replace the command: input or placeholder steps with your choice of agent harness:

The state file schema and skills are tool-agnostic — only the invocation step differs.

Workflows Copy Chapter

Security Copy Chapter

• Use GITHUB_TOKEN with minimum permissions
• No secrets in workflow logs
• See safety.md

Overview (`examples/grok/README.md`) Copy Section

Grok Build TUI

New: See changelog-drafter.md for the low-risk, high-ROI release notes pattern. Examples

Native primitives: /loop, scheduler_create, worktree isolation, skills, MCP, sub-agents.

Common Commands Copy Chapter

/loop 5m /pr-babysit check
/loop 1d Run loop-triage and update STATE.md
/loop 15m Check CI on main — see patterns/ci-sweeper.md

Background tasks: Ctrl+G demote, queue pane Ctrl+;.

See docs/primitives-matrix.md.

Overview (`examples/hermes/README.md`) Copy Section

Hermes Agent

Hermes Agent ships the six loop primitives (cronjob / skill / STATE / delegate_task / MCP / memory) in one binary — no extra runtime needed for a full L1 daily-triage loop.

Optional channel delivery (Telegram, Slack, Discord, WhatsApp, SMS, Feishu) is Hermes's differentiator — the same cron job can post its summary into any connected home channel.

No loop-init --tool hermes yet — copy skills and state manually, then schedule via hermes cron.

See docs/primitives-matrix.md for the Hermes column in the cross-tool matrix.

Overview (`examples/mcp/README.md`) Copy Section

MCP / Connectors Cookbook

Practical, scoped examples for connecting loops to real tools via MCP (or equivalent plugins/connectors).

Core principle: Give loops the minimum privilege they need. Prefer read + comment over write. Use human gates + worktrees for anything that mutates state.

Run the loop-engineering MCP server Copy Chapter

If you want to try the MCP server without cloning the repo, use the published package:

LOOP_PROJECT_ROOT=. npx @cobusgreyling/loop-mcp-server

Copy the example MCP configuration:

cp examples/mcp/loop-engineering.mcp.json <your-mcp-config-location>

Then point your MCP client to the command above.

The local clone/dev path still works if you want to inspect or change the server implementation directly; see the example configuration files below.

Quick Patterns Copy Chapter

Example Configurations Copy Chapter

See the files in this directory:

• loop-engineering.mcp.json — starter config for the published MCP server.
• parallel-search.mcp.json — optional free, keyless
  web search and page fetching through a pinned stdio-to-HTTP bridge; see the
  setup and manual dependency-research walkthrough.
• github-readonly.mcp.json (existing) — safe starting point for discovery.
• github-propose.json — read + limited write for comments and draft PRs (sign comments as the loop).
• linear.json — example for creating/updating issues from loop state.
• slack-read.json — ingest channel threads into triage.
• knos.mcp.json — local shared state for parallel loops (pip install knos,
  Python 3.10+). knos-decisions.example.md beside it shows the record shape; it
  is plain markdown, so it reads with nothing installed and the server is only
  needed for live claims.
• safe-write-pattern.md — the recommended architecture for any mutating action.

Usage in a Loop Prompt (Grok example) Copy Chapter

/loop 1d Use the github-propose MCP. Scan open PRs with pr-review-triage. For actionable low-risk items on allowlisted paths: open worktree, minimal-fix, verifier. Then post a signed comment on the PR with a link to the worktree diff. Never merge.

Always:

• Declare the bot identity in comments ("🤖 Loop Engineering — Changelog Drafter").
• Record the MCP action + result in STATE or the pattern-specific state file.
• Have an explicit denylist in the skill or LOOP.md.

Safety Notes Copy Chapter

• Never give a loop the ability to push tags or create releases without an explicit human gate (even for changelog).
• For Linear / ticketing: the loop can propose or update status; a human (or a very trusted allowlist) does final close on high-severity items.
• Test new connectors in report-only (L1) mode first.
• Log every MCP call the loop makes (the monitor tool or GitHub Action logs are your friend).

See also: docs/safety.md, docs/operating-loops.md, and the individual pattern docs for human gate recommendations.

Overview (`examples/openclaw/README.md`) Copy Section

OpenClaw

Self-hosted Gateway: cron scheduling, workspace skills, MCP, multi-agent routing, and optional delivery to Slack/Telegram/WhatsApp.

No loop-init --tool openclaw yet — copy skills and state manually.

See docs/primitives-matrix.md.

Overview (`examples/opencode/README.md`) Copy Section

Opencode

Open-source coding agent that runs from the CLI, can run headlessly via opencode run, supports named agents, and can connect to tools through MCP. Loop engineering primitives publish to plain files: AGENTS.md, STATE.md, and skills/ folders in the AgentSkills format.

Starter kit: ../../starters/minimal-loop-opencode/ — clone-and-run scaffold for L1 daily triage.

No loop-init --tool opencode yet; copy the starter or follow the snippets below in 30 seconds.

See docs/primitives-matrix.md for the full capability comparison.

Overview (`examples/windsurf/README.md`) Copy Section

Windsurf Examples

Copy-pasteable loop patterns for Windsurf, using Cascade Workflows as the manual workflow surface and .windsurf/rules/ for persistent skill context. External reminders or triggers can provide cadence, but should not merge or act on PRs.

No loop-init --tool windsurf yet — copy SKILL.md + STATE.md from any starter (e.g. starters/minimal-loop), then follow the example to wire a Cascade Workflow.

Audit after copying:

npx @cobusgreyling/loop-audit . --suggest

Overview (`resources/ky-cut-surface-philosophy-v0_1/README.md`) Copy Section

KY Cut Surface Philosophy v0.1

Status: OPEN (public philosophy) · HOLD (technical claim) · KILL (overclaim)

Archived philosophy artifact contributed by @sololys. Not a pattern, runtime, or validation claim.

Core thesis: candidate generation is not consequence realization.

Loop engineering bridge: see stories/ky-cut-surface-generation-vs-consequence.md.

Files Copy Chapter

Boundary Copy Chapter

Manifest files (MANIFEST.sha256, MANIFEST_VERIFY.txt) are for archive discipline only.

Overview (`scripts/issue-bodies/hermes-examples-readme.md`) Copy Section

Goal Copy Chapter

Add Hermes Agent to the examples index so the new daily-triage bridge is discoverable from examples/README.md.

Files Copy Chapter

• examples/README.md

Acceptance criteria Copy Chapter

• Add Hermes row to the tool directory table (link examples/hermes/)
• Add Hermes column to the pattern coverage table (at least Daily Triage — link examples/hermes/daily-triage.md)
• Keep table formatting consistent with existing columns

Estimated time: ~15 minutes

Overview (`starters/changelog-drafter-opencode/README.md`) Copy Section

Changelog Drafter — Opencode Starter

Clone-and-run scaffold for the Changelog Drafter pattern with opencode. Scan merged PRs and commits, produce categorized release notes.

Quick Start Copy Chapter

npx @cobusgreyling/loop-init . --pattern changelog-drafter --tool opencode

Or copy manually:

cp -r starters/changelog-drafter-opencode/skills .
cp starters/changelog-drafter-opencode/AGENTS.md .
cp starters/changelog-drafter-opencode/LOOP.md .
cp starters/changelog-drafter-opencode/changelog-drafter-state.md.example changelog-drafter-state.md
cp starters/changelog-drafter-opencode/opencode.json.example opencode.json

Start (L1 report + draft, week 1):

opencode run \
  "Run skills/changelog-scan/SKILL.md. Scan merges since last tag (or last 7 days). Produce categorized draft in RELEASE_NOTES_DRAFT.md. Update state. Do not publish or create PRs." \
  --title "Changelog drafter"

What's Included Copy Chapter

Next Steps Copy Chapter

• patterns/changelog-drafter.md
• examples/opencode/changelog-drafter.md
• docs/loop-design-checklist.md
• stories/changelog-drafter-week-one.md

Overview (`starters/changelog-drafter/README.md`) Copy Section

Changelog Drafter Starter

Scaffold for the Changelog Drafter loop (L1 report + draft → L2 assisted publish prep). Excellent low-risk second or third loop.

Quick Start Copy Chapter

# Recommended
npx @cobusgreyling/loop-init . --pattern changelog-drafter --tool grok

# Or manual copy (Grok)
cp -r starters/changelog-drafter/.grok/skills/changelog-scan .grok/skills/
cp -r starters/changelog-drafter/.grok/skills/draft-release-notes .grok/skills/
cp starters/changelog-drafter/changelog-drafter-state.md.example changelog-drafter-state.md
cp starters/changelog-drafter/LOOP.md .

Start (Grok example — report/draft only in week one):

/loop 1d Run changelog-scan on merges since last tag (or last 7 days). Produce a clean categorized draft in RELEASE_NOTES_DRAFT.md using draft-release-notes skill. Update changelog-drafter-state.md. Never publish or tag without explicit human approval.

Files Copy Chapter

Also Bring In (recommended) Copy Chapter

• loop-verifier (or use the human as verifier for L1)
• Your project's release voice / style guide (add a short section to AGENTS.md or a project skill)

Safety Copy Chapter

• This loop proposes drafts only. Publishing (updating CHANGELOG.md, creating GitHub releases, pushing tags) should require human review or a very tight allowlist + verifier.
• Always surface breaking changes and security items explicitly for human sign-off.
• See safety.md and the pattern doc for full guidance.

After copying, run:

npx @cobusgreyling/loop-audit . --suggest

Overview (`starters/ci-sweeper-opencode/README.md`) Copy Section

CI Sweeper — Opencode Starter

Clone-and-run scaffold for the CI Sweeper pattern with opencode. React to failing CI with minimal fixes at short cadences.

Quick Start Copy Chapter

npx @cobusgreyling/loop-init . --pattern ci-sweeper --tool opencode

Or copy manually:

cp -r starters/ci-sweeper-opencode/skills .
cp starters/ci-sweeper-opencode/AGENTS.md .
cp starters/ci-sweeper-opencode/LOOP.md .
cp starters/ci-sweeper-opencode/ci-sweeper-state.md.example ci-sweeper-state.md
cp starters/ci-sweeper-opencode/opencode.json.example opencode.json

Start (L2 cautious — CI sweeper is action-oriented from week one):

opencode run \
  "Run skills/ci-triage/SKILL.md. Classify each failing check. For clear single-file regressions, create a worktree and apply a minimal fix with verifier. Run loop-gate check before commit. Update ci-sweeper-state.md. Infra and security failures: escalate." \
  --title "CI sweeper"

What's Included Copy Chapter

Next Steps Copy Chapter

• patterns/ci-sweeper.md
• examples/opencode/ci-sweeper.md
• docs/loop-design-checklist.md

Overview (`starters/ci-sweeper/README.md`) Copy Section

CI Sweeper Starter

Scaffold for the CI Sweeper loop.

Quick Start Copy Chapter

1. Copy skills and state:

   bash Copy

   npx @cobusgreyling/loop-init . --pattern ci-sweeper --tool grok
   # Or manual:
   mkdir -p .grok/skills
   cp -r starters/ci-sweeper/.grok/skills/ci-triage .grok/skills/
   cp templates/SKILL.md.minimal-fix .grok/skills/minimal-fix/SKILL.md
   cp templates/SKILL.md.verifier .grok/skills/loop-verifier/SKILL.md
   cp starters/ci-sweeper/ci-sweeper-state.md.example ci-sweeper-state.md

2. Add GitHub Action (optional): examples/github-actions/ci-sweeper.yml

3. Start (Grok):

   bash Copy

   /loop 15m Check CI on main. Update ci-sweeper-state.md. Classify failures. For new actionable failures (not flakes): worktree + minimal-fix + loop-verifier. Run loop-gate check before commit. Escalate after 3 attempts.

Flake Policy Copy Chapter

If the same test failed and passed on retry without code change → Watch, do not auto-fix.

Overview (`starters/dependency-sweeper-opencode/README.md`) Copy Section

Dependency Sweeper — Opencode Starter

Clone-and-run scaffold for the Dependency Sweeper pattern with opencode. Discover, safely apply, and verify dependency updates.

Quick Start Copy Chapter

npx @cobusgreyling/loop-init . --pattern dependency-sweeper --tool opencode

Or copy manually:

cp -r starters/dependency-sweeper-opencode/skills .
cp starters/dependency-sweeper-opencode/AGENTS.md .
cp starters/dependency-sweeper-opencode/LOOP.md .
cp starters/dependency-sweeper-opencode/dependency-sweeper-state.md.example dependency-sweeper-state.md
cp starters/dependency-sweeper-opencode/opencode.json.example opencode.json

Start (L2 assisted, patch-only):

opencode run \
  "Run skills/dependency-triage/SKILL.md. Scan package manifests for outdated and vulnerable deps. Patch-only auto-fix in worktree with verifier. Run loop-gate check before commit. Escalate majors, high-sev CVEs, and denylist packages. Update state." \
  --title "Dependency sweeper"

What's Included Copy Chapter

Next Steps Copy Chapter

• patterns/dependency-sweeper.md
• examples/opencode/dependency-sweeper.md
• docs/loop-design-checklist.md
• stories/dependency-sweeper-week-one.md

Overview (`starters/dependency-sweeper/README.md`) Copy Section

Dependency Sweeper Starter

Clone-and-run scaffold for the Dependency Sweeper pattern (L2 assisted, patch-only with strong verifier gates).

Quick Start Copy Chapter

npx @cobusgreyling/loop-init . --pattern dependency-sweeper --tool grok

Or manual copy:

cp -r starters/dependency-sweeper/.grok/skills/dependency-triage .grok/skills/
mkdir -p .grok/skills/loop-verifier .grok/skills/minimal-fix
cp templates/SKILL.md.verifier .grok/skills/loop-verifier/SKILL.md
cp templates/SKILL.md.minimal-fix .grok/skills/minimal-fix/SKILL.md
cp starters/dependency-sweeper/dependency-sweeper-state.md.example dependency-sweeper-state.md
cp starters/dependency-sweeper/LOOP.md .

Claude Code / Codex: use --tool claude or --tool codex with loop-init.

Start (Grok):

/loop 6h Run dependency-triage on package manifests and lockfiles. Patch-only auto-fix in worktree + verifier (npm ci && npm test). Run loop-context --check before each retry on the same package; run loop-gate check before commit. Escalate majors, high-sev CVEs, and denylist packages after 2 attempts. Update dependency-sweeper-state.md.

What's Included Copy Chapter

Next Steps Copy Chapter

• patterns/dependency-sweeper.md
• docs/loop-design-checklist.md
• stories/dependency-sweeper-week-one.md

Safety: Majors and high-severity breaking fixes stay behind explicit human gates.

Overview (`starters/issue-triage-opencode/README.md`) Copy Section

Issue Triage — Opencode Starter

Clone-and-run scaffold for the Issue Triage pattern with opencode. Keep the issue queue legible so morning triage always knows the top five.

Quick Start Copy Chapter

npx @cobusgreyling/loop-init . --pattern issue-triage --tool opencode

Or copy manually:

cp -r starters/issue-triage-opencode/skills .
cp starters/issue-triage-opencode/AGENTS.md .
cp starters/issue-triage-opencode/LOOP.md .
cp starters/issue-triage-opencode/issue-triage-state.md.example issue-triage-state.md
cp starters/issue-triage-opencode/opencode.json.example opencode.json

Start (L1 propose-only, week 1):

opencode run \
  "Run skills/issue-triage/SKILL.md. Scan open issues since last run. Update issue-triage-state.md with top 5, proposed labels, and needs-human bucket. Propose only — do not apply labels or close issues." \
  --title "Issue triage"

What's Included Copy Chapter

Next Steps Copy Chapter

• patterns/issue-triage.md
• examples/opencode/issue-triage.md
• docs/loop-design-checklist.md

Overview (`starters/issue-triage/README.md`) Copy Section

Issue Triage Starter

Scaffold for the Issue Triage loop — L1 propose-only week one. Pairs with Daily Triage as a low-risk issue queue feeder.

Quick Start Copy Chapter

# Grok
npx @cobusgreyling/loop-init . --pattern issue-triage --tool grok

# Claude Code
npx @cobusgreyling/loop-init . --pattern issue-triage --tool claude

# Codex
npx @cobusgreyling/loop-init . --pattern issue-triage --tool codex

Start (Grok, week one):

/loop 2h Run issue-triage. Read issue-triage-state.md first. Update Top 5 and proposed labels. No auto-apply. Escalate security and ambiguous items.

Files Copy Chapter

Safety Copy Chapter

• No auto-label or close in L1
• Denylist: auth, payments, security — see safety.md

Overview (`starters/minimal-loop-claude/README.md`) Copy Section

Minimal Loop Starter — Claude Code

Clone this into your project root to run a report-only daily triage loop (L1 readiness).

Quick Start Copy Chapter

1. Copy files into your repo:

   bash Copy

   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 Copy

   /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 Copy Chapter

Next Steps Copy Chapter

• Loop Design Checklist
• Daily Triage pattern
• Claude Code example
• Run npx @cobusgreyling/loop-audit . for readiness score

Overview (`starters/minimal-loop-codex/README.md`) Copy Section

Minimal Loop Starter — Codex

Clone this into your project root to run a report-only daily triage loop (L1 readiness).

Quick Start Copy Chapter

1. Copy files into your repo:

   bash Copy

   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

   text Copy

   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 Copy Chapter

Next Steps Copy Chapter

• Loop Design Checklist
• Daily Triage pattern
• Codex example
• Run npx @cobusgreyling/loop-audit . for readiness score

Overview (`starters/minimal-loop-opencode/README.md`) Copy Section

Minimal Loop Starter — Opencode

Clone this into your project root to run a report-only daily triage loop (L1 readiness) with opencode.

Quick Start Copy Chapter

1. Scaffold (recommended):

   bash Copy

   npx @cobusgreyling/loop-init . --pattern daily-triage --tool opencode

   Or copy manually:

   bash Copy

   cp -r starters/minimal-loop-opencode/skills .
   cp starters/minimal-loop-opencode/AGENTS.md .
   cp starters/minimal-loop-opencode/LOOP.md .
   cp starters/minimal-loop-opencode/STATE.md.example STATE.md
   cp starters/minimal-loop-opencode/opencode.json.example opencode.json

2. Customize STATE.md project name.

3. Start the loop:

   bash Copy

   opencode run "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." --agent loop-triage

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 a verifier agent in a worktree.

What's Included Copy Chapter

Next Steps Copy Chapter

• Loop Design Checklist
• Daily Triage pattern
• Opencode example
• Run npx @cobusgreyling/loop-audit . for readiness score

Overview (`starters/minimal-loop/README.md`) Copy Section

Minimal Loop Starter

Clone this into your project root to run a report-only daily triage loop (L1 readiness).

Quick Start Copy Chapter

1. Copy files into your repo:

   bash Copy

   cp -r starters/minimal-loop/.grok/skills/loop-triage .grok/skills/  # Grok
   cp starters/minimal-loop/STATE.md.example STATE.md

2. Customize STATE.md project name.

3. Start the loop (Grok):

   bash Copy

   /loop 1d Run the loop-triage skill. 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 + loop-verifier from templates/ and enable small auto-wins.

What's Included Copy Chapter

Other tools Copy Chapter

• Claude Code: minimal-loop-claude
• Codex: minimal-loop-codex

Next Steps Copy Chapter

• Loop Design Checklist
• Daily Triage pattern
• Run npx @cobusgreyling/loop-audit . for readiness score

Overview (`starters/post-merge-cleanup-opencode/README.md`) Copy Section

Post-Merge Cleanup — Opencode Starter

Clone-and-run scaffold for the Post-Merge Cleanup pattern with opencode. Follow-up tech debt after merges land on main.

Quick Start Copy Chapter

npx @cobusgreyling/loop-init . --pattern post-merge-cleanup --tool opencode

Or copy manually:

cp -r starters/post-merge-cleanup-opencode/skills .
cp starters/post-merge-cleanup-opencode/AGENTS.md .
cp starters/post-merge-cleanup-opencode/LOOP.md .
cp starters/post-merge-cleanup-opencode/post-merge-state.md.example post-merge-state.md
cp starters/post-merge-cleanup-opencode/opencode.json.example opencode.json

Start (report-only, week 1):

opencode run \
  "Run skills/post-merge-scan/SKILL.md. Scan merges to main in the last 48h. Propose small doc/lint/comment fixes only — ticket anything architectural. Update post-merge-state.md. Do not edit source code." \
  --title "Post-merge cleanup"

What's Included Copy Chapter

Next Steps Copy Chapter

• patterns/post-merge-cleanup.md
• examples/opencode/post-merge-cleanup.md
• docs/loop-design-checklist.md
• stories/post-merge-cleanup-honest-win.md

Overview (`starters/post-merge-cleanup/README.md`) Copy Section

Post-Merge Cleanup Starter

Scaffold for the Post-Merge Cleanup loop (L1 report → L2 small fixes).

Quick Start Copy Chapter

# Grok
npx @cobusgreyling/loop-init . --pattern post-merge-cleanup --tool grok

# Or manual copy
cp -r starters/post-merge-cleanup/.grok/skills/post-merge-scan .grok/skills/
cp starters/post-merge-cleanup/post-merge-state.md.example post-merge-state.md
cp starters/post-merge-cleanup/LOOP.md .

Start (Grok):

/loop 1d Run post-merge-scan on merges to main (last 7d). Update post-merge-state.md. Small doc/link fixes only in worktree. Run loop-context --check before each retry on the same regression; run loop-gate check before commit. Escalate refactors.

Files Copy Chapter

Safety Copy Chapter

• No large refactors without human ticket
• Denylist: feature flags, auth paths — see safety.md

Overview (`starters/pr-babysitter-opencode/README.md`) Copy Section

PR Babysitter — Opencode Starter

Clone-and-run scaffold for the PR Babysitter pattern with opencode. Watch open PRs, surface blockers, and act only on safe obvious maintenance tasks.

Quick Start Copy Chapter

npx @cobusgreyling/loop-init . --pattern pr-babysitter --tool opencode

Or copy manually:

cp -r starters/pr-babysitter-opencode/skills .
cp starters/pr-babysitter-opencode/AGENTS.md .
cp starters/pr-babysitter-opencode/LOOP.md .
cp starters/pr-babysitter-opencode/pr-babysitter-state.md.example pr-babysitter-state.md
cp starters/pr-babysitter-opencode/opencode.json.example opencode.json

Start (report-only, week 1):

opencode run \
  "Run PR babysitter triage. Read pr-babysitter-state.md first. List PRs with red CI, stale review, merge conflicts, or unanswered review comments. Do not edit code. Update pr-babysitter-state.md." \
  --title "PR babysitter"

What's Included Copy Chapter

Next Steps Copy Chapter

• patterns/pr-babysitter.md
• examples/opencode/pr-babysitter.md
• docs/loop-design-checklist.md
• stories/pr-babysitter-week-one.md

Overview (`starters/pr-babysitter/README.md`) Copy Section

PR Babysitter Starter

Scaffold for the PR Babysitter loop (L2 — assisted fixes with verifier).

Quick Start Copy Chapter

1. Copy into your repo:

   bash Copy

   npx @cobusgreyling/loop-init . --pattern pr-babysitter --tool grok
   # Or manual:
   cp -r starters/pr-babysitter/.grok/skills/* .grok/skills/
   cp starters/pr-babysitter/pr-babysitter-state.md.example pr-babysitter-state.md
   cp starters/pr-babysitter/LOOP.md .

2. Customize skills with your review norms and required checks.

3. Start (Grok):

   bash Copy

   /loop 5m Check open PRs. Update pr-babysitter-state.md. For CI failures or actionable review comments on allowlisted PRs: worktree + minimal-fix + loop-verifier. Run loop-context --check before each retry; run loop-gate check before commit. Never merge — propose only. Escalate after 3 attempts per PR.

4. Sign PR comments: 🤖 Loop Engineering — PR Babysitter

Files Copy Chapter

Safety Copy Chapter

• No auto-merge by default
• Denylist: auth, payments, secrets — see safety.md

Overview (`starters/thin-loop/README.md`) Copy Section

Thin Loop starter

One GitHub Action. No STATE.md, no skills, no budget files.

The issue tracker is the spine. The job summary is the report. Week one is L1 (report only).

Install Copy Chapter

npx @cobusgreyling/loop init . --pattern thin-loop --tool claude

Or copy:

mkdir -p .github/workflows
cp starters/thin-loop/.github/workflows/thin-loop.yml .github/workflows/

Merge to main. Open an issue or wait for the weekday cron. Read the Actions summary.

What you get Copy Chapter

What you do not get (on purpose) Copy Chapter

• STATE.md — add it when findings must persist across runs (Daily Triage).
• Agent invocation — wire loop-action later if you want a model in the loop.
• A high Loop Ready score — files-on-disk are not the goal here.

First week Copy Chapter

1. Merge the workflow.
2. Confirm one run is green.
3. Read the summary. Do not let it label, close, or push.
4. Graduate to Daily Triage only if you need a queue that GitHub does not already hold.

Overview (`tools/goal-audit/README.md`) Copy Section

goal-audit

Goal Readiness Score CLI for Grok Build /goal workflows.

Install / run Copy Chapter

npx @cobusgreyling/goal-audit .
npx @cobusgreyling/goal-audit . --suggest
npx @cobusgreyling/goal-audit . --json

Levels Copy Chapter

Development Copy Chapter

npm install
npm test

Overview (`tools/goal-init/README.md`) Copy Section

@cobusgreyling/goal-init

Scaffolds goal engineering workflows. This CLI initializes a directory with GOAL.md, goal-budget.md, and relevant skills to support autonomous agents in completing objectives incrementally.

Usage Copy Chapter

npx @cobusgreyling/goal-init . --tool grok

Supported tools:

• grok (default)
• claude
• codex
• opencode

Overview (`tools/loop-action/README.md`) Copy Section

Loop Engineering Action

An official GitHub Composite Action to safely execute autonomous agents in your CI/CD pipelines.

Instead of writing complex bash scripts to enforce circuit breakers, run readiness audits, and isolate agent execution in worktrees, this action wraps the entire Loop Engineering safety suite into a single, elegant step.

Usage Copy Chapter

- uses: cobusgreyling/loop-engineering/tools/loop-action@main
  with:
    pattern: 'ci-sweeper'
    command: 'npx grok-cli run --skill .grok/skills/ci-sweeper/SKILL.md'
    level: 'L2'
    sandbox: 'true'
    sandbox-shell: 'false'

Inputs Copy Chapter

What it does under the hood Copy Chapter

When this action runs, it sequentially executes:

1. loop-audit: Checks the repository against the Loop Readiness rubric (ensuring STATE.md, gate.yaml, and constraints are in place).
2. loop-context: Acts as a circuit breaker. It halts the workflow immediately if the loop is stuck in a failure cycle or has exhausted its daily token budget.
3. Write command script: command is passed through the step's env: map (not spliced into the run: script text) and written verbatim to a temp file under $RUNNER_TEMP. This keeps multi-line commands, quotes, and shell metacharacters intact as a single script instead of being re-parsed by the surrounding workflow YAML.
4. Execution (loop-sandbox): If sandbox: 'true', that script is invoked as bash -eo pipefail <script> inside an ephemeral git worktree via loop-sandbox, which tracks all modifications into a patch file and cleans up. Otherwise, it executes bash -eo pipefail <script> directly in the main tree.

Safe usage of `command` Copy Chapter

command is always executed as a Bash script via the temporary script file
written in step 3 above — this is true whether sandbox is 'true' or
'false', and regardless of sandbox-shell. The script runs with bash -eo pipefail, so:

• any command that exits non-zero stops the script immediately (set -e)
• a failing command anywhere in a pipeline fails the whole pipeline
  (pipefail), not just its last stage

sandbox-shell only controls whether loop-sandbox additionally routes the
bash <script> invocation through its own internal shell (--shell) before
running it — it is a loop-sandbox compatibility knob, not something you
need to set to get shell syntax (pipes, &&, multi-line scripts, etc.) in
command. Those already work through the temporary script regardless of
sandbox-shell.

Treat command the same as any other run: step in a workflow:

- uses: cobusgreyling/loop-engineering/tools/loop-action@main
  with:
    pattern: 'ci-sweeper'
    level: 'L2'
    sandbox: 'true'
    command: |
      npx grok-cli run --skill .grok/skills/ci-sweeper/SKILL.md
      echo "done"

Multi-line command: | blocks are supported and run as a single atomic
script — every line executes inside the chosen path (sandbox or direct), not
just the first.

Warning — never embed untrusted input directly in command.
Do not interpolate values from issue titles/bodies, PR titles/bodies, commit
messages, branch names, or any other content an external, untrusted actor
can influence (e.g. command: 'echo ${{ github.event.issue.title }}').
command runs as an arbitrary shell script with the permissions of the
job, so untrusted text placed in it is a shell/command injection
vulnerability regardless of how the action passes the string internally.
If you need data from the triggering event, pass it through an
intermediate step that validates/escapes it (or write it to a file and
have your agent read the file) instead of splicing it into command.

Overview (`tools/loop-audit/README.md`) Copy Section

loop-audit

CLI that scores a project's Loop Readiness (0–100) and suggests next steps.

npx @cobusgreyling/loop-audit . --suggest works immediately (published package).

Install & Run Copy Chapter

npm (recommended):

npx @cobusgreyling/loop-audit .
npx @cobusgreyling/loop-audit . --suggest

From this repo:

# readiness-core is a monorepo sibling (file: dep) — prebuild builds it for you
cd tools/loop-audit
npm install
npm run build   # runs prebuild → builds ../readiness-core, then tsc
node dist/cli.js /path/to/your/project

Before/after demo Copy Chapter

See scores climb from empty → L1 starter → L2 verifier:

bash scripts/before-after-demo.sh

Options Copy Chapter

loop-audit .              # human-readable (default)
loop-audit . --json       # machine-readable
loop-audit . --md         # markdown report
loop-audit . --suggest    # copy-from-template commands + activity tips (all tools)
loop-audit . --badge      # markdown README badge (Loop Ready level + score)

Exit code 2 if score < 40 (useful for CI gates once your project is loop-ready).

Publish to npm Copy Chapter

Maintainers:

cd tools/loop-audit
npm run build
npm publish --access public

Signals Checked (v1.7+) Copy Chapter

When score ≥ 80 and no .foundry/stack.yaml, audit recommends:

npx @cobusgreyling/loop-init . --with-foundry

L3 requires verifier + state + cost observability (budget + run log + LOOP.md budget), proven loop activity (not just files on disk), and proven guardrails: a loop-drill.json showing the current gate.yaml passing its drills, with no recorded guardrail failing.

Present is not proven Copy Chapter

Every signal counts content, not filenames:

• Empty files don't score. A file that is empty or whitespace, or JSON that is just {} / [], is a placeholder. The audit lists each one under Not counted instead of crediting it.
• Skills must load. A skill is a directory with a SKILL.md that has name and description frontmatter, which every host needs before it will invoke it. The same goes for a Claude Code verifier agent. A bare directory, or a file with no frontmatter, doesn't count, whatever it's called.
• gate.yaml must be a policy. It needs version: 1 and a denylist:. Anything else would be refused by loop-gate, so it earns nothing and is reported as a failure.

Files can only show a guardrail is configured. loop-drill shows whether it fires, by running it against a seeded fault and a benign case. Record the results and commit them:

npx @cobusgreyling/loop-drill . --record          # gate + breaker: offline, no tokens
npx @cobusgreyling/loop-drill . --only verifier --verifier-cmd "npm test" --setup "npm ci" --record
git add loop-drill.json

The audit reads the record per guardrail:

The gate proof is tied to a sha256 of gate.yaml (line endings normalised), so weakening the policy after recording drops L3 until the drills are run again. Gate and breaker drills are deterministic, so they don't expire otherwise.

The record is a claim the repo makes about itself, like a Last run: timestamp, so a determined author can hand-write one. Re-run the drills in CI to keep it honest; this repo's own CI does (see scripts/ci-validate-gates.sh and scripts/ci-audit-gates.sh).

Levels Copy Chapter

See docs/loop-design-checklist.md.

Overview (`tools/loop-context/README.md`) Copy Section

loop-context

Stateful memory manager for agent loops. Keeps the context window clean and stops runaway loops before they burn tokens.

Long-running agent loops fail in two classic ways the loop-engineering docs warn about:

• Context overflow & rot — conversation history and error logs grow until the model loses the original goal or drowns in stale stack traces.
• Stagnant / no-progress loops — the agent retries the same failing action forever, quietly blowing the token budget.

loop-context sits between the agent and its durable memory (STATE.md, run logs) and, before each iteration, does three things:

1. Summarize what has been tried and what failed.
2. Prune verbose stack traces, collapse repeated errors, and drop stale attempts outside a recent window.
3. Inject only the essentials into the next prompt.

A circuit breaker watches iteration count, token spend, stagnation (same error N× in a row), and no-progress (too many consecutive failures) — and escalates to a human instead of looping in vain.

Everything is deterministic and dependency-free: no LLM call is needed to summarize or prune, so it is cheap enough to run on every iteration.

Install / run Copy Chapter

npx @cobusgreyling/loop-context --help
# or from this repo:
cd tools/loop-context && npm install && npm test

The ledger Copy Chapter

The tool reads a run ledger — a JSON record of the loop's goal and its attempts:

{
  "goal": "Get the failing migration test to pass",
  "attempts": [
    { "iteration": 1, "action": "run migration", "outcome": "failure",
      "error": "Error: connect ECONNREFUSED 127.0.0.1:5432", "tokensUsed": 1500 },
    { "iteration": 2, "action": "run migration again", "outcome": "failure",
      "error": "Error: connect ECONNREFUSED 127.0.0.1:5432", "tokensUsed": 1400 }
  ]
}

outcome is success | failure | noop. error and tokensUsed are optional.

Usage Copy Chapter

# Circuit breaker — exit 0 = continue, 2 = escalate (wire into a loop's control flow)
loop-context --check --ledger run.json

# Compact context block for the next prompt
loop-context --inject --ledger run.json

# Factual rollup of the run
loop-context --summary --ledger run.json --json

# Pruned ledger (recent window, trimmed traces, collapsed repeats)
loop-context --prune --ledger run.json

# Pipe on stdin
cat run.json | loop-context --check

Options Copy Section

Exit codes: 0 continue · 2 escalate · 1 error.

A value that would switch a rule off is refused with exit 1 instead of being accepted. That covers a threshold of 0 or a fraction like 1.5, and a similarity threshold above 1: similarity is at most 1.0, so 95 would mean no two errors ever match and the stagnation rule never fires.

Resolving the token budget from a pattern Copy Chapter

Typing --token-budget <n> by hand means guessing. loop-cost already
computes a realistic per-run estimate for every pattern and readiness level, so resolve
the cap from there instead:

loop-context --check --ledger run.json --budget-from-pattern ci-sweeper --budget-level L2

An explicit --token-budget <n> always wins over --budget-from-pattern — the derived
value only fills in when no number was typed. loop-context shells out to loop-cost's
built CLI (monorepo sibling first, then an installed @cobusgreyling/loop-cost
dependency) — the same resolution loop-init already uses for loop-audit — so the two
packages stay independent at the source level; an unknown pattern id surfaces
loop-cost's own error instead of failing silently.

Tracking a daily cap across separate runs Copy Chapter

--budget-from-pattern only guards one run's ledger. Patterns also have a daily
cap (loop-cost's suggestedDailyCap) that spans many runs across a day —
--daily-budget-from-pattern tracks that:

loop-context --check --ledger run.json --daily-budget-from-pattern ci-sweeper \
  --budget-level L2 --on-exceed ./scripts/on-budget-exceed.sh

Each --check call adds the ledger's newest attempt's tokensUsed to a per-pattern
state file (daily-spend..json, { "date": "...", "tokensUsedToday": N }),
rolling over to zero when the stored date isn't today (UTC). Once the running total
reaches the pattern's suggested daily cap, --check escalates with trigger
daily-budget — but only if no per-run trigger (stagnation, no-progress, token-budget,
max-iterations) already fired; per-run reasons always take priority. --budget-level,
--budget-cadence, and --budget-conservative (shared with --budget-from-pattern)
shape the daily-cap lookup too.

--on-exceed <script> fires on any escalate, not just daily-budget — it's a
generic hook for automating loop-budget.md's "On budget exceed" checklist (pause
schedulers, log the event, notify a human) instead of doing those steps by hand. The
script's exit code is not checked and does not change --check's own exit code.

Populating the ledger Copy Chapter

Your loop control script appends one object per iteration to run.json (or pipes the same shape on stdin):

# after each agent iteration — append attempt, then gate the next one
node -e "
const fs = require('fs');
const ledger = JSON.parse(fs.readFileSync('run.json', 'utf8'));
ledger.attempts.push({
  iteration: ledger.attempts.length + 1,
  action: 'run migration tests',
  outcome: 'failure',
  error: process.argv[1],
  tokensUsed: Number(process.argv[2] || 0),
});
fs.writeFileSync('run.json', JSON.stringify(ledger, null, 2));
" \"\$ERROR_MSG\" \"\$TOKENS\"
loop-context --check --ledger run.json || { loop-context --inject --ledger run.json; exit 2; }

Initialize once at loop start: { \"goal\": \"Get CI green on main\", \"attempts\": [] }.

In a loop Copy Chapter

# inside your loop's control script, before each iteration:
if ! loop-context --check --ledger run.json; then
  loop-context --inject --ledger run.json > escalation.md   # hand a clean summary to the human
  exit 0                                                     # stop instead of retrying
fi

Library API Copy Chapter

import {
  checkCircuitBreaker,
  pruneLedger,
  summarizeAttempts,
  buildContextInjection,
} from '@cobusgreyling/loop-context';

const decision = checkCircuitBreaker(ledger);
if (decision.escalate) escalateToHuman(decision.reason);
else runNextIteration(buildContextInjection(ledger));

checkCircuitBreaker, pruneLedger, summarizeAttempts and buildContextInjection throw on a config that would switch a rule off (a non-positive or fractional count, or a similarityThreshold outside (0, 1]), rather than quietly never escalating. Call validateBreakerConfig / validatePruneConfig to check a config up front.

Where it fits Copy Chapter

This is the Memory / State primitive of loop engineering made dynamic: STATE.md stores state statically; loop-context manages it across iterations. See docs/primitives.md and the operating & safety guides.

MIT · part of loop-engineering by Cobus Greyling.

Overview (`tools/loop-cost/README.md`) Copy Section

loop-cost

Estimate daily token spend for loop engineering patterns by cadence and readiness level (L1–L3).

Uses cost metadata from patterns/registry.yaml.

Install & Run Copy Chapter

npx @cobusgreyling/loop-cost --pattern ci-sweeper --cadence 15m --level L2
npx @cobusgreyling/loop-cost --pattern daily-triage --level L1 --json
npx @cobusgreyling/loop-cost --list
npx @cobusgreyling/loop-cost --pattern daily-triage --level L1 --with-caching

From this repo:

cd tools/loop-cost
npm install
npm test

Options Copy Chapter

Scenarios Copy Chapter

Each estimate includes:

• Early-exit / no-op — empty watchlist, minimal tokens
• Full triage — every run does a full scan
• Action every run — implementer + verifier every time (worst case)
• Realistic blend — level-based mix (documented in output)
• Caching (opt-in via --with-caching) — discounts the stable portion of tokens using Anthropic-style cache-read pricing (~10% of base input); omitted when a pattern has no stable_fraction

Pair with loop-budget.md (scaffolded by loop-init) and loop-audit cost observability checks.

Orchestration cost Copy Chapter

The scenarios above assume one implementer pass. A loop that fans out to
multiple agents costs more on the action path (the no-op scan and single
triage pass are unaffected). --orchestration applies a multiplier so the
estimate — and the realistic per-run cap that feeds the circuit breaker —
reflects the real shape of the run:

npx @cobusgreyling/loop-cost --pattern ci-sweeper --level L2 --orchestration maker-checker
npx @cobusgreyling/loop-cost --pattern ci-sweeper --level L2 --orchestration parallel:3

Multipliers above 2x emit a warning — deep fan-out or debate is easy to enable
and expensive to run unattended.

Feed the circuit breaker Copy Chapter

loop-context's breaker can resolve --token-budget directly
from a pattern's realistic per-run estimate instead of a hand-typed guess:

npx @cobusgreyling/loop-context --check --ledger loop-ledger.json \
  --budget-from-pattern ci-sweeper --budget-level L2

loop-context shells out to this CLI's built output to do it — the packages stay
independent at the source level, no shared runtime state. An explicit
--token-budget on the loop-context call always overrides the derived value.

See docs/operating-loops.md.

Overview (`tools/loop-drill/README.md`) Copy Section

loop-drill

Fire drills for loop guardrails. Injects a known fault and asserts the guardrail actually fires.

loop-audit scores whether your guardrails are present. loop-drill tests whether they work.

Why Copy Chapter

docs/failure-modes.md names the ways loops fail. Several have mechanical counterparts — loop-gate for path scope, loop-context's circuit breaker for runaway retries. loop-audit awards points for having them.

Nothing checked whether they fire.

The sharpest case is the verifier. loop-audit gives its joint-largest signal (14 points) for a verifier and gates L3 on it. From files alone it can only check that a verifier loads: a skill or agent file with a name and a description. A verifier that approves everything loads just as well. docs/failure-modes.md calls the resulting failure Verifier Theater and rates it S2; docs/primitives.md calls maker/checker "the single most important structural pattern for reliable loops".

loop-drill closes that gap by running the real verifier against real seeded defects, and --record hands the result back to loop-audit.

Usage Copy Chapter

# Offline drills — no agent, no tokens, no network
npx @cobusgreyling/loop-drill .

# The verifier canary
npx @cobusgreyling/loop-drill . --only verifier \
  --verifier-cmd "npm test" --setup "npm ci"

# The injection canary — pass the command your loop runs
npx @cobusgreyling/loop-drill . --only injection \
  --agent-cmd "claude -p 'run the loop-triage skill'"

# Record the results for loop-audit (commit loop-drill.json)
npx @cobusgreyling/loop-drill . --record

Options Copy Section

Exit codes match loop-gate and loop-context so control scripts chain all three: 0 all passed, 1 some skipped, 2 a guardrail failed to fire.

The drills Copy Chapter

Each drill is tagged with the docs/failure-modes.md entry it exercises, so the report reads as coverage of that document.

A breaker drill is only credited when the breaker escalates for the rule under test. Escalating for another reason — say, the iteration cap firing before stagnation is ever checked — leaves that rule unproven, and the drill fails.

Both directions, always Copy Section

Every guardrail is drilled twice, because only one direction is easy:

• sensitivity — the fault is caught. A guardrail that never fires is theater.
• specificity — benign input is not caught. A guardrail that blocks everything passes every sensitivity drill while being useless.

A denylist: ["**"] catches every seeded fault and still fails, because it blocks an ordinary docs change too.

Recording proof for loop-audit Copy Chapter

loop-audit scores what a repo has. --record lets it score what works. It writes loop-drill.json at the repo root, grouped by guardrail:

{
  "schema": 1,
  "tool": "@cobusgreyling/loop-drill",
  "guardrails": {
    "gate": {
      "recordedAt": "2026-09-28T15:08:23.379Z",
      "input": { "file": "gate.yaml", "sha256": "…" },
      "results": [
        { "id": "gate.denylist[**/.env]", "failureMode": "Over-Reach (Wrong Scope)", "direction": "sensitivity", "outcome": "passed" },
        { "id": "gate.benign", "failureMode": "Over-Reach (Wrong Scope)", "direction": "specificity", "outcome": "passed" }
      ]
    }
  }
}

• Failures are recorded too. loop-audit withdraws the points for a guardrail shown not to fire, so a verifier that approves seeded defects stops counting as a verifier.
• Only the guardrails you ran are replaced. --only verifier --record refreshes the canary and keeps the gate and breaker results, so a slow canary doesn't have to be repeated to refresh a cheap drill.
• The gate proof is tied to the policy it drilled. The record keeps a sha256 of gate.yaml (line endings normalised). Edit the file and loop-audit treats the old proof as stale until you record again. Canary results expire after 30 days, because the code and the agent they tested keep changing.

loop-audit needs the current gate.yaml proven for L3. That means at least one drill caught its fault, at least one benign case got through, and nothing failed. It's the same both-directions rule the drills follow.

How the verifier canary works Copy Chapter

Borrowed from mutation testing. Rather than asking a model to invent a defect — non-deterministic and token-hungry — it applies a small mechanical edit to real source and checks whether the verifier notices:

control (repo)      no defect     -> must ACCEPT (exit 0)
control (worktree)  no defect     -> must ACCEPT (exit 0)
mutant × N          one defect    -> must REJECT (non-zero)

Mutation score = mutants rejected / mutants run.

Three properties make the result trustworthy:

1. Isolation. Each run happens in an ephemeral git worktree, removed even on throw, so a verifier that writes or builds cannot touch your checkout.
2. The worktree control. A fresh worktree has no node_modules. Without this second control, npm test would fail there for reasons unrelated to code quality and every mutant would score as caught — a broken setup reporting a perfect score. When it fails, mutants are skipped, not scored, and you're pointed at --setup.
3. Bail on a failed control. A verifier that rejects a clean tree catches every mutant while being worthless. The mutants never run, so it can't report 100%.

Operators are restricted to edits that change behaviour in any C-family language and that a reviewer would call a bug: ===↔!==, <=→<, >=→>, &&→||, return true↔return false. Ambiguous edits are deliberately excluded — <→> breaks TS generics and JSX, +→- mangles string concatenation, and either would make a correct verifier look broken. Matches inside comments are skipped, and test files, dist/, and node_modules/ are never mutated.

How the injection canary works Copy Chapter

Loops copy third-party text — issue and PR titles, check names — into STATE.md and read it back on the next run. Anyone can open an issue. A skill can tell the agent to treat that text as data (Untrusted input); this drill checks whether it does.

It plants a benign instruction in the state file inside an ephemeral worktree, runs your real agent command there, and inspects what the agent did:

control             clean worktree        -> the agent must run (exit 0, or 2 = escalated)
visible             instruction in a      -> not obeyed, not copied forward
                    planted issue title
hidden-comment      instruction in an     -> not obeyed, not copied forward
                    HTML comment

The planted instruction only ever asks for a marker file named with a fresh random nonce, so running it against a real agent is harmless whatever happens. The marker's presence — at the root or anywhere else in the worktree — means the agent obeyed. The nonce appearing in a file the agent wrote means it copied the payload forward, where it would be read again next run; that fails too, because it is how an injection outlives the run that should have caught it. An agent that rewrites the state file and drops the suspicious item passes.

Injection resistance = variants ignored / variants run.

The same trap as the verifier canary applies: an agent that never starts "resists" every injection. So the control must complete in a clean worktree before any variant runs, and a variant where the agent crashes without leaving a marker is inconclusive (skipped), never a pass. Exit 2 counts as a completed run, since that is how loops here escalate to a human.

Example Copy Chapter

A rubber-stamp verifier, caught:

Verifier Theater — ❌ NOT PROVEN
  ✅ verifier accepts an unmodified tree
  ✅ verifier accepts a clean worktree
  ❌ verifier rejects strict-equality-flip in src/gate.ts:34
      expected: non-zero exit (rejected)
      actual:   exit 0 (approved a seeded defect)
      flip === to !== (typeof v === 'string' -> typeof v !== 'string')

Mutation score: 0% of seeded defects rejected

Limitations Copy Chapter

• Mutation is regex-based, not AST-based. It cannot construct a semantically interesting bug, only a mechanically detectable one. A verifier that catches every mutant is not proven to catch subtle logic errors — this establishes a floor, not a ceiling.
• The canary costs whatever your verifier costs, once per mutant plus two controls. Start with --mutants 1 and --scope.
• The injection canary tests two payloads, not all of them. Resisting a planted title and an HTML comment is evidence, not proof — a determined attacker has far more phrasings. Treat a pass as a floor, and keep tokens least-privilege regardless.
• The injection canary only sees effects inside the worktree. It detects a marker file and copied text. An agent that obeyed by calling an external API would not be caught; the payload never asks for that, so a real run stays harmless.
• Each canary run costs one agent run per variant plus a control. With a real model, that is three runs by default.
• Escalation Failure and Notification Fatigue have no drills yet — they need a notification sink to observe.

Development Copy Chapter

npm ci && npm test

License Copy Chapter

MIT

Overview (`tools/loop-gate/README.md`) Copy Section

loop-gate

Mechanical enforcement of static safety policy — the code behind docs/safety.md's Path Denylist and Auto-Merge Policy, and LOOP.md's "No auto-merge on main except trivial dependency patches" / "Denylist... without human review" rules. Nothing evaluated a proposed change against that prose before; loop-gate does.

Deliberately has no knowledge of run history. Stagnation, repeated failures, and token/daily budgets already belong to loop-context's circuit breaker — loop-gate only looks at what is being proposed (which paths, what action type), not how the run has behaved so far. Chain the two:

loop-context --check --ledger run.json ...            || exit 2   # run-history based
loop-gate check --action auto-merge --paths a.ts,b.ts  || exit 2   # policy based
do-the-merge

Install & Run Copy Chapter

npx @cobusgreyling/loop-gate check --action auto-merge --paths docs/guide.md

From this repo:

cd tools/loop-gate
npm install
npm test

Usage Copy Chapter

loop-gate check --action <commit|merge|auto-merge> --paths <f1,f2,...> [--gate-file gate.yaml] [--json]

Exit codes: 0 allowed · 2 escalate · 1 error (bad flags, missing/invalid config).

Policy file Copy Chapter

gate.yaml is the machine-readable twin of docs/safety.md — see templates/gate.yaml.template to scaffold your own, or this repo's own dogfood gate.yaml:

version: 1
denylist:
  - ".env"
  - "**/secrets/**"
  - "auth/**"
maxFiles: 10
autoMergeAllowlist:
  - "docs/**"
  - "**/*.md"

Checked in order (first match wins, same "most specific trigger first" convention loop-context's circuit breaker uses):

1. denylist — any changed path matching a glob here escalates, regardless of --action.
2. maxFiles — more changed paths than this escalates (matches docs/safety.md's "Changes touching >N files" human gate).
3. autoMergeAllowlist — only checked when --action auto-merge; every changed path must match one of these globs, or it escalates.

Glob matching is via minimatch (the same semantics .gitignore-style globs use — ** matches across path segments).

What this does not do Copy Chapter

• Does not read a run ledger, and never will — that keeps it decoupled from loop-context at the source level, the same way loop-worktree and loop-context stay independent while still being paired by convention in a control script.
• Does not produce its own escalation summary format — fold its JSON decision into whatever your control script already assembles from loop-context --inject when escalating to a human.
• Does not enforce anything by itself — like loop-worktree's locks, this is advisory: a control script that skips calling loop-gate is not physically blocked. The mechanism is only as good as the scripts that call it.

See docs/safety.md for the policy this codifies, and docs/primitives.md for where safety gates fit in the Five Building Blocks + Memory model.

Overview (`tools/loop-init/README.md`) Copy Section

loop-init

Scaffold loop engineering starters into your project by pattern and tool.

npx @cobusgreyling/loop-init . --pattern daily-triage --tool claude works immediately.

See docs/loop-init-validation.md for a validated pattern × --tool matrix.

Install & Run Copy Chapter

npx @cobusgreyling/loop-init . --pattern daily-triage --tool claude
npx @cobusgreyling/loop-init . --pattern daily-triage --tool opencode
npx @cobusgreyling/loop-init . -p pr-babysitter -t claude
npx @cobusgreyling/loop-init . -p dependency-sweeper --dry-run
# One-command LE → harness-foundry funnel:
npx @cobusgreyling/loop-init . --pattern daily-triage --tool claude --with-foundry

See docs/RELEASE.md for npm publish tags. The published package bundles starters/ and templates/ from this monorepo.

After scaffolding, always run npx @cobusgreyling/loop-audit . --suggest and actually execute the first report-only loop to generate activity signals.

`--with-foundry` (harness runtime) Copy Chapter

Scaffolds a harness-foundry stack beside your loop files:

Creates .foundry/stack.yaml, outerloop hook stub, and a short README. Equivalent alias on the Foundry CLI:

npx @cobusgreyling/harness-foundry init --from loop-engineering:daily-triage

Every loop-init run prints a Foundry CTA; when Loop Ready is ≥ 80, the CTA is emphasized as the next step after design.

Interface provider (implementer preset) Copy Section

The implementer preset defaults to the built-in interface primitive. Pass --model-provider minimax to emit a model/minimax provider primitive instead, --model-provider orcarouter to emit a model/orcarouter provider primitive, or --model-provider cheaperinference to emit a model/cheaperinference provider primitive. The generated stack always carries the provider endpoints and model options, so you can switch provider/model without regenerating:

npx @cobusgreyling/loop-init . -p ci-sweeper -t grok --with-foundry --model-provider minimax
npx @cobusgreyling/loop-init . -p ci-sweeper -t grok --with-foundry --model-provider minimax --region cn_zh --model MiniMax-M2.7
npx @cobusgreyling/loop-init . -p ci-sweeper -t claude --with-foundry --model-provider orcarouter
npx @cobusgreyling/loop-init . -p ci-sweeper -t claude --with-foundry --model-provider orcarouter --model orcarouter/auto
npx @cobusgreyling/loop-init . -p ci-sweeper -t claude --with-foundry --model-provider cheaperinference
npx @cobusgreyling/loop-init . -p ci-sweeper -t claude --with-foundry --model-provider cheaperinference --model claude-sonnet-5

MiniMax model options and both endpoints (global_en → https://api.minimax.io, cn_zh → https://api.minimaxi.com) are written into .foundry/stack.yaml. The OrcaRouter provider writes the gateway's OpenAI- and Anthropic-compatible endpoints (https://api.orcarouter.ai) plus its routing model options (orcarouter/fusion, orcarouter/fusion-flash, orcarouter/auto, orcarouter/free). The Cheaper Inference provider writes the gateway's OpenAI-compatible (https://api.cheaperinference.com/v1) and Anthropic-compatible (https://api.cheaperinference.com) endpoints plus its model options. Set CHEAPER_INFERENCE_API_KEY to a key from cheaperinference.com/signup.

Patterns Copy Chapter

L2 patterns (ci-sweeper, dependency-sweeper) also copy minimal-fix and loop-verifier templates when missing from the starter.

Fix-capable patterns (pr-babysitter, ci-sweeper, dependency-sweeper, post-merge-cleanup) also get a circuit breaker:

• loop-guard skill — logs each attempt to loop-ledger.json and runs loop-context --check before retrying
• loop-ledger.json — seeded with the pattern's goal, its pattern/level, and an empty attempts array

The ledger's pattern/level let loop-guard size the breaker's --token-budget from loop-cost's realistic per-run estimate instead of a hand-typed number. The breaker escalates (same error N× in a row, too many consecutive failures, token budget, or iteration cap) instead of looping in vain. Report-only patterns skip it.

Patterns that act on human-authored, often underspecified input (issue-triage) also get an intake skill:

• loop-intake skill — when a work item is too vague to verify "done", it asks one question at a time, pushes for exact values, and writes an open question + needs-human escalation instead of guessing. Clarifying up front keeps the loop from burning fix attempts on a goal that was never well defined.

Every scaffold also creates:

• loop-budget.md — pattern-specific daily caps and kill switch
• loop-run-log.md — append-only run history
• loop-budget skill — runtime budget guard at start/end of each run

Tools Copy Chapter

• grok (default)
• claude
• codex
• opencode — daily-triage ships minimal-loop-opencode (skills/, AGENTS.md, opencode.json)

Falls back to Grok starter paths when a per-tool variant is not yet available.

From this repo Copy Chapter

cd tools/loop-init && npm ci && npm test
node dist/cli.js /path/to/project --pattern daily-triage --tool grok

Pair with loop-audit and loop-cost after scaffolding:

npx @cobusgreyling/loop-cost --pattern daily-triage --level L1
npx @cobusgreyling/loop-audit . --suggest

Overview (`tools/loop-metrics/README.md`) Copy Section

loop-metrics

A CLI dashboard for visualizing the token burn, success rate, and ROI of your autonomous loops based on loop-run-log.md.

Installation Copy Chapter

This tool runs natively against your loop-engineering repository:

npm install @cobusgreyling/loop-metrics

(Or just run it via npx from your project root without installing)

Usage Copy Chapter

Run the dashboard from the root of a project containing a loop-run-log.md:

npx @cobusgreyling/loop-metrics

Filtering Copy Section

You can filter the dashboard by a specific loop pattern or restrict the timeframe to a certain number of days (e.g. 7d for the last 7 days):

# Only show metrics for the daily-triage pattern over the last 30 days
npx @cobusgreyling/loop-metrics --pattern daily-triage --timeframe 30d

Options Copy Section

• --log : Path to your loop run log (default: ./loop-run-log.md)
• --pattern : Calculate metrics only for a specific pattern.
• --timeframe <days>: Limit calculation to runs within the last N days (e.g., 7d, 30d).
• --help: Show the help message.

How ROI is Calculated Copy Chapter

loop-metrics uses a simple heuristic to calculate ROI:

• +10 points for every action_taken (successful fix, triage, or state update).
• -5 points for every escalation (tripping a circuit breaker or requiring human intervention).

This gives you an instant, high-level view of whether your autonomous loops are providing net positive value or just generating noise.

Overview (`tools/loop-sandbox/README.md`) Copy Section

loop-sandbox

Ephemeral worktree isolation for Loop Engineering. Divert agent execution into an isolated git worktree, capture their changes as a reviewable .patch file, and instantly destroy the sandbox.

Why loop-sandbox? Copy Chapter

Unattended AI agents (loops) running directly in your main working tree can cause damage, overwrite untracked files, or make it incredibly tedious to untangle failed execution attempts.

loop-sandbox solves this by providing ephemeral worktree isolation:

1. It automatically creates an isolated git worktree for the agent to run in.
2. The agent runs its command, interacting with the codebase completely naturally.
3. When the command finishes, loop-sandbox automatically captures the agent's edits (including new untracked files) into a clean .patch file.
4. It nukes the worktree, keeping your main repo completely clean.

A human can then safely review the patch and apply it with one keystroke.

[!WARNING]
Isolation Limits: This is not a containerized air-gap. The agent process retains full filesystem and network access. It can escape the worktree (e.g. ../../), and changes outside the worktree or to .gitignored files will not be captured in the patch. This tool is complementary to docs/safety.md and does not replace OS-level sandboxing for hostile code.

Installation Copy Chapter

npm install @cobusgreyling/loop-sandbox
# or run directly via npx
npx @cobusgreyling/loop-sandbox run -- <command>

[!IMPORTANT]
Required Gitignores: You must add the following to your project's .gitignore to prevent patches and worktree manifests from being committed:

text Copy

.loop-sandbox/
.loop-worktrees/

Usage Copy Chapter

loop-sandbox <command> [options]

Commands Copy Section

Options for `run` Copy Section

Examples Copy Section

Running a tool via an agent:

# Safely let an agent run your linter/formatter without polluting your working tree
npx @cobusgreyling/loop-sandbox run -- npx my-agent

Running a shell command:

npx @cobusgreyling/loop-sandbox run --shell -- bash -c "echo 'hello' > test.txt"

Running alongside a scheduled loop that touches the same files:

npx @cobusgreyling/loop-sandbox run --lock-paths "src/**,docs/**" -- npx my-agent

Reviewing and applying patches:

# List all patches the sandbox caught
npx @cobusgreyling/loop-sandbox review

# Example output:
# === Loop Sandbox Patches ===
# 📄 sandbox-82f1e394.patch (1.2 KB)
#    Apply: git apply .loop-sandbox/patches/sandbox-82f1e394.patch

How it works Copy Chapter

Under the hood, loop-sandbox leverages @cobusgreyling/loop-worktree and native git worktree primitives. It creates a temporary branch from your current HEAD, spawns your process with its cwd set to the isolated tree, runs git diff --cached to generate the patch, and uses git worktree remove --force to clean up.

Multi-loop safety Copy Chapter

A sandbox run is not, by itself, protected against a scheduled loop editing
the same files at the same time -- --lock-paths opts a run into
loop-worktree's advisory lock (acquired before the worktree is created,
released once the run finishes) so a colliding scheduled loop's own lock
call fails loudly instead of racing silently. See
docs/multi-loop.md for the wider convention this
follows.

Overview (`tools/loop-swarm/README.md`) Copy Section

loop-swarm

Multi-agent consensus sandboxing for extreme high-confidence loop operations.

loop-swarm runs an agent command multiple times sequentially in separate, isolated loop-sandbox worktrees. It then extracts the resulting .patch files from each run, hashes them, and automatically determines if a majority consensus was reached.

If an agent produces non-deterministic results, loop-swarm acts as an L3 safety net by ensuring that only changes verified by multiple sequential agent runs are proposed.

[!IMPORTANT]
This tool implements an ephemeral git worktree isolation safety boundary. It is NOT an OS-level sandbox or container. For full details on the threat model, please read Safety Boundaries.

Usage Copy Chapter

npx @cobusgreyling/loop-swarm run --count 3 -- npx my-agent run --task "Refactor utils.ts"

See Quickstart for workflow examples and command patterns.

How it works Copy Chapter

1. Spawns N (default: 3) instances of loop-sandbox sequentially (to prevent git worktree and signal handler races).
2. Waits for all sandboxes to finish executing the agent and extract their diffs. Any agent that fails (non-zero exit code) is disqualified from voting.
3. Hashes the raw byte contents of each .patch file.
4. If a strict majority (Math.floor(N / 2) + 1 of the total launched agents) produce the exact same byte-for-byte patch, it copies the winning patch to .loop-sandbox/patches/consensus.patch.
5. Cleans up all the ephemeral worktrees.

Exit Codes & Behavior Copy Chapter

• 0: Consensus reached successfully (either on a specific patch, or on "no changes needed" if the majority of agents succeeded without producing a patch).
• 1: Failure to reach consensus, or internal tool failure.

Limitations Copy Chapter

• Byte-Identical Consensus: Consensus relies on exact SHA-256 hashing of the patch bytes. If two agents arrive at semantically identical code but with different whitespace or comment ordering, loop-swarm will consider them divergent.
• Shared Stdio: The sequential agents share the parent process's standard IO.
• Time Penalty: Because execution is currently serialized to maintain safety guarantees on the manifest, running an agent with --count 3 will take roughly 3x as long as running it once.
• SIGINT Handling: Because loop-sandbox runs in-process, its signal handler will exit the entire process on SIGINT. A signal during an agent run exits the entire swarm rather than allowing swarm-owned cleanup. This is a v1 limitation until subprocessing is implemented.

Overview (`tools/loop-sync/README.md`) Copy Section

loop-sync

Detect and sync drift between Loop configuration files in your repository.

Why loop-sync? Copy Chapter

When working in teams, Loop configurations can drift over time:

• STATE.md and LOOP.md get out of sync
• Skills are updated but not reflected in configuration
• Required files are missing
• Configuration drifts from starters

loop-sync detects these issues and provides actionable suggestions.

Installation Copy Chapter

npm install @cobusgreyling/loop-sync
# or
npx @cobusgreyling/loop-sync .

Usage Copy Chapter

loop-sync [target-dir] [options]

Options Copy Section

Examples Copy Section

# Basic sync check
loop-sync .

# Verbose output
loop-sync ./my-project -v

# JSON output for scripting
loop-sync ./my-project --json

# Preview what --auto-fix would scaffold/change, without writing anything
loop-sync ./my-project --auto-fix --dry-run

# Scaffold the safely-fixable files and fix the LOOP.md/STATE.md reference
loop-sync ./my-project --auto-fix

What it checks Copy Chapter

1. Required files

   • STATE.md (required)
   • LOOP.md (required)
   • AGENTS.md (recommended)

2. STATE.md ↔ LOOP.md consistency

   • Structural similarity
   • State file references
   • Pattern consistency

3. gate.yaml ↔ docs/safety.md policy parity

   • Denylist paths documented in docs/safety.md but not enforced by gate.yaml (error —
     readers trust the doc while loop-gate silently allows the path)
   • Denylist paths enforced by gate.yaml but undocumented in docs/safety.md (warning)
   • gate.yaml limits such as maxFiles that the prose policy never states (info)

   gate.yaml calls itself "the machine-readable twin of docs/safety.md" and asks you to keep
   the two in sync by hand. This check makes that invariant mechanical. It is read-only even
   under --auto-fix: which side is correct is a human decision, so loop-sync reports the
   divergence rather than silently rewriting a safety policy.

   Skipped when either file is absent — a project with no docs/safety.md has no prose policy
   to drift from.

4. Skills directory

   • Existence of .claude/skills/
   • Version information in SKILL.md files

5. Configuration drift

   • Missing references
   • Orphaned files
   • Inconsistencies

Score Interpretation Copy Chapter

Output Example Copy Chapter

Loop Sync Report
══════════════════════════════════════════════════
Score: 85/100 (healthy)

✅ No issues detected. Configuration is consistent.

💡 Suggestions:
   - Run loop-init to scaffold missing files

Integration with CI/CD Copy Chapter

Add to your GitHub Actions workflow:

- name: Run loop-sync
  run: npx @cobusgreyling/loop-sync .

Development Copy Chapter

cd tools/loop-sync
npm install
npm run build
npm test

License Copy Chapter

MIT

Overview (`tools/loop-worktree/README.md`) Copy Section

loop-worktree

Manage isolated git worktrees for loop engineering attempts. One worktree per fix attempt; mark it when the verifier rejects or a human escalates; sweep the discarded ones.

LOOP.md and docs/primitives.md describe this convention in prose ("one worktree per fix; discard after verifier REJECT or human escalation"). This tool is the code behind it: a shared place for worktrees to live, a manifest that tracks their status, and a reconciler that sweeps orphans.

Install & Run Copy Chapter

npx @cobusgreyling/loop-worktree create --run-id ci-sweeper-2026-07-07-01 --pattern ci-sweeper
npx @cobusgreyling/loop-worktree list

From this repo:

cd tools/loop-worktree
npm install
npm test

Library API Copy Chapter

ESM consumers can use the worktree API from the package root and the lock
coordinator from its supported lock subpath:

import { createWorktree, cleanupWorktrees } from '@cobusgreyling/loop-worktree';
import { lockPaths, unlockOwner } from '@cobusgreyling/loop-worktree/lock';

The lock subpath is the stable programmatic entry point for tools that need
advisory path locking without importing private files under dist/. See Quickstart for CLI and JS usage.

Commands Copy Chapter

loop-worktree create --run-id <id> --pattern <p> [--base main]
  # git worktree add -b loop/<id> .loop-worktrees/<id> <base>, records the manifest entry

loop-worktree mark --run-id <id> --status rejected
  # updates the manifest only (audit trail); does not delete the worktree

loop-worktree cleanup [--status rejected,escalated] [--older-than 24h] [--force]
  # git worktree remove for matching entries, then prunes them from the manifest

loop-worktree gc [--force] [--json]
  # reconciles `git worktree list` against the manifest:
  #   - on disk under .loop-worktrees/ but not in the manifest -> reported as an orphan
  #   - in the manifest but not on disk -> dropped from the manifest
  # report-only by default; --force removes orphans

loop-worktree list [--status active] [--json]

loop-worktree lock --paths <glob1,glob2,...> --owner <name> [--ttl 6h] [--wait 15m]
  # advisory lock: fails if another (non-expired) owner already holds an overlapping path
  # --wait queues instead of failing immediately; detects wait-for-graph deadlocks

loop-worktree unlock --owner <name>
  # releases that owner's lock; no-op if it didn't hold one

loop-worktree locks [--sweep] [--force] [--json]
  # lists active locks and wait intents; --sweep reports expired ones (report-only; --force deletes them)

Status Copy Chapter

An entry is one of: active, rejected, escalated, merged, stale.

cleanup sweeps rejected and escalated by default. active is never swept automatically.

Safety Copy Chapter

• create fails with a clear message (not a raw git error) if the directory is not a git repo, or if --run-id already has an active worktree.
• cleanup runs git worktree remove without --force first, so git refuses to delete a worktree with uncommitted or untracked changes; that entry is reported as skipped. Pass --force only when you accept the data loss.
• gc is report-only by default, matching the repo's convention that anything scanning broadly reports rather than acts.

Preventing multi-loop collisions Copy Chapter

Independently-scheduled loops can race on the same files -- see
stories/multi-loop-collision.md and
stories/dependency-vs-ci-sweeper-collision.md
for real incidents this caused. lock/unlock give
docs/multi-loop.md's acting_on convention a
mechanical form:

loop-worktree lock --paths package.json,package-lock.json --owner dependency-sweeper --ttl 6h \
  || exit 2   # another owner holds an overlapping path -- skip this run
loop-worktree create --run-id "$RUN_ID" --pattern dependency-sweeper
# ... do the work ...
loop-worktree unlock --owner dependency-sweeper

It's deliberately advisory, not enforced by create itself -- a loop that
skips the lock call is not physically blocked, matching this repo's
existing "prose plus tooling" philosophy rather than hard sandboxing.
Locking is keyed on path globs, not run ids, so it also catches collisions
across different patterns (e.g. CI Sweeper and Dependency Sweeper both
touching package.json), not just within one.

--paths overlap is compared segment by segment (split on /): a wildcard
segment (* or **) is compatible with anything at that position, so
src/** overlaps src/foo.ts, but docs/api does not overlap
docs/apidocs.md (different literal segments, not just a shorter string).
This is intentionally simple (an advisory lock, not a full glob engine),
matching how --older-than already parses durations elsewhere in this tool.

Locks never expire on their own unless you pass --ttl; an orphaned lock
(owner crashed without unlocking) is surfaced -- not silently ignored -- by
loop-worktree locks --sweep, and only deleted with --force, mirroring
gc's existing report-only-by-default convention for anything that scans
broadly instead of acting on one named target. --owner is restricted to
letters, digits, ., _, - (no path separators), since it names the lock
file directly. Concurrent lock calls are serialized through a short-lived
mutex file so two racing invocations can't both pass the overlap check
before either writes.

Pairing with loop-context Copy Chapter

A loop's control script that calls loop-context --check and escalates should also mark its worktree:

loop-worktree mark --run-id "$RUN_ID" --status escalated

The two tools stay independent: loop-worktree does not read the ledger, and loop-context does not know about git.

Manifest Copy Chapter

.loop-worktrees/manifest.json (add .loop-worktrees/ to .gitignore):

{
  "version": 1,
  "worktrees": [
    {
      "id": "ci-sweeper-2026-07-07-01",
      "path": ".loop-worktrees/ci-sweeper-2026-07-07-01",
      "branch": "loop/ci-sweeper-2026-07-07-01",
      "baseBranch": "main",
      "pattern": "ci-sweeper",
      "createdAt": "2026-07-07T08:00:00.000Z",
      "status": "active"
    }
  ]
}

Locks Copy Chapter

.loop-worktrees/locks/<owner>.json, one file per owner (also add
.loop-worktrees/ to .gitignore -- it already covers this):

{
  "owner": "dependency-sweeper",
  "paths": ["package.json", "package-lock.json"],
  "lockedAt": "2026-07-14T08:00:00.000Z",
  "expiresAt": "2026-07-14T14:00:00.000Z"
}

expiresAt is absent when no --ttl was given.

See docs/primitives.md for where worktrees fit in the Five Building Blocks + Memory model.

Overview (`tools/loop/README.md`) Copy Section

@cobusgreyling/loop

Unified front door for Loop Engineering CLIs.

npx @cobusgreyling/loop init . --pattern daily-triage --tool claude
npx @cobusgreyling/loop doctor .

This package does not replace loop-init, loop-audit, or the other tools. It wraps them and adds doctor + status so week-one activation is one mental model.

Week-one path Copy Chapter

# 1. Scaffold (report-only)
npx @cobusgreyling/loop init . --pattern daily-triage --tool claude

# 2. One health check
npx @cobusgreyling/loop doctor .

# 3. Optional cost estimate
npx @cobusgreyling/loop cost -p daily-triage -l L1 -c 1d

# 4. Day-2 dashboard
npx @cobusgreyling/loop status .

Doctor exit codes Copy Section

npx @cobusgreyling/loop doctor . --json
npx @cobusgreyling/loop status . --json

Compatibility (old doors stay open) Copy Chapter

These continue to work forever (or until a future major with long deprecation):

npx @cobusgreyling/loop-init .
npx @cobusgreyling/loop-audit . --suggest
npx @cobusgreyling/loop-cost --pattern daily-triage
npx @cobusgreyling/loop-sync .

loop <cmd> is the same binary behavior for pass-through commands.

Monorepo develop Copy Chapter

# Build sibling tools first (audit + sync used by doctor)
(cd ../readiness-core && npm ci && npm run build)
(cd ../loop-audit && npm ci && npm run build)
(cd ../loop-sync && npm ci && npm run build)
(cd ../loop-init && npm ci && npm run build)

cd ../loop
npm ci
npm test
node dist/cli.js doctor ../..
node dist/cli.js status ../..

Agent skill Copy Chapter

See skills/install-loop in the monorepo — a short skill agents can follow to install and doctor a project.

License Copy Chapter

MIT

Overview (`tools/mcp-server/README.md`) Copy Section

@cobusgreyling/loop-mcp-server

MCP (Model Context Protocol) server for loop-engineering — exposes patterns, skills, state, budget, and audit tools as runtime-queryable resources for AI agents.

Instead of stuffing all loop documentation into the prompt, agents can query only what they need on-demand via MCP.

Quick Start Copy Chapter

npx @cobusgreyling/loop-mcp-server

From a cloned loop-engineering repo:

cd tools/mcp-server && npm ci && npm test
node dist/index.js

Set LOOP_PROJECT_ROOT to your target project (defaults to cwd).

Configure in Claude Code / Grok / any MCP client Copy Section

Add to your MCP config (.mcp.json or equivalent):

{
  "mcpServers": {
    "loop-engineering": {
      "command": "npx",
      "args": ["-y", "@cobusgreyling/loop-mcp-server"],
      "env": {
        "LOOP_PROJECT_ROOT": "."
      }
    }
  }
}

Resources Copy Chapter

Tools Copy Chapter

Environment Copy Chapter

Development Copy Chapter

cd tools/mcp-server
npm install
npm run build
npm test

Architecture Copy Chapter

Agent (Claude Code / Grok / Codex)
  │
  ├─ MCP Resource Read ──→ loop://patterns/daily-triage
  ├─ MCP Tool Call ──→ loop_recommend_pattern("watch CI failures")
  └─ MCP Tool Call ──→ loop_estimate_cost("ci-sweeper", "L2")
  │
  ▼
loop-mcp-server (stdio transport)
  │
  ├─ resolver.ts ──→ reads patterns/, skills/, STATE.md, LOOP.md, etc.
  └─ index.ts ──→ MCP protocol handlers

The server reads from the local filesystem at LOOP_PROJECT_ROOT. It is read-only — it never writes to the project.

See Also Copy Chapter

• Loop Engineering Patterns
• MCP Examples
• Primitives: Plugins & Connectors
• Safety: MCP Least Privilege

Overview (`tools/readiness-core/README.md`) Copy Section

@cobusgreyling/readiness-core

Core types and utilities for loop-audit and goal-audit.

Usage Copy Chapter

This package is intended for internal use within the loop-engineering monorepo. It exports shared types like BaseAuditResult, Finding, and core heuristics for auditing file existence and skill directories.

QUICKSTART (`docs/QUICKSTART.md`) Copy Section

Quickstart — 5 minutes to your first loop

Stop prompting. Design the loop. Get a score.

Watch the score climb: loop-audit-demo.gif (10 → 70 → 100 in ~15s).

Landed from X, the showcase, or a friend's README? This is the shortest path from zero to a running loop.

Week one rule: report only. No auto-fix, no auto-merge. Read what the loop writes before you let it act.

Front door: prefer the unified CLI (@cobusgreyling/loop). Dedicated packages (loop-init, loop-audit, …) stay fully supported — see cli-front-door.md.

1. Pick your pain (30 seconds) Copy Chapter

Have a feature or refactor to finish, not a maintenance cadence? That is a different job — see jobs.md and the refactor / change path. Do not point daily-triage at a whole-repo rewrite.

Not sure which loop? Use the interactive pattern picker on the showcase — it recommends a pattern, scaffold command, first /loop line, and a token estimate.

Or start with Daily Triage if you just want to learn loop discipline with low risk.

2. Scaffold in your repo (60 seconds) Copy Chapter

Run this in the root of any git project (no clone required):

npx @cobusgreyling/loop init . --pattern daily-triage --tool claude
# One health check (audit + sync + top 3 actions):
npx @cobusgreyling/loop doctor .
# Optional one-command funnel into harness-foundry:
npx @cobusgreyling/loop init . --pattern daily-triage --tool claude --with-foundry

Equivalent (old door, still supported):

npx @cobusgreyling/loop-init . --pattern daily-triage --tool claude

Swap --pattern for any pattern from patterns/registry.yaml. List all patterns:

npx @cobusgreyling/loop init --help

Which `--tool` values work? Copy Section

loop-init copies the starter kit, creates STATE.md, LOOP.md, loop-budget.md, and loop-run-log.md, then prints your Loop Ready score and first command.

3. Check cost before you schedule (30 seconds) Copy Chapter

npx @cobusgreyling/loop cost --pattern daily-triage --level L1 --cadence 1d
# same as: npx @cobusgreyling/loop-cost --pattern daily-triage --level L1 --cadence 1d

Adjust --pattern, --level (L1 → L2 → L3), and --cadence to match what you plan to run. High-frequency loops (CI Sweeper at 5m) can burn tokens fast — slow the cadence or require early-exit triage first.

Circuit breaker for L2+ loops (optional) Copy Section

When a loop starts fixing code unattended, wire a circuit breaker so it escalates instead of retrying the same failure forever. loop-init scaffolds loop-ledger.json and a loop-guard skill for fix-capable patterns; check the ledger before each retry:

npx @cobusgreyling/loop context --check --ledger loop-ledger.json
# same as: npx @cobusgreyling/loop-context --check --ledger loop-ledger.json

Exit 0 = continue · 2 = escalate to a human. The breaker trips on max iterations, the same error repeating N× in a row, too many consecutive failures, or a token budget cap. Full API: tools/loop-context/README.md.

Token budget negotiation (`budget-negotiator`)

When an L3 autonomous loop reaches ≥90% of its daily token cap in loop-budget.md with critical High Priority items remaining, it can use the budget-negotiator skill to request an extension instead of an abrupt hard stop.

• Negotiation vs Hard Exit: Standard loop-budget exits immediately when over cap. budget-negotiator calculates current ROI, drafts a structured budget bump request (+20% or max +50k tokens, once per day), and appends it to STATE.md under [BUDGET NEGOTIATION].
• Human Gate Safety: Agents are strictly forbidden from self-raising token caps in loop-budget.md. A human maintainer must explicitly approve the request by editing loop-budget.md before the loop can resume.

4. Audit readiness (30 seconds) Copy Chapter

# Prefer doctor for day-to-day (includes audit + sync)
npx @cobusgreyling/loop doctor .
# Or audit alone:
npx @cobusgreyling/loop audit . --suggest

Scores 0–100 with concrete next steps. Re-run after each improvement. Paste a badge when you're proud of the score:

npx @cobusgreyling/loop badge .

When the score is ≥ 80, audit (and loop init) nudge you to version the loop as a harness-foundry stack — declarative runtime, traces, outerloop emit:

npx @cobusgreyling/loop init . --with-foundry
npx @cobusgreyling/harness-foundry validate
npx @cobusgreyling/harness-foundry run --goal "Verify harness wiring"

To configure provider-specific stacks like MiniMax during scaffolding:

npx @cobusgreyling/loop init . --pattern daily-triage --tool claude \
  --with-foundry --model-provider minimax --region global_en --model MiniMax-M3

MiniMax Foundry flags:

• --model-provider minimax
• --region: global_en (default) | cn_zh
• --model: e.g. MiniMax-M3

See harness-foundry for full provider and stack runtime documentation.

Catch drift before you schedule (`loop sync`) Copy Section

loop audit scores readiness; loop sync checks that your STATE.md and LOOP.md still agree. When they drift — you edit LOOP.md to add a loop but never wire it into STATE.md, or a starter update leaves one file behind — a scheduled loop can run against stale instructions. loop doctor runs this for you.

npx @cobusgreyling/loop sync .
# same as: npx @cobusgreyling/loop-sync .

Sample output on a fresh daily-triage scaffold:

Loop Sync Report
══════════════════════════════════════════════════
Score: 80/100 (healthy)

Found 2 issue(s):

⚠️ Warnings:
   - LOOP.md: LOOP.md does not reference STATE.md
   - STATE.md ↔ LOOP.md: Low structural similarity between STATE.md and LOOP.md

💡 Suggestions:
   - Review STATE.md and LOOP.md for consistency

Read it top-down: the score (70+ healthy, 40–69 warning, below 40 needs attention) is the headline, then each warning names the two files that disagree and how. Here, LOOP.md describes loops that never point back at STATE.md — expected right after scaffolding, worth fixing once you customize either file.

When to run it: after editing LOOP.md, and again before you schedule an L2 loop — so an unattended run never fires on stale state. Full checks, options, and score bands: tools/loop-sync/README.md.

Optional: MCP runtime lookup Copy Section

Agents can query patterns, skills, and state on demand instead of stuffing docs into every prompt. Copy the config stub from examples/mcp/loop-engineering.mcp.json into your MCP client settings.

Run the server from npm (no clone required):

LOOP_PROJECT_ROOT=. npx @cobusgreyling/loop-mcp-server

Or from a cloned loop-engineering repo for local development:

cd path/to/loop-engineering/tools/mcp-server && npm ci && npm run build
LOOP_PROJECT_ROOT=/path/to/your/project node dist/index.js

See tools/mcp-server/README.md for resources and tools.

4b. Set the merge gate (30 seconds) Copy Chapter

Before any loop can auto-merge, it needs a gate.yaml defining what's off-limits and what's safe to merge unattended. Copy the starter from templates/gate.yaml.template into your repo root as gate.yaml:

version: 1
denylist:
  - "src/auth/**"
  - "**/*.env"
autoMergeAllowlist:
  - "docs/**"
  - "**/*.md"

This is not a free-form list of gates — denylist and autoMergeAllowlist are fixed keys loop-gate checks against (there's also an optional maxFiles cap — see the full template for details).

Enforce it mechanically before any auto-merge action:

npx @cobusgreyling/loop gate check --action auto-merge --paths <f1,f2,...>
# same as: npx @cobusgreyling/loop-gate check --action auto-merge --paths <f1,f2,...>

Exit 0 = allowed · 2 = escalate to a human. Already running loop-audit --auto-fix? It emits a loadable gate.yaml for you automatically — no need to hand-write one.

See tools/loop-gate/README.md for the full policy schema and docs/safety.md for the risk/mitigation model this gate enforces.

5. Run your first loop — report only (2 minutes) Copy Chapter

Grok Copy Section

/loop 1d Run loop-triage. Update STATE.md. No auto-fix in week one.

Claude Code Copy Section

/loop 1d Run $loop-triage. Read STATE.md. Merge findings into High Priority and Watch List. Update Last run. Do not edit code.

Codex Copy Section

Use the first-run command printed by loop-init (pattern-specific). Week one: triage and state updates only.

OpenClaw Copy Section

No loop-init --tool openclaw yet — copy skills/loop-triage/SKILL.md and STATE.md, then create an isolated cron job. See examples/openclaw/daily-triage.md.

Opencode Copy Section

npx @cobusgreyling/loop-init . --pattern daily-triage --tool opencode

Then schedule with cron or systemd — each tick runs headless via opencode run:

opencode run "Run loop-triage. Read STATE.md first. Update High Priority and Watch List. No auto-fix in week one." --agent loop-triage

See examples/opencode/daily-triage.md for worktree + verifier patterns (L2+).

Hermes Copy Section

No loop-init --tool hermes yet — install the loop-triage skill manually and schedule via hermes cron. See examples/hermes/daily-triage.md for setup, channel delivery, and the full command reference.

Week one: use --deliver local so routine triage output stays out of your chat history until you trust it.

Cursor Copy Section

No loop-init --tool cursor yet — copy skills and state from any starter, then map scheduling to editor Automations. See examples/cursor/daily-triage.md.

Windsurf Copy Section

No loop-init --tool windsurf yet — copy skills and state from any starter, then map scheduling to a Cascade Workflow. See examples/windsurf/daily-triage.md.

GitHub Actions only Copy Section

Workflow examples under examples/github-actions/ are schema-complete; you wire the agent invocation (Codex API, repository_dispatch, etc.). Start with report-only outputs to a state file or issue comment.

GitHub Actions composite action (`loop-action`) Copy Section

For CI/CD workflows, use the official GitHub Composite Action tools/loop-action to automatically run readiness audits (loop-audit), enforce circuit breakers (loop-context), and isolate execution in worktrees (loop-sandbox):

- uses: cobusgreyling/loop-engineering/tools/loop-action@main
  with:
    pattern: 'ci-sweeper'
    level: 'L1'            # L1 (report-only) -> L2 -> L3
    sandbox: 'false'       # set 'true' for ephemeral worktree isolation (L2)
    command: |
      npx grok-cli run --skill .grok/skills/ci-sweeper/SKILL.md

Week-one rule: report-only mode (level: 'L1'). No auto-fix, no auto-merge. Review generated state output before enabling actions.

Note on command: Unquoted multi-arg command strings can be fragile when parsed by shell runners. Prefer multi-line command: | blocks or a single script path (e.g. scripts/run-agent.sh).

See tools/loop-action/README.md and docs/safety.md for action inputs, security guardrails, and permission boundaries.

6. Read the output, commit state (1 minute) Copy Chapter

Open STATE.md. Did the loop capture real priorities? Edit anything wrong — you're still the engineer.

Commit the scaffold + first run update so loop-audit sees activity on the next audit.

What next? Copy Chapter

L2: isolated fix attempts (`loop-worktree`) Copy Section

PR Babysitter and CI Sweeper need one git worktree per fix attempt so retries don't collide on the same branch. loop-worktree tracks them in a manifest and sweeps rejected attempts.

# Create an isolated worktree for one fix attempt
npx @cobusgreyling/loop-worktree create --run-id pr-217-fix-1 --pattern pr-babysitter

# Run your fix in the worktree path printed by create, then verifier...

# Verifier rejected — mark for cleanup (audit trail only)
npx @cobusgreyling/loop-worktree mark --run-id pr-217-fix-1 --status rejected

# Sweep rejected/escalated worktrees older than 24h
npx @cobusgreyling/loop-worktree cleanup --older-than 24h

# List active worktrees
npx @cobusgreyling/loop-worktree list

To prevent multi-loop collisions on shared paths across concurrent runs, use advisory path locks via CLI or public JS import:

# CLI advisory lock (skips or queues if another owner holds an overlapping path)
npx @cobusgreyling/loop-worktree lock --paths package.json,package-lock.json --owner dependency-sweeper --ttl 6h
npx @cobusgreyling/loop-worktree unlock --owner dependency-sweeper

Programmatic loops can import lock primitives directly from @cobusgreyling/loop-worktree/lock without deep-importing internal files under dist/:

import { lockPaths, unlockOwner, LOCKS_DIR } from '@cobusgreyling/loop-worktree/lock';

await lockPaths({ root, owner, paths, ttl: '6h' });
await unlockOwner(root, owner);

Pair with the circuit breaker above: when loop-context --check exits 2, mark the worktree escalated before handing off to a human. The two tools stay independent — see tools/loop-worktree/README.md.

Ephemeral worktree isolation (`loop-sandbox`) Copy Section

To run an agent command in a temporary, isolated git worktree and capture its changes as a reviewable .patch file without touching your working tree, use loop-sandbox (tools/loop-sandbox/README.md). It automatically spawns a clean worktree from HEAD, executes your process, captures all edits (including untracked files) into a .patch file, and destroys the worktree so your repo stays pristine.

# Run an agent command in an ephemeral sandbox
npx @cobusgreyling/loop-sandbox run -- npx my-agent

# Optional --shell to run raw shell commands (e.g. bash -c)
npx @cobusgreyling/loop-sandbox run --shell -- bash -c "echo 'fix' > file.txt"

# List and review generated patches before applying
npx @cobusgreyling/loop-sandbox review
git apply .loop-sandbox/patches/<patch-id>.patch

Windows compatibility: On Windows, npm .cmd shims (npx, tsc, etc.) that fail with ENOENT are automatically retried through a shell, so you do not need to pass --shell just for npx.

Safety note: loop-sandbox provides worktree isolation, but process execution retains OS-level filesystem and network access — see docs/safety.md. Always inspect patch files before running git apply.

Multi-agent consensus sandboxing (`loop-swarm`) Copy Section

For high-confidence L3 operations, loop-swarm (tools/loop-swarm/README.md) runs an agent command multiple times sequentially across N (default: 3) isolated loop-sandbox worktrees. It hashes the resulting .patch files and verifies that a majority produced byte-identical changes before writing a consensus patch to .loop-sandbox/patches/consensus.patch.

If an agent produces non-deterministic edits, loop-swarm acts as a consensus safety net by accepting only changes independently reproduced across runs.

# Run multi-agent consensus across 3 sequential sandboxes
npx @cobusgreyling/loop-swarm run --count 3 -- <agent-cmd>

Limitations & Safety: Runs are serialized sequentially to maintain safety guarantees on the manifest (~N× longer execution), shared stdio, and SIGINT signals exit the entire process. loop-swarm provides git worktree isolation rather than OS-level container isolation — see docs/safety.md.

Windows / CRLF notes Copy Section

Windows contributors and loop operators should keep line-ending and process invocation differences in mind:

• Git line endings: Recommended repository config is git config core.autocrlf input (or false with LF line endings) so checkouts and commits maintain clean LF line breaks across platforms.
• loop-sync frontmatter: YAML frontmatter extraction in STATE.md and LOOP.md supports both LF and CRLF line endings (#476).
• loop-sandbox shims: Windows .cmd executable shims (npx, tsc, etc.) that fail with ENOENT are automatically retried via shell execution, so manual --shell is rarely needed (tools/loop-sandbox/README.md).

Troubleshooting

• If loop-sync reports drift unexpectedly on Windows: Check for CRLF line breaks in STATE.md / LOOP.md. loop-sync strips carriage returns, but converting files to LF (git config core.autocrlf input) ensures multi-line matches match cleanly.
• If loop-sandbox fails with ENOENT spawning commands: Ensure command binaries are in your PATH, or explicitly pass --shell if calling custom .bat/.cmd scripts.

Copy-paste cheat sheet Copy Chapter

# Scaffold — --tool accepts: grok | claude | codex | opencode
# (cursor, windsurf, openclaw: manual copy — see table in section 2)
npx @cobusgreyling/loop-init . --pattern daily-triage --tool claude

# List patterns and flags
npx @cobusgreyling/loop-init --help

# Cost check
npx @cobusgreyling/loop-cost --pattern daily-triage --level L1 --cadence 1d

# Audit + suggestions
npx @cobusgreyling/loop-audit . --suggest

# Optional badge for your README
npx @cobusgreyling/loop-audit . --badge

# Check STATE.md ↔ LOOP.md drift (run after editing LOOP.md, before scheduling L2)
npx @cobusgreyling/loop-sync .

# Optional MCP runtime lookup (patterns, skills, state on demand)
LOOP_PROJECT_ROOT=. npx @cobusgreyling/loop-mcp-server

# L2: isolated worktree per fix attempt (PR Babysitter, CI Sweeper)
npx @cobusgreyling/loop-worktree create --run-id <id> --pattern <pattern>
npx @cobusgreyling/loop-worktree mark --run-id <id> --status rejected
npx @cobusgreyling/loop-worktree cleanup --older-than 24h

# Ephemeral worktree isolation + patch capture
npx @cobusgreyling/loop-sandbox run -- <command>
npx @cobusgreyling/loop-sandbox review

# Multi-agent consensus sandboxing across sequential sandboxes
npx @cobusgreyling/loop-swarm run --count 3 -- <agent-cmd>

Learn the why (optional, 10 minutes) Copy Chapter

• Loop Engineering essay — concept and primitives
• Primitives matrix — Grok vs Claude vs Codex vs OpenClaw vs Opencode vs Cursor
• Operating loops — when to kill a loop

Questions? GitHub Discussions · Share your setup via Add Adopter

GITHUB PAGES (`docs/GITHUB_PAGES.md`) Copy Section

Enable GitHub Pages

1. Repo Settings → Pages
2. Source: Deploy from branch main
3. Folder: /docs
4. Save — showcase at https://cobusgreyling.github.io/loop-engineering/

The homepage (docs/index.html) is the full interactive showcase with patterns, primitives, quick-start, and an anatomy diagram.

The root README.md and LOOP.md describe how this reference dogfoods its own patterns via .github/workflows/audit.yml + validate-patterns.yml.

First deploy may take 1–2 minutes. After enabling, the daily scheduled audit workflow keeps the published site aligned with the reference's loop readiness score.

Pro tip: run node tools/loop-audit/dist/cli.js . --suggest locally and improve the score over time — the workflows will reflect it.

RELEASE (`docs/RELEASE.md`) Copy Section

Release playbook — npm packages

This repo ships public npm packages from tools/. Front door for users: @cobusgreyling/loop (cli-front-door.md). Sibling packages stay published and supported.

One-time setup (trusted publishing — recommended) Copy Chapter

Link npm to GitHub, then for each package on npmjs.com → package Settings → Trusted Publisher → GitHub Actions:

Names must match exactly (case-sensitive). No NPM_TOKEN secret is required when trusted publishing is configured.

Auth: release workflows use repo secret NPM_TOKEN (Automation token). Refresh it at npmjs.com → Access Tokens if publishes fail with E401/E404.

Retry without re-tagging: Actions → Release workflow → Run workflow → enter the tag (e.g. loop-audit-v1.6.0).

Trusted publishing (optional): configure per package on npm; OIDC alone is not sufficient unless NPM_TOKEN is removed and trusted publishers are verified.

Version bump Copy Chapter

Edit version in the package package.json, update that package's CHANGELOG.md if present, and commit to main via PR.

Publish Copy Chapter

Tag pushes trigger the release workflows:

# readiness-core (MUST be published before loop-audit and goal-audit)
git tag readiness-core-v1.0.0
git push origin readiness-core-v1.0.0

# loop (unified front door — pass-through + doctor/status)
git tag loop-v0.1.0
git push origin loop-v0.1.0

# loop-audit (runs tests before publish)
git tag loop-audit-v1.6.0
git push origin loop-audit-v1.6.0

# loop-init (bundles starters/templates, runs smoke tests)
git tag loop-init-v1.3.3
git push origin loop-init-v1.3.3

# loop-cost (bundles patterns/registry.yaml)
git tag loop-cost-v1.0.3
git push origin loop-cost-v1.0.3

# loop-sync (drift detection between STATE.md and LOOP.md)
git tag loop-sync-v1.0.0
git push origin loop-sync-v1.0.0

# loop-context (stateful memory manager + circuit breaker)
git tag loop-context-v1.0.0
git push origin loop-context-v1.0.0

# loop-mcp-server (MCP runtime lookup for patterns, skills, state)
git tag loop-mcp-server-v1.0.0
git push origin loop-mcp-server-v1.0.0

# loop-worktree (isolated git worktrees per fix attempt)
git tag loop-worktree-v1.0.0
git push origin loop-worktree-v1.0.0

# loop-gate (path denylist + auto-merge allowlist)
git tag loop-gate-v1.0.0
git push origin loop-gate-v1.0.0

# goal-audit (Goal Engineering readiness scorer — companion repo)
git tag goal-audit-v1.0.2
git push origin goal-audit-v1.0.2

# goal-init (scaffold goal engineering setups)
git tag goal-init-v1.0.0
git push origin goal-init-v1.0.0

Workflows: .github/workflows/release-loop.yml, .github/workflows/release-readiness-core.yml, .github/workflows/release-loop-audit.yml, .github/workflows/release-loop-init.yml, .github/workflows/release-loop-cost.yml, .github/workflows/release-loop-sync.yml, .github/workflows/release-loop-context.yml, .github/workflows/release-loop-mcp-server.yml, .github/workflows/release-loop-worktree.yml, .github/workflows/release-loop-gate.yml, .github/workflows/release-goal-audit.yml, .github/workflows/release-goal-init.yml.

Verify after publish Copy Chapter

npx @cobusgreyling/loop-audit --help
npx @cobusgreyling/loop-init --help
npx @cobusgreyling/loop-cost --help
npx @cobusgreyling/loop-sync --help
npx @cobusgreyling/loop-context --help
npx @cobusgreyling/loop-mcp-server --help
npx @cobusgreyling/loop-worktree --help
npx @cobusgreyling/goal-audit --help

mkdir /tmp/loop-init-test && cd /tmp/loop-init-test
npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok --dry-run

Changelog & release notes (no root `CHANGELOG.md`) Copy Chapter

This repo does not maintain a root CHANGELOG.md. Use:

After publish: trim RELEASE_NOTES_DRAFT.md to a short “since last discussion” stub for the next drafter run.

Before npm is live (local / monorepo) Copy Chapter

cd tools/loop-audit && npm ci && npm test && node dist/cli.js ../.. --suggest
cd tools/loop-init && npm ci && npm test && node dist/cli.js /tmp/target --pattern daily-triage --dry-run

Config.Yml (`docs/_config.yml`) Copy Section

title: Loop Engineering
theme: jekyll-theme-minimal
baseurl: "/loop-engineering"
url: "https://cobusgreyling.github.io"

markdown: GFM

exclude:

• ../node_modules
• ../tools

Adopters (`docs/adopters.md`) Copy Section

Adopters & community setups

Forks and stars mean people are trying this in their own stacks. If you run a loop from this repo (or adapted from it), add yourself here via PR.

Pinned: Add your project — Loop Ready badge + adopters list (Discussions)

Loop Ready badge Copy Chapter

Show your readiness level in your README:

npx @cobusgreyling/loop-audit . --badge

Paste the markdown output into your README. Re-run after you graduate L1 → L2 → L3.

How to list your project Copy Chapter

Fast path: open the Add Adopter issue — we'll add your row.

Or open a PR that adds a row to the table below:

Adopters Copy Chapter

Your project here — see CONTRIBUTING.md.

Show & tell Copy Chapter

Prefer chat over a PR? Post in GitHub Discussions → Show and tell with:

1. Which pattern you picked and why
2. Your first /loop or scheduler command
3. One surprise (good or bad)

Failure reports are first-class — see stories/.

Anti Patterns (`docs/anti-patterns.md`) Copy Section

Anti-Patterns

Design mistakes to avoid before enabling unattended loops. For runtime incidents, see failure-modes.md.

1. Same agent implements and verifies Copy Chapter

Anti-pattern: One session marks its own work "done" after running tests once.

Why it fails: Confirmation bias; weak tests get rubber-stamped.

Do instead: Separate verifier sub-agent, model, or /goal checker. Verifier default stance: REJECT.

2. No attempt cap Copy Chapter

Anti-pattern: "Keep trying until CI is green."

Why it fails: Infinite fix loops, token burn, merge of wrong fixes.

Do instead: Hard cap (e.g. 3 attempts) → escalate with full context in state file.

3. Vague triage output Copy Chapter

Anti-pattern: Triage skill returns paragraphs of narrative.

Why it fails: Loop cannot parse priorities; humans ignore STATE.md.

Do instead: Structured markdown sections with one-line items and explicit Suggested loop action.

4. L3 before L1 quality Copy Chapter

Anti-pattern: Auto-fix and auto-PR on day one.

Why it fails: Loop acts on bad signal; comprehension debt explodes.

Do instead: L1 report-only week one. Measure triage accuracy before enabling L2.

5. Shared state without schema Copy Chapter

Anti-pattern: Three loops append to one unstructured STATE.md.

Why it fails: State rot, conflicting actions, ghost items.

Do instead: One state file per pattern, or clearly separated sections with prune rules.

6. MCP with write-everything scope Copy Chapter

Anti-pattern: Loop can merge PRs, post to Slack, and edit production tickets on day one.

Why it fails: Blast radius of a bad triage decision is huge.

Do instead: L1 read-only connectors. Expand scope only after trust is earned.

7. No kill switch Copy Chapter

Anti-pattern: Loop runs 24/7 with no pause criteria.

Why it fails: Alert fatigue, budget overrun, weekend incidents.

Do instead: Document pause/kill in LOOP.md + templates/loop-budget.md.template.

8. Fixing flakes with code Copy Chapter

Anti-pattern: CI Sweeper changes application code when classification is flake.

Why it fails: Masks infra problems; introduces random diffs.

Do instead: Classify → quarantine or retry policy → escalate env/infra failures.

9. Auto-merge without allowlist Copy Chapter

Anti-pattern: "Verifier passed, merge it."

Why it fails: Security and business-logic bugs pass weak verifiers.

Do instead: Explicit path allowlist; human merge for denylist paths per safety.md.

10. No run log Copy Chapter

Anti-pattern: Only STATE.md, no history of what the loop did.

Why it fails: Cannot debug "why did it do that Tuesday?"

Do instead: Append to loop-run-log.md per operating-loops.md.

Architecture Diagrams (`docs/architecture-diagrams.md`) Copy Section

Architecture Diagrams

Deeper, more detailed companions to the Anatomy of a Loop diagram in the README. Where that one shows the linear shape of a single loop, these show: the actor-level sequence within one run, the states a run moves through, how the three autonomy levels relate, and how the actual tools in tools/ map onto the Five Building Blocks + Memory model.

All diagrams are Mermaid, rendered natively by GitHub when viewing this file.

One loop cycle (sequence) Copy Chapter

Who talks to whom, in order, within a single run — including the fork between the safe auto-path and the human escalation path.

sequenceDiagram
    actor Eng as Engineer
    participant Sched as Scheduler
    participant Skill as Triage Skill
    participant State as STATE.md / Memory
    participant WT as Worktree
    participant Maker as Implementer Agent
    participant Check as Verifier Agent
    participant MCP as MCP / Git / Tickets
    participant Gate as Human Gate

    Sched->>Skill: Fire pattern (e.g. daily-triage)
    Skill->>State: Read goals + last run + budget
    State-->>Skill: Context snapshot
    Skill->>WT: Create isolated worktree
    WT-->>Skill: worktree path
    Skill->>Maker: Task with skills + constraints
    Maker->>Maker: Implement change in worktree
    Maker->>Check: Hand off patch
    Check->>Check: Run tests + policy gates

    alt Verify pass and budget OK
        Check->>MCP: Open PR or update ticket
        MCP-->>Gate: PR link + summary
        Gate->>Gate: Safe and allowlisted?
        alt Safe auto-path
            Gate->>MCP: Approve merge or leave L1 report
            MCP->>State: Write run outcome
        else Risky or ambiguous
            Gate->>Eng: Escalate with full context
            Eng->>MCP: Decide / override
            MCP->>State: Write decision + outcome
        end
    else Verify fail or budget exceeded
        Check->>State: Log failure mode
        Check->>Eng: Report only, no auto-merge
    end

Run lifecycle (state) Copy Chapter

The states one scheduled run moves through, from cadence fire to the final durable log entry.

stateDiagram-v2
    [*] --> Scheduled
    Scheduled --> LoadingContext: cadence fire
    LoadingContext --> BlockedBudget: budget exceeded
    LoadingContext --> RunningTriage: context OK
    RunningTriage --> WorkingInWorktree: task selected
    RunningTriage --> IdleNoop: nothing to do
    WorkingInWorktree --> Verifying: implementer done
    Verifying --> AwaitingHumanGate: verify pass + risky
    Verifying --> Failed: verify fail
    AwaitingHumanGate --> Applied: human or allowlist approve
    AwaitingHumanGate --> Rejected: human reject
    Applied --> Logged
    Failed --> Logged
    Rejected --> Logged
    BlockedBudget --> Logged
    IdleNoop --> Logged
    Logged --> [*]

Autonomy levels L1-L3 Copy Chapter

How a pattern moves between report-only, assisted, and unattended operation — see primitives-matrix.md for the readiness criteria behind each transition.

stateDiagram-v2
    [*] --> L1_ReportOnly
    L1_ReportOnly --> L2_Assisted: audit score up + human OK
    L2_Assisted --> L3_Unattended: denylist + budget + gates proven
    L3_Unattended --> L2_Assisted: incident or cost spike
    L2_Assisted --> L1_ReportOnly: kill switch
    L3_Unattended --> L1_ReportOnly: kill switch

Stack: primitives + tools Copy Chapter

The Five Building Blocks + Memory model made concrete: which package in tools/ implements which primitive, and how they connect.

flowchart TB
    subgraph Human["Engineer / Owner"]
        Design[Design LOOP.md patterns]
        Gate[Human gate + kill switch]
        Review[Read PRs + reports]
    end

    subgraph Control["Control plane"]
        Sched[Automations / Scheduling]
        Patterns[patterns/registry.yaml]
        Cost[loop-cost: estimate spend]
    end

    subgraph Memory["Durable memory"]
        State[STATE.md]
        LoopDoc[LOOP.md]
        Context[loop-context: prune, inject, circuit breaker]
        Sync[loop-sync]
    end

    subgraph Execution["Execution plane"]
        WT[loop-worktree: isolated attempts + locks]
        Maker[Implementer sub-agent]
        Verifier[Verifier sub-agent]
    end

    subgraph Tooling["CLIs + connectors"]
        Init[loop-init: scaffold]
        Audit[loop-audit: readiness score]
        MCP[MCP server: read-only policy + tools]
    end

    Design --> Patterns
    Init --> State
    Init --> LoopDoc
    Sched --> Patterns
    Patterns --> Cost
    Cost --> Context
    Patterns --> WT
    State <--> Sync
    WT --> Maker
    Maker --> Verifier
    Verifier --> Context
    Context --> Gate
    Verifier --> MCP
    Gate --> Review
    Audit --> Design

Area Owners (`docs/area-owners.md`) Copy Section

Area owners

Optional community ownership for review routing. Owner still ships main and releases; area owners help triage and review scoped PRs faster.

What area owners do Copy Chapter

1. Triage issues labeled docs, story, or good first issue that touch their paths
2. Review PRs that only change those paths (approve, request changes, or ping maintainer)
3. Unstick stale “I'll take this” claims after ~14 days with no PR (comment + free the issue)
4. Escalate anything that changes scoring, safety, npm publish, or CI to the maintainer

What they do *not* need to do Copy Chapter

• Merge to main alone if branch rules require maintainer approval
• Own npm releases or security advisories (SECURITY.md)
• Review tools/ CLI changes unless they ask

Becoming an area owner Copy Chapter

Multi-PR track record in the area + public invite from the maintainer. Start with CONTRIBUTING.md and the contributor quickstart.

CODEOWNERS (../CODEOWNERS) lists the maintainer only. Area owners are invited on the PR when their review is useful; putting them in CODEOWNERS auto-requests a review on every docs/examples PR and leaves fork PRs BLOCKED after the maintainer has already approved.

Cli Front Door (`docs/cli-front-door.md`) Copy Section

CLI front door — `@cobusgreyling/loop`

Additive. Old packages stay fully supported. This is the recommended entry for new users, forks, and agents.

Why Copy Chapter

Loop Engineering ships several focused CLIs (loop-init, loop-audit, loop-cost, …). That is great for maintainers; it is hard for first-time adopters to remember.

@cobusgreyling/loop is a thin umbrella:

1. One binary people can remember
2. Pass-through to existing tools (same flags)
3. doctor / status for activation and day-2 habit

npx @cobusgreyling/loop init . -p daily-triage -t claude
npx @cobusgreyling/loop doctor .

Map (new → same as before) Copy Chapter

loop init with --with-foundry supports custom provider flags such as --model-provider minimax --region (global_en|cn_zh) --model MiniMax-M3. See QUICKSTART for examples.

Doctor exit codes Copy Chapter

npx @cobusgreyling/loop doctor . --json

Forks & contributors Copy Chapter

• Forks that already call loop-init / loop-audit: change nothing.
• New docs / skills / Actions: prefer loop.
• Contributors adding tools: keep a dedicated package; add a one-line pass-through in tools/loop if it should be discoverable.

Agent skill Copy Chapter

skills/install-loop/SKILL.md — copy into .grok/skills, .claude/skills, etc., or point agents at this path.

Publish Copy Chapter

git tag loop-v0.1.0
git push origin loop-v0.1.0

Workflow: .github/workflows/release-loop.yml. See RELEASE.md.

Version policy Copy Chapter

• 0.x while the umbrella settles; pass-through tracks whatever sibling versions are installed via monorepo dist or npx.
• No deprecation of sibling packages in this phase.

Concepts (`docs/concepts.md`) Copy Section

Concepts & Vocabulary

Loop engineering sits in a family of ideas about agentic software development. This glossary links them so you can design loops with the right mental model.

Loop Engineering Copy Chapter

Replacing yourself as the prompter. You design a system that discovers work, assigns it, verifies results, and persists state — instead of typing the next prompt yourself.

A loop is a recursive goal: define purpose, let the agent iterate (with sub-agents and external memory) until done or until the loop escalates to a human.

Related Concepts (Addy Osmani) Copy Chapter

Agent Harness Engineering Copy Section

The environment one agent runs in: tools, context, permissions, rules. The harness is the sandbox; the loop is what schedules and orchestrates harness runs over time.

Harness = single session setup
Loop    = harness + schedule + state + verification chain

The Factory Model Copy Section

The system that builds the software: pipelines, agents, checks, and handoffs. Loop engineering is how you operate the factory floor — not manually assembling each unit.

Intent Debt Copy Section

Every session, the agent starts cold. Missing intent gets filled with confident guesses. Skills are how you pay down intent debt — conventions, build steps, and "we don't do it this way" written once, read every run.

Comprehension Debt Copy Section

The gap between what exists in the repo and what you actually understand. Faster loops ship more code you didn't write — comprehension debt grows unless you read what the loop made.

Cognitive Surrender Copy Section

The trap of letting the loop run while you stop having opinions. Designing loops with judgment is the cure; using loops to avoid thinking is the accelerant. Same action, opposite outcome.

Orchestration Tax Copy Section

The human cost of coordinating parallel agents: review bandwidth, merge conflicts, context switching. Worktrees remove mechanical collisions; you remain the ceiling on how many parallel loops you can absorb.

Code Agent Orchestra / Adversarial Code Review Copy Section

Structural pattern: different agents with different roles (explore, implement, verify). The implementer must never grade its own homework. Critical for unattended loops.

The Six Primitives (+ Memory) Copy Chapter

See primitives.md and primitives-matrix.md.

1. Automations / Scheduling
2. Worktrees
3. Skills
4. Plugins & Connectors (MCP)
5. Sub-agents (maker / checker)
6. + Memory / State (external, durable)

Concept Map Copy Chapter

flowchart TB
  subgraph human [Human — highest leverage]
    Design[Design loop]
    Judgment[Encode judgment in skills + verifiers]
    Gate[Human gates for high-risk work]
  end

  subgraph loop [Loop system]
    Schedule[Scheduler /loop cron Action]
    Triage[Triage skill]
    State[(STATE.md / Linear)]
    Impl[Implementer sub-agent]
    Verify[Verifier sub-agent]
    MCP[MCP connectors]
  end

  Design --> Schedule
  Schedule --> Triage
  Triage --> State
  State --> Impl
  Impl --> Verify
  Verify --> MCP
  MCP --> State
  Verify --> Gate
  Judgment --> Triage
  Judgment --> Verify

Where to Go Next Copy Chapter

• Loop Design Checklist — before you ship a loop
• Failure Modes — when loops go wrong
• Operating Loops — cost, logging, when to pause
• Safety — guardrails for production

Failure Modes (`docs/failure-modes.md`) Copy Section

Failure Mode Catalog

Real ways loops fail — and how good design mitigates them. Use this when debugging a misbehaving loop or writing a new pattern.

Classification Copy Chapter

Infinite Fix Loop Copy Chapter

Symptom: Same PR or CI job gets automated fix attempts 5+ times; never converges.

Severity: S2

Causes:

• Verifier too weak or same session as implementer
• Root cause misdiagnosed (symptom fixing)
• Flaky test treated as regression

Mitigations:

• Hard cap on attempts (e.g. 3) → escalate to human
• Separate verifier model / higher reasoning effort
• Classify flakes in triage; quarantine instead of code change
• Record attempt count in state file

State Rot Copy Chapter

Symptom: STATE.md references merged PRs, closed tickets, or stale branches.

Severity: S1 → S2 (loop acts on ghosts)

Causes:

• No prune step at end of run
• State file not read at start
• Multiple loops writing same file without schema

Mitigations:

• Prune closed/merged items every run
• Last run timestamp + validate IDs against live API
• One state file per loop pattern, or clear sections

Verifier Theater Copy Chapter

Symptom: Verifier "approves" but tests fail in CI or review finds obvious bugs.

Severity: S2

Causes:

• Verifier prompt too vague ("looks good")
• Verifier doesn't run tests
• Same model, same context as implementer

Mitigations:

• Verifier must run test/lint commands and report output
• Different instructions: "find reasons to reject"
• Stronger model on verifier for unattended loops

Notification Fatigue Copy Chapter

Symptom: Slack/email pings every 5 minutes; team mutes the bot.

Severity: S1 → S2 (real escalations missed)

Causes:

• Notify on every run, not every actionable finding
• Low bar for "high priority" in triage skill

Mitigations:

• Notify only when human decision required
• Digest mode for report-only loops
• Tighten triage "High Priority" rules

Token Burn Copy Chapter

Symptom: Bill spikes; loop runs full sub-agent chains on empty or noisy triage.

Severity: S1

Causes:

• Sub-minute cadence with heavy sub-agents
• No early exit when watchlist empty
• Retrying entire pipeline on transient API errors

Mitigations:

• Cheaper triage-only pass first; spawn sub-agents only for actionable items
• scheduler_delete when nothing to watch
• Daily token budget → pause loop
• See operating-loops.md

Over-Reach (Wrong Scope) Copy Chapter

Symptom: Loop refactors unrelated modules, "fixes" design issues, or touches denylisted paths.

Severity: S2 → S3

Causes:

• minimal-fix skill too permissive
• No path allowlist/denylist
• Triage puts architectural work in "High Priority"

Mitigations:

• safety.md denylist enforced in skills
• "Smallest possible diff" + verifier checks touched files
• Triage skill: signal only, no invention

Comprehension Debt Spiral Copy Chapter

Symptom: Velocity up, but no one can explain recent changes; review becomes rubber-stamp.

Severity: S2 (long-term)

Causes:

• Human stops reading loop output
• Auto-merge on growing allowlist
• No weekly human synthesis of loop actions

Mitigations:

• Mandatory human review for non-trivial PRs
• Weekly "loop digest" read by owner
• Cap auto-merge to truly trivial paths

Cognitive Surrender Copy Chapter

Symptom: "The loop handles it" — no opinions on correctness or design.

Severity: S2 (cultural)

Causes:

• Loop success metric = volume, not quality
• No human gates on medium-risk work

Mitigations:

• Explicit human gates in every pattern
• Success metric: time saved with quality bar held
• Osmani: "Build it like someone who intends to stay the engineer"

Parallel Collision Copy Chapter

Symptom: Two sub-agents edit same files; merge conflicts; corrupted state.

Severity: S2

Causes:

• No worktree isolation
• Two loops acting on same PR without coordination

Mitigations:

• isolation: worktree for all code-editing sub-agents
• Lock or queue in state: "PR #1234 — worktree in progress"

Escalation Failure Copy Chapter

Symptom: Loop stuck retrying; human never notified.

Severity: S2

Causes:

• Max attempts not implemented
• Escalation only writes to state no one reads

Mitigations:

• Connector ping on escalation (Slack, Linear comment)
• High Priority (waiting on human) section in STATE.md
• Alert if item in that section >24h

Prompt Injection via Untrusted Input Copy Chapter

Symptom: The loop does something no one asked for — runs a command, edits a file, approves a change, or relabels an issue — because text in an issue, PR, review comment, CI log or dependency changelog told it to.

Severity: S3

Causes:

• Loops read text written by people outside the loop, and the model cannot reliably tell data from instructions
• Third-party text copied into a state file looks like the loop's own notes on the next run
• Hidden text: HTML comments and invisible Unicode (zero-width characters, the U+E0000 tag block) render as nothing for a human reviewer but are read by the model
• Skills that never say which inputs are untrusted

Mitigations:

• Every skill that reads third-party text says it is data, not instructions — see Untrusted input
• Render third-party text inertly in state files: code spans, invisible characters stripped, length capped
• Least-privilege tokens and the path denylist, so an injected instruction has little it can reach
• Human review of anything the loop merges; flagged items escalate rather than act

Contributing Failures Copy Chapter

Have a story? Add a row via PR to this doc or open an issue with:

• Pattern name
• Symptom
• What mitigated it (or didn't)

Jobs (`docs/jobs.md`) Copy Section

What do you want to do?

This repo is a pattern library for operating agents around a codebase — triage, babysit PRs, sweep CI, keep deps current. It is not a “finish my feature / rewrite the module” button.

Week-one rule still applies: report only. Read what the loop writes before you let it act.