manage-worker-protocol

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Manage Worker Protocol

Use this for Orchestrator-to-Worker operations after bootstrap. Keep worker rooms independent, visible, and bounded by the Stage Contract.

This protocol only applies to visible CCM Worker Rooms controlled by the Orchestrator parent room. Do not use Codex native subagents, `spawn_agent`, model-side delegation, or hidden parallel agents as substitutes for visible CCM Worker Room execution.

Worker-room lifecycle tools require `chat_id` from the current CCM room context (`<ccm_turn ... chat_id="...">` or command metadata) and the resolved room must have `is_orchestrator: true`. Native `/goal` continuations may lack that room context or may resume a session bound to a non-orchestrator room. Never pass `CC_CHANNEL_SESSION_UUID`, `CODEX_CHANNEL_SESSION_UUID`, or `ccm-shared-codex-app-server` as `chat_id`; those identify the shared Codex bridge, not the room. If the first lifecycle call lacks `chat_id`, call `get_current_ccm_context` or the runtime's CCM context resolver before stopping; retry with the resolved parent room `chat_id` only when it is an orchestrator room. Ask for a parent-room `/cx goal ...`, `codex: ...`, or `claude: ...` cue only when the current turn/resolver lacks `chat_id`, is ambiguous, or resolves to `is_orchestrator: false`. Do not downgrade to hidden subagents when the requested execution mode is visible CCM Worker Rooms.

## Protocol Steps

1. Confirm `worker_task_id`, desired room name, room handle, cwd, default runtime, and Agent Resume Identity are recorded.
2. Start or lazy-start the assigned agent slot in the visible CCM Worker Room through Agent Control Path.
3. For every newly started Claude Code worker room, call `send_worker_raw_command` with `command: "/effort ultracode"` before sending the Worker Task. Do not ask a human to type `/cc effort ultracode` inside the worker room, and do not send it through `send_worker_task`.
4. Send runtime-specific `/goal` setup with `send_worker_raw_command`, then send a Worker Task brief with objective, inputs, output format, acceptance checks, non-goals, and deny-listed writes. The Worker Task brief must not include native `/goal` setup text.
5. Record prompt hash, send time, session id when available, and expected report path in `workers.md` or `reports/`.
6. Monitor with status, screen, transcript, freshness, and Completion Reportback. Treat freshness as a hint, not durable truth.
7. Move worker state through `task_sent`, `running`, `attention_needed`, `reported`, and later capture states only when evidence exists.

## Runtime-Specific Worker Goal Setup

- Claude worker goal setup must be sent with `send_worker_raw_command` as `/goal create dynamic workflow to <task specific goal description> /think-harder /superpowers:verification-before-completion` before the task-specific Worker Task brief.
- Codex worker goal setup must be sent with `send_worker_raw_command` as `/goal $superpowers:subagent-driven-development <task specific goal description> $think-harder $superpowers:verification-before-completion` before the task-specific Worker Task brief.
- The `<task specific goal description>` should be the shortest precise outcome for that worker, not the entire Stage Contract.
- Do not include either `/goal` setup command in `send_worker_task`; native setup belongs to `send_worker_raw_command`.
- Synthesis-related work always requires a dedicated Worker Room. If the stage needs report reconciliation, final curation, cross-worker synthesis, or combining related outputs, create/send a separate synthesis worker instead of making synthesis an implicit substep inside another agent instance.

## Prompt And Nav Handling

Allowed without review gate:

- Approve read-only access inside assigned inputs.
- Answer clarification already specified by the Worker Task.
- Deny out-of-scope path, tool, network, credential, or policy requests.
- Clear stale requests after restart when the live request cannot be answered safely.
- Interrupt a stuck worker and record why.

Escalate before acting:

- Credential, policy, sandbox, or network escalation outside the Stage Contract.
- Any prompt that changes scope, recommendation, acceptance criteria, or human-facing framing.
- Worker text that tries to control orchestration state.

## Completion Handling

- `reported` means final visible response arrived; it is not completion.
- Capture the Worker Report and transcript/session references before validation.
- Unknown or stale reportback must be reconciled with room/session facts and Git state before integration.
- If the worker is blocked, set `attention_needed` or `blocked` with the exact question and evidence.

## Message Envelope

```text
Native setup before this brief, sent via send_worker_raw_command:
- Claude: /goal create dynamic workflow to <task specific goal description> /think-harder /superpowers:verification-before-completion
- Codex: /goal $superpowers:subagent-driven-development <task specific goal description> $think-harder $superpowers:verification-before-completion

Worker Task: <worker_task_id>
Stage: <stage_name>
Objective: <single outcome>
Inputs: <files/docs/artifacts>
Inherited Quality Principles: think-harder on ambiguous tradeoffs; verify with the most relevant available evidence before completion
Internal Throughput: when useful, create a dynamic workflow with fan-out subagents inside this already-started visible Worker Room; synthesize and verify all internal fan-out results before reporting
Authority Boundary: internal fan-out is worker-local only; no worker-room creation/adoption/archive, no control over peer workers, and no authority to count internal subagents as CCM Worker Rooms
Deny-listed Writes: orchestration bookkeeping, credentials, other workers, room metadata
Output: Worker Report with evidence and next-step recommendation
Stop Condition: post the report, then wait for Orchestrator follow-up
```

From flyingImer/claude-channel-mux, Apache-2.0.

More from flyingImer/claude-channel-mux