opencodekit 0.14.0 → 0.14.2

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

@@ -46,8 +46,43 @@ Before acting, answer three questions in your head:
 
 **Is this mine to do?** Rush handles well-defined, localized (1-3 files), greenfield tasks. If any of these fail—ambiguous scope, system-wide changes, or legacy code with hidden invariants—delegate immediately. Don't power through complexity; avoid it.
 
+**Do I need to clarify?** If the request is ambiguous and wrong interpretation wastes significant effort, use the `question` tool to ask ONE focused question. But keep it rare—Rush moves fast. If you're unsure, delegate to @build who handles complexity better.
+
 **Do I need to read first?** If you're about to edit a file you haven't seen, stop. Read it. Never speculate about uninspected code.
 
+## Using the Question Tool (Sparingly)
+
+Rush uses questions rarely—only when wrong interpretation would waste significant effort AND the task is still small enough for Rush.
+
+**Good triggers (still ask fast):**
+
+- "Delete this" → Ask: Which files/branches specifically?
+- "Rename X" → Ask: New name preference?
+- Binary choice that user must decide
+
+**Bad triggers (delegate instead):**
+
+- "Add auth" → Too complex for Rush, delegate to @build
+- Multiple design decisions → Delegate to @planner
+- Research needed → Delegate to @scout
+
+**If you need to ask more than ONE question, the task is too complex for Rush. Delegate.**
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Confirm",
+      question: "Delete feature/old-auth branch?",
+      options: [
+        { label: "Yes, delete it", description: "Removes remote and local" },
+        { label: "No, keep it", description: "Abort operation" },
+      ],
+    },
+  ],
+});
+```
+
 ## Bail Triggers
 
 Delegate immediately when you hit any of these:
@@ -96,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.
@@ -114,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,7 @@ tools:
   edit: false
   write: false
   bash: false
-  memory-update: false
+  question: false
 ---
 
 # Scout Agent

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/brainstorm.md

@@ -275,7 +275,56 @@ bd create "[Idea name]" -t task -p 2
 
 ## Output
 
+```markdown
+Brainstorm Complete: $ARGUMENTS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Duration: [N] minutes
+Ideas generated: [N]
+Ideas evaluated: [N]
+
+Top 3:
+
+1. [Idea 1] - Score: [N]
+2. [Idea 2] - Score: [N]
+3. [Idea 3] - Score: [N]
+
+Recommendation: [Chosen approach]
+Confidence: [High/Medium/Low]
+
+Artifacts:
+
+- .beads/artifacts/<bead-id>/brainstorm.md (if bead)
+- Observation created ✓
+
+Follow-up beads: [N] created
 ```
+
+**Use question tool for next steps:**
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Next Step",
+      question: "What should we do next with $ARGUMENTS?",
+      options: [
+        {
+          label: "Research approach (Recommended)",
+          description: "Validate with /research",
+        },
+        { label: "Create implementation plan", description: "Plan with /plan" },
+        {
+          label: "Explore more",
+          description: "Continue brainstorming other aspects",
+        },
+        { label: "Done for now", description: "Save findings, revisit later" },
+      ],
+    },
+  ],
+});
+```
+
 Brainstorm Complete: $ARGUMENTS
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
@@ -284,6 +333,7 @@ Ideas generated: [N]
 Ideas evaluated: [N]
 
 Top 3:
+
 1. [Idea 1] - Score: [N]
 2. [Idea 2] - Score: [N]
 3. [Idea 3] - Score: [N]
@@ -292,21 +342,25 @@ Recommendation: [Chosen approach]
 Confidence: [High/Medium/Low]
 
 Artifacts:
+
 - .beads/artifacts/<bead-id>/brainstorm.md (if bead)
 - Observation created ✓
 
 Follow-up beads: [N] created
+
 ```
 
 **Next steps:**
 
 ```
+
 If ready to proceed:
-  /research <bead-id>   # Validate approach
-  /plan <bead-id>       # Create implementation plan
+/research <bead-id> # Validate approach
+/plan <bead-id> # Create implementation plan
 
 If need more exploration:
-  /brainstorm <new-aspect>   # Continue ideation
+/brainstorm <new-aspect> # Continue ideation
+
 ```
 
 ## Anti-Patterns
@@ -316,3 +370,4 @@ If need more exploration:
 - ❌ **Infinite brainstorming** - Time box and decide
 - ❌ **No decision** - Brainstorming must produce a recommendation
 - ❌ **No capture** - Undocumented ideas are lost ideas
+```

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

