claudetools/.claude/agents/AGENT_QUICK_REFERENCE.md

name, description

name	description
Agent Quick Reference	Quick reference guide for all available specialized agents

Agent Quick Reference

Last Updated: 2026-01-18

---

Available Specialized Agents

Documentation Squire (documentation-squire)

Purpose: Handle all documentation and keep Main Claude organized When to Use:

• Creating/updating .md files (guides, summaries, trackers)
• Need task checklist for complex work
• Main Claude forgetting TodoWrite
• Documentation getting out of sync
• Need completion summaries

Invocation:

Task tool:
  subagent_type: "documentation-squire"
  model: "haiku"  (cost-efficient)
  prompt: "Create [type] documentation for [work]"

Example:

User: "Create a technical debt tracker"

Main Claude invokes:
  subagent_type: "documentation-squire"
  prompt: "Create comprehensive technical debt tracker for GuruConnect, including all pending items from Phase 1"

---

Agent Delegation Rules

Main Claude Should Delegate When:

Documentation Work:

• ✓ Creating README, guides, summaries
• ✓ Updating technical debt trackers
• ✓ Writing installation instructions
• ✓ Creating troubleshooting guides
• ✗ Inline code comments (Main Claude handles)
• ✗ Quick status messages to user (Main Claude handles)

Task Organization:

• ✓ Complex tasks (>3 steps) - Let Doc Squire create checklist
• ✓ Multiple parallel tasks - Doc Squire manages
• ✗ Simple single-step tasks (Main Claude uses TodoWrite directly)

Specialized Work:

• ✓ Code review - Invoke code review agent
• ✓ Testing - Invoke testing agent
• ✓ Frontend - Invoke frontend design skill
• ✓ Infrastructure setup - Invoke infrastructure agent
• ✗ Simple edits (Main Claude handles directly)

---

Invocation Patterns

Pattern 1: Documentation Creation (Most Common)

User: "Document the CI/CD setup"

Main Claude:
1. Invokes Documentation Squire
2. Provides context (what was built, key details)
3. Receives completed documentation
4. Shows user summary and file location

Pattern 2: Task Management Reminder

Main Claude: [Starting complex work without TodoWrite]

Documentation Squire: [Auto-reminder]
"You're starting complex CI/CD work without a task list.
Consider using TodoWrite to track progress."

Main Claude: [Uses TodoWrite or delegates to Doc Squire for checklist]

Pattern 3: Agent Coordination

Code Review Agent: [Completes review]
"Documentation needed: Update technical debt tracker"

Main Claude: [Invokes Documentation Squire]
"Update TECHNICAL_DEBT.md with code review findings"

Documentation Squire: [Updates tracker]
Main Claude: "Tracker updated. Proceeding with fixes..."

Pattern 4: Status Check

User: "What's the current status?"

Main Claude: [Invokes Documentation Squire]
"Generate current project status summary"

Documentation Squire:
- Reads PHASE1_COMPLETE.md, TECHNICAL_DEBT.md, etc.
- Creates unified status report
- Returns summary

Main Claude: [Shows user the summary]

---

When NOT to Use Agents

Main Claude Should Handle Directly:

Simple Tasks:

• Single file edits
• Quick code changes
• Simple questions
• User responses
• Status updates

Interactive Work:

• Debugging with user
• Asking clarifying questions
• Real-time troubleshooting
• Immediate user requests

Code Work:

• Writing code (unless specialized like frontend)
• Code comments
• Simple refactoring
• Bug fixes

---

Agent Communication Protocol

Requesting Documentation from Agent

Template:

Task tool:
  subagent_type: "documentation-squire"
  model: "haiku"
  prompt: "[Action] [Type] for [Context]

  Details:
  - [Key detail 1]
  - [Key detail 2]
  - [Key detail 3]

  Output format: [What you want]"

Example:

Task tool:
  subagent_type: "documentation-squire"
  model: "haiku"
  prompt: "Create CI/CD activation guide for GuruConnect

  Details:
  - 3 workflows created (build, test, deploy)
  - Runner installed but not registered
  - Need step-by-step activation instructions

  Output format: Comprehensive guide with troubleshooting section"

Agent Signaling Documentation Needed

Template:

[DOCUMENTATION NEEDED]

Work completed: [description]
Documentation type: [guide/summary/tracker update]
Key information:
- [point 1]
- [point 2]
- [point 3]

Files to update: [file list]
Suggested filename: [name]

Passing to Documentation Squire agent...

---

TodoWrite Best Practices

When to Use TodoWrite

YES - Use TodoWrite:

• Complex tasks with 3+ steps
• Multi-file changes
• Long-running work (>10 minutes)
• Tasks with dependencies
• Work that might span messages

NO - Don't Use TodoWrite:

• Single-step tasks
• Quick responses
• Simple questions
• Already delegated to agent

