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.

Feat loop action (#375)

THRISHAL DOMA47c16a2331c8
diff --git a/examples/github-actions/ci-sweeper.yml b/examples/github-actions/ci-sweeper.yml
index 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 file
diff --git a/examples/github-actions/daily-triage.yml b/examples/github-actions/daily-triage.yml
index 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.md
fi
- # 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 artifact
uses: actions/upload-artifact@v4
diff --git a/examples/github-actions/dependency-sweeper.yml b/examples/github-actions/dependency-sweeper.yml
index 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 file
diff --git a/examples/github-actions/issue-triage.yml b/examples/github-actions/issue-triage.yml
index 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.md
fi
- # 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 artifact
uses: actions/upload-artifact@v4
diff --git a/examples/github-actions/pr-babysitter.yml b/examples/github-actions/pr-babysitter.yml
index 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 file
diff --git a/tools/loop-action/README.md b/tools/loop-action/README.md
new file mode 100644
index 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.yml
new file mode 100644
index 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