From 50f919dee751ee886c81c5891ecdccc94d959fb6 Mon Sep 17 00:00:00 2001
From: ducdmdev <ducdm.dev.work@gmail.com>
Date: Sat, 28 Feb 2026 23:37:59 +0700
Subject: [PATCH 1/3] =?UTF-8?q?feat:=20v1.4.0=20=E2=80=94=20prompt=20and?=
 =?UTF-8?q?=20template=20improvements?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add re-read workspace instruction to all 5 spawn templates
- Add team metrics section to final report template
- Bump version to 1.4.0 across plugin.json, marketplace.json, package.json
- Add CHANGELOG entry for v1.4.0
---
 .claude-plugin/marketplace.json |  2 +-
 .claude-plugin/plugin.json      |  2 +-
 CHANGELOG.md                    | 11 +++++++++++
 docs/report-format.md           | 11 +++++++++++
 docs/worker-roles.md            |  5 +++++
 package.json                    |  2 +-
 6 files changed, 30 insertions(+), 3 deletions(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index caba328..7962536 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.3.0",
+      "version": "1.4.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 d973297..4016d73 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.3.0",
+  "version": "1.4.0",
   "author": {
     "name": "Duc Do"
   }
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 600d46f..4f013d7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,17 @@ 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.4.0] - 2026-02-28
+
+### Added
+- Re-read workspace instruction in all spawn templates (prevents context drift)
+- Team metrics section in final report template
+- Custom roles reference in Phase 1 decomposition
+
+### Changed
+- `tasks.md` workspace template now groups tasks by status (In Progress / Blocked / Pending / Completed)
+- TeammateIdle hook updated to parse grouped tasks.md format
+
 ## [1.3.0] - 2026-02-27
 
 ### Added
diff --git a/docs/report-format.md b/docs/report-format.md
index 4723c4f..eecb1e3 100644
--- a/docs/report-format.md
+++ b/docs/report-format.md
@@ -52,6 +52,17 @@ This file is generated during Phase 5, step 6. It is the last file written befor
 ### Follow-up Items
 {Bulleted list of anything that needs attention after the team disbanded}
 
+### Team Metrics
+
+| Metric | Value |
+|--------|-------|
+| Tasks | {completed}/{total} |
+| Issues | {resolved}/{total} ({critical}C {high}H {medium}M {low}L) |
+| Handoffs | {count} |
+| Blocked events | {count} |
+| Remediation cycles | {0 or 1} |
+| Re-plans | {count, 0 if none} |
+
 ---
 
 ## Full Audit Trail
diff --git a/docs/worker-roles.md b/docs/worker-roles.md
index 68d9494..dd97bb0 100644
--- a/docs/worker-roles.md
+++ b/docs/worker-roles.md
@@ -89,6 +89,7 @@ Communication protocol — send structured messages to the lead:
 
 Rules:
 - Read and analyze only. Do not modify any files.
+- 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.
 - Report findings with specific file references (path:line).
 - Read workspace files before asking the lead questions — the answer may already be there.
 - When blocked, message the lead immediately with the BLOCKED format above.
@@ -119,6 +120,7 @@ Communication protocol — send structured messages to the lead:
 
 Rules:
 - 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).
 - Verify your work compiles/passes basic checks before marking tasks complete.
 - Read workspace files before asking the lead questions — the answer may already be there.
@@ -159,6 +161,7 @@ In COMPLETED messages, include total counts: "N issues: X high, Y medium, Z low"
 
 Rules:
 - Read and analyze only. Do not modify files.
+- 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.
 - Include specific file:line references and fix suggestions for every high-severity issue.
 - Read workspace issues.md to avoid reporting known/duplicate issues.
 - When you find a cross-cutting issue that affects another teammate's scope, use HANDOFF.
@@ -189,6 +192,7 @@ Communication protocol — send structured messages to the lead:
 
 Rules:
 - Actively try to break or disprove what other teammates produce.
+- 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.
 - Back every critique with evidence: specific code, concrete scenarios, or references.
 - Don't just criticize — propose alternatives when you find problems.
 - Read workspace files to understand what decisions were already made and why.
@@ -225,6 +229,7 @@ In COMPLETED messages, include total counts: "N tests: X passed, Y failed, Z ski
 
 Rules:
 - Run existing test suites and write new tests as needed to verify implementation correctness.
+- 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.
 - Do not modify implementation code. If you find a bug, report it via HANDOFF to the lead.
 - Include reproduction steps for every failure.
 - Read workspace files before asking the lead questions — the answer may already be there.
