opencodekit 0.23.2 → 0.23.4

package/dist/template/.opencode/skill/condition-based-waiting/SKILL.md

@@ -1,135 +0,0 @@
----
-name: condition-based-waiting
-description: Use when tests have race conditions, timing dependencies, or inconsistent pass/fail behavior - replaces arbitrary timeouts with condition polling to wait for actual state changes, eliminating flaky tests from timing guesses
-version: 1.0.0
-tags: [testing, debugging]
-dependencies: []
----
-
-# Condition-Based Waiting
-
-> **Replaces** arbitrary `sleep()` / `setTimeout()` calls and hardcoded delays that cause flaky tests and slow CI
-
-## When to Use
-
-- Tests are flaky due to arbitrary delays or timing guesses
-- You need to wait for async state changes (events, file writes, state transitions)
-
-## When NOT to Use
-
-- You are explicitly testing timing behavior (debounce, throttle, intervals)
-- A fixed, documented timeout is part of the requirement
-
-## Common Rationalizations
-
-| Rationalization                               | Rebuttal                                                                       |
-| --------------------------------------------- | ------------------------------------------------------------------------------ |
-| "50ms is plenty of time"                      | It's plenty on YOUR machine. CI runners under load disagree                    |
-| "The sleep worked in local testing"           | Local = fast SSD, idle CPU. CI = shared resources, variable latency            |
-| "Adding a waitFor is more complex than sleep" | A 5-line waitFor is simpler than debugging a flaky test 10 times               |
-| "This operation is always fast"               | "Always" until garbage collection, disk I/O, or network latency says otherwise |
-| "I'll increase the timeout if it flakes"      | Increasing timeouts slows the entire suite and masks the real problem          |
-| "It only fails sometimes"                     | "Sometimes" = race condition. Condition-based waiting eliminates it entirely   |
-
-## Overview
-
-Flaky tests often guess at timing with arbitrary delays. This creates race conditions where tests pass on fast machines but fail under load or in CI.
-
-**Core principle:** Wait for the actual condition you care about, not a guess about how long it takes.
-
-## Core Pattern
-
-```typescript
-// ❌ BEFORE: Guessing at timing
-await new Promise((r) => setTimeout(r, 50));
-const result = getResult();
-expect(result).toBeDefined();
-
-// ✅ AFTER: Waiting for condition
-await waitFor(() => getResult() !== undefined);
-const result = getResult();
-expect(result).toBeDefined();
-```
-
-## Quick Patterns
-
-| Scenario          | Pattern                                              |
-| ----------------- | ---------------------------------------------------- |
-| Wait for event    | `waitFor(() => events.find(e => e.type === 'DONE'))` |
-| Wait for state    | `waitFor(() => machine.state === 'ready')`           |
-| Wait for count    | `waitFor(() => items.length >= 5)`                   |
-| Wait for file     | `waitFor(() => fs.existsSync(path))`                 |
-| Complex condition | `waitFor(() => obj.ready && obj.value > 10)`         |
-
-## Implementation
-
-Generic polling function:
-
-```typescript
-async function waitFor<T>(
-  condition: () => T | undefined | null | false,
-  description: string,
-  timeoutMs = 5000,
-): Promise<T> {
-  const startTime = Date.now();
-
-  while (true) {
-    const result = condition();
-    if (result) return result;
-
-    if (Date.now() - startTime > timeoutMs) {
-      throw new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`);
-    }
-
-    await new Promise((r) => setTimeout(r, 10)); // Poll every 10ms
-  }
-}
-```
-
-See @example.ts for complete implementation with domain-specific helpers (`waitForEvent`, `waitForEventCount`, `waitForEventMatch`) from actual debugging session.
-
-## Common Mistakes
-
-**❌ Polling too fast:** `setTimeout(check, 1)` - wastes CPU
-**✅ Fix:** Poll every 10ms
-
-**❌ No timeout:** Loop forever if condition never met
-**✅ Fix:** Always include timeout with clear error
-
-**❌ Stale data:** Cache state before loop
-**✅ Fix:** Call getter inside loop for fresh data
-
-## When Arbitrary Timeout IS Correct
-
-```typescript
-// Tool ticks every 100ms - need 2 ticks to verify partial output
-await waitForEvent(manager, "TOOL_STARTED"); // First: wait for condition
-await new Promise((r) => setTimeout(r, 200)); // Then: wait for timed behavior
-// 200ms = 2 ticks at 100ms intervals - documented and justified
-```
-
-**Requirements:**
-
-1. First wait for triggering condition
-2. Based on known timing (not guessing)
-3. Comment explaining WHY
-
-## Verification
-
-- **After applying:** run the previously flaky test 5+ times — should pass consistently
-- **Check:** no hardcoded sleep/delay values remain in the test file
-- **Measure:** test execution time should decrease (no wasted wait time)
-
-## Real-World Impact
-
-From debugging session (2025-10-03):
-
-- Fixed 15 flaky tests across 3 files
-- Pass rate: 60% → 100%
-- Execution time: 40% faster
-- No more race conditions
-
-## See Also
-
-- `systematic-debugging`
-- `test-driven-development`

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`