opencodekit 0.14.0 → 0.14.2

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

@@ -73,31 +73,35 @@ If memory search fails (Ollama not running), continue to subagent research.
 
 ## Phase 1: Parallel Subagent Research
 
-Gather context before designing. Fire both in parallel:
+Gather context before designing. Fire both in background:
 
 ```typescript
 // Codebase patterns
-Task({
-  subagent_type: "explore",
+background_start({
+  agent: "explore",
   prompt: `For planning $ARGUMENTS, research the codebase:
     1. Find similar implementations or patterns
     2. Identify affected files and their structure
     3. Find related tests and testing patterns
     4. Check for potential conflicts with in-progress work
     Return: File paths, code patterns, test approach, conflicts`,
-  description: "Explore codebase for planning",
-});
+  title: "explore-for-plan",
+}); // → bg_123_abc
 
 // External best practices
-Task({
-  subagent_type: "scout",
+background_start({
+  agent: "scout",
   prompt: `Research implementation approaches for $ARGUMENTS:
     1. Best practices from official documentation
     2. Common patterns in open source projects
     3. Pitfalls and anti-patterns to avoid
     Return: Recommendations, code examples, warnings`,
-  description: "Scout best practices for planning",
-});
+  title: "scout-for-plan",
+}); // → bg_456_def
+
+// Collect when ready
+background_output({ taskId: "bg_123_abc" });
+background_output({ taskId: "bg_456_def" });
 ```
 
 **Continue working while subagents research.**
@@ -186,7 +190,25 @@ Decomposition: [Single bead | X tasks | X tasks with subtasks]
 
 Save to `.beads/artifacts/$ARGUMENTS/design.md`.
 
-**STOP. Wait for user to pick an option.**
+**STOP. Use question tool to ask user to pick an option:**
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Design",
+      question: "Which implementation approach should I use for $ARGUMENTS?",
+      options: [
+        { label: "Option A (Recommended)", description: "[Option A summary]" },
+        { label: "Option B", description: "[Option B summary]" },
+        { label: "Option C", description: "[Option C summary]" },
+      ],
+    },
+  ],
+});
+```
+
+Wait for user's answer before proceeding.
 
 ---
 
@@ -395,7 +417,52 @@ If issues detected after deployment:
 
 ---
 
-## Phase 7: Sync and Report
+## Phase 7: Parallel Task Execution (if --parallel)
+
+After creating hierarchy, execute READY tasks in parallel:
+
+```bash
+# Check what's ready to start
+bd ready --json
+```
+
+```typescript
+// Fire all READY tasks in parallel with beads integration
+for (const task of readyTasks) {
+  background_start({
+    agent: "build",
+    prompt: `Execute ${task.id}: ${task.title}
+
+      Context: Part of plan for $ARGUMENTS
+      Spec: See .beads/artifacts/$ARGUMENTS/plan.md
+
+      Requirements:
+      - Complete work items for this task
+      - Run verification commands from plan
+      - Commit with bead ID in message
+
+      Return: Changes made, verification results`,
+    beadId: task.id,
+    autoCloseBead: true,
+    title: `exec-${task.id}`
+  })
+}
+
+// Collect results
+for (const taskId of backgroundTaskIds) {
+  background_output({ taskId })  // → beadClosed: true
+}
+
+// Check newly unblocked tasks
+bd ready  // → Next wave of tasks now READY
+
+// Cleanup
+background_cancel({ all: true })
+```
+
+---
+
+## Phase 8: Sync and Report
 
 ```bash
 bd sync

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

@@ -120,23 +120,33 @@ git log origin/$(git branch --show-current)..HEAD --oneline 2>/dev/null || git l
 git diff --stat origin/$(git branch --show-current)..HEAD 2>/dev/null || git diff --stat HEAD~3..HEAD
 ```
 
-**Present to user:**
+**Use question tool to get push/PR decision:**
 
+```typescript
+question({
+  questions: [
+    {
+      header: "Push",
+      question: "Ready to push and create PR for $ARGUMENTS. What should I do?",
+      options: [
+        {
+          label: "Push & create PR (Recommended)",
+          description: "Push branch and create PR",
+        },
+        { label: "Push & draft PR", description: "Create as draft for review" },
+        {
+          label: "Show diff first",
+          description: "Review changes before pushing",
+        },
+        {
+          label: "Skip (I'll push manually)",
+          description: "Handle PR creation manually",
+        },
+      ],
+    },
+  ],
+});
 ```
-Ready to Push & Create PR
-━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Branch: [current branch]
-Commits: [N commits ahead of origin]
-
-Would you like me to:
-1. Push and create PR
-2. Push and create draft PR
-3. Show full diff first
-4. Skip (I'll push manually)
-```
-
-**Wait for user confirmation before proceeding.**
 
 If user confirms, push:
 

