opencodekit 0.11.0 → 0.12.0

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

@@ -1,19 +1,26 @@
 ---
-description: Create a new bead with spec
+description: Create bead(s) with automatic complexity analysis and decomposition
 argument-hint: "[optional title]"
 agent: build
 ---
 
 # Create Task
 
+## Load Beads Skill
+
+```typescript
+skill({ name: "beads" });
+```
+
+This skill provides the full beads workflow including Epic → Task → Subtask hierarchy.
+
 ## Phase 1: Check for Similar Work
 
 Before creating, search for existing or past work:
 
 ```typescript
-memory -
-  search({ query: "[keywords from title/problem]", type: "observations" });
-bd_ls({ status: "all", limit: 20 });
+memory_search({ query: "[keywords from title/problem]", type: "observations" });
+bd_ls({ status: "all", limit: 20, offset: 0 });
 ```
 
 If similar task exists:
@@ -36,52 +43,94 @@ If similar task exists:
 
 Keep it brief. Get: clear goal, success criteria, scope, constraints.
 
-## Phase 3: Classify & Estimate
+## Phase 3: Complexity Analysis
 
-Based on interview:
+Analyze the request to determine if it should be a single bead or decomposed:
 
-### Type & Priority
+### Complexity Signals
 
-- **Type**: bug | feature | task | chore
-- **Priority**: 0 (critical) to 4 (low), default 2
+```
+SIMPLE (Single Bead)                    COMPLEX (Needs Decomposition)
+━━━━━━━━━━━━━━━━━━━━                    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+• Single file change                    • Multiple unrelated files
+• One clear action                      • Multiple distinct actions
+• ~30 min or less                       • Hours/days of work
+• No phases needed                      • Has natural phases
+• One skill domain                      • Crosses domains (FE + BE)
+• Bug fix or small feature              • New system or major feature
+```
 
-### Complexity & Estimation
+### Automatic Classification
 
-| Complexity | Tool Calls | Description                        | Workflow            |
-| ---------- | ---------- | ---------------------------------- | ------------------- |
-| **S**      | ~10        | Single file fix, obvious solution  | → /implement        |
-| **M**      | ~30        | Few files, clear scope             | → /implement        |
-| **L**      | ~100       | Multiple files, needs research     | → /research → /plan |
-| **XL**     | Decompose  | Too big - break into smaller tasks | → Create sub-beads  |
+```typescript
+const analyzeComplexity = (request: string) => {
+  const signals = {
+    // COMPLEX signals
+    multiDomain: /frontend.*backend|api.*ui|database.*interface/i,
+    multiPhase: /first.*then|phase|step \d|after.*before/i,
+    largeScope: /system|architecture|refactor.*entire|redesign/i,
+    multiComponent: /and.*and|multiple|several|all.*components/i,
+    integration: /integrate|connect|sync.*between/i,
+
+    // SIMPLE signals
+    singleAction: /fix|update|add|remove|change.*one/i,
+    bugFix: /bug|error|broken|not working|crash/i,
+    smallScope: /typo|config|env|readme|comment/i,
+  };
+
+  let complexScore = 0;
+  if (signals.multiDomain.test(request)) complexScore += 3;
+  if (signals.multiPhase.test(request)) complexScore += 2;
+  if (signals.largeScope.test(request)) complexScore += 3;
+  if (signals.multiComponent.test(request)) complexScore += 2;
+  if (signals.integration.test(request)) complexScore += 2;
+
+  let simpleScore = 0;
+  if (signals.singleAction.test(request)) simpleScore += 2;
+  if (signals.bugFix.test(request)) simpleScore += 1;
+  if (signals.smallScope.test(request)) simpleScore += 3;
+
+  return complexScore > simpleScore + 2 ? "COMPLEX" : "SIMPLE";
+};
+```
 
-**Default:** M (medium)
+### Decision Point
 
