claude-termux 1.0.0

package/skills/dispatching-parallel-agents/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: dispatching-parallel-agents
+description: Use when facing 3+ independent failures that can be investigated without shared state or dependencies - dispatches multiple Claude agents to investigate and fix independent problems concurrently
+---
+
+# Dispatching Parallel Agents
+
+## Overview
+
+When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
+
+**Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.
+
+## When to Use
+
+```dot
+digraph when_to_use {
+    "Multiple failures?" [shape=diamond];
+    "Are they independent?" [shape=diamond];
+    "Single agent investigates all" [shape=box];
+    "One agent per problem domain" [shape=box];
+    "Can they work in parallel?" [shape=diamond];
+    "Sequential agents" [shape=box];
+    "Parallel dispatch" [shape=box];
+
+    "Multiple failures?" -> "Are they independent?" [label="yes"];
+    "Are they independent?" -> "Single agent investigates all" [label="no - related"];
+    "Are they independent?" -> "Can they work in parallel?" [label="yes"];
+    "Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
+    "Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
+}
+```
+
+**Use when:**
+- 3+ test files failing with different root causes
+- Multiple subsystems broken independently
+- Each problem can be understood without context from others
+- No shared state between investigations
+
+**Don't use when:**
+- Failures are related (fix one might fix others)
+- Need to understand full system state
+- Agents would interfere with each other
+
+## The Pattern
+
+### 1. Identify Independent Domains
+
+Group failures by what's broken:
+- File A tests: Tool approval flow
+- File B tests: Batch completion behavior
+- File C tests: Abort functionality
+
+Each domain is independent - fixing tool approval doesn't affect abort tests.
+
+### 2. Create Focused Agent Tasks
+
+Each agent gets:
+- **Specific scope:** One test file or subsystem
+- **Clear goal:** Make these tests pass
+- **Constraints:** Don't change other code
+- **Expected output:** Summary of what you found and fixed
+
+### 3. Dispatch in Parallel
+
+```typescript
+// In Claude Code / AI environment
+Task("Fix agent-tool-abort.test.ts failures")
+Task("Fix batch-completion-behavior.test.ts failures")
+Task("Fix tool-approval-race-conditions.test.ts failures")
+// All three run concurrently
+```
+
+### 4. Review and Integrate
+
+When agents return:
+- Read each summary
+- Verify fixes don't conflict
+- Run full test suite
+- Integrate all changes
+
+## Agent Prompt Structure
+
+Good agent prompts are:
+1. **Focused** - One clear problem domain
+2. **Self-contained** - All context needed to understand the problem
+3. **Specific about output** - What should the agent return?
+
+```markdown
+Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:
+
+1. "should abort tool with partial output capture" - expects 'interrupted at' in message
+2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
+3. "should properly track pendingToolCount" - expects 3 results but gets 0
+
+These are timing/race condition issues. Your task:
+
+1. Read the test file and understand what each test verifies
+2. Identify root cause - timing issues or actual bugs?
+3. Fix by:
+   - Replacing arbitrary timeouts with event-based waiting
+   - Fixing bugs in abort implementation if found
+   - Adjusting test expectations if testing changed behavior
+
+Do NOT just increase timeouts - find the real issue.
+
+Return: Summary of what you found and what you fixed.
+```
+
+## Common Mistakes
+
+**❌ Too broad:** "Fix all the tests" - agent gets lost
+**✅ Specific:** "Fix agent-tool-abort.test.ts" - focused scope
+
+**❌ No context:** "Fix the race condition" - agent doesn't know where
+**✅ Context:** Paste the error messages and test names
+
+**❌ No constraints:** Agent might refactor everything
+**✅ Constraints:** "Do NOT change production code" or "Fix tests only"
+
+**❌ Vague output:** "Fix it" - you don't know what changed
+**✅ Specific:** "Return summary of root cause and changes"
+
+## When NOT to Use
+
+**Related failures:** Fixing one might fix others - investigate together first
+**Need full context:** Understanding requires seeing entire system
+**Exploratory debugging:** You don't know what's broken yet
+**Shared state:** Agents would interfere (editing same files, using same resources)
+
+## Real Example from Session
+
+**Scenario:** 6 test failures across 3 files after major refactoring
+
+**Failures:**
+- agent-tool-abort.test.ts: 3 failures (timing issues)
+- batch-completion-behavior.test.ts: 2 failures (tools not executing)
+- tool-approval-race-conditions.test.ts: 1 failure (execution count = 0)
+
+**Decision:** Independent domains - abort logic separate from batch completion separate from race conditions
+
+**Dispatch:**
+```
+Agent 1 → Fix agent-tool-abort.test.ts
+Agent 2 → Fix batch-completion-behavior.test.ts
+Agent 3 → Fix tool-approval-race-conditions.test.ts
+```
+
+**Results:**
+- Agent 1: Replaced timeouts with event-based waiting
+- Agent 2: Fixed event structure bug (threadId in wrong place)
+- Agent 3: Added wait for async tool execution to complete
+
+**Integration:** All fixes independent, no conflicts, full suite green
+
+**Time saved:** 3 problems solved in parallel vs sequentially
+
+## Key Benefits
+
+1. **Parallelization** - Multiple investigations happen simultaneously
+2. **Focus** - Each agent has narrow scope, less context to track
+3. **Independence** - Agents don't interfere with each other
+4. **Speed** - 3 problems solved in time of 1
+
+## Verification
+
+After agents return:
+1. **Review each summary** - Understand what changed
+2. **Check for conflicts** - Did agents edit same code?
+3. **Run full suite** - Verify all fixes work together
+4. **Spot check** - Agents can make systematic errors
+
+## Real-World Impact
+
+From debugging session (2025-10-03):
+- 6 failures across 3 files
+- 3 agents dispatched in parallel
+- All investigations completed concurrently
+- All fixes integrated successfully
+- Zero conflicts between agent changes

