Specialist General Purpose

The default general-purpose agent for handling complex, multi-step tasks with automatic delegation capabilities, adapting its approach based on task complexity and identifying when to delegate to specialized agents.

When to Use This Agent

Choose Specialist General Purpose when:

• Tasks span multiple domains and no single specialist agent fits perfectly
• Starting exploratory work before knowing which specialist to engage
• Handling one-off tasks that do not justify configuring a specialized agent
• Coordinating work across multiple specialist agents
• Prototyping solutions that may later be refined by domain experts

Consider alternatives when:

• The task clearly falls within one domain (use the relevant specialist agent)
• Performance-critical work requiring deep domain expertise (use a specialist)
• Repetitive tasks that would benefit from a customized agent workflow

Quick Start

Copy
# .claude/agents/specialist-general-purpose.yml
name: Specialist General Purpose
description: Versatile agent for complex multi-step tasks
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - WebSearch
  - Task

Example invocation:

claude "Investigate why our app's Lighthouse score dropped from 95 to 72 after last week's deployment, identify the causes, and implement fixes"

Core Concepts

Task Decomposition Strategy

Complexity	Approach	Example
Simple	Direct execution	"Fix the typo in Header.tsx"
Moderate	Sequential steps	"Add form validation to the signup page"
Complex	Parallel subtasks	"Optimize all API endpoints for performance"
Exploratory	Research then plan	"Why is the app slow on mobile?"

Delegation Decision Framework

Copy
## When to Handle Directly
- Task is straightforward (< 3 steps)
- Requires reading/modifying < 5 files
- No specialized domain knowledge needed
- Quick research + implementation

## When to Delegate to Specialist
- Task requires deep domain expertise (security audit → security agent)
- Task involves specialized tooling (database migration → DBA agent)
- Task quality benefits from focused context (code review → reviewer agent)
- Parallel subtasks that can run independently

## Delegation Example
Task: "Make the app production-ready"
1. Self: Audit current state, create checklist
2. Delegate: Security agent → vulnerability scan
3. Delegate: Performance agent → optimization audit
4. Delegate: Test agent → coverage analysis
5. Self: Coordinate results, prioritize fixes
6. Delegate: DevOps agent → deployment pipeline

Multi-Step Execution Pattern

Copy
// General-purpose task execution approach
interface TaskPlan {
  goal: string;
  steps: Step[];
  currentStep: number;
  context: Record<string, unknown>;
}

// Example: Investigating a performance regression
const plan: TaskPlan = {
  goal: 'Fix Lighthouse score regression from 95 to 72',
  steps: [
    { action: 'Run Lighthouse audit', status: 'done', finding: 'LCP 4.2s, CLS 0.25' },
    { action: 'Compare bundle sizes', status: 'done', finding: '+180KB in main bundle' },
    { action: 'Identify new large imports', status: 'done', finding: 'moment.js added in DatePicker' },
    { action: 'Replace moment with date-fns', status: 'in-progress' },
    { action: 'Fix CLS: add dimensions to images', status: 'pending' },
    { action: 'Re-run Lighthouse to verify', status: 'pending' },
  ],
  currentStep: 3,
  context: { baselineScore: 95, currentScore: 72 },
};

Configuration

Parameter	Description	Default
delegation_enabled	Allow delegation to specialist agents	true
max_steps	Maximum steps before requesting user input	20
parallel_tasks	Maximum concurrent delegated subtasks	3
research_depth	Research thoroughness (quick, standard, deep)	standard
auto_verify	Automatically verify changes after implementation	true
progress_updates	How often to update the user on progress	per-step

Best Practices

1. Decompose complex tasks into independent steps before starting work. Write out the full plan before executing the first step. Each step should be independently verifiable: "Add Zod validation to /api/users endpoint" can be checked by running that endpoint's tests. A plan with clear steps lets you parallelize independent work, recover from failures at specific points, and communicate progress accurately.

2. Research before implementing when the problem space is unclear. For tasks like "why is the app slow," spend the first phase gathering data (profiling, auditing, measuring) rather than jumping to solutions. The investigation phase often reveals that the assumed problem is not the real problem. A 15-minute investigation can save hours of implementing the wrong fix.

3. Delegate to specialists when domain depth matters more than breadth. A general-purpose approach works for coordination and moderate-depth tasks. But a security audit, database performance tuning, or accessibility compliance check benefits from the focused context and domain expertise of a specialist agent. Use yourself as the coordinator and let specialists go deep.

4. Verify each step before proceeding to the next. After making a change, run the relevant tests, check the build, or validate the output before moving on. Compounding unverified changes makes it impossible to identify which step introduced a regression. The cost of a 30-second verification is far lower than the cost of debugging a multi-step cascade failure.

5. Document decisions and context for future reference. When you make choices during execution (chose library A over B, fixed the bug this way instead of that way), record the reasoning briefly. This context is valuable when revisiting the work, debugging regressions, or when another developer needs to understand why things are done a certain way.

Common Issues

Task scope expands beyond the original request. While investigating a performance issue, you discover a security vulnerability, stale dependencies, and poor test coverage. Each is worth fixing, but scope creep delays the original task. Note secondary findings for follow-up without acting on them immediately. Complete the original task first, then present the secondary findings as a prioritized list for the user to decide on.

Delegation overhead exceeds the benefit for small tasks. Setting up and coordinating a specialist agent for a task that takes 5 minutes to do directly wastes time. Use delegation only when the specialist's domain expertise genuinely improves the outcome or when the subtask is large enough to justify the coordination cost. For small tasks, doing them directly is faster and simpler.

Context is lost between steps in long multi-step workflows. After 15+ steps of investigation and implementation, earlier findings, decisions, and context may be forgotten. Maintain a running summary document that captures key findings, decisions made, and current state at each major milestone. This summary serves as a recovery point if the conversation context is compacted and as a final report for the user.