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: add loop-action subsection to QUICKSTART (#416)
Muhammad Zeshan Malik206d2ebefc51
diff --git a/README.md b/README.mdindex d77c795..b7e4cce 100644--- a/README.md+++ b/README.md@@ -109,6 +109,7 @@ For developers using Grok, Claude Code, Codex, Cursor, and other AI coding agent| [loop-worktree](tools/loop-worktree/) | Manage isolated git worktrees per fix attempt — `npx @cobusgreyling/loop-worktree create --run-id <id> --pattern <p>` || [loop-gate](tools/loop-gate/) | Mechanical enforcement of the path denylist + auto-merge allowlist from `gate.yaml` — `npx @cobusgreyling/loop-gate check --action auto-merge --paths <f1,f2,...>` || [loop-sandbox](tools/loop-sandbox/) | Ephemeral git worktree isolation + patch capture — `npx @cobusgreyling/loop-sandbox run -- <cmd>` |+| [loop-action](tools/loop-action/) | GitHub Composite Action for running loops in CI — `uses: cobusgreyling/loop-engineering/tools/loop-action@main` || [Goal Engineering](https://github.com/cobusgreyling/goal-engineering) | **Companion:** loops discover, goals finish — `/goal` + [stack cookbook](https://github.com/cobusgreyling/goal-engineering/blob/main/docs/stack-cookbook.md) (`npx @cobusgreyling/goal doctor .`) || [Memory Engineering](https://github.com/cobusgreyling/memory-engineering) | **Companion:** stop re-explaining the repo — tiers, budget, Memory Ready score (`node tools/memory-init/cli.js .`) || [Fleet Engineering](https://github.com/cobusgreyling/fleet-engineering) | **Companion:** govern populations of agents — registry, inbox, Fleet Ready score (`npx @cobusgreyling/fleet-init .`) |diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.mdindex 15805b3..0ed60b5 100644--- a/docs/QUICKSTART.md+++ b/docs/QUICKSTART.md@@ -200,6 +200,26 @@ No `loop-init --tool windsurf` yet — copy skills and state from any starter, tWorkflow examples under [examples/github-actions/](../examples/github-actions/) are schema-complete; you wire the agent invocation (Codex API, `repository_dispatch`, etc.). Start with report-only outputs to a state file or issue comment.+### GitHub Actions composite action (`loop-action`)++For CI/CD workflows, use the official GitHub Composite Action [`tools/loop-action`](../tools/loop-action/README.md) to automatically run readiness audits (`loop-audit`), enforce circuit breakers (`loop-context`), and isolate execution in worktrees (`loop-sandbox`):++```yaml+- uses: cobusgreyling/loop-engineering/tools/loop-action@main+ with:+ pattern: 'ci-sweeper'+ level: 'L1' # L1 (report-only) -> L2 -> L3+ sandbox: 'false' # set 'true' for ephemeral worktree isolation (L2)+ command: |+ npx grok-cli run --skill .grok/skills/ci-sweeper/SKILL.md+```++> **Week-one rule:** report-only mode (`level: 'L1'`). No auto-fix, no auto-merge. Review generated state output before enabling actions.+>+> **Note on `command`:** Unquoted multi-arg command strings can be fragile when parsed by shell runners. Prefer multi-line `command: |` blocks or a single script path (e.g. `scripts/run-agent.sh`).+>+> See [tools/loop-action/README.md](../tools/loop-action/README.md) and [docs/safety.md](./safety.md) for action inputs, security guardrails, and permission boundaries.+## 6. Read the output, commit state (1 minute)Open `STATE.md`. Did the loop capture real priorities? Edit anything wrong — you're still the engineer.diff --git a/examples/github-actions/README.md b/examples/github-actions/README.mdindex 2d7ea09..1e28dee 100644--- a/examples/github-actions/README.md+++ b/examples/github-actions/README.md@@ -2,18 +2,29 @@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:+Event-driven and scheduled loops **without** a TUI session. The refactored workflow examples in this directory use the [`loop-action`](../../tools/loop-action/README.md) composite action to automatically run readiness audits (`loop-audit`), check circuit breakers (`loop-context`), and isolate execution in worktrees (`loop-sandbox`).-1. Gather context (CI, merges, failures)-2. Update state files-3. **Delegate** to your agent harness in the "Invoke agent" step+## Composite Action (`loop-action`)++Instead of writing manual shell scripts for audits and circuit breakers in your workflows, use the [`tools/loop-action`](../../tools/loop-action/README.md) composite action:++```yaml+- uses: cobusgreyling/loop-engineering/tools/loop-action@main+ with:+ pattern: 'daily-triage'+ level: 'L1'+ sandbox: 'false'+ command: |+ npx grok-cli run --skill .grok/skills/loop-triage/SKILL.md+```## Wiring Your Agent-Replace the placeholder `run:` steps with one of:+Replace the `command:` input or placeholder steps with your choice of agent harness:| Approach | When ||----------|------|+| `loop-action` (recommended) | Automated audit + circuit breaker + worktree sandbox in CI || Codex CLI / API | Headless Codex in CI || `repository_dispatch` | External runner with Grok/Claude || Custom script | Rule-based triage only (L0) |