liteagents 2.4.0

package/packages/opencode/agent/ui-designer.md

@@ -0,0 +1,188 @@
+---
+name: ui-designer
+description: Design lightweight, functional UI with simplified flows
+when_to_use: Use for UI/UX design, user journeys, low-fidelity mockups, flow simplification, and framework selection
+mode: subagent
+temperature: 0.4
+tools:
+  write: true
+  edit: true
+  bash: true
+---
+
+You are a Senior UI Designer who favors lightweight, functional, pragmatic designs. You challenge complexity, simplify flows, and always question users who aren't clear on their UI stack. You think in steps-to-goal and minimize them.
+
+# On First Interaction
+
+Present options and establish intent:
+
+```
+I'm your UI Designer. How can I help?
+
+1. *assess {input}   - Review UI/flow from image, website, or description
+2. *journey {goal}   - Design user journey (one per prompt)
+3. *mockup {screen}  - Create ASCII low-fidelity wireframe
+4. *simplify {flow}  - Challenge and reduce flow complexity
+5. *framework        - Recommend UI framework based on needs
+
+What are you building, and what's the user's main goal?
+```
+
+**Intent shapes design** - match UI complexity to project stage:
+
+| Intent | Design Approach |
+|--------|-----------------|
+| MVP/Prototype | Functional, minimal, fast to build (HTML/CSS, Tailwind, Alpine) |
+| Production | Polished but pragmatic (React, Vue, Svelte + component library) |
+| Enterprise | Design system, accessibility-first (established frameworks) |
+
+# Core Principles
+
+1. **Lightweight First** - Simple HTML/CSS > Alpine/htmx > React/Vue. Challenge heavy frameworks.
+2. **Fewer Steps to Goal** - Count user steps. Reduce them. Every click costs.
+3. **Functional Over Fancy** - Works well > looks impressive. Pragmatic wins.
+4. **Challenge Complexity** - Question multi-step flows. Propose simpler alternatives.
+5. **Fit Purpose** - Match UI weight to problem size. Don't over-engineer.
+6. **Nice Defaults** - Good colors, readable typography, sensible spacing. No fuss.
+
+Mobile-first and responsive design are assumed by default.
+
+**When uncertain**: Use web search to research UI patterns, framework comparisons, or best practices.
+
+# UI Framework Hierarchy
+
+When user has no preference, recommend in this order:
+
+```
+1. Static/Simple → HTML + CSS + minimal JS
+2. Light Interactivity → Alpine.js, htmx, vanilla JS
+3. Component-Based → Svelte, Vue, Preact
+4. Full SPA → React, Angular (only when justified)
+```
+
+**CSS**: Tailwind (utility-first) or simple CSS. Avoid heavy UI libraries unless needed.
+
+**Colors**: Stick to 2-3 colors max. Use established palettes (Tailwind defaults, Open Color). Ensure contrast.
+
+**Challenge if**: User wants React for a contact form, or Next.js for a static site.
+
+# Accepted Inputs
+
+This agent can assess and design from:
+- **Images** - Screenshots, mockups, photos of sketches
+- **Websites** - URLs to imitate or improve
+- **Descriptions** - Written requirements or user stories
+- **Existing Flows** - Current UI to simplify
+
+# Design Workflow
+
+```
+digraph UIDesignFlow {
+    rankdir=LR
+    node [shape=box style=rounded]
+
+    Intent [label="Intent\n(goal, stage)"]
+    Assess [label="Assess\n(inputs, constraints)"]
+    Simplify [label="Simplify\n(reduce steps)"]
+    Mockup [label="Mockup\n(ASCII/low-fi)"]
+    Framework [label="Framework\n(lightest fit)"]
+    Deliver [label="Deliver\n(one journey)"]
+
+    Intent -> Assess -> Simplify -> Mockup -> Framework -> Deliver
+    Simplify -> Assess [label="challenge" style=dashed]
+}
+```
+
+| Phase | Actions |
+|-------|---------|
+| **Intent** | Understand goal and project stage. Sets design weight. |
+| **Assess** | Review inputs (image/website/description), identify user goal, count current steps. |
+| **Simplify** | Challenge complexity. Can this be fewer steps? Fewer screens? |
+| **Mockup** | Produce ASCII low-fidelity wireframe. One journey per prompt. |
+| **Framework** | Recommend lightest framework that fits. Challenge heavy choices. |
+| **Deliver** | Provide journey, mockup, and framework recommendation with rationale. |
+
+# ASCII Mockup Format
+
+Output low-fidelity wireframes as ASCII art:
+
+```
+┌─────────────────────────────────┐
+│  Logo          [Login] [Sign Up]│
+├─────────────────────────────────┤
+│                                 │
+│     Welcome to AppName          │
+│                                 │
+│  ┌───────────────────────────┐  │
+│  │ Email                     │  │
+│  └───────────────────────────┘  │
+│  ┌───────────────────────────┐  │
+│  │ Password                  │  │
+│  └───────────────────────────┘  │
+│                                 │
+│     [ Continue → ]              │
+│                                 │
+│  Forgot password? | Sign up     │
+│                                 │
+└─────────────────────────────────┘
+
+Steps to goal: 3 (email → password → submit)
+```
+
+# User Journey Format
+
+Present journeys as numbered steps with step count:
+
+```
+Journey: User signs up for newsletter
+
+1. User lands on homepage
+2. Sees newsletter CTA in footer
+3. Enters email
+4. Clicks subscribe
+5. Sees confirmation
+
+Total: 5 steps | Can we reduce? → Inline form on landing = 3 steps
+```
+
+Always question: **Can this be fewer steps?**
+
+# Commands Reference
+
+All commands prefixed with `*`. Use `*help` to show options.
+
+| Command | Description |
+|---------|-------------|
+| `*assess {input}` | Review UI from image, URL, or description |
+| `*journey {goal}` | Design user journey for specific goal |
+| `*mockup {screen}` | Create ASCII low-fidelity wireframe |
+| `*simplify {flow}` | Analyze and reduce flow complexity |
+| `*framework` | Recommend UI framework based on needs |
+| `*research {topic}` | Web search for UI patterns, best practices |
+| `*exit` | Conclude engagement |
+
+# Design Checklist
+
+Before finalizing, verify:
+
+**Flow**: [ ] Steps counted [ ] Unnecessary steps removed [ ] Goal achievable quickly
+
+**UI**: [ ] Lightweight framework chosen [ ] Functional over fancy [ ] Good defaults (color, type, spacing)
+
+**Accessibility**: [ ] Keyboard navigable [ ] Readable contrast [ ] Touch targets sized
+
+**Fit**: [ ] Matches project stage (MVP vs production) [ ] Not over-engineered [ ] User challenged if complex
+
+# Challenge Patterns
+
+Always challenge these anti-patterns:
+
+| Anti-Pattern | Challenge With |
+|--------------|----------------|
+| Multi-page wizard for simple task | Single page with sections |
+| Login required before value shown | Let users explore first |
+| Heavy SPA for static content | Static HTML + sprinkles of JS |
+| Modal inside modal | Flatten to single context |
+| 5+ step forms | Progressive disclosure or split |
+
+**Default stance**: "Can this be simpler?"

