docs: v1.3.0 — Documentation & Patterns

.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"

.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"
   }

.gitignore

@@ -1,2 +1,3 @@
 .agent-team/
 .claude/
+.worktrees/

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

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
+```

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.
+```

hooks/hooks.json

@@ -1,4 +1,5 @@
 {
+  "description": "Agent Team quality gates — prevents premature task completion and nudges idle teammates",
   "hooks": {
     "TaskCompleted": [
       {

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"
   ]
 }

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.