Initial commit: Flutter 无书应用项目

.trae/skills/planning-with-files/docs/cursor.md

@@ -0,0 +1,173 @@
+# 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).