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.

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.

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