​

Specialist Agents

​

Overview

• Persistent - Run continuously in tmux sessions
• Cross-issue - Work on multiple issues, building codebase knowledge
• Specialized - Each has a narrow, focused responsibility
• Coordinated - Managed by Cloister for handoffs

​

Types of Specialists

​

Review Agent

• Logic errors and edge cases
• Security vulnerabilities
• Performance issues
• Code quality and best practices

# Via dashboard - click "Review" button on issue card
# Or via CLI:
pan specialists wake review-agent --issue MIN-123

• PASSED - Code looks good, automatically queues test-agent
• BLOCKED - Issues found, sends feedback to work-agent with required fixes
• SKIPPED - Review not applicable or already completed

​

Test Agent

1. Runs all configured test suites (backend, frontend, integration, e2e)
2. Analyzes test failures to understand root causes
3. Reports results with actionable feedback
4. If tests pass, marks issue ready for merge

• PASSED - All tests pass, ready for human to approve merge
• FAILED - Tests failing, sends detailed feedback to work-agent
• SKIPPED - Tests not applicable or already run

projects:
  myproject:
    name: "My Project"
    path: /home/user/projects/myproject
    tests:
      backend:
        command: "npm test"
        timeout: 300000
      frontend_unit:
        command: "cd frontend && npm run test:unit"
        timeout: 180000
      e2e:
        command: "npm run test:e2e"
        timeout: 600000

​

Merge Agent

• It sees all code changes coming through the pipeline
• It builds context about the codebase over time
• When conflicts DO occur, it has better understanding for intelligent resolution
• Tests are always run before completing the merge

1. Pull latest main - Ensures local main is up-to-date
2. Analyze incoming changes - Reviews what the feature branch contains
3. Perform merge - Merges feature branch into main
4. Resolve conflicts - If conflicts exist, uses AI to resolve them intelligently
5. Run tests - Verifies the merge didn’t break anything
6. Commit merge - Commits the merge with descriptive message
7. Report results - Returns success/failure with details

# Via dashboard - click "Approve & Merge" on an issue card
# merge-agent is ALWAYS invoked, regardless of whether conflicts exist

# Via CLI
pan specialists wake merge-agent --issue MIN-123

• Never force-push
• Always run tests before completing
• Document conflict resolution decisions
• Provide detailed feedback on what was merged

​

Review Pipeline Flow

Human clicks "Review"
        │
        ▼
┌───────────────────┐
│   review-agent    │ Reviews code, checks for issues
└─────────┬─────────┘
          │ If PASSED: queues test-agent
          │ If BLOCKED: sends feedback to work-agent
          ▼
┌───────────────────┐
│    test-agent     │ Runs test suite, analyzes failures
└─────────┬─────────┘
          │ If PASSED: marks ready for merge
          │ If FAILED: sends feedback to work-agent
          ▼
┌───────────────────┐
│  (Human clicks    │ Human approval required
│  "Approve & Merge"│ before merge
└─────────┬─────────┘
          ▼
┌───────────────────┐
│   merge-agent     │ Performs merge, resolves conflicts
└───────────────────┘

• Human-initiated start - A human must click “Review” to start the pipeline
• Automatic handoffs - review-agent → test-agent happens automatically
• Human approval for merge - Merge is NOT automatic; human clicks “Approve & Merge”
• Feedback loops - Failed reviews/tests send feedback back to the work-agent

​

Queue Processing

1. Task arrives (via API or handoff)
        │
        ▼
2. wakeSpecialistOrQueue() checks if specialist is busy
        │
        ├── If IDLE: Wake specialist immediately with task
        │
        └── If BUSY: Add task to queue (hook.json)
                │
                ▼
3. When specialist completes current task:
        │
        ├── Updates status via API (passed/failed/skipped)
        │
        └── Dashboard automatically wakes specialist for next queued task

1. Sets the specialist state to idle
2. Checks the specialist’s queue for pending work
3. If work exists, immediately wakes the specialist with the next task

​

Agent Self-Requeue (Circuit Breaker)

# Work-agent requests re-review after fixing issues
pan work request-review MIN-123 -m "Fixed: added tests for edge cases"

• First human click resets the counter to 0
• Each pan work request-review increments the counter
• After 3 automatic re-requests, returns HTTP 429
• Human must click “Review” in dashboard to continue

​

Specialist Auto-Initialization

# Initialize all specialists
pan specialists init

# Initialize specific specialist
pan specialists init review-agent

​

Specialist Safeguards

1. Run in workspaces only - Never in the main project directory
2. Never checkout branches - They work with the branch already in the workspace
3. Create workspaces if needed - Use pan workspace create <ISSUE-ID> instead of git checkout

• Prompt instructions - Clear warnings in all specialist prompts
• Code enforcement - Specialists spawn with workspace as cwd
• Git hooks - Auto-revert if checkout detected in tmux sessions

​

Configuration

{
  "specialists": {
    "test_agent": {
      "enabled": true,
      "auto_wake": true,
      "model": "sonnet"
    },
    "review_agent": {
      "enabled": true,
      "auto_wake": false,
      "model": "sonnet"
    },
    "merge_agent": {
      "enabled": true,
      "auto_wake": false,
      "model": "sonnet"
    }
  }
}

• enabled - Whether the specialist is active
• auto_wake - Whether to automatically wake on trigger (vs manual)
• model - Which AI model to use (haiku, sonnet, opus)

​

Viewing Specialist Status

# Check status of all specialists
pan specialists status

# View specific specialist
pan specialists status review-agent

# See specialist queue
pan specialists queue review-agent

​

Related Guides

• Cloister - AI lifecycle manager that coordinates specialists
• Convoys - Parallel specialist execution for code review
• Agent Commands - CLI commands for working with agents