From octo
Implements features using multi-AI workflow with Codex and Gemini CLIs in Double Diamond Develop phase. Auto-activates on 'build X', 'implement Y', 'create Z', or 'develop feature' requests.
npx claudepluginhub nyldn/claude-octopus --plugin octoThis skill uses the workspace's default tool permissions.
> This file is generated from a template. Edit the `.tmpl` file, not this file directly.
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
This file is generated from a template. Edit the
.tmplfile, not this file directly. Runscripts/gen-skill-docs.shto regenerate after changes.
Before starting development:
.octo/STATE.md to verify Define phase complete# Verify Define phase is complete
if [[ -f ".octo/STATE.md" ]]; then
define_status=$("${HOME}/.claude-octopus/plugin/scripts/octo-state.sh" get_phase_status 2)
if [[ "$define_status" != "complete" ]]; then
echo "⚠️ Warning: Define phase not marked complete. Consider running definition first."
fi
fi
# Update state for Development phase
"${HOME}/.claude-octopus/plugin/scripts/octo-state.sh" update_state \
--phase 3 \
--position "Development" \
--status "in_progress"
This skill uses ENFORCED execution mode. You MUST follow this exact sequence.
Analyze the user's prompt and project to determine context:
Knowledge Context Indicators:
Dev Context Indicators:
Also check: Does project have package.json, Cargo.toml, etc.? (suggests Dev Context)
Capture context_type = "Dev" or "Knowledge"
When context_type is Dev, determine the subtype to inject domain-appropriate quality guidance into the prompt sent to providers. Append the matching supplement text after the user's prompt.
| Subtype | Trigger keywords | Quality supplement |
|---|---|---|
frontend-ui | "page", "widget", "component", "UI", "HTML", "CSS", "form", "dashboard", "layout" | See frontend-ui enrichment below. |
cli-tool | "CLI", "command-line", "terminal", "script", "flag", "argument" | Help text via --help flag. Meaningful exit codes (0 success, 1 user error, 2 system error). Stdin/stdout/stderr used correctly. Argument validation with clear error messages. |
api-service | "API", "endpoint", "REST", "GraphQL", "gRPC", "server", "route" | Input validation at boundaries. Consistent error response format. Auth/authz on every endpoint. Rate limiting consideration. OpenAPI/schema documentation. |
infra | "deploy", "terraform", "docker", "CI", "pipeline", "Kubernetes", "helm" | Idempotent operations. Secrets never hardcoded. Rollback path documented. Health checks included. |
data | "ETL", "pipeline", "migration", "schema", "database", "SQL" | Idempotent migrations. Backup/rollback strategy. Data validation at ingestion. |
general | Default if no subtype matches | No supplement — use base implementer persona only. |
When frontend-ui subtype is detected, do TWO things:
A. Inject quality supplement into the prompt: Self-contained files preferred. Accessibility: ARIA labels, keyboard nav, 44px touch targets (WCAG 2.5.5). Safe DOM: createElement over innerHTML. Progressive enhancement: feature-detect APIs (navigator.share, localStorage) with fallbacks. Persist user prefs via localStorage.
B. Pull design intelligence from BM25 (if available):
Before calling orchestrate.sh, check if the design intelligence engine exists and query it for relevant design context:
SEARCH_PY="${HOME}/.claude-octopus/plugin/vendors/ui-ux-pro-max-skill/src/ui-ux-pro-max/scripts/search.py"
if [[ -f "$SEARCH_PY" ]]; then
# Detect relevant domains from the prompt
design_context=""
# Style query — what visual style fits this task?
style_hit=$(python3 "$SEARCH_PY" "<user's task description>" --domain style --top 1 2>/dev/null || true)
[[ -n "$style_hit" ]] && design_context+="Design style suggestion: $style_hit\n"
# UX query — relevant UX patterns
ux_hit=$(python3 "$SEARCH_PY" "<user's task description>" --domain ux --top 1 2>/dev/null || true)
[[ -n "$ux_hit" ]] && design_context+="UX pattern: $ux_hit\n"
# Append to prompt if hits found
if [[ -n "$design_context" ]]; then
# Append design intelligence to the orchestrate.sh prompt
prompt="${prompt}\n\nDesign intelligence (from BM25 search):\n${design_context}"
fi
fi
This gives providers concrete design guidance (style direction, UX patterns) without requiring the user to run /octo:design-ui-ux separately. If the search engine isn't installed, implementation proceeds with the quality supplement only.
How to apply: When calling orchestrate.sh in Step 4, append the quality supplement (and design intelligence if available) to the prompt:
orchestrate.sh develop "<user prompt>\n\nQuality requirements for this deliverable:\n<supplement text>\n<design intelligence if found>"
DO NOT PROCEED TO STEP 2 until context determined. Context type (Dev vs Knowledge) and dev subtype determine which quality supplements and design intelligence to inject — wrong context wastes provider credits on irrelevant analysis.
MANDATORY: Run the centralized provider check BEFORE displaying the banner:
bash "${HOME}/.claude-octopus/plugin/scripts/helpers/check-providers.sh"
Use the ACTUAL results. PROHIBITED: Showing only "🔵 Claude: Available ✓" without listing all providers.
Validation:
/octo:setupDisplay this banner BEFORE orchestrate.sh execution (list ALL providers from check output):
For Dev Context:
🐙 **CLAUDE OCTOPUS ACTIVATED** - Multi-provider implementation mode
🛠️ [Dev] Develop Phase: [Brief description of what you're building]
Provider Availability:
🔴 Codex CLI: [status from check] - Code generation and patterns
🟡 Gemini CLI: [status from check] - Alternative approaches
🟢 Copilot CLI: [status from check] - GitHub integration
🟣 Qwen CLI: [status from check] - Additional perspective
🟤 OpenCode CLI: [status from check] - Multi-provider routing
🔵 Claude: Available ✓ - Integration and quality gates
💰 Estimated Cost: $0.02-0.10
⏱️ Estimated Time: 3-7 minutes
For Knowledge Context:
🐙 **CLAUDE OCTOPUS ACTIVATED** - Multi-provider implementation mode
🛠️ [Knowledge] Develop Phase: [Brief description of deliverable]
Provider Availability:
🔴 Codex CLI: ${codex_status} - Structure and framework application
🟡 Gemini CLI: ${gemini_status} - Content and narrative development
🔵 Claude: Available ✓ - Integration and quality review
💰 Estimated Cost: $0.02-0.10
⏱️ Estimated Time: 3-7 minutes
DO NOT PROCEED TO STEP 3 until banner displayed. The banner shows users which providers will run and what costs they'll incur — starting API calls without this visibility violates cost transparency.
Before executing the workflow, read any prior context:
# Initialize state if needed
"${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" init_state
# Set current workflow
"${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" set_current_workflow "flow-develop" "develop"
# Get prior decisions (critical for implementation)
prior_decisions=$("${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" get_decisions "all")
# Get context from discover and define phases
discover_context=$("${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" get_context "discover")
define_context=$("${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" get_context "define")
# Display what you found (if any)
if [[ "$discover_context" != "null" ]]; then
echo "📋 Discovery phase findings:"
echo " $discover_context"
fi
if [[ "$define_context" != "null" ]]; then
echo "📋 Definition phase scope:"
echo " $define_context"
fi
if [[ "$prior_decisions" != "[]" && "$prior_decisions" != "null" ]]; then
echo "📋 Implementing with decisions:"
echo "$prior_decisions" | jq -r '.[] | " - \(.decision) (\(.phase)): \(.rationale)"'
fi
This provides critical context for implementation:
search, timeline, get_observations) are available — use them to check for related past implementation patternsDO NOT PROCEED TO STEP 4 until state read.
You MUST execute this command via the Bash tool:
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh develop "<user's implementation request>"
CRITICAL: You are PROHIBITED from:
You MUST use the Bash tool to invoke orchestrate.sh.
If running in Claude Code v2.1.16+, users will see real-time progress indicators in the task spinner:
Phase 1 - External Provider Execution (Parallel):
Phase 2 - Synthesis (Sequential):
These spinner verb updates happen automatically - orchestrate.sh calls update_task_progress() before each agent execution. Users see exactly which provider is working and what it's doing.
If NOT running in Claude Code v2.1.16+: Progress indicators are silently skipped, no errors shown.
After orchestrate.sh completes, verify it succeeded:
# Find the latest synthesis file (created within last 10 minutes)
SYNTHESIS_FILE=$(find ~/.claude-octopus/results -name "tangle-synthesis-*.md" -mmin -10 2>/dev/null | head -n1)
if [[ -z "$SYNTHESIS_FILE" ]]; then
echo "❌ VALIDATION FAILED: No synthesis file found"
echo "orchestrate.sh did not execute properly"
exit 1
fi
echo "✅ VALIDATION PASSED: $SYNTHESIS_FILE"
cat "$SYNTHESIS_FILE"
If validation fails:
~/.claude-octopus/logs/After synthesis is verified, record implementation details in state:
# Extract key implementation decisions from synthesis
implementation_approach=$(head -50 "$SYNTHESIS_FILE" | grep -A 3 "## Implementation\|## Approach" | tail -3 | tr '\n' ' ')
# Record implementation decisions
decision_made=$(echo "$implementation_approach" | grep -o "implemented\|using [A-Za-z0-9 ]*\|chose to\|pattern:" | head -1)
if [[ -n "$decision_made" ]]; then
"${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" write_decision \
"develop" \
"$decision_made" \
"Multi-AI implementation consensus"
fi
# Update develop phase context
"${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" update_context \
"develop" \
"$implementation_approach"
# Update metrics
"${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" update_metrics "phases_completed" "1"
# Track actual providers used (dynamic — not hardcoded)
for _provider in $(bash "${HOME}/.claude-octopus/plugin/scripts/helpers/check-providers.sh" | grep ":available" | cut -d: -f1) claude; do
"${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" update_metrics "provider" "$_provider"
done
DO NOT PROCEED TO STEP 7 until state updated.
Read the synthesis file and present:
After user confirms, STEP 6: Implement the solution using Write/Edit tools
Include attribution:
---
*Multi-AI Implementation powered by Claude Octopus*
*Providers: 🔴 Codex | 🟡 Gemini | 🔵 Claude*
*Full implementation plan: $SYNTHESIS_FILE*
BEFORE executing ANY workflow actions, you MUST:
Analyze the user's prompt and project to determine context:
Knowledge Context Indicators (in prompt):
Dev Context Indicators (in prompt):
Also check: Does the project have package.json, Cargo.toml, etc.? (suggests Dev Context)
Step 1b: Detect Dev Subtype — see EXECUTION CONTRACT Step 1b above for subtype table and quality supplements. Append the matching supplement to the prompt before calling orchestrate.sh.
For Dev Context:
🐙 **CLAUDE OCTOPUS ACTIVATED** - Multi-provider implementation mode
🛠️ [Dev] Develop Phase: [Brief description of what you're building]
📋 Session: ${CLAUDE_SESSION_ID}
Providers:
🔴 Codex CLI - Code generation and patterns
🟡 Gemini CLI - Alternative approaches
🔵 Claude - Integration and quality gates
For Knowledge Context:
🐙 **CLAUDE OCTOPUS ACTIVATED** - Multi-provider implementation mode
🛠️ [Knowledge] Develop Phase: [Brief description of deliverable]
📋 Session: ${CLAUDE_SESSION_ID}
Providers:
🔴 Codex CLI - Structure and framework application
🟡 Gemini CLI - Content and narrative development
🔵 Claude - Integration and quality review
| Indicator | Provider | Cost Source |
|---|---|---|
| 🔴 | Codex CLI | User's OPENAI_API_KEY |
| 🟡 | Gemini CLI | User's GEMINI_API_KEY |
| 🟣 | Perplexity Sonar | User's PERPLEXITY_API_KEY |
| 🔵 | Claude | Included with Claude Code |
This is NOT optional. Users need to see which AI providers are active and understand they are being charged for external API calls (🔴 🟡).
Part of Double Diamond: DEVELOP (divergent thinking)
DEVELOP (tangle)
\ /
\ * /
\ * * /
\ /
\ /
Diverge with
solutions
The develop phase generates multiple implementation approaches using external CLI providers:
This is the divergent phase for solutions - we explore different implementation paths before converging on the best approach.
Use develop when you need:
Don't use develop for:
Before execution, you'll see:
🐙 **CLAUDE OCTOPUS ACTIVATED** - Multi-provider implementation
🛠️ Develop Phase: Building and developing solutions
Providers:
🔴 Codex CLI - Code generation and patterns
🟡 Gemini CLI - Alternative approaches
🔵 Claude - Integration and refinement
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh develop "<user's implementation request>"
The orchestrate.sh script will:
The tangle phase includes automatic quality validation:
When orchestrate.sh output contains AGENT_TEAMS_RESUME:${agent_id}:${task_id}:${role}:${phase}:
SendMessage({to: "${agent_id}", message: "<iteration prompt>"}) — this auto-resumes a stopped agent automatically (CC v2.1.77+)~/.claude-octopus/agent-teams/${task_id}.jsonbridge_store_agent_id(task_id, agent_id) in the bridge ledgerNote: The Agent(resume: ...) parameter was removed in CC v2.1.77. Always use SendMessage for agent continuation.
Results are saved to:
~/.claude-octopus/results/${SESSION_ID}/tangle-synthesis-<timestamp>.md
After reviewing all perspectives, implement the final solution using Write/Edit tools.
When this skill is invoked, follow the EXECUTION CONTRACT above exactly. The contract includes:
Each step is mandatory and blocking - you cannot proceed to the next step until the current one completes successfully.
Create tasks to track execution progress:
// At start of skill execution
TaskCreate({
subject: "Execute develop workflow with multi-AI providers",
description: "Run orchestrate.sh develop for implementation",
activeForm: "Running multi-AI develop workflow"
})
// Mark in_progress when calling orchestrate.sh
TaskUpdate({taskId: "...", status: "in_progress"})
// Mark completed ONLY after implementation finished
TaskUpdate({taskId: "...", status: "completed"})
If any step fails:
/octo:setup and STOPNever fall back to direct implementation if orchestrate.sh execution fails. Report the failure and let the user decide how to proceed.
After successful execution, present implementation plan with:
# Implementation Plan: <task>
## Recommended Approach
[Your strategic recommendation based on all perspectives]
## Implementation Steps
1. [Step-by-step implementation plan]
2. ...
## Code Overview
### Codex Approach
[Key implementation details from Codex]
### Gemini Approach
[Alternative considerations from Gemini]
### Final Implementation
[Your integrated solution]
## Quality Gates
- [ ] Security validation: PASSED/FAILED
- [ ] Best practices: PASSED/FAILED
- [ ] Code quality: PASSED/FAILED
Would you like me to proceed with implementation?
User: Build a user authentication system with JWT
Claude:
🐙 **CLAUDE OCTOPUS ACTIVATED** - Multi-provider implementation mode
🛠️ Develop Phase: Building authentication system
[Executes: ${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh develop "Build a user authentication system with JWT"]
[After completion, reads synthesis and presents:]
# Implementation Plan: User Authentication System
## Recommended Approach
Based on multi-provider analysis, I recommend a layered approach:
1. Auth middleware for JWT validation
2. Login/register endpoints
3. Token refresh mechanism
4. Secure password hashing (bcrypt)
## Implementation Steps
1. Create `src/auth/middleware.ts` - JWT validation middleware
2. Create `src/auth/controller.ts` - Login/register endpoints
3. Create `src/auth/service.ts` - Business logic
4. Create `src/auth/utils.ts` - Token generation/validation
5. Update `src/routes.ts` - Register auth routes
## Code Overview
### Codex Approach
- Modern TypeScript with strict types
- Express middleware pattern
- Redis for token blacklisting
- Comprehensive error handling
### Gemini Approach
- Passport.js integration suggestion
- Rate limiting on auth endpoints
- Multi-factor auth consideration
- Session management alternatives
### Final Implementation
- Hybrid: Modern TypeScript + Express patterns
- JWT with refresh tokens
- bcrypt password hashing
- Rate limiting included
- Optional MFA hooks for future
## Quality Gates
- ✅ Security validation: PASSED (bcrypt, secure tokens)
- ✅ Best practices: PASSED (TypeScript, error handling)
- ⚠️ Code quality: WARNING (consider adding request validation)
Would you like me to proceed with implementation?
[User: Yes, proceed]
[Claude creates files and implements the solution]
User: Create an API endpoint for fetching user notifications
Claude:
🐙 **CLAUDE OCTOPUS ACTIVATED** - Multi-provider implementation mode
🛠️ Develop Phase: Creating API endpoint
[Executes tangle workflow]
[Presents implementation plan with multi-provider perspectives]
[Implements the endpoint after user confirmation]
The tangle phase automatically runs quality checks via .claude/hooks/quality-gate.sh:
# Triggered after tangle execution (PostToolUse hook)
./hooks/quality-gate.sh
Quality Dimensions:
| Dimension | Weight | Criteria |
|---|---|---|
| Code Quality | 25% | Complexity, maintainability, documentation |
| Security | 35% | OWASP compliance, auth, input validation |
| Best Practices | 20% | Error handling, logging, testing |
| Completeness | 20% | Feature completeness, edge cases |
Scoring Thresholds:
Tangle is the third phase of the Double Diamond:
PROBE (Discover) → GRASP (Define) → TANGLE (Develop) → INK (Deliver)
After tangle completes, you may continue to:
Or use standalone for implementation tasks.
Before writing code, ensure:
When the develop phase runs iteratively (user requests multiple rounds of implementation, or the implementation requires fix-and-retry cycles), apply the self-regulation rules from skill-iterative-loop:
~/.claude-octopus/loop-config.conf, use those instead.Iteration N | Self-regulation: X% (reasons)This prevents develop workflows from spinning without progress when orchestrate.sh results require iterative refinement.
After implementation completes and before presenting results to the user, you MUST launch two verification agents in parallel. Do NOT skip this step or ask the user whether to run it — it is automatic.
Agent 1 — Code Review (Sonnet):
Agent(
model: "sonnet",
subagent_type: "feature-dev:code-reviewer",
run_in_background: true,
description: "Code review: post-develop",
prompt: "Review the code changes from this development session. Focus on:
1. Bugs, logic errors, security vulnerabilities
2. Hidden dependencies or coupling issues
3. Whether error handling covers failure modes
4. Adherence to project conventions (check CLAUDE.md)
Check git diff for the changed files. Report only high-confidence issues."
)
Agent 2 — E2E Verification (Sonnet):
Agent(
model: "sonnet",
run_in_background: true,
description: "E2E test: post-develop",
prompt: "Run end-to-end verification of the development changes:
1. Run the project's test suite (detect from package.json scripts, Makefile, or pyproject.toml)
2. Verify no regressions in existing tests
3. Check that new files are properly integrated (imported, registered, sourced)
4. Verify the implementation matches the original task requirements
Report: tests passed/failed, any integration issues found."
)
After both agents complete:
WHY: The user should never have to manually request a code review after development work. Fresh-eyes review from a different model (Sonnet vs Opus) catches issues the implementer is blind to. Running tests automatically catches regressions before the user discovers them.
After writing code, ensure:
External API Usage:
Tangle workflows typically cost $0.02-0.10 per task depending on complexity and code length.
After development completes:
.octo/STATE.md with completiongit tag octo-checkpoint-post-develop-$(date +%Y%m%d-%H%M%S)# Update state after Development completion
"${HOME}/.claude-octopus/plugin/scripts/octo-state.sh" update_state \
--status "complete" \
--history "Develop phase completed"
# Create git checkpoint tag
checkpoint_tag="octo-checkpoint-post-develop-$(date +%Y%m%d-%H%M%S)"
git tag "$checkpoint_tag" -m "Post-develop checkpoint from embrace workflow"
echo "📌 Created checkpoint: $checkpoint_tag"
# Record files modified in this phase
modified_files=$(git diff --name-only HEAD~1 2>/dev/null || echo "See git log")
"${HOME}/.claude-octopus/plugin/scripts/octo-state.sh" update_state \
--history "Files modified: $modified_files"
Ready to build! This skill activates automatically when users request implementation or building features.