liteagents 2.8.3 → 2.10.0

package/packages/claude/skills/{testing-anti-patterns → test-traps}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: testing-anti-patterns
+name: test-traps
 description: Use when writing or changing tests, adding mocks, or tempted to add test-only methods to production code - prevents testing mock behavior, production pollution with test-only methods, and mocking without understanding dependencies
-usage: /testing-anti-patterns <testing-scenario>
+usage: /test-traps <testing-scenario>
 auto_trigger: true
 ---
 
-# Testing Anti-Patterns
+# Test Traps
 
 ## Overview
 
@@ -253,6 +253,79 @@ TDD cycle:
 4. THEN claim complete
 ```
 
+## Anti-Pattern 6: Timeout-Based Waiting
+
+**The violation:**
+```typescript
+// Wait an arbitrary amount of time, then check
+await new Promise(r => setTimeout(r, 50));
+const result = getResult();
+expect(result).toBeDefined();
+```
+
+```python
+time.sleep(0.5)
+assert get_result() is not None
+```
+
+**Why this is wrong:**
+- Passes on fast machines, fails in CI under load (or vice versa).
+- Either too short (flaky) or too long (slow suite) — every value is wrong somewhere.
+- Hides the actual condition the test cares about.
+- A real bug in the async machinery looks identical to a "too-short sleep."
+
+**The fix — poll for the actual condition:**
+```typescript
+await waitFor(() => getResult() !== undefined);
+const result = getResult();
+expect(result).toBeDefined();
+```
+
+| 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)` |
+
+Minimal generic poller:
+```typescript
+async function waitFor<T>(
+  condition: () => T | undefined | null | false,
+  description = 'condition',
+  timeoutMs = 5000
+): Promise<T> {
+  const start = Date.now();
+  while (true) {
+    const result = condition();
+    if (result) return result;
+    if (Date.now() - start > timeoutMs) {
+      throw new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`);
+    }
+    await new Promise(r => setTimeout(r, 10));
+  }
+}
+```
+
+See `example.ts` for domain-specific helpers (`waitForEvent`, `waitForEventCount`, `waitForEventMatch`) drawn from a real debugging session.
+
+**Polling pitfalls:**
+- **Polling too fast** (`setTimeout(check, 1)`) wastes CPU. **Fix:** poll every ~10ms.
+- **No timeout** means a never-met condition hangs the suite forever. **Fix:** always include a timeout with a descriptive error.
+- **Stale data** — if you read state once before the loop, you'll never see updates. **Fix:** call the getter *inside* the loop.
+
+**When an arbitrary timeout IS correct:**
+```typescript
+// Tool ticks every 100ms; observe 2 ticks of partial output.
+await waitForEvent(manager, 'TOOL_STARTED'); // condition first
+await new Promise(r => setTimeout(r, 200));  // then a documented, calculated wait
+// 200ms = 2 ticks at the documented 100ms cadence
+```
+Requirements: (1) wait for the triggering condition first, (2) the delay is based on a *known* interval (not a guess), (3) a comment explains why a sleep is correct here.
+
+**Real-world impact** (debugging session, 2025-10-03): 15 flaky tests across 3 files, pass rate 60% → 100%, suite 40% faster, race conditions gone.
+
 ## When Mocks Become Too Complex
 
 **Warning signs:**
@@ -284,6 +357,7 @@ TDD cycle:
 | Mock without understanding | Understand dependencies first, mock minimally |
 | Incomplete mocks | Mirror real API completely |
 | Tests as afterthought | TDD - tests first |
+| Timeout-based waiting | Poll for the actual condition with `waitFor()` |
 | Over-complex mocks | Consider integration tests |
 
 ## Red Flags

package/packages/claude/skills/{root-cause-tracing → trace-back}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: root-cause-tracing
+name: trace-back
 description: Use when errors occur deep in execution and you need to trace back to find the original trigger - systematically traces bugs backward through call stack, adding instrumentation when needed, to identify source of invalid data or incorrect behavior
-usage: /root-cause-tracing <issue-description>
+usage: /trace-back <issue-description>
 auto_trigger: false
 ---
 
-# Root Cause Tracing
+# Trace Back
 
 ## Overview
 

package/packages/claude/skills/{verification-before-completion → verify-done}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: verification-before-completion
+name: verify-done
 description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
-usage: /verification-before-completion <work-to-verify>
+usage: /verify-done <work-to-verify>
 auto_trigger: true
 ---
 
-# Verification Before Completion
+# Verify Done
 
 ## Auto-Trigger
 

package/packages/droid/AGENTS.md

@@ -22,33 +22,27 @@ These subagents are available when using Claude Code CLI. Droid can reference th
 | system-architect | Architect | Use for system design, architecture documents, technology selection, API design, and infrastructure planning |
 | ui-designer | UX Expert | Use for UI/UX design, wireframes, prototypes, front-end specifications, and user experience optimization |
 
-## Droid Commands (22 total)
+## Droid Commands (17 total)
 
 | ID | Description | Usage | Auto |
 |---|---|---|---|
 | brainstorming | Refines rough ideas into fully-formed designs through collaborative questioning | /brainstorming <session-type> <topic> | false |
-| code-review | Reviews implementation against plan or requirements before proceeding | /code-review <review-scope> <focus-areas> | false |
-| condition-based-waiting | Replaces arbitrary timeouts with condition polling to wait for actual state changes | /condition-based-waiting <condition-type> <timeout-specs> | false |
-| debug | Debug an issue systematically using structured investigation techniques | /debug <issue-description> | - |
 | docs-builder | Create comprehensive project documentation with structured /docs hierarchy | /docs-builder | false |
-| explain | Explain code for someone new to the codebase | /explain <code-section> | - |
-| friction | Analyze session logs for failure patterns and behavioral signals | /friction <sessions-path> | - |
-| git-commit | Analyze changes and create intelligent git commits | /git-commit | - |
 | live-canvas | Design UI variations and collect click-to-annotate feedback from the browser (batch mode only on Droid) | /live-canvas | false |
 | optimize | Analyze and optimize performance issues | /optimize <target-area> | - |
 | refactor | Refactor code while maintaining behavior and tests | /refactor <code-section> | - |
 | remember | Consolidate stashes + friction into project memory | /remember | - |
-| review | Comprehensive code review including quality, tests, and architecture | /review | - |
-| root-cause-tracing | Systematically traces bugs backward through call stack to identify source | /root-cause-tracing <issue-description> | false |
+| diff-review | Comprehensive code review including quality, tests, and architecture | /diff-review | - |
+| trace-back | Systematically traces bugs backward through call stack to identify source | /trace-back <issue-description> | false |
 | security | Security vulnerability scan and analysis | /security | - |
 | ship | Pre-deployment verification checklist | /ship | - |
 | skill-creator | Guide for creating effective skills and extending Claude capabilities | /skill-creator <skill-type> <skill-description> | false |
 | stash | Save session context for compaction recovery or handoffs | /stash ["optional-name"] | - |
-| systematic-debugging | Four-phase debugging framework - investigate root cause before any fixes | /systematic-debugging <bug-or-error-description> | false |
-| test-driven-development | Write test first, watch it fail, write minimal code to pass | /test-driven-development <feature-or-behavior-to-test> | true |
-| test-generate | Generate comprehensive test suites for existing code | /test-generate <code-section> | - |
-| testing-anti-patterns | Prevents testing mock behavior and production pollution with test-only methods | /testing-anti-patterns <testing-scenario> | true |
-| verification-before-completion | Requires running verification commands before making any success claims | /verification-before-completion <work-to-verify> | true |
+| debug-method | Four-phase debugging framework - investigate root cause before any fixes | /debug-method <bug-or-error-description> | false |
+| tdd-flow | Write test first, watch it fail, write minimal code to pass | /tdd-flow <feature-or-behavior-to-test> | true |
+| test-generate | Generate tests, run them, verify each one actually exercises the code | /test-generate <file> | - |
+| test-traps | Prevents testing mock behavior and production pollution with test-only methods | /test-traps <testing-scenario> | true |
+| verify-done | Requires running verification commands before making any success claims | /verify-done <work-to-verify> | true |
 
 All resources are auto-discovered from frontmatter in their respective directories:
 - **Agents**: `./droids/*.md`

package/packages/{opencode/command/systematic-debugging.md → droid/commands/debug-method.md}

@@ -1,11 +1,11 @@
 ---
-name: systematic-debugging
+name: debug-method
 description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes - four-phase framework (root cause investigation, pattern analysis, hypothesis testing, implementation) that ensures understanding before attempting solutions
-usage: /systematic-debugging <bug-or-error-description>
+usage: /debug-method <bug-or-error-description>
 auto_trigger: false
 ---
 
-# Systematic Debugging
+# Debug Method
 
 ## Overview
 
@@ -113,7 +113,7 @@ You MUST complete each phase before proceeding to the next.
 
    **WHEN error is deep in call stack:**
 
-   **REQUIRED SUB-SKILL:** Use root-cause-tracing for backward tracing technique
+   **REQUIRED SUB-SKILL:** Use trace-back for backward tracing technique
 
    **Quick version:**
    - Where does bad value originate?
@@ -178,7 +178,7 @@ You MUST complete each phase before proceeding to the next.
    - Automated test if possible
    - One-off test script if no framework
    - MUST have before fixing
-   - **REQUIRED SUB-SKILL:** Use test-driven-development for writing proper failing tests
+   - **REQUIRED SUB-SKILL:** Use tdd-flow for writing proper failing tests
 
 2. **Implement Single Fix**
    - Address the root cause identified
@@ -280,13 +280,13 @@ If systematic investigation reveals issue is truly environmental, timing-depende
 ## Integration with Other Skills
 
 **This skill requires using:**
-- **root-cause-tracing** - REQUIRED when error is deep in call stack (see Phase 1, Step 5)
-- **test-driven-development** - REQUIRED for creating failing test case (see Phase 4, Step 1)
+- **trace-back** - REQUIRED when error is deep in call stack (see Phase 1, Step 5)
+- **tdd-flow** - REQUIRED for creating failing test case (see Phase 4, Step 1)
 
 **Complementary skills:**
 - **defense-in-depth** - Add validation at multiple layers after finding root cause
-- **condition-based-waiting** - Replace arbitrary timeouts identified in Phase 2
-- **verification-before-completion** - Verify fix worked before claiming success
+- **test-traps** (Anti-Pattern 6) - Replace arbitrary timeouts identified in Phase 2
+- **verify-done** - Verify fix worked before claiming success
 
 ## Real-World Impact
 

package/packages/droid/commands/diff-review.md

@@ -0,0 +1,78 @@
+---
+name: diff-review
+description: Review diff [file, branch, or range]
+usage: /diff-review
+argument-hint: [file, branch (e.g. main), range (main..HEAD), or empty]
+allowed-tools: Read, Edit, Grep, Glob, Bash(git diff *), Bash(git log *), Bash(git show *), Bash(git status *), Bash(git grep *), Bash(git rev-parse *), Bash(git merge-base *), Bash(rg *)
+---
+Review $ARGUMENTS. Interpret in this order:
+1. **Empty** → staged diff (`git diff --staged`); if empty, working-tree diff
+   (`git diff`).
+2. **A range** like `main..HEAD` or `origin/main...HEAD` → `git diff <range>`.
+3. **A single ref** (branch / tag / SHA — confirm with `git rev-parse
+   --verify`) → diff that ref's merge-base against `HEAD` (i.e. everything on
+   the current branch since it diverged: `git diff $(git merge-base <ref>
+   HEAD)..HEAD`). This is the common "review my branch before merging" path.
+4. **A file or directory path** → that target.
+5. Otherwise → ask.
+
+The diff is the subject; widen to surrounding code only as needed to judge a
+hunk. For multi-commit ranges, also skim `git log <range>` to understand
+intent before judging.
+
+## Check For
+- **Bugs needing a fix.** Logic errors, off-by-one, null/undefined paths,
+  races, wrong defaults, broken edge cases. Concrete failure modes only — not
+  vibes.
+- **Dead code.** Unreferenced functions / vars / imports / params, unreachable
+  branches, commented-out blocks, legacy paths the diff just obsoleted.
+  `git grep` the symbol before flagging — easy to be wrong.
+- **Loose ends.** TODO / FIXME / XXX added by this diff, half-finished
+  branches, silently swallowed errors, stub bodies, mocked-out paths,
+  "temporary" names, abandoned feature flags.
+- **Correctness.** Edge cases, error handling, type / contract violations,
+  broken invariants.
+- **Security.** OWASP Top 10, auth, data exposure. (`/security` for depth.)
+- **Performance.** N+1, blocking calls in hot paths, unbounded loops, indexes
+  the diff actually touches.
+- **Maintainability.** Complexity, naming, duplication — only when material.
+
+## Output Format
+### 🚨 Critical (blocks merge)
+### ⚠️ Warnings (should fix)
+### 💡 Suggestions (nice to have)
+
+Each finding: **Location** (`file:line`), **What's wrong**, **Why it matters**,
+**Concrete fix** — not "consider improving".
+
+## After the review — verify, then fix
+
+Findings are claims, not facts. Validate before acting; validate again after.
+
+**Verify each claim.** Re-read the cited `file:line` in context. For
+dead-code or unused-symbol claims, `git grep` the name across the repo before
+trusting it. Mark each **confirmed**, **false positive** (with reason), or
+**uncertain**.
+
+**Fix what's confirmed and unambiguous** — minimal shape, one obvious way, no
+change to a public API / response / caller contract. Apply directly. After
+each edit, re-read the changed region and confirm it does what you intended
+without breaking nearby logic. A fix isn't done until you've grounded it the
+same way you grounded the claim.
+
+**Stop and ask** when any of these hold (HITL gates — not all the time, only
+here):
+- the finding is **uncertain** after grounding,
+- the fix has **multiple reasonable shapes** (e.g. delete-vs-keep-behind-flag,
+  extract-vs-inline, patch-vs-rewrite) — present options with tradeoffs, not a
+  chosen path,
+- it **affects downstream** (signatures, response shape, schema, any caller
+  contract) or removes a public/exported symbol, or
+- the "dead code" looks intentionally kept (stub for upcoming work, framework
+  hook, documented extension point) — confirm before deleting.
+
+Final report: **confirmed-and-fixed** · **confirmed-but-asking** (why +
+options) · **false-positive** (why) · **uncertain** (what's needed to decide).
+
+End with a one-line verdict: **Ready to merge? Yes / No / With fixes** — and
+the reason in a sentence.