opencodekit 0.15.20 → 0.16.0

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

@@ -0,0 +1,613 @@
+---
+description: Start working on a bead - claim it and prepare context
+argument-hint: "<bead-id> [--worktree] [--research] [--parallel]"
+agent: build
+---
+
+# Start: $ARGUMENTS
+
+You're claiming a task and preparing to work on it. This is the entry point before implementation.
+
+> **CCPM Philosophy:** One issue ≠ one task. One issue = multiple parallel work streams.
+> Agents are "context firewalls" - they do heavy work and return concise summaries.
+
+## 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 |
+| `--parallel` | auto     | Analyze and spawn parallel work streams        |
+
+## Load Skills
+
+```typescript
+skill({ name: "beads" });
+skill({ name: "beads-bridge" }); // For cross-session todo coordination
+skill({ name: "prd" }); // PRD creation workflow
+skill({ name: "prd-task" }); // PRD to executable tasks conversion
+```
+
+## Ensure Git Hooks Installed
+
+First-time setup per repo (prevents stale JSONL issues):
+
+```bash
+bd hooks install 2>/dev/null || echo "Hooks already installed"
+```
+
+## Current State
+
+### Git Status
+
+!`git status --porcelain`
+!`git branch --show-current`
+
+### Active Tasks
+
+!`bd list --status=in_progress`
+
+If you have uncommitted changes, ask the user:
+
+1. Stash them (`git stash`)
+2. Commit them first
+3. Continue anyway (risky)
+
+If you already have tasks in_progress, warn the user before claiming another.
+
+## Task Details
+
+!`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
+```
+
+## Sync Beads State to OpenCode Todos
+
+Make beads tasks visible to subagents via todoread:
+
+```typescript
+// Push beads state to OpenCode todos
+beads_sync({ operation: "push" });
+```
+
+This enables subagents to see task context via `todoread()` without beads access.
+
+## Workspace Setup
+
+### Create Feature Branch
+
+Extract task info and parent branch for a readable branch name:
+
+```bash
+# Get current branch (parent branch)
+PARENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+# Get task title and type from bead
+BEAD_INFO=$(bd show $ARGUMENTS --json 2>/dev/null)
+BEAD_TITLE=$(echo "$BEAD_INFO" | jq -r '.title // ""' | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | cut -c1-40)
+BEAD_TYPE=$(echo "$BEAD_INFO" | jq -r '.type // "task"')
+
+# Map bead type to branch prefix
+case "$BEAD_TYPE" in
+  "bug") PREFIX="fix" ;;
+  "feature"|"epic") PREFIX="feat" ;;
+  "refactor") PREFIX="refactor" ;;
+  "chore") PREFIX="chore" ;;
+  *) PREFIX="feat" ;;
+esac
+
+# Create branch: <parent>/<type>/<bead-id>-<description>
+BRANCH_NAME="${PARENT_BRANCH}/${PREFIX}/$ARGUMENTS-${BEAD_TITLE}"
+git checkout -b "$BRANCH_NAME" 2>/dev/null || echo "Branch already exists or already on it"
+```
+
+**Branch naming convention:**
+| Parent Branch | Bead Type | Example |
+|---------------|-----------|---------|
+| main | bug | `main/fix/bd-a1b2-login-error` |
+| develop | feature | `develop/feat/bd-c3d4-user-auth` |
+| release-v2 | chore | `release-v2/chore/bd-e5f6-update-deps` |
+
+### 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
+# Get current branch (parent branch)
+PARENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+# Get task title for readable worktree name
+BEAD_INFO=$(bd show $ARGUMENTS --json 2>/dev/null)
+BEAD_TITLE=$(echo "$BEAD_INFO" | jq -r '.title // ""' | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | cut -c1-40)
+BEAD_TYPE=$(echo "$BEAD_INFO" | jq -r '.type // "task"')
+
+# Map bead type to branch prefix
+case "$BEAD_TYPE" in
+  "bug") PREFIX="fix" ;;
+  "feature"|"epic") PREFIX="feat" ;;
+  "refactor") PREFIX="refactor" ;;
+  *) PREFIX="feat" ;;
+esac
+
+# Create branch: <parent>/<type>/<bead-id>-<description>
+BRANCH_NAME="${PARENT_BRANCH}/${PREFIX}/$ARGUMENTS-${BEAD_TITLE}"
+
+# Verify .gitignore has worktree directory
+grep -q "^\.worktrees/$" .gitignore || echo ".worktrees/" >> .gitignore
+
+# Create worktree with readable branch name
+git worktree add ".worktrees/$ARGUMENTS" -b "$BRANCH_NAME"
+
+# 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
+// Run subagents in parallel - multiple Task calls in one message
+Task({
+  subagent_type: "explore",
+  description: "Explore codebase patterns",
+  prompt: `Research codebase patterns for $ARGUMENTS:
+    - Find similar implementations
+    - Identify affected files
+    - Note testing patterns used
+    Return: File list, patterns found, testing approach`,
+});
+
+Task({
+  subagent_type: "scout",
+  description: "Research external docs",
+  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`,
+});
+
+// Both run in parallel, results available immediately
+```
+
+**Subagent delegation rules:**
+
+- Subagents are **read-only** - they don't modify beads state
+- Results returned immediately when all complete
+- Use for research, not for implementation
+
+## Existing Artifacts
+
+!`ls .beads/artifacts/$ARGUMENTS/ 2>/dev/null || echo "No artifacts yet"`
+
+Look for:
+
+- `spec.md` - Requirements and constraints
+- `prd.md` - PRD created via `prd` skill (defines WHAT to build)
+- `prd.json` - Executable tasks from `prd-task` skill
+- `progress.txt` - PRD execution progress (append-only)
+- `research.md` - Previous research
+- `plan.md` - Implementation plan
+- `handoffs/` - Previous session handoffs
+
+### PRD Workflow (if prd.md exists but no prd.json)
+
+If `prd.md` exists but `prd.json` doesn't, convert PRD to tasks:
+
+```typescript
+// The prd-task skill converts PRD markdown to executable JSON
+// Read prd.md → Extract ## Tasks section → Write prd.json
+skill({ name: "prd-task" });
+
+// Then parse the PRD
+// This creates:
+// - .beads/artifacts/$ARGUMENTS/prd.json (task list)
+// - .beads/artifacts/$ARGUMENTS/progress.txt (progress log)
+```
+
+### PRD Workflow (if neither exists)
+
+If no PRD exists and task is complex (epic/feature), consider creating one:
+
+```typescript
+// The prd skill guides PRD creation with:
+// - Clarifying questions (5-7 max)
+// - Problem/solution framing
+// - Machine-convertible Tasks section
+skill({ name: "prd" });
+
+// Creates: .beads/artifacts/$ARGUMENTS/prd.md
+```
+
+## Check Previous Sessions
+
+```typescript
+search_session({ query: "$ARGUMENTS" });
+list_sessions({ limit: 3 });
+```
+
+Load context from previous work on this bead.
+
+## Load Related Memory (Semantic Search)
+
+Search for relevant past work and learnings before starting:
+
+```typescript
+// Find similar past work (semantic similarity)
+memory_search({ query: "[task title/description from bead]", limit: 3 });
+
+// Find related observations (gotchas, patterns, learnings)
+memory_search({ query: "[task keywords] gotchas patterns", limit: 3 });
+```
+
+**Review findings before diving in.** Past observations may contain:
+
+- Gotchas to avoid
+- Patterns that worked well
+- Decisions already made
+
+If memory search fails (Ollama not running), continue without it.
+
+## Parallel Stream Analysis (if --parallel flag or epic/task type)
+
+> **CCPM Insight:** A single task isn't one unit of work. It's multiple parallel work streams.
+> Streams are determined by analyzing the ACTUAL task requirements, not hardcoded categories.
+
+### Step 1: Analyze Work Streams
+
+Use swarm planning to analyze the specific task:
+
+```typescript
+// Get task details from bead
+const beadInfo = bd show $ARGUMENTS --json;
+const taskTitle = beadInfo.title;
+const taskDescription = beadInfo.description;
+
+// Read spec/plan if exists for file context
+const specContent = read(".beads/artifacts/$ARGUMENTS/spec.md");
+const planContent = read(".beads/artifacts/$ARGUMENTS/plan.md");
+
+// Analyze THIS SPECIFIC task for parallel execution
+const analysis = swarm_plan({
+  operation: "analyze",
+  task: taskTitle,                    // User's actual task
+  context: taskDescription,           // User's requirements
+  files: "[files from spec/plan]",    // Actual affected files
+});
+```
+
+The analysis returns **task-specific** streams:
+
+```typescript
+// Example analysis result (varies per task):
+{
+  classification: "search",           // Can parallelize
+  recommended_agents: 3,
+  streams: [
+    { id: "stream-1", scope: "src/auth/*", purpose: "Authentication logic" },
+    { id: "stream-2", scope: "src/api/auth/*", purpose: "Auth endpoints" },
+    { id: "stream-3", scope: "tests/auth/*", purpose: "Auth test coverage" },
+  ]
+}
+```
+
+### Step 2: Create Dynamic Delegation Packets
+
+**For EACH stream from analysis** (not hardcoded):
+
+```typescript
+// Iterate over streams from analysis - these are DYNAMIC based on task
+for (const stream of analysis.streams) {
+  swarm_delegate({
+    bead_id: "$ARGUMENTS",
+    title: stream.purpose, // From analysis, not hardcoded
+    expected_outcome: `Complete ${stream.purpose} for task requirements`,
+    required_tools: "read, grep, lsp, edit, bash",
+    must_do: "LSP before edits, verify changes, run relevant tests",
+    must_not_do: "no new deps without approval, stay within assigned scope",
+    acceptance_checks: "[derived from spec.md acceptance criteria]",
+    context: `Files: ${stream.scope}, Purpose: ${stream.purpose}`,
+    write: true,
+  });
+}
+```
+
+### Step 3: Spawn Workers for Each Stream
+
+```typescript
+// Launch workers based on ACTUAL analysis results
+for (const stream of analysis.streams) {
+  // Initialize monitoring for this stream
+  swarm_monitor({
+    operation: "progress_update",
+    team_name: "$ARGUMENTS-swarm",
+    worker_id: stream.id,
+    phase: "starting",
+    progress: 0,
+    status: "working",
+    file: stream.scope,
+  });
+
+  // Spawn worker with task-specific instructions
+  Task({
+    subagent_type: "general",
+    description: `${stream.id}: ${stream.purpose}`,
+    prompt: `Execute work stream for $ARGUMENTS.
+      
+      **Your Assignment:**
+      - Scope: ${stream.scope}
+      - Purpose: ${stream.purpose}
+      
+      **Load Context:**
+      - Delegation: .beads/artifacts/$ARGUMENTS/delegation.md
+      - Spec: .beads/artifacts/$ARGUMENTS/spec.md (if exists)
+      
+      **Work:** 
+      Complete all work within your assigned scope that fulfills the task requirements.
+      
+      **Return CONCISE summary only:**
+      - Files modified: [list]
+      - Changes made: [brief description]
+      - Verification: [pass/fail + what was checked]
+      
+      DO NOT return verbose output or file contents.`,
+  });
+}
+
+// All workers execute in parallel, results return when complete
+```
+
+### Step 4: Monitor Progress
+
+```typescript
+// Render progress visualization
+swarm_monitor({
+  operation: "render_block",
+  team_name: "$ARGUMENTS-swarm",
+});
+```
+
+**Output shows ACTUAL streams (dynamic):**
+
+```
+┌─ $ARGUMENTS-swarm ──────────────────────────┐
+│ stream-1 [████████░░] 80%  src/auth/*      │
+│ stream-2 [██████░░░░] 60%  src/api/auth/*  │
+│ stream-3 [████░░░░░░] 40%  tests/auth/*    │
+└─────────────────────────────────────────────┘
+```
+
+### Anti-Serial-Collapse Check
+
+Before proceeding, verify parallelization makes sense:
+
+```typescript
+swarm_plan({
+  operation: "check",
+  task: taskTitle,
+  files: analysis.streams.length,
+  recommended_agents: analysis.recommended_agents,
+});
+```
+
+**Warning signs:**
+
+- Only 1 stream identified for multi-file task
+- All streams depend on each other (should be sequential)
+- Same files appear in multiple streams (conflict risk)
+
+### When NOT to Parallelize
+
+Skip parallel analysis if:
+
+- Task is a `subtask` (leaf-level, already atomic)
+- Only 1-2 files affected
+- Sequential dependency chain (each step needs previous)
+- User explicitly passed `--no-parallel`
+
+## PRD Tasks (If Present)
+
+If `.beads/artifacts/$ARGUMENTS/prd.json` exists, execution is PRD-driven:
+
+```typescript
+// Load the prd-task skill for execution guidance
+skill({ name: "prd-task" });
+
+// Read task list
+const prdJson = read(".beads/artifacts/$ARGUMENTS/prd.json");
+const tasks = JSON.parse(prdJson).tasks;
+
+// Find next incomplete task
+const nextTask = tasks.find((t) => !t.passes);
+
+if (nextTask) {
+  console.log(`Next PRD task: ${nextTask.id}`);
+  console.log(`Description: ${nextTask.description}`);
+  console.log(`Verification steps:`);
+  nextTask.steps.forEach((s) => console.log(`  - ${s}`));
+}
+```
+
+**PRD execution flow:**
+
+1. Read `prd.json` for task list
+2. Find next task where `passes: false`
+3. Implement to satisfy verification steps
+4. Mark `passes: true` when verification passes
+5. Append progress to `progress.txt`
+6. Repeat until all tasks pass
+
+Proceed directly to implementation using the PRD tasks as the guide.
+
+## Determine Next Step
+
+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  | `/ship $ARGUMENTS`                |
+
+### For Tasks/Subtasks (leaf work)
+
+| Artifacts Found       | Next Step                                 |
+| --------------------- | ----------------------------------------- |
+| Nothing               | `/research $ARGUMENTS` or create PRD      |
+| Only spec.md          | `/plan $ARGUMENTS` or create PRD          |
+| prd.md (no prd.json)  | Run `prd-task` skill to convert to tasks  |
+| prd.json exists       | `/ship $ARGUMENTS` (PRD-driven execution) |
+| spec.md + research.md | `/plan $ARGUMENTS`                        |
+| plan.md exists        | `/ship $ARGUMENTS`                        |
+
+### PRD vs Plan Decision
+
+| Situation                            | Use PRD                 | Use Plan           |
+| ------------------------------------ | ----------------------- | ------------------ |
+| New feature with unclear scope       | ✅ Ask questions first  | ❌                 |
+| Bug fix or small change              | ❌                      | ✅ Quick plan      |
+| Multi-session epic                   | ✅ PRD for each subtask | ✅ High-level plan |
+| Refactoring with known scope         | ❌                      | ✅ Plan with tasks |
+| Feature needing stakeholder sign-off | ✅ PRD for review       | ❌                 |
+
+## Output
+
+```
+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]
+• prd.md: [exists/missing]
+• prd.json: [exists/missing] ([N] tasks, [M] complete)
+
+[If PRD exists:]
+┌─ PRD Progress ──────────────────────────┐
+│ Tasks: [completed]/[total]              │
+│ Next: [task-id] - [description]         │
+│ Verification:                           │
+│   • [step 1]                            │
+│   • [step 2]                            │
+└─────────────────────────────────────────┘
+
+┌─ Parallel Analysis ─────────────────────┐
+│ Classification: [search/chain/blocked]  │
+│ Streams: [N] identified from task       │
+│ Agents: [N] recommended                 │
+│                                         │
+│ Streams detected:                       │
+│ • [stream.purpose from analysis]        │
+│ • [stream.purpose from analysis]        │
+│ • ...                                   │
+└─────────────────────────────────────────┘
+
+[If parallel spawned:]
+┌─ $ARGUMENTS-swarm ──────────────────────┐
+│ [stream-id] [░░░░░░░░░░]  0%  [scope]  │
+│ [stream-id] [░░░░░░░░░░]  0%  [scope]  │
+│ ...                                     │
+└─────────────────────────────────────────┘
+
+Next: [recommended command based on state]
+```
+
+## Quick Start
+
+If `--quick` flag is passed and plan.md exists, skip directly to:
+
+```
+/implement $ARGUMENTS
+```
+
+---
+
+## Agent Return Format (CCPM Pattern)
+
+> **Key insight:** Agents are context firewalls. They do heavy work and return CONCISE summaries.
+
+When spawning subagents, always specify the return format:
+
+```typescript
+Task({
+  subagent_type: "explore",
+  prompt: `...
+  
+  Return ONLY:
+  - 3-5 key files (not all files examined)
+  - Pattern summary (not full code)
+  - Actionable insights (not observations)
+  
+  DO NOT return verbose output or file contents.`,
+});
+```
+
+**Good return:** "Found auth pattern in 3 files: src/auth/\*.ts uses JWT with 24h expiry"
+
+**Bad return:** [dumps entire file contents]
+
+---
+
+## Related Commands
+
+| Need                 | Command                          |
+| -------------------- | -------------------------------- |
+| Skip to implement    | `/ship $ARGUMENTS`               |
+| Create PRD first     | `/create $ARGUMENTS --prd`       |
+| Research first       | `/research $ARGUMENTS`           |
+| Plan implementation  | `/plan $ARGUMENTS`               |
+| Convert PRD to tasks | Use `prd-task` skill             |
+| Check PRD progress   | Read `prd.json` + `progress.txt` |

package/dist/template/.opencode/{commands → command}/ui-review.md

@@ -300,10 +300,8 @@ bd dep add <task-id> <bead-id>
 
 ## Related Commands
 
-| Need                | Command                |
-| ------------------- | ---------------------- |
-| Analyze mockup      | `/analyze-mockup`      |
-| Fix UI issues       | `/fix-ui`              |
-| Accessibility audit | `/accessibility-check` |
-| Design from scratch | `/design`              |
-| Audit design system | `/design-audit`        |
+| Need                 | Command         |
+| -------------------- | --------------- |
+| Design from scratch  | `/design`       |
+| Start implementation | `/start <bead>` |
+| Ship implementation  | `/ship <bead>`  |