Claude Code Team Builder

Claude Code Team Builder

What This Skill Produces

For any software project, this skill generates a complete .claude/ directory:

.claude/
├── CLAUDE.md                              ← project context Claude reads every session
├── settings.json                          ← orchestration + autonomy configuration
├── agents/
│   ├── orchestrator/AGENT.md              ← mandatory: plans, assigns, validates
│   ├── problem-solver/AGENT.md            ← mandatory: self-healing, task repair
│   ├── test-engineer/AGENT.md             ← mandatory: validates every feature
│   ├── documentation-writer/AGENT.md      ← mandatory: PRDs before development
│   └── [project-specific]/AGENT.md
├── skills/
│   ├── run/SKILL.md                       ← autonomous execution loop
│   ├── status/SKILL.md                    ← project state reporting
│   ├── dashboard/SKILL.md                 ← visual progress tracker
│   ├── deploy/SKILL.md                    ← workflow skill
│   ├── test/SKILL.md                      ← workflow skill
│   ├── review/SKILL.md                    ← workflow skill
│   └── [domain skills]/SKILL.md           ← project-specific
└── workspace/                             ← result files, progress.log, orchestrator_state.json

CLAUDE.md is the most important output — project context read at every session start: tech stack, domain concepts, agent routing, project completion criteria, available commands, and conventions.

Agents use the subfolder structure (agents/[name]/AGENT.md). Each agent carries its own handoff protocol. Four agents are mandatory on every project: orchestrator, problem-solver, test-engineer, documentation-writer.

Skills are two kinds:

• Execution skills — /run, /status, /dashboard — orchestration and monitoring
• Workflow skills — /deploy, /test, /review, /migrate — developer workflows
• Domain skills — tailored to what this project does (e.g., /process-refund, /onboard-vendor)

settings.json controls orchestration behavior: autonomy mode, milestone auto-advance, retry policy, and the self-healing pipeline.

This skill does NOT create:

• PRDs, architecture documents, or specs (the documentation-writer agent does that)
• Source code or project scaffolding (the dev agents do that)
• Any artifact outside .claude/

Phase 1: Discovery

Choose a mode — ALWAYS ask the user before doing anything else:

This is mandatory. Regardless of how the user triggers the skill — whether they say "set up a new project" or "build a team for my SaaS app" or paste a full project description unprompted — always present the mode choice first. Do not skip this step. Do not infer the mode from how the user started the conversation.

"To set up your project, I can work in two ways:

• Paste mode: Share everything you know — description, tech stack, requirements, constraints — and I'll infer the rest.
• Q&A mode: I'll ask you questions one section at a time. More thorough, better output for complex projects.

Which do you prefer?"

If the user already pasted a project description in their first message, still ask — they may want Q&A mode to fill in gaps they didn't think of. If they confirm paste mode, proceed with what they already shared.

Paste mode

The user pastes a project description. Extract answers to the question bank from what they provide, then ask only for critical gaps — at most 3 follow-ups. If something is genuinely unclear, make a reasonable assumption and state it explicitly.

Q&A mode

Ask questions from the question bank (references/question-bank.md) one section at a time. Present each section as a numbered list. Don't ask a question whose answer is already obvious from prior answers.

Required to proceed (minimum viable discovery):

1. What are you building? (type + purpose)
2. What's the tech stack? (frontend, backend, database)
3. What are the highest-risk or most complex technical areas?

Everything else can be inferred with reasonable defaults.

Phase 2: Determine Agents

Always include (mandatory):

• orchestrator — plans, assigns tasks, validates results, drives the execution loop
• problem-solver — self-healing: rewrites failed tasks, splits complex tasks, fixes acceptance criteria
• test-engineer — validates every feature
• documentation-writer — PRDs before development, specs for client handoff

Add based on tech stack and complexity:

Team size: 5–6 agents for simple projects (4 mandatory + 1–2 dev), 6–8 for medium, 8–10 for complex multi-surface projects.

Critical rule on agent descriptions: The description field is what Claude uses to route tasks. It must name the specific technologies and task types. A generic description like "backend API development" is useless. A good one says:

"Next.js App Router API routes, Prisma ORM queries, and Stripe Connect webhook handling. Use for any server-side logic, database work, or payment processing on the TaskFlow project."

Every agent file must reference the project's name, stack, and domain.

Model assignment by cognitive demand: Not every agent needs the same model. Assign based on the reasoning complexity of the work:

Ask the user during discovery (question 11) for their preference. Default: sonnet for all agents. If they want cost optimization, drop validation agents to haiku. If they want maximum quality, upgrade planning agents to opus.

Phase 3: Determine Skills

Execution skills — always included:

Workflow skills — include when the condition is met:

Domain skills — derive from the project's key workflows:

Think: "What multi-step task will this developer repeat many times?"

Examples by domain:

• E-commerce: /process-refund, /add-product, /sync-inventory
• SaaS / multi-tenant: /onboard-tenant, /audit-usage, /manage-subscription
• Marketplace: /approve-vendor, /process-payout, /handle-dispute
• Streaming/media: /check-stream-health, /rotate-cdn-keys
• Data/analytics: /generate-report, /run-pipeline, /validate-schema
• Auth-heavy: /audit-permissions, /rotate-keys

Create 1–3 domain skills based on what the project actually does.

Phase 4: Generate Files

Generation rule: copy structural sections verbatim

Templates contain two kinds of content:

