cvg-spawn

name	cvg-spawn
version	1.0.0
description	Wrap spawned-worker briefs (subagent or background agent) with auto-register + heartbeat boilerplate so they stay visible in the Convergio daemon. Use this when invoking the Task tool for code-mutating work in this repo.
allowed-tools	["Bash"]
triggers	["cvg-spawn","spawn subagent"]
preamble-tier	4

/cvg-spawn — wrap a spawned worker brief with Convergio auto-register

Why this skill exists

Claude Code spawned helpers (subagents and background agents launched via the parent's Task tool) run in a different harness from the top-level session. The SessionStart hook in .claude/settings.json therefore does not fire for them — they would silently disappear from the daemon's agent registry, which means:

• cvg agent list cannot see them.
• The TUI dashboard cannot colour-code them.
• cvg coherence agents cannot detect zombies.
• Audit cannot prove who did what.

/cvg-spawn solves this by emitting the canonical 3-step lifecycle wrapper (register → work → retire) plus a heartbeat reminder. The parent agent prepends the rendered block to every spawned-worker brief that contains code-mutating work in this repository.

When to invoke

The parent (top-level) agent should invoke /cvg-spawn immediately before calling the Task tool, then paste the rendered block into the head of the spawned worker's brief.

You do not need to invoke /cvg-spawn for read-only helpers (pure search, single-shot question answering). Invoke it whenever the spawned worker will edit files, run tests, push branches, or open PRs.

What this skill renders

The skill produces three deterministic outputs (and is safe to re-run: agent registration is an upsert):

1. A unique subagent_id of the form subagent-${TASK_DESC_SLUG}-${HEX8} where:
   • TASK_DESC_SLUG = first 24 chars of the task description, lower-cased, spaces replaced with -, non-alnum stripped.
   • HEX8 = 8 random hex chars (openssl rand -hex 4).
2. A bash block to prepend to the spawned-worker brief:
   • line 1: SUBAGENT_ID="subagent-<slug>-<hex8>" (or subagent-bg-... in background mode)
   • line 2: CVG_SPAWN_MODE="subagent"|"background"
   • line 3: budget pre-check — ./scripts/check-context-budget.sh refuses only on hard caps (exit 1). Soft warnings (exit 2) are advisory.
   • line 4: register POST to /v1/agent-registry/agents with kind=subagent and metadata.spawn_mode.
   • line 5: heartbeat POST to /v1/agent-registry/agents/${SUBAGENT_ID}/heartbeat.
   • line 6: # heartbeat every 5 min (subagent) or # heartbeat every 60 s (background)
   • line 7: budget mid-flight reminder — re-run check-context-budget.sh every ~200 LOC so the worker does not push past cap on push.
   • line 8: # ... do work ...
   • line 9: retire POST to /v1/agent-registry/agents/${SUBAGENT_ID}/retire.
3. A one-line confirmation summary the parent prints back to the user before launching the helper: Subagent <id> will be registered as kind=subagent (mode=...).

Execution

# default (subagent)
bash "$(dirname "$0")/cvg-spawn.sh" <task-description>

# background helper spawned via Task tool background mode
bash "$(dirname "$0")/cvg-spawn.sh" --mode background <task-description>

<task-description> is the short human-readable label the parent will pass into the Task tool's description field. The skill slug-ifies it to seed the subagent id.

If CONVERGIO_SPAWN_HEX is set (used by the integration smoke test), the skill uses it verbatim instead of generating fresh random bytes — that is the only deterministic seam.

Output contract

Stream	Content
stdout	The wrapper bash block (no leading blank line) followed by the one-line summary on its own line
stderr	Empty on success; one-line error on bad usage
exit	0 on success, 2 on missing argument or invalid --mode

The skill performs no network I/O. It only renders text. The register / heartbeat / retire calls fire when the spawned worker actually runs the rendered block.

Why kind=subagent

The agent registry kind field is a permissive lower-case string (see convergio-durability::store::agent_validation). Existing top-level sessions register as kind=claude or kind=copilot. Subagents register as kind=subagent so:

• The TUI dashboard can render them with reduced visual weight (smaller indent, gray accent).
• cvg coherence agents can decide whether to count them as PR-author candidates (a subagent normally is not the PR author — its parent is).
• Audit rows distinguish "I, the human-driven session, did this" from "I, a tool-spawned helper, did this".

The list of recognised kinds lives in docs/multi-agent-operating-model.md under "Subagent lifecycle".

Relation to /cvg-attach

/cvg-attach registers the top-level Claude Code session at session start (the SessionStart hook calls it). /cvg-spawn generates a wrapper for spawned helpers (subagents and background agents) launched mid-session via the Task tool. The two skills do not overlap — they cover the distinct harnesses in which Claude Code can run.