/plan

description: Structured planning - explore codebase, design architecture, evaluate options, produce detailed implementation plan
argument-hint: "[feature description] [--fast]"

Plan

Turn a task or idea into a detailed implementation plan. Clarifies scope, explores codebase, discusses approaches with user, designs architecture for selected approaches, evaluates with experts, then writes a bite-sized plan.

**HARD-GATE: This command produces a plan, NOT code. No files are modified except .lets/plans/.**

> **IMPORTANT:** If the spec below invokes any deferred tool (e.g. `AskUserQuestion`), you MUST load and call it as specified. Never skip the call, never substitute a default answer of your own — the tool invocation is part of the contract. This is critical.

--fast mode

`/lets:plan --fast` (combinable with a task-id or feature description, e.g. `/lets:plan lets-abc --fast`) skips the three subagent-dispatch phases - **Step 4** (explorer agents), **Step 6** (architect agents), **Step 7** (expert agents) - and replaces them with orchestrator-only equivalents (read files yourself, draft approaches inline, self-evaluate risks). Use it when the user explicitly wants a collaborative talk-through without subagent budget: "let's just plan it together, I'll review". Everything else - clarifying questions, interactive discussion, plan format, tracker recording, the saved file - is identical to the full flow. The plan's shape doesn't change; only *how* it's built.

When `--fast` is **not** set, run the full flow exactly as written.

Step 1: Capture the Goal

**Parse the argument:** strip a `--fast` token if present (sets fast mode); the rest is the feature goal.

**If a feature goal was provided:** use it.

**If no goal provided:** ask:

> "What are you trying to build or change?"

Wait for answer before proceeding.

Step 2: Active Task Context

Use the **detect-task** skill to find the active task: `Skill(skill: "lets:detect-task")`.

If Step 1 captured an explicit `<task-id>` argument (e.g. an interactive `--flow plan` launch into a fresh worktree), resolve-and-claim it per the **detect-task** *explicit task-id argument* convention - pointer only, don't re-paraphrase.

If task found:

show task=<task-id>          # returns {id,title,status,url,description}
comment-list task=<task-id>  # existing comments; absent -> continue with the description alone and say so

Load: title, description, existing comments, plus any further field the adapter's `show` declares in `returns:` (beads declares `design`).

If no task found, warn: > "No active task detected. Every session needs a task. Create one (the `create-task` skill) or pick from the tracker's `ready` view."

Do not block - continue if user acknowledges.

Step 3: Clarifying Questions

**Ask questions BEFORE exploration.** Scope must be clear before launching expensive agents.

Based on (goal + task description), identify unknowns that would change the architecture.

Present ALL questions at once - max 5, min 2.

Categories to draw from:

• **Scope**: What's explicitly OUT of scope?
• **Behavior**: Edge cases, error handling, user-facing behavior
• **Constraints**: Performance, compatibility, must-not-break areas
• **Success criteria**: How will we know it's done?
• **Unknowns**: Technical unknowns that need spiking first

Before exploring the codebase, I need to clarify scope:

1. {question}
2. {question}
...

Answer all at once.

Wait for user answers before proceeding.

Step 4: Codebase Exploration

Gather project context:

LETS_PROJECT_ROOT=$(git rev-parse --show-toplevel)
cat "$LETS_PROJECT_ROOT/CLAUDE.md" 2>/dev/null | head -200

--fast: orchestrator-only exploration

**If `--fast` is set:** skip the explorer-dispatch phase below (Exploration Strategy, Show Exploration Plan, Launch Explorers). Instead, build the Codebase Map yourself:

• Read/Grep/Glob the files relevant to the feature goal + user clarifications, on demand - prioritize the entry points, the modules the feature touches, and the existing patterns it should follow.
• Iterate: read a file, learn something, decide what to read next. Stop when you can describe the relevant surface confidently.
• Synthesize the same `## Codebase Map` structure (sections by area), then go to the **Checkpoint: Exploration Review** below (same checkpoint, same options).
• Note any area you couldn't cover ("didn't read X - low confidence there") so the user can ask for more.

Then jump to **Checkpoint: Exploration Review**.

Exploration Strategy

*(full mode only - skipped under `--fast`)*

Decide how many explorers to launch and what each should focus on.

**Inputs for decision:**

LETS_PROJECT_ROOT=$(git rev-parse --show-toplevel)
FILE_COUNT=$(find "$LETS_PROJECT_ROOT" -type f \
  -not -path '*/.git/*' \
  -not -path '*/node_modules/*' \
  -not -path '*/vendor/*' \
  -not -path '*/dist/*' \
  -not -path '*/.next/*' \
  -not -path '*/build/*' \
  -not -path '*/__pycache__/*' \
  | wc -l | tr -d ' ')

Based on the **feature goal**, **user clarifications**, **project size**, and **task description**, identify distinct focus areas that need exploration. Each focus area becomes one explorer agent.

**Guidelines for choosing focus areas:**

• Each explorer should have a clear, non-overlapping focus
• Small isolated feature -> 1-2 explorers (e.g., "map existing auth code", "map test patterns")
• Cross-cutting feature -> 3-5 explorers (e.g., one per module/layer it touches)
• Large-scale refactor or unclear scope -> 5-10 explorers (one per area of concern)
• Subagents have a separate rate limit - prefer more exploration when uncertain

**Confirmation gate:** If planning to launch more than 10 explorers:

AskUserQuestion(
  questions=[{
    question: "Planning {N} explorers for this feature. That's a lot - confirm?",
    header: "Confirm",
    options: [
      { label: "Launch all", description: "{N} explorers, thorough cover