┌─────────────────────────────────────────────────────────────────┐
│ THIS SKILL REQUIRES GIT REPOSITORY                              │
│ For non-git tasks, use other skills by prefix                   │
├─────────────────────────────────────────────────────────────────┤
│ USE THIS SKILL FOR:                                             │
│ - Parallel development on 2+ independent branches               │
│ - Spawning sub-Claude instances in isolated worktrees           │
│                                                                 │
│ ABSOLUTELY PROHIBITED:                                          │
│ - Calling wezterm/tmux commands directly                        │
│ - Writing git worktree add/remove commands yourself             │
│ - Deleting anything under .worktrees directory                  │
│ - Trying to "do it faster myself" without this skill            │
│                                                                 │
│ FOR BACKGROUND TASKS (bg:) → Use terminal-task-runner skill     │
│ FOR SUB-AGENTS (ag:) → Use agent-investigator skill             │
└─────────────────────────────────────────────────────────────────┘

# Set script path variable (use plugin installation location)
POLYDEV_SCRIPTS="/path/to/polydev/plugins/polydev/scripts"

# Define helper function for Windows compatibility
run_polydev() {
    local script="$1"
    shift
    SCRIPT_DIR="$POLYDEV_SCRIPTS" bash -c "$(cat "$POLYDEV_SCRIPTS/$script")" -- "$@"
}

# ✅ CORRECT - Use run_polydev helper (works on all platforms)
run_polydev spawn-session.sh <workspace> <branch> <worktree-path> <plan-file>
run_polydev poll.sh .worktrees 10
run_polydev list-sessions.sh

# ❌ WRONG - Direct execution FAILS SILENTLY on Windows
"$POLYDEV_SCRIPTS/spawn-session.sh" args...  # Silent failure!

WILL BANKRUPT USER - The following will drain funds:
- Spawn multiple parallel agents with opus model
- Not specifying model parameter (inherits expensive main agent model)
- Using haiku for tasks requiring code capability (will fail repeatedly, wasting more)

CORRECT USAGE:
- Task tool: MUST specify model: "sonnet"
- Only exception: User explicitly says "use opus/haiku"
- Default is always sonnet, no matter how important the task

// WRONG - will inherit main agent's opus model
Task({ prompt: "...", subagent_type: "general-purpose" })

// CORRECT - explicitly specify sonnet
Task({ prompt: "...", subagent_type: "general-purpose", model: "sonnet" })

BANNED FOREVER - The following are permanently prohibited:
- Calling wezterm cli spawn / tmux new-session yourself
- Calling wezterm cli send-text / tmux send-keys yourself
- Calling wezterm cli list / tmux list-sessions yourself
- Calling wezterm cli kill-pane / tmux kill-session yourself
- Reading terminal output yourself to determine status
- Writing git worktree add/remove commands yourself
- Deleting anything under .worktrees directory yourself
- Using relative path ./scripts/ (breaks when leaving directory)
- Any thought of "scripts are too cumbersome, I'll write it faster myself"

CLEANUP ORDER VIOLATION - Will cause "Permission denied":
- Deleting worktree before closing session (terminal holds directory lock!)
- Using rm -rf .worktrees/xxx instead of git worktree remove
- Skipping list-sessions.sh verification before deletion

worktree-path MUST be: .worktrees/<branch-name>

✅ CORRECT: .worktrees/feature-auth
✅ CORRECT: .worktrees/fix-login-bug
❌ WRONG:   /some/other/path
❌ WRONG:   ./src/components
❌ WRONG:   feature-auth (missing .worktrees/ prefix)

workspace determines window grouping. Same workspace = same window with multiple tabs.

✅ CORRECT - All parallel tasks use SAME workspace name:
   run_polydev spawn-session.sh my-project feature/auth ...
   run_polydev spawn-session.sh my-project feature/api ...
   run_polydev spawn-session.sh my-project feature/ui ...
   → Creates 1 window with 3 tabs

❌ WRONG - Different workspace names create separate windows:
   run_polydev spawn-session.sh ws1 feature/auth ...
   run_polydev spawn-session.sh ws2 feature/api ...
   run_polydev spawn-session.sh ws3 feature/ui ...
   → Creates 3 separate windows (BAD!)

Rule: Use project name as workspace for all parallel tasks.

run_polydev spawn-session.sh myproject feature/auth .worktrees/feature-auth PLAN.md

