spawn-instance

<!-- autoresearch: variation C — robust: skill-existence validation, exit taxonomy, idempotent recovery, dynamic SETUP.md, pre/post-flight verification -->

> **${var}** — Name and purpose of the new instance. Format `name: purpose`, e.g. `crypto-tracker: monitor DeFi protocols and token movements`. If empty, notify the owner and **stop** with exit `SPAWN_INVALID_VAR`.

Today is ${today}. Create a new Aeon instance by forking this repo, configuring it for a specific purpose, validating the configuration, and registering it in the fleet.

Read `memory/MEMORY.md` at the start for context.

## Security Model

This skill creates the repo and configuration but does **NOT** propagate secrets.
The new instance is inert until the owner manually sets secrets (`ANTHROPIC_API_KEY` or `CLAUDE_CODE_OAUTH_TOKEN`, plus notification secrets).
Each instance has its own API keys for billing isolation and blast-radius containment.

## Exit Taxonomy

Every run ends with one of these status codes, written to the log and (where relevant) included in the notification:

| Code | Meaning |
|------|---------|
| `SPAWN_OK` | Fork created, configured, pushed, Actions enabled, registered. |
| `SPAWN_FORK_EXISTS_RECOVERED` | Fork already existed but wasn't registered → configured + registered now. |
| `SPAWN_FORK_EXISTS_REGISTERED` | Fork exists AND is already registered and not archived — refused, no change. |
| `SPAWN_INVALID_VAR` | var was empty or couldn't be parsed into `name: purpose`. |
| `SPAWN_NO_SKILLS` | After validation, the skill plan was empty — refused. |
| `SPAWN_FORK_FAILED` | `gh repo fork` and the fallback `forks` API both failed. |
| `SPAWN_PUSH_FAILED` | Fork created but push failed — fork left in place, recovery instructions emitted. |
| `SPAWN_ACTIONS_FAILED` | Configuration pushed but enabling Actions failed — recovery instructions emitted. |
| `SPAWN_API_ERROR` | Any other GitHub API failure not covered above. |

## Steps

### 1. Parse and validate the var

- If `${var}` is empty, log `SPAWN_INVALID_VAR: empty var` to `memory/logs/${today}.md`, notify: `spawn-instance: empty var — re-run with "name: purpose"`, and **stop**.
- Split on the first `:` — left is `NAME_RAW`, right is `PURPOSE` (trim whitespace). If either is empty, exit `SPAWN_INVALID_VAR`.
- Derive `NAME`: lowercase `NAME_RAW`, replace non-alphanumeric runs with `-`, strip leading/trailing `-`, truncate to 40 chars. If empty after sanitization, exit `SPAWN_INVALID_VAR`.
- Set `REPO_NAME="aeon-${NAME}"`.

### 2. Pre-flight checks

```bash
gh auth status || { echo "SPAWN_API_ERROR: gh not authenticated"; exit 1; }
OWNER=$(gh api user --jq '.login') || { echo "SPAWN_API_ERROR: cannot read user"; exit 1; }
PARENT_REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
# If current repo is itself a fork, use the upstream as the parent:
PARENT_UPSTREAM=$(gh api "repos/${PARENT_REPO}" --jq '.parent.full_name // .full_name')
```

Check rate limit:
```bash
REMAINING=$(gh api rate_limit --jq '.resources.core.remaining')
[ "${REMAINING:-0}" -lt 50 ] && { echo "SPAWN_API_ERROR: rate limit too low (${REMAINING})"; exit 1; }
```

### 3. Check the fleet registry

Read `memory/instances.json`. If it doesn't exist, create it with `{"instances": []}`.

```json
{
  "instances": [
    {
      "name": "crypto-tracker",
      "repo": "OWNER/aeon-crypto-tracker",
      "purpose": "monitor DeFi protocols and token movements",
      "created": "2026-04-20",
      "status": "pending_secrets",
      "skills_enabled": ["token-movers", "defi-overview", "heartbeat"],
      "parent": "OWNER/aeon"
    }
  ]
}
```

- If an entry with `name == NAME` exists and `status != "archived"`, exit `SPAWN_FORK_EXISTS_REGISTERED`, notify, and **stop**.
- If an entry exists and is archived, remove it — the new run replaces it.

### 4. Build the skill plan from the live catalog

**Do not use a hardcoded skill list.** The catalog in earlier revisions contained broken names (`wallet-digest`, `trending-coins`, `tweet-digest`, `hn-digest` — none of which exist in `skills/`). Always enumerate live.

```bash
# Build live catalog of available skills and their tags/description.
for d in skills/*/; do
  name=$(basename "$d")
  [ -f "$d/SKILL.md" ] || continue
  # Extract frontmatter fields (description + tags)
  awk '/^---/{f++;next} f==1{print}' "$d/SKILL.md"
done
```

For each skill, parse the frontmatter `description:` and `tags:` lines. Classify the purpose into themes by keyword match (case-insensitive) and pick skills whose description or tags overlap:

| Purpose keywords | Prefer skills matching tags / keywords |
|---|---|
| `crypto`, `defi`, `token`, `chain`, `wallet` | tags `[crypto]` or description contains `token`/`defi`/`chain` |
| `research`, `paper`, `academic`, `science` | tags `[research]` or name contains `paper`/`research`/`deep-research` |
| `social`, `twitter`, `x `, `tweet`, `farcaster` | tags `[social]` or name contains `tweet`/`twitter`/`farcaster`/`reply` |
| `news`, `digest`, `feed`, `brief` | name contains `digest`/`brief`/`morning`/`rss`/`hacker-news` |
| `dev`, `code`, `github`, `repo`, `pr ` | tags `[dev]` or name contains `github`/`code`/`repo`/`pr-`/`changelog` |
| `security`, `vuln`, `audit` | tags `[security]` or name contains `security`/`vuln`/`audit` |
| `prediction`, `polymarket`, `kalshi`, `market` | name contains `polymarket`/`kalshi`/`market`/`narrative` |

Rules:
- **Cap at 8** content skills. Rank by keyword density in description against purpose; tie-break by name.
- **Always include `heartbeat`** if the file `skills/heartbeat/SKILL.md` exists (health monitoring).
- If the purpose doesn't match any theme, fall back to `[reflect, heartbeat]` (filtered against existence).
- **Validate every candidate** — drop any skill where `skills/${skill}/SKILL.md` doesn't exist; log each drop as `SPAWN_DROPPED_SKILL: ${skill}`.
- If the final list is empty (no content skills survive), exit `SPAWN_NO_SKILLS`, notify, and **stop**.

Save the final list as