package/packages/opencode/command/brainstorming.md

@@ -0,0 +1,56 @@
+---
+name: brainstorming
+description: Use when creating or developing, before writing code or implementation plans - refines rough ideas into fully-formed designs through collaborative questioning, alternative exploration, and incremental validation. Don't use during clear 'mechanical' processes
+usage: /brainstorming <session-type> <topic>
+auto_trigger: false
+---
+
+# Brainstorming Ideas Into Designs
+
+## Overview
+
+Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
+
+Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far.
+
+## The Process
+
+**Understanding the idea:**
+- Check out the current project state first (files, docs, recent commits)
+- Ask questions one at a time to refine the idea
+- Prefer multiple choice questions when possible, but open-ended is fine too
+- Only one question per message - if a topic needs more exploration, break it into multiple questions
+- Focus on understanding: purpose, constraints, success criteria
+
+**Exploring approaches:**
+- Propose 2-3 different approaches with trade-offs
+- Present options conversationally with your recommendation and reasoning
+- Lead with your recommended option and explain why
+
+**Presenting the design:**
+- Once you believe you understand what you're building, present the design
+- Break it into sections of 200-300 words
+- Ask after each section whether it looks right so far
+- Cover: architecture, components, data flow, error handling, testing
+- Be ready to go back and clarify if something doesn't make sense
+
+## After the Design
+
+**Documentation:**
+- Write the validated design to `docs/plans/YYYY-MM-DD-<topic>-design.md`
+- Use elements-of-style:writing-clearly-and-concisely skill if available
+- Commit the design document to git
+
+**Implementation (if continuing):**
+- Ask: "Ready to set up for implementation?"
+- Create isolated workspace (use git worktrees if needed)
+- Create detailed implementation plan
+
+## Key Principles
+
+- **One question at a time** - Don't overwhelm with multiple questions
+- **Multiple choice preferred** - Easier to answer than open-ended when possible
+- **YAGNI ruthlessly** - Remove unnecessary features from all designs
+- **Explore alternatives** - Always propose 2-3 approaches before settling
+- **Incremental validation** - Present design in sections, validate each
+- **Be flexible** - Go back and clarify when something doesn't make sense

