opencodekit 0.11.0 → 0.11.1

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

@@ -6,6 +6,12 @@ agent: build
 
 # Fix UI: $ARGUMENTS
 
+## Load Beads Skill
+
+```typescript
+skill({ name: "beads" });
+```
+
 ## Options
 
 - `--a11y`: Include full accessibility audit

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

@@ -6,6 +6,12 @@ agent: build
 
 # Fix: $ARGUMENTS
 
+## Load Beads Skill
+
+```typescript
+skill({ name: "beads" });
+```
+
 ## Options
 
 - `--quick`: Skip deep analysis, fix directly (for obvious bugs)

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

@@ -6,7 +6,12 @@ agent: build
 
 # Handoff
 
-**Load skill:** `skill({ name: "verification-before-completion" })`
+**Load skills:**
+
+```typescript
+skill({ name: "beads" }); // Session protocol
+skill({ name: "verification-before-completion" });
+```
 
 ## Phase 1: Check Messages
 

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

@@ -9,6 +9,7 @@ agent: build
 **Load skills:**
 
 ```typescript
+skill({ name: "beads" }); // Session protocol and hierarchy
 skill({ name: "test-driven-development" });
 skill({ name: "verification-before-completion" });
 ```

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

@@ -6,7 +6,12 @@ agent: build
 
 # Import Plan
 
-**Load skill:** `skill({ name: "executing-plans" })`
+**Load skills:**
+
+```typescript
+skill({ name: "beads" }); // For hierarchy and dependencies
+skill({ name: "executing-plans" }); // For plan execution
+```
 
 Import a markdown plan into Beads epics and issues. Follows Steve Yegge's "plan outside, import inside" pattern.
 

package/dist/template/.opencode/command/integration-test.md

@@ -10,6 +10,11 @@ Create integration tests that verify module boundaries and system interactions.
 
 ## Load Skills
 
+```typescript
+skill({ name: "beads" }); // Session protocol
+skill({ name: "test-driven-development" });
+```
+
 ```typescript
 skill({ name: "test-driven-development" });
 skill({ name: "condition-based-waiting" }); // For async tests

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

@@ -6,6 +6,12 @@ agent: build
 
 # Analyze Issue: $ARGUMENTS
 
+## Load Beads Skill
+
+```typescript
+skill({ name: "beads" });
+```
+
 ## Phase 1: Check for Duplicates
 
 Before creating, search for existing beads:

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

@@ -9,6 +9,14 @@ model: proxypal/gemini-3-flash-preview
 
 Create a complete feature track with discovery, specification, implementation plan, and sub-tasks.
 
+## Load Beads Skill
+
+```typescript
+skill({ name: "beads" });
+```
+
+This skill provides Epic → Task → Subtask hierarchy for complex features.
+
 ## Parse Arguments
 
 | Argument     | Default  | Options                              |

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

@@ -1,12 +1,25 @@
 ---
-description: Create implementation plan - design options, get approval, save plan
-argument-hint: "<bead-id>"
+description: Create implementation plan with optional bead decomposition
+argument-hint: "<bead-id> [--create-beads] [--parallel]"
 agent: planner
 ---
 
 # Plan
 
-**Load skill:** `skill({ name: "writing-plans" })`
+**Load skills:**
+
+```typescript
+skill({ name: "beads" }); // For hierarchy and dependencies
+skill({ name: "writing-plans" }); // For plan structure
+```
+
+## Arguments
+
+| Argument         | Default  | Description                           |
+| ---------------- | -------- | ------------------------------------- |
+| `<bead-id>`      | required | The bead to plan                      |
+| `--create-beads` | false    | Create child beads for each plan task |
+| `--parallel`     | false    | Identify parallel execution tracks    |
 
 ## Phase 1: Load Context
 
@@ -16,14 +29,14 @@ bd_show({ id: "$ARGUMENTS" });
 
 Read artifacts:
 
-```bash
-cat .beads/artifacts/<bead-id>/spec.md
-cat .beads/artifacts/<bead-id>/research.md
-cat .beads/artifacts/<bead-id>/design.md 2>/dev/null
+```typescript
+read({ filePath: ".beads/artifacts/<bead-id>/spec.md" });
+read({ filePath: ".beads/artifacts/<bead-id>/research.md" });
+read({ filePath: ".beads/artifacts/<bead-id>/design.md" }); // May not exist
 ```
 
 If spec.md missing: "Run `/create <bead-id>` first."
