opencodekit 0.12.2 → 0.12.3

package/dist/template/.opencode/command/triage.md

@@ -17,7 +17,7 @@ Analyze open tasks and optimize prioritization using dependency graph analysis,
 ## Phase 1: Initialize Beads Connection
 
 ```typescript
-bd_init({ _: true, team: "project", role: "triage" });
+bd_init({ team: "project", role: "build" });
 ```
 
 ## Phase 2: Gather Workspace State
@@ -27,7 +27,7 @@ Run in parallel:
 ```typescript
 bd_status({ include_agents: true });
 bd_ls({ status: "open", limit: 50, offset: 0 });
-bd_reservations({ reason: "Check active file locks" });
+bd_reservations();
 bd_inbox({ n: 10, unread: true, global: true });
 
 // Search for past discussions on recurring issues
@@ -199,14 +199,14 @@ AGENT WORKLOAD
 ━━━━━━━━━━━━━━
 Agent     │ Active │ Completed │ Load
 ──────────┼────────┼───────────┼──────
-fe-agent  │ 2      │ 8         │ HIGH
-be-agent  │ 1      │ 12        │ MEDIUM
-qa-agent  │ 0      │ 5         │ LOW
+build-1   │ 2      │ 8         │ HIGH
+build-2   │ 1      │ 12        │ MEDIUM
+review    │ 0      │ 5         │ LOW
 
 RECOMMENDATIONS
 ━━━━━━━━━━━━━━━
-1. 🔴 URGENT: bd-abc12 is blocking 4 tasks - assign to be-agent
-2. 🟡 REBALANCE: fe-agent has high load - redistribute to qa-agent
+1. 🔴 URGENT: bd-abc12 is blocking 4 tasks - assign to build agent
+2. 🟡 REBALANCE: build-1 has high load - redistribute to review agent
 3. 🟢 PARALLEL: Start Track A and B simultaneously
 4. ⚠️  STALE: bd-old99 has no activity for 7 days - review or close
 
@@ -221,12 +221,13 @@ If `--auto-assign` flag:
 
 ```typescript
 const assignmentRules = {
-  // Role detection from task tags/title
-  "frontend|ui|css|react|vue": "fe",
-  "backend|api|database|server": "be",
-  "test|qa|e2e|integration": "qa",
-  "deploy|ci|docker|infra": "devops",
-  "mobile|ios|android|react-native": "mobile",
+  // All implementation work goes to build agents
+  "frontend|ui|css|react|vue": "build",
+  "backend|api|database|server": "build",
+  "deploy|ci|docker|infra": "build",
+  "mobile|ios|android|react-native": "build",
+  // Review/QA work goes to review agent
+  "test|qa|e2e|integration": "review",
 };
 
 // Load balancing: prefer agent with lowest active count