package/dist/template/.opencode/command/ralph-loop.md

@@ -0,0 +1,97 @@
+---
+description: Start Ralph Wiggum autonomous loop for task completion
+argument-hint: "<task> [--prd <file>] [--max <iterations>] [--afk]"
+agent: build
+---
+
+# Ralph Wiggum Loop
+
+You are starting a Ralph Wiggum autonomous loop. This pattern enables you to work autonomously on a task list until completion.
+
+## Task
+
+$ARGUMENTS
+
+## Setup
+
+1. **Start the loop** by calling the `ralph-start` tool:
+
+```typescript
+ralph -
+  start({
+    task: "$1",
+    prdFile: "$2" || null, // Optional: PRD.md, tasks.md, etc.
+    progressFile: "progress.txt",
+    maxIterations: 50,
+    mode: "hitl", // or "afk" for autonomous
+  });
+```
+
+2. **Create progress.txt** if it doesn't exist:
+
+```markdown
+# Progress Log
+
+## Session Started: [date]
+
+### Completed Tasks
+
+(none yet)
+
+### Notes for Next Iteration
+
+- Starting fresh
+```
+
+## Loop Behavior
+
+After each iteration, the loop will automatically:
+
+1. Check if you output `<promise>COMPLETE</promise>`
+2. If yes → Loop ends, success!
+3. If no → Send continuation prompt for next iteration
+4. Repeat until completion or max iterations
+
+## Your Instructions
+
+For each iteration:
+
+1. **Review** the PRD/task list and progress file
+2. **Choose** the highest-priority incomplete task (YOU decide, not first in list)
+3. **Implement** ONE feature only (small steps prevent context rot)
+4. **Validate** with feedback loops:
+   - `npm run typecheck` (must pass)
+   - `npm run test` (must pass)
+   - `npm run lint` (must pass)
+5. **Commit** if all pass
+6. **Update** progress.txt with:
+   - Task completed
+   - Key decisions made
+   - Files changed
+   - Notes for next iteration
+
+## Exit Conditions
+
+Output `<promise>COMPLETE</promise>` when:
+
+- ALL tasks in the PRD are complete
+- ALL feedback loops pass
+- Code is committed
+
+The loop will also stop if:
+
+- Max iterations reached
+- You call `ralph-stop` tool
+- An error occurs
+
+## Best Practices
+
+- **Small steps**: One feature per iteration
+- **Quality over speed**: Never skip tests
+- **Explicit scope**: Vague tasks loop forever
+- **Track progress**: Update progress.txt every iteration
+- **Prioritize risk**: Hard tasks first, easy wins last
+
+## Start Now
+
+Call `ralph-start` with the task description to begin the loop.

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

@@ -99,7 +99,7 @@ Before reverting, check what depends on this:
 
 ### Downstream Report
 
-```
+````
 Downstream Impact Analysis
 ━━━━━━━━━━━━━━━━━━━━━━━━━━
 
@@ -119,8 +119,20 @@ Feature flags:
 - AUTH_ENABLED flag in production
 
 CAUTION: Reverting may break dependent features.
-Proceed? (yes/abort/revert-cascade)
-```
+
+```typescript
+question({
+  questions: [{
+    header: "Confirm",
+    question: "Ready to revert $ARGUMENTS? Breaking changes detected.",
+    options: [
+      { label: "Proceed with revert", description: "Execute revert with backups" },
+      { label: "Abort", description: "Cancel this operation" },
+      { label: "Revert cascade", description: "Revert dependent features too" }
+    ]
+  }]
+});
+````
 
 ---
 

package/dist/template/.opencode/command/skill-optimize.md

@@ -150,7 +150,37 @@ Rules:
 
 ### Clarification Techniques
 
-```
+````
+BEFORE (vague):
+──────────────
+"Check that the configuration is correct."
+
+AFTER (specific):
+────────────────
+"Verify config:
+1. Run: `npm run config:check`
+2. Confirm output shows: 'Configuration valid'
+3. If errors, check [specific file] for [specific issue]"
+
+Rules:
+- Replace "check" with specific verification command
+- Include expected output
+- Add troubleshooting for failures
+
+Use question tool to confirm:
+```typescript
+question({
+  questions: [{
+    header: "Verify",
+    question: "Configuration verified. Ready to continue?",
+    options: [
+      { label: "Yes, continue", description: "Proceed with optimization" },
+      { label: "No, fix issues", description: "Address validation errors first" }
+    ]
+  }]
+});
+````
+
 BEFORE (vague):
 ───────────────
 "Check that the configuration is correct."
@@ -158,19 +188,23 @@ BEFORE (vague):
 AFTER (specific):
 ─────────────────
 "Verify config:
+
 1. Run: `npm run config:check`
 2. Confirm output shows: 'Configuration valid'
 3. If errors, check [specific file] for [specific issue]"
 
 Rules:
+
 - Replace "check" with specific verification command
 - Include expected output
 - Add troubleshooting for failures
+
 ```
 
 ### Hardening Techniques
 
 ```
+
 BEFORE (soft):
 ──────────────
 "You should generally avoid committing directly to main."
@@ -180,20 +214,24 @@ AFTER (hardened):
 "NEVER commit directly to main. ALWAYS use feature branches.
 
 If tempted to commit to main because 'it's just a small fix':
+
 - STOP
 - Create branch anyway: git checkout -b fix/small-fix
 - This is NOT optional"
 
 Rules:
+
 - Add MUST/NEVER to critical rules
 - Anticipate rationalizations
 - Explicitly reject common excuses
 - Name the anti-pattern
+
 ```
 
 ### Expansion Techniques
 
 ```
+
 BEFORE (incomplete):
 ────────────────────
 "Handle errors appropriately."
@@ -203,23 +241,28 @@ AFTER (comprehensive):
 "Error Handling:
 
 Network Errors:
+
 - Retry 2x with exponential backoff
 - If still failing, log and surface to user
 
 Validation Errors:
+
 - Display specific field errors
 - Do NOT proceed with invalid data
 
 Permission Errors:
+
 - Log with full context
 - Display user-friendly message
 - Do NOT expose internal details"
 
 Rules:
+
 - List specific error categories
 - Provide handling for each
 - Include what NOT to do
-```
+
+````
 
 ## Phase 5: Test Optimizations
 
