bjornmelin/subspawn

Subspawn

Keep subagents bounded. The main agent owns planning, waits for delegated results, synthesizes evidence, and makes final decisions unless the user says otherwise.

Trigger Rules

Use this skill when:

• user asks for subagents, delegation, fan-out, or spawn policy
• task benefits from 1-3 independent bounded subtasks
• model or effort routing for subagents matters
• session needs evidence-first synthesis across delegated results
• custom agent selection or fork behavior matters

Only spawn when the user explicitly asks for subagents or parallel agent work. Do not use this skill to rationalize extra delegation. Keep work local when delegation would add coordination cost without improving quality.

User Overrides

Explicit user instructions override the default delegation heuristics.

If user specifies any below, honor unless unsafe or impossible:

• exact fan-out count
• mandatory delegation or mandatory no-delegation
• specific subagent model
• specific reasoning effort
• explicit wait behavior
• explicit read-only vs edit-capable delegation
• specific custom agent role

When override differs from default:

• keep task bounded anyway
• restate override in spawn contract
• keep synthesis + final decisions in main agent unless user says otherwise

Pre-Spawn Checklist

Before spawning:

1. State the exact batch you will spawn and why each subtask is independent.
2. Identify any work the main agent must pause until results arrive.
3. Tighten each subtask before increasing model or effort:
   • narrow task statement
   • narrow allowed scope or write surface
   • define exact output contract
   • define verification expectations
4. Default to read-only exploration unless scoped edits materially advance the task.

For nontrivial batches, generate a plan before spawning:

python3 skills/subspawn/scripts/subspawn_plan.py plan \
  --preset research \
  --task "Research current Codex subagent docs" \
  --scope "official OpenAI docs and GitHub only"

Use --role for explicit custom role selection, --mode edit only with disjoint write surfaces, and --json when another tool needs to consume the plan. Run validate-roles after changing subagent templates. Packaged standalone subspawn installs include local preset template copies in templates/agents/; full repo checkouts prefer the sibling deep-researcher and subagent-creator templates first.

Fan-Out Rules

• Prefer 1-3 focused subagents.
• No nested subagents unless user asks.
• Explorer-style: read-heavy, evidence-focused. Prefer a custom repo_explorer role when installed; keep Codex built-in explorer as a fallback and avoid custom names that accidentally shadow built-ins.
• Implementation: narrow, explicit file ownership.
• Prefer custom roles when they exist and match the task; fall back to built-in explorer, worker, or default.
• State selected roles in the spawn prompt.

Rendezvous Rule

After spawning a planned batch, immediately wait for every spawned subagent in that batch before doing substantive next work.

While subagents are running, allowed actions are limited to:

• wait_agent or equivalent wait/status operations
• send_input only to unblock or correct a running subagent
• resume_agent or close_agent for lifecycle recovery
• reporting a wait timeout, tool error, or explicit blocker to the user

Do not inspect files, run tests, browse, edit, continue local analysis, start new unrelated tool calls, or produce the final answer until the spawned batch has completed and its results have been synthesized. The only exception is an explicit user instruction to run asynchronous delegation without waiting.

When the runtime exposes explicit close operations, close completed subagent threads after synthesis so long-lived sessions do not accumulate stale agent or MCP resources.

Model Policy

Follow the active Codex tool schema and the custom agent files available in the session.

• Omit per-call model and reasoning_effort when inheriting the parent model or when a custom agent file already pins them.
• Use gpt-5.5 for demanding review, debugging, security, planning, and implementation agents when available.
• Use gpt-5.4 when gpt-5.5 is unavailable or the workflow is pinned to it.
• Use gpt-5.4-mini for lighter read-heavy scans, docs checks, inventories, and supporting workers.
• Use gpt-5.3-codex-spark only for low-latency, low-token, text-only triage where depth is not required.

Only set model or reasoning_effort directly when the user asks or the current tool schema supports that override and it is necessary. Include a one-line reason in the spawn prompt when overriding.

Effort Routing

Use medium as the default for most agents.

• Use high when an agent must trace complex logic, check assumptions, handle edge cases, investigate security-sensitive code, or resolve conflicting evidence.
• Use low only for straightforward lookup, inventory, or deterministic narrow checks.
• Use xhigh rarely, only for unusually hard bounded reasoning where the selected model supports it.

Before increasing effort, tighten:

• task statement
• output contract
• verification requirements

Fork And Context Policy

Use the current spawn_agent schema exactly.

Runtime compatibility matrix:

