docs

Imported from i-denipermana/prpal (docs/AGENTS.md). Install upstream with npx skills add i-denipermana/prpal --skill docs. Copyright stays with the author.

Review Agents Guide

Review agents are configurable AI profiles that determine how code reviews are conducted. This guide explains how to use built-in agents, create custom agents, and leverage the skills system.

Table of Contents

• Overview
• Built-in Agent
• Creating Custom Agents
• Skills System
• Custom Skills
• Memories
• Advanced Configuration
• Best Practices

Overview

An agent defines:

How Agents Work

User selects agent
        │
        ▼
Agent's prompt + selected skills
        │
        ▼
Combined with PR data (diff, description)
        │
        ▼
Sent to AI model via OpenCode
        │
        ▼
Structured review output

Built-in Agent

The app includes a default "PR Reviewer" agent:

{
  "id": "pr-reviewer",
  "name": "PR Reviewer",
  "description": "General-purpose code reviewer",
  "model": "anthropic/claude-sonnet-4-20250514",
  "temperature": 0.3,
  "isBuiltIn": true,
  "isDefault": true
}

The default agent analyzes:

• Code Quality - Clean code, naming, DRY violations
• Potential Bugs - Edge cases, null checks, async issues
• Security - Input validation, injection risks, auth issues
• Performance - N+1 queries, memory leaks, inefficiencies
• Best Practices - Framework conventions, testing, documentation

Creating Custom Agents

Via Settings UI

1. Click the tray icon and select Settings
2. Navigate to Agents tab
3. Click Create Agent
4. Fill in the form:
   • Name
   • Description
   • Model
   • Temperature
   • Prompt
   • Skills
5. Click Save

Via API

curl -X POST http://localhost:3847/api/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Security Reviewer",
    "description": "Focuses on security vulnerabilities",
    "model": "anthropic/claude-sonnet-4-20250514",
    "temperature": 0.1,
    "prompt": "You are a security-focused code reviewer...",
    "skills": ["security", "error-handling"]
  }'

Agent Properties

Skills System

Skills are specialized knowledge modules that enhance agent reviews. They inject focused instructions into the review prompt.

Built-in Skills

Skill Details

Security Skill

## Security Focus

Pay special attention to:

- SQL injection, XSS, CSRF vulnerabilities
- Authentication and authorization issues
- Sensitive data exposure (API keys, passwords, tokens)
- Input validation and sanitization
- Secure communication (HTTPS, encryption)
- Dependency vulnerabilities
- Rate limiting and DoS protection
- Secure session management

Performance Skill

## Performance Focus

Pay special attention to:

- N+1 query problems
- Unnecessary re-renders in React
- Memory leaks and resource cleanup
- Inefficient algorithms (O(n^2) when O(n) is possible)
- Missing caching opportunities
- Large bundle sizes and code splitting
- Lazy loading opportunities
- Database index usage
- Unnecessary computations in loops

TypeScript Skill

## TypeScript Focus

Pay special attention to:

- Proper type definitions (avoid 'any')
- Type inference vs explicit types
- Union types and discriminated unions
- Proper use of generics
- Type guards and narrowing
- Interface vs type usage
- Strict null checks
- Readonly and immutability
- Utility types usage

Combining Skills

Agents can use multiple skills:

{
  "name": "Full Stack Reviewer",
  "skills": ["security", "typescript", "react", "nodejs", "database"]
}

The skills are combined in the prompt, giving the AI reviewer comprehensive knowledge.

Custom Skills

You can create custom skills by adding markdown files to a skills folder.

Setup

1. Create a skills directory:

mkdir -p ~/.config/prpal/skills

2. Configure the skills folder in settings:

{
  "opencode": {
    "skillsFolder": "~/.config/prpal/skills"
  }
}

Creating a Custom Skill

Create a markdown file in your skills folder:

cat > ~/.config/prpal/skills/company-standards.md << 'EOF'
---
name: Company Standards
description: Your company coding conventions and standards
icon: building
---

## Company Coding Standards

### Naming Conventions
- Use camelCase for variables and functions
- Use PascalCase for classes and React components
- Use SCREAMING_SNAKE_CASE for constants
- Prefix interfaces with 'I' (e.g., IUser)

### File Structure
- One component per file
- Co-locate tests with source files
- Use barrel exports (index.ts)

### Code Style
- Maximum line length: 100 characters
- Use early returns to reduce nesting
- Prefer const over let
- No magic numbers - use named constants

