subctl-team-protocol

name	subctl-team-protocol
description	The wire protocol every subctl-spawned worker speaks with its team lead. Use this skill when you are running inside a subctl-managed team — i.e. `SUBCTL_AGENT_ROLE=worker` is set, or you were spawned by `subctl orch spawn` / `subctl team spawn` / a parent Claude Code instance using `TeamCreate` + `Agent` with `team_name`. It describes how to receive work, report progress, request approvals, hand off, and shut down cleanly. Lead agents (orchestrators / team-leads) also load this skill so the two sides of every message agree on shape.
scope	dev-team
loaded_by_default	[]
created_at	2026-05-10
created_by	operator

Subctl Team Protocol

This skill defines the message contract between a team lead (orchestrator Claude Code session) and its workers (sub-agents the lead spawned via TeamCreate + Agent with team_name). Both sides load this skill so the shapes never drift.

If you are the worker, your plain text output is not visible to the team lead — to communicate, you MUST use the SendMessage tool. The lead's messages to you are delivered automatically; you do not need to poll an inbox.

---

1. Roles

Role	Set by	Identifier
Team lead	subctl orch spawn (no --worker flag), or the operator's own Claude Code session running orchestrator-mode	SUBCTL_AGENT_ROLE=lead (or unset)
Worker	subctl orch spawn --worker, or any agent created by TeamCreate + Agent with team_name	SUBCTL_AGENT_ROLE=worker
Operator	The human at the keyboard	—

The lead never writes source code. Workers do. The operator is the tiebreaker on judgment calls.

Refer to teammates by name, never by UUID. The names are set by the parent at spawn time and surface in the iTerm2 pane title.

---

2. Sending messages — SendMessage

{
  "to": "<teammate-name>",            // e.g. "team-lead", "researcher", "impl-1"
  "summary": "5-10 word preview",     // required when message is a string
  "message": "<plain text or structured JSON>"
}

Rules:

• Worker → lead uses to: "team-lead" unless the lead has a different name.
• Lead → worker uses the worker's name from the original Agent call.
• Worker → worker ("peer DM") is allowed for tight coordination on non-overlapping scopes — e.g. one worker pinging another to release a file lock. Use sparingly; the lead should usually mediate.
• Plain-text status narration is fine. Structured JSON is reserved for the protocol messages below.
• Do not quote the original message when relaying — it's already rendered.

---

3. Protocol messages (structured JSON)

When the message field is a JSON object with a type, both sides interpret it as a protocol message. Echo the request_id in your response so the sender can correlate.

3.1 shutdown_request / shutdown_response

The lead asks a worker to terminate cleanly when its deliverable has landed.

// Lead → worker
{
  "to": "impl-1",
  "message": {
    "type": "shutdown_request",
    "request_id": "shutdown-2026-05-13-001",
    "reason": "Branch pushed, deliverable verified, freeing the pane."
  }
}

// Worker → lead
{
  "to": "team-lead",
  "message": {
    "type": "shutdown_response",
    "request_id": "shutdown-2026-05-13-001",
    "approve": true
  }
}

Approving terminates the worker process. The lead is responsible for sending shutdown as soon as a deliverable is committed — leaving idle workers parked wastes RAM and tmux panes (operator preference, captured in auto-memory).

Workers MUST NOT originate shutdown_request unless explicitly asked.

3.2 plan_approval_request / plan_approval_response

A worker asks the operator (via the lead) for go/no-go on a non-trivial plan before executing. The lead forwards to the master daemon's plan-approval queue; the operator decides from the dashboard Plans tab or Telegram /plans. See docs/master.md §2.5 for the queue mechanics.

// Worker → lead
{
  "to": "team-lead",
  "message": {
    "type": "plan_approval_request",
    "request_id": "plan-2026-05-13-007",
    "plan_summary": "Refactor profile loader to new schema",
    "plan_body": "1. Move config files\n2. Migrate keys\n3. Add tests\n4. Ship behind flag"
  }
}

// Lead → worker (after operator decides)
{
  "to": "impl-1",
  "message": {
    "type": "plan_approval_response",
    "request_id": "plan-2026-05-13-007",
    "approve": false,
    "feedback": "Skip step 3 — tests already cover this path. Otherwise proceed."
  }
}

approve: false sends the worker back to revise; do not silently proceed. Pending requests auto-reject after 60 minutes with feedback: "auto-expired".

3.3 No status JSON over SendMessage

