From teamwork
Event-driven coordination for teamwork orchestrators. Replaces polling-based monitoring loop with TeammateIdle and TaskCompleted hooks.
How this skill is triggered — by the user, by Claude, or both
Slash command
/teamwork:event-coordinationThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill provides the event-driven coordination model for teamwork v3 orchestrators. It replaces the v2 polling-based monitoring loop with native Claude Code hooks.
This skill provides the event-driven coordination model for teamwork v3 orchestrators. It replaces the v2 polling-based monitoring loop with native Claude Code hooks.
Claude Code provides two lifecycle hooks that enable event-driven orchestration:
| Hook | Trigger | Purpose |
|---|---|---|
| TaskCompleted | A task's status changes to completed | Track project progress, detect completion |
| TeammateIdle | A teammate finishes its current work | Detect available workers for task assignment |
Event occurs (e.g., task completed)
|
v
Claude Code fires hook
|
v
Plugin hook script runs (project-progress.js or teammate-idle.js)
|
v
Hook script outputs context information to stdout
|
v
Context is injected into the orchestrator's conversation
|
v
Orchestrator takes action based on context
Hooks do NOT take actions directly. They provide context that enables the orchestrator to make informed decisions.
When any task is marked as completed, project-progress.js runs and outputs the current project progress:
Progress: 4/7 completed, 2 in progress, 1 pending.
Or when all tasks are done:
All 7 tasks completed. Ready for final verification.
The orchestrator receives this context and decides:
# When hook reports all tasks completed
Task(
subagent_type="teamwork:final-verifier",
team_name="<team>",
name="verifier",
prompt="Verify project completion: run full build, full test suite, check all evidence..."
)
When a teammate becomes idle, teammate-idle.js runs and reports whether unassigned tasks are available:
worker-backend idle. 3 unassigned tasks available.
Or when no work remains:
worker-backend idle. No tasks available.
The orchestrator receives this context and decides:
# When no more tasks for an idle worker
SendMessage(
type="shutdown_request",
recipient="worker-backend",
content="All tasks assigned or completed. You may stop."
)
1. Orchestrator creates tasks and spawns workers
|
v
2. Workers claim tasks (TaskUpdate: owner, status=in_progress)
|
v
3. Workers implement and collect evidence
|
v
4. Worker completes task (TaskUpdate: status=completed)
|
v
5. TaskCompleted hook fires
|-- Hook outputs: "Progress: 4/7 completed..."
|-- Orchestrator reads progress
|
v
6. Worker becomes idle
|
v
7. TeammateIdle hook fires
|-- Hook outputs: "worker-backend idle. 2 unassigned tasks."
|-- Worker picks up next task (return to step 2)
|
v
8. When all tasks completed:
|-- TaskCompleted hook: "All 7 tasks completed."
|-- Orchestrator spawns final-verifier
|
v
9. Final verification
|-- Verifier checks build, tests, evidence
|-- SendMessage to orchestrator with results
|
v
10. Orchestrator handles result
|-- PASS: Shutdown workers, TeamDelete, report success
|-- FAIL: Create fix tasks, workers pick them up (return to step 2)
| Aspect | v2 (Polling) | v3 (Event-Driven) |
|---|---|---|
| Mechanism | mailbox-poll.js with timeout | Native hooks (TaskCompleted, TeammateIdle) |
| Response time | Up to timeout interval (30s default) | Immediate on event |
| Infrastructure | Mailbox scripts, inbox files, polling loop | Zero custom infrastructure |
| Wave management | Wave status tracking, wave-calculate.js | Native addBlockedBy dependency resolution |
| Code required | ~600 lines (monitoring-loop skill + scripts) | ~50 lines (2 hook scripts) |
| Orchestrator role | Active polling in a loop | Reactive to hook context |
| Failure detection | Manual stale task checking | Hook reports on every state change |
addBlockedBy. Tasks unblock automatically when their dependencies complete.SendMessage (native, auto-delivered). No inbox files or poll scripts.Hooks are configured in hooks/hooks.json:
{
"hooks": {
"TaskCompleted": [{
"matcher": "*",
"hooks": [{
"type": "command",
"command": "bun ${CLAUDE_PLUGIN_ROOT}/src/hooks/project-progress.js"
}]
}],
"TeammateIdle": [{
"matcher": "*",
"hooks": [{
"type": "command",
"command": "bun ${CLAUDE_PLUGIN_ROOT}/src/hooks/teammate-idle.js"
}]
}]
}
}
Hook scripts:
addBlockedBy handles task ordering. Do not manually track which tasks are unblocked.addBlockedBy dependencies and let workers pick them up naturallyTeamDelete()TaskList() and claim them. The orchestrator does not assign tasks directly.SendMessage to the orchestrator summarizing the result.shutdown_request message, finish current work and stop.| Scenario | Detection | Response |
|---|---|---|
| Hook script fails | stderr output, non-zero exit | Claude Code ignores output, orchestrator continues |
| Task stuck in_progress | TeammateIdle with no progress | Orchestrator checks stale tasks, releases if needed |
| All workers idle, tasks remain | Multiple TeammateIdle events | Orchestrator checks for blocked tasks, creates unblock tasks if needed |
| Final verification fails | Verifier sends failure message | Orchestrator creates fix tasks, workers resume |
| Hook fires but orchestrator missed it | Duplicate events possible | Idempotent orchestrator actions (check before acting) |
npx claudepluginhub mnthe/hardworker-marketplace --plugin teamworkUse when a task benefits from multiple Claude instances collaborating with peer-to-peer messaging - parallel research, multi-module features, cross-layer changes, or competing hypothesis debugging. Not for simple independent tasks (use parallel-execution) or sequential tasks (use delegated-execution).
Coordinates multiple Claude Code instances as agent teams for workflows needing inter-agent communication. Covers TeamCreate, SendMessage types, task coordination, hooks, and orchestration patterns.
Orchestrates parallel agent teams for coordinating 2+ workers, running SAM task waves, relaying discoveries between waves, handling blockers, and synthesizing results. Supports SAM structured and ad-hoc dispatch.