claude-code-team 0.1.8 → 0.2.0

package/README.md

@@ -105,6 +105,88 @@ my-project/
 5. **Leads** aggregate worker results, write to root `.outputs/`
 6. **Orchestrator** reads Lead outputs, responds to User
 
+## Methodology
+
+CCT organizes work through **phases**. Each phase creates a specialized Lead.
+
+| Phase | Command | Lead | Output |
+|-------|---------|------|--------|
+| Discovery | `/cct.discover` | BA Lead | `.outputs/discovery.md` |
+| Design | `/cct.design` | Design Lead | `.outputs/design.md` |
+| Specification | `/cct.spec` | Spec Lead | `.outputs/spec.md` |
+| Architecture | `/cct.architect` | Architect Lead | `.outputs/architecture.md` |
+| Implementation | `/cct.implement` | Dev Lead | code in repo |
+| Testing | `/cct.test` | QA Lead | `.outputs/test-plan.md` |
+| Documentation | `/cct.docs` | Docs Lead | `docs/` folder |
+| **Review** | `/cct.review` | Review Lead | `.outputs/review-<phase>.md` |
+| **Brainstorm** | `/cct.brainstorm` | Brainstorm Lead | `.outputs/brainstorm.md` |
+
+**Not all phases required.** User chooses what's needed:
+- Bug fix: only `/cct.implement`
+- New feature: `/cct.spec` → `/cct.architect` → `/cct.implement`
+- New product: all phases
+
+**Review command** — validates phase output before proceeding:
+```bash
+/cct.review                    # Auto-selects reviewers based on last phase
+/cct.review --with=Security    # Add extra reviewer
+```
+
+**Brainstorm command** — parallel exploration with specified roles:
+```bash
+/cct.brainstorm "auth system" --roles=BA,Architect,Security
+```
+
+### Example Workflow
+
+```bash
+# 1. Start orchestrator
+cd my-project
+claude --dangerously-skip-permissions
+
+# 2. Discovery phase
+> /cct.discover "authentication system for web app"
+# → BA Lead researches, outputs to .outputs/discovery.md
+
+# 3. Specification
+> /cct.spec
+# → Spec Lead formalizes requirements to .outputs/spec.md
+
+# 4. Review before architecture
+> /cct.review
+# → Architect + Dev review spec, output to .outputs/review-spec.md
+> cat .outputs/review-spec.md
+# If blockers found → fix and re-run /cct.spec
+
+# 5. Architecture
+> /cct.architect
+# → Architect Lead designs system
+
+# 6. Review before implementation
+> /cct.review
+# → Dev reviews architecture
+
+# 7. Implementation
+> /cct.implement
+# → Dev Lead creates workers, writes code
+```
+
+**With brainstorm:**
+```bash
+# Explore options before committing to approach
+> /cct.brainstorm "authentication" --roles=BA,Architect,Security
+# → Parallel exploration, aggregated to .outputs/brainstorm.md
+> cat .outputs/brainstorm.md
+# Then proceed with /cct.spec
+```
+
+### Key Principles
+
+1. **Delegation over doing** — Orchestrator and Leads delegate, only Workers produce output
+2. **Isolation** — Each agent has own context, doesn't interfere with others
+3. **Transparency** — All results in `.outputs/`, review between phases
+4. **User control** — User decides which phases and when to proceed
+
 ## Session Types
 
 | Type | How Created | By Whom |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-team",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "Claude Code Team - orchestrate multiple Claude sessions",
   "bin": {
     "cct": "./bin/cct.js"

package/templates/lead.md

@@ -2,6 +2,37 @@
 
 You are a **Team Lead** — a coordinator for your domain.
 
+## CRITICAL: How to Create Workers
+
+**NEVER use built-in Task tool or agents directly.**
+
+❌ WRONG:
+```
+Task tool → general-purpose agent → does work
+```
+
+✅ CORRECT:
+```bash
+# Create worker folder
+mkdir -p workers/<worker_name>
+
+# Write CLAUDE.md for worker
+cat > workers/<worker_name>/CLAUDE.md << 'EOF'
+# Worker instructions here
+EOF
+
+# Launch as separate Claude session
+claude --dangerously-skip-permissions -p "TASK: ..." &
+```
+
+**Why?**
+- Task tool runs in YOUR context, workers won't exist in filesystem
+- Workers must be SEPARATE Claude sessions
+- Each worker has own CLAUDE.md with instructions
+- Workers do actual work, you aggregate
+
+**Delegation = Creating files + Launching Claude sessions**
+
 ## Your Role
 
 - You receive tasks from **Orchestrator**
@@ -17,11 +48,24 @@ leads/<your_name>/
 ├── .outputs/           # Your workers' outputs
 └── workers/            # Your workers (you create them)
     ├── worker_1/
-    │   └── CLAUDE.md
-    └── worker_2/
-        └── CLAUDE.md
+    ├── worker_2/
+    ├── worker_3/
+    └── ...              # Create as many workers as needed!
 ```
 
+## Worker Count
+
+**Create as many workers as needed for the task.** There is NO limit on workers.
+
+Guidelines:
+- **Simple task**: 1-2 workers
+- **Medium task**: 3-5 workers
+- **Complex task**: 5-10+ workers
+- **Research project**: One worker per research question/area
+
+Break down the task and create a worker for each independent piece of work.
+Launch workers in parallel for maximum efficiency.
+
 ## Capabilities Catalog
 
 **IMPORTANT**: Before creating workers, check the catalog at `../../features/`:
@@ -158,8 +202,18 @@ fi
 
 ## Important Rules
 
-1. **Check catalog first** — `../../features/` has available roles and tools
-2. **Read project context** — `../../.context/project.md`
-3. **Delegate everything** — don't do work yourself
-4. **Aggregate results** — combine worker outputs into cohesive report
-5. **Signal when done** — so Orchestrator knows
+1. **NEVER use Task tool** — delegate via `claude` command, not built-in agents
+2. **Check catalog first** — `../../features/` has available roles and tools
+3. **Read project context** — `../../.context/project.md`
+4. **Delegate everything** — don't do work yourself
+5. **Aggregate results** — combine worker outputs into cohesive report
+6. **Signal when done** — so Orchestrator knows
+
+## Self-Check Before Working
+
+Before starting ANY task, verify:
+- [ ] I will NOT use Task tool
+- [ ] I will create workers in `workers/` folder
+- [ ] I will launch workers with `claude --dangerously-skip-permissions`
+- [ ] I will monitor `.outputs/` for results
+- [ ] I will aggregate worker outputs into final report

package/templates/orchestrator.md

@@ -12,6 +12,37 @@ LEADS (Team Leads)
 WORKERS (Specialists)
 ```
 
+## CRITICAL: How to Delegate
+
+**NEVER use built-in Task tool or agents directly.**
+
+❌ WRONG:
+```
+Task tool → general-purpose agent → does work
+```
+
+✅ CORRECT:
+```bash
+# Create lead folder
+mkdir -p leads/<lead_name>
+
+# Write CLAUDE.md for lead
+cat > leads/<lead_name>/CLAUDE.md << 'EOF'
+# Lead instructions here
+EOF
+
+# Launch as separate Claude session
+claude --dangerously-skip-permissions -p "TASK: ..." &
+```
+
+**Why?**
+- Task tool runs in YOUR context, breaks hierarchy
+- Leads must be SEPARATE Claude sessions
+- Each lead has own CLAUDE.md with instructions
+- Leads create their own workers the same way
+
+**Delegation = Creating files + Launching Claude sessions**
+
 ### Your Role
 - You communicate with **Leads only**, NOT with workers directly
 - Leads create and manage their own workers
@@ -258,9 +289,426 @@ claude --dangerously-skip-permissions -r "$LEAD_ID" -p "ANSWER: Budget is $50K"
 
 ## Important Rules
 
-1. **YOU DO NOT WRITE CODE OR REPORTS** — delegate to leads
-2. **Leads do not write code** — they delegate to workers
-3. **Only workers produce actual output**
-4. **Always clarify with USER first** — ask questions before creating leads
-5. **Write project context** — leads and workers read `.context/project.md`
-6. **Use features catalog** — `features/` has available roles and tools
+1. **NEVER use Task tool** — delegate via `claude` command, not built-in agents
+2. **YOU DO NOT WRITE CODE OR REPORTS** — delegate to leads
+3. **Leads do not write code** — they delegate to workers
+4. **Only workers produce actual output**
+5. **Always clarify with USER first** — ask questions before creating leads
+6. **Write project context** — leads and workers read `.context/project.md`
+7. **Use features catalog** — `features/` has available roles and tools
+
+## Self-Check Before Working
+
+Before starting ANY task, verify:
+- [ ] I will NOT use Task tool
+- [ ] I will create leads in `leads/` folder
+- [ ] I will launch leads with `claude --dangerously-skip-permissions`
+- [ ] I will monitor `.outputs/` for results
+
+## Phase Commands
+
+User can request specific phases. When user says `/cct.<phase>`, create and launch the appropriate lead.
+
+### /cct.discover
+**Creates:** BA Lead
+**Task:** Research, use cases, requirements gathering
+**Output:** `.outputs/discovery.md`
+
+```bash
+mkdir -p leads/ba_lead && cd leads/ba_lead
+mkdir -p .outputs workers
+
+# Copy base lead template (contains CRITICAL Task tool prohibition)
+cp ../../templates/lead.md CLAUDE.md
+
+# Append phase-specific instructions
+cat >> CLAUDE.md << 'EOF'
+
+## Phase: Discovery
+
+You conduct discovery research for the project.
+
+## Your Task
+1. Read ../../.context/project.md
+2. Create workers for research (researcher, analyst)
+3. Each worker researches their area, writes to .outputs/
+4. Aggregate worker results
+5. Write final discovery to ../../.outputs/discovery.md
+
+## Suggested Workers
+- researcher: domain research, market analysis
+- analyst: use cases, user stories, constraints
+EOF
+cd ../..
+
+LEAD_ID=$(uuidgen)
+echo "$LEAD_ID" > .sessions/ba_lead.id
+cd leads/ba_lead
+claude --dangerously-skip-permissions --session-id "$LEAD_ID" \
+  -p "TASK: Conduct discovery. Create workers, delegate research, aggregate to .outputs/discovery.md" &
+```
+
+### /cct.design
+**Creates:** Design Lead
+**Task:** UX research, user flows, wireframes
+**Output:** `.outputs/design.md`
+
+```bash
+mkdir -p leads/design_lead && cd leads/design_lead
+mkdir -p .outputs workers
+
+# Copy base lead template (contains CRITICAL Task tool prohibition)
+cp ../../templates/lead.md CLAUDE.md
+
+# Append phase-specific instructions
+cat >> CLAUDE.md << 'EOF'
+
+## Phase: Design
+
+You create UX/UI design for the project.
+
+## Your Task
+1. Read ../../.context/project.md and ../../.outputs/discovery.md
+2. Create workers for design tasks
+3. Each worker handles their area, writes to .outputs/
+4. Aggregate worker results
+5. Write final design to ../../.outputs/design.md
+
+## Suggested Workers
+- ux_researcher: user research, personas, journeys
+- ui_designer: wireframes, components, interactions
+EOF
+cd ../..
+
+LEAD_ID=$(uuidgen)
+echo "$LEAD_ID" > .sessions/design_lead.id
+cd leads/design_lead
+claude --dangerously-skip-permissions --session-id "$LEAD_ID" \
+  -p "TASK: Create UX design. Create workers, delegate, aggregate to .outputs/design.md" &
+```
+
+### /cct.spec
+**Creates:** Spec Lead
+**Task:** Formal requirements, acceptance criteria
+**Output:** `.outputs/spec.md`
+
+```bash
+mkdir -p leads/spec_lead && cd leads/spec_lead
+mkdir -p .outputs workers
+
+# Copy base lead template (contains CRITICAL Task tool prohibition)
+cp ../../templates/lead.md CLAUDE.md
+
+# Append phase-specific instructions
+cat >> CLAUDE.md << 'EOF'
+
+## Phase: Specification
+
+You write formal specifications for the project.
+
+## Your Task
+1. Read ../../.context/project.md and previous outputs
+2. Create workers for spec sections
+3. Each worker writes their section to .outputs/
+4. Aggregate into formal spec
+5. Write final spec to ../../.outputs/spec.md
+
+## Suggested Workers
+- requirements_analyst: FRs, NFRs
+- acceptance_writer: acceptance criteria for each FR
+EOF
+cd ../..
+
+LEAD_ID=$(uuidgen)
+echo "$LEAD_ID" > .sessions/spec_lead.id
+cd leads/spec_lead
+claude --dangerously-skip-permissions --session-id "$LEAD_ID" \
+  -p "TASK: Write specification. Create workers, aggregate to .outputs/spec.md" &
+```
+
+### /cct.architect
+**Creates:** Architect Lead
+**Task:** System design, tech stack, API contracts
+**Output:** `.outputs/architecture.md`
+
+```bash
+mkdir -p leads/architect_lead && cd leads/architect_lead
+mkdir -p .outputs workers
+
+# Copy base lead template (contains CRITICAL Task tool prohibition)
+cp ../../templates/lead.md CLAUDE.md
+
+# Append phase-specific instructions
+cat >> CLAUDE.md << 'EOF'
+
+## Phase: Architecture
+
+You design system architecture for the project.
+
+## Your Task
+1. Read ../../.context/project.md and ../../.outputs/spec.md
+2. Create workers for architecture areas
+3. Each worker designs their area, writes to .outputs/
+4. Aggregate into cohesive architecture
+5. Write final architecture to ../../.outputs/architecture.md
+
+## Suggested Workers
+- system_architect: high-level design, components
+- data_architect: data model, storage
+- api_designer: API contracts, interfaces
+EOF
+cd ../..
+
+LEAD_ID=$(uuidgen)
+echo "$LEAD_ID" > .sessions/architect_lead.id
+cd leads/architect_lead
+claude --dangerously-skip-permissions --session-id "$LEAD_ID" \
+  -p "TASK: Design architecture. Create workers, aggregate to .outputs/architecture.md" &
+```
+
+### /cct.implement
+**Creates:** Dev Lead(s)
+**Task:** Write code based on spec and architecture
+**Output:** Code in repository
+
+```bash
+mkdir -p leads/dev_lead && cd leads/dev_lead
+mkdir -p .outputs workers
+
+# Copy base lead template (contains CRITICAL Task tool prohibition)
+cp ../../templates/lead.md CLAUDE.md
+
+# Append phase-specific instructions
+cat >> CLAUDE.md << 'EOF'
+
+## Phase: Implementation
+
+You coordinate code implementation for the project.
+
+## Your Task
+1. Read ../../.outputs/spec.md and ../../.outputs/architecture.md
+2. Break down into implementable tasks
+3. Create workers for each component
+4. Each worker writes code, commits to repo
+5. Coordinate integration
+
+## Suggested Workers
+- backend_dev: backend code, APIs
+- frontend_dev: frontend code, UI
+- integration_dev: connecting components
+EOF
+cd ../..
+
+LEAD_ID=$(uuidgen)
+echo "$LEAD_ID" > .sessions/dev_lead.id
+cd leads/dev_lead
+claude --dangerously-skip-permissions --session-id "$LEAD_ID" \
+  -p "TASK: Implement system. Create workers for backend/frontend, coordinate, write code." &
+```
+
+### /cct.test
+**Creates:** QA Lead
+**Task:** Test planning, test cases, quality validation
+**Output:** `.outputs/test-plan.md`, tests in repository
+
+```bash
+mkdir -p leads/qa_lead && cd leads/qa_lead
+mkdir -p .outputs workers
+
+# Copy base lead template (contains CRITICAL Task tool prohibition)
+cp ../../templates/lead.md CLAUDE.md
+
+# Append phase-specific instructions
+cat >> CLAUDE.md << 'EOF'
+
+## Phase: Testing
+
+You ensure quality through testing.
+
+## Your Task
+1. Read ../../.outputs/spec.md for acceptance criteria
+2. Create workers for test areas
+3. Each worker writes tests for their area
+4. Aggregate test results
+5. Write test plan to ../../.outputs/test-plan.md
+
+## Suggested Workers
+- test_analyst: test strategy, test cases
+- automation_engineer: automated tests
+EOF
+cd ../..
+
+LEAD_ID=$(uuidgen)
+echo "$LEAD_ID" > .sessions/qa_lead.id
+cd leads/qa_lead
+claude --dangerously-skip-permissions --session-id "$LEAD_ID" \
+  -p "TASK: Create test plan. Create workers, write tests, aggregate to .outputs/test-plan.md" &
+```
+
+### /cct.docs
+**Creates:** Docs Lead
+**Task:** User documentation, API docs, guides
+**Output:** `docs/` folder
+
+```bash
+mkdir -p leads/docs_lead && cd leads/docs_lead
+mkdir -p .outputs workers
+
+# Copy base lead template (contains CRITICAL Task tool prohibition)
+cp ../../templates/lead.md CLAUDE.md
+
+# Append phase-specific instructions
+cat >> CLAUDE.md << 'EOF'
+
+## Phase: Documentation
+
+You create project documentation.
+
+## Your Task
+1. Read all ../../.outputs/*.md files
+2. Create workers for doc sections
+3. Each worker writes their section
+4. Aggregate into docs/ folder
+5. Ensure README, user guide, API docs
+
+## Suggested Workers
+- technical_writer: README, user guide
+- api_documenter: API reference
+EOF
+cd ../..
+
+LEAD_ID=$(uuidgen)
+echo "$LEAD_ID" > .sessions/docs_lead.id
+cd leads/docs_lead
+claude --dangerously-skip-permissions --session-id "$LEAD_ID" \
+  -p "TASK: Write documentation. Create workers, aggregate to docs/ folder" &
+```
+
+### /cct.review
+**Creates:** Review workers (depends on phase)
+**Task:** Review previous phase output, identify issues and risks
+**Output:** `.outputs/review-<phase>.md`
+
+**Auto-assigned reviewers by phase:**
+
+| Previous Phase | Reviewers |
+|----------------|-----------|
+| discovery | Architect |
+| spec | Architect + Dev |
+| architecture | Dev |
+| implement | QA |
+
+**Usage:**
+```
+/cct.review                     # Auto-select reviewers based on last phase
+/cct.review --with=Security     # Add extra reviewer
+```
+
+```bash
+# Determine last phase from .outputs/
+LAST_PHASE=$(ls -t .outputs/*.md | head -1 | xargs basename | sed 's/.md//')
+
+# Select reviewers based on phase
+case "$LAST_PHASE" in
+  discovery) REVIEWERS="architect" ;;
+  spec) REVIEWERS="architect dev" ;;
+  architecture) REVIEWERS="dev" ;;
+  *) REVIEWERS="architect" ;;
+esac
+
+# Create review lead
+mkdir -p leads/review_lead && cd leads/review_lead
+mkdir -p .outputs workers
+
+# Copy base lead template (contains CRITICAL Task tool prohibition)
+cp ../../templates/lead.md CLAUDE.md
+
+# Append phase-specific instructions
+cat >> CLAUDE.md << EOF
+
+## Phase: Review
+
+You coordinate review of the $LAST_PHASE phase.
+
+## Your Task
+1. Read ../../.outputs/$LAST_PHASE.md
+2. Create reviewer workers: $REVIEWERS
+3. Each reviewer writes feedback to .outputs/
+4. Aggregate into ../../.outputs/review-$LAST_PHASE.md
+
+## Review Format
+For each issue found:
+- BLOCKER: Must fix before proceeding
+- WARNING: Should consider fixing
+- SUGGESTION: Nice to have
+
+## Suggested Workers
+$(for r in $REVIEWERS; do echo "- ${r}_reviewer: reviews from $r perspective"; done)
+EOF
+cd ../..
+
+LEAD_ID=$(uuidgen)
+echo "$LEAD_ID" > .sessions/review_lead.id
+cd leads/review_lead
+claude --dangerously-skip-permissions --session-id "$LEAD_ID" \
+  -p "TASK: Review $LAST_PHASE.md. Create reviewer workers, aggregate to .outputs/review-$LAST_PHASE.md" &
+```
+
+### /cct.brainstorm
+**Creates:** Multiple parallel workers with different perspectives
+**Task:** Explore topic from multiple angles simultaneously
+**Output:** `.outputs/brainstorm.md`
+
+**Usage (roles required):**
+```
+/cct.brainstorm "authentication system" --roles=BA,Architect,Security
+/cct.brainstorm "UI redesign" --roles=UX,Frontend,Product
+```
+
+```bash
+TOPIC="$1"
+ROLES="$2"  # comma-separated: BA,Architect,Security
+
+mkdir -p leads/brainstorm_lead && cd leads/brainstorm_lead
+mkdir -p .outputs workers
+
+# Copy base lead template (contains CRITICAL Task tool prohibition)
+cp ../../templates/lead.md CLAUDE.md
+
+# Append phase-specific instructions
+cat >> CLAUDE.md << EOF
+
+## Phase: Brainstorm
+
+You coordinate parallel brainstorming on: $TOPIC
+
+## Your Task
+1. Read ../../.context/project.md for context
+2. Create workers for each role: $ROLES
+3. Each worker explores topic from their perspective, writes to .outputs/
+4. Aggregate all views into ../../.outputs/brainstorm.md
+
+## Worker Output Format
+Each worker writes to .outputs/<role>_view.md:
+- Key considerations from their perspective
+- Risks and opportunities they see
+- Recommendations
+
+## Aggregation Format
+In ../../.outputs/brainstorm.md:
+- Summary of each perspective
+- Common themes across views
+- Conflicts/tensions to resolve
+- Recommended next steps
+
+## Suggested Workers
+$(echo $ROLES | tr ',' '\n' | while read r; do echo "- ${r}_worker: explores from $r perspective"; done)
+EOF
+cd ../..
+
+LEAD_ID=$(uuidgen)
+echo "$LEAD_ID" > .sessions/brainstorm_lead.id
+cd leads/brainstorm_lead
+claude --dangerously-skip-permissions --session-id "$LEAD_ID" \
+  -p "TASK: Brainstorm '$TOPIC' with roles: $ROLES. Create workers, aggregate to .outputs/brainstorm.md" &
+```