Help us improve
Share bugs, ideas, or general feedback.
From dream-team
Executes implementation plans from spec files: detects mode (sequential, delegated, team) from YAML frontmatter, creates git feature branches, manages task dependencies, dispatches agents, runs validations/hooks.
npx claudepluginhub ratler/dream-team --plugin dream-teamHow this skill is triggered — by the user, by Claude, or both
Slash command
/dream-team:buildThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Execute an implementation plan by reading a spec file and running the strategy matching its declared mode.
Executes coding work from plan documents or prompts via triage, codebase scanning, and phased implementation with beta delegation for token efficiency.
Spawns parallel agent implementers in tmux split panes to execute implementation plans, orchestrated by team lead with spec compliance and code quality review gates. For 3+ independent tasks across files.
Executes tasks from TASK_N.md files or free-form descriptions, auto-generating missing scope, success criteria, and verification plans via /generate-tasks before implementation.
Share bugs, ideas, or general feedback.
Execute an implementation plan by reading a spec file and running the strategy matching its declared mode.
SPEC_PATH: $ARGUMENTS
AVAILABLE_AGENTS: ${CLAUDE_PLUGIN_ROOT}/agents/*.md
Agent spawning has real cost — each sub-agent consumes tokens for context loading, tool calls, and reporting. Before dispatching, ask: "Is this task complex enough to justify a separate agent?" A one-line config change does not need a builder agent, a review agent, and a validation agent. Use judgment:
SPEC_PATH is provided, stop and ask the user to provide it.mode, complexity, type, playwright, frontend-design, spec-version, and branch.spec-version is missing from frontmatter, log a warning ("spec written before spec-version was introduced — consider updating") but proceed normally. This ensures backwards compatibility.branch is present in frontmatter, this is a resumed build — see Resuming a Build below.mode, follow the corresponding execution strategy below.playwright: true, append the Playwright instructions (see below) to every builder and tester agent dispatch prompt. If playwright: false or missing, do NOT mention Playwright to agents.frontend-design: true, read ${CLAUDE_PLUGIN_ROOT}/templates/frontend-design-guidelines.md and the spec's ## Design Direction section. Append the Frontend Design Instructions (see below) to every builder agent dispatch prompt. If frontend-design: false or missing, do NOT mention frontend design to agents.branch: feat/<spec-name> into the spec file's frontmatter to mark the build as started.## Step by Step Tasks section.addBlockedBy to set dependencies per each task's Depends On field.## Validation Commands and verify ## Acceptance Criteria.If the spec's frontmatter contains a branch field, this is a resumed build:
.md extension, e.g., specs/2026-03-14-my-feature.md → specs/.build-state/my-feature).<task-id>.json file)."completed" tasks: create with status completed. Set the task description to the saved description field from the state file (this preserves agent reports and context)."in_progress" tasks: create with status in_progress. Set the description to the saved description (if any) plus a note: "RESUMED: This task was interrupted in a previous session. Check git log and changed files to determine what was completed before continuing.""pending" tasks: create normally.addBlockedBy per each task's dependsOn field from the state files.If the state directory does not exist but branch does, fall back to git-history-based resume: check out the branch, inspect commits with git log, and infer progress from what files exist and what tests pass.
Build state is persisted to disk so builds can resume from a fresh session. State directory: specs/.build-state/<spec-name>/ (derived by stripping the date prefix and .md extension from the spec filename).
After creating the feature branch and before creating tasks:
_meta.json with: specFile (spec path), branch (feature branch name), mode (from frontmatter), startedAt (current ISO timestamp), lastUpdated (same as startedAt), compactions (0).## Step by Step Tasks section, write a <task-id>.json file with: name (task name), status "pending", agentType (from spec Agent Type field, or "sequential" for sequential mode), startedAt null, completedAt null, lastUpdated (current ISO timestamp), description null, commitSha null, filesChanged [], dependsOn (array of task IDs from the Depends On field).The TaskCompleted hook automatically updates the task state file to "completed" with the agent's description, timestamp, and commit info. You do NOT need to manually update state files for task status transitions — the hook handles it.
After committing code, update the completed task's state file: set commitSha to the commit SHA and filesChanged to the list of files in that commit.
Delegated mode: Builder and debugger agents running in worktrees MUST commit their own changes inside the worktree before marking the task complete. The orchestrator then merges the worktree branch back into the feature branch. Read-only agents do not commit.
Team mode: Agents do NOT touch git. All git operations are handled by the orchestrator (teammates have no worktree isolation).
Before executing any tasks:
branch field. If yes, check out that branch — this is a resumed build (see Resuming a Build above).branch field, create a new feature branch:
git checkout -b feat/<spec-name-without-date>
Derive the branch name from the spec filename. For example, specs/2026-02-07-user-auth-api.md becomes feat/user-auth-api.branch: feat/<spec-name> into the spec file's YAML frontmatter (before the closing ---). This marks the spec as "build started" so it can be resumed if interrupted.branch field in frontmatter, check it out and add the field.Commit after each task passes review — never before review approval. This ensures only reviewed code enters the history.
Use this commit message format:
git add <files changed by the task>
git commit -m "<type>(<scope>): <what changed>"
Where <type> is one of: feat, fix, refactor, test, docs, chore. Keep the first line under 72 characters. Do NOT include internal task IDs in commit messages.
After all acceptance criteria pass, do NOT merge or push. Report the branch name and let the user decide what to do next.
You execute tasks directly — no sub-agents.
Follow the spec literally. When the spec provides exact values (hex colors, string templates, element types, class names, timeout values, API parameters, units), use those exact values. Do not substitute your own preferences — the spec author chose specific values to ensure reproducible builds. If the spec says #e57373, use #e57373 — not a "similar" red. If the spec says createElement("div"), use a div — not a p or span. If the spec says timeout: 10000, use 10000 — not 5000. Treat the spec as a blueprint, not a suggestion.
frontend-design: true, read ${CLAUDE_PLUGIN_ROOT}/templates/frontend-design-guidelines.md. When executing tasks that involve frontend/UI code, apply these guidelines along with the spec's ## Design Direction section.in_progress via TaskUpdate.playwright: true and the task involves UI changes, verify visually using Playwright MCP tools (navigate, screenshot, interact, check console). If Playwright tools are not available, skip and note it.completed via TaskUpdate.security-reviewer agent definition from AVAILABLE_AGENTS to load the security checklist. List all files changed on the feature branch (git diff --name-only main...HEAD). Read every changed file and work through the 7-category security checklist systematically. Report findings using Critical/Important/Minor severity. Fix any Critical or Important issues before proceeding to the code review task.docs agent definition from AVAILABLE_AGENTS. Read the spec's ## Documentation Requirements section. List all files changed on the feature branch (git diff --name-only main...HEAD). Read every changed file. Produce all required documentation: README updates, changelog entries, API docs, and inline comments for complex logic. Commit documentation changes with git add <files> && git commit -m "docs(<scope>): <description>".You are the orchestrator. You NEVER write code directly — you dispatch agents. When dispatching builder agents, emphasize that they must follow the spec literally — exact values specified in the task description (hex colors, string formats, element types, timeouts, units) must be used verbatim, not creatively interpreted.
## Review Policy section to understand review rules.scout agent (model: haiku) first to reconnoiter the target area. Use the scout's findings to enrich the builder's dispatch prompt with specific file paths, conventions, and gotchas. Then dispatch the builder.
When in doubt, lean toward dispatching rather than doing it yourself — the cost of a wrong direct implementation exceeds the cost of a sub-agent.Background: true and no dependency conflicts, dispatch with run_in_background: true.Task(subagent_type: "<agent-type>", model: "<model>", ...).model matching the agent definition: builder=opus, researcher=sonnet, reviewer=sonnet, tester=sonnet, validator=haiku, architect=opus, debugger=opus, security-reviewer=opus, docs=sonnet, scout=haiku, merger=sonnet.isolation: "worktree" and always spawn fresh (never reuse — worktrees are cleaned up after completion).reviewer agent (model: sonnet) with the task spec, files changed, and a summary of what the builder did.isolation: "worktree") and include the review feedback plus original task context in the prompt. Do NOT resume the previous builder — its worktree is gone.Max Retries times.completed.security-reviewer agent (model: opus) to audit all files changed on the feature branch. Provide the list of changed files (git diff --name-only main...HEAD) and the spec's acceptance criteria.
Max Retries times.docs agent (model: sonnet) to produce documentation. Provide: the spec's ## Documentation Requirements section, the list of files changed on the feature branch (git diff --name-only main...HEAD), and the spec's acceptance criteria. The docs agent commits its own changes. After the docs agent completes, proceed to the validator.validator agent for final verification.Builder and debugger agents run with isolation: "worktree", each on its own branch. The agent commits its work inside the worktree before marking the task complete. After review approval, the orchestrator merges the worktree branch back into the feature branch.
Protocol:
git worktree list / git branch.git checkout feat/<spec-name>.git merge <worktree-branch> --no-ff -m "merge: <worktree-branch>".merger agent (model: sonnet) with the source branch, target branch, and context about what the builder changed. The merger handles tiered conflict resolution. If the merger agent cannot resolve conflicts, escalate to the user.Note: Read-only agents (reviewer, validator, researcher, security-reviewer, architect) make no file changes — no merge needed.
When creating tasks via TaskCreate, always prefix the task description with [agent-type: <agent-type>] on its own line. For example, a builder task description starts with [agent-type: builder]. This tag is used by the TaskCompleted hook for audit logging.
When dispatching an agent, provide this context:
You are a <agent-type> agent.
**Your Task**: <task name>
**Task ID**: <id>
**IMPORTANT — Literal spec adherence**: When the task description provides exact values (hex colors, string templates, element types, class names, timeout values, API parameters, units), use those exact values. Do not substitute your own preferences. Treat the spec as a blueprint, not a suggestion.
**Description**:
<full task description from the spec, including all bullet points>
**Files to work with**:
<relevant files from the spec>
**File Scope** (builder tasks only):
<list of files this task may create or modify, from the spec's Files field>
These are the ONLY files you may create or modify. Read any file for context, but limit writes to this list.
**Acceptance Criteria for this task**:
<criteria specific to this task>
**Tests required**:
<tests from the spec's Tests field for this task>
**TDD is mandatory.** For every piece of functionality you implement:
1. Write a failing test first
2. Write the minimal code to make it pass
3. Refactor if needed, keeping tests green
Do NOT write implementation code without a corresponding test. If the task has no testable code, explain why in your report.
**Before marking done, commit your changes** with `git add <files> && git commit -m "<type>(<scope>): <what changed>"`. Use conventional commit format (feat, fix, refactor, test, docs, chore). Do NOT include task IDs. This is required so the orchestrator can merge your worktree branch back into the feature branch.
**Then write your completion report into the task description** using TaskUpdate. Include `[agent-type: <agent-type>]` as the first line of your report, followed by your structured report. Then mark the task completed. You can do both in a single TaskUpdate call:
TaskUpdate(taskId: "<id>", status: "completed", description: "[agent-type: <agent-type>]\n## Task Complete\n...")
playwright: true)Append this block to every builder and tester agent dispatch prompt when the spec has playwright: true. Do NOT include it for reviewer, validator, researcher, or architect agents. Do NOT include it if playwright: false or missing.
**Playwright MCP**: This project uses Playwright for frontend verification.
After making UI changes, verify them visually:
- Use playwright_navigate to load the relevant page
- Use playwright_screenshot to capture the current state
- Use playwright_click / playwright_fill to test interactions
- Use playwright_evaluate to check for console errors
If Playwright tools are not available in your tool list, skip this step and note it in your report.
frontend-design: true)Append this block to every builder agent dispatch prompt when the spec has frontend-design: true. Do NOT include it for reviewer, validator, researcher, or architect agents. Do NOT include it if frontend-design: false or missing.
Before dispatching, read ${CLAUDE_PLUGIN_ROOT}/templates/frontend-design-guidelines.md and include its full content in the builder prompt. Also include the spec's ## Design Direction section (aesthetic style, stack, component libraries, design notes).
**Frontend Design**: This project has specific design direction. Follow these guidelines for all UI code.
## Design Direction (from spec)
<paste the spec's Design Direction section here — aesthetic style, stack, component libraries, design notes>
## Frontend Design Guidelines
<paste the full content of templates/frontend-design-guidelines.md here>
Apply these guidelines to all UI code you write. The Design Direction section takes precedence for project-specific choices (aesthetic style, stack, component libraries). The guidelines provide implementation details (animation timings, interaction patterns, accessibility requirements, anti-generic rules).
You are the orchestrator of a dynamic agent team. You NEVER write code directly — you manage agent slots, schedule tasks, and handle git.
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set by attempting to use TeamCreate. If teams are not available, STOP immediately. Tell the user: "This spec uses mode: team, which requires agent teams. Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your environment and restart, or re-spec with /dream-team:spec-delegated as an alternative." Do NOT fall back to delegated mode. Do NOT proceed.## Team Configuration for Display Mode, Coordinate Only, Max Active Agents (default 6), and Rotation After (default 3).Max Active Agents. Ignore "Assigned To" labels and numbered suffixes — they are cosmetic. Schedule by Agent Type only.Coordinate Only: true, enable delegate mode (Shift+Tab) so you only coordinate.All agent slots are equal. No reserved slots. Fill dynamically based on unblocked tasks.
Scheduling loop — repeat until all tasks are complete: a. List all unblocked tasks. Sort: review tasks first, then others. b. For each unblocked task:
model matching agent type (builder=opus, researcher=sonnet, reviewer=sonnet, tester=sonnet, validator=haiku, architect=opus, debugger=opus, security-reviewer=opus, docs=sonnet, scout=haiku). Include full task text, file paths, and acceptance criteria.Max Active Agents. Count active agents before every spawn.
e. Complexity shortcut: For tasks assessed as Simple (1-2 files, config-only, trivial change), the orchestrator may execute them directly instead of spawning a builder. This is optional in team mode — use it to avoid consuming an agent slot for trivial work.Rotation After tasks (default 3). After reaching the limit, retire it and spawn fresh with a handoff summary (completed task IDs, commit SHAs, remaining tasks). Builders are always fresh per task — rotation does not apply to them.Team mode teammates do NOT support isolation: "worktree" — all teammates work directly in the main directory. Committing immediately after each builder completes is the primary mechanism for preventing conflicts.
Protocol:
git status in the main working directory.git add <changed-files> && git commit -m "<type>(<scope>): <what changed>".Note: Read-only agents (reviewer, validator, researcher, security-reviewer, architect) make no file changes, so no commit is needed after them.
Max Retries times.Plan Approval: true on a task, the agent must submit a plan before implementing. Review and approve or reject with feedback before the agent proceeds.security-reviewer agent (model: opus) in a free slot to audit all files changed on the feature branch. Provide the list of changed files (git diff --name-only main...HEAD) and the spec's acceptance criteria. If Critical issues are found, spawn a fresh builder agent (with isolation: "worktree") to fix them. After fixes, commit and re-run the security review. Commit security fixes before proceeding to documentation.docs agent (model: sonnet) in a free slot to produce documentation. Provide: the spec's ## Documentation Requirements section, the list of files changed on the feature branch (git diff --name-only main...HEAD), and the spec's acceptance criteria. Commit the docs agent's changes immediately after it completes (same protocol as builder commits in team mode). Then proceed to the validator.Regardless of mode, after all tasks are done:
## Validation Commands. Record output.## Acceptance Criteria. Mark pass/fail.## Documentation Requirements — verify the docs agent produced all required documentation.Build Complete
Spec: <spec file path>
Mode: <sequential | delegated | team>
Branch: feat/<spec-name>
Tasks: <completed>/<total>
Commits: <number of commits on branch>
Results:
- [x] <acceptance criterion 1> — PASS
- [x] <acceptance criterion 2> — PASS
- [ ] <acceptance criterion 3> — FAIL: <reason>
Validation:
- <command 1> — <result>
- <command 2> — <result>
Status: <ALL PASS | ISSUES FOUND>
If all criteria passed, suggest next steps: merge to main, create a PR, or keep the branch for further work.
If any acceptance criteria failed, list what needs to be fixed and ask the user how to proceed.