All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
- Removed
/agent-team:startand/agent-team:plancommands. Pipeline collapsed from 4 skills to 2 (execute+audit). - Role taxonomy collapsed from 13 specialized templates to 3 universal roles (Executor / Reviewer / Challenger) with archetype-specific extensions.
- Every task now runs through a mandatory ephemeral Executor → Reviewer → Challenger pipeline. Total spawn count is ~3× v3.x for the same plan.
- Audit's deep code review reduced to integration-only (per-task Challenger covers within-task adversarial review).
- Replace
/agent-team:start <task>with/agent-team:execute <task>. - Replace
/agent-team:plan <task>with/superpowers:writing-plans <task>. /agent-team:execute <plan-path>works the same as before for resuming./agent-team:auditis unchanged.- Custom roles (
docs/custom-roles.md): port your custom Implementer/Reviewer/etc. definitions to archetype-specific extensions. See the rewrittendocs/custom-roles.mdfor the porting guide with three concrete examples. - Existing v3.x workspaces are forward-compatible. Run
/agent-team:executewith no arguments to detect the resumable workspace and continue. ThePipeline status: approvedfield is still respected. - Resumed v3.x workspaces don't have
impact_filesintask-graph.json; the Reviewer populates it when it next runs on a task.
- New Phase 0 in execute: resolves plan, loads prior context, detects archetype, decomposes, marks plan-mode, presents for user approval.
- Auto-chain from execute →
superpowers:writing-plansif no plan found. - Auto-chain from execute → audit when work completes.
- Per-task
reviews/subdirectory in workspace:task-{id}-review.mdandtask-{id}-challenge.mdper task. - New
task-graph.jsonfields:impact_files(Reviewer's grep-based impact area),review_status,challenge_status.statusenum extended within_review. - New
CHALLENGE_REVIEWmessage type for the Challenger role. - Reviewer impact-analysis directive — grep-based call site / importer discovery (the "knowledge graph" via static analysis without parsers).
skills/execute/SKILL.mdPhase 4: replaces "Per-Task Code Review (Light)" with "Per-Task Adversarial Review Pipeline".skills/audit/SKILL.mdStep 4: deep code review → integration-only review of files in 2+ tasks'impact_files.skills/execute/agents/spawn-templates.md: 13 specialized templates → 3 universal templates with archetype directives.docs/teammate-roles.md: rewritten for 3-role taxonomy + Lead.docs/custom-roles.md: rewritten for archetype-extension model with v3.x porting guide.docs/team-archetypes.md: per-archetype Reviewer/Challenger focus subsections added.docs/workspace-templates.md: newreviews/subdir documentation, extendedtask-graph.jsonschema, Plan Audit Result table removed.scripts/generate-demo-cast.shandscripts/record-demo.sh: rewritten for v4.0 demo flow (Phase 0 + per-task pipeline + audit).tests/structure/test-doc-references.sh: updated for 2-skill layout, 3-role taxonomy, new message types.
skills/start/(entire skill).skills/plan/(entire skill).PLAN_REVIEWmessage type (no plan-reviewer agent in v4.0).- 7-check Plan Audit Result table from
docs/workspace-templates.md(writing-plans handles plan quality). - "Brainstorm & Clarify gate" from plan stage (brainstorming now happens upstream in
superpowers:brainstorming).
- Brainstorm & Clarify gate (plan stage) — conditional gate between plan audit and decomposition. Fires when uncertainty detected (analyst flags complexity, researcher reports risks, multiple decomposition strategies, or any concern). Presents structured options to user before proceeding.
- Per-task code review (execute stage) — Reviewer sends
CODE_REVIEWafter each implementer completes a task. Verdicts: approve, request_changes (max 1 fix cycle), comment. Skipped for read-only teammates. - Deep code review (audit stage) — new Step 3 in Phase 5. Reviewer reads ALL changed files for correctness, bugs, security, integration, and test coverage. Critical issues route to remediation gate.
CODE_REVIEWmessage type in communication protocol with execute-stage and audit-stage processing rules- Next-step suggestions after each pipeline stage completes — guides user to the natural next action (
/agent-team:execute,/agent-team:audit, review report, commit work, etc.) - Landing page with interactive terminal demo at https://ducdmdev.github.io/agent-team-plugin/ — Terminal Dark style, auto-typing 3-stage pipeline animation
- Stale step cross-references in audit SKILL.md after Step 3 insertion (Step 4→5, Step 5→6)
- Workspace completeness hook (SubagentStart) — validates all 4 tracking files and Archetype/Pipeline status fields before teammate spawn
- Plan-mode revision limit hook (PreToolUse(SendMessage)) — enforces max 2 revision rounds per teammate, blocks third PLAN_REVISION
- Pre-shutdown commit hook (PreToolUse(TeamDelete)) — blocks TeamDelete if any owned files have uncommitted changes
- Integration point file validation — enhanced existing hook to verify upstream task output files exist at convergence points
validate-task-graph.shhook (SubagentStart) — validates task-graph.json schema and detects circular dependencies before teammate spawn. Blocks on invalid JSON, missing required fields, dangling dependency references, or cycles.- Plan audit completeness gate — mandatory Plan Audit Result table in
progress.mdwith all 7 checks filled before plan presentation. Hard gate in plan SKILL.md. - Plan Audit Result template in
docs/workspace-templates.mdforprogress.md
- Plan stage now initializes
issues.mdduring workspace creation (TaskCompleted hook requires it) - Plan stage now documents
task-graph.jsonpopulation with JSON schema after decomposition - Audit stage now explicitly requires spawning all 3 roles (Reviewer, Elegance Reviewer, Audit Reviewer) with spawn prompt references
- README demo rewritten for v3.0.0 pipeline architecture (3-stage flow with team-per-stage)
- Skill restructure: 5 archetype skills to 4 pipeline stages — replaced
agent-team,agent-implement,agent-research,agent-audit,agent-planskills withstart,plan,execute,auditpipeline stages - Migrated shared docs into stage skills —
docs/shared-phases.md,docs/spawn-templates.md,docs/communication-protocol.md,docs/coordination-patterns.md,docs/coordination-advanced.md,docs/report-format.mdmoved into stage-specificreferences/,agents/,examples/subfolders
- Pipeline entry point (
skills/start/SKILL.md) — type detection, prior context loading, routing to plan/execute/audit - Prior context loading — plan stage loads lessons and error patterns from prior teams to inform decomposition
- Plan-mode gate — teammates propose their approach before executing; lead reviews and approves
- Error recovery loop — execute stage retries failed tasks with structured escalation (retry, reassign, simplify, skip)
- Elegance review — audit stage spawns an Elegance Reviewer agent to assess code quality beyond correctness
- Lessons capture — audit stage extracts reusable lessons for future teams
- Pattern library — audit stage builds coordination pattern recommendations from team experience
- Inter-stage review agents — plan-reviewer, execute-reviewer, audit-reviewer validate output between stages
- Elegance Reviewer role — new teammate role for post-execution quality assessment (auto-spawned by audit stage)
recovery_classfield — each teammate role now declares its error recovery behavior (full, report-gap, skip-and-continue, recover-only)- Plan-mode defaults in
docs/team-archetypes.md— each archetype has a default plan-mode setting - Stage-specific subfolders —
references/,examples/,agents/per stage skill for self-contained content - Team per stage — each pipeline stage creates and manages its own ephemeral team (plan: Researcher + Analyst + Plan Reviewer; execute: Implementers + Tester + Reviewer + Execute Reviewer; audit: Reviewer + Elegance Reviewer + Audit Reviewer)
- New spawn templates:
researcher.md,analyst.md(plan stage),reviewer.md(audit stage) **Pipeline status**,**Stage**, and**Archetype**fields inprogress.mdfor cross-stage handoffFINDINGandANALYSISmessage types for plan stage team communication
docs/shared-phases.md— phase logic inlined into each stage skilldocs/spawn-templates.md— migrated toskills/execute/agents/spawn-templates.mddocs/communication-protocol.md— migrated toskills/execute/references/communication-protocol.mddocs/coordination-patterns.md— migrated toskills/execute/references/coordination-patterns.mddocs/coordination-advanced.md— merged intoskills/execute/references/coordination-patterns.mddocs/report-format.md— migrated toskills/audit/references/report-format.mdskills/agent-team/— replaced byskills/start/skills/agent-implement/— replaced byskills/execute/skills/agent-research/— replaced byskills/execute/(team type detection in start stage)skills/agent-audit/— replaced byskills/audit/skills/agent-plan/— replaced byskills/plan/
task-graph.jsonworkspace file — centralized DAG with task dependencies, critical path, and convergence points. Created in Phase 3, maintained by lead, read by 3 new hook scriptscompute-critical-path.shhook (TaskCompleted) — recomputes and displays remaining critical path after each task completion, warns about blocked critical tasksdetect-resume.shhook (SessionStart) — detects resumable workspaces with smart staleness validation via git timestamps (valid/stale/missing output files)check-integration-point.shhook (TaskCompleted) — detects when convergence points (diamond dependencies) become fully unblocked, nudges lead to verify interface compatibility- Critical Path Awareness in Phase 4 — lead prioritizes critical-path blockers over non-critical work
- Resume from Existing Workspace coordination pattern — valid/stale/remaining protocol with archive option
- Integration Checkpoint Response coordination pattern — lead response protocol for convergence nudges
- CP column in
tasks.md— ★ marks critical path tasks, convergence notes in the Notes column
- Phase 1b gains convergence point marking (step 6 after integration points)
- Phase 2 gains critical path display and integration checkpoint preview
- Phase 3 gains resume detection (step 1a) and
task-graph.jsoncreation (step 4a) - Phase 4 gains critical-path-weighted prioritization and integration checkpoint processing
- Deadline Escalation gains critical-path acceleration (skip Nudge, go to Warn)
- Report gains critical path metrics (initial → final length, shift count) and integration checkpoint counts
- All 5 archetype SKILL.md files reference step 4a
agent-implementcompletion gate check #4 gains convergence-point awareness
- Split
coordination-patterns.md(633 lines) into core (316) + advanced (332) per skill best practices 500-line guidance - Split
teammate-roles.md(536 lines) into overview (168) + spawn-templates (407) - Added TOC to
shared-phases.md— explicit Contents section with anchor links
- Concrete decomposition examples in
agent-research,agent-audit,agent-planSKILL.md files docs/coordination-advanced.md— advanced coordination patterns (re-plan, adversarial review, checkpoint/rollback, escalation)docs/spawn-templates.md— detailed spawn prompt templates for all 11 teammate roles
- Missing
communication-protocol.mdin README Plugin Structure tree (pre-existing)
- Plan-aware Phase 1 — Phase 1 now scans for existing plan files, creates plans via
writing-plansskill when none exist, and audits all plans through a 7-check gate before team decomposition - Phase 1a: Plan Detection & Preparation — 5-step workflow (archetype context, scan, create, audit, user decision gate) with graceful fallback when writing-plans skill is unavailable
- Phase 1b: Decompose from Plan — team decomposition now derives parallel streams, file ownership, and dependencies from an approved plan rather than ad-hoc analysis
- Plan audit gate — 7 checks (task completeness, dependency coherence, file reference validity, scope coverage, reference freshness, feasibility, parallelizability) with severity levels
- Plan Status Update in Phase 5 — automatically marks source plan as COMPLETED, PARTIAL, or ABANDONED after team finishes
- Plan File Conventions in workspace-templates — documented status values, scan behavior, minimum structure requirements
- Early exit for trivial tasks — skips plan detection for single-file, no-dependency tasks
- Budget constraints — limits scan depth, candidate reads, and context bundle size to keep Phase 1a lightweight
- Plan-aware archetype detection — plan content now informs team type detection alongside trigger patterns
- IN PROGRESS status at Phase 3 — plan file marked as in-progress during workspace init to warn concurrent teams
- Phase 2 template — now includes
Based on:line showing plan file path and source (existing/generated) - Phase Checklist — updated to reflect Phase 1a/1b split and Phase 5 plan status update
- All 5 archetype SKILL.md files — Phase 1 overrides reference Phase 1a/1b, Phase 5 overrides include Plan Status Update step
- 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
- 4 archetype-specific skills —
/agent-implement,/agent-research,/agent-audit,/agent-planeach with focused Phase 3/5 overrides and archetype-specific completion gates - Shared phases doc (
docs/shared-phases.md) — extracted shared logic (Phases 1, 2, 4, shared steps of 3 and 5) referenced by all archetype skills
/agent-teamslimmed to hybrid catch-all — 102 lines (down from 443), with archetype auto-detection table that recommends dedicated skills when a clear match existsdocs/team-archetypes.mdsimplified — 95 lines (down from 157), now a detection reference only (phase profiles moved into each skill)- Test suite extended —
test-doc-references.shloops over allskills/*/SKILL.mdinstead of hardcoded path - README updated — new Archetype-Specific Commands table and updated plugin structure tree
- CLAUDE.md updated — file ownership table expanded, "Adding a New Archetype Skill" guide added
- Communication protocol consolidated — new
docs/communication-protocol.mdas canonical source; 11 spawn templates now use{COMMUNICATION_PROTOCOL}placeholder injected at spawn time - Terminology standardized — renamed
worker-roles.md→teammate-roles.md; "worker" eliminated from all active file references - SKILL.md restructured — moved Setup Failures, Workspace Update Protocol, file-locks/events.log details to docs; replaced with one-line references
- Quick Start section added to SKILL.md for fast orientation
- Concrete examples added: Phase 2 plan example and Phase 3 spawn prompt assembly example
- Protocol injection instruction added to Phase 3 for lead to read and substitute protocol at spawn time
- 5 team archetypes — Implementation, Research, Audit, Planning, Hybrid with auto-detection from task trigger patterns, phase profile overrides, and archetype-specific completion gates
- 6 new roles — Analyst, Planner, Writer, Strategist, Auditor, Scout with full spawn templates, subagent type annotations, and structured output formats
- 3 report variants — Findings Report (research), Audit Report (audit), Plan Report (planning) with shared outer structure and domain-specific content sections
- Archetype dispatch in SKILL.md — Phase 1 detection, Phase 2 team type display with user override, Phase 3-5 override callouts referencing team-archetypes.md
- Team archetypes reference (
docs/team-archetypes.md) — trigger patterns, phase profiles, Strictest Gate Rule for Hybrid teams, disambiguation notes for ambiguous triggers - Role variants — Migrator/Integrator/Debugger (Implementer), Facilitator (Challenger), Validator (Tester), Documenter (Writer)
- Role Selection Guide expanded with Archetype column and 8 new task type entries
- custom-roles.md intro updated to list all 12 built-in roles
- Date-prefixed workspace names —
MMDD-{task-slug}format prevents name collisions and enables chronological sorting - CLAUDE.md + skill hints in spawn prompts — all 5 spawn templates instruct teammates to read project conventions; role-specific skill hints (
/tdd,/requesting-code-review,/verification-before-completion) - Documentation references in workspace files — References sections in progress.md and report.md templates, Ref column in tasks.md, Phase 1 step to identify reference docs
- Completion Gate (Phase 5) — 8-item hard gate (uncommitted, build, lint, integration, security, issues, plan, docs) replaces the vague "Check integration" step
- Remediation Gate (Phase 5 step 8) simplified to handle residual issues only — primary issue resolution now handled by Completion Gate
- Quality Gate pattern in coordination-patterns.md updated with Completion Gate cross-reference
- TaskCompleted hook no longer blocks teammates whose output goes to gitignored
.agent-team/workspace (e.g.,report.md). Previously caused stuck retry loops when task subject contained implementation keywords like "Write".
- Git worktree isolation (opt-in) —
isolation: worktreein Phase 2 plan gives each implementer a dedicated worktree - Nested task decomposition — senior implementers can create sub-tasks and spawn sub-agents
- Worktree setup and merge scripts (
scripts/setup-worktree.sh,scripts/merge-worktrees.sh)
- Major version bump: nested decomposition changes the team coordination model
- Auto-branch per teammate — implementers create
{team-name}/{name}branches, merged in Phase 5 events.logworkspace file — structured JSON event log for post-mortem analysis- Direct Handoff coordination pattern — authorized peer-to-peer messaging with audit trail
- Branch Merge step in Phase 5
- SessionStart(compact) hook — auto-recovers workspace context after compaction
- PreToolUse(Write|Edit) hook — enforces file ownership (warn-then-block)
- SubagentStart/SubagentStop hooks — tracks teammate lifecycle in events.log
file-locks.jsonworkspace file — maps teammates to owned files/directories
- TaskCompleted hook now uses
task_idandteammate_namefor scoped git checks - Hooks section in SKILL.md updated to document all 5 hooks
- Re-read workspace instruction in all spawn templates (prevents context drift)
- Team metrics section in final report template
- Custom roles reference in Phase 1 decomposition
tasks.mdworkspace template now groups tasks by status (In Progress / Blocked / Pending / Completed)- TeammateIdle hook updated to parse grouped tasks.md format
- Re-plan on Block coordination pattern — structured re-planning when critical blockers invalidate the original plan
- Adversarial Review Rounds coordination pattern — multi-round cross-review for high-stakes changes
- Quality Gate coordination pattern — final validation pass before Phase 5 synthesis
- Auto-Block on Repeated Failures coordination pattern — auto-escalation after 3 blocked attempts on the same task
- Custom role definitions template (
docs/custom-roles.md) — project-specific roles alongside built-in ones descriptionfield inhooks/hooks.jsonfor better UX in/hooksmenu
- Remediation Gate in Phase 5 — spawn fix team for unresolved issues (max 1 cycle)
- Tester role with spawn template
- Pre-shutdown commit protocol for implementers
- Complexity assessment and dedicated reviewer/tester gate for complex plans
- Remediation cycle tracking in
progress.md
- TeammateIdle hook with loop protection (3 strikes)
- Batch updates coordination pattern
- First contact verification pattern
- Parallel shutdown pattern
- Initial release: 5-phase team orchestrator
- TaskCompleted hook with workspace and git change verification
- 5 teammate roles: Implementer, Reviewer, Researcher, Challenger, Leader
- Persistent workspace with progress.md, tasks.md, issues.md
- Structured communication protocol (STARTING/COMPLETED/BLOCKED/HANDOFF/QUESTION)
- Coordination patterns library
- Final report generation