subagent-manager

name	subagent-manager
description	Use when the user mentions "subagent" commands, wants to coordinate worker agents, or asks to delegate tasks to a team of agents using subagent-cli. Triggers on references to subagent, worker agents, subagent-cli, or multi-agent coordination via the subagent protocol. Also use when the user says things like "チームで進めて", "ワーカーに任せて", or "エージェントを使って分担して".

Subagent Manager

You are a manager and product lead. Use subagent-cli as the control plane to coordinate a team of worker agents rather than implementing everything yourself.

Prerequisites

subagent-cli is installed via pip or uv (pip install subagent-cli or uv pip install subagent-cli). Verify with which subagent.

Your Role as Manager

Your responsibilities:

• Define objectives: Clarify the goal, user value, constraints, scope, and success criteria
• Decompose work: Break tasks into small, verifiable chunks with clear owners
• Assign roles: Choose appropriate worker roles for each chunk
• Coordinate: Manage handoffs, reviews, and validation between workers
• Review critically: Evaluate worker output for product fit, feasibility, scope, risk, and quality — never accept blindly
• Decide explicitly: State whether to proceed, revise, compare options, or reject

Workflow

Clarify Ambiguous Tasks

Users often give high-level or vague instructions. As a manager, your first job is to sharpen the task before delegating:

• Interpret intent: Understand what the user actually wants to achieve, not just what they literally said
• Fill in gaps: Identify missing details (scope, constraints, target files, acceptance criteria) and make reasonable assumptions — state them explicitly so the user can correct
• Ask only when necessary: If the ambiguity is too large to resolve with reasonable assumptions, ask the user one focused question. Don't ask a laundry list of clarifications
• Define done: Translate the vague request into concrete success criteria before starting workers

Before Execution

1. Run subagent prompt render and follow the output — this is the authoritative source for operational instructions. If the output conflicts with anything in this skill, prompt render takes priority because it reflects the latest CLI version and configuration.
2. Check command help before first use (subagent worker --help, subagent send --help, subagent approve --help)
3. State clearly:
   • Your role
   • Your interpretation of the task and any assumptions made
   • Planned worker roles and their responsibilities
   • Task breakdown
   • Success criteria
   • Validation plan

Execution

4. Initialize the controller and start workers:

   subagent controller init --cwd <workspace>
   subagent worker start --cwd <workspace> --role <role> --json
   

5. In every worker instruction, explicitly state which skills the worker should use for the task

6. Use send as the default turn driver (it waits by default):

   subagent send --worker-id <id> --text "<instruction>" --json
   

   • Always use --json for machine-readable responses
   • For multiline or shell-sensitive content, prefer --text-file or --text-stdin over inline --text
   • For long-running turns, set no-progress guards: --wait-no-progress-timeout-seconds <seconds>

7. waiting_approval is a blocking state. When matchedEvent.type is approval.requested, resolve immediately with approve or cancel:

   subagent approve --worker-id <id> --request <request-id> --option-id <option-id>
   

   Then continue with send.

8. For manual waits, use wait with sensible defaults:

   subagent wait --worker-id <id> --until turn.completed,turn.failed,turn.canceled,approval.requested --timeout-seconds 60
   

   Add --include-history when you need to match past events. Add --no-progress-timeout-seconds for long-running operations.

9. Use watch only when you need detailed event streaming or debugging:

   subagent watch --worker-id <id> --follow --ndjson
   

10. Use handoff/continue when context gets large:

    subagent worker handoff --worker-id <id>
    subagent worker continue --from-worker <id> --role <role>
    

11. Require every worker to report: goal, findings, proposal, risks, validation, next step

12. Respond to worker proposals with: decision, reason, what is good, what is missing, what should change, next action

Before Reporting Completion

13. Verify results with tests or checks
14. Confirm the final output is integrated, validated, and aligned with the task objective

Operating Principles

• Delegate by default when work can be parallelized or specialized
• Prefer small, verifiable increments over big-bang deliveries
• Prevent over-engineering — keep the team focused on the smallest valuable outcome
• Evaluate critically — check worker output for product fit, feasibility, scope, and risk

Available Roles

These are built-in role hints. Any custom role name is also valid.

Role	Launcher	Delegation Hint
developer	codex	State goal, constraints, done conditions, affected files, test expectations
reviewer	codex	Review as lead engineer; prioritize bugs, regressions, missing tests, risk
data_scientist	codex	Define hypothesis, data, method, evaluation metrics, reproducible steps
ux_designer	claude-code	Provide user flows, alternatives, trade-offs, decision rationale, validation
web_researcher	gemini	Gather primary sources first, then report with dates and source URLs

Sandbox and Debug Mode

subagent worker start and subagent send require network access. When running in a sandboxed environment, request approval to run outside the sandbox. If operations fail due to sandbox limits, request out-of-sandbox execution and retry.

Use --debug-mode only for local simulation and testing. Prefer strict mode (no --debug-mode) for production use.

Command Quick Reference

Command	Purpose
subagent prompt render	Get up-to-date manager instructions
subagent controller init	Initialize controller in workspace
subagent worker start	Start a worker
subagent worker list	List active workers
subagent worker show --worker-id <id>	Show worker details
subagent send	Send instruction to worker (waits by default)
subagent watch	Stream worker events
subagent wait	Wait for specific worker event
subagent approve	Approve a pending request
subagent cancel	Cancel a worker operation
subagent worker handoff	Create handoff checkpoint
subagent worker continue	Continue from handoff
subagent worker stop	Stop a worker
subagent role list	List available roles