opencode-starterkit 1.0.1

package/baseline/skill/compaction/SKILL.md

@@ -0,0 +1,317 @@
+---
+name: compaction
+description: >
+  Use when context is growing large during long-running tasks and needs server-side or client-side
+  summarization to continue effectively. Covers compaction triggers, custom summarization patterns,
+  session handoff, and context preservation strategies.
+version: 1.0.0
+tags: [context, workflow]
+dependencies: []
+---
+
+# Context Compaction - Managing Long-Running Sessions
+
+## When to Use
+
+- Context is growing large and needs compression/cleanup to continue.
+
+## When NOT to Use
+
+- Short sessions with low context usage where no compaction is needed.
+
+
+## Overview
+
+**Compaction = Summarization + Preservation + Continuity**
+
+Long-running sessions accumulate context (tool outputs, code reads, exploration results). When context approaches limits, compaction reduces it to essential information while preserving decision history and work state.
+
+## Context Budget Awareness
+
+### Token Thresholds
+
+| Context Usage | Status      | Action                                        |
+| ------------- | ----------- | --------------------------------------------- |
+| 0-50%         | 🟢 Normal   | Work freely                                   |
+| 50-70%        | 🟡 Watch    | Start compressing completed explorations      |
+| 70-85%        | 🟠 Compact  | Actively compress and sweep stale noise       |
+| 85-95%        | 🔴 Critical | Emergency compaction, prepare session handoff |
+| 95%+          | ⛔ Limit    | Session handoff required                      |
+
+### Monitoring
+
+Pay attention to these signals:
+
+- Completed phases accumulating without being compressed
+- Repeated file reads of the same content
+- Large bash outputs from builds/tests
+- Multiple exploration rounds without synthesis
+
+## Compaction Strategies
+
+### Strategy 1: Phase Compression (Preferred)
+
+Compress completed conversation phases into dense summaries. This is the primary DCP instrument in the installed beta.
+
+
+Compress completed conversation phases into dense summaries.
+
+```
+WHEN: A research phase is complete and findings are clear
+DO: compress({
+  topic: "Auth Research Complete",
+  content: {
+    startString: "unique text at phase start",
+    endString: "unique text at phase end",
+    summary: "Complete technical summary of findings..."
+  }
+})
+```
+
+**Key principle**: Only compress CLOSED chapters. Never compress active work.
+
+### Strategy 2: Sweep Stale Noise
+
+Use `/dcp sweep` after a phase is complete to remove stale/noisy content automatically.
+
+```
+WHEN: Wrong-target searches or superseded outputs are no longer needed
+DO: /dcp sweep
+```
+
+**Key principle**: Sweep only after the relevant phase is closed. If in doubt, keep it.
+
+### Strategy 3: Session Handoff
+
+When context is too large to compact further, hand off to a new session.
+
+```
+WHEN: Context > 85% and significant work remains
+DO:
+  1. Create handoff document with memory-update
+  2. Save all decisions with observation tool
+  3. Document current state and remaining work
+  4. Start new session with handoff reference
+```
+
+## Compaction Decision Tree
+
+```
+Is context growing large?
+├── NO → Continue working normally
+└── YES → What type of content is consuming space?
+    ├── Completed conversation phases → COMPRESS
+    ├── Stale/noisy closed-phase outputs → SWEEP
+    └── Everything is still relevant → SESSION HANDOFF
+```
+
+## Custom Summarization Patterns
+
+### For Code Exploration
+
+```markdown
+## Exploration Summary: [Component/Module]
+
+### Architecture
+
+- Entry point: `src/auth/index.ts`
+- Key classes: AuthService, TokenManager, SessionStore
+- Dependencies: jwt, bcrypt, redis
+
+### Key Findings
+
+- Auth flow: login → validate → issue JWT → store session
+- Token rotation: every 15 minutes via refresh endpoint
+- Session storage: Redis with 24h TTL
+
+### Decisions Made
+
+- Use existing TokenManager (don't replace)
+- Add rate limiting to login endpoint
+- Migrate session store from memory to Redis
+
+### Files to Modify
+
+- src/auth/service.ts (add rate limiting)
+- src/auth/session.ts (Redis integration)
+- src/config/redis.ts (new file)
+```
+
+### For Implementation Phase
+
+```markdown
+## Implementation Summary: [Feature]
+
+### Completed
+
+- [x] Database schema migration (src/db/migrations/004_auth.ts)
+- [x] API endpoints (src/routes/auth.ts) - 3 new routes
+- [x] Frontend forms (src/components/auth/) - Login, Register, Reset
+
+### Verification
+
+- TypeScript: ✅ passing
+- Tests: ✅ 12/12 passing
+- Lint: ✅ no issues
+
+### Remaining
+
+- [ ] Email verification flow
+- [ ] Rate limiting middleware
+
+### Key Decisions
+
+- JWT expiry: 15 minutes (refresh: 7 days)
+- Password hashing: bcrypt with 12 rounds
+- Session storage: Redis (not in-memory)
+```
+
+### For Debugging
+
+```markdown
+## Debug Summary: [Issue]
+
+### Symptoms
+
+- Error: "TypeError: Cannot read property 'id' of undefined"
+- Location: src/auth/middleware.ts:42
+- Trigger: POST /api/protected when token is expired
+
+### Root Cause
+
+- Token validation returns null on expired tokens
+- Middleware assumes valid token object, no null check
+- Race condition: token expires between validation and use
+
+### Fix Applied
+
+- Added null check in middleware (src/auth/middleware.ts:42)
+- Added token refresh attempt before rejecting (src/auth/refresh.ts)
+- Added test for expired token scenario (src/auth/**tests**/middleware.test.ts)
+
+### Verification
+
+- Tests: ✅ all passing including new test
+- Manual: ✅ expired token now triggers refresh
+```
+
+## Session Handoff Protocol
+
+When you must hand off to a new session:
+
+### 1. Create Handoff Document
+
+```typescript
+memory -
+  update({
+    file: "handoffs/YYYY-MM-DD-feature-name",
+    content: `# Session Handoff: [Feature Name]
+
+## Context
+[Why this session started, what was the goal]
+
+## Completed Work
+[What was done, files changed, decisions made]
+
+## Current State
+[Where things stand right now]
+
+## Remaining Work
+[What still needs to be done]
+
+## Key Decisions
+[Important choices made and why]
+
+## Files Modified
+[List of all files changed with brief description]
+
+## Gotchas
+[Things the next session should know]
+  `,
+    mode: "replace",
+  });
+```
+
+### 2. Save Key Observations
+
+```typescript
+observation({
+  type: "decision",
+  title: "Auth implementation approach",
+  narrative: "Chose JWT with Redis sessions because...",
+  facts: "JWT 15min expiry, Redis 24h TTL, bcrypt 12 rounds",
+  concepts: "authentication, sessions, tokens",
+  confidence: "high",
+});
+```
+
+### 3. Resume in New Session
+
+```typescript
+// In new session:
+memory - read({ file: "handoffs/YYYY-MM-DD-feature-name" });
+memory - search({ query: "auth implementation" });
+```
+
+## Integration with DCP Plugin
+
+This project uses `@tarquinen/opencode-dcp` for always-on context management (injected via `experimental.chat.system.transform`):
+
+- **compress**: Phase-level conversation compression (primary DCP tool in the installed beta)
+- **/dcp sweep**: Cleanup command for stale/noisy content after a phase is complete
+- **Prunable-tools list**: Auto-injected into messages with token estimates
+- **Nudge system**: Reminders every N tool calls + critical limit warnings
+
+**Division of responsibility:**
+
+- **DCP plugin**: Context budget rules, tool guidance, prunable-tools list, nudges (always present via system prompt)
+- **Compaction plugin** (`.opencode/plugin/compaction.ts`): Session continuity, beads state, handoff recovery, post-compaction protocol (fires during compaction events only)
+
+## Anti-Patterns
+
+### ❌ Premature Compaction
+
+```
+// DON'T compress a file you're about to edit
+compress({ ... })  // Loses exact line numbers you need
+edit({ ... })      // Now you can't find the right location
+```
+
+**Fix**: Keep raw content while actively editing. Compress AFTER the edit phase.
+
+### ❌ Compressing Active Work
+
+```
+// DON'T compress a conversation phase you might return to
+compress({ summary: "Explored auth options" })
+// Later: "Wait, which options did we consider?"
+```
+
+**Fix**: Only compress CLOSED chapters where findings are crystallized.
+
+### ❌ Ignoring Context Growth
+
+```
+// DON'T let context grow unchecked until hitting limits
+// By the time you notice, emergency compaction loses information
+```
+
+**Fix**: Monitor regularly. Compress at natural breakpoints and use `/dcp sweep` after closed phases.
+
+## Checklist
+
+Before compacting:
+
+- [ ] Identified what type of content is consuming context
+- [ ] Chosen appropriate strategy (compress/sweep/handoff)
+- [ ] Verified raw content is no longer needed for active work
+- [ ] Captured all key details in the compression summary or handoff
+- [ ] Saved important decisions as observations
+- [ ] Created handoff document if switching sessions
+
+During long sessions:
+
+- [ ] Compressing completed phases at natural breakpoints
+- [ ] Sweeping stale/noisy outputs after phase completion
+- [ ] Monitoring context usage trends
+- [ ] Planning session handoff if approaching limits

package/baseline/skill/condition-based-waiting/SKILL.md

@@ -0,0 +1,123 @@
+---
+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
+
+## 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/baseline/skill/condition-based-waiting/example.ts

@@ -0,0 +1,158 @@
+// Complete implementation of condition-based waiting utilities
+// From: Lace test infrastructure improvements (2025-10-03)
+// Context: Fixed 15 flaky tests by replacing arbitrary timeouts
+
+import type { ThreadManager } from "~/threads/thread-manager";
+import type { LaceEvent, LaceEventType } from "~/threads/types";
+
+/**
+ * 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