-If research.md missing: "Run `/research <bead-id>` first."
+If research.md missing and complexity > M: "Run `/research <bead-id>` first."
 If design.md exists: Resume from saved design options.
 
 Reserve files while planning:
@@ -39,7 +52,46 @@ bd_reserve({
 });
 ```
 
-## Phase 2: Generate Design Options
+## Phase 2: Analyze for Decomposition
+
+Before generating options, analyze if this bead should be decomposed:
+
+```
+DECOMPOSITION ANALYSIS
+━━━━━━━━━━━━━━━━━━━━━━
+
+Bead: <bead-id>
+Title: [title from bead]
+Current Type: [task/feature/epic]
+
+Complexity Signals:
+[✓/✗] Multiple domains (frontend + backend)
+[✓/✗] Multiple files in different areas
+[✓/✗] Natural phases (setup → implement → test)
+[✓/✗] Could benefit from parallel execution
+[✓/✗] Estimated > 50 tool calls
+
+Recommendation: [DECOMPOSE / SINGLE PLAN]
+
+If DECOMPOSE: Will create Epic + child beads
+If SINGLE PLAN: Will create plan.md with task checklist
+```
+
+If `--create-beads` flag is set, proceed with decomposition.
+If complexity warrants decomposition, suggest it:
+
+```
+This bead would benefit from decomposition into subtasks.
+
+Benefits:
+• Parallel agent execution
+• Better context management
+• Clearer progress tracking
+
+Create child beads? (yes/no)
+```
+
+## Phase 3: Generate Design Options
 
 Present 2-3 approaches with this format:
 
@@ -64,6 +116,8 @@ Present 2-3 approaches with this format:
 - Files touched: [N]
 - Risk: [low/medium/high]
 
+**Parallelization potential:** [High/Medium/Low]
+
 ---
 
 ### Option B: [Name]
@@ -77,7 +131,7 @@ Present 2-3 approaches with this format:
 
 Save to `.beads/artifacts/<bead-id>/design.md` with status `Pending Approval`.
 
-## Phase 3: Get Approval
+## Phase 4: Get Approval
 
 **STOP and wait for human response.**
 
@@ -87,7 +141,7 @@ Pick an option (A/B/C), modify, or "none" to propose alternatives.
 
 Do not proceed until user confirms.
 
-## Phase 4: Create Plan with Task Contracts
+## Phase 5: Create Plan with Task Contracts
 
 After approval, write `.beads/artifacts/<bead-id>/plan.md`:
 
@@ -98,21 +152,22 @@ After approval, write `.beads/artifacts/<bead-id>/plan.md`:
 **Date:** <date>
 **Approach:** [selected option name]
 **Estimation:** ~[N] tool calls, [N] files
+**Decomposition:** [Yes - child beads created / No - single bead]
 
 ## Dependency Graph
 ```
 
-[Step 1] ──┬──> [Step 2a] ──┬──> [Step 4]
+[Task 1] ──┬──> [Task 2a] ──┬──> [Task 4]
 │ │
-└──> [Step 2b] ──┘
+└──> [Task 2b] ──┘
 │
-└──> [Step 3] (can run parallel)
+└──> [Task 3] (can run parallel)
 
 ````
 
 **Parallel Tracks:**
-- Track A: Steps 1 → 2a → 4
-- Track B: Steps 1 → 2b → 3 (independent after Step 1)
+- Track A: Tasks 1 → 2a → 4
+- Track B: Tasks 1 → 2b → 3 (independent after Task 1)
 
 ## Tasks
 
@@ -120,6 +175,7 @@ After approval, write `.beads/artifacts/<bead-id>/plan.md`:
 
 | Field         | Value                              |
 | ------------- | ---------------------------------- |