# Output format (TOON):
# worktree=.worktrees/feature,branch=feature,overall_status=in_progress,agent_status=active,last_update=2025-01-09T10:30:00Z,pane_id=5

result=$(run_polydev poll.sh .worktrees 10)

run_polydev restore-session.sh .worktrees/auth
run_polydev restore-session.sh .worktrees/auth --force  # Force restart

run_polydev wo-send-command.sh .worktrees/auth "npm test"
run_polydev wo-send-command.sh .worktrees/auth "password" --no-enter

# Send command to SSH session (use pane_id from list-sessions.sh)
run_polydev send-to-session.sh 5 "docker ps"

# Output format (TOON):
# session_id=wo:myproject:feature.0,status=alive,cwd=/path/to/worktree

run_polydev list-sessions.sh
run_polydev list-sessions.sh myproject

# By worktree path (preferred for wo: sessions)
run_polydev close-session.sh .worktrees/feature-auth

# By pane_id (for bg:/ag: sessions without worktree)
run_polydev close-session.sh --pane-id 5

# Output: Terminal screen content (no headers)

# Via worktree path (preferred for wo: sessions)
run_polydev capture-screen.sh .worktrees/auth --lines 50

# Via pane_id (for bg:/ag: sessions without worktree)
run_polydev capture-screen.sh --pane-id 5 --lines 50

┌─────────────────────────────────────────────────────────────────┐
│ CLEANUP MUST FOLLOW THIS EXACT ORDER:                           │
│                                                                 │
│ 1. close-session.sh  → Close terminal (releases directory lock) │
│ 2. list-sessions.sh  → Verify session is gone                   │
│ 3. git worktree remove → Delete worktree                        │
│ 4. git branch -D     → Delete branch (optional)                 │
│                                                                 │
│ ❌ SKIPPING STEP 1 = "Permission denied" error                  │
│ ❌ Direct rm -rf .worktrees/xxx = FORBIDDEN                     │
└─────────────────────────────────────────────────────────────────┘

run_polydev close-session.sh .worktrees/feature-auth

run_polydev list-sessions.sh  # Should show "(No sessions found)" or not include your session

git worktree remove .worktrees/auth --force
git worktree prune  # Clean up stale references

git branch -D feature-auth

pane_id=$(run_polydev run-background.sh build "npm run build")

pane_id=$(run_polydev spawn-agent.sh auth-research \
  --prompt "Analyze authentication mechanism in project" \
  --report ./.agent-reports/auth.md \
  --cwd "$(git rev-parse --show-toplevel)")

wo:workspace:branch.0    # Parallel dev (worktree)
bg:workspace:name.0      # Background cmd (background)
ag:workspace:name.0      # Agent investigation (agent)

POLYDEV_SCRIPTS="/path/to/polydev/plugins/polydev/scripts"

# Define helper function for Windows compatibility
run_polydev() {
    local script="$1"
    shift
    SCRIPT_DIR="$POLYDEV_SCRIPTS" bash -c "$(cat "$POLYDEV_SCRIPTS/$script")" -- "$@"
}

# After starting all sessions, immediately enter monitoring loop - cannot skip!
while branches_remaining; do
  result=$(run_polydev poll.sh .worktrees 10)  # Must call!

  # Parse TOON output lines
  echo "$result" | while IFS=',' read -r key1 rest; do
    worktree=$(echo "$key1" | cut -d'=' -f2)
    # Extract other fields: overall_status, agent_status, session_id, etc.
  done

  # Handle each worktree based on status
  # overall_status: in_progress, completed, hil, blocked, conflict, rejected
  # agent_status: active, idle, crashed

  case "$agent_status" in
    crashed) run_polydev restore-session.sh "$worktree" --force ;;
    idle)    # Check if restart needed
  esac

  case "$overall_status" in
    completed) # Verify and merge
    hil)       # Human intervention (human must decide)
    blocked)   # Needs help (main agent tries to solve, escalate to hil if fails)
  esac
done

User request
    |
Phase 0: Brainstorming (Optional)
    - Use polydev:brainstorming for complex/unclear requests
    |
Phase 1: Verification Strategy Research
    |
Phase 2: Task Decomposition
    |
Phase 3: User Confirmation
    |
Phase 4: Parallel Execution (spawn-session.sh + poll.sh loop)
    |
Phase 5: Incremental Verify & Merge
    |
Phase 6: Cleanup (Human Confirms)