gemini-helper-friend 2.0.0 → 2.0.2

package/dist/config/yaml/subagents.yaml

@@ -1,13 +1,52 @@
 # Gemini Helper Friend MCP - Subagent Configuration
 # YAML for metadata only - prompt templates in MDX files
-# Version: 2.0
+# Version: 2.1 - Enhanced descriptions with forcing patterns
+# Optimization: Detailed descriptions that force high-quality, structured prompts
 
-version: "2.0"
+version: "2.1"
 
 metadata:
   name: "gemini-helper-friend-mcp"
   displayName: "Gemini - Helper Friend MCP"
-  description: "Autonomous AI helper with specialized task types"
+  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
@@ -44,7 +83,25 @@ task_types:
   
   completion-inspector:
     display_name: "Completion Inspector"
-    description: "CTO-level code inspector that verifies if a task is TRULY 100% complete"
+    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
+      
     category: "verification"
     default_model: ""  # Auto-select
     template_file: "completion-inspector.mdx"
@@ -59,7 +116,31 @@ task_types:
   
   helper-friend:
     display_name: "Helper Friend"
-    description: "Research companion for deep analysis, bug investigation, and informed decision-making"
+    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
+      
     category: "research"
     default_model: ""  # Auto-select
     template_file: "helper-friend.mdx"
@@ -80,7 +161,28 @@ task_types:
   
   manual-tester:
     display_name: "Manual Tester"
-    description: "QA engineer who manually tests implementation using real Chrome browser and terminal"
+    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
+      
     category: "testing"
     default_model: ""  # Auto-select
     template_file: "manual-tester.mdx"
@@ -93,6 +195,54 @@ task_types:
       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
+      
+    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)
@@ -218,7 +368,7 @@ tools:
       📋 TASK TYPE ENUM (Required - NO STRINGS, NO GUESSING!)
       ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
       
-      Must be EXACTLY one of these three values:
+      Must be EXACTLY one of these four values:
       
       **1. `completion-inspector`** - CTO-Level Code Review
       
@@ -302,6 +452,34 @@ tools:
       
       **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
       ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -319,16 +497,70 @@ tools:
         type: string
         required: true
         validation:
-          pattern: "^(completion-inspector|helper-friend|manual-tester)$"
+          pattern: "^(completion-inspector|helper-friend|manual-tester|manual)$"
         description: |
-          **[REQUIRED] Task type enum - NO STRINGS, NO GUESSING**
+          **🎯 [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
           
-          Must be EXACTLY one of:
-          - `completion-inspector` - Code review and verification
-          - `helper-friend` - Research and investigation
-          - `manual-tester` - QA testing with browser
+          ---
           
-          The system will load the appropriate MDX template and merge with your prompt.
+          **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.
 
       prompt:
         type: string
@@ -336,25 +568,24 @@ tools:
         validation:
           minLength: 20
         description: |
-          **[REQUIRED] Your task-specific prompt**
-          
-          This will be merged with the task type's MDX template.
-          
-          **For completion-inspector, provide:**
-          - Original task requirements
-          - Acceptance criteria
-          - Implementation summary
-          - Files changed with descriptions
-          - START_COMMIT hash
-          - Why you think it's complete
-          
-          **For helper-friend, provide:**
-          - Ultimate goal and success criteria
-          - Current situation
-          - Files involved with descriptions
-          - What you've tried
-          - Current blocker/question
-          - Constraints
+          **🔥🔥🔥 [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!)
@@ -365,7 +596,480 @@ tools:
           - 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
 
       model:
         type: string