diff --git a/package.json b/package.json
index a267d57..a877ed7 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "agent-team-plugin",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Claude Code plugin for orchestrating parallel work via Agent Teams",
   "license": "MIT",
   "keywords": ["claude-code", "plugin", "agent-team", "orchestration", "parallel"],

From dadcafdddba551eaba0cfa5e28d778bc30d680cf Mon Sep 17 00:00:00 2001
From: ducdmdev <ducdm.dev.work@gmail.com>
Date: Sat, 28 Feb 2026 23:38:40 +0700
Subject: [PATCH 2/3] feat: group tasks.md by status, add custom roles
 reference to Phase 1

---
 docs/workspace-templates.md             |  22 +++-
 scripts/check-teammate-idle.sh          |   9 +-
 skills/agent-team/SKILL.md              |   1 +
 tests/hooks/test-check-teammate-idle.sh | 158 +++++++++++++++++++++---
 tests/lib/test-helpers.sh               |  23 +++-
 5 files changed, 186 insertions(+), 27 deletions(-)

diff --git a/docs/workspace-templates.md b/docs/workspace-templates.md
index dc9d095..d64d11e 100644
--- a/docs/workspace-templates.md
+++ b/docs/workspace-templates.md
@@ -53,9 +53,25 @@ Cross-teammate information transfers.
 
 **Last updated**: {timestamp}
 
-| ID | Subject | Owner | Status | Blocked By | Notes |
-|----|---------|-------|--------|-----------|-------|
-| {id} | {subject} | {owner} | pending / in_progress / completed | {IDs or "—"} | {brief notes} |
+## In Progress
+
+| ID | Subject | Owner | Notes |
+|----|---------|-------|-------|
+
+## Blocked
+
+| ID | Subject | Owner | Blocked By | Notes |
+|----|---------|-------|-----------|-------|
+
+## Pending
+
+| ID | Subject | Owner | Blocked By | Notes |
+|----|---------|-------|-----------|-------|
+
+## Completed
+
+| ID | Subject | Owner | Notes |
+|----|---------|-------|-------|
 ````
 
 ## issues.md
diff --git a/scripts/check-teammate-idle.sh b/scripts/check-teammate-idle.sh
index d4b4657..86a150a 100755
--- a/scripts/check-teammate-idle.sh
+++ b/scripts/check-teammate-idle.sh
@@ -54,8 +54,13 @@ if [ "$RETRY_COUNT" -ge "$MAX_RETRIES" ]; then
 fi
 
 # Count in-progress tasks owned by this teammate by parsing the markdown table.
