opencodekit 0.10.0 → 0.11.1

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,21 +29,73 @@ 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.
 
-## Phase 2: Generate Design Options
+Reserve files while planning:
 
-Present 2-3 approaches:
+```typescript
+bd_reserve({
+  paths: [
+    ".beads/artifacts/<bead-id>/design.md",
+    ".beads/artifacts/<bead-id>/plan.md",
+  ],
+  reason: "Planning $ARGUMENTS",
+  ttl: 1200,
+});
+```
+
+## 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:
+
+```markdown
 ## Design Options
 
 ### Option A: [Name]
@@ -38,202 +103,424 @@ Present 2-3 approaches:
 **Approach:** [1-2 sentence description]
 
 **Changes:**
+
 - `src/foo.ts` - [what changes]
 - `src/bar.ts` - [what changes]
 
-**Pros:**
-- [pro 1]
-- [pro 2]
+**Pros:** [bullet list]
+**Cons:** [bullet list]
+
+**Estimation:**
 
-**Cons:**
-- [con 1]
+- Tool calls: ~[N] (S=5-20, M=20-50, L=50-100, XL=needs decomposition)
+- Files touched: [N]
+- Risk: [low/medium/high]
 
-**Effort:** [S/M/L]
+**Parallelization potential:** [High/Medium/Low]
 
 ---
 
 ### Option B: [Name]
 
-**Approach:** [1-2 sentence description]
+[Same format]
 
-**Changes:**
-- `src/baz.ts` - [what changes]
+---
 
-**Pros:**
-- [pro 1]
+**Recommendation:** Option [A/B] because [reason].
+```
 
-**Cons:**
-- [con 1]
-- [con 2]
+Save to `.beads/artifacts/<bead-id>/design.md` with status `Pending Approval`.
 
-**Effort:** [S/M/L]
+## Phase 4: Get Approval
 
----
+**STOP and wait for human response.**
 
-**Recommendation:** Option [A/B] because [reason].
+```
+Pick an option (A/B/C), modify, or "none" to propose alternatives.
 ```
 
-## Phase 3: Save Design Document
+Do not proceed until user confirms.
 
-Save design options to `.beads/artifacts/<bead-id>/design.md`:
+## Phase 5: Create Plan with Task Contracts
+
+After approval, write `.beads/artifacts/<bead-id>/plan.md`:
 
 ```markdown
-# Design Options: [Title]
+# Implementation Plan: [Title]
 
 **Bead:** <bead-id>
 **Date:** <date>
-**Status:** Pending Approval
+**Approach:** [selected option name]
+**Estimation:** ~[N] tool calls, [N] files
+**Decomposition:** [Yes - child beads created / No - single bead]
 
-## Problem Statement
+## Dependency Graph
+```
 