@@ -116,17 +116,27 @@ git commit -m "$ARGUMENTS: [what was done]
 Closes: $ARGUMENTS"
 ```
 
-## Close The Task (Ask First)
+## Close The Task (Use Question Tool)
 
-**Ask the user:**
-
-```
-Close bead $ARGUMENTS?
-- Yes, close it
-- No, keep it open for now
+```typescript
+question({
+  questions: [
+    {
+      header: "Close",
+      question: "Should I close bead $ARGUMENTS?",
+      options: [
+        {
+          label: "Yes, close it (Recommended)",
+          description: "All gates passed, task complete",
+        },
+        { label: "No, keep open", description: "Need more work or review" },
+      ],
+    },
+  ],
+});
 ```
 
-If user confirms:
+If user confirms close:
 
 ```bash
 bd close $ARGUMENTS --reason "Completed: [1-line summary]"

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

@@ -115,23 +115,32 @@ git status
 git diff --cached --stat
 ```
 
-**Present to user:**
+**Use question tool to get commit decision:**
 
+```typescript
+question({
+  questions: [
+    {
+      header: "Commit",
+      question: "Fix Complete: $ARGUMENTS. What should I do next?",
+      options: [
+        {
+          label: "Commit changes (Recommended)",
+          description: "Git commit and bd sync",
+        },
+        {
+          label: "Show diff first",
+          description: "Review changes before committing",
+        },
+        {
+          label: "Skip commit",
+          description: "I'll review and commit manually",
+        },
+      ],
+    },
+  ],
+});
 ```
-Fix Complete: $ARGUMENTS
-━━━━━━━━━━━━━━━━━━━━━━━
-
-Root cause: [brief]
-Changes: [files]
-Tests: Pass ✓
-
-Would you like me to:
-1. Commit these changes
-2. Show full diff first
-3. Skip commit (I'll review manually)
-```
-
-**Wait for user confirmation before committing.**
 
 If user confirms:
 

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
@@ -67,7 +99,25 @@ If dirty, ask whether to stash, commit, or continue.
 Create a branch if not already on one for this task:
 
 ```bash
-git checkout -b $ARGUMENTS 2>/dev/null || echo "Already on branch"
+# Get current branch (parent branch)
+PARENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+# Get task title for readable branch name
+BEAD_INFO=$(bd show $ARGUMENTS --json 2>/dev/null)
+BEAD_TITLE=$(echo "$BEAD_INFO" | jq -r '.title // ""' | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | cut -c1-40)
+BEAD_TYPE=$(echo "$BEAD_INFO" | jq -r '.type // "task"')
+
+# Map bead type to branch prefix
+case "$BEAD_TYPE" in
+  "bug") PREFIX="fix" ;;
+  "feature"|"epic") PREFIX="feat" ;;
+  "refactor") PREFIX="refactor" ;;
+  *) PREFIX="feat" ;;
+esac
+
+# Create branch: <parent>/<type>/<bead-id>-<description>
+BRANCH_NAME="${PARENT_BRANCH}/${PREFIX}/$ARGUMENTS-${BEAD_TITLE}"
+git checkout -b "$BRANCH_NAME" 2>/dev/null || echo "Already on branch"
 ```
 
 Mark the task in progress (if not already):
@@ -104,7 +154,7 @@ First, get a quick codebase overview:
 
 ```typescript
 // Quick overview of relevant directories
-repo-map({ path: "src", format: "compact", maxDepth: 3 });
+repo - map({ path: "src", format: "compact", maxDepth: 3 });
 ```
 
 Then search for relevant patterns and learnings:
@@ -138,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 |
 | -------- | ------------------------------ | ---------------- | ---------------- |
@@ -296,26 +355,33 @@ git status
 git diff --cached --stat
 ```
 
