opencodekit 0.13.0 → 0.13.2

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

@@ -1,166 +1,438 @@
 ---
-description: Create implementation plan for a bead
-argument-hint: "<bead-id> [--create-beads]"
+description: Create implementation plan for a bead with subtask hierarchy
+argument-hint: "<bead-id> [--create-beads] [--parallel]"
 agent: planner
 ---
 
 # Plan: $ARGUMENTS
 
-You're creating an implementation plan. Design first, then execute.
+You're creating an implementation plan with proper Epic → Task → Subtask hierarchy and subagent research.
 
-## Load Context
+## Parse Arguments
 
-!`bd show $ARGUMENTS`
-!`cat .beads/artifacts/$ARGUMENTS/spec.md`
-!`cat .beads/artifacts/$ARGUMENTS/research.md 2>/dev/null`
+| Argument         | Default  | Description                               |
+| ---------------- | -------- | ----------------------------------------- |
+| `<bead-id>`      | required | The bead to plan                          |
+| `--create-beads` | false    | Create child beads after planning         |
+| `--parallel`     | false    | Run aggressive parallel subagent research |
 
-If spec.md missing: "Run `/create $ARGUMENTS` first."
-If complexity > M and no research: "Consider `/research $ARGUMENTS` first."
+## Load Skills & Context
 
-## Analyze For Decomposition
+```typescript
+skill({ name: "beads" });
+```
 
-Should this be one bead or multiple?
+```bash
+bd show $ARGUMENTS
+```
 
-**Keep as single bead:**
+Check for existing artifacts:
 
-- Single domain (just frontend OR just backend)
-- 2-3 files max
-- ~50 tool calls or less
-- No natural phases
+```bash
+cat .beads/artifacts/$ARGUMENTS/spec.md 2>/dev/null || echo "No spec found"
+cat .beads/artifacts/$ARGUMENTS/research.md 2>/dev/null || echo "No research found"
+```
 
-**Decompose into subtasks:**
+**If spec.md missing:** "Run `/create $ARGUMENTS` first to create a specification."
 
-- Crosses domains (frontend + backend)
-- Multiple independent pieces
-- Natural phases (setup → implement → test)
-- Could benefit from parallel agents
+**If complexity > M and no research:** "Consider `/research $ARGUMENTS` first for better planning."
 
-If decomposition makes sense, ask: "This would benefit from subtasks. Create child beads?"
+---
 
-## Generate Design Options
+## Phase 1: Parallel Subagent Research
+
+Gather context before designing. Fire both in parallel:
+
+```typescript
+// Codebase patterns
+Task({
+  subagent_type: "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",
+});
+
+// External best practices
+Task({
+  subagent_type: "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",
+});
+```
 
-Present 2-3 approaches:
+**Continue working while subagents research.**
+
+---
+
+## Phase 2: Analyze for Decomposition
+
+Determine the right level of granularity.
+
+### Hierarchy Decision Tree
 
 ```
-## Option A: [Name]
+Is this work...
+├── Single domain, 2-3 files, ~50 tool calls?
+│   └── Keep as single bead → Skip to "Generate Design Options"
+│
+├── Crosses domains (frontend + backend)?
+│   └── Create task per domain
+│
+├── Has natural phases (setup → implement → test)?
+│   └── Create task per phase
+│
+├── Could benefit from parallel agents?
+│   └── Create independent tasks
+│
+└── Would take multiple sessions?
+    └── Create epic with task breakdown
+```
+
+### Size Estimation Guide
+
+| Size | Tool Calls | Duration  | Hierarchy Level |
+| ---- | ---------- | --------- | --------------- |
+| S    | ~10        | 30 min    | Subtask         |
+| M    | ~30        | 1-2 hours | Task            |
+| L    | ~100       | 4-8 hours | Task (or Epic)  |
+| XL   | 100+       | Days      | Epic required   |
 
