jacksonemmerich/agent-detector

Aura Frog Agent Detector

Priority: HIGHEST - Runs FIRST for every message Version: 3.0.0

---

When to Use

ALWAYS - Every user message, no exceptions.

---

Auto-Complexity Detection

AI auto-detects task complexity. User doesn't need :fast or :hard variants.

Complexity Levels

complexity[3]{level,criteria,approach}:
  Quick,Single file/Simple fix/Clear scope,Direct implementation - skip research
  Standard,2-5 files/Feature add/Some unknowns,Scout first then implement
  Deep,6+ files/Architecture/Vague scope,Research + plan + implement

Auto-Detection Criteria

Quick (1-2 tool calls):

• Typo fix, single variable rename
• Add console.log/debugging
• Simple CSS change
• Clear file path given
• "Just do X" explicit instruction

Standard (3-6 tool calls):

• New component/function
• Bug fix with clear error
• API endpoint addition
• File modification with tests

Deep (7+ tool calls, use workflow-orchestrator):

• New feature across multiple files
• Refactoring/architecture change
• Vague requirements ("make it better")
• Security audit
• Performance optimization
• User asks to "plan" or "design"

Detection Logic

1. Count mentioned files/components
2. Check for vague vs specific language
3. Detect scope modifiers (all, entire, every)
4. Check for research keywords (how, why, best way)
5. Assign complexity level

---

Model Selection

Auto-select model based on task complexity and agent type.

Model Mapping

model_selection[3]{model,when_to_use,agents}:
  haiku,Quick tasks/Simple queries/Orchestration,pm-operations-orchestrator/project-manager
  sonnet,Standard implementation/Coding/Testing/Bug fixes,All dev agents/qa-automation/ui-expert
  opus,Architecture/Deep analysis/Security audits/Complex planning,security-expert (audits)/Any agent (architecture mode)

Complexity → Model

complexity_model[3]{complexity,default_model,override_to_opus}:
  Quick,haiku,Never
  Standard,sonnet,User asks for architecture/design
  Deep,sonnet,Always consider opus for planning phase

Task Type → Model

task_model[8]{task_type,model,reason}:
  Typo fix / config change,haiku,Minimal reasoning needed
  Bug fix / feature add,sonnet,Standard implementation
  API endpoint / component,sonnet,Standard implementation
  Test writing,sonnet,Requires code understanding
  Code review,sonnet,Pattern matching + analysis
  Architecture design,opus,Complex trade-off analysis
  Security audit,opus,Deep vulnerability analysis
  Refactoring / migration,opus,Cross-cutting impact analysis

Agent Default Models

agent_models[11]{agent,default_model,opus_when}:
  pm-operations-orchestrator,haiku,Never (orchestration only)
  project-manager,haiku,Never (detection/context loading)
  smart-agent-detector,haiku,Never (routing only)
  architect,sonnet,Schema design / migration planning / system architecture
  ui-expert,sonnet,Design system architecture
  mobile-expert,sonnet,Architecture decisions
  game-developer,sonnet,Game architecture decisions
  security-expert,sonnet,opus for full audits
  qa-automation,sonnet,Never
  devops-cicd,sonnet,Infrastructure architecture

Model Selection Output

Include in detection result:

## Detection Result
- **Agent:** backend-nodejs
- **Model:** sonnet
- **Complexity:** Standard
- **Reason:** API endpoint implementation

When spawning Task tool, use the detected model:

Task(subagent_type="backend-nodejs", model="sonnet", ...)

---

Multi-Layer Detection System

Layer 0: Task Content Analysis (NEW - Highest Priority)

Analyze the actual task, not just the repo. A backend repo may have frontend tasks (templates, PDFs, emails).

Full patterns: task-based-agent-selection.md