-# Match Owner column (col 4) and Status column (col 5) in pipe-delimited table.
-IN_PROGRESS=$(awk -F'|' -v owner="$TEAMMATE" 'tolower($4) ~ tolower(owner) && tolower($5) ~ /in_progress/' "$TASKS_FILE" 2>/dev/null | wc -l | tr -d ' ')
+# The grouped format uses section headers (## In Progress) as status indicators.
+# Match Owner column (col 4) within the "## In Progress" section.
+IN_PROGRESS=$(awk -F'|' -v owner="$TEAMMATE" '
+  /^## In Progress/ { in_progress=1; next }
+  /^## / { in_progress=0 }
+  in_progress && NF >= 4 && tolower($4) ~ tolower(owner)
+' "$TASKS_FILE" 2>/dev/null | wc -l | tr -d ' ')
 
 if [ "$IN_PROGRESS" -gt 0 ]; then
   # Increment retry counter
diff --git a/skills/agent-team/SKILL.md b/skills/agent-team/SKILL.md
index fc648c2..8a794cd 100644
--- a/skills/agent-team/SKILL.md
+++ b/skills/agent-team/SKILL.md
@@ -46,6 +46,7 @@ Analyze the user's task: $ARGUMENTS
    - **By layer**: data model vs API vs UI (best for full-stack features)
    - Avoid splits that create heavy cross-dependencies — if two streams need constant handoffs, merge them
 6. **Integration points** — for each pair of streams, identify where their outputs must connect (shared interfaces, API contracts, database schemas). These become explicit handoff points in Phase 2.
+7. **Check for custom roles** — if `docs/custom-roles.md` exists in the project, read it. Use custom roles alongside built-in roles when they match the task requirements.
 
 **Self-check**: "Do I have 2+ streams where each can make meaningful progress without waiting on the others? Are integration points identified?" If no, reconsider the split.
 
diff --git a/tests/hooks/test-check-teammate-idle.sh b/tests/hooks/test-check-teammate-idle.sh
index 724b706..1b64851 100755
--- a/tests/hooks/test-check-teammate-idle.sh
+++ b/tests/hooks/test-check-teammate-idle.sh
@@ -45,9 +45,28 @@ mkdir -p ".agent-team/t"
 cat > ".agent-team/t/tasks.md" <<'EOF'
 # Tasks: t
 
-| ID | Subject | Owner | Status | Blocked By | Notes |
-|----|---------|-------|--------|-----------|-------|
-| 1 | Build feature | alice | in_progress | — | working on it |
+**Last updated**: 2026-01-01
+
+## In Progress
+
+| ID | Subject | Owner | Notes |
+|----|---------|-------|-------|
+| 1 | Build feature | alice | working on it |
+
+## Blocked
+
+| ID | Subject | Owner | Blocked By | Notes |
+|----|---------|-------|-----------|-------|
+
+## Pending
+
+| ID | Subject | Owner | Blocked By | Notes |
+|----|---------|-------|-----------|-------|
+
+## Completed
+
+| ID | Subject | Owner | Notes |
+|----|---------|-------|-------|
 EOF
 rm -f "$COUNTER_DIR/t--alice"
 run_hook "$HOOK" '{"teammate_name":"alice","team_name":"t"}'
@@ -62,9 +81,28 @@ mkdir -p ".agent-team/t"
 cat > ".agent-team/t/tasks.md" <<'EOF'
 # Tasks: t
 
-| ID | Subject | Owner | Status | Blocked By | Notes |
-|----|---------|-------|--------|-----------|-------|
-| 1 | Build feature | alice | completed | — | done |
+**Last updated**: 2026-01-01
+
+## In Progress
+
+| ID | Subject | Owner | Notes |
+|----|---------|-------|-------|
+
+## Blocked
+
+| ID | Subject | Owner | Blocked By | Notes |
+|----|---------|-------|-----------|-------|
+
+## Pending
+
+| ID | Subject | Owner | Blocked By | Notes |
+|----|---------|-------|-----------|-------|
+
+## Completed
+
+| ID | Subject | Owner | Notes |
+|----|---------|-------|-------|
+| 1 | Build feature | alice | done |
 EOF
 rm -f "$COUNTER_DIR/t--alice"
 run_hook "$HOOK" '{"teammate_name":"alice","team_name":"t"}'
@@ -78,9 +116,28 @@ mkdir -p ".agent-team/t"
 cat > ".agent-team/t/tasks.md" <<'EOF'
 # Tasks: t
 
-| ID | Subject | Owner | Status | Blocked By | Notes |
-|----|---------|-------|--------|-----------|-------|
-| 1 | Build feature | alice | in_progress | — | stuck |
+**Last updated**: 2026-01-01
+
+## In Progress
+
+| ID | Subject | Owner | Notes |
+|----|---------|-------|-------|
+| 1 | Build feature | alice | stuck |
+
+## Blocked
+
+| ID | Subject | Owner | Blocked By | Notes |
+|----|---------|-------|-----------|-------|
+
+## Pending
+
+| ID | Subject | Owner | Blocked By | Notes |
+|----|---------|-------|-----------|-------|
+
+## Completed
+
+| ID | Subject | Owner | Notes |
+|----|---------|-------|-------|
 EOF
 rm -f "$COUNTER_DIR/t--alice"
 
@@ -104,22 +161,60 @@ mkdir -p ".agent-team/t"
 cat > ".agent-team/t/tasks.md" <<'EOF'
 # Tasks: t
 
-| ID | Subject | Owner | Status | Blocked By | Notes |
-|----|---------|-------|--------|-----------|-------|
-| 1 | Build feature | alice | in_progress | — | stuck |
+**Last updated**: 2026-01-01
+
+## In Progress
+
+| ID | Subject | Owner | Notes |
+|----|---------|-------|-------|
+| 1 | Build feature | alice | stuck |
+
+## Blocked
+
+| ID | Subject | Owner | Blocked By | Notes |
+|----|---------|-------|-----------|-------|
+
+## Pending
+
+| ID | Subject | Owner | Blocked By | Notes |
+|----|---------|-------|-----------|-------|
+
+## Completed
+
+| ID | Subject | Owner | Notes |
+|----|---------|-------|-------|
 EOF
 rm -f "$COUNTER_DIR/t--alice"
 run_hook "$HOOK" '{"teammate_name":"alice","team_name":"t"}'
 # Counter file should exist now
 assert_true "7: Counter file created" "[ -f '$COUNTER_DIR/t--alice' ]"
 
-# Now change task to completed
+# Now change task to completed (move from In Progress to Completed section)
 cat > ".agent-team/t/tasks.md" <<'EOF'
 # Tasks: t
 
-| ID | Subject | Owner | Status | Blocked By | Notes |
-|----|---------|-------|--------|-----------|-------|
-| 1 | Build feature | alice | completed | — | done |
+**Last updated**: 2026-01-01
+
+## In Progress
+
+| ID | Subject | Owner | Notes |
+|----|---------|-------|-------|
+
+## Blocked
+
+| ID | Subject | Owner | Blocked By | Notes |
+|----|---------|-------|-----------|-------|
+
+## Pending
+
+| ID | Subject | Owner | Blocked By | Notes |
+|----|---------|-------|-----------|-------|
+
+## Completed
+
+| ID | Subject | Owner | Notes |
+|----|---------|-------|-------|
+| 1 | Build feature | alice | done |
 EOF
 run_hook "$HOOK" '{"teammate_name":"alice","team_name":"t"}'
 assert_exit_code 0 "$HOOK_EXIT" "7: Counter reset — allows idle"
@@ -138,10 +233,33 @@ setup_temp_dir
 cd "$TEST_TEMP_DIR"
 # Create workspace at .agent-team/my-project/ (the original team)
 setup_mock_workspace "my-project"
-# Add an in-progress task owned by the teammate
-cat >> "$WORKSPACE_DIR/tasks.md" <<'TASKS'
-| 1 | Fix something | test-impl | in_progress | — | — |
-TASKS
+# Overwrite tasks.md with an in-progress task owned by the teammate
+cat > "$WORKSPACE_DIR/tasks.md" <<'EOF'
+# Tasks: test
+
+**Last updated**: 2026-01-01
+
+## In Progress
+
+| ID | Subject | Owner | Notes |
+|----|---------|-------|-------|
+| 1 | Fix something | test-impl | — |
+
+## Blocked
+
+| ID | Subject | Owner | Blocked By | Notes |
+|----|---------|-------|-----------|-------|
+
+## Pending
+
+| ID | Subject | Owner | Blocked By | Notes |
+|----|---------|-------|-----------|-------|
+
+## Completed
+
+| ID | Subject | Owner | Notes |
+|----|---------|-------|-------|
+EOF
 rm -f "$COUNTER_DIR/my-project-fix--test-impl"
 run_hook "$HOOK" '{"teammate_name":"test-impl","team_name":"my-project-fix"}'
 assert_exit_code 2 "$HOOK_EXIT" "9: Remediation team (-fix) finds original workspace and blocks idle"
diff --git a/tests/lib/test-helpers.sh b/tests/lib/test-helpers.sh
index 4f4596b..8d8e3ad 100755
--- a/tests/lib/test-helpers.sh
+++ b/tests/lib/test-helpers.sh
@@ -61,8 +61,27 @@ EOF
   cat > "$WORKSPACE_DIR/tasks.md" <<'EOF'
 # Tasks: test
 
-| ID | Subject | Owner | Status | Blocked By | Notes |
-|----|---------|-------|--------|-----------|-------|
+**Last updated**: 2026-01-01
+
+## In Progress
+
+| ID | Subject | Owner | Notes |
+|----|---------|-------|-------|
+
+## Blocked
+
+| ID | Subject | Owner | Blocked By | Notes |
+|----|---------|-------|-----------|-------|
+
+## Pending
+
+| ID | Subject | Owner | Blocked By | Notes |
+|----|---------|-------|-----------|-------|
+
+## Completed
+
+| ID | Subject | Owner | Notes |
+|----|---------|-------|-------|
 EOF
 
   cat > "$WORKSPACE_DIR/issues.md" <<'EOF'

From 7a239cfdb3c6ef2b13a298573e31ca0890410fe6 Mon Sep 17 00:00:00 2001
From: ducdmdev <ducdm.dev.work@gmail.com>
Date: Sat, 28 Feb 2026 23:50:55 +0700
Subject: [PATCH 3/3] test: add awk parser edge case tests for grouped tasks.md
 format
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Test 10: multiple in-progress tasks by same owner counts correctly
- Test 11: tasks in Blocked/Pending/Completed sections are ignored
- Test 12: mixed sections — only In Progress section counts
---
 tests/hooks/test-check-teammate-idle.sh | 114 ++++++++++++++++++++++++
 1 file changed, 114 insertions(+)

diff --git a/tests/hooks/test-check-teammate-idle.sh b/tests/hooks/test-check-teammate-idle.sh
index 1b64851..973e23b 100755
--- a/tests/hooks/test-check-teammate-idle.sh
+++ b/tests/hooks/test-check-teammate-idle.sh
@@ -265,6 +265,120 @@ run_hook "$HOOK" '{"teammate_name":"test-impl","team_name":"my-project-fix"}'
 assert_exit_code 2 "$HOOK_EXIT" "9: Remediation team (-fix) finds original workspace and blocks idle"
 cleanup_temp_dir
 
+# --- Test 10: Multiple in-progress tasks by same owner counts correctly ---
+setup_temp_dir
+cd "$TEST_TEMP_DIR"
+mkdir -p ".agent-team/t"
+cat > ".agent-team/t/tasks.md" <<'EOF'
+# Tasks: t
+
+**Last updated**: 2026-01-01
+
+## In Progress
+
+| ID | Subject | Owner | Notes |
+|----|---------|-------|-------|
+| 1 | Build auth | alice | working |
+| 2 | Build API | alice | started |
+| 3 | Build UI | bob | working |
+
+## Blocked
+
+| ID | Subject | Owner | Blocked By | Notes |
+|----|---------|-------|-----------|-------|
+
+## Pending
+
+| ID | Subject | Owner | Blocked By | Notes |
+|----|---------|-------|-----------|-------|
+
+## Completed
+
+| ID | Subject | Owner | Notes |
+|----|---------|-------|-------|
+EOF
+rm -f "$COUNTER_DIR/t--alice"
+run_hook "$HOOK" '{"teammate_name":"alice","team_name":"t"}'
+assert_exit_code 2 "$HOOK_EXIT" "10: Multiple in-progress tasks blocks"
+assert_stderr_contains "2 task" "$HOOK_STDERR" "10: Reports 2 tasks (not 1 or 3)"
+cleanup_temp_dir
+
+# --- Test 11: Tasks in Blocked/Pending/Completed sections are ignored ---
+setup_temp_dir
+cd "$TEST_TEMP_DIR"
+mkdir -p ".agent-team/t"
+cat > ".agent-team/t/tasks.md" <<'EOF'
+# Tasks: t
+
+**Last updated**: 2026-01-01
+
+## In Progress
+
+| ID | Subject | Owner | Notes |
+|----|---------|-------|-------|
+
+## Blocked
+
+| ID | Subject | Owner | Blocked By | Notes |
+|----|---------|-------|-----------|-------|
+| 1 | Fix auth | alice | 2 | waiting |
+
+## Pending
+
+| ID | Subject | Owner | Blocked By | Notes |
+|----|---------|-------|-----------|-------|
+| 2 | Write tests | alice | — | not started |
+
+## Completed
+
+| ID | Subject | Owner | Notes |
+|----|---------|-------|-------|
+| 3 | Setup config | alice | done |
+EOF
+rm -f "$COUNTER_DIR/t--alice"
+run_hook "$HOOK" '{"teammate_name":"alice","team_name":"t"}'
+assert_exit_code 0 "$HOOK_EXIT" "11: Tasks in Blocked/Pending/Completed sections allow idle"
+cleanup_temp_dir
+
+# --- Test 12: Mixed sections — only In Progress counts ---
+setup_temp_dir
+cd "$TEST_TEMP_DIR"
+mkdir -p ".agent-team/t"
+cat > ".agent-team/t/tasks.md" <<'EOF'
+# Tasks: t
+
+**Last updated**: 2026-01-01
+
+## In Progress
+
+| ID | Subject | Owner | Notes |
+|----|---------|-------|-------|
+| 1 | Build auth | alice | working |
+
+## Blocked
+
+| ID | Subject | Owner | Blocked By | Notes |
+|----|---------|-------|-----------|-------|
+| 2 | Fix bug | alice | 3 | waiting on bob |
+
+## Pending
+
+| ID | Subject | Owner | Blocked By | Notes |
+|----|---------|-------|-----------|-------|
+| 3 | Deploy | alice | 1 | not started |
+
+## Completed
+
+| ID | Subject | Owner | Notes |
+|----|---------|-------|-------|
+| 4 | Setup env | alice | done |
+EOF
+rm -f "$COUNTER_DIR/t--alice"
+run_hook "$HOOK" '{"teammate_name":"alice","team_name":"t"}'
+assert_exit_code 2 "$HOOK_EXIT" "12: Mixed sections — only In Progress blocks (exit code)"
+assert_stderr_contains "1 task" "$HOOK_STDERR" "12: Reports 1 task (ignores Blocked/Pending/Completed)"
+cleanup_temp_dir
+
 # Final cleanup
 rm -rf "$COUNTER_DIR"