-Approach: [1-2 sentences]
+**If XL detected:** "This requires epic-level decomposition. Creating subtasks is mandatory."
+
+---
+
+## Phase 3: Generate Design Options
+
+Present 2-3 implementation approaches:
+
+```markdown
+## Design Options for $ARGUMENTS
+
+### Option A: [Name]
+
+**Approach:** [1-2 sentences]
+
+**Changes:**
 
-Changes:
 - `src/foo.ts` - [what]
 - `src/bar.ts` - [what]
 
-Pros: [list]
-Cons: [list]
-Effort: [S/M/L] (~N tool calls)
+**Pros:** [list]
+**Cons:** [list]
+**Effort:** [S/M/L] (~N tool calls)
 
 ---
 
-## Option B: [Name]
+### Option B: [Name]
+
+**Approach:** [1-2 sentences]
+
+**Changes:**
 
-[same format]
+- `src/different.ts` - [what]
+
+**Pros:** [list]
+**Cons:** [list]
+**Effort:** [S/M/L] (~N tool calls)
 
 ---
 
-Recommendation: Option [A/B] because [reason].
+### Recommendation
+
+Option [X] because [reason].
+
+Decomposition: [Single bead | X tasks | X tasks with subtasks]
 ```
 
 Save to `.beads/artifacts/$ARGUMENTS/design.md`.
 
 **STOP. Wait for user to pick an option.**
 
-## Create Plan
+---
+
+## Phase 4: Create Task Hierarchy
+
+After user approval, design the hierarchy.
+
+### For Single Bead (S/M size)
 
-After approval, write `.beads/artifacts/$ARGUMENTS/plan.md`:
+Skip hierarchy, go directly to plan.md.
+
+### For Multi-Task Work (L/XL size)
+
+Design the decomposition:
 
 ```markdown
-# Plan: [Title]
+## Task Breakdown
 
-**Bead:** $ARGUMENTS
-**Approach:** [selected option]
-**Estimate:** ~N tool calls
+### Task 1: [Foundation/Setup] [S]
 
-## Tasks
+**Domain:** [backend/frontend/infra]
+**Blocked by:** None
+**Work:**
 
-### 1. [Task name]
+- [Specific deliverable]
+- [Specific deliverable]
 
-Files: `src/foo.ts`
-Changes:
+### Task 2: [Core Implementation] [M]
 
-- [ ] [specific change]
-- [ ] [specific change]
+**Domain:** [backend/frontend/infra]
+**Blocked by:** Task 1
+**Work:**
 
-Verify: `npm test -- foo.test.ts`
+- [Specific deliverable]
+
+**Subtasks (if complex):**
+
+- 2.1: [Atomic unit of work] [S]
+- 2.2: [Atomic unit of work] [S] → blocked by 2.1
+
+### Task 3: [Integration/Testing] [S]
+
+**Domain:** [testing]
+**Blocked by:** Task 2
+**Work:**
+
+- [Specific deliverable]
+```
 
 ---
 
-### 2. [Task name]
+## Phase 5: Create Child Beads (if --create-beads)
+
+With user approval or `--create-beads` flag:
 
-Depends on: Task 1
-Files: `src/bar.ts`
-Changes:
+```bash
+# Get parent bead ID
+PARENT=$ARGUMENTS
+
+# Task 1 (no blockers - starts immediately)
+bd create "[Task 1 title]" -t task -p 2
+# Capture: bd-xxx1
+
+# Link to parent
+bd dep add bd-xxx1 $PARENT
+
+# Task 2 (blocked by Task 1)
+bd create "[Task 2 title]" -t task -p 2
+# Capture: bd-xxx2
+
+bd dep add bd-xxx2 $PARENT
+bd dep add bd-xxx2 bd-xxx1 --type blocks
+
+# Task 3 (blocked by Task 2)
+bd create "[Task 3 title]" -t task -p 2
+# Capture: bd-xxx3
+
+bd dep add bd-xxx3 $PARENT
+bd dep add bd-xxx3 bd-xxx2 --type blocks
+```
+
+### Create Subtasks (for complex tasks)
+
+```bash
+# For Task 2, create subtasks:
+bd create "[Subtask 2.1 title]" -t subtask -p 2
+# Capture: bd-xxx2.1
 
-- [ ] [specific change]
+bd dep add bd-xxx2.1 bd-xxx2
+
+bd create "[Subtask 2.2 title]" -t subtask -p 2
+# Capture: bd-xxx2.2
+
+bd dep add bd-xxx2.2 bd-xxx2
+bd dep add bd-xxx2.2 bd-xxx2.1 --type blocks  # Sequential dependency
+```
 
