setup-agents

/setup-agents

Configures .claude/agents/ with specialized sub-agents for the project.

Mode Detection

Read .claude/starter-context.json if it exists
  → Exists: use fields agents_selected, project.type, project.team_size, project.tier — skip suggest
  → Does not exist (standalone): load catalog → detect context → suggest → confirm

Argument Handling

If an agent name is passed directly (e.g. /setup-agents pr-review): skip the suggestion step and go straight to that agent's entry in the catalog.

Context Detection

Load agents-catalog.json. For each entry, evaluate suggestWhen:

1. files: check whether any listed glob exists in the project root
2. context: if .claude/starter-context.json exists, evaluate conditions against its fields
   • teamSize > N → read project.team_size
   • tier == N → read project.tier
3. always: if alwaysInclude is true, suggest unconditionally — present first

In standalone mode without starter-context.json: ask the user for context that cannot be inferred from files (e.g. "How many people work on this project?").

For each suggested agent: show preview → confirm before writing.

How Sub-Agent Context Works

Sub-agents receive only two inputs when invoked:

1. Their agent file content (system prompt)
2. The prompt string passed by the main agent at invocation time

They do not inherit the main agent's conversation history or open files.

Two patterns handle this:

Autonomous agents — self-orient by reading project files on startup. No runtime input needed beyond a trigger phrase. Examples: drift-monitor, dependency-scanner, test-coverage.

Task-specific agents — require runtime context passed in the invocation prompt. The caller must include specific parameters (e.g. PR number, branch name). Examples: pr-review.

Use contextType in the catalog to identify which pattern each agent follows.

Agent File Format

Write to .claude/agents/[id].md using this structure: