opencodekit 0.16.15 → 0.16.17

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

@@ -1,625 +1,95 @@
 ---
-description: Start working on a bead - claim it and prepare context
-argument-hint: "<bead-id> [--worktree] [--research] [--parallel]"
+description: Start working on a bead - claim it and prepare workspace
+argument-hint: "<bead-id> [--worktree]"
 agent: build
 ---
 
 # Start: $ARGUMENTS
 
-You're claiming a task and preparing to work on it. This is the entry point before implementation.
+Claim a task and prepare workspace. Bridge between specification (`/create`) and implementation (`/ship`).
 
-> **Lifecycle context:** Ideation → Design → Specification → Task Conversion → Planning → **Implementation** → Verification
+> **Workflow:** `/create` → **`/start <id>`** → `/ship <id>`
 >
-> **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        |
+> ⛔ Bead MUST have `prd.md` (created via `/create`).
 
 ## Load Skills
 
 ```typescript
-skill({ name: "development-lifecycle" }); // Phase guidance
 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
-skill({ name: "memory-system" });
-
-// Load conditionally based on flags
-if (flags.includes("--parallel")) {
-  skill({ name: "swarm-coordination" }); // Parallel work orchestration
-  skill({ name: "agent-teams" }); // Team patterns and coordination
-}
+skill({ name: "prd-task" }); // PRD → executable tasks
 ```
 
-## Ensure Git Hooks Installed
+## Parse Arguments
+
+| Argument     | Default  | Description                  |
+| ------------ | -------- | ---------------------------- |
+| `<bead-id>`  | required | The bead to start            |
+| `--worktree` | false    | Create isolated git worktree |
 
-First-time setup per repo (prevents stale JSONL issues):
+## Phase 1: Pre-flight
 
 ```bash
-br hooks install 2>/dev/null || echo "Hooks already installed"
+git status --porcelain
+git branch --show-current
+br list --status=in_progress
 ```
 
-## Current State
-
-### Git Status
-
-!`git status --porcelain`
-!`git branch --show-current`
-
-### Active Tasks
-
-!`br list --status=in_progress`
-
-If you have uncommitted changes, ask the user:
+- If uncommitted changes: ask user to stash, commit, or continue
+- If other tasks in progress: warn before claiming another
 
-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
-
-!`br 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:
+## Phase 2: Validate Specification
 
 ```bash
-br dep tree $ARGUMENTS 2>/dev/null || echo "No dependencies"
+br show $ARGUMENTS
+ls .beads/artifacts/$ARGUMENTS/
 ```
 
-## Claim The Task
+Verify `prd.md` exists and has real content (not just placeholders). If missing or incomplete, tell user to run `/create` first.
+
+## Phase 3: Claim and Branch
 
 ```bash
 br 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
-swarm({ operation: "sync", action: "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:
+Create a feature branch:
 
 ```bash
-# Get current branch (parent branch)
-PARENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
-
-# Get task title and type from bead
-BEAD_INFO=$(br 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"
+git checkout -b feat/$ARGUMENTS-<short-title>
 ```
 
-**Branch naming convention:**
-| Parent Branch | Bead Type | Example |
-|---------------|-----------|---------|
-| main | bug | `main/fix/br-a1b2-login-error` |
-| develop | feature | `develop/feat/br-c3d4-user-auth` |
-| release-v2 | chore | `release-v2/chore/br-e5f6-update-deps` |
-
-### Option B: Git Worktree (if --worktree flag)
-
-For isolated work that won't conflict with main workspace:
+If `--worktree`:
 
 ```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=$(br 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:
-
-- `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 = br show $ARGUMENTS --json;
-const taskTitle = beadInfo.title;
-const taskDescription = beadInfo.description;
-
-// Read prd/plan if exists for file context
-const prdContent = read(".beads/artifacts/$ARGUMENTS/prd.md");
-const planContent = read(".beads/artifacts/$ARGUMENTS/plan.md");
-
-// Analyze THIS SPECIFIC task for parallel execution
-const analysis = swarm({
-  operation: "plan",
-  action: "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({
-    operation: "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({
-    operation: "monitor",
-    action: "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
+## Phase 4: Convert PRD to Tasks
 
-```typescript
-// Render progress visualization
-swarm({
-  operation: "monitor",
-  action: "render_block",
-  team_name: "$ARGUMENTS-swarm",
-});
-```
+If `prd.json` doesn't exist yet, use `prd-task` skill to convert PRD markdown → executable JSON.
 
-**Output shows ACTUAL streams (dynamic):**
+If `prd.json` already exists, show progress (completed/total tasks).
 
-```
-┌─ $ARGUMENTS-swarm ──────────────────────────┐
-│ stream-1 [████████░░] 80%  src/auth/*      │
-│ stream-2 [██████░░░░] 60%  src/api/auth/*  │
-│ stream-3 [████░░░░░░] 40%  tests/auth/*    │
-└─────────────────────────────────────────────┘
-```
-
-### Anti-Serial-Collapse Check
+## Phase 5: Report and Route
 
-Before proceeding, verify parallelization makes sense:
-
-```typescript
-swarm({
-  operation: "plan",
-  action: "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" });
+Output:
 
-// Read task list
-const prdJson = read(".beads/artifacts/$ARGUMENTS/prd.json");
-const tasks = JSON.parse(prdJson).tasks;
+1. Bead type and status
+2. Branch name
+3. Workspace (main or worktree)
+4. Artifact status (prd.md validated, prd.json exists/created)
+5. Next step recommendation
 
-// 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              | Ask user for task description             |
-| Only prd.md          | `/plan $ARGUMENTS` or use `prd-task`      |
-| prd.md (no prd.json) | Run `prd-task` skill to convert to tasks  |
-| prd.json exists      | `/ship $ARGUMENTS` (PRD-driven execution) |
-| prd.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:
-• prd.md: [exists/missing]
-• research.md: [exists/missing]
-• plan.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]
-
----
+| State              | Next Command             |
+| ------------------ | ------------------------ |
+| Has prd.json       | `/ship $ARGUMENTS`       |
+| Epic with subtasks | `/start <first-subtask>` |
+| Complex task       | `/plan $ARGUMENTS`       |
 
 ## Related Commands
 
-| Need                 | Command                          |
-| -------------------- | -------------------------------- |
-| Skip to implement    | `/ship $ARGUMENTS`               |
-| Research first       | `/research $ARGUMENTS`           |
-| Plan implementation  | `/plan $ARGUMENTS`               |
-| Convert PRD to tasks | Use `prd-task` skill             |
-| Check PRD progress   | Read `prd.json` + `progress.txt` |
+| Need                | Command      |
+| ------------------- | ------------ |
+| Create spec first   | `/create`    |
+| Plan implementation | `/plan <id>` |
+| Implement and ship  | `/ship <id>` |