+| **Bead**      | [child-bead-id if created]         |
 | **Files**     | `src/foo.ts`                       |
 | **Input**     | [What this task receives/needs]    |
 | **Output**    | [What this task produces]          |
@@ -143,6 +199,7 @@ After approval, write `.beads/artifacts/<bead-id>/plan.md`:
 
 | Field        | Value                            |
 | ------------ | -------------------------------- |
+| **Bead**     | [child-bead-id if created]       |
 | **Files**    | `src/bar.ts`                     |
 | **Input**    | Output from Task 1               |
 | **Output**   | [What this produces]             |
@@ -187,7 +244,117 @@ npm run test -- src/bar.test.ts
 
 ````
 
-## Phase 5: Generate ADR & Sync
+## Phase 6: Create Child Beads (if --create-beads or user approved)
+
+For each task in the plan, create a child bead:
+
+```typescript
+// Get parent bead ID
+const parentId = "$ARGUMENTS";
+
+// Task 1: No dependencies
+const task1 = bd_add({
+  title: "[Task 1 title from plan]",
+  type: "task",
+  pri: 2,
+  parent: parentId,
+  desc: "[Task 1 description]",
+  tags: ["[domain]", "[size]"],
+});
+
+// Task 2a: Depends on Task 1
+const task2a = bd_add({
+  title: "[Task 2a title from plan]",
+  type: "task",
+  pri: 2,
+  parent: parentId,
+  deps: [task1.id],
+  desc: "[Task 2a description]",
+  tags: ["[domain]", "[size]"],
+});
+
+// Task 2b: Also depends on Task 1 (parallel with 2a)
+const task2b = bd_add({
+  title: "[Task 2b title from plan]",
+  type: "task",
+  pri: 2,
+  parent: parentId,
+  deps: [task1.id],
+  desc: "[Task 2b description]",
+  tags: ["[domain]", "[size]"],
+});
+
+// Task 3: Depends on Task 1 (parallel track)
+const task3 = bd_add({
+  title: "[Task 3 title from plan]",
+  type: "task",
+  pri: 2,
+  parent: parentId,
+  deps: [task1.id],
+  desc: "[Task 3 description]",
+  tags: ["[domain]", "[size]"],
+});
+
+// Task 4: Depends on 2a and 2b
+const task4 = bd_add({
+  title: "[Task 4 title from plan]",
+  type: "task",
+  pri: 2,
+  parent: parentId,
+  deps: [task2a.id, task2b.id],
+  desc: "[Task 4 description]",
+  tags: ["[domain]", "[size]"],
+});
+````
+
+### Update Plan with Bead IDs
+
+After creating beads, update plan.md to include bead IDs in each task table.
+
+### Visualize Dependency Graph
+
+```
+CHILD BEADS CREATED
+━━━━━━━━━━━━━━━━━━━
+
+Parent: <parent-id> "[Title]"
+
+<parent>.1 [Task 1] ──┬──> <parent>.2 [Task 2a] ──┬──> <parent>.5 [Task 4]
+     (READY)          │          │                │
+                      │          ▼                │
+                      └──> <parent>.3 [Task 2b] ──┘
+                      │
+                      └──> <parent>.4 [Task 3]
+                                (parallel track)
+
+READY NOW: <parent>.1
+PARALLEL AFTER .1: <parent>.2, <parent>.3, <parent>.4
+FINAL: <parent>.5
+
+Run `bd ready` to see claimable work.
+```
+
+## Phase 7: Upgrade Parent to Epic (if needed)
+
+If parent was a `task` or `feature` and we created children, upgrade it:
+
+```typescript
+// Check current type
+const parent = bd_show({ id: parentId });
+
+if (parent.type !== "epic" && childBeadsCreated > 0) {
+  // Update parent to epic type
+  bd_msg({
+    subj: "Upgraded to Epic",
+    body: `${parentId} upgraded from ${parent.type} to epic with ${childBeadsCreated} subtasks`,
+    to: "all",
+    importance: "normal",
+    global: true,
+  });
+}
+```
+
+## Phase 8: Generate ADR & Sync
 
 Create `.beads/artifacts/<bead-id>/adr.md`:
 
@@ -205,6 +372,7 @@ Create `.beads/artifacts/<bead-id>/adr.md`:
 ## Decision
 
 We chose **[Option Name]** because:
+
 - [Reason 1]
 - [Reason 2]
 
@@ -213,29 +381,46 @@ We chose **[Option Name]** because:
 - **[Option B]:** Rejected because [reason]
 - **[Option C]:** Rejected because [reason]
 
+## Decomposition Decision
+
+[If child beads created:]
+We decomposed this into [N] subtasks because:
+
+- [Reason: parallel execution, context management, etc.]
+
+Child beads: <parent>.1, <parent>.2, ...
+
+[If not decomposed:]
+We kept this as a single bead because:
+
+- [Reason: small scope, single domain, etc.]
+
 ## Consequences
 
 **Positive:**
+
 - [Benefit 1]
 - [Benefit 2]
 
 **Negative:**
+
 - [Tradeoff 1]
 - [Tradeoff 2]
 
 ## Confirmation
 
 This decision is confirmed when:
+
 - [ ] Implementation complete per plan.md
 - [ ] All verification steps pass
-````
+```
 
 Update bead and sync:
 
 ```typescript
 bd_msg({
   subj: "Plan approved",
-  body: "Approach: [selected option]\nTasks: [count]\nEstimate: ~[N] tool calls",
+  body: `Approach: [selected option]\nTasks: [count]\nChild beads: [yes/no]\nEstimate: ~[N] tool calls`,
   to: "all",
   importance: "normal",
   global: true,
@@ -247,13 +432,14 @@ bd_sync({ reason: "Plan approved for $ARGUMENTS" });
 
 ## Output
 
+### Without Child Beads
+
 ```
 Plan Approved: <bead-id>
 ━━━━━━━━━━━━━━━━━━━━━━━━
 
 Approach: [selected option]
