Subagents

Subagents let the Spectral coding agent delegate work to specialized sub-agents. Each sub-agent runs in an isolated context window with its own system prompt, filtered tool set, and optional model override — keeping the main conversation lean and focused.

How It Works

┌──────────────────────────────────────────┐
│            Main Agent Session             │
│                                          │
│   User: "Review all auth files"          │
│         │                                │
│         ▼                                │
│   subagent({ agent: "reviewer",          │
│              task: "Review src/auth/" }) │
│         │                                │
│         ▼ (isolated context)             │
│   ┌──────────────────────────┐          │
│   │  Sub-agent: reviewer     │          │
│   │  Tools: read, grep, ls   │          │
│   │  Model: claude-haiku-4-5 │          │
│   │  → reads auth files      │          │
│   │  → produces review       │          │
│   └──────────┬───────────────┘          │
│              │                           │
│              ▼                           │
│   Main agent receives review result     │
│   → continues with the output           │
└──────────────────────────────────────────┘

Defining an Agent

Agents are .md files with YAML frontmatter followed by a system prompt body.

Project-level agents

your-project/
└── .spectral/
    └── agents/
        └── reviewer.md

User-level agents (global)

~/.spectral/agent/agents/reviewer.md

Example: Code Reviewer

---
name: reviewer
description: Reviews code changes for bugs, anti-patterns, and style issues
tools: read, grep, find, ls, bash
model: claude-haiku-4-5
---

You are a senior code reviewer. When given a file path or directory:
1. Read all relevant source files
2. Check for: logic errors, missing error handling, type safety issues,
   security concerns, performance problems
3. Produce a concise review with actionable suggestions
4. Use conventional commit style for your findings

Frontmatter Fields

Available Tools

Built-in tools: read, bash, edit, write, grep, find, ls.

Extension-registered tools (like recall, kanban_*, designer_*) are also resolved dynamically.

Execution Modes

The agent invokes subagents through the subagent tool with three modes:

Single Mode

Delegate one task to one agent:

{
  "agent": "reviewer",
  "task": "Review all route handlers in src/routes/ for missing error handling"
}

Parallel Mode

Run up to 8 tasks in parallel (max 4 concurrent):

{
  "tasks": [
    { "agent": "reviewer", "task": "Review src/auth/" },
    { "agent": "reviewer", "task": "Review src/api/" },
    { "agent": "doc-writer", "task": "Generate docs for packages/parser/" }
  ]
}

Chain Mode

Sequential execution where each step sees the previous output via {previous}:

{
  "chain": [
    { "agent": "investigator", "task": "Find all type errors in the project" },
    { "agent": "fixer", "task": "Fix the following errors: {previous}" }
  ]
}

If any step fails, the chain stops and returns the error.

Context Isolation

Each sub-agent invocation gets:

Agent Discovery

Agents are discovered from two locations based on agentScope:

Project-level agents are searched from the current working directory upwards until a .spectral/agents/ directory is found.

Security: Project Agent Confirmation

When agentScope is "project" or "both", the agent prompts for confirmation before running project-local agents (unless in headless/relay mode). This prevents untrusted repositories from silently running arbitrary agent definitions.

Model Resolution

Sub-agents resolve their model in this order:

1. Session model (if available and has configured auth)
2. Agent-configured model (from the model frontmatter field)
3. Error — if neither is available

The model string supports two formats:

• Short: claude-sonnet-4-5 (fuzzy match by model ID)
• Fully qualified: anthropic/claude-sonnet-4-5 (exact provider + model ID)

Example Agents

Documentation Writer

---
name: doc-writer
description: Generates API documentation from source code
tools: read, grep, find, ls
model: claude-sonnet-4-5
---

You are a technical writer. When given a source file or directory:
1. Read the code thoroughly
2. Extract the public API surface (exports, functions, classes, types)
3. Write clear, concise documentation with examples
4. Output valid Markdown suitable for API references

Test Generator

---
name: test-gen
description: Generates unit tests for uncovered code paths
tools: read, grep, find, ls, bash, write
model: claude-sonnet-4-5
---

You are a test engineer. When given a source file:
1. Read the file and its existing tests (if any)
2. Identify uncovered branches and edge cases
3. Generate thorough unit tests following project conventions
4. Write the test file using the `write` tool

Agents vs. Extensions

Next Steps

• Extensions
• Kanban Task Execution
• Observational Memory