dream-team: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

Dream Team is a Claude Code marketplace plugin that provides structured planning and execution for development projects. It follows the brainstorm → spec → build workflow across three execution tiers: sequential, delegated (sub-agents), and team (parallel Claude instances).

Installed as: dream-team@dream-team-marketplace (local marketplace via .claude-plugin/marketplace.json).

Commands

# Run all tests
make test

# Run a single test
node tests/test_session_start.js

# Install as plugin (local marketplace)
claude plugin marketplace add Ratler/dream-team-marketplace
claude plugin install dream-team@dream-team-marketplace

Tests are plain Node.js scripts (no test framework) that use execSync to invoke hooks and assert on JSON output. Hook tests that expect exit(1) need try/catch with err.stdout parsing.

Architecture

This is a Claude Code plugin, not a Node.js application. There is no package.json or build step. All files live at repo root (required by marketplace layout).

Plugin Structure

• commands/*.md — Only progress.md (runs bin/progress.js, no matching skill). Do NOT add commands/<name>.md wrappers for skills: plugin skills are invoked directly as /dream-team:<name>, so a same-named command registers the name twice, and a wrapper that has the model Read the SKILL.md bypasses the skill's frontmatter (Stop hooks never fire).
• skills/*/SKILL.md — Actual skill logic. YAML frontmatter defines name, description, argument hints, and Stop hooks. Skills that require arguments (plan, build, debug) start with a "no arguments → print usage and stop" check. The allowed-tools frontmatter field controls tool access (disallowed-tools is not a valid field). The build skill is split for token efficiency: SKILL.md holds shared sections (git workflow, build state, resume, report) and per-mode strategies live in skills/build/modes/{sequential,delegated,team}.md — only the file matching the spec's mode is loaded.
• agents/MANIFEST.md — Compact dispatch table (model, isolation, writes, reuse, capability per agent). Orchestrators and spec writers read this instead of the full agent definitions — agent .md files are loaded automatically as system prompts at spawn time and must never be bulk-read into an orchestrator session. Single source of truth for model assignments.
• agents/*.md — Agent definitions with model, color, and behavioral instructions. Model assignments are listed in agents/MANIFEST.md — when changing an agent's model: frontmatter, update the manifest in the same change. Builder and debugger agents use isolation: "worktree" for git worktree isolation in delegated mode and implicit-team team mode. Builder, reviewer, architect, and docs agents use memory: project for persistent cross-session knowledge. Read-only agents (researcher, architect, reviewer, security-reviewer, validator, scout) use disallowedTools: Write, Edit, NotebookEdit to enforce read-only access. Write agents (builder, debugger, tester, docs) commit their own changes as the last step of their Completion Protocol. All agents include [agent-type: X] in their report format and write reports to the task description via TaskUpdate(description: ...) — or return the report as their final message when the Task* tools are unavailable. The reviewer agent runs a structural-quality pass (simplification, ~1k-line file-size threshold, spaghetti prevention, boundary leaks, and architect-design compliance) alongside its correctness, spec-compliance, and test review — acting as the post-build enforcement backstop for the architect's design. Structural regressions and unjustified design drift are Important (blocking); pure missed simplifications are Minor (mentioned, non-blocking).
• hooks/*.js — JavaScript hooks (Node.js, no external deps). hooks.json registers SessionStart, PreToolUse, TaskCompleted, and PostCompact hooks. Stop hooks are declared in skill frontmatter under the hooks: key.
• lib/build-state.js — State persistence library. Functions for creating, reading, and updating per-task state files in specs/.build-state/<spec-name>/. Used by hooks and the progress dashboard.
• bin/task-state.js — Task tracking CLI for Claude Code builds without TaskCreate/TaskUpdate/TaskList/TaskGet (start, complete, commit, next). The build skill detects the Task* tools at start (TASK_TRACKING = native | state-files); in state-files mode the build-state files are the task list and complete does what the TaskCompleted hook does (shared code in lib/task-completion.js).
• bin/progress.js — CLI progress dashboard. Run node bin/progress.js <spec-path> from any terminal to see build progress without needing a Claude session.
• templates/spec-template.md — Shared spec template with conditional sections per execution mode and YAML frontmatter.
• specs/ — Generated spec files (date-prefixed: YYYY-MM-DD-<name>.md). Build state is persisted under specs/.build-state/<spec-name>/ with one JSON file per task plus _meta.json for build metadata.
• .claude-plugin/plugin.json — Plugin manifest. Omit empty string fields (e.g., homepage: "" fails URL validation).
• .claude-plugin/marketplace.json — Local marketplace definition.