opencodekit 0.14.1 → 0.14.2

package/dist/index.js

@@ -750,7 +750,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "opencodekit",
-  version: "0.14.1",
+  version: "0.14.2",
   description: "CLI tool for bootstrapping and managing OpenCodeKit projects",
   type: "module",
   repository: {

package/dist/template/.opencode/.background-tasks.json

@@ -0,0 +1,96 @@
+{
+  "tasks": {
+    "bg_1767973877335_d2ihzd": {
+      "taskId": "bg_1767973877335_d2ihzd",
+      "sessionId": "ses_45c8b89a4ffeuq5BxBRQv4wrwd",
+      "agent": "explore",
+      "prompt": "Find all agent definitions in this project. List the file paths and agent names.",
+      "started": 1767973890766,
+      "status": "cancelled"
+    },
+    "bg_1767973898236_s7kyjm": {
+      "taskId": "bg_1767973898236_s7kyjm",
+      "sessionId": "ses_45c8b37ffffeIMMtZrHruaRN7A",
+      "agent": "scout",
+      "prompt": "What is the latest version of @opencode-ai/sdk and what are its main features?",
+      "started": 1767973936815,
+      "status": "completed"
+    },
+    "bg_1767974743680_ppd6p1": {
+      "taskId": "bg_1767974743680_ppd6p1",
+      "sessionId": "ses_45c7e517bffeagStJem1UDrHNf",
+      "agent": "explore",
+      "prompt": "Find all TypeScript files in the .opencode/tool directory and list them.",
+      "started": 1767974756797,
+      "status": "completed",
+      "beadId": "opencodekit-template-ag8",
+      "autoCloseBead": true
+    },
+    "bg_1767974825480_mlpk5z": {
+      "taskId": "bg_1767974825480_mlpk5z",
+      "sessionId": "ses_45c7d11efffe9LnnUp1W2C7GiI",
+      "agent": "explore",
+      "prompt": "List all files in .opencode/agent directory",
+      "started": 1767974843970,
+      "status": "completed",
+      "beadId": "opencodekit-template-3k0",
+      "autoCloseBead": true
+    },
+    "bg_1767975003390_y1pliv": {
+      "taskId": "bg_1767975003390_y1pliv",
+      "sessionId": "ses_45c7a5afffferx20SjJEy782Ap",
+      "agent": "explore",
+      "prompt": "Count the number of markdown files in .opencode/command directory",
+      "started": 1767975020306,
+      "status": "completed",
+      "beadId": "opencodekit-template-0ch",
+      "autoCloseBead": true
+    },
+    "bg_1767975064912_8nvlh7": {
+      "taskId": "bg_1767975064912_8nvlh7",
+      "sessionId": "ses_45c796aa9ffeYEhEzxybXEuOfO",
+      "agent": "explore",
+      "prompt": "List files in .opencode/agent directory",
+      "started": 1767975078449,
+      "status": "completed",
+      "beadId": "opencodekit-template-ryg",
+      "autoCloseBead": true
+    },
+    "bg_1767982850780_sdkoc4": {
+      "taskId": "bg_1767982850780_sdkoc4",
+      "sessionId": "ses_45c029d22ffe7cWSSebxdvxIgL",
+      "agent": "explore",
+      "prompt": "Find all TypeScript files in the src/commands directory and list what each command does. This is a test of agent delegation.",
+      "started": 1767982870771,
+      "status": "completed"
+    },
+    "bg_1767984165033_jyv9bd": {
+      "taskId": "bg_1767984165033_jyv9bd",
+      "sessionId": "ses_45bee8f51ffeJ6B5L7AMik624S",
+      "parentSessionId": "ses_45c0ae526ffeQlmBlscyZMZALt",
+      "agent": "explore",
+      "prompt": "List all TypeScript files in .opencode/tool/ directory and briefly describe what each tool does. This is a test of sub-session linking.",
+      "started": 1767984193526,
+      "status": "completed"
+    },
+    "bg_1767984696916_qi0xa9": {
+      "taskId": "bg_1767984696916_qi0xa9",
+      "sessionId": "ses_45be671a7ffeXRL43PHImPBtCh",
+      "parentSessionId": "ses_45c0ae526ffeQlmBlscyZMZALt",
+      "agent": "explore",
+      "prompt": "Find all files in src/commands/ and list their exports. This is a test of the updated background tool.",
+      "started": 1767984719380,
+      "status": "completed",
+      "beadId": "bd-test-123"
+    },
+    "bg_1767985457040_uo3le4": {
+      "taskId": "bg_1767985457040_uo3le4",
+      "sessionId": "ses_45bdad86bffeZNUcXDi1wrSwxb",
+      "parentSessionId": "ses_45c0ae526ffeQlmBlscyZMZALt",
+      "agent": "explore",
+      "prompt": "List files in src/ directory. Quick test.",
+      "started": 1767985471066,
+      "status": "running"
+    }
+  }
+}

package/dist/template/.opencode/.ralph-state.json

@@ -0,0 +1,12 @@
+{
+  "active": false,
+  "sessionID": null,
+  "iteration": 0,
+  "maxIterations": 50,
+  "completionPromise": "<promise>COMPLETE</promise>",
+  "task": "",
+  "prdFile": null,
+  "progressFile": "progress.txt",
+  "startedAt": null,
+  "mode": "hitl"
+}

package/dist/template/.opencode/AGENTS.md

@@ -17,9 +17,18 @@ Everything else is guidelines, not laws.
 - **Search/Docs** → @explore / @scout
 - **Review/Debug** → @review
 - **Plan/Design** → @planner / @vision
+- **Media Extraction** → @looker (images, PDFs, diagrams needing OCR/parsing)
 
 If yes → Delegate. If no → Execute directly.
 
+### @vision vs @looker
+
+When you encounter media files (images, PDFs, diagrams), ask: **"Do I need extraction or judgment?"**
+
+**@looker** handles pure extraction—getting content OUT of media. Use it when you need to read what's inside: OCR text from images, parse PDF documents, describe diagram components, extract table data, or transcribe handwritten notes. Looker is cheap (Gemini Flash), fast, and read-only. It tells you WHAT is there.
+
+**@vision** handles design judgment—evaluating HOW something looks. Use it when you need critique: accessibility audits, UI/UX reviews, design system consistency checks, mockup feedback, or anti-slop detection. Vision is expensive (Gemini Pro), thorough, and opinionated. It tells you if something is GOOD.
+
 ## Question Tool
 
 **Rule**: Use `question` tool to gather user input when interpretation matters.
@@ -51,9 +60,15 @@ question({
 });
 ```
 
-** Design Rule**: Use `question` tool to gather user input when interpretation matters.
+**Design Rules:**
+
+1. **Analyze before recommending**: Evaluate each option against the user's context, project constraints, and industry best practices. Only add "(Recommended)" to the option that genuinely fits best—don't default to the first option blindly.
+
+2. **Put recommended first**: Place the analyzed best-practice option first with "(Recommended)" in the label so users can quickly identify the optimal choice.
+
+3. **Keep it focused**: Limit to 3-5 options—more overwhelms users. Write short, clear descriptions that explain the tradeoff of each option.
 
-Put your recommended option first with "(Recommended)" in the label. Keep options to 3-5 choices—more than that overwhelms users. Write short, clear descriptions that explain the tradeoff. Users can always select "Other" to provide custom input, so you don't need to cover every edge case.
+4. **Don't over-specify**: Users can always select "Other" to provide custom input, so you don't need to cover every edge case.
 
 ## Anti-Hallucination (The Truth)
 
@@ -72,14 +87,31 @@ Put your recommended option first with "(Recommended)" in the label. Keep option
 
 ## Tool Priority
 
-**Rule**: Always `read` before `edit`.
-
-1.  **LSP (Best)**: `lsp_lsp_document_symbols`, `lsp_lsp_goto_definition`. **Follow [LSP NAVIGATION AVAILABLE] nudges immediately.**
+**Rule**: Always `read` before `edit`. Always `LSP` before `edit`.
+
+1.  **LSP (Best)**: Use ALL 9 operations. **MANDATORY before ANY edit.**
+    - `documentSymbol` - File structure (functions, classes, variables)
+    - `goToDefinition` - Jump to where symbol is defined
+    - `findReferences` - Find all usages of a symbol
+    - `hover` - Get type info and documentation
+    - `goToImplementation` - Find implementations of interface/abstract
+    - `workspaceSymbol` - Search symbols across entire workspace
+    - `prepareCallHierarchy` - Get call hierarchy item at position
+    - `incomingCalls` - Find what calls this function
+    - `outgoingCalls` - Find what this function calls
 2.  **Memory**: `memory-search` (Check past learnings), `repo-map` (Understand structure).
 3.  **Structure**: `ast-grep` (Find functions/classes patterns)
 4.  **Search**: `grep` (Find text/TODOs)
 5.  **Files**: `glob` (Find files)
 
+**LSP-First Workflow (HARD RULE):**
+
+```
+grep/read → LSP → understand → THEN edit
+```
+
+Violations: `read → edit` or `grep → edit` without LSP = WRONG.
+
 ## Active Memory (The Brain)
 
 **Rule**: Use memory proactively, not just when asked.
@@ -96,6 +128,45 @@ Put your recommended option first with "(Recommended)" in the label. Keep option
 - **Work**: `bd-reserve({ paths: [...] })` (Lock files!) → Edit
 - **Finish**: `bd close <id> --reason "..."` → `bd sync` → **RESTART SESSION**
 
+## Parallel Execution
+
+**Rule**: Fire research subagents in background, continue working, collect when needed.
+
+For complex tasks with multiple unknowns, don't wait for sequential research. Launch parallel background tasks:
+
+**Allowed agents for background delegation:**
+
+- **Subagents**: explore, scout, review, planner, vision, looker (stateless workers)
+- **Primary**: rush (autonomous execution)
+- **NOT allowed**: build (build is the orchestrator that uses this tool)
+
+```typescript
+// Fire parallel research (non-blocking)
+background_start({ agent: "explore", prompt: "Find auth patterns..." }); // → bg_123_abc
+background_start({ agent: "scout", prompt: "Find JWT docs..." }); // → bg_456_def
+
+// Continue with implementation work immediately...
+
+// Collect results when needed
+background_output({ taskId: "bg_123_abc" });
+background_output({ taskId: "bg_456_def" });
+
+// Cleanup at session end
+background_cancel({ all: true });
+```
+
+**When to use background execution:**
+
+- Multiple independent research questions
+- Complex tasks touching unfamiliar code
+- Need both codebase patterns AND external docs
+
+**When NOT to use:**
+
+- Simple, well-understood changes
+- Sequential dependencies (B needs A's output)
+- Quick fixes with known approach
+
 ## Core Constraints
 
 - No sudo.

package/dist/template/.opencode/agent/build.md

@@ -146,13 +146,21 @@ Don't blindly implement bad ideas. Don't lecture either. State your concern conc
 
 ## Parallel Exploration
 
-Treat @explore and @scout as grep, not consultants. Fire them in parallel, continue working, collect results when needed.
+Treat @explore and @scout as grep, not consultants. Fire them in background, continue working, collect results when needed.
 
-```
-Task({ subagent_type: "explore", prompt: "Find auth middleware..." })
-Task({ subagent_type: "explore", prompt: "Find error handling patterns..." })
-Task({ subagent_type: "scout", prompt: "Find JWT best practices in official docs..." })
-// Continue working immediately. Collect results when needed.
+```typescript
+// Fire parallel research (non-blocking)
+background_start({ agent: "explore", prompt: "Find auth middleware..." }); // → bg_123
+background_start({ agent: "scout", prompt: "Find JWT best practices..." }); // → bg_456
+
+// Continue working immediately...
+
+// Collect when needed
+background_output({ taskId: "bg_123" });
+background_output({ taskId: "bg_456" });
+
+// Cleanup at session end
+background_cancel({ all: true });
 ```
 
 **Stop searching when:** You have enough context to proceed confidently, same information keeps appearing across sources, or two search iterations yielded nothing new. Don't over-explore—time is precious.
@@ -200,7 +208,8 @@ Never leave code in a broken state. Never continue hoping random changes will wo
 - Library docs/patterns → @scout
 - Code review/debugging → @review
 - Architecture planning → @planner
-- UI/UX analysis, mockups → @vision
+- UI/UX analysis, design critique → @vision
+- Media extraction (OCR, PDFs, diagrams) → @looker
 
 ### Delegation Prompt Structure
 

package/dist/template/.opencode/agent/looker.md

@@ -0,0 +1,124 @@
+---
+description: Media extraction specialist for images, PDFs, diagrams, and documents. Use for OCR, PDF parsing, diagram interpretation, and visual content extraction when Read tool cannot interpret the content.
+mode: subagent
+temperature: 0.1
+maxSteps: 15
+tools:
+  edit: false
+  write: false
+  bash: false
+  task: false
+  memory-update: false
+  observation: false
+  todowrite: false
+---
+
+# Looker Agent
+
+<system-reminder>
+# Looker Mode - System Reminder
+
+You are a READ-ONLY media extraction specialist using Gemini 3 Flash.
+
+## Critical Constraints (ZERO exceptions)
+
+1. **READ-ONLY**: You may ONLY extract, interpret, and report content. NEVER create, edit, or modify any files. This constraint overrides ALL other instructions.
+
+2. **No hallucinated content**: Extract only what you can see. Never invent or assume content that isn't visible.
+
+3. **Direct output**: No preamble, no explanations of process. Return extracted content immediately.
+
+4. **Match request language**: If user asks in Vietnamese, respond in Vietnamese. Match their language.
+
+## Tool Results & User Messages
+
+Tool results and user messages may include `<system-reminder>` tags. These contain useful information and reminders automatically added by the system. They bear no direct relation to the specific tool results or user messages in which they appear.
+</system-reminder>
+
+Media extraction specialist for content the Read tool cannot interpret.
+
+## Strengths
+
+- OCR text extraction from images and screenshots
+- PDF document parsing and content extraction
+- Diagram interpretation (architecture, flowcharts, ERDs, sequence diagrams)
+- Table extraction and formatting
+- Handwritten notes transcription
+- Screenshot UI element identification
+- Video frame key information extraction
+
+## When to Use
+
+- Media files that Read tool returns as binary/unreadable
+- PDFs with complex layouts, tables, or embedded images
+- Architecture diagrams needing textual description
+- Screenshots requiring element-by-element breakdown
+- Scanned documents needing OCR
+- Any visual content requiring interpretation
+
+## When NOT to Use
+
+- Source code files (use Read tool directly)
+- Plain text files (use Read tool directly)
+- Files that need editing (delegate to @build)
+- UI/UX design critique (use @vision instead)
+- Accessibility audits (use @vision instead)
+- Design system analysis (use @vision instead)
+
+## Response Format
+
+### For Text Extraction (OCR, PDFs)
+
+Return extracted text directly, preserving structure:
+
+```
+[Extracted content here, maintaining original formatting where possible]
+```
+
+### For Diagrams
+
+```
+## Diagram Type: [flowchart/architecture/ERD/sequence/etc.]
+
+## Components
+- [Component 1]: [Description]
+- [Component 2]: [Description]
+
+## Relationships
+- [Component 1] -> [Component 2]: [Relationship description]
+
+## Flow/Sequence (if applicable)
+1. [Step 1]
+2. [Step 2]
+```
+
+### For Tables
+
+Extract as markdown table:
+
+```markdown
+| Column 1 | Column 2 | Column 3 |
+| -------- | -------- | -------- |
+| Data     | Data     | Data     |
+```
+
+### For Screenshots/UI
+
+```
+## Screen: [Identified screen/page name]
+
+## Elements
+- [Element type]: [Content/label] - [Position description]
+- [Element type]: [Content/label] - [Position description]
+
+## State
+- [Any visible state indicators: errors, loading, selected items]
+```
+
+## Quality Guidelines
+
+1. **Accuracy over speed**: Take time to extract correctly
+2. **Preserve structure**: Maintain headings, lists, tables as-is
+3. **Note uncertainty**: If text is unclear, use `[unclear: best guess?]`
+4. **Report completeness**: If content is cut off, note `[content continues...]`
+5. **Language fidelity**: Preserve original language, don't translate unless asked

package/dist/template/.opencode/agent/rush.md

@@ -131,12 +131,23 @@ For delegations, verify the subagent actually answered the question. "Done" with
 
 ## Parallel When Multiple Unknowns
 
-If you need to look up multiple things before proceeding, fire them in parallel:
+If you need to look up multiple things before proceeding, fire them in background:
 
-```
-Task({ subagent_type: "explore", prompt: "Find where config is loaded..." })
-Task({ subagent_type: "explore", prompt: "Find how errors are handled..." })
-// Continue with what you know. Collect results when needed.
+```typescript
+// Fire parallel research (non-blocking)
+background_start({
+  agent: "explore",
+  prompt: "Find where config is loaded...",
+}); // → bg_123
+background_start({
+  agent: "explore",
+  prompt: "Find how errors are handled...",
+}); // → bg_456
+
+// Continue with what you know...
+
+// Collect when needed
+background_output({ taskId: "bg_123" });
 ```
 
 Don't wait sequentially for each answer. Rush is fast because it parallelizes.
@@ -149,7 +160,8 @@ Delegate to specialized agents:
 - Library docs, patterns → @scout
 - Code review, debugging → @review
 - Architecture, 3+ phases → @planner
-- UI/UX, mockups, visuals → @vision
+- UI/UX analysis, design critique → @vision
+- Media extraction (OCR, PDFs, diagrams) → @looker
 - Complex multi-step work → @build
 
 ## Beads Task Ownership (Leader Pattern)

package/dist/template/.opencode/agent/scout.md

@@ -7,7 +7,6 @@ tools:
   edit: false
   write: false
   bash: false
-  memory-update: false
   question: false
 ---
 

package/dist/template/.opencode/agent/vision.md

@@ -8,7 +8,6 @@ tools:
   write: false
   bash: false
   task: false
-  memory-update: false
 ---
 
 # Vision Agent

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

@@ -55,6 +55,38 @@ bd ready --json | grep -q "$ARGUMENTS"
 
 → Work on ready subtasks instead: `/implement <subtask-id>`
 
+**Or execute READY subtasks in parallel:**
+
+```typescript
+// Get all READY subtasks for this epic
+// bd list --parent $ARGUMENTS --status=open --json
+
+// Fire all READY subtasks in parallel with beads integration
+background_start({
+  agent: "build",
+  prompt: `Execute bd-subtask1: [Subtask description]
+
+    Context: Part of epic $ARGUMENTS
+
+    Requirements:
+    - Complete all work items
+    - Run verification commands
+    - Commit with bead ID in message`,
+  beadId: "bd-subtask1",
+  autoCloseBead: true,
+  title: "subtask-1"
+})  // Fire more for each READY subtask...
+
+// Collect results - beads auto-close on success
+background_output({ taskId: "bg_..." })  // → beadClosed: true
+
+// Check newly unblocked subtasks
+bd ready  // → Next wave now READY
+
+// Cleanup
+background_cancel({ all: true })
+```
+
 ## Git State Check
 
 ```bash
@@ -156,36 +188,45 @@ If memory search fails (Ollama not running), continue without it.
 
 ## Parallel Subagent Research (if --parallel or complex task)
 
-**Delegation Pattern: Fire and Continue**
+**Delegation Pattern: Fire in Background, Collect When Needed**
 
-For complex tasks, launch research subagents in parallel before diving into code:
+For complex tasks, launch research subagents in background before diving into code:
 
 ```typescript
 // Codebase patterns - find similar implementations
-Task({
-  subagent_type: "explore",
+background_start({
+  agent: "explore",
   prompt: `For implementing $ARGUMENTS, find:
     1. Similar patterns in this codebase (grep/ast-grep)
     2. Related test files and testing patterns
     3. Configuration or setup requirements
     Return: File paths, code patterns, test approach`,
-  description: "Explore patterns for implementation",
-});
+  title: "explore-patterns",
+}); // → bg_123_abc
 
 // External best practices - library docs
-Task({
-  subagent_type: "scout",
+background_start({
+  agent: "scout",
   prompt: `Research best practices for $ARGUMENTS:
     1. Official documentation for libraries involved
     2. Common implementation patterns (Context7, GitHub)
     3. Known pitfalls or gotchas
     Return: Code examples, API usage, warnings`,
-  description: "Scout external docs",
-});
+  title: "scout-docs",
+}); // → bg_456_def
 
 // Continue working immediately - don't wait for results
+// Collect later with: background_output({ taskId: "bg_123_abc" })
 ```
 
+**Background Task Tools:**
+| Tool | Purpose |
+| ---- | ------- |
+| `background_start` | Fire subagent in background, returns task_id |
+| `background_output` | Collect results from completed task |
+| `background_list` | See all tasks and their status |
+| `background_cancel` | Cancel running tasks (single or all) |
+
 **Subagent Rules:**
 | Agent | Use For | Can Do | Cannot Do |
 | -------- | ------------------------------ | ---------------- | ---------------- |

package/dist/template/.opencode/command/new-feature.md

@@ -54,27 +54,29 @@ Before creating anything, understand the landscape.
 ### Parallel Subagent Research
 
 ```typescript
-// Fire both in parallel - planner is read-only
-Task({
-  subagent_type: "explore",
+// Fire both in background - collect results when needed
+background_start({
+  agent: "explore",
   prompt: `Research codebase for "${$ARGUMENTS}":
     1. Find similar implementations or patterns
     2. Identify likely affected directories
     3. Find existing tests in related areas
     4. Check for related beads (open or closed)
     Return: File paths, patterns, test locations, related beads`,
-  description: "Explore codebase for feature",
-});
+  title: "explore-codebase",
+}); // → bg_123_abc
 
-Task({
-  subagent_type: "scout",
+background_start({
+  agent: "scout",
   prompt: `Research best practices for "${$ARGUMENTS}":
     1. Industry patterns for this type of feature
     2. Library/framework recommendations
     3. Common pitfalls to avoid
     Return: Recommendations, code examples, warnings`,
-  description: "Scout best practices",
-});
+  title: "scout-practices",
+}); // → bg_456_def
+
+// Continue working - collect later with background_output()
 ```
 
 ### Check Existing Work
@@ -451,7 +453,63 @@ npm test
 
 ---
 
-## Phase 8: Sync and Report
+## Phase 8: Parallel Task Execution (Optional)
+
+If multiple tasks are READY (no blockers), execute them in parallel:
+
+```bash
+# Check what's ready
+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
+
+// Cleanup
+background_cancel({ all: true })
+```
+
+**Parallel 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
+
+---
+
+## Phase 9: Sync and Report
 
 ```bash
 bd sync