@ultrakit/ultrakit 0.0.0

package/dist/template/.opencode/skill/code-simplification/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: code-simplification
+description: Use when reducing code complexity, eliminating dead code, or refactoring for clarity — enforces measure-before-cutting discipline to prevent breaking changes disguised as cleanup
+version: 1.0.0
+tags: [code-quality, refactoring]
+dependencies: [verification-before-completion]
+---
+
+# Code Simplification
+
+> **Replaces** ad-hoc "cleanup" refactors that introduce bugs — enforces systematic simplification with verification at every step
+
+## When to Use
+
+- Code is harder to understand than it needs to be
+- Functions are too long (>50 lines), files are too large (>500 lines)
+- Dead code, unused imports, or unnecessary abstractions exist
+- You're asked to "clean up" or "simplify" a module
+- Complexity is making bugs harder to fix
+
+## When NOT to Use
+
+- The code works, is readable, and isn't blocking anything — leave it alone
+- You're implementing a new feature (use incremental-implementation instead)
+- The "simplification" is actually a rewrite with different behavior
+
+## Common Rationalizations
+
+| Rationalization                        | Rebuttal                                                                                 |
+| -------------------------------------- | ---------------------------------------------------------------------------------------- |
+| "This code is ugly, let me rewrite it" | Ugly but working > beautiful but broken. Simplify incrementally, not wholesale           |
+| "Nobody uses this, I'll delete it"     | Verify with grep/find-references FIRST. "Nobody uses this" is the #1 cause of breakage   |
+| "I'll simplify it while I'm in here"   | Mixing feature work with refactoring makes both harder to review and revert              |
+| "This abstraction isn't needed"        | Check if it serves a testing, extension, or boundary purpose before removing             |
+| "I can make this more elegant"         | Elegant for whom? Optimize for the next reader, not for cleverness                       |
+| "The tests will catch any issues"      | Tests cover known behavior. Simplification can change behavior in ways tests don't cover |
+
+## Overview
+
+Code simplification is the discipline of making code easier to understand and maintain WITHOUT changing its behavior. The key word is discipline — undisciplined simplification introduces bugs.
+
+**Core principle:** Measure complexity, simplify the worst offender, verify nothing broke, repeat.
+
+## The Process
+
+```
+1. MEASURE  — Identify what's actually complex (not just what feels complex)
+2. ISOLATE  — Pick ONE simplification target
+3. VERIFY   — Ensure tests exist for current behavior
+4. SIMPLIFY — Apply the smallest change that reduces complexity
+5. CONFIRM  — Run full verification to prove behavior is unchanged
+6. REPEAT   — Pick the next target
+```
+
+## Complexity Signals
+
+| Signal                | Threshold        | Action                                      |
+| --------------------- | ---------------- | ------------------------------------------- |
+| Function length       | >50 lines        | Extract helper functions                    |
+| File length           | >500 lines       | Split into modules                          |
+| Nesting depth         | >3 levels        | Flatten with early returns or extract       |
+| Parameter count       | >4 params        | Use an options object                       |
+| Cyclomatic complexity | >10 per function | Break into smaller functions                |
+| Dead code             | Any              | Remove after verifying with find-references |
+| Unused imports        | Any              | Remove (linter usually catches these)       |
+| Duplicate code        | 3+ copies        | Extract shared function                     |
+
+## Simplification Patterns
+
+### Extract Function
+
+```typescript
+// BEFORE: Long function with embedded logic
+function processOrder(order: Order) {
+  // 20 lines of validation
+  // 15 lines of pricing
+  // 10 lines of notification
+}
+
+// AFTER: Named steps
+function processOrder(order: Order) {
+  validateOrder(order);
+  const total = calculateTotal(order);
+  notifyCustomer(order, total);
+}
+```
+
+### Early Return (Flatten Nesting)
+
+```typescript
+// BEFORE: Deep nesting
+function getUser(id: string) {
+  if (id) {
+    const user = db.find(id);
+    if (user) {
+      if (user.active) {
+        return user;
+      }
+    }
+  }
+  return null;
+}
+
+// AFTER: Guard clauses
+function getUser(id: string) {
+  if (!id) return null;
+  const user = db.find(id);
+  if (!user) return null;
+  if (!user.active) return null;
+  return user;
+}
+```
+
+### Remove Dead Code
+
+```
+1. Search: grep/find-references for the symbol
+2. Verify: No callers exist (check tests too)
+3. Remove: Delete the code
+4. Confirm: All tests still pass
+```
+
+**NEVER assume code is dead without searching.** Check:
+
+- Direct calls
+- Dynamic references (string-based lookups, reflection)
+- Test-only usage
+- Configuration references
+
+### Inline Unnecessary Abstraction
+
+```typescript
+// BEFORE: Wrapper that adds nothing
+function getUserName(user: User): string {
+  return user.name;
+}
+
+// AFTER: Just use the property directly
+user.name;
+```
+
+Only inline if the abstraction doesn't serve a testing, boundary, or extension purpose.
+
+### Replace Conditional with Early Exit
+
+```typescript
+// BEFORE
+function handle(input: string) {
+  let result = "";
+  if (isValid(input)) {
+    result = transform(input);
+  } else {
+    throw new Error("Invalid");
+  }
+  return result;
+}
+
+// AFTER
+function handle(input: string) {
+  if (!isValid(input)) throw new Error("Invalid");
+  return transform(input);
+}
+```
+
+## What NOT to Simplify
+
+- **Working error handling** — even if verbose, it's there for a reason
+- **Compatibility shims** — they exist because something needs them
+- **Performance-critical paths** — "simpler" may mean "slower"
+- **Code with extensive test coverage pointing at specific behavior** — the tests document WHY it's complex
+- **Other people's current work** — don't simplify files with active PRs
+
+## Red Flags — STOP
+
+If you catch yourself:
+
+- Changing behavior while "simplifying"
+- Removing code without checking references first
+- Simplifying more than one thing per commit
+- "Cleaning up" files you weren't asked to touch
+- Making the code "more elegant" without a clear readability improvement
+
+**STOP.** Revert the current change and pick a smaller target.
+
+## Verification
+
+Before each simplification:
+
+```bash
+# Ensure tests exist for current behavior
+npm test -- --related [file]
+```
+
+After each simplification:
+
+```bash
+npm run typecheck
+npm run lint
+npm test
+```
+
+**If ANY test fails, the simplification changed behavior.** Either:
+
+1. The simplification is wrong — revert it
+2. The test is testing implementation details — fix the test, but document WHY
+
+## See Also
+
+- **incremental-implementation** — Build new features in slices; simplify afterward
+- **systematic-debugging** — When simplification reveals hidden bugs
+- **defense-in-depth** — When simplifying validation, ensure all layers still hold

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

