diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 888480a..caba328 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -8,7 +8,7 @@ { "name": "agent-team", "description": "Orchestrates parallel work via Agent Teams with automated coordination, workspace tracking, and hook enforcement", - "version": "1.2.0", + "version": "1.3.0", "source": { "source": "url", "url": "https://github.com/ducdmdev/agent-team-plugin.git" diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 4b3c3f0..d973297 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agent-team", "description": "Orchestrates parallel work via Agent Teams with automated coordination, workspace tracking, and hook enforcement", - "version": "1.2.0", + "version": "1.3.0", "author": { "name": "Duc Do" } diff --git a/.gitignore b/.gitignore index 05eb4c2..c6e8e23 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ .agent-team/ .claude/ +.worktrees/ diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..600d46f --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,44 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [1.3.0] - 2026-02-27 + +### Added +- **Re-plan on Block** coordination pattern — structured re-planning when critical blockers invalidate the original plan +- **Adversarial Review Rounds** coordination pattern — multi-round cross-review for high-stakes changes +- **Quality Gate** coordination pattern — final validation pass before Phase 5 synthesis +- **Auto-Block on Repeated Failures** coordination pattern — auto-escalation after 3 blocked attempts on the same task +- Custom role definitions template (`docs/custom-roles.md`) — project-specific roles alongside built-in ones +- `description` field in `hooks/hooks.json` for better UX in `/hooks` menu + +## [1.2.0] - 2026-02-26 + +### Added +- Remediation Gate in Phase 5 — spawn fix team for unresolved issues (max 1 cycle) +- Tester role with spawn template +- Pre-shutdown commit protocol for implementers +- Complexity assessment and dedicated reviewer/tester gate for complex plans +- Remediation cycle tracking in `progress.md` + +## [1.1.0] - 2026-02-24 + +### Added +- TeammateIdle hook with loop protection (3 strikes) +- Batch updates coordination pattern +- First contact verification pattern +- Parallel shutdown pattern + +## [1.0.0] - 2026-02-23 + +### Added +- Initial release: 5-phase team orchestrator +- TaskCompleted hook with workspace and git change verification +- 5 teammate roles: Implementer, Reviewer, Researcher, Challenger, Leader +- Persistent workspace with progress.md, tasks.md, issues.md +- Structured communication protocol (STARTING/COMPLETED/BLOCKED/HANDOFF/QUESTION) +- Coordination patterns library +- Final report generation diff --git a/docs/coordination-patterns.md b/docs/coordination-patterns.md index b1a667b..5b290e2 100644 --- a/docs/coordination-patterns.md +++ b/docs/coordination-patterns.md @@ -18,6 +18,10 @@ Patterns for the lead to handle common coordination scenarios. - [Synthesis Pattern](#synthesis-pattern) — collecting final results - [Error Recovery](#error-recovery) — handling teammate errors - [Issue Triage After Context Recovery](#issue-triage-after-context-recovery) — post-compaction review +- [Re-plan on Block](#re-plan-on-block) — revising the plan when a critical block invalidates it +- [Adversarial Review Rounds](#adversarial-review-rounds) — multi-round cross-review for critical changes +- [Quality Gate](#quality-gate) — final validation pass before synthesis +- [Auto-Block on Repeated Failures](#auto-block-on-repeated-failures) — escalation after repeated failures ## Communication Protocol @@ -257,3 +261,140 @@ When the lead recovers from context compaction: - Can it be resolved now with information from other teammates? 4. Address critical/high issues before resuming normal coordination 5. Update `issues.md` rows as issues are resolved + +## Re-plan on Block + +When a critical or high-severity BLOCKED message arrives and the original plan may no longer be viable: + +### Detection + +The lead should consider re-planning when: +- A critical BLOCKED affects 2+ tasks or teammates +- A key assumption in the original Phase 2 plan turns out to be wrong +- An external dependency (API, library, service) is unavailable +- The blocking issue requires a fundamentally different approach + +### Protocol + +1. **Assess viability** — can the original plan still work with minor adjustments? + - If yes: resolve the block normally (stuck dependency resolution, reassignment) + - If no: proceed to re-plan +2. **Pause affected work** — message affected teammates: "Pause work on [tasks]. Re-planning in progress." +3. **Draft revised plan** — identify what changes: task decomposition, file ownership, teammate roles, dependencies +4. **Present to user** — this is a mandatory gate, same as Phase 2: + ``` + Re-plan needed: [reason] + + Original plan: [summary] + Revised plan: [summary of changes] + + Changes: + - [task/role/ownership changes] + + Approve revised plan? + ``` +5. **If approved**: update workspace (tasks.md, progress.md Decision Log), reassign tasks, message affected teammates with new scope +6. **If declined**: user provides alternative direction. Adjust accordingly. + +### Logging + +- Log re-plan decision in `progress.md` Decision Log with reasoning +- Update `tasks.md` with any new/modified/removed tasks +- Log the block that triggered re-planning in `issues.md` + +## Adversarial Review Rounds + +When review quality is critical (security-sensitive code, architectural decisions, complex refactors), use multi-round adversarial review instead of single-pass: + +### When to Use + +- Security-sensitive changes +- Architectural decisions with long-term implications +- Complex refactors touching multiple modules +- When the first reviewer's findings seem superficially clean (early agreement is suspicious) + +### Protocol + +1. **Round 1 — Primary review**: Reviewer A reviews the implementation and reports findings using the standard findings format (H/M/L severity with file:line references) +2. **Round 2 — Cross-review**: Reviewer B receives Reviewer A's findings and is tasked with: + - Verifying each finding (agree/disagree with evidence) + - Finding issues Reviewer A missed + - Challenging any "PASS" assessments that seem too lenient +3. **Round 3 — Synthesis**: Lead collects both reviews and: + - Identifies agreements (high confidence findings) + - Identifies disagreements (need resolution) + - For disagreements: asks the dissenting reviewer to provide specific evidence +4. **Resolution**: If disagreements persist after Round 3, escalate to user with both positions and evidence + +### Lead Coordination + +- Route findings between reviewers via summarized messages (don't relay verbatim — extract actionable points) +- Log the review rounds in `progress.md` Decision Log: "Adversarial review: Round N complete, X agreements, Y disagreements" +- Create separate review tasks for each round (e.g., #5 "Primary security review", #6 "Cross-review of #5 findings") +- Reviewers can use subagents (Task tool with Explore) to parallelize file reads within their review scope + +### Team Composition + +- Minimum: 2 reviewers + lead +- Reviewers should have different review lenses when possible (e.g., security + performance, correctness + maintainability) +- Do NOT have the original implementer serve as a reviewer in adversarial rounds + +## Quality Gate + +A final validation pass before Phase 5 synthesis. Catches integration issues that per-task checks miss. + +### When to Use + +- Complex plans with 3+ implementers +- Cross-module changes where integration bugs are likely +- Plans marked as "complex" in Phase 2 + +### Protocol + +1. **Trigger**: All implementation tasks are completed. Before starting Phase 5. +2. **Assign quick verification tasks** to remaining active teammates: + - Build verification: "Run `[build command]` and report result" + - Test verification: "Run `[test command]` and report result" + - Integration check: "Verify [module A] correctly calls [module B] after both teammates' changes" + - Lint/format check: "Run linter and report any new warnings" +3. **Gate decision**: + - All checks pass → proceed to Phase 5 + - Failures found → create fix tasks, assign to relevant implementers, re-run gate after fixes +4. **Log**: Record gate result in `progress.md` Decision Log: "Quality gate: PASS" or "Quality gate: FAIL — [issues], fix tasks created" + +### Implementation + +The lead creates verification tasks with clear pass/fail criteria: + +``` +Task: "Quality gate — build verification" +Description: Run the project build command. Report PASS if it succeeds, FAIL with error output if it fails. +Completion criteria: Build exits 0 with no errors. +``` + +Assign to the nearest available teammate (reviewer or tester preferred, implementer if no others are available). + +## Auto-Block on Repeated Failures + +Prevents teammates from spinning on the same error. Escalates automatically after repeated failures. + +### Protocol + +1. **Track blocked count per task** — when receiving a BLOCKED message, check `issues.md` for previous BLOCKED entries on the same task +2. **Threshold: 3 attempts** — if a teammate has reported BLOCKED on the same task 3 times: + - Do NOT let them retry + - Mark the task as blocked in `tasks.md` + - Escalate immediately: either reassign to a different teammate or escalate to the user +3. **Log**: Update `issues.md` with the escalation: "Auto-blocked after 3 attempts. Reassigned to [teammate] / Escalated to user." + +### Lead Check + +When processing a BLOCKED message: +``` +1. Read issues.md — count OPEN entries for this task ID +2. If count >= 2 (this is the 3rd block): + a. Message teammate: "This task has been blocked 3 times. Pausing your work on it." + b. Decide: reassign or escalate +3. If count < 2: + a. Acknowledge and route to resolution as normal +``` diff --git a/docs/custom-roles.md b/docs/custom-roles.md new file mode 100644 index 0000000..1f82a19 --- /dev/null +++ b/docs/custom-roles.md @@ -0,0 +1,84 @@ +# Custom Role Definitions + +Project-specific role definitions that extend the built-in roles (Implementer, Reviewer, Researcher, Challenger, Tester). + +The team lead reads this file during Phase 1 task decomposition and uses custom roles alongside built-in roles when they match the task requirements. + +## How to Use + +1. Define custom roles below using the template +2. When invoking `/agent-team`, the lead will check for this file +3. Custom roles are used alongside built-in roles — they don't replace them + +## Template + +Copy this template for each custom role: + +### {Role Name} + +**Purpose**: {One sentence — what does this role do that built-in roles don't cover?} + +**When to use**: {Task types or scenarios where this role is appropriate} + +**Subagent type**: `general-purpose` | `Explore` + +**Typical tools**: {Comma-separated tool list} + +**Spawn prompt template**: +```text +You are a {role name} on this team. Your job is to {primary responsibility}. + +Your assigned tasks: [TASK_IDS] +Your focus area: [AREA] + +Workspace: .agent-team/[TEAM_NAME]/ — read these files for context. + +Communication protocol — send structured messages to the lead: +- STARTING #N: {what I plan to do} +- COMPLETED #N: {what I did, results} +- BLOCKED #N: severity={level}, {blocker}, impact={what can't proceed} +- HANDOFF #N: {output for another teammate} +- QUESTION: {what I need to know} + +Rules: +- {Role-specific rules} +- Read workspace files before asking the lead questions. +- After completing each task, mark complete via TaskUpdate and check TaskList. +``` + +## Example: Database Migration Specialist + +### Database Migration Specialist + +**Purpose**: Handle schema migrations, data transformations, and database-specific concerns that general implementers may not handle safely. + +**When to use**: Tasks involving schema changes, data migrations, or database engine-specific optimizations. + +**Subagent type**: `general-purpose` + +**Typical tools**: Read, Write, Edit, Bash, Grep, Glob + +**Spawn prompt template**: +```text +You are a database migration specialist on this team. Your job is to write safe, reversible database migrations and handle data transformations. + +Your assigned tasks: [TASK_IDS] +Your file ownership: [MIGRATION_FILES/DIRECTORIES] + +Workspace: .agent-team/[TEAM_NAME]/ — read these files for context. + +Communication protocol — send structured messages to the lead: +- STARTING #N: {migration I plan to write, tables affected} +- COMPLETED #N: {migration written, rollback verified, any data concerns} +- BLOCKED #N: severity={level}, {blocker}, impact={what can't proceed} +- HANDOFF #N: {schema changes that implementers need to know about} +- QUESTION: {what I need to know} + +Rules: +- Every migration MUST have a rollback/down migration. +- Test migrations on a copy before applying to the main database. +- ONLY modify files in your owned area (migration directories). +- Document any data loss risks in your COMPLETED message. +- Read workspace files before asking the lead questions. +- After completing each task, mark complete via TaskUpdate and check TaskList. +``` diff --git a/hooks/hooks.json b/hooks/hooks.json index ffc54b7..401ff20 100644 --- a/hooks/hooks.json +++ b/hooks/hooks.json @@ -1,4 +1,5 @@ { + "description": "Agent Team quality gates — prevents premature task completion and nudges idle teammates", "hooks": { "TaskCompleted": [ { diff --git a/package.json b/package.json index 263ad02..a267d57 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "agent-team-plugin", - "version": "1.2.0", + "version": "1.3.0", "description": "Claude Code plugin for orchestrating parallel work via Agent Teams", "license": "MIT", "keywords": ["claude-code", "plugin", "agent-team", "orchestration", "parallel"], @@ -20,6 +20,7 @@ "docs/", "tests/", "README.md", - "LICENSE" + "LICENSE", + "CHANGELOG.md" ] } diff --git a/skills/agent-team/SKILL.md b/skills/agent-team/SKILL.md index fc239c9..fc648c2 100644 --- a/skills/agent-team/SKILL.md +++ b/skills/agent-team/SKILL.md @@ -241,6 +241,10 @@ For detailed patterns on these scenarios, see [coordination-patterns.md](../../d - **Synthesis pattern** — collect structured summaries from all teammates at completion - **Error recovery** — log to issues.md, acknowledge, assess and route to resolution - **Issue triage after context recovery** — review OPEN issues in issues.md after compaction +- **Re-plan on Block** — when a critical blocker invalidates the original plan, re-plan with user approval +- **Adversarial review rounds** — multi-round cross-review for high-stakes changes +- **Quality gate** — final validation pass before Phase 5 synthesis +- **Auto-block on repeated failures** — auto-escalation after 3 blocked attempts **Periodic scan**: on every context recovery, check `issues.md` for OPEN items and address them before resuming normal coordination.