opencodekit 0.18.0 → 0.18.2

package/dist/template/.opencode/skill/writing-skills/references/claude-search-optimization.md

@@ -0,0 +1,140 @@
+# Claude Search Optimization (CSO)
+
+**Critical for discovery:** Future Claude needs to FIND your skill
+
+## 1. Rich Description Field
+
+**Purpose:** Claude reads description to decide which skills to load for a given task. Make it answer: "Should I read this skill right now?"
+
+**Format:** Start with "Use when..." to focus on triggering conditions, then explain what it does
+
+**Content:**
+
+- Use concrete triggers, symptoms, and situations that signal this skill applies
+- Describe the _problem_ (race conditions, inconsistent behavior) not _language-specific symptoms_ (setTimeout, sleep)
+- Keep triggers technology-agnostic unless the skill itself is technology-specific
+- If skill is technology-specific, make that explicit in the trigger
+- Write in third person (injected into system prompt)
+
+```yaml
+# ❌ BAD: Too abstract, vague, doesn't include when to use
+description: For async testing
+
+# ❌ BAD: First person
+description: I can help you with async tests when they're flaky
+
+# ❌ BAD: Mentions technology but skill isn't specific to it
+description: Use when tests use setTimeout/sleep and are flaky
+
+# ✅ GOOD: Starts with "Use when", describes problem, then what it does
+description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently - replaces arbitrary timeouts with condition polling for reliable async tests
+
+# ✅ GOOD: Technology-specific skill with explicit trigger
+description: Use when using React Router and handling authentication redirects - provides patterns for protected routes and auth state management
+```
+
+## 2. Keyword Coverage
+
+Use words Claude would search for:
+
+- Error messages: "Hook timed out", "ENOTEMPTY", "race condition"
+- Symptoms: "flaky", "hanging", "zombie", "pollution"
+- Synonyms: "timeout/hang/freeze", "cleanup/teardown/afterEach"
+- Tools: Actual commands, library names, file types
+
+## 3. Descriptive Naming
+
+**Use active voice, verb-first:**
+
+- ✅ `creating-skills` not `skill-creation`
+- ✅ `testing-skills-with-subagents` not `subagent-skill-testing`
+
+## 4. Token Efficiency (Critical)
+
+**Problem:** getting-started and frequently-referenced skills load into EVERY conversation. Every token counts.
+
+**Target word counts:**
+
+- getting-started workflows: <150 words each
+- Frequently-loaded skills: <200 words total
+- Other skills: <500 words (still be concise)
+
+**Techniques:**
+
+**Move details to tool help:**
+
+```bash
+# ❌ BAD: Document all flags in SKILL.md
+search-conversations supports --text, --both, --after DATE, --before DATE, --limit N
+
+# ✅ GOOD: Reference --help
+search-conversations supports multiple modes and filters. Run --help for details.
+```
+
+**Use cross-references:**
+
+```markdown
+# ❌ BAD: Repeat workflow details
+
+When searching, dispatch subagent with template...
+[20 lines of repeated instructions]
+
+# ✅ GOOD: Reference other skill
+
+Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.
+```
+
+**Compress examples:**
+
+```markdown
+# ❌ BAD: Verbose example (42 words)
+
+your human partner: "How did we handle authentication errors in React Router before?"
+You: I'll search past conversations for React Router authentication patterns.
+[Dispatch subagent with search query: "React Router authentication error handling 401"]
+
+# ✅ GOOD: Minimal example (20 words)
+
+Partner: "How did we handle auth errors in React Router?"
+You: Searching...
+[Dispatch subagent → synthesis]
+```
+
+**Eliminate redundancy:**
+
+- Don't repeat what's in cross-referenced skills
+- Don't explain what's obvious from command
+- Don't include multiple examples of same pattern
+
+**Verification:**
+
+```bash
+wc -w skills/path/SKILL.md
+# getting-started workflows: aim for <150 each
+# Other frequently-loaded: aim for <200 total
+```
+
+**Name by what you DO or core insight:**
+
+- ✅ `condition-based-waiting` > `async-test-helpers`
+- ✅ `using-skills` not `skill-usage`
+- ✅ `flatten-with-flags` > `data-structure-refactoring`
+- ✅ `root-cause-tracing` > `debugging-techniques`
+
+**Gerunds (-ing) work well for processes:**
+
+- `creating-skills`, `testing-skills`, `debugging-with-logs`
+- Active, describes the action you're taking
+
+## 4. Cross-Referencing Other Skills
+
+**When writing documentation that references other skills:**
+
+Use skill name only, with explicit requirement markers:
+
+- ✅ Good: `**REQUIRED SUB-SKILL:** Use skill({ name: "test-driven-development" })`
+- ✅ Good: `**REQUIRED BACKGROUND:** You MUST understand systematic-debugging`
+- ❌ Bad: `See skills/testing/test-driven-development` (unclear if required)
+- ❌ Bad: `@skills/testing/test-driven-development/SKILL.md` (force-loads, burns context)
+
+**Why no @ links:** `@` syntax force-loads files immediately, consuming 200k+ context before you need them.