@@ -0,0 +1,135 @@
+---
+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

@@ -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

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

@@ -0,0 +1,149 @@
+---
+name: context-condensation
+description: Use when context is approaching budget limits and you need to compress, OR when handing off to another session. Provides the explicit keep/drop rubric for what survives compression — preserve goals, progress, critical files, failing tests; drop exploration noise and resolved threads. Pairs with `/dcp compress` and `/handoff`. Adapted from OpenHands context-condensation, Manus context engineering, HumanLayer backpressure.
+---
+
+# Context Condensation
+
+> Compression is not deletion — it is **selection of what survives**. The wrong selection makes the agent restart from zero. This skill defines what to keep.
+
+## When to Use
+
+- Context >100k tokens and growing
+- Phase boundary reached (research done, ready to implement)
+- Handing off to a new session via `/handoff`
+- A subagent returns large output you need to integrate
+- After `/dcp compress` ran but you still feel context drift
+
+## Core Principle: 4 Tiers of Survival
+
+Every conversation chunk falls into one of four tiers. Compress accordingly.
+
+| Tier | Content                                                  | Action                  |
+| ---- | -------------------------------------------------------- | ----------------------- |
+| 1    | Goal, constraints, user-stated requirements              | **Preserve verbatim**   |
+| 2    | Critical state — failing tests, current bug, open files  | **Preserve as summary** |
+| 3    | Decisions made, alternatives rejected, why               | **Preserve as 1-liner** |
+| 4    | Exploration noise — failed greps, dead ends, raw outputs | **Drop entirely**       |
+
+## Keep List (Always)
+
+Compress around these — never drop:
+
+- **The user's literal request.** Direct quote when short. Paraphrase only when long, and label as paraphrase.
+- **Active failures.** Current error message, failing test name + reason, open bug. Tells the next agent what's broken.
+- **Decisions + rationale.** "Chose JWT over sessions because [reason]." One line each. Future agents inherit the why.
+- **File paths currently being edited.** Exact paths, not "the auth file".
+- **Verification status.** Last typecheck/lint/test result with timestamp.
+- **Open questions for the user.** Questions awaiting human input.
+- **Constraints discovered mid-task.** "User can't add new deps", "DB is read-only in this env".
+
+## Drop List (Aggressive)
+
+Compress these to a single line or remove entirely:
+
+- **Resolved exploration.** Found the file? Drop the 5 greps that led there.
+- **Tool output noise.** Full directory listings, `ls` outputs, package install logs. Keep only the relevant filename.
+- **Verbose reasoning.** Your own multi-paragraph thinking that ended in one decision. Keep the decision.
+- **Acknowledgments.** "Got it", "I'll do that next" — pure social filler.
+- **Failed attempts that taught nothing.** If a wrong approach added no information, drop it. Keep failures that revealed a constraint.
+- **Sub-agent self-reports.** Keep the result + verification, drop the agent's narrative summary (Worker Distrust Protocol — don't trust the prose).
+- **Old plans you've since revised.** Keep only the current plan.
+
+## Failure Preservation Rule
+
+> **Useful failures stay. Useless failures go.**
+
+A failure is **useful** if it:
+
+- Revealed a constraint ("can't use `mv` on this filesystem")
+- Eliminated a hypothesis ("the bug is not in the parser")
+- Showed a trap that another agent would re-fall into
+
+A failure is **useless** if it:
+
+- Was a typo / fat-finger fixed immediately
+- Was a tool-call format error with no semantic content
+- Was an obvious dead end no agent would repeat
+
+**Manus rule** (from "Context Engineering for AI Agents: Lessons from Building Manus"): keep useful failures **in-context** as warnings. Don't compress to "encountered errors then succeeded" — that loses the warning.
+
+## Condensation Triggers (Beyond Token Count)
+
+Token count is one trigger. These are the others:
+
+| Trigger                               | Action                                          |
+| ------------------------------------- | ----------------------------------------------- |
+| Phase boundary (research → implement) | Compress all of research phase to summary       |
+| Subagent returns >2k tokens           | Compress immediately, keep result + evidence    |
+| Same question asked twice in session  | Indicates context drift — compress aggressively |
+| Plan revised                          | Drop old plan completely                        |
+| Conversation feels "lost"             | Compress; restart from goal + current state     |
+
+## The Handoff Variant
+
+When compressing for `/handoff` (different session, different agent will pick up), be **even more selective**:
+
+- Preserve everything in Keep List
+- Add a **`## Next Step`** with the literal next action
+- Add a **`## Don't Re-Discover`** with traps already mapped
+- Drop everything else
+
+Handoff format:
+
+```markdown
+## Goal
+
+[user's literal request]
+
+## Status
+
+- Done: [list of completed items with file:line]
+- In progress: [current task]
+- Blocked: [what's blocking, what was tried]
+
+## Critical State
+
+- Open files: [paths]
+- Last verification: [command + result + timestamp]
+- Active failures: [error / failing test]
+
+## Decisions Made
+
+- [one-liner] → [one-line rationale]
+
+## Don't Re-Discover
+
+- [trap 1]: [why]
+- [trap 2]: [why]
+
+## Next Step
+
+[literal next action — copy-pastable command or description]
+```
+
+## Anti-Patterns
+
+- **"Let me summarize what we did so far..."** in every response — you're re-summarizing instead of compressing once at boundaries
+- **Dropping the goal during compression** — the worst failure mode; the next agent has no anchor
+- **Keeping all failures** — context fills with noise, real signals get buried
+- **Lossy paraphrase of user request** — when in doubt, quote verbatim
+- **Compressing during active edits** — wait for atomic step to finish
+
+## Integration
+
+- **Before `/dcp compress`:** Use this rubric to decide what your `summary` field should contain
+- **In `/handoff`:** This skill defines the handoff format
+- **After subagent return:** Apply Drop List to the agent's narrative, keep result + verification only
+- **In long sessions:** Re-read your own context every ~30 messages and apply the rubric
+
+## Output
+
+When you condense, briefly state what survived and what dropped:
+
+```
+Compressed messages 12-34. Kept: goal, 3 decisions, current failure (auth.ts:42 null deref).
+Dropped: 5 file searches, 2 abandoned approaches, dir listings.
+```
+
+This makes the compression auditable. The user (or next agent) can challenge what got cut.