Planning With Teams

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 (Task tool only).

Agent Teams Tools

When Agent Teams is enabled, you have access to these tools:

Hooks for quality gates:

• TeammateIdle — Runs when a teammate goes idle. Exit with code 2 to send feedback and keep them working.
• TaskCompleted — Runs when a task is marked complete. Exit with code 2 to prevent completion and send feedback.

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."

Security Boundary

This skill uses a PreToolUse hook to re-read team_plan.md before team tool calls. Content written to team_plan.md is injected into context repeatedly — making it a high-value target for indirect prompt injection.

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)

Best Practices (from official docs)

Team Sizing

• 3-5 teammates works for most workflows
• 5-6 tasks per teammate keeps everyone productive
• More teammates = higher token cost and coordination overhead

Give Teammates Context

Teammates load CLAUDE.md, MCP servers, and skills automatically, but NOT the lead's conversation history. Include task-specific details in spawn prompts:

Spawn a security reviewer with: "Review src/auth/ for vulnerabilities.
Focus on JWT handling in token.js. The app uses httpOnly cookies."

Plan Approval for Risky Tasks

For complex changes, require teammates to plan before implementing:

Spawn an architect teammate to refactor the auth module.
Require plan approval before they make any changes.

The teammate works in read-only plan mode until the lead approves.

Avoid File Conflicts

Break work so each teammate owns different files. Two teammates editing the same file leads to overwrites.

Monitor and Steer

Check in on teammates regularly. Redirect approaches that aren't working. Letting a team run unattended too long increases wasted effort.

Display Modes

Set in your Claude Code settings:

In-process: Use Shift+Down to cycle 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

Known Limitations

Agent Teams are experimental. Be aware of:

• No session resumption with in-process teammates — /resume and /rewind do not restore teammates
• Task status can lag — Teammates sometimes fail to mark tasks complete; check manually
• Shutdown can be slow — Teammates finish current request before shutting down
• One team per session — Clean up current team before starting a new one
• No nested teams — Teammates cannot spawn their own teams
• Split panes require tmux or iTerm2 — Not supported in VS Code terminal, Windows Terminal, or Ghostty

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.

Examples: Planning with Teams in Action

Example 1: Parallel Code Review

User Request: "Review PR #142 for security, performance, and test coverage"

Step 1: Lead Creates Team Plan

# Team Plan: PR #142 Code Review

## Goal
Comprehensive review of PR #142 covering security, performance, and tests.

## Team Composition
| Teammate | Role | Focus | Model |
|----------|------|-------|-------|
| Lead | Coordinator | Synthesis | inherit |
| security-reviewer | Reviewer | Security vulnerabilities | sonnet |
| perf-reviewer | Reviewer | Performance impact | sonnet |
| test-reviewer | Reviewer | Test coverage | haiku |

## Phases

### Phase 1: Security Review [security-reviewer]
- [ ] Check for injection vulnerabilities
- [ ] Review authentication changes
- [ ] Audit data exposure
- **Status:** pending

### Phase 2: Performance Review [perf-reviewer]
- [ ] Analyze query complexity
- [ ] Check for N+1 patterns
- [ ] Review memory usage
- **Status:** pending

### Phase 3: Test Review [test-reviewer]
- [ ] Verify new code has tests
- [ ] Check edge cases covered
- [ ] Review test quality
- **Status:** pending

### Phase 4: Synthesis [Lead]
- [ ] Combine all findings
- [ ] Resolve any conflicts
- [ ] Create final review
- **Status:** pending

Step 2: Lead Spawns Team

Create an agent team to review PR #142:

Teammate 1 (security-reviewer):
- Focus on security vulnerabilities (injection, auth, data exposure)
- Read team_plan.md first, then review the PR
- Write findings to team_findings.md under "## Security Findings"
- Model: sonnet

Teammate 2 (perf-reviewer):
- Focus on performance impact (queries, memory, algorithms)
- Read team_plan.md first, then review the PR
- Write findings to team_findings.md under "## Performance Findings"
- Model: sonnet

Teammate 3 (test-reviewer):
- Focus on test coverage and quality
- Read team_plan.md first, then review the PR
- Write findings to team_findings.md under "## Test Coverage Findings"
- Model: haiku

Step 3: Teammates Work in Parallel

security-reviewer:

Read team_plan.md           # Understand scope
gh pr diff 142              # Get the changes
Read team_findings.md       # Check if others found anything
# ... analyze for security issues ...
Edit team_findings.md       # Add: "## Security Findings\n- Found SQL injection..."
Message lead: "Security review complete. Found 2 critical issues."

perf-reviewer:

Read team_plan.md           # Understand scope
gh pr diff 142              # Get the changes
# ... analyze for performance ...
Edit team_findings.md       # Add: "## Performance Findings\n- N+1 query in..."
Message lead: "Performance review complete. Found 1 warning."

test-reviewer:

Read team_plan.md           # Understand scope
gh pr diff 142              # Get the changes
# ... analyze test coverage ...
Edit team_findings.md       # Add: "## Test Coverage\n- Missing tests for..."
Message lead: "Test review complete. Coverage gaps identified."

Step 4: Lead Synthesizes

Read team_findings.md       # All findings in one place!
# Synthesize into final review
gh pr comment 142 --body "## Code Review Summary..."

Result: team_findings.md

# Team Findings: PR #142 Review

## Security Findings
**Reviewer:** security-reviewer
**Severity:** 2 Critical, 1 Warning

### Critical: SQL Injection in search endpoint
- File: `src/api/search.ts:45`
- Issue: User input directly interpolated into query
- Fix: Use parameterized query

### Critical: Missing auth check on admin route
- File: `src/routes/admin.ts:12`
- Issue: No authentication middleware
- Fix: Add `requireAdmin` middleware

### Warning: Sensitive data in logs
- File: `src/utils/logger.ts:78`
- Issue: Email addresses logged in plain text
- Fix: Mask PII before logging

## Performance Findings
**Reviewer:** perf-reviewer
**Severity:** 1 Warning

### Warning: N+1 Query Pattern
- File: `src/services/users.ts:34`
- Issue: Loading related records in loop
- Fix: Use eager loading with `.include()`

## Test Coverage Findings
**Reviewer:** test-reviewer
**Coverage:** 67% (below 80% threshold)

### Missing Tests
- `src/api/search.ts` - No tests for search endpoint
- `src/routes/admin.ts` - No tests for admin routes

### Recommendations
- Add integration tests for new endpoints
- Add edge case tests for empty results

---

Example 2: Debugging with Competing Hypotheses

User Request: "Users report the app exits after one message instead of staying connected"

Team Plan

# Team Plan: Connection Dropout Bug

## Goal
Identify root cause of connection dropping after one message.

## Team Composition
| Teammate | Role | Hypothesis | Model |
|----------|------|------------|-------|
| Lead | Coordinator | Synthesis | inherit |
| ws-investigator | Researcher | WebSocket issue | sonnet |
| timeout-investigator | Researcher | Timeout/keepalive | sonnet |
| state-investigator | Researcher | State management | sonnet |
| memory-investigator | Researcher | Memory leak | haiku |

## Investigation Rules
1. Each investigator explores their hypothesis
2. Document evidence FOR and AGAINST in team_findings.md
3. Challenge each other's findings
4. Converge on most likely cause

Spawning the Debug Team

Create an agent team to debug the connection dropout:

Spawn 4 investigators, each with a different hypothesis:

1. ws-investigator: "WebSocket connection handling is broken"
2. timeout-investigator: "Keep-alive or timeout misconfiguration"
3. state-investigator: "State gets corrupted after first message"
4. memory-investigator: "Memory leak causes crash"

Have them:
- Explore their hypothesis
- Document evidence to team_findings.md
- Challenge each other's theories
- Converge on root cause

Team Findings After Investigation

# Team Findings: Connection Dropout

## Hypothesis 1: WebSocket Issue [ws-investigator]
**Verdict:** UNLIKELY

### Evidence For
- None found

### Evidence Against
- WebSocket connection established correctly
- Handshake completes successfully
- No errors in WS logs

## Hypothesis 2: Timeout/Keepalive [timeout-investigator]
**Verdict:** LIKELY - PRIMARY CAUSE

### Evidence For
- Server timeout set to 5 seconds (too short!)
- No keepalive ping/pong implemented
- Logs show "connection timeout" errors

### Evidence Against
- None

### Recommendation
- Increase timeout to 30 seconds
- Implement ping/pong keepalive

## Hypothesis 3: State Management [state-investigator]
**Verdict:** CONTRIBUTING FACTOR

### Evidence For
- State not persisted after first message
- Reconnection loses context