-[What we're solving - from spec.md]
+[Task 1] ──┬──> [Task 2a] ──┬──> [Task 4]
+│ │
+└──> [Task 2b] ──┘
+│
+└──> [Task 3] (can run parallel)
 
-## Options Considered
+````
 
-### Option A: [Name]
+**Parallel Tracks:**
+- Track A: Tasks 1 → 2a → 4
+- Track B: Tasks 1 → 2b → 3 (independent after Task 1)
 
-**Approach:** [1-2 sentence description]
+## Tasks
+
+### Task 1: [Title]
+
+| Field         | Value                              |
+| ------------- | ---------------------------------- |
+| **Bead**      | [child-bead-id if created]         |
+| **Files**     | `src/foo.ts`                       |
+| **Input**     | [What this task receives/needs]    |
+| **Output**    | [What this task produces]          |
+| **Success**   | [Concrete verification criteria]   |
+| **Rollback**  | [How to undo if this fails]        |
+| **Depends**   | None                               |
+| **Effort**    | S (~10 tool calls)                 |
 
 **Changes:**
+- [ ] [Specific change 1]
+- [ ] [Specific change 2]
 
-- `src/foo.ts` - [what changes]
-- `src/bar.ts` - [what changes]
+**Verification:**
+```bash
+[Actual command to verify success]
+````
 
-**Pros:**
+---
 
-- [pro 1]
-- [pro 2]
+### Task 2a: [Title]
 
-**Cons:**
+| Field        | Value                            |
+| ------------ | -------------------------------- |
+| **Bead**     | [child-bead-id if created]       |
+| **Files**    | `src/bar.ts`                     |
+| **Input**    | Output from Task 1               |
+| **Output**   | [What this produces]             |
+| **Success**  | [Test passes, type checks, etc.] |
+| **Rollback** | `git checkout src/bar.ts`        |
+| **Depends**  | Task 1                           |
+| **Effort**   | M (~30 tool calls)               |
 
-- [con 1]
+**Changes:**
 
-**Effort:** [S/M/L]
+- [ ] [Specific change]
 
----
+**Verification:**
 
-### Option B: [Name]
+```bash
+npm run test -- src/bar.test.ts
+```
 
-**Approach:** [1-2 sentence description]
+---
 
-**Changes:**
+[Continue for all tasks...]
 
-- `src/baz.ts` - [what changes]
+## Escape Hatches
 
-**Pros:**
+- **Max iterations per task:** 3 attempts before human intervention
+- **Checkpoint after:** Tasks 2a, 3 (high-risk points)
+- **Abort if:** [Condition that means we should stop]
 
-- [pro 1]
+## Final Verification
 
-**Cons:**
+- [ ] All task verifications pass
+- [ ] `npm run type-check` passes
+- [ ] `npm run test` passes
+- [ ] Manual smoke test: [specific action]
 
-- [con 1]
-- [con 2]
+## Risks
 
-**Effort:** [S/M/L]
+| Risk     | Likelihood | Impact | Mitigation      |
+| -------- | ---------- | ------ | --------------- |
+| [Risk 1] | Medium     | High   | [How to handle] |
+| [Risk 2] | Low        | Medium | [How to handle] |
 
----
+````
 
-## Recommendation
+## Phase 6: Create Child Beads (if --create-beads or user approved)
 
-Option [A/B] because [reason].
+For each task in the plan, create a child bead:
 
-## Decision
+```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
 
-**Chosen:** [To be filled after approval]
-**Rationale:** [To be filled after approval]
 ```
+CHILD BEADS CREATED
+━━━━━━━━━━━━━━━━━━━
 
-## Phase 4: Get Approval
+Parent: <parent-id> "[Title]"
 
-**STOP and wait for human response.**
+<parent>.1 [Task 1] ──┬──> <parent>.2 [Task 2a] ──┬──> <parent>.5 [Task 4]
+     (READY)          │          │                │
+                      │          ▼                │
+                      └──> <parent>.3 [Task 2b] ──┘
+                      │
+                      └──> <parent>.4 [Task 3]
+                                (parallel track)
 
-```
-Pick an option (A/B/C), modify, or "none" to propose alternatives.
-```
+READY NOW: <parent>.1
+PARALLEL AFTER .1: <parent>.2, <parent>.3, <parent>.4
+FINAL: <parent>.5
 
-Do not proceed until user confirms.
+Run `bd ready` to see claimable work.
+```
 
-## Phase 5: Update Design Decision
+## Phase 7: Upgrade Parent to Epic (if needed)
 
-After approval, update `.beads/artifacts/<bead-id>/design.md`:
+If parent was a `task` or `feature` and we created children, upgrade it:
 
-- Change **Status:** to `Approved`
-- Fill in **Chosen:** with selected option
-- Fill in **Rationale:** with user's reasoning
+```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 6: Create Plan
+## Phase 8: Generate ADR & Sync
 
-After approval, write `.beads/artifacts/<bead-id>/plan.md`:
+Create `.beads/artifacts/<bead-id>/adr.md`:
 
 ```markdown
-# Implementation Plan: [Title]
+# ADR: [Decision Title]
 
-**Bead:** <bead-id>
+**Status:** Accepted
 **Date:** <date>
-**Approach:** [selected option name]
+**Bead:** <bead-id>
 
-## Overview
+## Context
 
-[1-2 paragraph description of approach]
+[Problem statement from spec.md - why we needed to decide]
 
-## Steps
+## Decision
 
-### Step 1: [Title]
+We chose **[Option Name]** because:
 
-**Files:** `src/foo.ts`
+- [Reason 1]
+- [Reason 2]
 
-**Changes:**
+## Alternatives Considered
 
-- [ ] [Specific change 1]
-- [ ] [Specific change 2]
+- **[Option B]:** Rejected because [reason]
+- **[Option C]:** Rejected because [reason]
 
-**Tests:** [What to verify]
+## Decomposition Decision
 
----
+[If child beads created:]
+We decomposed this into [N] subtasks because:
 
-### Step 2: [Title]
+- [Reason: parallel execution, context management, etc.]
 
-**Files:** `src/bar.ts`, `src/baz.ts`
+Child beads: <parent>.1, <parent>.2, ...
 
-**Changes:**
+[If not decomposed:]
+We kept this as a single bead because:
 
-- [ ] [Specific change]
+- [Reason: small scope, single domain, etc.]
 
-**Tests:** [What to verify]
+## Consequences
 
----
+**Positive:**
 
-### Step 3: [Title]
+- [Benefit 1]
+- [Benefit 2]
 
-...
+**Negative:**
 
-## Verification
+- [Tradeoff 1]
+- [Tradeoff 2]
 
-- [ ] Unit tests pass
-- [ ] Integration tests pass
-- [ ] Type check passes
-- [ ] [Custom verification from spec]
+## Confirmation
 
-## Risks
+This decision is confirmed when:
 
-- [Risk 1] - [mitigation]
+- [ ] Implementation complete per plan.md
+- [ ] All verification steps pass
 ```
 
-## Phase 7: Update Bead
+Update bead and sync:
 
-Add a note about plan approval via `bd_msg` or update the spec with the approved approach.
+```typescript
+bd_msg({
+  subj: "Plan approved",
+  body: `Approach: [selected option]\nTasks: [count]\nChild beads: [yes/no]\nEstimate: ~[N] tool calls`,
+  to: "all",
+  importance: "normal",
+  global: true,
+});
+
+bd_release({ _: true });
+bd_sync({ reason: "Plan approved for $ARGUMENTS" });
+```
 
 ## Output
 
+### Without Child Beads
+
 ```
 Plan Approved: <bead-id>
 ━━━━━━━━━━━━━━━━━━━━━━━━
 
 Approach: [selected option]
-Steps: [count]
-Effort: [S/M/L]
+Tasks: [count] (tracked in plan.md)
+Estimate: ~[N] tool calls
 
-Plan saved: .beads/artifacts/<bead-id>/plan.md
+Artifacts:
+- .beads/artifacts/<bead-id>/design.md (approved)
+- .beads/artifacts/<bead-id>/plan.md
+- .beads/artifacts/<bead-id>/adr.md
 
 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
+```