diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 432c93c..a9181d2 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": "2.3.0", + "version": "2.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 3ffc8ec..d05ccb9 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": "2.3.0", + "version": "2.4.0", "author": { "name": "Duc Do" } diff --git a/CHANGELOG.md b/CHANGELOG.md index c02866b..9e27338 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,21 @@ 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.4.0] - 2026-03-09 + +### Added +- **PROGRESS message type**: Optional granular progress reporting for long-running tasks +- **CHECKPOINT message type**: Intermediate results with downstream task notification +- **Confidence grades**: Optional `[X%]` annotation on reviewer/auditor findings +- **Priority marking**: Optional `priority={critical|high|normal|low}` on STARTING/HANDOFF +- **Checkpoint/Rollback pattern**: Save and resume long-running tasks at natural breakpoints +- **Deadline Escalation pattern**: Proactive time-based escalation for stalled tasks +- **Circular Dependency Detection**: DAG validation in Phase 2 to prevent deadlocks +- **Graceful Degradation pattern**: Controlled scope reduction under resource pressure +- **Warm vs Cold Handoff**: Context-level distinction for result handoffs +- **Anti-Pattern Catalog**: 8 documented coordination pitfalls with prevention/mitigation +- **Scaling Patterns documentation**: Read-only extension, phased execution, sub-agent specialization + ## [2.3.0] - 2026-03-09 ### Added diff --git a/CLAUDE.md b/CLAUDE.md index b56c30a..80a098c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -50,6 +50,7 @@ docs/ Shared phases + reference docs consumed by skills at runt | `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 | +| `.agent-team/0309-protocol-research/` | Research findings | Reference only — do not modify. Contains 4 reports on protocol, patterns, resilience, and scaling | ## Conventions diff --git a/README.md b/README.md index 7e940cf..681781b 100644 --- a/README.md +++ b/README.md @@ -173,6 +173,13 @@ HANDOFF #N: what I produced that another teammate needs QUESTION: what I need to know ``` +Optional extended messages for long-running tasks: + +``` +PROGRESS #N: milestone={desc}, percent={0-100}, eta={minutes} +CHECKPOINT #N: intermediate results, artifacts, ready_for=[task IDs] +``` + ## Hooks Five hooks enforce team discipline automatically: diff --git a/docs/communication-protocol.md b/docs/communication-protocol.md index abf60aa..538a929 100644 --- a/docs/communication-protocol.md +++ b/docs/communication-protocol.md @@ -5,6 +5,7 @@ Canonical definition of structured messages used by all teammates. The lead read ## Contents - [Structured Messages](#structured-messages) +- [Extended Messages (Optional)](#extended-messages-optional) - [Reviewer/Auditor Findings Format](#reviewerauditor-findings-format) - [Tester Results Format](#tester-results-format) - [Auditor Compliance Format](#auditor-compliance-format) @@ -23,6 +24,53 @@ HANDOFF #N: {what I produced that another teammate needs, key details} QUESTION: {what I need to know, what I already checked in workspace} ``` +## Extended Messages (Optional) + +These message types are optional enhancements. Teammates use them when the lead requests granular updates or when tasks are long-running. + +### Progress Reporting + +For long-running tasks (>5 minutes expected), teammates report intermediate progress: + +``` +PROGRESS #N: milestone={description}, percent={0-100}, eta={minutes or omitted} +``` + +Example: +``` +PROGRESS #5: milestone="security scan phase 2 of 4", percent=50, eta=3 +``` + +**Lead processing**: Log milestone in `tasks.md` Notes column. No workspace file update needed unless the milestone unblocks another task. + +### Checkpoint (Partial Completion) + +When a task produces intermediate artifacts that downstream tasks can consume early: + +``` +CHECKPOINT #N: {what was completed}, artifacts={file references}, ready_for=[task IDs] +``` + +Example: +``` +CHECKPOINT #5: completed 50/100 tests, early findings: 3 failures in auth module, artifacts=.agent-team/{team}/test-results-partial.md, ready_for=[6] +``` + +**Lead processing**: If `ready_for` lists task IDs, message the dependent teammate with the checkpoint details. Log in `progress.md` Handoffs section. + +### Priority Marking + +Teammates can signal task urgency in STARTING and HANDOFF messages: + +``` +STARTING #N: priority={critical|high|normal|low}, {what I plan to do, which files I'll touch} +HANDOFF #N: priority={critical|high|normal|low}, {what I produced, key details} +``` + +Default is `normal` — omit the field for routine work. Use `critical` only when the task blocks multiple teammates or has a deadline. + +**Lead processing**: Prioritize `critical` and `high` messages. For `critical` HANDOFF, forward immediately (don't batch). + ## Reviewer/Auditor Findings Format Use consistent severity labels with sequential numbering per severity within each task: @@ -31,6 +79,12 @@ Use consistent severity labels with sequential numbering per severity within eac - **M{n}** (medium — should fix): file:line, description - **L{n}** (low — suggestion): file:line, description +**Optional confidence grade**: Append `[X%]` to any finding when confidence is meaningful: +- `H1[95%]: src/auth.py:15, SQL injection via unsanitized input, fix: use parameterized query` +- `M2[60%]: src/api.py:42, possible race condition under load` + +Omit the grade when confidence is obviously high (most findings). Use it when a finding is uncertain or based on inference rather than direct evidence. + In COMPLETED messages, include total counts: "N issues: X high, Y medium, Z low" ## Tester Results Format diff --git a/docs/coordination-patterns.md b/docs/coordination-patterns.md index 89ad57d..90a1246 100644 --- a/docs/coordination-patterns.md +++ b/docs/coordination-patterns.md @@ -22,8 +22,13 @@ Patterns for the lead to handle common coordination scenarios during Phase 4. - [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 +- [Checkpoint/Rollback](#checkpointrollback) — save and resume long-running tasks +- [Deadline Escalation](#deadline-escalation) — time-based proactive escalation +- [Circular Dependency Detection](#circular-dependency-detection) — prevent deadlocks in Phase 2 +- [Graceful Degradation](#graceful-degradation) — scope reduction under resource pressure - [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 +- [Anti-Pattern Catalog](#anti-pattern-catalog) — known coordination pitfalls to avoid ## Communication Protocol @@ -201,6 +206,25 @@ When Teammate A produces output that Teammate B needs: Do NOT have teammates message each other directly for handoffs unless they need a back-and-forth discussion. The lead summarizing and forwarding keeps coordination clean and maintains the workspace audit trail. +### Warm vs Cold Handoff + +- **Warm handoff**: Lead forwards full context — what was done, why, key decisions, and specific next steps for the receiving teammate. Use when the handoff requires understanding of reasoning. + ``` + A finished task #3 (auth token refactor). Key changes: + - Moved token validation to src/auth/validate.ts + - New interface: TokenResult { valid: boolean, claims: Claims } + - Decision: used JWT over opaque tokens (see progress.md Decision Log) + You can now proceed with task #5 using the new TokenResult interface. + ``` + +- **Cold handoff**: Lead forwards minimal context — just file paths and a pointer to workspace. Use when the receiving teammate only needs to know what files to read. + ``` + A finished task #3. Output files: src/auth/validate.ts, src/auth/types.ts. + Check workspace tasks.md for full details. Proceed with task #5. + ``` + +**Default to warm handoffs** — the extra context costs little and prevents follow-up QUESTION messages. Use cold handoffs only when the downstream task is clearly independent (e.g., reviewer just needs to read files). + ## Teammate Not Responding If a teammate hasn't sent an update after an extended period: @@ -382,6 +406,156 @@ Completion criteria: Build exits 0 with no errors. Assign to the nearest available teammate (reviewer or tester preferred, implementer if no others are available). +## Checkpoint/Rollback + +Save consistent state at natural breakpoints during long-running tasks. Enables recovery from mid-task failures without losing completed work. + +### When to Use + +- Tasks expected to take >10 minutes +- Multi-step migrations, large refactors, or batch operations +- Any task where partial failure is possible and rework is expensive + +### Protocol + +1. **Lead instructs** in spawn prompt: "For long tasks, send CHECKPOINT messages at natural breakpoints (after each module, after each migration step, etc.)" +2. **Teammate sends** CHECKPOINT at each breakpoint: + ``` + CHECKPOINT #N: {what was completed}, artifacts={file references}, ready_for=[task IDs] + ``` +3. **Lead logs** checkpoint in `progress.md` Decision Log: "Checkpoint: task #N at [milestone]" +4. **On failure**: Lead messages teammate with last checkpoint context: + ``` + Resume from checkpoint. Last known state: + - Completed: {checkpoint description} + - Artifacts: {file references} + - Remaining: {what's left to do} + ``` +5. **If teammate is unrecoverable**: spawn replacement with checkpoint context in prompt + +### Workspace Integration + +- Checkpoints are logged in `progress.md` Decision Log (not a separate file) +- Checkpoint artifacts live in the workspace directory: `.agent-team/{team}/checkpoint-{task-id}.md` +- On task completion, checkpoint artifacts can be cleaned up or kept for audit + +### Key Rule + +Checkpoints are lightweight — a one-line CHECKPOINT message, not a full state dump. The workspace files (`tasks.md`, `issues.md`) already track team-level state. Checkpoints track task-level progress within a single teammate's scope. + +## Deadline Escalation + +Proactive time-based escalation to prevent tasks from exceeding the user's time budget. + +### When to Use + +- User has an implicit or explicit time constraint +- A task has been in_progress for an extended period with no PROGRESS or COMPLETED message +- The team session is approaching context limits + +### Protocol + +1. **Lead tracks** estimated task duration in `progress.md`: + ``` + **Session started**: {timestamp} + ``` +2. **Lead proactively checks** tasks that have been in_progress without updates: + ``` + Status check on task #N — it's been [duration] since your last update. + What's your progress? Use PROGRESS or COMPLETED format. + If blocked, use BLOCKED so I can log and route it. + ``` +3. **Escalation ladder**: + - **Nudge** (first check): request status update + - **Warn** (second check, ~5 min later): "Task #N is at risk. Need status or BLOCKED report." + - **Escalate** (third check): mark task as at-risk in `tasks.md`, consider reassignment or scope reduction +4. **Scope reduction option**: if task is too large, lead proposes splitting: + ``` + Task #N is taking longer than expected. Options: + a) Continue (estimated X more minutes) + b) Split: complete [partial scope], defer [remaining scope] as follow-up + c) Reassign to [other teammate] + ``` + +### Key Rule + +Deadline escalation is proactive, not punitive. The goal is visibility — silent tasks are the biggest risk to team throughput. Combine with the PROGRESS message type for teammates to self-report before escalation triggers. + +## Circular Dependency Detection + +Validate task dependency graphs before execution to prevent silent deadlocks. + +### When to Use + +- Phase 2 plan has 4+ tasks with `blocked by` relationships +- Any time tasks form chains longer than 2 levels deep + +### Protocol + +1. **During Phase 2**: Before presenting the plan, trace all dependency chains: + - For each task with `blocked by`, follow the chain: A blocks B blocks C... + - If any chain leads back to a task already visited, there's a cycle +2. **On cycle detected**: Do NOT present the plan. Instead, restructure: + - Option A: Merge the cyclic tasks into one (assign to same teammate) + - Option B: Remove the weakest dependency (the one where the blocker could be worked around) + - Option C: Split one task to break the cycle (the blocking portion runs first) +3. **Log**: Record the detected cycle and resolution in `progress.md` Decision Log + +### Example + +``` +Task #1: Set up database schema +Task #2: Write API endpoints (blocked by #1) +Task #3: Write migrations (blocked by #2) +Task #1 update: schema depends on migration format (blocked by #3) ← CYCLE + +Resolution: Merge #1 and #3 into single task "Database schema + migrations" +``` + +### Prevention + +The best prevention is Phase 1 decomposition by independent modules, not by sequential steps. If streams need constant handoffs, merge them. + +## Graceful Degradation + +Reduce scope rather than stopping when the team hits resource limits or unrecoverable blockers. + +### When to Use + +- Context window is running low (frequent compaction) +- Multiple teammates are blocked and remediation isn't viable +- User's time budget is exceeded but partial delivery has value + +### Protocol + +1. **Detect degradation trigger**: + - 2+ context compactions in short succession + - 3+ teammates blocked simultaneously + - Lead judges that full scope cannot be completed +2. **Assess salvageable work**: read `tasks.md` — which tasks are COMPLETED? What partial value exists? +3. **Present scope reduction to user**: + ``` + Scope reduction needed: [trigger reason] + + Completed work (will be preserved): + - [task IDs and summaries] + + Work to defer (will be logged as follow-up): + - [task IDs and summaries] + + Approve reduced scope? + ``` +4. **If approved**: + - Mark deferred tasks as `deferred` in `tasks.md` + - Shut down teammates working on deferred tasks + - Continue to Phase 5 with completed work only + - Include deferred items in report's Follow-up section +5. **Log**: Record scope reduction decision in `progress.md` Decision Log + +### Key Rule + +Graceful degradation is a controlled retreat, not a failure. The user gets partial value immediately and a clear list of what remains. This is always better than a team that burns context trying to finish everything and produces nothing. + ## Auto-Block on Repeated Failures Prevents teammates from spinning on the same error. Escalates automatically after repeated failures. @@ -433,3 +607,27 @@ For pre-approved information transfers between specific teammates, bypassing the ### Key Rule The audit trail MUST be maintained. Direct handoffs save time but must still be logged via the lead's workspace updates. + +## Anti-Pattern Catalog + +Known coordination anti-patterns to avoid. These emerge from research into multi-agent systems (CrewAI, AutoGen, LangGraph, MetaGPT) and distributed systems theory. + +### Critical (Prevent by Design) + +**Circular Wait Deadlock**: Tasks A→B→C→A where each blocks the next. Prevention: validate dependency DAG in Phase 2 (see [Circular Dependency Detection](#circular-dependency-detection)). + +**Race Condition on Shared State**: Two teammates simultaneously edit the same file; last write wins. Prevention: 1:1 file ownership mapping in Phase 2 + PreToolUse hook enforcement. + +**Context Overflow Cascade**: Workspace grows unbounded; teammates can't read full context; compaction fires repeatedly. Prevention: batch workspace updates, keep workspace files concise, use [Graceful Degradation](#graceful-degradation) when compaction frequency increases. + +**Infinite Re-Debate Loop**: Two teammates keep revisiting a completed decision. Prevention: once a task is COMPLETED, no further work on it unless explicitly reassigned by the lead. Log decisions in `progress.md` Decision Log as the authoritative record. + +### Warning (Monitor and Mitigate) + +**Silent Failure**: Teammate completes but sends no message — task appears blocked but is actually done. Mitigation: First Contact Verification + proactive check-ins. If idle 2+ cycles without any message, investigate. + +**Scope Explosion**: Team grows beyond lead's effective span of control (>6 agents). Mitigation: enforce team size limits in Phase 3; for >6, use hierarchical sub-leads or phased execution. + +**Single Point of Failure**: All work depends on one teammate; if they fail, the whole team stalls. Mitigation: avoid assigning >50% of tasks to any single teammate. For critical paths, ensure another teammate can take over. + +**Byzantine Output**: Teammate reports task complete but output is incorrect or hallucinated. Mitigation: Adversarial Review Rounds for critical tasks; verify file changes actually exist before marking tasks complete (TaskCompleted hook already does this for implementers). diff --git a/docs/plans/2026-03-09-protocol-and-patterns-improvement.md b/docs/plans/2026-03-09-protocol-and-patterns-improvement.md new file mode 100644 index 0000000..d441e2a --- /dev/null +++ b/docs/plans/2026-03-09-protocol-and-patterns-improvement.md @@ -0,0 +1,750 @@ +# Protocol & Coordination Patterns Improvement Plan + +**Status:** COMPLETED — Implemented via team 0309-protocol-improvement, released as v2.4.0 (2026-03-09) + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** Enhance the agent-team plugin's communication protocol, coordination patterns, and resilience based on research findings from team 0309-protocol-research. + +**Architecture:** All changes are documentation-only (docs/*.md). No hook scripts, no SKILL.md frontmatter changes, no code changes. Each task adds a self-contained section to an existing doc file. The protocol remains additive and backward-compatible — existing 5-prefix messages are unchanged. + +**Tech Stack:** Markdown documentation files, bash test scripts + +**Reference:** `.agent-team/0309-protocol-research/final-report.md` — synthesized research from 4 parallel streams + +--- + +### Task 1: Add PROGRESS and CHECKPOINT message types to communication protocol + +**Files:** +- Modify: `docs/communication-protocol.md` + +**Step 1: Read the current file** + +Read `docs/communication-protocol.md` to confirm current structure (Contents, Structured Messages, then role-specific formats). + +**Step 2: Add PROGRESS and CHECKPOINT to Structured Messages** + +After the existing 5-prefix code block (lines 18-24), add two new optional message types. Edit the code block to become: + +``` +STARTING #N: {what I plan to do, which files I'll touch} +COMPLETED #N: {what I did, files changed, any concerns} +BLOCKED #N: severity={critical|high|medium|low}, {what's blocking}, impact={what can't proceed} +HANDOFF #N: {what I produced that another teammate needs, key details} +QUESTION: {what I need to know, what I already checked in workspace} +``` + +Then add a new section `## Extended Messages (Optional)` after the Structured Messages section, before the Reviewer/Auditor format: + +```markdown +## Extended Messages (Optional) + +These message types are optional enhancements. Teammates use them when the lead requests granular updates or when tasks are long-running. + +### Progress Reporting + +For long-running tasks (>5 minutes expected), teammates report intermediate progress: + +``` +PROGRESS #N: milestone={description}, percent={0-100}, eta={minutes or omitted} +``` + +Example: +``` +PROGRESS #5: milestone="security scan phase 2 of 4", percent=50, eta=3 +``` + +**Lead processing**: Log milestone in `tasks.md` Notes column. No workspace file update needed unless the milestone unblocks another task. + +### Checkpoint (Partial Completion) + +When a task produces intermediate artifacts that downstream tasks can consume early: + +``` +CHECKPOINT #N: {what was completed}, artifacts={file references}, ready_for=[task IDs] +``` + +Example: +``` +CHECKPOINT #5: completed 50/100 tests, early findings: 3 failures in auth module, artifacts=.agent-team/{team}/test-results-partial.md, ready_for=[6] +``` + +**Lead processing**: If `ready_for` lists task IDs, message the dependent teammate with the checkpoint details. Log in `progress.md` Handoffs section. +``` + +**Step 3: Run tests to verify doc references still resolve** + +Run: `bash tests/run-tests.sh` +Expected: All tests pass (no new doc refs added, only content within existing file) + +**Step 4: Commit** + +```bash +git add docs/communication-protocol.md +git commit -m "feat: add PROGRESS and CHECKPOINT optional message types to protocol" +``` + +--- + +### Task 2: Add confidence grades and priority marking to protocol + +**Files:** +- Modify: `docs/communication-protocol.md` + +**Step 1: Add confidence grades to Reviewer/Auditor Findings Format** + +After the existing H/M/L format (lines 30-33), add an optional confidence annotation. Edit the section to read: + +```markdown +## Reviewer/Auditor Findings Format + +Use consistent severity labels with sequential numbering per severity within each task: + +- **H{n}** (high — must fix): file:line, description, suggested fix +- **M{n}** (medium — should fix): file:line, description +- **L{n}** (low — suggestion): file:line, description + +**Optional confidence grade**: Append `[X%]` to any finding when confidence is meaningful: +- `H1[95%]: src/auth.py:15, SQL injection via unsanitized input, fix: use parameterized query` +- `M2[60%]: src/api.py:42, possible race condition under load` + +Omit the grade when confidence is obviously high (most findings). Use it when a finding is uncertain or based on inference rather than direct evidence. + +In COMPLETED messages, include total counts: "N issues: X high, Y medium, Z low" +``` + +**Step 2: Add priority marking to Structured Messages section** + +In the Extended Messages section (added in Task 1), add a Priority Marking subsection: + +```markdown +### Priority Marking + +Teammates can signal task urgency in STARTING and HANDOFF messages: + +``` +STARTING #N: priority={critical|high|normal|low}, {what I plan to do, which files I'll touch} +HANDOFF #N: priority={critical|high|normal|low}, {what I produced, key details} +``` + +Default is `normal` — omit the field for routine work. Use `critical` only when the task blocks multiple teammates or has a deadline. + +**Lead processing**: Prioritize `critical` and `high` messages. For `critical` HANDOFF, forward immediately (don't batch). +``` + +**Step 3: Run tests** + +Run: `bash tests/run-tests.sh` +Expected: All tests pass + +**Step 4: Commit** + +```bash +git add docs/communication-protocol.md +git commit -m "feat: add confidence grades and priority marking to protocol" +``` + +--- + +### Task 3: Add Checkpoint/Rollback coordination pattern + +**Files:** +- Modify: `docs/coordination-patterns.md` + +**Step 1: Read the current file to identify insertion point** + +Read `docs/coordination-patterns.md`. New patterns go before the existing "## Auto-Block on Repeated Failures" section (around line 385). + +**Step 2: Add Checkpoint/Rollback pattern** + +Insert a new section before Auto-Block on Repeated Failures: + +```markdown +## Checkpoint/Rollback + +Save consistent state at natural breakpoints during long-running tasks. Enables recovery from mid-task failures without losing completed work. + +### When to Use + +- Tasks expected to take >10 minutes +- Multi-step migrations, large refactors, or batch operations +- Any task where partial failure is possible and rework is expensive + +### Protocol + +1. **Lead instructs** in spawn prompt: "For long tasks, send CHECKPOINT messages at natural breakpoints (after each module, after each migration step, etc.)" +2. **Teammate sends** CHECKPOINT at each breakpoint: + ``` + CHECKPOINT #N: {what was completed}, artifacts={file references}, ready_for=[task IDs] + ``` +3. **Lead logs** checkpoint in `progress.md` Decision Log: "Checkpoint: task #N at [milestone]" +4. **On failure**: Lead messages teammate with last checkpoint context: + ``` + Resume from checkpoint. Last known state: + - Completed: {checkpoint description} + - Artifacts: {file references} + - Remaining: {what's left to do} + ``` +5. **If teammate is unrecoverable**: spawn replacement with checkpoint context in prompt + +### Workspace Integration + +- Checkpoints are logged in `progress.md` Decision Log (not a separate file) +- Checkpoint artifacts live in the workspace directory: `.agent-team/{team}/checkpoint-{task-id}.md` +- On task completion, checkpoint artifacts can be cleaned up or kept for audit + +### Key Rule + +Checkpoints are lightweight — a one-line CHECKPOINT message, not a full state dump. The workspace files (`tasks.md`, `issues.md`) already track team-level state. Checkpoints track task-level progress within a single teammate's scope. +``` + +**Step 3: Update the Contents list** + +Add `- [Checkpoint/Rollback](#checkpointrollback) — save and resume long-running tasks` to the Contents list in the appropriate position (after Quality Gate). + +**Step 4: Run tests** + +Run: `bash tests/run-tests.sh` +Expected: All tests pass + +**Step 5: Commit** + +```bash +git add docs/coordination-patterns.md +git commit -m "feat: add checkpoint/rollback coordination pattern" +``` + +--- + +### Task 4: Add Deadline/Timeout Escalation coordination pattern + +**Files:** +- Modify: `docs/coordination-patterns.md` + +**Step 1: Add Deadline Escalation pattern** + +Insert after the Checkpoint/Rollback section added in Task 3: + +```markdown +## Deadline Escalation + +Proactive time-based escalation to prevent tasks from exceeding the user's time budget. + +### When to Use + +- User has an implicit or explicit time constraint +- A task has been in_progress for an extended period with no PROGRESS or COMPLETED message +- The team session is approaching context limits + +### Protocol + +1. **Lead tracks** estimated task duration in `progress.md`: + ``` + **Session started**: {timestamp} + ``` +2. **Lead proactively checks** tasks that have been in_progress without updates: + ``` + Status check on task #N — it's been [duration] since your last update. + What's your progress? Use PROGRESS or COMPLETED format. + If blocked, use BLOCKED so I can log and route it. + ``` +3. **Escalation ladder**: + - **Nudge** (first check): request status update + - **Warn** (second check, ~5 min later): "Task #N is at risk. Need status or BLOCKED report." + - **Escalate** (third check): mark task as at-risk in `tasks.md`, consider reassignment or scope reduction +4. **Scope reduction option**: if task is too large, lead proposes splitting: + ``` + Task #N is taking longer than expected. Options: + a) Continue (estimated X more minutes) + b) Split: complete [partial scope], defer [remaining scope] as follow-up + c) Reassign to [other teammate] + ``` + +### Key Rule + +Deadline escalation is proactive, not punitive. The goal is visibility — silent tasks are the biggest risk to team throughput. Combine with the PROGRESS message type for teammates to self-report before escalation triggers. +``` + +**Step 2: Update the Contents list** + +Add `- [Deadline Escalation](#deadline-escalation) — time-based proactive escalation` to the Contents list. + +**Step 3: Run tests** + +Run: `bash tests/run-tests.sh` +Expected: All tests pass + +**Step 4: Commit** + +```bash +git add docs/coordination-patterns.md +git commit -m "feat: add deadline escalation coordination pattern" +``` + +--- + +### Task 5: Add Circular Dependency Detection to Phase 2 + +**Files:** +- Modify: `docs/shared-phases.md` +- Modify: `docs/coordination-patterns.md` + +**Step 1: Add DAG validation step to Phase 2 in shared-phases.md** + +In shared-phases.md, Phase 2 plan presentation section (around line 51), add a new self-check. The existing self-check block (lines 87-89) has 2 numbered checks. Append a 3rd check after check #2 (line 89), before "Wait for user confirmation": + +```markdown +3. "Do any tasks form circular dependencies? Trace each `blocked by` chain — if task A blocks B blocks C blocks A, that's a cycle. If found, restructure: merge the cyclic tasks or break the cycle by removing one dependency." +``` + +**Step 2: Add Circular Dependency Detection pattern to coordination-patterns.md** + +Insert after Deadline Escalation: + +```markdown +## Circular Dependency Detection + +Validate task dependency graphs before execution to prevent silent deadlocks. + +### When to Use + +- Phase 2 plan has 4+ tasks with `blocked by` relationships +- Any time tasks form chains longer than 2 levels deep + +### Protocol + +1. **During Phase 2**: Before presenting the plan, trace all dependency chains: + - For each task with `blocked by`, follow the chain: A blocks B blocks C... + - If any chain leads back to a task already visited, there's a cycle +2. **On cycle detected**: Do NOT present the plan. Instead, restructure: + - Option A: Merge the cyclic tasks into one (assign to same teammate) + - Option B: Remove the weakest dependency (the one where the blocker could be worked around) + - Option C: Split one task to break the cycle (the blocking portion runs first) +3. **Log**: Record the detected cycle and resolution in `progress.md` Decision Log + +### Example + +``` +Task #1: Set up database schema +Task #2: Write API endpoints (blocked by #1) +Task #3: Write migrations (blocked by #2) +Task #1 update: schema depends on migration format (blocked by #3) ← CYCLE + +Resolution: Merge #1 and #3 into single task "Database schema + migrations" +``` + +### Prevention + +The best prevention is Phase 1 decomposition by independent modules, not by sequential steps. If streams need constant handoffs, merge them. +``` + +**Step 3: Update the Contents list in coordination-patterns.md** + +Add `- [Circular Dependency Detection](#circular-dependency-detection) — prevent deadlocks in Phase 2`. + +**Step 4: Run tests** + +Run: `bash tests/run-tests.sh` +Expected: All tests pass + +**Step 5: Commit** + +```bash +git add docs/shared-phases.md docs/coordination-patterns.md +git commit -m "feat: add circular dependency detection to Phase 2 and coordination patterns" +``` + +--- + +### Task 6: Add Graceful Degradation coordination pattern + +**Files:** +- Modify: `docs/coordination-patterns.md` + +**Step 1: Add Graceful Degradation pattern** + +Insert after Circular Dependency Detection: + +```markdown +## Graceful Degradation + +Reduce scope rather than stopping when the team hits resource limits or unrecoverable blockers. + +### When to Use + +- Context window is running low (frequent compaction) +- Multiple teammates are blocked and remediation isn't viable +- User's time budget is exceeded but partial delivery has value + +### Protocol + +1. **Detect degradation trigger**: + - 2+ context compactions in short succession + - 3+ teammates blocked simultaneously + - Lead judges that full scope cannot be completed +2. **Assess salvageable work**: read `tasks.md` — which tasks are COMPLETED? What partial value exists? +3. **Present scope reduction to user**: + ``` + Scope reduction needed: [trigger reason] + + Completed work (will be preserved): + - [task IDs and summaries] + + Work to defer (will be logged as follow-up): + - [task IDs and summaries] + + Approve reduced scope? + ``` +4. **If approved**: + - Mark deferred tasks as `deferred` in `tasks.md` + - Shut down teammates working on deferred tasks + - Continue to Phase 5 with completed work only + - Include deferred items in report's Follow-up section +5. **Log**: Record scope reduction decision in `progress.md` Decision Log + +### Key Rule + +Graceful degradation is a controlled retreat, not a failure. The user gets partial value immediately and a clear list of what remains. This is always better than a team that burns context trying to finish everything and produces nothing. +``` + +**Step 2: Update the Contents list** + +Add `- [Graceful Degradation](#graceful-degradation) — scope reduction under resource pressure`. + +**Step 3: Run tests** + +Run: `bash tests/run-tests.sh` +Expected: All tests pass + +**Step 4: Commit** + +```bash +git add docs/coordination-patterns.md +git commit -m "feat: add graceful degradation coordination pattern" +``` + +--- + +### Task 7: Add Warm vs Cold Handoff distinction + +**Files:** +- Modify: `docs/coordination-patterns.md` + +**Step 1: Enhance the existing Result Handoff Between Teammates section** + +In coordination-patterns.md, find the "Result Handoff Between Teammates" section (around line 194). Add a subsection at the end: + +```markdown +### Warm vs Cold Handoff + +- **Warm handoff**: Lead forwards full context — what was done, why, key decisions, and specific next steps for the receiving teammate. Use when the handoff requires understanding of reasoning. + ``` + A finished task #3 (auth token refactor). Key changes: + - Moved token validation to src/auth/validate.ts + - New interface: TokenResult { valid: boolean, claims: Claims } + - Decision: used JWT over opaque tokens (see progress.md Decision Log) + You can now proceed with task #5 using the new TokenResult interface. + ``` + +- **Cold handoff**: Lead forwards minimal context — just file paths and a pointer to workspace. Use when the receiving teammate only needs to know what files to read. + ``` + A finished task #3. Output files: src/auth/validate.ts, src/auth/types.ts. + Check workspace tasks.md for full details. Proceed with task #5. + ``` + +**Default to warm handoffs** — the extra context costs little and prevents follow-up QUESTION messages. Use cold handoffs only when the downstream task is clearly independent (e.g., reviewer just needs to read files). +``` + +**Step 2: Run tests** + +Run: `bash tests/run-tests.sh` +Expected: All tests pass + +**Step 3: Commit** + +```bash +git add docs/coordination-patterns.md +git commit -m "feat: add warm vs cold handoff distinction to result handoff pattern" +``` + +--- + +### Task 8: Add Anti-Pattern Catalog + +**Files:** +- Modify: `docs/coordination-patterns.md` + +**Step 1: Add Anti-Pattern Catalog section** + +Add at the very end of coordination-patterns.md, after the Direct Handoff section: + +```markdown +## Anti-Pattern Catalog + +Known coordination anti-patterns to avoid. These emerge from research into multi-agent systems (CrewAI, AutoGen, LangGraph, MetaGPT) and distributed systems theory. + +### Critical (Prevent by Design) + +**Circular Wait Deadlock**: Tasks A→B→C→A where each blocks the next. Prevention: validate dependency DAG in Phase 2 (see [Circular Dependency Detection](#circular-dependency-detection)). + +**Race Condition on Shared State**: Two teammates simultaneously edit the same file; last write wins. Prevention: 1:1 file ownership mapping in Phase 2 + PreToolUse hook enforcement. + +**Context Overflow Cascade**: Workspace grows unbounded; teammates can't read full context; compaction fires repeatedly. Prevention: batch workspace updates, keep workspace files concise, use [Graceful Degradation](#graceful-degradation) when compaction frequency increases. + +**Infinite Re-Debate Loop**: Two teammates keep revisiting a completed decision. Prevention: once a task is COMPLETED, no further work on it unless explicitly reassigned by the lead. Log decisions in `progress.md` Decision Log as the authoritative record. + +### Warning (Monitor and Mitigate) + +**Silent Failure**: Teammate completes but sends no message — task appears blocked but is actually done. Mitigation: First Contact Verification + proactive check-ins. If idle 2+ cycles without any message, investigate. + +**Scope Explosion**: Team grows beyond lead's effective span of control (>6 agents). Mitigation: enforce team size limits in Phase 3; for >6, use hierarchical sub-leads or phased execution. + +**Single Point of Failure**: All work depends on one teammate; if they fail, the whole team stalls. Mitigation: avoid assigning >50% of tasks to any single teammate. For critical paths, ensure another teammate can take over. + +**Byzantine Output**: Teammate reports task complete but output is incorrect or hallucinated. Mitigation: Adversarial Review Rounds for critical tasks; verify file changes actually exist before marking tasks complete (TaskCompleted hook already does this for implementers). +``` + +**Step 2: Update the Contents list** + +Add `- [Anti-Pattern Catalog](#anti-pattern-catalog) — known coordination pitfalls to avoid` to Contents. + +**Step 3: Run tests** + +Run: `bash tests/run-tests.sh` +Expected: All tests pass + +**Step 4: Commit** + +```bash +git add docs/coordination-patterns.md +git commit -m "feat: add anti-pattern catalog to coordination patterns" +``` + +--- + +### Task 9: Document scaling best practices in team-archetypes.md + +**Files:** +- Modify: `docs/team-archetypes.md` + +**Step 1: Add Scaling Patterns section** + +After the "Design Notes" section and before "See Also", add: + +```markdown +## Scaling Patterns + +When team size exceeds the default 4-6 limit, use these patterns. They are ordered by complexity — try simpler patterns first. + +### Read-Only Extension (5-6 agents) + +Add 1-2 read-only teammates (Researchers, Reviewers with `subagent_type: "Explore"`) to a standard 4-agent team. Zero file conflict risk, minimal coordination overhead. + +**When to use**: Need parallel investigation alongside implementation. + +**Example Phase 2 plan**: +``` +Teammates (6 total): +⚠ Team size check: 6 agents (4 core + 2 read-only researchers) +- impl-1 (Implementer): backend auth refactor -> owns src/auth/ +- impl-2 (Implementer): frontend auth UI -> owns src/components/auth/ +- reviewer (Reviewer): code quality review -> read-only +- tester (Tester): verify auth flows -> read-only +- perf-analyst (Researcher): performance impact analysis -> read-only (Explore) +- sec-researcher (Researcher): security implications -> read-only (Explore) +``` + +### Phased Execution (12-16+ agents over time) + +Break large projects into sequential team waves. Each phase is an independent team (4-6 agents). Workspace carries forward between phases. + +**When to use**: Clear sequential stages (research → design → implement → test). + +**Protocol**: +1. Run Phase 1 team (e.g., 3 researchers), collect findings +2. Present findings to user, get approval for Phase 2 +3. TeamDelete Phase 1, create Phase 2 team (e.g., 4 implementers) reusing same workspace +4. Repeat for Phase 3 (verification) + +**Key constraint**: Each phase waits for the previous to complete. High wall-clock time but low concurrent token cost. + +### Sub-Agent Specialization (within 4-6 agents) + +Senior implementers spawn subagents for independent subtasks within their scope. Multiplies throughput without multiplying team coordination. + +**When to use**: A single teammate's task is large enough to parallelize internally. + +**Already supported**: See [teammate-roles.md Nested Task Decomposition](teammate-roles.md#nested-task-decomposition-senior-implementers). One level of nesting max. +``` + +**Step 2: Run tests** + +Run: `bash tests/run-tests.sh` +Expected: All tests pass + +**Step 3: Commit** + +```bash +git add docs/team-archetypes.md +git commit -m "feat: document scaling patterns in team archetypes" +``` + +--- + +### Task 10: Update shared-phases.md Lead Processing Rules for new message types + +**Files:** +- Modify: `docs/shared-phases.md` + +**Step 1: Add PROGRESS and CHECKPOINT to Lead Processing Rules** + +In shared-phases.md Phase 4 section, find the Lead Processing Rules table (around line 204-210). Add two new rows: + +```markdown +| PROGRESS | Note milestone in `tasks.md` Notes column. If percent indicates near-completion, no action needed. If stalled, trigger Deadline Escalation | +| CHECKPOINT | If `ready_for` lists task IDs, forward checkpoint details to dependent teammate. Log in `progress.md` Handoffs | +``` + +**Step 2: Run tests** + +Run: `bash tests/run-tests.sh` +Expected: All tests pass + +**Step 3: Commit** + +```bash +git add docs/shared-phases.md +git commit -m "feat: add PROGRESS and CHECKPOINT to lead processing rules" +``` + +--- + +### Task 11: Update README.md with new protocol and patterns + +**Files:** +- Modify: `README.md` + +**Step 1: Update Communication Protocol section** + +In README.md, find the Communication Protocol section (line 164). Add the two new optional message types after the existing 5: + +```markdown +### Communication Protocol + +Teammates use structured messages for clean coordination: + +``` +STARTING #N: what I plan to do, which files I'll touch +COMPLETED #N: what I did, files changed, any concerns +BLOCKED #N: severity={level}, what's blocking, impact +HANDOFF #N: what I produced that another teammate needs +QUESTION: what I need to know +``` + +Optional extended messages for long-running tasks: + +``` +PROGRESS #N: milestone={desc}, percent={0-100}, eta={minutes} +CHECKPOINT #N: intermediate results, artifacts, ready_for=[task IDs] +``` +``` + +**Step 2: Run tests** + +Run: `bash tests/run-tests.sh` +Expected: All tests pass + +**Step 3: Commit** + +```bash +git add README.md +git commit -m "docs: update README with new protocol message types" +``` + +--- + +### Task 12: Update CLAUDE.md to reference new patterns and research + +**Files:** +- Modify: `CLAUDE.md` + +**Step 1: Verify research workspace exists** + +Run: `ls .agent-team/0309-protocol-research/final-report.md` +Expected: File exists. If not, this task should be skipped (the reference would be dangling). + +**Step 2: Add research reference to CLAUDE.md** + +In the File Ownership table, add a row for the research workspace: + +```markdown +| `.agent-team/0309-protocol-research/` | Research findings | Reference only — do not modify. Contains 4 reports on protocol, patterns, resilience, and scaling | +``` + +**Step 3: Run full test suite** + +Run: `bash tests/run-tests.sh` +Expected: All tests pass (final verification) + +**Step 4: Commit** + +```bash +git add CLAUDE.md +git commit -m "docs: add research findings reference to CLAUDE.md" +``` + +--- + +### Task 13: Final verification and version bump + +**Files:** +- Modify: `.claude-plugin/plugin.json` +- Modify: `.claude-plugin/marketplace.json` +- Modify: `package.json` +- Modify: `CHANGELOG.md` + +**Step 1: Run full test suite** + +Run: `bash tests/run-tests.sh` +Expected: All 78+ assertions pass + +**Step 2: Bump version to 2.4.0** + +Update version in all three files from `2.3.0` to `2.4.0`: +- `.claude-plugin/plugin.json`: `"version": "2.4.0"` +- `.claude-plugin/marketplace.json`: `"version": "2.4.0"` +- `package.json`: `"version": "2.4.0"` + +**Step 3: Add CHANGELOG entry** + +Add to top of CHANGELOG.md: + +```markdown +## 2.4.0 + +### Added +- **PROGRESS message type**: Optional granular progress reporting for long-running tasks +- **CHECKPOINT message type**: Intermediate results with downstream task notification +- **Confidence grades**: Optional `[X%]` annotation on reviewer/auditor findings +- **Priority marking**: Optional `priority={critical|high|normal|low}` on STARTING/HANDOFF +- **Checkpoint/Rollback pattern**: Save and resume long-running tasks at natural breakpoints +- **Deadline Escalation pattern**: Proactive time-based escalation for stalled tasks +- **Circular Dependency Detection**: DAG validation in Phase 2 to prevent deadlocks +- **Graceful Degradation pattern**: Controlled scope reduction under resource pressure +- **Warm vs Cold Handoff**: Context-level distinction for result handoffs +- **Anti-Pattern Catalog**: 8 documented coordination pitfalls with prevention/mitigation +- **Scaling Patterns documentation**: Read-only extension, phased execution, sub-agent specialization +``` + +**Step 4: Validate plugin** + +Run: `claude plugin validate .` +Expected: Validation passes + +**Step 5: Commit** + +```bash +git add .claude-plugin/plugin.json .claude-plugin/marketplace.json package.json CHANGELOG.md +git commit -m "chore: bump version to 2.4.0" +``` diff --git a/docs/plans/2026-03-09-split-skills-by-archetype.md b/docs/plans/2026-03-09-split-skills-by-archetype.md new file mode 100644 index 0000000..05de6af --- /dev/null +++ b/docs/plans/2026-03-09-split-skills-by-archetype.md @@ -0,0 +1,996 @@ +# Split Agent-Team Skill by Archetype — Implementation Plan + +**Status:** COMPLETED — Merged to main via `0362627` (2026-03-09) + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** Split the monolithic `/agent-team` SKILL.md into 5 focused skills — one per archetype — plus a shared phases doc, eliminating conditional branching from each skill prompt. + +**Architecture:** Extract shared logic (Phase 1 analysis, Phase 2 plan presentation, Phase 4 coordination) into `docs/shared-phases.md`. Create 4 new archetype-specific skills (`agent-research`, `agent-audit`, `agent-implement`, `agent-plan`) and slim down `agent-team` to be the Hybrid catch-all. Each skill references shared docs but contains only its archetype-specific Phase 3 and Phase 5 behavior. + +**Tech Stack:** Markdown (SKILL.md frontmatter), Bash (test scripts) + +--- + +### Task 1: Create `docs/shared-phases.md` — extract shared logic + +**Files:** +- Create: `docs/shared-phases.md` + +**Step 1: Write the shared phases doc** + +Extract from current `skills/agent-team/SKILL.md` the sections that are identical across all archetypes: + +```markdown +# Shared Phases Reference + +Shared phase logic for all agent-team archetype skills. Each archetype skill references this file for Phases 1, 2, and 4. + +## Orchestrator Identity + +You are the **Team Lead**. Your sole job is coordination — you never write code directly. You maintain a persistent workspace that tracks everything the team does. + +For your full role definition, see [teammate-roles.md](teammate-roles.md) under "Leader". + +## Prerequisites + +Agent Teams require the experimental feature flag. Before proceeding, verify it is enabled: +- Check if TeamCreate tool is available +- If not, tell the user: "Agent Teams requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in your settings.json env or shell environment. Please enable it and restart." +- Do NOT proceed until TeamCreate is available + +**Recommended**: Tell the user to press Shift+Tab to enable delegate mode, which restricts you to coordination-only tools. This reinforces the Zero-Code Rule. + +## Hooks + +This plugin registers hooks at the plugin level via `hooks/hooks.json`. They enforce team discipline automatically: + +- **TaskCompleted** (`scripts/verify-task-complete.sh`): Blocks premature task completion — checks workspace files exist and implementation tasks have actual file changes. Uses `teammate_name` and `file-locks.json` to scope git checks to the teammate's owned files when available. Requires `jq`. +- **TeammateIdle** (`scripts/check-teammate-idle.sh`): Nudges idle teammates that still have in-progress tasks. Includes loop protection (allows idle after 3 blocked attempts). Requires `jq`. +- **SessionStart(compact)** (`scripts/recover-context.sh`): After context compaction, automatically outputs active workspace paths and recovery instructions. Non-blocking. +- **PreToolUse(Write|Edit)** (`scripts/check-file-ownership.sh`): Enforces file ownership via `file-locks.json`. Warn-then-block: first violation warns, second blocks. Workspace files (`.agent-team/`) always allowed. Requires `jq`. +- **SubagentStart / SubagentStop** (`scripts/track-teammate-lifecycle.sh`): Logs teammate spawn and stop events to `.agent-team/{team}/events.log`. Non-blocking. + +All hooks exit 0 (allow) if their dependencies are missing — they degrade gracefully. Hook paths use `${CLAUDE_PLUGIN_ROOT}`. + +## Phase 1: Analyze and Decompose + +Analyze the user's task: $ARGUMENTS + +1. **Identify independent work streams** — what can run in parallel without blocking? +2. **Identify sequential dependencies** — what MUST happen in order? +3. **Determine if a team is warranted** — if fewer than 2 independent streams exist, tell the user a single session is more efficient and stop here. +4. **Map file ownership** — each teammate owns distinct files. No two teammates edit the same file. +5. **Decomposition strategies** — choose the split that maximizes parallelism: + - **By module/area**: frontend vs backend, auth vs payments (best for feature work) + - **By concern**: implementation vs verification vs research (best for quality-critical tasks) + - **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. **Identify reference documents** — find specs, ADRs, design docs, PRs, or other docs relevant to the task. These populate the workspace References section in Phase 3. +7. **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. +8. **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. + +## Phase 2: Present Plan to User (MANDATORY — DO NOT SKIP) + +Before creating the team, you MUST present the decomposition and wait for explicit user approval. This is a hard gate — no tasks, no teammates, no workspace until the user says "yes". + +``` +Team plan for: [task summary] +Team type: [detected-type] (auto-detected from task — say "change to [type]" to override) +Complexity: standard | complex + (if complex) Reason: [why — e.g., multi-module, risky refactor, security-sensitive] + (if complex) ✓ Dedicated reviewer included + (if complex) ✓ Dedicated tester included + +Teammates (N total): +⚠ Team size check: [default max 4 | up to 6 if extra are read-only] +- [role-name]: [what they do] -> owns [files/area] +- [role-name]: [what they do] -> owns [files/area] + +Task breakdown: +1. [task] -> assigned to [role] +2. [task] -> assigned to [role] +3. [task] -> assigned to [role] (blocked by #1) + +Every phase has an owner (omit for pure review tasks): +- Setup/config: [role] +- Implementation: [role(s)] +- Verification: [role] +- Testing: [role] (required for complex plans) +- Finalization: [role] + +Isolation: shared (default) | worktree + (if worktree) Each implementer gets a git worktree with a dedicated branch. Zero conflict risk. + +Workspace: .agent-team/[team-name]/ +Estimated teammates: N +``` + +**Self-check before proceeding**: +1. "Is this plan complex? Complexity signals: multi-module/area changes, architectural decisions, risky refactors, multiple implementers with cross-dependencies, security-sensitive changes, new integrations. If yes, does the teammate list include a **dedicated reviewer** AND a **dedicated tester** (separate teammates, not combined)? If no, add them before presenting." +2. "Have I presented this plan AND received user confirmation?" If no, STOP. + +Wait for user confirmation before proceeding. + +## Phase 3: Create Team (shared steps) + +Steps shared by all archetypes. Archetype-specific overrides (file-locks, branches, roles) are in each skill's own Phase 3 section. + +1. **Check for existing team** — read `~/.claude/teams/` to see if a team already exists. If one does, ask the user whether to clean it up first or work within it. + +2. **Create team**: + ``` + TeamCreate: team-name = MMDD-{task-slug} (e.g., "0304-refactor-auth", "0304-review-pr-142") + The MMDD prefix is today's date. This prevents name collisions across sessions and makes workspaces chronologically sortable. + ``` + +3. **Initialize workspace** — immediately after TeamCreate, create the workspace directory and all 3 tracking files: + ``` + mkdir -p .agent-team/{team-name} + ``` + Use the templates from [workspace-templates.md](workspace-templates.md) to create: + - `.agent-team/{team-name}/progress.md` — team status, members, decisions, handoffs + - `.agent-team/{team-name}/tasks.md` — task ledger with status tracking + - `.agent-team/{team-name}/issues.md` — issue tracker with severity and impact + + Populate the `## References` section in `progress.md` with docs identified in Phase 1. If no reference docs were found, leave the table with a single `—` row. + + The workspace is your persistent memory AND the team's shared state. It MUST exist before any tasks are created. + + If a `.gitignore` exists and doesn't already exclude `.agent-team/`, add it. Workspace files are coordination artifacts, not project deliverables. + +4. **Create ALL tasks upfront** with dependencies: + - Use TaskCreate for each work item + - Use TaskUpdate to set blockedBy relationships + - Target 2-6 tasks per teammate (2-3 for focused reviews, 4-6 for implementation). 1:1 is acceptable when each stream is a single cohesive investigation (audit, deep research) + - Every task must have clear completion criteria in its description + - A good task is **completable in one focused session** and produces a **verifiable artifact** (a file changed, a test passing, a report written). If a task requires "implement the whole backend", it's too broad — split it. If a task is "add one import statement", it's too narrow — bundle it into an adjacent task. + - **Update workspace**: record all tasks in `tasks.md` + - **Self-check**: "Does every task have a verifiable completion criterion — something a teammate can confirm as done or not done?" If any task says just "implement X" without a success condition, rewrite it. + +5. **Spawn teammates** using the Task tool with `team_name`, `name`, and `subagent_type` parameters. See [teammate-roles.md](teammate-roles.md) for role-specific spawn templates. + + **subagent_type**: `"general-purpose"` for full tool access (implementers, challengers, testers). `"Explore"` for read-only research teammates. `"general-purpose"` if a reviewer needs Bash. Optionally set `mode: "plan"` for risky or architectural tasks. + + **Protocol injection**: Before building spawn prompts, read [communication-protocol.md](communication-protocol.md). Substitute the `{COMMUNICATION_PROTOCOL}` placeholder in each role's spawn template with the Structured Messages block. For roles with format placeholders (`{FINDINGS_FORMAT}`, `{RESULTS_FORMAT}`, `{REPORT_FORMAT}`), substitute the matching section from the same file. + + Every spawn prompt MUST include: + + Identity: + 1. Role and responsibilities + 2. Assigned task IDs + 3. Owned files/areas (exclusive — no overlap with other teammates) + + Context: + 4. Workspace path: `.agent-team/{team-name}/` — read for team state, write output artifacts here + 5. Communication protocol (STARTING/COMPLETED/BLOCKED/HANDOFF/QUESTION — see Phase 4) + 6. Project conventions: "Read CLAUDE.md if it exists. Follow its conventions." + 7. Skill hints: role-specific recommendations from [teammate-roles.md](teammate-roles.md) + + Behavior: + 8. When blocked: message the lead with severity and impact, do not wait silently + 9. After completing a task: mark complete via TaskUpdate, check TaskList, self-claim next available + 10. Use subagents (Task tool) for focused subtasks that don't need teammate communication + 11. Write output artifacts to the workspace directory + - **Nested decomposition** (optional): For large tasks, tell senior implementers: "You may create sub-tasks and spawn subagents for independent portions of your work. Report rolled-up results to me. One level of nesting max." + + **Update workspace**: record each teammate in `progress.md` Team Members table + +6. **Team size gate** — explicitly count before spawning: "I am spawning N teammates: [list names]." + - **Default max: 4** for mixed teams (implementers + reviewers/challengers) + - **Up to 6** if the additional teammates beyond 4 are **read-only** (researchers, reviewers using `subagent_type: "Explore"`) — read-only agents have zero file conflict risk and minimal coordination cost + - **Self-check for N > 4**: (1) every stream has zero file overlap, (2) cross-communication between teammates is minimal, (3) the lead can track all streams without excessive workspace churn + - If the self-check fails on any point, merge roles until it passes + +7. **Assign ALL work to teammates** — every phase of the task must have a teammate owner. This includes: + - Setup work (env files, config) — assign to an implementer + - Verification (build, test, lint) — assign to a reviewer or create verification tasks for an implementer + - Finalization (status updates, cleanup edits) — assign to the nearest teammate + - If a phase seems too small for a dedicated teammate, bundle it into an adjacent teammate's task list + +### Setup Failures + +See [coordination-patterns.md](coordination-patterns.md#setup-failures) for recovery actions on common Phase 3 failures (name collisions, missing feature flag, stale workspaces, spawn failures, context compaction). + +## Phase 4: Coordinate + +### Context Recovery +If your context was compacted or you feel disoriented, **read the workspace first**: +``` +Read: .agent-team/{team-name}/progress.md +Read: .agent-team/{team-name}/tasks.md +Read: .agent-team/{team-name}/issues.md +``` +This restores your full awareness of team state, decisions, and history. Then read `~/.claude/teams/{team-name}/config.json` for live team members and call TaskList for live task state. + +### Workspace Updates + +Update workspace files at every significant event. Batch multiple events into a single edit per file. See [workspace-templates.md](workspace-templates.md#workspace-update-protocol) for the full event-to-file mapping table. + +### Communication Protocol + +All teammates use structured message prefixes when communicating with the lead. Include this protocol in every teammate's spawn prompt: + +``` +STARTING #N: {what I plan to do, which files I'll touch} +COMPLETED #N: {what I did, files changed, any concerns} +BLOCKED #N: severity={critical|high|medium|low}, {what's blocking}, impact={what can't proceed} +HANDOFF #N: {what I produced that another teammate needs, key details} +QUESTION: {what I need to know, what I already checked in workspace} +``` + +#### Lead Processing Rules + +When receiving structured messages: + +| Prefix | Lead Action | +|--------|--------------| +| STARTING | Update `tasks.md` status to `in_progress`, add note | +| COMPLETED | Update `tasks.md` status to `completed`, add file list and notes. Check: does this unblock other tasks? If yes, message the dependent teammate | +| BLOCKED | Add row to `issues.md` immediately. Acknowledge the teammate. Route to resolution | +| HANDOFF | Extract key details, forward to dependent teammate with actionable context. Log in `progress.md` Handoffs | +| QUESTION | Check if answer is in workspace files. If yes, answer with file reference. If no, investigate | + +#### Plan Approval Handling + +When a teammate spawned with `mode: "plan"` finishes planning, they send a `plan_approval_request` message to the lead. You must respond via SendMessage with `type: "plan_approval_response"`, the teammate as `recipient`, the `request_id` from their request, and `approve: true` or `approve: false`. If rejecting, include `content` with specific feedback so the teammate can revise their plan. The teammate cannot proceed with implementation until the plan is approved. + +For high-frequency handoffs between specific teammates, you may authorize direct communication — see the Direct Handoff pattern in [coordination-patterns.md](coordination-patterns.md). The audit trail must still be maintained in `progress.md`. + +### Coordination Patterns + +For detailed patterns on these scenarios, see [coordination-patterns.md](coordination-patterns.md): +- **Batch updates** — collect pending updates and apply in a single pass per file +- **First contact verification** — confirming teammates are active after spawn +- **Parallel shutdown** — send all shutdown requests in a single turn, not sequentially +- **Pre-shutdown commit** — ensure implementers commit owned files before shutdown +- **Remediation gate** — spawn a fix team for unresolved issues (max 1 cycle) +- **Idle teammates** — the TeammateIdle hook nudges automatically; assign new work or confirm done +- **Blocked teammates** — log to `issues.md`, acknowledge, route to resolution +- **File conflicts** — stop both teammates, reassign ownership, log as **high** issue +- **Stuck dependencies** — check blocking task status, message assigned teammate, reassign if needed +- **Result handoff between teammates** — lead summarizes and forwards cross-teammate outputs +- **Teammate not responding** — status check, investigate, respawn if unrecoverable +- **Scope creep** — redirect teammates to assigned tasks +- **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 +- **Direct handoff** — authorized peer-to-peer messaging with audit trail + +**Periodic scan**: on every context recovery, check `issues.md` for OPEN items and address them before resuming normal coordination. + +The phase checklist is embedded in your `progress.md` — check it during workspace reads. + +## Phase 5: Synthesis and Completion (shared steps) + +Steps shared by all archetypes. Archetype-specific overrides (completion gate checks, report variant, commit/merge behavior) are in each skill's own Phase 5 section. + +1. **Verify all tasks completed** via TaskList — every task must be `completed` + +2. **Collect results** — message each teammate with the structured request (skip if teammates' COMPLETED messages already included full summaries — files changed, decisions, concerns): + ``` + Summarize your work: + - Task IDs completed + - Files created, modified, or deleted + - Key decisions you made + - Open concerns or follow-up items + ``` + +3. **Update workspace**: set `progress.md` status to `completing`, update `tasks.md` with final states and teammate notes. See Workspace Update Protocol in Phase 4 for event-to-file mappings. + +4. **Remediation gate** — the Completion Gate resolves most OPEN issues via fix tasks. This step handles residual issues that couldn't be resolved: + - If **0 OPEN issues** in `issues.md`: skip + - If **OPEN issues exist** and `progress.md` remediation cycle is already `1`: do NOT spawn another team. Include unresolved issues in the user report: + > **Unresolved issues (require manual follow-up):** + > - Issue #N (severity): description + > See `.agent-team/{team-name}/issues.md` for full details. + - If **OPEN issues exist** and remediation cycle is `0`: present issues to the user and propose a remediation team. Follow the full protocol in [coordination-patterns.md](coordination-patterns.md#remediation-gate). + +5. **Report to user**: + - Summary of all work completed + - Files modified by each teammate + - **Issues summary**: list any OPEN or MITIGATED issues from `issues.md` with their impact + - Any open concerns or follow-up items + - **Workspace path**: tell the user where the workspace is (`.agent-team/{team-name}/`) + +6. **Shutdown sequence** (parallel — do NOT wait for each one sequentially): + ``` + Send ALL shutdown_request messages in a single turn (parallel SendMessage calls) + Wait for all approval responses + If a teammate rejects: check their reason, resolve, then re-request + ``` + **Update workspace**: set `progress.md` status to `done`, record completion time + +7. **Cleanup**: + - **Only call TeamDelete after ALL teammates have confirmed shutdown.** TeamDelete may fail if teammates are still active — always wait for all shutdown confirmations first. + - TeamDelete to remove ephemeral team resources (`~/.claude/teams/{team-name}/`). The workspace at `.agent-team/{team-name}/` is NOT deleted — it is the permanent record + - Clean up idle hook counters: `rm -f /tmp/agent-team-idle-counters/{team-name}--* 2>/dev/null || true` + - Clean up ownership violation tracking: `rm -rf /tmp/agent-team-ownership-violations 2>/dev/null || true` + +## Anti-Patterns + +- **DO NOT implement or verify code yourself** (the Zero-Code Rule) — no editing files, no running build/test/lint. If it touches a file or runs a command, a teammate does it. Bundle small tasks into an adjacent teammate's scope. Bash is for workspace init (`mkdir`) and cleanup only +- **DO NOT let two teammates edit the same file** — guaranteed conflicts. Map every file to one owner in Phase 2 +- **DO NOT skip the report** — `.agent-team/{team-name}/report.md` MUST exist before shutdown +- **DO NOT assume task completion** — no COMPLETED message means the task is NOT done +- **DO NOT use broadcast for routine updates** — each broadcast = N messages. Use 1:1 messages by default +- **DO NOT nest teams** — teammates cannot spawn their own teams. One team per session — clean up before starting a new one. `/resume` and `/rewind` do not restore teammates + +## Reference + +- [teammate-roles.md](teammate-roles.md) — lead + teammate role definitions and spawn templates +- [communication-protocol.md](communication-protocol.md) — structured message formats (canonical source for spawn prompt injection) +- [coordination-patterns.md](coordination-patterns.md) — conflict resolution, handoff patterns, and communication protocol +- [report-format.md](report-format.md) — final report format and generation protocol +``` + +**Step 2: Verify the doc is self-consistent** + +Run: `grep -c '^\(##\|###\)' docs/shared-phases.md` +Expected: Should show section headings for Prerequisites, Hooks, Phase 1, Phase 2, Phase 3 (shared), Phase 4, Phase 5 (shared), Anti-Patterns, Reference. + +**Step 3: Commit** + +```bash +git add docs/shared-phases.md +git commit -m "docs: extract shared phases into docs/shared-phases.md" +``` + +--- + +### Task 2: Create `skills/agent-implement/SKILL.md` — Implementation archetype + +**Files:** +- Create: `skills/agent-implement/SKILL.md` + +**Step 1: Write the implementation skill** + +```markdown +--- +name: agent-implement +description: > + Orchestrates parallel implementation work via Agent Teams. Triggers when a task involves + building, refactoring, fixing, or migrating code with 2+ independent work streams. + Triggers: "implement in parallel", "build with a team", "refactor with teammates", + "fix in parallel", "migrate with a team". +argument-hint: "[implementation task description]" +allowed-tools: TeamCreate, TeamDelete, TaskCreate, TaskUpdate, TaskList, TaskGet, SendMessage, AskUserQuestion, Read, Write, Edit, Glob, Grep, Bash +--- + +# Implementation Team Orchestrator + +Read [shared-phases.md](../../docs/shared-phases.md) for your identity, prerequisites, hooks, and shared phase logic (Phases 1, 2, 4, and shared steps of 3 and 5). + +## Phase 1 Override: Decomposition Strategy + +Apply shared Phase 1, then: +- **Decompose by module/area** (frontend vs backend, auth vs payments) or **by layer** (data model vs API vs UI) +- **Default roles**: 1-2 Implementers + Reviewer (standard) or + Reviewer + Tester (complex) +- Detect archetype as `implementation` — show `Team type: implementation (auto-detected)` in Phase 2 + +## Phase 3 Override: Workspace Setup + +Apply shared Phase 3 steps 1-7, plus: + +### file-locks.json + +Create `.agent-team/{team-name}/file-locks.json` mapping each teammate to owned files/directories. Used by PreToolUse hook. See [workspace-templates.md](../../docs/workspace-templates.md#file-locksjson) for format. + +```json +{ + "teammate-name": ["src/auth/", "src/middleware/auth.ts"], + "other-teammate": ["src/api/", "tests/api/"] +} +``` + +### events.log + +Initially empty. Append-only JSON event log. Written by SubagentStart/Stop hooks and the lead during coordination. See [workspace-templates.md](../../docs/workspace-templates.md#eventslog) for format. + +### Branch Instructions + +Include in each **implementer's** spawn prompt: +- "Create branch `{team-name}/{your-name}` before starting work. If git is unavailable, skip." + +### Worktree Isolation (optional) + +If `isolation: worktree` was chosen in Phase 2: +- For each implementer, run `scripts/setup-worktree.sh {team-name} {teammate-name}` +- Include the worktree path in the implementer's spawn prompt as their working directory +- If worktree creation fails, fall back to shared mode and log warning in `issues.md` + +## Phase 5 Override: Completion + +Apply shared Phase 5 steps 1-3, then: + +### Pre-Shutdown Commit + +Message each **implementer** to commit their owned files: +``` +Commit your owned files before shutdown. +- Stage ONLY files in your owned area: git add +- Commit with a descriptive message following project conventions +- Send me the commit hash when done +- If the commit fails, fix the issue and retry. Do NOT proceed without a successful commit. +``` +Wait for all implementers to confirm. Log failures in `issues.md` as **high** severity. + +### Merge Branches + +- If worktree isolation: run `scripts/merge-worktrees.sh {team-name}` +- If auto-branching only: `git merge --no-ff {team-name}/{teammate-name}` per branch +- If merge conflicts: log in `issues.md`, assign implementer to resolve +- If neither branching nor worktrees: skip + +### Completion Gate (ALL 8 checks must PASS) + +Run checks in order. Items marked ★ are project-specific — PASS automatically if no tooling configured. + +| # | Check | How | PASS Criteria | On FAIL | +|---|-------|-----|---------------|---------| +| 1 | **Uncommitted changes** | `git status` scoped to each implementer's owned files | All owned files committed | Message implementer to commit | +| 2 | **Build & tests** | Assign teammate: "Run build + test commands, report PASS/FAIL" | Exit 0, all tests pass | Create fix task | +| 3 | **Lint/format** ★ | Assign teammate: "Run lint, report new warnings/errors" | No new lint errors | Create fix task | +| 4 | **Integration** | Assign teammate: "Verify cross-module connections" | Cross-teammate outputs connect | Create integration fix task | +| 5 | **Security scan** ★ | Assign teammate: "Check for secrets, OWASP top 10 in changed files" | No new security issues | Create fix task (critical) | +| 6 | **Workspace issues** | Read `issues.md` | 0 OPEN issues | Route to teammate | +| 7 | **Plan completion** | Compare Phase 2 plan vs TaskList | Every stream has completed tasks | Create missing tasks | +| 8 | **Documentation sync** | Assign teammate: "Check if README/docs need updates" | No stale docs | Create doc update task | + +Log gate result in `progress.md` Decision Log. + +### Generate Report + +Write `.agent-team/{team-name}/report.md` using the **standard report** template from [report-format.md](../../docs/report-format.md). Copy References from `progress.md`. + +**Self-check**: read the file back — does it contain the Executive Summary? If not, regenerate. + +Then continue with shared Phase 5 steps 4-7 (remediation gate, report to user, shutdown, cleanup). +``` + +**Step 2: Verify frontmatter** + +Run: `head -10 skills/agent-implement/SKILL.md` +Expected: Valid YAML frontmatter with name, description, argument-hint, allowed-tools. + +**Step 3: Commit** + +```bash +git add skills/agent-implement/SKILL.md +git commit -m "feat: add agent-implement skill for implementation archetype" +``` + +--- + +### Task 3: Create `skills/agent-research/SKILL.md` — Research archetype + +**Files:** +- Create: `skills/agent-research/SKILL.md` + +**Step 1: Write the research skill** + +```markdown +--- +name: agent-research +description: > + Orchestrates parallel research via Agent Teams. Triggers when a task involves + investigating, analyzing, or comparing approaches with 2+ independent research angles. + Triggers: "research in parallel", "investigate with a team", "analyze with teammates", + "compare approaches in parallel", "explore with a team". +argument-hint: "[research question or investigation topic]" +allowed-tools: TeamCreate, TeamDelete, TaskCreate, TaskUpdate, TaskList, TaskGet, SendMessage, AskUserQuestion, Read, Write, Edit, Glob, Grep, Bash +--- + +# Research Team Orchestrator + +Read [shared-phases.md](../../docs/shared-phases.md) for your identity, prerequisites, hooks, and shared phase logic (Phases 1, 2, 4, and shared steps of 3 and 5). + +## Phase 1 Override: Decomposition Strategy + +Apply shared Phase 1, then: +- **Decompose by research question/hypothesis**, not by module +- **Default roles**: 2-3 Researchers (different angles) + optional Analyst or Challenger +- Detect archetype as `research` — show `Team type: research (auto-detected)` in Phase 2 + +## Phase 3 Override: Workspace Setup + +Apply shared Phase 3 steps 1-7, with these differences: +- **SKIP file-locks.json** — all teammates are read-only, no file ownership to enforce +- **SKIP branch instructions** — no code branches needed +- File ownership hook (PreToolUse) is N/A for this archetype + +## Phase 5 Override: Completion + +Apply shared Phase 5 steps 1-3, then: + +- **SKIP pre-shutdown commit** — no files to commit (read-only team) +- **SKIP branch merge** — no branches created + +### Completion Gate (2 checks only) + +| # | Check | How | PASS Criteria | On FAIL | +|---|-------|-----|---------------|---------| +| 6 | **Workspace issues** | Read `issues.md` | 0 OPEN issues | Route to teammate | +| 7 | **Plan completion** | Compare Phase 2 plan vs TaskList | Every research angle has completed tasks | Create missing tasks | + +Checks #1-#5 and #8 are N/A for research teams (no code changes). + +Log gate result in `progress.md` Decision Log. + +### Generate Report + +Write `.agent-team/{team-name}/report.md` using the **findings report** variant from [report-format.md](../../docs/report-format.md#findings-report). Replace "Files Changed" with "What Was Discovered". Use "Findings" instead of "Files modified" in Per-Teammate Summaries. + +**Self-check**: read the file back — does it contain the Executive Summary? If not, regenerate. + +Then continue with shared Phase 5 steps 4-7 (remediation gate, report to user, shutdown, cleanup). +``` + +**Step 2: Verify frontmatter** + +Run: `head -10 skills/agent-research/SKILL.md` +Expected: Valid YAML frontmatter. + +**Step 3: Commit** + +```bash +git add skills/agent-research/SKILL.md +git commit -m "feat: add agent-research skill for research archetype" +``` + +--- + +### Task 4: Create `skills/agent-audit/SKILL.md` — Audit archetype + +**Files:** +- Create: `skills/agent-audit/SKILL.md` + +**Step 1: Write the audit skill** + +```markdown +--- +name: agent-audit +description: > + Orchestrates parallel audits via Agent Teams. Triggers when a task involves + reviewing, assessing, or evaluating code against standards with 2+ independent audit lenses. + Triggers: "audit in parallel", "review with a team", "assess with teammates", + "security review with a team", "code review in parallel", "check compliance". +argument-hint: "[audit scope and standards]" +allowed-tools: TeamCreate, TeamDelete, TaskCreate, TaskUpdate, TaskList, TaskGet, SendMessage, AskUserQuestion, Read, Write, Edit, Glob, Grep, Bash +--- + +# Audit Team Orchestrator + +Read [shared-phases.md](../../docs/shared-phases.md) for your identity, prerequisites, hooks, and shared phase logic (Phases 1, 2, 4, and shared steps of 3 and 5). + +## Phase 1 Override: Decomposition Strategy + +Apply shared Phase 1, then: +- **Decompose by audit lens/checklist area** (security, performance, compliance, style) +- **Default roles**: 2-3 Reviewers or Auditors (different lenses) + optional Challenger +- Detect archetype as `audit` — show `Team type: audit (auto-detected)` in Phase 2 + +## Phase 3 Override: Workspace Setup + +Apply shared Phase 3 steps 1-7, with these differences: +- **SKIP file-locks.json** — all teammates are read-only +- **SKIP branch instructions** — no code branches needed +- File ownership hook (PreToolUse) is N/A for this archetype + +## Phase 5 Override: Completion + +Apply shared Phase 5 steps 1-3, then: + +- **SKIP pre-shutdown commit** — no files to commit +- **SKIP branch merge** — no branches created + +### Completion Gate (4 checks) + +| # | Check | How | PASS Criteria | On FAIL | +|---|-------|-----|---------------|---------| +| 4 | **Integration** | Verify audit covered cross-module concerns | Audit comprehensiveness confirmed | Assign follow-up audit task | +| 5 | **Security** | Verify audit covered security aspects | Security coverage confirmed | Assign security audit task | +| 6 | **Workspace issues** | Read `issues.md` | 0 OPEN issues | Route to teammate | +| 7 | **Plan completion** | Compare Phase 2 plan vs TaskList | Every audit lens has completed tasks | Create missing tasks | + +Checks #1-#3 and #8 are N/A for audit teams (no code changes). Note: #4 and #5 assess audit coverage, not code correctness. + +Log gate result in `progress.md` Decision Log. + +### Generate Report + +Write `.agent-team/{team-name}/report.md` using the **audit report** variant from [report-format.md](../../docs/report-format.md#audit-report). Replace "Files Changed" with "What Was Audited". Use "Audit findings" and "Items checked" in Per-Teammate Summaries. + +**Self-check**: read the file back — does it contain the Executive Summary? If not, regenerate. + +Then continue with shared Phase 5 steps 4-7 (remediation gate, report to user, shutdown, cleanup). +``` + +**Step 2: Commit** + +```bash +git add skills/agent-audit/SKILL.md +git commit -m "feat: add agent-audit skill for audit archetype" +``` + +--- + +### Task 5: Create `skills/agent-plan/SKILL.md` — Planning archetype + +**Files:** +- Create: `skills/agent-plan/SKILL.md` + +**Step 1: Write the planning skill** + +```markdown +--- +name: agent-plan +description: > + Orchestrates parallel planning via Agent Teams. Triggers when a task involves + designing, architecting, or producing specs with 2+ independent planning concerns. + Triggers: "plan in parallel", "design with a team", "architect with teammates", + "produce specs in parallel", "strategy with a team". +argument-hint: "[planning scope or design question]" +allowed-tools: TeamCreate, TeamDelete, TaskCreate, TaskUpdate, TaskList, TaskGet, SendMessage, AskUserQuestion, Read, Write, Edit, Glob, Grep, Bash +--- + +# Planning Team Orchestrator + +Read [shared-phases.md](../../docs/shared-phases.md) for your identity, prerequisites, hooks, and shared phase logic (Phases 1, 2, 4, and shared steps of 3 and 5). + +## Phase 1 Override: Decomposition Strategy + +Apply shared Phase 1, then: +- **Decompose by planning concern** (architecture, data model, API design, etc.) +- **Default roles**: 1-2 Planners or Strategists + Researcher + optional Challenger +- Detect archetype as `planning` — show `Team type: planning (auto-detected)` in Phase 2 + +## Phase 3 Override: Workspace Setup + +Apply shared Phase 3 steps 1-7, with these differences: +- **SKIP file-locks.json** — Planners write docs to workspace, not project files +- **SKIP branch instructions** — no code branches +- If multiple Planners, assign distinct workspace sub-paths (e.g., `{workspace}/planner-1/`) to avoid write conflicts +- File ownership hook (PreToolUse) is N/A for this archetype + +## Phase 5 Override: Completion + +Apply shared Phase 5 steps 1-3, then: + +- **SKIP pre-shutdown commit** — planners write to workspace, not project files +- **SKIP branch merge** — no branches created + +### Completion Gate (2 checks only) + +| # | Check | How | PASS Criteria | On FAIL | +|---|-------|-----|---------------|---------| +| 6 | **Workspace issues** | Read `issues.md` | 0 OPEN issues | Route to teammate | +| 7 | **Plan completion** | Compare Phase 2 plan vs TaskList | Every planning concern has completed tasks | Create missing tasks | + +Checks #1-#5 and #8 are N/A for planning teams. + +Log gate result in `progress.md` Decision Log. + +### Generate Report + +Write `.agent-team/{team-name}/report.md` using the **plan report** variant from [report-format.md](../../docs/report-format.md#plan-report). Replace "Files Changed" with "What Was Planned". Use "Design contributions" and "Decisions proposed" in Per-Teammate Summaries. + +**Self-check**: read the file back — does it contain the Executive Summary? If not, regenerate. + +Then continue with shared Phase 5 steps 4-7 (remediation gate, report to user, shutdown, cleanup). +``` + +**Step 2: Commit** + +```bash +git add skills/agent-plan/SKILL.md +git commit -m "feat: add agent-plan skill for planning archetype" +``` + +--- + +### Task 6: Rewrite `skills/agent-team/SKILL.md` — Hybrid catch-all + +**Files:** +- Modify: `skills/agent-team/SKILL.md` (full rewrite) + +**Step 1: Rewrite SKILL.md as the Hybrid/catch-all skill** + +The new SKILL.md should: +- Keep the existing `name: agent-team` and existing trigger phrases +- Add archetype auto-detection that recommends the specific skill when a clear match exists +- Handle Hybrid archetype (mixed work types) natively +- Reference `shared-phases.md` for shared logic +- Contain Hybrid-specific Phase 3/5 overrides (conditional file-locks, strictest gate rule) + +```markdown +--- +name: agent-team +description: > + Orchestrates parallel work via Agent Teams. Triggers when a task has 2+ independent + work streams that benefit from parallel execution with inter-agent communication. + Triggers: "create a team", "work in parallel", "use agent team", "spawn teammates". +argument-hint: "[task description]" +allowed-tools: TeamCreate, TeamDelete, TaskCreate, TaskUpdate, TaskList, TaskGet, SendMessage, AskUserQuestion, Read, Write, Edit, Glob, Grep, Bash +--- + +# Agent Team Orchestrator + +Read [shared-phases.md](../../docs/shared-phases.md) for your identity, prerequisites, hooks, and shared phase logic (Phases 1, 2, 4, and shared steps of 3 and 5). + +## Archetype Detection + +Before proceeding with Phase 1, determine the team archetype from the user's task. Match against trigger patterns from [team-archetypes.md](../../docs/team-archetypes.md): + +| Archetype | Trigger Patterns | Dedicated Skill | +|-----------|-----------------|-----------------| +| Implementation | "implement", "build", "create", "refactor", "fix", "migrate" | `/agent-implement` | +| Research | "research", "investigate", "explore", "analyze", "compare" | `/agent-research` | +| Audit | "audit", "review", "assess", "evaluate", "check compliance" | `/agent-audit` | +| Planning | "plan", "design", "architect", "spec", "propose", "strategy" | `/agent-plan` | +| Hybrid | Task combines 2+ of the above | This skill (`/agent-team`) | + +**If a single archetype matches clearly**: Inform the user that a dedicated skill exists and proceed using that archetype's logic. Example: "This is an implementation task — I'll use the implementation team workflow." + +**If the task combines types** (e.g., "research X then implement Y"): This is a Hybrid — proceed below. + +**If no clear match**: Default to Implementation workflow. + +## Phase 1 Override: Hybrid Decomposition + +Apply shared Phase 1, then: +- **Identify which parts map to which archetype** (e.g., research streams vs implementation streams) +- **Compose roles from the full catalog** based on combined task types +- Show `Team type: hybrid ([component types])` in Phase 2 (e.g., `hybrid (research + implementation)`) + +## Phase 3 Override: Hybrid Workspace Setup + +Apply shared Phase 3 steps 1-7, plus: + +### file-locks.json (conditional) + +Create **only if ANY teammate writes project files** (implementers, writers with file ownership). Skip if all teammates are read-only. + +See [workspace-templates.md](../../docs/workspace-templates.md#file-locksjson) for format. + +### events.log + +Initially empty. Append-only JSON event log. + +### Branch Instructions (implementers only) + +Include branch instruction in each **implementer's** spawn prompt only: +- "Create branch `{team-name}/{your-name}` before starting work. If git is unavailable, skip." + +### Worktree Isolation (optional, implementers only) + +If chosen in Phase 2, apply only to implementers. See implementation archetype for details. + +## Phase 5 Override: Hybrid Completion + +Apply shared Phase 5 steps 1-3, then: + +### Pre-Shutdown Commit (conditional) + +Only if implementers or writers with file ownership exist. Message each to commit their owned files. See implementation archetype for the commit protocol. + +### Merge Branches (conditional) + +Only if branching or worktrees were used. See implementation archetype for merge protocol. + +### Completion Gate — Strictest Gate Rule + +Include any check required by ANY component archetype present in the team: + +| # | Check | Required if... | +|---|-------|---------------| +| 1 | **Uncommitted changes** | Any Implementer present | +| 2 | **Build & tests** | Any Implementer present | +| 3 | **Lint/format** ★ | Any Implementer present | +| 4 | **Integration** | Any Implementer present OR Audit component | +| 5 | **Security scan** ★ | Any Implementer present OR Audit component | +| 6 | **Workspace issues** | Always | +| 7 | **Plan completion** | Always | +| 8 | **Documentation sync** | Any Implementer present | + +★ = Project-specific. PASS automatically if no tooling configured. + +> **Lead judgment**: When the implementation component is minor (e.g., a single config change), mark checks as N/A with a brief note in `progress.md`. + +Log gate result in `progress.md` Decision Log. + +### Generate Report + +Write `.agent-team/{team-name}/report.md` using the **standard report** template from [report-format.md](../../docs/report-format.md). If the Hybrid has no Implementation component, omit "Files Changed" and substitute the appropriate variant section (e.g., "What Was Discovered" or "What Was Audited"). + +**Self-check**: read the file back — does it contain the Executive Summary? If not, regenerate. + +Then continue with shared Phase 5 steps 4-7 (remediation gate, report to user, shutdown, cleanup). +``` + +**Step 2: Verify line count reduction** + +Run: `wc -l skills/agent-team/SKILL.md` +Expected: ~120-140 lines (down from 443) + +**Step 3: Commit** + +```bash +git add skills/agent-team/SKILL.md +git commit -m "refactor: slim agent-team SKILL.md to hybrid catch-all, reference shared-phases.md" +``` + +--- + +### Task 7: Update `docs/team-archetypes.md` — simplify + +**Files:** +- Modify: `docs/team-archetypes.md` + +**Step 1: Simplify the archetypes doc** + +Now that each archetype has its own skill, `team-archetypes.md` no longer needs to carry the full phase profile overrides. It becomes a detection reference only. + +Remove the detailed phase profile tables from each archetype section (Implementation, Research, Audit, Planning, Hybrid). Keep: +- Archetype Detection table (trigger patterns) +- Purpose and default roles for each archetype +- Strictest Gate Rule table (used by Hybrid) +- Design Notes +- Add a "See Also" linking to each archetype skill + +Remove: +- Phase profile tables (moved into each skill) +- Completion gate details per archetype (moved into each skill) +- Report variant references per archetype (moved into each skill) + +**Step 2: Commit** + +```bash +git add docs/team-archetypes.md +git commit -m "refactor: simplify team-archetypes.md, phase profiles moved to archetype skills" +``` + +--- + +### Task 8: Update tests — doc reference validation for new skills + +**Files:** +- Modify: `tests/structure/test-doc-references.sh` + +**Step 1: Extend doc reference tests to cover all skills** + +The current test only checks `skills/agent-team/SKILL.md`. Update to check all `skills/*/SKILL.md`: + +Replace the hardcoded `SKILL_MD="skills/agent-team/SKILL.md"` with a loop over all skills. For each skill: +- Test: has `name` field in frontmatter +- Test: `allowed-tools` is comma-separated (no brackets) +- Test: all relative doc refs resolve + +Add a test verifying `docs/shared-phases.md` exists and all its relative refs resolve. + +**Step 2: Run the test suite** + +Run: `bash tests/run-tests.sh` +Expected: All tests pass including the new multi-skill checks. + +**Step 3: Commit** + +```bash +git add tests/structure/test-doc-references.sh +git commit -m "test: extend doc reference tests to cover all archetype skills" +``` + +--- + +### Task 9: Update `README.md` — document new skills + +**Files:** +- Modify: `README.md` + +**Step 1: Update the Usage section** + +Add a section showing the archetype-specific commands: + +```markdown +### Archetype-Specific Commands + +| Command | When to Use | Example | +|---------|------------|---------| +| `/agent-implement` | Build, refactor, fix, migrate code | "implement the new auth module in parallel" | +| `/agent-research` | Investigate, analyze, compare | "research database options with a team" | +| `/agent-audit` | Review, assess, evaluate | "audit security with parallel reviewers" | +| `/agent-plan` | Design, architect, produce specs | "design the API with a planning team" | +| `/agent-team` | Mixed work types or unsure | "research then implement the caching layer" | +``` + +**Step 2: Update the Plugin Structure section** + +Add the new skill directories to the tree: + +``` +skills/ +├── agent-team/SKILL.md # Hybrid/catch-all orchestrator +├── agent-implement/SKILL.md # Implementation teams +├── agent-research/SKILL.md # Research teams +├── agent-audit/SKILL.md # Audit teams +└── agent-plan/SKILL.md # Planning teams +``` + +**Step 3: Commit** + +```bash +git add README.md +git commit -m "docs: document archetype-specific skills in README" +``` + +--- + +### Task 10: Update `CLAUDE.md` — reflect new structure + +**Files:** +- Modify: `CLAUDE.md` + +**Step 1: Update File Ownership table** + +Add rows for the new skills and `docs/shared-phases.md`: + +| Area | Purpose | Edit Guidelines | +|------|---------|----------------| +| `skills/agent-team/SKILL.md` | Hybrid/catch-all skill | Archetype detection + hybrid-specific overrides | +| `skills/agent-implement/SKILL.md` | Implementation skill | Implementation-specific Phase 3/5 | +| `skills/agent-research/SKILL.md` | Research skill | Research-specific Phase 3/5 | +| `skills/agent-audit/SKILL.md` | Audit skill | Audit-specific Phase 3/5 | +| `skills/agent-plan/SKILL.md` | Planning skill | Planning-specific Phase 3/5 | +| `docs/shared-phases.md` | Shared phase logic | Changes here affect ALL archetype skills | + +**Step 2: Update "Common Tasks" section** + +Add a note about adding new archetypes: +- Create a new `skills/agent-{name}/SKILL.md` +- Add the archetype to the detection table in `skills/agent-team/SKILL.md` +- Add trigger patterns to `docs/team-archetypes.md` +- Update tests, README, CLAUDE.md + +**Step 3: Commit** + +```bash +git add CLAUDE.md +git commit -m "docs: update CLAUDE.md for archetype skill split" +``` + +--- + +### Task 11: Final validation + +**Step 1: Run full test suite** + +Run: `bash tests/run-tests.sh` +Expected: All tests pass. + +**Step 2: Verify all doc cross-references resolve** + +Run: `for skill in skills/*/SKILL.md; do echo "=== $skill ==="; grep -oE '\]\([^)]*\.md[^)]*\)' "$skill" | sed 's/\](//;s/)$//' | while read ref; do dir=$(dirname "$skill"); resolved="$dir/$ref"; [ -f "$resolved" ] && echo " OK: $ref" || echo " MISSING: $ref -> $resolved"; done; done` +Expected: All refs show OK. + +**Step 3: Verify line counts** + +Run: `wc -l skills/*/SKILL.md docs/shared-phases.md` +Expected: Each archetype skill ~60-100 lines, agent-team ~120 lines, shared-phases ~200 lines. + +**Step 4: Commit any fixes, then final commit if needed** + +--- + +Plan complete and saved to `docs/plans/2026-03-09-split-skills-by-archetype.md`. Two execution options: + +**1. Subagent-Driven (this session)** - I dispatch fresh subagent per task, review between tasks, fast iteration + +**2. Parallel Session (separate)** - Open new session with executing-plans, batch execution with checkpoints + +Which approach? \ No newline at end of file diff --git a/docs/shared-phases.md b/docs/shared-phases.md index ed0483a..470d63a 100644 --- a/docs/shared-phases.md +++ b/docs/shared-phases.md @@ -87,6 +87,7 @@ Estimated teammates: N **Self-check before proceeding**: 1. "Is this plan complex? Complexity signals: multi-module/area changes, architectural decisions, risky refactors, multiple implementers with cross-dependencies, security-sensitive changes, new integrations. If yes, does the teammate list include a **dedicated reviewer** AND a **dedicated tester** (separate teammates, not combined)? If no, add them before presenting." 2. "Have I presented this plan AND received user confirmation?" If no, STOP. +3. "Do any tasks form circular dependencies? Trace each `blocked by` chain — if task A blocks B blocks C blocks A, that's a cycle. If found, restructure: merge the cyclic tasks or break the cycle by removing one dependency." Wait for user confirmation before proceeding. @@ -208,6 +209,8 @@ When receiving structured messages: | BLOCKED | Add row to `issues.md` immediately. Acknowledge the teammate. Route to resolution | | HANDOFF | Extract key details, forward to dependent teammate with actionable context. Log in `progress.md` Handoffs | | QUESTION | Check if answer is in workspace files. If yes, answer with file reference. If no, investigate | +| PROGRESS | Note milestone in `tasks.md` Notes column. If percent indicates near-completion, no action needed. If stalled, trigger Deadline Escalation | +| CHECKPOINT | If `ready_for` lists task IDs, forward checkpoint details to dependent teammate. Log in `progress.md` Handoffs | #### Plan Approval Handling diff --git a/docs/team-archetypes.md b/docs/team-archetypes.md index caddd42..8e74f86 100644 --- a/docs/team-archetypes.md +++ b/docs/team-archetypes.md @@ -86,6 +86,50 @@ Intentional design choices documented for future reference: - **Documentation sprint archetype**: Classified as Hybrid (not Implementation) because Writers produce documentation rather than code — the Hybrid archetype correctly handles conditional file-locks and mixed read/write teams. - **Phase 2 team type display**: Uses `[detected-type] (auto-detected)` user-friendly format instead of a literal enum. This makes the override mechanism more intuitive for users. +## Scaling Patterns + +When team size exceeds the default 4-6 limit, use these patterns. They are ordered by complexity — try simpler patterns first. + +### Read-Only Extension (5-6 agents) + +Add 1-2 read-only teammates (Researchers, Reviewers with `subagent_type: "Explore"`) to a standard 4-agent team. Zero file conflict risk, minimal coordination overhead. + +**When to use**: Need parallel investigation alongside implementation. + +**Example Phase 2 plan**: +``` +Teammates (6 total): +⚠ Team size check: 6 agents (4 core + 2 read-only researchers) +- impl-1 (Implementer): backend auth refactor -> owns src/auth/ +- impl-2 (Implementer): frontend auth UI -> owns src/components/auth/ +- reviewer (Reviewer): code quality review -> read-only +- tester (Tester): verify auth flows -> read-only +- perf-analyst (Researcher): performance impact analysis -> read-only (Explore) +- sec-researcher (Researcher): security implications -> read-only (Explore) +``` + +### Phased Execution (12-16+ agents over time) + +Break large projects into sequential team waves. Each phase is an independent team (4-6 agents). Workspace carries forward between phases. + +**When to use**: Clear sequential stages (research → design → implement → test). + +**Protocol**: +1. Run Phase 1 team (e.g., 3 researchers), collect findings +2. Present findings to user, get approval for Phase 2 +3. TeamDelete Phase 1, create Phase 2 team (e.g., 4 implementers) reusing same workspace +4. Repeat for Phase 3 (verification) + +**Key constraint**: Each phase waits for the previous to complete. High wall-clock time but low concurrent token cost. + +### Sub-Agent Specialization (within 4-6 agents) + +Senior implementers spawn subagents for independent subtasks within their scope. Multiplies throughput without multiplying team coordination. + +**When to use**: A single teammate's task is large enough to parallelize internally. + +**Already supported**: See [teammate-roles.md Nested Task Decomposition](teammate-roles.md#nested-task-decomposition-senior-implementers). One level of nesting max. + ## See Also - `/agent-implement` — Implementation archetype skill diff --git a/package.json b/package.json index 264bf6b..0600f42 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "agent-team-plugin", - "version": "2.3.0", + "version": "2.4.0", "description": "Orchestrate parallel AI teammates in Claude Code — with hook enforcement, workspace tracking, and structured coordination across 5 phases", "license": "MIT", "keywords": [