gemini-helper-friend 2.0.5 → 2.0.7

package/dist/config/yaml/subagents.yaml

@@ -1,72 +1,18 @@
 # Gemini Helper Friend MCP - Subagent Configuration
-# YAML for metadata only - prompt templates in MDX files
-# Version: 2.1 - Enhanced descriptions with forcing patterns
-# Optimization: Detailed descriptions that force high-quality, structured prompts
-
-version: "2.1"
+version: "2.2"
 
 metadata:
   name: "gemini-helper-friend-mcp"
   displayName: "Gemini - Helper Friend MCP"
-  description: "Autonomous AI helper with specialized task types for code review, research, and testing"
-
-# ============================================================================
-# SHARED PRINCIPLES - Apply to ALL task types
-# ============================================================================
-shared:
-  core_philosophy: |
-    These subagents are designed for COMPREHENSIVE task execution through specialized modes.
-    Vague prompts = vague results. Detailed prompts = actionable insights.
-    
-    **CRITICAL:** The quality of output is DIRECTLY proportional to prompt detail.
-    - Short prompts (50 chars) → Generic, unhelpful responses
-    - Medium prompts (200 chars) → Partially useful responses
-    - Detailed prompts (500+ chars) → Specific, actionable insights
-    
-  principles:
-    context_is_king: |
-      The subagent has NO context about your task except what you provide.
-      Assume it knows NOTHING about your codebase, your goals, or your constraints.
-      Provide ALL relevant context - files, requirements, what you've tried, what failed.
-      
-    specificity_matters: |
-      "Check if it's done" → USELESS
-      "Verify Task X against requirements A, B, C using files X, Y, Z" → ACTIONABLE
-      
-    structured_input: |
-      Follow the template for each task type. Each section exists for a reason.
-      Skipping sections = missing critical context = suboptimal results.
-      
-  workflow_pattern: |
-    MANDATORY for all subagent calls:
-    1. GATHER CONTEXT → Collect all relevant files, requirements, constraints
-    2. STRUCTURE PROMPT → Follow the task-specific template (ALL sections!)
-    3. CALL SUBAGENT → Execute with async=true (default) or async=false for quick tasks
-    4. CHECK STATUS → Poll with check_subagent_task until completed
-    5. REVIEW RESULT → Evaluate output, take action on recommendations
-    
-    Why this works: Structured context enables the subagent to provide
-    specific, actionable recommendations instead of generic advice.
-
-# ============================================================================
-# GLOBAL SETTINGS
-# ============================================================================
+  description: "Autonomous AI helper with specialized task types"
 
 settings:
   defaults:
-    model: ""  # Uses fallback chain (see below)
+    model: ""
     yolo_mode: true
     append_instructions: true
-  
-  # Model fallback chain - tries in order until one succeeds
-  # 1. gemini-3-flash-preview (fastest, newest)
-  # 2. gemini-3-pro-preview (more capable)
-  # 3. gemini-3-pro (stable)
-  # 4. gemini-2.5-flash (reliable fallback)
-  
   cli:
     command: "gemini"
-    # Per gemini --help: use positional prompt (--prompt is deprecated)
     flags:
       yolo: "--yolo"
       model: "--model"
@@ -75,1096 +21,92 @@ settings:
       approval_mode: "--approval-mode"
       include_directories: "--include-directories"
 
-# ============================================================================
-# TASK TYPE DEFINITIONS (Metadata Only - Templates in MDX)
-# ============================================================================
-
 task_types:
-  
   completion-inspector:
     display_name: "Completion Inspector"
-    description: |
-      **🔍 CTO-LEVEL CODE INSPECTOR - Verifies if task is TRULY 100% complete**
-      
-      This subagent performs exhaustive verification that your implementation meets ALL requirements,
-      follows existing patterns, and leaves no cleanup debt.
-      
-      **What it analyzes:**
-      - Git diff (line-by-line change review against requirements)
-      - Codebase patterns (consistency with existing code style)
-      - Duplicate detection (find similar code that should be abstracted)
-      - Quality assessment (identify cleanup opportunities)
-      - Requirement coverage (map changes to acceptance criteria)
-      
-      **Output includes:**
-      - Completion percentage (0-100%)
-      - Requirements checklist (✅ met / ❌ not met)
-      - Quality issues found
-      - Specific action items with file locations
-      
+    description: "Verifies if task is 100% complete - analyzes git diff, patterns, requirements coverage"
     category: "verification"
-    default_model: ""  # Auto-select
     template_file: "completion-inspector.mdx"
-    
-    tool_limits:
-      sequentialthinking_max: 30
-      sequentialthinking_min: 15
-      warpgrep_max: 20
-      warpgrep_min: 8
-      deep_research_max: 30
-      web_search_keywords_max: 100
-  
+
   helper-friend:
     display_name: "Helper Friend"
-    description: |
-      **🧠 RESEARCH COMPANION - Deep analysis, bug investigation, informed decisions**
-      
-      This subagent conducts comprehensive research using codebase search, web research,
-      deep research with file attachments, and community consensus analysis.
-      
-      **What it does:**
-      - Codebase search (understand code structure, find similar patterns)
-      - Web research (best practices, documentation, tutorials)
-      - Deep research (technical questions with YOUR code as context)
-      - Reddit consensus (community experiences, real-world feedback)
-      
-      **Use cases:**
-      - 🐛 Bug investigation & root cause analysis
-      - 🏗️ Architecture & technology decisions
-      - 📚 Codebase understanding & discovery
-      - ✅ Best practices & pattern research
-      - 🔬 Pre-implementation research
-      
-      **Output includes:**
-      - Research findings with sources
-      - Recommendations with trade-offs
-      - Code examples where applicable
-      - Next steps and action items
-      
+    description: "Research companion - codebase search, web research, deep research, community analysis"
     category: "research"
