feat(plugin): add agent-teams-pipeline plugin

[0xarkstar]

Agent Teams Pipeline Plugin

Lifecycle management plugin for Claude Code's Agent Teams feature — 7 hooks, a cleanup script, and a multi-phase pipeline orchestration skill that address common Agent Teams pain points.

Problem

Agent Teams currently lacks lifecycle management, leading to:

• Orphaned agents that continue running after their team is deleted ([BUG] orphaned processes from subagents crashing computer #18405, Orphaned subagent process leaks memory when parent terminal session terminated #20369, Claude Code agents don't clean up spawned subprocesses #25180)
• Leaked tmux panes not cleaned up on shutdown (Agent team iTerm2 panes not closed on teammate shutdown #24385)
• Runaway agent spawning with no limit on concurrent teammates ([BUG] Agent Teams: Catastrophic agent lifecycle failures, duplicate spawning, and mailbox polling waste #25131)
• Context exhaustion freeze when context exceeds 60% ([MODEL] Opus 4.6 continuously stuck in explore and thinking loops (Claude Code) #24585)
• Post-pipeline thinking loops when continuing work after completion (Agent Teams: Idle teammate spawn burns ~4 turns of tokens before any productive work #24414)

Solution

7 hooks across 4 event types:

Hook	Event	What It Does
check-context-preemptive.sh	PreToolUse	Blocks ExitPlanMode/TeamCreate at 55%+ context
detect-pipeline-complete.sh	Stop	Detects "Pipeline Complete", sets flag, warns user
block-after-pipeline.sh	PreToolUse	Blocks heavy tools after Pipeline Complete
check-idle-reason.sh	TeammateIdle	Orphan detection + deliverable validation + auto-pane cleanup
check-team-limit.js	PreToolUse	Max 3 concurrent active teammates
verify-phase-output.sh	TaskCompleted	Validates pipeline deliverables (file existence, min size, PASS/FAIL)
check-context-stop.sh	Stop	Suggests fresh session at 75%+ context with retry guard

Plus:

• cleanup-team-panes.sh — Manual tmux pane cleanup ([team], --all, --orphans)
• Pipeline Orchestration Skill — Multi-phase protocol (P-1 Research → P4 Docs) with blocking shutdown, file ownership, failure recovery
• /agent-teams-pipeline:cleanup-team-panes slash command

Testing

All hooks are production-tested across 50+ pipeline runs with 3-agent teams on macOS. Key thresholds (55%/75% context, max 3 teammates, 200-char min deliverables) are empirically tuned from real failure incidents.

Platform Support

• macOS: Full support (mkdir atomic locking, stat -f, md5)
• Linux: Full support (stat -c, md5sum)

Requirements

• jq (JSON parsing in hooks)
• tmux (pane cleanup — optional if not using tmux-based spawning)
• Node.js (for check-team-limit.js)

Files

plugins/agent-teams-pipeline/
├── .claude-plugin/plugin.json
├── hooks/
│   ├── hooks.json
│   ├── check-context-preemptive.sh
│   ├── detect-pipeline-complete.sh
│   ├── block-after-pipeline.sh
│   ├── check-idle-reason.sh
│   ├── check-team-limit.js
│   ├── verify-phase-output.sh
│   └── check-context-stop.sh
├── scripts/cleanup-team-panes.sh
├── commands/cleanup-team-panes.md
├── skills/pipeline-orchestration/SKILL.md
├── README.md
└── LICENSE (MIT)

Also updates plugins/README.md table with the new plugin entry.