liteagents 2.4.0

package/packages/droid/commands/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/droid/commands/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

package/packages/droid/commands/docs-builder/templates.md

@@ -0,0 +1,572 @@
+# Documentation Templates
+
+Detailed templates for each file in the /docs structure.
+
+## 00-context/vision.md
+
+```markdown
+# Vision
+
+## Problem
+[What problem does this solve? Who feels the pain?]
+
+## Solution
+[How does this product solve it?]
+
+## Target Users
+[Who is this for? Primary/secondary personas]
+
+## Boundaries
+### In Scope
+- [Feature/capability 1]
+- [Feature/capability 2]
+
+### Out of Scope
+- [What we explicitly won't do]
+- [Adjacent problems we're ignoring]
+
+## Success Metrics
+- [Metric 1: how measured]
+- [Metric 2: how measured]
+```
+
+## 00-context/assumptions.md
+
+```markdown
+# Assumptions & Risks
+
+## Technical Assumptions
+- [Assumption 1: e.g., "Users have Python 3.8+"]
+- [Assumption 2: e.g., "API response time < 200ms"]
+
+## Business Assumptions
+- [Assumption 1: e.g., "Users prefer CLI over GUI"]
+- [Assumption 2: e.g., "10K users within 6 months"]
+
+## Known Risks
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| [Risk description] | High/Med/Low | [How we handle it] |
+
+## Open Questions
+- [ ] [Question 1 that needs answering]
+- [ ] [Question 2 that blocks decisions]
+```
+
+## 00-context/system-state.md
+
+```markdown
+# System State
+
+## What's Implemented
+### Core Features
+- [Feature 1] - Status: ✅ Live | 🚧 In Progress | 📋 Planned
+- [Feature 2] - Status: [...]
+
+### Tech Stack
+- Language: [e.g., Python 3.11]
+- Frameworks: [e.g., FastAPI, React]
+- Database: [e.g., PostgreSQL 15]
+- Infrastructure: [e.g., AWS, Docker]
+
+## What's In Progress
+- [Feature/change being worked on]
+- [Expected completion: rough timeframe]
+
+## What's Planned
+- [Next feature to build]
+- [Roadmap item 2]
+
+## Known Issues
+- [Issue 1: description, severity]
+- [Issue 2: description, severity]
+```
+
+## 01-product/prd.md
+
+```markdown
+# Product Requirements Document
+
+## Problem Statement
+[Clear description of problem. 2-3 paragraphs max.]
+
+## User Personas
+### Primary: [Persona Name]
+- **Who**: [Role/description]
+- **Pain**: [Current problem]
+- **Goal**: [What they want to achieve]
+
+### Secondary: [Persona Name]
+[Same structure]
+
+## Features
+### Must Have (P0)
+1. **[Feature name]**
+   - Description: [What it does]
+   - User value: [Why it matters]
+   - Acceptance: [How we know it's done]
+
+### Should Have (P1)
+[Same structure]
+
+### Nice to Have (P2)
+[Same structure]
+
+## Non-Functional Requirements
+- Performance: [e.g., "API responds < 200ms p95"]
+- Security: [e.g., "OAuth2, encrypted at rest"]
+- Scalability: [e.g., "Handle 10K concurrent users"]
+- Reliability: [e.g., "99.9% uptime"]
+
+## Success Criteria
+- [ ] [Measurable criterion 1]
+- [ ] [Measurable criterion 2]
+
+## Out of Scope
+- [Explicitly excluded feature 1]
+- [Explicitly excluded feature 2]
+```
+
+## 02-features/feature-<name>/feature-spec.md
+
+```markdown
+# Feature: [Name]
+
+## User Intent
+**As a** [user type]
+**I want to** [action]
+**So that** [benefit]
+
+## User Stories
+1. **Story 1**: [Description]
+   - Acceptance: User can [specific action]
+   - Acceptance: System responds with [expected behavior]
+
+## Acceptance Criteria
+- [ ] [Criterion 1: testable condition]
+- [ ] [Criterion 2: testable condition]
+- [ ] [Criterion 3: testable condition]
+
+## Edge Cases
+- **Case 1**: [Scenario] → [Expected behavior]
+- **Case 2**: [Scenario] → [Expected behavior]
+
+## UI/UX Notes
+[Wireframes, mockups, or interaction descriptions]
+```
+
+## 02-features/feature-<name>/tech-design.md
+
+```markdown
+# Technical Design: [Feature Name]
+
+## Architecture Approach
+[High-level approach. Diagram if helpful.]
+
+## Components
+### [Component 1]
+- **Responsibility**: [What it does]
+- **Interface**: [API/methods]
+- **Dependencies**: [What it needs]
+
+### [Component 2]
+[Same structure]
+
+## Data Models
+```language
+[Schema/types/interfaces]
+```
+
+## APIs
+### Endpoint: `METHOD /path`
+- **Request**: [Schema]
+- **Response**: [Schema]
+- **Errors**: [Error codes]
+
+## Security Considerations
+- [Auth/authz requirements]
+- [Data validation]
+- [Potential vulnerabilities addressed]
+
+## Performance Considerations
+- [Expected load]
+- [Optimization strategy]
+- [Caching approach]
+
+## Trade-offs
+- **Decision**: [What we chose]
+- **Alternatives**: [What we didn't choose]
+- **Rationale**: [Why]
+```
+
+## 02-features/feature-<name>/dev-tasks.md
+
+```markdown
+# Development Tasks: [Feature Name]
+
+## Tasks
+- [ ] Task 1: [Specific, executable action]
+  - Dependencies: [What must be done first]
+  - Files: [Which files to touch]
+- [ ] Task 2: [...]
+- [ ] Task 3: [...]
+
+## Implementation Notes
+[Context LLM needs to execute tasks]
+
+## Definition of Done
+- [ ] Code complete
+- [ ] Tests pass
+- [ ] Docs updated
+- [ ] Reviewed
+```
+
+## 02-features/feature-<name>/test-plan.md
+
+```markdown
+# Test Plan: [Feature Name]
+
+## Test Strategy
+- **Unit**: [What to unit test]
+- **Integration**: [What to integration test]
+- **E2E**: [What to E2E test]
+
+## Test Cases
+### TC-1: [Test name]
+- **Given**: [Precondition]
+- **When**: [Action]
+- **Then**: [Expected result]
+
+### TC-2: [Test name]
+[Same structure]
+
+## Edge Cases
+- [ ] Test: [Edge case 1]
+- [ ] Test: [Edge case 2]
+
+## Performance Tests
+- [ ] Load test: [Scenario]
+- [ ] Stress test: [Scenario]
+
+## Security Tests
+- [ ] Auth test: [Scenario]
+- [ ] Input validation: [Scenario]
+```
+
+## 03-logs/implementation-log.md
+
+```markdown
+# Implementation Log
+
+Track what changed in code and why.
+
+## YYYY-MM-DD - [Change Title]
+**What**: [Code changes made - files, functions, modules]
+**Why**: [Business/technical reason for change]
+**Impact**: [What changed for users/devs]
+**Ref**: [PR/commit/issue reference]
+
+---
+
+## YYYY-MM-DD - [Change Title]
+[Repeat structure]
+```
+
+## 03-logs/decisions-log.md
+
+```markdown
+# Decisions Log
+
+Track architectural and product decisions.
+
+## YYYY-MM-DD - [Decision Title]
+**Context**: [Why this decision needed]
+**Options Considered**:
+1. Option A: [Description, pros/cons]
+2. Option B: [Description, pros/cons]
+
+**Decision**: [What we chose]
+**Rationale**: [Why we chose it]
+**Consequences**: [Implications, trade-offs]
+**Ref**: [Discussion link, RFC number]
+
+---
+
+## YYYY-MM-DD - [Decision Title]
+[Repeat structure]
+```
+
+## 03-logs/bug-log.md
+
+```markdown
+# Bug Log
+
+Track bugs, root causes, fixes.
+
+## [BUG-001] - [Bug Title]
+**Reported**: YYYY-MM-DD
+**Severity**: Critical | High | Medium | Low
+**Symptoms**: [What users saw]
+**Root Cause**: [What went wrong technically]
+**Fix**: [How resolved]
+**Prevention**: [How we avoid repeating]
+**Ref**: [Issue/PR reference]
+
+---
+
+## [BUG-002] - [Bug Title]
+[Repeat structure]
+```
+
+## 03-logs/validation-log.md
+
+```markdown
+# Validation Log
+
+Track what happened after shipping.
+
+## YYYY-MM-DD - [Release/Feature Name]
+**Validated**: [What was tested in production]
+**Results**:
+- Metric 1: [Actual vs expected]
+- Metric 2: [Actual vs expected]
+
+**Issues Found**: [Problems discovered post-ship]
+**User Feedback**: [What users said]
+**Next Steps**: [Follow-up actions]
+
+---
+
+## YYYY-MM-DD - [Release/Feature Name]
+[Repeat structure]
+```
+
+## 03-logs/insights.md
+
+```markdown
+# Insights
+
+Learnings and future improvements.
+
+## What Worked Well
+- [Success 1: what and why]
+- [Success 2: what and why]
+
+## What Didn't Work
+- [Issue 1: what went wrong, how to improve]
+- [Issue 2: what went wrong, how to improve]
+
+## Process Improvements
+- [ ] [Change we should make to workflow]
+- [ ] [Tool/practice to adopt]
+
+## Technical Debt
+- [ ] [Debt item 1: what, impact, effort to fix]
+- [ ] [Debt item 2: what, impact, effort to fix]
+
+## Future Optimizations
+- [Optimization opportunity 1]
+- [Optimization opportunity 2]
+```
+
+## 04-process/dev-workflow.md
+
+```markdown
+# Development Workflow
+
+## Daily Dev Loop
+
+### 1. Pick Task
+- Check `02-features/*/dev-tasks.md` or backlog
+- Verify acceptance criteria clear
+
+### 2. Implement
+- Write test first (if TDD)
+- Implement feature
+- Run tests locally
+- Update docs
+
+### 3. Review
+- Self-review checklist:
+  - [ ] Tests pass
+  - [ ] Docs updated
+  - [ ] No console.logs/debugs
+  - [ ] Security reviewed
+- Create PR
+
+### 4. Ship
+- Merge after approval
+- Update `03-logs/implementation-log.md`
+- Monitor production
+
+## Branch Strategy
+- `main`: production-ready code
+- `feature/*`: new features
+- `fix/*`: bug fixes
+
+## Working with LLMs
+- Provide context: link to relevant docs
+- Reference acceptance criteria from feature specs
+- Ask to update logs after changes
+- Request test generation
+
+## Code Review Checklist
+- [ ] Matches acceptance criteria
+- [ ] Tests cover edge cases
+- [ ] Docs updated
+- [ ] No security issues
+- [ ] Performance acceptable
+```
+
+## 04-process/definition-of-done.md
+
+```markdown
+# Definition of Done
+
+## Code Complete
+- [ ] Implements all acceptance criteria
+- [ ] Passes all tests (unit, integration, e2e)
+- [ ] No linter errors
+- [ ] Code reviewed and approved
+- [ ] Security reviewed (if touching auth/data)
+
+## Documentation Complete
+- [ ] Feature spec updated (if behavior changed)
+- [ ] API docs updated (if APIs changed)
+- [ ] README updated (if setup changed)
+- [ ] Logs updated (implementation-log, decisions-log)
+
+## Testing Complete
+- [ ] Unit tests written and passing
+- [ ] Integration tests written and passing
+- [ ] Manual testing completed
+- [ ] Edge cases tested
+- [ ] Performance acceptable
+
+## Release Ready
+- [ ] Deployed to staging
+- [ ] Smoke tests pass
+- [ ] Rollback plan documented
+- [ ] Monitoring in place
+```
+
+## 04-process/llm-prompts.md
+
+```markdown
+# Canonical LLM Prompts
+
+Standard prompts for documentation tasks.
+
+## Create Feature Spec
+\`\`\`
+As backlog-manager, create a feature spec for [feature name] in 02-features/feature-[name]/.
+
+Requirements:
+[Paste requirements]
+
+Include:
+- User stories with acceptance criteria
+- Edge cases
+- UI/UX considerations
+\`\`\`
+
+## Create Technical Design
+\`\`\`
+As architect, create technical design for [feature name] in 02-features/feature-[name]/.
+
+Feature spec: 02-features/feature-[name]/feature-spec.md
+
+Include:
+- Architecture approach
+- Components and data models
+- APIs
+- Security and performance considerations
+- Trade-offs
+\`\`\`
+
+## Generate Dev Tasks
+\`\`\`
+As 2-generate-tasks, break down the feature into executable dev tasks.
+
+Feature spec: 02-features/feature-[name]/feature-spec.md
+Tech design: 02-features/feature-[name]/tech-design.md
+
+Create: 02-features/feature-[name]/dev-tasks.md
+\`\`\`
+
+## Update Implementation Log
+\`\`\`
+Update 03-logs/implementation-log.md with today's changes.
+
+Changes made:
+[Describe changes]
+
+Why:
+[Reason]
+
+Impact:
+[User/developer impact]
+\`\`\`
+
+## Update Decisions Log
+\`\`\`
+Update 03-logs/decisions-log.md with architectural decision.
+
+Decision: [What we decided]
+Context: [Why decision needed]
+Options: [Alternatives considered]
+Rationale: [Why we chose this]
+\`\`\`
+```
+
+## docs/README.md
+
+```markdown
+# Documentation Guide
+
+## Structure
+
+Our docs follow a 5-tier hierarchy:
+
+- **00-context/**: WHY this exists, WHAT's currently built
+- **01-product/**: WHAT we must build (requirements)
+- **02-features/**: HOW features are designed and built
+- **03-logs/**: MEMORY of changes, decisions, bugs over time
+- **04-process/**: HOW to work (workflows, standards)
+
+## Quick Navigation
+
+**Start here**: `00-context/vision.md` - understand product purpose
+**Requirements**: `01-product/prd.md` - single source of truth
+**Feature work**: `02-features/feature-*/` - specs, designs, tasks
+**History**: `03-logs/` - what changed and why
+**Workflows**: `04-process/` - how we work daily
+
+## For Developers
+
+1. **Starting new feature**:
+   - Read: `01-product/prd.md` for requirements
+   - Check: `02-features/` for existing feature patterns
+   - Create: `02-features/feature-<name>/` with 4 files
+
+2. **Daily work**:
+   - Follow: `04-process/dev-workflow.md`
+   - Check: `04-process/definition-of-done.md` before PR
+
+3. **After changes**:
+   - Update: `03-logs/implementation-log.md`
+   - Update: `03-logs/decisions-log.md` if architectural
+
+## For LLMs
+
+Standard prompts: `04-process/llm-prompts.md`
+Context loading: Start with `00-context/`, then drill into specific features
+
+## Legacy Docs
+
+[If existing docs/ subdirs exist, map them here]
+- Old `commands/` → See `02-features/cli/`
+- Old `development/` → See `04-process/dev-workflow.md`
+- Old `guides/` → Distributed across `02-features/`
+- Old `reference/` → See `00-context/` and `01-product/`
+```