opencodekit 0.15.15 → 0.15.18

package/dist/template/.opencode/{agent → agents}/scout.md

@@ -93,7 +93,7 @@ Run 2-3 tool calls in parallel.
 **Triggers:** "how do others", "compare", "best practices", "production patterns"
 **Target:** Summary, 3-5 code examples, tradeoffs, recommendation
 
-1. Search GitHub with grep_search (vary queries for different angles)
+1. Search GitHub with grepsearch (vary queries for different angles)
 2. Compare 3-5 implementations from different repositories
 3. Synthesize common patterns
 4. Note tradeoffs and edge cases
@@ -101,8 +101,8 @@ Run 2-3 tool calls in parallel.
 ```typescript
 // Run 4-6 external tool calls in parallel
 // Adapt language filter based on research context
-grep_search({ query: "<pattern 1>" }); // No language filter = search all
-grep_search({ query: "<pattern 2>", language: "<relevant lang>" });
+grepsearch({ query: "<pattern 1>" }); // No language filter = search all
+grepsearch({ query: "<pattern 2>", language: "<relevant lang>" });
 codesearch({ query: "<API usage>", tokensNum: 5000 });
 context7_query_docs({ libraryId: "<id>", topic: "<feature>" });
 ```
@@ -123,7 +123,7 @@ Run 4-6 tool calls in parallel.
 
 Every code reference must include a GitHub permalink. Never link to a branch or tag that can change.
 
-To construct a permalink: use `grep_search` to find code, then build the URL from the repository and file path returned. Format: `https://github.com/owner/repo/blob/<sha>/path/to/file#L10-L20`.
+To construct a permalink: use `grepsearch` to find code, then build the URL from the repository and file path returned. Format: `https://github.com/owner/repo/blob/<sha>/path/to/file#L10-L20`.
 
 ## Tool Priority (External Sources Only)
 
@@ -132,7 +132,7 @@ To construct a permalink: use `grep_search` to find code, then build the URL fro
 | 1        | memory-search | Past research findings                    | Instant |
 | 2        | context7      | Official library docs                     | Fast    |
 | 3        | codesearch    | Exa Code API for SDK/library patterns     | Fast    |
-| 4        | grep_search   | Cross-repo GitHub code search (1M+ repos) | Medium  |
+| 4        | grepsearch   | Cross-repo GitHub code search (1M+ repos) | Medium  |
 | 5        | webfetch      | Specific doc URLs, READMEs, changelogs    | Medium  |
 | 6        | opensrc + LSP | Clone & analyze source code               | Slow    |
 | 7        | websearch     | Tutorials, blog posts, recent news        | Slow    |
@@ -210,14 +210,14 @@ context7_query_docs({ libraryId: nodeId, topic: "streams API" });
 | Empty results     | Try related terms or "API reference"           |
 | API error         | Verify CONTEXT7_API_KEY is set (optional)      |
 
-## grep_search Tool
+## grepsearch Tool
 
 Use for cross-repository code search across 1M+ public GitHub repositories.
 
 ### Schema
 
 ```typescript
-grep_search({
+grepsearch({
   query: string,              // Required - search pattern (literal code, not keywords)
   repo?: string,              // Optional - filter to specific repo (e.g., "vercel/ai")
   language?: string[],        // Optional - e.g., ["TypeScript", "TSX"]
@@ -247,22 +247,22 @@ grep_search({
 
 ```typescript
 // Basic repo search
-grep_search({ query: "batch_tool", repo: "anomalyco/opencode" });
+grepsearch({ query: "batch_tool", repo: "anomalyco/opencode" });
 
 // With language filter