-Tasks: [count]
-Parallel tracks: [count]
+Tasks: [count] (tracked in plan.md)
 Estimate: ~[N] tool calls
 
 Artifacts:
@@ -263,3 +449,78 @@ Artifacts:
 
 Next: /implement <bead-id>
 ```
+
+### With Child Beads
+
+```
+Plan Approved: <bead-id> (Epic)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Approach: [selected option]
+Child beads created: [count]
+
+Subtasks:
+├── <bead>.1: [Task 1] [S] ← READY
+├── <bead>.2: [Task 2a] [M] ← blocked by .1
+├── <bead>.3: [Task 2b] [M] ← blocked by .1
+├── <bead>.4: [Task 3] [S] ← blocked by .1
+└── <bead>.5: [Task 4] [M] ← blocked by .2, .3
+
+Parallel Tracks:
+• Track A: .1 → .2 → .5
+• Track B: .1 → .3 → .5
+• Track C: .1 → .4
+
+Artifacts:
+- .beads/artifacts/<bead-id>/design.md
+- .beads/artifacts/<bead-id>/plan.md
+- .beads/artifacts/<bead-id>/adr.md
+
+Next Steps:
+├── Start first task: /implement <bead>.1
+├── See ready work: bd ready
+└── See parallel plan: bd_plan()
+
+For parallel agents:
+├── Agent 1 (backend): claim <bead>.1
+├── Agent 2 (frontend): wait for .1, then claim .3
+└── Agent 3 (qa): wait for .2 and .3, then claim .5
+```
+
+## When to Create Child Beads
+
+| Scenario                        | Create Beads?                        |
+| ------------------------------- | ------------------------------------ |
+| Simple task, single domain      | No - use plan.md checklist           |
+| 2-3 tasks, same domain          | No - use plan.md checklist           |
+| 3+ tasks, multiple domains      | Yes - enables parallel agents        |
+| Tasks with complex dependencies | Yes - beads tracks dependencies      |
+| Long-running work (days)        | Yes - better progress tracking       |
+| Work that may span sessions     | Yes - beads persists across sessions |
+
+## Integration with Agent Workflow
+
+After plan creates child beads:
+
+```typescript
+// Any agent can check ready work
+bd_init({ team: "project", role: "backend" });
+bd_ready(); // Shows <parent>.1 as ready
+
+// Agent claims and works
+bd_claim(); // Gets <parent>.1
+// ... do the work ...
+bd_done({ id: "<parent>.1", msg: "Completed setup" });
+
+// Now <parent>.2, .3, .4 become ready (unblocked)
+// Multiple agents can claim them in parallel
+```
+
+## Examples
+
+```bash
+/plan bd-auth01                    # Plan without creating beads
+/plan bd-auth01 --create-beads     # Plan and create child beads
+/plan bd-auth01 --parallel         # Focus on parallel execution
+/plan bd-auth01 --create-beads --parallel  # Full decomposition
+```

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

@@ -6,7 +6,12 @@ agent: build
 
 # Pull Request
 
-**Load skill:** `skill({ name: "verification-before-completion" })`
+**Load skills:**
+
+```typescript
+skill({ name: "beads" }); // Session protocol
+skill({ name: "verification-before-completion" });
+```
 
 ## Options
 

package/dist/template/.opencode/command/research-and-implement.md

@@ -8,6 +8,12 @@ agent: build
 
 Complete workflow that combines research, planning, and implementation into a single guided process.
 
+## Load Beads Skill
+
+```typescript
+skill({ name: "beads" });
+```
+
 ## When to Use
 
 | Scenario                  | Use This Command           |

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

@@ -6,6 +6,12 @@ agent: build
 
 # Research
 
+## Load Beads Skill
+
+```typescript
+skill({ name: "beads" });
+```
+
 ## Depth Levels
 
 | Level        | Tool Calls | Use Case                              |

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

@@ -8,6 +8,14 @@ agent: build
 
 Recover full context from a previous session and continue work on an in-progress task.
 
+## Load Beads Skill
+
+```typescript
+skill({ name: "beads" });
+```
+
+This skill provides the session protocol for proper context recovery.
+
 ## Prerequisites
 
 - Bead ID must exist

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

@@ -7,7 +7,12 @@ model: proxypal/gemini-3-flash-preview
 
 # Revert Feature: $ARGUMENTS
 
-**Load skill:** `skill({ name: "verification-before-completion" })`
+**Load skills:**
+
+```typescript
+skill({ name: "beads" }); // Session protocol
+skill({ name: "verification-before-completion" });
+```
 
 Intelligently revert changes for a bead with comprehensive safety checks.
 

package/dist/template/.opencode/command/review-codebase.md

@@ -6,6 +6,12 @@ agent: review
 
 # Review: $ARGUMENTS
 
+## Load Beads Skill
+
+```typescript
+skill({ name: "beads" });
+```
+
 ## Phase 1: Determine Scope
 
 Parse `$ARGUMENTS` to determine what to review:

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

@@ -6,6 +6,12 @@ agent: explore
 
 # Status Dashboard
 
+## Load Beads Skill
+
+```typescript
+skill({ name: "beads" });
+```
+
 Generate a comprehensive project status report covering tasks, sessions, git state, and system health.
 
 ## Phase 1: Gather All State (Parallel)

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

@@ -6,6 +6,12 @@ agent: build
 
 # Triage
 
+## Load Beads Skill
+
+```typescript
+skill({ name: "beads" });
+```
+
 Analyze open tasks and optimize prioritization using dependency graph analysis, SLA tracking, and multi-agent coordination.
 
 ## Phase 1: Initialize Beads Connection

package/dist/template/.opencode/command/ui-review.md

@@ -11,6 +11,10 @@ Comprehensive UI/UX review with structured scoring and actionable feedback.
 
 ## Load Skills
 
+```typescript
+skill({ name: "beads" }); // Session protocol
+```
+
 ```typescript
 skill({ name: "frontend-aesthetics" });
 skill({ name: "visual-analysis" });