package/dist/template/.opencode/skill/writing-skills/references/discovery-workflow.md

@@ -0,0 +1,11 @@
+# Discovery Workflow
+
+How future Claude finds your skill:
+
+1. **Encounters problem** ("tests are flaky")
+2. **Finds SKILL** (description matches)
+3. **Scans overview** (is this relevant?)
+4. **Reads patterns** (quick reference table)
+5. **Loads example** (only when implementing)
+
+**Optimize for this flow** - put searchable terms early and often.

package/dist/template/.opencode/skill/writing-skills/references/file-organization.md

@@ -0,0 +1,32 @@
+# File Organization
+
+## Self-Contained Skill
+
+```
+defense-in-depth/
+  SKILL.md    # Everything inline
+```
+
+When: All content fits, no heavy reference needed
+
+## Skill with Reusable Tool
+
+```
+condition-based-waiting/
+  SKILL.md    # Overview + patterns
+  example.ts  # Working helpers to adapt
+```
+
+When: Tool is reusable code, not just narrative
+
+## Skill with Heavy Reference
+
+```
+pptx/
+  SKILL.md       # Overview + workflows
+  pptxgenjs.md   # 600 lines API reference
+  ooxml.md       # 500 lines XML structure
+  scripts/       # Executable tools
+```
+
+When: Reference material too large for inline

package/dist/template/.opencode/skill/writing-skills/references/flowcharts-and-examples.md

@@ -0,0 +1,57 @@
+# Flowchart Usage and Code Examples
+
+## Flowchart Usage
+
+```dot
+digraph when_flowchart {
+    "Need to show information?" [shape=diamond];
+    "Decision where I might go wrong?" [shape=diamond];
+    "Use markdown" [shape=box];
+    "Small inline flowchart" [shape=box];
+
+    "Need to show information?" -> "Decision where I might go wrong?" [label="yes"];
+    "Decision where I might go wrong?" -> "Small inline flowchart" [label="yes"];
+    "Decision where I might go wrong?" -> "Use markdown" [label="no"];
+}
+```
+
+**Use flowcharts ONLY for:**
+
+- Non-obvious decision points
+- Process loops where you might stop too early
+- "When to use A vs B" decisions
+
+**Never use flowcharts for:**
+
+- Reference material → Tables, lists
+- Code examples → Markdown blocks
+- Linear instructions → Numbered lists
+- Labels without semantic meaning (step1, helper2)
+
+See @graphviz-conventions.dot for graphviz style rules.
+
+## Code Examples
+
+**One excellent example beats many mediocre ones**
+
+Choose most relevant language:
+
+- Testing techniques → TypeScript/JavaScript
+- System debugging → Shell/Python
+- Data processing → Python
+
+**Good example:**
+
+- Complete and runnable
+- Well-commented explaining WHY
+- From real scenario
+- Shows pattern clearly
+- Ready to adapt (not generic template)
+
+**Don't:**
+
+- Implement in 5+ languages
+- Create fill-in-the-blank templates
+- Write contrived examples
+
+You're good at porting - one great example is enough.