@@ -232,9 +275,9 @@ task({
   description: "Test original skill",
   prompt: `
     Load skill: skill({ name: "$ARGUMENTS" })
-    
+
     Scenario: [test scenario]
-    
+
     Follow the skill and report each step.
   `,
 });
@@ -245,13 +288,13 @@ task({
   description: "Test optimized skill",
   prompt: `
     Load skill: skill({ name: "$ARGUMENTS" })
-    
+
     Scenario: [same test scenario]
-    
+
     Follow the skill and report each step.
   `,
 });
-```
+````
 
 ### Compare Results
 
@@ -367,6 +410,27 @@ write({
 skill({ name: "$ARGUMENTS" });
 ```
 
+```typescript
+question({
+  questions: [
+    {
+      header: "Verify",
+      question: "Skill optimized and saved. Ready to deploy?",
+      options: [
+        {
+          label: "Yes, deploy (Recommended)",
+          description: "All verifications passed",
+        },
+        {
+          label: "No, fix issues",
+          description: "Need to address verification failures",
+        },
+      ],
+    },
+  ],
+});
+```
+
 Confirm:
 
 - [ ] Skill loads without error

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

@@ -75,14 +75,40 @@ bd update $ARGUMENTS --status in_progress
 
 ## Workspace Setup
 
-### Option A: Feature Branch (default)
+### Create Feature Branch
 
-If not already on a feature branch:
+Extract task info and parent branch for a readable branch name:
 
 ```bash
-git checkout -b $ARGUMENTS
+# Get current branch (parent branch)
+PARENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+# Get task title and type from bead
+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" ;;
+  "chore") PREFIX="chore" ;;
+  *) 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 "Branch already exists or already on it"
 ```
 
+**Branch naming convention:**
+| Parent Branch | Bead Type | Example |
+|---------------|-----------|---------|
+| main | bug | `main/fix/bd-a1b2-login-error` |
+| develop | feature | `develop/feat/bd-c3d4-user-auth` |
+| release-v2 | chore | `release-v2/chore/bd-e5f6-update-deps` |
+
 ### Option B: Git Worktree (if --worktree flag)
 
 For isolated work that won't conflict with main workspace:
@@ -101,11 +127,30 @@ skill({ name: "using-git-worktrees" });
 **Worktree setup:**
 
 ```bash
+# Get current branch (parent branch)
+PARENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+# Get task title for readable worktree 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}"
+
 # Verify .gitignore has worktree directory
 grep -q "^\.worktrees/$" .gitignore || echo ".worktrees/" >> .gitignore
 
-# Create worktree
-git worktree add .worktrees/$ARGUMENTS -b $ARGUMENTS
+# Create worktree with readable branch name
+git worktree add ".worktrees/$ARGUMENTS" -b "$BRANCH_NAME"
 
 # Navigate to worktree
 cd .worktrees/$ARGUMENTS
@@ -124,33 +169,36 @@ cd .worktrees/$ARGUMENTS
 For complex tasks, gather context before diving in:
 
 ```typescript
