Create Plan

Goal

Turn a user prompt into a single, actionable plan stored as a markdown file in .cursor/plans/, then obtain explicit approval before any buildout begins.

Minimal workflow

1. •

   Scan context quickly

   • •Read README.md and any obvious docs (docs/, CONTRIBUTING.md, ARCHITECTURE.md).
   • •Skim relevant files (the ones most likely touched).
   • •Identify constraints (language, frameworks, CI/test commands, deployment shape).
2. •

   Ask follow-ups only if blocking

   • •Ask at most 1–2 questions.
   • •Only ask if you cannot responsibly plan without the answer; prefer multiple-choice.
   • •If unsure but not blocked, make a reasonable assumption and proceed.
   • •Ask open questions directly to the user; do not append them to the plan file.
3. •

   Create a plan file in .cursor/plans/

   • •Ensure .cursor/plans/ exists; create it if missing.
   • •Name the file <agent_name>__<short summary no more than 5 words snake-cased>.plan.md.
   • •The plan file must contain YAML frontmatter in the format below, followed by human-readable details (headings + short sections) that expand on the plan.
   • •Include 6–10 ordered, verb-first action items.
   • •Each item should be atomic and include files/commands when useful.
   • •Use pending, in_progress, or completed for status.
4. •

   Handle the follow-up loop before building

   • •If you asked questions, stop after writing the plan file and wait for answers.
   • •When answers arrive, update the plan file to reflect the new information.
   • •If the user adds new requirements or changes scope, update the plan file again.
   • •Always refer back to this plan during the planning loop.
   • •Ask for explicit permission to begin building after each update.
5. •

   Output formatting

   • •Initial plan: confirm the plan file path and request permission to proceed.
   • •Follow-up after answers: confirm updates, mention the plan file path, and request permission again.

Plan template (follow exactly)

---
name: <Short Title Case name>
overview: <1–3 sentences describing intent and approach.>
todos:
  - id: <kebab-case-id>
    content: <Verb-first action item>
    status: pending
  - id: <kebab-case-id>
    content: <Verb-first action item>
    status: pending
---

# <Readable Title>

## Overview

<Short summary of the change and why.>

## Key Files

- <List key files and why they matter.>

## Implementation Notes

<Bullets or short paragraphs that clarify approach, constraints, and data flow.>

## Testing

- <Concrete manual or automated test steps.>

Checklist item guidance

Good items:

• •Point to likely files/modules: src/..., app/..., services/....
• •Name concrete validation: Run npm test, Add unit tests for X.
• •Include edge cases or risk checks when applicable.

Avoid:

• •Vague steps ("handle backend", "do auth").
• •Too many micro-steps.
• •Writing code snippets (keep the plan implementation-agnostic).