opencodekit 0.23.3 → 0.23.4

package/dist/template/.opencode/skill/condition-based-waiting/example.ts

@@ -1,171 +0,0 @@
-// Complete implementation of condition-based waiting utilities
-// From: Lace test infrastructure improvements (2025-10-03)
-// Context: Fixed 15 flaky tests by replacing arbitrary timeouts
-//
-// Self-contained — types are defined inline to avoid external dependencies.
-
-/** Minimal thread manager interface for condition polling */
-interface ThreadManager {
-  getEvents(threadId: string): LaceEvent[];
-}
-
-/** Generic event type identifier */
-type LaceEventType = string;
-
-/** Generic event with type discriminator and optional data payload */
-interface LaceEvent {
-  type: string;
-  data?: Record<string, unknown>;
-}
-
-/**
- * Wait for a specific event type to appear in thread
- *
- * @param threadManager - The thread manager to query
- * @param threadId - Thread to check for events
- * @param eventType - Type of event to wait for
- * @param timeoutMs - Maximum time to wait (default 5000ms)
- * @returns Promise resolving to the first matching event
- *
- * Example:
- *   await waitForEvent(threadManager, agentThreadId, 'TOOL_RESULT');
- */
-export function waitForEvent(
-  threadManager: ThreadManager,
-  threadId: string,
-  eventType: LaceEventType,
-  timeoutMs = 5000,
-): Promise<LaceEvent> {
-  return new Promise((resolve, reject) => {
-    const startTime = Date.now();
-
-    const check = () => {
-      const events = threadManager.getEvents(threadId);
-      const event = events.find((e) => e.type === eventType);
-
-      if (event) {
-        resolve(event);
-      } else if (Date.now() - startTime > timeoutMs) {
-        reject(new Error(`Timeout waiting for ${eventType} event after ${timeoutMs}ms`));
-      } else {
-        setTimeout(check, 10); // Poll every 10ms for efficiency
-      }
-    };
-
-    check();
-  });
-}
-
-/**
- * Wait for a specific number of events of a given type
- *
- * @param threadManager - The thread manager to query
- * @param threadId - Thread to check for events
- * @param eventType - Type of event to wait for
- * @param count - Number of events to wait for
- * @param timeoutMs - Maximum time to wait (default 5000ms)
- * @returns Promise resolving to all matching events once count is reached
- *
- * Example:
- *   // Wait for 2 AGENT_MESSAGE events (initial response + continuation)
- *   await waitForEventCount(threadManager, agentThreadId, 'AGENT_MESSAGE', 2);
- */
-export function waitForEventCount(
-  threadManager: ThreadManager,
-  threadId: string,
-  eventType: LaceEventType,
-  count: number,
-  timeoutMs = 5000,
-): Promise<LaceEvent[]> {
-  return new Promise((resolve, reject) => {
-    const startTime = Date.now();
-
-    const check = () => {
-      const events = threadManager.getEvents(threadId);
-      const matchingEvents = events.filter((e) => e.type === eventType);
-
-      if (matchingEvents.length >= count) {
-        resolve(matchingEvents);
-      } else if (Date.now() - startTime > timeoutMs) {
-        reject(
-          new Error(
-            `Timeout waiting for ${count} ${eventType} events after ${timeoutMs}ms (got ${matchingEvents.length})`,
-          ),
-        );
-      } else {
-        setTimeout(check, 10);
-      }
-    };
-
-    check();
-  });
-}
-
-/**
- * Wait for an event matching a custom predicate
- * Useful when you need to check event data, not just type
- *
- * @param threadManager - The thread manager to query
- * @param threadId - Thread to check for events
- * @param predicate - Function that returns true when event matches
- * @param description - Human-readable description for error messages
- * @param timeoutMs - Maximum time to wait (default 5000ms)
- * @returns Promise resolving to the first matching event
- *
- * Example:
- *   // Wait for TOOL_RESULT with specific ID
- *   await waitForEventMatch(
- *     threadManager,
- *     agentThreadId,
- *     (e) => e.type === 'TOOL_RESULT' && e.data.id === 'call_123',
- *     'TOOL_RESULT with id=call_123'
- *   );
- */
-export function waitForEventMatch(
-  threadManager: ThreadManager,
-  threadId: string,
-  predicate: (event: LaceEvent) => boolean,
-  description: string,
-  timeoutMs = 5000,
-): Promise<LaceEvent> {
-  return new Promise((resolve, reject) => {
-    const startTime = Date.now();
-
-    const check = () => {
-      const events = threadManager.getEvents(threadId);
-      const event = events.find(predicate);
-
-      if (event) {
-        resolve(event);
-      } else if (Date.now() - startTime > timeoutMs) {
-        reject(new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`));
-      } else {
-        setTimeout(check, 10);
-      }
-    };
-
-    check();
-  });
-}
-
-// Usage example from actual debugging session:
-//
-// BEFORE (flaky):
-// ---------------
-// const messagePromise = agent.sendMessage('Execute tools');
-// await new Promise(r => setTimeout(r, 300)); // Hope tools start in 300ms
-// agent.abort();
-// await messagePromise;
-// await new Promise(r => setTimeout(r, 50));  // Hope results arrive in 50ms
-// expect(toolResults.length).toBe(2);         // Fails randomly
-//
-// AFTER (reliable):
-// ----------------
-// const messagePromise = agent.sendMessage('Execute tools');
-// await waitForEventCount(threadManager, threadId, 'TOOL_CALL', 2); // Wait for tools to start
-// agent.abort();
-// await messagePromise;
-// await waitForEventCount(threadManager, threadId, 'TOOL_RESULT', 2); // Wait for results
-// expect(toolResults.length).toBe(2); // Always succeeds
-//
-// Result: 60% pass rate → 100%, 40% faster execution

package/dist/template/.opencode/skill/context-engineering/SKILL.md

@@ -1,176 +0,0 @@
----
-name: context-engineering
-description: Use when designing AGENTS.md hierarchies, understanding autonomous duration, or writing intent layers - covers principles for extending agent work capacity
-version: 1.0.0
-tags: [context, documentation]
-dependencies: []
----
-
-# Context Engineering
-
-## When to Use
-
-- Designing or refactoring AGENTS.md hierarchies and intent layers
-- You need to extend autonomous work duration via better context structure
-
-## When NOT to Use
-
-- You only need pruning/distillation mechanics (use context-management)
-- Simple tasks where context design is not relevant
-
-
-
-## Core Principle
-
-**Autonomous Duration**: How long can an agent work before losing the plot?
-
-Extend it by:
-
-- Binding tighter to intent (clear specs, constraints, invariants)
-- Providing systematic context (AGENTS.md hierarchy, memory files)
-- Verification loops (test → iterate → verify)
-
-## Three Context Constraints
-
-1. **Blind spots cause hallucinations** - Agent fills gaps with generic priors
-2. **Everything influences everything** - Noise degrades ALL output quality
-3. **Window is finite** - Performance degrades BEFORE hard token limits
-
-## Intent Layer Principles
-
-### What Belongs in Each AGENTS.md
-
-- **Purpose & Scope** - What this area does. What it DOESN'T do.
-- **Entry Points & Contracts** - Main APIs, invariants
-- **Usage Patterns** - Canonical examples
-- **Anti-patterns** - What NOT to do
-- **Dependencies & Downlinks** - Pointers to related context
-
-### Key Mechanics
-
-| Principle                | Meaning                                                  |
-| ------------------------ | -------------------------------------------------------- |
-| **Hierarchical loading** | When node loads, all ancestors load too (T-shaped view)  |
-| **Compression**          | Good nodes compress code; don't add bloat                |
-| **LCA placement**        | Place shared knowledge at shallowest node covering paths |
-| **Downlinks**            | Point to related context without loading everything      |
-
-## Practical Implications
-
-| Instead of              | Do This                                 |
-| ----------------------- | --------------------------------------- |
-| Reading entire files    | Use `lsp documentSymbol` for outline    |
-| Loading whole documents | Read specific line ranges               |
-| Flat file loading       | Navigate AGENTS.md hierarchy            |
-| Keeping completed work  | Compress closed phases, sweep stale noise (context-management) |
-
-## Anti-Patterns
-
-❌ Loading "everything that might be relevant"
-❌ Keeping old file reads after editing complete
-❌ Reading entire files when you only need a function
-❌ Ignoring AGENTS.md hierarchy
-
-## Static vs Runtime Context (Longshot Pattern)
-
-At scale (10+ agents), the difference between **static context** and **runtime context** is the difference between a coherent swarm and chaos.
-
-### Definitions
-
-| Type                | What It Is                                                   | When Loaded            | Example                                 |
-| ------------------- | ------------------------------------------------------------ | ---------------------- | --------------------------------------- |
-| **Static Context**  | Always-on knowledge — invariants, constraints, project shape | Always (auto-injected) | AGENTS.md, tech-stack.md, user.md       |
-| **Runtime Context** | Per-task injections — what THIS task needs right now         | Per-task               | Delegation packet, task spec, file list |
-
-### Why the Split Matters
-
-Without separation, context becomes soup:
-
-- Agent loads everything → hits token limit → degrades
-- Agents share stale context → conflicting decisions
-- No clear source of truth for "what is the objective"
-
-With separation:
-
-- Static = immune to session pollution (always fresh)
-- Runtime = scoped to task (cleaned up when done)
-- Result: agents stay coherent at 200-agent scale
-
-### Task Packet Format
-
-Every task dispatched to a worker agent MUST include an explicit context block:
-
-```markdown
-## Task Packet
-
-### Static Context (always available)
-
-- Project rules: AGENTS.md
-- Tech stack: .opencode/memory/project/tech-stack.md
-- Gotchas: .opencode/memory/project/gotchas.md
-
-### Runtime Context (this task only)
-
-- Objective: [one sentence]
-- Scope: [files this task may touch]
-- Constraints: [must_do / must_not_do]
-- Dependencies: [what was produced by prior tasks]
-- Verification: [acceptance commands]
-```
-
-### Injection Pattern
-
-When spawning workers, always inject runtime context explicitly:
-
-```typescript
-// WRONG: Vague prompt — agent guesses context
-Task({ prompt: "Implement auth service" });
-
-// RIGHT: Explicit static + runtime context split
-Task({
-  prompt: `## Static Context
-AGENTS.md governs all decisions. Tech stack: Bun, TypeScript strict mode.
-
-## Runtime Context
-Objective: Implement JWT auth service in src/auth/service.ts.
-Scope: Only modify src/auth/ directory.
-Dependencies: Schema defined in src/db/schema.ts (from task-1).
-Constraints:
-  MUST DO: Use zod for input validation
-  MUST NOT DO: Add new dependencies without approval
-Verification:
-  npm run typecheck && npm run lint && vitest src/auth/`,
-});
-```
-
-### Context Pollution Anti-Patterns
-
-| Anti-Pattern                                | Problem                           | Fix                                   |
-| ------------------------------------------- | --------------------------------- | ------------------------------------- |
-| Passing entire AGENTS.md as runtime context | Bloats token budget on every task | Load via static injection only        |
-| Runtime state persisting across waves       | Stale context poisons next wave   | Clear runtime state between waves     |
-| No objective in task packet                 | Agent drifts from goal            | Always include one-sentence objective |
-| Injection without scope                     | Agent modifies wrong files        | Always declare file scope             |
-
-### Static Context Files (Always Inject)
-
-These files are the project's invariant layer. Always available, never stale:
-
-```
-.opencode/memory/project/
-├── user.md          # User preferences, workflow rules
-├── tech-stack.md    # Frameworks, constraints
-├── gotchas.md       # Footguns, warnings
-└── project.md       # Vision, success criteria
-```
-
-### Runtime Context Files (Per-Task)
-
-These are created fresh per task and cleaned up after:
-
-```
-.opencode/artifacts/<slug>/
-├── delegation.md    # Task-specific instructions
-├── spec.md          # Technical requirements
-└── progress.txt     # Task state (append-only)
-```

package/dist/template/.opencode/skill/memory-system/SKILL.md

@@ -1,147 +0,0 @@
----
-name: memory-system
-description: Use when persisting learnings, loading previous context, or searching past decisions - covers memory file structure, tools, and when to update each file
-version: 1.2.0
-tags: [context, workflow]
-dependencies: []
----
-
-# Memory System Best Practices
-
-> **Replaces** losing context between sessions — persistent knowledge that survives session boundaries
-
-## When to Use
-
-- Starting work and needing prior decisions, bugfixes, or patterns
-- Recording non-obvious decisions/learnings for future sessions
-- Creating handoffs so the next session can continue quickly
-
-## When NOT to Use
-
-- Ephemeral debugging notes that won't matter after the current task
-- Storing generated artifacts/log dumps as long-term memory
-
-## Core Principle
-
-**Progressive disclosure**: search compactly, fetch fully only when relevant, then record high-signal observations.
-
-## Session Workflow
-
-1. **Ground (search first)**
-   - Run `memory-search` with task keywords before implementation.
-   - Check recent handoffs when resuming interrupted work.
-2. **Calibrate (progressive disclosure)**
-   - Use search results as index; `memory-search({ file: "..." })` for file access.
-   - Retrieve full observation details from search output.
-3. **Record (high-signal only)**
-   - Create `observation` for decisions, bugfixes, patterns, warnings, or durable learnings.
-   - Include searchable concepts and concrete file references.
-4. **Handoff (if session boundary)**
-   - Write a concise status note with completed work, blockers, and next steps using `observation`.
-
-## What Goes Where
-
-| Store | Put Here | Avoid Here |
-| --- | --- | --- |
-| `observation` (SQLite) | Events: decisions, bugfixes, reusable patterns, warnings, handoffs | Temporary notes, speculative ideas without evidence |
-| `memory-search` by file | Durable docs: handoffs, research, project notes | Every minor runtime detail from a single debug run |
-| Auto pipeline | Captured messages + distillations (automatic) | Manual copying of full transcripts |
-
-## Observation Quality Bar
-
-Use this checklist before creating an observation:
-
-- Is it likely useful in a future session?
-- Is it non-obvious (not already in code/comments)?
-- Can I summarize it in one clear title + short narrative?
-- Did I include strong search terms in `concepts` and relevant files?
-
-If most answers are "no", skip creating the observation.
-
-## Anti-Patterns
-
-| Anti-Pattern | Why It Fails | Instead |
-| --- | --- | --- |
-| Storing transient debugging info as permanent observations | Pollutes search results with low-value noise | Keep transient info in session context; record only durable findings |
-| Creating observations for every small finding (signal-to-noise) | Important items get buried and retrieval quality drops | Batch minor notes; publish one distilled observation per meaningful outcome |
-| Not searching memory before creating duplicate observations | Produces conflicting/duplicated records | Run `memory-search` first; update/supersede existing records when appropriate |
-| Using `observation` with `file` param for document-style content | Document-style content should use `memory-search({ file: "..." })` for file access | Use `observation` for events; write to memory files when structured document storage is needed |
-
-## Verification
-
-After creating an observation: `memory-search` with relevant keywords should find it.
-
-## Practical Defaults
-
-- Prefer specific queries over broad ones (`"auth race condition init"` > `"auth"`).
-- For ongoing work, append to one handoff file per task/day instead of many tiny files.
-- Keep observation titles concrete and action-oriented.
-
-## Admin Operations
-
-The `memory-admin` tool supports these operations:
-
-### Core (existing)
-| Operation | Purpose |
-|---|---|
-| `status` | Storage stats, FTS5 health, pipeline counts |
-| `full` | Full maintenance cycle (archive + checkpoint + vacuum) |
-| `archive` | Archive observations older than N days |
-| `checkpoint` | Checkpoint WAL file |
-| `vacuum` | Vacuum database |
-| `migrate` | Import .opencode/memory/observations/*.md into SQLite |
-| `capture-stats` | Temporal message capture statistics |
-| `distill-now` | Force distillation for current session |
-| `curate-now` | Force curator run |
-
-### Knowledge Intelligence (new in v2.1)
-| Operation | Purpose |
-|---|---|
-| `lint` | Find duplicates, contradictions, stale/orphan observations |
-| `index` | Generate a structured catalog of all observations |
-| `compile` | Build concept-grouped articles from observation clusters |
-| `log` | View the append-only operation audit trail |
-
-Examples:
-```
-memory-admin({ operation: "lint" })
-memory-admin({ operation: "lint", older_than_days: 60 })
-memory-admin({ operation: "index" })
-memory-admin({ operation: "compile" })
-memory-admin({ operation: "log" })
-```
-
-### Reading Compiled Artifacts
-```
-memory-search({ file: "index" })             // Full observation catalog
-memory-search({ file: "compiled/auth" })      // Compiled article for "auth" concept
-memory-search({ file: "log" })                // Operation audit trail
-```
-
-## Validation Gate
-
-The `observation` tool now validates before storing:
-- **Exact duplicate** → rejected (returns duplicate ID + supersede hint)
-- **Near-duplicate** → stored with warning
-- **Contradiction** → stored with warning (for decisions sharing concepts)
-- **Low quality** → stored with warning (no narrative + no concepts)
-
-To update an existing observation, use `supersedes`:
-```
-observation({ type: "decision", title: "Use JWT", supersedes: "42", ... })
-```
-
-## Idle Pipeline
-
-During `session.idle`, the memory system automatically runs:
-1. Distill undistilled messages
-2. Curate observations from distillations
-3. Optimize FTS5 index
-4. Checkpoint WAL if large
-5. Compile concept articles (max 10)
-6. Regenerate memory index
-
-## See Also
-
-- `context-management`
-- `session-management`

package/dist/template/.opencode/skill/structured-edit/SKILL.md

@@ -1,191 +0,0 @@
----
-name: structured-edit
-description: Use when editing files to reduce str_replace failures - combines LSP location with read-verify-edit pattern for reliable edits
-version: 1.0.0
-tags: [code-quality, workflow]
-dependencies: []
----
-
-# Structured Edit Protocol
-
-## When to Use
-
-- Editing files where exact string matches are error-prone (e.g., str_replace failures)
-- Making targeted changes that require precise location and verification
-
-## When NOT to Use
-
-- One-line edits where a direct edit is safe and unambiguous
-- Large refactors better served by full rewrites or file splits
-
-## Common Rationalizations
-
-| Rationalization                                   | Rebuttal                                                                                    |
-| ------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| "I remember what the file looks like"             | You remember what it looked like 5 edits ago. Read it fresh                                 |
-| "The edit is simple, I don't need to verify"      | Simple edits fail most often — whitespace, encoding, duplicate matches                      |
-| "LSP lookup is an extra step I can skip"          | LSP takes 1 call. Retrying a failed edit takes 3-5 calls                                    |
-| "I'll just use a larger context block to be safe" | Larger blocks = more chances for invisible character mismatches. Use minimal unique context |
-| "The file hasn't changed since I last read it"    | Other edits, formatters, and git operations can modify files between your reads             |
-
-## Overview
-
-The `str_replace` edit tool is the #1 source of failures in LLM coding. Models reproduce content with subtle differences (whitespace, encoding, line endings) causing "string not found" errors.
-
-**Core principle:** Don't guess content — locate, read, verify, then edit.
-
-## Why This Exists
-
-`str_replace` failures happen when:
-
-| Cause                | Example                                    |
-| -------------------- | ------------------------------------------ |
-| Whitespace mismatch  | Tabs vs spaces, trailing spaces            |
-| Content changed      | File modified since last read              |
-| Multiple matches     | Same string appears twice in file          |
-| Encoding differences | Line endings (CRLF vs LF), invisible chars |
-| Stale context        | Editing from memory instead of fresh read  |
-
-**Result:** Wasted tokens on retries, frustrated developers, broken workflows.
-
-## The Protocol
-
-### Step 1: LOCATE
-
-Use LSP to find exact positions instead of guessing:
-
-```typescript
-// Find where a function is defined
-lsp({ operation: "goToDefinition", filePath, line, character });
-
-// Find all references to a symbol
-lsp({ operation: "findReferences", filePath, line, character });
-
-// Get all symbols in a file
-lsp({ operation: "documentSymbol", filePath, line: 1, character: 1 });
-
-// Search for symbol across workspace
-lsp({ operation: "workspaceSymbol", filePath, line: 1, character: 1 });
-```
-
-### Step 2: READ
-
-Get fresh file content at the located position:
-
-```typescript
-// Read context around target line
-read({ filePath, offset: line - 10, limit: 30 });
-```
-
-**Always include context** — don't just read the target line.
-
-### Step 3: VERIFY
-
-Confirm expected content exists at the location:
-
-```typescript
-// Check that what you expect is actually there
-if (!content.includes(expectedSubstring)) {
-  // STOP — investigate before proceeding
-}
-```
-
-### Step 4: EDIT
-
-Apply minimal, scoped change with unique context:
-
-```typescript
-// Include enough surrounding lines for uniqueness
-edit({
-  filePath,
-  oldString: "  // unique context before\n  targetLine\n  // unique context after",
-  newString: "  // unique context before\n  modifiedLine\n  // unique context after",
-});
-```
-
-**Guidelines:**
-
-- Include 2-3 lines before/after for uniqueness
-- Never use just the target line
-- Keep oldString minimal but unique
-
-### Step 5: CONFIRM
-
-Verify the edit succeeded:
-
-```typescript
-// Read back the modified section
-read({ filePath, offset: line - 5, limit: 15 });
-
-// Confirm content matches intent
-```
-
-## Red Flags — STOP
-
-If you catch yourself:
-
-- Editing without reading first
-- Assuming content hasn't changed
-- Using large multi-line oldString values
-- Skipping the verify step
-- Guessing line numbers without LSP
-
-**STOP.** Return to Step 1.
-
-## Best Practices
-
-### File Size Matters
-
-From research on the "harness problem":
-
-| File Size     | Strategy                                   |
-| ------------- | ------------------------------------------ |
-| < 100 lines   | Full rewrite often easier than str_replace |
-| 100-400 lines | Structured edit with good context          |
-| > 400 lines   | Strongly prefer structured edits           |
-
-**Prefer smaller files** — composition over monoliths.
-
-### Unique Context Selection
-
-```typescript
-// BAD: Non-unique, whitespace-sensitive
-oldString: "return result;";
-
-// GOOD: Unique with surrounding context
-oldString: "  // Calculate final value\n  const result = compute(input);\n  return result;";
-```
-
-### When to Use LSP vs Direct
-
-| Scenario                  | Approach              |
-| ------------------------- | --------------------- |
-| Finding function/class    | LSP goToDefinition    |
-| Finding all usages        | LSP findReferences    |
-| Modifying specific symbol | LSP + structured edit |
-| Large refactoring         | Consider full rewrite |
-| Simple one-line change    | Direct edit OK        |
-
-## Integration with Other Skills
-
-**Use with:**
-
-- `verification-before-completion` — Always verify edits succeeded
-- `systematic-debugging` — When edit failures indicate deeper issues
-- `defense-in-depth` — Add validation after structural changes
-
-## Quick Reference
-
-```
-LOCATE  → lsp({ operation: "goToDefinition" | "findReferences", ... })
-READ    → read({ filePath, offset: line-10, limit: 30 })
-VERIFY  → Check expected content exists
-EDIT    → edit({ oldString: "...unique context...", newString: "..." })
-CONFIRM → read() again to verify success
-```
-
-## The Bottom Line
-
-**Don't trust your memory. Don't guess content. Locate, read, verify, edit, confirm.**
-
-This protocol eliminates the #1 source of LLM coding failures.