-    default_model: ""  # Auto-select
     template_file: "helper-friend.mdx"
-    
-    tool_limits:
-      sequentialthinking_max: 30
-      sequentialthinking_min: 10
-      warpgrep_max: 20
-      warpgrep_min: 4
-      deep_research_questions_max: 100
-      deep_research_per_call: 10
-      web_search_keywords_max: 500
-      web_search_per_call: 50
-      scrape_urls_max: 100
-      scrape_per_call: 30
-      reddit_posts_max: 100
-      reddit_per_call: 50
-  
+
   manual-tester:
     display_name: "Manual Tester"
-    description: |
-      **🧪 QA ENGINEER - Tests implementation using REAL Chrome browser and terminal**
-      
-      This subagent manually tests your implementation like a human QA engineer,
-      using Chrome DevTools MCP for browser interactions and terminal for API testing.
-      
-      **What it tests:**
-      - UI interactions (clicks, forms, navigation)
-      - Visual verification (screenshots, layout)
-      - Console monitoring (JS errors, warnings)
-      - Network inspection (API calls, responses)
-      - API testing (curl commands, response validation)
-      - Responsive design (multiple viewport sizes)
-      
-      **Output includes:**
-      - Test results (✅ PASS / ❌ FAIL for each test case)
-      - Screenshots of key states
-      - Console errors captured
-      - API response verification
-      - Reproduction steps for failures
-      - Recommendations for fixes
-      
+    description: "QA engineer - tests with real Chrome browser, API testing, screenshots"
     category: "testing"
-    default_model: ""  # Auto-select
     template_file: "manual-tester.mdx"
-    
-    tool_limits:
-      sequentialthinking_max: 30
-      sequentialthinking_min: 15
-      browser_interactions_max: 50
-      viewports_max: 5
-      screenshots_max: 30
-      api_calls_max: 50
-      warpgrep_max: 10
-  
+
   manual:
     display_name: "Manual Executor"
-    description: |
-      **🔨 GENERAL-PURPOSE EXECUTOR - Implements, fixes, creates, and completes work**
-      
-      This subagent is a versatile executor that can handle ANY task that doesn't fit
-      the specialized categories. Unlike the other subagents (inspector, researcher, tester),
-      this one EXECUTES and COMPLETES work.
-      
-      **What it does:**
-      - Implements features (writes code, creates files)
-      - Fixes bugs (debugs, patches, tests)
-      - Refactors code (restructures, improves)
-      - Sets up projects (initializes, configures)
-      - Modifies existing code (updates, enhances)
-      - Runs commands (tests, builds, deploys)
-      
-      **Use cases:**
-      - 🔨 Feature implementation from scratch
-      - 🐛 Bug fixes with code changes
-      - ♻️ Code refactoring and restructuring
-      - 🏗️ Project setup and configuration
-      - ✏️ Code modifications and enhancements
-      - 🔧 General development tasks
-      
-      **Output includes:**
-      - Summary of changes made
-      - Files created/modified with details
-      - Commands executed and results
-      - Verification of requirements met
-      - Notes and recommendations
-      
+    description: "General executor - implements features, fixes bugs, runs commands"
     category: "execution"
-    default_model: ""  # Auto-select
     template_file: "manual.mdx"
-    
-    tool_limits:
-      sequentialthinking_max: 30
-      sequentialthinking_min: 8
-      warpgrep_max: 20
-      warpgrep_min: 3
-      deep_research_max: 30
-      deep_research_per_call: 5
-      web_search_keywords_max: 100
-      web_search_per_call: 10
-      file_operations_max: 50
-      terminal_commands_max: 30
-
-# ============================================================================
-# TOOL DEFINITION (Single consolidated tool)
-# ============================================================================
 
 tools:
   - name: check_subagent_task
-    category: status
-    capability: query
-    
-    description: |
-      **🔔 CHECK IF TASK IS READY - Notification-Aware Status Check**
-      
-      Check if an async subagent task is ready to retrieve results.
-      
-      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-      📣 MCP NOTIFICATIONS (Automatic!)
-      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-      
-      **You will receive automatic notifications when tasks complete!**
-      
-      When a task finishes, the server sends:
-      - `notifications/resources/list_changed` → New result resource available
-      - `notifications/resources/updated` → Specific task resource updated
-      
-      **If your client supports MCP notifications:**
-      - You'll see "🎉 Task 34567 is READY!" in the resources list
-      - Just read the `task://34567` resource to get the result
-      - No polling needed!
-      
-      **If your client doesn't support notifications:**
-      - Use this tool to poll the task status
-      - Check every 5-10 seconds until `status: completed`
-      
-      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-      📚 RESOURCES (Best Practice!)
-      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-      
-      **Completed tasks are also exposed as MCP Resources:**
-      
-      - **URI:** `task://34567`
-      - **Name:** `✅ Task 34567 - helper-friend`
-      - **Description:** `🎉 Task 34567 is READY! Result available.`
-      
-      You can read the resource directly instead of using this tool:
-      ```
-      Read resource: task://34567
-      ```
-      
-      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-      📊 TASK STATES
-      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-      
-      - `pending` - Task queued, not yet started
-      - `running` - 🔄 Task in progress (check back soon!)
-      - `completed` - ✅ **READY!** Result available
-      - `failed` - ❌ Task failed (error message available)
-      - `not_found` - Invalid task ID or expired (1 hour TTL)
-      
-      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-      📋 RESPONSE EXAMPLES
-      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-      
-      **🔄 Still Running:**
-      ```json
-      {
-        "task_id": 34567,
-        "status": "running",
-        "progress": 45,
-        "task_type": "helper-friend",
-        "started_at": "2024-01-15T10:30:00Z"
-      }
-      ```
-      → Wait and check again, or wait for notification!
-      
-      **✅ READY - Task Completed:**
-      ```json
-      {
-        "task_id": 34567,
-        "status": "completed",
-        "result": "## Helper Friend Result\n\n...",
-        "task_type": "helper-friend",
-        "completed_at": "2024-01-15T10:35:00Z",
-        "duration_seconds": 300
-      }
-      ```
-      → 🎉 Result is in the response! Also available as resource `task://34567`
-      
-      **❌ Task Failed:**
-      ```json
-      {
-        "task_id": 34567,
-        "status": "failed",
-        "error": "API quota exceeded",
-        "task_type": "helper-friend"
-      }
-      ```
-
+    description: "Check async task status. Poll until `status: completed`, then read `result`."
     parameters:
       task_ids:
         type: array
         required: true
