docs/cursor.md
How to use planning-with-files with Cursor IDE — now with full hook support.
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.
.cursor/skills/planning-with-files/ to your project.cursor/hooks.json to your project.cursor/hooks/ directory to your projectCursor 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 |
The stop hook is the most powerful feature. When the agent tries to stop:
task_plan.md for phase completion statusfollowup_message that auto-prompts the agent to keep workingThis means the agent cannot stop until all phases are done (up to loop_limit of 3 retries).
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
└── ...
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.
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
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...'
Triggers: When the agent tries to stop working
What it does:
### Phase headers) in task_plan.md**Status:** complete and [complete] formats)followup_message to auto-continueloop_limit to prevent infinite loopsClaude 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.
The .cursor/skills/planning-with-files/SKILL.md file contains all the planning guidelines:
Cursor automatically loads skills from .cursor/skills/ when you open a project.
The templates in .cursor/skills/planning-with-files/templates/ are used when starting a new task:
task_plan.md - Phase tracking templatefindings.md - Research storage templateprogress.md - Session logging templateThe agent copies these to your project root when starting a new planning session.
Pin the planning files: Keep task_plan.md open in a split view for easy reference.
Trust the hooks: The stop hook will prevent premature completion — you don't need to manually verify phase status.
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.
Check hook logs: If hooks aren't working, check Cursor's output panel for hook execution logs.
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.
Open an issue at github.com/OthmanAdi/planning-with-files/issues.