opencode-starterkit 1.0.1

package/baseline/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/baseline/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/baseline/tool/context7.ts

@@ -0,0 +1,191 @@
+import { tool } from "@opencode-ai/plugin";
+
+// Context7 API v2 - https://context7.com/docs/api-guide
+const CONTEXT7_API = "https://context7.com/api/v2";
+
+interface LibraryInfo {
+	id: string;
+	title: string;
+	description?: string;
+	totalSnippets?: number;
+	trustScore?: number;
+	benchmarkScore?: number;
+	versions?: string[];
+}
+
+interface SearchResponse {
+	results: LibraryInfo[];
+}
+
+/**
+ * Consolidated Context7 documentation lookup tool.
+ * Operations: resolve (find library ID), query (get docs)
+ */
+export default tool({
+	description: `Context7 documentation lookup: resolve library IDs and query docs. Replaces manual doc searching and outdated API guessing — use this for all library documentation needs.
+
+WHEN: Looking up library APIs, checking function signatures, finding usage examples.
+SKIP: Searching your own codebase (use grep/LSP), general web research (use websearch).
+
+Common mistakes:
+- DON'T search for internal project code (use grep/tilth instead)
+- DON'T guess library versions — always resolve first, then query
+- DON'T use for general web research (use websearch instead)
+
+Operations:
+- "resolve": Find library ID from name (e.g., "react" → "/reactjs/react.dev")
+- "query": Get documentation for a library topic
+
+Example:
+context7({ operation: "resolve", libraryName: "react" })
+context7({ operation: "query", libraryId: "/reactjs/react.dev", topic: "hooks" })`,
+	args: {
+		operation: tool.schema
+			.string()
+			.optional()
+			.default("resolve")
+			.describe("Operation: resolve or query"),
+		libraryName: tool.schema
+			.string()
+			.optional()
+			.describe("Library name to resolve (for resolve operation)"),
+		libraryId: tool.schema
+			.string()
+			.optional()
+			.describe("Library ID from resolve (for query operation)"),
+		topic: tool.schema
+			.string()
+			.optional()
+			.describe("Documentation topic (for query operation)"),
+	},
+	execute: async (args: {
+		operation?: string;
+		libraryName?: string;
+		libraryId?: string;
+		topic?: string;
+	}) => {
+		const operation = args.operation || "resolve";
+
+		// Add API key if available
+		const apiKey = process.env.CONTEXT7_API_KEY;
+		const headers: HeadersInit = {
+			Accept: "application/json",
+			"User-Agent": "OpenCode/1.0",
+		};
+
+		if (apiKey) {
+			headers.Authorization = `Bearer ${apiKey}`;
+		}
+
+		// ===== RESOLVE =====
+		if (operation === "resolve") {
+			const { libraryName } = args;
+
+			if (!libraryName || libraryName.trim() === "") {
+				return "Error: libraryName is required for resolve operation";
+			}
+
+			try {
+				const url = new URL(`${CONTEXT7_API}/libs/search`);
+				url.searchParams.set("libraryName", libraryName);
+				url.searchParams.set("query", "documentation");
+
+				const response = await fetch(url.toString(), { headers });
+
+				if (!response.ok) {
+					if (response.status === 401) {
+						return `Error: Invalid CONTEXT7_API_KEY. Get a free key at https://context7.com/dashboard`;
+					}
+					if (response.status === 429) {
+						return `Error: Rate limit exceeded. Get a free API key at https://context7.com/dashboard for higher limits.`;
+					}
+					return `Error: Context7 API returned ${response.status}`;
+				}
+
+				const data = (await response.json()) as SearchResponse;
+				const libraries = data.results || [];
+
+				if (!libraries || libraries.length === 0) {
+					return `No libraries found matching: ${libraryName}\n\nTry:\n- Different library name\n- Check spelling\n- Use official package name`;
+				}
+
+				const formatted = libraries
+					.slice(0, 5)
+					.map((lib, i) => {
+						const desc = lib.description
+							? `\n   ${lib.description.slice(0, 100)}...`
+							: "";
+						const snippets = lib.totalSnippets
+							? ` (${lib.totalSnippets} snippets)`
+							: "";
+						const score = lib.benchmarkScore
+							? ` [score: ${lib.benchmarkScore}]`
+							: "";
+						return `${i + 1}. **${lib.title}** → \`${lib.id}\`${snippets}${score}${desc}`;
+					})
+					.join("\n\n");
+
+				return `Found ${libraries.length} libraries matching "${libraryName}":
+
+${formatted}
+
+**Next step**: Use \`context7({ operation: "query", libraryId: "${libraries[0].id}", topic: "your topic" })\` to fetch documentation.`;
+			} catch (error: unknown) {
+				const message = error instanceof Error ? error.message : String(error);
+				return `Error resolving library: ${message}`;
+			}
+		}
+
+		// ===== QUERY =====
+		if (operation === "query") {
+			const { libraryId, topic } = args;
+
+			if (!libraryId || libraryId.trim() === "") {
+				return 'Error: libraryId is required (use operation: "resolve" first)';
+			}
+
+			if (!topic || topic.trim() === "") {
+				return "Error: topic is required (e.g., 'hooks', 'setup', 'API reference')";
+			}
+
+			try {
+				const url = new URL(`${CONTEXT7_API}/context`);
+				url.searchParams.set("libraryId", libraryId);
+				url.searchParams.set("query", topic);
+
+				const queryHeaders = { ...headers, Accept: "text/plain" };
+				const response = await fetch(url.toString(), {
+					headers: queryHeaders,
+				});
+
+				if (!response.ok) {
+					if (response.status === 401) {
+						return `Error: Invalid CONTEXT7_API_KEY. Get a free key at https://context7.com/dashboard`;
+					}
+					if (response.status === 404) {
+						return `Error: Library not found: ${libraryId}\n\nUse operation: "resolve" first to find the correct ID.`;
+					}
+					if (response.status === 429) {
+						return `Error: Rate limit exceeded. Get a free API key at https://context7.com/dashboard for higher limits.`;
+					}
+					return `Error: Context7 API returned ${response.status}`;
+				}
+
+				const content = await response.text();
+
+				if (!content || content.trim() === "") {
+					return `No documentation found for "${topic}" in ${libraryId}.\n\nTry:\n- Simpler terms (e.g., "useState" instead of "state management")\n- Different topic spelling\n- Broader topics like "API reference" or "getting started"`;
+				}
+
+				return `# Documentation: ${topic} (${libraryId})
+
+${content}`;
+			} catch (error: unknown) {
+				const message = error instanceof Error ? error.message : String(error);
+				return `Error querying documentation: ${message}`;
+			}
+		}
+
+		return `Unknown operation: ${operation}. Use: resolve, query`;
+	},
+});

