---
name: subagent-registry
description: Manage named subagent instances. MUST be used when spawning, resuming, listing, or deleting subagents. Read this skill FIRST before any subagent operation.
---

# Subagent Registry — CRITICAL

You MUST manage `<project>/.pi/subagents.json` for ALL subagent operations. Read the file before any operation. Write the file after any change.

## File Location

`<cwd>/.pi/subagents.json` (where cwd is the current project directory)

## File Format

```json
{
  "session": "<pi-session-name-or-project-dir>",
  "agents": [
    {
      "name": "<human-readable-name>",
      "id": "<agent-uuid-from-spawn-notification>",
      "type": "<subagent_type>",
      "provider": "<exact-provider-config-from-agent-frontmatter>",
      "status": "running|completed|error",
      "created": "<ISO-timestamp>"
    }
  ]
}
```

## MANDATORY Operations

### SPAWN — Always do this:
1. Ask user for a name if not provided: "What should I name this subagent?"
2. Spawn the agent: `Agent({ subagent_type, prompt, run_in_background: true })`
3. Wait for completion notification — extract the agent ID from the response
4. Read current `.pi/subagents.json`
5. Append new agent entry with name, id, type, provider, status="running", timestamp
6. Write updated `.pi/subagents.json`
7. Tell user: "Created subagent '<name>' (<id-short>) using <provider>"

### LIST — Always do this:
1. Read `.pi/subagents.json`
2. If file doesn't exist or agents array is empty: "No subagents found."
3. Display compact table:
```
Name         Type        Provider    Status    Created
----         ----        --------    ------    -------
searcher     chat-search Google      ↻ run     15:35
```
4. Show: name, type, provider, status, created time

### RESUME — Always do this:
1. Read `.pi/subagents.json`, find agent by name
2. If not found: "No subagent named '<name>'. Available: <list-of-names>"
3. If found: `Agent({ subagent_type, resume: "<agent-id>", prompt: "<new-task>", run_in_background: true })`
4. Update status to "running" in registry
5. Tell user: "Resumed '<name>' (<id-short>) — <provider> cache warm"

### DELETE — Always do this:
1. Read `.pi/subagents.json`, find agent by name
2. If running: steer to abort first
3. Remove entry from registry array
4. Write updated `.pi/subagents.json`
5. Tell user: "Deleted '<name>'"

### DELETE SESSION — Always do this:
1. Read `.pi/subagents.json`
2. Remove all agents where session matches
3. Write updated `.pi/subagents.json`
4. Tell user: "Deleted <N> subagents from session '<name>'"

## Rules

- **NEVER spawn without asking for a name first**
- **NEVER skip writing to the registry** after spawn/resume/delete
- **ALWAYS read the registry** before listing or resuming
- **Provider config must be preserved exactly** from the agent's frontmatter (e.g., "only:DeepInfra")
- **No auto-cleanup** — agents persist until explicitly deleted
- **Each named agent gets `memory: project`** in its frontmatter for persistent memory

## Example Workflow

```
User: "Spawn a coder-pro to fix the login module"
You: "What should I name this subagent?"
User: "auth-login"
You: *spawn agent → get ID 7efad0d8-5a78-415*
You: *read .pi/subagents.json → append entry → write file*
You: "Created subagent 'auth-login' (7efad0d8) using DeepInfra"

User: "List my subagents"
You: *read .pi/subagents.json → display table*
  auth-login    coder-pro  DeepInfra  ↻ running  20:00

User: "Resume auth-login and add password reset"
You: *read .pi/subagents.json → find ID → resume*
You: "Resumed 'auth-login' (7efad0d8) — DeepInfra cache warm"
```