spawn/CLAUDE.md

# Spawn

Spawn is a matrix of **agents x clouds**. Every script provisions a cloud server, installs an agent, injects OpenRouter credentials, and drops the user into an interactive session.

## The Matrix

`manifest.json` is the source of truth. It tracks:
- **agents** — coding agents / AI tools (Claude Code, OpenClaw, NanoClaw, ...)
- **clouds** — cloud providers to run them on (Sprite, Hetzner, ...)
- **matrix** — which `cloud/agent` combinations are `"implemented"` vs `"missing"`

## How to Improve Spawn

When run via `./improve.sh`, your job is to pick ONE of these tasks and execute it:

### 1. Fill a missing matrix entry

Look at `manifest.json` → `matrix` for any `"missing"` entry. To implement it:

- Find the **cloud's** `lib/common.sh` — it has all the provider-specific primitives (create server, run command, upload file, interactive session)
- Find the **agent's** existing script on another cloud — it shows the install steps, config files, env vars, and launch command
- Combine them: use the cloud's primitives to execute the agent's setup steps
- The script goes at `{cloud}/{agent}.sh`

**Pattern for every script:**
```
1. Source {cloud}/lib/common.sh (local or remote fallback)
2. Authenticate with cloud provider
3. Provision server/VM
4. Wait for readiness
5. Install the agent
6. Get OpenRouter API key (env var or OAuth)
7. Inject env vars into shell config
8. Write agent-specific config files
9. Launch interactive session
```

**OpenRouter injection is mandatory.** Every agent script MUST:
- Set `OPENROUTER_API_KEY` in the shell environment
- Set provider-specific env vars (e.g., `ANTHROPIC_BASE_URL=https://openrouter.ai/api`)
- These come from the agent's `env` field in `manifest.json`

### 2. Add a new agent

Research coding agents, AI CLI tools, or AI-powered dev tools. To add one:

1. Add an entry to `manifest.json` → `agents` with: name, description, url, install command, launch command, and env vars needed for OpenRouter
2. Add `"missing"` entries to the matrix for every existing cloud
3. Implement the script for at least one cloud
4. Update `README.md`

**Where to find new agents:**
- GitHub trending in AI/coding categories
- OpenRouter's ecosystem
- HuggingFace agent frameworks
- CLI tools that accept `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` (these work with OpenRouter via base URL override)

### 3. Add a new cloud provider

Research cloud providers with API-based provisioning. To add one:

1. Create `{cloud}/lib/common.sh` with the provider's primitives:
   - Auth/token management (env var → config file → prompt)
   - Server creation (API call or CLI)
   - SSH/exec connectivity
   - File upload
   - Interactive session
   - Server destruction
2. Add an entry to `manifest.json` → `clouds`
3. Add `"missing"` entries to the matrix for every existing agent
4. Implement at least one agent script
5. Update `README.md`

**Good candidate clouds** have:
- REST API or simple CLI for provisioning
- SSH access to the created server
- Cloud-init or similar userdata support
- Pay-per-hour pricing (so users can destroy after use)

### 4. Extend tests

`test/run.sh` contains the test harness. When adding a new cloud or agent:
- Add mock functions for the cloud's CLI/API calls
- Add per-script assertions matching the agent's setup steps
- Run `bash test/run.sh` to verify

## File Structure Convention

```
spawn/
  cli/
    spawn.sh          # Main CLI binary (interactive picker, matrix viewer, launcher)
    install.sh        # One-liner installer (downloads spawn.sh to ~/.local/bin)
  {cloud}/
    lib/common.sh     # Cloud-specific shared functions
    {agent}.sh        # One script per agent
  manifest.json       # The matrix (source of truth)
  improve.sh          # Run this to trigger one improvement cycle
  test/run.sh         # Test harness
  README.md           # User-facing docs
```

## CLI (`cli/`)

The `spawn` CLI is a pure-bash binary that provides a unified entry point for the matrix.

- **`cli/spawn.sh`** — Main binary. Fetches manifest.json from GitHub (cached for 1hr at `~/.cache/spawn/`), parses it with `jq` or `python3` fallback, and provides: interactive picker (`spawn`), direct launch (`spawn <agent> <cloud>`), agent info (`spawn <agent>`), matrix table (`spawn list`), and self-update (`spawn update`). Installed to `~/.local/bin/spawn`.
- **`cli/install.sh`** — One-liner installer. Downloads `spawn.sh` to `~/.local/bin/spawn`, sets executable bit, and prints PATH instructions if needed. Override install dir with `SPAWN_INSTALL_DIR` env var.

## Script Conventions

- `#!/bin/bash` + `set -e`
- Source `lib/common.sh` with local-first, remote-fallback pattern
- Use `OPENROUTER_API_KEY` env var to skip OAuth when set
- All env vars documented in README.md under the relevant section
- Remote fallback URL: `https://raw.githubusercontent.com/OpenRouterTeam/spawn/main/{path}`
- Scripts must be runnable via: `bash <(curl -fsSL https://openrouter.ai/lab/spawn/{cloud}/{agent}.sh)`

## After Each Change

1. Update `manifest.json` matrix status to `"implemented"`
2. Update `README.md` with usage instructions
3. Run `bash -n {file}` to syntax-check your scripts
4. Commit with a descriptive message

## Agent Team Roles

When running as part of an agent team (`./improve.sh`), teammates are assigned specific roles:

### Gap Filler
You're assigned a specific `{cloud}/{agent}` entry to implement. Steps:
1. Read `{cloud}/lib/common.sh` — understand the cloud's primitives
2. Read an existing `{agent}.sh` on another cloud — understand the install steps
3. Write `{cloud}/{agent}.sh` combining the two
4. Update `manifest.json` matrix entry to `"implemented"`
5. Add usage entry to `README.md` under the cloud's section
6. `bash -n` syntax check
7. Commit your changes only (don't touch other teammates' files)

### Agent Scout
Research and add ONE new AI coding agent. Requirements:
- Must be installable via a single command (`npm install -g`, `pip install`, `curl | bash`, etc.)
- Must accept API keys via environment variables (`OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`, etc.)
- OpenRouter compatibility: either native `OPENROUTER_API_KEY` support, or `OPENAI_BASE_URL=https://openrouter.ai/api/v1` override
- Add to `manifest.json` → `agents` with full metadata including `env` field
- Add `"missing"` entries in the matrix for ALL existing clouds
- Implement on at least 2 clouds to prove the pattern
- Update `README.md`

### Cloud Scout
Research and add ONE new cloud provider. Requirements:
- REST API or CLI for provisioning VMs/instances
- SSH access to created servers
- Cloud-init, userdata, or startup-script support
- Pay-per-hour pricing
- Create `{cloud}/lib/common.sh` with ALL primitives (see existing clouds for the pattern)
- Add to `manifest.json` → `clouds`
- Add `"missing"` entries for ALL existing agents
- Implement at least 2 agents to prove the lib works
- Update `README.md`

### Coordination Rules
- **Never edit the same file as another teammate** — coordinate via the shared task list
- **manifest.json conflicts**: only ONE teammate should update manifest.json at a time. If you're a Gap Filler, update just your entry. If you're a Scout, add your block and your matrix entries.
- **README.md**: append your section, don't rewrite others' sections
- **Commit early**: commit your work as soon as it's done so other teammates can see it
- **Self-claim**: when you finish your assigned task, check the task list for the next unblocked item