skill-parallel-agents

> **Host: Codex CLI** — This skill was designed for Claude Code and adapted for Codex. > Cross-reference commands use installed skill names in Codex rather than `/octo:*` slash commands. > Use the active Codex shell and subagent tools. Do not claim a provider, model, or host subagent is available until the current session exposes it. > For host tool equivalents, see `skills/blocks/codex-host-adapter.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. ```bash # 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:** 1. **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:*` 2. **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 3. **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 host subagent 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: ```bash 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: ```text 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: ```text 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) ```bash ${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 ```bash ${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) ```bash ${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 ```bash ${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: ```bash ${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) │ └─────────────────┘ ``` ```bash # 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 ``` ```bash ${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 | ```bash ${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:** ```bash ${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