skill-parallel-agents

Decompose large tasks across parallel agents — use for migrations, multi-file refactors, or batch work

Quality

73%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/skill-parallel-agents/SKILL.md

Claude Octopus - Multi-Tentacled Orchestrator

MANDATORY COMPLIANCE — DO NOT SKIP

When this skill is invoked, you MUST dispatch work to multiple providers in parallel. You are PROHIBITED from:

Running tasks sequentially with a single model instead of parallel multi-provider dispatch
Skipping orchestrate.sh and doing the work directly
Deciding the task is "simple enough" for a single provider
Substituting serial Claude-only execution for multi-LLM parallel execution

This skill exists specifically for multi-provider parallel work. If you catch yourself thinking "I'll just do this myself" — STOP.

Multi-tentacled orchestrator for Claude Code - using Double Diamond methodology for comprehensive problem exploration, consensus building, and validated delivery.

DISCOVER          DEFINE           DEVELOP          DELIVER
      (probe)         (grasp)          (tangle)          (ink)

    \         /     \         /     \         /     \         /
     \   *   /       \   *   /       \   *   /       \   *   /
      \ * * /         \     /         \ * * /         \     /
       \   /           \   /           \   /           \   /
        \ /             \ /             \ /             \ /

   Diverge then      Converge to      Diverge with     Converge to
    converge          problem          solutions        delivery

Quick Start

Note for Claude Code users: You don't need to run these commands! Just talk naturally to Claude:

"Research OAuth authentication patterns"

"Build a user authentication system"

"Review this code for security issues"

The commands below are for direct CLI usage or automation.

# Full Double Diamond workflow (all 4 phases)
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh embrace "Build a user authentication system"

# Individual phases
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh probe "Research authentication best practices"
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grasp "Define auth requirements"
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh tangle "Implement auth feature"
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh ink "Validate and deliver auth implementation"

# Crossfire: Adversarial cross-model review
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grapple "implement password reset API"
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grapple --principles security "implement JWT auth"
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh squeeze "review auth.ts for vulnerabilities"

# Smart auto-routing (detects intent automatically)
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "research OAuth patterns"           # -> probe
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "build user login"                  # -> tangle + ink
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "review the auth code"              # -> ink

IMPORTANT: When NOT to Use This Skill

DO NOT use this skill if the user's request involves:

Built-in Claude Code commands - Commands starting with / that are part of Claude Code itself:
- /plugin - Plugin management (add, remove, update, list)
- /init - Project initialization
- /help - Help documentation
- /clear - Clear conversation
- /commit - Git commit operations
- /remember - Memory management
- Any other / command that isn't /parallel-agents or /octo:*
Direct tool usage - Simple file operations, git commands, or terminal tasks
- Reading/writing files
- Running git commands
- Basic bash operations
- These should use built-in tools directly
Claude Code configuration - Managing Claude Code itself
- Changing settings
- Managing plugins
- Updating Claude Code

If the user's request matches any of the above, DO NOT activate this skill. Handle the request using standard Claude Code tools and capabilities instead.

Visual Indicators - Know What's Running

Claude Octopus uses visual indicators so you always know which AI is responding:

Indicator	Meaning	Uses
🐙	Parallel Mode	Multiple CLIs orchestrated via orchestrate.sh
🔴	Codex CLI	OpenAI Codex (your OPENAI_API_KEY)
🧭	Antigravity CLI	Google Antigravity (your authenticated seat)
🔵	Claude Subagent	Claude Code Task tool (built-in)

What Triggers External CLIs vs Subagents

External CLIs execute when:

Using /parallel-agents command explicitly
Using /octo:debate command (AI Debate Hub)
Running orchestrate.sh workflows (probe, grasp, tangle, ink, embrace, grapple, squeeze)
Knowledge mode deliberation (when Knowledge Mode is ON)
Natural language that triggers this skill (research, build, review tasks)

Claude Subagents execute when:

