planning-with-teams - GitLite

KO | EN

gitlite — search

#web #api #machine-learning #ai #computer-vision #claude-code #ruby #animation #kubernetes #list

planning-with-teams

(★ 27)

Manus-style context engineering for Claude Code Agent Teams. Coordinate multiple Claude instances with shared planning files.

File Explorer

ZIP Download

- marketplace.json
- plan.md
- spawn-team.md
- status.md
- team-status.md
- team.md
- installation.md
- troubleshooting.md
- README.md
- banner-v2.png
- banner.png
- card-v2.png
- check-team-complete.ps1
- check-team-complete.sh
- - examples.md
  - reference.md
  - SKILL.md
- team_findings.md
- team_plan.md
- team_progress.md
.gitignore
CHANGELOG.md
CITATION.cff
LICENSE
package.json
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

Command Glossary

Commands referenced in this DOCs, explained below.

🔍

`git clone`

View Details ▼

Clone an existing repository.

git clone {{remote_repository_location}} {{path/to/directory}}

Clone an existing repository into a new directory (the default directory is the repository name):

git clone --recursive {{remote_repository_location}}

Clone an existing repository and its submodules:

git clone {{[-n|--no-checkout]}} {{remote_repository_location}}

Clone only the `.git` directory of an existing repository:

🔍

`npx`

View Details ▼

This command is an alias of `npm exec`.

tldr npm exec

View documentation for the original command:

# Project Badges

License: MIT Visit
Claude Code Plugin Visit
Agent Teams Visit
Version Visit
Opus 4.6 Visit
skillcheck passed Visit

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<p align="center">
  <a href="https://github.com/OthmanAdi/planning-with-teams">
    <img src="https://raw.githubusercontent.com/OthmanAdi/planning-with-teams/master/media/banner-v2.png" alt="Planning with Teams" width="900">
  </a>
</p>

**Manus-style context engineering for Claude Code Agent Teams.**

Coordinate multiple Claude Code instances with shared planning files, structured task assignment, and persistent working memory. The first skill to apply proven context engineering methodology to multi-agent workflows.

> Based on [planning-with-files](https://github.com/OthmanAdi/planning-with-files) methodology

---

## ⚠️ IMPORTANT: Agent Teams Must Be Enabled

<details>
<summary><strong>Click to expand - You MUST enable Agent Teams before using this skill</strong></summary>

### Why This Matters

Without Agent Teams enabled, this skill will fall back to using Task subagents. While subagents work, they **cannot** use the native Agent Teams features:
- ❌ No peer-to-peer messaging between teammates
- ❌ No Teammate, SendMessage, TaskCreate tools
- ❌ Limited to Task tool (standard subagents)

### How to Enable

**Option 1: Settings.json (Recommended)**

Add this to `~/.claude/settings.json`:
```json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}
```

**Option 2: Environment Variable**

Add to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.):
```bash
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
```

### Verify It's Enabled

After enabling, **restart Claude Code** and check that the skill uses "Agent Teams" mode instead of "Task subagents" mode in the team plan.

</details>

---

## Why This Exists

Claude Code's [Agent Teams](https://code.claude.com/docs/en/agent-teams) feature lets you coordinate multiple Claude instances working in parallel. But without proper coordination:

- Teammates forget the overall goal
- Findings get siloed in individual contexts
- Work gets duplicated or conflicts
- Token costs skyrocket with no benefit

**Planning with Teams** solves this by applying [Manus principles](https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus) to multi-agent coordination:

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

Agent Team:       Each Agent = Separate RAM (isolated)
                  Shared Files = Shared Disk (accessible to ALL)

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

---

## Features

- **100% Native Agent Teams** — Uses Anthropic's built-in Teammate, SendMessage, TaskCreate tools
- **Shared Planning Files** — `team_plan.md`, `team_findings.md`, `team_progress.md`
- **Manus Methodology** — Re-read before decide, log errors, 3-Strike Protocol
- **Clear Ownership** — File ownership prevents conflicts
- **Hooks Integration** — Automatic status checks on session end
- **Cross-Platform Scripts** — Bash, PowerShell, and Python utilities

---

## Quick Start

### 1. Enable Agent Teams

```bash
# In your shell
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

# Or in settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}
```

### 2. Install the Skill

```bash
npx skills add OthmanAdi/planning-with-teams --skill planning-with-teams -g
```

