spawn-agent

Files (1)

• SKILL.md

SKILL.md (first lines)

# Skill: spawn-agent

Spawn a new sub-agent. The default path is: ask what it's for, scaffold it,
start it as a plain systemd service, register it on the bridge. No Terraform,
no Docker, no container — the agent is reachable via `@<name>` in a message
as soon as this finishes. Self-heal, starter skills, a full numbered-rules
constitution, and Docker isolation are all opt-in flags layered on top —
never part of the default pass.

## Usage

```
spawn-agent <agent-name> <one-line-purpose>
  [--mode=docker]        # opt in to Terraform + container isolation (advanced)
  [--with-self-heal]     # wire in the self-heal escalation skill
  [--with-skill=<name>]  # scaffold one starter skill from a template
  [--full-constitution]  # write the old-style numbered-rules MEMORY.md
```

If invoked conversationally ("create an agent that does X"), ask only for the
agent name and a one-line purpose — nothing else — then run straight through
without per-step confirmation.

## Default flow — service mode (no Terraform, no Docker)

Every `agents/...` path below is relative to the repo checkout, not to Iris's
own working directory (`/iris/data`, where she actually runs from) — `cd`
there first, same convention as `skills/github/SKILL.md` /
`skills/terraform/SKILL.md`:
```bash
cd "${IRIS_REPO_DIR:-/iris/repo}"
```
Skipping this sends every relative path below looking in the wrong place
(seen in production: `ls agents/lib/` and `cat agents/service-bootstrap.template.sh`
came back empty from `/iris/data`, and the actual files were only found after
a `find /iris -name ...` turned up `/iris/repo/agents/...`).

### Step 1 — Scaffold

Create `agents/<name>/`:
```
agents/<name>/
├── MEMORY.md   ← name + the one-line purpose (a paragraph, not a constitution)
├── README.md   ← agent keeps this updated
└── skills/     ← empty unless --with-skill / --with-self-heal was given
```
`--full-constitution` writes the old numbered-rules/what-it-can't-do-without-confirmation
form of `MEMORY.md` instead of the one-paragraph default.

### Step 2 — Commit (only if a GitHub PAT is configured)

```bash
if agents/lib/register-bridge.sh has-pat; then
  cd /iris/repo && git add "agents/<name>/" && git commit -m "feat: scaffold <name> agent" && \
    git push "https://x-access-token:$(get-secret GITHUB-TOKEN)@github.com/${IRIS_GITHUB_ORG}/${IRIS_GITHUB_REPO}.git" main
else
  echo "No GitHub PAT configured — skipping commit, agent stays local-only for now."
fi
```
No PAT means no point calling `gh`/git tooling — skip cleanly, don't attempt
and fall back. The agent still runs and is bridge-reachable either way;
persisting the scaffold into git (so it survives a VM rebuild) is a separate
concern from making it exist right now.

### Step 3 — Start it as a systemd service

```bash
PORT=$(agents/lib/register-bridge.sh next-port)
cp agents/service-bootstrap.template.sh agents/<name>/bootstrap.sh
sed -i "s/<your-agent>/<name>/g; s/<port>/${PORT}/g" agents/<name>/bootstrap.sh
bash agents/<name>/bootstrap.sh
```
Use one `sed` pass for both placeholders, not two separate edits to the same
file — two concurrent edits to `bootstrap.sh` race on the read-modify-write,
and the loser's substitution gets silently clobbered back to the placeholder
(seen in production: `AGENT_NAME` reverted to `<your-agent>`, producing
`Invalid unit name "iris-agent-<your-agent>"` on start).
This reuses the same already-built `iris-runtime` binary Iris herself runs
(see `bootstrap.sh`'s "Build iris-runtime" step) — no per-agent build, no
container. The unit (`iris-agent-<name>.service`) is active in about a
second. `service-bootstrap.template.sh` already resolves and embeds the
current `IRIS_PROVIDER`/`IRIS_MODEL`/LLM key and symlinks `models.json`, so
the agent can generate a response with no further action — but see below for
any *other* secret a skill you're attaching needs.

**Decide which secrets this agent needs, from the skills it's actually
getting.** If `--with-skill=<name>` scaffolded a skill (or a starter skill was
copied by hand) whose `SKILL.md` frontmatter declares a `secrets:` list — e.g.
`search-web`'s `secrets: [PERPLEXITY-API-KEY]` — that secret must reach this
agent or the skill fails at the exact moment it's invoked, not at spawn time.
Collect this deterministically, don't read frontmatter by hand:
```bash
SECRETS_CSV=$(agents/lib/register-bridge.sh collect-secrets agents/<name>/skills/*)
```
This unions every `secrets:` entry across all skills scaffolded into
`agents/<name>/skills/` and prints them as a comma-separated list (empty if
none declare any). Then check each one actually resolves *now*, before the
agent goes live with a skill it can't use yet:
```bash
agents/lib/register-bridge.sh check-secrets "$SECRETS_CSV"
```
This warns (doesn't block) about any name that doesn't resolve via
`get-secret` in the current install — surface those warnings to the user so
they know to configure it, but keep going; a missing secret means that one
skill fails when invoked, not that the whole agent is broken.

For each collected secret, in an env-mode install, resolve it from
`/iris/.env` and add it to `agents/<name>/bootstrap.sh` as its own literal
`Environment=` line — the same pattern the template already uses for the LLM
key, never `EnvironmentFile=/iris/.env` (see the template's own warning for
why). In a store/proxy-mode install, skip the literal env var and instead pass
`$SECRETS_CSV` through to `register-bridge.sh register` in the next step — the
agent resolves it itself via `get-secret`/the internal broker route,
credential-store agnostic either way.

### Step 4 — Patch it into the bridge (always, unconditional)

```bash
agents/lib/register-bridge.sh register "<name>" "http://127.0.0.1:${PORT}" "<one-line-purpose>" "" "$SECRETS_CSV"

From irisworks/iris-core, Apache-2.0.

More from irisworks/iris-core