---
name: background-agents
description: Parallel background agent delegation using Gateway V2 for true multitasking
category: orchestration
priority: P0
tags: [parallel, delegation, multitasking, gateway, wzrd]
subskills:
  - gateway-integration
  - model-routing
  - agent-spawning
  - job-tracking
---

# Skill: Background Agents

## Purpose
Enable true parallel background agent execution using wzrd.dev Gateway V2 system, allowing multiple agents to work simultaneously on different tasks.

## Core Principle
**"True parallelism beats async delegation. Spawn, don't wait."**

## Why Not OpenCode Background Agents?

The OpenCode background agents plugin has critical limitations:
1. **Blocks main session** - Can't receive messages while sub-agent runs
2. **Single process** - Still runs in same OpenCode instance
3. **No true parallelism** - Just async within same context

Our Gateway V2 solution:
1. **True parallel processes** - Each agent runs independently
2. **Non-blocking** - Continue working while agents run
3. **Persistent results** - Saved to job tracking system
4. **Unlimited concurrency** - Spawn as many agents as needed

## Workflow

### Step 1: Identify Parallelizable Work
- Research tasks that can run independently
- Code review/analysis tasks
- Data processing/fetching
- Documentation generation
- Testing/validation tasks

### Step 2: Spawn Background Agent via Gateway V2
```bash
curl -X POST http://127.0.0.1:18801/api/gateway/chat \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Research best practices for OAuth2 PKCE",
    "agent": "raya",
    "topic": "background-research",
    "model": "deepseek-ai/deepseek-v3.2",
    "platform": "cli",
    "background": true,
    "jobId": "oauth-research-001"
  }'
```

### Step 3: Continue Working
- Keep coding, brainstorming, or reviewing
- Receive notifications when jobs complete
- Multiple background agents can run simultaneously

### Step 4: Retrieve Results
```bash
curl http://127.0.0.1:18801/api/jobs/oauth-research-001
```

## Gateway V2 Integration

### Agent Configuration
```json
{
  "tieredRouting": {
    "routes": {
      "remi": {
        "agent": "remi",
        "workdir": "/home/mdwzrd/wzrd.dev",
        "memory": "/home/mdwzrd/wzrd.dev/memory/MEMORY.md"
      },
      "raya": {
        "agent": "raya", 
        "workdir": "/home/mdwzrd/wzrd.dev",
        "memory": "/home/mdwzrd/wzrd.dev/memory/research/MEMORY.md"
      },
      "renata": {
        "agent": "renata",
        "workdir": "/home/mdwzrd/wzrd.dev/projects/edge.dev",
        "memory": "/home/mdwzrd/wzrd.dev/projects/renata/memory/MEMORY.md"
      }
    }
  }
}
```

### Model Routing Strategy

| Agent | Model | Use Case | Cost |
|-------|-------|----------|------|
| **remi** | glm-4.5-air | Orchestration, coordination | Free (NVIDIA) |
| **raya** | deepseek-ai/deepseek-v3.2 | Research, analysis | Free (NVIDIA) |
| **renata** | glm-4.5 | Trading strategies | Free (NVIDIA) |
| **ted** | glm-4.7 | Architecture, deep reasoning | Free (NVIDIA) |
| **sadie** | glm-4.5-air | Quick tasks, planning | Free (NVIDIA) |

## Job Tracking System

### Job Storage Location
```
/home/mdwzrd/wzrd.dev/gateway-v2/jobs/
├── {job-id}.json      # Job metadata and results
├── {job-id}.md        # Markdown output
└── {job-id}.log       # Execution logs
```

### Job Status Updates
Gateway V2 provides WebSocket notifications:
```
ws://127.0.0.1:18801/ws/jobs
```

## Command Integration

### Use `/launch` Command with Background Flag
```bash
wzrd launch --agent raya --prompt "Research OAuth2 PKCE" --background --job-id oauth-research
```

### Custom CLI Commands
```bash
# Spawn background agent
wzrd bg-spawn --agent raya --prompt "Research task"

# List running background jobs
wzrd bg-jobs

# Get job results
wzrd bg-results <job-id>

# Kill background job
wzrd bg-kill <job-id>
```

## Examples

### Example 1: Parallel Research & Coding
```bash
# Spawn research in background
curl -X POST http://127.0.0.1:18801/api/gateway/chat \
  -d '{
    "prompt": "Research WebSocket best practices",
    "agent": "raya",
    "background": true,
    "jobId": "websocket-research"
  }'

# Continue coding while research runs
wzrd --topic "api-design" opencode "Implement WebSocket endpoint"
```

### Example 2: Multi-Agent Code Review
```bash
# Spawn architecture review
curl -X POST http://127.0.0.1:18801/api/gateway/chat \
  -d '{
    "prompt": "Review architecture of auth system",
    "agent": "ted",
    "background": true,
    "jobId": "arch-review"
  }'

# Spawn security review  
curl -X POST http://127.0.0.1:18801/api/gateway/chat \
  -d '{
    "prompt": "Review security of auth endpoints",
    "agent": "security-agent",
    "background": true,
    "jobId": "security-review"
  }'

# Continue implementing features
```

### Example 3: Trading Agent Parallel Work
```bash
# Renata builds strategy in background
curl -X POST http://127.0.0.1:18801/api/gateway/chat \
  -d '{
    "prompt": "Build V31 scanner for FBO pattern",
    "agent": "renata",
    "workdir": "/home/mdwzrd/wzrd.dev/projects/edge.dev",
    "background": true,
    "jobId": "fbo-scanner"
  }'

# Continue on other trading tasks
```

## Gold Standard Integration

### Read-Back Verification
1. Verify job was created: `ls ~/wzrd.dev/gateway-v2/jobs/{job-id}.*`
2. Check job status via API
3. Verify results saved to disk

### Executable Proof
- Show job files created
- Demonstrate non-blocking main session
- Display parallel execution logs

### Loop Prevention
If background agent fails:
1. Retry with simplified prompt
2. Fall back to different model
3. Escalate to main agent after 3 failures

## Integration with Existing Skills

### `orchestration` Skill
- Use for coordinating multiple background agents
- Role-shifting between monitoring and working

### `agent-onboarding` Skill  
- Create specialized background agents
- Define agent personas and capabilities

### `commands` Skill
- Create `/bg-*` command family
- Integrate with existing command patterns

## Implementation Checklist

- [ ] Gateway V2 configured with NVIDIA models
- [ ] Job tracking system implemented
- [ ] WebSocket notifications working
- [ ] CLI commands for bg operations
- [ ] Integration with existing agent personas
- [ ] Memory persistence for job results
- [ ] Error handling and retry logic

## Performance Considerations

### Concurrency Limits
- Maximum 10 concurrent background agents
- Memory monitoring via Gateway V2
- Auto-kill stalled jobs after 30 minutes

### Resource Management
- Each agent gets isolated memory space
- Model selection based on task complexity
- Results automatically compressed and saved

---

**"Don't wait for answers. Work while answers work for you."**

Base directory for this skill: /home/mdwzrd/.claude/skills/background-agents
Relative paths in this skill are relative to this base directory.