feat: v2.1.0 - Claude Code v2.1 compatibility + docs restructure

- Add SessionStart hook for skill ready notification - Add PostToolUse hook for phase completion reminders - Add user-invocable: true for slash menu visibility - Convert allowed-tools to YAML list format - Create docs/ folder with organized documentation - Refactor README to be cleaner with docs links - Update version to 2.1.0 in all manifests
Add Community Forks section with multi-manus-planning
2026-01-10 17:21:15 +01:00 · 2026-01-09 14:33:07 +01:00 · 2026-01-09 14:29:34 +01:00 · 2026-01-09 14:26:49 +01:00 · 2026-01-09 13:27:56 +01:00 · 2026-01-09 17:46:53 +07:00
17 changed files with 2233 additions and 100 deletions
@@ -1,6 +1,6 @@
 {
  "name": "planning-with-files",
-  "version": "2.0.0",
+  "version": "2.1.0",
  "description": "Manus-style persistent markdown files for planning, progress tracking, and knowledge storage. Includes hooks for automatic plan re-reading and completion verification. Use when starting complex tasks, multi-step projects, research tasks, or when you want structured output.",
  "author": {
    "name": "OthmanAdi",
@@ -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 |
@@ -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
@@ -2,6 +2,56 @@

 All notable changes to this project will be documented in this file.

+## [2.1.0] - 2026-01-10
+
+### Added
+
+- **Claude Code v2.1 Compatibility**
+  - Updated skill to leverage all new Claude Code v2.1 features
+  - Requires Claude Code v2.1.0 or later
+
+- **`user-invocable: true` Frontmatter**
+  - Skill now appears in slash command menu
+  - Users can manually invoke with `/planning-with-files`
+  - Auto-detection still works as before
+
+- **`SessionStart` Hook**
+  - Notifies user when skill is loaded and ready
+  - Displays message at session start confirming skill availability
+
+- **`PostToolUse` Hook**
+  - Runs after every Write/Edit operation
+  - Reminds Claude to update `task_plan.md` if a phase was completed
+  - Helps prevent forgotten status updates
+
+- **YAML List Format for `allowed-tools`**
+  - Migrated from comma-separated string to YAML list syntax
+  - Cleaner, more maintainable frontmatter
+  - Follows Claude Code v2.1 best practices
+
+### Changed
+
+- Version bumped to 2.1.0 in SKILL.md, plugin.json, and README.md
+- README.md updated with v2.1.0 features section
+- Versions table updated to reflect new release
+
+### Compatibility
+
+- **Minimum Claude Code Version:** v2.1.0
+- **Backward Compatible:** Yes (works with older Claude Code, but new hooks may not fire)
+
+## [2.0.1] - 2026-01-09
+
+### Fixed
+
+- Planning files now correctly created in project directory, not skill installation folder
+- Added "Important: Where Files Go" section to SKILL.md
+- Added Troubleshooting section to README.md
+
+### Thanks
+
+- @wqh17101 for reporting and confirming the fix
+
 ## [2.0.0] - 2026-01-08

 ### Added
@@ -10,28 +10,48 @@ If this skill helps you work smarter, that's all I wanted.

 ---

-A Claude Code plugin containing an [Agent Skill](https://code.claude.com/docs/en/skills) that transforms your workflow to use persistent markdown files for planning, progress tracking, and knowledge storage — the exact pattern that made Manus worth billions.
+A Claude Code plugin that transforms your workflow to use persistent markdown files for planning, progress tracking, and knowledge storage — the exact pattern that made Manus worth billions.

 [![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.1.0-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)

-## What's New in v2.0.0
+## Quick Install

- **Hooks Integration** — Automatic plan re-reading and completion verification
- **Templates** — Structured templates for task_plan.md, findings.md, progress.md
- **Scripts** — Helper scripts for initialization and completion checks
- **Enhanced Documentation** — 2-Action Rule, 3-Strike Protocol, 5-Question Reboot Test
+```bash
+/plugin marketplace add OthmanAdi/planning-with-files
+/plugin install planning-with-files@planning-with-files
+```

-See [CHANGELOG.md](CHANGELOG.md) for details. Upgrading from v1.x? See [MIGRATION.md](MIGRATION.md).
+See [docs/installation.md](docs/installation.md) for all installation methods.
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Installation Guide](docs/installation.md) | All installation methods (plugin, manual, Cursor, Windows) |
+| [Quick Start](docs/quickstart.md) | 5-step guide to using the pattern |
+| [Workflow Diagram](docs/workflow.md) | Visual diagram of how files and hooks interact |
+| [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions |
+| [Cursor Setup](docs/cursor.md) | Cursor IDE-specific instructions |
+| [Windows Setup](docs/windows.md) | Windows-specific notes |
+
+## Versions
+
+| Version | Features | Install |
+|---------|----------|---------|
+| **v2.1.0** (current) | Claude Code v2.1 compatible, SessionStart hook, PostToolUse hook, user-invocable | `/plugin install planning-with-files@planning-with-files` |
+| **v2.0.x** | Hooks, templates, scripts | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
+| **v1.0.0** (legacy) | Core 3-file pattern | `git clone -b legacy` |
+
+See [CHANGELOG.md](CHANGELOG.md) for details.

 ## Why This Skill?

 On December 29, 2025, [Meta acquired Manus for $2 billion](https://techcrunch.com/2025/12/29/meta-just-bought-manus-an-ai-startup-everyone-has-been-talking-about/). In just 8 months, Manus went from launch to $100M+ revenue. Their secret? **Context engineering**.

-This skill implements Manus's core workflow pattern:
-
 > "Markdown is my 'working memory' on disk. Since I process information iteratively and my active context has limits, Markdown files serve as scratch pads for notes, checkpoints for progress, building blocks for final deliverables."
 > — Manus AI

@@ -63,55 +83,22 @@ Filesystem = Disk (persistent, unlimited)
 → Anything important gets written to disk.
 ```

-## Installation
-
-### As a Claude Code Plugin (Recommended)
-
-Install directly using the Claude Code CLI:
-
-```
-/plugin marketplace add OthmanAdi/planning-with-files
-/plugin install planning-with-files@planning-with-files
-```
-
-### Manual Installation
-
-Clone or copy this repository into your project's `.claude/plugins/` directory:
-
-```bash
-# Option 1: Clone into plugins directory
-mkdir -p .claude/plugins
-git clone https://github.com/OthmanAdi/planning-with-files.git .claude/plugins/planning-with-files
-
-# Option 2: Add as git submodule
-git submodule add https://github.com/OthmanAdi/planning-with-files.git .claude/plugins/planning-with-files
-
-# Option 3: Use --plugin-dir flag
-git clone https://github.com/OthmanAdi/planning-with-files.git
-claude --plugin-dir ./planning-with-files
-```
-
-### Legacy Installation (Skills Only)
-
-Copy the `skills/` directory contents into your `.claude/skills/` folder:
-
-```bash
-git clone https://github.com/OthmanAdi/planning-with-files.git
-cp -r planning-with-files/skills/* ~/.claude/skills/
-```
-
 ## Usage

 Once installed, Claude will automatically:

 1. **Create `task_plan.md`** before starting complex tasks
-2. **Re-read plan** before major decisions (via hooks)
-3. **Update progress** with checkboxes after each phase
+2. **Re-read plan** before major decisions (via PreToolUse hook)
+3. **Remind you** to update status after file writes (via PostToolUse hook)
 4. **Store findings** in `findings.md` instead of stuffing context
 5. **Log errors** for future reference
-6. **Verify completion** before stopping (via hooks)
+6. **Verify completion** before stopping (via Stop hook)

-### Key Rules
+Or invoke manually with `/planning-with-files`.
+
+See [docs/quickstart.md](docs/quickstart.md) for the full 5-step guide.
+
+## Key Rules

 1. **Create Plan First** — Never start without `task_plan.md`
 2. **The 2-Action Rule** — Save findings after every 2 view/browser operations
@@ -122,31 +109,28 @@ Once installed, Claude will automatically:

 ```
 planning-with-files/
-├── .claude-plugin/
-│   ├── plugin.json          # Plugin manifest
-│   └── marketplace.json     # Marketplace listing
+├── docs/                    # Documentation
+│   ├── installation.md
+│   ├── quickstart.md
+│   ├── workflow.md
+│   ├── troubleshooting.md
+│   ├── cursor.md
+│   └── windows.md
 ├── skills/
 │   └── planning-with-files/
 │       ├── SKILL.md         # Main skill definition
-│       ├── reference.md     # Manus principles
-│       ├── examples.md      # Usage examples
 │       ├── templates/       # File templates
-│       │   ├── task_plan.md
-│       │   ├── findings.md
-│       │   └── progress.md
 │       └── scripts/         # Helper scripts
-│           ├── init-session.sh
-│           └── check-complete.sh
-├── CHANGELOG.md             # Version history
-├── MIGRATION.md             # Upgrade guide
+├── .claude-plugin/          # Plugin manifest
+├── .cursor/                 # Cursor rules
+├── CHANGELOG.md
+├── MIGRATION.md
 ├── LICENSE
 └── README.md
 ```

 ## The Manus Principles

-This skill implements these key context engineering principles:
-
 | Principle | Implementation |
 |-----------|----------------|
 | Filesystem as memory | Store in files, not context |
@@ -162,13 +146,20 @@ This skill implements these key context engineering principles:
 - Research tasks
 - Building/creating projects
 - Tasks spanning many tool calls
- Anything requiring organization

 **Skip for:**
 - Simple questions
 - Single-file edits
 - Quick lookups

+## Community Forks
+
+| Fork | Author | Features |
+|------|--------|----------|
+| [multi-manus-planning](https://github.com/kmichels/multi-manus-planning) | [@kmichels](https://github.com/kmichels) | Multi-project support, SessionStart git sync |
+
+*Built something? Open an issue to get listed!*
+
 ## Acknowledgments

 - **Manus AI** — For pioneering context engineering patterns
@@ -0,0 +1,144 @@
+# Cursor IDE Setup
+
+How to use planning-with-files with Cursor IDE.
+
+---
+
+## Installation
+
+### Option 1: Copy rules directory
+
+```bash
+git clone https://github.com/OthmanAdi/planning-with-files.git
+cp -r planning-with-files/.cursor .cursor
+```
+
+### Option 2: Manual setup
+
+Create `.cursor/rules/planning-with-files.mdc` in your project with the content from this repo.
+
+---
+
+## Important Limitations
+
+> **Note:** Hooks (PreToolUse, PostToolUse, Stop, SessionStart) are **Claude Code specific** and will NOT work in Cursor.
+
+### What works in Cursor:
+
+- Core 3-file planning pattern
+- Templates (task_plan.md, findings.md, progress.md)
+- All planning rules and guidelines
+- The 2-Action Rule
+- The 3-Strike Error Protocol
+- Read vs Write Decision Matrix
+
+### What doesn't work in Cursor:
+
+- SessionStart hook (no startup notification)
+- PreToolUse hook (no automatic plan re-reading)
+- PostToolUse hook (no automatic reminders)
+- Stop hook (no automatic completion verification)
+
+---
+
+## Manual Workflow for Cursor
+
+Since hooks don't work in Cursor, you'll need to follow the pattern manually:
+
+### 1. Create planning files first
+
+Before any complex task:
+```
+Create task_plan.md, findings.md, and progress.md using the planning-with-files templates.
+```
+
+### 2. Re-read plan before decisions
+
+Periodically ask:
+```
+Please read task_plan.md to refresh the goals before continuing.
+```
+
+### 3. Update files after phases
+
+After completing work:
+```
+Update task_plan.md to mark this phase complete.
+Update progress.md with what was done.
+```
+
+### 4. Verify completion manually
+
+Before finishing:
+```
+Check task_plan.md - are all phases marked complete?
+```
+
+---
+
+## Cursor Rules File
+
+The `.cursor/rules/planning-with-files.mdc` file contains all the planning guidelines formatted for Cursor's rules system.
+
+### File location
+
+```
+your-project/
+├── .cursor/
+│   └── rules/
+│       └── planning-with-files.mdc
+├── task_plan.md
+├── findings.md
+├── progress.md
+└── ...
+```
+
+### Activating rules
+
+Cursor automatically loads rules from `.cursor/rules/` when you open a project.
+
+---
+
+## Templates
+
+The templates in `skills/planning-with-files/templates/` work in Cursor:
+
+- `task_plan.md` - Phase tracking template
+- `findings.md` - Research storage template
+- `progress.md` - Session logging template
+
+Copy them to your project root when starting a new task.
+
+---
+
+## Tips for Cursor Users
+
+1. **Pin the planning files:** Keep task_plan.md open in a split view for easy reference.
+
+2. **Add to .cursorrules:** You can also add planning guidelines to your project's `.cursorrules` file.
+
+3. **Use explicit prompts:** Since there's no auto-detection, be explicit:
+   ```
+   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 status regularly:** Without the Stop hook, manually verify completion before finishing.
+
+---
+
+## Migrating from Cursor to Claude Code
+
+If you want full hook support, consider using Claude Code CLI:
+
+1. Install Claude Code
+2. Run `/plugin install planning-with-files@planning-with-files`
+3. All hooks will work automatically
+
+Your existing planning files (task_plan.md, etc.) are compatible with both.
+
+---
+
+## Need Help?
+
+Open an issue at [github.com/OthmanAdi/planning-with-files/issues](https://github.com/OthmanAdi/planning-with-files/issues).
@@ -0,0 +1,160 @@
+# Installation Guide
+
+Complete installation instructions for planning-with-files.
+
+## Quick Install (Recommended)
+
+```bash
+/plugin marketplace add OthmanAdi/planning-with-files
+/plugin install planning-with-files@planning-with-files
+```
+
+That's it! The skill is now active.
+
+---
+
+## Installation Methods
+
+### 1. Claude Code Plugin (Recommended)
+
+Install directly using the Claude Code CLI:
+
+```bash
+/plugin marketplace add OthmanAdi/planning-with-files
+/plugin install planning-with-files@planning-with-files
+```
+
+**Advantages:**
+- Automatic updates
+- Proper hook integration
+- Full feature support
+
+---
+
+### 2. Manual Installation
+
+Clone or copy this repository into your project's `.claude/plugins/` directory:
+
+#### Option A: Clone into plugins directory
+
+```bash
+mkdir -p .claude/plugins
+git clone https://github.com/OthmanAdi/planning-with-files.git .claude/plugins/planning-with-files
+```
+
+#### Option B: Add as git submodule
+
+```bash
+git submodule add https://github.com/OthmanAdi/planning-with-files.git .claude/plugins/planning-with-files
+```
+
+#### Option C: Use --plugin-dir flag
+
+```bash
+git clone https://github.com/OthmanAdi/planning-with-files.git
+claude --plugin-dir ./planning-with-files
+```
+
+---
+
+### 3. Legacy Installation (Skills Only)
+
+If you only want the skill without the full plugin structure:
+
+```bash
+git clone https://github.com/OthmanAdi/planning-with-files.git
+cp -r planning-with-files/skills/* ~/.claude/skills/
+```
+
+---
+
+### 4. 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/`.
+
+---
+
+## Verifying Installation
+
+After installation, verify the skill is loaded:
+
+1. Start a new Claude Code session
+2. You should see: `[planning-with-files] Ready. Auto-activates for complex tasks, or invoke manually with /planning-with-files`
+3. Or type `/planning-with-files` to manually invoke
+
+---
+
+## Updating
+
+### Plugin Installation
+
+```bash
+/plugin update planning-with-files@planning-with-files
+```
+
+### Manual Installation
+
+```bash
+cd .claude/plugins/planning-with-files
+git pull origin master
+```
+
+### Skills Only
+
+```bash
+cd ~/.claude/skills/planning-with-files
+git pull origin master
+```
+
+---
+
+## Uninstalling
+
+### Plugin
+
+```bash
+/plugin uninstall planning-with-files@planning-with-files
+```
+
+### Manual
+
+```bash
+rm -rf .claude/plugins/planning-with-files
+```
+
+### Skills Only
+
+```bash
+rm -rf ~/.claude/skills/planning-with-files
+```
+
+---
+
+## Requirements
+
+- **Claude Code:** v2.1.0 or later (for full hook support)
+- **Older versions:** Core functionality works, but hooks may not fire
+
+---
+
+## Platform-Specific Notes
+
+### Windows
+
+See [docs/windows.md](windows.md) for Windows-specific installation notes.
+
+### Cursor
+
+See [docs/cursor.md](cursor.md) for Cursor IDE installation.
+
+---
+
+## Need Help?
+
+If installation fails, check [docs/troubleshooting.md](troubleshooting.md) or open an issue at [github.com/OthmanAdi/planning-with-files/issues](https://github.com/OthmanAdi/planning-with-files/issues).
@@ -0,0 +1,162 @@
+# Quick Start Guide
+
+Follow these 5 steps to use the planning-with-files pattern.
+
+---
+
+## Step 1: Create Your Planning Files
+
+**When:** Before starting any work on a complex task
+
+**Action:** Create all three files using the templates:
+
+```bash
+# Option 1: Use the init script (if available)
+./scripts/init-session.sh
+
+# Option 2: Copy templates manually
+cp templates/task_plan.md task_plan.md
+cp templates/findings.md findings.md
+cp templates/progress.md progress.md
+```
+
+**Update:** Fill in the Goal section in `task_plan.md` with your task description.
+
+---
+
+## Step 2: Plan Your Phases
+
+**When:** Right after creating the files
+
+**Action:** Break your task into 3-7 phases in `task_plan.md`
+
+**Example:**
+```markdown
+### Phase 1: Requirements & Discovery
+- [ ] Understand user intent
+- [ ] Research existing solutions
+- **Status:** in_progress
+
+### Phase 2: Implementation
+- [ ] Write core code
+- **Status:** pending
+```
+
+**Update:**
+- `task_plan.md`: Define your phases
+- `progress.md`: Note that planning is complete
+
+---
+
+## Step 3: Work and Document
+
+**When:** Throughout the task
+
+**Action:** As you work, update files:
+
+| What Happens | Which File to Update | What to Add |
+|--------------|---------------------|-------------|
+| You research something | `findings.md` | Add to "Research Findings" |
+| You view 2 browser/search results | `findings.md` | **MUST update** (2-Action Rule) |
+| You make a technical decision | `findings.md` | Add to "Technical Decisions" with rationale |
+| You complete a phase | `task_plan.md` | Change status: `in_progress` → `complete` |
+| You complete a phase | `progress.md` | Log actions taken, files modified |
+| An error occurs | `task_plan.md` | Add to "Errors Encountered" table |
+| An error occurs | `progress.md` | Add to "Error Log" with timestamp |
+
+**Example workflow:**
+```
+1. Research → Update findings.md
+2. Research → Update findings.md (2nd time - MUST update now!)
+3. Make decision → Update findings.md "Technical Decisions"
+4. Implement code → Update progress.md "Actions taken"
+5. Complete phase → Update task_plan.md status to "complete"
+6. Complete phase → Update progress.md with phase summary
+```
+
+---
+
+## Step 4: Re-read Before Decisions
+
+**When:** Before making major decisions (automatic with hooks in Claude Code)
+
+**Action:** The PreToolUse hook automatically reads `task_plan.md` before Write/Edit/Bash operations
+
+**Manual reminder (if not using hooks):** Before important choices, read `task_plan.md` to refresh your goals
+
+**Why:** After many tool calls, original goals can be forgotten. Re-reading brings them back into attention.
+
+---
+
+## Step 5: Complete and Verify
+
+**When:** When you think the task is done
+
+**Action:** Verify completion:
+
+1. **Check `task_plan.md`**: All phases should have `**Status:** complete`
+2. **Check `progress.md`**: All phases should be logged with actions taken
+3. **Run completion check** (if using hooks, this happens automatically):
+   ```bash
+   ./scripts/check-complete.sh
+   ```
+
+**If not complete:** The Stop hook (or script) will prevent stopping. Continue working until all phases are done.
+
+**If complete:** Deliver your work! All three planning files document your process.
+
+---
+
+## Quick Reference: When to Update Which File
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  task_plan.md                                            │
+│  Update when:                                            │
+│  • Starting task (create it first!)                      │
+│  • Completing a phase (change status)                    │
+│  • Making a major decision (add to Decisions table)     │
+│  • Encountering an error (add to Errors table)          │
+│  • Re-reading before decisions (automatic via hook)      │
+└─────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────┐
+│  findings.md                                             │
+│  Update when:                                            │
+│  • Discovering something new (research, exploration)    │
+│  • After 2 view/browser/search operations (2-Action!)   │
+│  • Making a technical decision (with rationale)          │
+│  • Finding useful resources (URLs, docs)                 │
+│  • Viewing images/PDFs (capture as text immediately!)   │
+└─────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────┐
+│  progress.md                                             │
+│  Update when:                                            │
+│  • Starting a new phase (log start time)                 │
+│  • Completing a phase (log actions, files modified)      │
+│  • Running tests (add to Test Results table)            │
+│  • Encountering errors (add to Error Log with timestamp)│
+│  • Resuming after a break (update 5-Question Check)     │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Common Mistakes to Avoid
+
+| Don't | Do Instead |
+|-------|------------|
+| Start work without creating `task_plan.md` | Always create the plan file first |
+| Forget to update `findings.md` after 2 browser operations | Set a reminder: "2 view/browser ops = update findings.md" |
+| Skip logging errors because you fixed them quickly | Log ALL errors, even ones you resolved immediately |
+| Repeat the same failed action | If something fails, log it and try a different approach |
+| Only update one file | The three files work together - update them as a set |
+
+---
+
+## Next Steps
+
+- See [examples/README.md](../examples/README.md) for complete walkthrough examples
+- See [workflow.md](workflow.md) for the visual workflow diagram
+- See [troubleshooting.md](troubleshooting.md) if you encounter issues
@@ -0,0 +1,207 @@
+# Troubleshooting
+
+Common issues and their solutions.
+
+---
+
+## Planning files created in wrong directory
+
+**Issue:** When using `/planning-with-files`, 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:**
+
+### Solution 1: Specify your project path when invoking
+
+```
+/planning-with-files - I'm working in /path/to/my-project/, create all files there
+```
+
+### Solution 2: Add context before invoking
+
+```
+I'm working on the project at /path/to/my-project/
+```
+Then run `/planning-with-files`.
+
+### Solution 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.
+```
+
+### Solution 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.
+```
+
+**Note:** This was 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
+```
+
+If files are missing, they may have been created in:
+- The skill installation folder (`~/.claude/skills/planning-with-files/`)
+- A temporary directory
+- A different working directory
+
+---
+
+## Hooks not triggering
+
+**Issue:** The PreToolUse hook (which reads task_plan.md before actions) doesn't seem to run.
+
+**Solution:**
+
+1. **Check Claude Code version:**
+   ```bash
+   claude --version
+   ```
+   Hooks require Claude Code v2.1.0 or later for full support.
+
+2. **Verify skill installation:**
+   ```bash
+   ls ~/.claude/skills/planning-with-files/
+   ```
+   or
+   ```bash
+   ls .claude/plugins/planning-with-files/
+   ```
+
+3. **Check that task_plan.md exists:**
+   The PreToolUse hook runs `cat task_plan.md`. If the file doesn't exist, the hook silently succeeds (by design).
+
+4. **Check for YAML errors:**
+   Run Claude Code with debug mode:
+   ```bash
+   claude --debug
+   ```
+   Look for skill loading errors.
+
+---
+
+## SessionStart hook not showing message
+
+**Issue:** The "Ready" message doesn't appear when starting Claude Code.
+
+**Solution:**
+
+1. SessionStart hooks require Claude Code v2.1.0+
+2. The hook only fires once per session
+3. If you've already started a session, restart Claude Code
+
+---
+
+## PostToolUse hook not running
+
+**Issue:** The reminder message after Write/Edit doesn't appear.
+
+**Solution:**
+
+1. PostToolUse hooks require Claude Code v2.1.0+
+2. The hook only fires after successful Write/Edit operations
+3. Check the matcher pattern: it's set to `"Write|Edit"` only
+
+---
+
+## Skill not auto-detecting complex tasks
+
+**Issue:** Claude doesn't automatically use the planning pattern for complex tasks.
+
+**Solution:**
+
+1. **Manually invoke:**
+   ```
+   /planning-with-files
+   ```
+
+2. **Trigger words:** The skill auto-activates based on its description. Try phrases like:
+   - "complex multi-step task"
+   - "research project"
+   - "task requiring many steps"
+
+3. **Be explicit:**
+   ```
+   This is a complex task that will require >5 tool calls.
+   Please use the planning-with-files pattern.
+   ```
+
+---
+
+## Stop hook blocking completion
+
+**Issue:** Claude won't stop because the Stop hook says phases aren't complete.
+
+**Solution:**
+
+1. **Check task_plan.md:** All phases should have `**Status:** complete`
+
+2. **Manual override:** If you need to stop anyway:
+   ```
+   Override the completion check - I want to stop now.
+   ```
+
+3. **Fix the status:** Update incomplete phases to `complete` if they're actually done.
+
+---
+
+## YAML frontmatter errors
+
+**Issue:** Skill won't load due to YAML errors.
+
+**Solution:**
+
+1. **Check indentation:** YAML requires spaces, not tabs
+2. **Check the first line:** Must be exactly `---` with no blank lines before it
+3. **Validate YAML:** Use an online YAML validator
+
+Common mistakes:
+```yaml
+# WRONG - tabs
+hooks:
+	PreToolUse:
+
+# CORRECT - spaces
+hooks:
+  PreToolUse:
+```
+
+---
+
+## Windows-specific issues
+
+See [docs/windows.md](windows.md) for Windows-specific troubleshooting.
+
+---
+
+## Cursor-specific issues
+
+See [docs/cursor.md](cursor.md) for Cursor IDE troubleshooting.
+
+---
+
+## Still stuck?
+
+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`)
+- Your operating system
+- The command you ran
+- What happened vs what you expected
+- Any error messages
@@ -0,0 +1,139 @@
+# Windows Setup
+
+Windows-specific installation and usage notes.
+
+---
+
+## Installation on Windows
+
+### Via winget (Recommended)
+
+Claude Code supports Windows Package Manager:
+
+```powershell
+winget install Anthropic.ClaudeCode
+```
+
+Then install the skill:
+
+```
+/plugin marketplace add OthmanAdi/planning-with-files
+/plugin install planning-with-files@planning-with-files
+```
+
+### Manual Installation
+
+```powershell
+# Create plugins directory
+mkdir -p $env:USERPROFILE\.claude\plugins
+
+# Clone the repository
+git clone https://github.com/OthmanAdi/planning-with-files.git $env:USERPROFILE\.claude\plugins\planning-with-files
+```
+
+### Skills Only
+
+```powershell
+git clone https://github.com/OthmanAdi/planning-with-files.git
+Copy-Item -Recurse planning-with-files\skills\* $env:USERPROFILE\.claude\skills\
+```
+
+---
+
+## Path Differences
+
+| Unix/macOS | Windows |
+|------------|---------|
+| `~/.claude/skills/` | `%USERPROFILE%\.claude\skills\` |
+| `~/.claude/plugins/` | `%USERPROFILE%\.claude\plugins\` |
+| `.claude/plugins/` | `.claude\plugins\` |
+
+---
+
+## Shell Script Compatibility
+
+The helper scripts (`init-session.sh`, `check-complete.sh`) are bash scripts.
+
+### Option 1: Use Git Bash
+
+If you have Git for Windows installed, run scripts in Git Bash:
+
+```bash
+./scripts/init-session.sh
+```
+
+### Option 2: Use WSL
+
+```bash
+wsl ./scripts/init-session.sh
+```
+
+### Option 3: Manual alternative
+
+Instead of running scripts, manually create the files:
+
+```powershell
+# Copy templates to current directory
+Copy-Item templates\task_plan.md .
+Copy-Item templates\findings.md .
+Copy-Item templates\progress.md .
+```
+
+---
+
+## Hook Commands
+
+The hooks use Unix-style commands. On Windows with Claude Code:
+
+- Hooks run in a Unix-compatible shell environment
+- Commands like `cat`, `head`, `echo` work automatically
+- No changes needed to the skill configuration
+
+---
+
+## Common Windows Issues
+
+### Path separators
+
+If you see path errors, ensure you're using the correct separator:
+
+```powershell
+# Windows
+$env:USERPROFILE\.claude\skills\
+
+# Not Unix-style
+~/.claude/skills/
+```
+
+### Line endings
+
+If templates appear corrupted, check line endings:
+
+```powershell
+# Convert to Windows line endings if needed
+(Get-Content template.md) | Set-Content -Encoding UTF8 template.md
+```
+
+### Permission errors
+
+Run PowerShell as Administrator if you get permission errors:
+
+```powershell
+# Right-click PowerShell → Run as Administrator
+```
+
+---
+
+## Terminal Recommendations
+
+For best experience on Windows:
+
+1. **Windows Terminal** - Modern terminal with good Unicode support
+2. **Git Bash** - Unix-like environment on Windows
+3. **WSL** - Full Linux environment
+
+---
+
+## Need Help?
+
+Open an issue at [github.com/OthmanAdi/planning-with-files/issues](https://github.com/OthmanAdi/planning-with-files/issues).
@@ -0,0 +1,209 @@
+# Workflow Diagram
+
+This diagram shows how the three files work together and how hooks interact with them.
+
+---
+
+## Visual Workflow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    TASK START                                    │
+│  User requests a complex task (>5 tool calls expected)          │
+└────────────────────────┬────────────────────────────────────────┘
+                         │
+                         ▼
+         ┌───────────────────────────────┐
+         │  STEP 1: Create task_plan.md │
+         │  (NEVER skip this step!)      │
+         └───────────────┬───────────────┘
+                         │
+                         ▼
+         ┌───────────────────────────────┐
+         │  STEP 2: Create findings.md   │
+         │  STEP 3: Create progress.md   │
+         └───────────────┬───────────────┘
+                         │
+                         ▼
+    ┌────────────────────────────────────────────┐
+    │         WORK LOOP (Iterative)              │
+    │                                            │
+    │  ┌──────────────────────────────────────┐ │
+    │  │  PreToolUse Hook (Automatic)         │ │
+    │  │  → Reads task_plan.md before        │ │
+    │  │    Write/Edit/Bash operations       │ │
+    │  │  → Refreshes goals in attention      │ │
+    │  └──────────────┬───────────────────────┘ │
+    │                 │                          │
+    │                 ▼                          │
+    │  ┌──────────────────────────────────────┐ │
+    │  │  Perform work (tool calls)          │ │
+    │  │  - Research → Update findings.md    │ │
+    │  │  - Implement → Update progress.md    │ │
+    │  │  - Make decisions → Update both     │ │
+    │  └──────────────┬───────────────────────┘ │
+    │                 │                          │
+    │                 ▼                          │
+    │  ┌──────────────────────────────────────┐ │
+    │  │  PostToolUse Hook (Automatic)        │ │
+    │  │  → Reminds to update task_plan.md   │ │
+    │  │    if phase completed               │ │
+    │  └──────────────┬───────────────────────┘ │
+    │                 │                          │
+    │                 ▼                          │
+    │  ┌──────────────────────────────────────┐ │
+    │  │  After 2 view/browser operations:    │ │
+    │  │  → MUST update findings.md           │ │
+    │  │    (2-Action Rule)                   │ │
+    │  └──────────────┬───────────────────────┘ │
+    │                 │                          │
+    │                 ▼                          │
+    │  ┌──────────────────────────────────────┐ │
+    │  │  After completing a phase:            │ │
+    │  │  → Update task_plan.md status        │ │
+    │  │  → Update progress.md with details   │ │
+    │  └──────────────┬───────────────────────┘ │
+    │                 │                          │
+    │                 ▼                          │
+    │  ┌──────────────────────────────────────┐ │
+    │  │  If error occurs:                    │ │
+    │  │  → Log in task_plan.md               │ │
+    │  │  → Log in progress.md                │ │
+    │  │  → Document resolution               │ │
+    │  └──────────────┬───────────────────────┘ │
+    │                 │                          │
+    │                 └──────────┐               │
+    │                            │               │
+    │                            ▼               │
+    │              ┌──────────────────────┐     │
+    │              │  More work to do?    │     │
+    │              └──────┬───────────────┘     │
+    │                     │                     │
+    │              YES ───┘                     │
+    │              │                            │
+    │              └──────────┐                 │
+    │                         │                 │
+    └─────────────────────────┘                 │
+                                                 │
+                         NO                      │
+                         │                       │
+                         ▼                       │
+         ┌──────────────────────────────────────┐
+         │  Stop Hook (Automatic)               │
+         │  → Checks if all phases complete     │
+         │  → Verifies task_plan.md status      │
+         └──────────────┬───────────────────────┘
+                         │
+                         ▼
+         ┌──────────────────────────────────────┐
+         │  All phases complete?                │
+         └──────────────┬───────────────────────┘
+                         │
+              ┌──────────┴──────────┐
+              │                     │
+            YES                    NO
+              │                     │
+              ▼                     ▼
+    ┌─────────────────┐    ┌─────────────────┐
+    │  TASK COMPLETE  │    │  Continue work  │
+    │  Deliver files  │    │  (back to loop) │
+    └─────────────────┘    └─────────────────┘
+```
+
+---
+
+## Key Interactions
+
+### Hooks
+
+| Hook | When It Fires | What It Does |
+|------|---------------|--------------|
+| **SessionStart** | When Claude Code session begins | Notifies skill is ready |
+| **PreToolUse** | Before Write/Edit/Bash operations | Reads `task_plan.md` to refresh goals |
+| **PostToolUse** | After Write/Edit operations | Reminds to update phase status |
+| **Stop** | When Claude tries to stop | Verifies all phases are complete |
+
+### The 2-Action Rule
+
+After every 2 view/browser/search operations, you MUST update `findings.md`.
+
+```
+Operation 1: WebSearch → Note results
+Operation 2: WebFetch → MUST UPDATE findings.md NOW
+Operation 3: Read file → Note findings
+Operation 4: Grep search → MUST UPDATE findings.md NOW
+```
+
+### Phase Completion
+
+When a phase is complete:
+
+1. Update `task_plan.md`:
+   - Change status: `in_progress` → `complete`
+   - Mark checkboxes: `[ ]` → `[x]`
+
+2. Update `progress.md`:
+   - Log actions taken
+   - List files created/modified
+   - Note any issues encountered
+
+### Error Handling
+
+When an error occurs:
+
+1. Log in `task_plan.md` → Errors Encountered table
+2. Log in `progress.md` → Error Log with timestamp
+3. Document the resolution
+4. Never repeat the same failed action
+
+---
+
+## File Relationships
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         task_plan.md                             │
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │  Goal: What you're trying to achieve                    │   │
+│  │  Phases: 3-7 steps with status tracking                 │   │
+│  │  Decisions: Major choices made                          │   │
+│  │  Errors: Problems encountered                           │   │
+│  └─────────────────────────────────────────────────────────┘   │
+│                              │                                   │
+│              PreToolUse hook reads this                         │
+│              before every Write/Edit/Bash                       │
+└─────────────────────────────────────────────────────────────────┘
+                               │
+          ┌────────────────────┼────────────────────┐
+          │                    │                    │
+          ▼                    │                    ▼
+┌─────────────────┐            │          ┌─────────────────┐
+│   findings.md   │            │          │   progress.md   │
+│                 │            │          │                 │
+│  Research       │◄───────────┘          │  Session log    │
+│  Discoveries    │                       │  Actions taken  │
+│  Tech decisions │                       │  Test results   │
+│  Resources      │                       │  Error log      │
+└─────────────────┘                       └─────────────────┘
+```
+
+---
+
+## The 5-Question Reboot Test
+
+If you can answer these questions, your context management is solid:
+
+| Question | Answer Source |
+|----------|---------------|
+| Where am I? | Current phase in `task_plan.md` |
+| Where am I going? | Remaining phases in `task_plan.md` |
+| What's the goal? | Goal statement in `task_plan.md` |
+| What have I learned? | `findings.md` |
+| What have I done? | `progress.md` |
+
+---
+
+## Next Steps
+
+- [Quick Start Guide](quickstart.md) - Step-by-step tutorial
+- [Troubleshooting](troubleshooting.md) - Common issues and solutions
@@ -1,15 +1,634 @@
-# Examples
+# Examples: Planning with Files in Action

-Real-world usage examples of the planning-with-files skill.
+This directory contains real-world examples showing how the 3-file planning pattern works in practice.

-## Coming Soon
+## Example: Building a Todo App

- Research task example
- Bug fix example
- Feature development example
- Multi-step project example
+This walkthrough demonstrates a complete task from start to finish, showing how `task_plan.md`, `findings.md`, and `progress.md` evolve together.

-Each example will include the actual `task_plan.md`, `notes.md`, and deliverable files generated during real tasks.
+### The Task
+
+**User Request:** "Build a simple command-line todo app in Python that can add, list, and delete tasks."
+
+---
+
+## Phase 1: Initial Planning (Task Start)
+
+### task_plan.md (Initial State)
+
+```markdown
+# Task Plan: Build Command-Line Todo App
+
+## Goal
+Create a Python CLI todo app with add, list, and delete functionality.
+
+## Current Phase
+Phase 1
+
+## Phases
+
+### Phase 1: Requirements & Discovery
+- [ ] Understand user intent
+- [ ] Identify constraints and requirements
+- [ ] Document findings in findings.md
+- **Status:** in_progress
+
+### Phase 2: Planning & Structure
+- [ ] Define technical approach
+- [ ] Create project structure
+- [ ] Document decisions with rationale
+- **Status:** pending
+
+### Phase 3: Implementation
+- [ ] Write todo.py with core functions
+- [ ] Implement add functionality
+- [ ] Implement list functionality
+- [ ] Implement delete functionality
+- **Status:** pending
+
+### Phase 4: Testing & Verification
+- [ ] Test add operation
+- [ ] Test list operation
+- [ ] Test delete operation
+- [ ] Verify error handling
+- **Status:** pending
+
+### Phase 5: Delivery
+- [ ] Review code quality
+- [ ] Ensure all features work
+- [ ] Deliver to user
+- **Status:** pending
+
+## Key Questions
+1. Should tasks persist between sessions? (Yes - need file storage)
+2. What format for storing tasks? (JSON file)
+3. Command-line interface style? (Simple argparse)
+
+## 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
+```
+
+### findings.md (Initial State)
+
+```markdown
+# Findings & Decisions
+
+## Requirements
+- Command-line interface
+- Add tasks
+- List all tasks
+- Delete tasks
+- Python implementation
+- Tasks should persist (survive app restart)
+
+## Research Findings
+- (To be filled as we explore)
+
+## Technical Decisions
+| Decision | Rationale |
+|----------|-----------|
+|          |           |
+
+## Issues Encountered
+| Issue | Resolution |
+|-------|------------|
+|       |            |
+
+## Resources
+- Python argparse documentation (to be referenced)
+
+## Visual/Browser Findings
+- (To be updated after research)
+
+---
+*Update this file after every 2 view/browser/search operations*
+*This prevents visual information from being lost*
+```
+
+### progress.md (Initial State)
+
+```markdown
+# Progress Log
+
+## Session: 2026-01-15
+
+### Phase 1: Requirements & Discovery
+- **Status:** in_progress
+- **Started:** 2026-01-15 10:00
+- Actions taken:
+  - Created task_plan.md
+  - Created findings.md
+  - Created progress.md
+- Files created/modified:
+  - task_plan.md (created)
+  - findings.md (created)
+  - progress.md (created)
+
+### Phase 2: Planning & Structure
+- **Status:** pending
+- Actions taken:
+  -
+- Files created/modified:
+  -
+
+## Test Results
+| Test | Input | Expected | Actual | Status |
+|------|-------|----------|--------|--------|
+|      |       |          |        |        |
+
+## Error Log
+| Timestamp | Error | Attempt | Resolution |
+|-----------|-------|---------|------------|
+|           |       | 1       |            |
+
+## 5-Question Reboot Check
+| Question | Answer |
+|----------|--------|
+| Where am I? | Phase 1 - Requirements & Discovery |
+| Where am I going? | Phase 2-5: Planning, Implementation, Testing, Delivery |
+| What's the goal? | Build Python CLI todo app with add/list/delete |
+| What have I learned? | See findings.md |
+| What have I done? | Created planning files |
+
+---
+*Update after completing each phase or encountering errors*
+```
+
+---
+
+## Phase 2: After Research & Planning
+
+### task_plan.md (Updated)
+
+```markdown
+# Task Plan: Build Command-Line Todo App
+
+## Goal
+Create a Python CLI todo app with add, list, and delete functionality.
+
+## Current Phase
+Phase 2
+
+## Phases
+
+### Phase 1: Requirements & Discovery
+- [x] Understand user intent ✓
+- [x] Identify constraints and requirements ✓
+- [x] Document findings in findings.md ✓
+- **Status:** complete
+
+### Phase 2: Planning & Structure
+- [x] Define technical approach ✓
+- [x] Create project structure ✓
+- [x] Document decisions with rationale ✓
+- **Status:** complete
+
+### Phase 3: Implementation
+- [ ] Write todo.py with core functions
+- [ ] Implement add functionality
+- [ ] Implement list functionality
+- [ ] Implement delete functionality
+- **Status:** in_progress
+
+### Phase 4: Testing & Verification
+- [ ] Test add operation
+- [ ] Test list operation
+- [ ] Test delete operation
+- [ ] Verify error handling
+- **Status:** pending
+
+### Phase 5: Delivery
+- [ ] Review code quality
+- [ ] Ensure all features work
+- [ ] Deliver to user
+- **Status:** pending
+
+## Key Questions
+1. Should tasks persist between sessions? ✓ Yes - using JSON file
+2. What format for storing tasks? ✓ JSON file (todos.json)
+3. Command-line interface style? ✓ argparse with subcommands
+
+## Decisions Made
+| Decision | Rationale |
+|----------|-----------|
+| Use JSON for storage | Simple, human-readable, built-in Python support |
+| argparse with subcommands | Clean CLI: `python todo.py add "task"`, `python todo.py list` |
+| Store in todos.json | Standard location, easy to find and debug |
+
+## 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
+```
+
+### findings.md (Updated)
+
+```markdown
+# Findings & Decisions
+
+## Requirements
+- Command-line interface
+- Add tasks
+- List all tasks
+- Delete tasks
+- Python implementation
+- Tasks should persist (survive app restart)
+
+## Research Findings
+- Python's `argparse` module is perfect for CLI subcommands
+- `json` module handles file persistence easily
+- Standard pattern: `python todo.py <command> [args]`
+- File structure: Single `todo.py` file is sufficient for this scope
+
+## Technical Decisions
+| Decision | Rationale |
+|----------|-----------|
+| Use JSON for storage | Simple, human-readable, built-in Python support |
+| argparse with subcommands | Clean CLI: `python todo.py add "task"`, `python todo.py list` |
+| Store in todos.json | Standard location, easy to find and debug |
+| Single file structure | Simple enough for one file, can refactor later if needed |
+
+## Issues Encountered
+| Issue | Resolution |
+|-------|------------|
+|       |            |
+
+## Resources
+- Python argparse documentation: https://docs.python.org/3/library/argparse.html
+- Python json module: https://docs.python.org/3/library/json.html
+
+## Visual/Browser Findings
+- Reviewed argparse examples - subcommand pattern is straightforward
+- JSON file format: array of objects with `id` and `task` fields
+
+---
+*Update this file after every 2 view/browser/search operations*
+*This prevents visual information from being lost*
+```
+
+### progress.md (Updated)
+
+```markdown
+# Progress Log
+
+## Session: 2026-01-15
+
+### Phase 1: Requirements & Discovery
+- **Status:** complete
+- **Started:** 2026-01-15 10:00
+- **Completed:** 2026-01-15 10:15
+- Actions taken:
+  - Created task_plan.md
+  - Created findings.md
+  - Created progress.md
+  - Researched Python CLI patterns
+  - Decided on JSON storage
+- Files created/modified:
+  - task_plan.md (created, updated)
+  - findings.md (created, updated)
+  - progress.md (created)
+
+### Phase 2: Planning & Structure
+- **Status:** complete
+- **Started:** 2026-01-15 10:15
+- **Completed:** 2026-01-15 10:20
+- Actions taken:
+  - Defined technical approach (argparse + JSON)
+  - Documented decisions in findings.md
+  - Updated task_plan.md with decisions
+- Files created/modified:
+  - task_plan.md (updated)
+  - findings.md (updated)
+
+### Phase 3: Implementation
+- **Status:** in_progress
+- **Started:** 2026-01-15 10:20
+- Actions taken:
+  - Starting to write todo.py
+- Files created/modified:
+  - (todo.py will be created)
+
+## Test Results
+| Test | Input | Expected | Actual | Status |
+|------|-------|----------|--------|--------|
+|      |       |          |        |        |
+
+## Error Log
+| Timestamp | Error | Attempt | Resolution |
+|-----------|-------|---------|------------|
+|           |       | 1       |            |
+
+## 5-Question Reboot Check
+| Question | Answer |
+|----------|--------|
+| Where am I? | Phase 3 - Implementation |
+| Where am I going? | Phase 4-5: Testing, Delivery |
+| What's the goal? | Build Python CLI todo app with add/list/delete |
+| What have I learned? | argparse subcommands, JSON storage pattern (see findings.md) |
+| What have I done? | Completed planning, starting implementation |
+
+---
+*Update after completing each phase or encountering errors*
+```
+
+---
+
+## Phase 3: During Implementation (With Error)
+
+### task_plan.md (After Error Encountered)
+
+```markdown
+# Task Plan: Build Command-Line Todo App
+
+## Goal
+Create a Python CLI todo app with add, list, and delete functionality.
+
+## Current Phase
+Phase 3
+
+## Phases
+
+### Phase 1: Requirements & Discovery
+- [x] Understand user intent ✓
+- [x] Identify constraints and requirements ✓
+- [x] Document findings in findings.md ✓
+- **Status:** complete
+
+### Phase 2: Planning & Structure
+- [x] Define technical approach ✓
+- [x] Create project structure ✓
+- [x] Document decisions with rationale ✓
+- **Status:** complete
+
+### Phase 3: Implementation
+- [x] Write todo.py with core functions ✓
+- [x] Implement add functionality ✓
+- [ ] Implement list functionality (CURRENT)
+- [ ] Implement delete functionality
+- **Status:** in_progress
+
+### Phase 4: Testing & Verification
+- [ ] Test add operation
+- [ ] Test list operation
+- [ ] Test delete operation
+- [ ] Verify error handling
+- **Status:** pending
+
+### Phase 5: Delivery
+- [ ] Review code quality
+- [ ] Ensure all features work
+- [ ] Deliver to user
+- **Status:** pending
+
+## Key Questions
+1. Should tasks persist between sessions? ✓ Yes - using JSON file
+2. What format for storing tasks? ✓ JSON file (todos.json)
+3. Command-line interface style? ✓ argparse with subcommands
+
+## Decisions Made
+| Decision | Rationale |
+|----------|-----------|
+| Use JSON for storage | Simple, human-readable, built-in Python support |
+| argparse with subcommands | Clean CLI: `python todo.py add "task"`, `python todo.py list` |
+| Store in todos.json | Standard location, easy to find and debug |
+| Use incremental IDs | Simple counter, easier than UUIDs for this use case |
+
+## Errors Encountered
+| Error | Attempt | Resolution |
+|-------|---------|------------|
+| FileNotFoundError when reading todos.json | 1 | Check if file exists, create empty list if not |
+| JSONDecodeError on empty file | 2 | Handle empty file case explicitly |
+
+## 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
+```
+
+### progress.md (With Error Logged)
+
+```markdown
+# Progress Log
+
+## Session: 2026-01-15
+
+### Phase 1: Requirements & Discovery
+- **Status:** complete
+- **Started:** 2026-01-15 10:00
+- **Completed:** 2026-01-15 10:15
+- Actions taken:
+  - Created task_plan.md
+  - Created findings.md
+  - Created progress.md
+  - Researched Python CLI patterns
+  - Decided on JSON storage
+- Files created/modified:
+  - task_plan.md (created, updated)
+  - findings.md (created, updated)
+  - progress.md (created)
+
+### Phase 2: Planning & Structure
+- **Status:** complete
+- **Started:** 2026-01-15 10:15
+- **Completed:** 2026-01-15 10:20
+- Actions taken:
+  - Defined technical approach (argparse + JSON)
+  - Documented decisions in findings.md
+  - Updated task_plan.md with decisions
+- Files created/modified:
+  - task_plan.md (updated)
+  - findings.md (updated)
+
+### Phase 3: Implementation
+- **Status:** in_progress
+- **Started:** 2026-01-15 10:20
+- Actions taken:
+  - Created todo.py with basic structure
+  - Implemented add functionality
+  - Encountered FileNotFoundError (handled)
+  - Encountered JSONDecodeError on empty file (handled)
+  - Working on list functionality
+- Files created/modified:
+  - todo.py (created, modified)
+  - todos.json (created by app)
+
+## Test Results
+| Test | Input | Expected | Actual | Status |
+|------|-------|----------|--------|--------|
+| Add task | `python todo.py add "Buy milk"` | Task added to todos.json | Task added successfully | ✓ |
+| List tasks | `python todo.py list` | Shows all tasks | FileNotFoundError (fixed) | Fixed |
+
+## Error Log
+| Timestamp | Error | Attempt | Resolution |
+|-----------|-------|---------|------------|
+| 2026-01-15 10:35 | FileNotFoundError when reading todos.json | 1 | Added file existence check, create empty list if not exists |
+| 2026-01-15 10:37 | JSONDecodeError on empty file | 2 | Added explicit empty file handling before json.load() |
+
+## 5-Question Reboot Check
+| Question | Answer |
+|----------|--------|
+| Where am I? | Phase 3 - Implementation (working on list functionality) |
+| Where am I going? | Phase 4-5: Testing, Delivery |
+| What's the goal? | Build Python CLI todo app with add/list/delete |
+| What have I learned? | Need to handle file not existing, empty file edge cases (see findings.md) |
+| What have I done? | Completed add functionality, fixed file handling errors, working on list |
+
+---
+*Update after completing each phase or encountering errors*
+```
+
+---
+
+## Phase 4: Task Complete
+
+### task_plan.md (Final State)
+
+```markdown
+# Task Plan: Build Command-Line Todo App
+
+## Goal
+Create a Python CLI todo app with add, list, and delete functionality.
+
+## Current Phase
+Phase 5 (Complete)
+
+## Phases
+
+### Phase 1: Requirements & Discovery
+- [x] Understand user intent ✓
+- [x] Identify constraints and requirements ✓
+- [x] Document findings in findings.md ✓
+- **Status:** complete
+
+### Phase 2: Planning & Structure
+- [x] Define technical approach ✓
+- [x] Create project structure ✓
+- [x] Document decisions with rationale ✓
+- **Status:** complete
+
+### Phase 3: Implementation
+- [x] Write todo.py with core functions ✓
+- [x] Implement add functionality ✓
+- [x] Implement list functionality ✓
+- [x] Implement delete functionality ✓
+- **Status:** complete
+
+### Phase 4: Testing & Verification
+- [x] Test add operation ✓
+- [x] Test list operation ✓
+- [x] Test delete operation ✓
+- [x] Verify error handling ✓
+- **Status:** complete
+
+### Phase 5: Delivery
+- [x] Review code quality ✓
+- [x] Ensure all features work ✓
+- [x] Deliver to user ✓
+- **Status:** complete
+
+## Key Questions
+1. Should tasks persist between sessions? ✓ Yes - using JSON file
+2. What format for storing tasks? ✓ JSON file (todos.json)
+3. Command-line interface style? ✓ argparse with subcommands
+
+## Decisions Made
+| Decision | Rationale |
+|----------|-----------|
+| Use JSON for storage | Simple, human-readable, built-in Python support |
+| argparse with subcommands | Clean CLI: `python todo.py add "task"`, `python todo.py list` |
+| Store in todos.json | Standard location, easy to find and debug |
+| Use incremental IDs | Simple counter, easier than UUIDs for this use case |
+
+## Errors Encountered
+| Error | Attempt | Resolution |
+|-------|---------|------------|
+| FileNotFoundError when reading todos.json | 1 | Check if file exists, create empty list if not |
+| JSONDecodeError on empty file | 2 | Handle empty file case explicitly |
+
+## 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
+```
+
+---
+
+## Key Takeaways
+
+### How Files Work Together
+
+1. **task_plan.md** = Your roadmap
+   - Created first, before any work begins
+   - Updated after each phase completes
+   - Re-read before major decisions (automatic via hooks)
+   - Tracks what's done, what's next, what went wrong
+
+2. **findings.md** = Your knowledge base
+   - Captures research and discoveries
+   - Stores technical decisions with rationale
+   - Updated after every 2 view/browser operations (2-Action Rule)
+   - Prevents losing important information
+
+3. **progress.md** = Your session log
+   - Records what you did and when
+   - Tracks test results
+   - Logs ALL errors (even ones you fixed)
+   - Answers the "5-Question Reboot Test"
+
+### The Workflow Pattern
+
+```
+START TASK
+  ↓
+Create task_plan.md (NEVER skip this!)
+  ↓
+Create findings.md
+  ↓
+Create progress.md
+  ↓
+[Work on task]
+  ↓
+Update files as you go:
+  - task_plan.md: Mark phases complete, log errors
+  - findings.md: Save discoveries (especially after 2 view/browser ops)
+  - progress.md: Log actions, tests, errors
+  ↓
+Re-read task_plan.md before major decisions
+  ↓
+COMPLETE TASK
+```
+
+### Common Patterns
+
+- **Error occurs?** → Log it in `task_plan.md` AND `progress.md`
+- **Made a decision?** → Document in `findings.md` with rationale
+- **Viewed 2 things?** → Save findings to `findings.md` immediately
+- **Starting new phase?** → Update status in `task_plan.md` and `progress.md`
+- **Uncertain what to do?** → Re-read `task_plan.md` to refresh goals
+
+---
+
+## More Examples
+
+Want to see more examples? Check out:
+- [examples.md](../skills/planning-with-files/examples.md) - Additional patterns and use cases

 ---

@@ -1,14 +1,32 @@
 ---
 name: planning-with-files
-version: "2.0.0"
+version: "2.1.0"
 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
+user-invocable: true
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - WebFetch
+  - WebSearch
 hooks:
+  SessionStart:
+    - hooks:
+        - type: command
+          command: "echo '[planning-with-files] Ready. Auto-activates for complex tasks, or invoke manually with /planning-with-files'"
  PreToolUse:
    - matcher: "Write|Edit|Bash"
      hooks:
        - type: command
          command: "cat task_plan.md 2>/dev/null | head -30 || true"
+  PostToolUse:
+    - matcher: "Write|Edit"
+      hooks:
+        - type: command
+          command: "echo '[planning-with-files] File updated. If this completes a phase, update task_plan.md status.'"
  Stop:
    - hooks:
        - type: command
@@ -19,16 +37,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 +208,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 |
@@ -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
@@ -1,34 +1,95 @@
 # Findings & Decisions
+<!-- 
+  WHAT: Your knowledge base for the task. Stores everything you discover and decide.
+  WHY: Context windows are limited. This file is your "external memory" - persistent and unlimited.
+  WHEN: Update after ANY discovery, especially after 2 view/browser/search operations (2-Action Rule).
+-->

 ## Requirements
+<!-- 
+  WHAT: What the user asked for, broken down into specific requirements.
+  WHY: Keeps requirements visible so you don't forget what you're building.
+  WHEN: Fill this in during Phase 1 (Requirements & Discovery).
+  EXAMPLE:
+    - Command-line interface
+    - Add tasks
+    - List all tasks
+    - Delete tasks
+    - Python implementation
+-->
 <!-- Captured from user request -->
 -

 ## Research Findings
+<!-- 
+  WHAT: Key discoveries from web searches, documentation reading, or exploration.
+  WHY: Multimodal content (images, browser results) doesn't persist. Write it down immediately.
+  WHEN: After EVERY 2 view/browser/search operations, update this section (2-Action Rule).
+  EXAMPLE:
+    - Python's argparse module supports subcommands for clean CLI design
+    - JSON module handles file persistence easily
+    - Standard pattern: python script.py <command> [args]
+-->
 <!-- Key discoveries during exploration -->
 -

 ## Technical Decisions
+<!-- 
+  WHAT: Architecture and implementation choices you've made, with reasoning.
+  WHY: You'll forget why you chose a technology or approach. This table preserves that knowledge.
+  WHEN: Update whenever you make a significant technical choice.
+  EXAMPLE:
+    | Use JSON for storage | Simple, human-readable, built-in Python support |
+    | argparse with subcommands | Clean CLI: python todo.py add "task" |
+-->
 <!-- Decisions made with rationale -->
 | Decision | Rationale |
 |----------|-----------|
 |          |           |

 ## Issues Encountered
+<!-- 
+  WHAT: Problems you ran into and how you solved them.
+  WHY: Similar to errors in task_plan.md, but focused on broader issues (not just code errors).
+  WHEN: Document when you encounter blockers or unexpected challenges.
+  EXAMPLE:
+    | Empty file causes JSONDecodeError | Added explicit empty file check before json.load() |
+-->
 <!-- Errors and how they were resolved -->
 | Issue | Resolution |
 |-------|------------|
 |       |            |

 ## Resources
+<!-- 
+  WHAT: URLs, file paths, API references, documentation links you've found useful.
+  WHY: Easy reference for later. Don't lose important links in context.
+  WHEN: Add as you discover useful resources.
+  EXAMPLE:
+    - Python argparse docs: https://docs.python.org/3/library/argparse.html
+    - Project structure: src/main.py, src/utils.py
+-->
 <!-- URLs, file paths, API references -->
 -

 ## Visual/Browser Findings
+<!-- 
+  WHAT: Information you learned from viewing images, PDFs, or browser results.
+  WHY: CRITICAL - Visual/multimodal content doesn't persist in context. Must be captured as text.
+  WHEN: IMMEDIATELY after viewing images or browser results. Don't wait!
+  EXAMPLE:
+    - Screenshot shows login form has email and password fields
+    - Browser shows API returns JSON with "status" and "data" keys
+-->
 <!-- CRITICAL: Update after every 2 view/browser operations -->
 <!-- Multimodal content must be captured as text immediately -->
 -

 ---
+<!-- 
+  REMINDER: The 2-Action Rule
+  After every 2 view/browser/search operations, you MUST update this file.
+  This prevents visual information from being lost when context resets.
+-->
 *Update this file after every 2 view/browser/search operations*
 *This prevents visual information from being lost*
@@ -1,16 +1,54 @@
 # Progress Log
+<!-- 
+  WHAT: Your session log - a chronological record of what you did, when, and what happened.
+  WHY: Answers "What have I done?" in the 5-Question Reboot Test. Helps you resume after breaks.
+  WHEN: Update after completing each phase or encountering errors. More detailed than task_plan.md.
+-->

 ## Session: [DATE]
+<!-- 
+  WHAT: The date of this work session.
+  WHY: Helps track when work happened, useful for resuming after time gaps.
+  EXAMPLE: 2026-01-15
+-->

 ### Phase 1: [Title]
+<!-- 
+  WHAT: Detailed log of actions taken during this phase.
+  WHY: Provides context for what was done, making it easier to resume or debug.
+  WHEN: Update as you work through the phase, or at least when you complete it.
+-->
 - **Status:** in_progress
 - **Started:** [timestamp]
+<!-- 
+  STATUS: Same as task_plan.md (pending, in_progress, complete)
+  TIMESTAMP: When you started this phase (e.g., "2026-01-15 10:00")
+-->
 - Actions taken:
+  <!-- 
+    WHAT: List of specific actions you performed.
+    EXAMPLE:
+      - Created todo.py with basic structure
+      - Implemented add functionality
+      - Fixed FileNotFoundError
+  -->
  -
 - Files created/modified:
+  <!-- 
+    WHAT: Which files you created or changed.
+    WHY: Quick reference for what was touched. Helps with debugging and review.
+    EXAMPLE:
+      - todo.py (created)
+      - todos.json (created by app)
+      - task_plan.md (updated)
+  -->
  -

 ### Phase 2: [Title]
+<!-- 
+  WHAT: Same structure as Phase 1, for the next phase.
+  WHY: Keep a separate log entry for each phase to track progress clearly.
+-->
 - **Status:** pending
 - Actions taken:
  -
@@ -18,19 +56,45 @@
  -

 ## Test Results
-
+<!-- 
+  WHAT: Table of tests you ran, what you expected, what actually happened.
+  WHY: Documents verification of functionality. Helps catch regressions.
+  WHEN: Update as you test features, especially during Phase 4 (Testing & Verification).
+  EXAMPLE:
+    | Add task | python todo.py add "Buy milk" | Task added | Task added successfully | ✓ |
+    | List tasks | python todo.py list | Shows all tasks | Shows all tasks | ✓ |
+-->
 | Test | Input | Expected | Actual | Status |
 |------|-------|----------|--------|--------|
 |      |       |          |        |        |

 ## Error Log
-
+<!-- 
+  WHAT: Detailed log of every error encountered, with timestamps and resolution attempts.
+  WHY: More detailed than task_plan.md's error table. Helps you learn from mistakes.
+  WHEN: Add immediately when an error occurs, even if you fix it quickly.
+  EXAMPLE:
+    | 2026-01-15 10:35 | FileNotFoundError | 1 | Added file existence check |
+    | 2026-01-15 10:37 | JSONDecodeError | 2 | Added empty file handling |
+-->
 <!-- Keep ALL errors - they help avoid repetition -->
 | Timestamp | Error | Attempt | Resolution |
 |-----------|-------|---------|------------|
 |           |       | 1       |            |

 ## 5-Question Reboot Check
+<!-- 
+  WHAT: Five questions that verify your context is solid. If you can answer these, you're on track.
+  WHY: This is the "reboot test" - if you can answer all 5, you can resume work effectively.
+  WHEN: Update periodically, especially when resuming after a break or context reset.
+  
+  THE 5 QUESTIONS:
+  1. Where am I? → Current phase in task_plan.md
+  2. Where am I going? → Remaining phases
+  3. What's the goal? → Goal statement in task_plan.md
+  4. What have I learned? → See findings.md
+  5. What have I done? → See progress.md (this file)
+-->
 <!-- If you can answer these, context is solid -->
 | Question | Answer |
 |----------|--------|
@@ -41,4 +105,10 @@
 | What have I done? | See above |

 ---
+<!-- 
+  REMINDER: 
+  - Update after completing each phase or encountering errors
+  - Be detailed - this is your "what happened" log
+  - Include timestamps for errors to track when issues occurred
+-->
 *Update after completing each phase or encountering errors*
@@ -0,0 +1,132 @@
+# Task Plan: [Brief Description]
+<!-- 
+  WHAT: This is your roadmap for the entire task. Think of it as your "working memory on disk."
+  WHY: After 50+ tool calls, your original goals can get forgotten. This file keeps them fresh.
+  WHEN: Create this FIRST, before starting any work. Update after each phase completes.
+-->
+
+## Goal
+<!-- 
+  WHAT: One clear sentence describing what you're trying to achieve.
+  WHY: This is your north star. Re-reading this keeps you focused on the end state.
+  EXAMPLE: "Create a Python CLI todo app with add, list, and delete functionality."
+-->
+[One sentence describing the end state]
+
+## Current Phase
+<!-- 
+  WHAT: Which phase you're currently working on (e.g., "Phase 1", "Phase 3").
+  WHY: Quick reference for where you are in the task. Update this as you progress.
+-->
+Phase 1
+
+## Phases
+<!-- 
+  WHAT: Break your task into 3-7 logical phases. Each phase should be completable.
+  WHY: Breaking work into phases prevents overwhelm and makes progress visible.
+  WHEN: Update status after completing each phase: pending → in_progress → complete
+-->
+
+### Phase 1: Requirements & Discovery
+<!-- 
+  WHAT: Understand what needs to be done and gather initial information.
+  WHY: Starting without understanding leads to wasted effort. This phase prevents that.
+-->
+- [ ] Understand user intent
+- [ ] Identify constraints and requirements
+- [ ] Document findings in findings.md
+- **Status:** in_progress
+<!-- 
+  STATUS VALUES:
+  - pending: Not started yet
+  - in_progress: Currently working on this
+  - complete: Finished this phase
+-->
+
+### Phase 2: Planning & Structure
+<!-- 
+  WHAT: Decide how you'll approach the problem and what structure you'll use.
+  WHY: Good planning prevents rework. Document decisions so you remember why you chose them.
+-->
+- [ ] Define technical approach
+- [ ] Create project structure if needed
+- [ ] Document decisions with rationale
+- **Status:** pending
+
+### Phase 3: Implementation
+<!-- 
+  WHAT: Actually build/create/write the solution.
+  WHY: This is where the work happens. Break into smaller sub-tasks if needed.
+-->
+- [ ] Execute the plan step by step
+- [ ] Write code to files before executing
+- [ ] Test incrementally
+- **Status:** pending
+
+### Phase 4: Testing & Verification
+<!-- 
+  WHAT: Verify everything works and meets requirements.
+  WHY: Catching issues early saves time. Document test results in progress.md.
+-->
+- [ ] Verify all requirements met
+- [ ] Document test results in progress.md
+- [ ] Fix any issues found
+- **Status:** pending
+
+### Phase 5: Delivery
+<!-- 
+  WHAT: Final review and handoff to user.
+  WHY: Ensures nothing is forgotten and deliverables are complete.
+-->
+- [ ] Review all output files
+- [ ] Ensure deliverables are complete
+- [ ] Deliver to user
+- **Status:** pending
+
+## Key Questions
+<!-- 
+  WHAT: Important questions you need to answer during the task.
+  WHY: These guide your research and decision-making. Answer them as you go.
+  EXAMPLE: 
+    1. Should tasks persist between sessions? (Yes - need file storage)
+    2. What format for storing tasks? (JSON file)
+-->
+1. [Question to answer]
+2. [Question to answer]
+
+## Decisions Made
+<!-- 
+  WHAT: Technical and design decisions you've made, with the reasoning behind them.
+  WHY: You'll forget why you made choices. This table helps you remember and justify decisions.
+  WHEN: Update whenever you make a significant choice (technology, approach, structure).
+  EXAMPLE:
+    | Use JSON for storage | Simple, human-readable, built-in Python support |
+-->
+| Decision | Rationale |
+|----------|-----------|
+|          |           |
+
+## Errors Encountered
+<!-- 
+  WHAT: Every error you encounter, what attempt number it was, and how you resolved it.
+  WHY: Logging errors prevents repeating the same mistakes. This is critical for learning.
+  WHEN: Add immediately when an error occurs, even if you fix it quickly.
+  EXAMPLE:
+    | FileNotFoundError | 1 | Check if file exists, create empty list if not |
+    | JSONDecodeError | 2 | Handle empty file case explicitly |
+-->
+| Error | Attempt | Resolution |
+|-------|---------|------------|
+|       | 1       |            |
+
+## Notes
+<!-- 
+  REMINDERS:
+  - 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
+  - Never repeat a failed action - mutate your approach instead
+-->
+- 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
Author	SHA1	Message	Date
OthmanAdi	ab135ea63e	feat: v2.1.0 - Claude Code v2.1 compatibility + docs restructure - Add SessionStart hook for skill ready notification - Add PostToolUse hook for phase completion reminders - Add user-invocable: true for slash menu visibility - Convert allowed-tools to YAML list format - Create docs/ folder with organized documentation - Refactor README to be cleaner with docs links - Update version to 2.1.0 in all manifests	2026-01-10 17:21:15 +01:00
OthmanAdi	a01b24e4b6	Add Community Forks section with multi-manus-planning	2026-01-09 14:33:07 +01:00
OthmanAdi	1ce0372f7b	Make workflow diagram collapsible	2026-01-09 14:29:34 +01:00
OthmanAdi	6a0edccaab	Merge PR #12 : Beginner-friendly documentation enhancements - Add workflow diagram showing task lifecycle and hooks - Add Quick Start guide with 5-step walkthrough - Add complete 'Build a Todo App' example in examples/README.md - Add inline WHAT/WHY/WHEN/EXAMPLE comments to templates - Add 'Common Mistakes to Avoid' section - Add 'When to Update Which File' quick reference Thanks to @fuahyo for this excellent contribution!	2026-01-09 14:26:49 +01:00
OthmanAdi	50a8f45fca	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	2026-01-09 13:27:56 +01:00
fuahyo	67772c085d	docs: enhance beginner-friendliness with examples, templates, quick start, and workflow diagram	2026-01-09 17:46:53 +07:00
OthmanAdi	7251f923e4	Add one-line installer to README	2026-01-09 01:18:07 +01:00
OthmanAdi	0a753038b2	Fix: Add missing task_plan.md template (was in gitignore)	2026-01-09 01:17:06 +01:00
OthmanAdi	ef493399f0	Add Cursor support for v2.0.0	2026-01-08 22:17:21 +01:00
OthmanAdi	269116c2af	docs: add version table to README	2026-01-08 22:03:58 +01:00
OthmanAdi	006ea9a6c1	fix: check-complete.sh grep pattern for status detection	2026-01-08 21:38:32 +01:00