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
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.ymlindex 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: writejobs:update:@@ -21,9 +23,96 @@ jobs:gh auth setup-gitpython3 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@v9with:- 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 filediff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.mdindex 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 PRdiff --git a/RELEASE_NOTES_DRAFT.md b/RELEASE_NOTES_DRAFT.mdnew file mode 100644index 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 filediff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.mdindex 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 WatSee [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.+### CursorNo `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.mdindex 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.mdnew file mode 100644index 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