Execute the pending plan in PLANS.md using an agent team for parallel implementation. Use when user says "implement the plan", "execute the plan", "team implement", or after any plan-* skill creates a plan. Spawns worker agents in isolated git worktrees for full code isolation. Updates Linear issues in real-time. Falls back to single-agent mode if agent teams unavailable.
Execute the current pending work in PLANS.md using an agent team for parallel implementation. You are the team lead/coordinator. You break the plan into domain-based work units, create isolated git worktrees for each worker, spawn worker agents, coordinate their progress, merge their work, and handle verification and documentation.
Each worker operates in its own git worktree — a fully isolated working directory with its own branch, staging area, and node_modules. Workers cannot corrupt each other's files. Task assignment is domain-based — overlapping file edits are acceptable and resolved by the lead during the merge phase.
If agent teams are unavailable (TeamCreate fails), fall back to single-agent mode — see "Fallback: Single-Agent Mode" section.
mcp__linear__list_issues with team: "Food Scanner" and state: "Todo" directly (never delegate to a subagent — subagents don't have MCP access). If the tool is unavailable or errors, and tell the user: "Linear MCP is not connected. Run to reconnect, then re-run this skill." Do NOT rationalize continuing without Linear./mcp## Fix Plan (h2 level) with no iteration after itBefore partitioning into work units, assess whether workers are justified. Worker overhead (worktree setup, team creation, spawning, coordination, merge, cleanup) is significant — only use workers when the implementation work clearly exceeds that overhead.
For each pending task/fix, estimate its size:
| Size | Description | Examples |
|---|---|---|
| 0 | No TypeScript code — docs, config, skill files only | Update CLAUDE.md, edit .env.example, modify SKILL.md |
| S | Single-line or few-line surgical change | Replace one API call, add try/catch, add an attribute, fix a condition |
| M | Moderate implementation with tests | New error state with tests, add timeout+logging to multiple calls |
| L | Substantial new code or multi-file feature | New component, new API route, refactor a module, implement a protocol |
claude.ts = 1 unit, not 2.| Independent work units | Total effort | Decision |
|---|---|---|
| 1 unit (any effort) | Any | Single-agent — no parallelism benefit |
| 2+ units | ≤6 points | Single-agent — worker overhead exceeds implementation time |
| 2+ units | 7–11 points | Workers if ≥3 units, otherwise single-agent |
| 2+ units | ≥12 points | Workers — parallelism pays off |
Announce the decision with reasoning: "N tasks across M independent units, effort score P — [workers/single-agent mode]." Then jump to "Fallback: Single-Agent Mode" if single-agent, or continue to "Work Partitioning" if workers.
Rationale: Pure task/file counts miss complexity. Five surgical fixes (5×S=5 points) don't justify workers even across 7 files, but four substantial features (4×L=16 points) clearly do. The effort score captures this. Calibrated from real iterations: a batch of 7 mixed M/L tasks across 3 domains → workers justified and succeeded; a batch of 3 small fixes → worker overhead wasted more time than the fixes took; a fix plan of 5 S-sized tasks → single-agent was correct.
Group pending tasks into work units by domain — related areas of the codebase that form coherent implementation units. Workers MAY touch overlapping files; the lead resolves conflicts during the merge phase.
For each pending task in PLANS.md:
Group tasks into work units where:
Partitioning guidelines:
Deciding the number of workers:
| Work units | Workers |
|---|---|
| 1 | 1 (still benefits from dedicated context) |
| 2 | 2 |
| 3 | 3 |
| 4+ | Cap at 4 (diminishing returns, coordination overhead) |
Tasks involving CLI tools that generate files (e.g., npx drizzle-kit generate) MUST NOT be assigned to workers. Workers hand-write generated files instead of running the command, producing corrupt output.
How to handle:
Before proceeding, verify:
Log the partition plan — output to the user so they can see how work is divided.
If on main, create a feature branch:
git checkout -b feat/<plan-name>
If already on a feature branch, stay on it. Record the branch name as FEATURE_BRANCH.
Remove any leftover worktrees and branches from a previous failed run:
git worktree prune
# For each worker N:
git branch -D <FEATURE_BRANCH>-worker-N 2>/dev/null || true
rm -rf _workers/
For each worker:
git worktree add _workers/worker-N -b <FEATURE_BRANCH>-worker-N
IMPORTANT: Use a hyphen (-worker-N), NOT a slash (/worker-N). Git cannot create refs/heads/feat/foo-123/worker-1 when refs/heads/feat/foo-123 already exists as a branch ref.
Example: if FEATURE_BRANCH is feat/foo-123-notifications, worker branches are:
feat/foo-123-notifications-worker-1feat/foo-123-notifications-worker-2Pre-check: Verify .gitignore covers symlinks before creating them. The node_modules/ entry (with trailing slash) only matches directories — a symlink is a file and won't be excluded. Ensure a bare node_modules entry exists:
grep -q '^node_modules$' .gitignore || sed -i '' '/^node_modules\//i\
node_modules' .gitignore
Each worktree needs dependencies and environment variables:
# For each worker N:
ln -s "$(pwd)/node_modules" _workers/worker-N/node_modules
cp .env _workers/worker-N/.env 2>/dev/null || true
cp .env.local _workers/worker-N/.env.local 2>/dev/null || true
Why symlink, not copy: cp -r node_modules breaks .bin/ symlinks on macOS — cp -r dereferences symlinks, turning .bin/vitest -> ../vitest/vitest.mjs into a regular file containing import './dist/cli.js' that can't resolve. Symlinking is instant and avoids the issue entirely. Workers don't install packages, so a shared read-only reference is safe.
If git worktree add fails:
git worktree prune && rm -rf _workers/git branch -D <FEATURE_BRANCH>-worker-N 2>/dev/null || trueUse TeamCreate:
team_name: "plan-implement"description: "Parallel plan implementation with worktree-isolated workers"If TeamCreate fails, clean up worktrees and switch to Fallback: Single-Agent Mode.
Use TaskCreate for each work unit:
Use Task tool with team_name: "plan-implement", subagent_type: "general-purpose", model: "sonnet", and mode: "bypassPermissions" for each worker. Name them worker-1, worker-2, etc.
Spawn all workers in parallel (concurrent Task calls in one message).
Read references/worker-prompt-template.md for the full worker prompt template, testing context examples, and protocol consistency block.
After spawning, for each work unit:
TaskUpdate to assign each task to its worker by namemcp__linear__update_issue:
CRITICAL: Workers do NOT have access to Linear MCP tools. The lead handles ALL Linear state transitions.
When a worker REPORTS starting a task:
mcp__linear__update_issueWhen a worker REPORTS completing a task:
mcp__linear__update_issueIf a task has no Linear issue link, skip state updates for that task.
After spawning workers, wait at least 5 minutes before taking any corrective action. Workers need 2–4 turns to: cd to workspace, validate environment, read CLAUDE.md, read source files, and send their first "Starting Task" message.
During the grace period:
After 5 minutes with no messages from a worker:
git -C _workers/worker-N status --shortWhile workers are actively working (uncommitted changes visible in their worktree):
git -C _workers/worker-N status --shortIf the user reports a worker is struggling, check worktree status first. If changes exist, the worker is making progress — report this to the user and wait. Workers often hit temporary test failures and self-resolve within a few turns.
TaskListTaskUpdate
d. Immediately send shutdown request via SendMessage with type: "shutdown_request" — do not wait for other workers to finishTeamDelete immediately — the team is no longer needed. Deleting it now prevents bug-hunter/verifier subagents from accidentally joining as team members.| Blocker Type | Action |
|---|---|
| Worker needs another worker's code | Tell them to proceed with their best assumption — conflicts resolved at merge |
| Test failure worker can't resolve | Read the failing test output, provide guidance |
| Unclear requirements | Re-read PLANS.md, provide clarification |
| Generated file needed | Acknowledge — lead handles it post-merge |
Once ALL workers have reported completion and committed their changes:
Before sending any shutdown requests, verify each worker's state:
# For each worker N:
git -C _workers/worker-N log --oneline -1
git -C _workers/worker-N status --short
If a worker has uncommitted changes (files listed by status --short), salvage them:
git -C _workers/worker-N add -A -- ':!node_modules' ':!.env' ':!.env.local'
git -C _workers/worker-N commit -m "lead: salvage worker-N uncommitted progress"
Workers should already be shut down individually during the Coordination phase (each shut down as they completed). Verify:
TaskListTeamDelete was called after the last shutdown confirmationIf any worker was NOT shut down during coordination (e.g., went idle without reporting), salvage their work (step 1) and send shutdown now. Call TeamDelete after the last confirmation.
CRITICAL: Never delete worktrees while workers are alive. Worktree deletion is IRREVERSIBLE and destroys all uncommitted worker progress. The sequence MUST be: shutdown all workers → verify all confirmed → THEN delete worktrees in the Cleanup phase.
Merge worker branches into the feature branch one at a time, foundation-first.
Determine merge order:
For each worker branch (in order):
git merge <FEATURE_BRANCH>-worker-N
After each merge (starting from the second):
npm run typecheck
If type errors → fix them before merging the next worker. This catches integration issues early before they compound.
If a merge has conflicts:
grep -rn '<<<<<<\|======\|>>>>>>' <resolved-files> — fix any stray markers before committinggit add resolved files, then git commit (git's auto-generated merge message is fine)npm run typecheck before continuing to the next mergeIf git merge fails entirely (e.g., worktree artifacts like committed symlinks):
git cherry-pick <FEATURE_BRANCH>-worker-N --no-commitgit reset HEAD node_modules 2>/dev/nullgit commit -m "fix: [worker summary]"node_modules is still a real directory (not a symlink): ls -ld node_modules | head -1rm -f node_modules && npm installIf any tasks were reserved for the lead during partitioning:
npx drizzle-kit generate)If the plan required new npm packages that workers couldn't install:
npm install <package-name>
Run the full unit/integration test suite immediately after all merges:
npm test
Why here (before bug-hunter): Workers only run targeted tests (npx vitest run "pattern") in their worktrees. Cross-domain integration bugs (missing events on certain paths, stale closures at boundaries, type mismatches between worker outputs) only surface when all code is merged and the full suite runs. Catching these before bug-hunter reduces the bug-hunter's job to logic issues that tests don't cover.
If failures → fix directly, then re-run until all tests pass.
Ensure PostgreSQL is running before E2E tests:
docker ps --filter name=postgres-e2e --format '{{.Status}}' | grep -q Up || \
(docker rm -f postgres-e2e 2>/dev/null; docker run -d --name postgres-e2e -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=food_scanner -p 5432:5432 postgres:latest && \
until docker exec postgres-e2e pg_isready -U postgres 2>/dev/null; do sleep 1; done)
Run the verifier agent in E2E mode:
Task tool with subagent_type "verifier" and prompt "e2e"
If E2E tests fail → fix the specs directly, then re-run.
Bug hunter:
Task tool with subagent_type "bug-hunter"
Fix ALL real bugs — pre-existing or new. Only skip verifiable false positives.
Verifier (tests + lint + build):
Task tool with subagent_type "verifier"
If failures → fix directly (workers are shut down by this point).
After verification passes, append a new "Iteration N" section to PLANS.md using the template in references/iteration-template.md.
After documenting results (skip in single-agent fallback mode), the lead MUST clean up worktrees, worker branches, sync dependencies, and verify clean state. Follow references/cleanup-procedures.md for the full step-by-step procedure.
If TeamCreate fails or worktree setup fails, implement the plan sequentially as a single agent:
Inform user: "Agent teams/worktrees unavailable. Implementing in single-agent mode."
Clean up any partially created worktrees: git worktree prune && rm -rf _workers/
Follow TDD strictly for each task:
Track point budget as a proxy for context usage:
| Tool call type | Points |
|---|---|
| Glob, Grep, Edit, MCP call (Linear etc.) | 1 |
| Read, Write | 2 |
| Bash (test run, build, git) | 3 |
| Task subagent (verifier, bug-hunter) | 5 |
| Cumulative points | Action |
|---|---|
| < 200 | Continue to next task |
| 200–230 | Continue only if next task is small (≤ 3 files) |
| > 230 | STOP — run pre-stop checklist immediately |
Pre-stop checklist (run when stopping, regardless of reason):
bug-hunter agent — fix ALL real bugs foundverifier agent — fix any failures or warningsDocument results — Same Iteration block format (omit Work Partition and Merge Summary)
MANDATORY: After cleanup (or after documenting results in single-agent mode), commit all changes and push.
Steps:
git status --porcelain=v1, then git add <file> ... — skip files matching .env*, *.key, *.pem, credentials*, secrets*-m string (do not include Co-Authored-By tags):
git commit -m "plan: implement iteration N - [brief summary]"
Use "Method: single-agent" in fallback mode. Keep the message on one line — task details are already in PLANS.md.
IMPORTANT: Do NOT use git commit -m "$(cat <<'EOF'...)" or any $() subshell — the subshell triggers permission prompts even with Bash(git *) in the allow list.git pushBranch handling:
main, create a feature branch first: git checkout -b feat/[plan-name]| Situation | Action |
|---|---|
| PLANS.md doesn't exist or is empty | STOP — "No plan found. Run plan-backlog or plan-inline first." |
| PLANS.md has "Status: COMPLETE" | STOP — "Plan already complete. Create a new plan first." |
git worktree add fails | Clean up, fall back to single-agent mode |
| TeamCreate fails | Clean up worktrees, switch to single-agent fallback |
| Worker branch already exists | Delete it first: git branch -D <branch> 2>/dev/null |
| All tasks in same domain (1 unit) | Use 1 worker — still benefits from isolated context |
| Worker stops without reporting | Check worktree: git -C _workers/worker-N status --short. If changes exist, salvage and commit from lead. If empty, implement tasks in single-agent mode. Do NOT delete the worktree until shutdown is confirmed. |
| Worker reports workspace missing | Worktree was deleted prematurely. Shut down the worker. Implement its tasks in single-agent mode. |
| Worker's Bash environment breaks | Known bug (#17321) — worker used Bash for file ops. Shut down the worker. Implement its tasks in single-agent mode. |
| Small batch (low effort score) | Skip workers entirely — use single-agent mode from the start (see Scope Assessment) |
| Merge conflict | Resolve in feature branch, run typecheck, continue merging |
| Type errors after merge | Fix before merging next worker |
| Integration failures after all merges | Fix directly in verification phase |
| Test won't fail in step 2 (single-agent) | Review test logic — ensure it tests new behavior |
| Test won't pass in step 4 (single-agent) | Debug implementation, do not skip |
This skill implements plans. It does NOT:
npx vitest run "pattern" in their worktree. No build, no full suite, no E2E.npm run typecheck) after each merge. After resolving conflicts, always verify no stray <<<<<< markers remain.git add -A && git commit in their worktree. Lead merges locally via the shared git object database.Co-Authored-By tags.env*, *.key, *.pem, credentials*, secrets*