Simple file operations (read, write, edit)
Git commands and bash operations
Code reading and navigation
Tasks that don't need multiple perspectives
Built-in Claude Code capabilities are sufficient

Why this matters: External CLIs use your OpenAI/Google API quotas and incur costs. Claude subagents are included with Claude Code at no additional charge.

When you see 🐙 CLAUDE OCTOPUS ACTIVATED, external CLI providers such as Codex, Antigravity, and others will be invoked for multi-perspective analysis.

Force Multi-Provider Mode

Sometimes you want multi-provider analysis even for simple tasks that wouldn't normally trigger workflows. This is useful when you need comprehensive perspectives on decisions, want to compare how different models think, or when automatic routing underestimates task complexity.

Explicit Command

Force multi-provider execution using the /octo:multi command:

/octo:multi "Explain how Redis works"
/octo:multi "What is OAuth?"
/octo:multi "Review this simple function"
/octo:multi "Should we use TypeScript?"

Natural Language Triggers

You can also force multi-provider mode with natural language:

"Run this with all providers: What is JWT?"
"I want multiple AI models to look at our architecture"
"Get multiple perspectives on this design decision"
"Use all providers for explaining caching strategies"
"Force multi-provider analysis of our API design"

When to Force Parallel Mode

Use forced parallel mode when:

High-stakes decisions require comprehensive analysis from multiple models
Comparing perspectives - you want to see how different models approach the same problem
Simple questions with depth - seemingly simple questions that deserve thorough multi-model analysis
Learning different approaches - exploring how each model thinks about a topic
Automatic routing underestimates complexity - task appears simple but has nuance

Don't force parallel mode when:

Task already auto-triggers workflows (octo research, octo build, octo review)
Simple factual questions Claude can answer reliably
Cost efficiency is important (see cost awareness below)
File operations or code navigation (use built-in tools)

Cost Awareness

Forcing parallel mode uses external CLIs for every task, which incurs API costs:

Provider	Cost per Query	What It Uses
🔴 Codex CLI	~$0.01-0.05	Your OPENAI_API_KEY
🧭 Antigravity CLI	Included with access/subscription	Antigravity CLI auth
🔵 Claude	Included	Claude Code subscription

Total cost per forced query: ~$0.02-0.08

Use forced parallel mode judiciously for tasks where multiple perspectives genuinely add value. For routine work, let automatic routing decide when multi-provider analysis is beneficial.

Visual Indicator

When you force parallel mode, you'll see this banner:

🐙 **CLAUDE OCTOPUS ACTIVATED** - Multi-provider mode
Force parallel execution

Providers:
🔴 Codex CLI - [Role in this task]
🧭 Antigravity CLI - [Role in this task]
🔵 Claude - [Role in this task]

Followed by results from each provider marked with their indicators (for example 🔴 🟡 🧭 🔵).

Prerequisites check

Once this skill activates, run the local provider check:

OCTO_ROOT="${CLAUDE_PLUGIN_ROOT:-${HOME}/.claude-octopus/plugin}"
"$OCTO_ROOT/scripts/orchestrate.sh" detect-providers

This check reads local commands, credentials, and the one-hour cache. It does not call provider APIs. Current output includes the Claude Code version contract and one status per provider:

Detecting Claude Code version...

CLAUDE_CODE_VERSION=2.1.219
CLAUDE_CODE_STATUS=ok
CLAUDE_CODE_MINIMUM=2.1.14

CODEX_STATUS=ok
AGY_STATUS=unauthenticated

Provider values are ok, unauthenticated, quota, not-installed, or a specific reason such as model-invalid.

Route based on the result

If Claude Code is outdated, stop and show the version and update instructions reported by the command:

CLAUDE_CODE_VERSION=2.1.13
CLAUDE_CODE_STATUS=outdated
CLAUDE_CODE_MINIMUM=2.1.14

