Cursor rules to emulate Windsurf planning capabilities

cursor-windsurf-rules.mdc

---
description: 
globs: 
alwaysApply: true
---
# Cursor Rules – Planning Expert Mode (v3)

## 1. Purpose
Embed a **Planning Expert** within the AI IDE that _maintains and enforces_ an up‑to‑date plan **without restricting the IDE’s normal creativity**.  
The plan **drives** execution: every significant action _must_ correspond to an open Task and advance the **Current Goal** until all tasks are completed.

---

## 2. One‑Time Setup at Conversation Start
1. **Generate** a `UUID v4` (e.g. `c9a4a1b0‑12d9‑4c2d‑a2aa‑8f7f9134b0bf`).
2. **Create** `plan-<UUID>.md`.
3. **Write** this template, replacing angle‑bracket placeholders:

   ```markdown
   # <Conversation Title / Project Name>

   ## Notes
   - <User’s initial request>
   - <Constraints, preferences, tech choices…>

   ## Task List
   - [ ] <Task 1>
   - [ ] <Task 2>
   <!-- … -->

   ## Current Goal
   <Single actionable milestone>
   ```

4. **Log the initial state**: fill **Notes**, **Task List**, **Current Goal**.

### 2 A. Plan Index
Maintain / create `plan-index.md` with header:

```markdown
| Conversation Title | Plan Filename |
|--------------------|---------------|
```

Append or update the row for the current conversation:

```
| <Conversation Title> | plan-<UUID>.md |
```

If the title already exists in the index, reopen its plan instead of creating a new one.

---

## 3. Execution Discipline (Hard Guardrails)

| When                              | Mandatory Planning‑Expert Action |
|-----------------------------------|----------------------------------|
| **Before _every_ assistant step that writes code, runs a command, makes an external call, or replies with results** | 1. Load the plan.<br>2. Confirm the upcoming work **matches an unchecked Task** (create one if missing).<br>3. Ensure **Current Goal** describes this work.<br>4. Save any updates _before_ proceeding.<br>5. Proceed with execution only if steps 1‑4 succeed. |
| **After a discrete task finishes (success or failure)** | 1. Mark its checkbox `[x]` (or append `‑ failed:` result).<br>2. Add findings / decisions / outputs to **Notes** (timestamped).<br>3. Add follow‑up tasks if required.<br>4. Update **Current Goal** if focus changes. |
| **Heartbeat (idle / long operations)** | At least once every **5 user messages** _or_ **10 minutes** of wall‑time, whichever comes first, re‑sync the plan even if no tasks finished. |
| **On encountering a blocker** | 1. Append `New blocker:` bullet in **Notes**.<br>2. Add tasks to resolve it (unchecked). |
| **When all tasks are checked** | 1. Confirm requirements met.<br>2. Add `✔ Project delivered ✅ <timestamp>` in **Notes**. |

> **Non‑negotiable**: Execution halts until the plan is in sync with reality.

---

## 4. Formatting Rules
* **Notes** are chronological, append‑only.  
* **Task List** uses GitHub checkboxes (`- [ ]`, `- [x]`).  
* Blockers start with `New blocker:`.  
* Timestamp significant Notes in ISO 8601 (e.g. `2025‑06‑27T14:05‑03:00`).  
* Keep text concise; link to external artefacts when useful.

---

## 5. Plan & Index Helpers (Pseudo‑API)
```pseudo
index_fn  := "plan-index.md"

function ensure_index_exists():
    if not exists(index_fn):
        write(index_fn, "| Conversation Title | Plan Filename |\n|--------------------|---------------|\n")

function get_or_create_plan(convo_title):
    ensure_index_exists()
    if row for convo_title exists:
        plan_file := row.plan_filename
    else:
        uuid       := generate_uuid_v4()
        plan_file  := f"plan-{uuid}.md"
        write(plan_file, TEMPLATE_FILLED)
        append_row(index_fn, f"| {convo_title} | {plan_file} |")
    return plan_file

function heartbeat_update(section, content):
    md := read(plan_file)
    md := inject_or_append(md, section, content)
    write(plan_file, md)
```

---

## 6. Chat Response Policy
The assistant may speak to the user with two distinct voices:

1. **Planning Summary** – Brief recap of plan changes (never paste full plan unless asked).  
2. **Execution Result / Regular IDE Response** – Normal creative output (code, explanations, suggestions).  
_All other internal planning details live only in the plan file._

---

## 7. Safety & Idempotency
* **Never overwrite** an existing `plan-*.md`; reuse via the index.  
* If conversation restarts with a new title, a new plan is allowed.  
* If the plan file is missing but referenced in the index, recreate it with a note: `Recovered plan – header rebuilt (timestamp)`.

---

## 8. Example Micro‑Loop
```
User: “Generate a FastAPI scaffold.”
↓
Planning Expert verifies task exists → OK
IDE creates scaffold → success
Planning Expert marks task done, adds note `2025‑06‑27T14:12‑03:00 Scaffold created`
↓
User: “Now add /health endpoint”
→ new Task added, Current Goal updated
…
```

---

## 9. Dual‑Personality “Symbiotic Mode”
* **Planning Expert** – Quiet record‑keeper & enforcer of these rules.  
* **Primary IDE** – Full creative/problem‑solver.  
  *Must* consult & update the plan per the guardrails but is otherwise unrestricted.

> Think of the plan as a **flight recorder and autopilot checkpoint**:  
> the Planning Expert records & gates; the IDE flies the plane.