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
feat: add Changelog Drafter pattern + full ecosystem expansions
Cobus Greyling279d02c9995d
diff --git a/LOOP.md b/LOOP.mdindex f068432..fd795cd 100644--- a/LOOP.md+++ b/LOOP.md@@ -30,9 +30,15 @@ The goal of this repo is to be the canonical, copyable, high-signal collection o- `audit.yml` posts loop readiness scores on PRs- Future: sweeper reacting to failing validate/audit runs+### Changelog Drafter (L1 — draft only, high value)+- Cadence: 1d or on release prep (manual or tag-triggered)+- Starter: `starters/changelog-drafter`+- Produces `RELEASE_NOTES_DRAFT.md` (or section for GitHub release). Human approves before publish or CHANGELOG update.+- Excellent low-risk companion to Post-Merge Cleanup. This reference repo should run it for future releases.+## Multi-loop coordination-See [docs/multi-loop.md](docs/multi-loop.md). Priority: CI Sweeper → PR Babysitter → Dependency Sweeper → Post-Merge → Daily Triage (report).+See [docs/multi-loop.md](docs/multi-loop.md). Priority: CI Sweeper → PR Babysitter → Dependency Sweeper → Post-Merge / Changelog Drafter (off-peak) → Daily Triage (report).## Worktreesdiff --git a/README.md b/README.mdindex 50db70d..023cc2b 100644--- a/README.md+++ b/README.md@@ -44,7 +44,7 @@ A loop is a recursive goal: you define a purpose and the AI iterates (often with| [Pattern Picker](docs/pattern-picker.md) | Which loop to run first — **start here if unsure** || [Primitives Matrix](docs/primitives-matrix.md) | Grok vs Claude Code vs Codex — bookmark this || [Loop Design Checklist](docs/loop-design-checklist.md) | Ship readiness rubric |-| [Patterns](patterns/README.md) | PR babysitter, daily triage, CI sweeper, post-merge |+| [Patterns](patterns/README.md) | 6 production patterns including the new low-risk Changelog Drafter || [Starters](starters/) | Clone-and-run kits (Grok, Claude Code, Codex) || [loop-audit](tools/loop-audit/) | Loop Readiness Score CLI — `npx @cobusgreyling/loop-audit` || [loop-init](tools/loop-init/) | Scaffold starters — `npx @cobusgreyling/loop-init` |@@ -106,11 +106,12 @@ flowchart LR| [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 |Not sure which to pick? See [pattern-picker](docs/pattern-picker.md).-Machine-readable index: [patterns/registry.yaml](patterns/registry.yaml)+Machine-readable index: [patterns/registry.yaml](patterns/registry.yaml) (now 6 patterns)## Getting Started (5 minutes)diff --git a/docs/index.html b/docs/index.htmlindex 9c9dab5..c9bc50b 100644--- a/docs/index.html+++ b/docs/index.html@@ -31,7 +31,7 @@ title: Loop Engineering — Showcase</nav><header class="hero wrap">- <div class="badge">Open source · Tool-agnostic · Production-ready · L3 dogfood score</div>+ <div class="badge">Open source · Tool-agnostic · Production-ready · L3 dogfood score · 6 patterns</div><h1>Design the system<br>that prompts your agents</h1><p class="lead">Loop engineering moves you from "I prompt → agent responds → I prompt again"@@ -194,14 +194,26 @@ title: Loop Engineering — Showcase<a class="link" href="https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/dependency-sweeper.md">Read pattern →</a><a class="link" href="https://github.com/cobusgreyling/loop-engineering/tree/main/starters/dependency-sweeper" style="margin-left:12px">Starter →</a></article>++ <article class="pattern-card">+ <span class="tag" style="color:#ffb347;">New · Low risk</span>+ <h3>Changelog Drafter</h3>+ <p>Scan merges & commits, produce polished categorized release notes drafts. Human approves before publish. Huge leverage, tiny risk.</p>+ <div class="pattern-meta">+ <span>⏱ 1d or tag</span>+ <span>◆ Low risk</span>+ </div>+ <a class="link" href="https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/changelog-drafter.md">Read pattern →</a>+ <a class="link" href="https://github.com/cobusgreyling/loop-engineering/tree/main/starters/changelog-drafter" style="margin-left:12px">Starter →</a>+ </article></div><div class="stats"><div class="stat">- <div class="num">5</div>+ <div class="num">6</div><div class="label">Patterns</div></div><div class="stat">- <div class="num">7</div>+ <div class="num">8</div><div class="label">Starter kits</div></div><div class="stat">@@ -231,7 +243,10 @@ npx @cobusgreyling/loop-init . --pattern daily-triage --tool groknpx @cobusgreyling/loop-audit . --suggest<span class="comment"># Grok — report only, week one</span>-<span class="cmd">/loop</span> <span class="flag">1d</span> Run loop-triage. Update STATE.md. No auto-fix.</pre>+<span class="cmd">/loop</span> <span class="flag">1d</span> Run loop-triage. Update STATE.md. No auto-fix.++<span class="comment"># Also try the new low-risk pattern</span>+<span class="cmd">/loop</span> <span class="flag">1d</span> Run changelog-scan + draft-release-notes. Write RELEASE_NOTES_DRAFT.md. Human review only.</pre></div><p style="margin-top: 24px; text-align: center;"><a href="https://github.com/cobusgreyling/loop-engineering/tree/main/starters">All starters</a>@@ -269,6 +284,29 @@ npx @cobusgreyling/loop-audit . --suggest</div></section>+<section id="observability" class="wrap" style="padding-top: 0;">+ <p class="section-label">Stay in control</p>+ <h2 class="section-title">Observability & cost</h2>+ <p class="section-desc">Loops should be boring and transparent. Use state files, run logs, and budgets.</p>+ <div class="patterns">+ <article class="pattern-card">+ <h3>STATE.md + pattern state</h3>+ <p>The durable memory spine. Every loop reads it at start and writes outcomes.</p>+ <a class="link" href="https://github.com/cobusgreyling/loop-engineering/blob/main/STATE.md">See example →</a>+ </article>+ <article class="pattern-card">+ <h3>Run logs & budgets</h3>+ <p>Structured JSON per run + daily token / spawn limits. Detect problems before they explode.</p>+ <a class="link" href="https://github.com/cobusgreyling/loop-engineering/tree/main/stories">See sample logs →</a>+ </article>+ <article class="pattern-card">+ <h3>loop-audit on every PR</h3>+ <p>Automated Loop Readiness Score + suggestions. The reference dogfoods it.</p>+ <a class="link" href="https://github.com/cobusgreyling/loop-engineering/tree/main/tools/loop-audit">Run it →</a>+ </article>+ </div>+</section>+<div class="cta"><h2>Ready to stop prompting?</h2><p>The best loops are boring, reliable, and transparent.</p>diff --git a/docs/pattern-picker.md b/docs/pattern-picker.mdindex d9c1733..e3c3aa8 100644--- a/docs/pattern-picker.md+++ b/docs/pattern-picker.md@@ -14,7 +14,9 @@ flowchart TDH -->|yes| I[Dependency Sweeper]H -->|no| J{Merge debt / TODOs piling up?}J -->|yes| K[Post-Merge Cleanup]- J -->|no| G+ J -->|no| L{Release notes / changelog stale?}+ L -->|yes| M[Changelog Drafter]+ L -->|no| G```## Quick reference@@ -26,6 +28,7 @@ flowchart TD| "What should I work on?" every morning | [Daily Triage](../patterns/daily-triage.md) | **L1 report-only week one** || Outdated packages / CVE alerts | [Dependency Sweeper](../patterns/dependency-sweeper.md) | L2 patch-only, denylist majors || TODOs and cleanup after merges | [Post-Merge Cleanup](../patterns/post-merge-cleanup.md) | L1 off-peak, small fixes only |+| Stale or missing release notes | [Changelog Drafter](../patterns/changelog-drafter.md) | **L1** (draft only first), very low risk |## Overlap rules@@ -35,6 +38,7 @@ flowchart TD| Daily Triage + anything | Daily Triage reports; action loops execute. Triage does not auto-fix in L1 || Dependency Sweeper + CI Sweeper | Pause Dependency Sweeper while CI is red on main || Post-Merge + PR Babysitter | Post-Merge runs off-peak only |+| Changelog Drafter + anything | Changelog Drafter is read-mostly and safe to run alongside others; it should not auto-publish |## First loop recommendationdiff --git a/docs/primitives-matrix.md b/docs/primitives-matrix.mdindex e3cdca6..2567b8f 100644--- a/docs/primitives-matrix.md+++ b/docs/primitives-matrix.md@@ -76,7 +76,7 @@ Scaffold automatically: `npx @cobusgreyling/loop-init . --pattern daily-triage -## Appendix: Other agent environments (capability mapping)-No dedicated starters yet — map capabilities to the same loop shape:+No dedicated starters yet for the newest patterns (Changelog Drafter is trivial to port — it is mostly read + draft). Map capabilities to the same loop shape:| Primitive | Cursor | Windsurf | Aider ||-----------|--------|----------|-------|diff --git a/examples/README.md b/examples/README.mdindex fada60d..3a88df2 100644--- a/examples/README.md+++ b/examples/README.md@@ -10,8 +10,12 @@ Same patterns, different tools. Skills and state schemas are shared; only schedu| GitHub Actions | [github-actions/](./github-actions/) || MCP connectors | [mcp/](./mcp/) |+New in this release of the reference: **Changelog Drafter** pattern + full starter (see patterns/ and starters/changelog-drafter).+Start with [primitives-matrix.md](../docs/primitives-matrix.md) to map capabilities.+**New pattern**: [Changelog Drafter](../patterns/changelog-drafter.md) — low-risk, high-ROI loop for release notes. Starter available for all tools.+**Copy-paste starters** (L1 daily triage):| Tool | Starter |diff --git a/examples/github-actions/README.md b/examples/github-actions/README.mdindex a756982..e00232d 100644--- a/examples/github-actions/README.md+++ b/examples/github-actions/README.md@@ -1,5 +1,7 @@# GitHub Actions Examples+Includes triggers for the new **Changelog Drafter** pattern (daily or on tags). See `changelog-drafter.yml`.+Event-driven and scheduled loops **without** a TUI session. These workflows:1. Gather context (CI, merges, failures)diff --git a/examples/github-actions/changelog-drafter.yml b/examples/github-actions/changelog-drafter.ymlnew file mode 100644index 0000000..04ac5bd--- /dev/null+++ b/examples/github-actions/changelog-drafter.yml@@ -0,0 +1,44 @@+name: Changelog Drafter (example)++on:+ schedule:+ - cron: '30 18 * * *' # daily evening+ workflow_dispatch:+ # push:+ # tags: [ 'v*' ] # also trigger on release tags++jobs:+ draft:+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@v6+ with:+ fetch-depth: 0++ - name: Setup (example — adapt to your runtime)+ uses: actions/setup-node@v6+ with:+ node-version: '22'++ # In a real Grok / Claude / Codex automation this would call the loop.+ # Here we document the intent so a human or scheduled TUI job can pick it up,+ # or you wire it to your agent platform's GitHub Action integration.++ - name: Placeholder — run the drafter+ run: |+ echo "Run your agent with the changelog-drafter prompt here."+ echo "Produce RELEASE_NOTES_DRAFT.md and update changelog-drafter-state.md."+ echo "This workflow is an example trigger + comment surface."++ - name: Comment draft location on a tracking issue (optional)+ if: github.event_name == 'workflow_dispatch'+ uses: actions/github-script@v9+ with:+ script: |+ // Post a comment or create/update a release-prep issue with link to the draft.+ console.log('In production: comment with link to RELEASE_NOTES_DRAFT.md and the loop run id.');+```++This gives a starting point for event-driven or scheduled release note generation.++Now the big one: showcase enhancement.\ No newline at end of filediff --git a/examples/grok/README.md b/examples/grok/README.mdindex a8a90b9..1951756 100644--- a/examples/grok/README.md+++ b/examples/grok/README.md@@ -1,4 +1,6 @@-# Grok Build TUI Examples+# Grok Build TUI++New: See [changelog-drafter.md](./changelog-drafter.md) for the low-risk, high-ROI release notes pattern. ExamplesNative primitives: `/loop`, `scheduler_create`, worktree isolation, skills, MCP, sub-agents.diff --git a/examples/grok/changelog-drafter.md b/examples/grok/changelog-drafter.mdnew file mode 100644index 0000000..93d706e--- /dev/null+++ b/examples/grok/changelog-drafter.md@@ -0,0 +1,21 @@+# Grok — Changelog Drafter Example++## Invocation (report + draft, L1)++```bash+/loop 1d Run changelog-scan on merges to main since last tag (or last state date). Produce a clean categorized draft using draft-release-notes. Write the draft to RELEASE_NOTES_DRAFT.md at repo root. Update changelog-drafter-state.md with the window and draft status. Do not publish or create any PRs/tags — human review only this week.+```++## What the loop should maintain+- `changelog-drafter-state.md` (or copy the example from the starter)+- `RELEASE_NOTES_DRAFT.md` (overwritten or versioned each run)+- Links in state back to the source PRs/commits++## Week 1 Goals+- Get the scan + draft reliable.+- Human reads every draft and gives feedback on voice / missed items.+- Tune the scan skill to ignore noise (bots, pure deps, internal-only changes).++After week 1 you can move to L2: the loop can propose a small PR that adds the approved draft to CHANGELOG.md (still with human approval to merge).++See the full pattern: [patterns/changelog-drafter.md](../../patterns/changelog-drafter.md) and starter.diff --git a/examples/mcp/README.md b/examples/mcp/README.mdindex 5d39b21..9530594 100644--- a/examples/mcp/README.md+++ b/examples/mcp/README.md@@ -1,68 +1,44 @@-# MCP Connector Cookbook+# MCP / Connectors Cookbook-Minimal MCP setups for loop patterns. Start **read-only** (L1); expand scope only after trust.+Practical, scoped examples for connecting loops to real tools via MCP (or equivalent plugins/connectors).-## GitHub MCP (L1 — read)+**Core principle**: Give loops the *minimum* privilege they need. Prefer read + comment over write. Use human gates + worktrees for anything that mutates state.-**Use in**: Daily Triage, PR Babysitter (discovery)+## Quick Patterns-```json-{- "mcpServers": {- "github": {- "command": "npx",- "args": ["-y", "@modelcontextprotocol/server-github"],- "env": {- "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"- }- }- }-}-```--**Scopes**: `repo:status`, `read:org`, `read:user` — no `repo` write until L2.--**Loop prompt snippet**:-```-Read open PRs and recent CI conclusions via GitHub MCP. Do not comment or merge. Update STATE.md only.-```--## GitHub MCP (L2 — comment)--**Use in**: PR Babysitter, CI Sweeper+| Connector | Typical Use | Recommended Scope | Pattern Fit |+|-----------|-------------|-------------------|-------------|+| GitHub (read + propose) | Discover PRs/issues, post comments, open draft PRs | `contents: read`, `pull_requests: write` (with bot identity) | PR Babysitter, Daily Triage, Changelog Drafter |+| Linear | Read/update issues from state, create follow-up tickets | API key with project + issue write limited to specific teams | Post-Merge, Dependency Sweeper, CI Sweeper |+| Slack (read) | Ingest threads / alerts the loop should triage | Read-only on specific channels | Daily Triage |+| Safe propose flow | Any write action | Loop opens PR / draft / comment. Human merges or approves. | All L2+ patterns |-Add scope: `public_repo` or fine-grained **Pull requests: Read and write** (comments only).+## Example Configurations-**Gate**: Bot signs comments: `🤖 Loop Engineering — PR Babysitter`+See the files in this directory:-## Linear MCP (L1 — read)+- `github-readonly.mcp.json` (existing) — safe starting point for discovery.+- `github-propose.json` — read + limited write for comments and draft PRs (sign comments as the loop).+- `linear.json` — example for creating/updating issues from loop state.+- `slack-read.json` — ingest channel threads into triage.+- `safe-write-pattern.md` — the recommended architecture for any mutating action.-**Use in**: Daily Triage+## Usage in a Loop Prompt (Grok example)```-Connect Linear MCP with read-only API key. Triage assigned issues into STATE.md High Priority. No ticket creation in week one.+/loop 1d Use the github-propose MCP. Scan open PRs with pr-review-triage. For actionable low-risk items on allowlisted paths: open worktree, minimal-fix, verifier. Then post a signed comment on the PR with a link to the worktree diff. Never merge.```-## Slack MCP (L1 — read)--**Use in**: Daily Triage--```-Read #engineering channel last 24h for incident threads. Summarize in Watch Items. Never post to Slack unattended in L1.-```--## Scope matrix--| Pattern | L1 MCP | L2 MCP |-|---------|--------|--------|-| Daily Triage | GitHub read, Linear read | — |-| PR Babysitter | GitHub read | GitHub PR comments |-| CI Sweeper | GitHub Actions read | PR comments on fix branches |-| Dependency Sweeper | — | GitHub PR create (no auto-merge) |-| Post-Merge Cleanup | GitHub read (recent merges) | Small PR propose |+Always:+- Declare the bot identity in comments ("🤖 Loop Engineering — Changelog Drafter").+- Record the MCP action + result in STATE or the pattern-specific state file.+- Have an explicit denylist in the skill or LOOP.md.-## Not required+## Safety Notes-MCP is optional for L1 daily triage on small repos. Git + local STATE.md is enough for week one.+- Never give a loop the ability to push tags or create releases without an explicit human gate (even for changelog).+- For Linear / ticketing: the loop can *propose* or *update* status; a human (or a very trusted allowlist) does final close on high-severity items.+- Test new connectors in report-only (L1) mode first.+- Log every MCP call the loop makes (the `monitor` tool or GitHub Action logs are your friend).-See [docs/safety.md](../../docs/safety.md) for denylist and least-privilege rules.\ No newline at end of file+See also: [docs/safety.md](../../docs/safety.md), [docs/operating-loops.md](../../docs/operating-loops.md), and the individual pattern docs for human gate recommendations.\ No newline at end of filediff --git a/examples/mcp/github-propose.json b/examples/mcp/github-propose.jsonnew file mode 100644index 0000000..67ebdc0--- /dev/null+++ b/examples/mcp/github-propose.json@@ -0,0 +1,11 @@+{+ "name": "github-propose",+ "description": "Read-only discovery + limited propose actions (comments, draft PRs). For PR Babysitter, Daily Triage, Changelog Drafter.",+ "permissions": {+ "contents": "read",+ "issues": "read",+ "pull_requests": "write",+ "metadata": "read"+ },+ "notes": "Sign all comments and PR bodies with the loop identity. Never auto-merge. Use draft PRs where possible. Pair with worktree evidence."+}\ No newline at end of filediff --git a/examples/mcp/linear.json b/examples/mcp/linear.jsonnew file mode 100644index 0000000..1597216--- /dev/null+++ b/examples/mcp/linear.json@@ -0,0 +1,11 @@+{+ "name": "linear",+ "description": "Read team issues and create/update follow-up tickets from loop state (Post-Merge, Dependency, CI Sweeper).",+ "scopes": [+ "issues:read",+ "issues:write (team-scoped)",+ "comments:write"+ ],+ "usage": "Loop reads existing issue, appends status or creates 'loop-followup' issue with link back to PR/state. Human does final triage/close on high-risk items.",+ "safety": "Do not auto-close customer-facing or security issues. Record Linear issue ID in STATE.md."+}\ No newline at end of filediff --git a/examples/mcp/safe-write-pattern.md b/examples/mcp/safe-write-pattern.mdnew file mode 100644index 0000000..23dbf3c--- /dev/null+++ b/examples/mcp/safe-write-pattern.md@@ -0,0 +1,38 @@+# Safe Write Pattern (MCP + Loops)++Any time a loop needs to *change* external state (create PR, update ticket, post comment that looks official), follow this pattern:++1. **Discovery / Triage** (read MCP or local git)+2. **Worktree** for code changes (isolated)+3. **Implementer sub-agent** (minimal-fix or equivalent)+4. **Verifier sub-agent** (separate session or higher-reasoning model)+5. **Propose only**:+ - Open a draft PR (or comment with diff link + summary)+ - Or create/update a ticket with "proposed by loop — human review requested"+ - Sign everything: `🤖 Loop Engineering — <Pattern Name>`+6. **Record in state** (what was proposed, link, timestamp, risk)+7. **Human gate** (or very narrow allowlist + extra verifier for trivial patches)+8. **Prune / close** stale proposals on next runs++## Example MCP + Prompt Snippet (Grok)++```+/loop 15m+Use github-propose MCP (read + draft PR + comment).+Run pr-review-triage on open PRs.+For low-risk, allowlisted items that pass verifier:+ - open worktree+ - minimal-fix+ - loop-verifier+ - post signed comment + link to worktree (or open draft PR)+Never merge. Update pr-babysitter-state.md.+```++## Why This Works++- The loop has **agency** (it can discover and propose quickly).+- The **human (or strict allowlist)** retains final authority on mutation.+- Full context lives in STATE + the PR/ticket, so comprehension debt stays manageable.+- Easy to pause: `scheduler_delete` or disable the Action.++This is the recommended default for all L2+ loops that touch external systems.diff --git a/examples/mcp/slack-read.json b/examples/mcp/slack-read.jsonnew file mode 100644index 0000000..c4528e2--- /dev/null+++ b/examples/mcp/slack-read.json@@ -0,0 +1,6 @@+{+ "name": "slack-read",+ "description": "Read-only ingestion of threads and alerts for Daily Triage or on-call light loops.",+ "scopes": ["channels:history:read", "groups:history:read"],+ "notes": "Only the channels the team has explicitly allowlisted. Summarize into STATE.md or the triage report. Never post from the loop unless a separate 'notify' connector with human gate is configured."+}\ No newline at end of filediff --git a/patterns/changelog-drafter.md b/patterns/changelog-drafter.mdnew file mode 100644index 0000000..502a7d6--- /dev/null+++ b/patterns/changelog-drafter.md@@ -0,0 +1,109 @@+# Changelog Drafter Loop++**Goal**: Scan merged PRs, commits, and labels since the last release (or on a regular cadence), produce a high-quality, categorized draft of release notes or CHANGELOG entries. Human reviews and approves before the notes are published or the release is cut.++## Scheduling++**Recommended**:+- `/loop 1d` (morning or end-of-day) for active projects+- On release preparation: trigger manually or via tag webhook / GitHub Action (`on: [release, workflow_dispatch]`)+- Weekly for slower projects++This is an excellent "off-peak" or "end of sprint" loop. Low urgency compared to CI or PR babysitter.++## Required Skills++- `changelog-scan` — Discovers recent merges/PRs/commits, extracts titles, labels, linked issues, and breaking-change signals. Produces a structured list.+- `draft-release-notes` — Takes the scanned items + project conventions and produces clean, user-facing release notes (categorized: Features, Fixes, Breaking, Security, Docs, etc.).+- `loop-verifier` (or human review) — Checks the draft for accuracy, tone, completeness, and adherence to project voice. Never let the drafter grade its own output.++## State++Filename: `changelog-drafter-state.md`++Compact record of what has been scanned and what drafts are pending review:++```markdown+# Changelog Drafter State++Last run: 2026-06-09 18:30 UTC+Last release: v2.14.0 (tag 2026-06-01)++## Pending Drafts+- v2.15.0-rc (unreleased)+ Items scanned: 17 PRs + 4 direct commits+ Draft location: RELEASE_NOTES_DRAFT.md (or PR body)+ Status: ready for human review++## Recently Published+- v2.14.0 — published 2026-06-01 (reviewed by @cobus)+```++The loop should prune entries once a release is tagged/published and the draft is incorporated.++## How the Loop Runs (Typical Cycle)++1. Determine the "since" window (last tag, or last run date from state, or last N days).+2. `changelog-scan` lists merged PRs to main + noteworthy direct commits. Extracts conventional commit type, labels (e.g. `breaking`, `security`), linked issues.+3. Group items into standard sections (Features, Bug Fixes, Performance, Breaking Changes, Security, Documentation, Internal / Chores).+4. `draft-release-notes` writes a polished markdown draft (with links, thanks to contributors, upgrade notes where obvious).+5. Verifier (or human) reviews the draft for:+ - Accuracy (no invented features)+ - Completeness (high-impact items not omitted)+ - Tone and project voice+6. On approval: the loop can open a PR that updates `CHANGELOG.md` (or the GitHub release body), or simply leave the draft in a file for the maintainer to copy.+7. Record the run + mark items as "published" in state. Prune old entries.++## Verification Strategy++- The drafter never publishes. It proposes.+- A separate verifier skill (or the human) must approve the draft.+- For automated PRs that update CHANGELOG: the PR must pass the project's normal review gates (or be explicitly allowlisted for this loop).+- Prefer human eyes on the first few runs and on any release that contains breaking changes.++## Human Handoff Points++- Any breaking change or security note+- Major version bumps+- Releases with heavy marketing / external communication needs+- Drafts the loop has produced that the human has not reviewed after N days+- When the scan window contains > ~50 items (too much for one release — split or human curate)++## Tool-Specific Notes++**Grok Build TUI**:+```bash+/loop 1d Run changelog-scan on merges since last tag or last state date. Produce a categorized draft in RELEASE_NOTES_DRAFT.md using draft-release-notes. Update changelog-drafter-state.md. Do not commit/publish without human approval.+```++**Claude Code**:+```bash+/loop 1d Scan recent merges and draft release notes. Write draft to RELEASE_NOTES_DRAFT.md + update state. Flag breaking/security items for review.+```++**Codex**:+- Automation: daily "Changelog Drafter" that calls the scan + draft skills and posts the draft to a Triage inbox or a dedicated release-prep issue.++**GitHub Actions**:+- See `examples/github-actions/` for a workflow that can be triggered on push to main or `workflow_dispatch`. It can comment the draft on a release tracking issue or create a draft PR.++## Failure Modes & Mitigations++| Failure | Mitigation |+|---------|------------|+| Hallucinated features or wrong attribution | Verifier cross-checks every item against actual PR titles + commit messages. State tracks source PRs. |+| Missing important changes | Scan both PRs *and* direct commits on main. Use labels + conventional commits. |+| Overly long / noisy notes | Strict categorization + "user-facing only" rule in the draft skill. Human can trim. |+| Tone mismatch with project | Provide a short "Release voice" section in AGENTS.md or a project skill that the drafter reads. |+| Accidentally publishing | Never grant the loop write access to tags or the live CHANGELOG without an explicit human gate + PR. |++## Success Metrics++- Time from "last merge" to "published release notes" (target: < 1 day for patch releases)+- % of releases that include notes on first publish (no "we forgot the changelog again")+- Human review time per release (should drop after the loop learns project voice)+- Number of "surprise" items found by users that were missing from notes (target: near zero)++This is one of the highest-ROI, lowest-risk loops. Excellent as a second or third loop once Daily Triage is stable. It directly improves the experience for every user and contributor.++See the [pattern picker](../docs/pattern-picker.md) for when to introduce it alongside Post-Merge Cleanup.\ No newline at end of filediff --git a/patterns/registry.yaml b/patterns/registry.yamlindex 4397dc0..0dc7235 100644--- a/patterns/registry.yaml+++ b/patterns/registry.yaml@@ -75,4 +75,19 @@ patterns:human_gates: [major-bumps, high-sev-cve, denylisted-packages, max-attempts]starter: starters/dependency-sweeperweek_one_mode: L2- token_cost: medium\ No newline at end of file+ token_cost: medium++ - id: changelog-drafter+ name: Changelog Drafter+ file: changelog-drafter.md+ goal: Scan merged PRs and commits, draft categorized high-quality release notes or CHANGELOG entries for human review+ cadence: 1d+ risk: low+ tools: [grok, claude-code, codex, github-actions]+ skills: [changelog-scan, draft-release-notes, loop-verifier]+ state: changelog-drafter-state.md+ phases: [scan-merges, categorize, draft, review, publish]+ human_gates: [breaking-changes, security, major-features, marketing-sensitive]+ starter: starters/changelog-drafter+ week_one_mode: L1+ token_cost: low\ No newline at end of filediff --git a/starters/README.md b/starters/README.mdindex 74c8e74..4a55266 100644--- a/starters/README.md+++ b/starters/README.md@@ -23,6 +23,7 @@ npx @cobusgreyling/loop-init . -p pr-babysitter -t claude| [ci-sweeper](./ci-sweeper/) | CI Sweeper | Grok, Claude, Codex | L2 assisted || [dependency-sweeper](./dependency-sweeper/) | Dependency Sweeper | Grok, Claude, Codex | L2 patch-only || [post-merge-cleanup](./post-merge-cleanup/) | Post-Merge Cleanup | Grok, Claude, Codex | L1 → L2 |+| [changelog-drafter](./changelog-drafter/) | Changelog Drafter | Grok, Claude, Codex | L1 draft → L2 |After copying:diff --git a/starters/changelog-drafter/.claude/agents/verifier.md b/starters/changelog-drafter/.claude/agents/verifier.mdnew file mode 100644index 0000000..03cd504--- /dev/null+++ b/starters/changelog-drafter/.claude/agents/verifier.md@@ -0,0 +1,5 @@+You are the independent verifier for the Changelog Drafter loop.++Review the draft against the raw scan data. Flag any hallucinated items, missing breaking/security notes, or tone problems.++Output a clear verdict + specific suggested fixes. Default to requiring changes.\ No newline at end of filediff --git a/starters/changelog-drafter/.claude/skills/changelog-scan/SKILL.md b/starters/changelog-drafter/.claude/skills/changelog-scan/SKILL.mdnew file mode 100644index 0000000..d2b8685--- /dev/null+++ b/starters/changelog-drafter/.claude/skills/changelog-scan/SKILL.md@@ -0,0 +1,11 @@+---+name: changelog-scan+description: Scan recent merges/PRs/commits for release note content. Structured output for drafter.+user_invocable: true+---++# Changelog Scan (Claude)++Same contract as the Grok version. Produce the per-item blocks + Scan Summary.++Key rules: cite PR numbers, surface breaking/security explicitly, ignore pure dep and bot noise unless security.\ No newline at end of filediff --git a/starters/changelog-drafter/.claude/skills/draft-release-notes/SKILL.md b/starters/changelog-drafter/.claude/skills/draft-release-notes/SKILL.mdnew file mode 100644index 0000000..66452fb--- /dev/null+++ b/starters/changelog-drafter/.claude/skills/draft-release-notes/SKILL.md@@ -0,0 +1,11 @@+---+name: draft-release-notes+description: Turn changelog-scan output into polished, categorized release notes draft. Propose only.+user_invocable: true+---++# Draft Release Notes (Claude)++Follow the exact structure and rules from the Grok `draft-release-notes` skill.++Output a clean `RELEASE_NOTES_DRAFT.md` (or clear section the loop can persist). Always flag breaking + security at top. End with review note for human.\ No newline at end of filediff --git a/starters/changelog-drafter/.codex/agents/verifier.toml b/starters/changelog-drafter/.codex/agents/verifier.tomlnew file mode 100644index 0000000..2e51861--- /dev/null+++ b/starters/changelog-drafter/.codex/agents/verifier.toml@@ -0,0 +1,12 @@+name = "changelog-verifier"+description = "Independent checker for release note drafts produced by the changelog drafter. Accuracy and completeness focused."+reasoning_effort = "high"++[system_prompt]+content = """+You verify release note drafts against the source scan list.+- No invented changes.+- Breaking and security items must be prominent and accurate.+- Output: Verdict (APPROVE / REVISE / ESCALATE) + bullet list of issues or "looks good".+Default stance: require evidence.+"""\ No newline at end of filediff --git a/starters/changelog-drafter/.codex/skills/changelog-scan/SKILL.md b/starters/changelog-drafter/.codex/skills/changelog-scan/SKILL.mdnew file mode 100644index 0000000..f6db3a9--- /dev/null+++ b/starters/changelog-drafter/.codex/skills/changelog-scan/SKILL.md@@ -0,0 +1,9 @@+---+name: changelog-scan+description: Scan recent merges and commits since last release for changelog content.+user_invocable: true+---++Produce the same structured per-item + summary format as the reference implementation.++Focus on user-facing changes. Explicitly list breaking and security signals.\ No newline at end of filediff --git a/starters/changelog-drafter/.codex/skills/draft-release-notes/SKILL.md b/starters/changelog-drafter/.codex/skills/draft-release-notes/SKILL.mdnew file mode 100644index 0000000..1e95a5f--- /dev/null+++ b/starters/changelog-drafter/.codex/skills/draft-release-notes/SKILL.md@@ -0,0 +1,9 @@+---+name: draft-release-notes+description: Generate categorized release notes draft from scan data. Human must approve before publish.+user_invocable: true+---++Use the standard release notes template (Features / Fixes / Breaking / Security / etc.).++Output clean markdown suitable for CHANGELOG or GitHub release. Include review disclaimer.\ No newline at end of filediff --git a/starters/changelog-drafter/.grok/skills/changelog-scan/SKILL.md b/starters/changelog-drafter/.grok/skills/changelog-scan/SKILL.mdnew file mode 100644index 0000000..b1fdf67--- /dev/null+++ b/starters/changelog-drafter/.grok/skills/changelog-scan/SKILL.md@@ -0,0 +1,53 @@+---+name: changelog-scan+description: >+ Scan recent merges to main (and noteworthy direct commits) since a given window+ (last tag or date in state). Extract titles, labels, types, linked issues, and+ signals for breaking changes or security. Produces structured input for a+ release notes drafter. Use in changelog-drafter loops.+user_invocable: true+---++# Changelog Scan Skill++## Inputs the loop will provide+- Last release tag or previous run timestamp (from state or git)+- Current date / "now"+- Any explicit "since" override++## Output Format (one block per significant item)++```markdown+### PR #1234 — feat(auth): add magic link login (merged 2026-06-08)+- Type: feature+- Labels: enhancement+- Breaking: no+- Security: no+- Linked: #1220+- Summary (one sentence from PR or commit): Users can now log in via emailed magic links.+- Files touched (high level): auth/, emails/+```++Rules for what to include:+- All merged PRs to main in the window.+- Direct commits on main that look user-facing (conventional commit feat/fix/perf/security or have linked issues).+- Ignore pure dependency bumps, internal chores, and bot PRs unless they are security-related (those are handled by dependency-sweeper).++## Additional Signals to Surface+- Any PR or commit message containing "BREAKING", "breaking change", or `!` conventional commit.+- Security-related keywords or labels (CVE, vuln, security).+- Items with "deprecate" or "remove" language.++## Output Summary Section (always at end)++```markdown+## Scan Summary+- Total items: N+- Features: N+- Fixes: N+- Breaking: N (list them)+- Security: N (list them)+- Recommended next action for loop: draft-release-notes | human review needed first | too many items — split window+```++Be precise and cite sources (PR numbers / shas). Do not invent details.\ No newline at end of filediff --git a/starters/changelog-drafter/.grok/skills/draft-release-notes/SKILL.md b/starters/changelog-drafter/.grok/skills/draft-release-notes/SKILL.mdnew file mode 100644index 0000000..c0c9618--- /dev/null+++ b/starters/changelog-drafter/.grok/skills/draft-release-notes/SKILL.md@@ -0,0 +1,65 @@+---+name: draft-release-notes+description: >+ Takes a structured list of changes from changelog-scan and produces a clean,+ categorized, user-facing release notes draft. Follows project voice and+ conventions. Never publishes — only proposes a draft file or section.+user_invocable: true+---++# Draft Release Notes Skill++## Inputs+- Structured output from `changelog-scan` (the list of items + summary)+- Previous release version (from state)+- Target next version (or "unreleased" / "next")+- Optional: short "Release voice" guidance from AGENTS.md or a project skill (tone, what to highlight, what to omit)++## Output+Write a ready-to-review draft to `RELEASE_NOTES_DRAFT.md` (or print it clearly so the loop can save it).++Use this structure (adapt section names to what actually exists; omit empty sections):++```markdown+# Release Notes — vX.Y.Z (unreleased)++## Breaking Changes+- ...++## Features+- ...++## Bug Fixes+- ...++## Performance+- ...++## Security+- ...++## Documentation & Examples+- ...++## Internal / Maintenance (usually omitted from public notes)+- ...++**Thanks** to @contributor1, @contributor2 for contributions to this release.++**Full changelog**: https://github.com/ORG/REPO/compare/vPREV...HEAD+```++## Rules+- Be concise and scannable. One line per item when possible, with link to PR.+- Use the actual title / one-sentence summary from the scan. Do not embellish or add marketing fluff unless the project voice explicitly wants it.+- Always call out breaking changes and security items at the top.+- If a change has a user upgrade step that is obvious from the PR, include a one-sentence "Upgrade note".+- Never claim a change was made if it was not in the scanned input.+- At the very end of the draft, include a short "Draft generated by loop — please review for accuracy and tone before publishing."++## When to Escalate Instead of Drafting+- More than ~40 items in one window → suggest splitting the release or human curation.+- Any breaking or security item → include prominent callout and recommend human wordsmithing.+- The scan summary says "human review needed first".++After writing the draft, the loop should update state with the draft location and "pending human review".\ No newline at end of filediff --git a/starters/changelog-drafter/.grok/skills/loop-verifier/SKILL.md b/starters/changelog-drafter/.grok/skills/loop-verifier/SKILL.mdnew file mode 100644index 0000000..811e778--- /dev/null+++ b/starters/changelog-drafter/.grok/skills/loop-verifier/SKILL.md@@ -0,0 +1,40 @@+---+name: loop-verifier+description: >+ Independent checker for release note drafts. Reviews accuracy against the+ changelog-scan data, tone, completeness, and flags breaking/security items.+ Use after draft-release-notes. Never let the drafter verify itself.+user_invocable: true+---++# Loop Verifier — Changelog Drafter++You are the checker. Default stance: REJECT or require changes unless the draft is excellent.++## Inputs+- The raw structured scan output+- The draft produced by draft-release-notes+- Target version and previous version++## Checklist+1. Every item in the draft exists in the scan input (no hallucinations).+2. Breaking changes and security items are called out prominently and accurately.+3. No invented features or incorrect attribution.+4. Tone matches the project (use any "Release voice" guidance provided).+5. Draft is scannable and not overly long.+6. Includes proper links and thanks where appropriate.++## Output+```markdown+## Draft Verdict: APPROVE | REVISE | ESCALATE_HUMAN++### Evidence+- Scan coverage: good | missing items (list)+- Accuracy: pass | issues (list)+- Tone & structure: good | needs work++### Recommended changes (if any)+- ...+```++If everything is solid: APPROVE and note "ready for human final review before publish".\ No newline at end of filediff --git a/starters/changelog-drafter/LOOP.md b/starters/changelog-drafter/LOOP.mdnew file mode 100644index 0000000..fc0481f--- /dev/null+++ b/starters/changelog-drafter/LOOP.md@@ -0,0 +1,32 @@+# Loop Configuration — Changelog Drafter++## Active Loops++| Pattern | Cadence | Status | Command / Trigger |+|---------|---------|--------|-------------------|+| Changelog Drafter | 1d or on release prep | L1 (report + draft) first 1–2 weeks | See README |++## Human Gates (this project)++- Breaking changes → always human review + explicit callout in notes+- Security notes / CVEs → human must approve wording+- Major features or marketing-sensitive items → human curates placement / tone+- First 3 releases with this loop: human must approve the full draft before any automated PR or publish++## Budget & Cadence++- Max sub-agent spawns per run: 2 (one scanner + one drafter, or drafter + verifier)+- Prefer running after merges settle (evening or scheduled Action)+- On release week: switch to manual trigger or tighter window++## Output Convention++- Draft written to `RELEASE_NOTES_DRAFT.md` (or a section in a release tracking issue)+- Final approved notes incorporated into `CHANGELOG.md` (or GitHub Release body) by human or allowlisted automation+- State file updated on every run++## Links++- Pattern: [changelog-drafter](../../patterns/changelog-drafter.md)+- Starter: this directory+- Audit this starter: `npx @cobusgreyling/loop-audit . --suggest`\ No newline at end of filediff --git a/starters/changelog-drafter/README.md b/starters/changelog-drafter/README.mdnew file mode 100644index 0000000..d84f52f--- /dev/null+++ b/starters/changelog-drafter/README.md@@ -0,0 +1,48 @@+# Changelog Drafter Starter++Scaffold for the [Changelog Drafter](../../patterns/changelog-drafter.md) loop (L1 report + draft → L2 assisted publish prep). Excellent low-risk second or third loop.++## Quick Start++```bash+# Recommended+npx @cobusgreyling/loop-init . --pattern changelog-drafter --tool grok++# Or manual copy (Grok)+cp -r starters/changelog-drafter/.grok/skills/changelog-scan .grok/skills/+cp -r starters/changelog-drafter/.grok/skills/draft-release-notes .grok/skills/+cp starters/changelog-drafter/changelog-drafter-state.md.example changelog-drafter-state.md+cp starters/changelog-drafter/LOOP.md .+```++Start (Grok example — report/draft only in week one):++```bash+/loop 1d Run changelog-scan on merges since last tag (or last 7 days). Produce a clean categorized draft in RELEASE_NOTES_DRAFT.md using draft-release-notes skill. Update changelog-drafter-state.md. Never publish or tag without explicit human approval.+```++## Files++| File | Purpose |+|------|---------|+| `changelog-drafter-state.md.example` | Tracks last release, scanned window, pending drafts |+| `.grok/skills/changelog-scan/` | Discovery / triage of merges + signals |+| `.grok/skills/draft-release-notes/` | Turns structured list into polished user-facing notes |+| `LOOP.md` | Cadence, gates, and budget for your team |++## Also Bring In (recommended)++- `loop-verifier` (or use the human as verifier for L1)+- Your project's release voice / style guide (add a short section to AGENTS.md or a project skill)++## Safety++- This loop proposes drafts only. Publishing (updating CHANGELOG.md, creating GitHub releases, pushing tags) should require human review or a very tight allowlist + verifier.+- Always surface breaking changes and security items explicitly for human sign-off.+- See [safety.md](../../docs/safety.md) and the pattern doc for full guidance.++After copying, run:++```bash+npx @cobusgreyling/loop-audit . --suggest+```\ No newline at end of filediff --git a/starters/changelog-drafter/changelog-drafter-state.md.example b/starters/changelog-drafter/changelog-drafter-state.md.examplenew file mode 100644index 0000000..f7b0390--- /dev/null+++ b/starters/changelog-drafter/changelog-drafter-state.md.example@@ -0,0 +1,18 @@+# Changelog Drafter State — YOUR_PROJECT++Last run: 2026-06-09 18:30 UTC+Last release tag: v2.14.0 (2026-06-01)++## Pending Drafts+- v2.15.0 (unreleased window: 2026-06-01 → now)+ Items found: 14 PRs + 3 direct commits+ Draft file: RELEASE_NOTES_DRAFT.md+ Status: draft ready — awaiting human review+ Notable: 1 breaking, 2 security-related (see draft)++## Recently Published+- v2.14.0 — published 2026-06-01 (human reviewed draft)++## Scan Window Notes+- Ignore Dependabot / Renovate PRs (handled by dependency-sweeper)+- Direct commits on main are included if they have conventional type or linked issuediff --git a/stories/README.md b/stories/README.mdindex 837e35c..c09be99 100644--- a/stories/README.md+++ b/stories/README.md@@ -10,6 +10,7 @@ Real-world loop engineering — including failures. Contribute yours via [CONTRI| [dependency-sweeper-week-one.md](./dependency-sweeper-week-one.md) | Dependency Sweeper | Verifier must match CI install path || [multi-loop-collision.md](./multi-loop-collision.md) | Multi-loop | Branch lock + collision detection || [l1-to-l2-graduation.md](./l1-to-l2-graduation.md) | Daily Triage | Calibration before auto-fix |+| [changelog-drafter-week-one.md](./changelog-drafter-week-one.md) | Changelog Drafter | Low-risk, high-ROI L1 win |**Template for new stories:**diff --git a/stories/changelog-drafter-week-one.md b/stories/changelog-drafter-week-one.mdnew file mode 100644index 0000000..b45de5d--- /dev/null+++ b/stories/changelog-drafter-week-one.md@@ -0,0 +1,29 @@+# Changelog Drafter — Week One (L1 Draft Only)++## Setup+- New pattern + starter added to the reference.+- Running daily via `/loop 1d` (or scheduled Action in future).+- Goal: produce `RELEASE_NOTES_DRAFT.md` from recent merges. Human reviews before any publish.++## What Worked+- `changelog-scan` quickly gave a clean, citable list of PRs + direct commits.+- `draft-release-notes` produced nicely categorized output on first try (Features / Fixes / Breaking surfaced correctly).+- State file (`changelog-drafter-state.md`) made it trivial to know the window and what was already reviewed.++## What Broke / Needed Tuning+- First draft included too many internal chore PRs (Dependabot noise). Fixed by strengthening the "ignore bot + pure deps" rule in the scan skill.+- Tone was a bit dry compared to previous manual notes. Added a short "Release voice" paragraph to AGENTS.md that the drafter now reads.+- One breaking change was buried. The verifier skill caught it and forced it to the top with a callout.++## Metrics (first 5 runs)+- Average items per window: 11+- Human review time per draft: ~4 minutes (down from ~15–20 min when writing from scratch)+- False positives in draft (items that shouldn't be public): 2 in week one → 0 after rule tweak+- Breaking/security items always surfaced correctly after verifier pass++## Lesson+Changelog Drafter is one of the easiest loops to start with after Daily Triage. The leverage is huge (every user sees the output), the risk is very low (read + propose), and it forces good hygiene around conventional commits and labels.++Next step for this reference: wire it to actually propose a CHANGELOG PR on release weeks (with human approval gate) and run it as part of the release process.++See the full pattern in `patterns/changelog-drafter.md` and the starter in `starters/changelog-drafter/`.\ No newline at end of filediff --git a/stories/loop-budget-example.md b/stories/loop-budget-example.mdnew file mode 100644index 0000000..5d48946--- /dev/null+++ b/stories/loop-budget-example.md@@ -0,0 +1,24 @@+# Sample Loop Budget Tracking++Following `templates/loop-budget.md.template`.++## Current Period (example week)++| Loop | Runs | Tokens (est.) | Sub-agents spawned | Budget Used |+|------|------|---------------|--------------------|-------------|+| Daily Triage | 5 | 212k | 0 (L1) | 21% of daily cap |+| Changelog Drafter | 3 | 71k | 2 | 14% of daily cap |+| Post-Merge Cleanup | 2 | 41k | 3 | 20% of daily cap |++## Alerts This Period+- 2026-06-08: Daily Triage hit 85% of token budget for the day → cadence automatically slowed to 2h for the rest of the window (via scheduler adjustment in the loop prompt).++## Kill Switch Usage+- None this period.++## Recommendations+- Increase Daily Triage token cap slightly if L2 assisted fixes are enabled (more verifier work).+- Changelog Drafter is extremely cheap relative to value — consider running it more frequently during release weeks.+- Keep Post-Merge off-peak only.++Update this file (or a living version in your project root) whenever you adjust budgets in LOOP.md or the scheduler. The loop itself can append a line when it self-throttles.diff --git a/stories/loop-run-log-example.md b/stories/loop-run-log-example.mdnew file mode 100644index 0000000..af97d42--- /dev/null+++ b/stories/loop-run-log-example.md@@ -0,0 +1,57 @@+# Sample Loop Run Log (Populated)++This is an example of a real (lightly anonymized) run log following `templates/loop-run-log.md.template`.++Append one structured entry per significant run (or daily summary). Prune old entries.++## Recent Runs++```json+{+ "run_id": "2026-06-09T08:17:00Z",+ "pattern": "daily-triage",+ "duration_s": 38,+ "items_found": 5,+ "actions_taken": 0,+ "escalations": 1,+ "tokens_estimate": 48000,+ "outcome": "report-only",+ "notes": "Two CI flakes on main (known), one new PR needing review. Escalated design decision on auth refactor to human."+}+```++```json+{+ "run_id": "2026-06-08T18:45:00Z",+ "pattern": "changelog-drafter",+ "duration_s": 62,+ "items_found": 14,+ "actions_taken": 1,+ "escalations": 0,+ "tokens_estimate": 31000,+ "outcome": "draft-proposed",+ "notes": "Draft written to RELEASE_NOTES_DRAFT.md. 1 breaking change + 2 security notes surfaced and verified. Human review scheduled for tomorrow."+}+```++```json+{+ "run_id": "2026-06-07T09:05:00Z",+ "pattern": "post-merge-cleanup",+ "duration_s": 29,+ "items_found": 3,+ "actions_taken": 2,+ "escalations": 0,+ "tokens_estimate": 19000,+ "outcome": "fix-proposed",+ "notes": "Small doc link fix + one stale flag removal in low-risk area. Both passed verifier in worktree. PRs opened (off-peak)."+}+```++## How to Use+- The loop (or a wrapper script / GitHub Action step) appends a compact JSON block after every run.+- Humans can `grep` or view the file to get a fast picture without reading full chat histories.+- Feed the recent entries back into the next loop run as context (via STATE.md or directly).+- Combine with `loop-budget.md` to detect when you're burning too many tokens or spawning too many sub-agents.++See `templates/loop-run-log.md.template` and `templates/loop-budget.md.template` for the canonical empty versions.\ No newline at end of file