opencodekit 0.18.2 → 0.18.3

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 } 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,7 +18,7 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 //#endregion
 //#region package.json
-var version = "0.18.2";
+var version = "0.18.3";
 
 //#endregion
 //#region src/utils/errors.ts
@@ -2409,6 +2409,83 @@ async function editAutoupdate(configPath) {
 	p.log.success(`Autoupdate set to ${color.cyan(selectedValue)}`);
 }
 
+//#endregion
+//#region src/utils/manifest.ts
+const MANIFEST_FILE = ".template-manifest.json";
+/**
+* Compute SHA-256 hash of file content.
+*/
+function hashFile(filePath) {
+	const content = readFileSync(filePath, "utf-8");
+	return createHash("sha256").update(content).digest("hex");
+}
+/**
+* Scan a directory recursively and build a hash map of all files.
+* Returns record of relative paths to SHA-256 hashes.
+*/
+function buildManifestFromDir(dir, skipDirs = [
+	"node_modules",
+	".git",
+	"dist",
+	"coverage"
+]) {
+	const files = {};
+	function walk(currentDir) {
+		for (const entry of readdirSync(currentDir, { withFileTypes: true })) if (entry.isDirectory()) {
+			if (skipDirs.includes(entry.name)) continue;
+			walk(join(currentDir, entry.name));
+		} else if (entry.isFile()) {
+			if (entry.name === MANIFEST_FILE) continue;
+			const fullPath = join(currentDir, entry.name);
+			const relPath = relative(dir, fullPath);
+			files[relPath] = hashFile(fullPath);
+		}
+	}
+	walk(dir);
+	return files;
+}
+/**
+* Generate and save a template manifest after installation.
+*/
+function generateManifest(opencodeDir, version) {
+	const manifest = {
+		version,
+		createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+		files: buildManifestFromDir(opencodeDir)
+	};
+	writeFileSync(join(opencodeDir, MANIFEST_FILE), JSON.stringify(manifest, null, 2));
+	return manifest;
+}
+/**
+* Load existing manifest from .opencode/ directory.
+* Returns null if no manifest exists.
+*/
+function loadManifest(opencodeDir) {
+	const manifestPath = join(opencodeDir, MANIFEST_FILE);
+	if (!existsSync(manifestPath)) return null;
+	try {
+		return JSON.parse(readFileSync(manifestPath, "utf-8"));
+	} catch {
+		return null;
+	}
+}
+/**
+* Determine if a file has been modified by the user.
+* Compares current file hash against the manifest's recorded hash.
+*
+* Returns:
+* - "unmodified" — file matches template, safe to update
+* - "modified" — user changed it, should preserve
+* - "unknown" — not in manifest (new user file or missing manifest)
+*/
+function fileModificationStatus(filePath, relativePath, manifest) {
+	if (!manifest) return "unknown";
+	const templateHash = manifest.files[relativePath];
+	if (!templateHash) return "unknown";
+	if (!existsSync(filePath)) return "unmodified";
+	return hashFile(filePath) === templateHash ? "unmodified" : "modified";
+}
+
 //#endregion
 //#region src/utils/patch.ts
 /**
@@ -2467,7 +2544,7 @@ function savePatchMetadata(opencodeDir, metadata) {
 /**
 * Get the current OpenCodeKit version from package.json.
 */
