Initial agents skill - instance management with personalities

2026-02-02 23:20:33 +01:00
commit 53c2fca080
3 changed files with 744 additions and 0 deletions
--- a/SKILL.md
+++ b/SKILL.md
@@ -0,0 +1,135 @@
+---
+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"}'
+```