TodoWrite Format

TodoWrite:
  todos:
    - content: "Action in imperative form"
      activeForm: "Action in present continuous"
      status: "pending" | "in_progress" | "completed"

Example:

todos:
  - content: "Create build workflow"
    activeForm: "Creating build workflow"
    status: "in_progress"

  - content: "Test workflow triggers"
    activeForm: "Testing workflow triggers"
    status: "pending"

TodoWrite Rules

1. Exactly ONE task in_progress at a time
2. Mark complete immediately after finishing
3. Update before switching tasks
4. Remove irrelevant tasks
5. Break down complex tasks

---

Documentation Standards

File Naming

• ALL_CAPS.md - Major documents (TECHNICAL_DEBT.md)
• lowercase-dashed.md - Specific guides (activation-guide.md)
• PascalCase.md - Code-related docs (APIReference.md)
• PHASE#_WEEKN_STATUS.md - Phase tracking

Document Headers

# Title

**Status:** [Active/Complete/Deprecated]
**Last Updated:** YYYY-MM-DD
**Related Docs:** [Links]

---

## Overview
...

Formatting Rules

• ✓ Headers for hierarchy (##, ###)
• ✓ Code blocks with language tags
• ✓ Tables for structured data
• ✓ Lists for sequences
• ✓ Bold for emphasis
• ✗ NO EMOJIS (project guideline)
• ✗ No ALL CAPS in prose
• ✓ Clear section breaks (---)

---

Decision Matrix: Should I Delegate?

Task Type	Delegate To	Direct Handle
Create README	Documentation Squire	-
Update tech debt	Documentation Squire	-
Write guide	Documentation Squire	-
Code review	Code Review Agent	-
Run tests	Testing Agent	-
Frontend design	Frontend Skill	-
Simple code edit	-	Main Claude
Answer question	-	Main Claude
Debug with user	-	Main Claude
Quick status	-	Main Claude

Rule of Thumb:

• Specialized work → Delegate to specialist
• Documentation → Documentation Squire
• Simple/interactive → Main Claude
• When unsure → Ask Documentation Squire for advice

---

Common Scenarios

Scenario 1: User Asks for Status

User: "What's the current status?"

Main Claude options:
A) Quick status → Answer directly from memory
B) Comprehensive status → Invoke Documentation Squire to generate report
C) Unknown status → Invoke Doc Squire to research and report

Choose: Based on complexity and detail needed

Scenario 2: Completed Major Work

Main Claude: [Just completed CI/CD setup]

Next steps:
1. Mark todos complete
2. Invoke Documentation Squire to create completion summary
3. Update TECHNICAL_DEBT.md (via Doc Squire)
4. Tell user what was accomplished

DON'T: Write completion summary inline (delegate to Doc Squire)

Scenario 3: Starting Complex Task

User: "Implement CI/CD pipeline"

Main Claude:
1. Invoke Documentation Squire: "Create task checklist for CI/CD implementation"
2. Doc Squire returns checklist
3. Use TodoWrite with checklist items
4. Begin implementation

DON'T: Skip straight to implementation without task list

Scenario 4: Found Technical Debt

Main Claude: [Discovers systemd watchdog issue]

Next steps:
1. Fix immediate problem
2. Note need for proper implementation
3. Invoke Documentation Squire: "Add systemd watchdog implementation to TECHNICAL_DEBT.md"
4. Continue with main work

DON'T: Manually edit TECHNICAL_DEBT.md (let Doc Squire maintain it)

---

Troubleshooting

"When should I invoke vs handle directly?"

Invoke agent when:

• Specialized knowledge needed
• Large documentation work
• Want to save context
• Task will take multiple steps
• Need consistency across files

Handle directly when:

• Simple one-off task
• Need immediate response
• Interactive with user
• Already know exactly what to do

"Agent not available?"

If agent doesn't exist, Main Claude should handle directly but note:

[FUTURE AGENT OPPORTUNITY]

Task: [description]
Would benefit from: [agent type]
Reason: [why specialized agent would help]

Add to future agent development list.

"Multiple agents needed?"

Coordination approach:

1. Break down work by specialty
2. Invoke agents sequentially
3. Use Documentation Squire to coordinate outputs
4. Main Claude integrates results

---

Quick Commands

Invoke Documentation Squire

Task with subagent_type="documentation-squire", prompt="[task]"

Create Task Checklist

Invoke Doc Squire: "Create task checklist for [work]"
Then use TodoWrite with checklist

Update Technical Debt

Invoke Doc Squire: "Add [item] to TECHNICAL_DEBT.md under [priority] priority"

Generate Status Report

Invoke Doc Squire: "Generate current project status summary"

Create Completion Summary

Invoke Doc Squire: "Create completion summary for [work done]"

---

Document Version: 1.0 Purpose: Quick reference for agent delegation Audience: Main Claude, future agent developers