CCteam Creator

Team Project Setup

Set up a multi-agent team for complex projects, using persistent files for planning and progress tracking.

Prerequisites

Before starting Step 1, you (team-lead) MUST read all reference files directly into your own context:

Read references/onboarding.md
Read references/templates.md
Read references/roles.md

Do NOT delegate this to a subagent (Explore, general-purpose, etc.). Subagents return summaries, losing critical detail — you need the full templates and onboarding prompts to generate files and spawn agents correctly.

Process

Step 0 Update Check (auto): Background version fetch + one-line notification if newer version exists Step 0 Detect (auto): Check if .plans/ exists → if yes, offer to resume existing project

1. Requirements Consultation — Introduce the team mechanism to the user and gather requirements
2. Confirm the Plan — Summarize requirements and let the user confirm the team configuration
3. Create planning files (including per-agent subdirectories)
4. Create the team + spawn agents
5. Confirm setup + guide user to compact context

Step 0 Update Check: Version Self-Check (Auto — Before Anything Else, ~2s)

Before any other step, perform a lightweight version check. No user consent needed, do not ask any questions.

1. Remote version: WebFetch https://raw.githubusercontent.com/jessepwj/CCteam-creator/master/.claude-plugin/plugin.json with prompt: "What is the value of the version field? Respond with just the version string."
2. Local version: Use Bash to read local plugin.json (try these paths in order, use the first that exists):

``bash cat ~/.claude/plugins/cache/ccteam/CCteam-creator/*/.claude-plugin/plugin.json 2>/dev/null || \ cat ~/.claude/plugins/cache/ccteam/CCteam-creator-cn/*/.claude-plugin/plugin.json 2>/dev/null || \ cat ~/.claude/skills/CCteam-creator/.claude-plugin/plugin.json 2>/dev/null ``

Extract the version field from the output.

1. Compare:

• remote ≤ local, OR WebFetch failed, OR local plugin.json not found → completely silent, proceed to the next step. Do NOT print "version check passed" or any confirmation noise
• remote > local → print one notification line (just one, then immediately continue, do NOT wait for user reply):

> ℹ️ A newer CCteam-creator version is available ( → ). It will auto-apply on next Claude Code startup. Continuing with in this session. For immediate effect: /plugin marketplace update ccteam → /exit → restart → re-trigger this skill.

Hard rules:

• ❌ Do NOT ask the user "continue with old version?" — no confirmation at all
• ❌ Do NOT attempt to Bash-update the plugin cache yourself — that's Claude Code's job, not the skill's
• ❌ Do NOT render the version check as a visible task in TodoWrite/TaskCreate — it should run in the background invisibly
• ❌ If the network fails, do NOT retry — just proceed
• ✅ At most one notification line, then immediately proceed to the next step

Step 0 Detect: Detect Existing Project (Auto — Before Anything Else)

Before starting setup, check if .plans/ directory exists in the current working directory.

If .plans/ exists:

1. Read the project CLAUDE.md (auto-loaded) to get the team roster and project context
2. Scan .plans/ for project directories — if multiple, list them
3. Tell the user: "I found an existing project [name] with [roster]. Resume this project or start a new one?"
4. If resume:

a. Check if .plans//team-snapshot.md exists b. If snapshot exists: Read the snapshot header metadata. Compare skill source file timestamps against snapshot generation time:

• Source files unchanged → use cached onboarding prompts from snapshot to spawn agents directly (skip reading skill reference files)
• Source files changed → inform user: "Skill files have been updated since this team was created. Use cached config for fast resume, or re-read skill files to pick up latest protocols?" Let user decide

c. If no snapshot: Fall back to reading all skill reference files (onboarding.md, roles.md) to rebuild onboarding prompts, then spawn agents d. After spawning, check TaskList / read progress files to pick up where things left off

1. If new: Proceed to Step 1 as normal

If .plans/ does not exist: Skip directly to Step 1.

Step 1: Requirements Consultation (Talk First, Then Act)

Goal of this step: Help the user fully understand how the team works, while gathering their actual requirements. Do not rush to create any files or teams.

1.1 Introduce the Team Mechanism

In a natural, conversational tone (do not copy this text verbatim — adapt to context), explain the following points:

What a team is:

• You (Claude) act as team-lead, simultaneously directing multiple AI agents working in parallel
• Team-lead is the main conversation control plane, not a spawned teammate
• Each agent has a clearly defined role (development, research, testing, review, etc.)
• Agents can communicate directly with each other (e.g., dev reaching out to reviewer directly)
• All progress is persisted via the file system, so context loss is not a concern

