opencodekit 0.21.10 → 0.22.0

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

@@ -0,0 +1,56 @@
+---
+description: Debug and fix a bug or failing test
+argument-hint: "<description of bug or error>"
+agent: build
+---
+
+# Fix: $ARGUMENTS
+
+Systematically debug and fix the reported issue.
+
+## Load Skills
+
+```typescript
+skill({ name: "systematic-debugging" });
+skill({ name: "root-cause-tracing" });
+skill({ name: "verification-before-completion" });
+```
+
+## Process
+
+### Phase 1: Reproduce
+
+```bash
+# Reproduce the issue with the exact steps or command
+```
+
+### Phase 2: Isolate
+
+- Search for the error message or symptom in the codebase
+- Trace the execution path to find the root cause
+- Read the 2-4 most relevant files
+- Distinguish symptom from root cause
+
+### Phase 3: Fix
+
+- Apply the minimal fix for the root cause
+- Do not add speculative guards, tolerant readers, or defensive copies
+- Prefer making the bad state impossible over handling all bad states
+
+### Phase 4: Verify
+
+```bash
+npm run typecheck
+npm run lint
+npm test            # or vitest relevant test
+```
+
+If verification fails twice on the same approach, escalate with learnings.
+
+## Output
+
+Report:
+1. Root cause (with file:line)
+2. Fix applied
+3. Verification results
+4. What else was considered and rejected

package/dist/template/.opencode/command/improve-architecture.md

@@ -0,0 +1,55 @@
+---
+description: Proactive architecture health check — find shallow modules, propose deep-module redesigns
+argument-hint: "[path|module|'all'] [--scope surface|deep]"
+agent: review
+---
+
+# Improve Architecture: $ARGUMENTS
+
+Proactive architecture health check. Find shallow modules and propose deep-module redesigns.
+
+## Load Skills
+
+```typescript
+skill({ name: "deep-module-design" });
+skill({ name: "verification-before-completion" });
+```
+
+## Architecture Check
+
+Apply Ousterhout's deep module principles:
+- **Small interface** — does this module expose more than it should?
+- **Information hiding** — are implementation details leaking?
+- **Pull complexity downward** — are callers doing work the module should own?
+
+## Process
+
+### Phase 1: Scan
+
+If path given, focus on that directory. If `all`, scan the full project.
+
+For each module, assess:
+- Lines of interface vs lines of implementation
+- Number of callers and how they use it
+- What knowledge is embedded but not encapsulated
+- What would break if the module were redesigned
+
+### Phase 2: Propose
+
+For each finding:
+
+| Module | Issue | Proposed Redesign | Effort | Risk |
+|---|---|---|---|---|
+| path/to/module | Shallow interface exposing internals | Encapsulate behind 3 functions | M | Low |
+
+### Phase 3: Prioritize
+
+Rank proposals by impact/effort ratio. Recommend top 1-3 changes worth making.
+
+## Output
+
+Report:
+1. Modules reviewed
+2. Findings (current issue, proposed redesign, effort, risk)
+3. Top recommendations
+4. Quick wins (S-effort changes)

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

@@ -1,31 +1,49 @@
 ---
-description: Initialize core project setup (AGENTS.md + tech-stack detection only)
-argument-hint: "[--deep]"
+description: Initialize project setup — AGENTS.md, planning context, user profile, and tech stack
+argument-hint: "[--deep] [--context|--user|--all]"
 agent: build
 ---
 
 # Init: $ARGUMENTS
 
-Core project setup. Creates AGENTS.md and detects tech stack. Run once per project.
+Initialize project setup. Run once per project. Supports three modes via argument flags.
 
-> **Next steps:** `/init-user` for personalization, `/init-context` for GSD planning workflow
+> **Next step for fresh projects:** `/plan` to create first implementation plan.  
+> **Next step for brownfield:** `/review-codebase` for deep codebase analysis.
 
 ## Load Skills
 
 ```typescript
 skill({ name: "index-knowledge" });
+skill({ name: "context-initialization" });
+skill({ name: "brainstorming" });
+skill({ name: "verification-before-completion" });
+skill({ name: "swarm-coordination" }); // For --brownfield analysis
 ```
 