package/skills/documentation-generation/SKILL.md

@@ -0,0 +1,8 @@
+documentation-generation skill helps create comprehensive, maintainable documentation for software projects through structured templates and examples.
+
+For code review, check that:
+1. Documentation exists for all public APIs
+2. Examples are provided and tested
+3. README is complete and up-to-date
+4. Inline comments explain complex logic
+5. Architecture decisions are documented

package/skills/documentation-generation/templates/README.template.md

@@ -0,0 +1,60 @@
+# [Project Name]
+
+[One sentence description]
+
+## Features
+
+- [Feature 1]
+- [Feature 2]
+- [Feature 3]
+
+## Installation
+
+```bash
+npm install [package-name]
+```
+
+## Usage
+
+```javascript
+const example = require('[package-name]');
+
+// Basic usage
+example.method();
+```
+
+## API Reference
+
+### [Class/Module Name]
+
+#### [Method Name]([parameters])
+
+Description of method
+
+**Parameters:**
+- `param1` (type): Description
+- `param2` (type, optional): Description
+
+**Returns:**
+- Type: Description of return value
+
+**Example:**
+```javascript
+const result = example.method(param1, param2);
+```
+
+## Examples
+
+See `/examples` directory for complete examples.
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch
+3. Commit your changes
+4. Push to the branch
+5. Create a Pull Request
+
+## License
+
+[License Name]

