Subagent Spawn Command Builder

---
name: subagent-spawn-command-builder
description: Build sessions_spawn command payloads from JSON profiles. Use when you want reusable subagent profiles (model/thinking/timeout/cleanup/agentId/label) and command-ready JSON without executing spawn.
---

# subagent-spawn-command-builder

Generate `sessions_spawn` payload JSON from profile config.
This skill does not execute `sessions_spawn`; it only builds payload/command JSON.

## Files

- Builder script: `scripts/build_spawn_payload.mjs`
- Builder log: `state/build-log.jsonl`

## Supported sessions_spawn parameters

- `task` (required)
- `label` (optional)
- `agentId` (optional)
- `model` (optional)
- `thinking` (optional)
- `runTimeoutSeconds` (optional)
- `cleanup` (`keep|delete`, optional)
- `cwd` (optional) — working directory for the subagent
- `mode` (`run|session`, optional)

## Setup

Read the "Subagent Spawn Profiles" table in TOOLS.md for default values per profile. Pass values as explicit CLI arguments (`--model`, `--thinking`, `--run-timeout-seconds`, `--cleanup`). The `--profile` flag is now a logging label, not a lookup key for a config file.

## Generate payload

```bash
skills/subagent-spawn-command-builder/scripts/build_spawn_payload.mjs \
  --profile heartbeat \
  --task "Analyze recent context and return a compact summary" \
  --label heartbeat-test \
  --model claude-sonnet-4-20250514 \
  --thinking low \
  --run-timeout-seconds 300 \
  --cleanup delete
```

The script prints JSON directly usable for `sessions_spawn`.

## Merge/priority rule

All values come from explicit CLI arguments. `--profile` is a logging label only (not a config lookup key). Refer to the "Subagent Spawn Profiles" table in TOOLS.md for recommended defaults per profile.

`task` always comes from CLI `--task`.

## CLI options

Note: this builder is Node.js (`.mjs`) based. If generated tasks include Python execution steps, write commands with `python3` (not `python`).

- `--profile` (required)
- `--task` (required)
- `--label`
- `--agent-id`
- `--model`
- `--thinking`
- `--run-timeout-seconds`
- `--cleanup keep|delete`
- `--cwd <path>`
- `--mode run|session`