-## Options
+## Parse Arguments
 
-| Argument | Default | Description                               |
-| -------- | ------- | ----------------------------------------- |
-| `--deep` | false   | Comprehensive research (~100+ tool calls) |
+| Argument | Default | Description |
+|---|---|---|
+| `--deep` | false | Comprehensive research for AGENTS.md (~100+ tool calls) |
+| `--context` | false | Init planning context (roadmap, state) |
+| `--user` | false | Init user profile |
+| `--all` | false | Full init: AGENTS.md + context + user profile |
 
-## Phase 1: Detect Project
+**Mode rules:**
+- No flags (default): Core project setup — AGENTS.md + tech stack only
+- `--context`: Planning context (roadmap.md, state.md)
+- `--user`: User profile (user.md)
+- `--all`: Everything
+- `--deep` applies to AGENTS.md generation only
 
-Detect and validate:
+---
+
+## Mode 1: Core Setup (Default)
 
+### Phase 1: Detect Project
+
+Detect and validate:
 - Package manager and dependencies (with versions)
 - Build, test, lint, dev commands — **validate each actually works**
 - CI/CD configuration
@@ -34,82 +52,84 @@ Detect and validate:
 
 With `--deep`: Also analyze git history, source patterns, subsystem candidates.
 
-## Phase 2: Preview Detection
+### Phase 2: Preview Detection
 
-After detecting project, show summary and ask for confirmation:
+Show detected summary and ask for confirmation before writing.
 
-```typescript
-question({
-  questions: [
-    {
-      header: "Preview",
-      question: `Detected: ${detectedTechStack}. Create AGENTS.md?`,
-      options: [
-        { label: "Yes, create it (Recommended)" },
-        { label: "Show me what you'll write first" },
-        { label: "Cancel" },
-      ],
-    },
-  ],
-});
-```
+### Phase 3: Create AGENTS.md
+
+Create `./AGENTS.md` — target <60 lines (max 150). Follow `index-knowledge` format:
+- Tech stack with versions, file structure, validated commands
+- Code example from actual codebase
+- Testing conventions, boundaries, gotchas
+
+**Principles:** Examples > explanations. Pointers > copies. If AGENTS.md exists, improve it — don't overwrite blindly.
 
-**If "Show me":** Display detected values without writing files, then ask again.
+### Phase 4: Create tech-stack.md
 
-## Phase 3: Create AGENTS.md
+Write detected values to `.opencode/memory/project/tech-stack.md`. Persist with memory update.
 
-Create `./AGENTS.md` — **target <60 lines** (max 150). Follow the `index-knowledge` skill format:
+---
+
+## Mode 2: Planning Context (`--context`)
+
+Initialize project planning context with roadmap and state files.
 
-- Tech stack with versions
-- File structure
-- Commands (validated)
-- Code example from actual codebase (5-10 lines)
-- Testing conventions
-- Boundaries (always/ask-first/never)
-- Gotchas
+### Phase 1: Discovery
 
-**Principles**: Examples > explanations. Pointers > copies. If AGENTS.md exists, improve it — don't overwrite blindly.
+If `--brownfield` (detected from existing codebase), run parallel codebase analysis:
+- `explore` for architecture patterns
+- `explore` for data flow
+- `explore` for domain boundaries
 
-## Phase 4: Create tech-stack.md
+If greenfield, skip to requirements gathering.
 
-From template `.opencode/memory/_templates/tech-stack.md`:
+### Phase 2: Requirements Gathering
 
-Read the template from `.opencode/memory/_templates/tech-stack.md` and write it to `.opencode/memory/project/tech-stack.md`.
+Ask questions to define:
+- Project vision and goals (1-2 sentences each)
+- Target users and their needs
+- Core features (what must exist)
+- Technical constraints
+- Success criteria
 
-Fill detected values:
+### Phase 3: Create Files
 
