ducdmdev · ducdmdev · Mar 2, 2026 · Feb 28, 2026 · Feb 28, 2026 · Feb 28, 2026
diff --git 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.4.0",
+      "version": "2.0.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
@@ -1,7 +1,7 @@
 {
   "name": "agent-team",
   "description": "Orchestrates parallel work via Agent Teams with automated coordination, workspace tracking, and hook enforcement",
-  "version": "1.4.0",
+  "version": "2.0.0",
   "author": {
     "name": "Duc Do"
   }

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,36 @@ 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).
 
+## [2.0.0] - 2026-03-01
+
+### Added
+- **Git worktree isolation** (opt-in) — `isolation: worktree` in Phase 2 plan gives each implementer a dedicated worktree
+- **Nested task decomposition** — senior implementers can create sub-tasks and spawn sub-agents
+- Worktree setup and merge scripts (`scripts/setup-worktree.sh`, `scripts/merge-worktrees.sh`)
+
+### Changed
+- Major version bump: nested decomposition changes the team coordination model
+
+## [1.6.0] - 2026-03-01
+
+### Added
+- Auto-branch per teammate — implementers create `{team-name}/{name}` branches, merged in Phase 5
+- `events.log` workspace file — structured JSON event log for post-mortem analysis
+- Direct Handoff coordination pattern — authorized peer-to-peer messaging with audit trail
+- Branch Merge step in Phase 5
+
+## [1.5.0] - 2026-03-01
+
+### Added
+- **SessionStart(compact) hook** — auto-recovers workspace context after compaction
+- **PreToolUse(Write|Edit) hook** — enforces file ownership (warn-then-block)
+- **SubagentStart/SubagentStop hooks** — tracks teammate lifecycle in events.log
+- `file-locks.json` workspace file — maps teammates to owned files/directories
+
+### Changed
+- TaskCompleted hook now uses `task_id` and `teammate_name` for scoped git checks
+- Hooks section in SKILL.md updated to document all 5 hooks
+
 ## [1.4.0] - 2026-02-28
 
 ### Added

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -28,12 +28,17 @@ docs/                  Reference docs consumed by SKILL.md at runtime
 |------|---------|----------------|
 | `.claude-plugin/plugin.json` | Plugin identity | Bump version here on release |
 | `.claude-plugin/marketplace.json` | Marketplace registry | Bump version here too, keep in sync with plugin.json |
-| `hooks/hooks.json` | Hook registration | Update timeout values, add new hooks, or update hook command paths |
-| `scripts/*.sh` | Hook enforcement logic | Written in bash (`#!/bin/bash`), degrade gracefully without `jq` |
+| `hooks/hooks.json` | Hook registration (6 hooks) | Update timeout values, add new hooks, or update hook command paths |
+| `scripts/*.sh` | Hook enforcement logic (7 scripts) | Written in bash (`#!/bin/bash`), degrade gracefully without `jq` |
 | `skills/agent-team/SKILL.md` | Core skill prompt | Most changes go here. Keep Phase 1-5 structure |
 | `docs/worker-roles.md` | Role definitions + spawn templates | Update when adding new roles |
 | `docs/coordination-patterns.md` | Conflict resolution, handoffs | Update when adding new coordination patterns |
+| `docs/workspace-templates.md` | Workspace file templates | Update when adding new workspace files |
 | `docs/report-format.md` | Final report template | Update when changing report structure |
+| `docs/custom-roles.md` | Project-specific role template | Reference for users creating custom roles |
+| `CHANGELOG.md` | Version history | Add entry for each release |
+| `README.md` | User-facing documentation | Keep in sync with feature changes |
+| `tests/` | Hook and structure tests | `hooks/` for hook tests, `structure/` for plugin validation |
 
 ## Conventions
 
@@ -71,6 +76,14 @@ chore:    maintenance (package.json, CI, dependencies)
 
 ## Testing
 