When it's a good fit:

• Projects with parallel multi-module development (frontend and backend progressing simultaneously)
• Tasks requiring research + development + testing across multiple phases
• Larger codebases that need code review and quality assurance

When it's not a good fit:

• Simple single-file changes or small bug fixes
• Tasks that only need a single role (a single agent is more efficient)

How it works:

• The team-lead (you) assigns tasks, coordinates progress, and makes decisions
• The team-lead also owns user alignment, phase transitions, and the team's durable operating rules
• Each agent has its own working directory (.plans//), recording tasks, findings, and progress
• Agents escalate blockers to the team-lead, who provides direction after review
• After development, devs automatically request a code review from the reviewer

1.2 Gather User Requirements

After the introduction, learn the following through conversation:

1. Working language — Observe the language the user communicates in. If they use English, the team responds in English; if Chinese, team responds in Chinese. Match the language in CLAUDE.md and onboarding prompts accordingly
2. Task type — Is this software development, research/analysis, content creation, data processing, or a mix? This determines whether standard roles apply directly or need adaptation
3. What the user wants to accomplish — Project goals, deliverables, success criteria
4. Current state — Is this a greenfield project or existing work? What tools/tech/resources are already in place?
5. User involvement — Do they want to be involved in every decision, or prefer the team to work autonomously?
6. Special requirements — Domain-specific standards, quality bars, deadlines, constraints
7. Quality priorities — What matters most for this project beyond "code works"? Examples: product depth (handles real edge cases), visual polish, performance, API design elegance, test coverage depth. These become Review Dimensions that the reviewer scores against. 3-5 dimensions, each with a weight (high/medium/low) and concrete calibration anchors (what STRONG vs WEAK looks like in this project's context)

Note: Do not fire all questions at once. Follow up naturally based on the user's answers, like a normal conversation. If the user's requirements are already clear, you may skip some questions.

1.3 Recommend a Team Configuration

Based on the user's needs, recommend an appropriate combination of roles. Explain each role's purpose and why you're recommending it.

The standard roles below are optimized for software development projects. For non-software or mixed tasks, the team framework is universal (file-based planning, task folders, phase gates, review protocols) — but the roles should be adapted to the actual work. See "Adapting for Non-Software Projects" below.

Available standard roles (software development):

| Role | Name | Reference Agent | model | Core Capability | |------|------|----------------|-------|----------------| | Backend Dev | backend-dev | tdd-guide | sonnet | Write code + TDD + large tasks split into task folders | | Frontend Dev | frontend-dev | tdd-guide | sonnet | Write code + TDD + large tasks split into task folders | | Explorer/Researcher | researcher | — | sonnet | Code search + web research + read-only (no code edits) | | E2E Tester | e2e-tester | e2e-runner | sonnet | E2E testing + browser automation + bug tracking | | Code Reviewer | reviewer | code-reviewer | sonnet | Read-only review + deep security/quality/performance checks | | Custodian | custodian | refactor-cleaner | sonnet | Constraint compliance + doc governance + pattern→automation + code cleanup |

> Model default: All roles use sonnet. Upgrade specific roles to opus only when the user requests it, cost is not a concern, or the role handles critical/complex logic (e.g., security-sensitive review, complex business logic). Ask the user during Step 1 if unsure.

See [references/roles.md](references/roles.md) for detailed role definitions and capabilities.

Recommendation principles:

• More roles is not always better — choose based on actual project needs
• Small projects may only need 1 dev + 1 researcher
• Large projects can have the full set of roles
• Multi-instance researchers: Spawn multiple researchers when the research workload is large enough to benefit from parallelism. Two main patterns:
• Volume splitting (most common): Same type of work, split by quantity. E.g., 30 source files to analyze → researcher-1 takes modules A-M, researcher-2 takes N-Z. Same responsibilities, just faster through parallel processing
• Direction splitting: Fully independent research topics. E.g., tech stack evaluation + codebase analysis + competitor research — each produces its own conclusions with no dependency on the others
• Name by number (researcher-1/researcher-2) for volume splits, by focus (researcher-api/researcher-arch) for direction splits. Each gets its own .plans/ directory. No race conditions — researchers are read-only on source code
• Anti-pattern: Do NOT split when direction B depends on A's output (e.g., "first determine auth approach, then research libraries for it") — a single researcher sequentially is faster than two in a blocking chain
• custodian is recommended for teams with 4+ agents or long-running projects. For small teams (2-3 agents), custodian overhead may not be worth it — team-lead can absorb the compliance checks directly
• Users can add custom roles (explain that custom roles require: name, responsibilities, model choice)

Adapting for Non-Software Projects:

The standard roles above are one proven configuration. For non-software or mixed tasks, design your own roles based on these principles:

1. Separate creation from review — whoever creates deliverables should not be the one reviewing them
2. Research can parallelize — independent information-gathering directions should be separate agents (see multi-instance researcher)
3. Quality gate and validation are different things — reviewing the work (is it well-made?) is not the same as validating the result (does it actually achieve the goal?). Consider whether you need both
4. The framework is universal — task folders, findings.md, progress.md, 3-Strike, phase gates, and context recovery all work regardless of what the team is doing. Only the role names and responsibilities change

1.4 What Users Can Customize

Inform the user that the following can all be adjusted as needed:

• Role composition: Choose which roles to include and which to leave out
• Custom roles: If standard roles don't cover the need, new roles can be defined
• Task phases: How many phases the project has and the goal of each phase
• Technical decisions: Tech stack, framework choices, coding standards
• Review strictness: Whether code review or security review is required

Team-lead = the main conversation (you). Do not generate a team-lead agent.

If the user is improving an existing team system rather than starting from scratch, explicitly decide whether the change belongs in:

• the current project's docs only, or
• the CCteam-creator source templates themselves

Rule of thumb:

• project-specific workflow tweaks → update project docs
• durable team protocol changes (team-lead responsibilities, role boundaries, onboarding prompts, CLAUDE.md template, task/finding/progress conventions) → update CCteam-creator first

Do not recommend immediately rebuilding an active team unless the template changes are already written back and a phase boundary has been chosen.

Step 2: Confirm the Plan

After thorough discussion, use AskUserQuestion to get final user confirmation on:

• Project name: Short, ASCII, kebab-case (e.g., chatr, data-pipeline)
• Brief description: 1-2 sentences
• Confirmed role list: Which roles are participating and what each is responsible for
• Initial phase plan: A rough breakdown of the project's key steps

Only proceed to the creation steps after the user confirms.

Step 3: Create Planning Files

See [references/templates.md](references/templates.md) for file templates.

Directory Structure

.plans//
  task_plan.md                -- Main plan (lean navigation map, not encyclopedia)
  findings.md                 -- Team-level summary
  progress.md                 -- Work log (archive old entries when bloated)
  decisions.md                -- Architecture decision log
  docs/                       -- Project knowledge base
    index.md                  -- Navigation map with sections & line ranges (custodian maintains)
    architecture.md           -- System architecture, components, data flow
    api-contracts.md          -- Frontend-backend API definitions
    invariants.md             -- Unbreakable system boundaries
  archive/                    -- Archived history (old progress, old plans)

  /               -- One directory per agent
    task_plan.md              -- Agent task list
    findings.md               -- INDEX only (keep lean, no content dumping)
    progress.md               -- Agent work log (archive old entries when bloated)
    -/          -- Task folder (one per assigned task)
      task_plan.md / findings.md / progress.md

Task Folder Pattern (All Roles)

Every role creates task folders when assigned distinct tasks. The root findings.md serves as an index — linking to each task-specific findings file instead of dumping everything into one giant document.

| Role | Folder Prefix | Example | |------|--------------|---------| | backend-dev / frontend-dev | task- | task-auth/, task-payments/ | | researcher | research- | research-tech-stack/, research-auth-options/ | | e2e-tester | test- | test-auth-flow/, test-checkout/ | | reviewer | review- | review-auth-module/, review-payments/ | | custodian | audit- | audit-phase1-compliance/, audit-doc-health/ |

Example structure with multiple roles:

.plans//
  backend-dev/
    task_plan.md              -- Agent overview
    findings.md               -- INDEX: links to each task
    progress.md
    task-auth/                -- Feature: auth module
      task_plan.md / findings.md / progress.md
    task-payments/            -- Feature: payments
      task_plan.md / findings.md / progress.md

  researcher/
    task_plan.md              -- Research agenda
    findings.md               -- INDEX: links to each research report
    progress.md
    research-tech-stack/      -- Research: tech stack evaluation
      task_plan.md / findings.md / progress.md
    research-auth-options/    -- Research: a

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jessepwj](https://github.com/jessepwj)
- **Source:** [jessepwj/CCteam-creator](https://github.com/jessepwj/CCteam-creator)
- **License:** MIT

Install and usage instructions live in the source repository linked above.