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: Jul 7 housekeeping — star-history, Hermes docs, release draft (#191)

Cobus Greyling395ccf7a33a0
diff --git a/.github/workflows/update-star-history.yml b/.github/workflows/update-star-history.yml
index 95b7248..5d4c188 100644
--- a/.github/workflows/update-star-history.yml
+++ b/.github/workflows/update-star-history.yml
@@ -7,6 +7,8 @@ on:
permissions:
contents: write
+ pull-requests: write
+ statuses: write
jobs:
update:
@@ -21,9 +23,96 @@ jobs:
gh auth setup-git
python3 scripts/generate-star-history.py
- - name: Commit chart if changed
- uses: stefanzweifel/git-auto-commit-action@v7
+ - name: Run validate gates (for PR status)
+ id: validate_gates
+ continue-on-error: true
+ run: bash scripts/ci-validate-gates.sh
+
+ - name: Run audit gates (for PR status)
+ id: audit_gates
+ continue-on-error: true
+ run: bash scripts/ci-audit-gates.sh
+
+ - name: Fail the run if either gate failed
+ if: steps.validate_gates.outcome == 'failure' || steps.audit_gates.outcome == 'failure'
+ run: |
+ echo "validate gates: ${{ steps.validate_gates.outcome }}"
+ echo "audit gates: ${{ steps.audit_gates.outcome }}"
+ echo "One or more dogfood gates failed — not opening an automated PR."
+ exit 1
+
+ - name: Open PR for chart SVGs if changed
+ id: pr
+ env:
+ GH_TOKEN: ${{ github.token }}
+ run: |
+ git config user.name "github-actions[bot]"
+ git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+ if git diff --quiet assets/visuals/star-history.svg assets/visuals/star-history-dark.svg; then
+ echo "No chart changes — skip PR"
+ echo "opened=false" >> "$GITHUB_OUTPUT"
+ exit 0
+ fi
+
+ BRANCH="automated/star-history-$(date -u +%Y-%m-%d)"
+ git fetch origin main "$BRANCH" 2>/dev/null || git fetch origin main
+ git checkout -B "$BRANCH"
+ git add assets/visuals/star-history.svg assets/visuals/star-history-dark.svg
+ git commit -m "chore: update star-history chart SVGs"
+ if git rev-parse --verify "refs/remotes/origin/${BRANCH}" >/dev/null 2>&1; then
+ git rebase "origin/${BRANCH}"
+ fi
+ git push -u origin "$BRANCH" --force-with-lease
+ echo "head_sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+ echo "branch=${BRANCH}" >> "$GITHUB_OUTPUT"
+ echo "opened=true" >> "$GITHUB_OUTPUT"
+
+ EXISTING=$(gh pr list --head "${{ github.repository_owner }}:${BRANCH}" --base main --state open --json number -q '.[0].number' 2>/dev/null || true)
+ if [ -n "$EXISTING" ] && [ "$EXISTING" != "null" ]; then
+ echo "PR #$EXISTING already open"
+ PR_NUMBER="$EXISTING"
+ else
+ gh pr create \
+ --base main \
+ --head "$BRANCH" \
+ --title "chore: update star-history chart $(date -u +%Y-%m-%d)" \
+ --body "Automated star-history SVG refresh from \`update-star-history.yml\`.
+
+ Branch protection requires PR merge — direct pushes to \`main\` are blocked."
+ PR_NUMBER=$(gh pr view "$BRANCH" --json number -q '.number')
+ fi
+ echo "number=${PR_NUMBER}" >> "$GITHUB_OUTPUT"
+ gh pr merge "$PR_NUMBER" --auto --squash --delete-branch
+
+ - name: Post required commit statuses for branch protection
+ if: steps.pr.outputs.opened == 'true'
+ uses: actions/github-script@v9
with:
- commit_message: 'chore: update star-history chart SVGs'
- file_pattern: assets/visuals/star-history.svg assets/visuals/star-history-dark.svg
- branch: main
\ No newline at end of file
+ script: |
+ const sha = '${{ steps.pr.outputs.head_sha }}';
+ if (!sha) {
+ core.setFailed('Missing head_sha for commit statuses');
+ return;
+ }
+ const toState = (outcome) => (outcome === 'success' ? 'success' : 'failure');
+ const checks = [
+ {
+ context: 'validate',
+ description: 'Pattern/registry gates (star-history inline)',
+ state: toState('${{ steps.validate_gates.outcome }}'),
+ },
+ {
+ context: 'audit',
+ description: 'Loop readiness gates (star-history inline)',
+ state: toState('${{ steps.audit_gates.outcome }}'),
+ },
+ ];
+ for (const check of checks) {
+ await github.rest.repos.createCommitStatus({
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ sha,
+ ...check,
+ });
+ }
\ No newline at end of file
diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md
index 058a125..f984af5 100644
--- a/CONTRIBUTORS.md
+++ b/CONTRIBUTORS.md
@@ -2,18 +2,18 @@
Thank you to everyone who shipped docs, stories, examples, and tool fixes.
-*Generated 2026-07-06 via `node scripts/generate-contributors.mjs` — re-run after merges.*
+*Generated 2026-07-07 via `node scripts/generate-contributors.mjs` — re-run after merges.*
| Contributor | Highlights |
|-------------|------------|
-| [@KhaiTrang1995](https://github.com/KhaiTrang1995) | #165 feat(loop-guard): size the token budget from loop-cost per pattern<br>#140 feat(loop-init): wire loop-context circuit breaker into scaffolding + ci-sweeper |
+| [@KhaiTrang1995](https://github.com/KhaiTrang1995) | #190 feat(loop-worktree): manage isolated git worktrees per fix attempt<br>#165 feat(loop-guard): size the token budget from loop-cost per pattern |
+| [@k-anushka14](https://github.com/k-anushka14) | #185 Docs/add aider to examples index<br>#183 Docs/opencode constraints example |
| [@50thycal](https://github.com/50thycal) | story: `quant-loop-out-of-time.md`<br>story: `quant-loop-the-verifier-problem.md` |
| [@neerajdad123-byte](https://github.com/neerajdad123-byte) | 3 commits |
+| [@sololys](https://github.com/sololys) | story: `ky-cut-surface-generation-vs-consequence.md` |
| [@ulises-jeremias](https://github.com/ulises-jeremias) | #98 docs(examples): add opencode tool coverage |
| [@jiaobotao](https://github.com/jiaobotao) | #141 Add Hermes Agent example (daily-triage) + primitives matrix column |
-| [@k-anushka14](https://github.com/k-anushka14) | #156 docs: add Cursor PR Babysitter example |
| [@roian6](https://github.com/roian6) | #127 docs: expand Aider primitives appendix |
-| [@sololys](https://github.com/sololys) | story: `ky-cut-surface-generation-vs-consequence.md` |
| [@Zhang-986](https://github.com/Zhang-986) | #138 fix(loop-sync): honor json output flag |
## Your first PR
diff --git a/RELEASE_NOTES_DRAFT.md b/RELEASE_NOTES_DRAFT.md
new file mode 100644
index 0000000..e35bd4b
--- /dev/null
+++ b/RELEASE_NOTES_DRAFT.md
@@ -0,0 +1,62 @@
+# Release notes draft — since `loop-mcp-server-v1.0.0`
+
+**Status:** Draft for human review ([#181](https://github.com/cobusgreyling/loop-engineering/issues/181)). Edit before publishing a discussion post or tagging packages.
+
+**Window:** 2026-07-06 → 2026-07-07
+
+---
+
+## Highlights
+
+### New: `loop-worktree` CLI ([#190](https://github.com/cobusgreyling/loop-engineering/pull/190))
+
+Isolated git worktrees per fix attempt — supports PR Babysitter and CI Sweeper L2 patterns without branch collisions.
+
+```bash
+npx @cobusgreyling/loop-worktree list
+npx @cobusgreyling/loop-worktree create fix-123 --branch fix/issue-123
+```
+
+Thanks [@KhaiTrang1995](https://github.com/KhaiTrang1995).
+
+### Community docs & stories
+
+| PR | Contributor | What shipped |
+|----|-------------|--------------|
+| [#182](https://github.com/cobusgreyling/loop-engineering/pull/182) | @k-anushka14 | Multi-loop coordination story |
+| [#183](https://github.com/cobusgreyling/loop-engineering/pull/183) | @k-anushka14 | Opencode constraints example |
+| [#185](https://github.com/cobusgreyling/loop-engineering/pull/185) | @k-anushka14 | Aider appendix link in examples index |
+| Hermes index + QUICKSTART | @AshayK003 ([#187](https://github.com/cobusgreyling/loop-engineering/pull/187)–[#189](https://github.com/cobusgreyling/loop-engineering/pull/189)) | `examples/hermes/README.md`, QUICKSTART section, copy-paste starters row |
+
+### Philosophy & contributor growth
+
+- KY cut surface philosophy v0.1 ([#179](https://github.com/cobusgreyling/loop-engineering/pull/179)) — thanks [@sololys](https://github.com/sololys)
+- `CONTRIBUTORS.md` automation refresh ([#180](https://github.com/cobusgreyling/loop-engineering/pull/180))
+
+### Housekeeping (this batch)
+
+- **Star-history workflow** — opens an auto-merge PR instead of pushing to protected `main`
+- **examples/README.md** — deduplicated Hermes/Aider tool-directory rows
+- Stale branch prune + contributor PR backlog triage
+
+---
+
+## npm publish checklist
+
+No version bumps required unless you want to ship `loop-worktree` to npm.
+
+| Package | Current | Action |
+|---------|---------|--------|
+| `@cobusgreyling/loop-mcp-server` | 1.0.0 | No change |
+| `@cobusgreyling/loop-audit` | 1.5.3 | No change |
+| `@cobusgreyling/loop-init` | 1.3.3 | No change |
+| `loop-worktree` | repo-only | Optional first publish + `loop-worktree-v*` tag |
+
+---
+
+## Suggested publish steps
+
+1. Review and edit this draft.
+2. Post summary to [Discussions](https://github.com/cobusgreyling/loop-engineering/discussions/new?category=announcements).
+3. Close [#181](https://github.com/cobusgreyling/loop-engineering/issues/181) when published.
+4. (Optional) Tag `loop-worktree-v1.0.0` if npm publish is desired — add `release-loop-worktree.yml` first.
\ No newline at end of file
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
index bb26b0c..e6666b1 100644
--- a/docs/QUICKSTART.md
+++ b/docs/QUICKSTART.md
@@ -121,6 +121,12 @@ opencode run "Run loop-triage. Read STATE.md first. Update High Priority and Wat
See [examples/opencode/daily-triage.md](../examples/opencode/daily-triage.md) for worktree + verifier patterns (L2+).
+### Hermes
+
+No `loop-init --tool hermes` yet — install the `loop-triage` skill manually and schedule via `hermes cron`. See [examples/hermes/daily-triage.md](../examples/hermes/daily-triage.md) for setup, channel delivery, and the full command reference.
+
+Week one: use `--deliver local` so routine triage output stays out of your chat history until you trust it.
+
### Cursor
No `loop-init --tool cursor` yet — copy skills and state from any starter, then map scheduling to editor Automations. See [examples/cursor/daily-triage.md](../examples/cursor/daily-triage.md).
diff --git a/examples/README.md b/examples/README.md
index ec4cda4..d4e8e50 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -15,8 +15,6 @@ Same patterns, different tools. Skills and state schemas are shared; only schedu
| GitHub Actions | [github-actions/](./github-actions/) |
| Aider CLI | [primitives-matrix § Aider](../docs/primitives-matrix.md#appendix-aider-cli) — CLI-first loops via cron + `--read` skills |
| MCP connectors | [mcp/](./mcp/) — config example; reference server in [tools/mcp-server/](../tools/mcp-server/) |
-| Hermes | [hermes/](./hermes/) |
-| Aider | [Aider CLI](../docs/primitives-matrix.md#aider-cli) — CLI-first loops via cron + `--read` skills |
Start with [primitives-matrix.md](../docs/primitives-matrix.md) to map capabilities.
@@ -42,4 +40,5 @@ L2 patterns ship multi-tool skills inside one starter folder — see `starters/<
| Claude Code | [minimal-loop-claude](../starters/minimal-loop-claude/) | via `loop-init --tool claude` | via `loop-init --tool claude` | via `loop-init --tool claude` | via `loop-init --tool claude` | via `loop-init --tool claude` | via `loop-init --tool claude` |
| Codex | [minimal-loop-codex](../starters/minimal-loop-codex/) | via `loop-init --tool codex` | via `loop-init --tool codex` | via `loop-init --tool codex` | via `loop-init --tool codex` | via `loop-init --tool codex` | via `loop-init --tool codex` |
| OpenClaw | [openclaw/daily-triage.md](./openclaw/daily-triage.md) (manual) | [openclaw/pr-babysitter.md](./openclaw/pr-babysitter.md) | [openclaw/ci-sweeper.md](./openclaw/ci-sweeper.md) | [openclaw/dependency-sweeper.md](./openclaw/dependency-sweeper.md) | [openclaw/post-merge-cleanup.md](./openclaw/post-merge-cleanup.md) | [openclaw/changelog-drafter.md](./openclaw/changelog-drafter.md) | [openclaw/issue-triage.md](./openclaw/issue-triage.md) |
+| Hermes | [hermes/daily-triage.md](./hermes/daily-triage.md) (manual) | — | — | — | — | — | — |
| Opencode | [minimal-loop-opencode](../starters/minimal-loop-opencode/) | [pr-babysitter-opencode](../starters/pr-babysitter-opencode/) | [ci-sweeper-opencode](../starters/ci-sweeper-opencode/) | [dependency-sweeper-opencode](../starters/dependency-sweeper-opencode/) | [post-merge-cleanup-opencode](../starters/post-merge-cleanup-opencode/) | [changelog-drafter-opencode](../starters/changelog-drafter-opencode/) | [issue-triage-opencode](../starters/issue-triage-opencode/) |
diff --git a/examples/hermes/README.md b/examples/hermes/README.md
new file mode 100644
index 0000000..dd55947
--- /dev/null
+++ b/examples/hermes/README.md
@@ -0,0 +1,13 @@
+# Hermes Agent
+
+[Hermes Agent](https://hermes-agent.nousresearch.com/docs) ships the six loop primitives (cronjob / skill / STATE / delegate_task / MCP / memory) in one binary — no extra runtime needed for a full L1 daily-triage loop.
+
+| Example | Pattern |
+|---------|---------|
+| [daily-triage.md](./daily-triage.md) | Daily Triage (L1 report → L2 assisted) |
+
+Optional **channel delivery** (Telegram, Slack, Discord, WhatsApp, SMS, Feishu) is Hermes's differentiator — the same cron job can post its summary into any connected home channel.
+
+No `loop-init --tool hermes` yet — copy skills and state manually, then schedule via `hermes cron`.
+
+See [docs/primitives-matrix.md](../../docs/primitives-matrix.md) for the Hermes column in the cross-tool matrix.
\ No newline at end of file