+### Run Full Test Suite
+
+```bash
+bash tests/run-tests.sh
+```
+
+Runs 9 test files (78 assertions) covering all hooks and plugin structure.
+
 ### Validate Plugin
 
 ```bash
@@ -87,9 +100,14 @@ Then trigger with: "use agent team to [task]"
 
 ### Verify Hooks
 
-1. Start a team session
-2. Try marking a task complete without file changes — TaskCompleted hook should block
-3. Let a teammate go idle with in-progress tasks — TeammateIdle hook should nudge
+Six hooks registered in `hooks/hooks.json`:
+
+1. **TaskCompleted** — try marking a task complete without file changes (should block)
+2. **TeammateIdle** — let a teammate go idle with in-progress tasks (should nudge)
+3. **SessionStart(compact)** — compact context in a team session (should recover workspace)
+4. **PreToolUse(Write|Edit)** — have a teammate edit another's file (should warn, then block)
+5. **SubagentStart** — spawn a teammate (should log to events.log)
+6. **SubagentStop** — teammate shuts down (should log to events.log)
 
 ## Common Tasks
 
@@ -109,9 +127,11 @@ Then trigger with: "use agent team to [task]"
 
 ### Releasing a New Version
 
-1. Update version in `.claude-plugin/plugin.json`
-2. Update version in `.claude-plugin/marketplace.json`
-3. Update version in `package.json`
-4. Run `claude plugin validate .`
-5. Commit with `chore: bump version to X.Y.Z`
-6. Tag with `git tag vX.Y.Z`
+1. Run `bash tests/run-tests.sh` — all tests must pass
+2. Update version in `.claude-plugin/plugin.json`
+3. Update version in `.claude-plugin/marketplace.json`
+4. Update version in `package.json`
+5. Add entry to `CHANGELOG.md`
+6. Run `claude plugin validate .`
+7. Commit with `chore: bump version to X.Y.Z`
+8. Tag with `git tag vX.Y.Z`
diff --git a/README.md b/README.md
@@ -99,32 +99,54 @@ QUESTION:      what I need to know
 
 ## Hooks
 
-Two hooks enforce team discipline automatically:
+Five hooks enforce team discipline automatically:
 
 ### TaskCompleted
 
 Blocks premature task completion by checking:
 - Workspace exists with all tracking files (`progress.md`, `tasks.md`, `issues.md`)
 - Implementation tasks have actual file changes (via `git status`)
+- Supports scoped checks using `task_id` and `teammate_name`
 
 ### TeammateIdle
 
 Nudges idle teammates that still have in-progress tasks:
 - Counts assigned in-progress tasks
 - Loop protection: allows idle after 3 consecutive blocks (teammate is genuinely stuck)
 
-Both hooks degrade gracefully — exit 0 if `jq` is missing.
+### SessionStart (compact)
+
+Auto-recovers workspace context after context compaction:
+- Detects active workspaces and injects recovery context
+- Skips completed workspaces (status: done)
+
+### PreToolUse (Write|Edit)
+
+Enforces file ownership boundaries:
+- Reads `file-locks.json` from the workspace to determine ownership
+- First violation: warns (exit 0). Second violation: blocks (exit 2)
+- Workspace files are always allowed regardless of ownership
+
+### SubagentStart / SubagentStop
+
+Tracks teammate lifecycle in `events.log`:
+- Logs spawn and stop events with timestamps and teammate metadata
+- Provides post-mortem analysis data
+
+All hooks degrade gracefully — exit 0 if `jq` is missing.
 
 ## Workspace
 
 Each team creates a persistent workspace at `.agent-team/{team-name}/` in your project:
 
 ```
 .agent-team/{team-name}/
