opencodekit 0.15.10 → 0.15.11

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;

package/dist/template/.opencode/skill/swarm-coordination/SKILL.md

@@ -0,0 +1,405 @@
+---
+name: swarm-coordination
+description: >
+  Use when implementing plans with multiple independent tasks that can run in parallel.
+  Enables leader agents to spawn, coordinate, and monitor worker swarms. Covers delegation
+  packets, mailbox communication, task assignment, and graceful shutdown patterns.
+version: "1.0.0"
+license: MIT
+---
+
+# Swarm Coordination - Multi-Agent Parallel Execution
+
+Coordinate multiple agents working on independent tasks in parallel. Leader orchestrates, workers execute, mailbox communicates.
+
+## Overview
+
+**Swarm = Leader + Workers + Mailbox**
+
+- **Leader (build agent)**: Orchestrates the swarm - spawns workers, monitors progress, synthesizes results
+- **Workers (general agents)**: Execute independent tasks - read delegation, make changes, report back
+- **Mailbox (swarm-mail.jsonl)**: Append-only log for coordination messages
+
+**Key Distinction**:
+
+- **Swarm**: Parallel execution of independent tasks from a plan
+- **Beads**: Task tracking and dependency management across sessions
+- **Task tool**: Spawning individual subagents for research/execution
+
+**When to Use Swarm Coordination**:
+
+- "Does this plan have 3+ independent tasks?" → **YES** = Swarm
+- "Can multiple tasks run in parallel without conflicts?" → **YES** = Swarm
+- "Do I need to coordinate multiple agents?" → **YES** = Swarm
+- "Is this a single task or sequential dependency chain?" → **NO** = Single agent
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         BUILD AGENT (Leader)                     │
+│  - Parses plan into tasks                                        │
+│  - Creates delegation packets                                    │
+│  - Spawns worker agents via Task tool                            │
+│  - Monitors mailbox for progress                                 │
+│  - Synthesizes final results                                     │
+└─────────────────────────────────────────────────────────────────┘
+         │                    │                    │
+         ▼                    ▼                    ▼
+┌─────────────┐      ┌─────────────┐      ┌─────────────┐
+│  WORKER-1   │      │  WORKER-2   │      │  WORKER-3   │
+│  (general)  │      │  (general)  │      │  (general)  │
+│             │      │             │      │             │
+│ - Read      │      │ - Read      │      │ - Read      │
+│   delegation│      │   delegation│      │   delegation│
+│ - Execute   │      │ - Execute   │      │ - Execute   │
+│ - Report    │      │ - Report    │      │ - Report    │
+└─────────────┘      └─────────────┘      └─────────────┘
+         │                    │                    │
+         └────────────────────┼────────────────────┘
+                              ▼
+                    ┌─────────────────┐
+                    │  SWARM MAILBOX  │
+                    │  (swarm-mail    │
+                    │   .jsonl)       │
+                    └─────────────────┘
+```
+
+## Swarm Launch Flow (5 Steps)
+
+### Step 1: Parse Plan into Tasks
+
+Extract independent tasks from the approved plan:
+
+```typescript
+// Read the plan
+const plan = read({ filePath: ".beads/artifacts/<bead-id>/plan.md" });
+
+// Identify parallelizable tasks
+// Tasks are parallel if they:
+// - Don't modify the same files
+// - Don't have sequential dependencies
+// - Can verify independently
+```
+
+### Step 2: Create Delegation Packets
+
+For each task, create a delegation packet:
+
+```typescript
+swarm_delegate({
+  bead_id: "task-1",
+  title: "Implement auth service",
+  expected_outcome: "Auth service with JWT tokens, tests pass",
+  required_tools: "read, grep, lsp, edit, bash",
+  must_do: "LSP before edits, run npm test after changes",
+  must_not_do: "No new dependencies, don't edit config files",
+  acceptance_checks: "typecheck: npm run typecheck, lint: npm run lint, test: npm test",
+  context: "See .beads/artifacts/task-1/spec.md for requirements",
+  write: true,
+});
+```
+
+### Step 3: Spawn Worker Agents
+
+Use Task tool to spawn workers in parallel:
+
+```typescript
+// Multiple Task calls in one message run simultaneously
+Task({
+  subagent_type: "general",
+  description: "Execute task-1",
+  prompt: `Execute bead task-1: Implement auth service
+
+Read delegation packet at: .beads/artifacts/task-1/delegation.md
+
+Requirements:
+1. Follow all MUST DO constraints
+2. Avoid all MUST NOT DO items
+3. Run acceptance checks before claiming done
+4. Report completion via swarm-helper sendTeamMessage
+
+Team: plan-implementation
+Worker: worker-1`,
+});
+
+Task({
+  subagent_type: "general",
+  description: "Execute task-2",
+  prompt: `Execute bead task-2: Add user routes
+...same pattern...`,
+});
+
+Task({
+  subagent_type: "general",
+  description: "Execute task-3",
+  prompt: `Execute bead task-3: Create frontend forms
+...same pattern...`,
+});
+// All three run in parallel
+```
+
+### Step 4: Monitor Progress
+
+Check mailbox for worker reports:
+
+```typescript
+swarm_helper({
+  operation: "getTeamStatus",
+  team_name: "plan-implementation",
+  limit: 20,
+});
+// Returns messages from workers about progress
+```
+
+### Step 5: Synthesize Results
+
+When all workers complete:
+
+1. Read their completion messages from mailbox
+2. Verify all acceptance checks passed
+3. Run full test suite
+4. Summarize what was accomplished
+5. Close the parent bead
+
+## Delegation Packet Structure
+
+```markdown
+# Delegation Packet
+
+- TASK: task-1 - Implement auth service
+- EXPECTED OUTCOME: Auth service with JWT tokens, tests pass
+- REQUIRED TOOLS:
+  - read
+  - grep
+  - lsp
+  - edit
+  - bash
+- MUST DO:
+  - LSP before edits
+  - Run npm test after changes
+  - Follow existing code patterns
+- MUST NOT DO:
+  - No new dependencies
+  - Don't edit config files
+  - Don't modify shared utilities
+- ACCEPTANCE CHECKS:
+  - typecheck: npm run typecheck
+  - lint: npm run lint
+  - test: npm test
+- CONTEXT:
+  See .beads/artifacts/task-1/spec.md for requirements
+```
+
+## Worker Protocol
+
+Workers follow this execution pattern:
+
+### 1. Read Delegation
+
+```typescript
+// First action: read the delegation packet
+read({ filePath: ".beads/artifacts/<task-id>/delegation.md" });
+```
+
+### 2. Announce Start
+
+```typescript
+swarm_helper({
+  operation: "sendTeamMessage",
+  team_name: "plan-implementation",
+  from_worker: "worker-1",
+  to_worker: "leader",
+  message: "Starting: <task-title>",
+});
+```
+
+### 3. Execute Task
+
+Follow the MUST DO constraints. Avoid MUST NOT DO items. Use required tools only.
+
+### 4. Run Acceptance Checks
+
+```bash
+# Run each check from the delegation packet
+npm run typecheck
+npm run lint
+npm test
+```
+
+### 5. Report Completion
+
+```typescript
+swarm_helper({
+  operation: "sendTeamMessage",
+  team_name: "plan-implementation",
+  from_worker: "worker-1",
+  to_worker: "leader",
+  message: "DONE: <task-title>. All checks passed. Changes: <summary>",
+});
+```
+
+## Mailbox Message Format
+
+Messages in `.beads/swarm-mail.jsonl`:
+
+```json
+{
+  "timestamp": "2025-01-27T10:30:00.000Z",
+  "team_name": "plan-implementation",
+  "from_worker": "worker-1",
+  "to_worker": "leader",
+  "message": "DONE: Implement auth service. All checks passed.",
+  "status": "unread"
+}
+```
+
+### Message Types
+
+| Type     | From   | To       | Purpose                     |
+| -------- | ------ | -------- | --------------------------- |
+| START    | worker | leader   | Worker beginning task       |
+| PROGRESS | worker | leader   | Intermediate update         |
+| BLOCKED  | worker | leader   | Worker needs help           |
+| DONE     | worker | leader   | Task completed successfully |
+| ERROR    | worker | leader   | Task failed                 |
+| HELP     | worker | worker-N | Request assistance          |
+| ASSIGN   | leader | worker   | New task assignment         |
+| SHUTDOWN | leader | all      | Graceful shutdown signal    |
+
+## Conflict Prevention
+
+### File Reservation
+
+Before workers start, leader reserves files:
+
+```typescript
+// Reserve files for each worker
+bd_reserve({
+  paths: ["src/auth/service.ts", "src/auth/types.ts"],
+  reason: "worker-1: auth service implementation",
+});
+```
+
+### Non-Overlapping Assignments
+
+Ensure workers don't edit same files:
+
+| Worker   | Assigned Files          |
+| -------- | ----------------------- |
+| worker-1 | src/auth/\*             |
+| worker-2 | src/routes/user/\*      |
+| worker-3 | src/components/forms/\* |
+
+## Error Handling
+
+### Worker Fails Acceptance Checks
+
+```typescript
+// Worker sends error message
+swarm_helper({
+  operation: "sendTeamMessage",
+  team_name: "plan-implementation",
+  from_worker: "worker-1",
+  to_worker: "leader",
+  message: "ERROR: typecheck failed. Issue: missing type for AuthToken",
+});
+```
+
+### Leader Response
+
+1. Read error from mailbox
+2. Decide: fix locally or reassign
+3. Either spawn fix-agent or adjust task
+
+### Worker Gets Blocked
+
+```typescript
+// Worker asks for help
+swarm_helper({
+  operation: "sendTeamMessage",
+  team_name: "plan-implementation",
+  from_worker: "worker-2",
+  to_worker: "leader",
+  message: "BLOCKED: Need auth service types. Waiting on worker-1.",
+});
+```
+
+## Graceful Shutdown
+
+Leader signals completion:
+
+```typescript
+// After all workers done
+swarm_helper({
+  operation: "sendTeamMessage",
+  team_name: "plan-implementation",
+  from_worker: "leader",
+  to_worker: "all",
+  message: "SHUTDOWN: All tasks complete. Final verification passed.",
+});
+```
+
+## When to Use Swarm vs Single Agent
+
+| Scenario                      | Approach     |
+| ----------------------------- | ------------ |
+| 1-2 file changes              | Single agent |
+| Sequential dependencies       | Single agent |
+| 3+ independent parallel tasks | Swarm        |
+| Cross-domain work (FE/BE/DB)  | Swarm        |
+| Time-sensitive parallel work  | Swarm        |
+
+## Integration with Beads
+
+Swarm works on top of Beads:
+
+1. **Plan creates beads** for each task
+2. **Leader claims parent** bead
+3. **Workers claim child** beads
+4. **Completion closes** beads via `bd_done()`
+
+```typescript
+// Leader workflow
+bd_claim(); // Gets parent task
+// ... spawn swarm ...
+// ... monitor completion ...
+bd_done({ id: "parent-task", msg: "Swarm completed all subtasks" });
+```
+
+## Quick Reference
+
+```
+SWARM LAUNCH:
+  1. Parse plan → identify parallel tasks
+  2. Create delegation packets (swarm-delegate)
+  3. Spawn workers (Task tool, multiple in one message)
+  4. Monitor mailbox (swarm-helper getTeamStatus)
+  5. Synthesize results
+
+WORKER EXECUTION:
+  1. Read delegation packet
+  2. Announce start via mailbox
+  3. Execute with constraints
+  4. Run acceptance checks
+  5. Report completion via mailbox
+
+COORDINATION:
+  - Mailbox: .beads/swarm-mail.jsonl
+  - Delegation: .beads/artifacts/<id>/delegation.md
+  - File locks: bd_reserve() before spawning
+
+SHUTDOWN:
+  - All workers done → leader sends SHUTDOWN
+  - Run full test suite
+  - Close parent bead
+```
+
+## Rules
+
+1. **Leader spawns, workers execute** - Clear role separation
+2. **Delegation packets are contracts** - Workers follow them strictly
+3. **Mailbox for coordination** - All communication through swarm-mail
+4. **No file conflicts** - Reserve before spawning workers
+5. **Acceptance checks required** - Workers verify before reporting done
+6. **Graceful shutdown** - Leader waits for all workers, then shuts down