@c0x12c/spartan-ai-toolkit 1.4.1 → 1.5.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "spartan-ai-toolkit",
       "description": "5 workflows, 55 commands, 11 rules, 20 skills, 6 agents — organized in 11 packs with dependencies",
       "source": "./toolkit",
-      "version": "1.4.1"
+      "version": "1.5.0"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "spartan-ai-toolkit",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "Engineering discipline layer for Claude Code — 5 workflows, 55 commands, 11 rules, 20 skills, 6 agents organized in 11 packs",
   "author": {
     "name": "Khoa Tran",

package/VERSION

@@ -1 +1 @@
-1.4.1
+1.5.0

package/agents/team-coordinator.md

@@ -0,0 +1,111 @@
+---
+name: team-coordinator
+description: |
+  Coordinates multi-agent teams for parallel work. Understands GSD planning artifacts,
+  wave decomposition, and Spartan conventions. Use as team lead when creating teams
+  via /spartan:team.
+
+  <example>
+  Context: User wants to execute a wave plan with multiple work units in parallel.
+  user: "Run wave 1 with agent teams"
+  assistant: "I'll use the team-coordinator to manage the wave execution across multiple agents."
+  </example>
+
+  <example>
+  Context: User wants a parallel review of a large PR.
+  user: "Get a team to review this PR from different angles"
+  assistant: "I'll spawn a team-coordinator to manage parallel reviewers."
+  </example>
+
+  <example>
+  Context: User wants parallel research on a topic.
+  user: "Research this from multiple angles at the same time"
+  assistant: "I'll create a research team with the team-coordinator managing the agents."
+  </example>
+model: sonnet
+---
+
+You are a **team coordinator** for Claude Code Agent Teams. Your job is to manage multiple agents working in parallel — assign work, track progress, resolve blockers, and synthesize results.
+
+## Core Responsibilities
+
+1. **Task breakdown** — split work into independent units that agents can tackle in parallel
+2. **Agent assignment** — match tasks to the right agent type based on what tools they need
+3. **Progress tracking** — monitor task completion, nudge stuck agents, reassign if needed
+4. **Quality gates** — verify results between phases (especially between waves)
+5. **Synthesis** — combine outputs from multiple agents into a single coherent result
+
+## How You Work
+
+### Reading Project Context
+
+At the start of any team session:
+1. Check `.memory/index.md` if it exists — this has project knowledge from past sessions
+2. Check `.planning/` if it exists — this has specs, plans, and wave decompositions
+3. Read the project's `CLAUDE.md` for conventions and rules
+
+### Task Management
+
+- Use `TaskCreate` for each work item. Be specific in descriptions.
+- Set `addBlockedBy` for real dependencies between tasks. Don't over-constrain.
+- Good task size: 15-60 min of work, max 3 files, one clear deliverable.
+- Aim for 5-6 tasks per teammate.
+
+### Spawning Teammates
+
+Pick the right agent type for each role:
+
+| Role | Agent Type | Why |
+|------|-----------|-----|
+| Code implementation | `general-purpose` | Needs Edit/Write/Bash tools |
+| Code review | `phase-reviewer` or `general-purpose` | Needs Read + project rules |
+| Research / exploration | `Explore` | Read-only, fast, focused |
+| Architecture / planning | `Plan` | Read-only, designs solutions |
+| Idea critique | `idea-killer` | Harsh evaluator |
+
+### Communication Protocol
+
+- **Messages arrive automatically.** Don't poll or check inbox.
+- **Teammates go idle between turns.** This is normal. Send a message to wake them up.
+- **Use direct messages** (`to: "agent-name"`) for specific agents.
+- **Use broadcast** (`to: "*"`) only when everyone needs the same info. It costs tokens.
+- **Don't send JSON status messages.** Use plain text. Use TaskUpdate for status changes.
+
+### Wave Execution Protocol
+
+When executing waves from a GSD plan:
+
+1. **Parse the plan** — identify work units and their wave assignments
+2. **Execute one wave at a time** — all WUs in a wave can run in parallel
+3. **Verify between waves** — run tests, check for conflicts
+4. **Advance only when clean** — don't start Wave N+1 until Wave N passes all checks
+
+```
+Wave 1: spawn agents → work in parallel → all complete → verify tests
+  ↓ (tests pass)
+Wave 2: spawn agents → work in parallel → all complete → verify tests
+  ↓ (tests pass)
+Wave 3: integration → final verification
+```
+
+### Conflict Resolution
+
+When agents work on overlapping areas:
+- Use `isolation: "worktree"` to give each agent its own repo copy
+- After completion, merge worktree changes one at a time
+- If merge conflicts arise, resolve them yourself or ask the user
+
+## Working Principles
+
+- **Bias toward parallel work.** If two tasks don't depend on each other, run them at the same time.
+- **Small teams over big teams.** 2-3 focused agents beat 6 scattered ones.
+- **Fail fast.** If an agent is stuck for more than 2 messages, reassign or handle it yourself.
+- **Don't micromanage.** Give clear specs, let agents work, review results.
+- **Synthesize, don't just collect.** When agents report back, combine their outputs into a single coherent result. Don't dump raw agent outputs on the user.
+
+## Communication Style
+
+- Direct and brief. No fluff.
+- Report progress as a table (task, owner, status).
+- Flag blockers immediately — don't wait for the user to ask.
+- When synthesizing results, lead with the conclusion, then supporting details.

package/claude-md/30-project-mgmt.md

@@ -13,6 +13,7 @@
 | `/spartan:forensics "problem"` | Post-mortem investigation — diagnose failed workflows |
 | `/spartan:brownfield [svc]` | Map existing codebase; generates CONTEXT-MAP.md |
 | `/spartan:map-codebase` | Deep codebase analysis and architecture mapping |
+| `/spartan:team [action]` | Agent Teams: `create`, `status`, `wave`, `review`, `research`, `build`, `clean` |
 
 ### Office Hours (GSD Discuss Phase)
 When running `/spartan:phase discuss N`, Claude MUST ask these 3 forcing questions BEFORE gathering requirements:
@@ -90,3 +91,29 @@ Multi-tab: each Claude Code tab handles one WU from the same wave.
 ```
 
 Users never need to type `/gsd:*` commands — the wrappers handle everything.
+
+### Agent Teams (Experimental)
+
+**Requires:** `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` env var set to `1`.
+
+Agent Teams replace manual multi-tab parallelism with automated multi-agent coordination. Multiple Claude Code sessions share a task list, communicate via messages, and work in parallel.
+
+| Command | What it does |
+|---|---|
+| `/spartan:team create` | Create a team with smart defaults for a task |
+| `/spartan:team status` | Show team progress and teammate states |
+| `/spartan:team wave` | Execute a GSD wave plan using Agent Teams |
+| `/spartan:team review` | Quick-spawn: parallel review team (quality + tests + security) |
+| `/spartan:team research` | Quick-spawn: research swarm (breadth + depth + contrarian) |
+| `/spartan:team build` | Quick-spawn: parallel implementation team |
+| `/spartan:team clean` | Shut down teammates and clean up |
+
+**How it bridges waves:**
+```
+Wave plan (.planning/)  →  /spartan:team wave  →  Agent Teams
+  WU-1, WU-3, WU-5         TeamCreate              Teammate per WU
+  (was: manual tabs)        TaskCreate per WU       Worktree isolation
+                            Spawn agents            Auto-advance waves
+```
+
+Teams store state in `~/.claude/teams/` and `~/.claude/tasks/`. Clean up with `/spartan:team clean`.

package/commands/spartan/build.md

@@ -241,6 +241,36 @@ Write the first failing test for Task 1. Show it fails.
 
 ## Stage 3: Implement
 
+### Agent Teams boost (if enabled)
+
+```bash
+echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not_set}"
+```
+
+**If Agent Teams is enabled AND the plan has 4+ tasks AND the feature is full-stack:**
+
+Offer to parallelize implementation with Agent Teams:
+> "This has [N] tasks across backend and frontend. Want me to spin up a build team?
+>
+> I'd go with **A** — parallel tracks save time on full-stack work.
+>
+> - **A) Build team** — one backend agent + one frontend agent, working in parallel (uses more tokens)
+> - **B) Sequential** — I'll do all tasks one by one (cheaper, simpler)"
+
+If user picks A:
+1. Use `TeamCreate` with name `build-{feature-slug}`
+2. Create tasks from the plan — backend tasks assigned to `backend-dev`, frontend tasks to `frontend-dev`
+3. Set `addBlockedBy` for frontend tasks that need backend API first
+4. Spawn two agents with `isolation: "worktree"`:
+   - **backend-dev** — gets backend tasks, relevant Kotlin/Micronaut rules
+   - **frontend-dev** — gets frontend tasks, relevant React/Next.js rules
+5. Monitor progress. When both finish, merge worktrees and run full test suite.
+6. After completion, use `TeamDelete` to clean up.
+
+If user picks B (or Agent Teams not enabled), continue with sequential execution below.
+
+### Sequential execution (default)
+
 Execute each task in order:
 
 ### For each task:

package/commands/spartan/gate-review.md

@@ -76,7 +76,34 @@ Note any issues you find. Fix what you can before calling the reviewer.
 
 ---
 
-## Step 3: Spawn the Reviewer
+## Step 3: Spawn the Reviewer(s)
+
+### Agent Teams boost (if enabled)
+
+```bash
+echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not_set}"
+```
+
+**If Agent Teams is enabled AND the diff has 10+ changed files or touches 3+ modules:**
+
+Offer to use a review team for parallel review:
+> "This is a big change ([N] files across [N] modules). Want a parallel review team?
+>
+> I'd go with **A** — multiple reviewers catch different things.
+>
+> - **A) Review team** — quality reviewer + test reviewer + security reviewer, all in parallel
+> - **B) Single reviewer** — one phase-reviewer agent (cheaper, faster for small changes)"
+
+If user picks A → run `/spartan:team review` internally. Three agents review in parallel:
+1. **quality-reviewer** — code design, SOLID, clean code, stack conventions
+2. **test-reviewer** — test coverage, edge cases, test quality
+3. **security-reviewer** — auth, input validation, data handling
+
+After all report back, synthesize findings and continue to Step 4 (Discussion).
+
+If user picks B (or Agent Teams not enabled) → use single reviewer below.
+
+### Single reviewer (default)
 
 Spawn the `phase-reviewer` agent as a subagent. Give it:
 

package/commands/spartan/map-codebase.md

@@ -42,7 +42,26 @@ All documents include **file paths in backticks** so Claude can navigate directl
 
 ## Execution
 
-Delegate to GSD's map-codebase workflow:
+### Agent Teams boost (if enabled)
+
+```bash
+echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not_set}"
+```
+
+**If Agent Teams is enabled**, use a coordinated mapping team instead of independent subagents:
+
+1. Use `TeamCreate` with name `map-{project-slug}`
+2. Create 4 tasks — one per domain (tech, architecture, quality, concerns)
+3. Spawn 4 agents in parallel:
+   - **tech-mapper** — STACK.md + INTEGRATIONS.md
+   - **arch-mapper** — ARCHITECTURE.md + STRUCTURE.md
+   - **quality-mapper** — CONVENTIONS.md + TESTING.md
+   - **concerns-mapper** — CONCERNS.md
+4. Agents can message each other if they find cross-cutting issues (e.g., tech mapper finds a security concern → messages concerns-mapper)
+5. After all complete, verify 7 documents exist and are non-empty
+6. Clean up team with `TeamDelete`
+
+**If Agent Teams is NOT enabled**, delegate to GSD:
 
 **Run this command now:**
 

package/commands/spartan/onboard.md

@@ -103,6 +103,25 @@ git branch -a | head -20
 
 **Goal:** Understand how the pieces fit together. Build a mental model.
 
+### Agent Teams boost (if enabled)
+
+```bash
+echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not_set}"
+```
+
+**If Agent Teams is enabled AND the codebase is large (50+ files or multi-module):**
+
+Run a parallel mapping team for faster analysis:
+1. Use `TeamCreate` with name `onboard-{project-slug}`
+2. Spawn 2-3 mapper agents in parallel:
+   - **stack-mapper** — tech stack, dependencies, build tools
+   - **arch-mapper** — architecture patterns, data flow, entry points
+   - **quality-mapper** — conventions, test patterns, concerns
+3. After all report back, synthesize into the architecture overview below
+4. Clean up team with `TeamDelete`
+
+**If Agent Teams is NOT enabled (or codebase is small)**, map manually:
+
 ### Architecture mapping
 
 Use the approach from `/spartan:map-codebase` internally:

package/commands/spartan/phase.md

@@ -61,6 +61,30 @@ If the user has multiple Claude Code tabs available, suggest:
 
 Running the planned tasks wave by wave.
 
+### Agent Teams boost (if enabled)
+
+```bash
+echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not_set}"
+```
+
+**If Agent Teams is enabled AND the wave plan has 2+ parallel work units in any wave:**
+
+Offer to use Agent Teams for wave execution:
+> "Wave 1 has [N] parallel work units. Want me to use Agent Teams?
+>
+> I'd go with **A** — it automates what you'd do manually across tabs.
+>
+> - **A) Agent Teams** — one agent per WU, worktree isolation, auto-advance between waves
+> - **B) Manual** — I'll execute sequentially, or you open multiple tabs yourself"
+
+If user picks A → run `/spartan:team wave` internally. This:
+1. Creates a team from the wave plan
+2. Spawns one agent per WU with worktree isolation
+3. Verifies tests pass between waves
+4. Auto-advances to the next wave
+
+If user picks B (or Agent Teams not enabled) → continue with default execution:
+
 **Run:** `/gsd:execute-phase {{ args[1] | default: "N" }}`
 
 During execution:

package/commands/spartan/research.md

@@ -75,6 +75,25 @@ Options:
 
 **Goal:** Find real data from real sources. Track everything.
 
+### Agent Teams boost (if enabled)
+
+```bash
+echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not_set}"
+```
+
+**If Agent Teams is enabled**, run parallel research agents for faster, broader coverage:
+
+1. Use `TeamCreate` with name `research-{topic-slug}`
+2. Spawn 2-3 agents based on the source strategy from Stage 1:
+   - **breadth-researcher** — runs direct + alternative + adjacent queries, collects 8-15 sources
+   - **depth-researcher** — picks the top 3-5 sources from breadth, goes deep on each
+   - **contrarian-researcher** (optional) — searches for counterarguments, failures, criticism
+3. Each agent tracks sources with credibility scores (see format below)
+4. After all report back, merge source lists and continue to Stage 3 (Analyze)
+5. Clean up team with `TeamDelete`
+
+**If Agent Teams is NOT enabled**, gather sequentially:
+
 ### Search strategy
 Use the `deep-research` skill. Run multiple search queries — not just one:
 

package/commands/spartan/startup.md

@@ -128,6 +128,26 @@ Based on results:
 
 ## Stage 3: Dig
 
+### Agent Teams boost (if enabled)
+
+```bash
+echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not_set}"
+```
+
+**If Agent Teams is enabled**, run market research and competitor teardowns in parallel:
+
+1. Use `TeamCreate` with name `research-{idea-slug}`
+2. Spawn 2-3 agents:
+   - **market-researcher** — TAM/SAM/SOM, growth signals, adjacent markets
+   - **competitor-analyst** — teardown 3+ competitors, find gaps
+   - **contrarian** (optional) — challenge assumptions, find risks
+3. After all report back, synthesize into a single research doc
+4. Clean up team with `TeamDelete`
+
+Skip to step 11 (synthesis) after team reports back.
+
+**If Agent Teams is NOT enabled**, run sequentially:
+
 9. Use the `market-research` skill — TAM/SAM/SOM, growth signals, adjacent markets
 10. Use the `competitive-teardown` skill — at least 3 competitors, strengths, weaknesses, gaps
 11. Write synthesis:

package/commands/spartan/team.md

@@ -0,0 +1,505 @@
+---
+name: spartan:team
+description: Manage Claude Code Agent Teams — coordinate multi-agent work with shared tasks, messaging, and parallel execution. Bridges wave-based planning with native agent teams.
+argument-hint: "[create | status | wave | review | research | build | clean]"
+preamble-tier: 3
+---
+
+# Agent Teams: {{ args[0] | default: "create" }}
+
+You are managing **Claude Code Agent Teams** — multiple Claude Code sessions working together with shared task lists, direct messaging, and coordinated parallel execution.
+
+**What are Agent Teams?** Native Claude Code feature where one session (team lead) coordinates multiple teammate sessions. Each teammate has its own context window, works independently, and communicates via messages. Unlike subagents, teammates can talk to each other directly.
+
+---
+
+## Prerequisites Check (always run first)
+
+Before any sub-action, check that Agent Teams is enabled:
+
+```bash
+echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not_set}"
+```
+
+**If `not_set`**, stop and tell the user:
+
+> Agent Teams needs to be enabled first. Add this to your settings:
+>
+> **Option A — settings.json** (in `~/.claude/settings.json` or `.claude/settings.json`):
+> ```json
+> {
+>   "env": {
+>     "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+>   }
+> }
+> ```
+>
+> **Option B — shell** (temporary, current session only):
+> ```bash
+> export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
+> ```
+>
+> Then run `/spartan:team` again.
+
+**If enabled**, proceed to the routed sub-action below.
+
+---
+
+## Route by argument
+
+{% if args[0] == "create" or args[0] == nil %}
+## Create Team
+
+Create a new agent team for coordinated parallel work.
+
+### Step 1: Understand the task
+
+Ask the user (if not already clear from context):
+
+> What's the goal for this team?
+>
+> I'd go with **A** — most tasks fit a small focused team.
+>
+> - **A) Small team (2-3 agents)** — fast coordination, low token cost, good for most tasks
+> - **B) Medium team (4-5 agents)** — parallel research or multi-module builds
+> - **C) Custom** — you tell me the roles
+
+### Step 2: Design the team
+
+Based on the task, decide:
+- **Team name** — kebab-case, descriptive (e.g., `auth-refactor`, `api-review`, `market-research`)
+- **Teammate roles** — what each agent does (e.g., "backend-impl", "frontend-impl", "test-writer")
+- **Agent types** — pick the right `subagent_type` for each role:
+  - `general-purpose` — for implementation work (has all tools including Edit/Write)
+  - `Explore` — for read-only research and codebase exploration
+  - `Plan` — for architecture and planning (read-only, no edits)
+  - Custom agents from `~/.claude/agents/` — for specialized work (e.g., `phase-reviewer`)
+
+### Step 3: Create the team
+
+Use `TeamCreate` with the team name and description:
+
+```
+TeamCreate:
+  team_name: "{descriptive-kebab-name}"
+  description: "Brief description of what the team is doing"
+```
+
+### Step 4: Create tasks
+
+Use `TaskCreate` for each work item. Set up dependencies with `addBlockedBy` where needed.
+
+Good tasks are:
+- **Specific** — "Implement user authentication endpoint" not "do backend work"
+- **Self-contained** — one agent can finish it without waiting on others
+- **Sized right** — 15-60 min of work each. 5-6 tasks per teammate is ideal.
+
+### Step 5: Spawn teammates
+
+For each teammate, use the `Agent` tool with `team_name` and `name` parameters:
+
+```
+Agent:
+  team_name: "{team-name}"
+  name: "{teammate-role}"
+  subagent_type: "{agent-type}"
+  prompt: |
+    You are {role description}.
+
+    Your tasks are in the shared task list. Check TaskList, claim unassigned
+    tasks with TaskUpdate (set owner to your name), and work through them.
+
+    Context:
+    - Project: {brief project context}
+    - Your focus: {what this agent should work on}
+    - Key files: {relevant file paths}
+
+    When done with a task, mark it completed and check TaskList for next work.
+    Message the team lead if you're blocked or need input.
+```
+
+**Key rules for spawn prompts:**
+- Tell the agent to check `TaskList` and self-claim tasks
+- Give file paths, not inline content (saves context)
+- Reference `.memory/` and `.planning/` if they exist
+- Use `isolation: "worktree"` when agents edit overlapping files
+
+### Step 6: Monitor and coordinate
+
+After spawning:
+- Messages from teammates come in automatically — no polling needed
+- Use `SendMessage` to redirect or give feedback
+- Teammates go idle between turns — this is normal, send them a message to wake them up
+- When all tasks are done, proceed to cleanup
+
+Tell the user: "Team `{name}` is running with {N} teammates. I'll coordinate and report back as they finish."
+
+{% elif args[0] == "status" %}
+## Team Status
+
+Show the current state of the active team.
+
+### Step 1: Find active teams
+
+```bash
+ls -la ~/.claude/teams/ 2>/dev/null || echo "NO_TEAMS_DIR"
+```
+
+If no teams directory or empty, tell user: "No active teams. Run `/spartan:team create` to start one."
+
+### Step 2: Read team config
+
+For each team found, read the config:
+
+```bash
+cat ~/.claude/teams/*/config.json 2>/dev/null
+```
+
+### Step 3: Show task progress
+
+Use `TaskList` to show all tasks and their status.
+
+Display as a table:
+
+```
+## Team: {team-name}
+| # | Task | Owner | Status |
+|---|------|-------|--------|
+| 1 | Implement auth endpoint | backend-dev | completed |
+| 2 | Write auth tests | test-writer | in_progress |
+| 3 | Add login page | frontend-dev | pending |
+```
+
+**Summary:** X of Y tasks done. Teammates: {list with idle/active state}.
+
+Suggest next actions:
+- All done? → "Run `/spartan:team clean` to shut down"
+- Some stuck? → "I can message {teammate} to check on task #{N}"
+- Need more work? → "I can add more tasks with TaskCreate"
+
+{% elif args[0] == "wave" %}
+## Wave Execution with Agent Teams
+
+Execute a GSD wave plan using Agent Teams instead of manual multi-tab work.
+
+### Step 1: Find the wave plan
+
+```bash
+# Look for the current phase plan
+ls .planning/milestones/*/phases/*/PLAN.md 2>/dev/null
+ls .planning/PLAN.md 2>/dev/null
+```
+
+If no plan found:
+> No wave plan found. Run `/spartan:phase plan N` first to create a plan with wave decomposition.
+> Or run `/spartan:team create` to build a team from scratch.
+
+If found, read the plan and look for wave structure (sections like "Wave 1", "Wave 2", or work units with dependency info).
+
+### Step 2: Parse waves
+
+From the plan, extract:
+- **Work units (WUs)** — each atomic task
+- **Wave assignments** — which WUs can run in parallel (Wave 1), which depend on earlier waves
+- **File paths** — what each WU touches
+
+### Step 3: Create team for current wave
+
+Identify which wave to execute (usually the first incomplete one).
+
+Use `TeamCreate`:
+```
+team_name: "{milestone}-wave-{N}"
+description: "Wave {N} execution: {list of WU names}"
+```
+
+### Step 4: Create tasks from WUs
+
+For each WU in the current wave, `TaskCreate` with:
+- Subject from WU name
+- Description from WU spec + acceptance criteria
+- For Wave 2+ WUs, set `addBlockedBy` pointing to Wave 1 task IDs
+
+### Step 5: Spawn one agent per WU
+
+Each agent gets:
+- A worktree (`isolation: "worktree"`) for safe parallel edits
+- The WU spec as its prompt
+- References to `.memory/` for project context
+- The specific file paths it should touch
+
+```
+Agent:
+  team_name: "{team-name}"
+  name: "wu-{N}-{short-slug}"
+  subagent_type: "general-purpose"
+  isolation: "worktree"
+  prompt: |
+    You are implementing Work Unit {N}: {WU title}.
+
+    Spec: {WU description from plan}
+    Files to touch: {file list}
+    Acceptance criteria: {from plan}
+
+    Read .memory/index.md for project context.
+    Follow TDD: write test first, then implement, then verify.
+
+    When done, mark your task completed and message the lead.
+```
+
+### Step 6: Monitor wave completion
+
+Wait for all Wave N agents to complete. Between waves:
+
+1. Verify all tests pass:
+```bash
+# Run the project's test command
+./gradlew test 2>&1 | tail -20  # or npm test, etc.
+```
+
+2. If tests pass → advance to Wave N+1 (create new tasks, spawn new agents)
+3. If tests fail → message the relevant agent to fix, or handle it yourself
+
+### Step 7: Complete
+
+After all waves finish:
+- Run full test suite
+- Tell user: "All {N} waves complete. {X} work units done. Tests: {pass/fail}."
+- Suggest: "Run `/spartan:team clean` to shut down, then `/spartan:pr-ready` to ship."
+
+{% elif args[0] == "review" %}
+## Quick Spawn: Review Team
+
+Spin up a parallel review team for a PR or set of changes.
+
+### Step 1: Identify what to review
+
+Check for a PR number in args, or detect changes:
+```bash
+git diff --stat main...HEAD 2>/dev/null || git diff --stat HEAD~3..HEAD
+```
+
+### Step 2: Create review team
+
+```
+TeamCreate:
+  team_name: "review-{branch-or-pr}"
+  description: "Parallel code review"
+```
+
+### Step 3: Create review tasks
+
+Create 2-3 focused review tasks:
+1. **Code quality** — design, SOLID, clean code, stack conventions
+2. **Test coverage** — are tests adequate, edge cases covered, test quality
+3. **Security** (if applicable) — auth, input validation, data handling
+
+### Step 4: Spawn reviewers
+
+Spawn 2-3 agents with appropriate expertise:
+
+- **quality-reviewer** — use `phase-reviewer` agent type if available, otherwise `general-purpose`
+- **test-reviewer** — `general-purpose` agent focused on test analysis
+- **security-reviewer** (optional) — `general-purpose` agent focused on security
+
+Each reviewer gets:
+- The diff or changed file list
+- Their specific review focus
+- Instructions to report findings in the Gate 3.5 format
+
+### Step 5: Synthesize
+
+When all reviewers report back:
+- Combine findings into one review summary
+- Deduplicate overlapping issues
+- Prioritize: HIGH (must fix) → MEDIUM (should fix) → LOW (nice to have)
+- Give verdict: **ACCEPT** or **NEEDS CHANGES**
+
+{% elif args[0] == "research" %}
+## Quick Spawn: Research Team
+
+Spin up a research swarm to explore a topic from multiple angles.
+
+### Step 1: Get the topic
+
+Use `{{ args[1] }}` if provided, otherwise ask the user what to research.
+
+### Step 2: Create research team
+
+```
+TeamCreate:
+  team_name: "research-{topic-slug}"
+  description: "Research: {topic}"
+```
+
+### Step 3: Design research angles
+
+Create 2-3 complementary research tasks:
+1. **Breadth search** — survey the landscape, find key sources, map the space
+2. **Depth analysis** — go deep on the most promising findings from breadth
+3. **Contrarian view** (optional) — find counterarguments, risks, things that could go wrong
+
+### Step 4: Spawn researchers
+
+- **surveyor** — `Explore` or `general-purpose` with web search focus
+- **analyst** — `general-purpose` for deep analysis
+- **contrarian** — `general-purpose` playing devil's advocate (use `idea-killer` agent if available)
+
+Each gets the topic + their angle + instructions to report structured findings.
+
+### Step 5: Synthesize
+
+Combine into a structured report:
+- Key findings (agreed across agents)
+- Disagreements (where agents had different conclusions)
+- Recommendations
+- Sources and confidence levels
+
+Save to `.planning/research/{topic-slug}.md` if in a project context.
+
+{% elif args[0] == "build" %}
+## Quick Spawn: Build Team
+
+Spin up a parallel implementation team for a feature.
+
+### Step 1: Understand the feature
+
+Check for existing spec/plan:
+```bash
+ls .planning/specs/ .planning/PLAN.md 2>/dev/null
+```
+
+If no spec exists, tell user: "No spec found. Run `/spartan:spec` first, or describe the feature and I'll split it into parallel work."
+
+### Step 2: Detect stack and split work
+
+```bash
+ls build.gradle.kts package.json next.config.* 2>/dev/null
+```
+
+Split strategy:
+- **Full-stack** → one backend agent + one frontend agent
+- **Backend only** → split by service boundaries or layers (API + data + tests)
+- **Frontend only** → split by pages/components + tests
+
+### Step 3: Create build team
+
+```
+TeamCreate:
+  team_name: "build-{feature-slug}"
+  description: "Building: {feature name}"
+```
+
+### Step 4: Create implementation tasks
+
+From the spec/plan, create tasks for each parallel track. Set `addBlockedBy` for tasks that depend on earlier ones (e.g., frontend depends on API being done).
+
+### Step 5: Spawn builders
+
+Each builder agent gets:
+- Worktree isolation (`isolation: "worktree"`)
+- Their track's tasks and file paths
+- Instructions to follow TDD
+- References to relevant rules from installed packs
+- `.memory/` context
+
+### Step 6: Integration
+
+After parallel tracks complete:
+1. Merge worktree changes
+2. Run full test suite
+3. Fix any integration issues
+4. Report results to user
+
+{% elif args[0] == "clean" %}
+## Clean Up Team
+
+Shut down all teammates and clean up team resources.
+
+### Step 1: Find active teams
+
+```bash
+ls ~/.claude/teams/ 2>/dev/null || echo "NO_TEAMS"
+```
+
+If no teams, tell user: "No active teams to clean up."
+
+### Step 2: Check for active teammates
+
+Read team config to find members. For each active teammate, send a shutdown request:
+
+```
+SendMessage:
+  to: "{teammate-name}"
+  message:
+    type: "shutdown_request"
+    reason: "Team work complete, shutting down"
+```
+
+Wait for shutdown responses. If a teammate rejects, tell the user why.
+
+### Step 3: Delete team
+
+After all teammates are shut down, use `TeamDelete` to clean up:
+
+```
+TeamDelete: {}
+```
+
+This removes:
+- `~/.claude/teams/{team-name}/`
+- `~/.claude/tasks/{team-name}/`
+
+### Step 4: Report
+
+Tell user: "Team `{name}` cleaned up. {N} teammates shut down, task list removed."
+
+If there were orphaned tmux sessions:
+```bash
+tmux ls 2>/dev/null | grep -i "{team-name}" || echo "no orphaned sessions"
+```
+
+If found, suggest: `tmux kill-session -t {session-name}`
+
+{% else %}
+## Unknown argument: {{ args[0] }}
+
+Available options:
+- `/spartan:team` — Create a new agent team (default)
+- `/spartan:team create` — Create a team with smart defaults
+- `/spartan:team status` — Show team progress and teammate states
+- `/spartan:team wave` — Execute a GSD wave plan using Agent Teams
+- `/spartan:team review` — Quick-spawn: parallel review team
+- `/spartan:team research` — Quick-spawn: research swarm
+- `/spartan:team build` — Quick-spawn: parallel build team
+- `/spartan:team clean` — Shut down teammates and clean up
+{% endif %}
+
+---
+
+## Best Practices (applies to all sub-actions)
+
+### Team Size
+- **2-3 agents** for most tasks. Start small.
+- **4-5 agents** only when work is truly independent (no shared files).
+- More agents = more tokens. Each agent has its own context window.
+
+### Task Design
+- 5-6 tasks per teammate keeps everyone productive.
+- Each task should be 15-60 min of work.
+- Set `addBlockedBy` for real dependencies. Don't block unnecessarily.
+
+### Isolation
+- Use `isolation: "worktree"` when agents might edit the same files.
+- Without worktrees, agents work in the same repo — last write wins.
+
+### Communication
+- Messages are delivered automatically. Don't poll.
+- Teammates go idle between turns — send a message to wake them up.
+- Use `SendMessage` with `to: "*"` sparingly — it costs tokens for every teammate.
+
+### Integration with Spartan Workflow
+- **After team work** → `/spartan:pr-ready` for the full pre-PR checklist
+- **Wave execution** → `/spartan:team wave` replaces manual multi-tab work from GSD v5
+- **Review teams** → works alongside `/spartan:gate-review` for dual-agent reviews
+- **Research teams** → feeds into `/spartan:research` report format

package/commands/spartan.md

@@ -111,6 +111,11 @@ Route here when the user wants a specific tool, not a full workflow.
 | "big project", "multi-day", "new milestone" | `/spartan:project new` |
 | "continue phase", "next phase" | `/spartan:phase` |
 | "workstreams", "parallel work" | `/spartan:workstreams` |
+| "agent team", "spawn team", "create team", "multi-agent" | `/spartan:team` |
+| "run wave with agents", "execute wave with team" | `/spartan:team wave` |
+| "parallel review", "team review" | `/spartan:team review` |
+| "research swarm", "parallel research" | `/spartan:team research` |
+| "parallel build", "team build" | `/spartan:team build` |
 | "standup", "what did I do" | `/spartan:daily` |
 
 **Product thinking:**
@@ -248,6 +253,8 @@ You don't have to wait for the user to type `/spartan`. When you notice these pa
 | User is confused about what to do next | "Type `/spartan` and I'll figure out the right workflow." |
 | User just finished a big feature, no tests mentioned | "Should we add tests? `/spartan:e2e` for browser tests, or unit tests first." |
 | User has been coding for a while, no review mentioned | "Want a quick review before moving on? `/spartan:review`" |
+| User has a wave plan with 3+ parallel work units | "This wave has parallel tasks — want to use `/spartan:team wave` to run them with Agent Teams?" |
+| User wants multiple things reviewed or researched at once | "I can spin up a team for parallel work — `/spartan:team`" |
 
 ### How to suggest
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c0x12c/spartan-ai-toolkit",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "Engineering discipline layer for AI coding agents — commands, rules, skills, agents, and packs for Claude Code",
   "type": "module",
   "bin": {

package/packs/packs.compiled.json

@@ -191,11 +191,14 @@
         "gsd-upgrade",
         "forensics",
         "brownfield",
-        "map-codebase"
+        "map-codebase",
+        "team"
       ],
       "rules": [],
       "skills": [],
-      "agents": [],
+      "agents": [
+        "team-coordinator.md"
+      ],
       "claudeSections": [
         "30-project-mgmt.md"
       ]

package/packs/project-mgmt.yaml

@@ -13,10 +13,12 @@ commands:
   - forensics
   - brownfield
   - map-codebase
+  - team
 
 rules: []
 skills: []
-agents: []
+agents:
+  - team-coordinator.md
 
 claude-sections:
   - 30-project-mgmt.md