---
name: "Agent Quick Reference"
description: "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
```markdown
# 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