opencodekit 0.12.6 → 0.13.0

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

@@ -506,6 +506,50 @@ bd_claim(); // Gets frontend task that was waiting on API
 5. **Use `bd_msg(to="all")`** - For team-wide announcements
 6. **Sync regularly** - `bd_sync()` at session end
 
+## Best Practices (from Steve Yegge)
+
+### Daily/Weekly Maintenance
+
+| Task         | Frequency      | Command               | Why                                            |
+| ------------ | -------------- | --------------------- | ---------------------------------------------- |
+| Health check | Weekly         | `bd doctor`           | Repairs database issues, detects orphaned work |
+| Cleanup      | Every few days | `bd cleanup --days 7` | Keep DB under 200-500 issues for performance   |
+| Upgrade      | Weekly         | `bd upgrade`          | Get latest features and fixes                  |
+| Git hooks    | Once per repo  | `bd hooks install`    | Auto-sync on commit/merge/checkout             |
+
+### Key Principles
+
+1. **Plan outside Beads first** - Use planning tools, then import tasks to beads
+2. **One task per session, then restart** - Fresh context prevents confusion
+3. **File lots of issues** - Any work >2 minutes should be tracked
+4. **Use short prefixes** - `bd-`, `vc-`, `wy-` etc.
+5. **"Land the plane" = PUSH** - `bd sync` means git push, not "ready when you are"
+6. **Include issue ID in commits** - `git commit -m "Fix bug (bd-abc)"`
+
+### Database Health
+
+```bash
+# Check database size
+bd list --status=all --json | wc -l
+
+# Target: under 200-500 issues
+# If over, run cleanup more aggressively:
+bd cleanup --days 3
+```
+
+### Git Hooks (Essential)
+
+```bash
+bd hooks install
+```
+
+Installs hooks for:
+
+- **pre-commit**: Sync before commit
+- **post-merge**: Import changes after merge
+- **pre-push**: Ensure sync before push
+- **post-checkout**: Refresh after branch switch
+
 ## Quick Reference
 
 ```

package/dist/template/.opencode/skill/condition-based-waiting/example.ts

@@ -2,8 +2,8 @@
 // From: Lace test infrastructure improvements (2025-10-03)
 // Context: Fixed 15 flaky tests by replacing arbitrary timeouts
 
-import type { ThreadManager } from '~/threads/thread-manager';
-import type { LaceEvent, LaceEventType } from '~/threads/types';
+import type { ThreadManager } from "~/threads/thread-manager";
+import type { LaceEvent, LaceEventType } from "~/threads/types";
 
 /**
  * Wait for a specific event type to appear in thread
@@ -18,29 +18,33 @@ import type { LaceEvent, LaceEventType } from '~/threads/types';
  *   await waitForEvent(threadManager, agentThreadId, 'TOOL_RESULT');
  */
 export function waitForEvent(
-  threadManager: ThreadManager,
-  threadId: string,
-  eventType: LaceEventType,
-  timeoutMs = 5000
+	threadManager: ThreadManager,
+	threadId: string,
+	eventType: LaceEventType,
+	timeoutMs = 5000,
 ): Promise<LaceEvent> {
-  return new Promise((resolve, reject) => {
-    const startTime = Date.now();
+	return new Promise((resolve, reject) => {
+		const startTime = Date.now();
 
-    const check = () => {
-      const events = threadManager.getEvents(threadId);
-      const event = events.find((e) => e.type === eventType);
+		const check = () => {
+			const events = threadManager.getEvents(threadId);
+			const event = events.find((e) => e.type === eventType);
 
-      if (event) {
-        resolve(event);
-      } else if (Date.now() - startTime > timeoutMs) {
-        reject(new Error(`Timeout waiting for ${eventType} event after ${timeoutMs}ms`));
-      } else {
-        setTimeout(check, 10); // Poll every 10ms for efficiency
-      }
-    };
+			if (event) {
+				resolve(event);
+			} else if (Date.now() - startTime > timeoutMs) {
+				reject(
+					new Error(
+						`Timeout waiting for ${eventType} event after ${timeoutMs}ms`,
+					),
+				);
+			} else {
+				setTimeout(check, 10); // Poll every 10ms for efficiency
+			}
+		};
 
-    check();
-  });
+		check();
+	});
 }
 
 /**
@@ -58,34 +62,34 @@ export function waitForEvent(
  *   await waitForEventCount(threadManager, agentThreadId, 'AGENT_MESSAGE', 2);
  */
 export function waitForEventCount(
-  threadManager: ThreadManager,
-  threadId: string,
-  eventType: LaceEventType,
-  count: number,
-  timeoutMs = 5000
+	threadManager: ThreadManager,
+	threadId: string,
+	eventType: LaceEventType,
+	count: number,
+	timeoutMs = 5000,
 ): Promise<LaceEvent[]> {
-  return new Promise((resolve, reject) => {
-    const startTime = Date.now();
+	return new Promise((resolve, reject) => {
+		const startTime = Date.now();
 
-    const check = () => {
-      const events = threadManager.getEvents(threadId);
-      const matchingEvents = events.filter((e) => e.type === eventType);
+		const check = () => {
+			const events = threadManager.getEvents(threadId);
+			const matchingEvents = events.filter((e) => e.type === eventType);
 
-      if (matchingEvents.length >= count) {
-        resolve(matchingEvents);
-      } else if (Date.now() - startTime > timeoutMs) {
-        reject(
-          new Error(
-            `Timeout waiting for ${count} ${eventType} events after ${timeoutMs}ms (got ${matchingEvents.length})`
-          )
-        );
-      } else {
-        setTimeout(check, 10);
-      }
-    };
+			if (matchingEvents.length >= count) {
+				resolve(matchingEvents);
+			} else if (Date.now() - startTime > timeoutMs) {
+				reject(
+					new Error(
+						`Timeout waiting for ${count} ${eventType} events after ${timeoutMs}ms (got ${matchingEvents.length})`,
+					),
+				);
+			} else {
+				setTimeout(check, 10);
+			}
+		};
 
-    check();
-  });
+		check();
+	});
 }
 
 /**
@@ -109,30 +113,32 @@ export function waitForEventCount(
  *   );
  */
 export function waitForEventMatch(
-  threadManager: ThreadManager,
-  threadId: string,
-  predicate: (event: LaceEvent) => boolean,
-  description: string,
-  timeoutMs = 5000
+	threadManager: ThreadManager,
+	threadId: string,
+	predicate: (event: LaceEvent) => boolean,
+	description: string,
+	timeoutMs = 5000,
 ): Promise<LaceEvent> {
-  return new Promise((resolve, reject) => {
-    const startTime = Date.now();
+	return new Promise((resolve, reject) => {
+		const startTime = Date.now();
 
-    const check = () => {
-      const events = threadManager.getEvents(threadId);
-      const event = events.find(predicate);
+		const check = () => {
+			const events = threadManager.getEvents(threadId);
+			const event = events.find(predicate);
 
-      if (event) {
-        resolve(event);
-      } else if (Date.now() - startTime > timeoutMs) {
-        reject(new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`));
-      } else {
-        setTimeout(check, 10);
-      }
-    };
+			if (event) {
+				resolve(event);
+			} else if (Date.now() - startTime > timeoutMs) {
+				reject(
+					new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`),
+				);
+			} else {
+				setTimeout(check, 10);
+			}
+		};
 
-    check();
-  });
+		check();
+	});
 }
 
 // Usage example from actual debugging session:

package/dist/template/.opencode/tool/ast-grep.ts

@@ -6,8 +6,8 @@
  * Requires: npm install -g @ast-grep/cli (or brew install ast-grep)
  */
 
-import { exec } from "child_process";
-import { promisify } from "util";
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
 import { tool } from "@opencode-ai/plugin";
 
 const execAsync = promisify(exec);
@@ -224,7 +224,7 @@ Install via:
 						preview += `... and ${count - 10} more matches\n`;
 					}
 
-					preview += `\n**To apply:** Run again with dryRun: false`;
+					preview += "\n**To apply:** Run again with dryRun: false";
 					return preview;
 				} catch {
 					return `Dry run preview:\n${stdout}`;

package/dist/template/.opencode/tool/bd-inbox.ts

@@ -1,6 +1,6 @@
-import path from "path";
+import fs from "node:fs/promises";
+import path from "node:path";
 import { tool } from "@opencode-ai/plugin";
-import fs from "fs/promises";
 
 const RESERVATIONS_DIR = ".reservations";
 const MESSAGES_FILE = "messages.jsonl";
@@ -84,7 +84,7 @@ export default tool({
 				}
 				await fs.writeFile(
 					messagesPath,
-					allMsgs.map((m) => JSON.stringify(m)).join("\n") + "\n",
+					`${allMsgs.map((m) => JSON.stringify(m)).join("\n")}\n`,
 					"utf-8",
 				);
 			}
@@ -99,11 +99,12 @@ export default tool({
 			messages = messages.slice(-limit).reverse();
 
 			return JSON.stringify({ msgs: messages, count: messages.length });
-		} catch (e: any) {
-			if (e.code === "ENOENT") {
+		} catch (e) {
+			const err = e as NodeJS.ErrnoException;
+			if (err.code === "ENOENT") {
 				return JSON.stringify({ msgs: [], count: 0 });
 			}
-			return JSON.stringify({ error: e.message });
+			return JSON.stringify({ error: (e as Error).message });
 		}
 	},
 });

package/dist/template/.opencode/tool/bd-msg.ts

@@ -1,6 +1,6 @@
-import path from "path";
+import fs from "node:fs/promises";
+import path from "node:path";
 import { tool } from "@opencode-ai/plugin";
-import fs from "fs/promises";
 
 const RESERVATIONS_DIR = ".reservations";
 const MESSAGES_FILE = "messages.jsonl";
@@ -56,7 +56,7 @@ export default tool({
 			read: false,
 		};
 
-		await fs.appendFile(messagesPath, JSON.stringify(msg) + "\n", "utf-8");
+		await fs.appendFile(messagesPath, `${JSON.stringify(msg)}\n`, "utf-8");
 		return JSON.stringify({ ok: 1, id: msg.id });
 	},
 });

package/dist/template/.opencode/tool/bd-release.ts

@@ -1,6 +1,6 @@
-import path from "path";
+import fs from "node:fs/promises";
+import path from "node:path";
 import { tool } from "@opencode-ai/plugin";
-import fs from "fs/promises";
 
 const RESERVATIONS_DIR = ".reservations";
 

package/dist/template/.opencode/tool/bd-reserve.ts

@@ -1,6 +1,6 @@
-import path from "path";
+import fs from "node:fs/promises";
+import path from "node:path";
 import { tool } from "@opencode-ai/plugin";
-import fs from "fs/promises";
 
 const RESERVATIONS_DIR = ".reservations";
 
@@ -69,8 +69,9 @@ export default tool({
 				};
 				await fs.writeFile(metaPath, JSON.stringify(lockData), "utf-8");
 				granted.push(filePath);
-			} catch (e: any) {
-				if (e.code === "EEXIST") {
+			} catch (e) {
+				const err = e as NodeJS.ErrnoException;
+				if (err.code === "EEXIST") {
 					// Lock exists - check if expired or ours
 					try {
 						const content = await fs.readFile(metaPath, "utf-8");

package/dist/template/.opencode/tool/memory-read.ts

@@ -1,66 +1,66 @@
+import fs from "node:fs/promises";
+import path from "node:path";
 import { tool } from "@opencode-ai/plugin";
-import fs from "fs/promises";
-import path from "path";
 
 export default tool({
-  description:
-    "Read memory files for persistent cross-session context. Returns current project state, learnings, and active tasks. Supports subdirectories (e.g., 'research/opencode-sessions').",
-  args: {
-    file: tool.schema
-      .string()
-      .optional()
-      .describe(
-        "Memory file to read: handoffs/YYYY-MM-DD-phase, research/YYYY-MM-DD-topic, _templates/task-prd, _templates/task-spec, _templates/task-review, _templates/research, _templates/handoff",
-      ),
-  },
-  execute: async (args: { file?: string }) => {
-    const fileName = args.file || "memory";
+	description:
+		"Read memory files for persistent cross-session context. Returns current project state, learnings, and active tasks. Supports subdirectories (e.g., 'research/opencode-sessions').",
+	args: {
+		file: tool.schema
+			.string()
+			.optional()
+			.describe(
+				"Memory file to read: handoffs/YYYY-MM-DD-phase, research/YYYY-MM-DD-topic, _templates/task-prd, _templates/task-spec, _templates/task-review, _templates/research, _templates/handoff",
+			),
+	},
+	execute: async (args: { file?: string }) => {
+		const fileName = args.file || "memory";
 
-    // Normalize: strip .md extension if present
-    const normalizedFile = fileName.replace(/\.md$/i, "");
+		// Normalize: strip .md extension if present
+		const normalizedFile = fileName.replace(/\.md$/i, "");
 
-    // Location priority: project > global > legacy
-    const locations = [
-      path.join(process.cwd(), ".opencode/memory", `${normalizedFile}.md`),
-      path.join(
-        process.env.HOME || "",
-        ".config/opencode/memory",
-        `${normalizedFile}.md`,
-      ),
-      path.join(
-        process.cwd(),
-        ".config/opencode/memory",
-        `${normalizedFile}.md`,
-      ),
-    ];
+		// Location priority: project > global > legacy
+		const locations = [
+			path.join(process.cwd(), ".opencode/memory", `${normalizedFile}.md`),
+			path.join(
+				process.env.HOME || "",
+				".config/opencode/memory",
+				`${normalizedFile}.md`,
+			),
+			path.join(
+				process.cwd(),
+				".config/opencode/memory",
+				`${normalizedFile}.md`,
+			),
+		];
 
-    // Try each location in order
-    for (const filePath of locations) {
-      try {
-        const content = await fs.readFile(filePath, "utf-8");
-        const locationLabel = filePath.includes(".opencode/memory")
-          ? "project"
-          : filePath.includes(process.env.HOME || "")
-            ? "global"
-            : "legacy";
-        return `[Read from ${locationLabel}: ${filePath}]\n\n${content}`;
-      } catch (error) {
-        // Continue to next location if file not found
-        if (
-          error instanceof Error &&
-          "code" in error &&
-          error.code === "ENOENT"
-        ) {
-          continue;
-        }
-        // Other errors should be reported
-        if (error instanceof Error) {
-          return `Error reading memory from ${filePath}: ${error.message}`;
-        }
-      }
-    }
+		// Try each location in order
+		for (const filePath of locations) {
+			try {
+				const content = await fs.readFile(filePath, "utf-8");
+				const locationLabel = filePath.includes(".opencode/memory")
+					? "project"
+					: filePath.includes(process.env.HOME || "")
+						? "global"
+						: "legacy";
+				return `[Read from ${locationLabel}: ${filePath}]\n\n${content}`;
+			} catch (error) {
+				// Continue to next location if file not found
+				if (
+					error instanceof Error &&
+					"code" in error &&
+					error.code === "ENOENT"
+				) {
+					continue;
+				}
+				// Other errors should be reported
+				if (error instanceof Error) {
+					return `Error reading memory from ${filePath}: ${error.message}`;
+				}
+			}
+		}
 
-    // No file found in any location
-    return `Memory file '${normalizedFile}.md' not found in any location.\nSearched:\n- ${locations.join("\n- ")}\n\nStructure:\n- handoffs/YYYY-MM-DD-phase (phase transitions)\n- research/YYYY-MM-DD-topic (research findings)\n- _templates/ (prd, spec, review, research, handoff)`;
-  },
+		// No file found in any location
+		return `Memory file '${normalizedFile}.md' not found in any location.\nSearched:\n- ${locations.join("\n- ")}\n\nStructure:\n- handoffs/YYYY-MM-DD-phase (phase transitions)\n- research/YYYY-MM-DD-topic (research findings)\n- _templates/ (prd, spec, review, research, handoff)`;
+	},
 });

package/dist/template/.opencode/tool/memory-search.ts

@@ -1,6 +1,6 @@
-import path from "path";
+import fs from "node:fs/promises";
+import path from "node:path";
 import { tool } from "@opencode-ai/plugin";
-import fs from "fs/promises";
 
 interface SearchResult {
 	file: string;

package/dist/template/.opencode/tool/memory-update.ts

@@ -1,61 +1,60 @@
+import fs from "node:fs/promises";
+import path from "node:path";
 import { tool } from "@opencode-ai/plugin";
-import fs from "fs/promises";
-import path from "path";
 
 export default tool({
-  description:
-    "Update memory files with new learnings, progress, or context. Appends or replaces content based on mode. Supports subdirectories for organization (e.g., 'research/opencode-sessions' creates .opencode/memory/research/opencode-sessions.md).",
-  args: {
-    file: tool.schema
-      .string()
-      .describe(
-        "Memory file to update: handoffs/YYYY-MM-DD-phase, research/YYYY-MM-DD-topic. Use _templates/ for reference only.",
-      ),
-    content: tool.schema
-      .string()
-      .describe("Content to write or append to the memory file"),
-    mode: tool.schema
-      .string()
-      .optional()
-      .default("replace")
-      .describe(
-        "Update mode: 'replace' (overwrite file) or 'append' (add to end).",
-      ),
-  },
-  execute: async (args: { file: string; content: string; mode?: string }) => {
-    // Always write to project memory (.opencode/memory/)
-    const memoryDir = path.join(process.cwd(), ".opencode/memory");
+	description:
+		"Update memory files with new learnings, progress, or context. Appends or replaces content based on mode. Supports subdirectories for organization (e.g., 'research/opencode-sessions' creates .opencode/memory/research/opencode-sessions.md).",
+	args: {
+		file: tool.schema
+			.string()
+			.describe(
+				"Memory file to update: handoffs/YYYY-MM-DD-phase, research/YYYY-MM-DD-topic. Use _templates/ for reference only.",
+			),
+		content: tool.schema
+			.string()
+			.describe("Content to write or append to the memory file"),
+		mode: tool.schema
+			.string()
+			.optional()
+			.default("replace")
+			.describe(
+				"Update mode: 'replace' (overwrite file) or 'append' (add to end).",
+			),
+	},
+	execute: async (args: { file: string; content: string; mode?: string }) => {
+		// Always write to project memory (.opencode/memory/)
+		const memoryDir = path.join(process.cwd(), ".opencode/memory");
 
-    // Normalize file path: strip existing .md extension, handle subdirectories
-    let normalizedFile = args.file.replace(/\.md$/i, ""); // Remove .md if present
-    const filePath = path.join(memoryDir, `${normalizedFile}.md`);
-    const mode = args.mode || "replace";
+		// Normalize file path: strip existing .md extension, handle subdirectories
+		const normalizedFile = args.file.replace(/\.md$/i, ""); // Remove .md if present
+		const filePath = path.join(memoryDir, `${normalizedFile}.md`);
+		const mode = args.mode || "replace";
 
-    try {
-      // Ensure parent directory exists (handles subdirectories)
-      const fileDir = path.dirname(filePath);
-      await fs.mkdir(fileDir, { recursive: true });
+		try {
+			// Ensure parent directory exists (handles subdirectories)
+			const fileDir = path.dirname(filePath);
+			await fs.mkdir(fileDir, { recursive: true });
 
-      if (mode === "append") {
-        const timestamp = new Date().toISOString();
-        const appendContent = `\n\n---\n**Updated:** ${timestamp}\n\n${args.content}`;
-        await fs.appendFile(filePath, appendContent, "utf-8");
-        return `Successfully appended to ${normalizedFile}.md\n[Written to: ${filePath}]`;
-      } else {
-        // Replace mode - update timestamp
-        const timestamp = new Date().toISOString();
-        const updatedContent = args.content.replace(
-          /\*\*Last Updated:\*\* \[Timestamp\]/,
-          `**Last Updated:** ${timestamp}`,
-        );
-        await fs.writeFile(filePath, updatedContent, "utf-8");
-        return `Successfully updated ${normalizedFile}.md\n[Written to: ${filePath}]`;
-      }
-    } catch (error) {
-      if (error instanceof Error) {
-        return `Error updating memory: ${error.message}`;
-      }
-      return `Unknown error updating memory file`;
-    }
-  },
+			if (mode === "append") {
+				const timestamp = new Date().toISOString();
+				const appendContent = `\n\n---\n**Updated:** ${timestamp}\n\n${args.content}`;
+				await fs.appendFile(filePath, appendContent, "utf-8");
+				return `Successfully appended to ${normalizedFile}.md\n[Written to: ${filePath}]`;
+			}
+			// Replace mode - update timestamp
+			const timestamp = new Date().toISOString();
+			const updatedContent = args.content.replace(
+				/\*\*Last Updated:\*\* \[Timestamp\]/,
+				`**Last Updated:** ${timestamp}`,
+			);
+			await fs.writeFile(filePath, updatedContent, "utf-8");
+			return `Successfully updated ${normalizedFile}.md\n[Written to: ${filePath}]`;
+		} catch (error) {
+			if (error instanceof Error) {
+				return `Error updating memory: ${error.message}`;
+			}
+			return "Unknown error updating memory file";
+		}
+	},
 });

package/dist/template/.opencode/tool/observation.ts

@@ -1,6 +1,6 @@
-import path from "path";
+import fs from "node:fs/promises";
+import path from "node:path";
 import { tool } from "@opencode-ai/plugin";
-import fs from "fs/promises";
 
 // Observation types following claude-mem patterns
 type ObservationType =
@@ -112,9 +112,9 @@ export default tool({
 			observation += `**Files:** ${files.map((f) => `\`${f}\``).join(", ")}\n`;
 		}
 
-		observation += `\n---\n\n`;
+		observation += "\n---\n\n";
 		observation += args.content;
-		observation += `\n`;
+		observation += "\n";
 
 		try {
 			// Ensure directory exists
@@ -128,7 +128,7 @@ export default tool({
 			// Update bead notes if bead_id provided
 			if (args.bead_id) {
 				try {
-					const { execSync } = await import("child_process");
+					const { execSync } = await import("node:child_process");
 					const noteContent = `${icon} ${obsType}: ${args.title}`;
 					execSync(
 						`bd edit ${args.bead_id} --note "${noteContent.replace(/"/g, '\\"')}"`,
@@ -149,7 +149,7 @@ export default tool({
 			if (error instanceof Error) {
 				return `Error saving observation: ${error.message}`;
 			}
-			return `Unknown error saving observation`;
+			return "Unknown error saving observation";
 		}
 	},
 });