package/dist/template/.opencode/skill/writing-skills/references/rationalization-hardening.md

@@ -0,0 +1,75 @@
+# Bulletproofing Skills Against Rationalization
+
+Skills that enforce discipline (like TDD) need to resist rationalization. Agents are smart and will find loopholes when under pressure.
+
+**Psychology note:** Understanding WHY persuasion techniques work helps you apply them systematically. See persuasion-principles.md for research foundation (Cialdini, 2021; Meincke et al., 2025) on authority, commitment, scarcity, social proof, and unity principles.
+
+## Close Every Loophole Explicitly
+
+Don't just state the rule - forbid specific workarounds:
+
+<Bad>
+```markdown
+Write code before test? Delete it.
+```
+</Bad>
+
+<Good>
+```markdown
+Write code before test? Delete it. Start over.
+
+**No exceptions:**
+
+- Don't keep it as "reference"
+- Don't "adapt" it while writing tests
+- Don't look at it
+- Delete means delete
+
+````
+</Good>
+
+## Address "Spirit vs Letter" Arguments
+
+Add foundational principle early:
+
+```markdown
+**Violating the letter of the rules is violating the spirit of the rules.**
+````
+
+This cuts off entire class of "I'm following the spirit" rationalizations.
+
+## Build Rationalization Table
+
+Capture rationalizations from baseline testing (see Testing section below). Every excuse agents make goes in the table:
+
+```markdown
+| Excuse                           | Reality                                                                 |
+| -------------------------------- | ----------------------------------------------------------------------- |
+| "Too simple to test"             | Simple code breaks. Test takes 30 seconds.                              |
+| "I'll test after"                | Tests passing immediately prove nothing.                                |
+| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
+```
+
+## Create Red Flags List
+
+Make it easy for agents to self-check when rationalizing:
+
+```markdown
+## Red Flags - STOP and Start Over
+
+- Code before test
+- "I already manually tested it"
+- "Tests after achieve the same purpose"
+- "It's about spirit not ritual"
+- "This is different because..."
+
+**All of these mean: Delete code. Start over with TDD.**
+```
+
+## Update CSO for Violation Symptoms
+
+Add to description: symptoms of when you're ABOUT to violate the rule:
+
+```yaml
+description: use when implementing any feature or bugfix, before writing implementation code
+```

package/dist/template/.opencode/skill/writing-skills/references/testing-skill-types.md

@@ -0,0 +1,52 @@
+# Testing All Skill Types
+
+Different skill types need different test approaches:
+
+## Discipline-Enforcing Skills (rules/requirements)
+
+**Examples:** TDD, verification-before-completion, designing-before-coding
+
+**Test with:**
+
+- Academic questions: Do they understand the rules?
+- Pressure scenarios: Do they comply under stress?
+- Multiple pressures combined: time + sunk cost + exhaustion
+- Identify rationalizations and add explicit counters
+
+**Success criteria:** Agent follows rule under maximum pressure
+
+## Technique Skills (how-to guides)
+
+**Examples:** condition-based-waiting, root-cause-tracing, defensive-programming
+
+**Test with:**
+
+- Application scenarios: Can they apply the technique correctly?
+- Variation scenarios: Do they handle edge cases?
+- Missing information tests: Do instructions have gaps?
+
+**Success criteria:** Agent successfully applies technique to new scenario
+
+## Pattern Skills (mental models)
+
+**Examples:** reducing-complexity, information-hiding concepts
+
+**Test with:**
+
+- Recognition scenarios: Do they recognize when pattern applies?
+- Application scenarios: Can they use the mental model?
+- Counter-examples: Do they know when NOT to apply?
+
+**Success criteria:** Agent correctly identifies when/how to apply pattern
+
+## Reference Skills (documentation/APIs)
+
+**Examples:** API documentation, command references, library guides
+
+**Test with:**
+
+- Retrieval scenarios: Can they find the right information?
+- Application scenarios: Can they use what they found correctly?
+- Gap testing: Are common use cases covered?
+
+**Success criteria:** Agent finds and correctly applies reference information

