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
Feat loop action (#375)
THRISHAL DOMA47c16a2331c8
diff --git a/examples/github-actions/ci-sweeper.yml b/examples/github-actions/ci-sweeper.ymlindex 8b62966..67eb0e4 100644--- a/examples/github-actions/ci-sweeper.yml+++ b/examples/github-actions/ci-sweeper.yml@@ -37,21 +37,13 @@ jobs:echo "- URL: ${{ github.event.workflow_run.html_url }}" >> "$FILE"echo "- Loop action: pending agent invocation" >> "$FILE"- - name: Circuit breaker check- id: circuit_breaker- run: |- npx --yes @cobusgreyling/loop-context --check --ledger loop-ledger.json \- --budget-from-pattern ci-sweeper --budget-level L2 || echo "tripped=true" >> "$GITHUB_OUTPUT"- continue-on-error: true-- - name: Invoke fix agent- if: steps.circuit_breaker.outputs.tripped != 'true'- run: |- echo "::notice::Wire to agent: classify failure, worktree fix, verifier, open PR."- echo "See patterns/ci-sweeper.md and docs/safety.md"-- - name: Escalate (circuit breaker tripped)- if: steps.circuit_breaker.outputs.tripped == 'true'- run: |- echo "::warning::Circuit breaker tripped — same failure recurred or attempt cap reached."- echo "Escalating to human instead of retrying. See docs/safety.md#human-gates-required."\ No newline at end of file+ - name: Invoke CI Sweeper Agent+ uses: cobusgreyling/loop-engineering/tools/loop-action@main+ with:+ pattern: 'ci-sweeper'+ level: 'L2'+ sandbox: 'true'+ sandbox-shell: 'true'+ command: |+ echo "::notice::Wire to agent: classify failure, worktree fix, verifier, open PR."+ echo "See patterns/ci-sweeper.md and docs/safety.md"\ No newline at end of filediff --git a/examples/github-actions/daily-triage.yml b/examples/github-actions/daily-triage.ymlindex c42e141..adf35bc 100644--- a/examples/github-actions/daily-triage.yml+++ b/examples/github-actions/daily-triage.yml@@ -36,15 +36,17 @@ jobs:echo "# Loop State\n\nLast run: never\n\n## High Priority\n\n## Watch List\n" > STATE.mdfi- # Replace this step with your agent invocation:- # - Codex CLI in headless mode- # - repository_dispatch to a machine running Grok/Claude- # - Custom triage script that updates STATE.md- - name: Run triage agent- run: |- echo "::notice::Wire this step to your agent harness."- echo "Prompt: Run loop-triage skill. Update STATE.md. Report only unless L2 enabled."- echo "See examples/github-actions/README.md"+ # Replace this step with your agent invocation (e.g., Codex CLI, Grok/Claude runner)+ - name: Invoke Daily Triage Agent+ uses: cobusgreyling/loop-engineering/tools/loop-action@main+ with:+ pattern: 'daily-triage'+ level: 'L1'+ sandbox-shell: 'true'+ command: |+ echo "::notice::Wire this step to your agent harness."+ echo "Prompt: Run loop-triage skill. Update STATE.md. Report only unless L2 enabled."+ echo "See examples/github-actions/README.md"- name: Upload state artifactuses: actions/upload-artifact@v4diff --git a/examples/github-actions/dependency-sweeper.yml b/examples/github-actions/dependency-sweeper.ymlindex 974bdca..5cd1309 100644--- a/examples/github-actions/dependency-sweeper.yml+++ b/examples/github-actions/dependency-sweeper.yml@@ -18,21 +18,14 @@ jobs:with:node-version: '22'- - name: Circuit breaker check- id: circuit_breaker- run: |- npx --yes @cobusgreyling/loop-context --check --ledger loop-ledger.json \- --budget-from-pattern dependency-sweeper --budget-level L2 || echo "tripped=true" >> "$GITHUB_OUTPUT"- continue-on-error: true-- - name: Placeholder — wire to your agent runtime- if: steps.circuit_breaker.outputs.tripped != 'true'- run: |- echo "Run dependency-triage (npm audit / outdated)."- echo "Patch-only fixes in worktree with verifier."- echo "Update dependency-sweeper-state.md — escalate majors."-- - name: Escalate (circuit breaker tripped)- if: steps.circuit_breaker.outputs.tripped == 'true'- run: |- echo "::warning::Circuit breaker tripped for this package — see docs/safety.md#human-gates-required."\ No newline at end of file+ - name: Invoke Dependency Sweeper Agent+ uses: cobusgreyling/loop-engineering/tools/loop-action@main+ with:+ pattern: 'dependency-sweeper'+ level: 'L2'+ sandbox: 'true'+ sandbox-shell: 'true'+ command: |+ echo "Run dependency-triage (npm audit / outdated)."+ echo "Patch-only fixes in worktree with verifier."+ echo "Update dependency-sweeper-state.md — escalate majors."\ No newline at end of filediff --git a/examples/github-actions/issue-triage.yml b/examples/github-actions/issue-triage.ymlindex 7f7194d..30be6b5 100644--- a/examples/github-actions/issue-triage.yml+++ b/examples/github-actions/issue-triage.yml@@ -37,13 +37,18 @@ jobs:echo "# Issue Triage State\n\nLast run: never\nOpen actionable: 0\n\n## Top 5\n\n## Proposed Labels (L1 — not applied)\n" > issue-triage-state.mdfi- # Replace with your agent invocation (Codex CLI, repository_dispatch, Grok/Claude runner)- - name: Run issue-triage agent- run: |- echo "::notice::Wire this step to your agent harness."- echo "Prompt: Run issue-triage skill. Update issue-triage-state.md."- echo "Week 1: propose labels and priority only — no auto-apply or close."- echo "See examples/github-actions/README.md and examples/grok/issue-triage.md"+ # Replace with your agent invocation (e.g., Codex CLI, Grok/Claude runner)+ - name: Invoke Issue Triage Agent+ uses: cobusgreyling/loop-engineering/tools/loop-action@main+ with:+ pattern: 'issue-triage'+ level: 'L1'+ sandbox-shell: 'true'+ command: |+ echo "::notice::Wire this step to your agent harness."+ echo "Prompt: Run issue-triage skill. Update issue-triage-state.md."+ echo "Week 1: propose labels and priority only — no auto-apply or close."+ echo "See examples/github-actions/README.md and examples/grok/issue-triage.md"- name: Upload state artifactuses: actions/upload-artifact@v4diff --git a/examples/github-actions/pr-babysitter.yml b/examples/github-actions/pr-babysitter.ymlindex f158850..35a8df8 100644--- a/examples/github-actions/pr-babysitter.yml+++ b/examples/github-actions/pr-babysitter.yml@@ -16,8 +16,13 @@ jobs:steps:- uses: actions/checkout@v7- - name: Placeholder — wire to your agent runtime- run: |- echo "Run pr-review-triage against open PRs."- echo "Update pr-babysitter-state.md in a follow-up PR."- echo "No auto-merge in week one — see patterns/pr-babysitter.md"\ No newline at end of file+ - name: Invoke PR Babysitter Agent+ uses: cobusgreyling/loop-engineering/tools/loop-action@main+ with:+ pattern: 'pr-babysitter'+ level: 'L1'+ sandbox-shell: 'true'+ command: |+ echo "Run pr-review-triage against open PRs."+ echo "Update pr-babysitter-state.md in a follow-up PR."+ echo "No auto-merge in week one — see patterns/pr-babysitter.md"\ No newline at end of filediff --git a/tools/loop-action/README.md b/tools/loop-action/README.mdnew file mode 100644index 0000000..957bb01--- /dev/null+++ b/tools/loop-action/README.md@@ -0,0 +1,34 @@+# Loop Engineering Action++An official GitHub Composite Action to safely execute autonomous agents in your CI/CD pipelines.++Instead of writing complex bash scripts to enforce circuit breakers, run readiness audits, and isolate agent execution in worktrees, this action wraps the entire [Loop Engineering](https://github.com/cobusgreyling/loop-engineering) safety suite into a single, elegant step.++## Usage++```yaml+- uses: cobusgreyling/loop-engineering/tools/loop-action@main+ with:+ pattern: 'ci-sweeper'+ command: 'npx grok-cli run --skill .grok/skills/ci-sweeper/SKILL.md'+ level: 'L2'+ sandbox: 'true'+ sandbox-shell: 'false'+```++## Inputs++| Input | Required | Default | Description |+|-------|----------|---------|-------------|+| `pattern` | **Yes** | | The loop pattern you are running (e.g., `ci-sweeper`, `daily-triage`). Must match a pattern in `loop-budget.md`. |+| `command` | **Yes** | | The actual terminal command to invoke your agent (e.g., `claude`, `grok`, `aider`). |+| `level` | No | `L1` | The autonomy level for budget constraint verification (`L1`, `L2`, `L3`). |+| `sandbox` | No | `false` | If `'true'`, routes the execution through `loop-sandbox` to provide ephemeral worktree isolation, capturing changes securely without destroying the main working tree. |+| `sandbox-shell` | No | `false` | If `'true'`, routes the execution inside a shell environment (`--shell`). |++## What it does under the hood++When this action runs, it sequentially executes:+1. **`loop-audit`**: Checks the repository against the Loop Readiness rubric (ensuring `STATE.md`, `gate.yaml`, and constraints are in place).+2. **`loop-context`**: Acts as a circuit breaker. It halts the workflow immediately if the loop is stuck in a failure cycle or has exhausted its daily token budget.+3. **Execution (`loop-sandbox`)**: If `sandbox: 'true'`, it dynamically isolates the agent inside an ephemeral git worktree, tracks all modifications into a patch file, and cleans up. Otherwise, it executes the command directly in the main tree.diff --git a/tools/loop-action/action.yml b/tools/loop-action/action.ymlnew file mode 100644index 0000000..43a2d67--- /dev/null+++ b/tools/loop-action/action.yml@@ -0,0 +1,52 @@+name: 'Loop Engineering Action'+description: 'Enforce circuit breakers, readiness audits, and sandboxing for autonomous loops natively in CI.'+author: 'Cobus Greyling'++inputs:+ pattern:+ description: 'The loop pattern (e.g. ci-sweeper, pr-babysitter, dependency-sweeper)'+ required: true+ command:+ description: 'The actual agent command to run if gates pass'+ required: true+ level:+ description: 'Budget level for circuit breaker (L1, L2, L3)'+ required: false+ default: 'L1'+ sandbox:+ description: 'Run the command inside an ephemeral isolated git worktree (loop-sandbox)'+ required: false+ default: 'false'+ sandbox-shell:+ description: 'Run the sandbox command inside a shell environment (--shell)'+ required: false+ default: 'false'++runs:+ using: "composite"+ steps:+ - name: Audit Loop Readiness+ run: npx --yes @cobusgreyling/loop-audit .+ shell: bash++ - name: Check Circuit Breaker+ id: breaker+ run: |+ npx --yes @cobusgreyling/loop-context --check --ledger loop-ledger.json \+ --budget-from-pattern ${{ inputs.pattern }} --budget-level ${{ inputs.level }}+ shell: bash++ - name: Run Agent (Sandbox)+ if: ${{ inputs.sandbox == 'true' }}+ run: |+ if [ "${{ inputs.sandbox-shell }}" == "true" ]; then+ npx --yes @cobusgreyling/loop-sandbox run --shell -- ${{ inputs.command }}+ else+ npx --yes @cobusgreyling/loop-sandbox run -- ${{ inputs.command }}+ fi+ shell: bash++ - name: Run Agent (Direct)+ if: ${{ inputs.sandbox != 'true' }}+ run: ${{ inputs.command }}+ shell: bash