From octo
Scopes project requirements with multi-AI CLIs (Codex, Gemini, Copilot, Qwen, Claude) during Double Diamond Define phase. Auto-activates on 'define requirements for X' or 'clarify scope of Y' 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 definition:
.octo/STATE.md to verify Discover phase complete# Verify Discover phase is complete
if [[ -f ".octo/STATE.md" ]]; then
discover_status=$("${HOME}/.claude-octopus/plugin/scripts/octo-state.sh" get_phase_status 1)
if [[ "$discover_status" != "complete" ]]; then
echo "⚠️ Warning: Discover phase not marked complete. Consider running discovery first."
fi
fi
# Update state for Definition phase
"${HOME}/.claude-octopus/plugin/scripts/octo-state.sh" update_state \
--phase 2 \
--position "Definition" \
--status "in_progress"
This skill uses ENFORCED execution mode. You MUST follow this exact sequence.
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):
🐙 **CLAUDE OCTOPUS ACTIVATED** - Multi-provider definition mode
🎯 Define Phase: [Brief description of what you're defining/scoping]
Provider Availability:
🔴 Codex CLI: [status from check] - Technical requirements analysis
🟡 Gemini CLI: [status from check] - Business context and constraints
🟢 Copilot CLI: [status from check] - GitHub integration perspective
🟣 Qwen CLI: [status from check] - Alternative analysis
🟤 OpenCode CLI: [status from check] - Multi-provider routing
🔵 Claude: Available ✓ - Consensus building and synthesis
💰 Estimated Cost: $0.01-0.05
⏱️ Estimated Time: 2-5 minutes
DO NOT PROCEED TO STEP 2 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-define" "define"
# Get prior decisions (if any)
prior_decisions=$("${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" get_decisions "all")
# Get context from discover phase
discover_context=$("${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" get_context "discover")
# Display what you found (if any)
if [[ "$discover_context" != "null" ]]; then
echo "📋 Building on discovery findings:"
echo " $discover_context"
fi
if [[ "$prior_decisions" != "[]" && "$prior_decisions" != "null" ]]; then
echo "📋 Respecting prior decisions:"
echo "$prior_decisions" | jq -r '.[] | " - \(.decision) (\(.phase)): \(.rationale)"'
fi
This provides context from:
search, timeline, get_observations) are available — use them to find past decisions on similar topicsDO NOT PROCEED TO STEP 3 until state read.
Before executing expensive multi-AI orchestration, capture the user's vision to scope the work effectively.
Ask clarifying questions using AskUserQuestion:
Use AskUserQuestion tool to ask:
1. **User Experience**
Question: "How should users interact with this feature?"
Header: "User Flow"
Options:
- label: "API-first (programmatic access)"
description: "Build API endpoints first, UI later"
- label: "UI-first (user-facing interface)"
description: "Build user interface first, API supports it"
- label: "Both simultaneously"
description: "Develop API and UI in parallel"
- label: "Not applicable"
description: "This feature doesn't have a user interaction"
2. **Implementation Approach**
Question: "What technical approach do you prefer?"
Header: "Approach"
Options:
- label: "Fastest to market"
description: "Prioritize speed, use existing libraries"
- label: "Most maintainable"
description: "Focus on clean architecture, may take longer"
- label: "Best performance"
description: "Optimize for speed and efficiency"
- label: "Multi-LLM debate (Claude + Codex + Gemini)"
description: "Three AI models debate the best approach — uses external API credits"
3. **Scope Boundaries**
Question: "What's explicitly OUT of scope for this phase?"
Header: "Out of Scope"
Options:
- label: "Testing and QA"
description: "Focus on implementation, test later"
- label: "Performance optimization"
description: "Get it working first, optimize later"
- label: "Edge cases"
description: "Handle happy path only initially"
- label: "Nothing excluded"
description: "Everything is in scope"
multiSelect: true
If user selected "Multi-LLM debate (Claude + Codex + Gemini)" for approach: Before proceeding with orchestrate.sh, run a Multi-LLM debate to determine the technical approach:
/octo:debate --rounds 2 --debate-style collaborative "What is the best technical approach for [feature]? Consider: speed to market, maintainability, performance, and the existing codebase patterns."
Use the debate synthesis to set the approach context for the Define phase.
After gathering answers, create context file:
# Source context manager
source "${HOME}/.claude-octopus/plugin/scripts/context-manager.sh"
# Extract user answers from AskUserQuestion results
user_flow="[Answer from question 1]"
approach="[Answer from question 2]"
out_of_scope="[Answer from question 3]"
# Create context file with user vision
create_templated_context \
"define" \
"$(echo "$USER_REQUEST" | head -c 50)..." \
"User wants: $user_flow approach with $approach priority" \
"$approach" \
"Implementation of requested feature" \
"$out_of_scope"
echo "📋 Context captured and saved to .claude-octopus/context/define-context.md"
This context will be used to:
DO NOT PROCEED TO STEP 4 until context captured. User vision (UX approach, priorities, out-of-scope items) scopes the multi-AI research — without it, providers research too broadly and the definition misses the user's actual intent.
You MUST execute this command via the Bash tool:
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh define "<user's clarification 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 "grasp-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 findings and decisions in state:
# Extract key definition from synthesis
key_definition=$(head -50 "$SYNTHESIS_FILE" | grep -A 3 "## Problem Definition\|## Summary" | tail -3 | tr '\n' ' ')
# Record any architectural decisions made
# (You should identify these from the synthesis - e.g., tech stack, approach, patterns)
decision_made=$(echo "$key_definition" | grep -o "decided to\|chose to\|selected\|using [A-Za-z0-9 ]*" | head -1)
if [[ -n "$decision_made" ]]; then
"${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" write_decision \
"define" \
"$decision_made" \
"Consensus from multi-AI definition phase"
fi
# Update define phase context
"${HOME}/.claude-octopus/plugin/scripts/state-manager.sh" update_context \
"define" \
"$key_definition"
# 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:
Include attribution:
---
*Multi-AI Problem Definition powered by Claude Octopus*
*Providers: 🔴 Codex | 🟡 Gemini | 🔵 Claude*
*Full problem definition: $SYNTHESIS_FILE*
BEFORE executing ANY workflow actions, you MUST output this banner:
First, check task status (if available):
task_status=$("${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" get-task-status 2>/dev/null || echo "")
🐙 **CLAUDE OCTOPUS ACTIVATED** - Multi-provider definition mode
🎯 Define Phase: [Brief description of what you're defining/scoping]
📋 Session: ${CLAUDE_SESSION_ID}
📝 Tasks: ${task_status}
Providers:
🔴 Codex CLI - Technical requirements analysis
🟡 Gemini CLI - Business context and constraints
🔵 Claude - Consensus building and synthesis
| 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: DEFINE (convergent thinking)
DEFINE (grasp)
\ /
\ /
\ /
\ /
\ /
Converge to
problem
The define phase clarifies and scopes problems using external CLI providers:
This is the convergent phase after discovery - we narrow down from broad research to specific problem definition.
Use define when you need:
Don't use define for:
Before execution, you'll see:
🐙 **CLAUDE OCTOPUS ACTIVATED** - Multi-provider problem definition
🎯 Define Phase: Clarifying requirements and scope
Providers:
🔴 Codex CLI - Technical requirements
🟡 Gemini CLI - Business needs and context
🔵 Claude - Problem synthesis
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh define "<user's clarification request>"
The orchestrate.sh script will:
Results are saved to:
~/.claude-octopus/results/${SESSION_ID}/grasp-synthesis-<timestamp>.md
Read the synthesis and present clear, actionable requirements to the user.
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 define workflow with multi-AI providers",
description: "Run orchestrate.sh define for problem clarification",
activeForm: "Running multi-AI define workflow"
})
// Mark in_progress when calling orchestrate.sh
TaskUpdate({taskId: "...", status: "in_progress"})
// Mark completed ONLY after synthesis file verified
TaskUpdate({taskId: "...", status: "completed"})
If any step fails:
/octo:setup and STOPNever fall back to direct analysis if orchestrate.sh execution fails. Report the failure and let the user decide how to proceed.
After successful execution, present problem definition with:
# Problem Definition: <task>
## Core Requirements
[Essential requirements that must be met]
## Technical Constraints
[Technical limitations and considerations]
## User Needs
[What users actually need from this]
## Edge Cases to Handle
[Specific edge cases identified]
## Out of Scope
[What is explicitly NOT included]
## Perspectives
### Codex Analysis (Technical)
[Technical requirements and constraints]
### Gemini Analysis (Business/User)
[User needs and business context]
### Claude Synthesis
[Integrated problem definition]
## Requirements Checklist
- [ ] Functional requirements defined
- [ ] Non-functional requirements defined
- [ ] Technical constraints identified
- [ ] Edge cases documented
- [ ] Out-of-scope items clarified
- [ ] Success criteria established
## Next Steps
[Recommended next actions - usually tangle phase for implementation]
Full problem definition saved to: <synthesis file path>
User: Define the exact requirements for our user authentication system
Claude:
🐙 **CLAUDE OCTOPUS ACTIVATED** - Multi-provider problem definition
🎯 Define Phase: Clarifying authentication requirements
[Executes: ${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh define "Define exact requirements for user authentication system"]
[After completion, reads synthesis and presents:]
# Problem Definition: User Authentication System
## Core Requirements
### Must Have (P0)
1. User registration with email + password
2. Secure login with JWT token generation
3. Password reset via email
4. Session management with token refresh
5. Logout (token invalidation)
### Should Have (P1)
6. Remember me functionality
7. Account lockout after failed attempts
8. Email verification on signup
9. Password strength requirements
### Nice to Have (P2)
10. OAuth social login (Google, GitHub)
11. Two-factor authentication
12. Single sign-on (SSO)
## Technical Constraints
- Must work with existing Express.js backend
- Token storage: Redis for production, in-memory for dev
- Password hashing: bcrypt (min 12 rounds)
- Token expiry: Access token 15min, refresh token 7 days
- Rate limiting: Max 5 login attempts per 15min per IP
## User Needs
- Simple registration process (< 2 minutes)
- Secure password recovery without support tickets
- Stay logged in across browser sessions (remember me)
- Clear error messages for failed login
- Ability to log out from all devices
## Edge Cases to Handle
1. **Concurrent logins**: Same user, multiple devices
2. **Expired tokens**: Graceful refresh without re-login
3. **Password reset race condition**: Multiple reset requests
4. **Account enumeration**: Don't reveal if email exists
5. **Token theft**: Detect suspicious login locations
6. **Deleted users**: Handle auth for soft-deleted accounts
## Out of Scope
- ❌ Biometric authentication (fingerprint, face ID)
- ❌ LDAP/Active Directory integration
- ❌ Custom OAuth provider implementation
- ❌ Device fingerprinting
- ❌ Passwordless email magic links
## Perspectives
### Codex Analysis (Technical)
- JWT structure: { userId, role, exp, iat, jti }
- Database schema for users, refresh_tokens, password_resets
- API endpoints: POST /register, POST /login, POST /logout, POST /refresh, POST /reset-password
- Middleware for auth verification
- Security: HTTPS only, secure cookies, CSRF protection
### Gemini Analysis (Business/User)
- User journey: Registration -> Email verification -> Login -> Access app
- Error handling: Clear messages without security leaks
- Performance: Auth checks < 50ms
- Compliance: GDPR (data deletion), password policies
- Analytics: Track signup conversion, failed login rates
### Claude Synthesis
- Hybrid approach: Core auth (P0) first, iterate on P1/P2
- Security-first: All requirements validated against OWASP
- User experience: Balance security with convenience
- Scalable: Design for 100K users, plan for 1M+
## Requirements Checklist
- ✅ Functional requirements defined (registration, login, reset)
- ✅ Non-functional requirements defined (performance, security)
- ✅ Technical constraints identified (Express, Redis, bcrypt)
- ✅ Edge cases documented (6 critical cases)
- ✅ Out-of-scope items clarified (4 items)
- ✅ Success criteria established (< 2min registration, < 50ms auth)
## Next Steps
1. **Immediate**: Review and confirm requirements with stakeholders
2. **Then**: Use **tangle-workflow** to implement the auth system
3. **Finally**: Use **ink-workflow** to validate implementation
Ready to proceed to implementation?
Full problem definition saved to: ~/.claude-octopus/results/abc-123/grasp-synthesis-20250118-144530.md
User: What exactly does the notification feature need to do?
Claude:
🐙 **CLAUDE OCTOPUS ACTIVATED** - Multi-provider problem definition
🎯 Define Phase: Clarifying notification requirements
[Executes grasp workflow]
[Presents detailed problem definition with:]
- Core notification types (email, push, in-app)
- Delivery requirements (real-time vs batched)
- User preferences (opt-in/out, frequency)
- Technical constraints (message queue, delivery tracking)
- Edge cases (offline users, rate limits)
Ready to build once requirements are confirmed.
Grasp is the second phase of the Double Diamond:
PROBE (Discover) → GRASP (Define) → TANGLE (Develop) → INK (Deliver)
Typical flow:
Or use grasp standalone when requirements are unclear.
Before completing grasp workflow, ensure:
External API Usage:
Grasp workflows typically cost $0.01-0.05 per task depending on complexity.
After definition completes:
.octo/STATE.md with completion.octo/ROADMAP.md with defined phases and success criteria# Update state after Definition completion
"${HOME}/.claude-octopus/plugin/scripts/octo-state.sh" update_state \
--status "complete" \
--history "Define phase completed"
# Populate ROADMAP.md with defined requirements
if [[ -f "$SYNTHESIS_FILE" ]]; then
echo "📝 Updating .octo/ROADMAP.md with defined phases..."
"${HOME}/.claude-octopus/plugin/scripts/octo-state.sh" update_roadmap \
--from-synthesis "$SYNTHESIS_FILE"
fi
Ready to define! This skill activates automatically when users request requirement clarification or problem definition.