/plan

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

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/. The command ENDS when the plan is saved - implementation starts ONLY when the user runs `/lets:execute`. Nothing the user says after the plan ("ok", "approved", a question) starts it.**

> **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.

--idea mode

`/lets:plan --idea` (combinable with a task-id; `--fast` is a no-op here, no agents run anyway) writes a **concept document**, not a plan: the wish, captured before anyone decides how to build it. `/lets:execute` never picks it up and refuses it by path; a later `/lets:plan` on the same task reads it as input.

| Step | In `--idea` mode | |---|---| | 3 | Questions about the wish: who wants it, why, how it should feel, what triggers it, what is out of scope, who takes it over (the handoff target) | | 4, 6, 7 | SKIPPED - no codebase exploration, no architecture, no experts; no code snippets or file paths anywhere in the document | | 5 | Discuss behaviour variants the user would notice, not implementations | | 9 | The idea template below - NO `STOP` banner (there is nothing to execute) | | 10 | Save via `Skill(skill: "lets:artifact-path", args: "kind=idea ext=md task={TASK_ID}")` and record it (below) |

Idea template:

# {Idea name}

> **IDEA BANK ENTRY - NOT A PLAN.** Nothing here is executable; /lets:execute refuses this file.

**Task:** {task-id or none}
**Date:** {YYYY-MM-DD}

## Problem
## What exists today
## The wish (user-visible behaviour)
## Triggers
## Constraints
## Open questions
## Handoff

When a task is active:

comment-add task=<task-id> body="Idea document: .lets/plans/<ARTIFACT basename>"

Output: the saved path and one line - "Idea saved - run `/lets:plan` on this task to turn it into a plan."

Step 1: Capture the Goal

**Parse the argument:** strip a `--fast` token if present (sets fast mode) and an `--idea` token (sets idea mode, `## --idea 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. `--orc` is stripped per that convention before the task-id test.

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`).

**Idea input (normal mode).** Look for an idea document on this task and, when one exists, Read it and treat it as input to Step 3:

LETS_PROJECT_ROOT=$(git rev-parse --show-toplevel)
ls -t "$LETS_PROJECT_ROOT/.lets/plans/"*"-{task-id}-idea"*.md 2>/dev/null | head -1

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