-├── progress.md     # Team status, members, decisions, handoffs
-├── tasks.md        # Task ledger with status and dependencies
-├── issues.md       # Issue tracker with severity and resolution
-└── report.md       # Final report (generated at completion)
+├── progress.md      # Team status, members, decisions, handoffs
+├── tasks.md         # Task ledger with status and dependencies
+├── issues.md        # Issue tracker with severity and resolution
+├── file-locks.json  # File ownership map (teammate -> files/directories)
+├── events.log       # Structured JSON event log for post-mortem analysis
+└── report.md        # Final report (generated at completion)
 ```
 
 - **Persists** after team deletion — it's the permanent record
@@ -141,15 +163,22 @@ agent-team-plugin/
 ├── hooks/
 │   └── hooks.json               # Hook definitions (${CLAUDE_PLUGIN_ROOT} paths)
 ├── scripts/
-│   ├── verify-task-complete.sh  # TaskCompleted hook
-│   └── check-teammate-idle.sh   # TeammateIdle hook
+│   ├── verify-task-complete.sh      # TaskCompleted hook
+│   ├── check-teammate-idle.sh       # TeammateIdle hook
+│   ├── recover-context.sh           # SessionStart(compact) hook
+│   ├── check-file-ownership.sh      # PreToolUse(Write|Edit) hook
+│   ├── track-teammate-lifecycle.sh  # SubagentStart/Stop hook
+│   ├── setup-worktree.sh            # Worktree creation for isolation mode
+│   └── merge-worktrees.sh           # Worktree merge in Phase 5
 ├── skills/
 │   └── agent-team/
 │       └── SKILL.md             # Main skill (team lead orchestrator)
 ├── docs/
 │   ├── worker-roles.md          # Role definitions and spawn templates
 │   ├── coordination-patterns.md # Conflict resolution and handoff patterns
-│   └── report-format.md         # Final report specification
+│   ├── workspace-templates.md   # Workspace file templates for Phase 3
+│   ├── report-format.md         # Final report specification
+│   └── custom-roles.md          # Template for project-specific roles
 ├── package.json
 ├── CLAUDE.md
 ├── LICENSE
@@ -204,9 +233,9 @@ scoop install jq         # Windows
 
 For teams larger than 4, verify: (1) every stream has zero file overlap, (2) cross-communication is minimal, (3) workspace churn is manageable.
 
-## Planned Features
+## Changelog
 
-See `docs/plans/` for approved designs and implementation plans for upcoming features.
+See [CHANGELOG.md](CHANGELOG.md) for a detailed version history.
 
 ## License
 

diff --git a/docs/coordination-patterns.md b/docs/coordination-patterns.md
@@ -22,6 +22,7 @@ Patterns for the lead to handle common coordination scenarios.
 - [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
+- [Direct Handoff](#direct-handoff) — authorized peer-to-peer messaging with audit trail
 
 ## Communication Protocol
 
@@ -398,3 +399,30 @@ When processing a BLOCKED message:
 3. If count < 2:
    a. Acknowledge and route to resolution as normal
 ```
+
+## Direct Handoff
+
+For pre-approved information transfers between specific teammates, bypassing the lead for efficiency.
+
+### When to Use
+
+- Two teammates have a clear dependency (A produces -> B consumes)
+- The handoff content is straightforward (file paths, interface definitions)
+- The lead has explicitly authorized the direct channel in their spawn prompts
+
+### When NOT to Use
+
+- The handoff requires interpretation or decision-making (route through lead)
+- The information needs to be visible to multiple teammates (use lead routing)
+- First-time handoffs between teammates who haven't worked together in this session
+
+### Protocol
+
+1. **Lead authorizes** in spawn prompts: "For handoffs to [teammate-name], you may message them directly. Include the lead in a summary."
+2. **Sender** messages the recipient directly using SendMessage with `type: "message"` and the recipient's name
+3. **Sender also messages the lead** with a brief summary: "HANDOFF #N: Sent [details] directly to [recipient]"
+4. **Lead logs** the handoff in `progress.md` Handoffs section (audit trail preserved)
+
+### Key Rule
+
+The audit trail MUST be maintained. Direct handoffs save time but must still be logged via the lead's workspace updates.
diff --git a/docs/report-format.md b/docs/report-format.md
@@ -13,7 +13,7 @@ The final report is a persistent artifact generated at completion. It lives in t
 
 `.agent-team/{team-name}/report.md` (relative to project root)
 
