Cursor IDE Setup

Cursor IDE Setup

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

Installation

Option 1: Copy .cursor directory (Recommended)

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:

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:

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