fix: clarify working directory for planning files (v2.0.1)

- Add 'Important: Where Files Go' section to SKILL.md
- Update Quick Start with explicit 'in your project' instructions
- Add troubleshooting section to README
- Bump version to 2.0.1

Fixes #11

.cursor/rules/planning-with-files.mdc

@@ -0,0 +1,159 @@
+---
+description: Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use for multi-step tasks, research, or anything requiring >5 tool calls.
+globs:
+alwaysApply: false
+---
+
+# Planning with Files
+
+Work like Manus: Use persistent markdown files as your "working memory on disk."
+
+## Quick Start
+
+Before ANY complex task:
+
+1. **Create `task_plan.md`** — Phase tracking and progress
+2. **Create `findings.md`** — Research and discoveries
+3. **Create `progress.md`** — Session log and test results
+4. **Re-read plan before decisions** — Refreshes goals in attention window
+5. **Update after each phase** — Mark complete, log errors
+
+## The Core Pattern
+
+```
+Context Window = RAM (volatile, limited)
+Filesystem = Disk (persistent, unlimited)
+
+→ Anything important gets written to disk.
+```
+
+## File Purposes
+
+| File | Purpose | When to Update |
+|------|---------|----------------|
+| `task_plan.md` | Phases, progress, decisions | After each phase |
+| `findings.md` | Research, discoveries | After ANY discovery |
+| `progress.md` | Session log, test results | Throughout session |
+
+## Critical Rules
+
+### 1. Create Plan First
+Never start a complex task without `task_plan.md`. Non-negotiable.
+
+### 2. The 2-Action Rule
+> "After every 2 view/browser/search operations, IMMEDIATELY save key findings to text files."
+
+This prevents visual/multimodal information from being lost.
+
+### 3. Read Before Decide
+Before major decisions, read the plan file. This keeps goals in your attention window.
+
+### 4. Update After Act
+After completing any phase:
+- Mark phase status: `in_progress` → `complete`
+- Log any errors encountered
+- Note files created/modified
+
+### 5. Log ALL Errors
+Every error goes in the plan file. This builds knowledge and prevents repetition.
+
+```markdown
+## Errors Encountered
+| Error | Attempt | Resolution |
+|-------|---------|------------|
+| FileNotFoundError | 1 | Created default config |
+| API timeout | 2 | Added retry logic |
+```
+
+### 6. Never Repeat Failures
+```
+if action_failed:
+    next_action != same_action
+```
+Track what you tried. Mutate the approach.
+
+## The 3-Strike Error Protocol
+
+```
+ATTEMPT 1: Diagnose & Fix
+  → Read error carefully
+  → Identify root cause
+  → Apply targeted fix
+
+ATTEMPT 2: Alternative Approach
+  → Same error? Try different method
+  → Different tool? Different library?
+  → NEVER repeat exact same failing action
+
+ATTEMPT 3: Broader Rethink
+  → Question assumptions
+  → Search for solutions
+  → Consider updating the plan
+
+AFTER 3 FAILURES: Escalate to User
+  → Explain what you tried
+  → Share the specific error
+  → Ask for guidance
+```
+
+## Read vs Write Decision Matrix
+
+| Situation | Action | Reason |
+|-----------|--------|--------|
+| Just wrote a file | DON'T read | Content still in context |
+| Viewed image/PDF | Write findings NOW | Multimodal → text before lost |
+| Browser returned data | Write to file | Screenshots don't persist |
+| Starting new phase | Read plan/findings | Re-orient if context stale |
+| Error occurred | Read relevant file | Need current state to fix |
+| Resuming after gap | Read all planning files | Recover state |
+
+## The 5-Question Reboot Test
+
+If you can answer these, your context management is solid:
+
+| Question | Answer Source |
+|----------|---------------|
+| Where am I? | Current phase in task_plan.md |
+| Where am I going? | Remaining phases |
+| What's the goal? | Goal statement in plan |
+| What have I learned? | findings.md |
+| What have I done? | progress.md |
+
+## Manus Principles
+
+### Principle 1: Filesystem as External Memory
+Store large content in files, keep only paths in context. Agent can "look up" information when needed.
+
+### Principle 2: Attention Manipulation
+After ~50 tool calls, models forget original goals ("lost in the middle" effect). Re-reading `task_plan.md` brings goals back into the attention window.
+
+### Principle 3: Keep Failure Traces
+Keep failed actions in the plan file. The model updates its understanding when seeing failures. Error recovery is "one of the clearest signals of TRUE agentic behavior."
+
+### Principle 4: Avoid Few-Shot Overfitting
+Vary phrasings slightly. Don't copy-paste patterns blindly. Uniformity breeds fragility.
+
+## When to Use This Pattern
+
+**Use for:**
+- Multi-step tasks (3+ steps)
+- Research tasks
+- Building/creating projects
+- Tasks spanning many tool calls
+- Anything requiring organization
+
+**Skip for:**
+- Simple questions
+- Single-file edits
+- Quick lookups
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Use TodoWrite for persistence | Create task_plan.md file |
+| State goals once and forget | Re-read plan before decisions |
+| Hide errors and retry silently | Log errors to plan file |
+| Stuff everything in context | Store large content in files |
+| Start executing immediately | Create plan file FIRST |
+| Repeat failed actions | Track attempts, mutate approach |

