# Planning

> Interactive planning for complex requests — QnA, plan file, structured approval.

- Skill: `clode-labs/planning` (Agent Skill)
- Install (CLI): `npx skillmds@latest add clode-labs/planning`
- Raw SKILL.md: https://api.skillmd.com/api/skills/clode-labs/planning/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: clode-labs (https://skillmd.com/u/clode-labs)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/clode-labs/planning

---


# Planning Skill

Use this skill when the request is complex, ambiguous, multi-domain, or the user says "plan this". Skip planning for simple, well-defined tasks or when the user says "just do it".

## Protocol

### 1. Create the Plan File FIRST

You MUST create the plan file before calling start_planning. This is MANDATORY — VS Code opens immediately and needs the file to exist.

```bash
mkdir -p <APP_WORKING_DIR>/.planning
cat > <APP_WORKING_DIR>/.planning/<descriptive-name>.md << 'PLAN'
# Plan: [Title]

## What We're Building
[Initial understanding of the request]

## Open Questions
[What needs clarification]

## Decisions Made
[Updated after each answer]
PLAN
```

Never reuse filenames. Structure is freeform — let it emerge from the conversation.

### 2. Start Planning

Call `aramb_mcp.chat_start_planning` with `file_path=".planning/<descriptive-name>.md"` — this opens the plan file in VS Code for the user. Do NOT send any messages before this call.

### 3. Interactive Q&A

Ask ONE question at a time using `aramb_mcp.chat_ask_question`. Never inline numbered-list questions in your reply text — they store as plain text with no `options`, the frontend cannot render a picker, and the user reply comes back as unstructured free text.

Pass choices as the `options` array — do NOT inline them as a numbered list in the `question` body. The platform stores the array structurally so the UI renders a real choice picker and the answer comes back as `selected_option`.

```bash
npx mcporter call aramb_mcp.chat_ask_question \
  project_id="<PROJECT_ID>" application_id="<APPLICATION_ID>" \
  question="Question 1/5 — What authentication approach should we use?" \
  options='["JWT tokens — stateless, good for APIs", "Session-based — simpler, server-side state", "OAuth 2.0 — delegate to Google/GitHub"]'
```

Rules:
- ALWAYS `aramb_mcp.chat_ask_question`. Never inline-numbered-list questions in your reply text.
- Include the progress marker in the `question` string (Question 1/5, 2/5, …) — count can change dynamically.
- 2-4 options per question. Each option is a short label with a brief pro/con after an em-dash.
- After each answer: update the plan file, then ask the next question.
- The user is watching the plan file in VS Code — keep it current.

### 3b. Handling "Surprise me!" / defaults

If the user says "surprise me", "use defaults", "you decide", or similar at ANY point during Q&A:
- **STOP asking questions immediately** — do not ask any more questions
- For ALL remaining unanswered questions, choose the most common/sensible default
- Update the plan file with all decisions (note which were auto-decided)
- Proceed directly to Step 4 (Submit the Plan)

### 4. Submit the Plan

When all questions are answered, call `aramb_mcp.chat_submit_plan` with the
**mode-agnostic** plan payload:

- `summary`: one-line description
- `approach`: technical approach
- `key_decisions`: `[{decision, rationale}]`

The plan no longer carries `agents` or `tasks` arrays — those were dropped
from the schema as part of the MCP toolkit split. Task creation is the
post-approval step's responsibility (see Step 5 below): in team mode you
follow up with `aramb_mcp.tasks_create`; in solo mode you just start executing.
Keep the task list in your planning **file** (`.planning/<...>.md`) for
your own reference, but don't try to pass it through `submit_plan`.

**CRITICAL: After calling `submit_plan`, STOP. Do not send any more messages. Wait for the user's response.**

### 5. Handle User Response

The user responds via chat message:

- **Approved** (e.g., "Plan approved, proceed further!", "looks good", "go ahead"):
  1. Call `aramb_mcp.chat_finish_planning`
  2. **Team mode**: call `aramb_mcp.tasks_create` with the tasks you'd captured in your planning file.
     **Solo mode**: skip step (2) — solo has no task surface; start executing directly.
     If you're in a skill that runs in both modes and need to branch, call
     `aramb_mcp.chat_get_mode application_id="<APPLICATION_ID>"` to confirm.

- **Modification requested** (user sends feedback like "change X to Y"):
  1. Update the plan file with revisions
  2. Call `aramb_mcp.chat_submit_plan` again with updated data
  3. STOP and wait again

- **Rejected** (user says "no", "scrap this", "start over"):
  1. Ask the user what they'd prefer instead