tmux-team-creator

What this skill does

# Tmux Team Creator

## Overview

This skill enables creating powerful multi-agent AI teams that run autonomously in tmux sessions. The architecture is battle-tested on complex projects and can be customized for any domain.

**Key Insight**: Sample teams are TEMPLATES, not exact copies. When creating a team, customize roles, prompts, and workflows for the specific project.

---

## ⚠️ CRITICAL: Tmux Pane Detection Bug (EXTREMELY COMMON)

**THIS BUG WILL WASTE HOURS IF NOT PREVENTED!**

### The Bug

When agents need to determine which tmux pane they're running in, **NEVER use `tmux display-message -p '#{pane_index}'`** - this command returns the **ACTIVE/FOCUSED pane** (where the user's cursor is), NOT the pane where the agent is actually running!

### The Fix

**Always use the `$TMUX_PANE` environment variable:**

```bash
# WRONG - Returns active cursor pane, not your pane
tmux display-message -p '#{pane_index}'

# CORRECT - Returns YOUR actual pane
echo $TMUX_PANE
# Then look up this pane ID to get your role
tmux list-panes -a -F '#{pane_id} #{pane_index} #{@role_name}' | grep $TMUX_PANE
```

### Why This Matters

- In multi-agent teams, each pane has a specific role (PO, TL, DEV, etc.)
- Messages must route correctly based on pane roles
- If agents misidentify their pane, they send messages to wrong agents
- This causes hours of debugging "why is PO acting like DEV?"

### Where to Check

When creating a new team from templates, verify these files use `$TMUX_PANE`:

1. **Role prompt files** (`prompts/*_PROMPT.md`) - Should document correct pane detection
2. **Init commands** (`commands/init-role.md`) - Should use `$TMUX_PANE` for role detection
3. **Setup scripts** (`setup-team.sh`) - Should set `@role_name` on correct panes
4. **Hook scripts** (`hooks/*.sh`, `hooks/*.py`) - **CRITICAL:** Must use `$TMUX_PANE`
   - **Bash hooks:** `ROLE=$(tmux show-options -t "$TMUX_PANE" -qv @role_name)`
   - **Python hooks:** `tmux_pane = os.environ.get("TMUX_PANE")` then `["tmux", "show-options", "-pt", tmux_pane, "-qv", "@role_name"]`
   - **WRONG:** `tmux show-options -pv @role_name` (queries cursor pane!)
   - **FIX APPLIED:** `hooks/session_start_team_docs.py` (2026-01-02) - All new teams now use correct detection

### Prevention Checklist

When creating a new team, add this to ALL role prompts:

```markdown
## Tmux Pane Configuration & Role Detection

**CRITICAL: Correct Pane Detection**

**NEVER use `tmux display-message -p '#{pane_index}'`** - it returns the active/focused pane, not YOUR pane!

**Always use $TMUX_PANE environment variable:**

\`\`\`bash
# Find YOUR actual pane ID
echo "My pane: $TMUX_PANE"

# Look up your pane's role
tmux list-panes -a -F '#{pane_id} #{pane_index} #{@role_name}' | grep $TMUX_PANE
\`\`\`
```

**This bug has already been fixed in all sample team templates.** When creating new teams, copy the corrected patterns.

---

## FIRST: Ask User Which Team Template

**Before creating any team, ask the user which template they want to use.**

### Available Templates

#### Software Development Teams

| Template | Best For | Roles | Key Features |
|----------|----------|-------|--------------|
| **scrum-team** | Standard Scrum projects | PO, SM, TL, BE, FE, QA | Full Scrum framework, SM owns process improvement, Sprint-based |
| **scrum-minimal-team** | Small projects, MVPs | PO, SM, EX | Lightweight 3-person Scrum, EX combines TL+DEV+QA |
| **game-dev-team** | Game development projects | PM, GD, FE, BE, QA | Game-focused with design→implementation flow |

#### Research & Analysis Teams

| Template | Best For | Roles | Key Features |
|----------|----------|-------|--------------|
| **mckinsey-research-team** | Market research, competitive analysis | EM, RL, PR, SR, DA, QR | McKinsey 7-step methodology, MECE structuring, Pyramid Principle |
| **pg-insights-team** | Consumer insights, brand strategy | IM, MR, IA, SL, QR | P&G Three-Step Formula, human-centric, goosebumps test |

