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(examples): fix opencode loop invocations
ulises-jeremias098d9839f0bf
diff --git a/docs/primitives-matrix.md b/docs/primitives-matrix.mdindex 7d6b73c..cdcb521 100644--- a/docs/primitives-matrix.md+++ b/docs/primitives-matrix.md@@ -30,7 +30,7 @@ Tool-agnostic loop design: the **capability** is what matters, not the product n|---------|------|-------------|-------|----------|----------|--------|----------|| Authoring format | `SKILL.md` + optional scripts/references | Same | Same | Same ([AgentSkills](https://agentskills.io)) | Same (`SKILL.md` under `skills/<name>/`) | `SKILL.md` or `.mdc` rules with frontmatter | Markdown rules + workflow files || Distribution | Copy to `.grok/skills/` or user skills dir | Plugin / copy to project | Plugin bundle | `<workspace>/skills/`, ClawHub, `openclaw skills install` | Copy to `skills/`; keep project rules in `AGENTS.md` | `.cursor/skills/` or `.cursor/rules/` | `.windsurf/rules/` + `.windsurf/workflows/` in repo |-| Invocation | Skill name in prompt or auto-match on description | `$skill-name` or implicit | `$skill-name` | Slash command or auto-injected in system prompt | Name skill in `--prompt` or list in `opencode.json` | Rules auto-apply by glob; skills on demand | `/workflow-name` or Rules always-on in Cascade |+| Invocation | Skill name in prompt or auto-match on description | `$skill-name` or implicit | `$skill-name` | Slash command or auto-injected in system prompt | Name the skill in the `opencode run` message, or configure named agents in `opencode.json` | Rules auto-apply by glob; skills on demand | `/workflow-name` or Rules always-on in Cascade |## Sub-agent Patternsdiff --git a/examples/opencode/ci-sweeper.md b/examples/opencode/ci-sweeper.mdindex 5128156..613a9e3 100644--- a/examples/opencode/ci-sweeper.md+++ b/examples/opencode/ci-sweeper.md@@ -34,7 +34,6 @@ CI sweeper tolerates nothing wasted between runs. A system cron at 5-minute resoset -euo pipefailopencode run \"Run skills/ci-triage/SKILL.md. Classify each failing check. For clear single-file regressions, create a git worktree, run the implementer agent with --dir <worktree>, then run verifier with the diff as --file. Update ci-sweeper-state.md. For infra or security-test failures, escalate to a human with full context. Max 3 attempts per item." \- --agent ci-triage \--title "CI sweeper"```@@ -46,7 +45,7 @@ If you'd rather keep the loop fully in the CLI, run a long-lived shell loop inst```bashwhile true; do- opencode run "Run ci-triage. Fix only clear regressions in a worktree with verifier. Max 3 attempts. Escalate infra and security test failures." --agent ci-triage+ opencode run "Run skills/ci-triage/SKILL.md. Fix only clear regressions in a worktree with verifier. Max 3 attempts. Escalate infra and security test failures."sleep 300done```@@ -58,8 +57,8 @@ Same primitive, different scheduler.```bash# .github/workflows/ci-sweeper-webhook.yml can post to a small opencode bridge:curl -X POST http://opencode-bridge:8080/hooks/agent \- -H 'Authorization: Bearer ${OPENCODE_HOOK_TOKEN}' \- -H 'Content-Type: application/json' \+ -H "Authorization: Bearer ${OPENCODE_HOOK_TOKEN}" \+ -H "Content-Type: application/json" \-d '{"message":"Run ci-triage. Inspect recent CI failures. No fixes in report-only mode."}'```@@ -69,7 +68,7 @@ Keep hook endpoints on loopback or a trusted tailnet (see [docs/safety.md](../..| Role | Opencode shape ||------|----------------|-| Triage | `skills/ci-triage/SKILL.md` (or alias to `loop-triage`) + `--agent ci-triage` |+| Triage | `skills/ci-triage/SKILL.md` (or alias to `loop-triage`) named in the `opencode run` message || Implementer | `opencode run "..." --agent implementer --dir <worktree>` || Verifier | `opencode run "Verify diff" --agent verifier --file <diff.patch>` |diff --git a/examples/opencode/daily-triage.md b/examples/opencode/daily-triage.mdindex b08a08e..b0a8a4f 100644--- a/examples/opencode/daily-triage.md+++ b/examples/opencode/daily-triage.md@@ -21,7 +21,7 @@ Use cron or a systemd timer to run a fresh opencode session each morning. The pr```bashopencode run \"Run the loop-triage skill. Read STATE.md first. Append high-priority items under High Priority and Watch List. Update Last run timestamp. Do not edit source code. End with a 5-line summary." \- --title "Daily triage — repo:$(basename $(pwd))"+ --title "Daily triage — repo:${PWD##*/}"```The report-only stance is enforced by `AGENTS.md` and the prompt: no source-code edits in week one.@@ -34,18 +34,21 @@ Faster cadence during active periods:## With Small Auto-Fixes (Week 3+)-Create a verifier named agent, isolate each implementer in a `git worktree`, and pass the worktree path with `--dir`:+Create named `implementer` and `verifier` agents in `opencode.json`, isolate each implementer in a `git worktree`, and pass the worktree path with `--dir`:```bash-git worktree add ../wt-small-fix -b loop/small-fix+FIX_ID="$(date +%Y%m%d%H%M%S)"+WORKTREE="../wt-small-fix-$FIX_ID"+git worktree add "$WORKTREE" -b "loop/small-fix-$FIX_ID"opencode run \"Run loop-triage. For one high-priority single-file bugfix: implement the minimal fix, run tests, and write a summary plus diff path. Escalate ambiguous or denylisted paths." \--agent implementer \- --dir ../wt-small-fix-git -C ../wt-small-fix diff > /tmp/loop-diff.patch+ --dir "$WORKTREE"+DIFF_FILE="$(mktemp /tmp/loop-diff.XXXXXX.patch)"+git -C "$WORKTREE" diff > "$DIFF_FILE"opencode run "Review this diff against project rules and tests. APPROVE or REJECT only." \--agent verifier \- --file /tmp/loop-diff.patch+ --file "$DIFF_FILE"```The verifier sees only the diff; the implementer works only inside the worktree. This preserves the same **maker/checker split** Claude Code expresses with `isolation: worktree`.@@ -56,10 +59,11 @@ For a one-shot "get main green" session, drive opencode with the [Goal Engineeri```bashopencode run "Goal: all tests on main pass and lint is clean. Stop when tests pass and write the evidence."-git diff > /tmp/goal-diff.patch+DIFF_FILE="$(mktemp /tmp/goal-diff.XXXXXX.patch)"+git diff > "$DIFF_FILE"opencode run "Verify the goal is complete. APPROVE only if tests pass and the diff is minimal." \--agent verifier \- --file /tmp/goal-diff.patch+ --file "$DIFF_FILE"```## Skills Setup@@ -71,19 +75,23 @@ mkdir -p skills/loop-triagecp templates/SKILL.md.loop-triage skills/loop-triage/SKILL.md```-Create named verifier/implementer agents when you graduate to L2. The CLI writes the agent definition to the path you provide:--```bash-opencode agent create \- --path .opencode/agent/verifier.md \- --description "Review diffs and test evidence; APPROVE or REJECT only." \- --mode subagent \- --permissions read,grep,bash-opencode agent create \- --path .opencode/agent/implementer.md \- --description "Implement minimal scoped fixes in an isolated worktree." \- --mode subagent \- --permissions read,grep,edit,bash+Create named verifier/implementer agents when you graduate to L2. The starter's `opencode.json.example` already includes both names; copy it to `opencode.json` or add this shape manually:++```json+{+ "agent": {+ "implementer": {+ "description": "Implement minimal scoped fixes in an isolated worktree.",+ "mode": "subagent",+ "prompt": "Implement only the requested minimal fix. Stay within the supplied worktree and run documented tests."+ },+ "verifier": {+ "description": "Review diffs and test evidence; APPROVE or REJECT only.",+ "mode": "subagent",+ "prompt": "Review the supplied diff against project rules and tests. Do not edit files. APPROVE or REJECT only."+ }+ }+}```## Sub-agentsdiff --git a/examples/opencode/pr-babysitter.md b/examples/opencode/pr-babysitter.mdindex 7bc973a..1728399 100644--- a/examples/opencode/pr-babysitter.md+++ b/examples/opencode/pr-babysitter.md@@ -15,13 +15,16 @@ Keep the first week boring: read GitHub state, update state, notify humans.## With Small Auto-Fixes (Week 3+)```bash-git worktree add ../wt-pr-fix -b loop/pr-fix+FIX_ID="$(date +%Y%m%d%H%M%S)"+WORKTREE="../wt-pr-fix-$FIX_ID"+git worktree add "$WORKTREE" -b "loop/pr-fix-$FIX_ID"opencode run \"Run PR babysitter triage. For PRs authored by us with red CI caused by a clear single-file regression: apply a minimal fix in this worktree and run tests. For review comments, draft a response or patch but do not resolve threads without human approval. Never force-push." \--agent implementer \- --dir ../wt-pr-fix-git -C ../wt-pr-fix diff > /tmp/pr-fix.patch-opencode run "Review the PR fix diff. APPROVE or REJECT only." --agent verifier --file /tmp/pr-fix.patch+ --dir "$WORKTREE"+DIFF_FILE="$(mktemp /tmp/pr-fix.XXXXXX.patch)"+git -C "$WORKTREE" diff > "$DIFF_FILE"+opencode run "Review the PR fix diff. APPROVE or REJECT only." --agent verifier --file "$DIFF_FILE"```## Idempotencydiff --git a/starters/minimal-loop-opencode/opencode.json.example b/starters/minimal-loop-opencode/opencode.json.exampleindex 92b485e..a8ee2de 100644--- a/starters/minimal-loop-opencode/opencode.json.example+++ b/starters/minimal-loop-opencode/opencode.json.example@@ -11,6 +11,16 @@"edit": "ask"}},+ "implementer": {+ "name": "implementer",+ "description": "L2 implementer agent for minimal scoped fixes inside an isolated worktree.",+ "mode": "subagent",+ "prompt": "Implement only the requested minimal fix. Stay within the supplied worktree, respect AGENTS.md and LOOP.md, run documented tests, and stop for human approval on denylisted paths.",+ "permission": {+ "bash": "ask",+ "edit": "ask"+ }+ },"verifier": {"name": "verifier","description": "Checker agent for L2+ changes. Reviews diffs and test evidence; APPROVE or REJECT only.",