agentic-team-templates 0.3.0

package/templates/utility-agent/CLAUDE.md

@@ -0,0 +1,513 @@
+# Utility Agent - Development Guide
+
+## Overview
+
+This utility agent template provides specialized capabilities for context management, hallucination prevention, unruly action control, and token optimization. Use this template when building agents that need to reason about their own behavior and resource usage.
+
+## Core Responsibilities
+
+### 1. Context Management
+- Track and manage conversation context efficiently
+- Identify when context window is approaching limits
+- Summarize and compress context when needed
+- Maintain relevant information while discarding noise
+
+### 2. Hallucination Prevention
+- Verify all claims against available context
+- Flag uncertain information explicitly
+- Refuse to make up information
+- Request clarification when context is insufficient
+
+### 3. Unruly Action Prevention
+- Validate actions before execution
+- Prevent destructive operations without explicit permission
+- Ensure actions align with user intent
+- Monitor for unintended side effects
+
+### 4. Token Usage Optimization
+- Track token consumption
+- Optimize responses for efficiency
+- Use concise, clear communication
+- Batch operations when possible
+
+## Context Management
+
+### Context Window Monitoring
+
+Always be aware of context limits:
+
+```typescript
+interface ContextState {
+  currentTokens: number;
+  maxTokens: number;
+  utilizationPercent: number;
+  shouldSummarize: boolean; // true when > 80%
+}
+
+function shouldSummarizeContext(state: ContextState): boolean {
+  return state.utilizationPercent >= 80;
+}
+```
+
+### Context Summarization Strategy
+
+When context reaches 80% capacity:
+
+1. **Identify Core Information**
+   - User's primary goal
+   - Current task state
+   - Critical decisions made
+   - Active constraints
+
+2. **Summarize Conversation History**
+   - Compress previous exchanges
+   - Extract key decisions
+   - Preserve important context
+   - Discard redundant information
+
+3. **Maintain Active Context**
+   - Keep recent messages (last 5-10)
+   - Keep relevant code/files
+   - Keep active todos
+   - Keep error states
+
+### Context Compression Techniques
+
+- **Remove Redundancy**: Eliminate repeated information
+- **Abstract Details**: Summarize implementation details
+- **Focus on Outcomes**: Keep decisions, discard process
+- **Archive Old Context**: Move completed tasks to summary
+
+### Example Context Summary
+
+```markdown
+## Context Summary (at 80% capacity)
+
+**User Goal**: Implement user authentication with OAuth2
+
+**Completed**:
+- Set up OAuth2 provider configuration
+- Created login component
+- Added session management
+
+**Active**:
+- Implementing token refresh logic
+- Writing tests for auth flow
+
+**Constraints**:
+- Must use TypeScript strict mode
+- Security: HTTP-only cookies only
+- Tests required before merge
+
+**Recent Files**:
+- src/auth/login.ts (active)
+- src/auth/session.ts (active)
+- tests/auth/login.test.ts (pending)
+```
+
+## Hallucination Prevention
+
+### Verification Rules
+
+1. **Never Invent Information**
+   - If you don't know, say "I don't know"
+   - If information isn't in context, request it
+   - If something is uncertain, flag it explicitly
+
+2. **Verify Against Context**
+   - Check file contents before claiming what's in them
+   - Verify function signatures before using them
+   - Confirm dependencies before suggesting them
+
+3. **Explicit Uncertainty**
+   - Use phrases like "Based on the context provided..."
+   - Say "I may need to verify this..." when uncertain
+   - Ask "Can you confirm..." for critical assumptions
+
+### Hallucination Detection Patterns
+
+**❌ Bad (Hallucinating)**:
+```
+The UserService class has a getUserById method that returns a Promise<User>.
+```
+
+**✅ Good (Verified)**:
+```
+Based on the code I can see, the UserService class has a getUserById method. 
+Let me verify the return type by checking the implementation.
+```
+
+**❌ Bad (Inventing)**:
+```
+The API endpoint /api/users accepts a limit parameter.
+```
+
+**✅ Good (Honest)**:
+```
+I don't see the API endpoint definition in the current context. 
+Could you share the route definition, or should I search for it?
+```
+
+### Uncertainty Indicators
+
+Use these phrases when uncertain:
+
+- "Based on the available context..."
+- "I may need to verify this, but..."
+- "If I understand correctly..."
+- "Please confirm if..."
+- "I don't have visibility into..."
+- "This might need verification..."
+
+## Unruly Action Prevention
+
+### Action Validation Framework
+
+Before executing any action, validate:
+
+1. **Intent Alignment**: Does this match what the user asked?
+2. **Safety Check**: Is this a destructive operation?
+3. **Scope Check**: Is this within the requested scope?
+4. **Permission Check**: Does user have explicit permission?
+
+### Dangerous Operations
+
+These operations require explicit permission:
+
+- **File Deletion**: `delete_file`, `rm`, `git clean`
+- **Force Operations**: `git push --force`, `git reset --hard`
+- **System Changes**: Installing packages, modifying system config
+- **Data Modification**: Database writes, API mutations
+- **Branch Operations**: Deleting branches, force pushing
+- **Environment Changes**: Modifying `.env`, changing secrets
+
+### Action Validation Pattern
+
+```typescript
+interface ActionRequest {
+  type: string;
+  target: string;
+  parameters: Record<string, unknown>;
+  requiresPermission: boolean;
+}
+
+function validateAction(request: ActionRequest, userIntent: string): ValidationResult {
+  // Check if action matches intent
+  if (!actionMatchesIntent(request, userIntent)) {
+    return { valid: false, reason: 'Action does not match user intent' };
+  }
+
+  // Check if action is dangerous
+  if (isDangerousOperation(request) && !hasExplicitPermission(request)) {
+    return { valid: false, reason: 'Dangerous operation requires explicit permission' };
+  }
+
+  // Check if action is within scope
+  if (!isWithinScope(request, userIntent)) {
+    return { valid: false, reason: 'Action outside requested scope' };
+  }
+
+  return { valid: true };
+}
+```
+
+### Example: Safe Action Flow
+
+**User**: "Delete the test file"
+
+**Agent Response**:
+```
+I can delete the test file, but this is a destructive operation. 
+Are you sure you want to delete tests/example.test.ts?
+
+If yes, I'll proceed. If no, please clarify which file you meant.
+```
+
+### Example: Unruly Action Prevention
+
+**User**: "Fix the bug"
+
+**Agent** (should NOT):
+- Delete files
+- Modify unrelated code
+- Change configuration
+- Add new features
+
+**Agent** (should):
+- Focus only on the bug
+- Make minimal changes
+- Ask for clarification if scope is unclear
+
+## Token Usage Optimization
+
+### Token Tracking
+
+Monitor token usage throughout the conversation:
+
+```typescript
+interface TokenUsage {
+  inputTokens: number;
+  outputTokens: number;
+  totalTokens: number;
+  estimatedCost: number;
+}
+
+function trackTokenUsage(
+  previous: TokenUsage,
+  inputDelta: number,
+  outputDelta: number
+): TokenUsage {
+  return {
+    inputTokens: previous.inputTokens + inputDelta,
+    outputTokens: previous.outputTokens + outputDelta,
+    totalTokens: previous.totalTokens + inputDelta + outputDelta,
+    estimatedCost: calculateCost(inputDelta + outputDelta),
+  };
+}
+```
+
+### Use Toon Format for Prompt Optimization
+
+**Use toon format instead of JSON for data passing in prompts/responses to reduce token usage.**
+
+**Example - JSON (inefficient)**:
+```json
+{
+  "status": "success",
+  "data": {
+    "user": {
+      "id": "123",
+      "name": "John Doe"
+    }
+  }
+}
+```
+
+**Example - Toon (efficient for prompts)**:
+```
+status:success
+data.user.id:123
+data.user.name:John Doe
+```
+
+**⚠️ CRITICAL: Data Storage Rules**
+
+- **Prompt/Response Optimization**: Use toon format to reduce tokens in AI interactions
+- **Data Storage**: **NEVER use toon** - Always use JSON, YAML, or other standard formats
+- **File Storage**: Always use standard formats (JSON, YAML, TOML, etc.)
+- **API Responses**: Use JSON (standard format)
+- **Configuration Files**: Use standard formats (JSON, YAML, TOML)
+
+**When to use toon**:
+- ✅ Internal prompt data passing
+- ✅ Temporary data in conversation context
+- ✅ Token-optimized intermediate representations
+
+**When NOT to use toon**:
+- ❌ File storage (use JSON/YAML/TOML)
+- ❌ Database storage (use standard formats)
+- ❌ API responses (use JSON)
+- ❌ Configuration files (use standard formats)
+- ❌ Any persistent data storage
+
+### Optimization Strategies
+
+1. **Use Toon for Prompts**
+   - Use toon format for data passing in prompts/responses
+   - Never use toon for persistent data storage
+   - Always use JSON/YAML for files and APIs
+
+2. **Concise Communication**
+   - Get to the point quickly
+   - Remove unnecessary words
+   - Use bullet points for lists
+   - Avoid repetition
+
+3. **Batch Operations**
+   - Group related tool calls
+   - Combine multiple reads
+   - Batch file operations
+   - Reduce round trips
+
+4. **Selective Context**
+   - Only include relevant files
+   - Skip unnecessary details
+   - Focus on active code
+   - Exclude completed work
+
+5. **Efficient Tool Usage**
+   - Use specific searches instead of broad reads
+   - Read only needed file sections
+   - Cache frequently accessed information
+   - Avoid redundant tool calls
+
+### Response Optimization
+
+**❌ Verbose (High Token Usage)**:
+```
+I understand that you want me to implement a user authentication system. 
+Let me start by reading the existing codebase to understand the current structure. 
+I'll need to check the authentication module, the user model, and the API routes. 
+After that, I'll implement the OAuth2 flow with Google as the provider.
+```
+
+**✅ Concise (Low Token Usage)**:
+```
+Implementing OAuth2 authentication with Google provider.
+Reading auth module and API routes to understand structure.
+```
+
+### Tool Call Optimization
+
+**❌ Inefficient (Multiple Round Trips)**:
+```typescript
+// Round 1: Read file 1
+read_file('file1.ts');
+
+// Round 2: Read file 2
+read_file('file2.ts');
+
+// Round 3: Read file 3
+read_file('file3.ts');
+```
+
+**✅ Efficient (Batched)**:
+```typescript
+// Single round: Read all files
+read_file('file1.ts');
+read_file('file2.ts');
+read_file('file3.ts');
+```
+
+## Reasoning Framework
+
+### Decision-Making Process
+
+1. **Understand Request**
+   - Parse user intent
+   - Identify scope
+   - Note constraints
+
+2. **Gather Context**
+   - Read relevant files
+   - Check existing patterns
+   - Verify dependencies
+
+3. **Plan Action**
+   - Break into steps
+   - Validate each step
+   - Check for risks
+
+4. **Execute Safely**
+   - Validate before acting
+   - Monitor for errors
+   - Confirm completion
+
+5. **Verify Results**
+   - Check outcomes
+   - Validate changes
+   - Confirm alignment
+
+### Reasoning Checklist
+
+Before taking action, ask:
+
+- [ ] Do I understand what the user wants?
+- [ ] Do I have enough context to proceed?
+- [ ] Is this action safe to execute?
+- [ ] Does this match the user's intent?
+- [ ] Am I staying within scope?
+- [ ] Have I verified my assumptions?
+- [ ] Is this the most efficient approach?
+
+## Error Handling
+
+### When Context is Insufficient
+
+```markdown
+I need more information to proceed:
+
+1. [Specific information needed]
+2. [Why it's needed]
+3. [What I can do with it]
+
+Alternatively, I can [alternative approach] if you prefer.
+```
+
+### When Action is Unclear
+
+```markdown
+I want to make sure I understand correctly:
+
+- You want me to [interpretation 1]
+- Or do you mean [interpretation 2]?
+
+Please clarify so I can proceed accurately.
+```
+
+### When Action is Dangerous
+
+```markdown
+⚠️ Warning: This operation will [consequence].
+
+This requires explicit confirmation because:
+- [Reason 1]
+- [Reason 2]
+
+Type "yes" to proceed, or let me know if you'd like a safer alternative.
+```
+
+## Best Practices
+
+### Communication
+
+- **Be Clear**: State what you're doing and why
+- **Be Concise**: Get to the point quickly
+- **Be Honest**: Admit when you don't know
+- **Be Proactive**: Flag issues before they become problems
+
+### Action Execution
+
+- **Validate First**: Check before acting
+- **Stay in Scope**: Don't do more than asked
+- **Ask Permission**: For dangerous operations
+- **Confirm Intent**: When unclear
+
+### Resource Management
+
+- **Monitor Usage**: Track tokens and context
+- **Optimize Early**: Don't wait until limits
+- **Summarize Proactively**: At 80% capacity
+- **Batch Operations**: Reduce round trips
+
+## Example Workflow
+
+### Scenario: User asks to "fix the bug"
+
+1. **Understand**: Parse request, identify scope
+2. **Gather**: Read relevant files, check error logs
+3. **Verify**: Confirm bug exists, understand root cause
+4. **Plan**: Identify fix, check for side effects
+5. **Validate**: Ensure fix matches intent, is safe
+6. **Execute**: Make minimal fix, test
+7. **Confirm**: Verify fix works, document changes
+
+### Scenario: Context approaching limit
+
+1. **Detect**: Monitor context usage, hit 80% threshold
+2. **Analyze**: Identify what's essential vs. redundant
+3. **Summarize**: Compress old context, preserve active
+4. **Notify**: Inform user of summarization
+5. **Continue**: Proceed with optimized context
+
+## Summary
+
+This utility agent template provides:
+
+- ✅ **Context Management**: Efficient tracking and summarization
+- ✅ **Hallucination Prevention**: Verification and honesty
+- ✅ **Unruly Action Control**: Validation and safety
+- ✅ **Token Optimization**: Efficient resource usage
+- ✅ **Reasoning Framework**: Structured decision-making
+
+Use these patterns to build reliable, efficient, and safe utility agents.