Skip to content

Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.

chore: community health (CoC, issue templates) + GFI/story wave (#329)

Cobus Greylingbf00cc2251b3
diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000..8ebaba6
--- /dev/null
+++ b/.github/CODE_OF_CONDUCT.md
@@ -0,0 +1,81 @@
+# Code of Conduct
+
+## Our pledge
+
+We pledge to make participation in Loop Engineering a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our standards
+
+**Examples of behavior that contributes to a positive environment:**
+
+- Engineering over hype; honest failure reports are first-class content
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Focusing on what is best for the community and for people running loops in production
+- Tool-agnostic defaults; tool-specific advice labeled clearly
+
+**Examples of unacceptable behavior:**
+
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others’ private information without explicit permission
+- Shipping or promoting unsafe auto-fix patterns without human gates as “best practice”
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement responsibilities
+
+Project maintainers are responsible for clarifying and enforcing standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior they deem inappropriate, threatening, offensive, or harmful.
+
+Maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned with this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces — GitHub issues, pull requests, discussions, and any other official channels — and also applies when an individual is officially representing the project in public spaces.
+
+## Enforcement
+
+Report incidents to the maintainers via [SECURITY.md](./SECURITY.md) contact methods or by emailing the repository owner through GitHub. All complaints will be reviewed and investigated promptly and fairly.
+
+Maintainers are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement guidelines
+
+Maintainers will follow these Community Impact Guidelines:
+
+### 1. Correction
+
+**Community Impact:** Use of inappropriate language or other behavior deemed unprofessional.
+
+**Consequence:** A private, written warning providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact:** A violation through a single incident or series of actions.
+
+**Consequence:** A warning with consequences for continued behavior. No interaction with the people involved for a specified period. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary ban
+
+**Community Impact:** A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence:** A temporary ban from any sort of interaction or public communication with the community for a specified period.
+
+### 4. Permanent ban
+
+**Community Impact:** Demonstrating a pattern of violation, harassment, or aggression toward individuals or groups.
+
+**Consequence:** A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla’s code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.
diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md
index 1d6dd5b..0c9a0c2 100644
--- a/.github/ISSUE_TEMPLATE/bug-report.md
+++ b/.github/ISSUE_TEMPLATE/bug-report.md
@@ -1,27 +1,26 @@
---
-name: Bug report (for the reference, starters, loop-audit, or docs)
-about: Something is broken, inaccurate, or the audit gives wrong results
-labels: bug
+name: Bug report
+about: Something is broken, inaccurate, or loop-audit gives wrong results
+title: "[bug] "
+labels: ["bug"]
---
-**Describe the bug**:
+**Describe the bug**
-**Steps to reproduce**:
-1.
-2.
+**Steps to reproduce**
+1.
+2.
-**Expected behavior**:
+**Expected behavior**
-**Actual behavior** (include output of `loop-audit --json` or command if relevant):
+**Actual behavior** (include `loop-audit --json` or command output if relevant)
-**Environment**:
+**Environment**
- OS:
-- Node (for audit):
-- Tool used (Grok / Claude / Codex / GH Actions):
+- Node (for CLIs):
+- Tool (Grok / Claude / Codex / Cursor / Opencode / other):
- Target repo (if not this one):
-**Additional context** (links to patterns, commits, screenshots):
+**Additional context**
----
-
-*If this is a pattern or safety issue, please also reference `docs/safety.md` or `docs/failure-modes.md`.*
+If this is a pattern or safety issue, reference `docs/safety.md` or `docs/failure-modes.md`.
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index 511a3ed..3487e22 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -1,31 +1,14 @@
blank_issues_enabled: false
contact_links:
- - name: "\u2753 Question or Discussion"
- url: https://github.com/cobusgreyling/loop-engineering/discussions
- about: "For general questions, ideas, or chat about loop engineering, use Discussions."
- - name: "\ud83d\udc1b Report an issue with the docs site or showcase"
- url: https://github.com/cobusgreyling/loop-engineering/issues/new?labels=docs
- about: "Use the bug report template for the reference itself."
- - name: "\ud83c\udf10 Add my project to Adopters"
+ - name: "❓ Ask anything"
+ url: https://github.com/cobusgreyling/loop-engineering/discussions/327
+ about: "Setup, scoring, safety, tool mapping — prefer Discussions for questions."
+ - name: "📣 Show your loop"
+ url: https://github.com/cobusgreyling/loop-engineering/discussions/326
+ about: "First runs, Loop Ready scores, honest failures."
+ - name: "🏷️ Add my project to Adopters"
url: https://github.com/cobusgreyling/loop-engineering/issues/new?template=add-adopter.yml
- about: "List your loop on the showcase adopters wall and docs/adopters.md."
- - name: "\ud83c\udf31 Good first issues (contributor quickstart)"
- url: https://github.com/cobusgreyling/loop-engineering/discussions/123
- about: "Scoped ~10 min–1 hr tasks. Comment I'll take this on an issue to get assigned."
-
-labels:
- - name: "pattern-request"
- description: "Request for a new documented loop pattern"
- color: "0e8a16"
- - name: "story"
- description: "Production story or failure report"
- color: "5319e7"
- - name: "tooling"
- description: "loop-audit, registry, starters, templates"
- color: "1d76db"
- - name: "docs"
- description: "Documentation, primitives, checklist, showcase"
- color: "bfd4f2"
- - name: "good first issue"
- description: "Good for newcomers"
- color: "7057ff"
+ about: "List your loop on the adopters wall."
+ - name: "🌱 Good first issues"
+ url: https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
+ about: "Scoped ~10 min–1 hr tasks. Comment I'll take this to get assigned."
diff --git a/.github/ISSUE_TEMPLATE/pattern-request.md b/.github/ISSUE_TEMPLATE/pattern-request.md
index 5342c80..c833e96 100644
--- a/.github/ISSUE_TEMPLATE/pattern-request.md
+++ b/.github/ISSUE_TEMPLATE/pattern-request.md
@@ -1,27 +1,16 @@
---
name: Pattern request
-about: Suggest a new reusable loop pattern with production potential
-labels: pattern-request
+about: Request a new documented loop pattern
+title: "[pattern] "
+labels: ["pattern-request"]
---
-**Pattern name idea**:
+**Pattern name** (short)
-**What problem does it solve?** (one paragraph)
+**Problem it solves**
-**Typical cadence**:
+**Tools you care about** (Grok / Claude / Codex / Cursor / …)
-**Risk level** (low / medium / high):
+**Similar existing pattern?** (link under `patterns/` if any)
-**Target tools** (Grok / Claude Code / Codex / GitHub Actions / other):
-
-**Why this belongs in the reference** (real usage or strong signal from others):
-
-**Proposed skills** (triage, fix, verify...):
-
-**Human gates you expect**:
-
-**Any existing starter code or notes** (links, private repo redacted examples):
-
----
-
-*We will turn accepted requests into full `patterns/*.md` + `registry.yaml` entry + starter + at least one story following the template.*
+**Would you draft a PR?** yes / no / need guidance
diff --git a/.github/ISSUE_TEMPLATE/share-story.md b/.github/ISSUE_TEMPLATE/share-story.md
index 35ad02d..691266f 100644
--- a/.github/ISSUE_TEMPLATE/share-story.md
+++ b/.github/ISSUE_TEMPLATE/share-story.md
@@ -1,25 +1,18 @@
---
-name: Share a production story (wins or failures)
-about: Real-world loop engineering experience. Failures and surprises are first-class.
-labels: story
+name: Share a production story
+about: Honest win or failure from running a loop
+title: "[story] "
+labels: ["story", "good first issue"]
---
-**Pattern(s) used**:
+**Pattern used** (Daily Triage / PR Babysitter / CI Sweeper / other)
-**Context** (team size, tools, repo(s), what you were trying to automate):
+**Tool** (Grok / Claude / Codex / Cursor / Opencode / other)
-**What worked**:
+**What worked**
-**What broke or surprised you** (required — honest failures make the reference valuable):
+**What failed or surprised you** (required — failures are first-class)
-**Metrics or qualitative outcome** (time saved, PRs merged, incidents avoided, tokens burned, etc.):
+**Actionable lesson** (one paragraph)
-**Actionable lesson** (one crisp paragraph others can apply):
-
-**Would you run this unattended today?** (L1 / L2 / L3 and why):
-
-**Artifacts you can share** (redacted state snippets, skill text, workflow yml, screenshots — attach or paste):
-
----
-
-Thank you. These stories are the most valuable part of the project.
+**Optional:** PR under `stories/` instead of this issue — same-day review when possible.
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000..8ebaba6
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,81 @@
+# Code of Conduct
+
+## Our pledge
+
+We pledge to make participation in Loop Engineering a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our standards
+
+**Examples of behavior that contributes to a positive environment:**
+
+- Engineering over hype; honest failure reports are first-class content
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Focusing on what is best for the community and for people running loops in production
+- Tool-agnostic defaults; tool-specific advice labeled clearly
+
+**Examples of unacceptable behavior:**
+
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others’ private information without explicit permission
+- Shipping or promoting unsafe auto-fix patterns without human gates as “best practice”
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement responsibilities
+
+Project maintainers are responsible for clarifying and enforcing standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior they deem inappropriate, threatening, offensive, or harmful.
+
+Maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned with this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces — GitHub issues, pull requests, discussions, and any other official channels — and also applies when an individual is officially representing the project in public spaces.
+
+## Enforcement
+
+Report incidents to the maintainers via [SECURITY.md](./SECURITY.md) contact methods or by emailing the repository owner through GitHub. All complaints will be reviewed and investigated promptly and fairly.
+
+Maintainers are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement guidelines
+
+Maintainers will follow these Community Impact Guidelines:
+
+### 1. Correction
+
+**Community Impact:** Use of inappropriate language or other behavior deemed unprofessional.
+
+**Consequence:** A private, written warning providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact:** A violation through a single incident or series of actions.
+
+**Consequence:** A warning with consequences for continued behavior. No interaction with the people involved for a specified period. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary ban
+
+**Community Impact:** A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence:** A temporary ban from any sort of interaction or public communication with the community for a specified period.
+
+### 4. Permanent ban
+
+**Community Impact:** Demonstrating a pattern of violation, harassment, or aggression toward individuals or groups.
+
+**Consequence:** A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla’s code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a3cb133..0c743a8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -59,9 +59,14 @@ Also add an entry to `patterns/registry.yaml`.
## Code of Conduct
+This project follows the [Code of Conduct](./CODE_OF_CONDUCT.md) (Contributor Covenant).
+
+In short:
+
- Engineering over hype
- Failures are first-class content
- Tool-agnostic by default; tool-specific in labeled sections
+- Harassment and bad-faith participation are not tolerated
## Maintainer response (adopters & stories)
@@ -75,8 +80,8 @@ Automation posts a welcome comment on new story/adopter PRs (see `.github/workfl
## Community
-- **Questions**: [GitHub Discussions](https://github.com/cobusgreyling/loop-engineering/discussions) (preferred) or issue with label `question`
-- **Show your loop**: [Add Adopter issue](https://github.com/cobusgreyling/loop-engineering/issues/new?template=add-adopter.yml), Discussions, or a row in [docs/adopters.md](./docs/adopters.md)
+- **Questions**: [Ask anything](https://github.com/cobusgreyling/loop-engineering/discussions/327) (preferred) or issue with label `question`
+- **Show your loop**: [Show your loop](https://github.com/cobusgreyling/loop-engineering/discussions/326), [Add Adopter issue](https://github.com/cobusgreyling/loop-engineering/issues/new?template=add-adopter.yml), or a row in [docs/adopters.md](./docs/adopters.md)
- **Loop Ready badge**: `npx @cobusgreyling/loop-audit . --badge` — paste into your README
- **Good first issues**: look for label [`good first issue`](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
- **Hall of fame**: [CONTRIBUTORS.md](./CONTRIBUTORS.md) — regenerate after merges with `npm run contributors:generate`
diff --git a/README.md b/README.md
index 7cbc1c8..f5548f7 100644
--- a/README.md
+++ b/README.md
@@ -280,21 +280,19 @@ Addy Osmani:
| Pick one | Issue |
|----------|-------|
| ~10 min | [#120 — Add your project to adopters](https://github.com/cobusgreyling/loop-engineering/issues/120) |
-| ~15 min | [#118 — Daily Triage story](https://github.com/cobusgreyling/loop-engineering/issues/118) · [#119 — PR Babysitter failure story](https://github.com/cobusgreyling/loop-engineering/issues/119) |
-| ~15 min | [#226 — `loop-sync` subsection in QUICKSTART](https://github.com/cobusgreyling/loop-engineering/issues/226) |
-| ~20 min | [#117 — Continue.dev row in primitives matrix](https://github.com/cobusgreyling/loop-engineering/issues/117) |
-| ~30 min | [#147 — Cline appendix](https://github.com/cobusgreyling/loop-engineering/issues/147) · [#220 — Cursor CI Sweeper example](https://github.com/cobusgreyling/loop-engineering/issues/220) |
-| ~30 min | [#221 — Cursor Post-Merge Cleanup](https://github.com/cobusgreyling/loop-engineering/issues/221) · [#224 — Cursor Issue Triage](https://github.com/cobusgreyling/loop-engineering/issues/224) |
-| ~30 min | [#195 — Roo Code appendix](https://github.com/cobusgreyling/loop-engineering/issues/195) · [#196 — GitHub Copilot appendix](https://github.com/cobusgreyling/loop-engineering/issues/196) |
-| ~45 min | [#225 — Hermes PR Babysitter example](https://github.com/cobusgreyling/loop-engineering/issues/225) · [#231 — loop-init validation checklist](https://github.com/cobusgreyling/loop-engineering/issues/231) |
-| ~1 hr | [#229](https://github.com/cobusgreyling/loop-engineering/issues/229) / [#230](https://github.com/cobusgreyling/loop-engineering/issues/230) — **your story** (worktree week-two, multi-loop failure) |
-| ~1 hr | [#173 — Issue Triage week-one story](https://github.com/cobusgreyling/loop-engineering/issues/173) |
+| ~15 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) |
+| ~20 min | [#119 — PR Babysitter failure story](https://github.com/cobusgreyling/loop-engineering/issues/119) |
+| ~30 min | [#117 — Continue.dev](https://github.com/cobusgreyling/loop-engineering/issues/117) · [#147 — Cline](https://github.com/cobusgreyling/loop-engineering/issues/147) |
+| ~30 min | [#195 — Roo Code](https://github.com/cobusgreyling/loop-engineering/issues/195) · [#196 — GitHub Copilot](https://github.com/cobusgreyling/loop-engineering/issues/196) |
+| ~40 min | [#220 — Cursor CI Sweeper](https://github.com/cobusgreyling/loop-engineering/issues/220) · [#223 — Cursor Changelog Drafter](https://github.com/cobusgreyling/loop-engineering/issues/223) |
+| ~40 min | [#224 — Cursor Issue Triage](https://github.com/cobusgreyling/loop-engineering/issues/224) |
+| Hubs | [Show your loop](https://github.com/cobusgreyling/loop-engineering/discussions/326) · [Ask anything](https://github.com/cobusgreyling/loop-engineering/discussions/327) |
Comment **"I'll take this"** on any [`good first issue`](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) for assignment.
## Contributing
-Share production patterns, tool mappings, and failure stories. See [CONTRIBUTING.md](CONTRIBUTING.md) (contribution ladder + [`good first issue` backlog](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)), [adopters](docs/adopters.md), and [GitHub Discussions](https://github.com/cobusgreyling/loop-engineering/discussions).
+Share production patterns, tool mappings, and failure stories. See [CONTRIBUTING.md](CONTRIBUTING.md) (contribution ladder + [`good first issue` backlog](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)), [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).
## Sources
diff --git a/docs/distribution/substack-score-climbs-then-budget-burns.md b/docs/distribution/substack-score-climbs-then-budget-burns.md
new file mode 100644
index 0000000..d0a839a
--- /dev/null
+++ b/docs/distribution/substack-score-climbs-then-budget-burns.md
@@ -0,0 +1,104 @@
+# The Score Climbed to 100. Then the Budget Burned.
+
+*Subtitle: Loop Ready measures scaffold — not permission to let agents write unattended.*
+
+---
+
+You can make an AI coding agent look brilliant for an afternoon.
+
+You can also burn a week of token budget overnight fixing the same flaky test.
+
+This is a field note from dogfooding [Loop Engineering](https://github.com/cobusgreyling/loop-engineering) — the patterns, starters, and CLIs for designing systems that prompt your agents (instead of you re-prompting every morning).
+
+If you only remember one line:
+
+> **A Loop Ready score of 100 is a landing checklist, not a green light for auto-fix.**
+
+---
+
+## The 15-second dopamine hit
+
+```bash
+npx @cobusgreyling/loop-init . --pattern daily-triage --tool claude
+npx @cobusgreyling/loop-audit . --suggest
+```
+
+On a greenfield or “we have AGENTS.md and chaos” repo, the score can climb from the teens into the 90s once you have:
+
+- a pattern and skills
+- `STATE.md` / loop files
+- budget + constraints
+- a run log
+
+That climb is real. It’s also **dangerous** if you confuse *readiness of the harness* with *permission to merge*.
+
+We shipped a clearer path in [v1.6.0](https://github.com/cobusgreyling/loop-engineering/releases/tag/v1.6.0): `loop-init --with-foundry`, `loop-audit` 1.7 Harness Runtime signals, and `loop-gate` for mechanical denylists.
+
+---
+
+## Week one: the part that worked
+
+We ran **Daily Triage** in **report-only** mode.
+
+No auto-close. No auto-merge. No “just fix main” ambition.
+
+The loop’s job was to produce a human-readable agenda: stale PRs, flaky suites, normalized red builds. Humans acted on the report in standup.
+
+That week was boring. Boring is the goal.
+
+---
+
+## Week two: the part that failed
+
+Day six, we “graduated” to a CI Sweeper on a tight cadence.
+
+We skipped:
+
+1. A **separate** verifier (maker graded its own homework)
+2. A **branch allowlist** (feature-branch chaos entered the loop)
+3. A **hard stop** on daily tokens (cadence compounds faster than Slack)
+
+Within 48 hours the ledger looked like a runway fire: millions of tokens, symptom PRs, state drift, and one config change that would have broken prod if a human hadn’t caught it.
+
+We killed the sweeper. We went back to report-only. We wrote the failure down so we wouldn’t relearn it as folklore.
+
+(Repo story: [`score-climbs-then-budget-burns.md`](https://github.com/cobusgreyling/loop-engineering/blob/main/stories/score-climbs-then-budget-burns.md) · earlier cousin: [why we killed CI sweeper](https://github.com/cobusgreyling/loop-engineering/blob/main/stories/why-we-killed-ci-sweeper.md).)
+
+---
+
+## The design rule
+
+| Phase | Allowed | Forbidden |
+|-------|---------|-----------|
+| L1 (week one+) | Report, label proposals, draft notes | Unattended code changes |
+| L2 (only after L1 is boring) | Fixes in worktrees, gated PRs | Direct pushes, prod-path writes without `loop-gate` |
+| Always | Budget stop conditions, human merge | “The score was high so we turned on everything” |
+
+Loop engineering is not prompt engineering with a stopwatch.
+
+It’s **systems design**: schedule, skills, state, verification, handoff, budget.
+
+---
+
+## What to run tomorrow morning
+
+```bash
+npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok
+npx @cobusgreyling/loop-audit . --suggest
+npx @cobusgreyling/loop-cost --pattern daily-triage --level L1 --cadence 1d
+```
+
+When the score is high **and** report-only has been boring for two weeks, then consider L2 — and version the loop as a harness (`--with-foundry`) so you can evolve it without folklore.
+
+---
+
+## Join the loop
+
+- Repo: https://github.com/cobusgreyling/loop-engineering
+- Release: https://github.com/cobusgreyling/loop-engineering/releases/tag/v1.6.0
+- Show your score: https://github.com/cobusgreyling/loop-engineering/discussions/326
+- Ask anything: https://github.com/cobusgreyling/loop-engineering/discussions/327
+
+If you post a score, post a failure too. That’s the culture.
+
+— Cobus
diff --git a/docs/distribution/v1.6.0-social-drafts.md b/docs/distribution/v1.6.0-social-drafts.md
new file mode 100644
index 0000000..c8a2890
--- /dev/null
+++ b/docs/distribution/v1.6.0-social-drafts.md
@@ -0,0 +1,94 @@
+# v1.6.0 social drafts — ready to post
+
+Use these as-is or lightly edit. Goal: **score 10→100 in ~15s**, then point at the safe path.
+
+**Links**
+
+- Release: https://github.com/cobusgreyling/loop-engineering/releases/tag/v1.6.0
+- Repo: https://github.com/cobusgreyling/loop-engineering
+- Demo GIF: https://raw.githubusercontent.com/cobusgreyling/loop-engineering/main/assets/visuals/loop-audit-demo.gif
+- Showcase: https://cobusgreyling.github.io/loop-engineering/
+- Show your loop: https://github.com/cobusgreyling/loop-engineering/discussions/326
+- Story (Substack source): `stories/score-climbs-then-budget-burns.md`
+
+---
+
+## X / Twitter — thread
+
+**1/**
+Stop prompting your coding agent every morning.
+
+Design the loop that prompts it.
+
+Loop Engineering just shipped **v1.6.0**.
+
+**2/**
+One command:
+
+```
+npx @cobusgreyling/loop-init .
+```
+
+Scaffold skills + state + budget, then watch **Loop Ready** climb.
+
+(GIF: score climbing in ~15s)
+
+**3/**
+v1.6.0 in three bullets:
+
+1. `loop-init --with-foundry` — design → versioned harness
+2. `loop-gate` — denylist + auto-merge allowlist
+3. Safer long runs — stagnation detection + worktree wait queue
+
+**4/**
+Unpopular lesson from dogfooding:
+
+A score of 100 is a *checklist*, not permission to auto-fix.
+
+Week one: report-only.
+Week two: only if week one was boring.
+
+**5/**
+Try it → post your score:
+
+https://github.com/cobusgreyling/loop-engineering
+
+Show your loop: https://github.com/cobusgreyling/loop-engineering/discussions/326
+
+---
+
+## LinkedIn — single post
+
+**Title line:** Your AI coding agent doesn’t need better prompts. It needs a better loop.
+
+Most teams still open Claude/Cursor/Codex every morning and re-explain the repo.
+
+Loop engineering flips that: you design the system that prompts the agent — schedule, skills, state, budget, human gates — then measure readiness.
+
+**Ship check (v1.6.0):**
+
+```bash
+npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok
+npx @cobusgreyling/loop-audit . --suggest
+```
+
+In about 15 seconds you can go from “empty repo” to a Loop Ready score and a first report-only triage command.
+
+What’s new:
+
+- `--with-foundry` to version the loop as a harness when you’re ready
+- `loop-gate` for mechanical path safety
+- Honest failure culture (score ≠ license to auto-merge)
+
+If you try it, drop your before/after score in the comments or on our “Show your loop” discussion.
+
+Repo: https://github.com/cobusgreyling/loop-engineering
+Release: https://github.com/cobusgreyling/loop-engineering/releases/tag/v1.6.0
+
+#AI #SoftwareEngineering #DevTools #CodingAgents #OpenSource
+
+---
+
+## Image / media
+
+Attach `assets/visuals/loop-audit-demo.gif` (score climb) or `assets/visuals/LE5.jpeg` (hero).
diff --git a/stories/README.md b/stories/README.md
index aa6b95a..5f1e5c0 100644
--- a/stories/README.md
+++ b/stories/README.md
@@ -4,6 +4,7 @@ Real-world loop engineering — including failures. Contribute yours via [CONTRI
| Story | Pattern | Takeaway |
|-------|---------|----------|
+| [score-climbs-then-budget-burns.md](./score-climbs-then-budget-burns.md) | Daily Triage → CI Sweeper | Score ≠ permission to auto-fix; budget burn after early L2 |
| [pr-babysitter-week-one.md](./pr-babysitter-week-one.md) | PR Babysitter | State + attempt limits + verifier |
| [daily-triage-report-only.md](./daily-triage-report-only.md) | Daily Triage | L1 before L2 |
| [why-we-killed-ci-sweeper.md](./why-we-killed-ci-sweeper.md) | CI Sweeper | Budget, branch allowlist, kill switch |
diff --git a/stories/score-climbs-then-budget-burns.md b/stories/score-climbs-then-budget-burns.md
new file mode 100644
index 0000000..12f9075
--- /dev/null
+++ b/stories/score-climbs-then-budget-burns.md
@@ -0,0 +1,74 @@
+# The Score Climbed to 100. Then the Budget Burned.
+
+*Production story — week-one win, week-two failure. Companion to [v1.6.0](https://github.com/cobusgreyling/loop-engineering/releases/tag/v1.6.0).*
+
+## Context
+
+Pattern: **Daily Triage** → premature **CI Sweeper**
+Tools: Claude Code + GitHub Actions
+Level: L1 report-only (days 1–5), then L2 auto-fix too early (day 6)
+
+## What worked (week one)
+
+```bash
+npx @cobusgreyling/loop-init . --pattern daily-triage --tool claude
+npx @cobusgreyling/loop-audit . --suggest
+```
+
+Loop Ready went **~15 → 92** in an afternoon: `STATE.md`, skills, budget file, constraints, run log. The audit `--suggest` list was the actual roadmap — not a vanity score.
+
+Daily Triage in **report-only** mode surfaced:
+
+- 4 stale PRs with no reviewers
+- 1 flaky suite that had been “someone else’s problem” for weeks
+- A `main` red that humans had normalized
+
+No auto-merge. No unattended writes. Humans used the report as a standup agenda.
+
+## What failed (week two)
+
+On day 6 we “graduated” to CI Sweeper on a 15-minute cadence **without**:
+
+1. A separate verifier agent
+2. A branch allowlist (`main` only)
+3. A hard daily token cap enforced outside the model’s goodwill
+
+Within 48 hours:
+
+- ~**6–8M tokens** spent chasing the same flaky test
+- Multiple fix PRs that treated symptoms (sleep, retry) not cause
+- `STATE.md` and the run log disagreed about what was “done”
+- Human review caught one config change that would have broken prod deploys
+
+We killed the sweeper (`scheduler_delete` / disabled Action), rewrote the budget, and returned to Daily Triage report-only for another week. See also [`why-we-killed-ci-sweeper.md`](./why-we-killed-ci-sweeper.md).
+
+## Root causes
+
+| Miss | Why it hurt |
+|------|-------------|
+| Score ≠ permission | Loop Ready 90+ measures *scaffold*, not *license to auto-fix* |
+| Same-session verifier | Maker graded its own homework |
+| No worktree isolation | Partial fixes polluted the working tree mid-loop |
+| Cadence without budget | 15m ticks compound faster than humans notice |
+
+## What we changed
+
+1. **L1 until boring** — two clean weeks of report-only before any L2
+2. **`loop-gate` + denylist** — mechanical blocks on prod paths ([v1.6.0](https://github.com/cobusgreyling/loop-engineering/releases/tag/v1.6.0))
+3. **Verifier as separate pass** — different agent / higher scrutiny
+4. **Budget as stop condition** — when the ledger trips, the loop stops, full stop
+5. Optional **`--with-foundry`** when promoting a stable loop to a versioned harness
+
+## Lesson
+
+A climbing Loop Ready score is a *landing checklist*, not a green light for unattended writes. Design the loop, measure readiness, then **earn** auto-fix with boring report-only weeks — not with a badge.
+
+## Try the safe path
+
+```bash
+npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok
+npx @cobusgreyling/loop-audit . --suggest
+npx @cobusgreyling/loop-cost --pattern daily-triage --level L1 --cadence 1d
+```
+
+Share your score or failure: [Show your loop](https://github.com/cobusgreyling/loop-engineering/discussions/326).