package/baseline/tool/grepsearch.ts

@@ -0,0 +1,143 @@
+import { tool } from "@opencode-ai/plugin";
+
+const GREP_APP_API = "https://grep.app/api/search";
+
+interface SearchResult {
+	repo: string;
+	path: string;
+	content: { snippet: string };
+	total_matches: string;
+}
+
+interface GrepResponse {
+	hits: { hits: SearchResult[] };
+	time: number;
+}
+
+export default tool({
+	description: `Search real-world code examples from GitHub repositories via grep.app. Replaces asking "how do others use X?" — use this for finding production patterns and real-world API usage.
+
+WHEN: Implementing unfamiliar APIs, looking for production patterns, understanding library integrations.
+SKIP: Searching your own codebase (use grep/tilth), looking up docs (use context7), general research (use websearch).
+
+Common mistakes:
+- DON'T search for keywords like "react tutorial" — search for literal code: "useState("
+- DON'T use without language filter when searching common patterns
+- DON'T ignore the repo filter when you know which project to search
+
+Use when:
+- Implementing unfamiliar APIs - see how others use a library
+- Looking for production patterns - find real-world examples
+- Understanding library integrations - see how things work together
+
+IMPORTANT: Search for **literal code patterns**, not keywords:
+✅ Good: "useState(", "import React from", "async function"
+❌ Bad: "react tutorial", "best practices", "how to use"
+
+Examples:
+  grepsearch({ query: "getServerSession", language: "TypeScript" })
+  grepsearch({ query: "CORS(", language: "Python", repo: "flask" })
+  grepsearch({ query: "export async function POST", path: "route.ts" })
+`,
+	args: {
+		query: tool.schema
+			.string()
+			.describe("Code pattern to search for (literal text)"),
+		language: tool.schema
+			.string()
+			.optional()
+			.describe("Filter by language: TypeScript, TSX, Python, Go, Rust, etc."),
+		repo: tool.schema
+			.string()
+			.optional()
+			.describe("Filter by repo: 'owner/repo' or partial match"),
+		path: tool.schema
+			.string()
+			.optional()
+			.describe("Filter by file path: 'src/', '.test.ts', etc."),
+		limit: tool.schema
+			.number()
+			.optional()
+			.describe("Max results to return (default: 10, max: 20)"),
+	},
+	execute: async (args) => {
+		const { query, language, repo, path, limit = 10 } = args;
+
+		if (!query || query.trim() === "") {
+			return "Error: query is required";
+		}
+
+		// Build URL with proper filter parameters
+		// grep.app uses filter[lang][0]=TypeScript format, NOT inline lang:TypeScript
+		const url = new URL(GREP_APP_API);
+		url.searchParams.set("q", query);
+
+		// Add language filter (grep.app uses filter[lang][0] format)
+		if (language) {
+			url.searchParams.set("filter[lang][0]", language);
+		}
+
+		// Add repo filter
+		if (repo) {
+			url.searchParams.set("filter[repo][0]", repo);
+		}
+
+		// Add path filter
+		if (path) {
+			url.searchParams.set("filter[path][0]", path);
+		}
+
+		try {
+			const response = await fetch(url.toString(), {
+				headers: {
+					Accept: "application/json",
+					"User-Agent": "OpenCode/1.0",
+				},
+			});
+
+			if (!response.ok) {
+				return `Error: grep.app API returned ${response.status}`;
+			}
+
+			const data = (await response.json()) as GrepResponse;
+
+			if (!data.hits?.hits?.length) {
+				return `No results found for: ${query}${language ? ` (${language})` : ""}`;
+			}
+
+			const maxResults = Math.min(limit, 20);
+			const results = data.hits.hits.slice(0, maxResults);
+
+			const formatted = results.map((hit, i) => {
+				const repoName = hit.repo || "unknown";
+				const filePath = hit.path || "unknown";
+				const snippet = hit.content?.snippet || "";
+
+				// Clean up HTML from snippet and extract text
+				const cleanCode = snippet
+					.replace(/<[^>]*>/g, "") // Remove HTML tags
+					.replace(/&lt;/g, "<")
+					.replace(/&gt;/g, ">")
+					.replace(/&amp;/g, "&")
+					.replace(/&quot;/g, '"')
+					.split("\n")
+					.slice(0, 8)
+					.join("\n")
+					.trim();
+
+				return `## ${i + 1}. ${repoName}
+**File**: ${filePath}
+\`\`\`
+${cleanCode}
+\`\`\``;
+			});
+
+			return `Found ${data.hits.hits.length} results (showing ${results.length}) in ${data.time}ms:
+
+${formatted.join("\n\n")}`;
+		} catch (error: unknown) {
+			const message = error instanceof Error ? error.message : String(error);
+			return `Error searching grep.app: ${message}`;
+		}
+	},
+});