-## Phase 4: Create Bead
+```
+COMPLEXITY ANALYSIS
+━━━━━━━━━━━━━━━━━━━
 
-Reserve the artifacts directory:
+Request: "[user's request]"
 
-```typescript
-bd_reserve({
-  paths: [".beads/artifacts/<bead-id>/spec.md"],
-  reason: "Creating new task",
-  ttl: 600,
-});
-```
+Signals detected:
+✓ Multiple domains (frontend + backend)
+✓ Multi-phase work (setup → implement → test)
+✓ Integration required
 
-Propose:
+Classification: COMPLEX
 
-```
-Creating:
-  Title: [title]
-  Type: [type]
-  Priority: [0-4]
-  Estimate: [S/M/L/XL] (~[N] tool calls)
-  Role: [fe/be/mobile/devops/qa] (optional)
+Recommendation: Create Epic with 3-4 subtasks
 
-Approve? (yes/modify)
+Options:
+1. [Recommended] Create Epic + decompose into subtasks
+2. Create single bead (override complexity detection)
+3. Let me clarify scope first
+
+Choose (1/2/3): _
 ```
 
-On approval:
+**STOP and wait for user confirmation.**
+
+## Phase 4A: Simple Path (Single Bead)
+
+If SIMPLE or user overrides:
+
+### Type & Priority
+
+- **Type**: bug | feature | task | chore
+- **Priority**: 0 (critical) to 4 (low), default 2
+
+### Create Single Bead
 
 ```typescript
 bd_add({
@@ -89,69 +138,196 @@ bd_add({
   type: "[type]",
   pri: [priority],
   desc: "[description]",
-  tags: ["[role]", "[estimate]"], // e.g., ["fe", "M"]
+  tags: ["[role]", "[estimate]"],
 });
 ```
 
-### Link Dependencies
+### Create Spec
+
+Write `.beads/artifacts/<bead-id>/spec.md` (see Standard Spec template below).
+
+**Continue to Phase 6.**
+
+## Phase 4B: Complex Path (Epic + Subtasks)
+
+If COMPLEX and user confirms decomposition:
+
+### Step 1: Identify Natural Breakdown
+
+```
+DECOMPOSITION ANALYSIS
+━━━━━━━━━━━━━━━━━━━━━━
+
+Request: "Add user authentication with OAuth"
+
+Natural breakdown:
+
+1. Database & Schema [Backend]
+   - User table, sessions table
+   - Can start immediately
+
+2. OAuth Provider Integration [Backend]
+   - Google, GitHub providers
+   - Depends on: #1
 
-If this task depends on others:
+3. Auth API Endpoints [Backend]
+   - Login, logout, refresh
+   - Depends on: #1, #2
+
+4. Frontend Auth Flow [Frontend]
+   - Login page, protected routes
+   - Depends on: #3
+
+5. Testing & Documentation [QA]
+   - E2E tests, API docs
+   - Depends on: #3, #4
+
+Parallel execution possible:
+- Track A: #1 → #2 → #3
+- Track B: #4 (can start after #3 ready)
+- Track C: #5 (final)
+
+Create this structure? (yes/modify)
+```
+
+**STOP and wait for user confirmation.**
+
+### Step 2: Create Epic
 
 ```typescript
-bd_add({
-  title: "[title]",
-  type: "[type]",
+const epic = bd_add({
+  title: "[Feature Name]",
+  type: "epic",
   pri: [priority],
-  deps: ["<blocking-bead-id>"], // Tasks that must complete first
+  desc: "[Overview of the feature]",
+  tags: ["epic", "[domain]"],
 });
+// Returns: { id: "bd-a3f8" }
 ```
 
-### Assign to Role (optional)
+### Step 3: Create Child Tasks with Dependencies
 
 ```typescript
-bd_assign({ id: "<bead-id>", role: "[fe/be/mobile/devops/qa]", notify: true });
+// Task 1: No dependencies (can start immediately)
+const task1 = bd_add({
+  title: "Database schema for auth",
+  type: "task",
+  pri: 2,
+  parent: "bd-a3f8", // Links to epic
+  desc: "Create user and session tables",
+  tags: ["backend", "database", "S"],
+});
+// Returns: { id: "bd-a3f8.1" }
+
+// Task 2: Depends on Task 1
+const task2 = bd_add({
+  title: "OAuth provider integration",
+  type: "task",
+  pri: 2,
+  parent: "bd-a3f8",
+  deps: ["bd-a3f8.1"], // Blocked by task 1
+  desc: "Integrate Google and GitHub OAuth",
+  tags: ["backend", "M"],
+});
+// Returns: { id: "bd-a3f8.2" }
+
+// Task 3: Depends on Tasks 1 and 2
+const task3 = bd_add({
+  title: "Auth API endpoints",
+  type: "task",
+  pri: 2,
+  parent: "bd-a3f8",
+  deps: ["bd-a3f8.1", "bd-a3f8.2"],
+  desc: "Login, logout, refresh endpoints",
+  tags: ["backend", "api", "M"],
+});
+// Returns: { id: "bd-a3f8.3" }
+
+// Task 4: Depends on Task 3 (different domain - can be parallel agent)
+const task4 = bd_add({
+  title: "Frontend auth flow",
+  type: "task",
+  pri: 2,
+  parent: "bd-a3f8",
+  deps: ["bd-a3f8.3"],
+  desc: "Login page, protected routes, auth context",
+  tags: ["frontend", "M"],
+});
+// Returns: { id: "bd-a3f8.4" }
+
+// Task 5: Final task
+const task5 = bd_add({
+  title: "Auth testing and docs",
+  type: "task",
+  pri: 3,
+  parent: "bd-a3f8",
+  deps: ["bd-a3f8.3", "bd-a3f8.4"],
+  desc: "E2E tests and API documentation",
+  tags: ["qa", "docs", "S"],
+});
+// Returns: { id: "bd-a3f8.5" }
 ```
 
-## Phase 5: Create Spec
+### Step 4: Visualize Dependency Graph
 
-```bash
-mkdir -p .beads/artifacts/<bead-id>
+```
+DEPENDENCY GRAPH: bd-a3f8 "User Authentication"
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+bd-a3f8.1 [Database] ────┬────► bd-a3f8.2 [OAuth] ────┐
+     (ready)             │           │                │
+                         │           ▼                │
+                         └────► bd-a3f8.3 [API] ◄─────┘
+                                     │
+                    ┌────────────────┼────────────────┐
+                    ▼                                 ▼
+             bd-a3f8.4 [Frontend]              bd-a3f8.5 [Testing]
+                    │                                 ▲
+                    └─────────────────────────────────┘
+
+READY NOW: bd-a3f8.1 (no blockers)
+BLOCKED:   bd-a3f8.2, bd-a3f8.3, bd-a3f8.4, bd-a3f8.5
 ```
 
-Use the PRD template from `.opencode/memory/_templates/prd.md` as the base structure.
-
-Write `.beads/artifacts/<bead-id>/spec.md`:
+## Phase 5: Create Spec for Epic
 
-### Standard Spec (S/M complexity)
+Write `.beads/artifacts/<epic-id>/spec.md`:
 
 ```markdown
-# [Title]
+# [Feature Name]
 
-**Bead:** <bead-id>
+**Epic:** <epic-id>
 **Created:** [date]
-**Status:** To Do
-**Estimate:** [S/M] (~[N] tool calls)
+**Status:** In Progress
+**Complexity:** XL (decomposed into [N] subtasks)
 
 ## Goal
 
 [1-2 sentences: What exactly are we building and why?]
 
-## Scope
+## Subtasks
 
-**In-Scope:**
+| ID       | Title             | Status  | Depends On | Assignee |
+| -------- | ----------------- | ------- | ---------- | -------- |
+| <epic>.1 | Database schema   | Ready   | -          | backend  |
+| <epic>.2 | OAuth integration | Blocked | .1         | backend  |
+| <epic>.3 | API endpoints     | Blocked | .1, .2     | backend  |
+| <epic>.4 | Frontend flow     | Blocked | .3         | frontend |
+| <epic>.5 | Testing & docs    | Blocked | .3, .4     | qa       |
 
-- [What we ARE doing]
+## Parallel Execution
 
-**Out-of-Scope:**
+Agents can work in parallel on:
 
-- [What we are NOT doing]
+- **After .1 completes:** .2 can start
+- **After .3 completes:** .4 and .5 can start in parallel
 
 ## Success Criteria
 
-- [ ] [Criterion 1]
-  - Verify: `[actual command to test this]`
-- [ ] [Criterion 2]
-  - Verify: `[actual command to test this]`
+- [ ] All subtasks completed
+- [ ] Integration tests passing
+- [ ] [Specific acceptance criterion]
+  - Verify: `[command]`
 
 ## Constraints
 
@@ -168,111 +344,170 @@ Write `.beads/artifacts/<bead-id>/spec.md`:
 [Additional context]
 ```
 
-### Deep Spec (L/XL complexity)
+## Phase 6: Spec Quality Check
 
-Add these sections:
+Before presenting, verify:
 
-```markdown
-## User Flow
+- [ ] **Testable criteria?** Each success criterion has a verification command
+- [ ] **Constraints explicit?** "Must" and "Never" rules documented
+- [ ] **Dependencies correct?** Graph makes sense, no cycles
+- [ ] **Scope clear?** In/Out boundaries defined
+- [ ] **Parallel paths identified?** Agents can work concurrently
+
+## Phase 7: Review and Confirm
 
-1. [Step 1: What user sees/does]
-2. [Step 2]
-3. [Step 3]
+Present the structure for approval:
 
-## Dependencies
+```
+CREATED: [Feature Name]
+━━━━━━━━━━━━━━━━━━━━━━━
+
+Epic: bd-a3f8 "[Feature Name]"
+
+Subtasks:
+├── bd-a3f8.1: Database schema [S] ← READY
+├── bd-a3f8.2: OAuth integration [M] ← blocked by .1
+├── bd-a3f8.3: API endpoints [M] ← blocked by .1, .2
+├── bd-a3f8.4: Frontend flow [M] ← blocked by .3
+└── bd-a3f8.5: Testing & docs [S] ← blocked by .3, .4
 
-- `<bead-id>` - [what it provides]
-- [External dependency]
+Parallel Tracks:
+• Backend agent: .1 → .2 → .3
+• Frontend agent: .4 (after .3)
+• QA agent: .5 (after .3, .4)
 
-## Edge Cases
+Spec: .beads/artifacts/bd-a3f8/spec.md
 
-- [Edge case 1] → [expected behavior]
-- [Edge case 2] → [expected behavior]
+Quality check:
+✓ Testable criteria
+✓ Dependencies valid
+✓ Parallel paths identified
 
-## Open Questions
+Approve? (yes/modify)
+```
 
-- [Question for research phase]
-- [Uncertainty to resolve]
+**STOP and wait for human response.**
 
-## Technical Approach
+## Phase 8: Sync & Report
 
-[To be filled during /research phase]
+```typescript
+bd_sync({ reason: "Created epic $ARGUMENTS with subtasks" });
 ```
 
-## Phase 6: Spec Quality Check
+### Next Steps by Structure
 
-Before presenting, verify:
+**Single Bead (Simple):**
 
-- [ ] **Testable criteria?** Each success criterion has a verification command
-- [ ] **Constraints explicit?** "Must" and "Never" rules documented
-- [ ] **Edge cases identified?** (for L/XL complexity)
-- [ ] **Scope clear?** In/Out boundaries defined
-- [ ] **Estimate realistic?** Based on similar past work
+```
+Next: /implement <bead-id>
+```
 
-Fix any gaps before proceeding.
+**Epic with Subtasks (Complex):**
 
-## Phase 7: Review Spec
+```
+Ready to start: bd-a3f8.1 (first unblocked task)
 
-Present the spec for approval:
+Next steps:
+├── /implement bd-a3f8.1  (start first task)
+├── bd ready              (see all ready work)
+└── bd_blocked()          (see blocked tasks)
 
+For parallel agents:
+├── Agent 1: /implement bd-a3f8.1
+├── Agent 2: (wait for .1, then .2)
+└── Agent 3: (wait for .3, then .4)
 ```
-Spec Preview:
-━━━━━━━━━━━━━
 
-[Show full spec.md content]
+## Templates
 
-━━━━━━━━━━━━━
-Quality check:
-✓ Testable criteria
-✓ Constraints explicit
-✓ Scope clear
-[✓/⚠] Edge cases (if L/XL)
+### Standard Spec (Simple Tasks)
 
-Approve spec? (yes/modify)
-```
+```markdown
+# [Title]
 
-**STOP and wait for human response.**
+**Bead:** <bead-id>
+**Created:** [date]
+**Status:** To Do
+**Estimate:** [S/M] (~[N] tool calls)
 
-If "modify": Iterate on spec based on feedback until approved.
-If "yes": Proceed to sync and report.
+## Goal
 
-## Phase 8: Sync & Report
+[1-2 sentences: What exactly are we building and why?]
 
-```typescript
-bd_release({ _: true });
-bd_sync({ reason: "Created task $ARGUMENTS" });
-```
+## Scope
 
-```
-Created: <bead-id>
-━━━━━━━━━━━━━━━━━
+**In-Scope:**
 
-Title: [title]
-Type: [type]
-Estimate: [S/M/L/XL] (~[N] tool calls)
+- [What we ARE doing]
 
-Spec: .beads/artifacts/<bead-id>/spec.md
-```
+**Out-of-Scope:**
 
-### Next Steps by Complexity
+- [What we are NOT doing]
 
-**S/M complexity:**
+## Success Criteria
 
-```
-Next: /implement <bead-id>
-```
+- [ ] [Criterion 1]
+  - Verify: `[actual command to test this]`
+- [ ] [Criterion 2]
+  - Verify: `[actual command to test this]`
 
-**L complexity:**
+## Constraints
 
-```
-Next: /research <bead-id>
-```
+**Must:**
 
-**XL complexity:**
+- [Required constraint]
+
+**Never:**
 
+- [Anti-pattern or forbidden action]
+
+## Notes
+
+[Additional context]
 ```
-This task is too large. Break it down:
-  /create "[subtask 1]"  # Then link as dependency
-  /create "[subtask 2]"
-  /create "[subtask 3]"
+
+## When to Decompose
+
+| Scenario                   | Action                               |
+| -------------------------- | ------------------------------------ |
+| Bug fix                    | Single bead                          |
+| Config change              | Single bead                          |
+| Small feature (1 file)     | Single bead                          |
+| Feature touching 2-3 files | Single bead with phases in plan      |
+| Feature crossing FE/BE     | Epic + subtasks by domain            |
+| New system/service         | Epic + subtasks by component         |
+| Refactor multiple areas    | Epic + subtasks by area              |
+| Integration work           | Epic + subtasks by integration point |
+
+## Anti-Patterns
+
+❌ **One Giant Bead**
+Creating a single bead for "Implement entire auth system" - agents lose context, can't parallelize.
+
+❌ **Too Many Tiny Beads**  
+Creating 20 beads for a simple feature - overhead exceeds value.
+
+❌ **No Dependencies**
+Creating subtasks without linking dependencies - agents don't know execution order.
+
+❌ **Missing Domain Tags**
+Not tagging with `frontend`/`backend`/`qa` - can't route to specialized agents.
+
+## Integration with Parallel Agents
+
+When epic is created with proper dependencies:
+
+```typescript
+// Agent 1 claims ready work
+bd_init({ team: "project", role: "backend" });
+bd_claim(); // Gets bd-a3f8.1 (first ready task)
+
+// Agent 1 completes, Agent 2 can now start
+bd_done({ id: "bd-a3f8.1", msg: "Schema created" });
+
+// Agent 2 claims next ready work
+bd_claim(); // Gets bd-a3f8.2 (now unblocked)
+
+// After bd-a3f8.3 completes, both .4 and .5 become ready
+// Multiple agents can work on them in parallel
 ```

package/dist/template/.opencode/command/design-audit.md

@@ -7,6 +7,12 @@ model: proxypal/gemini-3-pro-preview
 
 # Design Audit: $ARGUMENTS
 
+## Load Beads Skill
+
+```typescript
+skill({ name: "beads" });
+```
+
 ## Phase 1: Source Detection & File Discovery
 
 Parse `$ARGUMENTS`:

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

@@ -6,6 +6,12 @@ agent: vision
 
 # Design: $ARGUMENTS
 
+## Load Beads Skill
+
+```typescript
+skill({ name: "beads" });
+```
+
 ## Phase 1: Context Discovery
 
 Parse `$ARGUMENTS` to determine design task:

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

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

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

@@ -11,6 +11,7 @@ agent: build
 **Load skills:**
 
 ```typescript
+skill({ name: "beads" }); // Session protocol
 skill({ name: "systematic-debugging" });
 skill({ name: "root-cause-tracing" });
 ```

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

@@ -6,6 +6,12 @@ agent: build
 
 # Fix Type Errors
 
+## Load Beads Skill
+
+```typescript
+skill({ name: "beads" });
+```
+
 ## Options
 
 - `--strict`: Also fix warnings and enable stricter checks