opencodekit 0.15.10 → 0.15.12

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

package/dist/template/.opencode/tool/swarm-delegate.ts

@@ -0,0 +1,175 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { tool } from "@opencode-ai/plugin";
+
+function isSafePathSegment(value: string): boolean {
+	if (!value) return false;
+	if (value.includes("..")) return false;
+	if (value.includes("/")) return false;
+	if (value.includes("\\")) return false;
+	return true;
+}
+
+function sanitizeFilename(value: string): string {
+	const trimmed = value.trim();
+	if (!trimmed) return "delegation.md";
+	if (!isSafePathSegment(trimmed)) return "delegation.md";
+	return trimmed;
+}
+
+function splitList(input?: string): string[] {
+	if (!input) return [];
+	const parts = input
+		.split(/\r?\n|,/g)
+		.map((s) => s.trim())
+		.filter(Boolean);
+	return [...new Set(parts)];
+}
+
+function formatBullets(items: string[]): string {
+	if (items.length === 0) return "- (none)";
+	return items.map((i) => `- ${i}`).join("\n");
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+	try {
+		await fs.access(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export default tool({
+	description: `Generate a Swarm delegation packet (Beads-as-board).
+
+Purpose:
+- Creates a consistent delegation envelope for a specific Beads task
+- Optionally appends it to .beads/artifacts/<id>/delegation.md
+
+Example:
+swarm-delegate({
+  bead_id: "opencodekit-template-xyz",
+  title: "Add feature X",
+  expected_outcome: "Feature X works and tests pass",
+  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
+})`,
+	args: {
+		bead_id: tool.schema
+			.string()
+			.describe("Beads issue id (e.g., opencodekit-template-abc)"),
+		title: tool.schema
+			.string()
+			.optional()
+			.describe("Optional title (defaults to Beads id only)"),
+		expected_outcome: tool.schema
+			.string()
+			.describe("Measurable end state for this task"),
+		required_tools: tool.schema
+			.string()
+			.optional()
+			.describe("Comma/newline-separated list of tools"),
+		must_do: tool.schema
+			.string()
+			.optional()
+			.describe("Comma/newline-separated MUST DO list"),
+		must_not_do: tool.schema
+			.string()
+			.optional()
+			.describe("Comma/newline-separated MUST NOT DO list"),
+		acceptance_checks: tool.schema
+			.string()
+			.optional()
+			.describe(
+				"Comma/newline-separated checks (prefer 'typecheck: <command>', 'lint: <command>', 'test: <command>')",
+			),
+		context: tool.schema
+			.string()
+			.optional()
+			.describe("Extra context pointers (files/links/notes)"),
+		write: tool.schema
+			.boolean()
+			.optional()
+			.describe("When true, append packet to task artifact file"),
+		output_file: tool.schema
+			.string()
+			.optional()
+			.describe(
+				"Artifact filename under .beads/artifacts/<id>/ (default: delegation.md)",
+			),
+	},
+	execute: async (args: {
+		bead_id: string;
+		title?: string;
+		expected_outcome: string;
+		required_tools?: string;
+		must_do?: string;
+		must_not_do?: string;
+		acceptance_checks?: string;
+		context?: string;
+		write?: boolean;
+		output_file?: string;
+	}) => {
+		const beadId = args.bead_id.trim();
+		if (!beadId) return "Error: bead_id is required.";
+		if (!isSafePathSegment(beadId)) {
+			return "Error: bead_id must be a single path segment (no slashes or '..').";
+		}
+
+		const title = args.title?.trim();
+		const taskLine = title ? `${beadId} - ${title}` : beadId;
+
+		const requiredTools = splitList(args.required_tools);
+		const mustDo = splitList(args.must_do);
+		const mustNotDo = splitList(args.must_not_do);
+		const acceptanceChecks = splitList(args.acceptance_checks);
+		const context = args.context?.trim();
+
+		const now = new Date();
+		const stamp = now.toISOString();
+
+		const packet = [
+			"# Delegation Packet",
+			"",
+			`- TASK: ${taskLine}`,
+			`- EXPECTED OUTCOME: ${args.expected_outcome.trim()}`,
+			"- REQUIRED TOOLS:",
+			formatBullets(requiredTools),
+			"- MUST DO:",
+			formatBullets(mustDo),
+			"- MUST NOT DO:",
+			formatBullets(mustNotDo),
+			"- ACCEPTANCE CHECKS:",
+			formatBullets(acceptanceChecks),
+			"- CONTEXT:",
+			context ? context : "(none)",
+		].join("\n");
+
+		if (!args.write) {
+			return `${packet}\n`;
+		}
+
+		const artifactDir = path.join(process.cwd(), ".beads", "artifacts", beadId);
+		const outName = sanitizeFilename(args.output_file || "delegation.md");
+		const outPath = path.join(artifactDir, outName);
+
+		const specPath = path.join(artifactDir, "spec.md");
+		const hasSpec = await fileExists(specPath);
+
+		await fs.mkdir(artifactDir, { recursive: true });
+
+		const header = `\n\n---\nGenerated: ${stamp}\n---\n\n`;
+		await fs.appendFile(outPath, `${header}${packet}\n`, "utf-8");
+
+		const specNote = hasSpec
+			? ""
+			: `\nWarning: spec.md not found at ${specPath}`;
+
+		return `✓ Delegation packet appended to ${outPath}${specNote}\n\n${packet}\n`;
+	},
+});