opencodekit 0.15.21 → 0.16.0

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

@@ -0,0 +1,156 @@
+---
+description: Ship a bead - implement, verify, review, close
+argument-hint: "<bead-id> [--parallel] [--swarm]"
+agent: build
+---
+
+# Ship: $ARGUMENTS
+
+This command combines implementation and finish gates. It implements, verifies, runs review, then closes.
+
+## Load Skills
+
+```typescript
+skill({ name: "beads" });
+skill({ name: "test-driven-development" });
+skill({ name: "verification-before-completion" });
+skill({ name: "finishing-a-development-branch" });
+skill({ name: "receiving-code-review" });
+skill({ name: "swarm-coordination" });
+skill({ name: "beads-bridge" });
+```
+
+## Skill Routing
+
+- Use **systematic-debugging** when a gate fails and root cause is unclear.
+- Use **receiving-code-review** to triage review feedback after the review agent runs.
+
+## Verify Task & Claim
+
+```bash
+bd show $ARGUMENTS
+bd update $ARGUMENTS --status in_progress
+```
+
+## Pre-Flight Verification
+
+Run `/verify $ARGUMENTS --quick` to check:
+
+- All spec requirements addressed
+- All gates passing
+- No obvious contradictions
+
+If verification fails, fix issues before proceeding.
+
+## Implement (Keep It Focused)
+
+- Read before edit
+- Delegate research if unclear (Task → explore/scout)
+- Keep scope ≤ 3 files or create subtasks
+
+If the task is large (3+ independent subtasks), use swarm mode.
+
+## Run Verification Gates
+
+Detect project type:
+
+```bash
+ls package.json Cargo.toml pyproject.toml go.mod Makefile 2>/dev/null
+```
+
+**Node/TypeScript:**
+
+```bash
+npm run build 2>/dev/null || true
+npm test
+npm run lint 2>/dev/null || true
+npm run typecheck 2>/dev/null || true
+```
+
+**Rust:**
+
+```bash
+cargo build
+cargo test
+cargo clippy -- -D warnings
+```
+
+**Python:**
+
+```bash
+pytest
+ruff check .
+mypy . 2>/dev/null || true
+```
+
+**Go:**
+
+```bash
+go build ./...
+go test ./...
+golangci-lint run
+```
+
+If ANY gate fails, stop and fix before proceeding.
+
+## Stage Changes For Review
+
+```bash
+git add -A
+git status
+git diff --cached --stat
+```
+
+## Spawn Review Agent (After Tests)
+
+```typescript
+Task({
+  subagent_type: "review",
+  description: "Review changes for $ARGUMENTS",
+  prompt: `Review the staged changes for bead $ARGUMENTS.
+
+Context:
+- Use git status and git diff --cached to see changes
+- Focus on correctness, edge cases, and risks
+- Report issues with file:line references
+
+Return:
+- Summary of findings
+- Critical/High/Medium issues (if any)
+`,
+});
+```
+
+If review finds issues, fix them, re-run verification gates, then re-run review.
+
+## Verify Success Criteria
+
+```bash
+cat .beads/artifacts/$ARGUMENTS/spec.md
+```
+
+Ensure all criteria are met before closing.
+
+## Close Bead (Ask First)
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Close",
+      question: "Ship complete. Close bead $ARGUMENTS?",
+      options: [
+        { label: "Yes, close it (Recommended)", description: "All gates passed" },
+        { label: "No, keep open", description: "Need more work" },
+      ],
+    },
+  ],
+});
+```
+
+If confirmed:
+
+```bash
+bd close $ARGUMENTS --reason "Shipped: verification + review passed"
+bd sync
+```

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> [--worktree] [--research]"
+argument-hint: "<bead-id> [--worktree] [--research] [--parallel]"
 agent: build
 ---
 
@@ -8,6 +8,9 @@ agent: build
 
 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                                    |
@@ -15,12 +18,15 @@ You're claiming a task and preparing to work on it. This is the entry point befo
 | `<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
@@ -218,13 +224,42 @@ Task({
 Look for:
 
 - `spec.md` - Requirements and constraints
-- `prd.md` - PRD (optional, recommended for features)
-- `prd.json` - PRD tasks (generated from prd.md)
+- `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
@@ -240,21 +275,10 @@ Search for relevant past work and learnings before starting:
 
 ```typescript
 // Find similar past work (semantic similarity)
-memory -
-  search({
-    query: "[task title/description from bead]",
-    mode: "semantic",
-    limit: 3,
-  });
+memory_search({ query: "[task title/description from bead]", limit: 3 });
 
 // Find related observations (gotchas, patterns, learnings)
-memory -
-  search({
-    query: "[task keywords]",
-    mode: "semantic",
-    type: "observation",
-    limit: 3,
-  });
+memory_search({ query: "[task keywords] gotchas patterns", limit: 3 });
 ```
 
 **Review findings before diving in.** Past observations may contain:
@@ -265,10 +289,196 @@ memory -
 
 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: next is `/complete-next-task $ARGUMENTS`.
-- If `.beads/artifacts/$ARGUMENTS/prd.md` exists but `prd.json` does not: generate tasks with `prd-task` (see `/create` for the full PRD workflow).
+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
 
@@ -280,17 +490,28 @@ Based on task type and what exists:
 | ------------------ | --------------------------------- |
 | No subtasks        | `/plan $ARGUMENTS --create-beads` |
 | Has ready subtasks | `/start <first-subtask-id>`       |
-| All subtasks done  | `/finish $ARGUMENTS`              |
+| All subtasks done  | `/ship $ARGUMENTS`                |
 
 ### For Tasks/Subtasks (leaf work)
 
-| Artifacts Found       | Next Command                     |
-| --------------------- | -------------------------------- |
-| Nothing               | `/research $ARGUMENTS`           |
-| Only spec.md          | `/plan $ARGUMENTS`               |
-| spec.md + research.md | `/plan $ARGUMENTS`               |
-| plan.md exists        | `/implement $ARGUMENTS`          |
-| prd.json exists       | `/complete-next-task $ARGUMENTS` |
+| 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
 
@@ -311,8 +532,35 @@ Artifacts:
 • spec.md: [exists/missing]
 • research.md: [exists/missing]
 • plan.md: [exists/missing]
-
-Research: [launched/skipped]
+• 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]
 ```
@@ -324,3 +572,42 @@ 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/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>`  |