@@ -253,12 +254,12 @@ for (const task of readyTasks.filter((t) => !t.assignee && t.priority <= 2)) {
 AUTO-ASSIGNMENTS
 ━━━━━━━━━━━━━━━━
 
-✓ bd-abc12 → be-agent (detected: backend, API)
-✓ bd-def34 → fe-agent (detected: frontend, React)
-✓ bd-ghi56 → devops (detected: infrastructure)
+✓ bd-abc12 → build (detected: backend, API)
+✓ bd-def34 → build (detected: frontend, React)
+✓ bd-ghi56 → build (detected: infrastructure)
 
 Skipped:
-- bd-xyz99: Already assigned to qa-agent
+- bd-xyz99: Already assigned to review agent
 - bd-old88: No matching role detected (manual assignment needed)
 ```
 
@@ -293,7 +294,11 @@ console.log("3. Review individually");
 ## Phase 9: Sync and Notify
 
 ```typescript
-bd_sync({ reason: "Triage complete" });
+
+```
+
+```typescript
+bd_sync({ reason: "Sync triage changes" });
 
 // Broadcast triage summary if significant changes
 if (assignmentsMade > 0 || priorityChanges > 0) {

package/dist/template/.opencode/memory/project/commands.md

@@ -52,14 +52,146 @@ OPENCODE_DISABLE_PRUNE=true             # Disable DCP pruning
 "nudgeFrequency": 8    // LLM nudged every 8 tool calls (default: 10)
 ```
 
+## Beads CLI (Core)
+
+The `bd` command is your issue tracker. JSONL is source of truth, SQLite is cache.
+
+### Essential Commands
+
+```bash
+bd ready                              # Unblocked tasks (use this to find work)
+bd list --status=open                 # All open issues
+bd show <id>                          # Full details
+bd create "Title" -t task -p 2        # Create (type: task/bug/feature/epic, priority: 0-4)
+bd update <id> --status in_progress   # Claim work
+bd close <id> --reason "Done"         # Complete
+bd sync                               # Export/commit/push (always run at session end)
+```
+
+### Dependencies
+
+```bash
+bd dep add <child> <parent> --type blocks   # Child blocked until parent closes
+bd dep tree <id>                            # Visualize dependency chain
+bd blocked                                  # Show all blocked issues
+```
+
+### Coordination
+
+```bash
+bd list --status in_progress          # See what's claimed by others
+git pull && bd import                 # Get latest from team
+bd sync                               # Push your changes
+```
+
+### Priority Levels
+
+- **P0** - Critical (security, data loss)
+- **P1** - High (major features, important bugs)
+- **P2** - Medium (default)
+- **P3** - Low
+- **P4** - Backlog
+
+### Sandbox Mode
+
+If running in restricted environment (Claude Code, etc.):
+
+```bash
+bd --sandbox ready
+# Or: bd --no-daemon --no-auto-flush --no-auto-import list
+```
+
+## Beads Plugin Tools (For OpenCode Agents)
+
+This project's plugin (`.opencode/plugin/beads.ts`) provides typed tools that wrap the CLI.
+
+### Session Lifecycle
+
+```typescript
+bd_init({ role: "build" }); // Join workspace - MUST call first
+bd_claim(); // Get next ready task, mark in_progress
+bd_reserve({ paths: ["src/foo.ts"] }); // Lock files before editing
+// ... do work ...
+bd_done({ id: "bd-xxx", msg: "Done" }); // Close + release locks + sync
+```
+
+### Task Management
+
+```typescript
+bd_add({ title: "Task", pri: 2, type: "task" }); // Create issue
+bd_show({ id: "bd-xxx" }); // Get full details
+bd_ls({ status: "open", limit: 10 }); // List issues
+bd_ready(); // Ready-to-work tasks
+bd_update({ id: "bd-xxx", status: "in_progress" }); // Update issue
+bd_search({ query: "auth" }); // Search issues
+```
+
+### File Locking (Plugin-Only)
+
+```typescript
+bd_reserve({ paths: ["src/a.ts", "src/b.ts"], ttl: 600 }); // Lock files
+bd_reservations(); // List active locks
+bd_release({ paths: ["src/a.ts"] }); // Release specific
+bd_release(); // Release all
+```
+
+### Messaging (Plugin-Only)
+
+```typescript
+bd_msg({ subj: "Done", to: "all", global: true }); // Broadcast
+bd_inbox({ n: 5, unread: true }); // Check messages
+bd_ack({ ids: ["msg-abc", "msg-def"] }); // Mark messages as read
+```
+
+### Agent Coordination (Plugin-Only)
+
+```typescript
+bd_whois(); // See all agents and their current work
+bd_whois({ agent: "build-abc" }); // Lookup specific agent
+```
+
+### Maintenance
+
+```typescript
+bd_sync(); // Sync with git
+bd_status({ include_agents: true }); // Workspace overview
+bd_doctor(); // Check database health
+bd_cleanup({ days: 7 }); // Remove old closed issues
+```
+
 ## Beads Workflow
 
+### Start Work
+
 ```bash
-bd ready              # Show issues ready to work (no blockers)
-bd list --status=open # All open issues
-bd show <id>          # Full issue details with dependencies
-bd create --title="..." --type=task --priority=2
-bd update <id> --status=in_progress
-bd close <id> --reason="Completed"
-bd sync               # Commit and push changes
+bd ready                              # Find unblocked task
+bd update bd-xxx --status in_progress # Claim it
+git checkout -b bd-xxx                # Create branch
 ```
+
+### During Work
+
+```bash
+git commit -m "WIP: bd-xxx - [progress]"  # Checkpoint commits
+bd sync                                    # Sync beads state
+```
+
+### End Session
+
+```bash
+git add -A && git commit -m "bd-xxx: [summary]"
+bd close bd-xxx --reason "Completed: [what]"
+bd sync
+git push
+```
+
+### Handoff (If Not Finishing)
+
+```bash
+git commit -m "WIP: bd-xxx - [where stopped]"
+# Create handoff in .beads/artifacts/bd-xxx/handoffs/
+bd sync
+git push
+```
+
+Resume later with: `/resume bd-xxx`

package/dist/template/.opencode/memory/project/gotchas.md

@@ -58,3 +58,88 @@ If tools are unexpectedly blocked:
 2. Check project config: `.opencode/opencode.json`
 3. Project config takes precedence
 4. Use `"*": "ask"` as base rule to debug which pattern is matching
+
+## Beads Gotchas
+
+### Core Beads CLI vs This Project's Plugin
+
+**Core beads CLI** (`bd`) is the upstream tool from steveyegge/beads.
+
+**This project's plugin** (`.opencode/plugin/beads.ts`) wraps the CLI and adds:
+
+- `bd_done()` - closes task + releases locks + syncs in one call
+- `bd_reserve()` / `bd_release()` - atomic file locking via mkdir
+- `bd_claim()` - finds ready task + marks in_progress
+- `bd_msg()` / `bd_inbox()` / `bd_ack()` - agent-to-agent messaging
+- `bd_whois()` - agent directory lookup (who's working on what)
+- Agent state (current task, reserved files, agent ID)
+
+### Which To Use
+
+| Context              | Use                     |
+| -------------------- | ----------------------- |
+| OpenCode agents      | Plugin tools (`bd_*()`) |
+| Shell scripts, CI/CD | CLI (`bd`)              |
+| Human terminal       | CLI (`bd`)              |
+
+### Plugin Tools (Preferred for Agents)
+
+```typescript
+bd_init({ role: "build" }); // Join workspace
+bd_claim(); // Get next ready task
+bd_reserve({ paths: ["src/foo.ts"] }); // Lock files
+// ... do work ...
+bd_done({ id: "bd-xxx", msg: "Done" }); // Close + release + sync
+```
+
+### CLI Commands (For Scripts/Humans)
+
+```bash
+bd create "Task title" -t task -p 2   # Create
+bd update bd-xxx --status in_progress  # Claim
+bd close bd-xxx --reason "Done"        # Complete
+bd sync                                 # Push to git
+```
+
+### Hash-Based IDs Prevent Collisions
+
+Beads uses hash IDs (`bd-a3f8`) not sequential IDs (`bd-1`, `bd-2`). This eliminates merge conflicts when multiple agents create issues on different branches.
+
+Don't assume sequential IDs. Always use `bd show` to get exact IDs.
+
+### `bd ready` Is Your Friend
+
+`bd ready` shows tasks with NO unresolved blockers. Use it to find work instead of `bd list`.
+
+### Dependencies Block Work
+
+```bash
+bd dep add bd-child bd-parent --type blocks
+```
+
+Now `bd-child` won't appear in `bd ready` until `bd-parent` closes. Check `bd blocked` to see what's waiting.
+
+### Git Is The Coordination Layer
+
+No central server. Agents coordinate via:
+
+1. Issue status (in_progress = claimed)
+2. Git branches
+3. `bd sync` to push/pull changes
+
+### Sandbox Environments (Claude Code, etc.)
+
+Daemon can't be killed by sandbox. Use:
+
+```bash
+bd --sandbox ready
+# Or: bd --no-daemon --no-auto-flush --no-auto-import list
+```
+
+### 30-Second Debounce
+
+Rapid operations get batched into single JSONL flush after 30s. Force immediate sync:
+
+```bash
+bd sync
+```

package/dist/template/.opencode/plugin/beads.ts

@@ -366,10 +366,12 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 		filePath: string,
 		reason?: string,
 		ttlSeconds = 600,
+		overrideAgent?: string,
 	): Promise<{ acquired: boolean; holder?: string }> {
 		const lockPath = lockDir(filePath);
 		const now = Date.now();
 		const expires = now + ttlSeconds * 1000;
+		const agentToUse = overrideAgent || state.agentId;
 
 		// Atomic: mkdir fails if dir exists
 		try {
@@ -384,10 +386,10 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 				if (lock.expires < now) {
 					// Expired - remove and retry
 					await $`rm -rf ${lockPath}`.cwd(directory).quiet();
-					return acquireLock(filePath, reason, ttlSeconds);
+					return acquireLock(filePath, reason, ttlSeconds, overrideAgent);
 				}
 
-				if (lock.agent === state.agentId) {
+				if (lock.agent === agentToUse) {
 					// We already hold this lock - refresh it
 					lock.expires = expires;
 					await $`echo ${JSON.stringify(lock)} > ${metaPath}`
@@ -400,14 +402,14 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 			} catch {
 				// Corrupted lock - remove and retry
 				await $`rm -rf ${lockPath}`.cwd(directory).quiet();
-				return acquireLock(filePath, reason, ttlSeconds);
+				return acquireLock(filePath, reason, ttlSeconds, overrideAgent);
 			}
 		}
 
 		// Lock acquired - write metadata
 		const lockData: LockData = {
 			path: filePath,
-			agent: state.agentId,
+			agent: agentToUse,
 			reason,
 			created: now,
 			expires,
@@ -597,7 +599,7 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 					role: tool.schema
 						.string()
 						.optional()
-						.describe("Role: fe|be|mobile|devops|qa"),
+						.describe("Role: build|rush|explore|planner|review|scout|vision"),
 				},
 				async execute(args) {
 					await $`bd init`
@@ -670,11 +672,17 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 						.default("completed")
 						.describe("Completion message"),
 				},
-				async execute(args) {
+				async execute(args, context) {
 					const taskId = args.id || state.currentTask;
 					if (!taskId) return json({ error: "No task ID" });
 
-					const closeResult = await bdClose(taskId, args.msg);
+					// Audit trail
+					const auditAgent = context?.agent || state.agentId;
+
+					const closeResult = await bdClose(
+						taskId,
+						`${args.msg} [by ${auditAgent}]`,
+					);
 					if (closeResult.error) return json({ error: closeResult.error });
 
 					// Release all locks
@@ -708,7 +716,9 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 					tags: tool.schema
 						.array(tool.schema.string())
 						.optional()
-						.describe("Role tags: fe,be,mobile,devops,qa"),
+						.describe(
+							"Agent tags: build,rush,explore,planner,review,scout,vision",
+						),
 					parent: tool.schema.string().optional().describe("Parent issue ID"),
 					deps: tool.schema
 						.array(tool.schema.string())
@@ -754,7 +764,9 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 					"Assign task to role (leader only). Adds tag and notifies.",
 				args: {
 					id: tool.schema.string().describe("Issue ID"),
-					role: tool.schema.string().describe("Role: fe|be|mobile|devops|qa"),
+					role: tool.schema
+						.string()
+						.describe("Role: build|rush|explore|planner|review|scout|vision"),
 					notify: tool.schema
 						.boolean()
 						.default(true)
@@ -882,16 +894,24 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 						.default(600)
 						.describe("Seconds until expiry"),
 				},
-				async execute(args) {
+				async execute(args, context) {
 					if (!args.paths?.length) return json({ error: "paths required" });
 
+					// Log who is reserving for audit
+					const reservingAgent = context?.agent || state.agentId;
+
 					await ensureReservationsDir();
 
 					const granted: string[] = [];
 					const conflicts: { path: string; holder?: string }[] = [];
 
 					for (const path of args.paths) {
-						const result = await acquireLock(path, args.reason, args.ttl);
+						const result = await acquireLock(
+							path,
+							args.reason,
+							args.ttl,
+							reservingAgent,
+						);
 						if (result.acquired) {
 							granted.push(path);
 						} else {
@@ -963,12 +983,15 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 						.default(false)
 						.describe("Send to all workspaces"),
 				},
-				async execute(args) {
+				async execute(args, context) {
 					if (!args.subj) return json({ error: "subj required" });
 
+					// Use context agent if available for audit trail
+					const senderAgent = context?.agent || state.agentId;
+
 					const msg: Message = {
 						id: `msg-${Date.now().toString(36)}`,
-						from: state.agentId,
+						from: senderAgent,
 						to: args.to || "all",
 						subj: args.subj,
 						body: args.body,
@@ -1000,6 +1023,117 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 				},
 			}),
 
+			bd_ack: tool({
+				description: "Acknowledge message(s). Marks as read.",
+				args: {
+					ids: tool.schema
+						.array(tool.schema.string())
+						.describe("Message IDs to acknowledge"),
+				},
+				async execute(args) {
+					if (!args.ids?.length) return json({ error: "ids required" });
+
+					try {
+						const content =
+							await $`cat ${RESERVATIONS_DIR}/messages.jsonl 2>/dev/null`
+								.cwd(directory)
+								.text();
+
+						if (!content.trim()) return json({ acked: 0 });
+
+						const idsToAck = new Set(args.ids);
+						let acked = 0;
+
+						const msgs = content
+							.trim()
+							.split("\n")
+							.map((line) => {
+								try {
+									const msg = JSON.parse(line) as Message;
+									if (idsToAck.has(msg.id) && !msg.read) {
+										msg.read = true;
+										acked++;
+									}
+									return msg;
+								} catch {
+									return null;
+								}
+							})
+							.filter((m): m is Message => m !== null);
+
+						const newContent = msgs.map((m) => JSON.stringify(m)).join("\n");
+						await $`echo ${newContent} > ${RESERVATIONS_DIR}/messages.jsonl`
+							.cwd(directory)
+							.quiet();
+
+						return json({ ok: 1, acked });
+					} catch {
+						return json({ acked: 0 });
+					}
+				},
+			}),
+
+			bd_whois: tool({
+				description: "Agent directory lookup. See who's working on what.",
+				args: {
+					agent: tool.schema
+						.string()
+						.optional()
+						.describe("Agent ID to lookup (empty=all)"),
+				},
+				async execute(args) {
+					const locks = await getAllLocks();
+					const { tasks: inProgressTasks } = await bdList({
+						status: "in_progress",
+					});
+
+					// Build agent activity map
+					const agentMap: Record<
+						string,
+						{
+							files: string[];
+							task?: string;
+							role?: string;
+						}
+					> = {};
+
+					// Add locks info
+					for (const lock of locks) {
+						if (!agentMap[lock.agent]) {
+							agentMap[lock.agent] = { files: [] };
+						}
+						agentMap[lock.agent].files.push(lock.path);
+						if (lock.task) {
+							agentMap[lock.agent].task = lock.task;
+						}
+					}
+
+					// Add current agent info
+					if (!agentMap[state.agentId]) {
+						agentMap[state.agentId] = { files: [] };
+					}
+					agentMap[state.agentId].role = state.role || undefined;
+					if (state.currentTask) {
+						agentMap[state.agentId].task = state.currentTask;
+					}
+
+					// Filter if specific agent requested
+					if (args.agent) {
+						const agent = agentMap[args.agent];
+						if (!agent) return json({ error: "agent not found" });
+						return json({ agent: args.agent, ...agent });
+					}
+
+					return json({
+						agents: Object.entries(agentMap).map(([id, info]) => ({
+							id,
+							...info,
+						})),
+						in_progress_tasks: inProgressTasks.length,
+					});
+				},
+			}),
+
 			bd_status: tool({
 				description: "Workspace overview. Shows agents, tasks, locks.",
 				args: {
@@ -1038,10 +1172,22 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 
 			bd_sync: tool({
 				description: "Sync with git. Pull/push changes.",
-				args: {},
-				async execute() {
+				args: {
+					reason: tool.schema
+						.string()
+						.optional()
+						.describe("Audit trail reason for sync"),
+				},
+				async execute(args, context) {
 					const result = await bdSync();
-					return json({ ok: 1, output: result.output });
+					// Log sync with context for audit trail
+					const syncAgent = context?.agent || state.agentId;
+					return json({
+						ok: 1,
+						output: result.output,
+						by: syncAgent,
+						reason: args.reason,
+					});
 				},
 			}),
 
@@ -1249,6 +1395,25 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 			if (event.type === "session.idle" && state.currentTask) {
 				await bdSync();
 			}
+
+			// Cleanup expired locks on compaction
+			if (event.type === "session.compacted") {
+				await cleanupExpiredLocks();
+			}
+
+			// Log errors to audit trail
+			if (event.type === "session.error" && state.currentTask) {
+				await appendMessage({
+					id: `err-${Date.now().toString(36)}`,
+					from: state.agentId,
+					to: "all",
+					subj: `Session error on task ${state.currentTask}`,
+					body: `Error occurred during task execution`,
+					importance: "high",
+					at: Date.now(),
+					read: false,
+				});
+			}
 		},
 	};
 };

package/dist/template/.opencode/skill/beads/SKILL.md

@@ -340,6 +340,21 @@ bd_msg({
 bd_inbox({ unread: true, n: 10 });
 ```
 
+### Acknowledge Messages
+
+```typescript
+bd_ack({ ids: ["msg-abc", "msg-def"] }); // Mark as read
+```
+
+## Agent Coordination
+
+### Who's Working on What
+
+```typescript
+bd_whois(); // All agents with their files and tasks
+bd_whois({ agent: "build-abc" }); // Specific agent lookup
+```
+
 ## Status and Analysis
 
 ### Workspace Overview