-Verify: `npm test -- bar.test.ts`
+### Verify Hierarchy
+
+```bash
+bd dep tree $ARGUMENTS
+```
 
 ---
 
-## Final Verification
+## Phase 6: Create Plan Document
+
+Write `.beads/artifacts/$ARGUMENTS/plan.md`:
+
+```markdown
+# Implementation Plan: [Title]
 
-- [ ] `npm test`
-- [ ] `npm run type-check`
+**Bead:** $ARGUMENTS
+**Approach:** [Selected option]
+**Total estimate:** ~N tool calls ([X-Y hours])
+
+## Hierarchy
 ```
 
-## If Creating Child Beads
+$ARGUMENTS (Epic/Task)
+├── bd-xxx1: [Title] [S] ← READY
+├── bd-xxx2: [Title] [M] → blocked by bd-xxx1
+│ ├── bd-xxx2.1: [Subtask] [S]
+│ └── bd-xxx2.2: [Subtask] [S] → blocked by bd-xxx2.1
+└── bd-xxx3: [Title] [S] → blocked by bd-xxx2
+
+```
+
+---
+
+## Task 1: [Title] [S]
+
+**Bead:** bd-xxx1
+**Estimate:** ~10 tool calls (30 min)
+**Blocked by:** None
+
+**Files:**
+- `src/foo.ts`
+
+**Changes:**
+- [ ] [Specific change with detail]
+- [ ] [Specific change with detail]
+
+**Verify:** `npm test -- foo.test.ts`
+
+---
+
+## Task 2: [Title] [M]
+
+**Bead:** bd-xxx2
+**Estimate:** ~30 tool calls (1-2 hours)
+**Blocked by:** Task 1
+
+**Subtasks:**
+
+### 2.1: [Subtask Title] [S]
+
+**Bead:** bd-xxx2.1
+**Files:** `src/bar.ts`
+**Changes:**
+- [ ] [Specific change]
+
+**Verify:** `npm test -- bar.test.ts`
+
+### 2.2: [Subtask Title] [S]
+
+**Bead:** bd-xxx2.2
+**Blocked by:** 2.1
+**Files:** `src/baz.ts`
+**Changes:**
+- [ ] [Specific change]
 
-With `--create-beads` flag or user approval:
+**Verify:** `npm test -- baz.test.ts`
 
-````bash
-# Task 1 (no blockers)
-bd create "[task 1 title]" -t task -p 2
+---
+
+## Task 3: [Title] [S]
+
+**Bead:** bd-xxx3
+**Estimate:** ~10 tool calls (30 min)
+**Blocked by:** Task 2
+
+**Files:**
+- `tests/integration/`
+
+**Changes:**
+- [ ] [Specific change]
+
+**Verify:** `npm run test:integration`
+
+---
 
-# Task 2 (blocked by task 1)
-bd create "[task 2 title]" -t task -p 2
-bd dep add bd-[task2] bd-[task1] --type blocks
+## Final Verification
 
-!`bd dep tree $ARGUMENTS`
+- [ ] All acceptance criteria from spec.md met
+- [ ] Full test suite: `npm test`
+- [ ] Type check: `npm run typecheck`
+- [ ] Lint: `npm run lint`
 
-Update plan.md with bead IDs.
+## Rollback Plan
 
-## Sync
+If issues detected after deployment:
+1. [Rollback step 1]
+2. [Rollback step 2]
+```
+
+---
+
+## Phase 7: Sync and Report
 
 ```bash
 bd sync
-````
-
-## Output
+```
 
-Without child beads:
+### Output (without child beads)
 
 ```
-Plan: $ARGUMENTS
+Plan Complete: $ARGUMENTS
+━━━━━━━━━━━━━━━━━━━━━━━━
 
-Approach: [selected]
-Tasks: [count]
+Approach: [Selected option]
+Tasks: 1 (single bead)
 Estimate: ~N tool calls
 
 Artifacts:
-- .beads/artifacts/$ARGUMENTS/design.md
-- .beads/artifacts/$ARGUMENTS/plan.md
+├── .beads/artifacts/$ARGUMENTS/design.md
+└── .beads/artifacts/$ARGUMENTS/plan.md
 
 Next: /implement $ARGUMENTS
 ```
 