package/skills/error-handling/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: error-handling
+description: Use when implementing error handling code to ensure all errors are properly caught, logged, and recovered from - includes try-catch patterns, error boundaries, graceful degradation, and user-friendly error messages
+---
+
+# Error Handling Skill
+
+You are an Error Handling Expert specializing in making code robust and resilient through proper error management. Your expertise includes:
+
+- **Try-Catch Patterns**: Proper wrapping of error-prone code
+- **Error Boundaries**: Preventing errors from crashing the application
+- **Logging**: Structured error logging for debugging
+- **Graceful Degradation: Fallback mechanisms when things fail
+- **User-Friendly Messages**: Clear, actionable error messages
+
+## When to Use
+
+Trigger this skill when:
+
+- Implementing error handling in code
+- Fixing unhandled exceptions
+- Adding logging to debug errors
+- Making code more robust
+- Improving error recovery mechanisms
+
+## Core Principles
+
+### 1. Try-Catch Patterns
+
+#### JavaScript/TypeScript
+```typescript
+try {
+  const result = riskyOperation();
+  return result;
+} catch (error) {
+  // Log error
+  console.error('Error in riskyOperation:', error);
+  // Handle error appropriately
+  return defaultValue;
+}
+```
+
+#### Python
+```python
+try:
+    result = risky_operation()
+    return result
+except Exception as error:
+    log_error(f"Error in risky_operation: {str(error)}")
+    return default_value
+```
+
+### 2. Error Boundaries
+
+Prevent errors from crashing the application:
+
+```typescript
+// Error boundary component (React)
+class ErrorBoundary extends React.Component {
+  componentDidCatch(error, errorInfo) {
+    console.error('Error caught:', error, errorInfo);
+    return (
+      <div className="error-page">
+        <h1>Something went wrong</h1>
+        <p>{error.toString()}</p>
+      </div>
+    );
+  }
+}
+```
+
+### 3. Structured Error Logging
+
+Log errors with context:
+
+```typescript
+interface AppError extends Error {
+  code: string;           // Unique error code
+  timestamp: string;     // When error occurred
+  user: string;         // User who experienced the error
+  stack: string;          // Stack trace
+  context?: {           // Additional context
+    component?: string;
+    action?: string;
+    state?: object;
+  };
+}
+```
+
+### 4. Graceful Degradation
+
+Fallback mechanisms when things fail:
+
+```typescript
+// Fallback for API calls
+async function fetchUserData(userId: string) {
+  try {
+    return await fetch(`/api/users/${userId}`);
+  } catch (error) {
+    console.error('Failed to fetch user data, using cache:', error);
+    return getCachedUserData(userId); // Fallback to cache
+  }
+}
+```
+
+## Error Handling Best Practices
+
+### DO ✅
+
+- **Catch specific errors**: Catch specific error types if you can handle them differently
+- **Log with context**: Include timestamp, user ID, request ID
+- **Provide user-friendly messages**: "Failed to save your changes. Please try again."
+- **Log to appropriate level**: `console.error`, `logger.error`, `logger.warn`
+- **Consider recovery**: Can the error be recovered? Can we retry?
+- **Don't log sensitive data**: Passwords, tokens, personal info
+- **Propagate errors when appropriate**: Let parent handler handle it
+
+### DON'T ❌
+
+- **Catch-all errors**: `catch (e) { console.log(e); }` - loses error information
+- **Swallow errors silently**: Errors should not disappear
+- **Log sensitive information**: Passwords, tokens, PII
+- **Use console.log for errors**: Use proper logging library
+- **Expose internal details**: Don't show stack traces to end-users
+- **Ignore errors silently**: Every error should be at minimum logged
+- **Retry indefinitely: Always have max retry limits
+
+## Error Categories
+
+### 1. User Errors
+Examples: Invalid input, wrong file format, permission denied
+
+**Handling**:
+- Validate inputs beforehand
+- Provide clear error messages
+- Guide user to correct the issue
+
+### 2. System Errors
+Examples: Database connection failed, file not found, network timeout
+
+**Handling**:
+- Log error details
+- Provide fallback options
+- Consider retry logic with backoff
+
+### 3. Programming Errors
+Examples: TypeError, ReferenceError, SyntaxError
+
+**Handling**:
+- Fix the bug causing the error
+- Add validation to prevent it
+- Test the fix to ensure it works
+
+## Error Recovery Strategies
+
+### 1. Retry Logic
+```typescript
+async function fetchWithRetry<T>(
+  url: string,
+  options: RequestInit,
+  maxRetries: number = 3
+): Promise<T> {
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      const response = await fetch(url, options);
+      if (response.ok) return response.json();
+
+      // Retry on server errors or timeouts
+      if (response.status === 408 || response.status === 429) {
+        const waitTime = Math.pow(2, attempt) * 1000; // Exponential backoff
+        await delay(waitTime);
+        continue;
+      }
+
+      // Non-retryable errors
+      throw new Error(`HTTP Error ${response.status}: ${response.statusText}`);
+    } catch (error) {
+      if (attempt < maxRetries - 1) {
+        const waitTime = Math.pow(2, attempt) * 1000;
+        await delay(waitTime);
+      } else {
+        throw error;
+      }
+    }
+  }
+}
+```
+
+### 2. Circuit Breaker Pattern
+
+```typescript
+class CircuitBreaker {
+  private failures: number = 0;
+  private lastFailure: Date | null = null;
+  private timeout: number = 60000; // 1 minute
+
+  async execute<T>(operation: () => Promise<T>): Promise<T> {
+    if (this.failures >= 3) {
+      throw new Error('Circuit breaker is open - too many recent failures');
+    }
+
+    try {
+      const result = await operation();
+      this.failures = 0; // Reset on success
+      this.lastFailure = null;
+      return result;
+    } catch (error) {
+      this.failures++;
+      this.lastFailure = new Date();
+      throw error;
+    }
+  }
+}
+```
+
+### 3. Fallback Mechanisms
+
+```typescript
+function getPreference<T>(
+  preference: string,
+  defaultValue: T
+): T {
+  try {
+    return fetchPreferenceFromDB(preference);
+  } catch (error) {
+    console.warn(`Failed to fetch ${preference} from DB, using default: ${error.message}`);
+    return defaultValue;
+  }
+}
+```
+
+## Error Handling Checklist
+
+When implementing error handling, ensure:
+
+### Structure
+- [ ] All error-prone code wrapped in try-catch
+- [ ] Error boundaries installed at component level
+- [ ] Global error handler installed (if needed)
+- [ ] Error logging configured
+
+### Logging
+- [ ] Appropriate log levels (error, warn, info, debug)
+- [ -> Log with context: timestamp, userId, requestId
+- [ ] Sensitive data excluded from logs
+- [ ] Logs stored securely
+
+### Recovery
+- [ ] Retry logic implemented for transient failures
+- [ ] Fallback mechanisms in place
+- [ ] Circuit breaker pattern for failing services
+- [] Graceful degradation in place
+
+### Messages
+- [ ] Error messages user-friendly and actionable
+- [ ] Technical details logged separately
+- [ ] No sensitive data in user-facing errors
+
+### Testing
+- [ ] Error cases tested with test cases
+- [ ] Error logging tested
+- [ ] Recovery mechanisms tested
+- [ ] Error boundaries tested
+
+---
+
+**Remember**: "Error handling is not about preventing errors (that's impossible!) - it's about handling them gracefully when they DO occur!"

package/skills/executing-plans/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: executing-plans
+description: Use when partner provides a complete implementation plan to execute in controlled batches with review checkpoints - loads plan, reviews critically, executes tasks in batches, reports for review between batches
+---
+
+# Executing Plans
+
+## Overview
+
+Load plan, review critically, execute tasks in batches, report for review between batches.
+
+**Core principle:** Batch execution with checkpoints for architect review.
+
+**Announce at start:** "I'm using the executing-plans skill to implement this plan."
+
+## The Process
+
+### Step 1: Load and Review Plan
+1. Read plan file
+2. Review critically - identify any questions or concerns about the plan
+3. If concerns: Raise them with your human partner before starting
+4. If no concerns: Create TodoWrite and proceed
+
+### Step 2: Execute Batch
+**Default: First 3 tasks**
+
+For each task:
+1. Mark as in_progress
+2. Follow each step exactly (plan has bite-sized steps)
+3. Run verifications as specified
+4. Mark as completed
+
+### Step 3: Report
+When batch complete:
+- Show what was implemented
+- Show verification output
+- Say: "Ready for feedback."
+
+### Step 4: Continue
+Based on feedback:
+- Apply changes if needed
+- Execute next batch
+- Repeat until complete
+
+### Step 5: Complete Development
+
+After all tasks complete and verified:
+- Announce: "I'm using the finishing-a-development-branch skill to complete this work."
+- **REQUIRED SUB-SKILL:** Use superpowers:finishing-a-development-branch
+- Follow that skill to verify tests, present options, execute choice
+
+## When to Stop and Ask for Help
+
+**STOP executing immediately when:**
+- Hit a blocker mid-batch (missing dependency, test fails, instruction unclear)
+- Plan has critical gaps preventing starting
+- You don't understand an instruction
+- Verification fails repeatedly
+
+**Ask for clarification rather than guessing.**
+
+## When to Revisit Earlier Steps
+
+**Return to Review (Step 1) when:**
+- Partner updates the plan based on your feedback
+- Fundamental approach needs rethinking
+
+**Don't force through blockers** - stop and ask.
+
+## Remember
+- Review plan critically first
+- Follow plan steps exactly
+- Don't skip verifications
+- Reference skills when plan says to
+- Between batches: just report and wait
+- Stop when blocked, don't guess