Aidderall MCP Server

<!-- Copyright (C) 2024 Briam R. <briamr@gmail.com> This document is part of Aidderall MCP Server. Aidderall MCP Server is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. --> # Aidderall Usage Guide: Getting AI to Work Effectively This guide shows how to get AI assistants to use Aidderall effectively for complex, multi-step projects. ## Related Documentation - **[README](../README.md)** - Installation and quick start - **[Technical Specification](vision/Aidderall_Vision.md)** - Detailed technical architecture - **[AI Assistant Evolution](vision/AI_Assistant_Evolution.md)** - Vision and philosophy ## 🎯 Quick Start Commands ### For Complex Projects - "Use Aidderall to plan and execute [task]" - "Break down [project] using Aidderall” - "Create a task stack for [goal]" - "Track this work with Aidderall" ### For Resuming Work - "Check your task stack and continue where you left off" - "What's your current task in Aidderall?" - “What’s the current big picture?” ### For clearing the task stack - “Go for zen!” - “Mark all tasks as complete in Aidderall” ## 📋 Best Practices ### 1. Start with Clear, High-Level Goals ❌ **Avoid vague requests:** ``` "Help me with some coding stuff" "Fix my project" ``` ✅ **Be specific about the outcome:** ``` "Help me refactor this authentication system using Aidderall" "Use Aidderall to build a REST API for user management" ``` ### 2. Encourage Deep Decomposition Tell the AI to break down complex tasks: ``` "Break this down into subtasks until you have something concrete to do" "Use Aidderall to fully plan this before starting implementation" "Create a comprehensive task hierarchy for this project" ``` ### 3. Leverage Multi-Session Persistence Start new conversations by checking existing work: ``` "First check your Aidderall for any ongoing work" "Show me your current tasks, then continue" "What did you complete in our last session?" ``` ## 🔧 Effective Usage Patterns ### The Project Kickoff Pattern ``` You: "I need to build a REST API for user management. Use Aidderall to manage this project." Expected AI behavior: - Creates main task: "Build REST API for User Management" - Extends with subtasks: "Design API endpoints", "Set up project structure", etc. - Begins systematic implementation ``` ### The Interruption Handler Pattern ``` You: "Actually, first check if we have the right Python version" Expected AI behavior: - Pushes new task: "Verify Python Version" - Completes the check - Automatically returns to previous work ``` ### The Progress Review Pattern ``` You: "Show me your current task stack" You: "What's left to complete?" You: "Continue with the current task" Expected AI behavior: - Shows full task hierarchy - Identifies current position - Resumes work systematically ``` ## 💡 Power User Techniques ### 1. Complex Problem Solving ``` "Create a comprehensive task stack for migrating our database from MySQL to PostgreSQL, then work through it systematically" ``` ### 2. Research and Implementation Projects ``` "Use Aidderall to research WebSocket implementations, design our real-time system, and build a proof of concept" ``` ### 3. Debugging and Investigation ``` "Track down this memory leak using Aidderall. Start with symptoms and dig deeper until you find the root cause" ``` ### 4. Learning and Documentation ``` "Use Aidderall to learn about GraphQL, document your findings, and create example implementations" ``` ## 🚫 Common Pitfalls to Avoid ### 1. Don't Micromanage the Stack ❌ **Wrong:** "Create a task, then extend it, then create another task..." ✅ **Right:** "Use Aidderall to manage this project" ### 2. Don't Jump Between Unrelated Tasks ❌ **Wrong:** Asking about different projects without completing current work ✅ **Right:** Let AI complete task sequences or explicitly save state ### 3. Don't Ignore Existing Work ❌ **Wrong:** Starting new projects without checking current tasks ✅ **Right:** "First check your current focus, then we'll decide how to proceed" ### 4. Don't Treat It Like a Simple TODO List ❌ **Wrong:** Using it just to track items ✅ **Right:** Using it for deep work with context preservation ## 🎯 Understanding Task Types: When to Create vs Extend ### create_new_task: Handling Interruptions and Discoveries Use `create_new_task` when you encounter something unexpected that must be addressed immediately: **Example 1: Bug Discovery** ``` AI: "I'm implementing the user authentication feature..." AI: "Wait, I found a SQL injection vulnerability in the existing login code." AI: *Uses create_new_task: "Fix SQL injection vulnerability"* ``` **Example 2: Missing Dependencies** ``` AI: "Adding the payment processing module..." AI: "The required Stripe SDK isn't installed and configured." AI: *Uses create_new_task: "Install and configure Stripe SDK"* ``` ### extend_current_task: Planned Decomposition Use `extend_current_task` when breaking down work into known steps: **Example 1: Feature Implementation** ``` Current task: "Implement user profile feature" AI: *Uses extend_current_task: "Create profile database schema"* AI: *Uses extend_current_task: "Build profile API endpoints"* AI: *Uses extend_current_task: "Design profile UI components"* ``` **Example 2: Refactoring Project** ``` Current task: "Refactor authentication system" AI: *Uses extend_current_task: "Extract auth logic to service"* AI: *Uses extend_current_task: "Update all auth imports"* AI: *Uses extend_current_task: "Add comprehensive tests"* ``` ### Key Distinction - **create_new_task**: "I discovered something that needs attention NOW" - **extend_current_task**: "I'm planning the steps to complete my current goal" ## 📝 Complete Project Example ### Day 1: Project Start ``` You: "Help me create a Python package for data validation. Use Aidderall to manage the entire process." AI: *Creates main task: "Create Python Data Validation Package"* *Extends with: "Design Package Structure"* *Pushes: "Research Python Packaging Best Practices"* *Researches and documents findings* *Completes research, pops back* *Continues with package design...* ``` ### Day 2: Resumption ``` You: "Continue working on the validation package" AI: *Checks current task: "Implement Core Validators"* *Shows progress so far* *Resumes implementation exactly where left off* ``` ### Day 3: New Requirements ``` You: "We need to add async support to the validators" AI: *Pushes new task: "Add Async Support"* *Maintains context of overall project* *Integrates new requirement smoothly* ``` ## 🔑 Key Success Factors ### 1. Trust the Process Let AI decompose problems naturally rather than dictating structure. ### 2. Think in Projects, Not Queries Frame work as ongoing projects rather than one-off questions. ### 3. Leverage Persistence Take advantage of cross-session memory for complex work. ### 4. Be Clear About Focus When multiple projects exist, specify which one to work on. ## 🎯 The Magic Phrase When in doubt, just say: > **"Use Aidderall to [your goal]"** The AI will naturally organize the work into a proper task hierarchy and work through it systematically. ## 📊 Checking Progress Useful commands for monitoring: - "Show me the big picture" - See all tasks - "What's your current focus?" - See active task - "What have you completed?" - Review finished work - "Explain your task structure" - Understand the plan ## 🔄 Iterative Improvement As you work with Aidderall: 1. AI learns your project patterns 2. You develop shared vocabulary 3. Collaboration becomes more efficient 4. Projects complete more reliably Remember: Aidderall transforms AI from a question-answerer into a persistent, focused collaborator. Use it accordingly! ## 📚 Living Document Approach Aidderall maintains a "living document" of your work - completed tasks remain visible in the structure, creating a comprehensive history of what's been accomplished. ### Understanding Task Visibility When you complete a task, it doesn't disappear: ``` get_big_picture() # Output: # Design authentication system (pending) # Research OAuth providers (completed) ← Still visible! # Implement login flow (current) <-- YOU ARE HERE # Add password reset (pending) ``` This approach provides: - **Context**: See what led to current work - **Progress tracking**: Visual indication of completion - **Reference**: Completed task bodies contain valuable information ### Workspace Management with remove_task If your workspace gets cluttered with completed tasks, use `remove_task` to clean up: ``` "Remove the completed OAuth research task to declutter" # AI uses: remove_task("task-id-for-oauth-research") ``` Important: Removed tasks are preserved in the task history - nothing is lost! ## 🔄 Non-Linear Workflows with switch_focus Unlike traditional task lists, Aidderall allows jumping between any tasks: ### Example: Handling Urgent Issues ``` Current state: - Working on documentation (current) - Bug report comes in "Switch focus to investigate the critical bug in user authentication" # AI uses: create_new_task("Fix critical auth bug", "Users can't log in...") # Then later: switch_focus("doc-task-id") to return to documentation ``` ### Example: Research-Driven Development ``` "I need to research three different approaches before deciding" # AI creates three research tasks # Uses switch_focus to jump between them as information is discovered # No need to complete them in order ``` ### Finding Task IDs To use switch_focus effectively: ``` "Show me all tasks with their IDs" # AI uses: get_big_picture(format='json') or get_stack_overview() ``` ## See Also - For technical implementation details, see the [Technical Specification](vision/Aidderall_Vision.md) - For the broader vision of AI transformation, read [AI Assistant Evolution](vision/AI_Assistant_Evolution.md) - For development history, check the [Work Log](../worklog.md)