### Selection Logic

**If user specifies:**
- "Scrum team" / "standard Scrum" / "with Scrum Master" → Use `scrum-team`
- "minimal Scrum" / "small team" / "solo dev" / "MVP" / "lightweight" → Use `scrum-minimal-team`
- "game" / "game development" / "game project" → Use `game-dev-team`
- "market research" / "competitive analysis" / "McKinsey" / "research team" → Use `mckinsey-research-team`
- "consumer insights" / "P&G" / "brand strategy" / "emotional research" → Use `pg-insights-team`

**If user doesn't specify:**
Ask: "Which team template would you like to use?"

**Software Development:**
- **scrum-team** (Recommended for dev) - Full Scrum with PO, SM, TL, BE, FE, QA. SM owns process improvement.
- **game-dev-team** - Game development with PM, GD, FE, BE, QA. Design-first workflow.

**Research & Analysis:**
- **mckinsey-research-team** - McKinsey-style research with EM, RL, PR, SR, DA, QR. Hypothesis-driven, MECE structured.
- **pg-insights-team** - P&G-style consumer insights with IM, MR, IA, SL, QR. Human-centric, emotional + logical.

### Template Descriptions

#### 1. scrum-team (Recommended for most projects)

**Roles:** PO (Product Owner), SM (Scrum Master), TL (Tech Lead), BE (Backend), FE (Frontend), QA (Tester)

**Key Features:**
- Full Scrum framework adapted for AI teams
- SM owns process improvement with 4-checkpoint monitoring mechanism
- Sprint-based workflow with Planning, Review, Retrospective
- Black-box QA testing
- Prompt hygiene rules (add after 2-3 recurring issues, remove when learned)

**Best for:** Teams that want structured improvement, multiple sprints, quality focus

#### 2. scrum-minimal-team (Lightweight Scrum)

**Roles:** PO (Product Owner), SM (Scrum Master), EX (Executive = TL + DEV + QA)

**Key Features:**
- Minimal overhead for small projects
- EX combines architecture, development, and testing
- Same Sprint-based workflow as full Scrum
- SM still owns process improvement
- 3-pane tmux layout

**Best for:** Solo developers, MVPs, prototypes, personal projects wanting Scrum structure

#### 3. game-dev-team (Game Development)

**Roles:** DS (Game Designer), SM (Scrum Master), AR (Game Architect), DV (Game Developer), QA (Game QA)

**Key Features:**
- BMGD (BMAD Game Development) methodology + Scrum practices
- Design→Architecture→Implementation→Testing flow
- 60fps is non-negotiable - performance is a feature
- Playable increments every Sprint
- Design from player experience first

**Workflow:**
1. DS: Create Game Brief and GDD (mechanics, systems, content)
2. AR: Select engine, plan architecture, define performance budgets
3. DV: Implement Sprint stories with TDD
4. QA: Automated tests, playtests, performance profiling

**Best for:** Game development projects, interactive applications, real-time simulations

#### 4. mckinsey-research-team (McKinsey-style research)

**Roles:** EM (Engagement Manager), RL (Research Lead), PR (Primary Researcher), SR (Secondary Researcher), DA (Data Analyst), QR (Quality Reviewer)

**Key Features:**
- McKinsey 7-step problem-solving process
- MECE structuring (Mutually Exclusive, Collectively Exhaustive)
- Pyramid Principle for communication (lead with answer)
- Triangulation (multiple sources for key findings)
- EM owns process improvement with 4-checkpoint monitoring

**Workflow:**
1. Define Problem (EM ↔ Client)
2. Structure Problem (RL - MECE issue tree)
3. Prioritize Issues (EM + RL)
4. Plan Analysis (EM)
5. Conduct Analysis (PR, SR, DA in parallel)
6. Synthesize Findings (RL)
7. Communicate Recommendations (EM + RL → QR → Client)

**Best for:** Market research, competitive analysis, industry analysis, due diligence, strategy research

#### 5. pg-insights-team (P&G-style consumer insights)

**Roles:** IM (Insights Manager), MR (Moments Researcher), IA (Insight Analyst), SL (Strategy Lead), QR (Quality Reviewer)

**Key Features:**
- P&G Three-Step Insights Formula
- Human-centric research (everyday moments)
- Logic + Emotion connection
- Goosebumps test for insight validation
- IM owns process i