-        items:
-          type: integer
-        validation:
-          minItems: 1
-        description: |
-          **[REQUIRED] Array of 5-digit task IDs**
-          
-          Pass one or more task IDs returned by `gemini-subagent` when called with `async: true`.
-          
-          **Examples:**
-          - Single task: `[34567]`
-          - Multiple tasks: `[34567, 34568, 34569]`
-          
-          **Smart Behavior:**
-          - Completed/failed tasks are shown FIRST with full results
-          - Running/pending tasks are listed in header/footer as "Waiting Tasks"
-          - Only call this with task IDs you haven't received results for yet
-          - Already-completed task results are displayed immediately (no re-fetching)
-          
-          **Output Format:**
-          - Header: `Waiting Tasks: 10003, 10004` (if any incomplete)
-          - Each completed task: `# Task ID: 0001` H1 heading with result
-          - Footer: Same waiting tasks list
-          
-          **Pro tip:** If your client supports notifications, you'll see completed
-          tasks appear in the resources list automatically!
+        description: "Array of 5-digit task IDs. Example: `[34567]`"
 
   - name: gemini-subagent
-    category: execution
-    capability: autonomous
-    
     description: |
-      **🤖 GEMINI SUBAGENT - Specialized Task Execution**
-      
-      Single unified tool with three specialized modes via strict task_type enum.
-      
-      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-      📋 TASK TYPE ENUM (Required - NO STRINGS, NO GUESSING!)
-      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-      
-      Must be EXACTLY one of these four values:
-      
-      **1. `completion-inspector`** - CTO-Level Code Review
-      
-      **Purpose:** Verifies if a task is TRULY 100% complete
-      
-      **Uses:**
-      - Git diff analysis (line-by-line change review)
-      - Codebase search (find duplicates, missed abstractions)
-      - Pattern detection (consistency with existing code)
-      - Quality assessment (cleanup opportunities)
-      
-      **When to use:**
-      - ✅ After implementation, before marking "done"
-      - ✅ After major refactoring or feature work
-      - ✅ Before committing final changes
-      - ✅ When you suspect cleanup is needed
-      
-      **When NOT to use:**
-      - ❌ Task clearly still in progress
-      - ❌ Haven't made any changes yet
-      - ❌ Simple one-line changes
-      
-      **Output:** Completion %, requirements met/not met, quality issues, action items
-      
-      **Model:** Auto-select (Gemini CLI chooses best)
-      
-      ---
-      
-      **2. `helper-friend`** - Research Companion
-      
-      **Purpose:** Deep analysis, bug investigation, informed decision-making
-      
-      **Uses:**
-      - Codebase search (understand code structure)
-      - Web research (best practices, documentation)
-      - Deep research (technical questions with file attachments)
-      - Reddit consensus (community experiences)
-      
-      **When to use:**
-      - ✅ Bug investigation & root cause analysis
-      - ✅ Architecture & technology decisions
-      - ✅ Codebase understanding & discovery
-      - ✅ Best practices & pattern research
-      - ✅ Pre-implementation research
-      
-      **When NOT to use:**
-      - ❌ Already know what to do, just need to code
-      - ❌ Simple questions you can answer yourself
-      - ❌ Tasks needing immediate action, not research
-      
-      **Output:** Research findings, recommendations, trade-offs, sources
-      
-      **Model:** Auto-select (Gemini CLI chooses best)
-      
-      ---
-      
-      **3. `manual-tester`** - QA Engineer with Real Browser
-      
-      **Purpose:** Tests if implementation actually WORKS using real Chrome browser
-      
-      **Uses:**
-      - Chrome DevTools MCP (real browser interactions)
-      - Terminal/curl (API testing)
-      - Screenshots (visual verification)
-      - Console monitoring (JS error detection)
-      - Network inspection (API call verification)
-      
-      **When to use:**
-      - ✅ After completion-inspector confirms 100% code complete
-      - ✅ Frontend changes need testing
-      - ✅ Backend/API changes need testing
-      - ✅ Full flow verification
-      - ✅ Responsive design verification
-      
-      **When NOT to use:**
-      - ❌ Code isn't complete yet
-      - ❌ No user-facing changes to test
-      - ❌ Pure refactoring with no behavior changes
-      
-      **Output:** Test report with pass/fail, reproduction steps, screenshots, console errors
-      
-      **Model:** Auto-select (Gemini CLI chooses best)
-      
-      ---
-      
-      **4. `manual`** - General-Purpose Executor
-      
-      **Purpose:** Implements, fixes, creates, and completes ANY task
-      
-      **Uses:**
-      - File operations (read, write, edit)
-      - Terminal commands (test, build, install)
-      - Codebase search (understand existing code)
-      - Research tools (when external knowledge needed)
-      
-      **When to use:**
-      - ✅ Feature implementation from scratch
-      - ✅ Bug fixes with code changes
-      - ✅ Code refactoring and restructuring
-      - ✅ Project setup and configuration
-      - ✅ General development tasks
-      
-      **When NOT to use:**
-      - ❌ Only need inspection (use completion-inspector)
-      - ❌ Only need research (use helper-friend)
-      - ❌ Only need testing (use manual-tester)
-      
-      **Output:** Summary of changes, files modified, verification results
-      
-      **Model:** Auto-select (Gemini CLI chooses best)
-      
-      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-      ⚙️ HOW IT WORKS
-      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-      
-      1. You select task_type enum (strict validation)
-      2. System loads corresponding MDX template
-      3. Merges template + your prompt
-      4. Executes: `gemini --yolo -p "[merged_prompt]"`
-      5. Returns specialized result
-      
-      **No shell commands, no intermediate steps** - Pure CLI-to-prompt translation.
+      Gemini subagent with 4 task types:
+      - `completion-inspector`: Verify task completion (git diff, patterns, requirements)
+      - `helper-friend`: Research (codebase, web, docs, community)
+      - `manual-tester`: QA testing (browser, API, screenshots)
+      - `manual`: General executor (implement, fix, run commands)
 
     parameters:
       task_type:
         type: string
         required: true