| Surface | Typical fields | Safe custom-role posture | | --- | --- | --- | | legacy tool | agent_type, model, reasoning_effort, fork_context | Keep prompt self-contained. Avoid combining full fork_context with role/model overrides if rejected. | | multi-agent v2 | agent_type, model, reasoning_effort, task_name, fork_turns | Set stable task_name; use fork_turns: "none" for custom role/model/effort overrides unless inherited history is required. | | custom agent file | standalone TOML role under ~/.codex/agents or .codex/agents | Prefer omitting per-call model/effort when the role file pins them. |

If the schema exposes fork_turns and task_name:

• Always provide a stable snake_case task_name.
• For custom agents, built-in agent_type, or direct model/reasoning overrides, set fork_turns: "none" unless the user explicitly requests inherited history. Current Codex multi-agent v2 rejects full-history forks with role, model, or reasoning overrides.
• Use fork_turns: "all" only when the child must inherit full parent context and no role/model/reasoning override is required.
• Use a positive integer string for partial history when a small amount of recent context is enough.

If the schema exposes legacy fork_context:

• Do not combine full-context fork behavior with explicit role/model/reasoning overrides if the tool reports that combination is unsupported.
• Prefer fresh, bounded prompts with the required context embedded.

Escalation Rules

Escalate only specific subagents that underfit.

Escalation order:

1. tighten scope + output contract
2. tighten verification requirements
3. raise effort on only that subagent if needed
4. switch only that subagent to a stronger model when available

Mandatory Spawn Contract

Every spawned subagent prompt must explicitly specify:

1. narrow task or question
2. allowed scope or surfaces
3. whether the agent is read-only or may edit
4. strict wait expectation
5. exact return format

Spawn prompt shape:

Task: one bounded task or question
Scope: paths, modules, docs, APIs, or explicit ownership
Mode: read-only, or may edit named files only
Wait: parent will wait for all spawned agents before substantive next work
Role: selected custom or built-in agent role
Model: inherited, custom-agent pinned, or explicit override with reason
Reasoning: inherited, custom-agent pinned, or explicit override with reason
Return format:
- Status
- Evidence or role-specific source headings
- Files inspected/changed, queries run, or sources hydrated
- Commands run or provider calls
- Findings or claims with confidence and source IDs
- Risks/blockers

When a custom role template provides a narrower return contract, use the template-specific headings emitted by the planner.

For edit-capable workers, also say:

• You are not alone in the codebase.
• Do not revert edits made by others.
• Adjust your implementation to accommodate concurrent changes.

Return Contract

Require concise, evidence-first output:

• key finding or result
• file paths + symbols touched or inspected
• commands or checks run, if any
• recommended next action
• unresolved questions or risks

No vague summaries without evidence.

Prefer:

• file refs over narration
• symbol refs over generic descriptions
• concrete command evidence over assertions

Verification Rules

For proposed changes, require one of:

• tests or checks run
• concrete command-level verification plan when execution is not appropriate

Subagent proposes edits without tests: require exact checks to run next.

Wait Timeout Rules

Use long bounded waits for the full batch rather than short polling loops. If a wait times out:

1. make one status or follow-up attempt for the running agents
2. wait once more with a bounded timeout
3. synthesize completed results and clearly mark unresolved agents, or close stuck agents if their output is no longer useful

Do not forget open subagents. Final output must account for every spawned subagent as completed, timed out, closed, or failed.

Synthesis Rules

Before any substantive next work or final answer:

1. wait for all requested subagents
2. merge overlapping findings
3. drop duplicate observations
4. surface conflicts explicitly
5. resolve disagreements in main-agent synthesis
6. highest-signal evidence first

When findings conflict, produce a conflict ledger with:

• conflicting claim
• evidence each side
• resolution or remaining uncertainty

Forward-Testing

Validating this skill requires at least one probe forcing real delegation, not only a refusal path.

Good probe:

• explicitly 2 read-only subagents
• disjoint bounded questions
• strict wait-for-all synthesis
• each spawn includes full mandatory spawn contract

Planning-only smoke:

python3 skills/subspawn/scripts/subspawn_plan.py validate-roles
python3 skills/subspawn/scripts/subspawn_plan.py plan \
  --preset review \
  --task "Review this PR for correctness and test gaps" \
  --scope "current PR diff only"

Failure Modes

Common failure modes + fixes:

• Overscoped subtask: shrink task + allowed surface.
• Weak output: restate return contract + evidence requirements.
• Parent overlaps work: stop, wait for the batch, then synthesize.
• Parent forgot a subagent: wait or close it, then account for it in synthesis.
• Role/model override rejected: retry with fresh context or compatible fork fields for the active tool schema.
• Lightweight model underfits: tighten once, then escalate only that subagent.
• Too many agents: collapse to 1–3, synthesis local.
• Edit collisions: read-only discovery or disjoint write surfaces.