.gitignore

@@ -14,9 +14,10 @@ task_plan.md
 research_notes.md
 notes.md
 
-# But keep example task files
+# But keep example and template files
 !examples/*.md
 !examples/**/*.md
+!**/templates/*.md
 
 # Keep the skill folder clean
 *.log

README.md

@@ -15,7 +15,15 @@ A Claude Code plugin containing an [Agent Skill](https://code.claude.com/docs/en
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-Plugin-blue)](https://code.claude.com/docs/en/plugins)
 [![Claude Code Skill](https://img.shields.io/badge/Claude%20Code-Skill-green)](https://code.claude.com/docs/en/skills)
-[![Version](https://img.shields.io/badge/version-2.0.0-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)
+[![Cursor Rules](https://img.shields.io/badge/Cursor-Rules-purple)](https://docs.cursor.com/context/rules-for-ai)
+[![Version](https://img.shields.io/badge/version-2.0.1-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)
+
+## Versions
+
+| Version | Branch | Features | Install |
+|---------|--------|----------|---------|
+| **v2.0.0** (current) | `master` | Hooks, templates, scripts | `/plugin install planning-with-files@planning-with-files` |
+| **v1.0.0** (legacy) | `legacy` | Core 3-file pattern | `git clone -b legacy https://github.com/OthmanAdi/planning-with-files.git` |
 
 ## What's New in v2.0.0
 
@@ -100,6 +108,29 @@ git clone https://github.com/OthmanAdi/planning-with-files.git
 cp -r planning-with-files/skills/* ~/.claude/skills/
 ```
 
+### Cursor Installation
+
+Copy the `.cursor/rules/` directory into your project:
+
+```bash
+git clone https://github.com/OthmanAdi/planning-with-files.git
+cp -r planning-with-files/.cursor .cursor
+```
+
+Or manually create `.cursor/rules/planning-with-files.mdc` in your project with the content from this repo.
+
+> **Note:** Hooks (PreToolUse, Stop) are Claude Code specific and won't work in Cursor. The core planning workflow still applies.
+
+### One-Line Installer (Skills Only)
+
+Extract just the skill directly into your current directory:
+
+```bash
+curl -L https://github.com/OthmanAdi/planning-with-files/archive/master.tar.gz | tar -xzv --strip-components=2 "planning-with-files-master/skills/planning-with-files"
+```
+
+Then move `planning-with-files/` to `~/.claude/skills/`.
+
 ## Usage
 
 Once installed, Claude will automatically:
@@ -118,6 +149,74 @@ Once installed, Claude will automatically:
 3. **Log ALL Errors** — They help avoid repetition
 4. **Never Repeat Failures** — Track attempts, mutate approach
 
+## Troubleshooting
+
+### Planning files created in wrong directory
+
+**Issue:** When using `/plan`, the files (`task_plan.md`, `findings.md`, `progress.md`) are created in the skill installation directory instead of your project.
+
+**Why this happens:** When the skill runs as a subagent, it may not inherit your terminal's current working directory.
+
+**Solutions:**
+
+1. **Specify your project path when invoking:**
+   ```
+   /plan - I'm working in /path/to/my-project/, create all files there
+   ```
+
+2. **Add context before invoking:**
+   ```
+   I'm working on the project at /path/to/my-project/
+   ```
+   Then run `/plan`.
+
+3. **Create a CLAUDE.md in your project root:**
+   ```markdown
+   # Project Context
+
+   All planning files (task_plan.md, findings.md, progress.md)
+   should be created in this directory.
+   ```
+
+4. **Use the skill directly without subagent:**
+   ```
+   Help me plan this task using the planning-with-files approach.
+   Create task_plan.md, findings.md, and progress.md here.
+   ```
+
+**Fixed in v2.0.1:** The skill instructions now explicitly specify that planning files should be created in your project directory, not the skill installation folder.
+
+---
+
+### Files not persisting between sessions
+
+**Issue:** Planning files seem to disappear or aren't found when resuming work.
+
+**Solution:** Make sure the files are in your project root, not in a temporary location. Check with:
+```bash
+ls -la task_plan.md findings.md progress.md
+```
+
+---
+
+### Hooks not triggering
+
+**Issue:** The PreToolUse hook (which reads task_plan.md before actions) doesn't seem to run.
+
+**Solution:**
+1. Ensure you're using Claude Code v1.0.18 or later
+2. Verify the skill is installed correctly: `ls ~/.claude/skills/planning-with-files/`
+3. Check that `task_plan.md` exists in your current directory
+
+---
+
+### Need help?
+
+Open an issue at [github.com/OthmanAdi/planning-with-files/issues](https://github.com/OthmanAdi/planning-with-files/issues) with:
+- Your Claude Code version (`claude --version`)
+- The command you ran
+- What happened vs what you expected
+
 ## File Structure
 
 ```
@@ -125,6 +224,9 @@ planning-with-files/
 ├── .claude-plugin/
 │   ├── plugin.json          # Plugin manifest
 │   └── marketplace.json     # Marketplace listing
+├── .cursor/
+│   └── rules/
+│       └── planning-with-files.mdc  # Cursor rules file
 ├── skills/
 │   └── planning-with-files/
 │       ├── SKILL.md         # Main skill definition

skills/planning-with-files/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: planning-with-files
-version: "2.0.0"
+version: "2.0.1"
 description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls.
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch
 hooks:
@@ -19,16 +19,32 @@ hooks:
 
 Work like Manus: Use persistent markdown files as your "working memory on disk."
 
+## Important: Where Files Go
+
+When using this skill:
+
+- **Templates** are stored in the skill directory at `${CLAUDE_PLUGIN_ROOT}/templates/`
+- **Your planning files** (`task_plan.md`, `findings.md`, `progress.md`) should be created in **your project directory** — the folder where you're working
+
+| Location | What Goes There |
+|----------|-----------------|
+| Skill directory (`${CLAUDE_PLUGIN_ROOT}/`) | Templates, scripts, reference docs |
+| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
+
+This ensures your planning files live alongside your code, not buried in the skill installation folder.
+
 ## Quick Start
 
 Before ANY complex task:
 
-1. **Create `task_plan.md`** — See [templates/task_plan.md](templates/task_plan.md)
-2. **Create `findings.md`** — See [templates/findings.md](templates/findings.md)
-3. **Create `progress.md`** — See [templates/progress.md](templates/progress.md)
+1. **Create `task_plan.md`** in your project — Use [templates/task_plan.md](templates/task_plan.md) as reference
+2. **Create `findings.md`** in your project — Use [templates/findings.md](templates/findings.md) as reference
+3. **Create `progress.md`** in your project — Use [templates/progress.md](templates/progress.md) as reference
 4. **Re-read plan before decisions** — Refreshes goals in attention window
 5. **Update after each phase** — Mark complete, log errors
 
+> **Note:** All three planning files should be created in your current working directory (your project root), not in the skill's installation folder.
+
 ## The Core Pattern
 
 ```
@@ -174,3 +190,4 @@ Helper scripts for automation:
 | Stuff everything in context | Store large content in files |
 | Start executing immediately | Create plan file FIRST |
 | Repeat failed actions | Track attempts, mutate approach |
+| Create files in skill directory | Create files in your project |

skills/planning-with-files/scripts/check-complete.sh

@@ -3,8 +3,6 @@
 # Exit 0 if complete, exit 1 if incomplete
 # Used by Stop hook to verify task completion
 
-set -e
-
 PLAN_FILE="${1:-task_plan.md}"
 
 if [ ! -f "$PLAN_FILE" ]; then
@@ -16,11 +14,17 @@ fi
 echo "=== Task Completion Check ==="
 echo ""
 
-# Count phases by status
-TOTAL=$(grep -c "### Phase" "$PLAN_FILE" 2>/dev/null || echo "0")
-COMPLETE=$(grep -c "Status:\*\* complete" "$PLAN_FILE" 2>/dev/null || echo "0")
-IN_PROGRESS=$(grep -c "Status:\*\* in_progress" "$PLAN_FILE" 2>/dev/null || echo "0")
-PENDING=$(grep -c "Status:\*\* pending" "$PLAN_FILE" 2>/dev/null || echo "0")
+# Count phases by status (using -F for fixed string matching)
+TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
+COMPLETE=$(grep -cF "**Status:** complete" "$PLAN_FILE" || true)
+IN_PROGRESS=$(grep -cF "**Status:** in_progress" "$PLAN_FILE" || true)
+PENDING=$(grep -cF "**Status:** pending" "$PLAN_FILE" || true)
+
+# Default to 0 if empty
+: "${TOTAL:=0}"
+: "${COMPLETE:=0}"
+: "${IN_PROGRESS:=0}"
+: "${PENDING:=0}"
 
 echo "Total phases:   $TOTAL"
 echo "Complete:       $COMPLETE"
@@ -31,20 +35,10 @@ echo ""
 # Check completion
 if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
     echo "ALL PHASES COMPLETE"
-    echo ""
-    echo "5-Question Reboot Test:"
-    echo "  Where am I? → All phases done"
-    echo "  Where am I going? → Delivery"
-    echo "  What's the goal? → Check task_plan.md"
-    echo "  What have I learned? → See findings.md"
-    echo "  What have I done? → See progress.md"
     exit 0
 else
     echo "TASK NOT COMPLETE"
     echo ""
-    echo "Incomplete phases:"
-    grep -B1 "Status:\*\* pending\|Status:\*\* in_progress" "$PLAN_FILE" | grep "### Phase" || echo "  (none found)"
-    echo ""
     echo "Do not stop until all phases are complete."
     exit 1
 fi

skills/planning-with-files/templates/task_plan.md

@@ -0,0 +1,58 @@
+# Task Plan: [Brief Description]
+
+## Goal
+[One sentence describing the end state]
+
+## Current Phase
+Phase 1
+
+## Phases
+
+### Phase 1: Requirements & Discovery
+- [ ] Understand user intent
+- [ ] Identify constraints and requirements
+- [ ] Document findings in notes.md
+- **Status:** in_progress
+
+### Phase 2: Planning & Structure
+- [ ] Define technical approach
+- [ ] Create project structure if needed
+- [ ] Document decisions with rationale
+- **Status:** pending
+
+### Phase 3: Implementation
+- [ ] Execute the plan step by step
+- [ ] Write code to files before executing
+- [ ] Test incrementally
+- **Status:** pending
+
+### Phase 4: Testing & Verification
+- [ ] Verify all requirements met
+- [ ] Document test results in progress.md
+- [ ] Fix any issues found
+- **Status:** pending
+
+### Phase 5: Delivery
+- [ ] Review all output files
+- [ ] Ensure deliverables are complete
+- [ ] Deliver to user
+- **Status:** pending
+
+## Key Questions
+1. [Question to answer]
+2. [Question to answer]
+
+## Decisions Made
+| Decision | Rationale |
+|----------|-----------|
+|          |           |
+
+## Errors Encountered
+| Error | Attempt | Resolution |
+|-------|---------|------------|
+|       | 1       |            |
+
+## Notes
+- Update phase status as you progress: pending → in_progress → complete
+- Re-read this plan before major decisions (attention manipulation)
+- Log ALL errors - they help avoid repetition