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): add opencode tool coverage
ulises-jeremias4d083c07e71a
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 9ff129a..404b869 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -8,7 +8,7 @@ This repo is a **practical engineering reference**, not a hype collection. We we|--------------|-------|| New loop pattern | `patterns/` + `patterns/registry.yaml` || Production story | `stories/` |-| Tool example | `examples/{grok,claude-code,codex,openclaw,github-actions}/` |+| Tool example | `examples/{grok,claude-code,codex,openclaw,opencode,github-actions}/` || Skill template | `templates/` || Starter kit | `starters/` || Doc improvement | `docs/` |@@ -58,4 +58,4 @@ Also add an entry to `patterns/registry.yaml`.- **Good first issues**: look for label [`good first issue`](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)- **Security**: see [SECURITY.md](./SECURITY.md) — do not file public issues for exploitable vulnerabilities-Thank you for helping make this the go-to reference for loop engineering.\ No newline at end of file+Thank you for helping make this the go-to reference for loop engineering.diff --git a/README.md b/README.mdindex 0f320ff..fe5b456 100644--- a/README.md+++ b/README.md@@ -83,10 +83,11 @@ For developers using Grok, Claude Code, Codex, Cursor, and other AI coding agent| [Quickstart (5 min)](docs/QUICKSTART.md) | Scaffold → cost check → audit → first loop — **start here if you just landed** || [Loop Engineering essay](https://cobusgreyling.substack.com/p/loop-engineering) | The concept, primitives, and Grok mapping — read for the why || [Pattern Picker](docs/pattern-picker.md) | Which loop to run first — **start here if unsure** |-| [Primitives Matrix](docs/primitives-matrix.md) | Grok vs Claude Code vs Codex — bookmark this |+| [Primitives Matrix](docs/primitives-matrix.md) | Cross-tool loop primitive mapping — bookmark this || [Loop Design Checklist](docs/loop-design-checklist.md) | Ship readiness rubric || [Patterns](patterns/README.md) | 7 production patterns + [interactive picker](https://cobusgreyling.github.io/loop-engineering/#interactive) |-| [Starters](starters/) | Clone-and-run kits (Grok, Claude Code, Codex) |+| [Starters](starters/) | Clone-and-run kits (Grok, Claude Code, Codex, Opencode) |+| [Opencode examples](examples/opencode/) | CLI-first loops: cron/systemd + `opencode run`, skills, worktrees || [loop-audit](tools/loop-audit/) | Loop Readiness Score CLI (v1.5 + constraints scoring) — `npx @cobusgreyling/loop-audit . --suggest` · `--badge` for README || [loop-init](tools/loop-init/) | Scaffold starters + budget/run-log + constraints (v1.2) — `npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok` || [loop-cost](tools/loop-cost/) | Token spend estimator — `npx @cobusgreyling/loop-cost` |@@ -218,6 +219,7 @@ Phased rollout: **L1 report → L2 assisted fixes → L3 unattended** — see [l- [Claude Code](examples/claude-code/)- [Codex](examples/codex/)- [OpenClaw](examples/openclaw/daily-triage.md)+- [Opencode](examples/opencode/)- [GitHub Actions](examples/github-actions/)## Operating & Safetydiff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.mdindex 5b4a8da..47c266a 100644--- a/docs/QUICKSTART.md+++ b/docs/QUICKSTART.md@@ -70,7 +70,7 @@ No `loop-init --tool openclaw` yet — copy `skills/loop-triage/SKILL.md` and `S### Cursor or Windsurf-No `loop-init --tool cursor` yet — copy skills and state from any starter, then map scheduling to editor Automations or Workflows. See the [Cursor & Windsurf appendix](./primitives-matrix.md#appendix-editor-transfer-recipes-cursor--windsurf) in the primitives matrix.+No `loop-init --tool cursor` yet — copy skills and state from any starter, then map scheduling to editor Automations or Workflows. See the [Opencode, Cursor & Windsurf appendix](./primitives-matrix.md#appendix-editor-transfer-recipes-opencode-cursor--windsurf) in the primitives matrix.### GitHub Actions only@@ -116,4 +116,4 @@ npx @cobusgreyling/loop-audit . --badge----*Questions? [GitHub Discussions](https://github.com/cobusgreyling/loop-engineering/discussions) · Share your setup via [Add Adopter](https://github.com/cobusgreyling/loop-engineering/issues/new?template=add-adopter.yml)*\ No newline at end of file+*Questions? [GitHub Discussions](https://github.com/cobusgreyling/loop-engineering/discussions) · Share your setup via [Add Adopter](https://github.com/cobusgreyling/loop-engineering/issues/new?template=add-adopter.yml)*diff --git a/docs/assets/css/showcase.css b/docs/assets/css/showcase.cssindex 4893060..5cda479 100644--- a/docs/assets/css/showcase.css+++ b/docs/assets/css/showcase.css@@ -436,6 +436,7 @@ section {.tool-pill.claude { border-color: rgba(255, 179, 71, 0.3); color: var(--accent-warm); }.tool-pill.codex { border-color: rgba(91, 157, 255, 0.3); color: var(--accent-2); }.tool-pill.openclaw { border-color: rgba(255, 107, 107, 0.35); color: #ff8a7a; }+.tool-pill.opencode { border-color: rgba(165, 123, 255, 0.35); color: #b99cff; }/* Code block */.code-block {@@ -805,4 +806,4 @@ section {.adopter-placeholder .btn {align-self: flex-start;margin-top: 4px;-}\ No newline at end of file+}diff --git a/docs/index.html b/docs/index.htmlindex bc4e466..40512e5 100644--- a/docs/index.html+++ b/docs/index.html@@ -8,7 +8,7 @@ title: Loop Engineering — Showcase<meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Loop Engineering — Design systems that prompt your agents</title>- <meta name="description" content="The practical reference for loop engineering. Patterns, starters, checklists, and tooling for Grok, Claude Code, and Codex.">+ <meta name="description" content="The practical reference for loop engineering. Patterns, starters, checklists, and tooling for Grok, Claude Code, Codex, OpenClaw, and Opencode."><meta property="og:title" content="Loop Engineering"><meta property="og:description" content="Stop prompting. Design the loop. Get a score. Two npx commands."><meta property="og:image" content="https://raw.githubusercontent.com/cobusgreyling/loop-engineering/main/assets/visuals/loop-engineering-social-banner.jpg">@@ -127,7 +127,7 @@ title: Loop Engineering — Showcase<section id="primitives" class="wrap"><p class="section-label">Building blocks</p><h2 class="section-title">Five primitives + memory</h2>- <p class="section-desc">The same shape works in Grok, Claude Code, Codex, and OpenClaw. Tool names differ; capabilities converge.</p>+ <p class="section-desc">The same shape works in Grok, Claude Code, Codex, OpenClaw, Opencode, and Actions. Tool names differ; capabilities converge.</p><div class="primitives"><div class="primitive"><div class="icon">⏱</div>@@ -165,6 +165,7 @@ title: Loop Engineering — Showcase<span class="tool-pill claude">Claude Code</span><span class="tool-pill codex">Codex</span><span class="tool-pill openclaw">OpenClaw</span>+ <span class="tool-pill opencode">Opencode</span><span class="tool-pill">GitHub Actions</span></div><p style="text-align: center; margin-top: 24px;">@@ -864,4 +865,4 @@ document.addEventListener('DOMContentLoaded', () => {</script></body>-</html>\ No newline at end of file+</html>diff --git a/docs/primitives-matrix.md b/docs/primitives-matrix.mdindex 77f5755..7d6b73c 100644--- a/docs/primitives-matrix.md+++ b/docs/primitives-matrix.md@@ -1,44 +1,44 @@-# Primitives Matrix — Grok, Claude Code, Codex, OpenClaw, Cursor, Windsurf+# Primitives Matrix — Grok, Claude Code, Codex, OpenClaw, Opencode, Cursor, Windsurf-Tool-agnostic loop design: the **capability** is what matters, not the product name. This matrix maps each primitive to how it appears in six major agent environments.+Tool-agnostic loop design: the **capability** is what matters, not the product name. This matrix maps each primitive to how it appears in seven major agent environments.-| Primitive | Job in the Loop | Grok Build TUI | Claude Code | Codex | OpenClaw | Cursor | Windsurf |-|-----------|-----------------|----------------|-------------|-------|----------|--------|----------|-| **Automations / Scheduling** | Discovery + triage on a cadence | `/loop [interval] <prompt>`, `scheduler_create` / `scheduler_list` / `scheduler_delete` (`recurring`, `durable`, `fireImmediately`), `monitor` for streaming events | `/loop`, scheduled tasks, cron, hooks, GitHub Actions | [Automations tab](https://developers.openai.com/codex/app/automations): project, prompt, cadence, environment; Triage inbox | [`openclaw cron`](https://docs.openclaw.ai/automation/cron-jobs) (`--cron` / `--every` / `--at`, isolated or main session); webhooks (`POST /hooks/agent`, `/hooks/wake`); heartbeat | Cloud Agents + **Automations** (cron, webhooks, Linear/GitHub/Slack triggers); foreground Agent chat for ad-hoc `/loop`-style prompts | Cascade **Workflows** (`/workflow-name`, manual invoke); pair with GitHub Actions or external cron for true scheduling |-| **Run-until-done** | Keep working until a verifiable condition holds | [`/goal`](https://github.com/cobusgreyling/goal-engineering) + `update_goal` — persistent objective across turns ([Goal Engineering](https://github.com/cobusgreyling/goal-engineering)) | `/goal` — separate model checks completion | `/goal` — pause/resume, verifiable stop condition | Recurring isolated cron with explicit stop condition in `--message`; delegate via `coding-agent` skill to external CLI; hand off bounded work to Goal Engineering | Agent mode + **hooks** (`.cursor/hooks.json`) for grind-until-green loops | Workflow steps with explicit verification checkpoints; **Memories** for cross-session continuity |-| **Worktrees** | Safe parallel execution | Subagents with `isolation: "worktree"`, background tasks | `git worktree`, `--worktree`, `isolation: worktree` on subagents | Built-in worktree per thread | `exec` + `git worktree` in agent workspace; `coding-agent` delegates to CLI backends; optional sandbox per agent | Git worktree per Composer / Cloud Agent task | Workspace isolation; multiple simultaneous Cascade sessions |-| **Skills** | Persistent project knowledge | `SKILL.md` in `.grok/skills/` or `~/.grok/skills/`; invoked by name | `SKILL.md` in `.claude/skills/` or project skills | [Agent Skills](https://developers.openai.com/codex/skills) — `$name` or implicit match | `SKILL.md` in `<workspace>/skills/`, `.agents/skills`, or `~/.openclaw/skills`; [AgentSkills](https://agentskills.io) spec; [ClawHub](https://clawhub.ai) + `openclaw skills install` | `.cursor/rules/*.mdc` (globs, `alwaysApply`), `AGENTS.md`, `.cursor/skills/` | `.devin/rules/` or `.windsurf/rules/` (persistent context); `.windsurf/workflows/` (reusable recipes) |-| **Plugins & Connectors** | Reach into real tools | MCP servers via `CallMcpTool` | MCP servers + plugins | Connectors (MCP) + plugins for distribution | MCP + channel plugins (Slack, Telegram, WhatsApp, etc.); browser automation plugin | MCP in settings; Cloud Agent sandbox with full connector access | MCP via Cascade settings / `mcp_config.json` |-| **Sub-agents** | Maker / checker split | `Task` tool with `subagent_type`, worktree isolation | Task subagents in `.claude/agents/`, agent teams | Subagents as TOML in `.codex/agents/` | `agents.list` multi-agent routing; isolated cron subagent orchestration; separate verifier agent id | Multi-agent mode, review mode, custom agents in `.cursor/agents/` | Multiple Cascades in parallel; workflow-orchestrated implementer → reviewer steps |-| **State / Memory** | Track what's done across runs | `STATE.md`, todos, durable scheduler state | `AGENTS.md`, progress files, Linear via MCP | Markdown or Linear via connector | `STATE.md`, `HEARTBEAT.md` in workspace; cron persisted in Gateway SQLite; Skill Workshop for skill proposals | `STATE.md`, `LOOP.md`, Cloud Agent memories | `STATE.md`, Cascade **Memories**, workflow run notes |+| Primitive | Job in the Loop | Grok Build TUI | Claude Code | Codex | OpenClaw | Opencode | Cursor | Windsurf |+|-----------|-----------------|----------------|-------------|-------|----------|----------|--------|----------|+| **Automations / Scheduling** | Discovery + triage on a cadence | `/loop [interval] <prompt>`, `scheduler_create` / `scheduler_list` / `scheduler_delete` (`recurring`, `durable`, `fireImmediately`), `monitor` for streaming events | `/loop`, scheduled tasks, cron, hooks, GitHub Actions | [Automations tab](https://developers.openai.com/codex/app/automations): project, prompt, cadence, environment; Triage inbox | [`openclaw cron`](https://docs.openclaw.ai/automation/cron-jobs) (`--cron` / `--every` / `--at`, isolated or main session); webhooks (`POST /hooks/agent`, `/hooks/wake`); heartbeat | OS cron / systemd timer / GitHub Action invokes `opencode run "..."`; headless server via `opencode serve` | Cloud Agents + **Automations** (cron, webhooks, Linear/GitHub/Slack triggers); foreground Agent chat for ad-hoc `/loop`-style prompts | Cascade **Workflows** (`/workflow-name`, manual invoke); pair with GitHub Actions or external cron for true scheduling |+| **Run-until-done** | Keep working until a verifiable condition holds | [`/goal`](https://github.com/cobusgreyling/goal-engineering) + `update_goal` — persistent objective across turns ([Goal Engineering](https://github.com/cobusgreyling/goal-engineering)) | `/goal` — separate model checks completion | `/goal` — pause/resume, verifiable stop condition | Recurring isolated cron with explicit stop condition in `--message`; delegate via `coding-agent` skill to external CLI; hand off bounded work to Goal Engineering | Bounded `opencode run "<goal + stop condition>"` sessions; follow with verifier agent via `--agent verifier` | Agent mode + **hooks** (`.cursor/hooks.json`) for grind-until-green loops | Workflow steps with explicit verification checkpoints; **Memories** for cross-session continuity |+| **Worktrees** | Safe parallel execution | Subagents with `isolation: "worktree"`, background tasks | `git worktree`, `--worktree`, `isolation: worktree` on subagents | Built-in worktree per thread | `exec` + `git worktree` in agent workspace; `coding-agent` delegates to CLI backends; optional sandbox per agent | Explicit `git worktree` per implementer run; pass worktree path with `--dir` | Git worktree per Composer / Cloud Agent task | Workspace isolation; multiple simultaneous Cascade sessions |+| **Skills** | Persistent project knowledge | `SKILL.md` in `.grok/skills/` or `~/.grok/skills/`; invoked by name | `SKILL.md` in `.claude/skills/` or project skills | [Agent Skills](https://developers.openai.com/codex/skills) — `$name` or implicit match | `SKILL.md` in `<workspace>/skills/`, `.agents/skills`, or `~/.openclaw/skills`; [AgentSkills](https://agentskills.io) spec; [ClawHub](https://clawhub.ai) + `openclaw skills install` | `SKILL.md` in `skills/<name>/`; `AGENTS.md` for always-on repo rules | `.cursor/rules/*.mdc` (globs, `alwaysApply`), `AGENTS.md`, `.cursor/skills/` | `.devin/rules/` or `.windsurf/rules/` (persistent context); `.windsurf/workflows/` (reusable recipes) |+| **Plugins & Connectors** | Reach into real tools | MCP servers via `CallMcpTool` | MCP servers + plugins | Connectors (MCP) + plugins for distribution | MCP + channel plugins (Slack, Telegram, WhatsApp, etc.); browser automation plugin | MCP servers in `opencode.json`; GitHub/Linear/Slack via CLI or MCP bridge | MCP in settings; Cloud Agent sandbox with full connector access | MCP via Cascade settings / `mcp_config.json` |+| **Sub-agents** | Maker / checker split | `Task` tool with `subagent_type`, worktree isolation | Task subagents in `.claude/agents/`, agent teams | Subagents as TOML in `.codex/agents/` | `agents.list` multi-agent routing; isolated cron subagent orchestration; separate verifier agent id | Named agents via `opencode agent`; invoke one role per run with `--agent verifier` or `--agent implementer` | Multi-agent mode, review mode, custom agents in `.cursor/agents/` | Multiple Cascades in parallel; workflow-orchestrated implementer → reviewer steps |+| **State / Memory** | Track what's done across runs | `STATE.md`, todos, durable scheduler state | `AGENTS.md`, progress files, Linear via MCP | Markdown or Linear via connector | `STATE.md`, `HEARTBEAT.md` in workspace; cron persisted in Gateway SQLite; Skill Workshop for skill proposals | `STATE.md`, `LOOP.md`, `AGENTS.md`, session export via `opencode export <sessionID>` | `STATE.md`, `LOOP.md`, Cloud Agent memories | `STATE.md`, Cascade **Memories**, workflow run notes |**Reference MCP server:** this repo ships [`tools/mcp-server/`](../tools/mcp-server/) — patterns, skills, state, budget, and safety docs as runtime-queryable MCP resources (reduces prompt stuffing). Config example: [`examples/mcp/loop-engineering.mcp.json`](../examples/mcp/loop-engineering.mcp.json).## Scheduling Quick Reference-| Use case | Grok | Claude Code | Codex | OpenClaw | Cursor | Windsurf |-|----------|------|-------------|-------|----------|--------|----------|-| Every 5 minutes | `/loop 5m <prompt>` | `/loop 5m <prompt>` | Automation, 5m cadence | `openclaw cron create "*/5 * * * *" --session isolated --message "..."` | Automation cron trigger | External cron + `/workflow` or Action |-| Daily morning | `/loop 1d <prompt>` | Cron / `/loop 1d` | Automation, daily | `openclaw cron create "0 7 * * *" --tz ... --session isolated` + optional `--announce` | Automation daily + `AGENTS.md` context | Daily workflow + Memories |-| Until tests pass | [`/goal`](https://github.com/cobusgreyling/goal-engineering/blob/main/patterns/tests-green.md) + `goal-verifier` skill (or loop + verifier) | `/goal all tests pass` | `/goal` | Isolated cron + verifier in message, or `coding-agent` + external CLI | Hooks grind-until-green | Workflow with test/fix loop |-| Survive restart | `scheduler_create` with `durable: true` | Hooks + persisted config | Automation (server-side) | Cron jobs persist in Gateway SQLite | Cloud Agent + repo-persisted state | Memories + committed `STATE.md` |-| Event-driven (CI fail) | `monitor` or GitHub Action | GitHub Action + webhook | Automation + webhook | `POST /hooks/agent` or mapped webhooks | Automation on PR/issue events | GitHub Action triggers + `/workflow` |+| Use case | Grok | Claude Code | Codex | OpenClaw | Opencode | Cursor | Windsurf |+|----------|------|-------------|-------|----------|----------|--------|----------|+| Every 5 minutes | `/loop 5m <prompt>` | `/loop 5m <prompt>` | Automation, 5m cadence | `openclaw cron create "*/5 * * * *" --session isolated --message "..."` | Cron/systemd calls `opencode run "..."` | Automation cron trigger | External cron + `/workflow` or Action |+| Daily morning | `/loop 1d <prompt>` | Cron / `/loop 1d` | Automation, daily | `openclaw cron create "0 7 * * *" --tz ... --session isolated` + optional `--announce` | Cron/systemd calls `opencode run "Run loop-triage"` | Automation daily + `AGENTS.md` context | Daily workflow + Memories |+| Until tests pass | [`/goal`](https://github.com/cobusgreyling/goal-engineering/blob/main/patterns/tests-green.md) + `goal-verifier` skill (or loop + verifier) | `/goal all tests pass` | `/goal` | Isolated cron + verifier in message, or `coding-agent` + external CLI | `opencode run "Goal: all tests pass. Stop when verifier approves."` | Hooks grind-until-green | Workflow with test/fix loop |+| Survive restart | `scheduler_create` with `durable: true` | Hooks + persisted config | Automation (server-side) | Cron jobs persist in Gateway SQLite | systemd timer + committed `STATE.md` + exported sessions | Cloud Agent + repo-persisted state | Memories + committed `STATE.md` |+| Event-driven (CI fail) | `monitor` or GitHub Action | GitHub Action + webhook | Automation + webhook | `POST /hooks/agent` or mapped webhooks | GitHub Action / webhook bridge calls `opencode run` | Automation on PR/issue events | GitHub Action triggers + `/workflow` |## Skill Packaging-| Concept | Grok | Claude Code | Codex | OpenClaw | Cursor | Windsurf |-|---------|------|-------------|-------|----------|--------|----------|-| Authoring format | `SKILL.md` + optional scripts/references | Same | Same | Same ([AgentSkills](https://agentskills.io)) | `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` | `.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 | Rules auto-apply by glob; skills on demand | `/workflow-name` or Rules always-on in Cascade |+| Concept | Grok | Claude Code | Codex | OpenClaw | Opencode | Cursor | Windsurf |+|---------|------|-------------|-------|----------|----------|--------|----------|+| 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 |## Sub-agent Patterns-| Split | When to use | Grok | Claude Code | Codex | OpenClaw | Cursor | Windsurf |-|-------|-------------|------|-------------|-------|----------|--------|----------|-| Implementer → Verifier | Any unattended code change | `Task` + different instructions/model | `.claude/agents/reviewer.md` | TOML agent with higher `reasoning_effort` | Separate `agents.list` id or verifier block in cron message | Review mode or second Cloud Agent pass | Second Cascade or workflow review step |-| Explorer → Implementer | Large unfamiliar codebase | `explore` subagent_type | Explorer agent | Fast read-only subagent | `--light-context` cron + follow-up isolated job | `@codebase` + plan mode first | Audit workflow (read-only) then implement |-| Triage only | Report-first loops | `loop-triage` skill | `$loop-triage` | Automation calls skill | `loop-triage` + isolated cron; restrict `--tools` | `AGENTS.md` + report-only rule | Triage workflow, no edit steps |+| Split | When to use | Grok | Claude Code | Codex | OpenClaw | Opencode | Cursor | Windsurf |+|-------|-------------|------|-------------|-------|----------|----------|--------|----------|+| Implementer → Verifier | Any unattended code change | `Task` + different instructions/model | `.claude/agents/reviewer.md` | TOML agent with higher `reasoning_effort` | Separate `agents.list` id or verifier block in cron message | `opencode run "..." --agent implementer` in worktree, then `opencode run "Verify diff" --agent verifier --file diff.patch` | Review mode or second Cloud Agent pass | Second Cascade or workflow review step |+| Explorer → Implementer | Large unfamiliar codebase | `explore` subagent_type | Explorer agent | Fast read-only subagent | `--light-context` cron + follow-up isolated job | First `opencode run "read-only exploration..."`, then follow-up implementer in a worktree | `@codebase` + plan mode first | Audit workflow (read-only) then implement |+| Triage only | Report-first loops | `loop-triage` skill | `$loop-triage` | Automation calls skill | `loop-triage` + isolated cron; restrict `--tools` | `opencode run "Run loop-triage. Do not edit code."` | `AGENTS.md` + report-only rule | Triage workflow, no edit steps |## State Conventions@@ -63,7 +63,7 @@ You do not need to pick one forever. A well-designed loop transfers:3. Document the **verification split** (who checks whom)4. Map scheduling to your current TUI, editor, or Action-See [examples/](../examples/) for the same pattern implemented across tools.+For opencode, the transfer usually means `skills/`, `STATE.md`, `AGENTS.md`, and cron/systemd invoking `opencode run`. See [examples/](../examples/) for the same pattern implemented across tools.## Copy-paste starters (Daily Triage, L1)@@ -73,6 +73,7 @@ See [examples/](../examples/) for the same pattern implemented across tools.| Claude Code | [starters/minimal-loop-claude](../starters/minimal-loop-claude/) || Codex | [starters/minimal-loop-codex](../starters/minimal-loop-codex/) || OpenClaw | [examples/openclaw/daily-triage.md](../examples/openclaw/daily-triage.md) — copy `skills/` + `STATE.md`; no `loop-init` yet |+| Opencode | [starters/minimal-loop-opencode](../starters/minimal-loop-opencode/) || Cursor / Windsurf | Copy `SKILL.md` + `STATE.md` from any starter; map scheduling to editor Automations or Workflows (see appendix) |Audit after copying: `npx @cobusgreyling/loop-audit . --suggest`@@ -89,18 +90,18 @@ Loops discover ongoing work; **goals finish bounded tasks**. Canonical reference| Audit goal readiness | `npx @cobusgreyling/goal-audit . --suggest` || Goal vs loop decision | [goal-vs-loop.md](https://github.com/cobusgreyling/goal-engineering/blob/main/docs/goal-vs-loop.md) |-## Appendix: Editor transfer recipes (Cursor & Windsurf)+## Appendix: Editor transfer recipes (Opencode, Cursor & Windsurf)-No dedicated starters yet — map capabilities to the same loop shape:+Transfer recipes map the same loop shape onto each host:-| Step | Cursor | Windsurf |-|------|--------|----------|-| 1. Skills | Copy `templates/SKILL.md.loop-triage` → `.cursor/skills/loop-triage/SKILL.md`; add always-on triage rules in `.cursor/rules/` | Copy skill content into `.windsurf/rules/loop-triage.md` |-| 2. State | `cp starters/minimal-loop/STATE.md.example STATE.md` | Same — commit `STATE.md` at repo root |-| 3. Scheduling | Cloud Automation (cron) or manual Agent prompt on cadence | Create `.windsurf/workflows/daily-triage.md`, invoke `/daily-triage` |-| 4. Verification | `.cursor/agents/loop-verifier.md` from `templates/SKILL.md.verifier` | Add review step at end of workflow; human gate on denylist paths |-| 5. Connectors | Enable GitHub MCP read-only for issue/PR discovery | Configure GitHub MCP in Cascade settings |+| Step | Opencode | Cursor | Windsurf |+|------|----------|--------|----------|+| 1. Skills | Copy `templates/SKILL.md.loop-triage` → `skills/loop-triage/SKILL.md`; add always-on rules in `AGENTS.md` | Copy `templates/SKILL.md.loop-triage` → `.cursor/skills/loop-triage/SKILL.md`; add always-on triage rules in `.cursor/rules/` | Copy skill content into `.windsurf/rules/loop-triage.md` |+| 2. State | `cp starters/minimal-loop-opencode/STATE.md.example STATE.md` | `cp starters/minimal-loop/STATE.md.example STATE.md` | Same — commit `STATE.md` at repo root |+| 3. Scheduling | Cron/systemd calls `opencode run "Run loop-triage"`; use `--session` / `--continue` for continuity | Cloud Automation (cron) or manual Agent prompt on cadence | Create `.windsurf/workflows/daily-triage.md`, invoke `/daily-triage` |+| 4. Verification | Create a verifier named agent with `opencode agent`; invoke via `opencode run "Verify diff" --agent verifier --file diff.patch` | `.cursor/agents/loop-verifier.md` from `templates/SKILL.md.verifier` | Add review step at end of workflow; human gate on denylist paths |+| 5. Connectors | Configure MCP or CLI bridges in `opencode.json` | Enable GitHub MCP read-only for issue/PR discovery | Configure GitHub MCP in Cascade settings |**Aider** (CLI-only): use `--watch` or scripted sessions; state in `STATE.md`; reviewer = second terminal session.-Transfer recipe: copy the tool-agnostic `SKILL.md` + state schema from this repo; map scheduling to your editor's automation surface.\ No newline at end of file+Transfer recipe: copy the tool-agnostic `SKILL.md` + state schema from this repo; map scheduling to your editor's automation surface.diff --git a/examples/README.md b/examples/README.mdindex f4d24b1..977fff6 100644--- a/examples/README.md+++ b/examples/README.md@@ -8,6 +8,7 @@ Same patterns, different tools. Skills and state schemas are shared; only schedu| Claude Code | [claude-code/](./claude-code/) || Codex App | [codex/](./codex/) || OpenClaw | [openclaw/](./openclaw/) |+| Opencode | [opencode/](./opencode/) || GitHub Actions | [github-actions/](./github-actions/) || MCP connectors | [mcp/](./mcp/) — config example; reference server in [tools/mcp-server/](../tools/mcp-server/) |@@ -15,15 +16,15 @@ Start with [primitives-matrix.md](../docs/primitives-matrix.md) to map capabilit## Pattern coverage-| Pattern | Grok | Claude | Codex | OpenClaw | GH Actions |-|---------|------|--------|-------|----------|------------|-| Daily Triage | [grok/daily-triage.md](./grok/daily-triage.md) | [claude-code/daily-triage.md](./claude-code/daily-triage.md) | [codex/daily-triage.md](./codex/daily-triage.md) | [openclaw/daily-triage.md](./openclaw/daily-triage.md) | [github-actions/daily-triage.yml](./github-actions/daily-triage.yml) |-| PR Babysitter | [grok/pr-babysitter.md](./grok/pr-babysitter.md) | [claude-code/pr-babysitter.md](./claude-code/pr-babysitter.md) | [codex/pr-babysitter.md](./codex/pr-babysitter.md) | [github-actions/pr-babysitter.yml](./github-actions/pr-babysitter.yml) |-| CI Sweeper | [grok/ci-sweeper.md](./grok/ci-sweeper.md) | [claude-code/ci-sweeper.md](./claude-code/ci-sweeper.md) | [codex/ci-sweeper.md](./codex/ci-sweeper.md) | [github-actions/ci-sweeper.yml](./github-actions/ci-sweeper.yml) |-| Post-Merge Cleanup | [grok/post-merge-cleanup.md](./grok/post-merge-cleanup.md) | [claude-code/post-merge-cleanup.md](./claude-code/post-merge-cleanup.md) | [codex/post-merge-cleanup.md](./codex/post-merge-cleanup.md) | [github-actions/post-merge-cleanup.yml](./github-actions/post-merge-cleanup.yml) |-| Dependency Sweeper | [grok/dependency-sweeper.md](./grok/dependency-sweeper.md) | [claude-code/dependency-sweeper.md](./claude-code/dependency-sweeper.md) | [codex/dependency-sweeper.md](./codex/dependency-sweeper.md) | [github-actions/dependency-sweeper.yml](./github-actions/dependency-sweeper.yml) |-| Changelog Drafter | [grok/changelog-drafter.md](./grok/changelog-drafter.md) | [claude-code/changelog-drafter.md](./claude-code/changelog-drafter.md) | [codex/changelog-drafter.md](./codex/changelog-drafter.md) | [github-actions/changelog-drafter.yml](./github-actions/changelog-drafter.yml) |-| Issue Triage | [grok/issue-triage.md](./grok/issue-triage.md) | [claude-code/issue-triage.md](./claude-code/issue-triage.md) | [codex/issue-triage.md](./codex/issue-triage.md) | [github-actions/issue-triage.yml](./github-actions/issue-triage.yml) |+| Pattern | Grok | Claude | Codex | OpenClaw | Opencode | GH Actions |+|---------|------|--------|-------|----------|----------|------------|+| Daily Triage | [grok/daily-triage.md](./grok/daily-triage.md) | [claude-code/daily-triage.md](./claude-code/daily-triage.md) | [codex/daily-triage.md](./codex/daily-triage.md) | [openclaw/daily-triage.md](./openclaw/daily-triage.md) | [opencode/daily-triage.md](./opencode/daily-triage.md) | [github-actions/daily-triage.yml](./github-actions/daily-triage.yml) |+| PR Babysitter | [grok/pr-babysitter.md](./grok/pr-babysitter.md) | [claude-code/pr-babysitter.md](./claude-code/pr-babysitter.md) | [codex/pr-babysitter.md](./codex/pr-babysitter.md) | — | [opencode/pr-babysitter.md](./opencode/pr-babysitter.md) | [github-actions/pr-babysitter.yml](./github-actions/pr-babysitter.yml) |+| CI Sweeper | [grok/ci-sweeper.md](./grok/ci-sweeper.md) | [claude-code/ci-sweeper.md](./claude-code/ci-sweeper.md) | [codex/ci-sweeper.md](./codex/ci-sweeper.md) | — | [opencode/ci-sweeper.md](./opencode/ci-sweeper.md) | [github-actions/ci-sweeper.yml](./github-actions/ci-sweeper.yml) |+| Post-Merge Cleanup | [grok/post-merge-cleanup.md](./grok/post-merge-cleanup.md) | [claude-code/post-merge-cleanup.md](./claude-code/post-merge-cleanup.md) | [codex/post-merge-cleanup.md](./codex/post-merge-cleanup.md) | — | — | [github-actions/post-merge-cleanup.yml](./github-actions/post-merge-cleanup.yml) |+| Dependency Sweeper | [grok/dependency-sweeper.md](./grok/dependency-sweeper.md) | [claude-code/dependency-sweeper.md](./claude-code/dependency-sweeper.md) | [codex/dependency-sweeper.md](./codex/dependency-sweeper.md) | — | — | [github-actions/dependency-sweeper.yml](./github-actions/dependency-sweeper.yml) |+| Changelog Drafter | [grok/changelog-drafter.md](./grok/changelog-drafter.md) | [claude-code/changelog-drafter.md](./claude-code/changelog-drafter.md) | [codex/changelog-drafter.md](./codex/changelog-drafter.md) | — | — | [github-actions/changelog-drafter.yml](./github-actions/changelog-drafter.yml) |+| Issue Triage | [grok/issue-triage.md](./grok/issue-triage.md) | [claude-code/issue-triage.md](./claude-code/issue-triage.md) | [codex/issue-triage.md](./codex/issue-triage.md) | — | — | [github-actions/issue-triage.yml](./github-actions/issue-triage.yml) |L2 patterns ship multi-tool skills inside one starter folder — see `starters/<pattern>/`.@@ -34,4 +35,5 @@ L2 patterns ship multi-tool skills inside one starter folder — see `starters/<| Grok | [starters/minimal-loop](../starters/minimal-loop/) || Claude Code | [starters/minimal-loop-claude](../starters/minimal-loop-claude/) || Codex | [starters/minimal-loop-codex](../starters/minimal-loop-codex/) |-| OpenClaw | [openclaw/daily-triage.md](./openclaw/daily-triage.md) (manual setup) |\ No newline at end of file+| OpenClaw | [openclaw/daily-triage.md](./openclaw/daily-triage.md) (manual setup) |+| Opencode | [starters/minimal-loop-opencode](../starters/minimal-loop-opencode/) |diff --git a/examples/opencode/README.md b/examples/opencode/README.mdnew file mode 100644index 0000000..b47f454--- /dev/null+++ b/examples/opencode/README.md@@ -0,0 +1,16 @@+# Opencode++Open-source coding agent that runs from the CLI, can run headlessly via `opencode run`, supports named agents, and can connect to tools through MCP. Loop engineering primitives publish to plain files: `AGENTS.md`, `STATE.md`, and `skills/` folders in the [AgentSkills](https://agentskills.io) format.++| Example | Pattern |+|---------|---------|+| [daily-triage.md](./daily-triage.md) | Daily Triage (L1 report → L2 assisted) |+| [constraints.md](./constraints.md) | Constraints (binding rules loaded before every loop run) |+| [ci-sweeper.md](./ci-sweeper.md) | CI Sweeper (cron/systemd + `opencode run` for short cadences) |+| [pr-babysitter.md](./pr-babysitter.md) | PR Babysitter (long-running PR shepherd with worktree isolation) |++> **Starter kit:** [../../starters/minimal-loop-opencode/](../../starters/minimal-loop-opencode/) — clone-and-run scaffold for L1 daily triage.+>+> No `loop-init --tool opencode` yet; copy the starter or follow the snippets below in 30 seconds.++See [docs/primitives-matrix.md](../../docs/primitives-matrix.md) for the full capability comparison.diff --git a/examples/opencode/ci-sweeper.md b/examples/opencode/ci-sweeper.mdnew file mode 100644index 0000000..5128156--- /dev/null+++ b/examples/opencode/ci-sweeper.md@@ -0,0 +1,89 @@+# CI Sweeper — Opencode++React to failing CI with minimal fixes and short cadences. opencode shines at 5–15 minute loops because the CLI doesn't depend on a TUI session.++## Prerequisites++```bash+mkdir -p skills/ci-triage+cp templates/SKILL.md.loop-triage skills/ci-triage/SKILL.md # same triage body+mkdir -p skills/minimal-fix+cp templates/SKILL.md.minimal-fix skills/minimal-fix/SKILL.md+mkdir -p skills/loop-verifier+cp templates/SKILL.md.verifier skills/loop-verifier/SKILL.md+```++Plus a fresh state file at the root:++```bash+cp starters/minimal-loop-opencode/STATE.md.example ci-sweeper-state.md+```++## Cadence: cron (recommended for CI sweeper)++CI sweeper tolerates nothing wasted between runs. A system cron at 5-minute resolution is the canonical schedule; pair it with a wrapper script that throws context to the agent:++```cron+*/5 * * * * cd /repo && /usr/local/bin/opencode-run-ci.sh >> /var/log/ci-sweeper.log 2>&1+```++`opencode-run-ci.sh`:++```bash+#!/usr/bin/env bash+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"+```++Use [loop-cost](https://github.com/cobusgreyling/loop-engineering/blob/main/tools/loop-cost) before choosing a cadence; encode the daily cap in `LOOP.md` and `AGENTS.md` as a hard stop.++## Cadence: shell loop++If you'd rather keep the loop fully in the CLI, run a long-lived shell loop instead of editing crontab:++```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+ sleep 300+done+```++Same primitive, different scheduler.++## Webhook variant (post-deploy)++```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' \+ -d '{"message":"Run ci-triage. Inspect recent CI failures. No fixes in report-only mode."}'+```++Keep hook endpoints on loopback or a trusted tailnet (see [docs/safety.md](../../docs/safety.md)).++## Verification split++| Role | Opencode shape |+|------|----------------|+| Triage | `skills/ci-triage/SKILL.md` (or alias to `loop-triage`) + `--agent ci-triage` |+| Implementer | `opencode run "..." --agent implementer --dir <worktree>` |+| Verifier | `opencode run "Verify diff" --agent verifier --file <diff.patch>` |++Discard the worktree after verifier REJECT; merge or PR on APPROVE.++## Safety (L1 defaults)++- Dispatch into a worktree per attempt — never edit the main working tree.+- Max 3 fix attempts per item; escalate after to a human with full context.+- Infra / security / payments test failures: do not auto-fix; flag and stop.+- Budget cap documented in `LOOP.md` and enforced by the prompt (`loop-pause-all` stops action).++## References++- [patterns/ci-sweeper.md](../../patterns/ci-sweeper.md)+- [templates/SKILL.md.loop-triage](../../templates/SKILL.md.loop-triage)+- [tools/loop-cost](../../tools/loop-cost) — cadence-to-cost mappingdiff --git a/examples/opencode/constraints.md b/examples/opencode/constraints.mdnew file mode 100644index 0000000..ecc78ae--- /dev/null+++ b/examples/opencode/constraints.md@@ -0,0 +1,58 @@+# Constraints — Opencode++Binding rules the loop must never break. The `loop-constraints` skill reads `loop-constraints.md` at the start of every run.++## Quick start++```bash+# Append a rule (the loop runs once to read + persist, then every subsequent run enforces)+opencode run \+ "Append this rule to loop-constraints.md verbatim: 'Don't push before telling me. Always run tests first.'"+```++Or just edit `loop-constraints.md` directly. Comments are allowed; the loop reads every line below the header as a binding rule.++## Before every loop run++Make every scheduled run invoke constraints **before** triage. The skill itself reads `loop-constraints.md` and bakes the rules into the agent's context before any action runs:++```bash+opencode run "Run skills/loop-constraints/SKILL.md. Then run skills/loop-triage/SKILL.md. Update STATE.md. No auto-fix in week one."+```++## How it works++1. `loop-constraints.md` lives at the repo root.+2. `loop-constraints` skill lives at `skills/loop-constraints/SKILL.md` (copy from `templates/SKILL.md.loop-constraints`).+3. Every loop run starts with the constraints skill — it reads the file, loads rules, outputs them at the top of the prompt.+4. Triage then runs **inside the same context** with the rules baked in.++## Scaffold automatically++Opencode doesn't ship a `loop-init` scaffolder yet. Copy the templates:++```bash+mkdir -p skills/loop-constraints+cp templates/SKILL.md.loop-constraints skills/loop-constraints/SKILL.md+cp templates/loop-constraints.md loop-constraints.md+```++Or use the cross-tool scaffolder and import the generated files:++```bash+npx @cobusgreyling/loop-init . --pattern daily-triage --tool claude # generates SKILLs+mkdir -p skills+cp -r .claude/skills/* skills/ # adapt comments for opencode if needed+```++Both paths land at the same shape: a `loop-constraints.md` file you can edit by hand.++## Safety++Constraints are *binding*. If a rule can be misinterpreted, rewrite it — the loop will not second-guess, the human will.++## References++- [templates/loop-constraints.md](../../templates/loop-constraints.md) — default constraint set+- [templates/SKILL.md.loop-constraints](../../templates/SKILL.md.loop-constraints) — constraints skill template+- [docs/safety.md](../../docs/safety.md)diff --git a/examples/opencode/daily-triage.md b/examples/opencode/daily-triage.mdnew file mode 100644index 0000000..b08a08e--- /dev/null+++ b/examples/opencode/daily-triage.md@@ -0,0 +1,134 @@+# Daily Triage — Opencode++Same pattern as Grok and Claude Code; **scheduling runs from cron/systemd** and each tick invokes `opencode run` instead of a TUI `/loop`.++## Prerequisites++1. [Opencode CLI](https://opencode.ai) installed and authenticated against your preferred provider.+2. `STATE.md` at the repo root — copy from `starters/minimal-loop-opencode/STATE.md.example`.+3. `loop-triage` skill — copy `templates/SKILL.md.loop-triage` to `skills/loop-triage/SKILL.md`.++```bash+mkdir -p skills/loop-triage+cp templates/SKILL.md.loop-triage skills/loop-triage/SKILL.md+cp starters/minimal-loop-opencode/STATE.md.example STATE.md+```++## Report-Only (Week 1)++Use cron or a systemd timer to run a fresh opencode session each morning. The prompt forces the run to read `STATE.md` first so state carries across sessions.++```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))"+```++The report-only stance is enforced by `AGENTS.md` and the prompt: no source-code edits in week one.++Faster cadence during active periods:++```cron+0 */2 * * * cd /repo && opencode run "Run loop-triage. Report obvious small wins only. Update STATE.md. No code changes."+```++## 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`:++```bash+git worktree add ../wt-small-fix -b loop/small-fix+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+opencode run "Review this diff against project rules and tests. APPROVE or REJECT only." \+ --agent verifier \+ --file /tmp/loop-diff.patch+```++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`.++## Goal Mode Alternative++For a one-shot "get main green" session, drive opencode with the [Goal Engineering](https://github.com/cobusgreyling/goal-engineering) `/goal` skill. opencode is goal-friendly: hand it the goal, the stop condition, and the verifier prompt and let the verifier decide when to stop.++```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+opencode run "Verify the goal is complete. APPROVE only if tests pass and the diff is minimal." \+ --agent verifier \+ --file /tmp/goal-diff.patch+```++## Skills Setup++Copy from `templates/SKILL.md.loop-triage` to `skills/loop-triage/SKILL.md` (the `skills/` dir is auto-discovered by opencode at the repo root):++```bash+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+```++## Sub-agents++Opencode exposes named agents through `opencode agent`. Keep each agent's role text aligned with the same maker/checker contract used by the other examples:++```text+Verifier: review code changes against project skills and tests. Always REJECT or APPROVE.+```++Invoke one role per run with `--agent verifier` or `--agent implementer` (see Week 3+ example). Use explicit git worktrees for any implementer that will edit code.++## State Conventions++The default spine is `STATE.md` at the repo root. Use `STATE.md.example` for the template (gitignored live state). For pattern-specific state, follow the [state conventions in primitives-matrix.md](../../docs/primitives-matrix.md).++## Safety (L1 defaults)++- Week one: report-only prompt + `AGENTS.md` safety rules; no source-code edits.+- One worktree per fix attempt; discard after verifier REJECT.+- Never push without a draft PR and explicit human review on denylisted paths (`docs/safety.md`).+- Token budget: set `loop-pause-all` in `STATE.md` if a run exceeds the daily cap.++## Operations++```bash+crontab -l+systemctl --user list-timers+opencode session list+opencode export <sessionID> > loop-session.json+```++Pause: disable the cron/systemd timer or set `loop-pause-all` in `STATE.md` and teach the skill to stop acting.++Audit readiness: `npx @cobusgreyling/loop-audit . --suggest`.++## When to pick opencode over a TUI agent++- You want **scheduling without a TUI** — cron/systemd can call `opencode run` in CI, in tmux, and on a headless box.+- You want to keep your **state and skills in plain files** (`STATE.md`, `skills/`) that survive a host change.+- You're already running **systemd timers** or **cron** for unrelated work — fold opencode loops into the same scheduler.++## References++- Peter Steinberger — design loops, not one-off prompts ([sources](../../resources/sources.md))+- [primitives-matrix.md](../../docs/primitives-matrix.md) — opencode column+- [patterns/daily-triage.md](../../patterns/daily-triage.md)+- [docs/safety.md](../../docs/safety.md)diff --git a/examples/opencode/pr-babysitter.md b/examples/opencode/pr-babysitter.mdnew file mode 100644index 0000000..7bc973a--- /dev/null+++ b/examples/opencode/pr-babysitter.md@@ -0,0 +1,57 @@+# PR Babysitter — Opencode++Watch open PRs, surface blockers, and act only on safe, obvious maintenance tasks. opencode works well here because the loop can run headless while still preserving state in `pr-babysitter-state.md`.++## Report-Only (Week 1)++```bash+opencode run \+ "Run PR babysitter triage. Read pr-babysitter-state.md first. List PRs with red CI, stale review, merge conflicts, or unanswered review comments. Do not edit code. Update pr-babysitter-state.md and end with the top 3 human actions." \+ --title "PR babysitter"+```++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+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+```++## Idempotency++Before pushing anything, the loop must check whether an open PR or branch already exists for the same intent:++```bash+gh pr list --state open --search "<issue-or-fix-slug>" --json number,title,headRefName,url+```++If a matching PR exists, update state and skip duplicate work.++## Verification Split++| Role | Opencode shape |+|------|----------------|+| Triage | `skills/pr-review-triage/SKILL.md` or `skills/loop-triage/SKILL.md` with PR-focused prompt |+| Implementer | `opencode run "..." --agent implementer --dir <worktree>` scoped to the PR branch |+| Verifier | `opencode run "Verify diff" --agent verifier --file <diff.patch>` |++## Safety (L1 defaults)++- Never force-push without explicit human opt-in.+- Draft PRs by default; humans mark ready for review.+- Do not resolve review threads without approval.+- Security, auth, payments, infra, or public API changes always escalate.+- Max 3 fix attempts per PR before handoff.++## References++- [patterns/pr-babysitter.md](../../patterns/pr-babysitter.md)+- [docs/safety.md](../../docs/safety.md)+- [examples/github-actions/pr-babysitter.yml](../github-actions/pr-babysitter.yml)diff --git a/scripts/before-after-demo.sh b/scripts/before-after-demo.shindex 23671dc..01906ea 100755--- a/scripts/before-after-demo.sh+++ b/scripts/before-after-demo.sh@@ -73,5 +73,6 @@ echo "Done. Copy a starter for your tool:"echo " Grok: cp -r starters/minimal-loop/.grok/skills/loop-triage .grok/skills/"echo " Claude Code: cp -r starters/minimal-loop-claude/.claude/skills/loop-triage .claude/skills/"echo " Codex: cp -r starters/minimal-loop-codex/.codex/skills/loop-triage .codex/skills/"+echo " Opencode: cp -r starters/minimal-loop-opencode/skills ."echo ""-echo "Audit your project: npx @cobusgreyling/loop-audit . --suggest"\ No newline at end of file+echo "Audit your project: npx @cobusgreyling/loop-audit . --suggest"diff --git a/starters/README.md b/starters/README.mdindex fad3227..a51897c 100644--- a/starters/README.md+++ b/starters/README.md@@ -14,6 +14,7 @@ npx @cobusgreyling/loop-init . -p pr-babysitter -t claude| [minimal-loop](./minimal-loop/) | Grok | `.grok/skills/` || [minimal-loop-claude](./minimal-loop-claude/) | Claude Code | `.claude/skills/` + `.claude/agents/` || [minimal-loop-codex](./minimal-loop-codex/) | Codex | `.codex/skills/` + `.codex/agents/` |+| [minimal-loop-opencode](./minimal-loop-opencode/) | Opencode | `skills/` + `AGENTS.md` |## L2 assisted patterns@@ -31,4 +32,4 @@ After copying:```bashnpx @cobusgreyling/loop-audit .npx @cobusgreyling/loop-audit . --suggest-```\ No newline at end of file+```diff --git a/starters/minimal-loop-opencode/AGENTS.md b/starters/minimal-loop-opencode/AGENTS.mdnew file mode 100644index 0000000..6f602fe--- /dev/null+++ b/starters/minimal-loop-opencode/AGENTS.md@@ -0,0 +1,23 @@+# AGENTS.md — Opencode Minimal Loop++These rules are loaded by opencode before loop work.++## Loop Mode++- Start in L1 report-only mode.+- Read `STATE.md` before any triage.+- Update `STATE.md` after every loop run.+- Do not edit source code until the human explicitly enables L2.++## Safety++- Never push or merge without human approval.+- Never edit `.env`, `.env.*`, `auth/`, `payments/`, `secrets/`, or `credentials/`.+- Use a git worktree for every code-changing attempt.+- Max 3 fix attempts per item; escalate after that.++## Verification++- For L2+ changes, dispatch a verifier sub-agent after implementation.+- Run the project's documented tests before proposing a fix.+- Record test evidence in `STATE.md`.diff --git a/starters/minimal-loop-opencode/LOOP.md b/starters/minimal-loop-opencode/LOOP.mdnew file mode 100644index 0000000..4c6d061--- /dev/null+++ b/starters/minimal-loop-opencode/LOOP.md@@ -0,0 +1,33 @@+# Loop Configuration — Minimal Triage (Opencode)++## Active Loops++| Pattern | Cadence | Status | Command |+|---------|---------|--------|---------|+| Daily Triage | 1d | L1 report-only | `opencode run "Run loop-triage" --agent loop-triage` via cron/systemd |++## Human Gates++- No auto-fix until L2 checklist complete.+- All high-risk paths require human review (see docs/safety.md denylist).++## Worktrees++- Use an explicit `git worktree` and run opencode with `--dir <worktree>` for implementer runs (L2+).+- One worktree per fix attempt; discard after verifier REJECT.++## Connectors (MCP)++- MCP optional for L1 report-only loops.+- For L2+: GitHub MCP can read CI/issues; scope connectors to read + comment until trusted.++## Budget++- Max sub-agent spawns per run: 0 (L1).+- Review STATE.md daily.+- If token spend hits 80% of daily cap, switch to report-only.++## Links++- Pattern: [daily-triage](../../patterns/daily-triage.md)+- Checklist: [loop-design-checklist](../../docs/loop-design-checklist.md)diff --git a/starters/minimal-loop-opencode/README.md b/starters/minimal-loop-opencode/README.mdnew file mode 100644index 0000000..1606573--- /dev/null+++ b/starters/minimal-loop-opencode/README.md@@ -0,0 +1,44 @@+# Minimal Loop Starter — Opencode++Clone this into your project root to run a **report-only daily triage loop** (L1 readiness) with opencode.++## Quick Start++1. Copy files into your repo:++ ```bash+ cp -r starters/minimal-loop-opencode/skills .+ cp starters/minimal-loop-opencode/AGENTS.md .+ cp starters/minimal-loop-opencode/LOOP.md .+ cp starters/minimal-loop-opencode/STATE.md.example STATE.md+ cp starters/minimal-loop-opencode/opencode.json.example opencode.json+ ```++2. Customize `STATE.md` project name.++3. Start the loop:++ ```bash+ opencode run "Run loop-triage. Read STATE.md first. Append high-priority and watch items. Update Last run timestamp. Do not auto-fix anything in week one." --agent loop-triage+ ```++4. Read `STATE.md` each morning for 1-2 weeks. Tune the triage skill.++5. When triage quality is good, add `minimal-fix` from `templates/SKILL.md.minimal-fix` and enable small auto-wins with a verifier agent in a worktree.++## What's Included++| File | Purpose |+|------|---------|+| `STATE.md.example` | State spine template |+| `skills/loop-triage/SKILL.md` | Triage skill |+| `AGENTS.md` | Always-on project rules for opencode |+| `LOOP.md` | Loop config doc for your team |+| `opencode.json.example` | Example opencode agent definitions |++## Next Steps++- [Loop Design Checklist](../../docs/loop-design-checklist.md)+- [Daily Triage pattern](../../patterns/daily-triage.md)+- [Opencode example](../../examples/opencode/daily-triage.md)+- Run `npx @cobusgreyling/loop-audit .` for readiness scorediff --git a/starters/minimal-loop-opencode/STATE.md.example b/starters/minimal-loop-opencode/STATE.md.examplenew file mode 100644index 0000000..cf5db35--- /dev/null+++ b/starters/minimal-loop-opencode/STATE.md.example@@ -0,0 +1,12 @@+# Loop State — My Project++Last run: never++## High Priority (loop is acting or waiting on human)++## Watch List++## Recent Noise (ignored this run)++---+Run log: —diff --git a/starters/minimal-loop-opencode/opencode.json.example b/starters/minimal-loop-opencode/opencode.json.examplenew file mode 100644index 0000000..92b485e--- /dev/null+++ b/starters/minimal-loop-opencode/opencode.json.example@@ -0,0 +1,25 @@+{+ "$schema": "https://opencode.ai/config.json",+ "agent": {+ "loop-triage": {+ "name": "loop-triage",+ "description": "Report-only daily triage loop. Reads STATE.md, updates high-priority items, and does not edit source code in L1 mode.",+ "mode": "primary",+ "prompt": "Read AGENTS.md, LOOP.md, STATE.md, and skills/loop-triage/SKILL.md. Run report-only triage. Update STATE.md. Do not edit source code unless the human has explicitly enabled L2.",+ "permission": {+ "bash": "ask",+ "edit": "ask"+ }+ },+ "verifier": {+ "name": "verifier",+ "description": "Checker agent for L2+ changes. Reviews diffs and test evidence; APPROVE or REJECT only.",+ "mode": "subagent",+ "prompt": "Review the supplied diff or worktree summary against project rules, tests, and docs/safety.md. Do not edit files. Respond with APPROVE or REJECT and concise evidence.",+ "permission": {+ "bash": "ask",+ "edit": "deny"+ }+ }+ }+}diff --git a/starters/minimal-loop-opencode/skills/loop-triage/SKILL.md b/starters/minimal-loop-opencode/skills/loop-triage/SKILL.mdnew file mode 100644index 0000000..1572519--- /dev/null+++ b/starters/minimal-loop-opencode/skills/loop-triage/SKILL.md@@ -0,0 +1,59 @@+---+name: loop-triage+description: >+ Triage recent changes, CI failures, issues, and conversations.+ Produces a concise, actionable findings report suitable for a loop to consume.+ Writes structured output to a state file or issue tracker.+user_invocable: true+---++# Loop Triage Skill++You are an expert engineering triage agent. Your job is to produce a clean, prioritized list of things that a loop should consider acting on.++## Inputs (the loop will provide these)++- Recent CI / test failures (last 24h)+- Open issues / tickets assigned to the team+- Recent commits on main (last 24-48h)+- Any chat threads the loop has visibility into+- The current state file (what the loop already knows about)++## Output Format++Produce a markdown report with these sections:++### 1. High-Priority Items (act on these)++- Clear, one-line description+- Why it matters (impact, risk, or customer pain)+- Suggested next action for the loop (for example, "draft minimal fix in isolated worktree")+- Rough effort estimate++### 2. Watch Items (monitor, do not act yet)++- Same format but lower urgency++### 3. Noise / Ignore++- Brief list of things the loop looked at and decided were not worth action++### 4. State Updates++- Any facts the loop should remember for the next run (for example, "PR #1234 now has 2 approvals")++## Rules++- Be brutally concise. The loop and the human reading the state will thank you.+- Only put something in "High-Priority" if a reasonable engineer would want to know about it today.+- When in doubt, put it in Watch or Noise rather than creating work.+- Never propose architectural overhauls during triage — this skill is for signal, not invention.+- Respect the project's existing skills and conventions (they will be provided in context).++## Example Invocation (in an opencode loop)++```bash+opencode run "Call loop-triage and append high-priority items to STATE.md. Do not edit code."+```++The triage skill should be the "eyes" of the loop. Keep it focused and honest.