package/baseline/tsconfig.json

@@ -0,0 +1,21 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "ESNext",
+		"moduleResolution": "bundler",
+		"allowSyntheticDefaultImports": true,
+		"esModuleInterop": true,
+		"allowJs": true,
+		"strict": false,
+		"noEmit": true,
+		"declaration": true,
+		"outDir": "./dist",
+		"rootDir": "./",
+		"skipLibCheck": true,
+		"forceConsistentCasingInFileNames": true,
+		"resolveJsonModule": true,
+		"types": ["node", "bun-types"]
+	},
+	"include": ["plugin/**/*.ts", "tool/**/*.ts", "agent/**/*.ts", "*.ts"],
+	"exclude": ["node_modules", "dist", "**/*.js", "**/*.test.ts"]
+}

package/baseline/tui.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "keybinds": {
+    "command_list": ";",
+    "leader": "`",
+    "session_child_cycle": "ctrl+alt+right",
+    "session_child_cycle_reverse": "ctrl+alt+left",
+    "session_compact": "ctrl+k"
+  },
+  "scroll_speed": 3,
+  "scroll_acceleration": {
+    "enabled": true
+  },
+  "diff_style": "auto"
+}

package/bin/mrc-opc.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { installGlobal } from '../src/install-global.mjs'
+import { printHelp, parseArgs } from '../src/cli.mjs'
+
+async function main() {
+  const cli = parseArgs(process.argv.slice(2))
+
+  if (cli.help || !cli.command) {
+    printHelp('mrc-opc')
+    process.exit(0)
+  }
+
+  if (cli.command === 'install') {
+    await installGlobal({ cwd: process.cwd(), args: cli.args })
+    process.exit(0)
+  }
+
+  printHelp('mrc-opc')
+  process.exit(1)
+}
+
+main().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

