Using Polydev Skills

When to Use This Skill

Use polydev skills when the user mentions:

•"parallel" / "simultaneously" / "at the same time"
•"multiple features" / "multiple tasks"
•Lists 2+ independent work items
•"worktree" / "branch" (in context of parallel work)
•"background" / "long-running command"

Script Path (Main Agent Must Follow)

All scripts MUST be called via $POLYDEV_SCRIPTS variable. NEVER use ./scripts/

⚠️ Windows Compatibility - CRITICAL

On Windows (Git Bash/MINGW), scripts MUST be executed using bash -c "$(cat ...)" pattern:

bash

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>

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

Why this pattern? Claude Code's Bash tool on Windows has an issue where direct script execution returns exit code 0 but produces no output and doesn't actually execute.

Skill Selection Flow

code

User message received
    |
Contains parallel/multiple keywords?
    | YES
Is it complex/unclear? --YES--> Run /polydev-brainstorm
    | NO
Ready to execute? --YES--> Use polydev:polydev skill
    |
Need detailed plans? --YES--> Use polydev:writing-plans skill
    |
Running background command? --YES--> Use polydev:terminal-task-runner skill

Available Skills

Skill	When to Use	Who Uses
`/polydev-brainstorm`	Complex/unclear requirements, need to decompose	Main Agent
`polydev:polydev`	Ready to execute parallel tasks	Main Agent
`polydev:writing-plans`	Need detailed implementation plans	Main Agent
`polydev:terminal-task-runner`	Long-running commands (builds, tests, servers, SSH)	Main Agent
`polydev:worktree-executor`	Execute in isolated worktree	Sub-Agent only
`polydev:agent-investigator`	Read-only research tasks	Sub-Agent only

Script Quick Reference (For Main Agent)

Always use run_polydev helper function (see above) for script execution.

Scenario	Script	Parameters
Create worktree + Claude	`spawn-session.sh`	`<workspace> <branch> <worktree-path> <plan-file>`
Monitor status	`poll.sh`	`<worktrees-dir> <timeout>`
Restore crashed session	`restore-session.sh`	`<worktree-path> [--force]`
Send to worktree	`wo-send-command.sh`	`<worktree-path> "<cmd>"`
Send to any session	`send-to-session.sh`	`<pane_id> "<cmd>"`
Read screen output	`capture-screen.sh`	`--pane-id <id> --lines N`
List sessions	`list-sessions.sh`	`[workspace]`
Close session	`close-session.sh`	`<worktree_path>` or `--pane-id <id>`
Start background command	`run-background.sh`	`<name> "<cmd>"`
Start Claude sub-agent	`spawn-agent.sh`	`<name> --prompt "<task>" --report <path> --cwd <dir>`
Start Codex CLI session	`spawn-codex.sh`	`<name> --prompt "<task>" --cwd <dir> [--output <path>]`
Start Gemini CLI session	`spawn-gemini.sh`	`<name> --prompt "<task>" --cwd <dir> [--output <path>]`

Example calls:

bash

run_polydev spawn-session.sh myproject feature/auth .worktrees/feature-auth PLAN.md
run_polydev poll.sh .worktrees 10
run_polydev list-sessions.sh

Red Flags - STOP and Check Polydev

If the main agent thinks:

Thought	Reality
"Execute these sequentially"	If independent, parallelize. Check polydev.
"Simple enough to do directly"	2+ tasks = potential parallelism. Check.
"Don't need the overhead"	Polydev saves time on multi-task work.
"Explore first"	Run /polydev-brainstorm to explore properly.
"Parallelize later"	Parallelize NOW if tasks are independent.

All of these mean: Check polydev skills first.

Quick Decision Guide

User says "implement X, Y, and Z":

•Are X, Y, Z independent? -> polydev:polydev
•Need clarification? -> /polydev-brainstorm
•Need detailed plans? -> polydev:writing-plans first

User says "run this build/test":

•Will it take > 30 seconds? -> polydev:terminal-task-runner
•Need to monitor output? -> polydev:terminal-task-runner

User says "SSH to server and run commands":

•Use polydev:terminal-task-runner
•Use run-background.sh to start SSH
•Use send-to-session.sh to send subsequent commands
•Use capture-screen.sh to read output

User says "research X":

•Read-only analysis? -> Use spawn-agent.sh (Claude), spawn-codex.sh (Codex), or spawn-gemini.sh (Gemini)
•Need parallel research? -> Multiple agents with different AI backends

Cost Control Reminder

Sub-agents MUST use model: "sonnet" unless user explicitly requests otherwise.

javascript

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

// Wrong - will bankrupt user
Task({ prompt: "...", subagent_type: "general-purpose" })

Integration

This skill is the entry point. After determining which skill to use:

code

using-polydev (this skill)
    |
/polydev-brainstorm (if complex)
    |
polydev:writing-plans (if need plans)
    |
polydev:polydev (execution)
    |
polydev:worktree-executor (per-branch, sub-agent)