-- Framework, language, runtime
-- Styling, components, design system
-- Database, ORM, state management
-- Testing tools
-- Verification commands
+- `.opencode/memory/project/roadmap.md` — vision, goals, user personas, feature roadmap, constraints, success criteria
+- `.opencode/memory/project/state.md` — current status, active decisions, known issues, next priorities
+- Update `.opencode/opencode.json` instructions to include roadmap.md and state.md
+
+---
 
-## Phase 5: Subsystems (--deep only)
+## Mode 3: User Profile (`--user`)
 
-Identify candidates for nested AGENTS.md:
+Create personalized user profile at `.opencode/memory/project/user.md`.
 
-- `packages/*/` in monorepos
-- `frontend/` vs `backend/` directories
-- Significantly different subsystem patterns
+### Phase 1: Gather Preferences
 
-Ask user before creating nested files.
+Ask questions about:
+- **Identity**: Name, role, experience level
+- **Communication**: Verbosity preference, feedback style, update frequency
+- **Workflow**: Branch strategy, commit style, review expectations, test expectations
+- **Technical**: Preferred tools, avoided patterns, dev environment
 
-## Phase 6: Verify and Report
+### Phase 2: Create user.md
 
-Verify:
+Write to `.opencode/memory/project/user.md` with the captured preferences.
 
-- [ ] AGENTS.md is <60 lines (or justified)
-- [ ] Commands validated and work
-- [ ] Boundaries include Never rules
-- [ ] Code example from actual codebase
-- [ ] tech-stack.md created
+### Phase 3: Update opencode.json
+
+Ensure user.md is in `instructions[]` as one of the 4 auto-injected files (user.md, tech-stack.md, project.md, git-context.md).
+
+> **Warning:** Do not add more files to `instructions[]` unless essential. Per-prompt injection of too many files causes session OOM. Use `memory-search({ file: "..." })` for on-demand access.
+
+---
 
-Output:
+## Output
 
-1. Files created (with line counts)
-2. Tech stack detected
-3. Commands validated (yes/no)
-4. Suggested next steps:
-   - `/init-user` — Create user profile
-   - `/init-context` — Set up GSD planning workflow
-   - `/review-codebase` — Deep codebase analysis
+Report what was created:
+1. AGENTS.md (if core setup ran)
+2. tech-stack.md (if core setup ran)
+3. roadmap.md + state.md (if `--context`)
+4. user.md (if `--user`)
+5. Recommended next command: `/plan`, `/review-codebase`, or `/resume`

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

@@ -0,0 +1,66 @@
+---
+description: Refactor code for clarity, performance, or maintainability
+argument-hint: "<file or path> [--scope minimal|moderate|aggressive]"
+agent: build
+---
+
+# Refactor: $ARGUMENTS
+
+Improve code quality without changing external behavior.
+
+## Load Skills
+
+```typescript
+skill({ name: "code-simplification" });
+skill({ name: "verification-before-completion" });
+```
+
+## Parse Arguments
+
+| Argument | Default | Description |
+|---|---|---|
+| `<file or path>` | required | File or directory to refactor |
+| `--scope` | minimal | `minimal` (rename/restructure), `moderate` (extract modules), `aggressive` (redesign) |
+
+## When to Refactor
+
+- Module has grown beyond its original purpose
+- Tests are hard to write because of tight coupling
+- Similar logic appears in multiple places
+- Files have crossed 300+ lines with unclear boundaries
+
+## Process
+
+### Phase 1: Assess
+
+1. Read all files in scope
+2. Identify: duplication, shallow interfaces, unclear naming, mixed concerns
+3. Plan the refactor — show plan if >3 files would change
+
+### Phase 2: Lock Behavior
+
+- If the module has tests, they must still pass after refactor
+- If no tests exist, run existing verification (typecheck, lint)
+- No behavior changes in a refactor — external API must be preserved
+
+### Phase 3: Execute
+
+- One change at a time, verify after each
+- Prefer small commits with clear messages
+- `refactor(scope): what changed`
+
+### Phase 4: Verify
+
+```bash
+npm run typecheck
+npm run lint
+npm test
+```
+
+## Output
+
+Report:
+1. What changed and why
+2. Files modified
+3. Verification results
+4. What was left for future refactors

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

