/plan

command: plan
disable-model-invocation: true
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

Load `skills/blocks/engineering-method-selection.md` from the installed plugin and apply only the methods relevant to this task. Preserve this entry point's execution contract and output format. Read referenced skills as instructions; do not invoke the current command recursively or add provider calls from a seat.

**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 each plan and intent contract in a unique run directory under the project-owned `.octo/plans/` namespace, or under octo-owned session storage when there is no project
• **Doesn't execute** - Plans are saved for review; execution requires user confirmation
• **Optional execution** - Can load `/octo:embrace` after explicit user approval or execute later
• **Prototype handoff** - Can propose one bounded experiment without writing or launching providers in native plan mode

Prototype proposal

When one risky assumption blocks the plan, offer a prototype with one question, hypothesis, deadline, artifact path, source revision, and success signal. In native read-only plan mode, present the proposal only. After explicit execution approval, load `skill-prototype` and store artifacts through `scripts/plan-storage.sh`. Choosing a prototype does not authorize deployment, provider calls, browser login, repository rewrites, or new permissions.

Before filing implementation tasks, map unresolved decisions and their dependency graph. A cycle withholds ready status. Claims must use the configured tracker's atomic operation and be read back before work starts. On tracker failure, save an explicitly unfiled proposal in the plan directory and stop tracker writes.

🤖 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 `${OCTO_PLAN_DIR}/session-intent.md` or `${OCTO_PLAN_DIR}/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:

   ⚠️  OCTO PLAN DEGRADED — Plan Mode Write Conflict

   Native plan mode is active. Octo cannot save its planning artifacts
   (session-intent.md, 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.**

---

Resolve Plan Storage Location

**After confirming native plan mode is not active, resolve one unique run directory before creating either artifact. Every other step in this command reads or writes `${OCTO_PLAN_DIR}/session-intent.md` and `${OCTO_PLAN_DIR}/session-plan.md`. Never substitute a bare `.claude/session-intent.md` or `.claude/session-plan.md` literal:**

PLAN_STORAGE="${CLAUDE_PLUGIN_ROOT:-${HOME}/.claude-octopus/plugin}/scripts/plan-storage.sh"
OCTO_PLAN_DIR="$("$PLAN_STORAGE" create "$PWD")" || {
  echo "Unable to resolve safe plan artifact storage" >&2
  exit 1
}
echo "Plan artifacts will be saved to: ${OCTO_PLAN_DIR}"

The resolver hard-blocks the global `~/.claude/` directory, detects git and marker-file project roots, creates a unique directory for every invocation, and records that directory for the current host session and workspace. Running `/octo:plan` from `$HOME` or another non-project directory uses `~/.claude-octopus/sessions/<session-id>/plans/<run-id>/`. Project runs use `<project-root>/.octo/plans/<run-id>/`.

Keep the absolute path printed by the resolver and use that exact path in every later Read, Write, Edit, and Bash action. If the path must be recovered in a later shell, run `"$PLAN_STORAGE" current "$PWD"`. Report the resolved absolute path, not a relative placeholder, in every confirmation message shown to the user.

Provider preflight

Before launching any Codex or other provider-backed planning seat, capture one authoritative status snapshot and retain it for the later visualization:

OCTO_ROOT="${CLAUDE_PLUGIN_ROOT:-${HOME}/.claude-octopus/plugin}"
provider_helper="$OCTO_ROOT/scripts/helpers/check-providers.sh"
if [[ ! -x "$provider_helper" ]]; then
  echo "Claude Octopus provider readiness helper is unavailable; planning in Claude-only mode." >&2
  PROVIDER_STATUS=""
else
  PROVIDER_STATUS="$("$provider_helper" 2>/dev/null || true)"
fi
printf '%s\n' "$PROVIDER_STATUS"

If the selected provider is unavailable or unauthenticated, keep the plan in Claude-only mode, name the failed preflight, and offer `/octo:setup` or `/octo:skill-doctor` as the recovery path. Do not describe an unstarted provider seat as completed.

MANDATORY COMPLIANCE — DO NOT SKIP

**When the user explicitly invokes `/octo:plan`, you MUST execute th