spawn-instance

name	spawn-instance
description	Add a teammate — one command (`aw team add … --start`) materializes an instance's home from a blueprint profile, sets up its isolated git worktree, and launches it. Use when a human asks for a teammate or assigned work needs one.

Spawn an instance (a teammate)

An instance is a runnable teammate with its own aweb identity, a home, and — for code roles — an isolated git worktree. Since aw 1.31, aw team add … --start does the whole thing in one command: it materializes the home from a blueprint profile, sets up the worktree isolation, and launches the runtime — no manual invite / accept / init / symlink / git worktree add dance.

Spawn when a human asks, or when assigned work needs a teammate — not on your own initiative to "get help".

Spawn — one command, from your own instance home

aw reads your identity from the current directory's .aw, so run this from your own home (it uses your team's authority to add the member):

aw team add <name>@aweb.team/<role>=<runtime> --start \
  --home <abs/path/to/agents/instances/<name>> \
  --session <tmux-session> --no-attach

• <role> is a profile in the blueprint (developer, reviewer, proofreader, …); <runtime> is claude-code or pi. Override the blueprint with --blueprint / AWEB_BLUEPRINT (default aweb.team).
• --start materializes the home from the public blueprint (an auth-less read), sets up <home>/worktree/ — a git worktree on the agent's own branch — plus a work-main/ symlink for coordination roles (works_on_main), then launches the runtime in tmux with channel preflight, trust/dev-channel prompt auto-answering, and pi --approve. It connects to the channel on its own.
• --session <name> + --no-attach — put the window in a named tmux session and don't attach. Use a fresh/throwaway session so you never touch a live team's session. --recreate is refused when the target session holds running agent windows; --force-kill is the explicit override that kills them. Prefer a fresh --session over ever reaching for --force-kill.
• --home overrides the default agents/instances/<name>. Never move or rename a home after materialization — aweb registers the identity at its path.

The agent runs aw from its home and does all git/builds from worktree/.

Verify: aw workspace status shows the new member active; the tmux pane shows the runtime up (claude: bypass permissions on; pi: ✓ aweb connected).

Materialize now, run later (two-step)

Drop --start to just materialize + isolate the home; launch it later with aw team up (same launch path). Use this when you want the home staged before running it.

Retire

When the teammate is no longer needed, use the retire-instance skill (revoke the membership, remove the worktree + home).