mirror of
https://github.com/OpenRouterTeam/spawn.git
synced 2026-04-28 11:59:29 +00:00
92e8618d20
* refactor: remove commands.ts compatibility shim and fix stale references - Delete packages/cli/src/commands.ts shim file (only re-exported commands/index.ts) - Update index.ts to import directly from ./commands/index.js - Update 24 test files to import from ../commands/index.js - Fix stale CLAUDE.md reference to commands.ts - Fix stale QA prompt references to commands.ts and wrong line numbers - Bump CLI version to 0.15.8 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs: remove stale references to deleted commands.ts compatibility shim --------- Co-authored-by: spawn-qa-bot <qa@openrouter.ai> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com> Co-authored-by: L <6723574+louisgv@users.noreply.github.com>
85 lines
4.2 KiB
Markdown
85 lines
4.2 KiB
Markdown
# 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** — AI agents and self-hosted AI tools (Claude Code, OpenClaw, ZeroClaw, ...)
|
|
- **clouds** — cloud providers to run them on (Sprite, Hetzner, ...)
|
|
- **matrix** — which `cloud/agent` combinations are `"implemented"` vs `"missing"`
|
|
|
|
## File Structure
|
|
|
|
```
|
|
spawn/
|
|
packages/
|
|
cli/
|
|
src/index.ts # CLI entry point (bun/TypeScript)
|
|
src/manifest.ts # Manifest fetch + cache logic
|
|
src/commands/ # Per-command modules (interactive, list, run, etc.)
|
|
src/commands/index.ts # Barrel re-export of all command modules
|
|
package.json # npm package (@openrouter/spawn)
|
|
sh/
|
|
cli/
|
|
install.sh # One-liner installer (bun → npm → auto-install bun)
|
|
shared/
|
|
github-auth.sh # Standalone GitHub CLI auth helper
|
|
key-request.sh # API key provisioning helpers (used by QA)
|
|
e2e/
|
|
lib/*.sh # E2E helper libraries
|
|
test/
|
|
macos-compat.sh # macOS compatibility test script
|
|
{cloud}/
|
|
{agent}.sh # Agent deployment scripts (thin bash → bun wrappers)
|
|
README.md # Cloud-specific usage docs
|
|
.claude/
|
|
rules/ # Modular rules (auto-loaded by Claude Code)
|
|
scripts/ # Hook scripts (enforce-worktree, validate-file, pre-merge-check)
|
|
skills/setup-agent-team/
|
|
trigger-server.ts # HTTP trigger server (concurrent runs, dedup)
|
|
discovery.sh # Discovery cycle script
|
|
refactor.sh # Dual-mode cycle script (issue fix or full refactor)
|
|
start-discovery.sh # Launcher with secrets (gitignored)
|
|
start-refactor.sh # Launcher with secrets (gitignored)
|
|
.github/workflows/
|
|
discovery.yml # Scheduled + issue-triggered discovery workflow
|
|
refactor.yml # Scheduled + issue-triggered refactor workflow
|
|
manifest.json # The matrix (source of truth)
|
|
discovery.sh # Run this to trigger one discovery cycle
|
|
fixtures/ # API response fixtures for testing
|
|
README.md # User-facing docs
|
|
CLAUDE.md # This file — project overview
|
|
```
|
|
|
|
### Architecture
|
|
|
|
All cloud provisioning and agent setup logic lives in TypeScript under `packages/cli/src/`. Agent scripts (`sh/{cloud}/{agent}.sh`) are thin bash wrappers that bootstrap bun and invoke the CLI.
|
|
|
|
**`sh/shared/github-auth.sh`** — Standalone GitHub CLI installer + OAuth login helper. Used by `packages/cli/src/shared/agent-setup.ts` to set up `gh` on remote VMs.
|
|
|
|
**`sh/shared/key-request.sh`** — API key provisioning helpers sourced by the QA harness (`qa.sh`) for loading cloud credentials from `~/.config/spawn/{cloud}.json`.
|
|
|
|
## After Each Change
|
|
|
|
1. `bash -n {file}` syntax check on all modified scripts
|
|
2. `cd packages/cli && bunx @biomejs/biome check src/` — **must pass with zero errors** (lint + format) on all modified TypeScript
|
|
3. Update `manifest.json` matrix status to `"implemented"`
|
|
4. Update the cloud's `sh/{cloud}/README.md` with usage instructions
|
|
5. Commit with a descriptive message
|
|
|
|
## Filing Issues for Discovered Problems
|
|
|
|
When you encounter bugs, stale references, broken functionality, or architectural issues that are **outside the scope of your current task**, file a GitHub issue immediately rather than ignoring them or trying to fix everything at once:
|
|
|
|
```bash
|
|
gh issue create --repo OpenRouterTeam/spawn --title "bug: <brief description>" --body "<details>"
|
|
```
|
|
|
|
Examples of when to file:
|
|
- Dead code or stale references to files/functions that no longer exist
|
|
- Broken features (e.g., `spawn delete` references non-existent shell scripts)
|
|
- Security concerns that need separate review
|
|
- Architectural debt that would be too large to fix in the current PR
|
|
|
|
**Do NOT silently ignore problems.** If you find something weird and won't fix it now, file an issue so it's tracked.
|