package/package.json

@@ -1,8 +1,15 @@
 {
 	"name": "opencodekit",
-	"version": "0.18.0",
+	"version": "0.18.2",
 	"description": "CLI tool for bootstrapping and managing OpenCodeKit projects",
-	"keywords": ["agents", "cli", "mcp", "opencode", "opencodekit", "template"],
+	"keywords": [
+		"agents",
+		"cli",
+		"mcp",
+		"opencode",
+		"opencodekit",
+		"template"
+	],
 	"license": "MIT",
 	"author": "OpenCodeKit",
 	"repository": {
@@ -12,7 +19,10 @@
 	"bin": {
 		"ock": "dist/index.js"
 	},
-	"files": ["dist", "README.md"],
+	"files": [
+		"dist",
+		"README.md"
+	],
 	"type": "module",
 	"publishConfig": {
 		"access": "public",
@@ -26,7 +36,8 @@
 		"test:watch": "vitest",
 		"validate:command-doc": "tsx src/validation/command-doc.ts --check",
 		"validate:docs-drift": "tsx src/validation/docs-drift.ts --check",
-		"validate:governance": "npm run validate:command-doc && npm run validate:docs-drift",
+		"validate:skill-lint": "tsx src/validation/skill-lint.ts --check",
+		"validate:governance": "npm run validate:command-doc && npm run validate:docs-drift && npm run validate:skill-lint",
 		"lint": "oxlint .",
 		"lint:fix": "oxlint --fix .",
 		"format": "oxfmt",

package/dist/template/.opencode/plugin/compaction.ts

@@ -1,190 +0,0 @@
-/**
- * Session Continuity Plugin (compaction-time context injection)
- *
- * Purpose:
- * - Provide compact, bounded state needed to resume work after compaction.
- * - Keep injected prompt guidance minimal and deterministic.
- *
- * Non-goals:
- * - Replace DCP policy/rules management.
- * - Inject large free-form manuals into the prompt.
- */
-
-import { Database } from "bun:sqlite";
-import { readFile, readdir, stat } from "node:fs/promises";
-import path from "node:path";
-import type { Plugin } from "@opencode-ai/plugin";
-
-const MAX_SESSION_CONTEXT_CHARS = 3000;
-const MAX_PROJECT_FILES = 3;
-const MAX_PROJECT_FILE_CHARS = 900;
-const MAX_HANDOFF_CHARS = 2500;
-const MAX_BEADS = 8;
-const MAX_COMBINED_CONTEXT_CHARS = 9000;
-
-interface BeadRow {
-	id: string;
-	title: string;
-}
-
-function truncate(text: string, maxChars: number): string {
-	if (text.length <= maxChars) return text;
-	return `${text.slice(0, maxChars)}\n...[truncated]`;
-}
-
-async function safeReadFile(filePath: string): Promise<string> {
-	try {
-		return await readFile(filePath, "utf-8");
-	} catch {
-		return "";
-	}
-}
-
-function renderSection(title: string, body: string): string {
-	if (!body.trim()) return "";
-	return `## ${title}\n${body.trim()}`;
-}
-
-async function readProjectMemoryContext(memoryDir: string): Promise<string> {
-	const projectDir = path.join(memoryDir, "project");
-	let names: string[] = [];
-	try {
-		names = (await readdir(projectDir))
-			.filter((name) => name.endsWith(".md"))
-			.sort()
-			.slice(0, MAX_PROJECT_FILES);
-	} catch {
-		return "";
-	}
-
-	const chunks: string[] = [];
-	for (const name of names) {
-		const fullPath = path.join(projectDir, name);
-		const content = (await safeReadFile(fullPath)).trim();
-		if (!content) continue;
-		chunks.push(
-			`### ${name.replace(/\.md$/, "")}\n${truncate(content, MAX_PROJECT_FILE_CHARS)}`,
-		);
-	}
-
-	return chunks.join("\n\n");
-}
-
-async function readLatestHandoff(handoffDir: string): Promise<string> {
-	let names: string[] = [];
-	try {
-		names = (await readdir(handoffDir)).filter((name) => name.endsWith(".md"));
-	} catch {
-		return "";
-	}
-
-	if (names.length === 0) return "";
-
-	const withMtime = await Promise.all(
-		names.map(async (name) => {
-			const fullPath = path.join(handoffDir, name);
-			try {
-				const info = await stat(fullPath);
-				return { name, fullPath, mtimeMs: info.mtimeMs };
-			} catch {
-				return { name, fullPath, mtimeMs: 0 };
-			}
-		}),
-	);
-
-	withMtime.sort((a, b) => b.mtimeMs - a.mtimeMs);
-	const latest = withMtime[0];
-	const content = (await safeReadFile(latest.fullPath)).trim();
-	if (!content) return "";
-
-	return `Source: ${latest.name}\n${truncate(content, MAX_HANDOFF_CHARS)}`;
-}
-
-/**
- * Read in-progress beads directly from SQLite database.
- * Cross-platform alternative to shell command execution.
- */
-function readInProgressBeads(directory: string): string {
-	const dbPath = path.join(directory, ".beads", "beads.db");
-	let db: Database | undefined;
-
-	try {
-		db = new Database(dbPath, { readonly: true });
-
-		const rows = db
-			.query<BeadRow, [number]>(
-				"SELECT id, title FROM issues WHERE status = 'in_progress' ORDER BY updated_at DESC LIMIT ?",
-			)
-			.all(MAX_BEADS);
-
-		if (rows.length === 0) return "";
-
-		return rows.map((row) => `- ${row.id}: ${row.title}`).join("\n");
-	} catch {
-		// Database may not exist, be locked, or have different schema
-		// Return empty string to allow graceful degradation
-		return "";
-	} finally {
-		db?.close();
-	}
-}
-
-export const CompactionPlugin: Plugin = async ({ directory }) => {
-	const memoryDir = path.join(directory, ".opencode", "memory");
-	const handoffDir = path.join(memoryDir, "handoffs");
-
-	return {
-		"experimental.session.compacting": async (_input, output) => {
-			const sessionContext = truncate(
-				(await safeReadFile(path.join(memoryDir, "session-context.md"))).trim(),
-				MAX_SESSION_CONTEXT_CHARS,
-			);
-
-			const [projectContext, handoffContext] = await Promise.all([
-				readProjectMemoryContext(memoryDir),
-				readLatestHandoff(handoffDir),
-			]);
-
-			// Synchronous SQLite query - no async/await needed
-			const beadsContext = readInProgressBeads(directory);
-
-			const combined = [
-				renderSection("Session Continuity", sessionContext),
-				renderSection("Active Beads", beadsContext),
-				renderSection("Previous Handoff", handoffContext),
-				renderSection("Project Memory", projectContext),
-			]
-				.filter(Boolean)
-				.join("\n\n");
-
-			if (combined) {
-				output.context.push(
-					`## Session Context\n${truncate(combined, MAX_COMBINED_CONTEXT_CHARS)}\n`,
-				);
-			}
-
-			output.prompt = `${output.prompt}
-
-<compaction_task>
-Summarize conversation state for reliable continuation after compaction.
-</compaction_task>
-
-<compaction_rules>
-- Preserve exact IDs, file paths, and unresolved constraints.
-- Distinguish completed work from current in-progress work.
-- Keep summary concise and execution-focused.
-- If critical context is missing, state uncertainty explicitly.
-</compaction_rules>
-
-<compaction_output>
-Include:
-- What was done
-- What is being worked on now
-- Files currently in play
-- Next actions
-- Persistent user constraints/preferences
-</compaction_output>
-`;
-		},
-	};
-};