Ships with octo. Installing the plugin gets this command.
⚡ How it fires
How this command gets triggered: by you, by Claude, or both.
Fires itselfClaude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.
Slash command/plan
👁️ Context preview
What this command does when you run it.
Intelligent plan builder - creates strategic execution plans (doesn't execute). Use /octo:embrace to execute plans.
📊 Stats
Stars3,869
Forks362
LanguageShell
LicenseMIT
📦 Ships with octo
</> Command definition
plan.md
---command: plan
description: "Intelligent plan builder - creates strategic execution plans (doesn't execute). Use /octo:embrace to execute plans."
aliases:
- build-plan
- intent
---# Plan - Intelligent Plan Builder
**Creates strategic execution plans based on user intent. Saves plans for review and optional execution with /octo:embrace.**
## Key Behavior
- **Creates plans** - Captures intent, analyzes requirements, generates weighted execution strategy
- **Saves to files** - Stores plan (`.claude/session-plan.md`) and intent contract (`.claude/session-intent.md`)
- **Doesn't execute** - Plans are saved for review; execution requires user confirmation
- **Optional execution** - Can invoke `/octo:embrace` immediately or user can execute later
## 🤖 INSTRUCTIONS FOR CLAUDE
### MANDATORY: Detect Plan Mode Write Conflict Before Starting
**THIS CHECK RUNS FIRST — before intent capture, before any artifact write.**
Native plan mode blocks all Write/Edit tool calls until `ExitPlanMode` is
called. If you are currently in plan mode (you entered it earlier this session
or the harness placed you in it), attempting to write `.claude/session-intent.md`
or `.claude/session-plan.md` will silently fail, producing a degraded native
plan instead of a full octo multi-provider plan.
**If you are in plan mode when /octo:plan is invoked, you MUST:**
1. Emit this exact warning as the very first output:
```text
⚠️ OCTO PLAN DEGRADED — Plan Mode Write Conflict
Native plan mode is active. Octo cannot save its planning artifacts
(.claude/session-intent.md, .claude/session-plan.md) while plan mode
restricts writes. You are getting display-only output — this is NOT
a full octo multi-provider plan.
To get the full octo plan:
1. Exit or cancel native plan mode
2. Re-run /octo:plan
Continuing with plan visualization only (no artifacts saved)…
```
2. Skip Step 2 (Create Intent Contract) and Step 5 (Save the Plan) entirely.
Do not attempt these writes — they will silently fail.
3. Complete Steps 1, 3, 4, and 6 so the user sees the visualization.
4. Repeat the re-run reminder at the end of Step 6.
**Do NOT silently fall through to generic native planning. The user invoked
/octo:plan deliberately. A visible degradation warning is mandatory.**
---
### MANDATORY COMPLIANCE — DO NOT SKIP
**When the user explicitly invokes `/octo:plan`, you MUST execute the structured planning workflow below.** You are PROHIBITED from doing the task directly, skipping the intent capture questions, or deciding the task is "too simple" for structured planning. The user chose this command deliberately — respect that choice.
---
When the user invokes this command (e.g., `/octo:plan <arguments>`):
### Step 1: Capture Comprehensive Intent
**CRITICAL: Start by capturing the user's full intent using structured questions.**
Ask 5 comprehensive questions to understand what they're trying to accomplish:
```javascript
AskUserQuestion({
questions: [
{
question: "What are you ultimately trying to accomplish?",
header: "Goal",
multiSelect: false,
options: [
{label: "Research a topic", description: "Gather information and options"},
{label: "Make a decision", description: "Choose between alternatives"},
{label: "Build something", description: "Create implementation or artifact"},
{label: "Review/improve existing", description: "Assess and enhance what's there"},
{label: "I'll describe it", description: "Let me write my own goal"}
]
},
{
question: "How much do you already know about this?",
header: "Knowledge",
multiSelect: false,
options: [
{label: "Just starting", description: "Need to learn the landscape"},
{label: "Some familiarity", description: "Know basics, need deeper dive"},
{label: "Well-informed", description: "Know options, need execution"},
{label: "Expert", description: "Just need implementation/validation"}
]
},
{
question: "How clear is the scope?",
header: "Clarity",
multiSelect: false,
options: [
{label: "Vague idea", description: "Not sure exactly what I need"},
{label: "General direction", description: "Know the area, need specifics"},
{label: "Clear requirements", description: "Know what to build"},
Render provider availability from actual provider checks before the plan visualization. Do not hand-write or summarize this provider block; run this block and include its output exactly in the plan. The output MUST include the Antigravity line even when `agy` is missing.
**Display a comprehensive plan visualization with ACTUAL provider status:**
```
🐙 **CLAUDE OCTOPUS PLAN**
WHAT YOU'LL END UP WITH:
[Clear description of the deliverable based on their goal]
HOW WE'LL GET THERE:
DISCOVER ████████████████ 40%
Research the landscape — Gather evidence and options
→ /octo:discover (extended depth)
DEFINE ████ 15%
Lock the scope — Confirm boundaries and approach
→ /octo:define (light touch)
DEVELOP ████████████ 30%
Build the solution — Create the implementation
→ /octo:develop
DELIVER ██████ 15%
Validate quality — Review and refine
→ /octo:deliver
Provider Availability:
🔴 Codex CLI: [Available ✓ / Not installed ✗]
🟡 Gemini CLI: [Available ✓ / Not installed ✗]
🧭 Antigravity CLI: [Available ✓ / Not installed ✗]
🟤 OpenCode: [Available ✓ / Not installed ✗]
🟢 Copilot CLI: [Available ✓ / Not installed ✗]
🟠 Qwen CLI: [Available ✓ / Not installed ✗]
⚫ Ollama: [Available ✓ / Not installed ✗]
🔵 Claude: Available ✓
🟣 Perplexity: [Configured ✓ / Not configured ✗]
YOUR INVOLVEMENT: [Checkpoints / Semi-autonomous / Hands-off]
Time estimate: [Rough estimate based on scope]
```
**PROHIBITED: Displaying only "🔵 Claude: Available ✓" without listing all providers.**
### Step 5: Save the Plan
**CRITICAL: The plan command creates plans, it does NOT execute them by default.**
1. **Save plan to `.claude/session-plan.md`:**
```markdown
# Session Plan
**Created:** [timestamp]
**Intent Contract:** See .claude/session-intent.md
## What You'll End Up With
[Clear description of deliverable]
## How We'll Get There
### Phase Weights
- Discover: [X]% - [Brief description]
- Define: [X]% - [Brief description]
- Develop: [X]% - [Brief description]
- Deliver: [X]% - [Brief description]
### Execution Commands
To execute this plan, run:
\`\`\`bash
/octo:embrace "[user's goal]"
\`\`\`
Or execute phases individually:
- `/octo:discover` (if Discover > 20%)
- `/octo:define` (if Define > 20%)
- `/octo:develop` (if Develop > 20%)
- `/octo:deliver` (if Deliver > 20%)
## Provider Requirements
🔴 Codex CLI: [Available ✓ / Not installed ✗]
🟡 Gemini CLI: [Available ✓ / Not installed ✗]
🧭 Antigravity CLI: [Available ✓ / Not installed ✗]
🟣 Perplexity: [Configured ✓ / Not configured ✗]
🔵 Claude: Available ✓
## Success Criteria
[From intent contract]
## Next Steps
1. Review this plan
2. Adjust if needed (re-run /octo:plan)
3. Execute with /octo:embrace when ready
```
2. **Display the plan to the user** (same visualization as before)
3. **Show completion message:**
```
✅ Plan saved to .claude/session-plan.md
To execute this plan, run:
/octo:embrace "[user's goal]"
Or adjust the plan:
/octo:plan (re-run to modify)
```
### Step 6: Offer Next Actions (Optional Execution)
**Ask user what they want to do with the plan:**
```javascript
AskUserQuestion({
questions: [
{
question: "What would you like to do with this plan?",
header: "Next Action",
multiSelect: false,
options: [
{label: "Review and execute later", description: "Plan saved, I'll run /octo:embrace when ready (Recommended)"},
{label: "Adjust plan weights", description: "Change phase emphasis before saving"},
{label: "Execute now", description: "Run /octo:embrace immediately with this plan"},
{label: "Multi-LLM debate the plan first", description: "Claude plus available external providers debate the plan's assumptions and risks before executing"},
{label: "Different approach", description: "Suggest an alternative strategy"}
]
}
]
})
```
**If "Review and execute later":**
- Save plan and exit
- User can review `.claude/session-plan.md` at their leisure
- User runs `/octo:embrace` when ready
**If "Adjust plan weights":**
- Ask which phases to emphasize/de-emphasize
- Regenerate plan visualization
- Save updated plan
- Return to Step 6 (ask again what to do)
**If "Execute now":**
- Invoke `/octo:embrace` skill with the user's goal
- Pass the intent contract and phase weights
- Let embrace workflow handle execution
**If "Multi-LLM debate the plan first":**
- Invoke `/octo:debate` with the plan as context (Claude plus available providers deliberate):
- Topic: "Should we proceed with this plan? What are the risks and blind spots?"
