From picopala
Orchestrates multi-agent Claude Code teams for complex tasks: spawns fresh workers to implement/fix, reviewers to cross-validate iteratively until approval or max rounds. Use for /picopala or agent swarms.
How this skill is triggered — by the user, by Claude, or both
Slash command
/picopala:picopalaThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Multi-agent orchestration where **every agent's work is reviewed by a different agent** in an **iterative adversarial loop** — the reviewer either APPROVES or sends back for REVISION, with fresh context each round.
Multi-agent orchestration where every agent's work is reviewed by a different agent in an iterative adversarial loop — the reviewer either APPROVES or sends back for REVISION, with fresh context each round.
Uses Claude Code Agent Teams — each teammate is a full independent Claude Code session with its own context window, communicating via messages and a shared task list.
Based on dialectical autocoding research: a structured coach/player feedback loop where the reviewer (coach) independently validates against requirements, catching the implementer's (player's) blind spots and false confidence. Key principles:
| Agent | Role | Tools | Model |
|---|---|---|---|
picopala:picopala-worker | Implement task or apply review fixes, commit, report to lead, shut down | Read, Edit, Write, Bash, Glob, Grep, WebFetch, WebSearch, SendMessage, TaskGet (disallowed: TaskUpdate, TaskCreate, TaskList) | opus |
picopala:picopala-reviewer | Cross-review with APPROVE/REVISE verdict, run verification commands | Read, Glob, Grep, Bash (whitelisted), SendMessage, TaskGet | opus |
Workers can edit files and run any commands. Reviewers cannot edit (disallowedTools: Edit, Write) but can run whitelisted read-only verification commands (tests, typecheck, lint) via a PreToolUse Bash filter hook.
/picopala Build a full authentication system with login, signup, password reset, and tests
/picopala Refactor the payment module — split into separate services with cross-review
/picopala Create a dashboard with API endpoints, React components, and E2E tests
┌──────────────────────────────────────────────┐
│ TECH LEAD (delegate mode only) │
│ Coordinates, delegates, synthesizes. │
│ NEVER implements, edits files, or builds. │
└───┬──────────────┬──────────────┬────────────┘
│ │ │
┌──────▼──┐ ┌──────▼──┐ ┌──────▼──┐
│Worker A │ │Worker B │ │Worker C │ IMPLEMENT
│implement│ │implement│ │implement│
│ commit │ │ commit │ │ commit │
└────┬────┘ └────┬────┘ └────┬────┘
✕ ✕ ✕ SHUTDOWN workers
│ │ │
┌────▼────┐ ┌────▼────┐ ┌────▼────┐
│Review B │ │Review C │ │Review A │ CROSS-REVIEW (round 1)
│→ REVISE │ │→APPROVE │ │→ REVISE │ findings → lead
└────┬────┘ └─────────┘ └────┬────┘
✕ ✕ SHUTDOWN reviewers
│ │
┌────▼────┐ ┌────▼────┐
│Fixer A │ │Fixer C │ FIX (new agents)
│ fixes │ │ fixes │
│ commit │ │ commit │
└────┬────┘ └────┬────┘
✕ ✕ SHUTDOWN fixers
│ │
┌────▼────┐ ┌────▼────┐
│Review B'│ │Review A'│ CROSS-REVIEW (round 2)
│→APPROVE │ │→APPROVE │ fresh context, no pollution
└─────────┘ └─────────┘
✕ ✕ SHUTDOWN reviewers
Intake → Plan → Create Team → [Execute Wave → Iterative Cross-Review Loop] → Cleanup
ALWAYS start here. Before any research or planning, use AskUserQuestion to understand:
Review round trade-offs (explain to user when asking):
Do NOT skip this phase. Do NOT assume scope, constraints, or priorities.
Each task declares explicit dependencies for maximum parallelization. Save to <topic>-plan.md using the template in references/plan-template.md.
Optional per-task fields for advanced control:
model: sonnet to reduce cost. Reserve opus for tasks involving state machine changes, cross-file refactoring, or complex logic.ALWAYS render the plan visually to the user using box-drawing characters showing waves and dependencies:
Wave 1 (parallel) Wave 2 (parallel) Wave 3
┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐
│ T1: Create │ │ T2: Install│ │ T3: Repo │ │ T4: Service│ │ T5: API │
│ DB Schema │ │ Packages │──│ Layer │ │ Layer │──│ Endpoints │
│ [backend] │ │ [config] │ │ [backend] │ │ [backend] │ │ [backend] │
└────────────┘ └────────────┘ └────────────┘ └────────────┘ └────────────┘
│ │ ▲ ▲ ▲
└──────────────┴───────────────┘ │ │
└──────────────┴───────────────┘
Show this to the user and confirm before proceeding.
python ${CLAUDE_PLUGIN_ROOT}/skills/picopala/scripts/picopala.py validate <topic>-plan.md
python ${CLAUDE_PLUGIN_ROOT}/skills/picopala/scripts/picopala.py waves <topic>-plan.md
Spawn a Plan subagent to review for missing dependencies, ordering issues, gaps. Revise if needed.
MANDATORY before creating the team. Verify the working tree is clean:
git diff --name-only HEAD
If the output is non-empty (tracked files have modifications), STOP and tell the user:
"The working tree has uncommitted tracked changes. Please commit or stash them before starting a picopala session. Uncommitted changes in the shared working tree will interfere with parallel workers."
Untracked files (?? in git status --porcelain) are acceptable — they don't cause merge conflicts between parallel workers. Only modified tracked files require commit/stash.
Do NOT proceed to team creation with modified tracked files.
TeamCreate: team_name="picopala-<topic>", description="<task summary>"
CRITICAL: The lead MUST operate in delegate mode. The lead NEVER:
The lead ONLY:
Use Shift+Tab to enter delegate mode, or simply never use file/code tools.
The lead creates the external state directory for hook approval markers:
mkdir -p ~/.claude/picopala-state/picopala-<topic>
Use TaskCreate for each plan task. Set dependencies with TaskUpdate addBlockedBy. Assign to workers with owner.
For each unblocked task, spawn a worker using the bundled picopala-worker agent:
Task tool:
name: "worker-t1"
team_name: "picopala-<topic>"
subagent_type: "picopala:picopala-worker"
prompt: |
## Context
- Plan file: [path to <topic>-plan.md]
- Overview: [relevant goals from plan]
- Completed dependencies: [list]
- Constraints: [risks from plan]
## Your Task
**Task [ID]: [Name]**
Location: [file paths]
Description: [full description]
Acceptance Criteria: [list from plan]
Validation: [tests or verification steps]
i18n scoping (if the task touches translation files): Add to the prompt: "i18n scope: only add/modify keys in the [namespace] namespace of translation files (e.g., en.json, es.json). Do NOT touch keys in other namespaces."
Note on project-level quality hooks: If the project has stop hooks (e.g., typecheck, lint), they may fire on the lead's turn and report errors from workers' in-progress code. This is expected noise during parallel execution — ignore until all workers in the current wave have completed and been shut down.
Workers implement their task, commit, and message the lead with completion status. They then go idle.
After receiving each worker's completion message, immediately send shutdown_request to the worker:
SendMessage type="shutdown_request" recipient="worker-t1" content="Implementation received. Shutting down."
Wait for shutdown_response (approve) before proceeding. All workers must be shut down before starting cross-review.
This is the core of the skill. The review loop iterates until APPROVED or max rounds reached. Each phase uses fresh agents — no agent is ever reused.
For each completed task, spawn a reviewer using the bundled picopala-reviewer agent:
Task tool:
name: "reviewer-t1-r1"
team_name: "picopala-<topic>"
subagent_type: "picopala:picopala-reviewer"
prompt: |
## Task Under Review
**Task [ID]: [Name]**
- Plan file: [path to <topic>-plan.md]
- Description: [task description from plan]
- Acceptance Criteria: [from plan]
- Files Modified: [from worker's output]
- Review Round: [N] of [max_review_rounds]
## Output
Send your findings as raw JSON (no code fences, no prose) via SendMessage to: [lead-name]
Use summary: "T[ID] review: [your verdict]"
Launch ALL reviewers in parallel. The reviewer sends structured JSON findings directly to the lead.
After receiving each reviewer's findings message, immediately send shutdown_request to the reviewer. Wait for shutdown_response before processing the verdict.
Parsing note: Extract the
verdictfield from the reviewer's JSON message. If the message is not valid JSON, treat it as REVISE and include the raw message in the fixer prompt for context.
If verdict = APPROVED:
[a-zA-Z0-9_-] only (replace other chars with _) so the filename matches what the hook expects:
mkdir -p ~/.claude/picopala-state/picopala-<topic> && \
echo "APPROVED by [reviewer-name] round [N] $(date -u +%Y-%m-%dT%H:%M:%SZ)" > ~/.claude/picopala-state/picopala-<topic>/[sanitized_task_id].approved
If verdict = REVISE and round < max_review_rounds:
Task tool:
name: "fixer-t1-r1"
team_name: "picopala-<topic>"
subagent_type: "picopala:picopala-worker"
prompt: |
## Context
- Plan file: [path to <topic>-plan.md]
- Overview: [relevant goals from plan]
- Constraints: [risks from plan]
## Your Task
**Task [ID]: [Name]**
Acceptance Criteria: [list from plan]
## Review Findings (Round [N])
[paste the full findings JSON from the reviewer]
Fix all P0/P1 findings and any FAIL items in the requirements checklist.
Use your judgment on P2/P3 findings.
shutdown_request to the fixer.reviewer-t1-r2) — increment round in name.If verdict = REVISE and round >= max_review_rounds:
failed with note: "Exceeded review budget ([N] rounds). Consider decomposing into smaller tasks."The lead maintains a mental model of each task's review state:
T1: round 1/2 → REVISE → fixer-t1-r1 → round 2/2 → APPROVED ✓
T2: round 1/2 → APPROVED ✓
T3: round 1/2 → REVISE → fixer-t3-r1 → round 2/2 → REVISE → FAILED (max rounds)
The lead only steps in if:
python ${CLAUDE_PLUGIN_ROOT}/skills/picopala/scripts/picopala.py status <topic>-plan.md to check progressAll agents should already be shut down at this point (each was shut down after finishing its work).
shutdown_request to each remaining teammate. Wait up to 10 seconds for shutdown_response. If a teammate does not respond:
shutdown_request with explicit content: "All work is done. Please shut down immediately."rm -rf on home paths as security hooks may block it):
rm ~/.claude/teams/picopala-<topic>/*.json 2>/dev/null; rmdir ~/.claude/teams/picopala-<topic> 2>/dev/null
rm ~/.claude/tasks/picopala-<topic>/*.json 2>/dev/null; rmdir ~/.claude/tasks/picopala-<topic> 2>/dev/null
rm ~/.claude/picopala-state/picopala-<topic>/*.approved 2>/dev/null
rmdir ~/.claude/picopala-state/picopala-<topic> 2>/dev/null
scripts/picopala.py — validate plans, compute waves, check statusnpx claudepluginhub jairotorregrosa/picopala --plugin picopalaOrchestrates multi-agent work at scale—research swarms, parallel builds, wave dispatch, build-review-fix pipelines, and any task needing 3+ agents. Selects strategy by work shape and partitions agents for true parallelism.
Sets up multi-agent teams for complex projects with file-based planning, per-agent directories, and teammate spawning. Triggers on team/swarm/start-project requests.
Orchestrates multi-agent teams to decompose complex tasks, select optimal sub-agents like Explore or Plan, and execute parallel work across domains such as frontend and backend.