Planning with Teams

Manus-style context engineering for Claude Code Agent Teams. Coordinate multiple Claude instances with shared planning files, structured task assignment, and persistent working memory.

Prerequisites

Agent Teams must be enabled:

# In your shell or settings.json
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Without this, Claude cannot spawn teammates. The skill will fall back to subagent mode.

The Core Insight

Agent Teams give each teammate their own context window. But without coordination:

• Teammates forget the overall goal
• Findings get lost between agents
• Work gets duplicated or conflicts

Solution: Apply Manus principles to multi-agent coordination.

Single Agent:     Context Window = RAM (volatile)
                  Filesystem = Disk (persistent)

Agent Team:       Each Agent = Separate RAM
                  Shared Files = Shared Disk

→ Shared planning files become the team's "collective memory"

Quick Start

Before ANY team-based task:

1. Create team_plan.md — Shared roadmap all teammates reference
2. Create team_findings.md — Shared discovery log
3. Create team_progress.md — Shared session log
4. Spawn team with clear roles — Each teammate owns specific phases
5. Teammates re-read plan before decisions — Keeps everyone aligned

Critical: All files go in YOUR PROJECT directory, not the skill folder.

File Locations

The Team Coordination Pattern

Phase 1: Team Lead Creates Plan

Before spawning teammates, the lead creates the shared planning files:

# Create team_plan.md with phases assigned to teammates
Write team_plan.md

# Create empty findings and progress files
Write team_findings.md
Write team_progress.md

Phase 2: Spawn Team with Clear Roles

Create an agent team for [TASK]:

Teammate 1 (researcher):
- Owns Phase 1: Discovery and requirements
- Writes findings to team_findings.md
- Model: haiku (fast, cheap for research)

Teammate 2 (implementer):
- Owns Phase 2-3: Design and implementation
- Reads team_findings.md before starting
- Model: sonnet (balanced)

Teammate 3 (reviewer):
- Owns Phase 4: Testing and verification
- Challenges findings, looks for issues
- Model: sonnet (needs reasoning)

Phase 3: Teammates Follow Manus Rules

Each teammate MUST:

1. Read team_plan.md before major decisions — Re-orients to team goal
2. Write discoveries to team_findings.md — Shared knowledge
3. Update team_progress.md after actions — Visibility for lead
4. Apply 3-Strike Error Protocol — Log failures, don't repeat
5. Message lead when phase complete — Coordination

Phase 4: Lead Synthesizes

When teammates finish:

1. Read all shared files
2. Synthesize findings
3. Resolve any conflicts
4. Deliver final result

Team Roles

Critical Rules

Rule 1: Shared Files Are Sacred

All teammates read from and write to the SAME files:

• team_plan.md — Single source of truth for phases
• team_findings.md — All discoveries go here
• team_progress.md — All activity logged here

Rule 2: Re-Read Before Decide

Each teammate re-reads team_plan.md before major decisions:

[Teammate has done many tool calls...]
[Original team goal may be forgotten...]

→ Read team_plan.md     # Goal refreshed in attention!
→ Now make decision     # Aligned with team objective

Rule 3: Write Findings Immediately

After ANY discovery (code found, error hit, decision made):

Edit team_findings.md   # Add finding immediately

Don't wait. Context is volatile. Disk is persistent.

Rule 4: The 2-Action Rule (Per Teammate)

"After every 2 view/browser/search operations, IMMEDIATELY save findings."

This applies to EACH teammate individually.

Rule 5: No Duplicate Work

Before starting work, teammates check team_findings.md:

Read team_findings.md   # Has someone already found this?

Rule 6: Message on Phase Complete

When a teammate finishes their phase:

Message lead: "Phase X complete. Key findings in team_findings.md section Y.
Ready for Phase X+1 or need review."

Team Plan Structure

# Team Plan: [Task Description]

## Goal
[One sentence — the north star for ALL teammates]

## Team Composition
| Teammate | Role | Phases Owned | Model |
|----------|------|--------------|-------|
| Lead | Coordinator | Synthesis | inherit |
| Agent-1 | Researcher | 1 | haiku |
| Agent-2 | Implementer | 2, 3 | sonnet |
| Agent-3 | Reviewer | 4 | sonnet |

## Current Status
- Phase 1: complete (Agent-1)
- Phase 2: in_progress (Agent-2)
- Phase 3: pending
- Phase 4: pending

## Phases

### Phase 1: Discovery [Agent-1]
- [ ] Research existing code
- [ ] Document patterns found
- [ ] Identify constraints
- **Status:** complete
- **Findings:** See team_findings.md#discovery

### Phase 2: Design [Agent-2]
- [ ] Review Phase 1 findings
- [ ] Create implementation plan
- [ ] Get lead approval if needed
- **Status:** in_progress

When to Use Agent Teams

Use teams for:

• Parallel code review (security + performance + tests)
• Research with competing hypotheses
• Feature development (frontend + backend + tests)
• Large refactoring (multiple modules)
• Cross-layer changes

Don't use teams for:

• Simple single-file edits
• Sequential dependent work
• Tasks under 5 tool calls
• Same-file modifications (conflict risk)

Display Modes

Set in your Claude Code settings:

In-process: Use Shift+Up/Down to select teammates, Ctrl+T for task list.

The 3-Strike Protocol (Team Version)

STRIKE 1: Teammate diagnoses & fixes
  → Log error to team_findings.md
  → Try alternative approach

STRIKE 2: Teammate tries different method
  → Update team_findings.md with attempt
  → If still failing, message lead

STRIKE 3: Escalate to lead
  → Lead reviews team_findings.md
  → Lead may reassign or intervene

AFTER 3 STRIKES: Lead escalates to user
  → Explain team's attempts
  → Share specific blockers
  → Ask for guidance

Anti-Patterns

Templates

Copy these to start:

• templates/team_plan.md — Team phase tracking
• templates/team_findings.md — Shared discoveries
• templates/team_progress.md — Session logging

Scripts

• scripts/check-team-complete.sh — Verify all phases complete
• scripts/check-team-complete.ps1 — Windows version
• scripts/team-status.py — Get team status summary

Advanced Topics

• Manus Principles: See reference.md
• Real Examples: See examples.md

Cleanup

When finished, always clean up the team:

Clean up the team

This removes team resources. Shut down teammates first if any are still running.