task_content_triggers[7]{category,example_patterns,activates,score_boost}:
  Frontend,html template/blade/twig/email template/pdf styling/css,ui-expert,+50 to +60
  Backend,api endpoint/controller/middleware/queue job/webhook,architect (+ framework skill),+50 to +55
  Database,migration/schema/query optimization/slow query/n+1,architect,+55 to +60
  Security,xss/sql injection/csrf/vulnerability/auth bypass,security-expert,+55 to +60
  DevOps,docker/kubernetes/ci-cd/terraform/deployment,devops-cicd,+50 to +55
  Testing,unit test/e2e test/coverage/mock/fixture,qa-automation,+45 to +55
  Design,figma/wireframe/design system/accessibility,ui-expert,+50 to +60

Key insight: Task content score ≥50 → Override or co-lead with repo-based agent.

Examples:

# Backend repo, but frontend task
Repo: Laravel API
Task: "Fix email template styling"
→ ui-expert (PRIMARY) + architect (SECONDARY)

# Frontend repo, but backend task
Repo: Next.js
Task: "Add rate limiting to API route"
→ architect (PRIMARY) + ui-expert (SECONDARY)

---

Layer 1: Explicit Technology Detection

Check if user directly mentions a technology:

tech_detection[10]{technology,keywords,agent,score}:
  React Native,react-native/expo/RN,mobile-react-native,+60
  Flutter,flutter/dart/bloc,mobile-flutter,+60
  Angular,angular/ngrx/rxjs,web-angular,+60
  Vue.js,vue/vuejs/pinia/nuxt,web-vuejs,+60
  React,react/reactjs/jsx,web-reactjs,+60
  Next.js,next/nextjs/ssr/ssg,web-nextjs,+60
  Node.js,nodejs/express/nestjs/fastify,backend-nodejs,+60
  Python,python/django/fastapi/flask,backend-python,+60
  Go,go/golang/gin/fiber,backend-go,+60
  Laravel,laravel/php/eloquent/artisan,backend-laravel,+60

Layer 2: Intent Detection Patterns

Detect user intent from action keywords:

intent_detection[8]{intent,keywords,primary,secondary}:
  Implementation,implement/create/add/build/develop,Dev agent,ui-expert/qa-automation
  Bug Fix,fix/bug/error/issue/broken/crash,Dev agent,qa-automation
  Testing,test/testing/coverage/QA/spec,qa-automation,Dev agent
  Design/UI,design/UI/UX/layout/figma/style,ui-expert,Dev agent
  Database,database/schema/query/migration/SQL,architect,Backend agent
  Security,security/vulnerability/audit/owasp/secure,security-expert,Dev agent
  Performance,performance/slow/optimize/speed/memory,devops-cicd,Dev agent
  Deployment,deploy/docker/kubernetes/CI-CD/pipeline,devops-cicd,-

Layer 3: Project Context Detection

Read project files to infer tech stack:

project_detection[10]{file,indicates,agent,score}:
  app.json (with expo),React Native,mobile-react-native,+40
  pubspec.yaml,Flutter,mobile-flutter,+40
  angular.json,Angular,web-angular,+40
  *.vue files,Vue.js,web-vuejs,+40
  next.config.js,Next.js,web-nextjs,+40
  package.json + react (no next),React,web-reactjs,+40
  package.json + express/nestjs,Node.js,backend-nodejs,+40
  requirements.txt/pyproject.toml,Python,backend-python,+40
  go.mod/go.sum,Go,backend-go,+40
  artisan/composer.json + laravel,Laravel,backend-laravel,+40

Layer 4: File Pattern Detection

Check recent files and naming conventions:

file_patterns[9]{pattern,agent,score}:
  *.phone.tsx/*.tablet.tsx,mobile-react-native,+20
  *.dart/lib/ folder,mobile-flutter,+20
  *.component.ts/*.service.ts,web-angular,+20
  *.vue,web-vuejs,+20
  app/route.ts (Next.js),web-nextjs,+20
  *.controller.ts/*.module.ts,backend-nodejs,+20
  views.py/models.py,backend-python,+20
  *.go,backend-go,+20
  *Controller.php/*Model.php,backend-laravel,+20

---

Scoring Weights

weights[9]{criterion,weight,description}:
  Task Content Match,+50-60,Task-based patterns override repo (Layer 0) - HIGHEST PRIORITY
  Explicit Mention,+60,User directly mentions technology
  Keyword Exact Match,+50,Direct keyword match to intent
  Project Context,+40,CWD/file structure/package files
  Semantic Match,+35,Contextual/implied match
  Task Complexity,+30,Inferred complexity level
  Conversation History,+25,Previous context/active agents
  File Patterns,+20,Recent files/naming conventions
  Project Priority Bonus,+25,Agent in project-config.yaml priority list

Task Content Override Rule: When task content score ≥50 for a different domain than the repo, that domain's agent becomes PRIMARY or co-PRIMARY.

---

Agent Thresholds

thresholds[4]{level,score,role}:
  Primary Agent,≥80,Leads the task
  Secondary Agent,50-79,Supporting role
  Optional Agent,30-49,May assist
  Not Activated,<30,Not selected

---

QA Agent Conditional Activation

qa-automation is ALWAYS Secondary when:

• Intent = Implementation (+30 pts as secondary)
• Intent = Bug Fix (+35 pts as secondary)
• New feature being created
• Code modification requested

qa-automation is Primary when:

• Intent = Testing (keywords: test, coverage, QA)
• User explicitly asks for tests
• Coverage report requested

qa-automation is SKIPPED when:

• Pure documentation task
• Pure design discussion (no code)
• Research/exploration only

---

Detection Process

Step 0: Task Content Analysis (NEW - Do This First!)

Analyze the task itself before checking the repo.

User: "Update the invoice PDF layout - table breaks across pages"

Task Analysis:
- "PDF" → Frontend task pattern (+50)
- "layout" → Frontend keyword (+40)
- "table" → Frontend keyword (+30)
→ Total frontend score: 120 pts → ui-expert is PRIMARY

Even if repo is pure backend, ui-expert leads this task!

Apply patterns from: task-based-agent-selection.md

Step 1: Extract Keywords

User: "Fix the login button not working on iOS"

Extracted:
- Action: "fix" → Bug Fix intent
- Component: "login button" → UI element
- Platform: "iOS" → Mobile
- Issue: "not working" → Bug context

Step 2: Check Project Context (Use Cached Detection!)

IMPORTANT: Use cached project detection to avoid re-scanning every task.

# 1. Check detection first (fast path):
.claude/project-contexts/[project-name]/project-detection.json

# 2. If detection valid (< 24h, key files unchanged):
   → Use cached: framework, agents, testInfra, filePatterns

# 3. If detection invalid or missing:
   → Run full detection (reads package.json, etc.)
   → Save to project-contexts for next task

# 4. Load project-specific overrides:
.claude/project-contexts/[project]/project-config.yaml
.claude/project-contexts/[project]/conventions.md

Detection invalidation triggers:

• Key config files changed (package.json mtime/size)
• Detection older than 24 hours
• User runs /project:refresh

Commands:

• /project:status - Show project detection
• /project:refresh - Force fresh scan

Step 3: Score All Agents (Combine Task + Repo)

mobile-react-native:
  - "iOS" keyword: +35 (semantic)
  - CWD = /mobile-app: +40 (context)
  - Recent *.phone.tsx: +20 (file pattern)
  → Total: 95 pts ✅ PRIMARY

qa-automation:
  - Bug fix intent: +35 (secondary for bugs)
  → Total: 35 pts ✅ OPTIONAL

ui-expert:
  - "button" keyword: +20 (UI element)
  → Total: 20 pts ❌ NOT SELECTED

Step 4: Select Agents

• Primary: Highest score ≥80
• Secondary: Score 50-79
• Optional: Score 30-49

Step 5: Show Banner

See: rules/agent-identification-banner.md for official format.

Single Agent Banner:

⚡ 🐸 AURA FROG v1.2.0 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
┃ Agent: [agent-name] │ Phase: [phase] - [name]          ┃
┃ Model: [model] │ 🔥 [aura-message]                      ┃
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Multi-Agent Banner (when collaboration needed):

⚡ 🐸 AURA FROG v1.2.0 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
┃ Agents: [primary] + [secondary], [tertiary]            ┃
┃ Phase: [phase] - [name] │ 🔥 [aura-message]            ┃
┃ Model: [model]                                         ┃
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---

Available Agents

agents[4]{category,count,list}:
  Development,4,architect/ui-expert/mobile-expert/game-developer
  Quality & Security,2,security-expert/qa-automation
  DevOps & Operations,1,devops-cicd
  Infrastructure,3,smart-agent-detector/pm-operations-orchestrator/project-manager

---

Examples

Example 1: Explicit Technology Mention

User: "Create a React Native screen for user profile"

Layer 1 (Explicit): "React Native" → +60
Layer 2 (Intent): "create" → Implementation
Layer 4 (Files): *.phone.tsx present → +20

Detection Result:
  ✅ Agent: mobile-expert (PRIMARY, 80 pts)
  ✅ Model: sonnet
  ✅ Complexity: Standard
  ✅ Secondary: ui-expert (35), qa-automation (30)

Example 2: Context-Based Detection (No Tech Mention)

User: "Fix the login bug"

Layer 2 (Intent): "fix", "bug" → Bug Fix intent
Layer 3 (Context): CWD=/backend-api, composer.json has laravel → +40
Layer 4 (Files): AuthController.php recent → +20

Detection Result:
  ✅ Agent: architect (PRIMARY, 95 pts) + laravel-expert skill
  ✅ Model: sonnet
  ✅ Complexity: Standard
  ✅ Secondary: qa-automation (35)

Example 3: Architecture Task (Uses Opus)

User: "Design the authentication system architecture"

Layer 2 (Intent): "design", "architecture" → Architecture intent
Complexity: Deep (architecture keyword)

Detection Result:
  ✅ Agent: architect (PRIMARY)
  ✅ Model: opus (architecture task)
  ✅ Complexity: Deep
  ✅ Secondary: security-expert (55)

Example 4: Quick Fix (Uses Haiku)

User: "Fix typo in README.md line 42"

Complexity: Quick (single file, explicit location)

Detection Result:
  ✅ Agent: pm-operations-orchestrator
  ✅ Model: haiku
  ✅ Complexity: Quick

Example 5: Backend Repo, Frontend Task (Task-Based Override)

User: "Fix the password reset email template - the button styling is broken"

Repo Context: Laravel API (backend)
Task Content Analysis:
- "email template" → frontend_task_patterns (+55)
- "styling" → frontend_keywords (+40)
- "button" → frontend_keywords (+30)
→ Frontend score: 125 pts (OVERRIDE)

Detection Result:
  ✅ Agent: ui-expert (PRIMARY, 125 pts) - leads template fix
  ✅ Agent: architect (SECONDARY, 40 pts) - Blade context + laravel-expert skill
  ✅ Model: sonnet
  ✅ Complexity: Standard

Example 6: Frontend Repo, Database Task (Task-Based Override)

User: "The user list page is slow - optimize the query"

Repo Context: Next.js frontend
Task Content Analysis:
- "slow" → database_task_patterns (+50)
- "optimize" → database context
- "query" → database_task_patterns (+40)
→ Database score: 90 pts (OVERRIDE)

Detection Result:
  ✅ Agent: architect (PRIMARY, 90 pts) - database optimization
  ✅ Agent: ui-expert (SECONDARY, 40 pts) - API route context + nextjs-expert skill
  ✅ Model: sonnet
  ✅ Complexity: Standard

Example 7: Backend Repo, PDF Generation (Task-Based Override)

User: "Invoice PDF has layout issues - table breaks across pages incorrectly"

Repo Context: Node.js API
Task Content Analysis:
- "PDF" → frontend_task_patterns (+50)
- "layout" → frontend_keywords (+40)
- "table" → frontend_keywords (+30)
→ Frontend score: 120 pts (OVERRIDE)

Detection Result:
  ✅ Agent: ui-expert (PRIMARY, 120 pts) - HTML/CSS for PDF
  ✅ Agent: architect (SECONDARY, 40 pts) - PDF library integration + nodejs-expert skill
  ✅ Model: sonnet
  ✅ Complexity: Standard

---

After Detection

1. Output detection result with agent, model, and complexity
2. Load agent instructions from agents/[agent-name].md
3. Use detected model when spawning Task tool:

   Task(subagent_type="[agent]", model="[detected-model]", ...)
   

4. Invoke appropriate skill:
   • Complex feature → workflow-orchestrator
   • Bug fix → bugfix-quick
   • Test request → test-writer
   • Code review → code-reviewer
5. Always load project context via project-context-loader before major actions

---

Team Mode Detection

When: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is enabled.

Team mode spawns multiple Claude Code instances as teammates (persistent, peer-to-peer messaging, shared task list) instead of subagents (fire-and-forget, hub-spoke).

Complexity Gate (CRITICAL — Token Savings)

Team mode is ONLY for Deep complexity + multi-domain tasks. All other tasks use single-agent or subagent mode to save tokens.

team_decision[5]{condition,mode,reason}:
  Complexity=Quick,single agent,Trivial task - no team overhead
  Complexity=Standard,subagent,Standard tasks never need teams - save tokens
  Complexity=Deep + 1 domain,subagent,Deep but single-focus - one agent sufficient
  Complexity=Deep + 2+ domains (≥50 each),team (if enabled),Only case for parallel teammates
  Agent Teams disabled,subagent,Feature not enabled - always subagent

Token impact: Team mode costs ~3x tokens (3 parallel context windows). Only justified when task requires parallel cross-domain work that would take 3x longer sequentially.

Gate checks (ALL must pass):

1. isAgentTeamsEnabled() returns true
2. Complexity = Deep
3. 2+ domains score ≥50 each
4. Task requires cross-domain collaboration (not just multiple files)

Team Mode Output Format

When team mode is selected, output:

## Detection Result
- **Agent:** architect (LEAD)
- **Mode:** team
- **Model:** opus
- **Complexity:** Deep
- **Team Composition:**
  - architect (lead) - system design, API endpoints
  - ui-expert (primary) - frontend components
  - qa-automation (primary) - test strategy + TDD
- **Reason:** Multi-domain feature requiring parallel work

When team mode is NOT selected (most tasks), output:

## Detection Result
- **Agent:** architect
- **Mode:** subagent
- **Model:** sonnet
- **Complexity:** Standard
- **Reason:** Single-domain task, team not needed

After Detection — Handoff

handoff[3]{mode,action,target}:
  single agent,Execute directly in current session,N/A
  subagent,Use Task tool with subagent_type,Task(subagent_type="aura-frog:architect")
  team,Hand off to workflow-orchestrator for parallel startup,workflow-orchestrator → TeamCreate → parallel Task calls

Team handoff: Agent detector does NOT create the team. It returns the detection result with Mode: team and Team Composition. The workflow-orchestrator handles the actual parallel startup sequence (TeamCreate → TaskCreate → parallel Task spawns).

Team Composition Rules

team_rules[4]{rule,detail}:
  Max teammates per phase,3 (lead + 2 primary)
  Lead selection,Highest scoring agent from detection
  Primary selection,Score 50-79 agents become teammates
  Minimum for team mode,2+ domains with score ≥50 each

---

Manual Override

User can force specific agent:

User: "Use only qa-automation for this task"
→ Override automatic selection
→ qa-automation becomes PRIMARY regardless of scoring

---

Full detection algorithm: agents/smart-agent-detector.md Selection guide: docs/AGENT_SELECTION_GUIDE.md

MANDATORY: Always show agent banner at start of EVERY response.