Or from npm: `pi install npm:planning-with-teams` ([package](https://www.npmjs.com/package/planning-with-teams))

Works with Claude Code, Cursor, Codex, Gemini CLI, and 40+ agents supporting the [Agent Skills](https://agentskills.io) spec.

<details>
<summary><strong>🔧 Claude Code Plugin (Advanced Features)</strong></summary>

For Claude Code-specific features like `/team` autocomplete commands:

```bash
# Add marketplace
/plugin marketplace add OthmanAdi/planning-with-teams

# Install plugin
/plugin install planning-with-teams
```

Or clone manually:
```bash
git clone https://github.com/OthmanAdi/planning-with-teams.git ~/.claude/plugins/planning-with-teams
```

</details>

### 3. Use It

```
/team
```

Or describe your task:
```
Create an agent team to review PR #142 for security, performance, and test coverage.
Use planning-with-teams for coordination.
```

---

## How It Works

### The Coordination Pattern

```
┌─────────────────────────────────────────────────────────┐
│                    TEAM LEAD                             │
│         └─ Creates team_plan.md                         │
│         └─ Assigns phases to teammates                   │
│         └─ Synthesizes team_findings.md                  │
├─────────────────────────────────────────────────────────┤
│  TEAMMATE 1        TEAMMATE 2        TEAMMATE 3         │
│  (Phase 1)         (Phase 2)         (Phase 3)          │
│       │                 │                 │              │
│       └─────────────────┴─────────────────┘              │
│                         │                                │
│               SHARED PLANNING FILES                      │
│       team_plan.md | team_findings.md | team_progress    │
└─────────────────────────────────────────────────────────┘
```

### The Three Shared Files

| File | Purpose | Who Updates |
|------|---------|-------------|
| `team_plan.md` | Shared roadmap, phases, status | Lead + all teammates |
| `team_findings.md` | Discoveries, errors, decisions | All teammates |
| `team_progress.md` | Session log, activity tracking | All teammates |

### Each Teammate Follows Manus Rules

1. **Read team_plan.md before major decisions** — Re-orients to team goal
2. **Write findings immediately** — Don't wait, context is volatile
3. **Apply 3-Strike Error Protocol** — Log failures, don't repeat
4. **Message lead when phase complete** — Coordination

---

## Commands

| Command | Autocomplete | Description |
|---------|--------------|-------------|
| `/planning-with-teams:plan` | Type `/plan` | Start team planning (v1.1.0+) |
| `/planning-with-teams:status` | Type `/status` | Show team progress at a glance (v1.1.0+) |
| `/planning-with-teams:team` | Type `/team` | Guided team setup |
| `/planning-with-teams:spawn-team` | Type `/spawn` | Quick spawn team for a task |
| `/planning-with-teams:team-status` | — | Get comprehensive status report |

> **New in v1.1.0:** `/plan` and `/status` commands for consistency with [planning-with-files](https://github.com/OthmanAdi/planning-with-files).

---

## 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)
- Debugging with multiple theories

**Don't use teams for:**
- Simple single-file edits
- Sequential dependent work
- Tasks under 5 tool calls
- Same-file modifications (conflict risk)

---

## Examples

### Parallel Code Review

```
Create an agent team to review PR #142:

Teammate 1 (security-reviewer):
- Focus on security vulnerabilities
- Write to team_findings.md under "## Security Findings"

Teammate 2 (perf-reviewer):
- Focus on performance impact
- Write to team_findings.md under "## Performance Findings"

Teammate 3 (test-reviewer):
- Focus on test coverage
- Write to team_findings.md under "## Test Coverage"
```

### Debugging with Competing Hypotheses

```
Create an agent team to investigate the connection dropout bug:

Spawn 4 investigators with different hypotheses:
1. WebSocket handling issue
2. Timeout/keepalive misconfiguration
3. State management corruption
4. Memory leak

Have them document evidence FOR and AGAINST in team_findings.md,
challenge each other's findings, and converge on root cause.
```

See [examples.md](skills/planning-with-teams/examples.md) for more.

---

## Token Economics

| Mode | Cost | When to Use |
|------|------|-------------|
| Single agent | 1x | Simple tasks |
| Subagents | 1.5-2x | Focused delegation |
| **Agent Teams** | 3-5x | Complex parallel work |

Agent Teams are expensive. Use them when parallel exploration genuinely adds value.

---

## Requirements

- Claude Code 2.1.32+
- `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
- For split-pane mode: tmux or iTerm2

---

## Documentation

- [SKILL.md](skills/planning-with-teams/SKILL.md) — Full methodology
- [reference.md](skills/planning-with-teams/reference.md) — Manus principles adapted for teams
- [examples.md](skills/planning-with-teams/examples.md) — Real use cases

---

## Related Projects

- [planning-with-files](https://github.com/OthmanAdi/planning-with-files) — Single-agent planning (the foundation)
- [Claude Code Agent Teams Docs](https://code.claude.com/docs/en/agent-teams) — Official documentation

---

## License

MIT License - see [LICENSE](LICENSE)

---

## Author

**Ahmad Othman Ammar Adi**

- GitHub: [@OthmanAdi](https://github.com/OthmanAdi)
- Website: [othmanadi.com](https://othmanadi.com)