---
name: plan
description: >
  Plan mode — explore read-only, write a plan to workspace/plans/, get approval,
  execute only after the user explicitly says so (now or later). Mirrors Claude
  Code plan mode.
  Use when user says "/plan X", "plan mode", "first plan then do X".
---

# Plan

Explore the task read-only, design an approach, write it to a plan file, and
**stop for approval**. Mutate nothing until the user explicitly approves
execution — which can happen now or much later. Plan now, execute whenever.

Four phases, run linearly. Emit a short status line between phases so the user
(especially on Telegram, where there is no thinking stream) sees progress.

## 1. Explore (read-only)

1. Restate the task in one sentence to confirm scope.
2. Investigate the relevant files and state: `read_file`, `ssh … cat` / `rsync`
   for server files, `--help`, the official wiki. Look for existing code,
   skills, or patterns to reuse instead of proposing new ones.
3. **No mutations.** Reading only.

Default: explore **linearly, yourself**. Planning is iterative — what you find
decides where you look next — and that does not split cleanly up front.

Use `spawn` **only** when the task is large and breaks into genuinely
independent parts (e.g. "explore three separate subsystems"). Then spawn one
subagent per part and wait for their results before phase 2. `spawn` is async
(results arrive via the message bus, not inline), so reach for it only at real
divisible scale — never routinely.

## 2. Design

Design the approach: what changes, where, and how it will be verified. Reuse
what you found in phase 1. If the request is genuinely ambiguous, ask now;
otherwise proceed.

## 3. Write the plan

1. Pick a kebab-case slug from the topic.
2. Write the plan to `/home/nanobot/.nanobot/workspace/plans/<slug>.md` (create
   the `plans/` directory if missing). This file write is the **only** write
   allowed before approval.
3. Plan structure:

   ```
   # <Title>

   ## Context
   Why this change — the problem, what prompted it, the intended outcome.

   ## Steps
   Numbered steps. Name the files to touch. Reference reusable code found
   in phase 1 with its path.

   ## Verification
   How to test the change end-to-end (run it, run tests, check behavior).
   ```

4. Also print a short version of the plan into the chat.

## 4. Approval (replaces ExitPlanMode — over chat)

Stop and ask for approval: say the plan was saved to
`workspace/plans/<slug>.md`, and ask whether to execute it now. Then wait.
Mutate nothing on your own.

- Approved + execute now → drop the read-only discipline and execute the plan in
  this conversation.
- Approved but **not now** → planning is done. The plan stays in
  `workspace/plans/<slug>.md` for later; the user can run it anytime by pointing
  at the file.
- Wants changes → rewrite the plan file (still read-only otherwise) and ask again.

## Edge cases

- `/plan` with no task → ask "What should I plan?".
- Tiny one-step task (typo fix, single-line change) → say a full plan is
  overkill and offer to just do it; don't force the ceremony.
- User already approved earlier and now says "execute the plan" → read the plan
  file and execute; no need to re-plan.

## Rules

- **Read-only through phases 1–3.** Do not write or edit files (except the plan
  file in phase 3), run mutating commands, change config, or restart services.
- Execute only after explicit approval to execute now. Approval to "save the
  plan" is not approval to run it.
- Reuse before inventing — prefer existing code, skills, and patterns found
  in phase 1.
- Respond in the user's language (the model localizes status and questions
  itself); keep the plan-file body and structure as above.
- Keep status lines to one short sentence. No filler, no emojis.