-grep_search({
+grepsearch({
   query: "getServerSession",
   language: ["TypeScript", "TSX"],
 });
 
 // Regex pattern (multi-line)
-grep_search({
+grepsearch({
   query: "(?s)useEffect\\(\\(\\) => {.*removeEventListener",
   useRegexp: true,
 });
 
 // Path filter for specific files
-grep_search({
+grepsearch({
   query: "CORS(",
   language: ["Python"],
   matchCase: true,
@@ -406,8 +406,8 @@ Structure your response as:
 
 ```
 context7 fails → try codesearch for patterns
-codesearch empty → try grep_search with broader query
-grep_search empty → webfetch specific doc URLs if known
+codesearch empty → try grepsearch with broader query
+grepsearch empty → webfetch specific doc URLs if known
 still stuck → opensrc clone + LSP analysis
 last resort → websearch for tutorials/blogs
 ```
@@ -417,10 +417,10 @@ last resort → websearch for tutorials/blogs
 **context7 doesn't find library:**
 
 1. Try `codesearch({ query: "<library> <function> example" })`
-2. Try `grep_search({ query: "import.*from.*<library>", language: ["TypeScript"] })`
+2. Try `grepsearch({ query: "import.*from.*<library>", language: ["TypeScript"] })`
 3. Clone with `npx opensrc <library>` and read source
 
-**grep_search returns nothing:**
+**grepsearch returns nothing:**
 
 - Broaden query: search concepts, not exact function names
 - Remove specific repo filter to search across all repos
@@ -429,7 +429,7 @@ last resort → websearch for tutorials/blogs
 - Search for error messages, config patterns, or import statements
 - Fall back to `codesearch` for conceptual queries
 
-**grep_search API error:**
+**grepsearch API error:**
 
 - The grep.app API may be temporarily unavailable
 - Fall back to `codesearch` for similar functionality
@@ -458,6 +458,6 @@ NO URL GUESSING: Only use URLs from tools or user input.
 CITE EVERYTHING: No claims without source links.
 
 Quick: context7 → codesearch → websearch (2-3 parallel calls)
-Deep: grep_search (4-6 parallel calls) → compare 3-5 repos → synthesize
-Fallback: context7 → codesearch → grep_search → webfetch → opensrc → websearch
+Deep: grepsearch (4-6 parallel calls) → compare 3-5 repos → synthesize
+Fallback: context7 → codesearch → grepsearch → webfetch → opensrc → websearch
 ```

package/dist/template/.opencode/{command → commands}/implement.md

@@ -22,7 +22,7 @@ You're implementing a tracked task. Stay focused, delegate research, verify as y
 skill({ name: "beads" });
 skill({ name: "test-driven-development" });
 skill({ name: "verification-before-completion" });
-skill({ name: "swarm-coordination" }); // For swarm mode
+skill({ name: "swarm-coordination" }); // For swarm mode with Kimi K2.5 PARL patterns
 ```
 
 Get the task details and check hierarchy:
@@ -59,17 +59,39 @@ bd ready --json | grep -q "$ARGUMENTS"
 
 **Or use SWARM MODE for parallel execution (recommended for 3+ subtasks):**
 
-## Swarm Mode Execution (--swarm flag or auto-detect)
+## Swarm Mode Execution (--swarm flag or auto-detect with PARL)
 
-When the task has 3+ independent subtasks that can run in parallel, use swarm coordination:
+When the task has 3+ independent subtasks, use Kimi K2.5 PARL swarm coordination:
 
-### Step 1: Evaluate Swarm Eligibility
+### Step 0: Task Analysis (Anti-Serial-Collapse)
 
 ```typescript
-// Check if subtasks are parallelizable:
-// - Do they modify different files? → YES = parallel OK
-// - Are they sequentially dependent? → NO = parallel OK
-// - Are there 3+ independent tasks? → YES = swarm beneficial
+// 1. Analyze the actual task
+const subtasks = await getSubtasks($ARGUMENTS); // Get all subtask IDs
+const files = await getFilesForSubtasks(subtasks); // Detect relevant files
+
+const analysis = await swarm_plan({
+  operation: "analyze",
+  task: "Implement " + $ARGUMENTS + " with " + subtasks.length + " subtasks",
+  files: files.join(","),
+});
+
+// 2. Check for serial collapse
+const check = await swarm_plan({
+  operation: "check",
+  task: "Implement " + $ARGUMENTS,
+  files: String(subtasks.length),
+  recommended_agents: analysis.classification.recommended_agents,
+});
+
+if (check.serial_collapse_detected) {
+  console.log(`⚠️ Serial collapse detected: ${check.warning_signs.join(", ")}`);
+  console.log(`✓ Adjusting to ${check.suggested_agents} agents`);
+}
+
+// 3. Use classification to guide swarm setup
+const { type, recommended_agents, phases } = analysis.classification;
+console.log(`Task type: ${type}, Agents: ${recommended_agents}, Phases: ${phases.length}`);
 ```
 
 ### Step 2: Create Delegation Packets
@@ -120,10 +142,12 @@ Worker: worker-1
 
 ## Protocol
 1. Read delegation packet FIRST
-2. Announce start: swarm-helper sendTeamMessage
+2. Report START: swarm-monitor({ operation: "progress_update", team_name: "$ARGUMENTS-swarm", worker_id: "worker-<N>", phase: "<phase>", progress: 0, status: "working" })
 3. Execute following MUST DO / avoiding MUST NOT DO
-4. Run ALL acceptance checks
-5. Report completion: swarm-helper sendTeamMessage
+4. Report PROGRESS (every 25%): swarm-monitor({ operation: "progress_update", ...progress: 25/50/75, file: "current-file.ts" })
+5. Run ALL acceptance checks
+6. Report DONE: swarm-monitor({ operation: "progress_update", ...progress: 100, status: "completed" })
+7. Send completion: swarm-monitor({ operation: "mail_send", team_name: "$ARGUMENTS-swarm", from_worker: "worker-<N>", message: "DONE: <actual work completed>" })
 
 Report format:
 - DONE: <summary> (if successful)
@@ -146,25 +170,53 @@ Task({
 // Results available when all complete
 ```
 
-### Step 5: Monitor Progress
+### Step 5: Monitor Progress (Real-time TUI)
 
-Check mailbox for worker status:
+Monitor with beautiful block UI:
 
 ```typescript
-swarm_helper({
-  operation: "getTeamStatus",
+// Render beautiful TUI block
+const ui = await swarm_monitor({
+  operation: "render_block",
   team_name: "$ARGUMENTS-swarm",
-  limit: 20,
+});
+console.log(ui); // Markdown block with tables, emojis, progress
+
+// Check detailed status
+const status = await swarm_monitor({
+  operation: "status",
+  team_name: "$ARGUMENTS-swarm",
+});
+const stats = JSON.parse(status).summary;
+
+// Check mailbox for messages
+const messages = await swarm_monitor({
+  operation: "mail_read",
+  team_name: "$ARGUMENTS-swarm",
+  limit: 10,
 });
 ```
 
 ### Step 6: Handle Worker Reports
 
-| Message | Action                                  |
-| ------- | --------------------------------------- |
-| DONE    | Mark subtask complete, continue waiting |
-| ERROR   | Analyze, fix locally or respawn         |
-| BLOCKED | Resolve blocker, send guidance          |
+Parse messages from swarm-monitor mail_read:
+
+| Message Type | Detection                         | Action                                 |
+| ------------ | --------------------------------- | -------------------------------------- |
+| DONE         | msg.message starts with "DONE"    | Mark subtask complete, check progress  |
+| ERROR        | msg.message starts with "ERROR"   | Analyze, fix locally or respawn worker |
+| BLOCKED      | msg.message starts with "BLOCKED" | Resolve blocker, send guidance         |
+| PROGRESS     | status from progress_update       | Update TUI, check for bottlenecks      |
+
+```typescript
+// Example: Handle errors
+for (const msg of JSON.parse(messages)) {
+  if (msg.message?.startsWith("ERROR")) {
+    console.log(`Worker ${msg.from_worker} failed: ${msg.message}`);
+    // Respawn or fix
+  }
+}
+```
 
 ### Step 7: Final Verification
 
@@ -175,9 +227,16 @@ After all workers complete:
 npm run typecheck && npm run lint && npm test
 ```
 
-### Step 8: Close Epic
+### Step 8: Close Epic & Cleanup
 
 ```bash
+# Clear swarm data
+await swarm_monitor({
+  operation: "clear",
+  team_name: "$ARGUMENTS-swarm"
+});
+
+# Close the epic
 bd close $ARGUMENTS --reason "Swarm completed all subtasks: <summary>"
 ```
 

package/dist/template/.opencode/{command → commands}/new-feature.md

@@ -13,6 +13,7 @@ Create a complete feature track with Epic → Task → Subtask hierarchy, proper
 ```typescript
 skill({ name: "beads" });
 skill({ name: "brainstorming" });
+skill({ name: "swarm-coordination" }); // For parallel task execution with Kimi K2.5 PARL
 ```
 
 ## Parse Arguments
@@ -452,9 +453,11 @@ npm test
 
 ---
 
-## Phase 8: Parallel Task Execution (Optional)
+## Phase 8: Parallel Task Execution with Swarm (Kimi K2.5 PARL)
 
-If multiple tasks are READY (no blockers), execute them in parallel:
+If multiple tasks are READY (no blockers), execute them in parallel using swarm coordination:
+
+### Step 1: Analyze Tasks for Parallelization
 
 ```bash
 # Check what's ready
@@ -462,49 +465,112 @@ bd ready --json
 ```
 
 ```typescript
-// Fire all READY tasks in parallel with auto-close
-background_start({
-  agent: "build",
-  prompt: `Execute bd-xxx1: [Task 1 description]
-
-    Context: This is part of epic [epic-id] for $ARGUMENTS
-
-    Requirements:
-    - Complete all work items in the task spec
-    - Run verification commands
-    - Commit changes with bead ID in message
-
-    Return: Summary of changes, files modified, verification results`,
-  beadId: "bd-xxx1",
-  autoCloseBead: true,
-  title: "task-1-execution"
-})  // → bg_task1
-
-background_start({
-  agent: "build",
-  prompt: `Execute bd-xxx2: [Task 2 description]...`,
-  beadId: "bd-xxx2",
-  autoCloseBead: true,
-  title: "task-2-execution"
-})  // → bg_task2
-
-// Collect results when done
-background_output({ taskId: "bg_task1" })  // → beadClosed: true
-background_output({ taskId: "bg_task2" })  // → beadClosed: true
-
-// Check what's now unblocked
-bd ready  // → Tasks that were blocked by xxx1, xxx2 now READY
+// Get all READY tasks
+const readyTasks = await getReadyTasks($ARGUMENTS);
+
+// Analyze if swarm mode is beneficial
+const analysis = await swarm_plan({
+  operation: "analyze",
+  task: `Implement ${$ARGUMENTS} with ${readyTasks.length} parallel tasks`,
+  files: readyTasks.map((t) => t.files).join(","),
+});
+
+console.log(`Classification: ${analysis.classification.type}`);
+console.log(`Recommended agents: ${analysis.classification.recommended_agents}`);
+```
+
+### Step 2: Setup Swarm Coordination
+
+```typescript
+const teamName = `${$ARGUMENTS}-swarm-${Date.now()}`;
+
+// Create delegation packets for each READY task
+for (const task of readyTasks) {
+  swarm_delegate({
+    bead_id: task.id,
+    title: `Execute ${task.id}: ${task.title}`,
+    expected_outcome: "Task completed with verification passing",
+    required_tools: "read, grep, lsp, edit, bash",
+    must_do: "LSP before edits, run verification, report progress via swarm-monitor",
+    must_not_do: "No new deps, don't edit files outside task scope",
+    acceptance_checks: "typecheck: npm run typecheck, lint: npm run lint, test: npm test",
+    context: `Part of epic ${$ARGUMENTS}. Team: ${teamName}`,
+    write: true,
+  });
+}
+```
+
+### Step 3: Spawn Worker Swarm
+
+```typescript
+// Launch all workers in parallel
+for (const task of readyTasks) {
+  Task({
+    subagent_type: "build",
+    description: `Execute ${task.id}`,
+    prompt: `Execute bead ${task.id}: ${task.title}
+
+## Delegation
+Read: .beads/artifacts/${task.id}/delegation.md
+
+## Coordination
+Team: ${teamName}
+Worker: worker-${task.id}
+
+## Protocol
+1. Read delegation packet
+2. Report START: swarm-monitor({ operation: "progress_update", team_name: "${teamName}", worker_id: "worker-${task.id}", phase: "implement", progress: 0, status: "working" })
+3. Execute task
+4. Report PROGRESS (every 25%): swarm-monitor({ operation: "progress_update", ...progress: 25/50/75, file: "current-file.ts" })
+5. Run acceptance checks
+6. Report DONE: swarm-monitor({ operation: "progress_update", ...progress: 100, status: "completed" })
+7. Send completion: swarm-monitor({ operation: "mail_send", team_name: "${teamName}", from_worker: "worker-${task.id}", message: "DONE: ${task.title} completed" })
+8. Close bead: bd close ${task.id} --reason "Completed via swarm"`,
+  });
+}
+```
+
+### Step 4: Monitor with TUI
+
+```typescript
+// Monitor loop with beautiful UI
+let allComplete = false;
+while (!allComplete) {
+  // Render TUI block
+  const ui = await swarm_monitor({
+    operation: "render_block",
+    team_name: teamName
+  });
+  console.log(ui);
+
+  // Check status
+  const status = await swarm_monitor({
+    operation: "status",
+    team_name: teamName
+  });
+  const stats = JSON.parse(status).summary;
+
+  allComplete = stats.completed === stats.total_workers;
+
+  if (!allComplete) {
+    await new Promise(r => setTimeout(r, 3000));
+  }
+}
 
 // Cleanup
-background_cancel({ all: true })
+await swarm_monitor({ operation: "clear", team_name: teamName });
+
+// Check newly unblocked tasks
+bd ready  // → Tasks that were blocked now READY
 ```
 
-**Parallel Execution Rules:**
+**Swarm Execution Rules:**
 
 - Only fire tasks that are READY (no unresolved blockers)
-- Each background task gets its own build agent session
-- Beads auto-close on successful completion
-- Check `bd ready` after each batch to find newly unblocked tasks
+- Use `swarm-plan analyze` to determine optimal agent count
+- Workers report progress via `swarm-monitor progress_update`
+- Monitor with `swarm-monitor render_block` for TUI
+- Cleanup with `swarm-monitor clear` when done
 
 ---
 

package/dist/template/.opencode/{command → commands}/research-ui.md

@@ -212,7 +212,7 @@ context7_resolve_library_id({
 });
 
 // Real-world implementations
-grep_search({
+grepsearch({
   query: "[pattern to find]",
   language: ["TypeScript", "TSX"],
   path: "components/",

package/dist/template/.opencode/{command → commands}/research.md

@@ -25,10 +25,30 @@ if (thorough) {
 
 // For source code analysis
 skill({ name: "source-code-research" });
+
+// For swarm coordination (if parallel research needed)
+skill({ name: "swarm-coordination" });
 ```
 
 ## Delegation Strategy
 
+### Step 1: Classify Research Task
+
+```typescript
+// Analyze if research benefits from parallelization
+const analysis = await swarm_plan({
+  operation: "analyze",
+  task: "Research " + $ARGUMENTS,
+  files: "<detected files or leave empty for external research>",
+});
+
+// For search-type research with multiple sources, use swarm
+if (analysis.classification.type === "search" && analysis.classification.recommended_agents > 1) {
+  console.log(`Research classified as ${analysis.classification.type}`);
+  console.log(`Recommended: ${analysis.classification.recommended_agents} parallel agents`);
+}
+```
+
 ### Internal Codebase → @explore
 
 Delegate LSP exploration to the explore agent:
@@ -50,17 +70,44 @@ Return file:line references for all findings.`,
 
 ### External Research → @scout (this agent)
 
-Scout handles external sources (context7, grep_search, codesearch, etc.)
+Scout handles external sources (context7, grepsearch, codesearch, etc.)
 
-### Parallel Execution
+### Parallel Execution (Swarm Mode for Research)
 
-Run internal and external research in parallel:
+For comprehensive research across multiple domains, use parallel agents:
 
 ```typescript
+// Option A: Simple parallel (2-3 agents)
 // Launch both in parallel
 task({ subagent_type: "explore", prompt: "LSP analysis of..." });
 context7_resolve_library_id({ libraryName: "<lib>" });
-grep_search({ query: "<pattern>", language: "TypeScript" });
+grepsearch({ query: "<pattern>", language: "TypeScript" });
+
+// Option B: Swarm mode for complex multi-domain research
+// Use when researching 3+ different areas simultaneously
+const teamName = `research-${Date.now()}`;
+
+// Spawn research workers
+Task({
+  subagent_type: "explore",
+  description: "Research domain A",
+  prompt: `Research [domain A] for ${$ARGUMENTS}...
+Report via swarm-monitor: progress_update + mail_send to team ${teamName}`,
+});
+
+Task({
+  subagent_type: "scout",
+  description: "Research domain B",
+  prompt: `Research [domain B] for ${$ARGUMENTS}...
+Report via swarm-monitor: progress_update + mail_send to team ${teamName}`,
+});
+
+// Monitor progress
+const ui = await swarm_monitor({
+  operation: "render_block",
+  team_name: teamName,
+});
+console.log(ui);
 ```
 
 ## Load Context
@@ -107,7 +154,7 @@ If memory search fails (Ollama not running), continue to external sources.
 2. **Official docs** (high trust) - What does the library documentation say?
 3. **Context7** (high trust) - API usage and examples
 4. **Source code** (high trust) - Library implementation (use `source-code-research` skill)
-5. **GitHub examples** (medium trust) - Real-world patterns via codesearch/grep_search
+5. **GitHub examples** (medium trust) - Real-world patterns via codesearch/grepsearch
 6. **Web search** (lower trust) - Only if tiers 1-5 don't answer
 
 ## Research
@@ -161,7 +208,7 @@ npx opensrc <owner>/<repo>         # GitHub repo
 
 ```typescript
 codesearch({ query: "<API usage pattern>", tokensNum: 5000 });
-grep_search({ query: "<code pattern>", language: "TypeScript" });
+grepsearch({ query: "<code pattern>", language: "TypeScript" });
 ```
 
 ## Validate Findings

package/dist/template/.opencode/memory/observations/2026-01-28-decision-gh-grep-mcp-wrapper-vs-native-grep-searc.md

@@ -4,18 +4,18 @@ created: 2026-01-28T16:59:35.621Z
 confidence: high
 valid_until: null
 superseded_by: null
-concepts: ["grep-search", "MCP", "native tool", "architecture", "best practices"]
+concepts: ["grepsearch", "MCP", "native tool", "architecture", "best practices"]
 ---
 
-# 🎯 gh-grep MCP wrapper vs native grep-search tool
+# 🎯 gh-grep MCP wrapper vs native grepsearch tool
 
 🟢 **Confidence:** high
 
 Created two implementations for GitHub code search:
 
-1. **Native tool** (.opencode/tool/grep-search.ts): TypeScript wrapper around grep.app API - WORKING ✅
+1. **Native tool** (.opencode/tool/grepsearch.ts): TypeScript wrapper around grep.app API - WORKING ✅
 2. **MCP skill** (.opencode/skill/gh-grep/): Skill wrapper that calls uvx grep-mcp server - BROKEN ❌
 
-The MCP server has an argument parsing bug ('str' object has no attribute 'get') that prevents tool execution. Even the SKILL.md documentation admits: "Note: The MCP server (grep-mcp) may have bugs. The native grep_search tool is recommended."
+The MCP server has an argument parsing bug ('str' object has no attribute 'get') that prevents tool execution. Even the SKILL.md documentation admits: "Note: The MCP server (grep-mcp) may have bugs. The native grepsearch tool is recommended."
 
 **Key insight**: We already documented the problem and recommended against the MCP approach. The native tool works perfectly and doesn't require external process dependencies.

package/dist/template/.opencode/memory/observations/2026-01-29-decision-copilot-auth-plugin-rate-limit-handling.md

@@ -0,0 +1,27 @@
+---
+type: decision
+created: 2026-01-29T14:26:09.644Z
+confidence: high
+valid_until: null
+superseded_by: null
+concepts: ["copilot", "claude", "rate-limit", "retry", "exponential-backoff", "anthropic-sdk", "reasoning"]
+files: [".opencode/plugin/copilot-auth.ts"]
+---
+
+# 🎯 Copilot Auth Plugin Rate Limit Handling
+
+🟢 **Confidence:** high
+
+Implemented retry logic with exponential backoff for Copilot auth plugin to handle 429 rate limit errors while preserving Claude reasoning support.
+
+Changes made to .opencode/plugin/copilot-auth.ts:
+1. Added RATE_LIMIT_CONFIG with maxRetries: 3, baseDelayMs: 2000, maxDelayMs: 30000
+2. Added calculateRetryDelay() function with exponential backoff + jitter
+3. Wrapped fetch() call in retry loop that handles:
+   - HTTP 429 (Too Many Requests) with automatic retry
+   - Network errors with automatic retry
+   - Console logging for debugging retry attempts
+
+Retry delays: ~2s, ~4s, ~8s (with random jitter)
+
+This allows using Claude Opus 4.5 and Haiku 4.5 with reasoning support through Anthropic SDK while gracefully handling rate limit issues instead of failing immediately.

package/dist/template/.opencode/memory/observations/2026-01-29-decision-spec-driven-approach-for-opencodekit.md

@@ -0,0 +1,21 @@
+---
+type: decision
+created: 2026-01-29T15:07:22.755Z
+confidence: high
+valid_until: null
+superseded_by: null
+concepts: ["spec-driven", "code-generation", "agent-prompts", "templates", "testing"]
+---
+
+# 🎯 Spec-driven approach for OpenCodeKit
+
+🟢 **Confidence:** high
+
+After analyzing the 'no-code library' article, decided NOT to apply spec-driven generation to agent prompts themselves (too non-deterministic for production). Instead, adopt these principles:
+
+1. Specs-first design for agent prompts - define expected behavior clearly
+2. Portable test cases for CLI integration tests (language-agnostic YAML)
+3. Generated scaffolding/templates for the `init` command to create OpenCode projects
+4. Keep agent prompts as actual code for determinism and version control
+
+Key insight: Specs are the primary artifact for utilities/scaffolding, but code is primary for core agent behavior.