@@ -0,0 +1,66 @@
+---
+description: Write or generate tests for code
+argument-hint: "<file or function> [--unit|--integration|--e2e]"
+agent: build
+---
+
+# Test: $ARGUMENTS
+
+Write or generate tests for the specified code.
+
+## Load Skills
+
+```typescript
+skill({ name: "test-driven-development" });
+skill({ name: "testing-anti-patterns" });
+skill({ name: "verification-before-completion" });
+```
+
+## Parse Arguments
+
+| Argument | Default | Description |
+|---|---|---|
+| `<file or function>` | required | File path or function name to test |
+| `--unit` | auto | Unit test (default for utils, helpers) |
+| `--integration` | false | Integration test (default for API, DB) |
+| `--e2e` | false | End-to-end test (requires full setup) |
+
+## Process
+
+### Phase 1: Understand
+
+1. Read the file and understand the function/module contract
+2. Identify: inputs, outputs, side effects, error states, edge cases
+3. Check existing tests for patterns and structure
+
+### Phase 2: Write Tests
+
+Cover:
+- Happy path (expected input → expected output)
+- Edge cases (empty, null, boundary values)
+- Error states (invalid input, missing dependencies)
+- Contract invariants (what must always be true)
+
+Follow the existing test patterns in the project. If none exist, check `vitest.config.ts`.
+
+### Phase 3: Run and Verify
+
+```bash
+vitest <path>  # or npm test
+```
+
+TDD if writing implementation simultaneously: RED → GREEN → REFACTOR.
+
+## Anti-Patterns
+
+- Testing implementation details instead of behavior
+- Mocking without understanding the real dependency
+- Test-only code in production files (exporting internals just for tests)
+- Brittle assertions (matching full objects when partial match suffices)
+
+## Output
+
+Report:
+1. Tests written
+2. Coverage summary
+3. Verification results

package/dist/template/.opencode/dcp.jsonc

