mirror of
https://github.com/OpenRouterTeam/spawn.git
synced 2026-04-28 03:49:31 +00:00
Add continuous improvement workflow for spawn matrix (#5)
- manifest.json: tracks agents x clouds matrix with metadata - CLAUDE.md: instructions for Claude Code to fill gaps and discover new agents/clouds - improve.sh: loop script that launches Claude Code to expand the matrix Current matrix: 3 agents (claude, openclaw, nanoclaw) x 2 clouds (sprite, hetzner) with 2 gaps remaining (hetzner/openclaw, hetzner/nanoclaw). Co-authored-by: Sprite <noreply@sprite.dev> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
L
GitHub
parent
bd30565d86
commit
6002e6c7f7
3 changed files with 391 additions and 0 deletions
114
CLAUDE.md
Normal file
114
CLAUDE.md
Normal file
|
|
@ -0,0 +1,114 @@
|
|||
# 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/
|
||||
{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
|
||||
```
|
||||
|
||||
## 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 test/run.sh` if tests exist for the cloud
|
||||
4. Commit with a descriptive message
|
||||
Loading…
Add table
Add a link
Reference in a new issue