-// Fire subagents in parallel - don't wait for results
-Task({
-  subagent_type: "explore",
+// Fire subagents in background - don't wait for results
+background_start({
+  agent: "explore",
   prompt: `Research codebase patterns for $ARGUMENTS:
     - Find similar implementations
     - Identify affected files
     - Note testing patterns used
     Return: File list, patterns found, testing approach`,
-  description: "Explore codebase for task",
-});
+  title: "explore-codebase",
+}); // → bg_123_abc
 
-Task({
-  subagent_type: "scout",
+background_start({
+  agent: "scout",
   prompt: `Research external docs for $ARGUMENTS:
     - API documentation for libraries involved
     - Best practices for the approach
     - Common pitfalls to avoid
     Return: Key findings, code examples, warnings`,
-  description: "Scout external resources",
-});
+  title: "scout-docs",
+}); // → bg_456_def
+
+// Collect later with: background_output({ taskId: "bg_123_abc" })
 ```
 
 **Subagent delegation rules:**
 
 - Subagents are **read-only** - they don't modify beads state
-- Results return to you (build agent) for integration
+- Results collected via `background_output({ taskId })` when ready
 - Use for research, not for implementation
+- Cleanup at session end: `background_cancel({ all: true })`
 
 ## Existing Artifacts
 

package/dist/template/.opencode/dcp.jsonc

@@ -14,28 +14,32 @@
 			// Nudge every 8 tool calls (slightly more aggressive than default 10)
 			"nudgeFrequency": 8,
 			// Protect state-modifying and critical workflow tools
+			// Updated for v1.1.8: Added question tool, removed legacy bd_* (use CLI)
 			"protectedTools": [
 				"write",
 				"edit",
+				"question",
 				"memory-read",
 				"memory-update",
 				"memory-search",
 				"observation",
 				"skill",
 				"skill_mcp",
+				"task",
+				"batch",
+				"todowrite",
+				"todoread",
+				"lsp",
 				"lsp_lsp_rename",
 				"lsp_lsp_find_references",
 				"lsp_lsp_goto_definition",
 				"lsp_lsp_code_actions",
 				"lsp_lsp_code_action_apply",
 				"lsp_lsp_organize_imports",
-				"bd_init",
-				"bd_claim",
-				"bd_done",
-				"bd_show",
-				"bd_reserve",
-				"bd_reservations",
-				"bd_sync"
+				"bd-reserve",
+				"bd-release",
+				"bd-msg",
+				"bd-inbox"
 			]
 		},
 		"discard": {

package/dist/template/.opencode/memory/{project/beads-workflow.md → beads-workflow.md}

@@ -426,6 +426,59 @@ git worktree remove .worktrees/bd-epic  # Cleanup worktree
 /finish bd-epic
 ```
 
+### Pattern 8: Ralph Wiggum Autonomous Loop
+
+For tasks that can run autonomously until completion. The agent loops until it outputs `<promise>COMPLETE</promise>` or hits max iterations.
+
+```
+/ralph-loop "Migrate all Jest tests to Vitest"
+# Or with PRD file:
+/ralph-loop "Complete PRD tasks" --prd PRD.md --max 50
+
+# Agent automatically:
+# 1. Picks highest-priority incomplete task
+# 2. Implements ONE feature
+# 3. Runs feedback loops (typecheck, test, lint)
+# 4. Commits if all pass
+# 5. Updates progress.txt
+# 6. Loops until <promise>COMPLETE</promise> or max iterations
+```
+
+**When to use Ralph:**
+
+| Scenario                  | Use Ralph? | Why                                  |
+| ------------------------- | ---------- | ------------------------------------ |
+| Test coverage improvement | ✅ Yes     | Clear success criteria, safe to loop |
+| Linting fixes             | ✅ Yes     | Deterministic, feedback-driven       |
+| Migration (Jest→Vitest)   | ✅ Yes     | Repetitive, well-defined end state   |
+| Feature implementation    | ⚠️ HITL    | Need oversight for design decisions  |
+| Architectural changes     | ❌ No      | Too risky for autonomous work        |
+| Vague "improve X" tasks   | ❌ No      | No clear completion criteria         |
+
+**Ralph + Beads Integration:**
+
+```bash
+# Create PRD from beads
+bd list --status=open --json > PRD.json
+
+# Start Ralph loop
+/ralph-loop "Complete all open tasks" --prd PRD.json
+
+# Ralph will work through tasks, you can:
+ralph-status   # Check progress
+ralph-stop     # Stop gracefully
+
+# After completion, sync beads
+bd sync
+```
+
+**Key constraints:**
+
+- ONE feature per iteration (prevents context rot)
+- MUST pass all feedback loops before commit
+- Small steps > large changes
+- Always cap iterations (never infinite loops)
+
 ## Agent Boundaries
 
 ### Leader Agents (Touch Beads)