@@ -1,8 +1,8 @@
 {
 	"$schema": "https://raw.githubusercontent.com/Opencode-DCP/opencode-dynamic-context-pruning/master/dcp.schema.json",
 	"enabled": true,
-	// Disable auto-update for config stability — update explicitly when pinning new versions
-	// (v3.1.10+: auto-update is supported; set true if you want rolling bug fixes)
+	// Disable auto-update for config stability — update explicitly when pinning new versions.
+	// v3.1.10+ auto-update is mature; set true if you want rolling bug fixes.
 	"autoUpdate": false,
 	"debug": false,
 	// "off" | "minimal" | "detailed" — keep minimal for low-noise dev flow
@@ -31,6 +31,7 @@
 	"protectedFilePatterns": [
 		"**/.env*",
 		"**/AGENTS.md",
+		"**/opencode.json*",
 		"**/package.json",
 		"**/tsconfig.json"
 	],
@@ -59,6 +60,16 @@
 		"protectUserMessages": false,
 		// v3.1.11+: preserve text wrapped in <protect>...</protect> during compression
 		"protectTags": false,
+		// Optional per-model max context limits — only if you need different thresholds
+		// per model. Uncomment and adjust for your models:
+		// "modelMaxLimits": {
+		//     "anthropic/claude-sonnet-4.6": "80%",
+		//     "openai/gpt-5.3-codex": "80%",
+		//     "github/github-copilot": "65%"
+		// },
+		// "modelMinLimits": {
+		//     "anthropic/claude-sonnet-4.6": "30%"
+		// },
 		// Auto-protected by DCP: task, skill, todowrite, todoread, compress, batch,
 		//                        plan_enter, plan_exit, write, edit
 		// Only list ADDITIONAL tools whose outputs should be appended to compression summaries

package/dist/template/.opencode/memory/README.md

@@ -38,11 +38,9 @@ memory/
 
 | Tool                | Purpose                                       |
 | ------------------- | --------------------------------------------- |
-| `observation()`     | Write structured observations to SQLite       |
-| `memory-search()`   | FTS5 full-text search (returns compact index) |
-| `memory-get()`      | Fetch full observation details by ID          |
-| `memory-timeline()` | Get chronological context around anchor       |
-| `memory-update()`   | Update markdown files in memory               |
+| `observation()`     | Write structured observations to SQLite or give feedback on existing ones |
+| `memory-search()`   | FTS5 full-text search (returns compact index) or read memory files by path |
+| `memory-admin()`    | Memory system administration: maintenance, migration, lint, compile, index |
 
 ## PARA Categories
 

package/dist/template/.opencode/memory/_templates/adr.md

@@ -0,0 +1,45 @@
+# ADR: [short title of decision]
+
+**Status:** [proposed | accepted | deprecated | superseded]
+**Date:** [YYYY-MM-DD]
+**Context:** [bead-id, issue/Linear ticket, or session reference]
+
+## Context
+
+What is the problem we are solving? What forces are at play? What constraints do we have?
+
+## Decision
+
+What did we decide to do? Be specific. This is the answer to the problem stated above.
+
+## Rationale
+
+Why this approach over the alternatives? What evidence or reasoning supports this decision?
+
+## Consequences
+
+What becomes easier or harder because of this decision? What tradeoffs did we accept?
+
+### Positive
+
+- [benefit 1]
+- [benefit 2]
+
+### Negative
+
+- [cost / risk 1]
+- [cost / risk 2]
+
+## Alternatives Considered
+
+### Alternative 1: [name]
+
+Pros/cons and why it was rejected.
+
+### Alternative 2: [name]
+
+Pros/cons and why it was rejected.
+
+## Notes
+
+- [Anything else? Links to related ADRs, PRDs, specs?]

package/dist/template/.opencode/memory/project/gotchas.md

@@ -53,7 +53,7 @@ The edit tool (`str_replace`) is the #1 source of failures in LLM coding. Models
 ## Memory System
 
 - Subagents (explore, scout, review) should NOT write to memory - only leader agents
-- Use `observation: false` and `memory-update: false` in agent configs to enforce
+- Use `observation: false` in agent configs to enforce
 
 ## Build System
 

package/dist/template/.opencode/memory/session-context.md

@@ -6,7 +6,7 @@ updated: 2025-01-08
 # Session Context
 
 <!--
-Agent-maintained via memory-update tool.
+Agent-maintained via observation tool.
 Update when: goal changes, key decision made, state shifts, uncertainty discovered.
 After compaction: read this file, ask 1-3 targeted questions if gaps exist.
 -->

package/dist/template/.opencode/plugin/README.md

@@ -42,7 +42,7 @@ plugin/
   - Injects relevant knowledge into system prompt (BM25 _ recency _ confidence scoring)
   - Manages context window via messages.transform (token budget enforcement)
   - Merges compaction logic (beads, handoffs, project memory, knowledge)
-  - Provides 11 tools: observation, memory-search, memory-get, memory-read, memory-update, memory-timeline, memory-graph-add, memory-graph-query, memory-graph-invalidate, memory-compact, memory-admin
+  - Provides 3 tools: observation, memory-search, memory-admin
 
 - `sessions.ts`
   - Provides tools: `find_sessions`, `read_session`

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

@@ -0,0 +1,62 @@
+/**
+ * Guard Plugin — Agent Safety & Convention Enforcement
+ *
+ * Ported from pikit's extensions/guard.ts.
+ *
+ * 1. Pipe-to-shell blocker: rejects `curl … | bash` / `wget … | bash` patterns.
+ * 2. Conventional Commits: rejects `git commit` with non-compliant messages.
+ */
+
+import type { Plugin } from "@opencode-ai/plugin";
+
+const CONVENTIONAL_RE =
+	/^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([a-z0-9._/-]+\))?!?: .+/;
+
+export const GuardPlugin: Plugin = async () => {
+	return {
+		"tool.execute.before": async (input, output) => {
+			if (input.tool !== "bash") return;
+
+			const cmd: string = (output.args as Record<string, unknown>)?.command ?? "";
+
+			// --- curl/wget | bash blocker ---
+			// Only match when curl/wget starts a command segment to avoid false positives
+			// on quoted text (e.g. commit messages) mentioning the pattern.
+			if (/(?:^|[;&|])\s*(?:curl|wget)\s.*\|\s*(?:ba)?sh/i.test(cmd)) {
+				throw new Error(
+					"Blocked: detected pipe-to-shell pattern (curl/wget | bash). Download first, inspect, then run.",
+				);
+			}
+
+			// --- conventional commit enforcer ---
+			const commitMatch = cmd.match(/git\s+commit\s/);
+			if (!commitMatch) return;
+
+			const msgMatch =
+				cmd.match(/(?:-m|--message=?)\s*"([^"]*)"/) ??
+				cmd.match(/(?:-m|--message=?)\s*'([^']*)'/) ??
+				cmd.match(/(?:-m|--message=?)\s+(\S+)/);
+
+			const msg = msgMatch?.[1];
+
+			if (!msg) {
+				throw new Error(
+					'Blocked: git commit missing -m message. Use: git commit -m "type(scope): subject"',
+				);
+			}
+
+			if (!CONVENTIONAL_RE.test(msg)) {
+				throw new Error(
+					[
+						"Blocked: commit message is not Conventional Commits compliant.",
+						`Got: ${msg}`,
+						"Expected: <type>(scope): <subject>",
+						"Types: feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert",
+					].join("\n"),
+				);
+			}
+		},
+	};
+};
+
+export default GuardPlugin;