-With child beads:
+### Output (with child beads)
 
 ```
-Plan: $ARGUMENTS (Epic)
+Plan Complete: $ARGUMENTS (Epic)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Approach: [Selected option]
+Total estimate: ~N tool calls ([X-Y hours])
 
-Subtasks:
-├── bd-[x].1: [title] ← READY
-├── bd-[x].2: [title] ← blocked by .1
-└── bd-[x].3: [title] ← blocked by .2
+Hierarchy:
+├── bd-xxx1: [Title] [S] ← READY
+├── bd-xxx2: [Title] [M] → blocked by bd-xxx1
+│   ├── bd-xxx2.1: [Subtask] [S]
+│   └── bd-xxx2.2: [Subtask] [S]
+└── bd-xxx3: [Title] [S] → blocked by bd-xxx2
+
+Artifacts:
+├── .beads/artifacts/$ARGUMENTS/design.md
+└── .beads/artifacts/$ARGUMENTS/plan.md
 
-Next: /implement bd-[x].1
+Ready to start: bd-xxx1
+
+Next: /start bd-xxx1
 ```
+
+---
+
+## Subagent Delegation Summary
+
+| Phase              | Subagent   | Purpose                              |
+| ------------------ | ---------- | ------------------------------------ |
+| Research           | `@explore` | Find codebase patterns               |
+| Research           | `@scout`   | Find best practices                  |
+| Design options     | None       | Planner creates                      |
+| Hierarchy creation | None       | Planner uses `bd` CLI                |
+| Implementation     | `@build`   | Delegated via `/start`, `/implement` |
+
+**Key Rule:** Planner is read-only. Creates structure and artifacts. Build agent executes.
+
+---
+
+## Related Commands
+
+| Need                 | Command                  |
+| -------------------- | ------------------------ |
+| Create spec first    | `/create <bead-id>`      |
+| Research before plan | `/research <bead-id>`    |
+| Start first task     | `/start <first-task-id>` |
+| View hierarchy       | `bd dep tree <bead-id>`  |
+| Import external plan | `/import-plan`           |

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

@@ -43,8 +43,9 @@ Don't duplicate work that's already been done.
 1. **Codebase patterns** (highest trust) - How does this project already do it?
 2. **Official docs** (high trust) - What does the library documentation say?
 3. **Context7** (high trust) - API usage and examples
-4. **GitHub examples** (medium trust) - Real-world patterns via codesearch/gh_grep
-5. **Web search** (lower trust) - Only if tiers 1-4 don't answer
+4. **Source code** (high trust) - Library implementation (use `source-code-research` skill)
+5. **GitHub examples** (medium trust) - Real-world patterns via codesearch/gh_grep
+6. **Web search** (lower trust) - Only if tiers 1-5 don't answer
 
 ## Research
 
@@ -67,6 +68,32 @@ context7_resolve_library_id({ libraryName: "<lib>", query: "<question>" });
 context7_query_docs({ libraryId: "<id>", query: "<specific question>" });
 ```
 
+### Source Code (When Docs Insufficient)
+
+**Use the `source-code-research` skill when:**
+
+- Documentation doesn't explain behavior clearly
+- Need to understand edge cases or internals
+- Library behaving unexpectedly
+- Evaluating library quality/fit
+
+```bash
+# Fetch package source code
+npx opensrc <package>              # npm package
+npx opensrc <package>@<version>    # specific version
+npx opensrc pypi:<package>         # Python
+npx opensrc <owner>/<repo>         # GitHub repo
+```
+
+```typescript
+// Then analyze the source
+glob({ pattern: "opensrc/**/src/**/*.ts" });
+grep({ pattern: "<function-name>", path: "opensrc/" });
+read({ filePath: "opensrc/repos/.../file.ts" });
+```
+
+**See:** `skill({ name: "source-code-research" })` for complete workflow.
+
 ### Code Examples
 
 ```typescript