-function getPackageVersion$1() {
+function getPackageVersion$2() {
 	const __dirname = dirname(fileURLToPath(import.meta.url));
 	const pkgPaths = [join(__dirname, "..", "..", "package.json"), join(__dirname, "..", "package.json")];
 	for (const pkgPath of pkgPaths) if (existsSync(pkgPath)) try {
@@ -2497,7 +2574,7 @@ function savePatch(opencodeDir, relativePath, templateContent, userContent) {
 		currentHash: calculateHash(userContent),
 		patchFile: patchFilename,
 		createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-		templateVersion: getPackageVersion$1()
+		templateVersion: getPackageVersion$2()
 	};
 	metadata.patches[relativePath] = entry;
 	savePatchMetadata(opencodeDir, metadata);
@@ -2578,7 +2655,7 @@ const EXCLUDED_FILES = [
 	"yarn.lock",
 	"pnpm-lock.yaml"
 ];
-const PRESERVE_USER_DIRS = ["memory/project"];
+const PRESERVE_USER_DIRS = ["memory/project", "context"];
 /**
 * Get the global OpenCode config directory based on OS.
 * - macOS/Linux: ~/.config/opencode/ (respects XDG_CONFIG_HOME)
@@ -2601,6 +2678,15 @@ function getTemplateRoot$1() {
 	for (const path of possiblePaths) if (existsSync(join(path, ".opencode"))) return path;
 	return null;
 }
+function getPackageVersion$1() {
+	const __dirname = dirname(fileURLToPath(import.meta.url));
+	const pkgPaths = [join(__dirname, "..", "..", "package.json"), join(__dirname, "..", "package.json")];
+	for (const pkgPath of pkgPaths) {
+		if (!existsSync(pkgPath)) continue;
+		return JSON.parse(readFileSync(pkgPath, "utf-8")).version;
+	}
+	return "unknown";
+}
 async function copyDir(src, dest) {
 	const { mkdir, readdir } = await import("node:fs/promises");
 	await mkdir(dest, { recursive: true });
@@ -2729,7 +2815,7 @@ function getTemplateFiles(templateRoot) {
 function findOrphans(targetDir, templateFiles) {
 	const opencodeDir = join(targetDir, ".opencode");
 	if (!existsSync(opencodeDir)) return [];
-	return getAffectedFiles(opencodeDir).filter((f) => !templateFiles.has(f));
+	return getAffectedFiles(opencodeDir).filter((f) => f !== MANIFEST_FILE && !templateFiles.has(f));
 }
 /**
 * Check if an orphan file is a modified template file (exists in template but content differs).
@@ -2778,16 +2864,23 @@ async function autoSavePatchesForOrphans(targetDir, templateRoot, orphans) {
 function preserveUserFiles(targetDir) {
 	const opencodeDir = join(targetDir, ".opencode");
 	const preserved = /* @__PURE__ */ new Map();
-	for (const relDir of PRESERVE_USER_DIRS) {
-		const dirPath = join(opencodeDir, relDir);
-		if (!existsSync(dirPath)) continue;
-		for (const entry of readdirSync(dirPath, { withFileTypes: true })) {
+	function collectFiles(currentDir, relativeDir) {
+		for (const entry of readdirSync(currentDir, { withFileTypes: true })) {
+			const filePath = join(currentDir, entry.name);
+			const relativePath = join(relativeDir, entry.name);
+			if (entry.isDirectory()) {
+				collectFiles(filePath, relativePath);
+				continue;
+			}
 			if (!entry.isFile()) continue;
-			const filePath = join(dirPath, entry.name);
-			const relativePath = join(relDir, entry.name);
 			preserved.set(relativePath, readFileSync(filePath, "utf-8"));
 		}
 	}
+	for (const relDir of PRESERVE_USER_DIRS) {
+		const dirPath = join(opencodeDir, relDir);
+		if (!existsSync(dirPath)) continue;
+		collectFiles(dirPath, relDir);
+	}
 	return preserved;
 }
 /**
@@ -2801,6 +2894,12 @@ function restoreUserFiles(targetDir, preserved) {
 		writeFileSync(filePath, content);
 	}
 }
+function finalizeInstalledFiles(targetDir, version, preservedFiles) {
+	generateManifest(join(targetDir, ".opencode"), version);
+	if (!preservedFiles || preservedFiles.size === 0) return 0;
+	restoreUserFiles(targetDir, preservedFiles);
+	return preservedFiles.size;
+}
 async function initCommand(rawOptions = {}) {
 	const options = parseOptions(InitOptionsSchema, rawOptions);
 	if (process.argv.includes("--quiet")) return;
@@ -2911,10 +3010,8 @@ async function initCommand(rawOptions = {}) {
 		process.exit(1);
 	}
 	s.stop("Done");
-	if (preservedFiles && preservedFiles.size > 0) {
-		restoreUserFiles(targetDir, preservedFiles);
-		p.log.info(`Preserved ${preservedFiles.size} user memory files (memory/project/)`);
-	}
+	const restoredFileCount = finalizeInstalledFiles(targetDir, getPackageVersion$1(), preservedFiles);
+	if (restoredFileCount > 0) p.log.info(`Preserved ${restoredFileCount} user memory files (memory/project/)`);
 	if (options.free) {
 		applyModelPreset(targetDir, "free");
 		p.log.info("Applied free model preset");
@@ -3352,6 +3449,7 @@ const PRESERVE_FILES = ["opencode.json", ".env"];
 const PRESERVE_DIRS = [
 	"agent",
 	"command",
+	"context",
 	"memory",
 	"skill",
 	"tool"
@@ -3388,7 +3486,8 @@ async function checkVersion(opencodeDir) {
 		needsUpdate: current !== latest
 	};
 }
-function copyDirWithPreserve(src, dest, preserveFiles, preserveDirs) {
+function copyDirWithPreserve(src, dest, preserveFiles, preserveDirs, manifest, basePath = "") {
+	const added = [];
 	const updated = [];
 	const preserved = [];
 	if (!existsSync(dest)) mkdirSync(dest, { recursive: true });
@@ -3399,25 +3498,34 @@ function copyDirWithPreserve(src, dest, preserveFiles, preserveDirs) {
 		const destPath = join(dest, entry.name);
 		if (entry.isDirectory()) if (preserveDirs.includes(entry.name)) {
 			if (!existsSync(destPath)) mkdirSync(destPath, { recursive: true });
-			const subResult = copyDirPreserveExisting(srcPath, destPath);
+			const subResult = copyDirPreserveExisting(srcPath, destPath, manifest, entry.name);
+			added.push(...subResult.added);
 			updated.push(...subResult.updated);
 			preserved.push(...subResult.preserved);
 		} else {
-			const subResult = copyDirWithPreserve(srcPath, destPath, [], []);
+			const subResult = copyDirWithPreserve(srcPath, destPath, [], [], manifest, join(basePath, entry.name));
+			added.push(...subResult.added);
 			updated.push(...subResult.updated);
+			preserved.push(...subResult.preserved);
 		}
-		else if (preserveFiles.includes(entry.name) && existsSync(destPath)) preserved.push(entry.name);
 		else {
-			copyFileSync(srcPath, destPath);
-			updated.push(entry.name);
+			const relativePath = join(basePath, entry.name);
+			if (preserveFiles.includes(entry.name) && existsSync(destPath)) preserved.push(relativePath);
+			else {
+				if (!existsSync(destPath)) added.push(relativePath);
+				else updated.push(relativePath);
+				copyFileSync(srcPath, destPath);
+			}
 		}
 	}
 	return {
+		added,
 		updated,
 		preserved
 	};
 }
-function copyDirPreserveExisting(src, dest) {
+function copyDirPreserveExisting(src, dest, manifest, basePath = "") {
+	const added = [];
 	const updated = [];
 	const preserved = [];
 	const entries = readdirSync(src, { withFileTypes: true });
@@ -3426,15 +3534,23 @@ function copyDirPreserveExisting(src, dest) {
 		const destPath = join(dest, entry.name);
 		if (entry.isDirectory()) {
 			if (!existsSync(destPath)) mkdirSync(destPath, { recursive: true });
-			const subResult = copyDirPreserveExisting(srcPath, destPath);
+			const subResult = copyDirPreserveExisting(srcPath, destPath, manifest, join(basePath, entry.name));
+			added.push(...subResult.added);
 			updated.push(...subResult.updated);
 			preserved.push(...subResult.preserved);
-		} else if (!existsSync(destPath)) {
-			copyFileSync(srcPath, destPath);
-			updated.push(entry.name);
-		} else preserved.push(entry.name);
+		} else {
+			const relativePath = join(basePath, entry.name);
+			if (!existsSync(destPath)) {
+				copyFileSync(srcPath, destPath);
+				added.push(relativePath);
+			} else if (fileModificationStatus(destPath, relativePath, manifest) === "unmodified") {
+				copyFileSync(srcPath, destPath);
+				updated.push(relativePath);
+			} else preserved.push(relativePath);
+		}
 	}
 	return {
+		added,
 		updated,
 		preserved
 	};
@@ -3451,10 +3567,20 @@ function getAllFiles(dir, base = "") {
 	}
 	return files;
 }
+function findUpgradeOrphans(installedFiles, templateFiles) {
+	return installedFiles.filter((file) => {
+		if (file === ".version") return false;
+		if (file === MANIFEST_FILE) return false;
+		if (PRESERVE_FILES.includes(file)) return false;
+		if (file === ".env" || file.endsWith(".env")) return false;
+		return !templateFiles.includes(file);
+	});
+}
 async function upgradeCommand(rawOptions = {}) {
 	const options = parseOptions(UpgradeOptionsSchema, rawOptions);
 	if (process.argv.includes("--quiet")) return;
 	const opencodeDir = join(process.cwd(), ".opencode");
+	const manifest = loadManifest(opencodeDir);
 	if (!existsSync(opencodeDir)) {
 		notInitialized();
 		return;
@@ -3495,8 +3621,11 @@ async function upgradeCommand(rawOptions = {}) {
 	}
 	const s = p.spinner();
 	s.start("Upgrading");
-	const result = copyDirWithPreserve(templateOpencode, opencodeDir, PRESERVE_FILES, PRESERVE_DIRS);
-	if (versionInfo.latest) writeFileSync(join(opencodeDir, ".version"), versionInfo.latest);
+	const result = copyDirWithPreserve(templateOpencode, opencodeDir, PRESERVE_FILES, PRESERVE_DIRS, manifest);
+	if (versionInfo.latest) {
+		writeFileSync(join(opencodeDir, ".version"), versionInfo.latest);
+		generateManifest(opencodeDir, versionInfo.latest);
+	}
 	s.stop("Done");
 	const patchMetadata = loadPatchMetadata(opencodeDir);
 	const patchCount = Object.keys(patchMetadata.patches).length;
@@ -3516,16 +3645,10 @@ async function upgradeCommand(rawOptions = {}) {
 		if (patchResults.conflicts > 0) p.log.warn(`${patchResults.conflicts} patch conflicts (see .opencode/patches/*.rej files)`);
 	}
 	if (result.updated.length > 0) p.log.success(`Updated ${result.updated.length} files`);
+	if (result.added.length > 0) p.log.success(`Added ${result.added.length} files`);
 	if (result.preserved.length > 0) p.log.info(`Preserved ${result.preserved.length} user files`);
 	if (patchResults.success > 0) p.log.success(`Reapplied ${patchResults.success} patches`);
-	const installedFiles = getAllFiles(opencodeDir);
-	const templateFiles = getAllFiles(templateOpencode);
-	const orphans = installedFiles.filter((file) => {
-		if (file === ".version") return false;
-		if (PRESERVE_FILES.includes(file)) return false;
-		if (file === ".env" || file.endsWith(".env")) return false;
-		return !templateFiles.includes(file);
-	});
+	const orphans = findUpgradeOrphans(getAllFiles(opencodeDir), getAllFiles(templateOpencode));
 	if (orphans.length > 0) {
 		p.log.info(`${color.yellow(orphans.length.toString())} files found that are not in the template (orphans).`);
 		if (options.pruneAll) {

package/dist/template/.opencode/.version

@@ -1 +1 @@
-0.17.5
+0.18.3

package/dist/template/.opencode/AGENTS.md

@@ -21,13 +21,15 @@ Your loop: **perceive → create → verify → ship.**
 When instructions conflict:
 
 1. **Security** — never expose or invent credentials
-2. **Anti-hallucination** — verify before asserting
+2. **Anti-hallucination** — verify before asserting; if context is missing, prefer lookup over guessing; if you must proceed without full context, label assumptions explicitly and choose a reversible action
 3. **User intent** — do what was asked, simply and directly
 4. **Agency preservation** — "likely difficult" ≠ "impossible" ≠ "don't try"
 5. This `AGENTS.md`
 6. Memory (`memory-search`)
 7. Project files and codebase evidence
 
+If a newer user instruction conflicts with an earlier one, follow the newer instruction. Preserve earlier instructions that don't conflict.
+
 ---
 
 ## Operating Principles
@@ -70,18 +72,46 @@ When instructions conflict:
 | `build.gradle`   | `gradle compileJava`                    | `gradle checkstyleMain` | `gradle test`   |
 | `Makefile`       | Check for `check`/`lint`/`test` targets |                         |                 |
 
+### Tool Persistence
+
+- Use tools whenever they materially improve correctness or completeness
+- Don't stop early when another tool call would improve the result
+- Keep calling tools until the task is complete **and** verification passes
+- If a tool returns empty or partial results, retry with a different strategy before giving up (see Empty Result Recovery)
+
+### Dependency Checks
+
+- Before taking an action, check whether prerequisite discovery, lookup, or memory retrieval steps are required
+- Don't skip prerequisite steps because the final action seems obvious
+- If a task depends on the output of a prior step, resolve that dependency first
+
+### Empty Result Recovery
+
+If a lookup, search, or tool call returns empty, partial, or suspiciously narrow results:
+
+1. Don't immediately conclude that no results exist
+2. Try at least 1-2 fallback strategies (alternative query terms, broader filters, different source/tool)
+3. Only then report "no results found" along with what strategies were attempted
+
+### Completeness Tracking
+
+- Treat a task as incomplete until all requested items are covered or explicitly marked `[blocked]`
+- Maintain an internal checklist of deliverables (use TodoWrite for multi-step work)
+- For lists, batches, or paginated results: determine expected scope, track processed items, confirm full coverage
+- If any item is blocked by missing data, mark it `[blocked]` and state exactly what is missing
+
 ---
 
 ## Hard Constraints (Never Violate)
 
-| Constraint    | Rule                                                                              |
-| ------------- | --------------------------------------------------------------------------------- |
-| Security      | Never expose/invent credentials                                                   |
-| Git Safety    | Never force push main/master; never bypass hooks                                  |
-| Git Restore   | Never run `reset --hard`, `checkout .`, `clean -fd` without explicit user request |
-| Honesty       | Never fabricate tool output; never guess URLs                                     |
-| Paths         | Use absolute paths for file operations                                            |
-| Reversibility | Ask first before destructive/irreversible actions                                 |
+| Constraint    | Rule                                                                                                                              |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| Security      | Never expose/invent credentials                                                                                                   |
+| Git Safety    | Never force push main/master; never bypass hooks                                                                                  |
+| Git Restore   | Never run `reset --hard`, `checkout .`, `clean -fd` without explicit user request                                                 |
+| Honesty       | Never fabricate tool output; never guess URLs; label inferences as inferences; if sources conflict, state the conflict explicitly |
+| Paths         | Use absolute paths for file operations                                                                                            |
+| Reversibility | Ask first before destructive/irreversible actions                                                                                 |
 
 ---
 

package/dist/template/.opencode/AGENT_ALIGNMENT.md

@@ -17,7 +17,7 @@ GSD has **11 specialized agents** (~12,000 total lines) vs OpenCodeKit's **8 gen
 | `gsd-phase-researcher`     | ~300  | Domain research for specific phases                                                               | `scout` (91 lines)                                            | Similar scope, GSD has more structured output                                                                |
 | `gsd-research-synthesizer` | ~200  | Aggregates parallel research findings                                                             | _No equivalent_                                               | **Missing**: Multi-agent research aggregation                                                                |
 | `gsd-plan-checker`         | ~400  | Validates plans against requirements before execution                                             | _No equivalent_                                               | **Missing**: Pre-execution plan validation                                                                   |
-| `gsd-roadmapper`           | ~300  | Creates ROADMAP.md with phase structure                                                           | _No equivalent_                                               | **Missing**: Dedicated roadmap creation                                                                      |
+| `gsd-roadmapper`           | ~300  | Creates roadmap.md with phase structure                                                           | _No equivalent_                                               | **Missing**: Dedicated roadmap creation                                                                      |
 | `gsd-codebase-mapper`      | ~500  | Analyzes existing codebase architecture                                                           | `explore` (65 lines)                                          | Deeper analysis: stack, conventions, concerns, architecture                                                  |
 | `gsd-project-researcher`   | ~250  | Project-level ecosystem research                                                                  | `scout`                                                       | Overlaps with phase-researcher                                                                               |
 | `gsd-integration-checker`  | ~200  | Validates integrations work correctly                                                             | _No equivalent_                                               | **Missing**: Integration validation agent                                                                    |
@@ -401,14 +401,14 @@ Recommendation: Add as skill or plan agent mode
 #### gsd-roadmapper (~300 lines)
 
 ```markdown
-Creates ROADMAP.md with phase structure.
+Creates roadmap.md with phase structure.
 
 Outputs:
 
-- PROJECT.md (vision)
+- project.md (vision)
 - REQUIREMENTS.md (scoped v1/v2)
-- ROADMAP.md (phases with goals)
-- STATE.md (memory)
+- roadmap.md (phases with goals)
+- state.md (memory)
 
 Recommendation: Add `/roadmap` command
 ```
@@ -510,7 +510,7 @@ research-lead (NEW - optional):
 
 /roadmap:
   description: Create project roadmap
-  creates: PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md
+  creates: project.md, REQUIREMENTS.md, roadmap.md, state.md
   ported_from: gsd:new-project (planning phase only)
 
 /verify:

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

@@ -82,109 +82,6 @@ Implement requested work, verify with fresh evidence, and coordinate subagents o
 - Re-run typecheck/lint/tests after meaningful edits
 - If verification fails twice on the same approach, **escalate with learnings**, not frustration
 
-## Memory Ritual
-
-Memory makes knowledge persistent. Follow this ritual every session:
-
-### Ground Phase — Load Context
-
-```typescript
-// 1. Search for relevant past work
-memory_search({ query: "<task keywords>", limit: 5 });
-
-// 2. Check recent handoffs
-memory_read({ file: "handoffs/last" });
-```
-
-### Transform Phase — Record Discoveries
-
-```typescript
-observation({
-  type: "pattern",
-  title: "Brief description",
-  narrative: "Context and reasoning...",
-  facts: "key, facts, here",
-  concepts: "searchable, keywords",
-  files_modified: "src/file.ts",
-});
-```
-
-## Rules
-
-- Be concise, direct, and evidence-based
-- Never claim success without fresh verification output
-- Ask before irreversible actions (close bead, commit, push, force operations)
-- Never bypass hooks or safety checks
-- Never fabricate tool output
-- Never use secrets not explicitly provided
-
-## Skills
-
-Always load:
-
-- beads (task tracking)
-- verification-before-completion
-
-Load contextually when needed:
-
-| Work Type              | Skills                                         |
-| ---------------------- | ---------------------------------------------- |
-| Planning artifacts     | prd-task, executing-plans, writing-plans, prd  |
-| Debug/bug work         | systematic-debugging, root-cause-tracing       |
-| Test-heavy work        | test-driven-development, testing-anti-patterns |
-| UI work                | frontend-design, react-best-practices          |
-| Parallel orchestration | swarm-coordination, beads-bridge               |
-
-## Execution Mode
-
-- **Sequential** by default for coupled work
-- **Parallel** for 3+ independent, file-disjoint tasks using `task(...)`
-
-## Deviation Rules (Auto-Fix Without Permission)
-
-While executing, you WILL discover work not in the plan. Apply these rules automatically:
-
-**RULE 1: Auto-fix bugs** (broken behavior, errors, logic issues)
-
-- Wrong queries, type errors, null pointer exceptions
-- Fix inline → verify → continue task
-
-**RULE 2: Auto-add missing critical functionality** (validation, auth, error handling)
-
-- Missing input validation, no auth on protected routes
-- No error handling, missing null checks
-
-**RULE 3: Auto-fix blocking issues** (missing deps, wrong types, broken imports)
-
-- Missing dependency, wrong types, broken imports
-
-**RULE 4: ASK about architectural changes** (new tables, library switches, major refactors)
-
-- STOP → report to user with: what found, proposed change, impact
-
-## Output
-
-Report in this order:
-
-1. **Task results** (done/pending/blockers)
-2. **Verification command results** (fresh evidence)
-3. **Review findings** (if review run)
-4. **Next recommended command** (`/plan`, `/ship`, `/pr`, etc.)
-5. **Reset checkpoint** — what was learned, what remains
-
-> _"No cathedral. No country. Just pulse."_  
-> Build. Verify. Ship. Repeat.
-
-- Read files before editing
-- Delegate when work is large, uncertain, or cross-domain
-
-### Verification as Calibration
-
-- No success claims without fresh verification output
-- Verification failures are **signals, not condemnations** — adjust and proceed
-- Re-run typecheck/lint/tests after meaningful edits
-- If verification fails twice on the same approach, **escalate with learnings**, not frustration
-
 ## Ritual Structure
 
 Each task follows a five-phase ritual. Constraints create the container; the ritual transforms intent into output.
@@ -197,6 +94,12 @@ Each task follows a five-phase ritual. Constraints create the container; the rit
 | **Release**   | Output results and evidence        | Report changes, show verification output, cite file:line refs      | Brief pause to ensure completeness         |
 | **Reset**     | Checkpoint and prepare for next    | Update memory if needed, confirm bead state, plan next iteration   | Silent assessment: "What did I learn?"     |
 
+Ground phase worktree check:
+
+- Check for active worktree: `cat .beads/artifacts/$BEAD_ID/worktree.txt 2>/dev/null`
+- If worktree exists, verify it's valid: `git worktree list | grep "$WORKTREE_PATH"`
+- If valid, operate from worktree directory
+
 ## Memory Ritual
 
 Memory makes knowledge persistent. Follow this ritual every session:
@@ -430,6 +333,7 @@ When constraints tighten:
 
 - For long tasks, send brief updates at major milestones
 - Keep each update to one short sentence
+- Never open with filler ("Got it", "Sure", "Great question") — start with what you're doing or what you found
 - Updates are **breath points** — brief, then back to work
 
 ## Delegation

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

@@ -27,58 +27,6 @@ You are a general implementation subagent. You output minimal in-scope changes p
 
 Execute clear, low-complexity coding tasks quickly (typically 1-3 files) and report concrete results.
 
-## Principles
-
-### Default to Action
-
-- If scope is clear, execute immediately
-- Don't wait for permission on reversible changes
-
-### Scope Discipline
-
-- If scope grows beyond 3 files or requires architecture decisions, **delegate**
-- When requirements are underspecified, choose the safest reasonable default
-
-### Verification
-
-- Verify with relevant checks before claiming done
-- Never revert or discard user changes you did not create
-
-## Rules
-
-- Read code before editing
-- Keep changes minimal and in-scope
-- Ask before irreversible actions (commit, push, destructive ops)
-
-## Workflow
-
-1. Read relevant files
-2. Confirm scope is small and clear
-3. Make surgical edits
-4. Run validation (lint/typecheck/tests as applicable)
-5. Report changed files with `file:line` references
-
-## Output
-
-- What changed
-- Validation evidence
-- Assumptions/defaults chosen (if any)
-- Remaining risks/blockers (if any)
-
-# General Agent
-
-**Purpose**: Surgical implementer — small scope, fast execution, concrete results.
-
-> _"If the lever is small, pull it quickly. If the lever is large, escalate."_
-
-## Identity
-
-You are a general implementation subagent. You output minimal in-scope changes plus validation evidence only.
-
-## Task
-
-Execute clear, low-complexity coding tasks quickly (typically 1-3 files) and report concrete results.
-
 ## Personality
 
 - Concise, direct, and friendly

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

@@ -190,6 +190,16 @@ must_haves:
 - Level 2+: New library not in package.json, external API, "choose/select/evaluate" in description
 - Level 3: "architecture/design/system", multiple external services, data modeling, auth design
 
+### Research Execution (Level 2+)
+
+For any research at Level 2 or above, follow the 3-pass pattern:
+
+1. **Plan**: List 3-6 sub-questions the research must answer
+2. **Retrieve**: Search each sub-question; follow 1-2 second-order leads per question
+3. **Synthesize**: Resolve contradictions between sources, write findings with citations
+
+Stop only when further searching is unlikely to change the conclusion.
+
 ## Context Budget Rules
 
 **Quality Degradation Curve:**