• Placeholders — text in [brackets] like [Project Name], [tech stack], [test framework]. Replace these with project-specific values.
• Structural sections — named blocks that define how agents and skills behave. These must be copied verbatim into the generated files. Do not paraphrase, shorten, summarize, or rewrite them in your own words.

Structural sections that must be copied verbatim from the templates:

Why this matters: These sections contain reasoning rules, not just descriptions. If the orchestrator gets a paraphrased summary instead of the full Task Sizing Rules, it can't reason about edge cases during replanning. If an agent gets a shortened Handoff Protocol, it may skip writing result files. The templates are precise because the rules need to be precise.

After replacing placeholders and copying structural sections, verify each generated file by checking that every structural section listed above is present and complete — not shortened, not reworded.

4A: Agent files (subfolder structure)

Create .claude/agents/[name]/AGENT.md for each agent. Use the templates in references/templates/agents.md. Replace all placeholders with project-specific content. Copy all structural sections verbatim per the rule above.

4B: Skill files

Create .claude/skills/[skill-name]/SKILL.md for each skill. Use the templates in references/templates/skills.md. Each skill should:

• Have a clear trigger description (the description frontmatter field)
• Walk through its workflow step by step
• Reference the project's actual commands, paths, and conventions
• Be short — workflow skills are usually 30–60 lines

4C: CLAUDE.md — the project brain

Use references/templates/claude-md.md as the structure. It must include:

1. Project summary — 2–3 sentences. What it is, who it's for, current status.
2. Tech stack — complete list
3. Key domain concepts — entities and business rules (3–8 concepts)
4. Agent routing — explicit rules with orchestrator as highest priority
5. Available skills — list of /commands with one-line descriptions
6. Project conventions — file structure, naming, what NOT to do
7. Project completion criteria — deterministic stopping point for the orchestrator
8. Task sizing — copy general rules from template verbatim, then add project-specific lines below them (per the generation rule above)
9. Current focus — placeholder the user updates as the project evolves

Keep CLAUDE.md under 130 lines. Dense but scannable.

4D: settings.json

{
  "autonomy": {
    "mode": "supervised",
    "auto_advance_milestones": true,
    "escalation_enabled": true
  },
  "retry_policy": {
    "max_retries": 4,
    "strategy": "classify-then-act",
    "simple_failure_retry": 1
  },
  "self_healing": {
    "enabled": true,
    "pipeline": ["simple-retry", "refine-instructions", "split-task", "reassign-agent", "escalate"],
    "invoke_problem_solver": "structural-failures-only"
  },
  "model_tiers": {
    "planning": "sonnet",
    "execution": "sonnet",
    "validation": "sonnet"
  }
}

The mode field accepts three values:

• "supervised" — pauses for human input at milestone boundaries and on escalation (default)
• "autonomous" — auto-advances milestones when acceptance criteria pass, only escalates on catastrophic failure
• "strict-autonomous" — escalation disabled entirely; the problem-solver handles everything

The model_tiers field controls which model each agent class uses:

• "planning" — orchestrator, problem-solver (options: "opus", "sonnet")
• "execution" — all developer agents, devops (options: "sonnet", "haiku")
• "validation" — test-engineer, code-reviewer, documentation-writer (options: "sonnet", "haiku")
• Default: "sonnet" for all tiers. For cost optimization, set validation to "haiku". For maximum quality, set planning to "opus".

4E: workspace directory and dashboard

Create .claude/workspace/ as an empty directory. Copy references/templates/dashboard.html into .claude/workspace/dashboard.html. Do NOT generate dashboard HTML from scratch — always use the fixed template.

The orchestrator will populate the workspace with:

• orchestrator_state.json — persistent state across sessions
• progress.log — task transition log
• dashboard.html — fixed template, reads tasks.json and progress.log dynamically
• [task-id].result.md — individual agent result files

Phase 5: Validate and Summarize

Before finishing, verify:

• ✅ All structural sections from templates are present and complete in generated files (see Phase 4 generation rule)
• ✅ orchestrator agent has: State Management, State Summarization, Task Sizing Rules, Execution Loop, Self-Healing Pipeline, Handoff Protocol — all verbatim
• ✅ problem-solver agent has: Self-Healing Workflow, Handoff Protocol — verbatim
• ✅ All other agents have: Handoff Protocol — verbatim
• ✅ Every agent uses subfolder structure (agents/[name]/AGENT.md)
• ✅ Every agent description references this project's actual tech stack and domain
• ✅ CLAUDE.md Task Sizing has general rules plus project-specific lines
• ✅ CLAUDE.md includes agent routing, skill list, domain concepts, completion criteria, and conventions
• ✅ settings.json includes autonomy, retry, self-healing, and model tier configuration
• ✅ dashboard.html in workspace is the fixed template copied from references/templates/dashboard.html
• ✅ Execution skills (/run, /status, /dashboard) included
• ✅ At least 2 workflow/domain skills created
• ✅ No PRDs, specs, architecture docs, or source code created
• ✅ Total files ≤ 25

Then summarize:

• What agents were created and why
• What skills were created and what they do
• What's in CLAUDE.md
• What autonomy mode is set and how to change it
• Suggested first action: run /run --plan to generate the task decomposition, review it, then /run to start execution

Reference Files

• references/question-bank.md — full discovery question bank, organized by category
• references/templates/agents.md — agent file templates for each role (including orchestrator + problem-solver)
• references/templates/skills.md — skill file templates for execution, workflow, and domain skills
• references/templates/claude-md.md — CLAUDE.md structure template
• references/templates/dashboard.html — fixed dashboard template (copy to workspace, do not regenerate)