| name | spawn-agent |
| description | Prepare a composed Agent-tool invocation via kei-spawn. Click-only wizard — pick role, describe task, set scope. Emits ready-to-paste prompt + subagent_type + isolation + DNA. |
| argument-hint | (no arguments) |
/spawn-agent — Click-only Agent-tool composer (index)
When to use
- Composing a ready-to-paste
Agent-tool invocation via the kei-spawn CLI without writing it by hand.
- Selecting agent role, task description, and scope files through a click-only wizard.
- Preparing a sub-agent spawn that complies with RULE 0.12 (branch + artefact bundle).
You convert a user's intent into a ready-to-paste Agent-tool invocation
via the kei-spawn CLI. Every decision is a click; only the task description
(Phase 2) is typed. No git, no side-effects on disk beyond the task.toml the
CLI consumes.
This SKILL.md is the INDEX. Each phase lives in its own file and is
executed in order. Never skip a phase. Never re-order phases.
Pipeline overview
| Phase | File | Purpose | AskUserQuestion |
|---|
| 1 | phase-1-role.md | Pick agent role (capability tier) | 1× AskUserQuestion |
| 2 | phase-2-task.md | Free-text task description (ONE paragraph) | 0× (only free-text in the skill) |
| 3 | phase-3-scope.md | Files whitelist glob patterns | 2× AskUserQuestion |
| 4 | phase-4-emit.md | Write task.toml, run kei-spawn, emit Agent-tool invocation | 1× AskUserQuestion (confirm-emit) |
Minimum AskUserQuestion count: 4 — pure-click contract.
Variables the pipeline produces
| Name | Set in | Meaning |
|---|
ROLE | Phase 1 | One of read-only / explorer / edit-local / edit-shared |
TASK | Phase 2 | Free-text task description (1-3 sentences) |
WHITELIST | Phase 3 | List of glob patterns (relative to repo root) |
DENYLIST | Phase 3 | Optional list of glob patterns (auto-derived from role if skipped) |
TASK_TOML | Phase 4 | Path tasks/<uuid>.toml relative to current repo |
AGENT_ID | Phase 4 | UUID returned by kei-spawn spawn |
DNA | Phase 4 | SHA-256 fingerprint returned by kei-spawn spawn |
SUBAGENT_TYPE | Phase 4 | Resolved by kei-spawn from ROLE (e.g. code-implementer / researcher) |
ISOLATION | Phase 4 | Resolved by kei-spawn from ROLE (worktree or shared) |
WORKTREE_PATH | Phase 4 | Returned when isolation=worktree |
Role → defaults map (LOAD-BEARING)
| ROLE | subagent_type | isolation | Bash? | Writes? |
|---|
| read-only | researcher | shared | no | no |
| explorer | researcher | shared | read-only bash | no |
| edit-local | code-implementer | worktree | cargo/test only | yes (whitelist) |
| edit-shared | code-implementer | worktree | cargo/test only | yes (whitelist) |
kei-spawn owns the resolution — this table is reference only. The skill
passes the ROLE string verbatim; the CLI returns the resolved values.
Final report (emit after Phase 4)
=== /SPAWN-AGENT REPORT ===
Role: <ROLE>
Task (first 80): <first 80 chars of TASK>...
Whitelist: <N globs> — <first 3 shown>
Denylist: <auto / explicit — N globs>
Agent ID: <UUID>
DNA: <sha256:first-12>...
subagent_type: <SUBAGENT_TYPE>
isolation: <ISOLATION>
Worktree: <WORKTREE_PATH or n/a>
Ready-to-paste Agent-tool invocation:
<JSON block — see phase-4-emit.md §4 for exact shape>
Next step on return:
kei-spawn verify <AGENT_ID> <WORKTREE_PATH>
Runtime binary resolution
kei-spawn must be on PATH OR reachable via $KEI_RUNTIME_BIN_DIR. The
phases call kei-spawn <cmd> directly; if the shell returns command not found, fall back to "$KEI_RUNTIME_BIN_DIR/kei-spawn" <cmd>. If both fail,
STOP and surface the error to the user with three constructive paths:
- (A) Build
kei-spawn from the kit source (cd _primitives/_rust/kei-spawn && cargo build --release).
- (B) Export
KEI_RUNTIME_BIN_DIR to point at an existing build.
- (C) Install via
install.sh which wires both.
Never silently substitute a mock.
Rules (enforced at every phase)
- Pure-click contract. Only
TASK (Phase 2) is typed. Every other
decision is an AskUserQuestion. Count them in the final report.
- NO DOWNGRADE (RULE -1). Any phase that fails returns 2-3 constructive
paths, never "can't be done".
- NO HALLUCINATION (RULE 0.4). Never fabricate a DNA or agent_id — they
come from
kei-spawn spawn --format=json verbatim. Never emit an Agent
invocation without a successful spawn call first.
- Plan Mode First (RULE 0.5). This skill IS the plan; each phase file
has its own verify-criterion. No
kei-spawn spawn call before Phase 4's
confirm click.
- Orchestrator branch first (RULE 0.13). The skill NEVER invokes git.
The emitted prompt MUST contain the phrase "MUST NOT invoke git" so the
spawned agent respects the rule. Phase 4 inserts this automatically.
- Constructor Pattern (RULE ZERO). One file per phase. This SKILL.md
stays <200 LOC; each phase file stays <200 LOC.
- Surgical Changes. The skill only writes
tasks/<uuid>.toml. It does
not modify project source, does not commit, does not push.
References
- phase-1-role.md · phase-2-task.md · phase-3-scope.md · phase-4-emit.md
_primitives/_rust/kei-spawn/ — CLI source (task.toml schema + spawn/verify commands)skills/new-agent/SKILL.md — sister skill: generates agent manifests; this skill spawns instances of existing agentsskills/hooks-control/SKILL.md — reference click-only pattern- RULE 0.12 (agent-git-model) — ledger row auto-written by
kei-spawn spawn
- RULE 0.13 (orchestrator-branch-first) — ban-phrase injected by Phase 4
