---
name: agents
description: Agent instance management with personalities
metadata:
  version: "1.0.0"
  vibestack:
    main: false
---

# Agents Skill

Manages Claude agent instances with different personalities.

## Concepts

- **Personality**: Template (CLAUDE.md + context) defining an agent's "soul"
- **Instance**: Running Claude process with a personality
- **Workspace**: Directory where an instance does its work

## Directory Structure

```
/personalities/           # Soul templates
├── orchestrator/
│   ├── CLAUDE.md         # System prompt / instructions
│   ├── config.yaml       # Optional: defaults
│   └── context/          # Reference docs
├── frontend-dev/
└── backend-dev/

/workspaces/              # Where work happens
├── project-a/
└── project-b/
```

## Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| `AGENTS_PORT` | API port | `8800` |
| `PERSONALITIES_DIR` | Personalities location | `/personalities` |
| `WORKSPACES_DIR` | Workspaces location | `/workspaces` |
| `AGENTS_DOMAIN` | Domain for Caddy | (none) |

## API

### Personalities

```bash
# List all personalities
GET /personalities

# Get personality details
GET /personalities/{name}
```

### Instances

```bash
# Spawn new instance
POST /instances
{
  "personality": "frontend-dev",
  "workspace": "/workspaces/my-app",  # optional
  "name": "frontend-1"                 # optional, auto-generated
}

# List running instances
GET /instances

# Get instance details
GET /instances/{id}

# Kill instance
DELETE /instances/{id}

# Quick spawn with defaults
POST /spawn/{personality}
```

### Conversations

```bash
# List conversations
GET /conversations

# Get conversation messages
GET /conversations/{id}
```

## Personality Config

Optional `config.yaml` in personality folder:

```yaml
name: frontend-dev
description: React/TypeScript specialist
default_workspace: /workspaces/frontend
model: claude-sonnet-4-20250514
max_turns: 20
max_instances: 3
lifecycle: on-demand  # or long-running
tools:
  - Bash
  - Read
  - Write
  - Edit
  - Glob
  - Grep
```

## Storage

Auto-detects available storage:
1. PostgreSQL (if postgres skill present)
2. DuckDB (if duckdb skill present)
3. SQLite (fallback)

## Instance Discovery

Instances can discover each other:
```bash
# From any instance
curl http://localhost:8800/instances
```

System prompt includes peer info at spawn time.

## Example: Spawning from Claude

An orchestrator agent can spawn specialists:
```bash
curl -X POST http://localhost:8800/instances \
  -d '{"personality":"frontend-dev","workspace":"/workspaces/app"}'
```