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.

docs: add loop-action subsection to QUICKSTART (#416)

Muhammad Zeshan Malik206d2ebefc51
diff --git a/README.md b/README.md
index 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.md
index 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, t
Workflow 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.md
index 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) |