Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.
TypeScript agentic-aiai-agentsai-codinganthropicautomationclaudeclaude-codecodexcoding-agentsdevops-automationdevtoolsgithub-actionsgrokllmloop-engineeringmcpprompt-engineering
Activation weeks 1–4: convert stars into a runnable loop (#561)
Cobus Greyling3f7ac78c4d1f
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.jsonnew file mode 100644index 0000000..2bfccf0--- /dev/null+++ b/.claude-plugin/marketplace.json@@ -0,0 +1,18 @@+{+ "name": "loop-engineering",+ "owner": {+ "name": "Cobus Greyling",+ "url": "https://github.com/cobusgreyling"+ },+ "metadata": {+ "description": "Practical loop engineering skills and starters for Claude Code.",+ "version": "1.0.0"+ },+ "plugins": [+ {+ "name": "loop-engineering",+ "source": "./",+ "description": "Triage, budget, constraints, and verifier skills. Pair with npx @cobusgreyling/loop init . --tool claude"+ }+ ]+}diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonnew file mode 100644index 0000000..d779bcb--- /dev/null+++ b/.claude-plugin/plugin.json@@ -0,0 +1,11 @@+{+ "name": "loop-engineering",+ "description": "Loop engineering skills: daily triage, budget, constraints, verifier. Week one is report-only.",+ "version": "1.0.0",+ "author": {+ "name": "Cobus Greyling",+ "url": "https://github.com/cobusgreyling"+ },+ "homepage": "https://github.com/cobusgreyling/loop-engineering",+ "keywords": ["loop-engineering", "triage", "skills", "claude-code"]+}diff --git a/.github/workflows/daily-triage.yml b/.github/workflows/daily-triage.ymlindex 9180966..5e30558 100644--- a/.github/workflows/daily-triage.yml+++ b/.github/workflows/daily-triage.yml@@ -77,6 +77,9 @@ jobs:echo "high=$HIGH" >> "$GITHUB_OUTPUT"echo "items=$ITEMS" >> "$GITHUB_OUTPUT"+ - name: Update last-run badge+ run: node scripts/update-last-run-badge.mjs+- name: Append loop-run-log.mdid: runlogrun: |@@ -142,8 +145,8 @@ jobs:git config user.name "github-actions[bot]"git config user.email "41898282+github-actions[bot]@users.noreply.github.com"- if git diff --quiet STATE.md loop-run-log.md; then- echo "No STATE.md or loop-run-log.md changes — skip PR"+ if git diff --quiet STATE.md loop-run-log.md docs/last-run.json; then+ echo "No STATE.md, loop-run-log.md, or last-run badge changes — skip PR"echo "opened=false" >> "$GITHUB_OUTPUT"exit 0fi@@ -152,7 +155,7 @@ jobs:git fetch origin main "$BRANCH" 2>/dev/null || git fetch origin main# -B keeps working-tree edits; avoids checkout conflicts with modified STATE.mdgit checkout -B "$BRANCH"- git add STATE.md loop-run-log.md+ git add STATE.md loop-run-log.md docs/last-run.jsongit commit -m "chore(loop): daily triage update STATE.md + run log [automated]"if git rev-parse --verify "refs/remotes/origin/${BRANCH}" >/dev/null 2>&1; thengit rebase "origin/${BRANCH}"diff --git a/LOOP.md b/LOOP.mdindex 9a00e10..71f2c5a 100644--- a/LOOP.md+++ b/LOOP.md@@ -77,11 +77,11 @@ npx @cobusgreyling/loop init . --pattern daily-triage --tool grok # after npm pbash scripts/before-after-demo.sh```-## Automation status (2026-07-10)+## Automation status (2026-08-28)| Loop | Level | Automation | Notes ||------|-------|------------|-------|-| Daily Triage | L1 | ✅ `daily-triage.yml` | Weekdays; `github-triage.mjs` writes `STATE.md` from open PRs/issues |+| Daily Triage | L1 | ✅ `daily-triage.yml` | Weekdays; `github-triage.mjs` writes `STATE.md`; `update-last-run-badge.mjs` writes `docs/last-run.json` || Fork PR gate | L1 | ✅ `fork-pr-gate.yml` | Content-only fork PRs get `validate`/`audit` statuses without workflow approval || Changelog Drafter | L1 | ✅ `changelog-drafter.yml` | Mondays; opens release-prep issue || Star History | L1 | ✅ `update-star-history.yml` | Daily; auto-PR to `main`; needs `STAR_HISTORY_TOKEN` secret (PAT). Skips (success) if secret unset — safe for forks |diff --git a/README.md b/README.mdindex 025802e..120a9e3 100644--- a/README.md+++ b/README.md@@ -1,366 +1,125 @@# Loop Engineering--<p align="center">- <a href="https://cobusgreyling.github.io/loop-engineering/">- <img src="https://img.shields.io/badge/✨_Explore_the_Showcase-Design_systems_that_prompt_your_agents-0d1117?style=for-the-badge&labelColor=111a28&color=3ee8c5" alt="Explore the Showcase" />- </a>-</p>-<p align="center">+ <a href="https://cobusgreyling.github.io/loop-engineering/"><img src="https://img.shields.io/badge/✨_Showcase-live-3ee8c5?style=for-the-badge&labelColor=111a28" alt="Showcase" /></a><a href="https://github.com/cobusgreyling/loop-engineering/stargazers"><img src="https://img.shields.io/github/stars/cobusgreyling/loop-engineering?style=social" alt="GitHub stars"></a>- <a href="https://github.com/cobusgreyling/loop-engineering/actions/workflows/audit.yml"><img src="https://img.shields.io/github/actions/workflow/status/cobusgreyling/loop-engineering/audit.yml?label=loop-audit%20dogfood" alt="loop-audit dogfood"></a><a href="https://www.npmjs.com/package/@cobusgreyling/loop"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop?label=loop" alt="loop npm"></a>- <a href="https://www.npmjs.com/package/@cobusgreyling/loop-audit"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop-audit?label=loop-audit" alt="loop-audit npm"></a>- <a href="https://www.npmjs.com/package/@cobusgreyling/loop-init"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop-init?label=loop-init" alt="loop-init npm"></a>- <a href="https://www.npmjs.com/package/@cobusgreyling/loop-cost"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop-cost?label=loop-cost" alt="loop-cost npm"></a>- <a href="https://www.npmjs.com/package/@cobusgreyling/loop-sync"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop-sync?label=loop-sync" alt="loop-sync npm"></a>- <a href="https://www.npmjs.com/package/@cobusgreyling/loop-context"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop-context?label=loop-context" alt="loop-context npm"></a>- <a href="https://www.npmjs.com/package/@cobusgreyling/loop-mcp-server"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop-mcp-server?label=loop-mcp-server" alt="loop-mcp-server npm"></a>- <a href="https://www.npmjs.com/package/@cobusgreyling/loop-worktree"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop-worktree?label=loop-worktree" alt="loop-worktree npm"></a>- <a href="https://github.com/cobusgreyling/loop-engineering/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a>- <a href="https://cobusgreyling.github.io/loop-engineering/"><img src="https://img.shields.io/badge/GitHub_Pages-live%20%7C%20interactive-3ee8c5" alt="Pages"></a>+ <a href="https://raw.githubusercontent.com/cobusgreyling/loop-engineering/main/docs/last-run.json"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/cobusgreyling/loop-engineering/main/docs/last-run.json" alt="last triage"></a>+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a></p>-<p align="center"><a href="https://cobusgreyling.github.io/loop-engineering/">- <img src="https://cdn.jsdelivr.net/gh/cobusgreyling/loop-engineering@main/assets/visuals/loop-engineering-logo.svg" alt="Loop Engineering logo" width="88" />+ <img src="https://cdn.jsdelivr.net/gh/cobusgreyling/loop-engineering@main/assets/visuals/loop-engineering-logo.svg" alt="Loop Engineering logo" width="72" /></a></p>> **Stop prompting. Design the loop. Get a score.**-<p align="center">- <img src="https://cdn.jsdelivr.net/gh/cobusgreyling/loop-engineering@main/assets/visuals/LE5.jpeg" alt="Loop Engineering — design the system that prompts your agents" width="100%" />-</p>--<p align="center">- <strong>Start in 5 minutes</strong> ·+<p align="center"><strong>Start in 5 minutes</strong> ·<a href="docs/QUICKSTART.md">Quickstart</a> ·- <a href="https://cobusgreyling.github.io/loop-engineering/#interactive">Pattern picker</a> ·- <a href="#help-wanted">Contribute</a> ·- <a href="https://github.com/cobusgreyling/loop-engineering/stargazers">⭐ Star</a>+ <a href="docs/jobs.md">What do you want to do?</a> ·+ <a href="docs/refactor.md">Refactor path</a> ·+ <a href="README.zh-CN.md">中文</a> ·+ <a href="https://cobusgreyling.github.io/loop-engineering/#interactive">Pattern picker</a></p>-<p align="center"><sub>If this repo changed how you run agents, a star helps others find the patterns. Docs & small PRs: we aim to review within <strong>48 hours</strong>.</sub></p>-```bash-# One front door — init + doctor + status-npx @cobusgreyling/loop init . --pattern daily-triage --tool grok+npx @cobusgreyling/loop init . --pattern daily-triage --tool claudenpx @cobusgreyling/loop doctor .```-`loop init` scaffolds skills, state, and budget files, then prints your **Loop Ready** score. `loop doctor` turns audit + sync into top-3 next actions. Swap `--tool` for `claude`, `codex`, or `opencode`. Optional: `--with-foundry` for a versioned harness stack. Legacy `npx @cobusgreyling/loop-init .` still works. See [docs/cli-front-door.md](docs/cli-front-door.md).+`--tool` defaults to `claude` if you omit it. Swap for `grok`, `codex`, or `opencode`. Week one is **report-only**.<p align="center"><a href="docs/QUICKSTART.md">- <img src="https://cdn.jsdelivr.net/gh/cobusgreyling/loop-engineering@main/assets/visuals/loop-audit-demo.gif" alt="Loop Ready score climbs from 10 to 100 in 15 seconds" width="100%" />+ <img src="https://cdn.jsdelivr.net/gh/cobusgreyling/loop-engineering@main/assets/visuals/loop-audit-demo.gif" alt="Loop Ready score climbing" width="100%" /></a></p>-Loop engineering replaces you as the person who prompts the agent — you design the system that does it instead.--**New here?** [Quickstart (5 min)](docs/QUICKSTART.md) · [Interactive picker](https://cobusgreyling.github.io/loop-engineering/#interactive) · [Help wanted](#help-wanted)--For developers using Grok, Claude Code, Codex, Cursor, and other AI coding agents.--<p align="center">- <strong><a href="https://cobusgreyling.github.io/loop-engineering/">→ Interactive showcase + pattern picker</a></strong>- ·- <a href="https://cobusgreyling.substack.com/p/loop-engineering">Essay</a>- ·- <a href="https://addyosmani.com/blog/loop-engineering/">Addy Osmani</a>-</p>--## Contents--- [Quickstart (5 min)](docs/QUICKSTART.md)-- [What do you want to do?](docs/jobs.md)-- [Quick Links](#quick-links)-- [Why This Matters](#why-this-matters)-- [The Five Building Blocks + Memory](#the-five-building-blocks--memory)-- [Patterns](#patterns)-- [Getting Started (5 minutes)](#getting-started-5-minutes)-- [Examples by Tool](#examples-by-tool)-- [Operating & Safety](#operating--safety)-- [Caveats](#caveats)-- [Help wanted](#help-wanted)-- [Contributing](#contributing)-- [Sources](#sources)-- [License](#license)--## Quick Links--| Start here | Description |-|------------|-------------|-| [Quickstart (5 min)](docs/QUICKSTART.md) | `loop init` → `loop doctor` → first loop — **start here if you just landed** |-| [What do you want to do?](docs/jobs.md) | Jobs table: keep the repo healthy vs **ship a refactor** ([tutorial](docs/refactor.md)) |-| [CLI front door](docs/cli-front-door.md) | Unified `@cobusgreyling/loop` — old packages stay open |-| [Loop Engineering essay](https://cobusgreyling.substack.com/p/loop-engineering) | The concept, primitives, and Grok mapping — read for the why |-| [Pattern Picker](docs/pattern-picker.md) | Which loop to run first — **start here if unsure** |-| [Primitives Matrix](docs/primitives-matrix.md) | Cross-tool loop primitive mapping — bookmark this |-| [Loop Design Checklist](docs/loop-design-checklist.md) | Ship readiness rubric |-| [Patterns](patterns/README.md) | 7 production patterns + [interactive picker](https://cobusgreyling.github.io/loop-engineering/#interactive) |-| [Starters](starters/) | Clone-and-run kits (Grok, Claude Code, Codex, Opencode) |-| [Opencode examples](examples/opencode/) | CLI-first loops: cron/systemd + `opencode run`, skills, worktrees |-| [**loop** (front door)](tools/loop/) | **Unified CLI** — `npx @cobusgreyling/loop init \| doctor \| status \| audit \| cost` · [cli-front-door](docs/cli-front-door.md) |-| [loop-audit](tools/loop-audit/) | Loop Readiness Score CLI (v1.7 — constraints + governance + **Harness Runtime**) — `npx @cobusgreyling/loop audit . --suggest` · also `loop-audit` |-| [loop-init](tools/loop-init/) | Scaffold starters + budget/run-log + constraints (v1.5) — `npx @cobusgreyling/loop init . --pattern daily-triage --tool grok` · also `loop-init` |-| [harness-foundry](https://github.com/cobusgreyling/harness-foundry) | **Companion runtime:** versioned stacks, sessions, traces — `npx @cobusgreyling/harness-foundry init --from loop-engineering:daily-triage` |-| [outerloop](https://github.com/cobusgreyling/outerloop) | **Companion governance:** evidence → verdict → answerability |-| [loop-cost](tools/loop-cost/) | Token spend estimator — `npx @cobusgreyling/loop-cost` |-| [loop-sync](tools/loop-sync/) | Drift detection between `STATE.md` and `LOOP.md` — `npx @cobusgreyling/loop-sync .` |-| [loop-context](tools/loop-context/) | Stateful memory manager + circuit breaker for long runs — `npx @cobusgreyling/loop-context --check --ledger run.json` |-| [loop-mcp-server](tools/mcp-server/) | MCP runtime lookup for patterns, skills, state — `npx @cobusgreyling/loop-mcp-server` |-| [loop-worktree](tools/loop-worktree/) | Manage isolated git worktrees per fix attempt — `npx @cobusgreyling/loop-worktree create --run-id <id> --pattern <p>` |-| [loop-gate](tools/loop-gate/) | Mechanical enforcement of the path denylist + auto-merge allowlist from `gate.yaml` — `npx @cobusgreyling/loop-gate check --action auto-merge --paths <f1,f2,...>` |-| [loop-sandbox](tools/loop-sandbox/) | Ephemeral git worktree isolation + patch capture — `npx @cobusgreyling/loop-sandbox run -- <cmd>` |-| [loop-action](tools/loop-action/) | GitHub Composite Action for running loops in CI — `uses: cobusgreyling/loop-engineering/tools/loop-action@main` |-| [Goal Engineering](https://github.com/cobusgreyling/goal-engineering) | **Companion:** loops discover, goals finish — `/goal` + [stack cookbook](https://github.com/cobusgreyling/goal-engineering/blob/main/docs/stack-cookbook.md) (`npx @cobusgreyling/goal doctor .`) |-| [Memory Engineering](https://github.com/cobusgreyling/memory-engineering) | **Companion:** stop re-explaining the repo — tiers, budget, Memory Ready score (`node tools/memory-init/cli.js .`) |-| [Fleet Engineering](https://github.com/cobusgreyling/fleet-engineering) | **Companion:** govern populations of agents — registry, inbox, Fleet Ready score (`npx @cobusgreyling/fleet-init .`) |-| [Stories](stories/) | Real wins and honest failures |--### Ecosystem stack--```-memory-engineering → loop-engineering → harness-foundry → outerloop → fleet-engineering- (persist) (patterns) (runtime) (verdict) (population)-```--| Layer | You get | Start |-|-------|---------|--------|-| **Memory** | Tiers, recall budget, Memory Ready score | [memory-engineering](https://github.com/cobusgreyling/memory-engineering) |-| **Design** (this repo) | Patterns, starters, Loop Ready score | `npx @cobusgreyling/loop init .` then `loop doctor .` |-| **Runtime** | Versioned harness, traces, evolve | `npx @cobusgreyling/loop init . --with-foundry` or [Foundry showcase](https://github.com/cobusgreyling/harness-foundry/blob/main/docs/showcase.md) |-| **Govern** | Evidence, verdict, answerability | [outerloop](https://github.com/cobusgreyling/outerloop) |-| **Fleet** | Registry, inbox, budgets, kill switch | `npx @cobusgreyling/fleet-init .` · [Fleet Ready](https://github.com/cobusgreyling/fleet-engineering/blob/main/docs/fleet-ready-score.md) |--**Scale beyond one loop:** when agents forget across sessions, add [memory-engineering](https://github.com/cobusgreyling/memory-engineering). When you have many agents/loops on a team, add [fleet-engineering](https://github.com/cobusgreyling/fleet-engineering).--**Next after Loop Ready 80+:** version the loop as a harness — `loop-init` prints the CTA automatically; `loop-audit` recommends Foundry when the score is strong but `.foundry/stack.yaml` is missing.--### Community & announcements--| Discussion | Summary |-|------------|---------|-| [Contributor quickstart](https://github.com/cobusgreyling/loop-engineering/discussions/123) | **Help wanted:** open `good first issues` — comment *I'll take this* to get assigned · see [Help wanted](#help-wanted) |-| [Community update](https://github.com/cobusgreyling/loop-engineering/discussions/145) | **July 4:** 5.5k stars, traffic sources, contributor merges |-| [Community week (Jul 8)](https://github.com/cobusgreyling/loop-engineering/discussions/219) | loop-worktree npm, MCP quickstart, tool appendices |-| [npm update (Jul 16)](https://github.com/cobusgreyling/loop-engineering/discussions/294) | `loop-context` 1.2.0 + `loop-worktree` 1.1.0 — daily budget, path locks |-| [Maintenance (Jul 10)](https://github.com/cobusgreyling/loop-engineering/discussions/241) | Doc sync, branch prune, loop-audit 1.6.0 follow-up |-| [Prior release notes](https://github.com/cobusgreyling/loop-engineering/discussions/89) | v1.5.0 — loop-sync, constraints, MCP server |-| [Add your project](https://github.com/cobusgreyling/loop-engineering/discussions/92) | **Pinned:** Loop Ready badge + adopters list |--<p align="center">- <img src="https://cdn.jsdelivr.net/gh/cobusgreyling/loop-engineering@main/assets/visuals/section-divider.svg" alt="" width="100%" />-</p>--## Why This Matters--Peter Steinberger:-> “You shouldn’t be prompting coding agents anymore. You should be designing loops that prompt your agents.”--Boris Cherny (Head of Claude Code at Anthropic):-> “I don’t prompt Claude anymore. I have loops running that prompt Claude and figuring out what to do. My job is to write loops.”+You design a system that discovers work, hands it to agents, verifies results, and persists state — instead of typing the next prompt yourself.-The leverage point has moved from crafting individual prompts to designing the control systems that orchestrate agents over time.+**New here?** [Quickstart](docs/QUICKSTART.md) · [Refactor a project](docs/refactor.md) · [Thin GitHub Action loop](starters/thin-loop/) (no `STATE.md` required)-## The Five Building Blocks + Memory+## What do you want to do?-| Primitive | Job in the Loop |-|-----------|-----------------|-| **Automations / Scheduling** | Discovery + triage on a cadence |-| **Worktrees** | Safe parallel execution |-| **Skills** | Persistent project knowledge |-| **Plugins & Connectors** | Reach into your real tools (MCP) |-| **Sub-agents** | Maker / checker split |-| **+ Memory / State** | Durable spine outside any conversation |+This is a **pattern library for operating agents around a codebase**. It is not a “rewrite the module” button.-Full detail: [docs/primitives.md](docs/primitives.md) · Cross-tool matrix: [docs/primitives-matrix.md](docs/primitives-matrix.md)+| I want to… | Start here |+|------------|------------|+| Keep the repo healthy (issues, CI, deps) | [Quickstart](docs/QUICKSTART.md) → `daily-triage` |+| Land and babysit PRs | [PR Babysitter](patterns/pr-babysitter.md) |+| Run a loop in GitHub Actions with almost no files | [Thin loop](starters/thin-loop/) |+| **Ship a feature or refactor** (todos → small PRs) | **[Refactor / change path](docs/refactor.md)** |-### Visual Overview--<p align="center">- <img src="https://cdn.jsdelivr.net/gh/cobusgreyling/loop-engineering@main/assets/visuals/primitives-infographic.jpg" alt="The Five Building Blocks + Memory — Loop Engineering" width="100%" />-</p>--### Anatomy of a Loop--<p align="center">- <img src="https://cdn.jsdelivr.net/gh/cobusgreyling/loop-engineering@main/assets/visuals/loop-cycle-animated.svg" alt="Animated loop flow — schedule, triage, state, worktree, implement, verify, MCP, human gate" width="100%" />-</p>--<details>-<summary>Mermaid diagram (copy-friendly)</summary>--```mermaid-flowchart LR- A[Schedule / Automation] --> B[Triage Skill]- B --> C[Read + Write STATE / Memory]- C --> D[Isolated Worktree]- D --> E[Implementer Sub-agent]- E --> F[Verifier Sub-agent<br/>tests + gates]- F --> G[MCP / Git / Tickets]- G --> H{Human Gate?}- H -->|safe / allowlisted| I[Commit / PR / Action]- H -->|risky / ambiguous| J[Escalate to human<br/>with full context]- I --> A- J --> A-```--</details>--Deeper diagrams — the actor-level sequence within one run, the run lifecycle's states, autonomy levels L1-L3, and how `tools/` maps onto the primitives — live in [docs/architecture-diagrams.md](docs/architecture-diagrams.md).--**This reference repo now runs its own `validate-patterns` + `audit` workflows on every push/PR** (see `.github/workflows/`). We also added `LOOP.md` describing the loops that will maintain it.+Full jobs table: [docs/jobs.md](docs/jobs.md).## Patterns-<p align="center">- <img src="https://cdn.jsdelivr.net/gh/cobusgreyling/loop-engineering@main/assets/visuals/patterns-overview.svg" alt="Seven production loop patterns with cadence and token cost" width="100%" />-</p>+| Pattern | Cadence | Week 1 | Cost |+|---------|---------|--------|------|+| [Daily Triage](patterns/daily-triage.md) | 1d–2h | L1 report | Low |+| [Thin loop](patterns/thin-loop.md) | event + 1d | L1 snapshot | Very low |+| [PR Babysitter](patterns/pr-babysitter.md) | 5–15m | L1 watch | High |+| [CI Sweeper](patterns/ci-sweeper.md) | 5–15m | L2 cautious | Very high |+| [Dependency Sweeper](patterns/dependency-sweeper.md) | 6h–1d | L2 patch-only | Medium |+| [Changelog Drafter](patterns/changelog-drafter.md) | 1d or tag | L1 draft | Low |+| [Post-Merge Cleanup](patterns/post-merge-cleanup.md) | 1d–6h | L1 off-peak | Low |+| [Issue Triage](patterns/issue-triage.md) | 2h–1d | L1 propose-only | Low |-| Pattern | Cadence | Starter | Week 1 | Token cost |-|---------|---------|---------|--------|------------|-| [Daily Triage](patterns/daily-triage.md) | 1d–2h | [minimal-loop](starters/minimal-loop/) | **L1** report | Low |-| [PR Babysitter](patterns/pr-babysitter.md) | 5–15m | [pr-babysitter](starters/pr-babysitter/) | L1 watch | High |-| [CI Sweeper](patterns/ci-sweeper.md) | 5–15m | [ci-sweeper](starters/ci-sweeper/) | L2 cautious | Very high |-| [Dependency Sweeper](patterns/dependency-sweeper.md) | 6h–1d | [dependency-sweeper](starters/dependency-sweeper/) | L2 patch-only | Medium |-| [Changelog Drafter](patterns/changelog-drafter.md) | 1d or tag | [changelog-drafter](starters/changelog-drafter/) | **L1** draft | Low |-| [Post-Merge Cleanup](patterns/post-merge-cleanup.md) | 1d–6h | [post-merge-cleanup](starters/post-merge-cleanup/) | **L1** off-peak | Low |-| [Issue Triage](patterns/issue-triage.md) | 2h–1d | [issue-triage](starters/issue-triage/) | **L1** propose-only | Low |+Interactive picker: [showcase](https://cobusgreyling.github.io/loop-engineering/#interactive). Index: [patterns/registry.yaml](patterns/registry.yaml).-Not sure which to pick? Try the [interactive picker](https://cobusgreyling.github.io/loop-engineering/#interactive) or [pattern-picker](docs/pattern-picker.md).--Machine-readable index: [patterns/registry.yaml](patterns/registry.yaml) (7 patterns)--## Getting Started (5 minutes)+## Getting started```bash-# 1. Scaffold + Loop Ready score (printed automatically)-npx @cobusgreyling/loop init . --pattern daily-triage --tool grok--# 2. One health check (audit + sync + files → top 3 actions)+npx @cobusgreyling/loop init . --pattern daily-triage --tool claudenpx @cobusgreyling/loop doctor .--# 3. Optional: cost estimate / badge / day-2 dashboardnpx @cobusgreyling/loop cost --pattern daily-triage --level L1-npx @cobusgreyling/loop badge .-npx @cobusgreyling/loop status .--# 4. See scores climb: empty → L1 → L2-bash scripts/before-after-demo.sh--# 5. Start report-only (Grok example)-/loop 1d Run loop-triage. Update STATE.md. No auto-fix in week one.```-**Same as before:** `npx @cobusgreyling/loop-init` and `loop-audit` still work — [CLI front door](docs/cli-front-door.md).--All npm CLIs publish from tagged releases — see [docs/RELEASE.md](docs/RELEASE.md). No clone required.+Empty repo → first `STATE.md` walkthrough: [scripts/empty-to-state-demo.sh](scripts/empty-to-state-demo.sh).-**Develop from source** (monorepo contributors):+Roll out **L1 report → L2 assisted → L3 unattended** only after the verifier has been right for a week. See [loop-design-checklist](docs/loop-design-checklist.md).-```bash-cd tools/loop && npm ci && npm test && node dist/cli.js doctor ../..-cd tools/loop-init && npm ci && npm test && node dist/cli.js /path/to/project --pattern daily-triage --tool grok-cd tools/loop-audit && npm ci && npm test && node dist/cli.js /path/to/project --suggest-cd tools/loop-cost && npm ci && npm test && node dist/cli.js --pattern ci-sweeper --cadence 15m-```+Loop Ready now **weights recent runs harder than files on disk**. A 30-day-old `STATE.md` is not L3.-Phased rollout: **L1 report → L2 assisted fixes → L3 unattended** — see [loop-design-checklist](docs/loop-design-checklist.md).+## Examples by tool-## Examples by Tool+[Claude Code](examples/claude-code/) (including the [plugin](examples/claude-code/plugin.md)) · [Grok](examples/grok/daily-triage.md) · [Codex](examples/codex/) · [OpenClaw](examples/openclaw/daily-triage.md) · [Opencode](examples/opencode/) · [GitHub Actions](examples/github-actions/)-- [Grok](examples/grok/daily-triage.md)-- [Claude Code](examples/claude-code/)-- [Codex](examples/codex/)-- [OpenClaw](examples/openclaw/daily-triage.md)-- [Opencode](examples/opencode/)-- [GitHub Actions](examples/github-actions/)+## Operating & safety-## Operating & Safety+[Failure modes](docs/failure-modes.md) · [Anti-patterns](docs/anti-patterns.md) · [Safety](docs/safety.md) · [Operating loops](docs/operating-loops.md) · [Stories](stories/) (wins **and** failures)-- [Failure Modes](docs/failure-modes.md) — incident-style catalog-- [Anti-Patterns](docs/anti-patterns.md) — design mistakes before production-- [Multi-Loop Coordination](docs/multi-loop.md) — when loops collide-- [Operating Loops](docs/operating-loops.md) — cost, logging, when to kill-- [Safety](docs/safety.md) — denylist, auto-merge, MCP scopes-- [Security](SECURITY.md) — reporting and unattended automation risks-- [Concepts](docs/concepts.md) — intent debt, comprehension debt, harness vs loop-- [MCP Cookbook](examples/mcp/) — connector examples by pattern--## Caveats--Loop engineering amplifies judgment — both good and bad.--- **Token costs** can explode with sub-agents and long-running loops.-- **Verification is still on you.** Unattended loops make unattended mistakes.-- **Comprehension debt** grows faster unless you read what the loop ships.-- Two people can run the same loop and get opposite results. The loop doesn't know. You do.--Addy Osmani:-> “Build the loop. But build it like someone who intends to stay the engineer, not just the person who presses go.”+Loop engineering amplifies judgment. Token costs can explode. Unattended loops make unattended mistakes. Read what the loop ships.## Help wanted-**First PR?** Pick an open issue below, or [Add Adopter](https://github.com/cobusgreyling/loop-engineering/issues/new?template=add-adopter.yml) / [Share a story](https://github.com/cobusgreyling/loop-engineering/issues/new?template=share-story.yml).--**Review SLA:** docs, stories, adopters, and small tests — **within 48 hours** (same-day when possible). See [CONTRIBUTORS.md](CONTRIBUTORS.md) and the [contributor quickstart](https://github.com/cobusgreyling/loop-engineering/discussions/123).+Docs and small PRs: first response within **48 hours**.-[`good first issue` backlog](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) (comment **"I'll take this"** for assignment). Prefer the live filter if a row below looks stale.+- [Add your project](https://github.com/cobusgreyling/loop-engineering/issues/new?template=add-adopter.yml) to [adopters](docs/adopters.md)+- [Share a story](https://github.com/cobusgreyling/loop-engineering/issues/new?template=share-story.yml) (failures first-class)+- Live [`good first issue`](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) list+- [Show your loop](https://github.com/cobusgreyling/loop-engineering/discussions/326) · [Ask anything](https://github.com/cobusgreyling/loop-engineering/discussions/327)-| Time | Issue | What you ship |-|------|-------|---------------|-| ~10 min | [#120 — Adopters list](https://github.com/cobusgreyling/loop-engineering/issues/120) | One row in `docs/adopters.md` (or [Add Adopter](https://github.com/cobusgreyling/loop-engineering/issues/new?template=add-adopter.yml) template) |-| ~15–20 min | [#118 — Daily Triage story](https://github.com/cobusgreyling/loop-engineering/issues/118) · [#173 — Issue Triage story](https://github.com/cobusgreyling/loop-engineering/issues/173) · [#119 — PR Babysitter failure](https://github.com/cobusgreyling/loop-engineering/issues/119) | Honest `stories/` write-up + index row |-| ~40–45 min | [#388 — Hermes Issue Triage](https://github.com/cobusgreyling/loop-engineering/issues/388) | Hermes Issue Triage example in `examples/hermes/` |-| Anytime | Templates | [Add Adopter](https://github.com/cobusgreyling/loop-engineering/issues/new?template=add-adopter.yml) · [Share a story](https://github.com/cobusgreyling/loop-engineering/issues/new?template=share-story.yml) |-| Hubs | Discussions | [Show your loop](https://github.com/cobusgreyling/loop-engineering/discussions/326) · [Ask anything](https://github.com/cobusgreyling/loop-engineering/discussions/327) |+See [CONTRIBUTING.md](CONTRIBUTING.md).-**Recently shipped (thanks!):** @AIMindCrafter — Windows/CRLF notes (#492), Windsurf Post-Merge Cleanup (#494), Windsurf Changelog Drafter (#495). @pxmpsdev — loop-sync CRLF tests (#496), readiness skill-dedup (#497), append-run-log invalid-JSON (#498), metrics unparseable run_id (#499). @shixi-li — Hermes CI Sweeper example (#500).--**Docs/examples triage:** @AIMindCrafter co-owns `docs/`, `examples/`, and `stories/` (see [CODEOWNERS](CODEOWNERS) + [docs/area-owners.md](docs/area-owners.md)).--Maintainers re-seed the backlog with `bash scripts/create-good-first-issues.sh` (idempotent; skips existing titles). Prefer [live open GFI filter](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) over this table if a row looks stale.+<details>+<summary>CLI packages and companion repos (optional — not required for week one)</summary>-## Contributing+Unified front door: `npx @cobusgreyling/loop` (`init` · `doctor` · `status` · `audit` · `cost`). Older packages (`loop-init`, `loop-audit`, …) stay supported.-Share production patterns, tool mappings, and failure stories. See [CONTRIBUTING.md](CONTRIBUTING.md) (ladder + setup), [Code of Conduct](CODE_OF_CONDUCT.md), [adopters](docs/adopters.md), and hubs: [Show your loop](https://github.com/cobusgreyling/loop-engineering/discussions/326) · [Ask anything](https://github.com/cobusgreyling/loop-engineering/discussions/327).+Companions exist for later: [memory-engineering](https://github.com/cobusgreyling/memory-engineering), [harness-foundry](https://github.com/cobusgreyling/harness-foundry), [outerloop](https://github.com/cobusgreyling/outerloop), [fleet-engineering](https://github.com/cobusgreyling/fleet-engineering), [goal-engineering](https://github.com/cobusgreyling/goal-engineering). Do not add them until a loop has actually run.-We aim to **first-respond within 48 hours** on external PRs. Start here: [`good first issue`](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) · [Help wanted](#help-wanted).+</details>## Sources-- [Cobus Greyling – Loop Engineering (Substack)](https://cobusgreyling.substack.com/p/loop-engineering)-- [Addy Osmani – Loop Engineering](https://addyosmani.com/blog/loop-engineering/)-- [Attribution & further reading](resources/sources.md)+- [Cobus Greyling — Loop Engineering](https://cobusgreyling.substack.com/p/loop-engineering)+- [Addy Osmani — Loop Engineering](https://addyosmani.com/blog/loop-engineering/)+- [Lulla et al. 2026 — Building Blocks, Adoption, and Impact](https://arxiv.org/abs/2608.21884) (this repo is the community reference they reviewed)+- [Attribution](resources/sources.md)## LicenseMIT-------*Practical, tool-aware reference for loop engineering, patterns you can clone, checklists you can ship against, and stories that include what broke.*--<p align="center">- <a href="https://cobusgreyling.substack.com/p/loop-engineering">Essay</a>- ·- <a href="https://cobusgreyling.github.io/loop-engineering/">Showcase</a>- ·- <a href="https://github.com/cobusgreyling">Cobus Greyling</a>-</p>--<p align="center">- <a href="https://cobusgreyling.github.io/loop-engineering/star-history.html">- <picture>- <source media="(prefers-color-scheme: dark)" srcset="https://cdn.jsdelivr.net/gh/cobusgreyling/loop-engineering@main/assets/visuals/star-history-dark.svg" />- <source media="(prefers-color-scheme: light)" srcset="https://cdn.jsdelivr.net/gh/cobusgreyling/loop-engineering@main/assets/visuals/star-history.svg" />- <img alt="Star History Chart" src="https://cdn.jsdelivr.net/gh/cobusgreyling/loop-engineering@main/assets/visuals/star-history.svg" />- </picture>- </a>-</p>-<p align="center"><sub>Static chart (CI-updated daily). <a href="https://cobusgreyling.github.io/loop-engineering/star-history.html">Live chart</a> needs a GitHub token — stored in your browser only.</sub></p>diff --git a/README.zh-CN.md b/README.zh-CN.mdnew file mode 100644index 0000000..e36954c--- /dev/null+++ b/README.zh-CN.md@@ -0,0 +1,54 @@+# Loop Engineering(中文)++> **别再逐条提示。设计循环。拿一个分数。**++[English README](README.md) · [5 分钟快速开始](docs/QUICKSTART.md) · [我想重构项目](docs/refactor.md)++```bash+npx @cobusgreyling/loop init . --pattern daily-triage --tool claude+npx @cobusgreyling/loop doctor .+```++省略 `--tool` 时默认 `claude`。可换成 `grok`、`codex`、`opencode`。第一周只做 **L1 报告**,不要自动改代码、不要自动合并。++## 这是什么++这是一套围绕代码库 **运转 coding agent** 的模式库(分诊、看护 PR、扫 CI、升依赖),不是「一键重写整个项目」的按钮。++| 我想… | 从这里开始 |+|--------|------------|+| 每天知道仓库里该干什么 | [Quickstart](docs/QUICKSTART.md) → `daily-triage` |+| 几乎不新增文件,只用 GitHub Action 跑循环 | [Thin loop](starters/thin-loop/) |+| **重构 / 拆 todo / 自动推进** | **[重构路径](docs/refactor.md)**(Issue #522 的完整回答) |++## 重构怎么做(摘要)++**没有「L3 无人值守重构整个仓库」这种模式。** 那是故意的:大范围改文件落在 [safety.md](docs/safety.md) 的 denylist 里。++正确路径:++1. `loop init` 只搭治理框架(`STATE.md`、预算、约束),第一周只读扫描。+2. Daily Triage 把「大重构」拆成 **足够小、一个 PR 能做完** 的 High Priority 行。+3. 每一项:worktree → implementer 改 → **独立** verifier 跑测试 → **你** 审 PR。+4. 只对已经信任的路径(测试、文档)考虑自动合并 allowlist。核心逻辑永远升级给人类。++逐步说明、反例、和 Goal Engineering 的边界:请读 **[docs/refactor.md](docs/refactor.md)**。++## 第一周命令++```bash+npx @cobusgreyling/loop init . --pattern daily-triage --tool claude+npx @cobusgreyling/loop doctor .+# 报告-only,例如 Claude Code:+# /loop 1d $loop-triage — 更新 STATE.md。第一周不要改代码。+```++空仓库走到第一份 `STATE.md`:[scripts/empty-to-state-demo.sh](scripts/empty-to-state-demo.sh)++## 分数说明++Loop Ready **更看最近有没有真正跑过循环**,而不是仓库里堆了多少模板文件。一份 30 天没更新的 `STATE.md` 不能算 L3。++## 许可++MITdiff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.mdindex 8959075..55b670f 100644--- a/docs/QUICKSTART.md+++ b/docs/QUICKSTART.md@@ -23,17 +23,17 @@ Or start with **Daily Triage** if you just want to learn loop discipline with loRun this in the root of any git project (no clone required):```bash-npx @cobusgreyling/loop init . --pattern daily-triage --tool grok+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 grok --with-foundry+npx @cobusgreyling/loop init . --pattern daily-triage --tool claude --with-foundry```Equivalent (old door, still supported):```bash-npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok+npx @cobusgreyling/loop-init . --pattern daily-triage --tool claude```Swap `--pattern` for any pattern from [patterns/registry.yaml](../patterns/registry.yaml). List all patterns:@@ -46,8 +46,8 @@ npx @cobusgreyling/loop init --help| `--tool` value | Scaffolded by `loop-init`? | Notes ||----------------|---------------------------|-------|-| `grok` | Yes (default) | Native `/loop` scheduling |-| `claude` | Yes | Native `/loop` + `$skill` invocation |+| `claude` | Yes (default) | Native `/loop` + `$skill` invocation |+| `grok` | Yes | Native `/loop` scheduling || `codex` | Yes | Automations tab for scheduling || `opencode` | Yes | Cron/systemd + `opencode run` || `cursor` | No — manual copy | Copy skills + `STATE.md`; use Automations — see [examples/cursor/](../examples/cursor/) |@@ -109,7 +109,7 @@ npx @cobusgreyling/harness-foundry run --goal "Verify harness wiring"To configure provider-specific stacks like **MiniMax** during scaffolding:```bash-npx @cobusgreyling/loop init . --pattern daily-triage --tool grok \+npx @cobusgreyling/loop init . --pattern daily-triage --tool claude \--with-foundry --model-provider minimax --region global_en --model MiniMax-M3```@@ -376,7 +376,7 @@ Windows contributors and loop operators should keep line-ending and process invo```bash# 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 grok+npx @cobusgreyling/loop-init . --pattern daily-triage --tool claude# List patterns and flagsnpx @cobusgreyling/loop-init --helpdiff --git a/docs/cli-front-door.md b/docs/cli-front-door.mdindex ef1b6ed..a23eb0e 100644--- a/docs/cli-front-door.md+++ b/docs/cli-front-door.md@@ -13,7 +13,7 @@ Loop Engineering ships several focused CLIs (`loop-init`, `loop-audit`, `loop-co3. **doctor** / **status** for activation and day-2 habit```text-npx @cobusgreyling/loop init . -p daily-triage -t grok+npx @cobusgreyling/loop init . -p daily-triage -t claudenpx @cobusgreyling/loop doctor .```diff --git a/docs/distribution/activation-checklist.md b/docs/distribution/activation-checklist.mdnew file mode 100644index 0000000..8de5ef9--- /dev/null+++ b/docs/distribution/activation-checklist.md@@ -0,0 +1,37 @@+# Activation checklist (weeks 1–4)++Shipped in the activation PR. Remaining human steps after merge:++## Publish npm (needs tags on `main`)++```bash+git tag loop-v0.2.0+git tag loop-init-v1.7.0+git tag loop-audit-v1.9.0+git push origin loop-v0.2.0 loop-init-v1.7.0 loop-audit-v1.9.0+```++Trusted publishing via `.github/workflows/release-loop.yml` (and siblings). Local `npm whoami` is unauthorized; do not `npm publish` from a laptop.++## Record the video++Script: [empty-to-state-video.md](./empty-to-state-video.md)+Rehearsal: `bash scripts/empty-to-state-demo.sh`++Swap the README hero GIF when the file is on YouTube/X.++## Post++- [arxiv-paper-thread.md](./arxiv-paper-thread.md) — X + LinkedIn+- [show-hn.md](./show-hn.md) — after tags are live so `npx` is 0.2.0+- [glossary-outreach.md](./glossary-outreach.md) — five outlets+- [fork-outreach.md](./fork-outreach.md) — 20 recent forks, one at a time++## Already done in-repo++- README cut; default `--tool claude`+- `#522` answer lives at [refactor.md](../refactor.md) + [README.zh-CN.md](../../README.zh-CN.md)+- Thin loop starter + last-run badge+- Loop Ready weights fresh runs; companions opt-in+- Claude Code plugin metadata+- Honest 22-run storydiff --git a/docs/distribution/arxiv-paper-thread.md b/docs/distribution/arxiv-paper-thread.mdnew file mode 100644index 0000000..5fbbd10--- /dev/null+++ b/docs/distribution/arxiv-paper-thread.md@@ -0,0 +1,56 @@+# Thread — Lulla et al. found 217 loops and almost no STATE.md++Source: https://arxiv.org/abs/2608.21884+This repo is the community reference they reviewed.++## X (copy-paste)++1/ Researchers scanned 36,710 repos for loop engineering.++They confirmed 217 autonomous agent loops.++Almost none commit STATE.md.++The config is in git. The runtime state is not.++2/ That matches what we see as maintainers of loop-engineering.++We prescribed STATE.md, loop-budget.md, verifier sub-agents.++The paper found: triggers (GitHub Actions) are real. The files we treat as the spine are almost absent.++3/ Most of those 217 loops were event-triggered PR review. The next PR is the next run. There is nothing to persist.++Scheduled loops were mostly issue triage. The issue tracker already holds the backlog.++4/ STATE.md still pays off when you need:++- attempt counts+- a watch list that is not an issue+- a kill switch and a budget the agent can read+- a human who was not in the last session++If GitHub already is the queue, do not invent a second one.++5/ We shipped a Thin Loop starter for the common case: one Action, job summary, optional comment. No STATE.md.++`npx @cobusgreyling/loop init . --pattern thin-loop --tool claude`++And Loop Ready now treats a 14-day-old Last run as stale, not L3.++6/ Paper: https://arxiv.org/abs/2608.21884++Repo: https://github.com/cobusgreyling/loop-engineering++If you run a loop that does commit state, add it to adopters. The empirical gap is still huge.++## LinkedIn (one post)++An ASE workshop paper (Lulla, Nersesyan, Mohsenimofidi, Treude, Baltes) mined 36k GitHub repos for loop engineering. 217 loops confirmed. Almost no project commits the state files the discourse (including our repo) prescribed.++Takeaway for practitioners: match the loop to the store you already have. PR review loops can stay in GitHub Actions + comments. Use STATE.md when the queue is not the tracker.++We changed the reference repo to match: a thin-loop starter, and Loop Ready that scores recent runs instead of template files.++https://arxiv.org/abs/2608.21884+https://github.com/cobusgreyling/loop-engineeringdiff --git a/docs/distribution/empty-to-state-video.md b/docs/distribution/empty-to-state-video.mdnew file mode 100644index 0000000..a975ae9--- /dev/null+++ b/docs/distribution/empty-to-state-video.md@@ -0,0 +1,39 @@+# Video script — empty repo to first STATE.md (8–10 min)++Record this once. Put the file on the README hero next to (or instead of) the score GIF. The score GIF shows files appearing; this video shows a **run**.++## Setup (before record)++- Clean terminal, 80–100 columns, dark theme.+- Clone of loop-engineering on `main` with `tools/loop-init` and `tools/loop-audit` built, **or** npm (`npx @cobusgreyling/loop`).+- No secrets on screen.++## Shot list++1. **0:00 title card (5s)** — “Empty repo → first STATE.md. Report only.”+2. **0:05 empty dir** — `mkdir demo && cd demo && git init && ls`+3. **0:20 init** — `npx @cobusgreyling/loop init . --pattern daily-triage --tool claude`+ - Pause on Loop Ready score. Say: “This score is files on disk. It is not permission to auto-fix.”+4. **1:30 doctor** — `npx @cobusgreyling/loop doctor .`+ - Point at the top 3 actions.+5. **2:30 STATE.md before a run** — `sed -n '1,16p' STATE.md`+ - Last run is empty/never.+6. **3:30 first loop (Claude Code)** — `/loop 1d $loop-triage — update STATE.md. Report-only week one.`+ - If recording without Claude: run `bash scripts/empty-to-state-demo.sh` from the reference repo and narrate the simulated Last run.+7. **6:00 STATE.md after** — High Priority has one real line. Last run is today’s ISO timestamp.+8. **7:00 commit** — `git add STATE.md && git commit -m "chore(loop): first L1 daily triage"`+ - “This commit is what Loop Ready counts as activity.”+9. **8:00 doctor again** — activity finding is ok.+10. **8:45 closer** — “Do not turn on L2 this week. Read the file tomorrow.”++## Caption (X / LinkedIn / YouTube)++Stop prompting. One command, one report-only loop, one STATE.md.++`npx @cobusgreyling/loop init . --pattern daily-triage --tool claude`++Repo: https://github.com/cobusgreyling/loop-engineering++## If you cannot record this week++Run `bash scripts/empty-to-state-demo.sh` and paste the terminal output into a gist linked from the README. A gist of a real run beats another score GIF.diff --git a/docs/distribution/fork-outreach.md b/docs/distribution/fork-outreach.mdnew file mode 100644index 0000000..13e3bf6--- /dev/null+++ b/docs/distribution/fork-outreach.md@@ -0,0 +1,51 @@+# Fork outreach — 20 recent forks++Goal: five adopter rows that are not this repo. Do not mass-issue. Personal note, one repo at a time.++## Message (GitHub, email, or X DM)++Hi — you forked loop-engineering. If you actually run a loop (even L1 report-only, even if you dropped STATE.md), I want one row in the adopters list:++https://github.com/cobusgreyling/loop-engineering/issues/new?template=add-adopter.yml++Pattern, tool, level, one line on what worked or broke. Failures preferred. Takes ~10 minutes. We review within 48 hours.++If you forked and never ran it, ignore this.++## How to pick 20++```bash+gh api "repos/cobusgreyling/loop-engineering/forks?sort=newest&per_page=20" \+ --jq '.[] | "\(.pushed_at)\t\(.full_name)\t\(.html_url)"'+```++Prefer forks with `pushed_at` after the fork date (they did something). Skip empty forks.++Snapshot (newest 20 as of 2026-08-28). Many share a `pushed_at` with the parent — those are likely empty forks; skip them.++| pushed_at (UTC) | Fork |+|-----------------|------|+| 2026-08-27 11:17 | https://github.com/Randika97/loop-engineering |+| 2026-08-27 11:17 | https://github.com/nhannguyensy/loop-engineering |+| 2026-08-27 11:17 | https://github.com/Srimalwimalaweera/loop-engineering |+| 2026-08-27 04:02 | https://github.com/Agi-Asi/loop-engineering |+| 2026-08-26 08:22 | https://github.com/laudarch/loop-engineering |+| 2026-08-26 08:22 | https://github.com/tokitam/loop-engineering |+| 2026-08-24 08:13 | https://github.com/itzMalieth/loop-engineering |+| 2026-08-24 08:13 | https://github.com/dleventis/loop-engineering |+| 2026-08-24 08:13 | https://github.com/MartinQuic/loop-engineering |+| 2026-08-24 08:13 | https://github.com/cryptXploit/loop-engineering |+| 2026-08-24 08:13 | https://github.com/FaisalRajpoot1/loop-engineering |+| 2026-08-24 08:13 | https://github.com/jo4josephine/loop-engineering |+| 2026-08-24 02:43 | https://github.com/ufda/loop-engineering |+| 2026-08-24 02:43 | https://github.com/meorstone/loop-engineering |+| 2026-08-23 02:42 | https://github.com/casper05/loop-engineering |+| 2026-08-23 02:42 | https://github.com/domdomsaigon123-collab/loop-engineering |+| 2026-08-23 02:42 | https://github.com/faisalcha/loop-engineering |+| 2026-08-23 02:42 | https://github.com/Tayonike/loop-engineering |+| 2026-08-23 02:42 | https://github.com/lucasboy66/loop-engineering |+| 2026-08-23 02:42 | https://github.com/Joaquin-Boilet/loop-engineering |++Post the same ask on the pinned adopters discussion instead of cold-emailing if a fork has no public email:++https://github.com/cobusgreyling/loop-engineering/discussions/92diff --git a/docs/distribution/glossary-outreach.md b/docs/distribution/glossary-outreach.mdnew file mode 100644index 0000000..6faf1e8--- /dev/null+++ b/docs/distribution/glossary-outreach.md@@ -0,0 +1,32 @@+# Glossary / roundup outreach++These pages discuss “loop engineering” without linking the reference repo. One short note each, after the activation PR is on main.++## Recipients++| Outlet | URL | Ask |+|--------|-----|-----|+| Data Science Dojo | https://datasciencedojo.com/blog/loop-engineering-design-patterns/ | Add the pattern library + `npx @cobusgreyling/loop` as the practical catalog (their “10 patterns” are inner ReAct-style, different layer) |+| Sofokus glossary | https://www.sofokus.com/ai-glossary/loop-engineering/ | Citation / further reading |+| V12 Labs | https://www.v12labs.io/blog/2026-07-18-loop-engineering-explained | Skepticism is fair; point at stories/thirty-weekday-runs.md and the thin loop |+| DEV.co listing | https://dev.co/ai/frameworks/loop-engineering | Refresh star count and default command (`--tool claude`) |+| Codingscape | https://codingscape.com/blog/loop-engineering-why-agent-loops-beat-prompt-engineering | Practical next step link |++## Note (email / form)++Subject: loop-engineering reference repo for your loop engineering piece++Thanks for writing about loop engineering. There is a tool-agnostic pattern library + CLI that people copy for Daily Triage / PR babysitting / CI sweep, including failure stories:++https://github.com/cobusgreyling/loop-engineering++Default on-ramp (Claude Code):++```+npx @cobusgreyling/loop init . --pattern daily-triage --tool claude+npx @cobusgreyling/loop doctor .+```++If useful, a “further reading” or “try it” link is enough. Happy to correct anything we got wrong relative to your article.++Cobusdiff --git a/docs/distribution/show-hn.md b/docs/distribution/show-hn.mdnew file mode 100644index 0000000..ff73638--- /dev/null+++ b/docs/distribution/show-hn.md@@ -0,0 +1,42 @@+# Show HN draft++Do not file until the activation PR is on `main` and the last-run badge is live.++## Title++Show HN: 22 weekday agent-triage runs on our own repo – what the score hid++## Text++Loop engineering (the June 2026 slogan: stop prompting, design the loop) has a reference repo: patterns, `npx @cobusgreyling/loop init`, a Loop Ready score.++We ran Daily Triage on that repo every weekday via GitHub Actions. The score stayed 100 / L3. The run log says something smaller:++- 22 recorded weekday runs (log prunes at 30 days)+- 22/22 outcome = report-only+- 0 escalations+- token field = constant 52k, not a measurement+- STATE.md last run 2026-08-27++An ASE workshop paper (arXiv:2608.21884) independently found 217 real loops in the wild and almost no STATE.md files. Most were event-triggered PR review. The tracker already was the state.++So we changed the repo:++1. README is one screen. Default `--tool claude`.+2. Thin loop starter: one GitHub Action, no STATE.md.+3. Loop Ready treats Last run older than 14 days as not-activity.+4. Honest story: https://github.com/cobusgreyling/loop-engineering/blob/main/stories/thirty-weekday-runs.md++Commands:++ npx @cobusgreyling/loop init . --pattern daily-triage --tool claude+ npx @cobusgreyling/loop doctor .++Or the thin version:++ npx @cobusgreyling/loop init . --pattern thin-loop --tool claude++Repo: https://github.com/cobusgreyling/loop-engineering+Paper: https://arxiv.org/abs/2608.21884++We are looking for people who actually run a loop (not just star) to add a row to docs/adopters.md.diff --git a/docs/index.html b/docs/index.htmlindex cc4625f..57ca69b 100644--- a/docs/index.html+++ b/docs/index.html@@ -75,7 +75,7 @@ title: Loop Engineering — Showcase</nav><header class="hero wrap">- <div class="badge">Open source · Tool-agnostic · Production-ready · L3 dogfood · 7 patterns · Interactive tools</div>+ <div class="badge">Open source · Tool-agnostic · Production-ready · 8 patterns · Interactive tools</div><h1>Stop prompting.<br>Design the loop.<br>Get a score.</h1><p class="lead">Run one command in any repo. <code>@cobusgreyling/loop</code> is the front door (<code>init</code> + <code>doctor</code>). <code>loop-init</code> still works. Prints your <strong>Loop Ready</strong> score plus the first run line.@@ -463,7 +463,7 @@ flowchart TB<span>terminal — minimal loop</span></div><pre><span class="comment"># Scaffold starter (or copy manually)</span>-npx @cobusgreyling/loop init . --pattern daily-triage --tool grok+npx @cobusgreyling/loop init . --pattern daily-triage --tool claude<span class="comment"># Score loop readiness (PRs get audit comments in CI)</span>npx @cobusgreyling/loop-audit . --suggest@@ -825,7 +825,7 @@ const PATTERNS = {patternId: 'ci-sweeper',costLevel: 'L2',costCadence: '15m',- npx: 'npx @cobusgreyling/loop init . --pattern ci-sweeper --tool grok',+ npx: 'npx @cobusgreyling/loop init . --pattern ci-sweeper --tool claude',loop: '/loop 15m Run ci-triage on failing CI. Update ci-sweeper-state.md. Fix only regressions in worktree. Max 3 attempts.',patternHref: 'https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/ci-sweeper.md',starterHref: 'https://github.com/cobusgreyling/loop-engineering/tree/main/starters/ci-sweeper'@@ -836,7 +836,7 @@ const PATTERNS = {patternId: 'pr-babysitter',costLevel: 'L1',costCadence: '10m',- npx: 'npx @cobusgreyling/loop init . --pattern pr-babysitter --tool grok',+ npx: 'npx @cobusgreyling/loop init . --pattern pr-babysitter --tool claude',loop: '/loop 10m Run pr-review-triage. Update pr-babysitter-state.md. Worktree + verifier. No auto-merge by default.',patternHref: 'https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/pr-babysitter.md',starterHref: 'https://github.com/cobusgreyling/loop-engineering/tree/main/starters/pr-babysitter'@@ -847,7 +847,7 @@ const PATTERNS = {patternId: 'daily-triage',costLevel: 'L1',costCadence: '1d',- npx: 'npx @cobusgreyling/loop init . --pattern daily-triage --tool grok',+ npx: 'npx @cobusgreyling/loop init . --pattern daily-triage --tool claude',loop: '/loop 1d Run loop-triage. Update STATE.md. No auto-fix in week one.',patternHref: 'https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/daily-triage.md',starterHref: 'https://github.com/cobusgreyling/loop-engineering/tree/main/starters/minimal-loop'@@ -858,7 +858,7 @@ const PATTERNS = {patternId: 'dependency-sweeper',costLevel: 'L2',costCadence: '6h',- npx: 'npx @cobusgreyling/loop init . --pattern dependency-sweeper --tool grok',+ npx: 'npx @cobusgreyling/loop init . --pattern dependency-sweeper --tool claude',loop: '/loop 6h Run dependency-triage. Patch-only auto-fix in worktree + verifier. Escalate majors.',patternHref: 'https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/dependency-sweeper.md',starterHref: 'https://github.com/cobusgreyling/loop-engineering/tree/main/starters/dependency-sweeper'@@ -869,7 +869,7 @@ const PATTERNS = {patternId: 'post-merge-cleanup',costLevel: 'L1',costCadence: '1d',- npx: 'npx @cobusgreyling/loop init . --pattern post-merge-cleanup --tool grok',+ npx: 'npx @cobusgreyling/loop init . --pattern post-merge-cleanup --tool claude',loop: '/loop 1d Run post-merge-scan on recent merges. Update post-merge-state.md. Small fixes only.',patternHref: 'https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/post-merge-cleanup.md',starterHref: 'https://github.com/cobusgreyling/loop-engineering/tree/main/starters/post-merge-cleanup'@@ -880,7 +880,7 @@ const PATTERNS = {patternId: 'changelog-drafter',costLevel: 'L1',costCadence: '1d',- npx: 'npx @cobusgreyling/loop init . --pattern changelog-drafter --tool grok',+ npx: 'npx @cobusgreyling/loop init . --pattern changelog-drafter --tool claude',loop: '/loop 1d Run changelog-scan + draft-release-notes. Write RELEASE_NOTES_DRAFT.md. Human review only.',patternHref: 'https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/changelog-drafter.md',starterHref: 'https://github.com/cobusgreyling/loop-engineering/tree/main/starters/changelog-drafter'@@ -891,7 +891,7 @@ const PATTERNS = {patternId: 'issue-triage',costLevel: 'L1',costCadence: '1d',- npx: 'npx @cobusgreyling/loop init . --pattern issue-triage --tool grok',+ npx: 'npx @cobusgreyling/loop init . --pattern issue-triage --tool claude',loop: '/loop 1d Run issue-triage. Update issue-triage-state.md. Propose labels and priorities only — no auto-close.',patternHref: 'https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/issue-triage.md',starterHref: 'https://github.com/cobusgreyling/loop-engineering/tree/main/starters/issue-triage'@@ -998,7 +998,7 @@ function setupSimulator() {} else if (score >= 78 && hasVerifier && hasState && !costReady) {level = 'L2';assess = 'Strong signals but missing cost observability — add budget + run log before L3.';- reco = 'npx @cobusgreyling/loop init . --pattern daily-triage --tool grok (scaffolds loop-budget.md + loop-run-log.md)';+ reco = 'npx @cobusgreyling/loop init . --pattern daily-triage --tool claude (scaffolds loop-budget.md + loop-run-log.md)';} else if (score >= 78 && hasVerifier && hasState && costReady && !hasActivity) {level = 'L2';assess = 'Strong structure but no proven loop runs yet.';@@ -1014,7 +1014,7 @@ function setupSimulator() {} else {level = 'L0';assess = 'Not loop-ready — start with a starter from this repo (minimal-loop or pr-babysitter).';- reco = 'npx @cobusgreyling/loop init . --pattern daily-triage --tool grok';+ reco = 'npx @cobusgreyling/loop init . --pattern daily-triage --tool claude';}scoreEl.textContent = score;diff --git a/docs/jobs.md b/docs/jobs.mdindex 2057211..e27453d 100644--- a/docs/jobs.md+++ b/docs/jobs.md@@ -5,6 +5,7 @@ This repo is a **pattern library for operating agents around a codebase** — tr| I want to… | Start here | Do **not** start here ||------------|------------|------------------------|| Keep a repo healthy (issues, CI, deps, changelog) | [Quickstart](./QUICKSTART.md) → `daily-triage` | Unattended L3 on day one |+| Run a loop as one GitHub Action with almost no files | [Thin loop](../starters/thin-loop/) | Expecting a high Loop Ready score || Land and babysit pull requests | [PR Babysitter](../patterns/pr-babysitter.md) | Merging from the loop || Fix a red build | [CI Sweeper](../patterns/ci-sweeper.md) | Patching flakes forever || Upgrade dependencies safely | [Dependency Sweeper](../patterns/dependency-sweeper.md) | Major bumps without a human |@@ -16,8 +17,8 @@ This repo is a **pattern library for operating agents around a codebase** — tr**Week-one rule still applies:** report only. Read what the loop writes before you let it act.```bash-npx @cobusgreyling/loop init . --pattern daily-triage --tool grok+npx @cobusgreyling/loop init . --pattern daily-triage --tool claudenpx @cobusgreyling/loop doctor .```-Swap `--tool` for `claude`, `codex`, or `opencode`. Unsure which pattern? [Pattern picker](https://cobusgreyling.github.io/loop-engineering/#interactive).+`--tool` defaults to `claude`. Swap for `grok`, `codex`, or `opencode`. Unsure which pattern? [Pattern picker](https://cobusgreyling.github.io/loop-engineering/#interactive).diff --git a/docs/last-run.json b/docs/last-run.jsonnew file mode 100644index 0000000..3dd6125--- /dev/null+++ b/docs/last-run.json@@ -0,0 +1,6 @@+{+ "schemaVersion": 1,+ "label": "last triage",+ "message": "2026-08-27",+ "color": "3ee8c5"+}diff --git a/docs/pattern-picker.md b/docs/pattern-picker.mdindex 945e0b9..d5d7262 100644--- a/docs/pattern-picker.md+++ b/docs/pattern-picker.md@@ -31,7 +31,7 @@ Estimate before you schedule:```bashnpx @cobusgreyling/loop-cost --pattern <id> --level L1-npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok # scaffolds loop-budget.md + loop-run-log.md+npx @cobusgreyling/loop-init . --pattern daily-triage --tool claude # scaffolds loop-budget.md + loop-run-log.md```| Situation | Prefer | Avoid (until budget + early-exit) |@@ -69,6 +69,6 @@ npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok # scaffoldsIf unsure, start with **Daily Triage at L1**. It teaches state discipline without auto-merge risk.```bash-npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok+npx @cobusgreyling/loop-init . --pattern daily-triage --tool claudenpx @cobusgreyling/loop-audit . --suggest```\ No newline at end of filediff --git a/docs/primitives-matrix.md b/docs/primitives-matrix.mdindex cd8c631..a7bd4ef 100644--- a/docs/primitives-matrix.md+++ b/docs/primitives-matrix.md@@ -79,7 +79,7 @@ For opencode, the transfer usually means `skills/`, `STATE.md`, `AGENTS.md`, andAudit after copying: `npx @cobusgreyling/loop-audit . --suggest`-Scaffold automatically: `npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok`+Scaffold automatically: `npx @cobusgreyling/loop-init . --pattern daily-triage --tool claude`## Goals (run-until-done)diff --git a/docs/refactor.md b/docs/refactor.mdindex 0b77433..6bffa76 100644--- a/docs/refactor.md+++ b/docs/refactor.md@@ -19,11 +19,11 @@ Use **both**: triage to list the slices, `/goal` (or a human) to implement one s### 0. Scaffold, do not code```bash-npx @cobusgreyling/loop init . --pattern daily-triage --tool opencode+npx @cobusgreyling/loop init . --pattern daily-triage --tool claudenpx @cobusgreyling/loop doctor .```-`--tool opencode` matches the usual “I want a CLI agent on a schedule” setup. `grok` / `claude` / `codex` work the same. This writes `STATE.md`, `LOOP.md`, `loop-budget.md`, `loop-run-log.md`, and constraints. **Week one: report only.**+Default `--tool` is `claude`. Use `opencode` for a CLI agent on cron; `grok` / `codex` work the same. This writes `STATE.md`, `LOOP.md`, `loop-budget.md`, `loop-run-log.md`, and constraints. **Week one: report only.**### 1. Inventory (L1)diff --git a/examples/README.md b/examples/README.mdindex 698b11a..ef5c397 100644--- a/examples/README.md+++ b/examples/README.md@@ -30,6 +30,7 @@ Start with [primitives-matrix.md](../docs/primitives-matrix.md) to map capabilit| Dependency Sweeper | [grok/dependency-sweeper.md](./grok/dependency-sweeper.md) | [claude-code/dependency-sweeper.md](./claude-code/dependency-sweeper.md) | [codex/dependency-sweeper.md](./codex/dependency-sweeper.md) | [openclaw/dependency-sweeper.md](./openclaw/dependency-sweeper.md) | [cursor/dependency-sweeper.md](./cursor/dependency-sweeper.md) | [windsurf/dependency-sweeper.md](./windsurf/dependency-sweeper.md) | [opencode/dependency-sweeper.md](./opencode/dependency-sweeper.md) | — | [github-actions/dependency-sweeper.yml](./github-actions/dependency-sweeper.yml) || Changelog Drafter | [grok/changelog-drafter.md](./grok/changelog-drafter.md) | [claude-code/changelog-drafter.md](./claude-code/changelog-drafter.md) | [codex/changelog-drafter.md](./codex/changelog-drafter.md) | [openclaw/changelog-drafter.md](./openclaw/changelog-drafter.md) | [cursor/changelog-drafter.md](./cursor/changelog-drafter.md) | [windsurf/changelog-drafter.md](./windsurf/changelog-drafter.md) | [opencode/changelog-drafter.md](./opencode/changelog-drafter.md) | — | [github-actions/changelog-drafter.yml](./github-actions/changelog-drafter.yml) || Issue Triage | [grok/issue-triage.md](./grok/issue-triage.md) | [claude-code/issue-triage.md](./claude-code/issue-triage.md) | [codex/issue-triage.md](./codex/issue-triage.md) | [openclaw/issue-triage.md](./openclaw/issue-triage.md) | [cursor/issue-triage.md](./cursor/issue-triage.md) | [windsurf/issue-triage.md](./windsurf/issue-triage.md) | [opencode/issue-triage.md](./opencode/issue-triage.md) | [hermes/issue-triage.md](./hermes/issue-triage.md) | [github-actions/issue-triage.yml](./github-actions/issue-triage.yml) |+| Thin Loop | — | — | — | — | — | — | — | — | [starters/thin-loop](../starters/thin-loop/) |L2 patterns ship multi-tool skills inside one starter folder — see `starters/<pattern>/`.diff --git a/examples/claude-code/daily-triage.md b/examples/claude-code/daily-triage.mdindex 764533b..13caf5c 100644--- a/examples/claude-code/daily-triage.md+++ b/examples/claude-code/daily-triage.md@@ -2,6 +2,8 @@Same pattern as Grok; different scheduling primitives.+Install skills via the [Claude Code plugin](./plugin.md), or copy folders below.+## Report-Only (Week 1)```bashdiff --git a/examples/claude-code/plugin.md b/examples/claude-code/plugin.mdnew file mode 100644index 0000000..51ce4ca--- /dev/null+++ b/examples/claude-code/plugin.md@@ -0,0 +1,26 @@+# Claude Code plugin++Install Loop Engineering skills inside Claude Code instead of copying folders by hand.++```bash+# from a Claude Code session, or the CLI:+claude plugin marketplace add cobusgreyling/loop-engineering+claude plugin install loop-engineering+```++This repo is the marketplace (`.claude-plugin/marketplace.json`). Skills live in [`skills/`](../../skills/).++Then scaffold the repo files (STATE, LOOP, budget) if they are missing:++```bash+npx @cobusgreyling/loop init . --pattern daily-triage --tool claude+npx @cobusgreyling/loop doctor .+```++First run (report-only):++```+/loop 1d $loop-triage — update STATE.md. Report-only week one.+```++If the plugin directory format changes upstream, the fallback remains: copy `starters/minimal-loop-claude/` as in [daily-triage.md](./daily-triage.md).diff --git a/examples/github-actions/README.md b/examples/github-actions/README.mdindex 1e28dee..ac56b90 100644--- a/examples/github-actions/README.md+++ b/examples/github-actions/README.md@@ -36,6 +36,7 @@ The state file schema and skills are tool-agnostic — only the invocation step| File | Trigger | Pattern ||------|---------|---------|| [daily-triage.yml](./daily-triage.yml) | Cron weekdays | Daily Triage |+| [thin-loop.yml](../../starters/thin-loop/.github/workflows/thin-loop.yml) | Issues/PRs + weekday cron | Thin Loop (no STATE.md) || [ci-sweeper.yml](./ci-sweeper.yml) | `workflow_run` failure | CI Sweeper || [post-merge-cleanup.yml](./post-merge-cleanup.yml) | Push to main + nightly | Post-Merge Cleanup || [issue-triage.yml](./issue-triage.yml) | Cron 2h weekdays + `issues` events | Issue Triage |diff --git a/patterns/README.md b/patterns/README.mdindex 8882bda..35d68b0 100644--- a/patterns/README.md+++ b/patterns/README.md@@ -21,13 +21,14 @@ Each pattern answers:| Post-Merge Cleanup | 1d–6h | Low | [post-merge-cleanup.md](./post-merge-cleanup.md) || Dependency Sweeper | 6h–1d | Medium | [dependency-sweeper.md](./dependency-sweeper.md) || Changelog Drafter | 1d | Low | [changelog-drafter.md](./changelog-drafter.md) |+| Thin Loop | event + 1d | Low | [thin-loop.md](./thin-loop.md) |Machine-readable index: [registry.yaml](./registry.yaml)## How to Use a Pattern1. Pick a pattern: [pattern-picker.md](../docs/pattern-picker.md)-2. Scaffold with `npx @cobusgreyling/loop-init . --pattern <name> --tool grok` (or `--tool opencode` / `--tool claude`) or copy from `starters/`+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 starter4. Set up scheduling (`/loop`, `scheduler_create`, GitHub Action, Codex Automation)5. Run week one in **L1 report-only** mode before enabling fixesdiff --git a/patterns/registry.yaml b/patterns/registry.yamlindex 3fc002d..59bc65a 100644--- a/patterns/registry.yaml+++ b/patterns/registry.yaml@@ -155,3 +155,25 @@ patterns:stable_fraction: 0.35suggested_daily_cap: 80000early_exit_required: false++ - id: thin-loop+ name: Thin Loop+ file: thin-loop.md+ goal: Report-only GitHub Action snapshot; the issue tracker is the state+ cadence: 1d+ risk: low+ tools: [github-actions, grok, claude-code, codex, opencode]+ skills: [loop-triage]+ state: STATE.md+ phases: [snapshot, summarize, optional-comment]+ human_gates: [all-writes]+ starter: starters/thin-loop+ week_one_mode: L1+ token_cost: low+ cost:+ tokens_noop: 1000+ tokens_report: 5000+ tokens_action: 1000+ stable_fraction: 0.9+ suggested_daily_cap: 20000+ early_exit_required: truediff --git a/patterns/thin-loop.md b/patterns/thin-loop.mdnew file mode 100644index 0000000..4e357a6--- /dev/null+++ b/patterns/thin-loop.md@@ -0,0 +1,68 @@+# Thin Loop++**Goal:** Run a report-only loop from GitHub Actions with almost no extra files. The issue tracker and the Actions job summary *are* the state.++This pattern exists because most loops in the wild already look like this. [Lulla et al. (2026)](https://arxiv.org/abs/2608.21884) confirmed 217 autonomous agent loops across 36k repositories: they commit **triggers** (cron / `pull_request` workflows), and almost never commit `STATE.md`. A thin loop matches that shape on purpose.++## When to use it++- You want a loop this week, not a methodology install.+- PR review or issue snapshot is the job; there is nothing to persist that GitHub does not already store.+- You will add `STATE.md` later **if** findings need to survive across runs (backlogs, attempt counts, budgets).++Do **not** start here if you need attempt caps, a maker/checker split, or a token kill switch — use [Daily Triage](./daily-triage.md) or [PR Babysitter](./pr-babysitter.md).++## Scheduling++| Surface | Trigger |+|---------|---------|+| GitHub Actions | `issues` / `pull_request` opened + weekday cron (see starter) |+| Claude / Grok / Codex | Optional later: `/loop 1d` reading the last job summary |++Week one: **L1**. The workflow writes `$GITHUB_STEP_SUMMARY`. It comments on the triggering issue/PR only when that thread does not already have a thin-loop marker.++## Required Skills++None required at L1. The workflow uses `gh` only.++- `loop-triage` — optional, if you later wire an agent into the Action via [loop-action](../tools/loop-action/)+- `loop-verifier` — optional, required before any write; maker/checker still applies once an implementer exists++State file: **not required**. GitHub issues/PRs carry the backlog. A `loop-run-log.md` line is optional proof for Loop Ready activity scoring.++## Typical cycle++1. Event or weekday cron fires.+2. Workflow lists open PRs and issues (`gh`).+3. Snapshot goes to the job summary.+4. If the event is an issue or PR, a short L1 comment is posted once.+5. Human reads the summary or comment. No code edits, no auto-merge.++## Verification Strategy++There is no implementer, so there is no verifier. The check is mechanical: `gh` succeeded and the summary is non-empty.++If you later invoke an agent, add [loop-verifier](../templates/SKILL.md.verifier) before any write — maker/checker, not the same session grading its own homework.++## Human hand-off++Everything is a hand-off. The loop does not close issues, apply labels, or push commits.++## Tool notes++- **GitHub Actions** is the native runtime. Starter: [starters/thin-loop](../starters/thin-loop/).+- Other tools: scaffold with `npx @cobusgreyling/loop init . --pattern thin-loop --tool claude` (tool suffix is ignored; you still get the workflow).++## Failure modes++| Failure | What to do |+|---------|------------|+| Comment spam | Marker `<!-- thin-loop -->` skips a second comment |+| Empty snapshot | `gh` auth — workflow needs `issues: write` / `pull-requests: write` |+| People expect a high Loop Ready score | Thin loops stay low until a dated run log or `STATE.md` Last run exists. That is intended. |++## Success metrics++- First green workflow run within 10 minutes of merge.+- No comments on threads that already had the marker.+- Zero file edits on `main` from the loop itself.diff --git a/scripts/ci-audit-gates.sh b/scripts/ci-audit-gates.shindex 0c0d583..eb31e69 100755--- a/scripts/ci-audit-gates.sh+++ b/scripts/ci-audit-gates.sh@@ -51,6 +51,12 @@ echo "=== Audit of starters (L1 gate) ==="FAILED=0for s in "$REPO_ROOT"/starters/*/; doNAME=$(basename "$s")+ # Thin loop is intentionally file-light (tracker is the state). Loop-audit+ # exits 2 below score 40; do not hold it to the L1 file-score gate.+ if [[ "$NAME" == "thin-loop" ]]; then+ echo "--- ${NAME}: skipped L1 file-score gate (by design)"+ continue+ fiSTARTER_AUDIT_FILE="$AUDIT_TMP_DIR/starter-${NAME}.json"node dist/cli.js "$s" --json > "$STARTER_AUDIT_FILE"STARTER_AUDIT_FILE="$STARTER_AUDIT_FILE" STARTER_NAME="$NAME" node -e 'diff --git a/scripts/empty-to-state-demo.sh b/scripts/empty-to-state-demo.shnew file mode 100755index 0000000..317bb2d--- /dev/null+++ b/scripts/empty-to-state-demo.sh@@ -0,0 +1,67 @@+#!/usr/bin/env bash+# Empty directory → scaffolded Daily Triage → first STATE.md.+# Run from the loop-engineering repo root. Does not publish or push.+set -euo pipefail++ROOT="$(cd "$(dirname "$0")/.." && pwd)"+INIT="$ROOT/tools/loop-init/dist/cli.js"+AUDIT="$ROOT/tools/loop-audit/dist/cli.js"++if [[ ! -f "$INIT" ]]; then+ echo "Build loop-init first: (cd tools/loop-init && npm test)" >&2+ exit 1+fi+if [[ ! -f "$AUDIT" ]]; then+ echo "Build loop-audit first: (cd tools/loop-audit && npm test)" >&2+ exit 1+fi++DIR="$(mktemp -d "${TMPDIR:-/tmp}/empty-to-state.XXXXXX")"+cleanup() { rm -rf "$DIR"; }+trap cleanup EXIT++echo "== 1. Empty git repo in $DIR"+git -C "$DIR" init -q+git -C "$DIR" config user.email "[email protected]"+git -C "$DIR" config user.name "Loop Demo"++echo "== 2. Scaffold Daily Triage (default tool is claude)"+node "$INIT" "$DIR" --pattern daily-triage --tool claude++echo+echo "== 3. Loop Ready (files only — no run yet)"+node "$AUDIT" "$DIR" || true++echo+echo "== 4. First STATE.md (before a real run)"+sed -n '1,20p' "$DIR/STATE.md"++echo+echo "== 5. Simulate one L1 run (what /loop writes)"+TS="$(date -u +%Y-%m-%dT%H:%M:%SZ)"+python3 - "$DIR/STATE.md" "$TS" <<'PY'+import pathlib, sys+p = pathlib.Path(sys.argv[1])+ts = sys.argv[2]+text = p.read_text()+text = text.replace("Last run: never", f"Last run: {ts} (empty-to-state demo)", 1) if "Last run: never" in text else (+ f"# Loop State\n\nLast run: {ts} (empty-to-state demo)\n\n## High Priority\n\n- Demo item: read this file tomorrow. Do not auto-fix.\n\n## Watch List\n"+ if "Last run:" not in text else+ __import__("re").sub(r"Last run:.*", f"Last run: {ts} (empty-to-state demo)", text, count=1)+)+if "## High Priority" in text and "Demo item:" not in text:+ text = text.replace("## High Priority", "## High Priority\n\n- Demo item: read this file tomorrow. Do not auto-fix.", 1)+p.write_text(text)+PY++git -C "$DIR" add STATE.md LOOP.md+git -C "$DIR" commit -qm "chore(loop): first L1 daily triage [demo]"++echo+echo "== 6. Loop Ready after one dated run + commit"+node "$AUDIT" "$DIR" || true++echo+echo "Done. That is the 10-minute path: init → doctor → one report-only run → commit STATE.md."+echo "Camera script: docs/distribution/empty-to-state-video.md"+echo "(temp dir removed on exit)"diff --git a/scripts/update-last-run-badge.mjs b/scripts/update-last-run-badge.mjsnew file mode 100755index 0000000..a111afb--- /dev/null+++ b/scripts/update-last-run-badge.mjs@@ -0,0 +1,45 @@+#!/usr/bin/env node+/**+ * Read STATE.md "Last run:" and write docs/last-run.json for a Shields endpoint badge.+ * Daily triage commits this file next to STATE.md.+ */+import { readFile, writeFile, mkdir } from 'node:fs/promises';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const STATE = path.join(ROOT, 'STATE.md');+const OUT = path.join(ROOT, 'docs', 'last-run.json');+const MAX_AGE_MS = 14 * 24 * 60 * 60 * 1000;++function parseLastRun(text) {+ const m = text.match(/Last run:\s*([0-9]{4}-[0-9]{2}-[0-9]{2}(?:[T ][0-9:.]+(?:Z|[+-][0-9:]+)?)?)/i);+ if (!m) return null;+ const raw = m[1].includes('T') || m[1].includes(' ') ? m[1].replace(' ', 'T') : `${m[1]}T00:00:00Z`;+ const d = new Date(raw);+ return Number.isNaN(d.getTime()) ? null : d;+}++const text = await readFile(STATE, 'utf8');+const when = parseLastRun(text);+const now = Date.now();++let message = 'unknown';+let color = '6e7681';+if (when) {+ message = when.toISOString().slice(0, 10);+ const age = now - when.getTime();+ if (age <= MAX_AGE_MS) color = '3ee8c5';+ else if (age <= 30 * 24 * 60 * 60 * 1000) color = 'd29922';+ else color = 'e5534b';+}++await mkdir(path.dirname(OUT), { recursive: true });+const payload = {+ schemaVersion: 1,+ label: 'last triage',+ message,+ color,+};+await writeFile(OUT, `${JSON.stringify(payload, null, 2)}\n`);+console.log(`last-run badge → ${message} (${color})`);diff --git a/skills/install-loop/SKILL.md b/skills/install-loop/SKILL.mdindex 16653b5..0e94420 100644--- a/skills/install-loop/SKILL.md+++ b/skills/install-loop/SKILL.md@@ -39,8 +39,9 @@ Do **not** deprecate or remove existing `loop-init` / `loop-audit` usages you fi| Post-merge TODOs | `post-merge-cleanup` || Stale release notes | `changelog-drafter` || Noisy issues | `issue-triage` |+ | One GitHub Action, almost no files | `thin-loop` |-3. **Pick tool** — `grok` | `claude` | `codex` | `opencode` (default `grok`).+3. **Pick tool** — `claude` | `grok` | `codex` | `opencode` (default `claude`).4. **Scaffold**```bashdiff --git a/starters/README.md b/starters/README.mdindex bf6cc54..fcea382 100644--- a/starters/README.md+++ b/starters/README.md@@ -3,8 +3,9 @@Clone-and-run scaffolds. Copy into your project — or use `loop-init`:```bash-npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok-npx @cobusgreyling/loop-init . -p pr-babysitter -t claude+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)@@ -15,6 +16,7 @@ npx @cobusgreyling/loop-init . -p pr-babysitter -t claude| [minimal-loop-claude](./minimal-loop-claude/) | Claude Code | `.claude/skills/` + `.claude/agents/` || [minimal-loop-codex](./minimal-loop-codex/) | Codex | `.codex/skills/` + `.codex/agents/` || [minimal-loop-opencode](./minimal-loop-opencode/) | Opencode | `skills/` + `AGENTS.md` |+| [thin-loop](./thin-loop/) | GitHub Actions (any tool) | `.github/workflows/thin-loop.yml` only |## L2 assisted patternsdiff --git a/starters/thin-loop/.github/workflows/thin-loop.yml b/starters/thin-loop/.github/workflows/thin-loop.ymlnew file mode 100644index 0000000..bd283ed--- /dev/null+++ b/starters/thin-loop/.github/workflows/thin-loop.yml@@ -0,0 +1,86 @@+# Thin loop — L1 snapshot. The tracker is the state; this workflow is the heartbeat.+# See starters/thin-loop/README.md and patterns/thin-loop.md.+name: Thin loop++on:+ issues:+ types: [opened]+ pull_request:+ types: [opened, ready_for_review]+ schedule:+ - cron: '0 8 * * 1-5'+ workflow_dispatch:++permissions:+ contents: read+ issues: write+ pull-requests: write++jobs:+ snapshot:+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@v4++ - name: Snapshot open work+ id: snap+ env:+ GH_TOKEN: ${{ github.token }}+ run: |+ {+ echo "# Thin loop snapshot $(date -u +%Y-%m-%dT%H:%M:%SZ)"+ echo+ echo "L1 report-only. No code edits, labels, or closes."+ echo+ echo "## Open pull requests"+ gh pr list --state open --limit 20 --json number,title,updatedAt \+ --jq '.[] | "- #\(.number) \(.title) (updated \(.updatedAt))"' \+ || echo "_none_"+ echo+ echo "## Open issues"+ gh issue list --state open --limit 20 --json number,title,updatedAt \+ --jq '.[] | "- #\(.number) \(.title) (updated \(.updatedAt))"' \+ || echo "_none_"+ } | tee "$GITHUB_STEP_SUMMARY" /tmp/thin-loop-summary.md++ - name: Comment once on the triggering item+ if: github.event_name == 'issues' || github.event_name == 'pull_request'+ env:+ GH_TOKEN: ${{ github.token }}+ EVENT_NAME: ${{ github.event_name }}+ ISSUE_NUMBER: ${{ github.event.issue.number }}+ PR_NUMBER: ${{ github.event.pull_request.number }}+ run: |+ set -euo pipefail+ MARKER='<!-- thin-loop -->'+ if [ "$EVENT_NAME" = "issues" ]; then+ NUMBER="$ISSUE_NUMBER"+ KIND=issue+ else+ NUMBER="$PR_NUMBER"+ KIND=pr+ fi+ if [ -z "$NUMBER" ]; then+ echo "No item number — skip comment"+ exit 0+ fi+ if [ "$KIND" = "issue" ]; then+ COMMENTS=$(gh api "repos/${{ github.repository }}/issues/${NUMBER}/comments" --jq '.[].body' || true)+ else+ COMMENTS=$(gh api "repos/${{ github.repository }}/issues/${NUMBER}/comments" --jq '.[].body' || true)+ fi+ if printf '%s' "$COMMENTS" | grep -q 'thin-loop'; then+ echo "Marker already present on #${NUMBER} — skip"+ exit 0+ fi+ {+ echo "$MARKER"+ echo "Thin loop saw this thread (L1). Snapshot is in the [workflow summary](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})."+ echo+ echo "No labels, closes, or code edits from this run."+ } > /tmp/thin-loop-comment.md+ if [ "$KIND" = "issue" ]; then+ gh issue comment "$NUMBER" --body-file /tmp/thin-loop-comment.md+ else+ gh pr comment "$NUMBER" --body-file /tmp/thin-loop-comment.md+ fidiff --git a/starters/thin-loop/LOOP.md b/starters/thin-loop/LOOP.mdnew file mode 100644index 0000000..55ca58b--- /dev/null+++ b/starters/thin-loop/LOOP.md@@ -0,0 +1,11 @@+# LOOP.md — Thin loop++- **Pattern:** thin-loop+- **Level:** L1 report-only+- **Cadence:** `issues`/`pull_request` opened + weekdays 08:00 UTC+- **State:** none. GitHub issues and PRs are the backlog. The Actions job summary is the report.+- **Writes:** job summary; at most one comment per thread (`<!-- thin-loop -->`).+- **Denylist:** no code edits, no labels, no closes, no pushes.+- **Kill switch:** disable `.github/workflows/thin-loop.yml` or cancel the workflow.++When a queue must survive across runs (attempt counts, budgets, watch lists), graduate to Daily Triage and add `STATE.md`.diff --git a/starters/thin-loop/README.md b/starters/thin-loop/README.mdnew file mode 100644index 0000000..54e0fdc--- /dev/null+++ b/starters/thin-loop/README.md@@ -0,0 +1,40 @@+# 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++```bash+npx @cobusgreyling/loop init . --pattern thin-loop --tool claude+```++Or copy:++```bash+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++| File | Purpose |+|------|---------|+| `.github/workflows/thin-loop.yml` | Event + weekday snapshot |+| `LOOP.md` | Cadence and gates in one page |++## What you do not get (on purpose)++- `STATE.md` — add it when findings must persist across runs ([Daily Triage](../minimal-loop-claude/)).+- Agent invocation — wire [loop-action](../../tools/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++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.diff --git a/stories/README.md b/stories/README.mdindex 265f519..6a8af1c 100644--- a/stories/README.md+++ b/stories/README.md@@ -20,6 +20,7 @@ Real-world loop engineering — including failures. Contribute yours via [CONTRI| [loop-worktree-week-two.md](./loop-worktree-week-two.md) | PR Babysitter + loop-worktree | Pair worktrees with `loop-context --check`; exact `outcome: failure` enum || [ci-sweeper-symptom-patching-and-circuit-breaker.md](./ci-sweeper-symptom-patching-and-circuit-breaker.md) | CI Sweeper | Symptom masking via test timeout inflation; denylist test setup files + `loop-context` circuit breaker || [loop-sandbox-ephemeral-isolation.md](./loop-sandbox-ephemeral-isolation.md) | CI Sweeper + loop-sandbox | Ephemeral worktree patch capture prevents hallucinated file deletions from dirtying working tree |+| [thirty-weekday-runs.md](./thirty-weekday-runs.md) | Daily Triage (this repo) | Loop Ready 100 hid 22 report-only runs and a hardcoded token field |**Template for new stories:**diff --git a/stories/thirty-weekday-runs.md b/stories/thirty-weekday-runs.mdnew file mode 100644index 0000000..d84b49b--- /dev/null+++ b/stories/thirty-weekday-runs.md@@ -0,0 +1,52 @@+# Thirty weekday runs — what Loop Ready 100 hid++**Pattern:** Daily Triage (this repository)+**Window:** 2026-07-29 → 2026-08-27 (the run log prunes at 30 days)+**Level:** L1 report-only, GitHub Actions++## Setup++`.github/workflows/daily-triage.yml` runs weekdays, writes `STATE.md` from open PRs and issues (`scripts/github-triage.mjs`), appends `loop-run-log.md`, and opens an automated PR. Humans merge. No auto-fix.++Loop Ready on this repo stayed **100 (L3)** for the whole window.++## What the log actually shows++| Metric | Value |+|--------|-------|+| Recorded runs | **22** (weekdays; log does not keep a full 60 days) |+| Outcome | **22 / 22 `report-only`** |+| Escalations | **0** |+| `items_found` sum | **28** (almost always 1 per morning) |+| `tokens_estimate` sum | **1,144,000** |++The token column is a **constant 52,000** written by the workflow, not a meter. Treat it as an upper bound we never measured. That is a loop-engineering own-goal: we tell everyone to log spend, then log a placeholder.++## What worked++- The heartbeat did not die. Automated PRs for `STATE.md` kept landing.+- Report-only held. Zero fix attempts, zero merges from the agent.+- The file that mattered to humans was the High Priority / Watch list, not the score.++## What broke (or never started)++- **Score ≠ work.** L3 on a loop that never leaves L1 is verifier theater for the badge.+- **Estimates are not observations.** `tokens_estimate: 52000` every row taught us nothing about cost.+- **Stale GFIs sat in Watch for 50+ days.** The loop reported them; nobody closed or rewrote them. A report-only loop still needs a human who reads.+- **We asked for 60 days of numbers and only kept 30.** The log’s own prune rule deleted the evidence a Show HN needs.++## Lesson++A loop that only writes `STATE.md` is still a cron job with a better filename — and that can be the right design. The failure is advertising L3 / 100 while the run log says `report-only` and the token field is hardcoded.++Changes that follow from this story: last-run badge on the README, Loop Ready weights **fresh runs** over files, and a [thin loop](../patterns/thin-loop.md) for teams who should not pretend they have state files.++## Metrics (copy for Show HN)++```+22 weekday Daily Triage runs+22 report-only, 0 escalations+Loop Ready 100 the whole time+token field: constant 52k, not measured+STATE.md last run: 2026-08-27+```diff --git a/tools/loop-audit/CHANGELOG.md b/tools/loop-audit/CHANGELOG.mdindex 52a34ff..4521f9d 100644--- a/tools/loop-audit/CHANGELOG.md+++ b/tools/loop-audit/CHANGELOG.md@@ -2,6 +2,15 @@All notable changes to `@cobusgreyling/loop-audit` are documented here.+## [1.9.0] - 2026-08-28++### Changed+- Loop activity requires a **fresh** `Last run` (≤14 days), a dated `loop-run-log.md` row, or a git commit that actually touches state / run-log files+- `LOOP.md` cadence text and a `triage` commit on README no longer count as activity+- Activity is worth 14 points (was 6)+- Missing `STATE.md` is a warning, not a fail, when `.github/workflows/thin-loop.yml` is present+- Companion funnels are not pushed to the top of `--suggest`+## [1.8.0] - 2026-07-29### Addeddiff --git a/tools/loop-audit/dist/auditor.d.ts b/tools/loop-audit/dist/auditor.d.tsindex 091aa9e..225de07 100644--- a/tools/loop-audit/dist/auditor.d.ts+++ b/tools/loop-audit/dist/auditor.d.ts@@ -86,6 +86,8 @@ export interface LoopSignals {export type { Finding };export interface AuditResult extends BaseAuditResult<'L0' | 'L1' | 'L2' | 'L3', LoopSignals> {}+/** Activity older than this does not count toward Loop Ready. */+export declare const ACTIVITY_MAX_AGE_MS: number;export declare function computeScore(signals: LoopSignals): {score: number;level: 'L0' | 'L1' | 'L2' | 'L3';diff --git a/tools/loop-audit/dist/auditor.js b/tools/loop-audit/dist/auditor.jsindex a1a906b..6e6b305 100644--- a/tools/loop-audit/dist/auditor.js+++ b/tools/loop-audit/dist/auditor.js@@ -38,7 +38,7 @@ const SCORE_WEIGHTS = {gateYaml: 3,constraintsFile: 4,constraintsSkill: 2,- loopActivity: 6,+ loopActivity: 14,/** Harness Runtime (harness-foundry) — stack, lock, sessions, emit, host */harnessStack: 4,harnessLock: 1,@@ -148,71 +148,77 @@ async function findSkills(root) {}return found;}+/** Activity older than this does not count toward Loop Ready. */+export const ACTIVITY_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1000;+function parseLastRunTimestamp(text) {+ const m = text.match(/Last run:\s*([0-9]{4}-[0-9]{2}-[0-9]{2}(?:[T ][0-9:.]+(?:Z|[+-][0-9:]+)?)?)/i);+ if (!m)+ return null;+ const raw = /T|\s/.test(m[1]) ? m[1].replace(' ', 'T') : `${m[1]}T00:00:00Z`;+ const d = new Date(raw);+ return Number.isNaN(d.getTime()) ? null : d;+}+function isFreshTimestamp(d, now = Date.now()) {+ const age = now - d.getTime();+ return age <= ACTIVITY_MAX_AGE_MS && age >= -60_000;+}async function detectLoopActivity(root) {const evidence = [];- const stateCandidates = [...STATE_FILES];- // 1. Look for "Last run" timestamps or dated entries inside state files (strong real-usage signal)- for (const sf of stateCandidates) {+ const now = Date.now();+ // 1. Fresh "Last run" timestamps in state files (not the mere presence of the words)+ for (const sf of STATE_FILES) {try {const p = path.join(root, sf);- if (await fileExists(p)) {- const txt = await readFile(p, 'utf8');- if (/last\s*run|last updated|^\s*-\s*\d{4}-\d{2}-\d{2}/im.test(txt) || /triage|loop run|changelog drafter/i.test(txt)) {- evidence.push(`state:${sf}`);- }- }+ if (!(await fileExists(p)))+ continue;+ const txt = await readFile(p, 'utf8');+ const when = parseLastRunTimestamp(txt);+ if (when && isFreshTimestamp(when, now))+ evidence.push(`state:${sf}:fresh`);}catch { }}- // 2. Presence of run log artifacts or dedicated log templates being used- const logHints = ['loop-run-log', 'run-log', 'loop.log', 'audit-report'];+ // 2. Dated JSON rows in the run log (file presence alone is not a run)try {- const entries = await readdir(root, { withFileTypes: true });- for (const e of entries) {- if (e.isFile() && logHints.some(h => e.name.toLowerCase().includes(h))) {- evidence.push(`log:${e.name}`);- }- }- }- catch { }- // 3. Workflow or LOOP evidence of scheduled execution- try {- const wfDir = path.join(root, '.github', 'workflows');- if (await fileExists(wfDir)) {- const wfs = await readdir(wfDir);- if (wfs.some(w => /triage|changelog|daily|loop|audit|pr-babysit/i.test(w))) {- evidence.push('github:loop-workflows');+ const logPath = path.join(root, 'loop-run-log.md');+ if (await fileExists(logPath)) {+ const txt = await readFile(logPath, 'utf8');+ for (const line of txt.split('\n')) {+ const trimmed = line.trim();+ if (!trimmed.startsWith('{'))+ continue;+ try {+ const row = JSON.parse(trimmed);+ if (!row.run_id)+ continue;+ const when = new Date(row.run_id);+ if (!Number.isNaN(when.getTime()) && isFreshTimestamp(when, now)) {+ evidence.push('log:loop-run-log.md:fresh');+ break;+ }+ }+ catch {+ // ignore invalid JSON lines+ }}}}catch { }- // 4. Light git history scan for loop-related commits (best dynamic proof)+ // 3. Git history on state / run-log files in the last 14 days — not arbitrary "triage" commit messagestry {- const log = execSync('git log --oneline -25 -- .', {+ const log = execSync('git log --since=14.days --oneline -- STATE.md loop-run-log.md "*state.md" "*-state.md"', {cwd: root,encoding: 'utf8',stdio: ['ignore', 'pipe', 'ignore'],timeout: 1500,});- const lower = log.toLowerCase();- if (/state\.md|loop|triage|changelog-drafter|post-merge|daily triage|audit/i.test(lower)) {- const firstMatch = log.trim().split('\n')[0] || '';- evidence.push(`git:${firstMatch.slice(0, 60)}`);- }+ const first = log.trim().split('\n')[0] || '';+ if (first)+ evidence.push(`git:${first.slice(0, 60)}`);}catch {// git not available or not a repo — ignore gracefully}- // 5. Check LOOP.md or a state for explicit "Last run" human-readable proof- try {- const loopP = path.join(root, 'LOOP.md');- if (await fileExists(loopP)) {- const txt = await readFile(loopP, 'utf8');- if (/last run|cadence|scheduled|automation/i.test(txt))- evidence.push('LOOP.md:active');- }- }- catch { }return { present: evidence.length > 0, evidence: Array.from(new Set(evidence)).slice(0, 4) };}export function computeScore(signals) {@@ -533,12 +539,35 @@ export async function auditProject(target) {memory,fleet,};+ const thinLoopWorkflow = await fileExists(path.join(root, '.github', 'workflows', 'thin-loop.yml'));if (!signals.stateFile.present) {- findings.push({ level: 'fail', message: 'No state file (STATE.md or pattern-specific state).' });- recommendations.push('Copy starters/minimal-loop/STATE.md.example (or -claude / -codex variant) to STATE.md');+ if (thinLoopWorkflow) {+ findings.push({+ level: 'warn',+ message: 'No STATE.md — acceptable for a thin loop if GitHub issues/PRs are the spine. Add STATE.md when findings must persist across runs.',+ });+ }+ else {+ findings.push({ level: 'fail', message: 'No state file (STATE.md or pattern-specific state).' });+ recommendations.push('Copy starters/minimal-loop/STATE.md.example (or -claude / -codex variant) to STATE.md — or scaffold starters/thin-loop if the tracker is the state');+ }}else {findings.push({ level: 'ok', message: `State file(s): ${statePaths.join(', ')}` });+ for (const sf of statePaths) {+ try {+ const txt = await readFile(path.join(root, sf), 'utf8');+ const when = parseLastRunTimestamp(txt);+ if (when && !isFreshTimestamp(when)) {+ findings.push({+ level: 'warn',+ message: `${sf} Last run is older than 14 days — files on disk are not loop activity.`,+ });+ recommendations.push(`Run the loop and commit ${sf} (or append loop-run-log.md) so Loop Ready can see a fresh timestamp`);+ }+ }+ catch { }+ }}if (!signals.triage.present) {findings.push({ level: 'warn', message: 'No triage skill detected.' });@@ -741,15 +770,8 @@ export async function auditProject(target) {}}const { score, level, assessment } = computeScore(signals);- if (score >= 80 && !signals.harness.stack) {- recommendations.unshift('Loop Ready 80+: version this loop as a harness — npx @cobusgreyling/loop-init . --with-foundry · showcase https://github.com/cobusgreyling/harness-foundry/blob/main/docs/showcase.md');- }- if (score >= 80 && !signals.memory.tiers) {- recommendations.unshift("Loop Ready 80+: version this loop's memory — npx @cobusgreyling/loop-init . --with-memory");- }- if (score >= 80 && !signals.fleet.registry) {- recommendations.unshift("Loop Ready 80+: version this loop for a fleet — npx @cobusgreyling/loop-init . --with-fleet");- }+ // Companion funnels stay available via --with-foundry / --with-memory / --with-fleet+ // but are not pushed to the top of week-one recommendations.const costReady = signals.cost.budgetDoc &&signals.cost.runLog &&signals.cost.loopMdBudget;diff --git a/tools/loop-audit/dist/cli.js b/tools/loop-audit/dist/cli.jsindex a0735c8..5cdd67a 100644--- a/tools/loop-audit/dist/cli.js+++ b/tools/loop-audit/dist/cli.js@@ -98,11 +98,11 @@ try {console.log(' # Then run: loop-audit . --suggest (again after changes)');console.log('');console.log(' # Or scaffold automatically:');- console.log(' npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok');+ console.log(' npx @cobusgreyling/loop-init . --pattern daily-triage --tool claude');console.log(' npx @cobusgreyling/loop-cost --pattern daily-triage --level L1');console.log('');- console.log(' # Version as a harness (harness-foundry) — one-command LE → Foundry funnel:');- console.log(' npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok --with-foundry');+ console.log(' # Optional companions (not required for week one):');+ console.log(' npx @cobusgreyling/loop-init . --pattern daily-triage --tool claude --with-foundry');console.log(' # or: npx @cobusgreyling/harness-foundry init --from loop-engineering:daily-triage');console.log(' npx @cobusgreyling/harness-foundry validate && npx @cobusgreyling/harness-foundry run --goal "Verify wiring"');console.log('');diff --git a/tools/loop-audit/dist/reporter.js b/tools/loop-audit/dist/reporter.jsindex 1484e3f..2fbec80 100644--- a/tools/loop-audit/dist/reporter.js+++ b/tools/loop-audit/dist/reporter.js@@ -45,27 +45,11 @@ export function formatHuman(r) {lines.push(`Share: npx @cobusgreyling/loop-audit ${auditTargetArg(r.target)} --badge`);lines.push('Docs: docs/loop-design-checklist.md');lines.push('Tip: rerun with --suggest for ready-to-paste copy commands from templates/starters.');- if (r.score >= 80 && !r.signals.harness?.stack) {- lines.push('');- lines.push('Next after Loop Ready 80+: version this loop as a harness');- lines.push(' npx @cobusgreyling/loop-init . --with-foundry');- lines.push(' Showcase: https://github.com/cobusgreyling/harness-foundry/blob/main/docs/showcase.md');- }- else if (r.signals.harness?.stack && !r.signals.harness.sessions) {+ if (r.signals.harness?.stack && !r.signals.harness.sessions) {lines.push('');lines.push('Harness stack present — run a session to earn session/trace credit:');lines.push(' npx @cobusgreyling/harness-foundry run --goal "Verify harness wiring"');}- if (r.score >= 80 && !r.signals.memory?.tiers) {- lines.push('');- lines.push('Next after Loop Ready 80+: add cross-session memory (memory-engineering)');- lines.push(' npx @cobusgreyling/loop-init . --with-memory');- }- if (r.score >= 80 && !r.signals.fleet?.registry) {- lines.push('');- lines.push('Next after Loop Ready 80+: version this loop for a fleet (fleet-engineering)');- lines.push(' npx @cobusgreyling/loop-init . --with-fleet');- }lines.push('');return lines.join('\n');}diff --git a/tools/loop-audit/package.json b/tools/loop-audit/package.jsonindex 184f412..d38b839 100644--- a/tools/loop-audit/package.json+++ b/tools/loop-audit/package.json@@ -1,6 +1,6 @@{"name": "@cobusgreyling/loop-audit",- "version": "1.8.0",+ "version": "1.9.0","description": "Loop engineering readiness auditor. Compute Loop Readiness Score (L0-L3), detect activity + harness runtime, and get actionable suggestions. npx @cobusgreyling/loop-audit . --suggest","type": "module","bin": {diff --git a/tools/loop-audit/src/auditor.ts b/tools/loop-audit/src/auditor.tsindex be1ee55..d66e870 100644--- a/tools/loop-audit/src/auditor.ts+++ b/tools/loop-audit/src/auditor.ts@@ -92,7 +92,7 @@ const SCORE_WEIGHTS = {gateYaml: 3,constraintsFile: 4,constraintsSkill: 2,- loopActivity: 6,+ loopActivity: 14,/** Harness Runtime (harness-foundry) — stack, lock, sessions, emit, host */harnessStack: 4,harnessLock: 1,@@ -207,71 +207,79 @@ async function findSkills(root: string): Promise<string[]> {return found;}+/** Activity older than this does not count toward Loop Ready. */+export const ACTIVITY_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1000;++function parseLastRunTimestamp(text: string): Date | null {+ const m = text.match(+ /Last run:\s*([0-9]{4}-[0-9]{2}-[0-9]{2}(?:[T ][0-9:.]+(?:Z|[+-][0-9:]+)?)?)/i,+ );+ if (!m) return null;+ const raw = /T|\s/.test(m[1]) ? m[1].replace(' ', 'T') : `${m[1]}T00:00:00Z`;+ const d = new Date(raw);+ return Number.isNaN(d.getTime()) ? null : d;+}++function isFreshTimestamp(d: Date, now = Date.now()): boolean {+ const age = now - d.getTime();+ return age <= ACTIVITY_MAX_AGE_MS && age >= -60_000;+}+async function detectLoopActivity(root: string): Promise<{ present: boolean; evidence: string[] }> {const evidence: string[] = [];- const stateCandidates = [...STATE_FILES];+ const now = Date.now();- // 1. Look for "Last run" timestamps or dated entries inside state files (strong real-usage signal)- for (const sf of stateCandidates) {+ // 1. Fresh "Last run" timestamps in state files (not the mere presence of the words)+ for (const sf of STATE_FILES) {try {const p = path.join(root, sf);- if (await fileExists(p)) {- const txt = await readFile(p, 'utf8');- if (/last\s*run|last updated|^\s*-\s*\d{4}-\d{2}-\d{2}/im.test(txt) || /triage|loop run|changelog drafter/i.test(txt)) {- evidence.push(`state:${sf}`);- }- }+ if (!(await fileExists(p))) continue;+ const txt = await readFile(p, 'utf8');+ const when = parseLastRunTimestamp(txt);+ if (when && isFreshTimestamp(when, now)) evidence.push(`state:${sf}:fresh`);} catch {}}- // 2. Presence of run log artifacts or dedicated log templates being used- const logHints = ['loop-run-log', 'run-log', 'loop.log', 'audit-report'];+ // 2. Dated JSON rows in the run log (file presence alone is not a run)try {- const entries = await readdir(root, { withFileTypes: true });- for (const e of entries) {- if (e.isFile() && logHints.some(h => e.name.toLowerCase().includes(h))) {- evidence.push(`log:${e.name}`);- }- }- } catch {}-- // 3. Workflow or LOOP evidence of scheduled execution- try {- const wfDir = path.join(root, '.github', 'workflows');- if (await fileExists(wfDir)) {- const wfs = await readdir(wfDir);- if (wfs.some(w => /triage|changelog|daily|loop|audit|pr-babysit/i.test(w))) {- evidence.push('github:loop-workflows');+ const logPath = path.join(root, 'loop-run-log.md');+ if (await fileExists(logPath)) {+ const txt = await readFile(logPath, 'utf8');+ for (const line of txt.split('\n')) {+ const trimmed = line.trim();+ if (!trimmed.startsWith('{')) continue;+ try {+ const row = JSON.parse(trimmed) as { run_id?: string };+ if (!row.run_id) continue;+ const when = new Date(row.run_id);+ if (!Number.isNaN(when.getTime()) && isFreshTimestamp(when, now)) {+ evidence.push('log:loop-run-log.md:fresh');+ break;+ }+ } catch {+ // ignore invalid JSON lines+ }}}} catch {}- // 4. Light git history scan for loop-related commits (best dynamic proof)+ // 3. Git history on state / run-log files in the last 14 days — not arbitrary "triage" commit messagestry {- const log = execSync('git log --oneline -25 -- .', {- cwd: root,- encoding: 'utf8',- stdio: ['ignore', 'pipe', 'ignore'],- timeout: 1500,- });- const lower = log.toLowerCase();- if (/state\.md|loop|triage|changelog-drafter|post-merge|daily triage|audit/i.test(lower)) {- const firstMatch = log.trim().split('\n')[0] || '';- evidence.push(`git:${firstMatch.slice(0, 60)}`);- }+ const log = execSync(+ 'git log --since=14.days --oneline -- STATE.md loop-run-log.md "*state.md" "*-state.md"',+ {+ cwd: root,+ encoding: 'utf8',+ stdio: ['ignore', 'pipe', 'ignore'],+ timeout: 1500,+ },+ );+ const first = log.trim().split('\n')[0] || '';+ if (first) evidence.push(`git:${first.slice(0, 60)}`);} catch {// git not available or not a repo — ignore gracefully}- // 5. Check LOOP.md or a state for explicit "Last run" human-readable proof- try {- const loopP = path.join(root, 'LOOP.md');- if (await fileExists(loopP)) {- const txt = await readFile(loopP, 'utf8');- if (/last run|cadence|scheduled|automation/i.test(txt)) evidence.push('LOOP.md:active');- }- } catch {}-return { present: evidence.length > 0, evidence: Array.from(new Set(evidence)).slice(0, 4) };}@@ -579,11 +587,33 @@ export async function auditProject(target: string): Promise<AuditResult> {fleet,};+ const thinLoopWorkflow = await fileExists(path.join(root, '.github', 'workflows', 'thin-loop.yml'));+if (!signals.stateFile.present) {- findings.push({ level: 'fail', message: 'No state file (STATE.md or pattern-specific state).' });- recommendations.push('Copy starters/minimal-loop/STATE.md.example (or -claude / -codex variant) to STATE.md');+ if (thinLoopWorkflow) {+ findings.push({+ level: 'warn',+ message: 'No STATE.md — acceptable for a thin loop if GitHub issues/PRs are the spine. Add STATE.md when findings must persist across runs.',+ });+ } else {+ findings.push({ level: 'fail', message: 'No state file (STATE.md or pattern-specific state).' });+ recommendations.push('Copy starters/minimal-loop/STATE.md.example (or -claude / -codex variant) to STATE.md — or scaffold starters/thin-loop if the tracker is the state');+ }} else {findings.push({ level: 'ok', message: `State file(s): ${statePaths.join(', ')}` });+ for (const sf of statePaths) {+ try {+ const txt = await readFile(path.join(root, sf), 'utf8');+ const when = parseLastRunTimestamp(txt);+ if (when && !isFreshTimestamp(when)) {+ findings.push({+ level: 'warn',+ message: `${sf} Last run is older than 14 days — files on disk are not loop activity.`,+ });+ recommendations.push(`Run the loop and commit ${sf} (or append loop-run-log.md) so Loop Ready can see a fresh timestamp`);+ }+ } catch {}+ }}if (!signals.triage.present) {@@ -795,23 +825,8 @@ export async function auditProject(target: string): Promise<AuditResult> {const { score, level, assessment } = computeScore(signals);- if (score >= 80 && !signals.harness.stack) {- recommendations.unshift(- 'Loop Ready 80+: version this loop as a harness — npx @cobusgreyling/loop-init . --with-foundry · showcase https://github.com/cobusgreyling/harness-foundry/blob/main/docs/showcase.md',- );- }-- if (score >= 80 && !signals.memory.tiers) {- recommendations.unshift(- "Loop Ready 80+: version this loop's memory — npx @cobusgreyling/loop-init . --with-memory",- );- }-- if (score >= 80 && !signals.fleet.registry) {- recommendations.unshift(- "Loop Ready 80+: version this loop for a fleet — npx @cobusgreyling/loop-init . --with-fleet",- );- }+ // Companion funnels stay available via --with-foundry / --with-memory / --with-fleet+ // but are not pushed to the top of week-one recommendations.const costReady =signals.cost.budgetDoc &&diff --git a/tools/loop-audit/src/cli.ts b/tools/loop-audit/src/cli.tsindex d5795b3..1408c2b 100644--- a/tools/loop-audit/src/cli.ts+++ b/tools/loop-audit/src/cli.ts@@ -97,11 +97,11 @@ try {console.log(' # Then run: loop-audit . --suggest (again after changes)');console.log('');console.log(' # Or scaffold automatically:');- console.log(' npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok');+ console.log(' npx @cobusgreyling/loop-init . --pattern daily-triage --tool claude');console.log(' npx @cobusgreyling/loop-cost --pattern daily-triage --level L1');console.log('');- console.log(' # Version as a harness (harness-foundry) — one-command LE → Foundry funnel:');- console.log(' npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok --with-foundry');+ console.log(' # Optional companions (not required for week one):');+ console.log(' npx @cobusgreyling/loop-init . --pattern daily-triage --tool claude --with-foundry');console.log(' # or: npx @cobusgreyling/harness-foundry init --from loop-engineering:daily-triage');console.log(' npx @cobusgreyling/harness-foundry validate && npx @cobusgreyling/harness-foundry run --goal "Verify wiring"');console.log('');diff --git a/tools/loop-audit/src/reporter.ts b/tools/loop-audit/src/reporter.tsindex 432dbe7..ac20793 100644--- a/tools/loop-audit/src/reporter.ts+++ b/tools/loop-audit/src/reporter.ts@@ -52,28 +52,11 @@ export function formatHuman(r: AuditResult): string {lines.push(`Share: npx @cobusgreyling/loop-audit ${auditTargetArg(r.target)} --badge`);lines.push('Docs: docs/loop-design-checklist.md');lines.push('Tip: rerun with --suggest for ready-to-paste copy commands from templates/starters.');- if (r.score >= 80 && !r.signals.harness?.stack) {- lines.push('');- lines.push('Next after Loop Ready 80+: version this loop as a harness');- lines.push(' npx @cobusgreyling/loop-init . --with-foundry');- lines.push(' Showcase: https://github.com/cobusgreyling/harness-foundry/blob/main/docs/showcase.md');- } else if (r.signals.harness?.stack && !r.signals.harness.sessions) {+ if (r.signals.harness?.stack && !r.signals.harness.sessions) {lines.push('');lines.push('Harness stack present — run a session to earn session/trace credit:');lines.push(' npx @cobusgreyling/harness-foundry run --goal "Verify harness wiring"');}-- if (r.score >= 80 && !r.signals.memory?.tiers) {- lines.push('');- lines.push('Next after Loop Ready 80+: add cross-session memory (memory-engineering)');- lines.push(' npx @cobusgreyling/loop-init . --with-memory');- }-- if (r.score >= 80 && !r.signals.fleet?.registry) {- lines.push('');- lines.push('Next after Loop Ready 80+: version this loop for a fleet (fleet-engineering)');- lines.push(' npx @cobusgreyling/loop-init . --with-fleet');- }lines.push('');return lines.join('\n');}diff --git a/tools/loop-audit/test/auditor.test.mjs b/tools/loop-audit/test/auditor.test.mjsindex 9c9f34f..2e48ee9 100644--- a/tools/loop-audit/test/auditor.test.mjs+++ b/tools/loop-audit/test/auditor.test.mjs@@ -289,8 +289,28 @@ test('auditProject: missing fleet recommends --with-fleet', async () => {}});-test('auditProject: git commit with triage counts as loop activity', async () => {+test('auditProject: git commit of STATE.md counts as loop activity', async () => {const dir = await mkdtemp(path.join(tmpdir(), 'loop-audit-git-'));+ try {+ execSync('git init', { cwd: dir, stdio: 'ignore' });+ execSync('git config user.email "[email protected]"', { cwd: dir, stdio: 'ignore' });+ execSync('git config user.name "Test"', { cwd: dir, stdio: 'ignore' });+ const today = new Date().toISOString();+ await writeFile(path.join(dir, 'STATE.md'), `# State\n\nLast run: ${today}\n`);+ execSync('git add STATE.md', { cwd: dir, stdio: 'ignore' });+ execSync('git commit -m "chore: daily triage update"', { cwd: dir, stdio: 'ignore' });+ const result = await auditProject(dir);+ assert.ok(result.signals.loopActivity.present);+ assert.ok(+ result.signals.loopActivity.evidence.some((e) => e.startsWith('git:') || e.startsWith('state:')),+ );+ } finally {+ await rm(dir, { recursive: true, force: true });+ }+});++test('auditProject: triage commit that does not touch state is not activity', async () => {+ const dir = await mkdtemp(path.join(tmpdir(), 'loop-audit-git-readme-'));try {execSync('git init', { cwd: dir, stdio: 'ignore' });execSync('git config user.email "[email protected]"', { cwd: dir, stdio: 'ignore' });@@ -299,8 +319,44 @@ test('auditProject: git commit with triage counts as loop activity', async () =>execSync('git add README.md', { cwd: dir, stdio: 'ignore' });execSync('git commit -m "chore: daily triage update"', { cwd: dir, stdio: 'ignore' });const result = await auditProject(dir);- assert.ok(result.signals.loopActivity.present);- assert.ok(result.signals.loopActivity.evidence.some((e) => e.startsWith('git:')));+ assert.equal(result.signals.loopActivity.present, false);+ } finally {+ await rm(dir, { recursive: true, force: true });+ }+});++test('auditProject: stale Last run is not activity', async () => {+ const dir = await mkdtemp(path.join(tmpdir(), 'loop-audit-stale-'));+ try {+ await writeFile(path.join(dir, 'STATE.md'), '# State\n\nLast run: 2020-01-01T00:00:00Z\n');+ const result = await auditProject(dir);+ assert.equal(result.signals.loopActivity.present, false);+ assert.ok(result.findings.some((f) => /older than 14 days/i.test(f.message)));+ } finally {+ await rm(dir, { recursive: true, force: true });+ }+});++test('auditProject: LOOP.md cadence text is not activity', async () => {+ const dir = await mkdtemp(path.join(tmpdir(), 'loop-audit-loopmd-'));+ try {+ await writeFile(path.join(dir, 'LOOP.md'), '# Loop\nCadence: scheduled daily automation.\nLast run documented here as a heading only.\n');+ const result = await auditProject(dir);+ assert.equal(result.signals.loopActivity.present, false);+ } finally {+ await rm(dir, { recursive: true, force: true });+ }+});++test('auditProject: thin-loop workflow without STATE.md is a warning not a fail', async () => {+ const dir = await mkdtemp(path.join(tmpdir(), 'loop-audit-thin-'));+ try {+ await mkdir(path.join(dir, '.github', 'workflows'), { recursive: true });+ await writeFile(path.join(dir, '.github', 'workflows', 'thin-loop.yml'), 'name: Thin loop\n');+ const result = await auditProject(dir);+ assert.equal(result.signals.stateFile.present, false);+ assert.ok(result.findings.some((f) => f.level === 'warn' && /thin loop/i.test(f.message)));+ assert.ok(!result.findings.some((f) => f.level === 'fail' && /No state file/i.test(f.message)));} finally {await rm(dir, { recursive: true, force: true });}diff --git a/tools/loop-init/CHANGELOG.md b/tools/loop-init/CHANGELOG.mdindex f433f86..2bf7747 100644--- a/tools/loop-init/CHANGELOG.md+++ b/tools/loop-init/CHANGELOG.md@@ -4,6 +4,15 @@ All notable changes to `@cobusgreyling/loop-init` are documented here.## [Unreleased]+## [1.7.0] - 2026-08-28++### Added+- `thin-loop` pattern: one GitHub Action, no `STATE.md` / skills / budget files+- Default `--tool` is `claude`++### Changed+- Companion CTAs (`--with-foundry`, `--with-memory`, `--with-fleet`) print only when those flags are passed+## [1.6.0] - 2026-07-29### Addeddiff --git a/tools/loop-init/README.md b/tools/loop-init/README.mdindex 0fa81e0..b0f3e4d 100644--- a/tools/loop-init/README.md+++ b/tools/loop-init/README.md@@ -2,19 +2,19 @@Scaffold loop engineering starters into your project by pattern and tool.-**npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok** works immediately.+**npx @cobusgreyling/loop-init . --pattern daily-triage --tool claude** works immediately.See [docs/loop-init-validation.md](../../docs/loop-init-validation.md) for a validated pattern × --tool matrix.## Install & Run```bash-npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok+npx @cobusgreyling/loop-init . --pattern daily-triage --tool claudenpx @cobusgreyling/loop-init . --pattern daily-triage --tool opencodenpx @cobusgreyling/loop-init . -p pr-babysitter -t claudenpx @cobusgreyling/loop-init . -p dependency-sweeper --dry-run# One-command LE → harness-foundry funnel:-npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok --with-foundry+npx @cobusgreyling/loop-init . --pattern daily-triage --tool claude --with-foundry```See [docs/RELEASE.md](../../docs/RELEASE.md) for npm publish tags. The published package bundles `starters/` and `templates/` from this monorepo.diff --git a/tools/loop-init/dist/cli.js b/tools/loop-init/dist/cli.jsindex 63a21f0..daaa513 100644--- a/tools/loop-init/dist/cli.js+++ b/tools/loop-init/dist/cli.js@@ -16,6 +16,7 @@ const PATTERN_STARTERS = {'post-merge-cleanup': 'post-merge-cleanup','changelog-drafter': 'changelog-drafter','issue-triage': 'issue-triage',+ 'thin-loop': 'thin-loop',};const TOOL_SUFFIX = {grok: '',@@ -23,6 +24,8 @@ const TOOL_SUFFIX = {codex: '-codex',opencode: '-opencode',};+/** Patterns with a single tool-agnostic starter (no -claude / -codex suffix). */+const TOOL_AGNOSTIC = new Set(['thin-loop']);const L2_PATTERNS = new Set(['ci-sweeper', 'dependency-sweeper']);const PATTERNS_NEEDING_FIX = new Set(['pr-babysitter',@@ -44,6 +47,7 @@ const STATE_FILES = {'post-merge-cleanup': 'post-merge-state.md','changelog-drafter': 'changelog-drafter-state.md','issue-triage': 'issue-triage-state.md',+ 'thin-loop': 'STATE.md',};/** Mirrors patterns/registry.yaml cost caps — used when scaffolding observability files. */const PATTERN_BUDGET = {@@ -54,6 +58,7 @@ const PATTERN_BUDGET = {'post-merge-cleanup': { name: 'Post-Merge Cleanup', maxRunsPerDay: 1, dailyCap: 200_000, maxSpawnsL1: 0, maxSpawnsL2: 2 },'changelog-drafter': { name: 'Changelog Drafter', maxRunsPerDay: 1, dailyCap: 100_000, maxSpawnsL1: 0, maxSpawnsL2: 2 },'issue-triage': { name: 'Issue Triage', maxRunsPerDay: 12, dailyCap: 80_000, maxSpawnsL1: 0, maxSpawnsL2: 1 },+ 'thin-loop': { name: 'Thin Loop', maxRunsPerDay: 24, dailyCap: 20_000, maxSpawnsL1: 0, maxSpawnsL2: 0 },};/** Map LE patterns → harness-foundry stack presets (report-only → minimal, fix → implementer). */const PATTERN_FOUNDRY_PRESET = {@@ -64,6 +69,7 @@ const PATTERN_FOUNDRY_PRESET = {'ci-sweeper': 'implementer','dependency-sweeper': 'implementer','post-merge-cleanup': 'implementer',+ 'thin-loop': 'minimal',};const FOUNDRY_SHOWCASE = 'https://github.com/cobusgreyling/harness-foundry/blob/main/docs/showcase.md';const MINIMAX_DEFAULT_MODEL = 'MiniMax-M3';@@ -130,7 +136,7 @@ ${endpoints}`;}function parseArgs(argv) {let pattern = 'daily-triage';- let tool = 'grok';+ let tool = 'claude';let target = '.';let dryRun = false;let withFoundry = false;@@ -172,7 +178,7 @@ function foundryStackYaml(stackName, pattern, preset, provider = 'anthropic', re? minimaxInterfaceYaml(model, region): ` - primitive: model/anthropicconfig:- model: claude-sonnet-4-20250514`;+ model: claude-sonnet-4-6`;return `name: ${stackName}version: 1.0.0description: "loop-engineering ${pattern} → implementer harness (loop-init --with-foundry)"@@ -295,51 +301,27 @@ async function scaffoldMemory(targetDir, templatesRoot, dryRun) {}}function printFoundryCta(opts) {- const { pattern, tool, withFoundry, score, preset } = opts;+ const { pattern, withFoundry, preset } = opts;+ if (!withFoundry)+ return;const mapped = preset ?? PATTERN_FOUNDRY_PRESET[pattern];console.log('');- if (withFoundry) {- console.log(`Harness stack ready (.foundry/, preset: ${mapped} for ${pattern})`);- console.log(' npx @cobusgreyling/harness-foundry validate');- console.log(' npx @cobusgreyling/harness-foundry run --goal "Verify harness wiring"');- console.log(` Showcase: ${FOUNDRY_SHOWCASE}`);- return;- }- const highReady = score !== null && score >= 80;- console.log(highReady- ? 'Next after Loop Ready 80+: version this loop as a harness'- : 'Optional: make this loop a versioned harness (harness-foundry)');- console.log(` npx @cobusgreyling/loop-init . --pattern ${pattern} --tool ${tool} --with-foundry`);- console.log(` # or: npx @cobusgreyling/harness-foundry init --from loop-engineering:${pattern}`);- if (highReady) {- console.log(` Showcase: ${FOUNDRY_SHOWCASE}`);- }+ console.log(`Harness stack ready (.foundry/, preset: ${mapped} for ${pattern})`);+ console.log(' npx @cobusgreyling/harness-foundry validate');+ console.log(' npx @cobusgreyling/harness-foundry run --goal "Verify harness wiring"');+ console.log(` Showcase: ${FOUNDRY_SHOWCASE}`);}function printFleetCta(opts) {- const { pattern, tool, withFleet, score } = opts;- console.log('');- if (withFleet) {- console.log('Fleet engineering stack ready (fleet-registry.md, fleet-inbox.md)');+ if (!opts.withFleet)return;- }- const highReady = score !== null && score >= 80;- console.log(highReady- ? 'Next after Loop Ready 80+: version this loop for a fleet (fleet-engineering)'- : 'Optional: add fleet-engineering for multi-agent populations');- console.log(` npx @cobusgreyling/loop-init . --pattern ${pattern} --tool ${tool} --with-fleet`);+ console.log('');+ console.log('Fleet engineering stack ready (fleet-registry.md, fleet-inbox.md)');}function printMemoryCta(opts) {- const { pattern, tool, withMemory, score } = opts;- console.log('');- if (withMemory) {- console.log('Memory engineering stack ready (memory-tiers.md, memory-budget.md)');+ if (!opts.withMemory)return;- }- const highReady = score !== null && score >= 80;- console.log(highReady- ? "Next after Loop Ready 80+: version this loop's memory (memory-engineering)"- : 'Optional: add memory-engineering for cross-session knowledge');- console.log(` npx @cobusgreyling/loop-init . --pattern ${pattern} --tool ${tool} --with-memory`);+ console.log('');+ console.log('Memory engineering stack ready (memory-tiers.md, memory-budget.md)');}async function exists(p) {try {@@ -424,6 +406,7 @@ const LEDGER_GOAL = {'post-merge-cleanup': 'Clean up regressions from recent merges','changelog-drafter': 'Draft accurate release notes','issue-triage': 'Triage the open issue queue',+ 'thin-loop': 'Snapshot open issues and PRs; do not edit code',};/*** Readiness level seeded into loop-ledger.json so the loop-guard skill can@@ -440,6 +423,7 @@ const LEDGER_LEVEL = {'post-merge-cleanup': 'L2','changelog-drafter': 'L1','issue-triage': 'L1',+ 'thin-loop': 'L1',};/*** Fix-capable loops retry actions, so they need a circuit breaker: scaffold the@@ -592,6 +576,12 @@ function firstLoopCommand(pattern, tool) {codex: 'Automation 2h: issue-triage → issue-triage-state.md. Propose only.',opencode: `${OPENCODE_RUN} "Run issue-triage. Update issue-triage-state.md. Propose labels only — no auto-apply."`,},+ 'thin-loop': {+ grok: 'Commit .github/workflows/thin-loop.yml. The Action is the loop — no STATE.md, no /loop required.',+ claude: 'Commit .github/workflows/thin-loop.yml. The Action is the loop — no STATE.md, no /loop required.',+ codex: 'Commit .github/workflows/thin-loop.yml. The Action is the loop — no STATE.md required.',+ opencode: 'Commit .github/workflows/thin-loop.yml. The Action is the loop — no STATE.md required.',+ },};return cmds[pattern][tool];}@@ -662,10 +652,11 @@ Patterns:post-merge-cleanupchangelog-drafter (new low-risk release notes pattern)issue-triage (new low-risk issue queue health companion to daily triage)+ thin-loop (GitHub Action snapshot — no STATE.md)Options:-p, --pattern Pattern to scaffold- -t, --tool Tool target (default: grok)+ -t, --tool Tool target (default: claude)--with-foundry Also scaffold .foundry/ stack (harness-foundry runtime)--with-memory Also scaffold memory-engineering tiers and budget--with-fleet Also scaffold fleet-engineering registry and inbox@@ -680,8 +671,9 @@ Foundry presets (with --with-foundry):fix-capable patterns → implementerExamples:- npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok- npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok --with-foundry+ npx @cobusgreyling/loop-init . --pattern daily-triage --tool claude+ npx @cobusgreyling/loop-init . --pattern thin-loop --tool claude+ npx @cobusgreyling/loop-init . --pattern daily-triage --tool claude --with-foundrynpx @cobusgreyling/loop-init . -p pr-babysitter -t claude --with-foundrynpx @cobusgreyling/loop-init . -p ci-sweeper -t grok --with-foundry --model-provider minimaxnpx @cobusgreyling/loop-init . -p ci-sweeper -t grok --with-foundry --model-provider minimax --region cn_zh --model MiniMax-M2.7@@ -719,7 +711,7 @@ Examples:}const targetDir = path.resolve(target);const baseStarter = PATTERN_STARTERS[pattern];- const suffix = TOOL_SUFFIX[tool];+ const suffix = TOOL_AGNOSTIC.has(pattern) ? '' : TOOL_SUFFIX[tool];const starterName = `${baseStarter}${suffix}`;const startersRoot = await resolveBundledOrMonorepo('starters');const templatesRoot = await resolveBundledOrMonorepo('templates');@@ -800,12 +792,23 @@ Examples:if (await exists(loopMd)) {await copyFile(loopMd, path.join(targetDir, 'LOOP.md'), dryRun);}- await copyL2Templates(pattern, tool, targetDir, templatesRoot, dryRun);- await scaffoldCircuitBreaker(pattern, tool, targetDir, templatesRoot, dryRun);- await scaffoldObservability(pattern, tool, targetDir, templatesRoot, dryRun);- await scaffoldIntake(pattern, tool, targetDir, templatesRoot, dryRun);- await scaffoldConstraints(targetDir, templatesRoot, tool, dryRun);- if (tool !== 'opencode' && !dryRun && !(await exists(path.join(targetDir, 'AGENTS.md')))) {+ const wfSrc = path.join(effectiveStarter, '.github', 'workflows');+ if (await exists(wfSrc)) {+ const wfEntries = await readDirNames(wfSrc);+ for (const entry of wfEntries) {+ if (!entry.endsWith('.yml') && !entry.endsWith('.yaml'))+ continue;+ await copyFile(path.join(wfSrc, entry), path.join(targetDir, '.github', 'workflows', entry), dryRun);+ }+ }+ if (pattern !== 'thin-loop') {+ await copyL2Templates(pattern, tool, targetDir, templatesRoot, dryRun);+ await scaffoldCircuitBreaker(pattern, tool, targetDir, templatesRoot, dryRun);+ await scaffoldObservability(pattern, tool, targetDir, templatesRoot, dryRun);+ await scaffoldIntake(pattern, tool, targetDir, templatesRoot, dryRun);+ await scaffoldConstraints(targetDir, templatesRoot, tool, dryRun);+ }+ if (tool !== 'opencode' && pattern !== 'thin-loop' && !dryRun && !(await exists(path.join(targetDir, 'AGENTS.md')))) {const agentsTemplate = `# AGENTS.md## Test commandsdiff --git a/tools/loop-init/package.json b/tools/loop-init/package.jsonindex faec662..e9508dd 100644--- a/tools/loop-init/package.json+++ b/tools/loop-init/package.json@@ -1,6 +1,6 @@{"name": "@cobusgreyling/loop-init",- "version": "1.6.0",+ "version": "1.7.0","description": "Scaffold loop engineering patterns and starters into any project. Optional --with-foundry harness stack. Supports Grok, Claude Code, Codex, Opencode and more. npx @cobusgreyling/loop-init . --pattern daily-triage --tool opencode --with-foundry","type": "module","bin": {diff --git a/tools/loop-init/registry.yaml b/tools/loop-init/registry.yamlindex c29c72b..59bc65a 100644--- a/tools/loop-init/registry.yaml+++ b/tools/loop-init/registry.yaml@@ -52,7 +52,7 @@ patterns:goal: React to failing CI with minimal fixes and escalationcadence: 5m-15mrisk: medium- tools: [grok, claude-code, codex, openclaw, opencode, github-actions]+ tools: [grok, claude-code, codex, openclaw, opencode, github-actions, windsurf]skills: [ci-triage, minimal-fix]state: ci-sweeper-state.mdphases: [detect, classify, fix, verify, escalate]@@ -96,7 +96,7 @@ patterns:goal: Discover, safely apply, and verify dependency + vulnerability updates with human gates on risky changescadence: 6h-1drisk: medium- tools: [grok, claude-code, codex, openclaw, opencode, github-actions]+ tools: [grok, claude-code, codex, openclaw, opencode, github-actions, windsurf]skills: [dependency-triage, minimal-fix, loop-verifier]state: dependency-sweeper-state.mdphases: [scan, triage-risk, patch-safe, verify-worktree, escalate-risky]@@ -140,7 +140,7 @@ patterns:goal: Discover, deduplicate, prioritize and label incoming issues/discussions so the team always has a clean actionable queue. Excellent low-risk companion to Daily Triage.cadence: 2h-1drisk: low- tools: [grok, claude-code, codex, openclaw, opencode, github-actions]+ tools: [grok, claude-code, codex, openclaw, opencode, github-actions, windsurf]skills: [issue-triage, loop-verifier]state: issue-triage-state.mdphases: [discover, dedupe, score, propose-labels, human-review]@@ -155,3 +155,25 @@ patterns:stable_fraction: 0.35suggested_daily_cap: 80000early_exit_required: false++ - id: thin-loop+ name: Thin Loop+ file: thin-loop.md+ goal: Report-only GitHub Action snapshot; the issue tracker is the state+ cadence: 1d+ risk: low+ tools: [github-actions, grok, claude-code, codex, opencode]+ skills: [loop-triage]+ state: STATE.md+ phases: [snapshot, summarize, optional-comment]+ human_gates: [all-writes]+ starter: starters/thin-loop+ week_one_mode: L1+ token_cost: low+ cost:+ tokens_noop: 1000+ tokens_report: 5000+ tokens_action: 1000+ stable_fraction: 0.9+ suggested_daily_cap: 20000+ early_exit_required: truediff --git a/tools/loop-init/src/cli.ts b/tools/loop-init/src/cli.tsindex 6f8d3af..6c5c1e7 100644--- a/tools/loop-init/src/cli.ts+++ b/tools/loop-init/src/cli.ts@@ -17,7 +17,8 @@ type Pattern =| 'dependency-sweeper'| 'post-merge-cleanup'| 'changelog-drafter'- | 'issue-triage';+ | 'issue-triage'+ | 'thin-loop';type Tool = 'grok' | 'claude' | 'codex' | 'opencode';@@ -29,6 +30,7 @@ const PATTERN_STARTERS: Record<Pattern, string> = {'post-merge-cleanup': 'post-merge-cleanup','changelog-drafter': 'changelog-drafter','issue-triage': 'issue-triage',+ 'thin-loop': 'thin-loop',};const TOOL_SUFFIX: Record<Tool, string> = {@@ -38,6 +40,9 @@ const TOOL_SUFFIX: Record<Tool, string> = {opencode: '-opencode',};+/** Patterns with a single tool-agnostic starter (no -claude / -codex suffix). */+const TOOL_AGNOSTIC = new Set<Pattern>(['thin-loop']);+const L2_PATTERNS = new Set<Pattern>(['ci-sweeper', 'dependency-sweeper']);const PATTERNS_NEEDING_FIX: Set<Pattern> = new Set([@@ -62,6 +67,7 @@ const STATE_FILES: Record<Pattern, string> = {'post-merge-cleanup': 'post-merge-state.md','changelog-drafter': 'changelog-drafter-state.md','issue-triage': 'issue-triage-state.md',+ 'thin-loop': 'STATE.md',};/** Mirrors patterns/registry.yaml cost caps — used when scaffolding observability files. */@@ -76,6 +82,7 @@ const PATTERN_BUDGET: Record<'post-merge-cleanup': { name: 'Post-Merge Cleanup', maxRunsPerDay: 1, dailyCap: 200_000, maxSpawnsL1: 0, maxSpawnsL2: 2 },'changelog-drafter': { name: 'Changelog Drafter', maxRunsPerDay: 1, dailyCap: 100_000, maxSpawnsL1: 0, maxSpawnsL2: 2 },'issue-triage': { name: 'Issue Triage', maxRunsPerDay: 12, dailyCap: 80_000, maxSpawnsL1: 0, maxSpawnsL2: 1 },+ 'thin-loop': { name: 'Thin Loop', maxRunsPerDay: 24, dailyCap: 20_000, maxSpawnsL1: 0, maxSpawnsL2: 0 },};type FoundryPreset = 'minimal' | 'implementer';@@ -89,6 +96,7 @@ const PATTERN_FOUNDRY_PRESET: Record<Pattern, FoundryPreset> = {'ci-sweeper': 'implementer','dependency-sweeper': 'implementer','post-merge-cleanup': 'implementer',+ 'thin-loop': 'minimal',};const FOUNDRY_SHOWCASE =@@ -198,7 +206,7 @@ ${endpoints}`;function parseArgs(argv: string[]) {let pattern: Pattern = 'daily-triage';- let tool: Tool = 'grok';+ let tool: Tool = 'claude';let target = '.';let dryRun = false;let withFoundry = false;@@ -393,32 +401,14 @@ function printFoundryCta(opts: {score: number | null;preset?: FoundryPreset;}) {- const { pattern, tool, withFoundry, score, preset } = opts;+ const { pattern, withFoundry, preset } = opts;+ if (!withFoundry) return;const mapped = preset ?? PATTERN_FOUNDRY_PRESET[pattern];console.log('');- if (withFoundry) {- console.log(`Harness stack ready (.foundry/, preset: ${mapped} for ${pattern})`);- console.log(' npx @cobusgreyling/harness-foundry validate');- console.log(' npx @cobusgreyling/harness-foundry run --goal "Verify harness wiring"');- console.log(` Showcase: ${FOUNDRY_SHOWCASE}`);- return;- }-- const highReady = score !== null && score >= 80;- console.log(- highReady- ? 'Next after Loop Ready 80+: version this loop as a harness'- : 'Optional: make this loop a versioned harness (harness-foundry)',- );- console.log(- ` npx @cobusgreyling/loop-init . --pattern ${pattern} --tool ${tool} --with-foundry`,- );- console.log(- ` # or: npx @cobusgreyling/harness-foundry init --from loop-engineering:${pattern}`,- );- if (highReady) {- console.log(` Showcase: ${FOUNDRY_SHOWCASE}`);- }+ console.log(`Harness stack ready (.foundry/, preset: ${mapped} for ${pattern})`);+ console.log(' npx @cobusgreyling/harness-foundry validate');+ console.log(' npx @cobusgreyling/harness-foundry run --goal "Verify harness wiring"');+ console.log(` Showcase: ${FOUNDRY_SHOWCASE}`);}function printFleetCta(opts: {@@ -427,22 +417,9 @@ function printFleetCta(opts: {withFleet: boolean;score: number | null;}) {- const { pattern, tool, withFleet, score } = opts;+ if (!opts.withFleet) return;console.log('');- if (withFleet) {- console.log('Fleet engineering stack ready (fleet-registry.md, fleet-inbox.md)');- return;- }-- const highReady = score !== null && score >= 80;- console.log(- highReady- ? 'Next after Loop Ready 80+: version this loop for a fleet (fleet-engineering)'- : 'Optional: add fleet-engineering for multi-agent populations',- );- console.log(- ` npx @cobusgreyling/loop-init . --pattern ${pattern} --tool ${tool} --with-fleet`,- );+ console.log('Fleet engineering stack ready (fleet-registry.md, fleet-inbox.md)');}function printMemoryCta(opts: {@@ -451,22 +428,9 @@ function printMemoryCta(opts: {withMemory: boolean;score: number | null;}) {- const { pattern, tool, withMemory, score } = opts;+ if (!opts.withMemory) return;console.log('');- if (withMemory) {- console.log('Memory engineering stack ready (memory-tiers.md, memory-budget.md)');- return;- }-- const highReady = score !== null && score >= 80;- console.log(- highReady- ? "Next after Loop Ready 80+: version this loop's memory (memory-engineering)"- : 'Optional: add memory-engineering for cross-session knowledge',- );- console.log(- ` npx @cobusgreyling/loop-init . --pattern ${pattern} --tool ${tool} --with-memory`,- );+ console.log('Memory engineering stack ready (memory-tiers.md, memory-budget.md)');}async function exists(p: string): Promise<boolean> {@@ -574,6 +538,7 @@ const LEDGER_GOAL: Record<Pattern, string> = {'post-merge-cleanup': 'Clean up regressions from recent merges','changelog-drafter': 'Draft accurate release notes','issue-triage': 'Triage the open issue queue',+ 'thin-loop': 'Snapshot open issues and PRs; do not edit code',};/**@@ -591,6 +556,7 @@ const LEDGER_LEVEL: Record<Pattern, string> = {'post-merge-cleanup': 'L2','changelog-drafter': 'L1','issue-triage': 'L1',+ 'thin-loop': 'L1',};/**@@ -779,6 +745,12 @@ function firstLoopCommand(pattern: Pattern, tool: Tool): string {codex: 'Automation 2h: issue-triage → issue-triage-state.md. Propose only.',opencode: `${OPENCODE_RUN} "Run issue-triage. Update issue-triage-state.md. Propose labels only — no auto-apply."`,},+ 'thin-loop': {+ grok: 'Commit .github/workflows/thin-loop.yml. The Action is the loop — no STATE.md, no /loop required.',+ claude: 'Commit .github/workflows/thin-loop.yml. The Action is the loop — no STATE.md, no /loop required.',+ codex: 'Commit .github/workflows/thin-loop.yml. The Action is the loop — no STATE.md required.',+ opencode: 'Commit .github/workflows/thin-loop.yml. The Action is the loop — no STATE.md required.',+ },};return cmds[pattern][tool];}@@ -852,10 +824,11 @@ Patterns:post-merge-cleanupchangelog-drafter (new low-risk release notes pattern)issue-triage (new low-risk issue queue health companion to daily triage)+ thin-loop (GitHub Action snapshot — no STATE.md)Options:-p, --pattern Pattern to scaffold- -t, --tool Tool target (default: grok)+ -t, --tool Tool target (default: claude)--with-foundry Also scaffold .foundry/ stack (harness-foundry runtime)--with-memory Also scaffold memory-engineering tiers and budget--with-fleet Also scaffold fleet-engineering registry and inbox@@ -870,8 +843,9 @@ Foundry presets (with --with-foundry):fix-capable patterns → implementerExamples:- npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok- npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok --with-foundry+ npx @cobusgreyling/loop-init . --pattern daily-triage --tool claude+ npx @cobusgreyling/loop-init . --pattern thin-loop --tool claude+ npx @cobusgreyling/loop-init . --pattern daily-triage --tool claude --with-foundrynpx @cobusgreyling/loop-init . -p pr-babysitter -t claude --with-foundrynpx @cobusgreyling/loop-init . -p ci-sweeper -t grok --with-foundry --model-provider minimaxnpx @cobusgreyling/loop-init . -p ci-sweeper -t grok --with-foundry --model-provider minimax --region cn_zh --model MiniMax-M2.7@@ -912,7 +886,7 @@ Examples:const targetDir = path.resolve(target);const baseStarter = PATTERN_STARTERS[pattern];- const suffix = TOOL_SUFFIX[tool];+ const suffix = TOOL_AGNOSTIC.has(pattern) ? '' : TOOL_SUFFIX[tool];const starterName = `${baseStarter}${suffix}`;const startersRoot = await resolveBundledOrMonorepo('starters');const templatesRoot = await resolveBundledOrMonorepo('templates');@@ -1009,13 +983,27 @@ Examples:await copyFile(loopMd, path.join(targetDir, 'LOOP.md'), dryRun);}- await copyL2Templates(pattern, tool, targetDir, templatesRoot, dryRun);- await scaffoldCircuitBreaker(pattern, tool, targetDir, templatesRoot, dryRun);- await scaffoldObservability(pattern, tool, targetDir, templatesRoot, dryRun);- await scaffoldIntake(pattern, tool, targetDir, templatesRoot, dryRun);+ const wfSrc = path.join(effectiveStarter, '.github', 'workflows');+ if (await exists(wfSrc)) {+ const wfEntries = await readDirNames(wfSrc);+ for (const entry of wfEntries) {+ if (!entry.endsWith('.yml') && !entry.endsWith('.yaml')) continue;+ await copyFile(+ path.join(wfSrc, entry),+ path.join(targetDir, '.github', 'workflows', entry),+ dryRun,+ );+ }+ }- await scaffoldConstraints(targetDir, templatesRoot, tool, dryRun);- if (tool !== 'opencode' && !dryRun && !(await exists(path.join(targetDir, 'AGENTS.md')))) {+ if (pattern !== 'thin-loop') {+ await copyL2Templates(pattern, tool, targetDir, templatesRoot, dryRun);+ await scaffoldCircuitBreaker(pattern, tool, targetDir, templatesRoot, dryRun);+ await scaffoldObservability(pattern, tool, targetDir, templatesRoot, dryRun);+ await scaffoldIntake(pattern, tool, targetDir, templatesRoot, dryRun);+ await scaffoldConstraints(targetDir, templatesRoot, tool, dryRun);+ }+ if (tool !== 'opencode' && pattern !== 'thin-loop' && !dryRun && !(await exists(path.join(targetDir, 'AGENTS.md')))) {const agentsTemplate = `# AGENTS.md## Test commandsdiff --git a/tools/loop-init/test/cli.test.mjs b/tools/loop-init/test/cli.test.mjsindex fb59346..b76eaac 100644--- a/tools/loop-init/test/cli.test.mjs+++ b/tools/loop-init/test/cli.test.mjs@@ -22,7 +22,35 @@ test('bundle-assets tolerates concurrent rebuilds', async () => {test('loop-init --help exits 0', async () => {const { stdout } = await exec('node', [CLI, '--help']);assert.match(stdout, /changelog-drafter/);+ assert.match(stdout, /thin-loop/);assert.match(stdout, /opencode/);+ assert.match(stdout, /default: claude/);+});++test('loop-init default tool is claude', async () => {+ const dir = await mkdtemp(path.join(tmpdir(), 'loop-init-default-tool-'));+ try {+ const { stdout } = await exec('node', [CLI, dir, '--pattern', 'daily-triage']);+ assert.match(stdout, /daily-triage → .* \(claude\)/);+ await access(path.join(dir, '.claude', 'skills', 'loop-triage', 'SKILL.md'));+ } finally {+ await rm(dir, { recursive: true, force: true });+ }+});++test('loop-init thin-loop copies workflow and skips STATE.md', async () => {+ const dir = await mkdtemp(path.join(tmpdir(), 'loop-init-thin-'));+ try {+ const { stdout } = await exec('node', [CLI, dir, '--pattern', 'thin-loop']);+ assert.match(stdout, /thin-loop/);+ await access(path.join(dir, '.github', 'workflows', 'thin-loop.yml'));+ await access(path.join(dir, 'LOOP.md'));+ await assert.rejects(() => access(path.join(dir, 'STATE.md')));+ await assert.rejects(() => access(path.join(dir, 'loop-budget.md')));+ assert.match(stdout, /The Action is the loop/);+ } finally {+ await rm(dir, { recursive: true, force: true });+ }});test('loop-init dry-run scaffolds daily-triage', async () => {@@ -206,12 +234,12 @@ test('loop-init does NOT scaffold circuit breaker for report-only daily-triage',}});-test('loop-init prints foundry CTA without --with-foundry', async () => {+test('loop-init does not print foundry CTA without --with-foundry', async () => {const dir = await mkdtemp(path.join(tmpdir(), 'loop-init-cta-'));try {const { stdout } = await exec('node', [CLI, dir, '--pattern', 'daily-triage', '--tool', 'grok']);- assert.match(stdout, /--with-foundry/);- assert.match(stdout, /harness-foundry/);+ assert.doesNotMatch(stdout, /Next after Loop Ready/);+ assert.doesNotMatch(stdout, /Optional: make this loop a versioned harness/);await assert.rejects(() => access(path.join(dir, '.foundry', 'stack.yaml')));} finally {await rm(dir, { recursive: true, force: true });@@ -399,12 +427,11 @@ test('loop-init --help documents --model-provider minimax', async () => {assert.match(stdout, /minimax/);});-test('loop-init prints memory CTA without --with-memory', async () => {+test('loop-init does not print memory CTA without --with-memory', async () => {const dir = await mkdtemp(path.join(tmpdir(), 'loop-init-mem-cta-'));try {const { stdout } = await exec('node', [CLI, dir, '--pattern', 'daily-triage', '--tool', 'grok']);- assert.match(stdout, /--with-memory/);- assert.match(stdout, /memory-engineering/);+ assert.doesNotMatch(stdout, /--with-memory/);await assert.rejects(() => access(path.join(dir, 'memory-tiers.md')));} finally {await rm(dir, { recursive: true, force: true });@@ -439,12 +466,11 @@ test('loop-init --help documents --with-memory', async () => {assert.match(stdout, /memory-engineering tiers and budget/);});-test('loop-init prints fleet CTA without --with-fleet', async () => {+test('loop-init does not print fleet CTA without --with-fleet', async () => {const dir = await mkdtemp(path.join(tmpdir(), 'loop-init-fleet-cta-'));try {const { stdout } = await exec('node', [CLI, dir, '--pattern', 'daily-triage', '--tool', 'grok']);- assert.match(stdout, /--with-fleet/);- assert.match(stdout, /fleet-engineering/);+ assert.doesNotMatch(stdout, /--with-fleet/);await assert.rejects(() => access(path.join(dir, 'fleet-registry.md')));} finally {await rm(dir, { recursive: true, force: true });diff --git a/tools/loop/CHANGELOG.md b/tools/loop/CHANGELOG.mdindex 553e82a..94782b3 100644--- a/tools/loop/CHANGELOG.md+++ b/tools/loop/CHANGELOG.md@@ -1,5 +1,12 @@# Changelog+## 0.2.0++- Default `--tool` is `claude` (was `grok`)+- Week-one copy and wizard default to Claude Code+- Wizard pain #8: thin-loop (GitHub Action, no extra files)+- Companion upsell (`--with-foundry` / memory / fleet) is opt-in, not printed on every init+## 0.1.2- Restore public name `@cobusgreyling/loop` after temporary loop-cli experimentdiff --git a/tools/loop/README.md b/tools/loop/README.mdindex 8243f8d..ef194be 100644--- a/tools/loop/README.md+++ b/tools/loop/README.md@@ -3,7 +3,7 @@**Unified front door** for [Loop Engineering](https://github.com/cobusgreyling/loop-engineering) CLIs.```bash-npx @cobusgreyling/loop init . --pattern daily-triage --tool grok+npx @cobusgreyling/loop init . --pattern daily-triage --tool claudenpx @cobusgreyling/loop doctor .```@@ -28,7 +28,7 @@ This package does **not** replace `loop-init`, `loop-audit`, or the other tools.```bash# 1. Scaffold (report-only)-npx @cobusgreyling/loop init . --pattern daily-triage --tool grok+npx @cobusgreyling/loop init . --pattern daily-triage --tool claude# 2. One health checknpx @cobusgreyling/loop doctor .diff --git a/tools/loop/dist/cli.js b/tools/loop/dist/cli.jsindex 7be4bc0..b1a9498 100755--- a/tools/loop/dist/cli.js+++ b/tools/loop/dist/cli.js@@ -7,7 +7,7 @@ import { runTool } from './pass-through.js';import { runDoctor, formatDoctorHuman } from './doctor.js';import { runStatus, formatStatusHuman } from './status.js';import { defaultPlan, executePlan, printNonInteractiveHelp, resolvePattern, resolveTool, runInteractiveWizard, } from './wizard.js';-const VERSION = '0.1.2';+const VERSION = '0.2.0';const PASS_THROUGH = new Set(['init','audit',@@ -35,7 +35,7 @@ Usage:loop context|worktree|gate|mcp|sandbox [args…]Week-one (recommended):- npx @cobusgreyling/loop init . --pattern daily-triage --tool grok+ npx @cobusgreyling/loop init . --pattern daily-triage --tool claudenpx @cobusgreyling/loop doctor .Doctor exit codes:diff --git a/tools/loop/dist/doctor.js b/tools/loop/dist/doctor.jsindex e26ca13..8fd7648 100644--- a/tools/loop/dist/doctor.js+++ b/tools/loop/dist/doctor.js@@ -88,14 +88,14 @@ export async function runDoctor(target) {actions.push({priority: 1,text: 'Scaffold a first loop (report-only week one)',- command: 'npx @cobusgreyling/loop init . --pattern daily-triage --tool grok',+ command: 'npx @cobusgreyling/loop init . --pattern daily-triage --tool claude',});}else if (!stateName) {actions.push({priority: 2,text: 'Add a state file (STATE.md or pattern state)',- command: 'npx @cobusgreyling/loop init . --pattern daily-triage --tool grok',+ command: 'npx @cobusgreyling/loop init . --pattern daily-triage --tool claude',});}if (!loopMd) {@@ -108,7 +108,7 @@ export async function runDoctor(target) {actions.push({priority: 10,text: 'Add loop-budget.md with daily token caps and kill switch',- command: 'npx @cobusgreyling/loop init . --pattern daily-triage --tool grok',+ command: 'npx @cobusgreyling/loop init . --pattern daily-triage --tool claude',});}if (!runLog) {diff --git a/tools/loop/dist/status.js b/tools/loop/dist/status.jsindex 12aab47..81135e7 100644--- a/tools/loop/dist/status.js+++ b/tools/loop/dist/status.js@@ -53,13 +53,13 @@ export async function runStatus(target) {}let nextHint = 'Run: npx @cobusgreyling/loop doctor .';if (!stateName && !loopRaw) {- nextHint = 'Scaffold: npx @cobusgreyling/loop init . --pattern daily-triage --tool grok';+ nextHint = 'Scaffold: npx @cobusgreyling/loop init . --pattern daily-triage --tool claude';}else if (recentRuns.length === 0) {nextHint = 'Schedule a report-only first run and append loop-run-log.md';}else if (readyScore !== null && readyScore >= 80) {- nextHint = 'Optional: npx @cobusgreyling/loop badge . · harness: loop init . --with-foundry';+ nextHint = 'Optional: npx @cobusgreyling/loop badge .';}return {target: root,diff --git a/tools/loop/dist/wizard.js b/tools/loop/dist/wizard.jsindex b31c503..ca9981f 100644--- a/tools/loop/dist/wizard.js+++ b/tools/loop/dist/wizard.js@@ -14,12 +14,13 @@ export const PAIN_OPTIONS = [{ id: '5', label: 'Merge debt / TODOs piling up', pattern: 'post-merge-cleanup' },{ id: '6', label: 'Stale release notes / changelogs', pattern: 'changelog-drafter' },{ id: '7', label: 'Noisy issue backlog / duplicates', pattern: 'issue-triage' },+ { id: '8', label: 'Just a GitHub Action, no extra files', pattern: 'thin-loop' },];export const TOOLS = ['grok', 'claude', 'codex', 'opencode'];export function defaultPlan() {return {pattern: 'daily-triage',- tool: 'grok',+ tool: 'claude',target: '.',withFoundry: false,};@@ -41,7 +42,7 @@ export function formatPainMenu() {lines.push(` ${p.id}) ${p.label} → ${p.pattern}`);}lines.push('');- lines.push(' Enter 1-7, or pattern id (default: daily-triage)');+ lines.push(' Enter 1-8, or pattern id (default: daily-triage)');return lines.join('\n');}export function resolvePattern(answer) {@@ -63,7 +64,7 @@ export function resolveTool(answer) {const t = answer.trim().toLowerCase();if (TOOLS.includes(t))return t;- return 'grok';+ return 'claude';}export async function runInteractiveWizard() {const rl = readline.createInterface({ input, output });@@ -72,7 +73,7 @@ export async function runInteractiveWizard() {console.log(formatPainMenu());const pain = await rl.question('> ');const pattern = resolvePattern(pain);- console.log(`\nCoding agent tool? (${TOOLS.join(' / ')}) [grok]`);+ console.log(`\nCoding agent tool? (${TOOLS.join(' / ')}) [claude]`);const toolAns = await rl.question('> ');const tool = resolveTool(toolAns);console.log('\nTarget directory? [.]');@@ -88,12 +89,12 @@ export function printNonInteractiveHelp() {console.log(formatWizardBanner());console.log(`Week-one path (copy/paste):- npx @cobusgreyling/loop init . --pattern daily-triage --tool grok+ npx @cobusgreyling/loop init . --pattern daily-triage --tool claudenpx @cobusgreyling/loop doctor .Or pick a pain point, then scaffold:-${PAIN_OPTIONS.map((p) => ` ${p.id}. ${p.label}\n npx @cobusgreyling/loop init . -p ${p.pattern} -t grok`).join('\n\n')}+${PAIN_OPTIONS.map((p) => ` ${p.id}. ${p.label}\n npx @cobusgreyling/loop init . -p ${p.pattern} -t claude`).join('\n\n')}Commands:loop init|audit|cost|sync|doctor|status|badge|wizarddiff --git a/tools/loop/package.json b/tools/loop/package.jsonindex bfd8e4b..1f8a324 100644--- a/tools/loop/package.json+++ b/tools/loop/package.json@@ -1,6 +1,6 @@{"name": "@cobusgreyling/loop",- "version": "0.1.2",+ "version": "0.2.0","description": "Unified Loop Engineering CLI \u2014 one front door for init, audit, cost, sync, doctor, and status. Existing packages stay supported. npx @cobusgreyling/loop doctor .","type": "module","bin": {diff --git a/tools/loop/src/cli.ts b/tools/loop/src/cli.tsindex a9d5fca..a74b5f2 100644--- a/tools/loop/src/cli.ts+++ b/tools/loop/src/cli.ts@@ -16,7 +16,7 @@ import {type WizardPlan,} from './wizard.js';-const VERSION = '0.1.2';+const VERSION = '0.2.0';const PASS_THROUGH = new Set(['init',@@ -46,7 +46,7 @@ Usage:loop context|worktree|gate|mcp|sandbox [args…]Week-one (recommended):- npx @cobusgreyling/loop init . --pattern daily-triage --tool grok+ npx @cobusgreyling/loop init . --pattern daily-triage --tool claudenpx @cobusgreyling/loop doctor .Doctor exit codes:diff --git a/tools/loop/src/doctor.ts b/tools/loop/src/doctor.tsindex eb2e276..e148352 100644--- a/tools/loop/src/doctor.ts+++ b/tools/loop/src/doctor.ts@@ -138,13 +138,13 @@ export async function runDoctor(target: string): Promise<DoctorReport> {actions.push({priority: 1,text: 'Scaffold a first loop (report-only week one)',- command: 'npx @cobusgreyling/loop init . --pattern daily-triage --tool grok',+ command: 'npx @cobusgreyling/loop init . --pattern daily-triage --tool claude',});} else if (!stateName) {actions.push({priority: 2,text: 'Add a state file (STATE.md or pattern state)',- command: 'npx @cobusgreyling/loop init . --pattern daily-triage --tool grok',+ command: 'npx @cobusgreyling/loop init . --pattern daily-triage --tool claude',});}if (!loopMd) {@@ -157,7 +157,7 @@ export async function runDoctor(target: string): Promise<DoctorReport> {actions.push({priority: 10,text: 'Add loop-budget.md with daily token caps and kill switch',- command: 'npx @cobusgreyling/loop init . --pattern daily-triage --tool grok',+ command: 'npx @cobusgreyling/loop init . --pattern daily-triage --tool claude',});}if (!runLog) {diff --git a/tools/loop/src/status.ts b/tools/loop/src/status.tsindex 3228228..96af1aa 100644--- a/tools/loop/src/status.ts+++ b/tools/loop/src/status.ts@@ -77,11 +77,11 @@ export async function runStatus(target: string): Promise<StatusReport> {let nextHint = 'Run: npx @cobusgreyling/loop doctor .';if (!stateName && !loopRaw) {- nextHint = 'Scaffold: npx @cobusgreyling/loop init . --pattern daily-triage --tool grok';+ nextHint = 'Scaffold: npx @cobusgreyling/loop init . --pattern daily-triage --tool claude';} else if (recentRuns.length === 0) {nextHint = 'Schedule a report-only first run and append loop-run-log.md';} else if (readyScore !== null && readyScore >= 80) {- nextHint = 'Optional: npx @cobusgreyling/loop badge . · harness: loop init . --with-foundry';+ nextHint = 'Optional: npx @cobusgreyling/loop badge .';}return {diff --git a/tools/loop/src/wizard.ts b/tools/loop/src/wizard.tsindex d23eb0e..11f70d9 100644--- a/tools/loop/src/wizard.ts+++ b/tools/loop/src/wizard.ts@@ -21,6 +21,7 @@ export const PAIN_OPTIONS: PainOption[] = [{ id: '5', label: 'Merge debt / TODOs piling up', pattern: 'post-merge-cleanup' },{ id: '6', label: 'Stale release notes / changelogs', pattern: 'changelog-drafter' },{ id: '7', label: 'Noisy issue backlog / duplicates', pattern: 'issue-triage' },+ { id: '8', label: 'Just a GitHub Action, no extra files', pattern: 'thin-loop' },];export const TOOLS = ['grok', 'claude', 'codex', 'opencode'] as const;@@ -36,7 +37,7 @@ export interface WizardPlan {export function defaultPlan(): WizardPlan {return {pattern: 'daily-triage',- tool: 'grok',+ tool: 'claude',target: '.',withFoundry: false,};@@ -60,7 +61,7 @@ export function formatPainMenu(): string {lines.push(` ${p.id}) ${p.label} → ${p.pattern}`);}lines.push('');- lines.push(' Enter 1-7, or pattern id (default: daily-triage)');+ lines.push(' Enter 1-8, or pattern id (default: daily-triage)');return lines.join('\n');}@@ -79,7 +80,7 @@ export function resolvePattern(answer: string): string {export function resolveTool(answer: string): WizardTool {const t = answer.trim().toLowerCase();if ((TOOLS as readonly string[]).includes(t)) return t as WizardTool;- return 'grok';+ return 'claude';}export async function runInteractiveWizard(): Promise<WizardPlan> {@@ -90,7 +91,7 @@ export async function runInteractiveWizard(): Promise<WizardPlan> {const pain = await rl.question('> ');const pattern = resolvePattern(pain);- console.log(`\nCoding agent tool? (${TOOLS.join(' / ')}) [grok]`);+ console.log(`\nCoding agent tool? (${TOOLS.join(' / ')}) [claude]`);const toolAns = await rl.question('> ');const tool = resolveTool(toolAns);@@ -108,12 +109,12 @@ export function printNonInteractiveHelp(): void {console.log(formatWizardBanner());console.log(`Week-one path (copy/paste):- npx @cobusgreyling/loop init . --pattern daily-triage --tool grok+ npx @cobusgreyling/loop init . --pattern daily-triage --tool claudenpx @cobusgreyling/loop doctor .Or pick a pain point, then scaffold:-${PAIN_OPTIONS.map((p) => ` ${p.id}. ${p.label}\n npx @cobusgreyling/loop init . -p ${p.pattern} -t grok`).join('\n\n')}+${PAIN_OPTIONS.map((p) => ` ${p.id}. ${p.label}\n npx @cobusgreyling/loop init . -p ${p.pattern} -t claude`).join('\n\n')}Commands:loop init|audit|cost|sync|doctor|status|badge|wizard