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
docs: cross-link Goal Engineering and add goal-audit npm bootstrap (#51)
Cobus Greyling99f497a705dc
diff --git a/.github/workflows/publish-goal-audit-bootstrap.yml b/.github/workflows/publish-goal-audit-bootstrap.ymlnew file mode 100644index 0000000..498c189--- /dev/null+++ b/.github/workflows/publish-goal-audit-bootstrap.yml@@ -0,0 +1,41 @@+name: Publish goal-audit (bootstrap)++# One-time bootstrap: publishes @cobusgreyling/goal-audit from goal-engineering+# using this repo's NPM_TOKEN. After first publish, use goal-engineering's+# release-goal-audit.yml tag workflow (copy NPM_TOKEN to that repo).++on:+ workflow_dispatch:++permissions:+ contents: read+ id-token: write++jobs:+ publish:+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@v6+ with:+ repository: cobusgreyling/goal-engineering+ ref: main++ - uses: actions/setup-node@v6+ with:+ node-version: '22'+ registry-url: 'https://registry.npmjs.org'+ cache: 'npm'+ cache-dependency-path: tools/goal-audit/package-lock.json++ - name: Install, build, test+ working-directory: tools/goal-audit+ run: |+ npm ci+ npm run build+ npm test++ - name: Publish to npm+ working-directory: tools/goal-audit+ run: npm publish --access public --provenance+ env:+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}\ No newline at end of filediff --git a/README.md b/README.mdindex f5dca11..7889208 100644--- a/README.md+++ b/README.md@@ -69,6 +69,7 @@ A loop is a recursive goal: you define a purpose and the AI iterates (often with| [loop-audit](tools/loop-audit/) | Loop Readiness Score CLI (v1.4 + activity detection) — `npx @cobusgreyling/loop-audit . --suggest` || [loop-init](tools/loop-init/) | Scaffold starters + budget/run-log (v1.2) — `npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok` || [loop-cost](tools/loop-cost/) | Token spend estimator — `npx @cobusgreyling/loop-cost` |+| [Goal Engineering](https://github.com/cobusgreyling/goal-engineering) | Companion: Grok Build `/goal` — run-until-done objectives (`npx @cobusgreyling/goal-audit`) || [Stories](stories/) | Real wins and honest failures |## Why This Mattersdiff --git a/docs/primitives-matrix.md b/docs/primitives-matrix.mdindex 93d84c5..55e9750 100644--- a/docs/primitives-matrix.md+++ b/docs/primitives-matrix.md@@ -5,7 +5,7 @@ Tool-agnostic loop design: the **capability** is what matters, not the product n| Primitive | Job in the Loop | Grok Build TUI | Claude Code | Codex | Cursor | Windsurf ||-----------|-----------------|----------------|-------------|-------|--------|----------|| **Automations / Scheduling** | Discovery + triage on a cadence | `/loop [interval] <prompt>`, `scheduler_create` / `scheduler_list` / `scheduler_delete` (`recurring`, `durable`, `fireImmediately`), `monitor` for streaming events | `/loop`, scheduled tasks, cron, hooks, GitHub Actions | [Automations tab](https://developers.openai.com/codex/app/automations): project, prompt, cadence, environment; Triage inbox | Cloud Agents + **Automations** (cron, webhooks, Linear/GitHub/Slack triggers); foreground Agent chat for ad-hoc `/loop`-style prompts | Cascade **Workflows** (`/workflow-name`, manual invoke); pair with GitHub Actions or external cron for true scheduling |-| **Run-until-done** | Keep working until a verifiable condition holds | Goal mode / explicit stopping conditions in loop prompts | `/goal` — separate model checks completion | `/goal` — pause/resume, verifiable stop condition | Agent mode + **hooks** (`.cursor/hooks.json`) for grind-until-green loops | Workflow steps with explicit verification checkpoints; **Memories** for cross-session continuity |+| **Run-until-done** | Keep working until a verifiable condition holds | [`/goal`](https://github.com/cobusgreyling/goal-engineering) + `update_goal` — persistent objective across turns ([Goal Engineering](https://github.com/cobusgreyling/goal-engineering)) | `/goal` — separate model checks completion | `/goal` — pause/resume, verifiable stop condition | Agent mode + **hooks** (`.cursor/hooks.json`) for grind-until-green loops | Workflow steps with explicit verification checkpoints; **Memories** for cross-session continuity || **Worktrees** | Safe parallel execution | Subagents with `isolation: "worktree"`, background tasks | `git worktree`, `--worktree`, `isolation: worktree` on subagents | Built-in worktree per thread | Git worktree per Composer / Cloud Agent task | Workspace isolation; multiple simultaneous Cascade sessions || **Skills** | Persistent project knowledge | `SKILL.md` in `.grok/skills/` or `~/.grok/skills/`; invoked by name | `SKILL.md` in `.claude/skills/` or project skills | [Agent Skills](https://developers.openai.com/codex/skills) — `$name` or implicit match | `.cursor/rules/*.mdc` (globs, `alwaysApply`), `AGENTS.md`, `.cursor/skills/` | `.devin/rules/` or `.windsurf/rules/` (persistent context); `.windsurf/workflows/` (reusable recipes) || **Plugins & Connectors** | Reach into real tools | MCP servers via `CallMcpTool` | MCP servers + plugins | Connectors (MCP) + plugins for distribution | MCP in settings; Cloud Agent sandbox with full connector access | MCP via Cascade settings / `mcp_config.json` |@@ -18,7 +18,7 @@ Tool-agnostic loop design: the **capability** is what matters, not the product n|----------|------|-------------|-------|--------|----------|| Every 5 minutes | `/loop 5m <prompt>` | `/loop 5m <prompt>` | Automation, 5m cadence | Automation cron trigger | External cron + `/workflow` or Action || Daily morning | `/loop 1d <prompt>` | Cron / `/loop 1d` | Automation, daily | Automation daily + `AGENTS.md` context | Daily workflow + Memories |-| Until tests pass | Loop + verifier sub-agent | `/goal all tests pass` | `/goal` | Hooks grind-until-green | Workflow with test/fix loop |+| Until tests pass | [`/goal`](https://github.com/cobusgreyling/goal-engineering/blob/main/patterns/tests-green.md) + `goal-verifier` skill (or loop + verifier) | `/goal all tests pass` | `/goal` | Hooks grind-until-green | Workflow with test/fix loop || Survive restart | `scheduler_create` with `durable: true` | Hooks + persisted config | Automation (server-side) | Cloud Agent + repo-persisted state | Memories + committed `STATE.md` || Event-driven (CI fail) | `monitor` or GitHub Action | GitHub Action + webhook | Automation + webhook | Automation on PR/issue events | GitHub Action triggers + `/workflow` |@@ -76,6 +76,16 @@ Audit after copying: `npx @cobusgreyling/loop-audit . --suggest`Scaffold automatically: `npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok`+## Goals (run-until-done)++Loops discover ongoing work; **goals finish bounded tasks**. Canonical reference: **[Goal Engineering](https://github.com/cobusgreyling/goal-engineering)** (`/goal`, `update_goal`, `GOAL.md`, `goal-verifier`).++| Handoff | Command |+|---------|---------|+| Loop found a fixable item | `/goal Read STATE.md top item. Complete per goal-engineering pattern. goal-verifier before done.` |+| Audit goal readiness | `npx @cobusgreyling/goal-audit . --suggest` |+| Goal vs loop decision | [goal-vs-loop.md](https://github.com/cobusgreyling/goal-engineering/blob/main/docs/goal-vs-loop.md) |+## Appendix: Editor transfer recipes (Cursor & Windsurf)No dedicated starters yet — map capabilities to the same loop shape: