opencodekit 0.13.0 → 0.13.2

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

@@ -1,6 +1,6 @@
 ---
 description: Start working on a bead - claim it and prepare context
-argument-hint: "<bead-id>"
+argument-hint: "<bead-id> [--worktree] [--research]"
 agent: build
 ---
 
@@ -8,6 +8,14 @@ agent: build
 
 You're claiming a task and preparing to work on it. This is the entry point before implementation.
 
+## Parse Arguments
+
+| Argument     | Default  | Description                                    |
+| ------------ | -------- | ---------------------------------------------- |
+| `<bead-id>`  | required | The bead to start working on                   |
+| `--worktree` | false    | Create isolated git worktree for this work     |
+| `--research` | false    | Run parallel subagent research before starting |
+
 ## Load Skills
 
 ```typescript
@@ -45,13 +53,29 @@ If you already have tasks in_progress, warn the user before claiming another.
 
 !`bd show $ARGUMENTS`
 
+Identify the task type from the bead:
+
+| Type      | Hierarchy Level | Typical Scope                     |
+| --------- | --------------- | --------------------------------- |
+| `epic`    | Parent          | Multi-session, has subtasks       |
+| `task`    | Middle          | Single session, may have subtasks |
+| `subtask` | Leaf            | Single focused unit of work       |
+
+Check for parent/child relationships:
+
+```bash
+bd dep tree $ARGUMENTS 2>/dev/null || echo "No dependencies"
+```
+
 ## Claim The Task
 
 ```bash
 bd update $ARGUMENTS --status in_progress
 ```
 
-## Create Branch
+## Workspace Setup
+
+### Option A: Feature Branch (default)
 
 If not already on a feature branch:
 
@@ -59,6 +83,75 @@ If not already on a feature branch:
 git checkout -b $ARGUMENTS
 ```
 
+### Option B: Git Worktree (if --worktree flag)
+
+For isolated work that won't conflict with main workspace:
+
+```typescript
+skill({ name: "using-git-worktrees" });
+```
+
+**When to use worktrees:**
+
+- Epic-level work spanning multiple sessions
+- Parallel work on different features
+- Need to keep main workspace clean
+- Long-running features with frequent context switches
+
+**Worktree setup:**
+
+```bash
+# Verify .gitignore has worktree directory
+grep -q "^\.worktrees/$" .gitignore || echo ".worktrees/" >> .gitignore
+
+# Create worktree
+git worktree add .worktrees/$ARGUMENTS -b $ARGUMENTS
+
+# Navigate to worktree
+cd .worktrees/$ARGUMENTS
+
+# Install dependencies (auto-detect project type)
+[ -f package.json ] && npm install
+[ -f Cargo.toml ] && cargo build
+[ -f requirements.txt ] && pip install -r requirements.txt
+[ -f go.mod ] && go mod download
+```
+
+**Beads in worktrees:** The `.beads/` database is shared with main repo automatically. No special configuration needed unless using `BEADS_DIR` for external storage.
+
+## Parallel Research (if --research flag or epic-level work)
+
+For complex tasks, gather context before diving in:
+
+```typescript
+// Fire subagents in parallel - don't wait for results
+Task({
+  subagent_type: "explore",
+  prompt: `Research codebase patterns for $ARGUMENTS:
+    - Find similar implementations
+    - Identify affected files
+    - Note testing patterns used
+    Return: File list, patterns found, testing approach`,
+  description: "Explore codebase for task",
+});
+
+Task({
+  subagent_type: "scout",
+  prompt: `Research external docs for $ARGUMENTS:
+    - API documentation for libraries involved
+    - Best practices for the approach
+    - Common pitfalls to avoid
+    Return: Key findings, code examples, warnings`,
+  description: "Scout external resources",
+});
+```
+
+**Subagent delegation rules:**
+
+- Subagents are **read-only** - they don't modify beads state
+- Results return to you (build agent) for integration
+- Use for research, not for implementation
+
 ## Existing Artifacts
 
 !`ls .beads/artifacts/$ARGUMENTS/ 2>/dev/null || echo "No artifacts yet"`
@@ -68,10 +161,30 @@ Look for:
 - `spec.md` - Requirements and constraints
 - `research.md` - Previous research
 - `plan.md` - Implementation plan
+- `handoffs/` - Previous session handoffs
+
+## Check Previous Sessions
+
+```typescript
+search_session({ query: "$ARGUMENTS" });
+list_sessions({ limit: 3 });
+```
+
+Load context from previous work on this bead.
 
 ## Determine Next Step
 
-Based on what exists:
+Based on task type and what exists:
+
+### For Epics (parent tasks)
+
+| State              | Next Command                      |
+| ------------------ | --------------------------------- |
+| No subtasks        | `/plan $ARGUMENTS --create-beads` |
+| Has ready subtasks | `/start <first-subtask-id>`       |
+| All subtasks done  | `/finish $ARGUMENTS`              |
+
+### For Tasks/Subtasks (leaf work)
 
 | Artifacts Found       | Next Command            |
 | --------------------- | ----------------------- |
@@ -86,15 +199,23 @@ Based on what exists:
 Started: $ARGUMENTS
 ━━━━━━━━━━━━━━━━━━━
 
+Type: [epic/task/subtask]
 Branch: $ARGUMENTS
+Workspace: [main | worktree: .worktrees/$ARGUMENTS]
 Status: in_progress
 
+Hierarchy:
+├── Parent: [parent-id or "none"]
+└── Children: [count or "none"]
+
 Artifacts:
 • spec.md: [exists/missing]
 • research.md: [exists/missing]
 • plan.md: [exists/missing]
 
-Next: [recommended command based on artifacts]
+Research: [launched/skipped]
+
+Next: [recommended command based on state]
 ```
 
 ## Quick Start

package/dist/template/.opencode/memory/project/beads-workflow.md

@@ -1,6 +1,6 @@
 ---
 purpose: Complete beads workflow mapping for OpenCodeKit commands
-updated: 2025-01-07
+updated: 2025-01-08
 ---
 
 # Beads Workflow Best Practices
@@ -17,6 +17,199 @@ Based on Steve Yegge's best practices and official beads documentation.
 | "Land the plane" = PUSH  | `bd sync` means git push         | Always verify push succeeded         |
 | Keep DB small            | Performance degrades >500 issues | `bd cleanup --days 7` weekly         |
 
+## Hierarchy Model: Epic → Task → Subtask
+
+### Hierarchy Levels
+
+```
+Epic (feature-level)
+├── Task 1 (domain or phase)
+│   ├── Subtask 1.1 (atomic work unit)
+│   └── Subtask 1.2
+├── Task 2 (blocked by Task 1)
+│   └── Subtask 2.1
+└── Task 3 (blocked by Task 2)
+```
+
+| Level   | Scope        | Duration   | Agent Work                            |
+| ------- | ------------ | ---------- | ------------------------------------- |
+| Epic    | Full feature | Days-weeks | Coordinate, delegate, not implement   |
+| Task    | Domain/phase | Hours-day  | May implement or delegate to subtasks |
+| Subtask | Atomic unit  | 30min-2hrs | Implement directly                    |
+
+### Size Estimation
+
+| Size | Tool Calls | Hierarchy Level    | Session Scope     |
+| ---- | ---------- | ------------------ | ----------------- |
+| S    | ~10        | Subtask            | Quick fix         |
+| M    | ~30        | Task               | Single session    |
+| L    | ~100       | Task with subtasks | Single session    |
+| XL   | 100+       | Epic required      | Multiple sessions |
+
+### Creating Hierarchy
+
+```bash
+# Create epic
+bd create "User Authentication" -t epic -p 2
+# Returns: bd-epic
+
+# Create tasks with dependencies
+bd create "Setup database schema" -t task -p 2
+bd dep add bd-xxx1 bd-epic
+
+bd create "Implement API endpoints" -t task -p 2
+bd dep add bd-xxx2 bd-epic
+bd dep add bd-xxx2 bd-xxx1 --type blocks  # Sequential
+
+# Create subtasks for complex tasks
+bd create "POST /api/users endpoint" -t subtask -p 2
+bd dep add bd-xxx2.1 bd-xxx2
+
+bd create "GET /api/users/:id endpoint" -t subtask -p 2
+bd dep add bd-xxx2.2 bd-xxx2
+bd dep add bd-xxx2.2 bd-xxx2.1 --type blocks  # Sequential subtasks
+
+# Verify hierarchy
+bd dep tree bd-epic
+```
+
+## Git Worktree Integration
+
+### When to Use Worktrees
+
+| Scenario                     | Use Worktree | Why                        |
+| ---------------------------- | ------------ | -------------------------- |
+| Epic-level work              | ✅ Yes       | Multi-session isolation    |
+| Parallel feature development | ✅ Yes       | No context switching       |
+| Long-running experiments     | ✅ Yes       | Keep main workspace clean  |
+| Single task (S/M)            | ❌ No        | Branch is sufficient       |
+| Hotfix/quick-build           | ❌ No        | Overkill for small changes |
+
+### Worktree Setup
+
+```bash
+# Verify .gitignore
+grep -q "^\.worktrees/$" .gitignore || echo ".worktrees/" >> .gitignore
+
+# Create worktree for feature
+git worktree add .worktrees/bd-xxx -b feature/auth
+
+# Navigate and setup
+cd .worktrees/bd-xxx
+npm install  # or project-specific setup
+
+# Verify clean baseline
+npm test
+```
+
+### Beads + Worktree Architecture
+
+```
+main-repo/
+├── .beads/              ← Shared database (all worktrees use this)
+├── .worktrees/
+│   ├── feature-a/       ← Worktree 1
+│   │   └── (working copy)
+│   └── feature-b/       ← Worktree 2
+│       └── (working copy)
+└── src/                 ← Main working copy
+```
+
+**Key insight:** `.beads/` is shared. All worktrees access the same database.
+
+### Worktree Daemon Behavior
+
+| Mode        | Configuration                          | Use When                 |
+| ----------- | -------------------------------------- | ------------------------ |
+| Default     | Daemon auto-disabled in worktrees      | Most cases               |
+| Sync branch | `bd config set sync-branch beads-sync` | Full daemon in worktrees |
+| External DB | `export BEADS_DIR=~/project/.beads`    | Complete separation      |
+| Sandbox     | `bd --sandbox` or `BEADS_NO_DAEMON=1`  | Claude Code, containers  |
+
+### Worktree Cleanup
+
+```bash
+# When feature complete
+cd /main-repo
+git worktree remove .worktrees/feature-a
+
+# Or force if dirty
+git worktree remove --force .worktrees/feature-a
+
+# Clean orphaned worktrees
+git worktree prune
+```
+
+## Subagent Delegation Patterns
+
+### Agent Hierarchy
+
+```
+Leader Agents (touch beads, sync, coordinate)
+├── build   - Primary implementation agent
+└── rush    - Fast-track implementation agent
+
+Subagents (read-only, stateless workers)
+├── explore - Codebase search, patterns
+├── scout   - External docs, best practices
+├── planner - Architecture, decomposition
+├── review  - Code review, debugging
+└── vision  - UI/UX, visual analysis
+```
+
+### Delegation Rules
+
+| Agent     | Can Do                     | Cannot Do              |
+| --------- | -------------------------- | ---------------------- |
+| `build`   | All beads ops, `bd sync`   | -                      |
+| `rush`    | All beads ops, `bd sync`   | -                      |
+| `explore` | Read, grep, glob, ast-grep | Edit, write, `bd sync` |
+| `scout`   | Fetch, search, Context7    | Edit, write, `bd sync` |
+| `planner` | Read, create artifacts     | Edit files, `bd sync`  |
+| `review`  | Read, analyze, suggest     | Edit files, `bd sync`  |
+| `vision`  | Analyze images, mockups    | All beads operations   |
+
+### Parallel Research Pattern
+
+Fire subagents in parallel, continue working immediately:
+
+```typescript
+// Launch both - don't wait
+Task({
+  subagent_type: "explore",
+  prompt: `Find codebase patterns for [task]:
+    - Similar implementations
+    - Test patterns
+    - Affected files
+    Return: File paths, patterns, test approach`,
+  description: "Explore codebase",
+});
+
+Task({
+  subagent_type: "scout",
+  prompt: `Research best practices for [task]:
+    - Official documentation
+    - Common patterns
+    - Pitfalls to avoid
+    Return: Examples, warnings, recommendations`,
+  description: "Scout external docs",
+});
+
+// Continue working immediately
+// Collect results when needed
+```
+
+### When to Delegate
+
+| Situation                | Delegate To | Why                        |
+| ------------------------ | ----------- | -------------------------- |
+| Need codebase patterns   | `@explore`  | Fast grep/glob/ast-grep    |
+| Need library docs        | `@scout`    | Context7, GitHub patterns  |
+| Complex planning         | `@planner`  | Structured decomposition   |
+| Code review before merge | `@review`   | Fresh eyes, evidence-based |
+| UI/mockup analysis       | `@vision`   | Visual expertise           |
+| Stuck on implementation  | `@explore`  | Fresh search perspective   |
+
 ## Maintenance Schedule
 
 | Task         | Frequency      | Command               | Why                                    |
@@ -101,23 +294,28 @@ model: gemini-2.5-pro # Override default model
 
 ### Lifecycle Commands (Touch Beads)
 
-| Command           | Agent   | Beads Operations                                       | When to Use                 |
-| ----------------- | ------- | ------------------------------------------------------ | --------------------------- |
-| `/triage`         | build   | `bd doctor`, `bd list`, `bd ready`, `bd cleanup`       | Start of day, find work     |
-| `/triage --quick` | build   | `bd ready`, `bd list --status=in_progress`             | Fast check, what's next     |
-| `/start <id>`     | build   | `bd update --status in_progress`, `bd hooks install`   | Claim a task                |
-| `/create`         | build   | `bd create`, `bd sync`                                 | Create new tracked task     |
-| `/new-feature`    | planner | `bd create` (epic + subtasks), `bd dep add`, `bd sync` | Complex feature with phases |
-| `/issue <num>`    | build   | `bd create`, `bd sync`, `gh issue comment`             | Import GitHub issue         |
-| `/plan <id>`      | planner | `bd create` (subtasks), `bd dep add`, `bd sync`        | Break down task             |
-| `/implement <id>` | build   | `bd update --status in_progress`, `bd sync`            | Do the work                 |
-| `/commit [id]`    | build   | `bd sync` (if bead-id provided)                        | Commit with traceability    |
-| `/finish <id>`    | build   | `bd close`, `bd sync`                                  | Complete task (asks first)  |
-| `/handoff <id>`   | build   | `bd sync`                                              | Pause work, save context    |
-| `/resume <id>`    | build   | `bd update --status in_progress`                       | Continue previous work      |
-| `/pr <id>`        | build   | `bd-msg`, `bd sync`                                    | Create pull request         |
-| `/fix`            | build   | `bd sync` (after user confirms commit)                 | Fix bugs with tracking      |
-| `/status`         | explore | `bd status`, `bd list`, `bd-inbox`, `bd-release`       | Dashboard view              |
+| Command                      | Agent   | Beads Operations                                       | When to Use                 |
+| ---------------------------- | ------- | ------------------------------------------------------ | --------------------------- |
+| `/triage`                    | build   | `bd doctor`, `bd list`, `bd ready`, `bd cleanup`       | Start of day, find work     |
+| `/triage --quick`            | build   | `bd ready`, `bd list --status=in_progress`             | Fast check, what's next     |
+| `/start <id>`                | build   | `bd update --status in_progress`, `bd hooks install`   | Claim a task                |
+| `/start <id> --worktree`     | build   | + Create git worktree                                  | Isolated feature work       |
+| `/start <id> --research`     | build   | + Parallel subagent research                           | Complex task preparation    |
+| `/create`                    | build   | `bd create`, `bd sync`                                 | Create new tracked task     |
+| `/new-feature`               | planner | `bd create` (epic + subtasks), `bd dep add`, `bd sync` | Complex feature with phases |
+| `/new-feature --worktree`    | planner | + Create git worktree for epic                         | Isolated feature branch     |
+| `/issue <num>`               | build   | `bd create`, `bd sync`, `gh issue comment`             | Import GitHub issue         |
+| `/plan <id>`                 | planner | `bd create` (subtasks), `bd dep add`, `bd sync`        | Break down task             |
+| `/plan <id> --create-beads`  | planner | Create child beads after planning                      | Auto-hierarchy creation     |
+| `/implement <id>`            | build   | `bd update --status in_progress`, `bd sync`            | Do the work                 |
+| `/implement <id> --parallel` | build   | + Aggressive subagent research                         | Complex implementation      |
+| `/commit [id]`               | build   | `bd sync` (if bead-id provided)                        | Commit with traceability    |
+| `/finish <id>`               | build   | `bd close`, `bd sync`                                  | Complete task (asks first)  |
+| `/handoff <id>`              | build   | `bd sync`                                              | Pause work, save context    |
+| `/resume <id>`               | build   | `bd update --status in_progress`                       | Continue previous work      |
+| `/pr <id>`                   | build   | `bd-msg`, `bd sync`                                    | Create pull request         |
+| `/fix`                       | build   | `bd sync` (after user confirms commit)                 | Fix bugs with tracking      |
+| `/status`                    | explore | `bd status`, `bd list`, `bd-inbox`, `bd-release`       | Dashboard view              |
 
 ### Research Commands (Read-Only Beads)
 
@@ -152,27 +350,34 @@ model: gemini-2.5-pro # Override default model
 /pr bd-xxx               # Create PR (asks first)
 ```
 
-### Pattern 2: Complex Feature (L/XL size)
+### Pattern 2: Complex Feature with Worktree (L/XL size)
 
 ```
-/triage                  # Full triage with health check
-/new-feature "Feature"   # Creates epic + spec + plan + subtasks
-/start bd-xxx.1          # Start first subtask
-/implement bd-xxx.1      # Implement
-/finish bd-xxx.1         # Complete subtask
-/start bd-xxx.2          # Next subtask (now unblocked)
+/triage                        # Full triage with health check
+/new-feature "Feature" --worktree  # Creates epic + subtasks + worktree
+cd .worktrees/bd-epic          # Enter worktree
+/start bd-xxx.1                # Start first task
+/implement bd-xxx.1            # Implement
+/finish bd-xxx.1               # Complete task
+/start bd-xxx.2                # Next task (now unblocked)
+/implement bd-xxx.2            # Continue...
+/finish bd-xxx.2               # Complete
 ...
-/finish bd-xxx           # Close epic when all subtasks done
+/finish bd-epic                # Close epic when all tasks done
+git worktree remove .worktrees/bd-epic  # Cleanup worktree
 ```
 
-### Pattern 3: Research-First
+### Pattern 3: Research-First with Subagent Delegation
 
 ```
-/create "Complex task"   # Create bead with spec
-/research bd-xxx         # Gather information (scout agent)
-/plan bd-xxx             # Design approach (planner agent)
-/implement bd-xxx        # Now implement with full context
-/finish bd-xxx           # Complete
+/create "Complex task"         # Create bead with spec
+/start bd-xxx --research       # Claim + parallel subagent research
+/plan bd-xxx --create-beads    # Design with auto-hierarchy
+/implement bd-xxx.1            # Implement first subtask
+/finish bd-xxx.1               # Complete subtask
+/implement bd-xxx.2 --parallel # Next subtask with research
+/finish bd-xxx.2               # Complete subtask
+/finish bd-xxx                 # Close parent task
 ```
 
 ### Pattern 4: Bug Fix
@@ -201,6 +406,26 @@ model: gemini-2.5-pro # Override default model
 /quick-build "fix typo"  # Single file, <30 min, commits directly
 ```
 
+### Pattern 7: Epic with Parallel Workstreams
+
+```
+/new-feature "Big Feature" --worktree
+# Creates: bd-epic with bd-xxx1, bd-xxx2, bd-xxx3
+
+# Agent 1 (main worktree)
+/start bd-xxx1 --worktree
+/implement bd-xxx1
+/finish bd-xxx1
+
+# Agent 2 (separate worktree - if independent)
+/start bd-xxx2 --worktree
+/implement bd-xxx2
+/finish bd-xxx2
+
+# Merge when all complete
+/finish bd-epic
+```
+
 ## Agent Boundaries
 
 ### Leader Agents (Touch Beads)
@@ -232,7 +457,7 @@ bd - reserve({ paths: ["src/auth.ts"], ttl: 600 });
 bd - release({ paths: ["src/auth.ts"] });
 
 // Check active locks
-bd - release(); // No args = list locks
+bd - release({ _: true }); // No paths = list locks
 ```
 
 ## Commit Message Format
@@ -253,18 +478,22 @@ Closes: bd-a1b2c3
 2. [ ] `bd sync` run (pushes to git)
 3. [ ] If incomplete: `/handoff <id>` created
 4. [ ] If complete: `/finish <id>` run
-5. [ ] No stale file locks
+5. [ ] No stale file locks (`bd-release({ _: true })`)
+6. [ ] Worktrees cleaned up (if used)
 
 ## Troubleshooting
 
-| Problem                | Solution                                |
-| ---------------------- | --------------------------------------- |
-| "bd command not found" | `npm install -g beads-village`          |
-| Orphaned issues        | `bd doctor --fix`                       |
-| DB too large           | `bd cleanup --days 3`                   |
-| Sync conflicts         | `bd sync --force` (careful!)            |
-| Stale handoff          | Check if rebase needed before `/resume` |
-| Task not in `bd ready` | Check blockers: `bd show <id>`          |
+| Problem                      | Solution                                            |
+| ---------------------------- | --------------------------------------------------- |
+| "bd command not found"       | `npm install -g beads-village`                      |
+| Orphaned issues              | `bd doctor --fix`                                   |
+| DB too large                 | `bd cleanup --days 3`                               |
+| Sync conflicts               | `bd sync --force` (careful!)                        |
+| Stale handoff                | Check if rebase needed before `/resume`             |
+| Task not in `bd ready`       | Check blockers: `bd show <id>`                      |
+| "Branch already checked out" | `rm -rf .git/beads-worktrees && git worktree prune` |
+| Daemon issues in worktree    | `bd config set sync-branch beads-sync`              |
+| Sandbox environment          | `bd --sandbox` or `BEADS_NO_DAEMON=1`               |
 
 ## Anti-Patterns
 
@@ -276,3 +505,6 @@ Closes: bd-a1b2c3
 | Subagents running `bd sync`            | Coordination issues   | Only leader agents sync          |
 | Force through complex with quick-build | Technical debt        | Proper `/create` workflow        |
 | Ignore `bd doctor` warnings            | Corruption risk       | Fix issues promptly              |
+| Skip worktree for XL features          | Merge conflicts       | Use `--worktree` flag            |
+| Implement epic directly                | Too large             | Work on subtasks instead         |
+| Wait for subagent results              | Blocks progress       | Fire parallel, continue working  |