From CCteam-creator
Sets up multi-agent teams for complex projects with file-based planning, per-agent directories, and teammate spawning. Triggers on team/swarm/start-project requests.
npx claudepluginhub jessepwj/ccteam-creator --plugin CCteam-creatorThis skill uses the workspace's default tool permissions.
Set up a multi-agent team for complex projects, using persistent files for planning and progress tracking.
Creates agent-almanac team composition files defining purpose, members, coordination patterns, task decomposition, and registry integration. Use for multi-agent workflows, complex reviews, or recurring collaborations.
Guides composing agent teams for complex tasks with predefined roles: Orchestrator, Explorer, Frontend (React), Backend (Rails), iOS/Swift, Android/Kotlin, Database.
Guides coordination of parallel agent teams (Implementer, Reviewer, Architect) for complex plans, cross-cutting concerns, and communicating work streams.
Share bugs, ideas, or general feedback.
Set up a multi-agent team for complex projects, using persistent files for planning and progress tracking.
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.
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
Before any other step, perform a lightweight version check. No user consent needed, do not ask any questions.
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."
Local version: Use Bash to read local plugin.json (try these paths in order, use the first that exists):
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.
Compare:
ℹ️ 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:
Before starting setup, check if .plans/ directory exists in the current working directory.
If .plans/ exists:
.plans/ for project directories — if multiple, list them.plans/<project>/team-snapshot.md exists
b. If snapshot exists: Read the snapshot header metadata. Compare skill source file timestamps against snapshot generation time:
If .plans/ does not exist: Skip directly to Step 1.
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.
In a natural, conversational tone (do not copy this text verbatim — adapt to context), explain the following points:
What a team is:
When it's a good fit:
When it's not a good fit:
How it works:
.plans/<project>/), recording tasks, findings, and progressAfter the introduction, learn the following through conversation:
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.
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 toopusonly 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 for detailed role definitions and capabilities.
Recommendation principles:
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 codeAdapting 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:
Inform the user that the following can all be adjusted as needed:
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:
CCteam-creator source templates themselvesRule of thumb:
CCteam-creator firstDo not recommend immediately rebuilding an active team unless the template changes are already written back and a phase boundary has been chosen.
After thorough discussion, use AskUserQuestion to get final user confirmation on:
chatr, data-pipeline)Only proceed to the creation steps after the user confirms.
See references/templates.md for file templates.
.plans/<project>/
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)
<agent-name>/ -- 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)
<prefix>-<task>/ -- Task folder (one per assigned task)
task_plan.md / findings.md / progress.md
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/<project>/
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: auth approaches
task_plan.md / findings.md / progress.md
e2e-tester/
task_plan.md -- Test plan overview
findings.md -- INDEX: links to each test round
progress.md
test-auth-flow/ -- Test scope: auth flow
task_plan.md / findings.md / progress.md
reviewer/
task_plan.md -- Review queue
findings.md -- INDEX: links to each review
progress.md
review-auth-module/ -- Review: auth module
findings.md / progress.md
Quick one-off notes (bug fixes, config changes) can go directly in root files without a task folder.
CLAUDE.md in the project working directory is always loaded into the main session's context by Claude Code. This is the mechanism that keeps team-lead operational knowledge persistent across context compressions.
Create (or append to) a CLAUDE.md file in the project working directory (not inside .plans/).
See references/templates.md for the CLAUDE.md template. The template must be dynamically filled based on the actual roles chosen in Step 2:
If the project directory already has a CLAUDE.md, append the team operations section at the end (with a clear separator), do not overwrite the existing content.
Without this file, after context compression the team-lead loses all knowledge of:
The CLAUDE.md solves this by keeping a concise operations guide permanently in context.
In Step 3, also create docs/index.md — a detailed navigation map showing each doc's sections and line ranges. This file is maintained by custodian and actively Read by agents when they need to find specific information. CLAUDE.md points to it but does NOT duplicate it (CLAUDE.md is only loaded at session start / after compact, so dynamic nav info belongs in docs/index.md).
See references/templates.md for the docs/index.md template.
CLAUDE.md is a living document, not a one-time generation. Update it when:
## Known Pitfalls)Do NOT put task-level details here — only durable operational knowledge that survives context compression.
If the project has testable code (backend, frontend, or both), set up the enforcement infrastructure:
Copy the bundled golden_rules.py from this skill into the project:
cp <skill-path>/scripts/golden_rules.py <project>/scripts/golden_rules.py
Then configure SRC_DIRS at the bottom of the copied file to match the project's source directories (e.g., ["src"], ["backend", "frontend"]).
golden_rules.py provides 5 universal checks out of the box:
custodian can add project-specific checks to golden_rules.py over time (see roles.md § Golden Rules Maintenance).
Create a CI script skeleton (scripts/run_ci.py):
golden_rules.check_all() as the first stepdocs/api-contracts.md exists)All check scripts (CI, contract validation, architecture linters) MUST produce agent-readable error messages with fix instructions:
# BAD: agent cannot act on this
ERROR: api-contracts.md out of sync
# GOOD: agent can directly fix this
[CONTRACT-SYNC] POST /api/auth/refresh — exists in code but not in docs
File: src/auth/controller.py:142
FIX: Add to docs/api-contracts.md under "Auth API" section.
Format: | POST | /api/auth/refresh | Refresh JWT token | { token: string } |
The skeleton does not need to be complete at project start — it grows as the project grows. But the file must exist from day one, otherwise no one will create it later.
Add the CI command to the project CLAUDE.md Key Protocols table so it survives context compression.
TeamCreate(team_name: "<project>").plans/ path in the description. Set dependencies (addBlockedBy) and owners (owner) via TaskUpdate. Specify input/output to minimize inter-agent information lossrun_in_background: trueSee references/onboarding.md for the onboarding prompt for each role.
.plans/<project>/team-snapshot.md containing the rendered onboarding prompts and skill file timestamps. See references/templates.md for the template. This enables fast resume without re-reading all skill files.Show the user a table of team members and the file locations.
Then guide the user to run /compact to free up context. Explain why:
.plans/ filesTell the user the following — verbatim or paraphrased:
After compaction, team-lead may "lose memory" — forgetting teammate names, operational protocols, and the current project context. This is normal behavior of Claude Code's compaction: CLAUDE.md is only injected at session start, and the compactor rewrites history (including the team roster and protocols) into a summary, so details can be lost.
If I (team-lead) seem confused after compaction, just tell me one sentence:
"Read
.plans/<project>/team-snapshot.mdto restore team state"This makes me reload the full team roster and all onboarding prompts, returning to a working state immediately. All progress is in
.plans/files — nothing is lost.
This warning must be delivered before guiding /compact — otherwise the user will hit an amnesiac lead and not know the rescue command.
~/.claude/tasks/, not in project). TaskCreate description = one-line summary + .plans/ path. When resuming a project in a new session, reconstruct tasks from each agent's findings.md indexteam_name) to permanently join the teamdocs/api-contracts.md and docs/architecture.md when code changes — undocumented APIs do not exist for other agentsdocs/invariants.md, then converted to automated tests. Reviewer is the second line of defense; automated tests are the first[AUTOMATE] on a recurring pattern, team-lead routes it to custodian, who builds a check script with agent-readable error messages and adds it to CI. Goal: convert manual checks into automated enforcement so reviewer can focus on deeper judgment callsdocs/, not hereCCteam-creator source files before recommending a rebuildStatus: complete in the root findings.md index. Do not rename, move, or prefix folders with _archive_. The index is the navigation layer; folder location must remain stable so cross-references don't break.plans/<project>/session-<N>-<topic>-plan.md (goal / solution / params / task split / dispatch order / rollback) BEFORE any SendMessage. Dispatch messages reference plan sections only — no re-explaining context inline, no dispatch-while-thinkingThe core idea behind planning-with-files is: file system = disk, context = memory, important things must be written to disk.
In a team project, this principle operates at three levels:
| Level | Owner | File Location | Focus |
|---|---|---|---|
| Project Global | team-lead | .plans/<project>/task_plan.md | Phase progress, architecture decisions, task assignments |
| Agent Level | Each agent individually | .plans/<project>/<agent>/ | Task index, general notes, work log |
| Task Level | Each agent | .plans/<project>/<agent>/<prefix>-<name>/ | Detailed steps, findings, and progress for a specific task |
Each agent's onboarding prompt already includes an equivalent self-check protocol (periodic 5-question check, 2-Action Rule, 3-Strike). The team-lead does not need to manually trigger these mechanisms — agents execute them autonomously.
Regarding
/planning-with-files:status: This command reads the single task_plan.md at the project root directory and is not aware of the team's multi-layered file structure. To check the main plan, directly Read.plans/<project>/task_plan.md.
The team-lead should also follow a periodic self-check principle. It is recommended to proactively check at these moments:
Quick scan (read each agent's progress.md in parallel):
Read .plans/<project>/backend-dev/progress.md
Read .plans/<project>/frontend-dev/progress.md
Read .plans/<project>/researcher/progress.md
...(adjust for actual roles)
Deep dive (read findings.md when something seems off):
Read .plans/<project>/<agent-name>/findings.md
Decision alignment (read the main plan when direction needs adjustment):
Read .plans/<project>/task_plan.md
Reading order: progress (where are we) → findings (what was encountered) → task_plan (what is the goal)
Mechanism (empirically verified): SendMessage to a spawned teammate is delivered only when the recipient is idle (between turns). You cannot interrupt a running agent — messages queue until its current turn ends. This is a hard system constraint, not a discipline rule.
Consequences for dispatch:
to: "*" still only lands per-recipient at each next idle. No preemptionprogress.md / findings.md / task folder directly. Files are live, messages are notCorollary: Files convey continuous state; messages convey intent at turn boundaries. When you need current ground truth, read the files — not messages.
The team-lead is responsible for more than dispatch:
.plans/<project>/task_plan.md, decisions.md, and project CLAUDE.mdCCteam-creatorIf these responsibilities are not kept in the main conversation, the team may continue operating, but it will drift.
When a team-level improvement is discovered, team-lead should classify it:
CCteam-creator source files firstExamples of template-level changes:
Recommended order:
CCteam-creatorDo not default to "edit template then rebuild immediately".
Prefer rebuilding:
When an agent reports "3 failures, escalating to team-lead":
## Known Pitfalls (symptom, root cause, fix, prevention)[TEAM-PROTOCOL] and consider template updatePhase boundary health check (quick, do alongside phase advancement):
in_progress tasks in TaskList that should be completed or reassigned?## Known Pitfalls. Run them BEFORE dispatching agents that depend on live state (typically e2e-tester and integration-focused devs) — do not rely on the previous phase's dev to remember. Environmental side effects should also appear in each dev's completion report as a standard field