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(opencode): loop-init tool, audit verifier detection, QUICKSTART

Cobus Greyling9cd0d8dbc3d7
diff --git a/STATE.md b/STATE.md
index dea372d..6f5a5c3 100644
--- a/STATE.md
+++ b/STATE.md
@@ -12,7 +12,7 @@ Last run: 2026-06-30T10:45:45Z (automated daily-triage workflow)
- Expand contributor failure stories (dependency sweeper, multi-loop).
- Collect a production story for Post-Merge Cleanup.
-- Validate `loop-init` scaffolds on fresh projects across all patterns.
+- Validate `loop-init` scaffolds on fresh projects across all patterns (`opencode` daily-triage shipped; L2 patterns still Grok-first).
## Recent Noise (ignored this run)
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
index 47c266a..8ab2972 100644
--- a/docs/QUICKSTART.md
+++ b/docs/QUICKSTART.md
@@ -22,7 +22,7 @@ Run this in the root of any git project (no clone required):
npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok
```
-Swap `--tool grok` for `claude` or `codex` if needed. Swap `--pattern` for any pattern from [patterns/registry.yaml](../patterns/registry.yaml).
+Swap `--tool grok` for `claude`, `codex`, or `opencode` if needed. Swap `--pattern` for any pattern from [patterns/registry.yaml](../patterns/registry.yaml).
`loop-init` copies the starter kit, creates `STATE.md`, `LOOP.md`, `loop-budget.md`, and `loop-run-log.md`, then **prints your Loop Ready score** and first command.
@@ -68,6 +68,20 @@ Use the first-run command printed by `loop-init` (pattern-specific). Week one: t
No `loop-init --tool openclaw` yet — copy `skills/loop-triage/SKILL.md` and `STATE.md`, then create an isolated cron job. See [examples/openclaw/daily-triage.md](../examples/openclaw/daily-triage.md).
+### Opencode
+
+```bash
+npx @cobusgreyling/loop-init . --pattern daily-triage --tool opencode
+```
+
+Then schedule with cron or systemd — each tick runs headless via `opencode run`:
+
+```bash
+opencode run "Run loop-triage. Read STATE.md first. Update High Priority and Watch List. No auto-fix in week one." --agent loop-triage
+```
+
+See [examples/opencode/daily-triage.md](../examples/opencode/daily-triage.md) for worktree + verifier patterns (L2+).
+
### 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 [Opencode, Cursor & Windsurf appendix](./primitives-matrix.md#appendix-editor-transfer-recipes-opencode-cursor--windsurf) in the primitives matrix.
@@ -95,7 +109,7 @@ Commit the scaffold + first run update so `loop-audit` sees activity on the next
## Copy-paste cheat sheet
```bash
-# Scaffold
+# Scaffold (swap --tool for claude | codex | opencode)
npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok
# Cost check
@@ -111,7 +125,7 @@ npx @cobusgreyling/loop-audit . --badge
## Learn the why (optional, 10 minutes)
- [Loop Engineering essay](https://cobusgreyling.substack.com/p/loop-engineering) — concept and primitives
-- [Primitives matrix](./primitives-matrix.md) — Grok vs Claude vs Codex vs OpenClaw vs Cursor
+- [Primitives matrix](./primitives-matrix.md) — Grok vs Claude vs Codex vs OpenClaw vs Opencode vs Cursor
- [Operating loops](./operating-loops.md) — when to kill a loop
---
diff --git a/examples/opencode/constraints.md b/examples/opencode/constraints.md
index ecc78ae..4f403b6 100644
--- a/examples/opencode/constraints.md
+++ b/examples/opencode/constraints.md
@@ -29,24 +29,20 @@ opencode run "Run skills/loop-constraints/SKILL.md. Then run skills/loop-triage/
## 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
+npx @cobusgreyling/loop-init . --pattern daily-triage --tool opencode
```
-Or use the cross-tool scaffolder and import the generated files:
+`loop-init` copies `loop-constraints.md` and `skills/loop-constraints/SKILL.md` into the repo root layout opencode expects.
+
+Manual copy still works:
```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
+mkdir -p skills/loop-constraints
+cp templates/SKILL.md.loop-constraints skills/loop-constraints/SKILL.md
+cp templates/loop-constraints.md loop-constraints.md
```
-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.
diff --git a/starters/minimal-loop-opencode/README.md b/starters/minimal-loop-opencode/README.md
index 1606573..c630686 100644
--- a/starters/minimal-loop-opencode/README.md
+++ b/starters/minimal-loop-opencode/README.md
@@ -4,7 +4,13 @@ Clone this into your project root to run a **report-only daily triage loop** (L1
## Quick Start
-1. Copy files into your repo:
+1. Scaffold (recommended):
+
+ ```bash
+ npx @cobusgreyling/loop-init . --pattern daily-triage --tool opencode
+ ```
+
+ Or copy manually:
```bash
cp -r starters/minimal-loop-opencode/skills .
diff --git a/tools/loop-audit/dist/auditor.js b/tools/loop-audit/dist/auditor.js
index fcf7082..cee4ef2 100644
--- a/tools/loop-audit/dist/auditor.js
+++ b/tools/loop-audit/dist/auditor.js
@@ -104,6 +104,27 @@ async function findSkills(root) {
}
}
}
+ // Opencode named agents in opencode.json (or the starter example before rename)
+ for (const configName of ['opencode.json', 'opencode.json.example']) {
+ const configPath = path.join(root, configName);
+ if (!(await fileExists(configPath)))
+ continue;
+ try {
+ const raw = await readFile(configPath, 'utf8');
+ const parsed = JSON.parse(raw);
+ const agents = parsed.agent ?? {};
+ for (const [key, def] of Object.entries(agents)) {
+ const name = (def?.name ?? key).toLowerCase();
+ if (name.includes('verifier') || key.toLowerCase().includes('verifier')) {
+ found.push('loop-verifier');
+ break;
+ }
+ }
+ }
+ catch {
+ // ignore invalid JSON
+ }
+ }
return found;
}
async function detectLoopActivity(root) {
@@ -377,7 +398,7 @@ export async function auditProject(target) {
}
if (!signals.verifier.present) {
findings.push({ level: 'warn', message: 'No loop-verifier skill — maker/checker split incomplete.' });
- recommendations.push('Add verifier: .grok/skills/loop-verifier, .claude/agents/loop-verifier.md, or .codex/agents/verifier.toml');
+ recommendations.push('Add verifier: .grok/skills/loop-verifier, .claude/agents/loop-verifier.md, .codex/agents/verifier.toml, or a verifier agent in opencode.json');
}
else {
findings.push({ level: 'ok', message: 'Verifier skill present.' });
diff --git a/tools/loop-audit/dist/cli.js b/tools/loop-audit/dist/cli.js
index 58c54dd..5580adf 100644
--- a/tools/loop-audit/dist/cli.js
+++ b/tools/loop-audit/dist/cli.js
@@ -63,6 +63,9 @@ try {
console.log(' # Codex:');
console.log(' cp -r starters/minimal-loop-codex/.codex/skills/loop-triage .codex/skills/');
console.log(' cp starters/minimal-loop-codex/.codex/agents/verifier.toml .codex/agents/');
+ console.log(' # Opencode:');
+ console.log(' npx @cobusgreyling/loop-init . --pattern daily-triage --tool opencode');
+ console.log(' # or: cp starters/minimal-loop-opencode/opencode.json.example opencode.json');
console.log(' # All tools:');
console.log(' cp starters/minimal-loop/STATE.md.example STATE.md # or -claude / -codex variant');
console.log(' cp starters/minimal-loop/LOOP.md .');
diff --git a/tools/loop-audit/src/auditor.ts b/tools/loop-audit/src/auditor.ts
index 9c7b795..708d22d 100644
--- a/tools/loop-audit/src/auditor.ts
+++ b/tools/loop-audit/src/auditor.ts
@@ -146,6 +146,26 @@ async function findSkills(root: string): Promise<string[]> {
}
}
+ // Opencode named agents in opencode.json (or the starter example before rename)
+ for (const configName of ['opencode.json', 'opencode.json.example']) {
+ const configPath = path.join(root, configName);
+ if (!(await fileExists(configPath))) continue;
+ try {
+ const raw = await readFile(configPath, 'utf8');
+ const parsed = JSON.parse(raw) as { agent?: Record<string, { name?: string }> };
+ const agents = parsed.agent ?? {};
+ for (const [key, def] of Object.entries(agents)) {
+ const name = (def?.name ?? key).toLowerCase();
+ if (name.includes('verifier') || key.toLowerCase().includes('verifier')) {
+ found.push('loop-verifier');
+ break;
+ }
+ }
+ } catch {
+ // ignore invalid JSON
+ }
+ }
+
return found;
}
@@ -412,7 +432,7 @@ export async function auditProject(target: string): Promise<AuditResult> {
if (!signals.verifier.present) {
findings.push({ level: 'warn', message: 'No loop-verifier skill — maker/checker split incomplete.' });
- recommendations.push('Add verifier: .grok/skills/loop-verifier, .claude/agents/loop-verifier.md, or .codex/agents/verifier.toml');
+ recommendations.push('Add verifier: .grok/skills/loop-verifier, .claude/agents/loop-verifier.md, .codex/agents/verifier.toml, or a verifier agent in opencode.json');
} else {
findings.push({ level: 'ok', message: 'Verifier skill present.' });
}
diff --git a/tools/loop-audit/src/cli.ts b/tools/loop-audit/src/cli.ts
index b99e5e5..3d324f2 100644
--- a/tools/loop-audit/src/cli.ts
+++ b/tools/loop-audit/src/cli.ts
@@ -63,6 +63,9 @@ try {
console.log(' # Codex:');
console.log(' cp -r starters/minimal-loop-codex/.codex/skills/loop-triage .codex/skills/');
console.log(' cp starters/minimal-loop-codex/.codex/agents/verifier.toml .codex/agents/');
+ console.log(' # Opencode:');
+ console.log(' npx @cobusgreyling/loop-init . --pattern daily-triage --tool opencode');
+ console.log(' # or: cp starters/minimal-loop-opencode/opencode.json.example opencode.json');
console.log(' # All tools:');
console.log(' cp starters/minimal-loop/STATE.md.example STATE.md # or -claude / -codex variant');
console.log(' cp starters/minimal-loop/LOOP.md .');
diff --git a/tools/loop-audit/test/auditor.test.mjs b/tools/loop-audit/test/auditor.test.mjs
index bfed8e7..7aec307 100644
--- a/tools/loop-audit/test/auditor.test.mjs
+++ b/tools/loop-audit/test/auditor.test.mjs
@@ -187,4 +187,29 @@ test('auditProject: L2 with verifier skill', async () => {
} finally {
await rm(dir, { recursive: true, force: true });
}
+});
+
+test('auditProject: opencode.json verifier agent counts as loop-verifier', async () => {
+ const dir = await mkdtemp(path.join(tmpdir(), 'loop-audit-opencode-'));
+ try {
+ await writeFile(path.join(dir, 'STATE.md'), '# State\n');
+ await mkdir(path.join(dir, 'skills', 'loop-triage'), { recursive: true });
+ await writeFile(
+ path.join(dir, 'skills', 'loop-triage', 'SKILL.md'),
+ '---\nname: loop-triage\ndescription: triage\n---\n# Triage\n',
+ );
+ await writeFile(
+ path.join(dir, 'opencode.json.example'),
+ JSON.stringify({
+ agent: {
+ verifier: { name: 'verifier', description: 'Checker agent' },
+ },
+ }),
+ );
+ const result = await auditProject(dir);
+ assert.ok(result.signals.verifier.present);
+ assert.equal(result.level, 'L2');
+ } finally {
+ await rm(dir, { recursive: true, force: true });
+ }
});
\ No newline at end of file
diff --git a/tools/loop-init/dist/cli.js b/tools/loop-init/dist/cli.js
index 92c475b..91041e0 100644
--- a/tools/loop-init/dist/cli.js
+++ b/tools/loop-init/dist/cli.js
@@ -20,6 +20,7 @@ const TOOL_SUFFIX = {
grok: '',
claude: '-claude',
codex: '-codex',
+ opencode: '-opencode',
};
const L2_PATTERNS = new Set(['ci-sweeper', 'dependency-sweeper']);
const PATTERNS_NEEDING_FIX = new Set([
@@ -100,6 +101,7 @@ async function copyTemplateSkill(templatesRoot, templateFile, targetDir, tool, s
grok: path.join(targetDir, '.grok', 'skills', skillName, 'SKILL.md'),
claude: path.join(targetDir, '.claude', 'skills', skillName, 'SKILL.md'),
codex: path.join(targetDir, '.codex', 'skills', skillName, 'SKILL.md'),
+ opencode: path.join(targetDir, 'skills', skillName, 'SKILL.md'),
};
const dest = destByTool[tool];
if (await exists(dest))
@@ -111,6 +113,7 @@ async function copyTemplateVerifier(templatesRoot, targetDir, tool, dryRun) {
grok: path.join(targetDir, '.grok', 'skills', 'loop-verifier', 'SKILL.md'),
claude: path.join(targetDir, '.claude', 'agents', 'loop-verifier.md'),
codex: path.join(targetDir, '.codex', 'agents', 'verifier.toml'),
+ opencode: path.join(targetDir, 'skills', 'loop-verifier', 'SKILL.md'),
};
const dest = verifierPaths[tool];
if (await exists(dest))
@@ -215,42 +218,50 @@ async function copyFile(src, dest, dryRun) {
console.log(` copied: ${src} → ${dest}`);
return true;
}
+const OPENCODE_RUN = 'opencode run';
function firstLoopCommand(pattern, tool) {
const cmds = {
'daily-triage': {
grok: '/loop 1d Run loop-triage. Update STATE.md. No auto-fix in week one.',
claude: '/loop 1d $loop-triage — update STATE.md. Report-only week one.',
codex: 'Automation daily: $loop-triage → update STATE.md. Report-only.',
+ opencode: `${OPENCODE_RUN} "Run loop-triage. Read STATE.md first. Update High Priority and Watch List. No auto-fix in week one." --agent loop-triage`,
},
'pr-babysitter': {
grok: '/loop 10m Run pr-review-triage. Update pr-babysitter-state.md. Worktree + minimal-fix + verifier for allowlisted PRs only. Escalate after 3 attempts.',
claude: '/loop 10m $pr-review-triage — update pr-babysitter-state.md. No auto-merge.',
codex: 'Automation 10m: pr-review-triage → pr-babysitter-state.md. No auto-merge.',
+ opencode: `${OPENCODE_RUN} "Run PR babysitter triage. Read pr-babysitter-state.md first. Report only — no code edits." --title "PR babysitter"`,
},
'ci-sweeper': {
grok: '/loop 15m Run ci-triage on failing CI. Update ci-sweeper-state.md. Fix only regressions in worktree. Max 3 attempts.',
claude: '/loop 15m $ci-triage — update ci-sweeper-state.md. Max 3 fix attempts.',
codex: 'Automation 15m: ci-triage on CI failures. Max 3 attempts.',
+ opencode: `${OPENCODE_RUN} "Run ci-triage on failing CI. Update ci-sweeper-state.md. Report only in week one."`,
},
'dependency-sweeper': {
grok: '/loop 6h Run dependency-triage. Patch-only auto-fix in worktree + verifier. Escalate majors and denylist.',
claude: '/loop 6h $dependency-triage — patch-only with verifier. Escalate risky bumps.',
codex: 'Automation 6h: dependency-triage. Patch-only with verifier.',
+ opencode: `${OPENCODE_RUN} "Run dependency-triage. Update dependency-sweeper-state.md. Report only — escalate majors."`,
},
'post-merge-cleanup': {
grok: '/loop 1d Run post-merge-scan on recent merges. Update post-merge-state.md. Small fixes only in worktree.',
claude: '/loop 1d $post-merge-scan — update post-merge-state.md. Small fixes only.',
codex: 'Automation daily: post-merge-scan → post-merge-state.md.',
+ opencode: `${OPENCODE_RUN} "Run post-merge-scan. Update post-merge-state.md. Report only in week one."`,
},
'changelog-drafter': {
grok: '/loop 1d Run changelog-scan on merges since last tag. Produce categorized draft in RELEASE_NOTES_DRAFT.md using draft-release-notes. Update changelog-drafter-state.md. Human review only.',
claude: '/loop 1d $changelog-scan + draft-release-notes — write RELEASE_NOTES_DRAFT.md and update state. Human approves before publish.',
codex: 'Automation daily: changelog-scan + draft-release-notes → RELEASE_NOTES_DRAFT.md. Human review.',
+ opencode: `${OPENCODE_RUN} "Run changelog-scan. Draft RELEASE_NOTES_DRAFT.md. Human review only — no publish."`,
},
'issue-triage': {
grok: '/loop 2h Run issue-triage. Update issue-triage-state.md. Propose labels and priority only. No auto-apply. Human reviews the needs-human slice.',
claude: '/loop 2h $issue-triage — update issue-triage-state.md. Suggest labels on allowlisted areas only. Report mode week one.',
codex: 'Automation 2h: issue-triage → issue-triage-state.md. Propose only.',
+ opencode: `${OPENCODE_RUN} "Run issue-triage. Update issue-triage-state.md. Propose labels only — no auto-apply."`,
},
};
return cmds[pattern][tool];
@@ -312,7 +323,7 @@ async function main() {
console.log(`loop-init — scaffold loop engineering starters
Usage:
- loop-init [target-dir] --pattern <name> --tool <grok|claude|codex>
+ loop-init [target-dir] --pattern <name> --tool <grok|claude|codex|opencode>
Patterns:
daily-triage (default)
@@ -332,6 +343,7 @@ Options:
Examples:
npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok
npx @cobusgreyling/loop-init . -p pr-babysitter -t claude
+ npx @cobusgreyling/loop-init . -p daily-triage -t opencode
`);
process.exit(0);
}
@@ -365,33 +377,52 @@ Examples:
? starterRoot
: path.join(startersRoot, baseStarter);
console.log(`\nloop-init: ${pattern} → ${targetDir} (${tool})${dryRun ? ' [dry-run]' : ''}\n`);
- const skillRoots = [
- path.join(effectiveStarter, '.grok', 'skills'),
- path.join(effectiveStarter, '.claude', 'skills'),
- path.join(effectiveStarter, '.codex', 'skills'),
- ];
- for (const skillsDir of skillRoots) {
- if (!(await exists(skillsDir)))
- continue;
- const toolPrefix = skillsDir.includes('.grok')
- ? '.grok/skills'
- : skillsDir.includes('.claude')
- ? '.claude/skills'
- : '.codex/skills';
- const entries = await readDirNames(skillsDir);
- for (const entry of entries) {
- await copyDir(path.join(skillsDir, entry), path.join(targetDir, toolPrefix, entry), dryRun);
+ if (tool === 'opencode') {
+ const skillsDir = path.join(effectiveStarter, 'skills');
+ if (await exists(skillsDir)) {
+ const entries = await readDirNames(skillsDir);
+ for (const entry of entries) {
+ await copyDir(path.join(skillsDir, entry), path.join(targetDir, 'skills', entry), dryRun);
+ }
+ }
+ const agentsMd = path.join(effectiveStarter, 'AGENTS.md');
+ if (await exists(agentsMd)) {
+ await copyFile(agentsMd, path.join(targetDir, 'AGENTS.md'), dryRun);
+ }
+ const opencodeJson = path.join(effectiveStarter, 'opencode.json.example');
+ if (await exists(opencodeJson)) {
+ await copyFile(opencodeJson, path.join(targetDir, 'opencode.json'), dryRun);
}
}
- const agentFiles = [
- { src: path.join(effectiveStarter, '.claude', 'agents'), dest: path.join(targetDir, '.claude', 'agents') },
- { src: path.join(effectiveStarter, '.codex', 'agents'), dest: path.join(targetDir, '.codex', 'agents') },
- ];
- for (const { src, dest } of agentFiles) {
- if (await exists(src)) {
- const entries = await readDirNames(src);
+ else {
+ const skillRoots = [
+ path.join(effectiveStarter, '.grok', 'skills'),
+ path.join(effectiveStarter, '.claude', 'skills'),
+ path.join(effectiveStarter, '.codex', 'skills'),
+ ];
+ for (const skillsDir of skillRoots) {
+ if (!(await exists(skillsDir)))
+ continue;
+ const toolPrefix = skillsDir.includes('.grok')
+ ? '.grok/skills'
+ : skillsDir.includes('.claude')
+ ? '.claude/skills'
+ : '.codex/skills';
+ const entries = await readDirNames(skillsDir);
for (const entry of entries) {
- await copyFile(path.join(src, entry), path.join(dest, entry), dryRun);
+ await copyDir(path.join(skillsDir, entry), path.join(targetDir, toolPrefix, entry), dryRun);
+ }
+ }
+ const agentFiles = [
+ { src: path.join(effectiveStarter, '.claude', 'agents'), dest: path.join(targetDir, '.claude', 'agents') },
+ { src: path.join(effectiveStarter, '.codex', 'agents'), dest: path.join(targetDir, '.codex', 'agents') },
+ ];
+ for (const { src, dest } of agentFiles) {
+ if (await exists(src)) {
+ const entries = await readDirNames(src);
+ for (const entry of entries) {
+ await copyFile(path.join(src, entry), path.join(dest, entry), dryRun);
+ }
}
}
}
@@ -413,7 +444,7 @@ Examples:
await copyL2Templates(pattern, tool, targetDir, templatesRoot, dryRun);
await scaffoldObservability(pattern, tool, targetDir, templatesRoot, dryRun);
await scaffoldConstraints(targetDir, templatesRoot, tool, dryRun);
- if (!dryRun && !(await exists(path.join(targetDir, 'AGENTS.md')))) {
+ if (tool !== 'opencode' && !dryRun && !(await exists(path.join(targetDir, 'AGENTS.md')))) {
const agentsTemplate = `# AGENTS.md
## Test commands
diff --git a/tools/loop-init/src/cli.ts b/tools/loop-init/src/cli.ts
index fcc5ee7..58d3c3e 100644
--- a/tools/loop-init/src/cli.ts
+++ b/tools/loop-init/src/cli.ts
@@ -18,7 +18,7 @@ type Pattern =
| 'changelog-drafter'
| 'issue-triage';
-type Tool = 'grok' | 'claude' | 'codex';
+type Tool = 'grok' | 'claude' | 'codex' | 'opencode';
const PATTERN_STARTERS: Record<Pattern, string> = {
'daily-triage': 'minimal-loop',
@@ -34,6 +34,7 @@ const TOOL_SUFFIX: Record<Tool, string> = {
grok: '',
claude: '-claude',
codex: '-codex',
+ opencode: '-opencode',
};
const L2_PATTERNS = new Set<Pattern>(['ci-sweeper', 'dependency-sweeper']);
@@ -127,6 +128,7 @@ async function copyTemplateSkill(
grok: path.join(targetDir, '.grok', 'skills', skillName, 'SKILL.md'),
claude: path.join(targetDir, '.claude', 'skills', skillName, 'SKILL.md'),
codex: path.join(targetDir, '.codex', 'skills', skillName, 'SKILL.md'),
+ opencode: path.join(targetDir, 'skills', skillName, 'SKILL.md'),
};
const dest = destByTool[tool];
if (await exists(dest)) return;
@@ -143,6 +145,7 @@ async function copyTemplateVerifier(
grok: path.join(targetDir, '.grok', 'skills', 'loop-verifier', 'SKILL.md'),
claude: path.join(targetDir, '.claude', 'agents', 'loop-verifier.md'),
codex: path.join(targetDir, '.codex', 'agents', 'verifier.toml'),
+ opencode: path.join(targetDir, 'skills', 'loop-verifier', 'SKILL.md'),
};
const dest = verifierPaths[tool];
if (await exists(dest)) return;
@@ -274,42 +277,51 @@ async function copyFile(src: string, dest: string, dryRun: boolean) {
return true;
}
+const OPENCODE_RUN = 'opencode run';
+
function firstLoopCommand(pattern: Pattern, tool: Tool): string {
const cmds: Record<Pattern, Record<Tool, string>> = {
'daily-triage': {
grok: '/loop 1d Run loop-triage. Update STATE.md. No auto-fix in week one.',
claude: '/loop 1d $loop-triage — update STATE.md. Report-only week one.',
codex: 'Automation daily: $loop-triage → update STATE.md. Report-only.',
+ opencode: `${OPENCODE_RUN} "Run loop-triage. Read STATE.md first. Update High Priority and Watch List. No auto-fix in week one." --agent loop-triage`,
},
'pr-babysitter': {
grok: '/loop 10m Run pr-review-triage. Update pr-babysitter-state.md. Worktree + minimal-fix + verifier for allowlisted PRs only. Escalate after 3 attempts.',
claude: '/loop 10m $pr-review-triage — update pr-babysitter-state.md. No auto-merge.',
codex: 'Automation 10m: pr-review-triage → pr-babysitter-state.md. No auto-merge.',
+ opencode: `${OPENCODE_RUN} "Run PR babysitter triage. Read pr-babysitter-state.md first. Report only — no code edits." --title "PR babysitter"`,
},
'ci-sweeper': {
grok: '/loop 15m Run ci-triage on failing CI. Update ci-sweeper-state.md. Fix only regressions in worktree. Max 3 attempts.',
claude: '/loop 15m $ci-triage — update ci-sweeper-state.md. Max 3 fix attempts.',
codex: 'Automation 15m: ci-triage on CI failures. Max 3 attempts.',
+ opencode: `${OPENCODE_RUN} "Run ci-triage on failing CI. Update ci-sweeper-state.md. Report only in week one."`,
},
'dependency-sweeper': {
grok: '/loop 6h Run dependency-triage. Patch-only auto-fix in worktree + verifier. Escalate majors and denylist.',
claude: '/loop 6h $dependency-triage — patch-only with verifier. Escalate risky bumps.',
codex: 'Automation 6h: dependency-triage. Patch-only with verifier.',
+ opencode: `${OPENCODE_RUN} "Run dependency-triage. Update dependency-sweeper-state.md. Report only — escalate majors."`,
},
'post-merge-cleanup': {
grok: '/loop 1d Run post-merge-scan on recent merges. Update post-merge-state.md. Small fixes only in worktree.',
claude: '/loop 1d $post-merge-scan — update post-merge-state.md. Small fixes only.',
codex: 'Automation daily: post-merge-scan → post-merge-state.md.',
+ opencode: `${OPENCODE_RUN} "Run post-merge-scan. Update post-merge-state.md. Report only in week one."`,
},
'changelog-drafter': {
grok: '/loop 1d Run changelog-scan on merges since last tag. Produce categorized draft in RELEASE_NOTES_DRAFT.md using draft-release-notes. Update changelog-drafter-state.md. Human review only.',
claude: '/loop 1d $changelog-scan + draft-release-notes — write RELEASE_NOTES_DRAFT.md and update state. Human approves before publish.',
codex: 'Automation daily: changelog-scan + draft-release-notes → RELEASE_NOTES_DRAFT.md. Human review.',
+ opencode: `${OPENCODE_RUN} "Run changelog-scan. Draft RELEASE_NOTES_DRAFT.md. Human review only — no publish."`,
},
'issue-triage': {
grok: '/loop 2h Run issue-triage. Update issue-triage-state.md. Propose labels and priority only. No auto-apply. Human reviews the needs-human slice.',
claude: '/loop 2h $issue-triage — update issue-triage-state.md. Suggest labels on allowlisted areas only. Report mode week one.',
codex: 'Automation 2h: issue-triage → issue-triage-state.md. Propose only.',
+ opencode: `${OPENCODE_RUN} "Run issue-triage. Update issue-triage-state.md. Propose labels only — no auto-apply."`,
},
};
return cmds[pattern][tool];
@@ -374,7 +386,7 @@ async function main() {
console.log(`loop-init — scaffold loop engineering starters
Usage:
- loop-init [target-dir] --pattern <name> --tool <grok|claude|codex>
+ loop-init [target-dir] --pattern <name> --tool <grok|claude|codex|opencode>
Patterns:
daily-triage (default)
@@ -394,6 +406,7 @@ Options:
Examples:
npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok
npx @cobusgreyling/loop-init . -p pr-babysitter -t claude
+ npx @cobusgreyling/loop-init . -p daily-triage -t opencode
`);
process.exit(0);
}
@@ -434,38 +447,62 @@ Examples:
console.log(`\nloop-init: ${pattern} → ${targetDir} (${tool})${dryRun ? ' [dry-run]' : ''}\n`);
- const skillRoots = [
- path.join(effectiveStarter, '.grok', 'skills'),
- path.join(effectiveStarter, '.claude', 'skills'),
- path.join(effectiveStarter, '.codex', 'skills'),
- ];
-
- for (const skillsDir of skillRoots) {
- if (!(await exists(skillsDir))) continue;
- const toolPrefix = skillsDir.includes('.grok')
- ? '.grok/skills'
- : skillsDir.includes('.claude')
- ? '.claude/skills'
- : '.codex/skills';
- const entries = await readDirNames(skillsDir);
- for (const entry of entries) {
- await copyDir(
- path.join(skillsDir, entry),
- path.join(targetDir, toolPrefix, entry),
- dryRun,
- );
+ if (tool === 'opencode') {
+ const skillsDir = path.join(effectiveStarter, 'skills');
+ if (await exists(skillsDir)) {
+ const entries = await readDirNames(skillsDir);
+ for (const entry of entries) {
+ await copyDir(
+ path.join(skillsDir, entry),
+ path.join(targetDir, 'skills', entry),
+ dryRun,
+ );
+ }
+ }
+
+ const agentsMd = path.join(effectiveStarter, 'AGENTS.md');
+ if (await exists(agentsMd)) {
+ await copyFile(agentsMd, path.join(targetDir, 'AGENTS.md'), dryRun);
}
- }
- const agentFiles = [
- { src: path.join(effectiveStarter, '.claude', 'agents'), dest: path.join(targetDir, '.claude', 'agents') },
- { src: path.join(effectiveStarter, '.codex', 'agents'), dest: path.join(targetDir, '.codex', 'agents') },
- ];
- for (const { src, dest } of agentFiles) {
- if (await exists(src)) {
- const entries = await readDirNames(src);
+ const opencodeJson = path.join(effectiveStarter, 'opencode.json.example');
+ if (await exists(opencodeJson)) {
+ await copyFile(opencodeJson, path.join(targetDir, 'opencode.json'), dryRun);
+ }
+ } else {
+ const skillRoots = [
+ path.join(effectiveStarter, '.grok', 'skills'),
+ path.join(effectiveStarter, '.claude', 'skills'),
+ path.join(effectiveStarter, '.codex', 'skills'),
+ ];
+
+ for (const skillsDir of skillRoots) {
+ if (!(await exists(skillsDir))) continue;
+ const toolPrefix = skillsDir.includes('.grok')
+ ? '.grok/skills'
+ : skillsDir.includes('.claude')
+ ? '.claude/skills'
+ : '.codex/skills';
+ const entries = await readDirNames(skillsDir);
for (const entry of entries) {
- await copyFile(path.join(src, entry), path.join(dest, entry), dryRun);
+ await copyDir(
+ path.join(skillsDir, entry),
+ path.join(targetDir, toolPrefix, entry),
+ dryRun,
+ );
+ }
+ }
+
+ const agentFiles = [
+ { src: path.join(effectiveStarter, '.claude', 'agents'), dest: path.join(targetDir, '.claude', 'agents') },
+ { src: path.join(effectiveStarter, '.codex', 'agents'), dest: path.join(targetDir, '.codex', 'agents') },
+ ];
+ for (const { src, dest } of agentFiles) {
+ if (await exists(src)) {
+ const entries = await readDirNames(src);
+ for (const entry of entries) {
+ await copyFile(path.join(src, entry), path.join(dest, entry), dryRun);
+ }
}
}
}
@@ -490,7 +527,7 @@ Examples:
await scaffoldObservability(pattern, tool, targetDir, templatesRoot, dryRun);
await scaffoldConstraints(targetDir, templatesRoot, tool, dryRun);
- if (!dryRun && !(await exists(path.join(targetDir, 'AGENTS.md')))) {
+ if (tool !== 'opencode' && !dryRun && !(await exists(path.join(targetDir, 'AGENTS.md')))) {
const agentsTemplate = `# AGENTS.md
## Test commands
diff --git a/tools/loop-init/test/cli.test.mjs b/tools/loop-init/test/cli.test.mjs
index 87923b0..914ed6a 100644
--- a/tools/loop-init/test/cli.test.mjs
+++ b/tools/loop-init/test/cli.test.mjs
@@ -22,6 +22,7 @@ test('bundle-assets tolerates concurrent rebuilds', async () => {
test('loop-init --help exits 0', async () => {
const { stdout } = await exec('node', [CLI, '--help']);
assert.match(stdout, /changelog-drafter/);
+ assert.match(stdout, /opencode/);
});
test('loop-init dry-run scaffolds daily-triage', async () => {
@@ -90,6 +91,22 @@ test('loop-init rejects unknown tool', async () => {
);
});
+test('loop-init scaffolds daily-triage for opencode', async () => {
+ const dir = await mkdtemp(path.join(tmpdir(), 'loop-init-opencode-'));
+ try {
+ await exec('node', [CLI, dir, '--pattern', 'daily-triage', '--tool', 'opencode']);
+ await access(path.join(dir, 'STATE.md'));
+ await access(path.join(dir, 'LOOP.md'));
+ await access(path.join(dir, 'AGENTS.md'));
+ await access(path.join(dir, 'opencode.json'));
+ await access(path.join(dir, 'skills', 'loop-triage', 'SKILL.md'));
+ await access(path.join(dir, 'loop-budget.md'));
+ await access(path.join(dir, 'loop-run-log.md'));
+ } finally {
+ await rm(dir, { recursive: true, force: true });
+ }
+});
+
test('loop-init scaffolds ci-sweeper with bundled assets', async () => {
const dir = await mkdtemp(path.join(tmpdir(), 'loop-init-'));
try {