-This file is generated during Phase 5, step 6. It is the last file written before shutdown.
+This file is generated during Phase 5, step 7. It is the last file written before shutdown.
 
 ## Template
 

diff --git a/docs/worker-roles.md b/docs/worker-roles.md
@@ -119,6 +119,7 @@ Communication protocol — send structured messages to the lead:
 - QUESTION: {what I need to know, what I already checked in workspace}
 
 Rules:
+- At the start of your first task, create a feature branch: `git checkout -b {team-name}/{your-name}`. All your work goes on this branch. If git is not available, skip branching and work directly.
 - ONLY modify files in your owned area. If you need changes elsewhere, message the lead.
 - Before starting each new task, re-read workspace files (progress.md, tasks.md, issues.md) to ensure you have current state. This prevents context drift on long-running sessions.
 - Send STARTING before beginning each task. Send COMPLETED after finishing (include files changed).
@@ -302,4 +303,18 @@ Key parameters:
 
 ## Subagent Usage Within Teammates
 
-Teammates can spawn subagents (Task tool) for self-contained subtasks that don't need cross-teammate communication. Use them to parallelize within your own scope — e.g., writing tests while implementing, or reading multiple files simultaneously. Do NOT use subagents when the subtask needs input from another teammate or requires back-and-forth iteration.
+Teammates can spawn subagents (Task tool) for self-contained subtasks that don't need cross-teammate communication.
+
+### Standard Usage
+Use subagents to parallelize within your own scope — e.g., writing tests while implementing, or reading multiple files simultaneously. Do NOT use subagents when the subtask needs input from another teammate.
+
+### Nested Task Decomposition (Senior Implementers)
+When explicitly authorized by the lead in the spawn prompt, senior implementers may:
+- Create sub-tasks using TaskCreate with IDs prefixed by their parent task (e.g., if working on task #3, create sub-tasks described as "#3.1 — [subject]", "#3.2 — [subject]")
+- Spawn subagents to work on sub-tasks in parallel
+- Report rolled-up results to the lead (the lead sees sub-tasks in TaskList but only interacts at the parent level)
+
+**Limits:**
+- One level of nesting max — sub-subagents cannot create further sub-tasks
+- Sub-tasks must be within the teammate's owned file scope
+- The teammate is responsible for coordinating their sub-agents (the lead does not manage them)
diff --git a/docs/workspace-templates.md b/docs/workspace-templates.md
@@ -7,6 +7,7 @@ Templates for the 3 workspace tracking files initialized during Phase 3. The lea
 - [progress.md](#progressmd) — team status, members, phase checklist, decisions, handoffs
 - [tasks.md](#tasksmd) — task ledger with status tracking
 - [issues.md](#issuesmd) — issue tracker with severity and impact
+- [Additional Workspace Files](#additional-workspace-files) — files created during Phase 3/4 (not template-based)
 
 ## progress.md
 
@@ -97,3 +98,31 @@ Cross-teammate information transfers.
 - **rework**: Completed work must be redone
 - **deferred**: Logged for post-team follow-up
 ````
+
+## Additional Workspace Files
+
+These files are created during Phase 3/4 but are not template-based — they are generated from runtime data.
+
+### file-locks.json
+
+Created during Phase 3 after spawning teammates. Maps each teammate to their owned files/directories. Used by the PreToolUse(Write|Edit) hook to enforce file ownership.
+
+```json
+{
+  "teammate-name": ["src/auth/", "src/middleware/auth.ts"],
+  "other-teammate": ["src/api/", "tests/api/"]
+}
+```
+
+### events.log
+
+Created by the SubagentStart/SubagentStop hooks during Phase 4. Each line is a JSON object recording teammate spawn and stop events. Used for post-mortem analysis.
+
+```json
+{"ts":"2026-03-01T00:00:00Z","type":"spawn","agent":"backend-impl","agent_type":"general-purpose"}
+{"ts":"2026-03-01T01:00:00Z","type":"stop","agent":"backend-impl"}
+```
+
+### report.md
+
+Generated during Phase 5 using the template in [report-format.md](report-format.md). This is the final artifact written before shutdown.