package/bin/ocp.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { installProjectOverlay } from '../src/install-project.mjs'
+import { printHelp, parseArgs } from '../src/cli.mjs'
+
+async function main() {
+  const cli = parseArgs(process.argv.slice(2))
+
+  if (cli.help || !cli.command) {
+    printHelp('ocp')
+    process.exit(0)
+  }
+
+  if (cli.command === 'install') {
+    await installProjectOverlay({ cwd: process.cwd(), args: cli.args, options: cli.options })
+    process.exit(0)
+  }
+
+  printHelp('ocp')
+  process.exit(1)
+}
+
+main().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

package/bin/opc.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { installProjectOverlay } from '../src/install-project.mjs'
+import { printHelp, parseArgs } from '../src/cli.mjs'
+
+async function main() {
+  const cli = parseArgs(process.argv.slice(2))
+
+  if (cli.help || !cli.command) {
+    printHelp('opc')
+    process.exit(0)
+  }
+
+  if (cli.command === 'install') {
+    await installProjectOverlay({ cwd: process.cwd(), args: cli.args, options: cli.options })
+    process.exit(0)
+  }
+
+  printHelp('opc')
+  process.exit(1)
+}
+
+main().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

package/bin/opencode-starterkit.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { installGlobal } from '../src/install-global.mjs'
+import { printHelp, parseArgs } from '../src/cli.mjs'
+
+async function main() {
+  const cli = parseArgs(process.argv.slice(2))
+
+  if (cli.help || !cli.command) {
+    printHelp('opencode-starterkit')
+    process.exit(0)
+  }
+
+  if (cli.command === 'install') {
+    await installGlobal({ cwd: process.cwd(), args: cli.args })
+    process.exit(0)
+  }
+
+  printHelp('opencode-starterkit')
+  process.exit(1)
+}
+
+main().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

package/docs/reports/2026-03-18-memory-db-architecture-note.md

@@ -0,0 +1,47 @@
+# Memory DB Architecture Note
+
+## Decision
+
+`mrc-opc` will use a **shared global baseline** for OpenCode operating assets, while keeping `memory.db*` as **per-project runtime state**.
+
+## Rationale
+
+Current VAT plugin code opens the memory DB from:
+
+```ts
+path.join(process.cwd(), '.opencode/memory.db')
+```
+
+That means the operational memory database is intentionally bound to the active repo working directory.
+
+## Policy
+
+### Global baseline
+Global baseline should contain:
+- plugin code
+- skills
+- commands
+- agent templates
+- config defaults
+- install/migration helpers
+
+### Project thin overlay
+Thin overlay should contain:
+- `.opencode/opencode.json`
+- `.opencode/memory/project/*`
+- repo-specific overrides/hooks only when necessary
+
+### Per-project runtime state
+Do not globalize these:
+- `.opencode/memory.db`
+- `.opencode/memory.db-shm`
+- `.opencode/memory.db-wal`
+
+These files must remain project-local runtime state.
+They should not be committed as template payload, but each project may generate them locally during runtime or install bootstrap.
+
+## Installer implication
+
+- `npx mrc-opc install` installs shared global baseline only
+- `opc install` creates the thin overlay for the current repo
+- project runtime may initialize `.opencode/memory.db` lazily on first use, or `opc install` can optionally pre-create an empty DB scaffold if needed