planning-with-files

# Cursor IDE Setup

How to use planning-with-files with Cursor IDE — now with full hook support.

---

## Installation

### Option 1: Copy .cursor directory (Recommended)

```bash
git clone https://github.com/OthmanAdi/planning-with-files.git
cp -r planning-with-files/.cursor .cursor
```

This copies the skill files, hooks config, and hook scripts to your project.

### Option 2: Manual setup

1. Copy `.cursor/skills/planning-with-files/` to your project
2. Copy `.cursor/hooks.json` to your project
3. Copy `.cursor/hooks/` directory to your project

---

## Hooks Support

Cursor now supports hooks natively via `.cursor/hooks.json`. This skill includes three hooks that mirror the Claude Code experience:

| Hook | Purpose | Cursor Feature |
|------|---------|----------------|
| `preToolUse` | Re-reads task_plan.md before tool operations | Keeps goals in context |
| `postToolUse` | Reminds to update plan after file edits | Prevents forgetting updates |
| `stop` | Checks if all phases are complete | **Auto-continues** if incomplete |

### How the Stop Hook Works

The stop hook is the most powerful feature. When the agent tries to stop:

1. It checks `task_plan.md` for phase completion status
2. If all phases are complete → allows the agent to stop
3. If phases are incomplete → sends a `followup_message` that auto-prompts the agent to keep working

This means the agent **cannot stop until all phases are done** (up to `loop_limit` of 3 retries).

### Hook Files

```
your-project/
├── .cursor/
│   ├── hooks.json                  ← Hook configuration
│   ├── hooks/
│   │   ├── pre-tool-use.sh         ← Pre-tool-use script
│   │   ├── post-tool-use.sh        ← Post-tool-use script
│   │   ├── stop.sh                 ← Completion check script
│   │   ├── pre-tool-use.ps1        ← PowerShell versions
│   │   ├── post-tool-use.ps1
│   │   └── stop.ps1
│   └── skills/
│       └── planning-with-files/
│           ├── SKILL.md
│           ├── examples.md
│           ├── reference.md
│           └── templates/
├── task_plan.md                     ← Your planning files (created per task)
├── findings.md
├── progress.md
└── ...
```

---

## Windows Setup

The default `hooks.json` uses bash scripts (works on macOS, Linux, and Windows with Git Bash).

**If you need native PowerShell**, rename the config files:

```powershell
# Back up the default config
Rename-Item .cursor\hooks.json hooks.unix.json

# Use the PowerShell config
Rename-Item .cursor\hooks.windows.json hooks.json
```

The `.cursor/hooks.windows.json` file uses PowerShell to execute the `.ps1` hook scripts directly.

---

## What Each Hook Does

### PreToolUse Hook

**Triggers:** Before Write, Edit, Shell, or Read operations

**What it does:** Reads the first 30 lines of `task_plan.md` and logs them to stderr for context. Always returns `{"decision": "allow"}` — it never blocks tools.

**Claude Code equivalent:** `cat task_plan.md 2>/dev/null | head -30 || true`

### PostToolUse Hook

**Triggers:** After Write or Edit operations

**What it does:** Outputs a reminder to update `task_plan.md` if a phase was completed.

**Claude Code equivalent:** `echo '[planning-with-files] File updated...'`

### Stop Hook

**Triggers:** When the agent tries to stop working

**What it does:**
1. Counts total phases (`### Phase` headers) in `task_plan.md`
2. Counts completed phases (supports both `**Status:** complete` and `[complete]` formats)
3. If incomplete, returns `followup_message` to auto-continue
4. Capped at 3 retries via `loop_limit` to prevent infinite loops

**Claude Code equivalent:** `scripts/check-complete.sh` — but Cursor's version is **more powerful** because it can auto-continue the agent instead of just reporting status.

---

## Skill Files

The `.cursor/skills/planning-with-files/SKILL.md` file contains all the planning guidelines:

- Core 3-file planning pattern
- Templates (task_plan.md, findings.md, progress.md)
- The 2-Action Rule
- The 3-Strike Error Protocol
- Read vs Write Decision Matrix

Cursor automatically loads skills from `.cursor/skills/` when you open a project.

---

## Templates

The templates in `.cursor/skills/planning-with-files/templates/` are used when starting a new task:

- `task_plan.md` - Phase tracking template
- `findings.md` - Research storage template
- `progress.md` - Session logging template

The agent copies these to your project root when starting a new planning session.

---

## Tips for Cursor Users

1. **Pin the planning files:** Keep task_plan.md open in a split view for easy reference.

2. **Trust the hooks:** The stop hook will prevent premature completion — you don't need to manually verify phase status.

3. **Use explicit prompts for complex tasks:**
   ```
   This is a complex task. Let's use the planning-with-files pattern.
   Start by creating task_plan.md with the goal and phases.
   ```

4. **Check hook logs:** If hooks aren't working, check Cursor's output panel for hook execution logs.

---

## Compatibility with Claude Code

Your planning files (task_plan.md, findings.md, progress.md) are fully compatible between Cursor and Claude Code. You can switch between them without any changes to your planning files.

---

## Need Help?

Open an issue at [github.com/OthmanAdi/planning-with-files/issues](https://github.com/OthmanAdi/planning-with-files/issues).