### Testing Requirements
- Minimum 80% code coverage
- Unit tests for all business logic
- Integration tests for API endpoints
- E2E tests for critical user flows
EOF

Skill File Format

---
name: Display Name
description: Brief description
icon: emoji-or-icon-name
---

# Skill Content

Your custom review instructions here...

Frontmatter Fields:

Using Custom Skills

Custom skills appear with the custom: prefix:

{
  "skills": ["security", "custom:company-standards"]
}

Memories

Memories provide persistent context about your project that applies to all reviews.

Setup

1. Create a memories directory:

mkdir -p ~/.config/prpal/memories

2. Configure the memories folder:

{
  "opencode": {
    "memoriesFolder": "~/.config/prpal/memories"
  }
}

Creating Memories

Create markdown files with project context:

cat > ~/.config/prpal/memories/project-context.md << 'EOF'
---
name: Project Context
---

# Project Overview

This is a fintech SaaS application for small business accounting.

## Technology Stack
- Frontend: React 18 with TypeScript
- Backend: Node.js with Fastify
- Database: PostgreSQL with Prisma ORM
- Queue: Redis with BullMQ
- Infrastructure: AWS ECS, RDS

## Key Architectural Decisions
- Domain-driven design with bounded contexts
- Event sourcing for financial transactions
- CQRS for complex queries
- Multi-tenant with row-level security

## Security Requirements
- SOC 2 Type II compliant
- PCI DSS for payment processing
- GDPR compliance for EU users
- All PII must be encrypted at rest

## Performance SLAs
- API response time < 200ms p95
- Page load time < 3s
- Uptime 99.9%
EOF

How Memories Work

Memories are always included in every review, providing consistent project context:

Agent Prompt
    │
    ├── Skills (selected per agent)
    │
    └── Memories (always included)
            │
            ▼
      Combined Prompt

Advanced Configuration

Temperature Guidelines

Model Selection

Example Agents

Security-Focused Agent

{
  "name": "Security Auditor",
  "description": "Deep security analysis for sensitive code",
  "model": "anthropic/claude-sonnet-4-20250514",
  "temperature": 0.1,
  "skills": ["security", "error-handling"],
  "prompt": "You are a senior security engineer conducting a thorough security audit. Be very strict and flag any potential vulnerabilities, even minor ones. Consider OWASP Top 10, supply chain attacks, and business logic flaws."
}

Performance-Focused Agent

{
  "name": "Performance Optimizer",
  "description": "Identifies performance bottlenecks",
  "model": "anthropic/claude-sonnet-4-20250514",
  "temperature": 0.2,
  "skills": ["performance", "database", "nodejs"],
  "prompt": "You are a performance expert. Focus on identifying bottlenecks, inefficient patterns, and optimization opportunities. Consider both runtime performance and resource utilization."
}

Junior-Friendly Agent

{
  "name": "Mentor",
  "description": "Educational reviews for junior developers",
  "model": "anthropic/claude-sonnet-4-20250514",
  "temperature": 0.4,
  "skills": ["code-quality", "documentation"],
  "prompt": "You are a senior developer mentoring a junior team member. Provide educational feedback that explains the 'why' behind suggestions. Be encouraging while still maintaining code quality standards."
}

Quick Review Agent

{
  "name": "Quick Check",
  "description": "Fast review for small PRs",
  "model": "anthropic/claude-sonnet-4-20250514",
  "temperature": 0.3,
  "skills": [],
  "maxSteps": 20,
  "prompt": "Perform a quick review focusing only on critical issues. Skip minor style suggestions. Only flag problems that could cause bugs or security issues."
}

Best Practices

Agent Design

1. Single Purpose - Each agent should have a clear focus
2. Appropriate Skills - Select skills relevant to the agent's purpose
3. Clear Prompts - Be specific about what the agent should focus on
4. Test Your Agents - Try them on representative PRs before relying on them

Prompt Writing

Good prompt structure:

1. Role definition (who is the reviewer)
2. Focus areas (what to look for)
3. Output expectations (how to format findings)
4. Constraints (what to ignore/emphasize)

Example:

You are a senior backend engineer reviewing API changes.

Focus on:
- RESTful design principles
- Error handling and status codes
- Request/response validation
- Breaking changes

Ignore:
- Minor formatting issues
- Documentation style
- Test implementation details

For each issue, explain the impact and provide a concrete fix.

Skill Selection

Memory Management

• Keep memories focused on stable project context
• Update memories when major architectural decisions change
• Don't include frequently changing information
• Keep memory files reasonably sized (under 2000 words each)