opencodekit 0.18.5 → 0.18.6

package/dist/index.js

@@ -2,7 +2,7 @@
 import { createRequire } from "node:module";
 import { cac } from "cac";
 import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
-import { basename, dirname, join, relative, resolve } from "node:path";
+import { basename, dirname, join, relative } from "node:path";
 import * as p from "@clack/prompts";
 import color from "picocolors";
 import { z } from "zod";
@@ -18,11 +18,35 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 //#endregion
 //#region package.json
-var version = "0.18.5";
+var version = "0.18.6";
 
 //#endregion
 //#region src/utils/errors.ts
 /**
+* Resolve the .opencode directory path.
+* Handles two cases:
+* 1. Standard project: cwd has .opencode/ subdirectory
+* 2. Global config dir: cwd IS the opencode config dir (has opencode.json directly)
+* Returns null if neither case applies.
+*/
+function resolveOpencodePath() {
+	const nested = join(process.cwd(), ".opencode");
+	if (existsSync(nested)) return nested;
+	if (existsSync(join(process.cwd(), "opencode.json"))) return process.cwd();
+	return null;
+}
+/**
+* Resolve opencode path or show "not initialized" error and return null.
+*/
+function requireOpencodePath() {
+	const resolved = resolveOpencodePath();
+	if (!resolved) {
+		notInitialized();
+		return null;
+	}
+	return resolved;
+}
+/**
 * Display a styled error message with optional fix suggestion
 */
 function showError(message, fix) {
@@ -79,7 +103,8 @@ const InitOptionsSchema = z.object({
 	yes: z.boolean().optional().default(false),
 	backup: z.boolean().optional().default(false),
 	prune: z.boolean().optional().default(false),
-	pruneAll: z.boolean().optional().default(false)
+	pruneAll: z.boolean().optional().default(false),
+	projectOnly: z.boolean().optional().default(false)
 });
 const UpgradeOptionsSchema = z.object({
 	force: z.boolean().optional().default(false),
@@ -192,11 +217,8 @@ function parseAction(schema, action) {
 //#region src/commands/agent.ts
 async function agentCommand(action) {
 	const validatedAction = parseAction(AgentActionSchema, action);
-	const opencodePath = join(process.cwd(), ".opencode");
-	if (!existsSync(opencodePath)) {
-		notInitialized();
-		return;
-	}
+	const opencodePath = requireOpencodePath();
+	if (!opencodePath) return;
 	const agentPath = join(opencodePath, "agent");
 	switch (validatedAction) {
 		case "list":
@@ -473,11 +495,8 @@ async function removeAgent(agentPath, agentNameArg) {
 //#region src/commands/command.ts
 async function commandCommand(action) {
 	const validatedAction = parseAction(CommandActionSchema, action);
-	const opencodePath = join(process.cwd(), ".opencode");
-	if (!existsSync(opencodePath)) {
-		notInitialized();
-		return;
-	}
+	const opencodePath = requireOpencodePath();
+	if (!opencodePath) return;
 	const commandDir = join(opencodePath, "command");
 	switch (validatedAction) {
 		case "list":
@@ -982,12 +1001,9 @@ async function getAgentsFromServer() {
 	return fetchFromServer("/agent");
 }
 async function configCommand(action) {
-	const opencodePath = join(process.cwd(), ".opencode");
+	const opencodePath = requireOpencodePath();
+	if (!opencodePath) return;
 	const configPath = join(opencodePath, "opencode.json");
-	if (!existsSync(opencodePath)) {
-		notInitialized();
-		return;
-	}
 	if (!existsSync(configPath)) {
 		showError("opencode.json not found", "ock init --force");
 		return;
@@ -2758,6 +2774,34 @@ const EXCLUDED_FILES = [
 	"pnpm-lock.yaml"
 ];
 const PRESERVE_USER_DIRS = ["memory/project", "context"];
+const SHARED_CONFIG_DIRS = [
+	"agent",
+	"command",
+	"skill",
+	"tool"
+];
+/**
+* Detect if global config has any of the shared dirs populated.
+* Returns null if no global config or no shared dirs found.
+*/
+function detectGlobalConfig() {
+	const globalDir = getGlobalConfigDir();
+	if (!existsSync(globalDir)) return null;
+	const coveredDirs = SHARED_CONFIG_DIRS.filter((d) => {
+		const dirPath = join(globalDir, d);
+		if (!existsSync(dirPath)) return false;
+		try {
+			return readdirSync(dirPath).filter((e) => !e.startsWith(".")).length > 0;
+		} catch {
+			return false;
+		}
+	});
+	if (coveredDirs.length === 0) return null;
+	return {
+		dir: globalDir,
+		coveredDirs
+	};
+}
 /**
 * Get the global OpenCode config directory based on OS.
 * - macOS/Linux: ~/.config/opencode/ (respects XDG_CONFIG_HOME)
@@ -2801,10 +2845,25 @@ async function copyDir(src, dest) {
 		else writeFileSync(destPath, readFileSync(srcPath, "utf-8"));
 	}
 }
-async function copyOpenCodeOnly(templateRoot, targetDir) {
+async function copyOpenCodeOnly(templateRoot, targetDir, skipDirs) {
 	const opencodeSrc = join(templateRoot, ".opencode");
 	const opencodeDest = join(targetDir, ".opencode");
 	if (!existsSync(opencodeSrc)) return false;
+	if (skipDirs && skipDirs.length > 0) {
+		const skipSet = new Set(skipDirs);
+		mkdirSync(opencodeDest, { recursive: true });
+		for (const entry of readdirSync(opencodeSrc, { withFileTypes: true })) {
+			if (EXCLUDED_DIRS.includes(entry.name)) continue;
+			if (!entry.isDirectory() && EXCLUDED_FILES.includes(entry.name)) continue;
+			if (entry.isSymbolicLink()) continue;
+			if (entry.isDirectory() && skipSet.has(entry.name)) continue;
+			const srcPath = join(opencodeSrc, entry.name);
+			const destPath = join(opencodeDest, entry.name);
+			if (entry.isDirectory()) await copyDir(srcPath, destPath);
+			else writeFileSync(destPath, readFileSync(srcPath, "utf-8"));
+		}
+		return true;
+	}
 	await copyDir(opencodeSrc, opencodeDest);
 	return true;
 }
@@ -3100,18 +3159,36 @@ async function initCommand(rawOptions = {}) {
 		}
 		projectName = name || projectName;
 	}
+	let skipDirs = [];
+	if (!options.global) {
+		const globalConfig = detectGlobalConfig();
+		if (globalConfig && options.projectOnly) {
+			skipDirs = globalConfig.coveredDirs;
+			p.log.info(`Using global config from ${color.cyan(globalConfig.dir)}`);
+			p.log.info(`Skipping: ${skipDirs.map((d) => color.dim(d)).join(", ")}`);
+		} else if (globalConfig && !options.yes) {
+			p.log.info(`Global config found at ${color.cyan(globalConfig.dir)}`);
+			p.log.info(`Available globally: ${globalConfig.coveredDirs.map((d) => color.green(d)).join(", ")}`);
+			const useGlobal = await p.confirm({
+				message: "Skip these (use global config)? Only project-scope files will be created locally.",
+				initialValue: true
+			});
+			if (!p.isCancel(useGlobal) && useGlobal) skipDirs = globalConfig.coveredDirs;
+		} else if (globalConfig && options.yes) p.log.info(`Global config found at ${color.cyan(globalConfig.dir)} — use ${color.bold("--project-only")} to skip shared dirs`);
+	}
 	const s = p.spinner();
 	if (mode === "scaffold") {
 		s.start("Scaffolding project");
 		mkdirSync(targetDir, { recursive: true });
 	} else if (mode === "add-config") s.start("Adding OpenCodeKit");
 	else s.start("Reinitializing");
-	if (!await copyOpenCodeOnly(templateRoot, targetDir)) {
+	if (!await copyOpenCodeOnly(templateRoot, targetDir, skipDirs)) {
 		s.stop("Failed");
 		p.outro(color.red("Template copy failed"));
 		process.exit(1);
 	}
 	s.stop("Done");
+	if (skipDirs.length > 0) p.log.info(`Project-only init: skipped ${skipDirs.map((d) => color.dim(d)).join(", ")} (using global config)`);
 	const restoredFileCount = finalizeInstalledFiles(targetDir, getPackageVersion$1(), preservedFiles);
 	if (restoredFileCount > 0) p.log.info(`Preserved ${restoredFileCount} user memory files (memory/project/)`);
 	if (options.free) {
@@ -3280,11 +3357,8 @@ async function initCommand(rawOptions = {}) {
 //#region src/commands/skill.ts
 async function skillCommand(action) {
 	const validatedAction = parseAction(SkillActionSchema, action);
-	const opencodePath = join(process.cwd(), ".opencode");
-	if (!existsSync(opencodePath)) {
-		notInitialized();
-		return;
-	}
+	const opencodePath = requireOpencodePath();
+	if (!opencodePath) return;
 	const skillDir = join(opencodePath, "skill");
 	switch (validatedAction) {
 		case "list":
@@ -3684,12 +3758,9 @@ function findUpgradeOrphans(installedFiles, templateFiles) {
 async function upgradeCommand(rawOptions = {}) {
 	const options = parseOptions(UpgradeOptionsSchema, rawOptions);
 	if (process.argv.includes("--quiet")) return;
-	const opencodeDir = join(process.cwd(), ".opencode");
+	const opencodeDir = requireOpencodePath();
+	if (!opencodeDir) return;
 	const manifest = loadManifest(opencodeDir);
-	if (!existsSync(opencodeDir)) {
-		notInitialized();
-		return;
-	}
 	p.intro(color.bgCyan(color.black(" Upgrade ")));
 	const versionInfo = await checkVersion(opencodeDir);
 	console.log();
@@ -4120,11 +4191,8 @@ function displayChecks(checks) {
 async function statusCommand() {
 	if (process.argv.includes("--quiet")) return;
 	const cwd = process.cwd();
-	const opencodeDir = join(cwd, ".opencode");
-	if (!existsSync(opencodeDir)) {
-		notInitialized();
-		return;
-	}
+	const opencodeDir = requireOpencodePath();
+	if (!opencodeDir) return;
 	const projectName = basename(cwd);
 	p.intro(color.bgCyan(color.black(` ${projectName} `)));
 	const agentDir = join(opencodeDir, "agent");
@@ -4163,14 +4231,6 @@ async function statusCommand() {
 
 //#endregion
 //#region src/commands/patch.ts
-function getOpencodeDir() {
-	const opencodeDir = join(resolve("."), ".opencode");
-	if (!existsSync(opencodeDir)) {
-		notInitialized();
-		return null;
-	}
-	return opencodeDir;
-}
 function listPatches(opencodeDir) {
 	const metadata = loadPatchMetadata(opencodeDir);
 	const entries = Object.entries(metadata.patches);
@@ -4399,7 +4459,7 @@ function togglePatch(opencodeDir, disable) {
 	}
 }
 async function patchCommand(action) {
-	const opencodeDir = getOpencodeDir();
+	const opencodeDir = requireOpencodePath();
 	if (!opencodeDir) return;
 	const validatedAction = parseAction(PatchActionSchema, action);
 	if (!validatedAction) {
@@ -5416,7 +5476,7 @@ function stripAnsi(str) {
 //#region src/tui/hooks/useData.ts
 function loadProjectData() {
 	const cwd = process.cwd();
-	const opencodeDir = join(cwd, ".opencode");
+	const opencodeDir = resolveOpencodePath() ?? join(cwd, ".opencode");
 	const projectName = basename(cwd);
 	const agentDir = join(opencodeDir, "agent");
 	let agents = [];
@@ -5445,9 +5505,6 @@ function loadProjectData() {
 		mcpServers
 	};
 }
-function isInitialized() {
-	return existsSync(join(process.cwd(), ".opencode"));
-}
 
 //#endregion
 //#region src/tui/index.ts
@@ -5455,10 +5512,7 @@ function isInitialized() {
 * Launch the TUI dashboard with interactive navigation.
 */
 async function launchTUI() {
-	if (!isInitialized()) {
-		notInitialized();
-		return;
-	}
+	if (!requireOpencodePath()) return;
 	await mainMenu();
 }
 async function mainMenu() {
@@ -5561,7 +5615,7 @@ const cli = cac("ock");
 cli.option("--verbose", "Enable verbose logging");
 cli.option("--quiet", "Suppress all output");
 cli.version(`${packageVersion}`);
-cli.command("init", "Initialize OpenCodeKit in current directory").option("--force", "Reinitialize even if already exists").option("--beads", "Also initialize .beads/ for multi-agent coordination").option("--global", "Install to global OpenCode config (~/.config/opencode/)").option("--free", "Use free models (default)").option("--recommend", "Use recommended premium models").option("-y, --yes", "Skip prompts, use defaults (for CI)").option("--backup", "Backup existing .opencode before overwriting").option("--prune", "Manually select orphan files to delete").option("--prune-all", "Auto-delete all orphan files").action(initCommand);
+cli.command("init", "Initialize OpenCodeKit in current directory").option("--force", "Reinitialize even if already exists").option("--beads", "Also initialize .beads/ for multi-agent coordination").option("--global", "Install to global OpenCode config (~/.config/opencode/)").option("--free", "Use free models (default)").option("--recommend", "Use recommended premium models").option("-y, --yes", "Skip prompts, use defaults (for CI)").option("--backup", "Backup existing .opencode before overwriting").option("--prune", "Manually select orphan files to delete").option("--prune-all", "Auto-delete all orphan files").option("--project-only", "Only init project-scope files (skip if global config has agents/skills/commands/tools)").action(initCommand);
 cli.command("agent [action]", "Manage agents (list, add, view)").action(async (action) => {
 	if (!action) {
 		console.log("\nUsage: ock agent <action>\n");

package/dist/template/.opencode/agent/explore.md

@@ -11,6 +11,9 @@ tools:
   memory-update: false
   observation: false
   question: false
+  websearch: false
+  webfetch: false
+  codesearch: false
 ---
 
 You are OpenCode, the best coding agent on the planet.
@@ -19,8 +22,6 @@ You are OpenCode, the best coding agent on the planet.
 
 **Purpose**: Read-only codebase cartographer — you map terrain, you don't build on it.
 
-> _"Agency is knowing where the levers are before you pull them."_
-
 ## Identity
 
 You are a read-only codebase explorer. You output concise, evidence-backed findings with absolute paths only.
@@ -29,45 +30,41 @@ You are a read-only codebase explorer. You output concise, evidence-backed findi
 
 Find relevant files, symbols, and usage paths quickly for the caller.
 
-## Skills
+## Tools — Use These for Local Code Search
 
-Always load:
+| Tool | Use For | Example |
+|------|---------|--------|
+| `grep` | Find text/regex patterns in files | `grep(pattern: "PatchEntry", include: "*.ts")` |
+| `glob` | Find files by name/pattern | `glob(pattern: "src/**/*.ts")` |
+| `lsp` (goToDefinition) | Jump to symbol definition | `lsp(operation: "goToDefinition", filePath: "...", line: N, character: N)` |
+| `lsp` (findReferences) | Find all usages of a symbol | `lsp(operation: "findReferences", ...)` |
+| `lsp` (hover) | Get type info and docs | `lsp(operation: "hover", ...)` |
+| `read` | Read file content | `read(filePath: "src/utils/patch.ts")` |
 
-```typescript
-skill({ name: "code-navigation" });
-```
+**NEVER** use `websearch`, `webfetch`, or `codesearch` — those search the internet, not your project.
 
 ## Rules
 
 - Never modify files — read-only is a hard constraint
 - Return absolute paths in final output
 - Cite `file:line` evidence whenever possible
-- Prefer semantic lookup (LSP) before broad text search when it improves precision
-- Stop when you can answer with concrete evidence or when additional search only repeats confirmed paths
+- **Always start with `grep` or `glob`** to locate files and symbols — do NOT read directories to browse
+- Use LSP for precise navigation after finding candidate locations
+- Stop when you can answer with concrete evidence
 
-## Before You Explore
+## Navigation Patterns
 
-- **Be certain**: Only explore what's needed for the task at hand
-- **Don't over-explore**: Stop when you have enough evidence to answer
-- **Use LSP first**: Start with goToDefinition/findReferences before grep
-- **Stay scoped**: Don't explore files outside the task scope
-- **Cite evidence**: Every finding needs file:line reference
+1. **Search first, read second**: `grep` to find where a symbol lives, then `read` only that section
+2. **Don't re-read**: If you already read a file, reference what you learned — don't read it again
+3. **Follow the chain**: definition → usages → callers via LSP findReferences
+4. **Target ≤3 tool calls per symbol**: grep → read section → done
 
 ## Workflow
 
-1. Discover candidate files with `glob` or `workspaceSymbol`
-2. Validate symbol flow with LSP (`goToDefinition`, `findReferences`)
-3. Use `grep` for targeted pattern checks
-4. Read only relevant sections
-5. Return findings + next steps
-
-## Thoroughness Levels
-
-| Level           | Scope                         | Use When                                   |
-| --------------- | ----------------------------- | ------------------------------------------ |
-| `quick`         | 1-3 files, direct answer      | Simple lookups, known symbol names         |
-| `medium`        | 3-6 files, include call paths | Understanding feature flow                 |
-| `very thorough` | Dependency map + edge cases   | Complex refactor prep, architecture review |
+1. `grep` or `glob` to discover candidate files
+2. `lsp` goToDefinition/findReferences for precise symbol navigation
+3. `read` only the relevant sections (use offset/limit)
+4. Return findings with file:line evidence
 
 ## Output
 

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

@@ -75,13 +75,15 @@ ls .beads/artifacts/$ARGUMENTS/
 
 If `plan.md` exists with dependency graph:
 
-1. **Parse waves** from plan header (Wave 1, Wave 2, etc.)
-2. **Execute Wave 1** (independent tasks) in parallel using `task()` subagents
-3. **Wait for Wave 1 completion** — all tasks pass or report failures
-4. **Execute Wave 2** (depends on Wave 1) in parallel
+1. **Load skill:** `skill({ name: "executing-plans" })`
+2. **Parse waves** from dependency graph section
+3. **Execute wave-by-wave:**
+   - Single-task wave → execute directly (no subagent overhead)
+   - Multi-task wave → dispatch parallel `task({ subagent_type: "general" })` subagents, one per task
+4. **Review after each wave** — run verification gates, report, wait for feedback
 5. **Continue** until all waves complete
 
-**Parallel safety:** Only tasks within same wave run in parallel. Tasks in Wave N+1 wait for Wave N.
+**Parallel safety:** Only tasks within same wave run in parallel. Tasks must NOT share files. Tasks in Wave N+1 wait for Wave N.
 
 ### Phase 3A: PRD Task Loop (Sequential Fallback)
 

package/dist/template/.opencode/skill/executing-plans/SKILL.md

@@ -1,29 +1,31 @@
 ---
 name: executing-plans
-description: Use when partner provides a complete implementation plan to execute in controlled batches with review checkpoints - loads plan, reviews critically, executes tasks in batches, reports for review between batches
-version: 1.0.0
-tags: [workflow, planning]
+description: Use when a complete implementation plan exists — parses dependency waves, executes independent tasks in parallel via subagents, runs review checkpoints between waves
+version: 2.0.0
+tags: [workflow, planning, parallel]
 dependencies: [writing-plans]
 ---
 
 # Executing Plans
 
-> **Replaces** unstructured implementation where the agent jumps between tasks without review checkpoints or batch control
+> **Replaces** sequential task-by-task implementation — detects parallelizable waves and dispatches subagents concurrently within each wave
+
 ## When to Use
 
-- A complete implementation plan exists and you need to execute it in batches with checkpoints
-- You must follow a plan precisely and report between waves for feedback
+- A complete implementation plan exists (`.beads/artifacts/<id>/plan.md` or provided directly)
+- The plan has a dependency graph with wave assignments from `/plan`
 
 ## When NOT to Use
 
-- There is no plan yet or requirements are still unclear
-- You need to create the plan or tasks first (use writing-plans or prd)
+- No plan yet (use `writing-plans` or `prd` first)
+- All tasks are tightly sequential with no parallelism opportunity
+- Fewer than 3 tasks (just execute directly, overhead not worth it)
 
 ## Overview
 
-Load plan, review critically, execute tasks in batches, report for review between batches.
+Load plan → parse dependency waves → execute each wave (parallel within, sequential between) → review after each wave → next wave.
 
-**Core principle:** Batch execution with checkpoints for architect review.
+**Core principle:** Parallel within waves, sequential between waves, review at wave boundaries.
 
 **Announce at start:** "I'm using the executing-plans skill to implement this plan."
 
@@ -36,104 +38,149 @@ Load plan, review critically, execute tasks in batches, report for review betwee
 - [ ] Read the plan file end-to-end
 - [ ] Identify goal, deliverables, risks, and missing pieces
 - [ ] If concerns, ask via `question()` and wait for decision
-- [ ] If no concerns, create TodoWrite and proceed
+- [ ] If no concerns, proceed to wave parsing
 
 1. Read plan file
-2. Review critically - identify any questions or concerns about the plan
-3. If concerns: Use question tool to raise them:
+2. Review critically — identify any questions or concerns
+3. If concerns: raise them with `question()` tool
+4. If no concerns: proceed
 
-```typescript
-question({
-  questions: [
-    {
-      header: "Concerns",
-      question: "Plan review complete. Any concerns before proceeding?",
-      options: [
-        {
-          label: "No concerns (Recommended)",
-          description: "Plan looks good, execute batches",
-        },
-        {
-          label: "Has concerns",
-          description: "Need clarification before starting",
-        },
-      ],
-    },
-  ],
-});
-```
+### Step 2: Parse Dependency Graph
 
-4. Read plan and identify:
-   - What is the goal?
-   - What are the deliverables?
-   - What are the risks?
-   - Does the approach make sense?
-   - Are there missing pieces?
+Look for the dependency graph section in the plan. The `/plan` command generates this format:
 
-If no concerns: Create TodoWrite and proceed
-If concerns: Wait for human to decide and resubmit
+```
+## Dependency Graph
 
-### Step 2: Execute Batch
+Task A: needs nothing, creates src/models/X.ts
+Task B: needs Task A, creates src/api/X.ts
+Task C: needs nothing, creates src/utils/Y.ts
+Task D: needs Task B + Task C, creates src/routes/Z.ts
 
-**Default: First 3 tasks**
+Wave 1: A, C  (independent)
+Wave 2: B     (depends on A)
+Wave 3: D     (depends on B, C)
+```
 
-**Before starting a batch**: create a wave-start git tag for safe rollback:
+**Extract:**
+- Which tasks belong to each wave
+- Which files each task modifies (for conflict detection)
+- Dependencies between tasks
 
-```bash
-# Tag the safe point before this batch/wave
-git tag wave-${BATCH_NUMBER}-start
-```
+**If no dependency graph found:** Fall back to sequential execution (batch of 3 tasks).
 
-#### Batch Execution Checklist
+**File conflict check:** Tasks in the same wave MUST NOT modify the same files. If they do, move one to the next wave.
 
-- [ ] Create wave start tag: `git tag wave-${BATCH_NUMBER}-start`
-- [ ] Mark each task in_progress
-- [ ] Follow each step exactly as written
-- [ ] Run all specified verifications
-- [ ] Mark tasks completed
-- [ ] Create wave complete tag: `git tag wave-${BATCH_NUMBER}-complete`
+### Step 3: Create TodoWrite
 
-For each task:
+Create todos for all tasks, grouped by wave:
 
-1. Mark as in_progress
-2. Follow each step exactly (plan has bite-sized steps)
-3. Run verifications as specified
-4. Mark as completed
+```typescript
+todowrite({
+  todos: [
+    { content: "Wave 1: Task A — [description]", status: "pending", priority: "high" },
+    { content: "Wave 1: Task C — [description]", status: "pending", priority: "high" },
+    { content: "Wave 1 review checkpoint", status: "pending", priority: "high" },
+    { content: "Wave 2: Task B — [description]", status: "pending", priority: "high" },
+    { content: "Wave 2 review checkpoint", status: "pending", priority: "high" },
+    // ...
+  ]
+});
+```
+
+### Step 4: Execute Wave
 
-**After batch passes all gates**: create a wave-complete tag:
+**Before starting a wave:** create a git tag for safe rollback:
 
 ```bash
-# Seal the completed wave - confirms all gates passed
-git tag wave-${BATCH_NUMBER}-complete
+git tag wave-${WAVE_NUMBER}-start
 ```
 
-### Step 3: Report
+#### Single-task wave (no parallelism needed)
 
-#### Batch Report Checklist
+Execute directly in the current agent context. No subagent overhead.
 
-- [ ] Summarize what was implemented
-- [ ] Include verification output
-- [ ] Confirm wave tag created (e.g., `wave-1-complete`)
-- [ ] Ask for feedback before continuing
+#### Multi-task wave (2+ independent tasks)
 
-When batch complete:
+Dispatch parallel subagents — one per task:
 
-- Show what was implemented
-- Show verification output
-- Show wave tag created (e.g., `wave-1-complete`)
-- Say: "Ready for feedback."
+```typescript
+// Dispatch all tasks in this wave simultaneously
+task({
+  subagent_type: "general",
+  description: `Wave ${N}: Task A — ${taskTitle}`,
+  prompt: `You are implementing Task A from the plan.
+
+## Task
+${taskDescription}
+
+## Files to modify
+${taskFiles.join('\n')}
+
+## Constraints
+- ONLY modify files listed above
+- Follow each step exactly as written in the task
+- Run verification commands specified in the task
+- Commit your changes: git add <specific-files> && git commit -m "feat: ${taskTitle}"
+
+## Report back
+- What you implemented
+- Files changed
+- Verification results (pass/fail)
+- Commit hash
+- Any issues or blockers`
+});
+// ...dispatch other tasks in this wave simultaneously
+```
 
-### Step 4: Continue
+**Critical rules for parallel dispatch:**
+
+| Rule | Why |
+| --- | --- |
+| Non-overlapping files | Subagents editing same file = merge conflicts |
+| Exact file list per subagent | Prevents scope creep into other tasks |
+| Each subagent commits independently | Clean git history per task |
+| Never `git add .` | Only stage files from this task |
+
+#### Wave Execution Checklist
+
+- [ ] Create wave start tag: `git tag wave-${WAVE_NUMBER}-start`
+- [ ] Dispatch subagents for all tasks in this wave (parallel)
+- [ ] Collect results from all subagents
+- [ ] Check for failures — if any task failed, stop and report
+- [ ] Run verification gates (typecheck + lint in parallel, then tests)
+- [ ] Create wave complete tag: `git tag wave-${WAVE_NUMBER}-complete`
+- [ ] Mark wave tasks as completed in TodoWrite
+
+### Step 5: Review Wave
+
+After each wave completes:
+
+1. **Synthesize results** from all subagents
+2. **Run verification gates** on the combined changes:
+   ```bash
+   # Parallel: typecheck + lint
+   npm run typecheck & npm run lint & wait
+   # Sequential: tests
+   npm test
+   ```
+3. **Report to user:**
+   - Tasks completed in this wave
+   - Verification results
+   - Wave tag created
+   - Any issues found
+4. **Wait for feedback** before proceeding to next wave
+
+### Step 6: Next Wave
 
 Based on feedback:
+- Apply corrections if needed
+- Execute next wave (repeat Steps 4-5)
+- Continue until all waves complete
 
-- Apply changes if needed
-- Execute next batch
-- Repeat until complete
-
-### Step 5: Complete Development
+### Step 7: Complete Development
 
-After all tasks complete and verified:
+After all waves complete and verified:
 
 - Announce: "I'm using finishing-a-development-branch skill to complete this work."
 - **REQUIRED SUB-SKILL:** Use skill({ name: "finishing-a-development-branch" })
@@ -147,84 +194,54 @@ Git tags act as checkpoints between waves. If a wave fails irrecoverably, roll b
 
 | When                         | Command                         | Purpose                   |
 | ---------------------------- | ------------------------------- | ------------------------- |
-| Before starting any batch    | `git tag wave-N-start`          | Mark rollback point       |
-| After batch passes all gates | `git tag wave-N-complete`       | Seal confirmed-good state |
+| Before starting any wave     | `git tag wave-N-start`          | Mark rollback point       |
+| After wave passes all gates  | `git tag wave-N-complete`       | Seal confirmed-good state |
 | On irrecoverable failure     | `git reset --hard wave-N-start` | Restore to pre-wave state |
 | Listing all wave checkpoints | `git tag --list "wave-*"`       | Audit trail of execution  |
 
 ### When to Rollback
 
 Roll back (with user confirmation) when:
-
-- Build gates fail twice consecutively in the same wave
-- Unexpected destructive changes were made
-- Drift check detects unrecoverable scope creep
+- Verification gates fail twice consecutively in the same wave
+- Subagent made destructive changes outside its file scope
 - Tests were broken and the cause is unclear
 
-**Always ask the user before running `git reset --hard`** - it discards uncommitted changes irreversibly.
-
-### Rollback Steps
-
-```bash
-# 1. Identify safe point
-git tag --list "wave-*"
-# e.g.: wave-1-complete  wave-2-start  wave-2-complete  wave-3-start
-
-# 2. Confirm with user: rollback to which tag?
-# e.g.: git reset --hard wave-2-complete (last known good)
+**Always ask the user before running `git reset --hard`** — it discards uncommitted changes irreversibly.
 
-# 3. Execute rollback (ONLY after user confirms)
-git reset --hard wave-2-complete
+## Sequential Fallback
 
-# 4. Verify state is clean
-npm run typecheck && npm run lint
+If the plan has no dependency graph or waves:
 
-# 5. Re-plan the failed batch with new approach
-```
+1. Group tasks into batches of 3
+2. Execute each batch sequentially (no parallel subagents)
+3. Review between batches
+4. Same wave-tag protocol applies
 
-### Tag Naming Convention
-
-```
-wave-1-start      # Before batch 1 starts
-wave-1-complete   # After batch 1 passes all gates
-wave-2-start      # Before batch 2 starts
-wave-2-complete   # After batch 2 passes all gates
-...
-```
-
-Use numeric batch numbers, not task names, for predictable reference.
+This preserves backward compatibility with plans that don't have wave assignments.
 
 ## When to Stop and Ask for Help
 
 **STOP executing immediately when:**
-
-- Hit a blocker mid-batch (missing dependency, test fails, instruction unclear)
+- Subagent reports a blocker or failure
+- File conflict detected between parallel tasks
+- Verification fails twice in the same wave
 - Plan has critical gaps preventing starting
-- You don't understand an instruction
-- Verification fails repeatedly
 
 **Ask for clarification rather than guessing.**
 
-## When to Revisit Earlier Steps
-
-**Return to Review (Step 1) when:**
-
-- Partner updates the plan based on your feedback
-- Fundamental approach needs rethinking
-
-**Don't force through blockers** - stop and ask.
-
-## Remember
+## Anti-Patterns
 
-- Review plan critically first
-- Follow plan steps exactly
-- Don't skip verifications
-- Reference skills when plan says to
-- Between batches: just report and wait
-- Stop when blocked, don't guess
+| Anti-Pattern | Why It Fails | Instead |
+| --- | --- | --- |
+| Dispatching parallel subagents for tasks that share files | Edit conflicts, lost changes, merge chaos | Move conflicting tasks to separate waves |
+| Skipping verification between waves | Broken code compounds across waves | Run all gates after each wave before proceeding |
+| Giving subagents the full plan instead of their task | Context pollution, scope creep | Extract only the specific task + file list |
+| Running all tasks in one wave regardless of dependencies | Later tasks fail because prerequisites aren't ready | Respect the dependency graph strictly |
+| Not committing per-task | Can't rollback individual tasks, messy git history | Each subagent commits its own changes |
 
 ## See Also
 
-- `writing-plans` - Create detailed, zero-ambiguity implementation plans before execution
-- `swarm-coordination` - Coordinate parallel execution when many independent tasks can run concurrently
-- `verification-before-completion` - Run final verification gates before claiming completion
+- `writing-plans` — Create detailed, zero-ambiguity implementation plans before execution
+- `swarm-coordination` — For 10+ task scenarios with full PARL orchestration
+- `subagent-driven-development` — For sequential per-task execution with review between each
+- `verification-before-completion` — Run final verification gates before claiming completion

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencodekit",
-	"version": "0.18.5",
+	"version": "0.18.6",
 	"description": "CLI tool for bootstrapping and managing OpenCodeKit projects",
 	"keywords": [
 		"agents",