-**Present to user:**
-
-```
-Implementation Complete: $ARGUMENTS
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Type: [epic/task/subtask]
-Tests: Pass ✓
-Changes: [files modified]
-
-Subtasks: [N completed / M total] (if applicable)
+**Use question tool to get commit decision:**
 
-Would you like me to:
-1. Commit these changes
-2. Show full diff first
-3. Skip commit (I'll review manually)
+```typescript
+question({
+  questions: [
+    {
+      header: "Commit",
+      question: "Implementation Complete: $ARGUMENTS. What should I do next?",
+      options: [
+        {
+          label: "Commit changes (Recommended)",
+          description: "Git commit and bd sync",
+        },
+        {
+          label: "Show diff first",
+          description: "Review changes before committing",
+        },
+        {
+          label: "Skip commit",
+          description: "I'll review and commit manually",
+        },
+      ],
+    },
+  ],
+});
 ```
 
-**Wait for user confirmation before committing.**
-
 If user confirms:
 
 ```bash

package/dist/template/.opencode/command/import-plan.md

@@ -46,7 +46,7 @@ Before importing, check for existing beads with similar titles:
 
 Compare plan titles against existing beads:
 
-```
+````
 Duplicate Check:
 ━━━━━━━━━━━━━━━━
 
@@ -59,8 +59,19 @@ Options:
 2. Force import (create duplicates)
 3. Cancel import
 
-Select option (1/2/3):
-```
+```typescript
+question({
+  questions: [{
+    header: "Duplicates",
+    question: "Potential duplicates found. What should I do?",
+    options: [
+      { label: "Skip duplicates (Recommended)", description: "Import only new items" },
+      { label: "Force import", description: "Create duplicate beads anyway" },
+      { label: "Cancel import", description: "Stop and review plan" }
+    ]
+  }]
+});
+````
 
 If `--force` flag set, skip this check and import everything.
 
@@ -78,7 +89,7 @@ Parse the plan for:
 
 Report:
 
-```
+````
 Plan Analysis: [filename]
 ━━━━━━━━━━━━━━━━━━━━━━━━
 
@@ -95,10 +106,21 @@ Structure:
 │   └── [Issue 1] [L] → depends on [Epic 1/Issue 2]
 └── ...
 
-Proceed with import? (yes/modify/cancel)
-```
-
-**STOP and wait for approval** (unless `--dry-run`, then just show preview).
+```typescript
+question({
+  questions: [{
+    header: "Import",
+    question: "Plan analyzed. Should I proceed with import?",
+    options: [
+      { label: "Proceed with import (Recommended)", description: "Create epics and issues" },
+      { label: "Modify plan", description: "Need changes before importing" },
+      { label: "Cancel", description: "Stop and review plan" }
+    ]
+  }]
+});
+````
+
+**STOP and wait for user approval** (unless `--dry-run`, then just show preview).
 
 ---
 

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
@@ -142,10 +144,34 @@ Key risks identified:
 - [Risk 1]: Mitigation: [...]
 - [Risk 2]: Mitigation: [...]
 
-Proceed with spec? (yes/modify/explore-more)
 ```
 
-**STOP and wait for approval** before proceeding.
+**STOP. Use question tool to get user approval:**
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Approve",
+      question:
+        "Should I proceed with creating the specification for $ARGUMENTS?",
+      options: [
+        {
+          label: "Yes, proceed",
+          description: "Approach looks good, create spec",
+        },
+        {
+          label: "Modify approach",
+          description: "Need changes to brainstorming",
+        },
+        { label: "Explore more", description: "Need more research first" },
+      ],
+    },
+  ],
+});
+```
+
+**Wait for user's answer before proceeding to spec creation.**
 
 ---
 
@@ -398,8 +424,17 @@ skill({ name: "using-git-worktrees" });
 # Ensure .gitignore has worktree directory
 grep -q "^\.worktrees/$" .gitignore || echo ".worktrees/" >> .gitignore
 
-# Create worktree for the epic
-git worktree add .worktrees/[epic-id] -b feature/[feature-name]
+# Get current branch (parent branch)
+PARENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+# Create readable branch name from feature name
+FEATURE_SLUG=$(echo "[feature-name]" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | cut -c1-40)
+
+# Create branch: <parent>/feat/<epic-id>-<description>
+BRANCH_NAME="${PARENT_BRANCH}/feat/[epic-id]-${FEATURE_SLUG}"
+
+# Create worktree for the epic with readable branch
+git worktree add ".worktrees/[epic-id]" -b "$BRANCH_NAME"
 
 # Setup in worktree
 cd .worktrees/[epic-id]
@@ -418,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