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(examples): fix opencode loop invocations

ulises-jeremias098d9839f0bf
diff --git a/docs/primitives-matrix.md b/docs/primitives-matrix.md
index 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 Patterns
diff --git a/examples/opencode/ci-sweeper.md b/examples/opencode/ci-sweeper.md
index 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 reso
set -euo pipefail
opencode 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
```bash
while 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 300
done
```
@@ -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.md
index 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
```bash
opencode 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
```bash
opencode 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-triage
cp 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-agents
diff --git a/examples/opencode/pr-babysitter.md b/examples/opencode/pr-babysitter.md
index 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"
```
## Idempotency
diff --git a/starters/minimal-loop-opencode/opencode.json.example b/starters/minimal-loop-opencode/opencode.json.example
index 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.",