opencodekit 0.10.0 → 0.11.1

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

@@ -1,51 +1,136 @@
 ---
-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
 
-## Phase 1: Interview
+## 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, offset: 0 });
+```
+
+If similar task exists:
+
+- Link as dependency, or
+- Extend existing task, or
+- Confirm this is intentionally separate
+
+## Phase 2: Interview
 
 **If title provided:** Use `$ARGUMENTS` as starting point.
 
-**If no title:** Ask:
+**If no title:** Ask in one message:
 
 1. "What problem are we solving?"
 2. "Bug, feature, or task?"
 3. "What's the acceptance criteria?"
+4. "Any constraints or 'never do X' rules?"
+5. "Related existing code or past work?"
 
-Keep it brief. Get: clear goal, success criteria, scope.
+Keep it brief. Get: clear goal, success criteria, scope, constraints.
 
-## Phase 2: Classify
+## Phase 3: Complexity Analysis
 
-Based on interview:
+Analyze the request to determine if it should be a single bead or decomposed:
 
-- **Type**: bug | feature | task | chore
-- **Priority**: 0 (critical) to 4 (low), default 2
-- **Complexity**: quick | deep
+### Complexity Signals
 
-**Quick** (default): Simple bugs, small changes, clear scope. No research/plan needed.
+```
+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
+```
 
-**Deep**: Complex features, unknowns, architectural changes. Needs research and planning.
+### Automatic Classification
 
-## Phase 3: Create Bead
+```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";
+};
+```
 
-Propose:
+### Decision Point
 
 ```
-Creating:
-  Title: [title]
-  Type: [type]
-  Priority: [0-4]
-  Complexity: [quick/deep]
-  Role: [fe/be/mobile/devops/qa] (optional, for multi-agent)
+COMPLEXITY ANALYSIS
+━━━━━━━━━━━━━━━━━━━
 
-Approve? (yes/modify)
+Request: "[user's request]"
+
+Signals detected:
+✓ Multiple domains (frontend + backend)
+✓ Multi-phase work (setup → implement → test)
+✓ Integration required
+
+Classification: COMPLEX
+
+Recommendation: Create Epic with 3-4 subtasks
+
+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({
@@ -53,123 +138,376 @@ bd_add({
   type: "[type]",
   pri: [priority],
   desc: "[description]",
+  tags: ["[role]", "[estimate]"],
 });
 ```
 
-**If using Beads Village for multi-agent coordination:** Add role tags so tasks can be auto-assigned to the right agent:
+### 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
+
+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]", pri: [priority], tags: ["[role]"] });
+const epic = bd_add({
+  title: "[Feature Name]",
+  type: "epic",
+  pri: [priority],
+  desc: "[Overview of the feature]",
+  tags: ["epic", "[domain]"],
+});
+// Returns: { id: "bd-a3f8" }
 ```
 
-This makes the task claimable by agents with matching roles.
+### Step 3: Create Child Tasks with Dependencies
 
-## Phase 4: Create Spec
+```typescript
+// 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" }
+```
+
+### 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.
+## Phase 5: Create Spec for Epic
 
-Write `.beads/artifacts/<bead-id>/spec.md`:
+Write `.beads/artifacts/<epic-id>/spec.md`:
 
 ```markdown
-# [Title]
+# [Feature Name]
 
-**Bead:** <bead-id>
+**Epic:** <epic-id>
 **Created:** [date]
-**Status:** To Do
+**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
 
-## User Flow
+## Success Criteria
 
-1. [Step 1: What user sees/does]
-2. [Step 2]
-3. [Step 3]
+- [ ] All subtasks completed
+- [ ] Integration tests passing
+- [ ] [Specific acceptance criterion]
+  - Verify: `[command]`
 
-## Success Criteria
+## Constraints
 
-- [ ] [Specific, measurable criterion 1]
-- [ ] [Specific, measurable criterion 2]
-- [ ] [Specific, measurable criterion 3]
+**Must:**
 
-## Dependencies
+- [Required constraint]
 
-- [List any prerequisites or blocking tasks]
+**Never:**
+
+- [Anti-pattern or forbidden action]
 
 ## Notes
 
-[Additional context or constraints]
+[Additional context]
 ```
 
-For **Quick** mode, simplify: Goal, Success Criteria, Notes only.
+## Phase 6: Spec Quality Check
 
-For **Deep** mode, add:
+Before presenting, verify:
 
-```markdown
-## Open Questions
+- [ ] **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
 
-- [Question for research phase]
+## Phase 7: Review and Confirm
 
-## Technical Approach
+Present the structure for approval:
 
-[To be filled during /research phase]
 ```
+CREATED: [Feature Name]
+━━━━━━━━━━━━━━━━━━━━━━━
 
-## Phase 5: Review Spec
+Epic: bd-a3f8 "[Feature Name]"
 
-Present the spec for approval:
+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
 
-```
-Spec Preview:
-━━━━━━━━━━━━━
+Parallel Tracks:
+• Backend agent: .1 → .2 → .3
+• Frontend agent: .4 (after .3)
+• QA agent: .5 (after .3, .4)
+
+Spec: .beads/artifacts/bd-a3f8/spec.md
 
-[Show full spec.md content]
+Quality check:
+✓ Testable criteria
+✓ Dependencies valid
+✓ Parallel paths identified
 
-━━━━━━━━━━━━━
-Approve spec? (yes/modify)
+Approve? (yes/modify)
 ```
 
 **STOP and wait for human response.**
 
-If "modify": Iterate on spec based on feedback until approved.
-If "yes": Proceed to report.
-
-## Phase 6: Report
+## Phase 8: Sync & Report
 
+```typescript
+bd_sync({ reason: "Created epic $ARGUMENTS with subtasks" });
 ```
-Created: <bead-id>
-━━━━━━━━━━━━━━━━━
 
-Title: [title]
-Type: [type]
-Mode: [Quick/Deep]
+### Next Steps by Structure
+
+**Single Bead (Simple):**
 
-Spec: .beads/artifacts/<bead-id>/spec.md
+```
+Next: /implement <bead-id>
 ```
 
-**Quick mode next step:**
+**Epic with Subtasks (Complex):**
 
 ```
-Next: /implement <bead-id>
+Ready to start: bd-a3f8.1 (first unblocked task)
+
+Next steps:
+├── /implement bd-a3f8.1  (start first task)
+├── bd ready              (see all ready work)
+└── bd_plan()             (see parallel execution plan)
+
+For parallel agents:
+├── Agent 1: /implement bd-a3f8.1
+├── Agent 2: (wait for .1, then .2)
+└── Agent 3: (wait for .3, then .4)
 ```
 
-**Deep mode next step:**
+## Templates
+
+### Standard Spec (Simple Tasks)
+
+```markdown
+# [Title]
+
+**Bead:** <bead-id>
+**Created:** [date]
+**Status:** To Do
+**Estimate:** [S/M] (~[N] tool calls)
+
+## Goal
+
+[1-2 sentences: What exactly are we building and why?]
 
+## Scope
+
+**In-Scope:**
+
+- [What we ARE doing]
+
+**Out-of-Scope:**
+
+- [What we are NOT doing]
+
+## Success Criteria
+
+- [ ] [Criterion 1]
+  - Verify: `[actual command to test this]`
+- [ ] [Criterion 2]
+  - Verify: `[actual command to test this]`
+
+## Constraints
+
+**Must:**
+
+- [Required constraint]
+
+**Never:**
+
+- [Anti-pattern or forbidden action]
+
+## Notes
+
+[Additional context]
 ```
-Next: /research <bead-id>
+
+## 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
 ```