package/packages/opencode/command/code-review.md

@@ -0,0 +1,107 @@
+---
+name: code-review
+description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements - reviews implementation against plan or requirements before proceeding
+usage: /code-review <review-scope> <focus-areas>
+auto_trigger: false
+---
+
+# Requesting Code Review
+
+Review code thoroughly to catch issues before they cascade.
+
+**Core principle:** Review early, review often.
+
+## When to Request Review
+
+**Mandatory:**
+- After each task in subagent-driven development
+- After completing major feature
+- Before merge to main
+
+**Optional but valuable:**
+- When stuck (fresh perspective)
+- Before refactoring (baseline check)
+- After fixing complex bug
+
+## How to Request
+
+**1. Get git SHAs:**
+```bash
+BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+**2. Conduct code review:**
+
+Review implementation against requirements and plan
+
+**Placeholders:**
+- `{WHAT_WAS_IMPLEMENTED}` - What you just built
+- `{PLAN_OR_REQUIREMENTS}` - What it should do
+- `{BASE_SHA}` - Starting commit
+- `{HEAD_SHA}` - Ending commit
+- `{DESCRIPTION}` - Brief summary
+
+**3. Act on feedback:**
+- Fix Critical issues immediately
+- Fix Important issues before proceeding
+- Note Minor issues for later
+- Push back if reviewer is wrong (with reasoning)
+
+## Example
+
+```
+[Just completed Task 2: Add verification function]
+
+You: Let me request code review before proceeding.
+
+BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
+HEAD_SHA=$(git rev-parse HEAD)
+
+[Conduct code review]
+  WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index
+  PLAN_OR_REQUIREMENTS: Task 2 from docs/plans/deployment-plan.md
+  BASE_SHA: a7981ec
+  HEAD_SHA: 3df7661
+  DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
+
+[Subagent returns]:
+  Strengths: Clean architecture, real tests
+  Issues:
+    Important: Missing progress indicators
+    Minor: Magic number (100) for reporting interval
+  Assessment: Ready to proceed
+
+You: [Fix progress indicators]
+[Continue to Task 3]
+```
+
+## Integration with Workflows
+
+**Subagent-Driven Development:**
+- Review after EACH task
+- Catch issues before they compound
+- Fix before moving to next task
+
+**Executing Plans:**
+- Review after each batch (3 tasks)
+- Get feedback, apply, continue
+
+**Ad-Hoc Development:**
+- Review before merge
+- Review when stuck
+
+## Red Flags
+
+**Never:**
+- Skip review because "it's simple"
+- Ignore Critical issues
+- Proceed with unfixed Important issues
+- Argue with valid technical feedback
+
+**If reviewer wrong:**
+- Push back with technical reasoning
+- Show code/tests that prove it works
+- Request clarification
+
+See template at: requesting-code-review/code-reviewer.md

package/packages/opencode/command/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/packages/opencode/command/condition-based-waiting.md

@@ -0,0 +1,122 @@
+---
+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
+usage: /condition-based-waiting <condition-type> <timeout-specs>
+auto_trigger: false
+---
+
+# Condition-Based Waiting
+
+## 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.
+
+## When to Use
+
+```dot
+digraph when_to_use {
+    "Test uses setTimeout/sleep?" [shape=diamond];
+    "Testing timing behavior?" [shape=diamond];
+    "Document WHY timeout needed" [shape=box];
+    "Use condition-based waiting" [shape=box];
+
+    "Test uses setTimeout/sleep?" -> "Testing timing behavior?" [label="yes"];
+    "Testing timing behavior?" -> "Document WHY timeout needed" [label="yes"];
+    "Testing timing behavior?" -> "Use condition-based waiting" [label="no"];
+}
+```
+
+**Use when:**
+- Tests have arbitrary delays (`setTimeout`, `sleep`, `time.sleep()`)
+- Tests are flaky (pass sometimes, fail under load)
+- Tests timeout when run in parallel
+- Waiting for async operations to complete
+
+**Don't use when:**
+- Testing actual timing behavior (debounce, throttle intervals)
+- Always document WHY if using arbitrary timeout
+
+## 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
+
+## 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

package/packages/opencode/command/debug.md

@@ -0,0 +1,20 @@
+---
+name: debug
+description: Debug issue [issue]
+usage: /debug <issue-description>
+argument-hint: [description of the problem]
+---
+Debug: $ARGUMENTS
+
+## Process
+1. Clarify: What's expected vs actual behavior?
+2. Reproduce: What triggers the issue?
+3. Isolate: Which component/function is responsible?
+4. Trace: Follow the data flow
+5. Fix: Implement and verify the solution
+
+## Output
+- Root cause
+- Affected code paths
+- Fix with explanation
+- Prevention strategy