-        validation:
-          pattern: "^(completion-inspector|helper-friend|manual-tester|manual)$"
-        description: |
-          **🎯 [REQUIRED] TASK TYPE SELECTOR - Choose Your Specialist**
-          
-          ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-          ⚠️ STRICT ENUM - Must be EXACTLY one of these four values!
-          ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-          
-          **1️⃣ `completion-inspector`** - CTO-Level Code Auditor
-          
-          **Use when:** You think your task is done and need verification
-          **What it does:** Analyzes git diff, checks patterns, finds issues
-          **Output:** Completion %, requirements checklist, action items
-          
-          ✅ Use for: After implementation, before PR, after refactoring
-          ❌ Skip if: Still coding, no changes yet, trivial fixes
-          
-          ---
-          
-          **2️⃣ `helper-friend`** - Research & Investigation Expert
-          
-          **Use when:** You need research, analysis, or decision support
-          **What it does:** Searches codebase, web, docs, community
-          **Output:** Findings, recommendations, trade-offs, sources
-          
-          ✅ Use for: Bug investigation, architecture decisions, learning patterns
-          ❌ Skip if: You already know what to do, simple questions
-          
-          ---
-          
-          **3️⃣ `manual-tester`** - QA Engineer with Real Browser
-          
-          **Use when:** Implementation is complete and needs testing
-          **What it does:** Browser testing, API testing, screenshots
-          **Output:** Test results, failures, screenshots, console errors
-          
-          ✅ Use for: UI testing, API testing, integration testing
-          ❌ Skip if: Code not ready, no user-facing changes, pure refactor
-          
-          ---
-          
-          **4️⃣ `manual`** - General-Purpose Executor
-          
-          **Use when:** You need to implement, fix, create, or complete a task
-          **What it does:** Executes file operations, terminal commands, codebase search, and research tools
-          **Output:** Summary of changes, files modified, verification results
-          
-          ✅ Use for: Feature implementation, bug fixes, code refactoring, project setup, and general development tasks
-          ❌ Skip if: Only need inspection, research, or testing
-          
-          ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-          🔄 RECOMMENDED WORKFLOW
-          ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-          
-          ```
-          1. Research phase → helper-friend (understand problem)
-          2. Implementation → [your coding work]
-          3. Verification → completion-inspector (is it done?)
-          4. Testing → manual-tester (does it work?)
-          5. Done → PR/commit
-          ```
-          
-          **VALIDATION:** Server rejects invalid task types immediately.
-          The selected type loads a specialized MDX template optimized for that task.
+        description: "One of: `completion-inspector`, `helper-friend`, `manual-tester`, `manual`"
 
       prompt:
         type: string
         required: true
-        validation:
-          minLength: 20
         description: |
