Agents Configuration

Overview

Agents define specialized AI proxy roles for executing specific types of tasks. Superpowers uses the agent system to implement specialized capabilities like code review and implementation.

Built-in Agents

code-reviewer

A code review agent that reviews completed project steps against original plans and coding standards.

Trigger scenarios:

• After completing a major project step
• After completing a significant feature implementation
• When validating code alignment with plans

Responsibilities:

1. Plan Alignment Analysis

   • Compare implementation against original planning document
   • Identify deviations and assess if they're justified
   • Verify all planned functionality is implemented

2. Code Quality Assessment

   • Check adherence to patterns and conventions
   • Evaluate error handling and type safety
   • Check test coverage and quality

3. Architecture and Design Review

   • Ensure SOLID principles are followed
   • Check separation of concerns and loose coupling
   • Assess scalability

4. Documentation and Standards

   • Verify comment and documentation completeness
   • Check coding standard compliance

5. Issue Classification

   • Critical: Must fix
   • Important: Should fix
   • Suggestions: Nice to have

Agent File Format

Agents are defined using Markdown files with YAML frontmatter:

---
name: agent-name
description: |
  Use this agent when [trigger condition]. Examples:
  <example>Context: ... user: "..." assistant: "..."</example>
model: inherit
---

You are a [role description].

When [performing task], you will:

1. **[Task Category 1]**:
   - [Specific action]
   - [Specific action]

2. **[Task Category 2]**:
   - [Specific action]
...

Frontmatter Fields

Field	Required	Description
name	Yes	Agent name, used for reference
description	Yes	Trigger conditions and examples to help AI decide when to use
model	No	Model to use, defaults to inherit from parent session

Creating Custom Agents

Step 1: Create the Agent File

Create my-agent.md in the agents/ directory:

---
name: security-auditor
description: |
  Use this agent when reviewing code for security vulnerabilities. Examples:
  <example>Context: User is about to deploy a new API endpoint.
  user: "I've added a new endpoint to handle file uploads"
  assistant: "Let me use the security-auditor agent to review this for potential vulnerabilities before deployment"</example>
model: inherit
---

You are a Security Auditor specializing in identifying vulnerabilities...

When auditing code, you will:

1. **Input Validation Review**:
   - Check for proper sanitization
   - Identify injection vulnerabilities
...

Step 2: Reference the Agent in Skills

Reference the agent in your skill's SKILL.md:

## Process

1. Complete implementation
2. Use `security-auditor` agent for security review
3. Fix discovered issues

Configuration File Locations

Platform	Built-in Agents	Custom Agents
Claude Code	~/.claude/plugins/superpowers/agents/	~/.claude/agents/
Cursor	~/.cursor/plugins/superpowers/agents/	~/.cursor/agents/
Codex	~/.codex/superpowers/agents/	~/.agents/agents/
OpenCode	~/.config/opencode/superpowers/agents/	~/.config/opencode/agents/

Using Agents

Agents are typically invoked automatically by skills, no manual triggering needed. For example:

• requesting-code-review skill invokes the code-reviewer agent
• subagent-driven-development uses agents for code review

Best Practices

Define Roles Specifically

Agent role descriptions should be clear and specific:

You are a Senior Code Reviewer with expertise in software architecture,
design patterns, and best practices.

Provide Trigger Examples

Include specific usage examples in the description to help AI correctly judge when to use the agent:

description: |
  Use this agent when a major project step has been completed.
  Examples:
  <example>Context: ... user: "I've finished implementing..." assistant: "..."</example>

Avoid Overlapping Responsibilities

Each agent should have a unique scope of responsibility. Avoid multiple agents doing the same thing.

Structure Output

Agent output should be structured for easy downstream processing:

Your output should be structured:
- **Critical Issues**: ...
- **Important Issues**: ...
- **Suggestions**: ...