Write Team Spec

Convert the brainstorming conversation into a formal spec file for team execution — separate Claude Code instances that work in parallel and communicate via shared task list and mailbox.

Prerequisites: This skill assumes /dream-team:plan has already been run in this session. If the conversation has no brainstorming context (no discussed requirements, no confirmed approach, no validated task breakdown), stop and tell the user: "No brainstorming context found. Run /dream-team:plan <prompt> first to explore requirements and design."

Requires: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS enabled in settings.

Filename Format

All spec files MUST be named with a date prefix: specs/YYYY-MM-DD-<descriptive-kebab-case>.md

Use today's date. Example: specs/2026-02-07-user-auth-api.md

What To Do

1. Read the spec template at ${CLAUDE_PLUGIN_ROOT}/templates/spec-template.md.
2. Read the available agent definitions at ${CLAUDE_PLUGIN_ROOT}/agents/*.md.
3. Summarize the agreed plan from the conversation — confirm with the user before writing.
4. Write the spec, filling in all sections from the brainstorming context.
5. Set frontmatter mode: team and spec-version: 1.
6. Set frontmatter playwright: true if the brainstorming decided to use Playwright MCP, otherwise playwright: false.
7. Set frontmatter frontend-design: true if the brainstorming discussed frontend/UI work and design direction, otherwise frontend-design: false.
8. If frontend-design: true, fill in the ## Design Direction section with the aesthetic style, stack, component libraries, and design notes from the brainstorming conversation. Auto-suggest component libraries based on the chosen stack if not explicitly discussed.
9. Design for MAXIMUM INDEPENDENCE between teammates — avoid assigning same-file edits to different agents.
10. Set plan_approval: true for high-risk or architectural tasks.
11. Size tasks at 5-6 per agent role for optimal productivity.
12. Include Team Configuration and Review Policy sections.
13. Fill in the ## Cleanup section with any teardown commands needed (stop servers, remove temp files). Use "N/A" if nothing to clean up.
14. Save to specs/YYYY-MM-DD-<descriptive-kebab-case>.md using today's date.

Eliminating Ambiguity

Specs are executed by agents that have no access to the brainstorming conversation. Every detail left unspecified becomes a coin flip — different agents will make different choices. The goal is deterministic builds: two agents reading the same task description should produce near-identical output.

When writing task descriptions, prefer concrete values over descriptive language:

• CSS: Specify exact hex colors, font stacks, spacing values, border-radius. Write background: #1a1a2e not "dark background". Write font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif not "system sans-serif stack".
• Strings: Write exact user-facing text in quotes. Write "Unable to load weather data" not "an error message". Write "${score} points by ${author} | ${comments} comments" not "display the score, author, and comments".
• DOM structure: Specify element types (<div>, <p>, <span>), class names, and nesting. Write createElement("div") not "create an element".
• API details: Specify exact URLs, query parameters, response field paths, units, and data transformations (rounding, formatting). Write windspeed_10m with mph or km/h explicitly — don't leave the unit unspecified.
• Implementation patterns: When a specific approach matters for consistency, spell it out. For example, specify whether a Promise should reject-and-catch or resolve-with-fallback. Specify timeout values. Specify whether to use classList.remove() or className =.
• Quote style: If the project has a convention, state it (e.g., "use double quotes throughout JS").

If you catch yourself writing a vague adjective ("red-tinted", "subtle", "clean"), replace it with the exact value. Vague descriptions are the #1 source of build divergence.

Task Rules

• Every task must have Agent Type, Parallel, and Plan Approval. Team mode does NOT use Assigned To — the orchestrator schedules by Agent Type only.
• Set Parallel: true for tasks that can run alongside others (no shared file edits)
• Set Plan Approval: true for high-risk tasks (architectural decisions, schema changes, security-critical code)
• Set Depends On conservatively — only add real dependencies, let parallelism happen naturally
• Every builder task must include a Tests field listing the test file paths and test cases it must produce. Use "N/A" only for tasks with zero testable code (research, docs, config-only).
• Every builder task must include a **Files** field listing exactly which files it creates or modifies, prefixed with creates: or modifies:. Review, research, and validation tasks may omit this field.
• Each builder task should produce 1-3 files and ~100-300 lines of code. If a task would be larger, split it into smaller tasks with clear file boundaries.
• For parallel builder tasks (Parallel: true), verify that their **Files** fields do not overlap. If two builders would modify the same file, make one depend on the other.
• Avoid assigning same-file edits to tasks that can run in parallel
• Research and architecture tasks should complete before build tasks depend on them
• After every builder task that writes code, add a review task assigned to the reviewer agent. The review task depends on the builder task it reviews.
• Add tester tasks when appropriate — do NOT add them by default for every builder task (builders already do TDD). Add a tester task when: (a) multiple builder tasks produce components that must integrate — the tester writes integration tests after both complete; (b) the project handles user input, auth, or has security-sensitive APIs — the tester writes adversarial/boundary tests; (c) acceptance criteria span the full stack — the tester writes E2E tests after all builders finish. Tester tasks depend on the builder task(s) they test and can run in parallel with review tasks.
• The second-to-last task MUST be a final code review (reviewer) that depends on all builder tasks
• The final task should always be assigned to the validator agent, depending on the final review

Team Configuration Guidance

• Display Mode: Use split-pane if the user has tmux/iTerm2, otherwise in-process
• Coordinate Only: Set true (recommended) so the lead only coordinates and never implements directly
• Max Active Agents: Default 6. This caps concurrent agent instances. The orchestrator asks the user to confirm before starting. Can be increased for large projects with many independent workstreams.
• Rotation After: Default 3. Each agent instance handles at most this many tasks before being retired and replaced with a fresh instance. Prevents context window exhaustion.

Review Policy Defaults

Use these defaults unless the brainstorming conversation specified otherwise:

• Review After: each task
• Fix Loop Trigger: Critical and Important
• Max Retries: 3
• Skip Review For: researcher, validator

Git

After saving the spec file, commit it:

git add specs/<spec-file>.md
git commit -m "spec: <short description of what the spec covers>"

Report

After saving and committing the spec, output:

Spec written (team mode)

File: specs/YYYY-MM-DD-<name>.md
Tasks: <number of tasks>
Complexity: <simple | medium | complex>
Config: display=<mode>, delegate=<true|false>, max_agents=<N>, rotation=<N>

NOTE: Agent teams require CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in settings.

Execute with: /dream-team:build specs/YYYY-MM-DD-<name>.md