opencodekit 0.15.9 → 0.15.11

package/dist/template/.opencode/package.json

@@ -11,7 +11,7 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
-    "@opencode-ai/plugin": "1.1.31"
+    "@opencode-ai/plugin": "1.1.36"
   },
   "devDependencies": {
     "@types/node": "^25.0.3",

package/dist/template/.opencode/plans/swarm-protocol.md

@@ -0,0 +1,123 @@
+# Swarm Protocol (Beads-as-Board)
+
+## Goal
+
+Use `.beads/` as the single source of truth for task state + dependencies, while agents coordinate through structured artifacts (not freeform chatter) and verification gates.
+
+## Roles (Strict)
+
+- Lead: Owns scope, prioritization, and all Beads state transitions.
+- Planner: Turns intent into Beads tasks + dependency DAG; no code changes.
+- Worker: Executes exactly one claimed task; posts a structured report.
+- Verifier: Independently validates acceptance checks; blocks close on missing evidence.
+
+## Board = Beads
+
+Canonical state lives in `.beads/issues.jsonl` (tasks) and `.beads/artifacts/<id>/` (task artifacts).
+
+- Create tasks: `bd create "Title" -p <1-3>`
+- See unblocked work: `bd ready`
+- Inspect context: `bd show <id>`
+- Claim work: `bd update <id> --status=in_progress`
+- Close work: `bd close <id> --reason="..."` then `bd sync`
+
+## Task Artifact Contract
+
+Every task MUST have `.beads/artifacts/<id>/spec.md`.
+
+Optional supporting files:
+
+- `.beads/artifacts/<id>/plan.md`: multi-step implementation plan, files touched, and gates
+- `.beads/artifacts/<id>/review.md`: verifier notes + evidence summary
+
+### spec.md (Minimum Template)
+
+- Context: why this exists
+- Scope: in / out
+- Constraints: MUST / MUST NOT (security, deps, dist/, etc.)
+- Acceptance Criteria: checkboxes, each with a verification method
+- Evidence Required: exact commands and expected signals (e.g. "typecheck command passes")
+
+#### Verification Defaults (Language-Agnostic)
+
+Do NOT assume npm/bun/pytest/etc. Prefer this pattern:
+
+- `typecheck`: `<command>`
+- `lint`: `<command>`
+- `test`: `<command>`
+- `build` (optional): `<command>`
+
+If the repository has a canonical list of commands, reference it (e.g. `.opencode/memory/project/commands.md`).
+
+Common stacks (examples only):
+
+| Stack   | typecheck                                  | lint                         | test                     |
+| ------- | ------------------------------------------ | ---------------------------- | ------------------------ |
+| Node/TS | `npm run typecheck` or `bun run typecheck` | `npm run lint`               | `bun test` or `npm test` |
+| Python  | `python -m mypy .`                         | `ruff check .`               | `pytest`                 |
+| Go      | `go test ./...` (compile+test)             | `golangci-lint run`          | `go test ./...`          |
+| Rust    | `cargo check`                              | `cargo fmt --check` (format) | `cargo test`             |
+
+## Delegation Packet (Worker Input)
+
+Every delegated task MUST include the following envelope:
+
+- TASK: `<id> - <title>`
+- EXPECTED OUTCOME: measurable end state
+- REQUIRED TOOLS: e.g. `read`, `grep`, `lsp`, `bash`
+- MUST DO: e.g. LSP-before-edits, run typecheck, run lint
+- MUST NOT DO: e.g. no new deps, no dist/ edits, no git push
+- ACCEPTANCE CHECKS: list of commands + pass criteria
+- CONTEXT: links to `.beads/artifacts/<id>/spec.md` + relevant files
+
+### Helper Tool
+
+If available, use the custom tool `swarm-delegate` to generate (and optionally write) a delegation packet:
+
+```ts
+swarm -
+  delegate({
+    bead_id: "opencodekit-template-xyz",
+    expected_outcome: "<measurable end state>",
+    required_tools: "read, grep, lsp, bash",
+    must_do: "LSP before edits, run project verification commands",
+    must_not_do: "no new deps, don't edit dist/",
+    acceptance_checks: "typecheck: <command>, lint: <command>, test: <command>",
+    context: "See .beads/artifacts/<id>/spec.md",
+    write: true,
+  });
+```
+
+## Worker Report (Worker Output)
+
+Workers MUST respond with a structured report:
+
+- Result: done / blocked / needs replan
+- Changes: file list + what changed (with file references)
+- Verification: commands run + pass/fail summary
+- Risks/Notes: edge cases, follow-ups
+- Confidence: high / medium / low
+
+## Gates (Non-Negotiable)
+
+- Planning gate: `.beads/artifacts/<id>/spec.md` exists with acceptance criteria BEFORE implementation starts
+- Execution gate: worker provides verification evidence BEFORE close
+- Review gate (risk-based): verifier signs off in `review.md` BEFORE close
+
+## Replan Triggers
+
+Immediately stop execution and return to planning if:
+
+- Scope expands to 4+ files unexpectedly
+- Requirement ambiguity changes implementation choice
+- Two-strike tool failures
+- New dependency or `.opencode/` structure change would be needed
+
+## Lead Checklist
+
+1. `bd ready` -> pick task -> `bd show <id>`
+2. Ensure `.beads/artifacts/<id>/spec.md` has acceptance checks
+3. `bd update <id> --status=in_progress`
+4. Delegate with the packet format
+5. Require worker report + evidence
+6. `bd close <id> --reason="..."` + `bd sync`

package/dist/template/.opencode/plugin/README.md

@@ -80,6 +80,16 @@ Session 3: read_session("previous") → Tests (90k) → close
 - High-priority or in-progress TODOs → Inject continuation prompt
 - Low-priority pending TODOs → OS notification only (no forced continuation)
 
+### swarm-enforcer.ts
+
+**Swarm protocol guardrails (Beads-as-board)** - nudges agents to follow the Beads-first workflow.
+
+- Treats `.beads/` as the single source of truth for the swarm task board
+- If user expresses implementation intent and no task is `in_progress`, injects a nudge to use `bd ready/show/update`
+- If there are `in_progress` tasks but `.beads/artifacts/<id>/spec.md` is missing, nudges to create it before implementation
+- On `file.edited`, warns if code is being changed without a claimed task or with missing `spec.md`
+- On `session.idle`, reminds to `bd close` + `bd sync` when work is done
+
 ### notification.ts
 
 **Session completion alerts** - sends native notifications when AI finishes.

package/dist/template/.opencode/plugin/swarm-enforcer.ts

@@ -0,0 +1,297 @@
+/**
+ * Swarm Enforcer Plugin
+ *
+ * Beads is the single source of truth for the swarm board.
+ * This plugin nudges agents to:
+ * - Claim a Beads task before making code changes
+ * - Ensure `spec.md` exists for in-progress tasks
+ * - Close/sync in-progress work at session end
+ *
+ * This plugin is intentionally non-destructive: it never runs `bd update/close/sync`.
+ */
+
+import fsPromises from "node:fs/promises";
+import path from "node:path";
+import type { Plugin } from "@opencode-ai/plugin";
+
+type BeadsIssue = {
+	id: string;
+	title?: string;
+	status?: string;
+};
+
+const BEADS_DIR = ".beads";
+const ISSUES_FILE = "issues.jsonl";
+
+const CODE_EXTENSIONS = [
+	".ts",
+	".tsx",
+	".js",
+	".jsx",
+	".mjs",
+	".cjs",
+	".py",
+	".go",
+	".rs",
+	".java",
+	".c",
+	".cpp",
+	".h",
+	".hpp",
+];
+
+const WORK_INTENT_PATTERNS = [
+	/\b(implement|fix|refactor|add|remove|delete|update|change|modify|create|build)\b/i,
+	/\b(edit|patch)\b/i,
+];
+
+function looksLikeWorkIntent(text: string): boolean {
+	return WORK_INTENT_PATTERNS.some((p) => p.test(text));
+}
+
+function isCodeFile(filePath: string): boolean {
+	return CODE_EXTENSIONS.some((ext) => filePath.endsWith(ext));
+}
+
+function isIgnoredPath(repoDir: string, filePath: string): boolean {
+	const absPath = path.isAbsolute(filePath)
+		? filePath
+		: path.join(repoDir, filePath);
+	const rel = path.relative(repoDir, absPath);
+
+	// Outside repo: ignore
+	if (rel.startsWith("..")) return true;
+
+	const normalized = rel.replace(/\\/g, "/");
+	return (
+		normalized.startsWith("node_modules/") ||
+		normalized.startsWith("dist/") ||
+		normalized.startsWith(".beads/") ||
+		normalized.startsWith(".git/")
+	);
+}
+
+function summarizeIssues(issues: BeadsIssue[], limit = 5): string {
+	return issues
+		.slice(0, limit)
+		.map((i) => `${i.id}${i.title ? `: ${i.title}` : ""}`)
+		.join("\n");
+}
+
+async function readIssuesJsonl(repoDir: string): Promise<BeadsIssue[]> {
+	const issuesPath = path.join(repoDir, BEADS_DIR, ISSUES_FILE);
+
+	let content: string;
+	try {
+		content = await fsPromises.readFile(issuesPath, "utf-8");
+	} catch {
+		return [];
+	}
+
+	const issues: BeadsIssue[] = [];
+	const lines = content.split(/\r?\n/);
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		try {
+			const parsed = JSON.parse(trimmed);
+			if (parsed && typeof parsed.id === "string") {
+				issues.push({
+					id: parsed.id,
+					title: typeof parsed.title === "string" ? parsed.title : undefined,
+					status: typeof parsed.status === "string" ? parsed.status : undefined,
+				});
+			}
+		} catch {
+			// Ignore malformed JSONL lines
+		}
+	}
+
+	return issues;
+}
+
+async function specExists(repoDir: string, issueId: string): Promise<boolean> {
+	const specPath = path.join(
+		repoDir,
+		BEADS_DIR,
+		"artifacts",
+		issueId,
+		"spec.md",
+	);
+	try {
+		await fsPromises.access(specPath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function buildNudge(params: {
+	inProgress: BeadsIssue[];
+	missingSpec: BeadsIssue[];
+}): string {
+	const { inProgress, missingSpec } = params;
+
+	if (inProgress.length === 0) {
+		return `
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚡ [SWARM PROTOCOL]
+
+Beads is the swarm board. Before any code changes:
+
+1) Pick a task: \`bd ready\` (or \`bd list\`)
+2) Inspect: \`bd show <id>\`
+3) Claim: \`bd update <id> --status=in_progress\`
+
+Then proceed with work and collect verification evidence.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`;
+	}
+
+	if (missingSpec.length > 0) {
+		return `
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚡ [SWARM PROTOCOL]
+
+In-progress Beads exist, but \`spec.md\` is missing for:
+
+${summarizeIssues(missingSpec)}
+
+Create \`.beads/artifacts/<id>/spec.md\` before implementation.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`;
+	}
+
+	return "";
+}
+
+export const SwarmEnforcer: Plugin = async ({ client, directory }) => {
+	const repoDir = directory || process.cwd();
+	let lastStateAt = 0;
+	let cachedInProgress: BeadsIssue[] = [];
+	let cachedMissingSpec: BeadsIssue[] = [];
+
+	const refreshState = async () => {
+		const now = Date.now();
+		if (now - lastStateAt < 1500) return;
+		lastStateAt = now;
+
+		const issues = await readIssuesJsonl(repoDir);
+		const inProgress = issues.filter((i) => i.status === "in_progress");
+
+		const missingSpec: BeadsIssue[] = [];
+		for (const issue of inProgress.slice(0, 10)) {
+			if (!(await specExists(repoDir, issue.id))) {
+				missingSpec.push(issue);
+			}
+		}
+
+		cachedInProgress = inProgress;
+		cachedMissingSpec = missingSpec;
+	};
+
+	const showToast = async (
+		title: string,
+		message: string,
+		variant: "info" | "success" | "warning" | "error" = "info",
+	) => {
+		try {
+			await client.tui.showToast({
+				body: {
+					title,
+					message,
+					variant,
+					duration: variant === "error" ? 8000 : 5000,
+				},
+			});
+		} catch {
+			// If toast is unavailable, fail silently
+		}
+	};
+
+	return {
+		// Nudge early when user expresses implementation intent
+		"chat.message": async (input, output) => {
+			const { sessionID, messageID } = input;
+			const { message, parts } = output;
+			if (message.role !== "user") return;
+
+			const fullText = parts
+				.filter((p) => p.type === "text" && !("synthetic" in p && p.synthetic))
+				.map((p) => ("text" in p ? p.text : ""))
+				.join(" ");
+
+			if (!looksLikeWorkIntent(fullText)) return;
+
+			await refreshState();
+
+			const nudge = buildNudge({
+				inProgress: cachedInProgress,
+				missingSpec: cachedMissingSpec,
+			});
+			if (!nudge) return;
+
+			parts.push({
+				id: `swarm-nudge-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+				sessionID,
+				messageID: messageID || "",
+				type: "text",
+				text: nudge,
+				synthetic: true,
+			} as import("@opencode-ai/sdk").Part);
+		},
+
+		// Warn if code gets edited while no task is claimed / spec missing
+		"file.edited": async ({ event }) => {
+			const filePath = event.properties?.file || event.properties?.path;
+			if (!filePath || typeof filePath !== "string") return;
+			if (isIgnoredPath(repoDir, filePath)) return;
+
+			const absPath = path.isAbsolute(filePath)
+				? filePath
+				: path.join(repoDir, filePath);
+
+			if (!isCodeFile(absPath)) return;
+
+			await refreshState();
+
+			if (cachedInProgress.length === 0) {
+				await showToast(
+					"Swarm: No task claimed",
+					"Beads is the board. Claim a task before code edits (bd ready/show/update).",
+					"warning",
+				);
+				return;
+			}
+
+			if (cachedMissingSpec.length > 0) {
+				await showToast(
+					"Swarm: Missing spec.md",
+					`Create .beads/artifacts/<id>/spec.md for: ${cachedMissingSpec
+						.slice(0, 3)
+						.map((i) => i.id)
+						.join(", ")}`,
+					"warning",
+				);
+			}
+		},
+
+		// Session end reminder: close/sync if tasks still in progress
+		"session.idle": async () => {
+			await refreshState();
+			if (cachedInProgress.length === 0) return;
+
+			const list = cachedInProgress
+				.slice(0, 5)
+				.map((i) => i.id)
+				.join(", ");
+			await showToast(
+				"Swarm: Work still in progress",
+				`In-progress Beads: ${list}. Close with bd close + bd sync when done.`,
+				"info",
+			);
+		},
+	};
+};
+
+export default SwarmEnforcer;