Workers MUST NOT send structured status JSON ({"type": "progress", ...}) over SendMessage — use TaskUpdate on the assigned task instead. The lead sees task state changes automatically.

---

4. Task lifecycle — TaskCreate / TaskUpdate

The lead creates tasks; workers update them.

TaskCreate({ subject, description })          // lead creates pending task
TaskUpdate({ id, status: "in_progress" })     // worker claims it on start
TaskUpdate({ id, status: "completed" })       // worker reports done
TaskUpdate({ id, status: "blocked",           // worker hits a blocker
             metadata: { blocker: "..." } })

Status transitions:

• pending → in_progress — worker starts. Set this BEFORE doing work, not after.
• in_progress → completed — work landed and verified. Only the worker sets this; the lead's verification pass may revert it.
• in_progress → blocked — surfaces an obstacle. Workers SHOULD attach a short blocker description; this is what the lead reads first.
• blocked → in_progress — worker resumes after the lead unblocks.

Do not create duplicate tasks. Call TaskList first if unsure.

---

5. Idle state

A worker is idle when:

• Its assigned task is completed AND the lead has acknowledged, OR
• It is waiting on a plan_approval_response from the operator, OR
• It explicitly reported "ready for next task" via SendMessage.

While idle, do not consume tokens looking for work. Do not run probes. Do not "check in" repeatedly. Wait for the next message from the lead. If the lead sends shutdown_request, approve it.

Leads: do not park workers idle "in case we need them later." Shut them down after a deliverable lands and re-spawn on demand. (Operator preference, auto-memory 2026-05-12.)

---

6. Concrete dispatch examples

6.1 Lead spawning a worker

// In the lead's session:
TeamCreate({ name: "v2.7.33-skills" })
Agent({
  description: "Build skill bundles + agent defs baseline",
  prompt: "<full briefing — see worker-prompt-format below>",
  team_name: "v2.7.33-skills",
  name: "skills-impl"
})

Plain Agent calls (no team_name) run as hidden background sub-processes and do NOT appear in iTerm2 panes — forbidden for code-writing work.

6.2 Worker reporting completion

SendMessage({
  to: "team-lead",
  summary: "skills shipped — branch pushed",
  message: "Branch v2.7.33-skills pushed at SHA abc1234. Worktree at " +
           "../subctl-v2.7.33-skills. Shipped 6 skills + 5 agent defs + " +
           "README. CHANGELOG entry added, VERSION bumped. Ready for shutdown."
})

---

7. Worker prompt format (lead-side)

Every worker prompt the lead writes MUST include:

• GOAL — one sentence
• CONTEXT — file paths, prior decisions, constraints
• DELIVERABLE — exact output expected (files, diffs, branch name, SHA)
• DONE WHEN — verifiable acceptance criteria
• REPORT BACK — what to SendMessage to team-lead when finished
• CONSTRAINTS — files the worker may NOT touch (scopes of other parallel workers, to prevent merge conflicts)

If your prompt cannot fill in CONSTRAINTS, you are probably dispatching the wrong slice — re-decompose.

---

8. Verification — leads only

When a worker reports "done," the lead verifies before marking the task complete. The verification surface is whatever proves the work landed:

• ls / cat the files the worker claims to have created
• git log --oneline -5 on the worker's branch to confirm commits
• bun test or pnpm build to confirm no regression
• curl to confirm endpoints respond

Do not trust the worker's narrative. The worker reports intent; the filesystem reports reality.

---

9. Failure modes

Symptom	Likely cause	Fix
Worker doesn't appear in a pane	Agent called without team_name	Use TeamCreate + Agent with team_name
"Team does not exist" error	Old session cleaned up the team	TeamCreate it again
Worker stops responding	Hit auto-compact, idle, or shutdown	Check TaskGet and TaskOutput; if dead, re-spawn
Plan approval never returns	Operator AFK; auto-expires at 60min	Worker should accept the auto-reject and re-request when human is back
Worker writes outside its scope	Bad CONSTRAINTS in the prompt	Lead fixes the prompt; worker reverts

---

10. Related skills

• orchestrator-mode — the lead-side activation rules
• handoff-protocol — mid-task handoffs between workers
• spec-driven-dev — how workers read and execute against a written spec

References

• docs/master.md §2.5 — plan-approval queue mechanics (v2.7.29)
• components/master/plan-approvals.ts — server-side queue implementation
• providers/claude/teams.sh — sets SUBCTL_AGENT_ROLE=worker at spawn