Agent Awareness

Agent Awareness Guide

You have access to specialized agents that are MORE EFFICIENT than basic tools. You MUST use these agents instead of grep, glob, or generic Task agents.

Decision Tree

Finding files or components? → Use codebase-locator agent

• Better than: grep, glob, find, ls
• Example: "Find all authentication-related files"

Understanding how code works? → Use codebase-analyzer agent

• Better than: Reading multiple files manually
• Example: "Analyze how the login flow works"

Finding similar implementations or patterns? → Use codebase-pattern-finder agent

• Better than: Searching and reading manually
• Example: "Find examples of API handlers"

Finding documentation in thoughts/? → Use thoughts-locator agent

• Better than: grep in thoughts directory
• Example: "Find research about authentication"

Understanding specific documents? → Use thoughts-analyzer agent

• Better than: Reading docs manually
• Example: "Extract key insights from these research docs"

Researching external information? → Use web-search-researcher agent

• Only when user explicitly asks for web research
• Example: "Research how JWT tokens work"

Analyzing complex errors or stack traces? → Use error-analyzer agent

• Better than: Reading multiple files manually to understand error
• Example: "Analyze this panic: nil pointer dereference at handler.go:42"

Available Agents

Implementation Agents

During implementation, use aggressive agent orchestration:

• See spawn-implementation-agents skill for full pattern
• Keep main agent under 40k tokens per phase
• Use sub-agents for file reading, pattern finding, testing, verification
• 60% token reduction per phase

When to Use Agents

ALWAYS Use Agents For:

• "Find all files that..."
• "Where is the code for..."
• "How does [feature] work?"
• "Find examples of..."
• "Show me similar..."
• "What documentation exists about..."

NEVER Use Basic Tools For:

• ❌ grep/Grep when looking for files or features
• ❌ glob/Glob when finding components
• ❌ Reading multiple files to understand a system
• ❌ Generic Task agents when specialized agents exist

How to Invoke Agents

Use the Task tool with the correct subagent_type:

Task(
  subagent_type="codebase-locator",
  prompt="Find all authentication-related files",
  description="Locate auth files"
)

Remember

Agents have isolated context windows and specialized tools. They are designed for these tasks and will give you better, faster, more comprehensive results than basic tools.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.