{"id":45951699,"url":"https://github.com/ducdmdev/agent-team-plugin","last_synced_at":"2026-03-09T06:02:16.912Z","repository":{"id":340312501,"uuid":"1165477457","full_name":"ducdmdev/agent-team-plugin","owner":"ducdmdev","description":"Orchestrate parallel AI teammates in Claude Code — with hook enforcement, workspace tracking, and structured coordination across 5 phases","archived":false,"fork":false,"pushed_at":"2026-03-06T08:27:11.000Z","size":792,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-06T12:48:28.335Z","etag":null,"topics":["agent-orchestration","agent-team","ai-agents","automation","claude","claude-code","claude-code-plugin","claude-plugin","developer-tools","multi-agent","orchestration","parallel-execution","plugin","team-coordination"],"latest_commit_sha":null,"homepage":"https://github.com/ducdmdev/agent-team-plugin#readme","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ducdmdev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-24T07:55:29.000Z","updated_at":"2026-03-06T08:27:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ducdmdev/agent-team-plugin","commit_stats":null,"previous_names":["ducdmdev/agent-team-plugin"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/ducdmdev/agent-team-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ducdmdev%2Fagent-team-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ducdmdev%2Fagent-team-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ducdmdev%2Fagent-team-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ducdmdev%2Fagent-team-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ducdmdev","download_url":"https://codeload.github.com/ducdmdev/agent-team-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ducdmdev%2Fagent-team-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30284629,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T02:57:19.223Z","status":"ssl_error","status_checked_at":"2026-03-09T02:56:26.373Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-orchestration","agent-team","ai-agents","automation","claude","claude-code","claude-code-plugin","claude-plugin","developer-tools","multi-agent","orchestration","parallel-execution","plugin","team-coordination"],"created_at":"2026-02-28T12:47:02.608Z","updated_at":"2026-03-09T06:02:16.892Z","avatar_url":"https://github.com/ducdmdev.png","language":"Shell","readme":"# Agent Team\n\n\u003e Orchestrate parallel work via AI Agent Teams in Claude Code — with automated coordination, workspace tracking, and hook enforcement.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Claude Code Plugin](https://img.shields.io/badge/Claude_Code-Plugin-blueviolet)](https://github.com/ducdmdev/agent-team-plugin)\n\n## What It Does\n\nThis plugin adds an **Agent Team** skill to Claude Code that decomposes complex tasks into parallel work streams executed by multiple AI teammates.\n\n- A **team lead** coordinates but never writes code\n- **Teammates** (implementers, reviewers, researchers) work in parallel — each owning distinct files\n- **Hooks** enforce discipline: block premature completion, nudge idle teammates\n- A **persistent workspace** tracks progress, tasks, issues, decisions, and generates a final report\n\n## See It In Action\n\n![Agent Team Demo](demo.gif)\n\nHere's what happens when you say: *\"use agent team to refactor the auth module\"*\n\n```\nYou \u003e use agent team to refactor the auth module\n\nPhase 1 - Analyze\n  Identified 3 independent streams: token validation, session management, middleware\n  No file overlaps detected\n\nPhase 2 - Plan (you approve before anything starts)\n  Team type: implementation (auto-detected)\n  Proposed team:\n    auth-impl-1 (Implementer) — owns src/auth/token.ts, src/auth/validate.ts\n    auth-impl-2 (Implementer) — owns src/auth/session.ts, src/middleware/auth.ts\n    auth-reviewer (Reviewer)  — reviews all changes\n  Approve? [y/n]\n\nYou \u003e y\n\nPhase 3 - Create\n  Created team \"0306-refactor-auth\"\n  Initialized workspace at .agent-team/0306-refactor-auth/\n  Spawned 3 teammates in parallel\n\nPhase 4 - Coordinate\n  auth-impl-1:  STARTING #1: Refactoring token validation, touching src/auth/token.ts\n  auth-impl-2:  STARTING #2: Extracting session logic to src/auth/session.ts\n  auth-impl-1:  COMPLETED #1: Token validation refactored, 3 files changed\n  auth-impl-2:  COMPLETED #2: Session management extracted, 2 files changed\n  auth-impl-1:  HANDOFF #3: New token interface ready for reviewer\n  auth-reviewer: STARTING #4: Reviewing all changes across both scopes\n  auth-reviewer: COMPLETED #4: 0 high, 2 medium, 1 low issues found\n\nPhase 5 - Synthesize\n  All tasks completed (4/4)\n  Completion gate: PASSED (build, tests, lint, integration)\n  Report: .agent-team/0306-refactor-auth/report.md\n  Team shut down. Total: 6 files changed, 0 open issues.\n```\n\nThe workspace persists at `.agent-team/0306-refactor-auth/` with the full audit trail: tasks, issues, decisions, and final report.\n\n## Prerequisites\n\n| Requirement | Details |\n|------------|---------|\n| Claude Code CLI | With plugin support |\n| Feature flag | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in shell env or `settings.json` |\n| `jq` | Required by hook scripts. Hooks skip gracefully if missing |\n| `git` | Optional — used for file change detection |\n\n## Installation\n\n### From Marketplace\n\nFirst, add the marketplace:\n\n```bash\nclaude plugin marketplace add ducdmdev/agent-team-plugin\n```\n\nThen install:\n\n```bash\nclaude plugin install agent-team\n```\n\n### Local Development\n\n```bash\nclaude --plugin-dir /path/to/agent-team-plugin\n```\n\n## Usage\n\nTrigger the skill with phrases like:\n\n```\n\u003e create a team to refactor the auth module\n\u003e work in parallel on the API endpoints and frontend components\n\u003e use agent team to build the new dashboard feature\n\u003e spawn teammates to review the PR from security, performance, and correctness angles\n```\n\nThe skill activates when your task has **2+ independent work streams**. If the task is better handled sequentially, the lead will tell you.\n\n### Archetype-Specific Commands\n\n| Command | When to Use | Example |\n|---------|------------|---------|\n| `/agent-implement` | Build, refactor, fix, migrate code | \"implement the new auth module in parallel\" |\n| `/agent-research` | Investigate, analyze, compare | \"research database options with a team\" |\n| `/agent-audit` | Review, assess, evaluate | \"audit security with parallel reviewers\" |\n| `/agent-plan` | Design, architect, produce specs | \"design the API with a planning team\" |\n| `/agent-team` | Mixed work types or unsure | \"research then implement the caching layer\" |\n\n## How It Works\n\n```\nPhase 1          Phase 2          Phase 3          Phase 4          Phase 5\nAnalyze    --\u003e   Present Plan --\u003e Create Team --\u003e  Coordinate  --\u003e  Synthesize\n                 (user approves)  (spawn agents)   (track work)     (report)\n```\n\n| Phase | What Happens |\n|-------|-------------|\n| **1. Analyze** | Identify independent streams, dependencies, file ownership |\n| **2. Plan** | Present teammate roles, task breakdown, and dependencies. **You approve before anything starts** |\n| **3. Create** | Create team, initialize workspace, create tasks, spawn teammates with roles and protocols |\n| **4. Coordinate** | Monitor progress, update workspace, resolve blockers, route handoffs between teammates |\n| **5. Synthesize** | Collect results, verify integration, generate final report, shut down team |\n\n### Teammate Roles\n\n| Role | Purpose | Tools |\n|------|---------|-------|\n| **Leader** | Coordinate team, track progress, never writes code | TaskCreate, TaskUpdate, SendMessage, Read, Write (workspace only) |\n| **Implementer** | Write code, create files, build features | Read, Write, Edit, Bash, Grep, Glob |\n| **Reviewer** | Validate quality, find issues | Read, Grep, Glob, Bash (read-only) |\n| **Researcher** | Investigate, analyze, report findings | Read, Grep, Glob, WebFetch, WebSearch |\n| **Challenger** | Stress-test assumptions, find edge cases | Read, Grep, Glob, Bash, WebSearch |\n| **Tester** | Run tests, verify builds, check runtime behavior | Read, Grep, Glob, Bash |\n| **Analyst** | Deep-dive into data, metrics, performance | Read, Grep, Glob, Bash (read-only) |\n| **Planner** | Produce specs, architecture designs, decision docs | Read, Write (docs only), Grep, Glob |\n| **Writer** | Produce documentation, ADRs, guides | Read, Write (docs only), Grep, Glob |\n| **Strategist** | Evaluate trade-offs, recommend direction | Read, Grep, Glob, WebFetch, WebSearch |\n| **Auditor** | Systematic checks against standards/checklists | Read, Grep, Glob, Bash (read-only) |\n| **Scout** | Quick recon — scan and report structure | Read, Grep, Glob, Bash (read-only) |\n\n### Team Types\n\nThe lead auto-detects the team type from your request and adapts the workflow accordingly:\n\n| Team Type | When Used | Default Roles | Output |\n|-----------|-----------|---------------|--------|\n| **Implementation** | Build, refactor, fix, migrate code | Implementers + Reviewer + Tester | Code changes + report |\n| **Research** | Investigate, analyze, compare approaches | Researchers + Analyst/Challenger | Findings report |\n| **Audit** | Review, assess, evaluate against standards | Reviewers/Auditors + Challenger | Audit report |\n| **Planning** | Design, architect, produce specs | Planners/Strategists + Researcher | Plan/spec document |\n| **Hybrid** | Mixed work types (e.g., research then implement) | Mix from all roles | Standard report |\n\nThe team type determines which completion checks apply and what the final report looks like. You can override the auto-detected type during plan approval.\n\n### Communication Protocol\n\nTeammates use structured messages for clean coordination:\n\n```\nSTARTING #N:   what I plan to do, which files I'll touch\nCOMPLETED #N:  what I did, files changed, any concerns\nBLOCKED #N:    severity={level}, what's blocking, impact\nHANDOFF #N:    what I produced that another teammate needs\nQUESTION:      what I need to know\n```\n\n## Hooks\n\nFive hooks enforce team discipline automatically:\n\n### TaskCompleted\n\nBlocks premature task completion by checking:\n- Workspace exists with all tracking files (`progress.md`, `tasks.md`, `issues.md`)\n- Implementation tasks have actual file changes (via `git status`)\n- Supports scoped checks using `task_id` and `teammate_name`\n\n### TeammateIdle\n\nNudges idle teammates that still have in-progress tasks:\n- Counts assigned in-progress tasks\n- Loop protection: allows idle after 3 consecutive blocks (teammate is genuinely stuck)\n\n### SessionStart (compact)\n\nAuto-recovers workspace context after context compaction:\n- Detects active workspaces and injects recovery context\n- Skips completed workspaces (status: done)\n\n### PreToolUse (Write|Edit)\n\nEnforces file ownership boundaries:\n- Reads `file-locks.json` from the workspace to determine ownership\n- First violation: warns (exit 0). Second violation: blocks (exit 2)\n- Workspace files are always allowed regardless of ownership\n\n### SubagentStart / SubagentStop\n\nTracks teammate lifecycle in `events.log`:\n- Logs spawn and stop events with timestamps and teammate metadata\n- Provides post-mortem analysis data\n\nAll hooks degrade gracefully — exit 0 if `jq` is missing.\n\n## Workspace\n\nEach team creates a persistent workspace at `.agent-team/{team-name}/` in your project, where `{team-name}` uses an `MMDD-` date prefix for uniqueness (e.g., `0304-refactor-auth`):\n\n```\n.agent-team/0304-refactor-auth/\n├── progress.md      # Team status, members, decisions, handoffs\n├── tasks.md         # Task ledger with status and dependencies\n├── issues.md        # Issue tracker with severity and resolution\n├── file-locks.json  # File ownership map (teammate -\u003e files/directories)\n├── events.log       # Structured JSON event log for post-mortem analysis\n└── report.md        # Final report (generated at completion)\n```\n\n- **Persists** after team deletion — it's the permanent record\n- **Shared** — all teammates can read for context\n- **Gitignored** — coordination artifacts, not deliverables. Automatically added to `.gitignore` during Phase 3 workspace setup if not already excluded.\n\n## Plugin Structure\n\n```\nagent-team-plugin/\n├── .claude-plugin/\n│   ├── plugin.json              # Plugin metadata\n│   └── marketplace.json         # Marketplace registry\n├── hooks/\n│   └── hooks.json               # Hook definitions (${CLAUDE_PLUGIN_ROOT} paths)\n├── scripts/\n│   ├── verify-task-complete.sh      # TaskCompleted hook\n│   ├── check-teammate-idle.sh       # TeammateIdle hook\n│   ├── recover-context.sh           # SessionStart(compact) hook\n│   ├── check-file-ownership.sh      # PreToolUse(Write|Edit) hook\n│   ├── track-teammate-lifecycle.sh  # SubagentStart/Stop hook\n│   ├── setup-worktree.sh            # Worktree creation for isolation mode\n│   └── merge-worktrees.sh           # Worktree merge in Phase 5\n├── skills/\n│   ├── agent-team/\n│   │   └── SKILL.md             # Hybrid/catch-all orchestrator\n│   ├── agent-implement/\n│   │   └── SKILL.md             # Implementation teams\n│   ├── agent-research/\n│   │   └── SKILL.md             # Research teams\n│   ├── agent-audit/\n│   │   └── SKILL.md             # Audit teams\n│   └── agent-plan/\n│       └── SKILL.md             # Planning teams\n├── docs/\n│   ├── shared-phases.md           # Shared phase logic for all archetype skills\n│   ├── teammate-roles.md          # Role definitions and spawn templates\n│   ├── coordination-patterns.md # Conflict resolution and handoff patterns\n│   ├── workspace-templates.md   # Workspace file templates for Phase 3\n│   ├── report-format.md         # Final report specification\n│   ├── team-archetypes.md       # Team type definitions and phase profiles\n│   └── custom-roles.md          # Template for project-specific roles\n├── package.json\n├── CLAUDE.md\n├── LICENSE\n└── README.md\n```\n\n## Troubleshooting\n\n### Agent Teams not available\n\n```\nError: TeamCreate tool is not available\n```\n\nSet the feature flag:\n\n```bash\nexport CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1\n```\n\nOr in Claude Code `settings.json`:\n\n```json\n{\n  \"env\": {\n    \"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS\": \"1\"\n  }\n}\n```\n\n### `jq` not installed\n\nHooks skip checks silently without `jq`. Install for full enforcement:\n\n```bash\nbrew install jq          # macOS\nsudo apt install jq      # Ubuntu/Debian\nscoop install jq         # Windows\n```\n\n### Hooks not firing\n\n1. Verify installed: `claude plugin list`\n2. Check `hooks/hooks.json` exists\n3. Ensure scripts are executable: `chmod +x scripts/*.sh`\n\n### Team size limits\n\n- **Max 4** for mixed teams (implementers + reviewers)\n- **Up to 6** if extras are read-only (researchers, reviewers)\n- Break larger tasks into sequential phases\n\nFor teams larger than 4, verify: (1) every stream has zero file overlap, (2) cross-communication is minimal, (3) workspace churn is manageable.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for a detailed version history.\n\n## License\n\n[MIT](LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fducdmdev%2Fagent-team-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fducdmdev%2Fagent-team-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fducdmdev%2Fagent-team-plugin/lists"}