feat: add debug agent for automatic session log analysis

[zbigniewsobiecki]

Summary

Adds a new debug agent that automatically analyzes agent session logs when uploaded to Trello cards. The agent identifies errors, inefficiencies, and provides actionable recommendations to improve agent performance.

Key Features

• Automatic Trigger: Detects .zip attachments matching {agent-type}-{timestamp}.zip pattern
• User Verification: Only processes logs uploaded by the authenticated CASCADE user
• Log Analysis: Downloads, extracts, and analyzes session logs including:
  • cascade.log - Agent execution events
  • llmist.log - Library-level logging
  • llm-calls/ - Numbered LLM request/response pairs
• Issue Detection: Identifies errors, failed gadget calls, iteration loops, excessive LLM usage, and scope creep
• Debug Card Creation: Creates a new card in DEBUG list with:
  • Title: {agent-type} - {original card name}
  • Executive summary
  • Key issues found
  • Timeline of events
  • Actionable recommendations
  • Link to original card
• Graceful Degradation: Skips silently if DEBUG list not configured
• Performance: No repository cloning needed (faster execution)
• Automatic Cleanup: Temp directories cleaned up after processing

Implementation Details

New Files

• src/triggers/trello/attachment-added.ts - Attachment trigger handler
• src/agents/prompts/templates/debug.eta - Debug agent system prompt

Modified Files

• src/trello/client.ts - Added getMe() method for user verification
• src/triggers/types.ts - Added attachment field to webhook payload
• src/triggers/index.ts - Registered attachment trigger
• src/agents/prompts/index.ts - Added debug agent type
• src/agents/registry.ts - Registered debug agent
• src/agents/base.ts - Skip repository setup for debug agent (log-only mode)
• src/triggers/trello/webhook-handler.ts - Added temp directory cleanup
• src/types/index.ts - Added debug agent fields to AgentInput
• config/projects.json - Added DEBUG list placeholder
• CLAUDE.md - Added documentation for debug agent setup and usage
• package.json / package-lock.json - Added @types/adm-zip dev dependency

Setup Instructions

1. Create a DEBUG list in your Trello board
2. Update config/projects.json with the DEBUG list ID:

   {
     "trello": {
       "lists": {
         "debug": "YOUR_DEBUG_LIST_ID"
       }
     }
   }

Testing

• ✅ All 62 existing tests pass
• ✅ TypeScript type checking passes
• ✅ Lint checks pass (2 pre-existing complexity warnings)

Example Flow

1. Implementation agent fails on a task
2. Agent uploads implementation-2026-01-02T12-34-56-789Z.zip to the card
3. Trello sends addAttachmentToCard webhook
4. AttachmentAddedTrigger detects pattern match and user verification
5. Downloads and extracts logs to /tmp/debug-{cardId}-{timestamp}/
6. Debug agent analyzes logs and identifies root cause
7. Creates debug card with detailed analysis
8. Temp directory automatically cleaned up

🤖 Generated with Claude Code