### Evidence Against
- Not the primary cause (connection drops regardless)

## Hypothesis 4: Memory Leak [memory-investigator]
**Verdict:** UNLIKELY

### Evidence For
- None found

### Evidence Against
- Memory usage stable
- No growth over time

## CONSENSUS
**Root Cause:** Timeout too short (5s) with no keepalive.
**Secondary Issue:** State not persisted on reconnect.

## Recommended Fix
1. Set timeout to 30 seconds
2. Implement ping/pong every 15 seconds
3. Add state persistence for reconnection

---

Example 3: Feature Development (Frontend + Backend + Tests)

User Request: "Add a dark mode toggle to the settings page"

Team Plan

# Team Plan: Dark Mode Feature

## Goal
Add functional dark mode toggle with theme persistence.

## Team Composition
| Teammate | Role | Owns | Model |
|----------|------|------|-------|
| Lead | Coordinator | Synthesis, final review | inherit |
| frontend-dev | Implementer | UI components, toggle | sonnet |
| backend-dev | Implementer | API, persistence | sonnet |
| test-dev | Implementer | All tests | sonnet |

## File Ownership (AVOID CONFLICTS)
| Teammate | Files They Can Edit |
|----------|---------------------|
| frontend-dev | src/components/*, src/styles/* |
| backend-dev | src/api/*, src/services/* |
| test-dev | tests/*, *.test.ts |

## Phases

### Phase 1: Research [All teammates]
- Explore existing theme system
- Document in team_findings.md
- **Status:** pending

### Phase 2: Frontend Implementation [frontend-dev]
- Create toggle component
- Add theme context
- Style dark mode
- **Status:** pending

### Phase 3: Backend Implementation [backend-dev]
- Add preferences API
- Persist theme choice
- **Status:** pending

### Phase 4: Testing [test-dev]
- Unit tests for toggle
- Integration tests for API
- E2E test for full flow
- **Status:** pending

### Phase 5: Integration [Lead]
- Verify all parts work together
- Final testing
- **Status:** pending

Coordinated Implementation

Phase 1 - All Research:

## Research Findings

### Frontend [frontend-dev]
- Existing theme: CSS custom properties in `src/styles/theme.ts`
- Toggle location: `src/components/Settings/SettingsPage.tsx`
- Theme provider pattern already exists

### Backend [backend-dev]
- User preferences API: `src/api/preferences.ts`
- Storage: Already has preferences table
- Just need to add `theme` field

### Testing [test-dev]
- Test framework: Jest + React Testing Library
- E2E: Playwright
- Coverage threshold: 80%

Phase 2-4 - Parallel Implementation:

Each teammate works on their owned files, writing findings to team_findings.md as they go. No conflicts because file ownership is clear.

---

Example 4: Error Recovery in Teams

The Wrong Way

Teammate-1: Read config.json
Error: File not found
Teammate-1: Read config.json  # Silent retry
Teammate-1: Read config.json  # Another retry

Teammate-2: Read config.json  # SAME ERROR!
Teammate-2: Read config.json  # Repeating mistake

The Right Way

Teammate-1: Read config.json
Error: File not found

Teammate-1: Edit team_findings.md
## Errors Encountered
| Error | Teammate | Resolution |
|-------|----------|------------|
| config.json not found | Teammate-1 | Will create default |

Teammate-1: Write config.json (default config)
Teammate-1: Read config.json
Success!

# Later...
Teammate-2: Read team_findings.md  # Sees the error already resolved
Teammate-2: Read config.json       # Works first try!

---

Example 5: Research Task with Multiple Sources

User Request: "Research authentication best practices and recommend an approach for our app"

Team Setup

# Team Plan: Auth Research

## Goal
Research auth approaches and recommend best fit for our stack.

## Team Composition
| Teammate | Research Area | Model |
|----------|---------------|-------|
| oauth-researcher | OAuth/OIDC providers | haiku |
| jwt-researcher | JWT implementation | haiku |
| session-researcher | Session-based auth | haiku |
| security-researcher | Security comparison | sonnet |

## Research Questions
1. What are the pros/cons of each approach?
2. Which fits our stack (Node.js + React)?
3. What are the security implications?
4. What's the implementation complexity?

Parallel Research

All four researchers work simultaneously:

• Each explores their assigned area
• Documents findings to team_findings.md
• Cross-references other findings

Synthesized Recommendation

# Team Findings: Authentication Research

## OAuth/OIDC [oauth-researcher]
**Pros:** Delegated auth, social login, industry standard
**Cons:** Complexity, external dependency
**Fit:** Good for consumer apps with social login

## JWT [jwt-researcher]
**Pros:** Stateless, scalable, cross-service
**Cons:** Token revocation complexity, size
**Fit:** Good for microservices, APIs

## Session-Based [session-researcher]
**Pros:** Simple, easy revocation, server control
**Cons:** Server state required, scaling challenges
**Fit:** Good for traditional web apps

## Security Comparison [security-researcher]
| Approach | OWASP Score | Common Vulnerabilities |
|----------|-------------|------------------------|
| OAuth | A | Redirect attacks, token leakage |
| JWT | B+ | None if implemented correctly |
| Session | B+ | CSRF, session fixation |

## RECOMMENDATION
For your Node.js + React stack with API-first architecture:
**Use JWT with short expiry + refresh tokens**

Rationale:
1. Stateless = easy scaling
2. Works well with React SPA
3. Good security when implemented correctly
4. Can add OAuth later for social login

---

Key Patterns Across All Examples

Pattern 1: Always Create Plan First

Every example starts with team_plan.md before spawning teammates.

Pattern 2: Clear Ownership

Teammates know exactly what they own. No conflicts.

Pattern 3: Shared Findings

Everything goes to team_findings.md. No siloed knowledge.

Pattern 4: Communicate Completion

Teammates message lead when done. Lead knows when to synthesize.

Pattern 5: Lead Synthesizes

Lead combines all findings into final deliverable.

Reference: Manus Principles for Agent Teams

This skill applies Manus context engineering principles to Claude Code's native Agent Teams feature. Manus was acquired by Meta for $2 billion in December 2025.

Why Manus Principles + Agent Teams?

The Problem:

• Agent Teams give each teammate their OWN context window
• Without coordination, teammates drift from the goal
• Findings get siloed in individual contexts
• Work duplicates or conflicts

The Solution:

• Shared planning files = shared memory across all agents
• Manus principles ensure each agent stays aligned
• Structured communication prevents chaos

┌─────────────────────────────────────────────────────────┐
│                    TEAM LEAD                             │
│         └─ Owns team_plan.md                            │
│         └─ Synthesizes team_findings.md                  │
├─────────────────────────────────────────────────────────┤
│  TEAMMATE 1        TEAMMATE 2        TEAMMATE 3         │
│  Own context       Own context       Own context         │
│       │                 │                 │              │
│       └─────────────────┴─────────────────┘              │
│                         │                                │
│               SHARED PLANNING FILES                      │
│         team_plan.md | team_findings.md | team_progress  │
└─────────────────────────────────────────────────────────┘

---

The 6 Manus Principles (Adapted for Teams)

Principle 1: KV-Cache Efficiency

"KV-cache hit rate is THE single most important metric."

Single Agent: Keep prompts stable for cache hits.

For Teams: Each teammate has their own cache. The shared files provide consistency across caches.

Implementation:

• Shared file structure stays consistent
• Each teammate reads the same team_plan.md
• Stable file format = better cache efficiency per agent

Principle 2: Mask, Don't Remove

"Don't dynamically remove tools (breaks KV-cache). Use logit masking instead."

For Teams:

• Don't change teammate tool access mid-task
• Define tool restrictions at spawn time
• Use role-based tool sets consistently

Principle 3: Filesystem as External Memory (CRITICAL FOR TEAMS)

"Markdown is my 'working memory' on disk."

Single Agent:

Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)

For Teams:

Teammate 1 Context = RAM-1 (volatile, isolated)
Teammate 2 Context = RAM-2 (volatile, isolated)
Teammate N Context = RAM-N (volatile, isolated)
Shared Files = SHARED DISK (persistent, accessible to ALL)

The shared files ARE the team's collective memory.

Principle 4: Manipulate Attention Through Recitation

"Re-read todo.md to push goals into attention span."

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

Teammate-2 has done 30 tool calls...
Original team goal is fading from attention...

→ Read team_plan.md              # Team goal refreshed!
→ Read team_findings.md          # See what others found!
→ Now make decision              # Aligned with team

Principle 5: Keep the Wrong Stuff In

"Leave the wrong turns in the context."

For Teams: Log ALL errors to team_findings.md, not just local context.

## Errors Encountered

### Teammate-1 (Researcher)
| Error | Attempt | Resolution |
|-------|---------|------------|
| API rate limit | 1 | Added delay between requests |

### Teammate-2 (Implementer)
| Error | Attempt | Resolution |
|-------|---------|------------|
| Import not found | 1 | Package needed: pip install X |

This prevents OTHER teammates from hitting the same errors.

Principle 6: Don't Get Few-Shotted

"Uniformity breeds fragility."

For Teams: Varied approaches across teammates.

• Researcher uses breadth-first exploration
• Implementer uses focused implementation
• Reviewer uses skeptical validation

Different perspectives = more robust outcome.

---

The 3 Context Strategies (Adapted for Teams)

Strategy 1: Context Reduction

Single Agent: Compact old tool results.

For Teams:

• Each teammate compacts their OWN context
• Key findings go to team_findings.md BEFORE compaction
• Shared files survive individual context limits

Strategy 2: Context Isolation (THIS IS AGENT TEAMS!)

Manus Architecture:

Planner Agent → Assigns to Executors
Knowledge Manager → Reviews conversations
Executor Sub-Agents → Own context windows

Agent Teams Architecture:

Team Lead → Assigns phases to Teammates
Shared Files → Persistent team knowledge
Teammates → Own context windows, own work

Key Insight: Manus found ~33% of actions were spent updating todo.md. Agent Teams solve this with native task management.

Strategy 3: Context Offloading

For Teams: Teammates offload to shared files:

• Findings → team_findings.md
• Progress → team_progress.md
• Decisions → team_plan.md

---

Anthropic Agent Teams Architecture

Native Tools Available

When CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1:

Storage Locations

Task States

pending → in_progress → completed

• Teammates can self-claim pending tasks
• Task dependencies auto-unblock when prerequisites complete

---

Team Communication Patterns

Pattern 1: Lead-Centric

         ┌──────────┐
         │   LEAD   │
         └────┬─────┘
              │
    ┌─────────┼─────────┐
    │         │         │
    ▼         ▼         ▼
 [TM-1]    [TM-2]    [TM-3]

All communication through lead. Best for simple coordination.

Pattern 2: Peer-to-Peer via Files

         ┌──────────┐
         │   LEAD   │
         └────┬─────┘
              │
    ┌─────────┼─────────┐
    │         │         │
    ▼         ▼         ▼
 [TM-1]────[TM-2]────[TM-3]
    │         │         │
    └─────────┴─────────┘
              │
     [SHARED FILES]

Teammates coordinate through shared files. Best for complex collaboration.

Pattern 3: Broadcast Updates

Lead: "All teammates: Phase 1 complete. Researcher found auth bug.
      See team_findings.md#auth-issue. Proceed to Phase 2."

Use sparingly. Broadcast consumes tokens across all teammates.

---

The Team Agent Loop

Each teammate operates in this loop:

┌─────────────────────────────────────────┐
│  1. READ SHARED CONTEXT                  │
│     - Read team_plan.md                  │
│     - Read team_findings.md              │
│     - Understand team state              │
├─────────────────────────────────────────┤
│  2. ANALYZE OWN TASK                     │
│     - What phase am I on?                │
│     - What do I need to deliver?         │
├─────────────────────────────────────────┤
│  3. EXECUTE                              │
│     - Do the work                        │
│     - Apply Manus principles             │
├─────────────────────────────────────────┤
│  4. UPDATE SHARED FILES                  │
│     - Write findings immediately         │
│     - Log progress                       │
├─────────────────────────────────────────┤
│  5. COMMUNICATE                          │
│     - Message lead on phase complete     │
│     - Flag blockers early                │
├─────────────────────────────────────────┤
│  6. ITERATE OR COMPLETE                  │
│     - More work? Return to step 1        │
│     - Done? Request shutdown             │
└─────────────────────────────────────────┘

---

Token Economics

Agent Teams are expensive. Use them when:

• Parallel exploration adds real value
• Task naturally splits into independent pieces
• Multiple perspectives improve outcome

---

Key Quotes

"Context window = RAM (volatile). Filesystem = Disk (persistent). For teams, shared files = shared disk."

"Each teammate re-reading team_plan.md is like a team standup — everyone realigns."

"Log errors to shared files. Your failure saves your teammate's time."

"Agent Teams without shared files is just expensive parallel chaos."

---

Source Materials

• Manus Context Engineering: https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
• Claude Code Agent Teams: https://code.claude.com/docs/en/agent-teams
• Anthropic Opus 4.6 Announcement: https://www.anthropic.com/news/claude-opus-4-6

Team Findings: [Task Description]

<!-- WHAT: Shared discovery log for the entire team. WHY: Findings in one teammate's context are invisible to others. This file makes them visible. WHEN: Update IMMEDIATELY after any discovery. Don't wait. -->

Discovery Log

<!-- WHAT: Chronological log of all findings. WHY: Shows the team's learning journey. Helps with context recovery. -->

---

Research Findings

<!-- WHAT: Information gathered during research phases. WHY: Shared knowledge base for all teammates. -->

[Topic 1]

Discovered by: [teammate-name] Date: [date]

[Findings here]

[Topic 2]

Discovered by: [teammate-name] Date: [date]

[Findings here]

---

Technical Findings

<!-- WHAT: Code patterns, architecture details, implementation notes. WHY: Teammates need to understand the codebase without re-exploring. -->

Codebase Structure

Discovered by: [teammate-name]

[relevant structure]

Key Files

Patterns Found

• [Pattern 1]
• [Pattern 2]

---

Implementation Notes

<!-- WHAT: Notes from implementation phase. WHY: Helps other teammates understand what was built and why. -->

[Component/Feature 1]

Implemented by: [teammate-name]

Approach: [Description]

Files Modified:

• [file1]
• [file2]

Notes: [Any important context]

---

Test Results

<!-- WHAT: Results from testing phase. WHY: Documents what was verified and what failed. -->

Test Summary

Failed Tests

---

Errors Encountered

<!-- WHAT: Every error any teammate hits, with resolution. WHY: Prevents OTHER teammates from hitting the same errors. CRITICAL: Log immediately. Your failure saves teammate time. -->

[Teammate-1 Name]

[Teammate-2 Name]

---

Decisions Made

<!-- WHAT: Technical and design decisions with rationale. WHY: Teammates need to understand WHY choices were made. -->

---

Open Questions

<!-- WHAT: Questions that need answers. WHY: Ensures nothing falls through the cracks. -->

---

Recommendations

<!-- WHAT: Suggestions for the final deliverable. WHY: Teammates may have insights the lead should consider. -->

From [Teammate-1]

• [Recommendation]

From [Teammate-2]

• [Recommendation]

---

References

<!-- WHAT: Links, docs, resources found during work. WHY: Team knowledge base for future reference. -->

• [Link 1]
• [Link 2]

Team Plan: [Brief Description]

<!-- WHAT: Shared roadmap for the entire team. Every teammate references this file. WHY: Without a shared plan, teammates drift from the goal and duplicate work. WHEN: Create FIRST, before spawning any teammates. Update as phases complete. -->

Goal

<!-- WHAT: One clear sentence describing what the TEAM is trying to achieve. WHY: This is the north star for ALL teammates. Re-reading keeps everyone aligned. --> [One sentence describing the end state]

Team Composition

<!-- WHAT: Who's on the team, their role, what they own, and which model they use. WHY: Clear ownership prevents conflicts and ensures accountability. -->

File Ownership

<!-- WHAT: Which files each teammate can modify. WHY: Prevents merge conflicts and clarifies responsibility. -->

Current Status

<!-- WHAT: Quick overview of where each phase stands. WHY: At-a-glance progress for any teammate reading this file. -->

• Phase 1: [pending/in_progress/complete] ([teammate])
• Phase 2: [pending/in_progress/complete] ([teammate])
• Phase 3: [pending/in_progress/complete] ([teammate])

Phases

<!-- WHAT: Break the task into 3-7 phases. Assign each to a teammate. WHY: Parallel work requires clear boundaries. Each teammate knows their scope. WHEN: Update status when phases complete: pending → in_progress → complete -->

Phase 1: Discovery & Research [Teammate-Name]

<!-- WHAT: Understand requirements, gather context, document findings. WHY: All teammates need shared understanding before diverging. -->

• [ ] Understand user requirements
• [ ] Research existing codebase
• [ ] Document findings in team_findings.md
• [ ] Message lead when complete
• Status: pending
• Assigned: [teammate-name]

Phase 2: Design & Planning [Teammate-Name]

<!-- WHAT: Create implementation approach based on Phase 1 findings. WHY: Good design prevents rework during implementation. -->

• [ ] Review team_findings.md from Phase 1
• [ ] Define technical approach
• [ ] Document decisions in team_findings.md
• [ ] Message lead when complete
• Status: pending
• Assigned: [teammate-name]

Phase 3: Implementation [Teammate-Name]

<!-- WHAT: Build the solution according to the design. WHY: This is where the work happens. -->

• [ ] Implement according to design
• [ ] Update team_progress.md as you go
• [ ] Write to team_findings.md if issues found
• [ ] Message lead when complete
• Status: pending
• Assigned: [teammate-name]

Phase 4: Testing & Verification [Teammate-Name]

<!-- WHAT: Verify the implementation works and meets requirements. WHY: Catch issues before delivery. -->

• [ ] Review implementation
• [ ] Test against requirements
• [ ] Document test results in team_findings.md
• [ ] Message lead when complete
• Status: pending
• Assigned: [teammate-name]

Phase 5: Synthesis & Delivery [Lead]

<!-- WHAT: Combine all work, resolve conflicts, deliver result. WHY: Lead ensures coherent final output. -->

• [ ] Read all team_findings.md entries
• [ ] Resolve any conflicts
• [ ] Create final deliverable
• [ ] Deliver to user
• Status: pending
• Assigned: Lead

Key Questions

<!-- WHAT: Questions the team needs to answer. WHY: Guides research and ensures nothing is missed. --> 1. [Question for the team] 2. [Question for the team]

Decisions Made

<!-- WHAT: Important decisions with rationale. WHY: Teammates need to know WHY choices were made. -->

Blockers

<!-- WHAT: Issues preventing progress. WHY: Visibility helps lead and other teammates assist. -->

Communication Log

<!-- WHAT: Key messages between teammates. WHY: Audit trail of coordination decisions. -->

Notes

<!-- REMINDERS for all teammates: -->

• Re-read this file before major decisions
• Write findings to team_findings.md immediately
• Message lead when your phase completes
• Check team_findings.md before starting work (avoid duplicates)
• Apply 3-Strike Error Protocol (log all errors)

Team Progress: [Task Description]

<!-- WHAT: Session log tracking all team activity. WHY: Provides visibility into what's happening across the team. WHEN: Update throughout the session. Each teammate logs their actions. -->

Session Info

• Started: [timestamp]
• Team: [team-name]
• Goal: [one-line goal]

---

Team Status Dashboard

<!-- WHAT: At-a-glance view of team state. WHY: Quick reference for lead and teammates. -->

Status Legend

• Active: Currently working
• Waiting: Waiting for dependency
• Blocked: Hit a blocker
• Complete: Finished all phases
• Idle: Between tasks

---

Activity Log

<!-- WHAT: Chronological log of all team actions. WHY: Audit trail for debugging and context recovery. -->

[Date]

Lead

[Teammate-1 Name]

[Teammate-2 Name]

---

Phase Progress

<!-- WHAT: Detailed progress within each phase. WHY: More granular than team_plan.md status. -->

Phase 1: [Name]

Owner: [teammate] Started: [time] Completed: [time or "In Progress"]

Phase 2: [Name]

Owner: [teammate] Started: [time] Completed: [time or "In Progress"]

---

Messages Exchanged

<!-- WHAT: Log of teammate communications. WHY: Context for coordination decisions. -->

---

Blockers Log

<!-- WHAT: Issues that blocked progress and how they were resolved. WHY: Learning for future teams. -->

---

Files Modified

<!-- WHAT: All files changed during this session. WHY: Tracking for review and potential rollback. -->

---

Token Usage

<!-- WHAT: Approximate token consumption per teammate. WHY: Agent Teams are expensive. Track costs. -->

---

Session Summary

<!-- WHAT: End-of-session summary. WHY: Quick reference for what was accomplished. WHEN: Fill this in before team cleanup. -->

Completed

• [ ] Phase 1
• [ ] Phase 2
• [ ] Phase 3

Deliverables

• [Deliverable 1]
• [Deliverable 2]

Outstanding Items

• [Item 1]
• [Item 2]

Next Steps

• [Step 1]
• [Step 2]

---

Team Cleanup

<!-- WHAT: Checklist before cleaning up the team. WHY: Ensure nothing is lost. -->

• [ ] All findings written to team_findings.md
• [ ] All progress logged to team_progress.md
• [ ] team_plan.md status updated
• [ ] Deliverables saved
• [ ] Teammates shut down
• [ ] Team cleaned up