-          **🔥🔥🔥 [REQUIRED] YOUR TASK-SPECIFIC PROMPT - MINIMUM 500-1000 WORDS EXPECTED 🔥🔥🔥**
-          
-          ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-          ⚠️ CRITICAL: THE SUBAGENT IS COMPLETELY BLIND WITHOUT YOUR CONTEXT
-          ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-          
-          The subagent has **ZERO** context about:
-          - Your codebase structure
-          - Your project goals
-          - Your tech stack
-          - Your constraints
-          - What you've already tried
-          - What files exist
-          - What the task even is
-          
-          **YOU MUST PROVIDE EVERYTHING.** Assume you're explaining to a brilliant
-          engineer who just joined the team 5 minutes ago. They're smart but they
-          know NOTHING about your project.
-          
-          **For manual-tester, provide:**
-          - Frontend URL (MANDATORY!)
-          - Backend URL (if applicable)
-          - Auth credentials
-          - Feature description
-          - Expected behaviors
-          - Test data
-          - Edge cases to test
-          
-          **For manual, provide:**
-          - Clear task description
-          - Requirements or acceptance criteria
-          - Relevant file paths or context
-          - Any constraints or preferences
-          - Expected outcome
-          
-          Minimum 20 characters required.
-          PROVIDE EVERYTHING.** Assume you're explaining to a brilliant
-          engineer who just joined the team 5 minutes ago. They're smart but they
-          know NOTHING about your project.
-          
-          ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-          📊 QUALITY SCALE - BE BRUTALLY HONEST WITH YOURSELF
-          ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-          
-          **WORD COUNT → QUALITY LEVEL → WHAT YOU'LL GET**
-          
-          **< 50 words** → 💀 GARBAGE
-          - "Check if done" / "Fix the bug" / "Test login"
-          - Response: Generic platitudes, wastes everyone's time
-          - You're better off not calling the subagent at all
-          
-          **50-100 words** → ❌ USELESS  
-          - Brief mention of task, no files, no context
-          - Response: Vague suggestions that don't apply to your code
-          - The subagent is guessing blindly
-          
-          **100-200 words** → ⚠️ POOR
-          - Some context but missing critical details
-          - Response: Partially relevant but misses your actual situation
-          - 50% of insights will be off-target
-          
-          **200-300 words** → 😐 MEDIOCRE
-          - Basic context, some files mentioned
-          - Response: Generally useful but lacks specificity
-          - You'll need follow-up questions
-          
-          **300-500 words** → ✅ ACCEPTABLE
-          - Good context, file paths included, requirements stated
-          - Response: Relevant and actionable
-          - Minimum threshold for useful output
-          
-          **500-750 words** → 🎯 GOOD
-          - Comprehensive context, detailed file descriptions
-          - What you tried, why it failed, specific questions
-          - Response: Highly targeted, specific recommendations
-          
-          **750-1000 words** → ⭐ EXCELLENT
-          - Full context: files, requirements, acceptance criteria
-          - Tech stack, constraints, edge cases, what you've tried
-          - Response: Expert-level analysis, production-ready advice
-          
-          **1000+ words** → 🏆 EXCEPTIONAL
-          - Complete project context, detailed file-by-file breakdown
-          - Historical context, related issues, future considerations
-          - Response: CTO-level strategic recommendations
-          
-          **🎯 TARGET: 500-1000 words minimum for any serious task!**
-          
-          ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-          📁 FILE CONTEXT - ABSOLUTELY MANDATORY
-          ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-          
-          **YOU MUST INCLUDE relative file paths for ALL relevant files!**
-          
-          The subagent CANNOT see your filesystem. If you don't tell it which
-          files exist and what they do, it's operating completely blind.
-          
-          **FORMAT:** Use relative paths from project root with descriptions:
-          
-          ```
-          📁 FILES CHANGED/RELEVANT:
-          
-          src/auth/auth.controller.ts
-          - Purpose: Handles login/register/logout endpoints
-          - What changed: Added JWT refresh token logic (lines 45-120)
-          - Dependencies: Uses src/auth/jwt.service.ts for token generation
-          - Exports: AuthController class with 4 public methods
-          
-          src/auth/jwt.service.ts  
-          - Purpose: JWT token generation and validation
-          - What changed: New refreshToken() method added
-          - Key functions: generateToken(), validateToken(), refreshToken()
-          - Config: Uses JWT_SECRET from environment
-          
-          src/middleware/auth.guard.ts
-          - Purpose: Protects routes requiring authentication
-          - What changed: Now checks for refresh token in cookie
-          - How it works: Extracts token from Authorization header or cookie
-          - Used by: All /api/protected/* routes
-          
-          src/types/auth.types.ts
-          - Purpose: TypeScript interfaces for auth
-          - What changed: Added RefreshTokenPayload interface
-          - Exports: User, TokenPayload, RefreshTokenPayload, AuthResponse
-          
-          tests/auth/auth.controller.spec.ts
-          - Purpose: Unit tests for auth controller
-          - What changed: Added 5 new tests for refresh flow
-          - Coverage: Now covers happy path + 3 error cases
-          ```
-          
-          **WHY THIS MATTERS:**
-          - Subagent can understand your architecture
-          - Can identify missing pieces
-          - Can check for consistency across files
-          - Can suggest improvements based on actual structure
-          
-          ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-          📋 TASK CONTEXT - WHAT ARE YOU ACTUALLY DOING?
-          ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-          
-          **Include the FULL context of what task you're working on:**
-          
-          ```
-          🎯 TASK CONTEXT:
-          
-          **Task Title:** Add JWT refresh token authentication
-          
-          **Background:** 
-          We're building a SaaS platform. Users were complaining about
-          being logged out every hour. We need refresh tokens to keep
-          sessions alive for 7 days while maintaining security.
-          
-          **Original Requirements:**
-          1. Access tokens expire in 15 minutes (security)
-          2. Refresh tokens expire in 7 days (convenience)
-          3. Refresh tokens stored in HTTP-only cookie (XSS protection)
-          4. Refresh token rotation on each refresh (security)
-          5. Invalidate all tokens on password change
-          
-          **Acceptance Criteria:**
-          - [ ] POST /auth/login returns access token + sets refresh cookie
-          - [ ] POST /auth/refresh exchanges refresh token for new access token
-          - [ ] Refresh token is rotated on each use
-          - [ ] Old refresh tokens are invalidated
-          - [ ] Password change invalidates all user sessions
-          
-          **Tech Stack:**
-          - Node.js 20 + Express 4.18
-          - TypeScript 5.3
-          - PostgreSQL 15 with Prisma ORM
-          - Jest for testing
-          - Redis for token blacklist
-          
-          **What I've Done So Far:**
-          1. Created jwt.service.ts with token generation ✅
-          2. Updated auth.controller.ts with refresh endpoint ✅
-          3. Added refresh token to login response ✅
-          4. Modified auth.guard.ts to check cookies ✅
-          5. Written basic tests ⏳ (in progress)
-          
-          **What's Not Working:**
-          - Token rotation works but old tokens aren't being blacklisted
-          - Tests are flaky - sometimes pass, sometimes fail
-          - Not sure if my Redis implementation is correct
-          
-          **Specific Questions:**
-          1. Is my refresh token rotation implementation secure?
-          2. Should I use Redis SET or SORTED SET for blacklist?
-          3. How do I make my tests deterministic?
-          ```
-          
-          ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-          🔧 WHAT YOU'VE TRIED - PREVENT DUPLICATE SUGGESTIONS
-          ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-          
-          **Tell the subagent what you've already attempted:**
-          
-          ```
-          🔄 WHAT I'VE TRIED:
-          
-          1. Used JWT library's built-in expiry
-             → Problem: Couldn't invalidate tokens before expiry
-             
-          2. Stored tokens in database
-             → Problem: Too slow, 50ms+ per request
-             
-          3. Redis with simple SET
-             → Problem: No automatic expiry, memory grows forever
-             
-          4. Asked ChatGPT
-             → Got generic advice that didn't fit our architecture
-          ```
-          
-          **WHY THIS MATTERS:**
-          - Avoids wasting time on already-tried solutions
-          - Helps subagent understand what DOESN'T work
-          - Shows your thinking process for better recommendations
-          
-          ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-          📋 PROMPT TEMPLATES BY TASK TYPE (FOLLOW EXACTLY!)
-          ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-          
-          **═══ COMPLETION-INSPECTOR TEMPLATE ═══**
-          
-          ```
-          🎯 TASK TITLE: [One-line description]
-          
-          📋 ORIGINAL REQUIREMENTS:
-          1. [Requirement 1 - be specific]
-          2. [Requirement 2 - include acceptance criteria]
-          3. [Requirement 3 - mention edge cases if any]
-          
-          ✅ ACCEPTANCE CRITERIA:
-          - [Criterion 1 - how to verify it's met]
-          - [Criterion 2 - testable condition]
-          - [Criterion 3 - measurable outcome]
-          
-          📝 IMPLEMENTATION SUMMARY:
-          [2-3 sentences describing what you implemented and your approach]
-          
-          📁 FILES CHANGED:
-          - `src/path/to/file1.ts` - [What changed and why]
-          - `src/path/to/file2.ts` - [What changed and why]
-          - `tests/path/to/test.ts` - [Tests added/modified]
-          
-          🔖 GIT CONTEXT:
-          - START_COMMIT: [hash or "HEAD~N"]
-          - Branch: [feature branch name]
-          
-          💭 WHY I THINK IT'S COMPLETE:
-          [Explain your reasoning - what makes you confident it's done?]
-          
-          ⚠️ AREAS OF CONCERN (if any):
-          [Any parts you're unsure about or want extra scrutiny on]
-          ```
-          
-          **═══ HELPER-FRIEND TEMPLATE ═══**
-          
-          ```
-          🎯 ULTIMATE GOAL:
-          [What are you trying to achieve? What does success look like?]
-          
-          📍 CURRENT SITUATION:
-          [Where are you now? What's the context?]
-          
-          📁 RELEVANT FILES (with descriptions):
-          - `src/path/to/file1.ts` - [What this file does, why it's relevant]
-          - `src/path/to/file2.ts` - [What this file does, why it's relevant]
-          
-          🔄 WHAT I'VE TRIED:
-          1. [Approach 1] → [Result/Why it didn't work]
-          2. [Approach 2] → [Result/Why it didn't work]
-          
-          ❓ SPECIFIC QUESTIONS:
-          1. [Question 1 - be specific, not vague]
-          2. [Question 2 - include context]
-          3. [Question 3 - what decision does this inform?]
-          
-          🚧 CURRENT BLOCKER:
-          [What's stopping you? Be specific about the problem.]
-          
-          📌 CONSTRAINTS:
-          - [Constraint 1 - tech stack limitations]
-          - [Constraint 2 - timeline/scope]
-          - [Constraint 3 - compatibility requirements]
-          
-          🎯 WHAT I NEED FROM YOU:
-          [Specific ask - research? recommendations? code examples?]
-          ```
-          
-          **═══ MANUAL-TESTER TEMPLATE ═══**
-          
-          ```
-          🌐 URLS (MANDATORY!):
-          - Frontend: [http://localhost:3000 or deployed URL]
-          - Backend API: [http://localhost:8000/api or deployed URL]
-          - Admin panel: [if applicable]
-          
-          🔐 AUTH CREDENTIALS (if needed):
-          - Username: [test user]
-          - Password: [test password]
-          - Or: [How to authenticate]
-          
-          📝 FEATURE TO TEST:
-          [Describe the feature in 2-3 sentences]
-          
-          ✅ EXPECTED BEHAVIORS:
-          1. [When user does X] → [Y should happen]
-          2. [When user does A] → [B should appear]
-          3. [Form validation] → [These errors should show]
-          
-          🧪 TEST SCENARIOS:
-          - Happy path: [Normal user flow to test]
-          - Error path: [Invalid input scenarios]
-          - Edge cases: [Boundary conditions]
-          
-          📊 TEST DATA:
-          - Valid input: [example values]
-          - Invalid input: [example values that should fail]
-          
-          📱 VIEWPORTS TO TEST:
-          - Desktop (1920x1080)
-          - Tablet (768x1024)
-          - Mobile (375x667)
-          
-          ⚠️ KNOWN ISSUES (skip these):
-          [Any known bugs to ignore during testing]
-          ```
-          
-          ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-          ❌ BAD vs ✅ GOOD EXAMPLES - THE DIFFERENCE IS NIGHT AND DAY
-          ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-          
-          **💀 GARBAGE (~5 words) - Complete waste of time:**
-          ```
-          "Check if it's done"
-          "Fix the bug"
-          "Test login"
-          ```
-          → Response will be: "I don't have enough context to help. Please provide..."
-          → You've wasted time and learned nothing
-          
-          **❌ USELESS (~30 words) - Subagent is guessing blindly:**
-          ```
-          "I added authentication to my Node.js app. Can you verify 
-          it's complete? I think I covered everything but not sure."
-          ```
-          → What kind of auth? What files? What requirements? What's "everything"?
-          → Response will be generic checklist that may not apply to your code
-          
-          **⚠️ POOR (~80 words) - Half the insights will be wrong:**
-          ```
-          "I'm working on JWT authentication for our Express API. I created
-          auth.controller.ts and jwt.service.ts. The login works but I'm
-          not sure about the refresh token implementation. We need tokens
-          to expire in 1 hour but users shouldn't be logged out while active."
-          ```
-          → Better but: What's in those files? What's the actual implementation?
-          → What does "not sure" mean specifically? What have you tried?
-          
-          **✅ ACCEPTABLE (~200 words) - Minimum for useful output:**
-          ```
-          🎯 TASK: JWT refresh token authentication
-          
-          📋 REQUIREMENTS:
-          1. Access tokens expire in 15 minutes
-          2. Refresh tokens expire in 7 days
-          3. Refresh tokens in HTTP-only cookies
-          
-          📁 FILES:
-          - src/auth/auth.controller.ts - Login/register/refresh endpoints
-          - src/auth/jwt.service.ts - Token generation and validation
-          - src/middleware/auth.guard.ts - Route protection
-          
-          ✅ ACCEPTANCE:
-          - POST /auth/login returns access token + sets refresh cookie
-          - POST /auth/refresh returns new access token
-          - Invalid tokens return 401
-          
-          💭 STATUS: Login works, refresh endpoint exists but untested
-          
-          ❓ QUESTIONS:
-          1. Is storing refresh token in cookie secure?
-          2. Should I rotate refresh tokens?
-          ```
-          
-          **🎯 GOOD (~500 words) - Highly targeted recommendations:**
-          ```
-          🎯 TASK TITLE: Implement JWT refresh token authentication
-          
-          **Background:**
-          Building a SaaS dashboard. Users complained about hourly logouts.
-          Need refresh tokens to maintain sessions for 7 days while keeping
-          access tokens short-lived for security.
-          
-          📋 ORIGINAL REQUIREMENTS:
-          1. Access tokens: 15 minute expiry (security best practice)
-          2. Refresh tokens: 7 day expiry (user convenience)
-          3. Refresh tokens: HTTP-only cookie (XSS protection)
-          4. Token rotation: New refresh token on each refresh (security)
-          5. Revocation: Password change invalidates all sessions
-          
-          ✅ ACCEPTANCE CRITERIA:
-          - [ ] POST /auth/login returns {accessToken} + sets refreshToken cookie
-          - [ ] POST /auth/refresh exchanges refresh for new access + new refresh
-          - [ ] Protected routes return 401 without valid access token
-          - [ ] Refresh with old/rotated token fails (single-use enforcement)
-          - [ ] Password change via /auth/password invalidates all tokens
-          
-          📁 FILES CHANGED:
-          
-          src/auth/auth.controller.ts (lines 1-120)
-          - Purpose: HTTP endpoints for auth operations
-          - Changes: Added /refresh endpoint, modified /login to set cookie
-          - Exports: AuthController with login(), register(), refresh(), logout()
-          - Dependencies: JwtService, UserService, Response (for cookies)
-          
-          src/auth/jwt.service.ts (lines 1-85)
-          - Purpose: Token generation, validation, rotation logic
-          - Changes: Added generateRefreshToken(), rotateRefreshToken(), blacklistToken()
-          - Key logic: Uses Redis for token blacklist with TTL matching token expiry
-          - Config: JWT_SECRET, REFRESH_SECRET from env
-          
-          src/middleware/auth.guard.ts (lines 1-45)
-          - Purpose: Protects routes requiring authentication
-          - Changes: Now extracts token from Authorization header OR cookie
-          - Logic: Validates access token, attaches user to request
-          
-          src/auth/dto/auth.dto.ts (lines 1-30)
-          - Purpose: Request/response type definitions
-          - Changes: Added RefreshTokenDto, TokenResponseDto
-          
-          tests/auth/auth.e2e-spec.ts (lines 1-150)
-          - Purpose: End-to-end auth flow tests
-          - Changes: Added 8 tests for refresh flow
-          - Coverage: Happy path, expired token, rotated token, blacklisted token
-          
-          🔖 GIT CONTEXT:
-          - START_COMMIT: abc123 (before auth changes)
-          - Current branch: feature/refresh-tokens
-          - 12 commits since start
-          
-          🔧 TECH STACK:
-          - Node.js 20, Express 4.18, TypeScript 5.3
-          - Prisma ORM with PostgreSQL 15
-          - Redis 7 for token blacklist
-          - Jest + Supertest for testing
-          
-          🔄 WHAT I'VE TRIED:
-          1. Storing tokens in database → Too slow (50ms/request)
-          2. JWT blacklist without Redis → Memory leak in production
-          3. Simple refresh without rotation → Security concern flagged in review
-          
-          💭 WHY I THINK IT'S COMPLETE:
-          - All 5 requirements implemented
-          - 8/8 e2e tests passing
-          - Manual testing works in Postman
-          - Code reviewed by team lead
-          
-          ⚠️ AREAS OF CONCERN:
-          - Redis connection handling during reconnects
-          - Is my token rotation truly atomic?
-          - Should blacklist use SET or SORTED SET?
-          
-          ❓ SPECIFIC QUESTIONS:
-          1. Is the refresh token rotation implementation secure against race conditions?
-          2. Is storing the refresh token family ID sufficient for revocation?
-          3. Any edge cases I'm missing in my test coverage?
-          ```
-          → This prompt gives the subagent EVERYTHING it needs to provide
-             expert-level, specific, actionable recommendations
-          
-          ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-          💡 PRO TIPS FOR MAXIMUM QUALITY OUTPUT
-          ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-          
-          1. **TARGET 500-1000 WORDS** - Seriously, more context = better output
-          2. **LIST EVERY FILE** - With relative paths AND what each file does
-          3. **DESCRIBE WHAT CHANGED** - Not just "modified" but HOW and WHY
-          4. **INCLUDE LINE NUMBERS** - "auth logic at lines 45-120" helps focus
-          5. **STATE YOUR TECH STACK** - Versions matter for compatibility advice
-          6. **EXPLAIN WHAT YOU TRIED** - Prevents duplicate suggestions
-          7. **ASK SPECIFIC QUESTIONS** - "Is X secure?" not "Is it good?"
-          8. **MENTION EDGE CASES** - What weird scenarios worry you?
-          9. **INCLUDE ERROR MESSAGES** - Exact errors, not paraphrased
-          10. **SHARE YOUR REASONING** - Why you made certain choices
-          
-          **THE GOLDEN RULE:**
-          
-          Imagine you're onboarding a brilliant senior engineer who just joined
-          your team. They've never seen your codebase. What would you tell them
-          to get them up to speed and able to give expert advice?
-          
-          **THAT is what your prompt should contain.**
-          
-          **REMEMBER:**
-          - 💀 < 50 words = You're wasting everyone's time
-          - ⚠️ 50-200 words = Expect generic, often wrong advice
-          - ✅ 200-500 words = Acceptable, targeted recommendations
-          - 🎯 500-1000 words = Expert-level, production-ready insights
-          - 🏆 1000+ words = CTO-level strategic guidance
+          Your task prompt. Include: task description, relevant files, requirements, context.
+          More detail = better results. Min 20 chars.
 
       model:
         type: string
         required: false
