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