package/dist/template/.opencode/plugin/{lib/memory-admin-tools.ts → memory/admin.ts}

@@ -33,7 +33,7 @@ import {
 	runFullMaintenance,
 	storeObservation,
 	vacuumDatabase,
-} from "./memory-db.js";
+} from "./db.js";
 
 interface AdminToolDeps {
 	directory: string;
@@ -157,7 +157,7 @@ export function createAdminTools(deps: AdminToolDeps) {
 												severity: "medium" as const,
 												title: `Graph contradiction: ${t.subject} ↔ ${t.object}`,
 												detail: `Active triple "${t.subject} —[${t.predicate}]→ ${t.object}" has ${contradictions.length} conflicting predicate(s): ${contradictions.map(c => c.predicate).join(", ")}`,
-												suggestion: `Use memory-graph-invalidate to close outdated triples`,
+												suggestion: `Use observation to update or supersede outdated observations`,
 												type: "contradiction" as const,
 												observation_ids: contradictions.map(c => c.source_observation_id).filter((id): id is number => id != null),
 											});
@@ -187,7 +187,7 @@ export function createAdminTools(deps: AdminToolDeps) {
 						}
 						case "index": {
 							const result = generateMemoryIndex();
-							return `Index generated: ${result.entryCount} observations, ${result.conceptCount} concepts. Read with \`memory-read({ file: "index" })\`.`;
+							return `Index generated: ${result.entryCount} observations, ${result.conceptCount} concepts. Read with \`memory-search({ file: "index" })\`.`;
 						}
 						case "compile": {
 							const result = compileObservations();
@@ -195,7 +195,7 @@ export function createAdminTools(deps: AdminToolDeps) {
 								return `No concept clusters with 3+ observations found. Nothing to compile.`;
 							}
 							const articleList = result.articles.map(a => `  - ${a.concept} (${a.observationCount} obs)`).join("\n");
-							return `Compiled ${result.articles.length} articles from ${result.totalObservations} observations (${result.skippedClusters} skipped).\n\nArticles:\n${articleList}\n\nRead with \`memory-read({ file: "compiled/<concept>" })\`.`;
+							return `Compiled ${result.articles.length} articles from ${result.totalObservations} observations (${result.skippedClusters} skipped).\n\nArticles:\n${articleList}\n\nRead with \`memory-search({ file: "compiled/<concept>" })\`.`;
 						}
 						case "log": {
 							return getLogContent();