-        description: |
-          **[OPTIONAL] Override model selection**
-          
-          Leave empty to use task type's default:
-          - completion-inspector: gemini-3-pro
-          - helper-friend: auto-select
-          - manual-tester: gemini-3-pro
-          
-          Available: `gemini-3-pro`, `gemini-3-flash`
+        description: "Override model. Leave empty for auto-select."
 
       sandbox:
         type: boolean
         required: false
         default: false
-        description: |
-          **[OPTIONAL] Run in sandbox mode**
-          
-          Enables sandbox isolation for safer execution.
-          Flag: --sandbox / -s
+        description: "Run in sandbox mode."
 
       approval_mode:
         type: string
         required: false
-        description: |
-          **[OPTIONAL] Override approval mode**
-          
-          Valid values:
-          - `default` - Prompt for approval
-          - `auto_edit` - Auto-approve edit tools
-          - `yolo` - Auto-approve all tools
-          
-          Leave empty to use --yolo (auto-approve all)
+        description: "Override: `default`, `auto_edit`, or `yolo`"
 
       include_directories:
         type: string
         required: false
-        description: |
-          **[OPTIONAL] Include additional directories**
-          
-          Comma-separated list of directories to include.
-          Example: "src,docs,tests"
+        description: "Additional directories. Example: `src,docs,tests`"
 
       include_instructions:
         type: boolean
         required: false
         default: true
-        description: |
-          Include task-specific instructions from MDX template.
-          Default: true (recommended)
-          Set false: For custom prompts that don't need template
+        description: "Include MDX template instructions. Default: true"
 
       async:
         type: boolean
         required: false
         default: true
         description: |
-          **[OPTIONAL] Async execution mode**
-          
-          **Default: true (async)**
-          - Returns immediately with a 5-digit task ID (e.g., 34567)
-          - Task runs in background
-          - Query status with `check_subagent_task` tool using the task ID
-          - Results stored in memory until retrieved
-          
-          **Set to false (sync/blocking):**
-          - Blocks until task completes
-          - Returns full result directly
-          - Use for quick tasks where you need immediate result
-          
-          **Example async flow:**
-          1. Call `gemini-subagent` with `async: true` (default)
-          2. Receive: `{"task_id": 34567, "status": "running"}`
-          3. Later: Call `check_subagent_task` with `task_id: 34567`
-          4. Receive: `{"status": "completed", "result": "..."}` or `{"status": "running"}`
-          
-          **⚠️ IMPORTANT:** When async=true, the response is NOT the result!
-          You MUST call `check_subagent_task` to get the actual result.
+          Async mode (default: true). Returns task_id immediately.
+          Set false to block and return result directly.