If one non-Claude provider reports ok, use it. Parallel execution needs at least one ready non-Claude provider, but ordinary Claude-only commands still work without one. If none reports ok, stop the parallel workflow, direct the user to /octo:setup, and do not simulate provider agreement by running one provider repeatedly. One ready provider can supply an additional perspective, but it is not multi-provider consensus.

The command writes ~/.claude-octopus/.provider-cache. Reuse it for up to one hour; after that, run detection again.

Double Diamond Workflow

Phase 1: PROBE (Discover)

Diverge then converge on understanding

Parallel research from 4 perspectives:

Problem space analysis (constraints, requirements, needs)
Existing solutions research (what worked, what failed)
Edge cases exploration (potential challenges)
Technical feasibility (prerequisites, dependencies)

${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh probe "What are the best approaches for real-time notifications?"

Phase 2: GRASP (Define)

Build consensus on the problem

Multi-tentacled problem definition:

Core problem statement
Success criteria
Constraints and boundaries

${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grasp "Define requirements for notification system" --context probe-synthesis-*.md

Phase 3: TANGLE (Develop)

Diverge with multiple solutions

Enhanced map-reduce with validation:

Task decomposition via LLM
Parallel execution across agents
Quality gate (75% success threshold)

${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh tangle "Implement notification service" --context grasp-consensus-*.md

Phase 4: INK (Deliver)

Converge to validated delivery

Pre-delivery validation:

Quality gate verification
Result synthesis
Final deliverable generation

${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh ink "Deliver notification system" --context tangle-validation-*.md

Full Workflow: EMBRACE

Run all 4 phases sequentially with automatic context passing:

${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh embrace "Create a complete user dashboard feature"

Crossfire: Adversarial Cross-Model Review

Different models have different blind spots. Crossfire commands force models to critique each other's work, catching more issues than single-model review.

GRAPPLE - Adversarial Debate

Two tentacles wrestling until consensus

Available providers each propose solutions, then critique each other's work. A synthesis determines the winner.

┌─────────────┐     ┌─────────────┐
│   Codex     │     │ Antigravity │
│ (Proposer)  │     │ (Proposer)  │
└──────┬──────┘     └──────┬──────┘
       │                   │
       ▼                   ▼
┌─────────────┐     ┌─────────────┐
│ PROPOSAL A  │ ←─→ │ PROPOSAL B  │
└──────┬──────┘     └──────┬──────┘
       │                   │
       ▼                   ▼
┌─────────────┐     ┌─────────────┐
│ Antigravity │     │   Codex     │
│ (Critic)    │     │  (Critic)   │
└──────┬──────┘     └──────┬──────┘
       │                   │
       └─────────┬─────────┘
                 ▼
       ┌─────────────────┐
       │   SYNTHESIS     │
       │ (Winner + Fix)  │
       └─────────────────┘

# Basic grapple
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grapple "implement password reset API"

# Grapple with security principles
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grapple --principles security "implement JWT authentication"

# Grapple with performance principles
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grapple --principles performance "optimize database queries"

SQUEEZE - Red Team Security Review

Octopus squeezes prey to test for weaknesses

Blue Team (Codex) implements secure code. Red Team (Antigravity) attacks to find vulnerabilities. Then remediation and validation.

Phase 1: Blue Team implements secure solution
Phase 2: Red Team finds vulnerabilities
Phase 3: Remediation fixes all issues
Phase 4: Validation verifies all fixed

${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh squeeze "implement user login form"
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh squeeze "review auth.ts for vulnerabilities"

Constitutional Principles

Grapple supports domain-specific critique principles:

Principle	Focus	Use Case
`general`	Overall quality	Default for most reviews
`security`	OWASP Top 10, secure coding	Auth, payments, user data
`performance`	N+1 queries, caching, async	Database, API optimization
`maintainability`	Clean code, testability	Refactoring, code reviews

${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grapple --principles security "implement password reset"
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grapple --principles performance "optimize search API"
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grapple --principles maintainability "refactor user service"

Smart Auto-Routing

The auto command detects intent keywords and routes to the appropriate workflow:

Keywords	Routes To	Phases
research, explore, investigate, analyze	`probe`	Discover
develop, dev, build, implement, create	`tangle` + `ink`	Develop + Deliver
qa, test, review, validate, check	`ink`	Deliver (quality focus)
security audit, red team, pentest	`squeeze`	Red Team
adversarial, cross-model, debate	`grapple`	Debate
(other coding keywords)	`codex` agent	Single agent
(other design keywords)	`agy` agent	Single agent

Examples:

${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "research best practices for caching"     # -> probe
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "build the caching layer"                 # -> tangle + ink
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "review the cache implementation"         # -> ink
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "security audit the auth module"          # -> squeeze
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "have both models debate the API design"  # -> grapple
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "fix the cache invalidation bug"          # -> codex

Quality Gates

The tangle phase enforces quality gates:

Score	Status	Behavior
>= 90%	PASSED	Proceed to ink
75-89%	WARNING	Proceed with caution
< 75%	FAILED	Ink phase flags for review

Command Reference

Double Diamond Commands

Command	Phase	Description
`probe <prompt>`	Discover	Parallel research with AI synthesis
`grasp <prompt>`	Define	Consensus building on problem definition
`tangle <prompt>`	Develop	Enhanced map-reduce with quality gates
`ink <prompt>`	Deliver	Validation and final delivery
`embrace <prompt>`	All 4	Full Double Diamond workflow
`preflight`	-	Validate all dependencies

Crossfire Commands (Adversarial Review)

Command	Description
`grapple <prompt>`	Codex vs Antigravity debate until consensus
`grapple --principles TYPE <prompt>`	Debate with domain principles (security, performance, maintainability)
`squeeze <prompt>`	Red Team security review (Blue Team vs Red Team)

Classic Orchestration Commands

Command	Description
`init`	Initialize workspace
`spawn <agent> <prompt>`	Spawn single agent
`auto <prompt>`	Smart routing (Double Diamond or agent)
`fan-out <prompt>`	Send to multiple agents
`map-reduce <prompt>`	Decompose and parallelize
`parallel [tasks.json]`	Execute task file
`status`	Show running agents
`kill [id\|all]`	Terminate agents
`clean`	Reset workspace
`aggregate [filter]`	Combine results

Options

Option	Default	Description
`-p, --parallel`	3	Max concurrent agents
`-t, --timeout`	300	Timeout per task (seconds)
`-v, --verbose`	false	Verbose logging
`-n, --dry-run`	false	Show without executing
`--context <file>`	-	Context from previous phase

Agent Selection (Premium Defaults)

Agent	Model	Best For
`codex`	gpt-5.6-sol	Frontier implementation and independent review
`codex-standard`	gpt-5.6-terra	Balanced implementation and review
`codex-mini`	gpt-5.6-luna	Quick fixes, simple tasks
`agy`	service-selected default	Deep analysis and external review
`agy-research`	service-selected default	Research-focused Antigravity seat
`codex-review`	gpt-5.6-sol	Code review mode
`openrouter`	Various	Universal fallback (400+ models)
`orcarouter`	Various	Universal fallback via OrcaRouter gateway

Provider-Aware Routing (v4.8)

Claude Octopus now intelligently routes tasks based on your subscription tiers and costs.

Provider Subscription Tiers

Provider	Tiers	Monthly Cost	Capabilities
Codex/OpenAI	Free, Plus, Pro, API	$0-200	code, chat, review
Antigravity	Google access/subscription	Included with access	code, analysis, external review
Claude	Pro, Max 5x, Max 20x, API	$20-200	code, chat, analysis, long-context
OpenRouter	Pay-per-use	Variable	400+ models, routing variants
OrcaRouter	Pay-per-use	Variable	Single gateway, namespaced model IDs

Cost Optimization Strategies

Strategy	Description
`balanced` (default)	Smart mix of cost and quality
`cost-first`	Prefer cheapest capable provider
`quality-first`	Prefer highest-tier provider

Example: If your Google seat includes Antigravity access, the system can prefer AGY for analysis without invoking the retired Gemini CLI.

Routing CLI Flags

# Force a specific provider
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh --provider agy auto "analyze code structure"

# Prefer cheapest option
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh --cost-first auto "research best practices"

# Prefer highest quality
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh --quality-first auto "complex refactoring task"

# OpenRouter routing variants
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh --openrouter-nitro auto "quick task"  # Fastest
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh --openrouter-floor auto "bulk task"   # Cheapest

Configuration

Provider tiers are configured during setup or via the providers config file:

# Run setup wizard (includes provider tier steps)
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh setup

# View current provider status
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh status

Configuration file: ~/.claude-octopus/.providers-config

version: "2.0"
providers:
  codex:
    installed: true
    auth_method: "oauth"
    subscription_tier: "plus"    # free|plus|pro|api-only
    cost_tier: "low"             # free|low|medium|high|bundled|pay-per-use

  agy:
    installed: true
    auth_method: "oauth"
    subscription_tier: "google"     # service-managed Google access
    cost_tier: "bundled"

  openrouter:
    enabled: false
    routing_preference: "default"   # default|nitro|floor

  orcarouter:
    enabled: false

cost_optimization:
  strategy: "balanced"  # cost-first|quality-first|balanced

OpenRouter Fallback

OpenRouter provides 400+ models as a universal fallback when direct external CLIs are unavailable:

# Set up OpenRouter API key
export OPENROUTER_API_KEY="sk-or-..."

# Re-run setup to configure
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh setup

OrcaRouter Fallback

OrcaRouter provides a single gateway to many models as a universal fallback when direct external CLIs are unavailable:

# Set up OrcaRouter API key
export ORCAROUTER_API_KEY="sk-orca-..."

# Re-run setup to configure
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh setup

Workspace Structure

~/.claude-octopus/
├── results/
│   ├── probe-synthesis-*.md      # Research findings
│   ├── grasp-consensus-*.md      # Problem definitions
│   ├── tangle-validation-*.md    # Quality gate reports
│   └── delivery-*.md             # Final deliverables
├── logs/                         # Execution logs
├── plans/                        # Execution plan history
└── .gitignore

Example Workflows

Research-First Development

# 1. Explore the problem space
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh probe "Authentication patterns for microservices"

# 2. Define the approach (with probe context)
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grasp "OAuth2 with JWT for our API" \
  --context ~/.claude-octopus/results/probe-synthesis-*.md

# 3. Implement with validation
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh tangle "Implement OAuth2 authentication"

# 4. Deliver with quality checks
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh ink "Finalize auth implementation"

Quick Build (Auto-Routed)

# Auto-detects "build" intent -> runs tangle + ink
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "build a rate limiting middleware"

Full Feature Development

# All 4 phases in one command
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh embrace "Create a user notification system with email and push support"

Best Practices

Start with embrace for new features requiring exploration
Use probe alone when researching before committing to an approach
Use auto for smart routing based on your intent
Chain phases with --context for incremental workflows
Run preflight before long workflows to verify dependencies
Review quality gates in tangle output before proceeding to ink

Troubleshooting

Pre-flight check fails

${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh preflight
# Verify: codex CLI, agy CLI, and task-relevant provider credentials

Quality gate failures

Tangle phase requires 75% success rate. If failing:

Break task into smaller subtasks
Increase timeout with -t 600
Check individual agent logs in ~/.claude-octopus/logs/

Reset workspace

${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh clean
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh init

Repository: nyldn/claude-octopus
Path: .claude/skills/skill-parallel-agents/SKILL.md
Commit: 805d58c

Last updated: 1 day ago
First committed: 3 months ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.