fix: remove ALL non-standard fields from SKILL.md - match Anthropic official format (v2.5.0)

Only 3 fields allowed: - name - description - license Removed: - version (not supported) - user-invocable (not supported) - allowed-tools (not supported) - hooks (not supported in SKILL.md) This matches the exact format used by official Anthropic skills.
fix: folder structure - removed duplicate planning-with-files/ folder (v2.4.1)
2026-01-20 12:00:02 +01:00 · 2026-01-20 11:08:32 +01:00 · 2026-01-20 11:08:10 +01:00 · 2026-01-20 11:01:56 +01:00 · 2026-01-20 10:16:02 +01:00 · 2026-01-18 10:46:02 +01:00
35 changed files with 4722 additions and 277 deletions
@@ -1,7 +1,7 @@
 {
  "name": "planning-with-files",
-  "version": "2.0.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.",
+  "version": "2.5.0",
+  "description": "Manus-style persistent markdown files for planning, progress tracking, and knowledge storage. Use when starting complex tasks, multi-step projects, research tasks, or when you want structured output.",
  "author": {
    "name": "OthmanAdi",
    "url": "https://github.com/OthmanAdi"
@@ -15,7 +15,6 @@
    "markdown",
    "context-engineering",
    "task-management",
-    "hooks",
    "templates"
  ]
 }
@@ -0,0 +1,92 @@
+# Installing planning-with-files for Codex
+
+## Prerequisites
+
+- Codex IDE installed
+- Git installed (optional, for cloning)
+
+## Installation
+
+### Option 1: Clone Repository (Recommended)
+
+```bash
+mkdir -p ~/.codex/skills
+cd ~/.codex/skills
+git clone https://github.com/OthmanAdi/planning-with-files.git
+```
+
+### Option 2: Manual Copy
+
+1. Download or clone this repository
+2. Copy the entire `planning-with-files/` directory to `~/.codex/skills/`
+3. Ensure the structure matches:
+   ```
+   ~/.codex/skills/planning-with-files/
+   ├── planning-with-files/
+   │   ├── SKILL.md
+   │   ├── templates/
+   │   └── scripts/
+   ```
+
+## Usage
+
+### If Using Superpowers
+
+If you have [obra/superpowers](https://github.com/obra/superpowers) installed:
+
+```bash
+~/.codex/superpowers/.codex/superpowers-codex use-skill planning-with-files
+```
+
+Superpowers will find it in your personal skills directory.
+
+### If NOT Using Superpowers
+
+Manually read the skill file when starting complex tasks:
+
+```bash
+cat ~/.codex/skills/planning-with-files/planning-with-files/SKILL.md
+```
+
+Or add to your `~/.codex/AGENTS.md`:
+
+```markdown
+## Planning with Files
+
+<IMPORTANT>
+For complex multi-step tasks (3+ steps, research, building projects):
+1. Read the planning-with-files skill: `cat ~/.codex/skills/planning-with-files/planning-with-files/SKILL.md`
+2. Create task_plan.md, findings.md, progress.md in your project directory
+3. Follow the 3-file pattern throughout the task
+</IMPORTANT>
+```
+
+## Verification
+
+Check that the skill exists:
+
+```bash
+ls -la ~/.codex/skills/planning-with-files/planning-with-files/SKILL.md
+```
+
+## Troubleshooting
+
+### Skill not found
+
+- Verify path: `~/.codex/skills/planning-with-files/planning-with-files/SKILL.md`
+- Check file exists and is readable
+- Ensure SKILL.md has proper YAML frontmatter
+
+### Scripts not executing
+
+**Windows users:**
+- Use PowerShell versions: `*.ps1`
+- Set execution policy: `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`
+
+**Unix/Mac users:**
+- Make scripts executable: `chmod +x ~/.codex/skills/planning-with-files/scripts/*.sh`
+
+## Getting Help
+
+- Issues: https://github.com/OthmanAdi/planning-with-files/issues
+- Documentation: https://github.com/OthmanAdi/planning-with-files
@@ -11,6 +11,8 @@ Thumbs.db

 # Development planning files (meta: I used this skill to build this skill!)
 task_plan.md
+findings.md
+progress.md
 research_notes.md
 notes.md

@@ -0,0 +1,153 @@
+# 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 |
@@ -0,0 +1,139 @@
+# Installing planning-with-files for OpenCode
+
+## Prerequisites
+
+- OpenCode.ai installed
+- Git installed (optional, for cloning)
+
+## Installation
+
+### Option 1: Global Installation (All Projects)
+
+```bash
+mkdir -p ~/.config/opencode/skills
+cd ~/.config/opencode/skills
+git clone https://github.com/OthmanAdi/planning-with-files.git
+```
+
+### Option 2: Project-Specific Installation
+
+```bash
+# In your OpenCode project root
+mkdir -p .opencode/skills
+cd .opencode/skills
+git clone https://github.com/OthmanAdi/planning-with-files.git
+```
+
+### Option 3: Manual Copy
+
+**For global installation:**
+1. Download or clone this repository
+2. Copy to `~/.config/opencode/skills/planning-with-files/`
+
+**For project installation:**
+1. Download or clone this repository
+2. Copy to `.opencode/skills/planning-with-files/` in your project
+
+## File Structure
+
+After installation:
+
+```
+~/.config/opencode/skills/planning-with-files/  (or .opencode/skills/planning-with-files/)
+├── planning-with-files/
+│   ├── SKILL.md              # Main skill file
+│   ├── templates/
+│   │   ├── task_plan.md
+│   │   ├── findings.md
+│   │   └── progress.md
+│   └── scripts/
+│       ├── check-complete.sh
+│       ├── check-complete.ps1
+│       ├── init-session.sh
+│       ├── init-session.ps1
+│       └── session-catchup.py
+```
+
+## Usage
+
+### If Using Superpowers Plugin
+
+If you have [obra/superpowers](https://github.com/obra/superpowers) installed as an OpenCode plugin:
+
+```
+Use the use_skill tool with skill_name: "planning-with-files"
+```
+
+OpenCode will find it automatically (personal skills override superpowers skills).
+
+### If NOT Using Superpowers
+
+You can still manually load the skill:
+
+1. Navigate to `~/.config/opencode/skills/planning-with-files/planning-with-files/`
+2. Read SKILL.md
+3. Follow the instructions for creating task_plan.md, findings.md, progress.md
+
+Or create a custom tool/command to load it.
+
+## Skill Priority
+
+If installed as:
+- **Project skill** (`.opencode/skills/planning-with-files/`) - Highest priority
+- **Personal skill** (`~/.config/opencode/skills/planning-with-files/`) - Medium priority
+- If superpowers has a planning-with-files skill - Lowest priority
+
+Project skills override personal skills, which override superpowers skills.
+
+## Verification
+
+**Global installation:**
+```bash
+ls -la ~/.config/opencode/skills/planning-with-files/planning-with-files/SKILL.md
+```
+
+**Project installation:**
+```bash
+ls -la .opencode/skills/planning-with-files/planning-with-files/SKILL.md
+```
+
+## Troubleshooting
+
+### Skill not loading
+
+1. Verify SKILL.md exists at the correct path
+2. Check YAML frontmatter is valid:
+   ```yaml
+   ---
+   name: planning-with-files
+   description: ...
+   ---
+   ```
+3. If using superpowers plugin, use `find_skills` tool to verify it's discovered
+
+### Scripts not executing
+
+**Windows:**
+- Use PowerShell versions: `*.ps1`
+- Set execution policy: `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`
+
+**Unix/Mac:**
+- Make executable: `chmod +x ~/.config/opencode/skills/planning-with-files/scripts/*.sh`
+
+### oh-my-opencode Blocking
+
+If using oh-my-opencode and the skill isn't recognized:
+
+1. Check `~/.config/opencode/oh-my-opencode.json`
+2. Ensure planning-with-files is NOT in `disabled_skills` array:
+   ```json
+   {
+     "disabled_skills": []
+   }
+   ```
+3. Restart OpenCode
+
+## Getting Help
+
+- Issues: https://github.com/OthmanAdi/planning-with-files/issues
+- Documentation: https://github.com/OthmanAdi/planning-with-files
@@ -2,6 +2,319 @@

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

+## [2.4.0] - 2026-01-20
+
+### Fixed
+
+- **CRITICAL: Fixed SKILL.md frontmatter to comply with official Agent Skills spec** (Issue #39)
+  - Removed invalid `hooks:` field from SKILL.md frontmatter (not supported by spec)
+  - Removed invalid top-level `version:` field (moved to `metadata.version`)
+  - Removed `user-invocable:` field (not in official spec)
+  - Changed `allowed-tools:` from YAML list to space-delimited string per spec
+  - This fixes `/planning-with-files` slash command not appearing for users
+
+### Changed
+
+- SKILL.md frontmatter now follows [Agent Skills Specification](https://agentskills.io/specification)
+- Version now stored in `metadata.version` field
+- Removed `${CLAUDE_PLUGIN_ROOT}` variable references from SKILL.md (use relative paths)
+- Updated plugin.json to v2.4.0
+
+### Technical Details
+
+The previous SKILL.md used non-standard frontmatter fields:
+```yaml
+# OLD (broken)
+version: "2.3.0"           # NOT supported at top level
+user-invocable: true       # NOT in official spec
+hooks:                     # NOT supported in SKILL.md
+  PreToolUse: ...
+```
+
+Now uses spec-compliant format:
+```yaml
+# NEW (fixed)
+name: planning-with-files
+description: ...
+license: MIT
+metadata:
+  version: "2.4.0"
+  author: OthmanAdi
+allowed-tools: Read Write Edit Bash Glob Grep WebFetch WebSearch
+```
+
+### Thanks
+
+- @wqh17101 for identifying the issue in #39
+- @dalisoft and @zoffyzhang for reporting the problem
+
+## [2.3.0] - 2026-01-17
+
+### Added
+
+- **Codex IDE Support**
+  - Created `.codex/INSTALL.md` with installation instructions
+  - Skills install to `~/.codex/skills/planning-with-files/`
+  - Works with obra/superpowers or standalone
+  - Added `docs/codex.md` for user documentation
+  - Based on analysis of obra/superpowers Codex implementation
+
+- **OpenCode IDE Support** (Issue #27)
+  - Created `.opencode/INSTALL.md` with installation instructions
+  - Global installation: `~/.config/opencode/skills/planning-with-files/`
+  - Project installation: `.opencode/skills/planning-with-files/`
+  - Works with obra/superpowers plugin or standalone
+  - oh-my-opencode compatibility documented
+  - Added `docs/opencode.md` for user documentation
+  - Based on analysis of obra/superpowers OpenCode plugin
+
+### Changed
+
+- Updated README.md with Supported IDEs table
+- Updated README.md file structure diagram
+- Updated docs/installation.md with Codex and OpenCode sections
+- Version bump to 2.3.0
+
+### Documentation
+
+- Added Codex and OpenCode to IDE support table in README
+- Created comprehensive installation guides for both IDEs
+- Documented skill priority system for OpenCode
+- Documented integration with superpowers ecosystem
+
+### Research
+
+This implementation is based on real analysis of:
+- [obra/superpowers](https://github.com/obra/superpowers) repository
+- Codex skill system and CLI architecture
+- OpenCode plugin system and skill resolution
+- Skill priority and override mechanisms
+
+### Thanks
+
+- @Realtyxxx for feedback on Issue #27 about OpenCode support
+- obra for the superpowers reference implementation
+
+---
+
+## [2.2.2] - 2026-01-17
+
+### Fixed
+
+- **Restored Skill Activation Language** (PR #34)
+  - Restored the activation trigger in SKILL.md description
+  - Description now includes: "Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls"
+  - This language was accidentally removed during the v2.2.1 merge
+  - Helps Claude auto-activate the skill when detecting appropriate tasks
+
+### Changed
+
+- Updated version to 2.2.2 in all SKILL.md files and plugin.json
+
+### Thanks
+
+- Community members for catching this issue
+
+---
+
+## [2.2.1] - 2026-01-17
+
+### Added
+
+- **Session Recovery Feature** (PR #33 by @lasmarois)
+  - Automatically detect and recover unsynced work from previous sessions after `/clear`
+  - New `scripts/session-catchup.py` analyzes previous session JSONL files
+  - Finds last planning file update and extracts conversation that happened after
+  - Recovery triggered automatically when invoking `/planning-with-files`
+  - Pure Python stdlib implementation, no external dependencies
+
+- **PreToolUse Hook Enhancement**
+  - Now triggers on Read/Glob/Grep in addition to Write/Edit/Bash
+  - Keeps task_plan.md in attention during research/exploration phases
+  - Better context management throughout workflow
+
+### Changed
+
+- SKILL.md restructured with session recovery as first instruction
+- Description updated to mention session recovery feature
+- README updated with session recovery workflow and instructions
+
+### Documentation
+
+- Added "Session Recovery" section to README
+- Documented optimal workflow for context window management
+- Instructions for disabling auto-compact in Claude Code settings
+
+### Thanks
+
+Special thanks to:
+- @lasmarois for session recovery implementation (PR #33)
+- Community members for testing and feedback
+
+---
+
+## [2.2.0] - 2026-01-17
+
+### Added
+
+- **Kilo Code Support** (PR #30 by @aimasteracc)
+  - Added Kilo Code IDE compatibility for the planning-with-files skill
+  - Created `.kilocode/rules/planning-with-files.md` with IDE-specific rules
+  - Added `docs/kilocode.md` comprehensive documentation for Kilo Code users
+  - Enables seamless integration with Kilo Code's planning workflow
+
+- **Windows PowerShell Support** (Fixes #32, #25)
+  - Created `check-complete.ps1` - PowerShell equivalent of bash script
+  - Created `init-session.ps1` - PowerShell session initialization
+  - Scripts available in all three locations (root, plugin, skills)
+  - OS-aware hook execution with automatic fallback
+  - Improves Windows user experience with native PowerShell support
+
+- **CONTRIBUTORS.md**
+  - Recognizes all community contributors
+  - Lists code contributors with their impact
+  - Acknowledges issue reporters and testers
+  - Documents community forks
+
+### Fixed
+
+- **Stop Hook Windows Compatibility** (Fixes #32)
+  - Hook now detects Windows environment automatically
+  - Uses PowerShell scripts on Windows, bash on Unix/Linux/Mac
+  - Graceful fallback if PowerShell not available
+  - Tested on Windows 11 PowerShell and Git Bash
+
+- **Script Path Resolution** (Fixes #25)
+  - Improved `${CLAUDE_PLUGIN_ROOT}` handling across platforms
+  - Scripts now work regardless of installation method
+  - Added error handling for missing scripts
+
+### Changed
+
+- **SKILL.md Hook Configuration**
+  - Stop hook now uses multi-line command with OS detection
+  - Supports pwsh (PowerShell Core), powershell (Windows PowerShell), and bash
+  - Automatic fallback chain for maximum compatibility
+
+- **Documentation Updates**
+  - Updated to support both Claude Code and Kilo Code environments
+  - Enhanced template compatibility across different AI coding assistants
+  - Updated `.gitignore` to include `findings.md` and `progress.md`
+
+### Files Added
+
+- `.kilocode/rules/planning-with-files.md` - Kilo Code IDE rules
+- `docs/kilocode.md` - Kilo Code-specific documentation
+- `scripts/check-complete.ps1` - PowerShell completion check (root level)
+- `scripts/init-session.ps1` - PowerShell session init (root level)
+- `planning-with-files/scripts/check-complete.ps1` - PowerShell (plugin level)
+- `planning-with-files/scripts/init-session.ps1` - PowerShell (plugin level)
+- `skills/planning-with-files/scripts/check-complete.ps1` - PowerShell (skills level)
+- `skills/planning-with-files/scripts/init-session.ps1` - PowerShell (skills level)
+- `CONTRIBUTORS.md` - Community contributor recognition
+- `COMPREHENSIVE_ISSUE_ANALYSIS.md` - Detailed issue research and solutions
+
+### Documentation
+
+- Added Windows troubleshooting guidance
+- Recognized community contributors in CONTRIBUTORS.md
+- Updated README to reflect Windows and Kilo Code support
+
+### Thanks
+
+Special thanks to:
+- @aimasteracc for Kilo Code support and PowerShell script contribution (PR #30)
+- @mtuwei for reporting Windows compatibility issues (#32)
+- All community members who tested and provided feedback
+
+  - Root cause: `${CLAUDE_PLUGIN_ROOT}` resolves to repo root, but templates were only in subfolders
+  - Added `templates/` and `scripts/` directories at repo root level
+  - Now templates are accessible regardless of how `CLAUDE_PLUGIN_ROOT` resolves
+  - Works for both plugin installs and manual installs
+
+### Structure
+
+After this fix, templates exist in THREE locations for maximum compatibility:
+- `templates/` - At repo root (for `${CLAUDE_PLUGIN_ROOT}/templates/`)
+- `planning-with-files/templates/` - For plugin marketplace installs
+- `skills/planning-with-files/templates/` - For legacy `~/.claude/skills/` installs
+
+### Workaround for Existing Users
+
+If you still experience issues after updating:
+1. Uninstall: `/plugin uninstall planning-with-files@planning-with-files`
+2. Reinstall: `/plugin marketplace add OthmanAdi/planning-with-files`
+3. Install: `/plugin install planning-with-files@planning-with-files`
+
+---
+
+## [2.1.1] - 2026-01-10
+
+### Fixed
+
+- **Plugin Template Path Issue** (Fixes #15)
+  - Templates weren't found when installed via plugin marketplace
+  - Plugin cache expected `planning-with-files/templates/` at repo root
+  - Added `planning-with-files/` folder at root level for plugin installs
+  - Kept `skills/planning-with-files/` for legacy `~/.claude/skills/` installs
+
+### Structure
+
+- `planning-with-files/` - For plugin marketplace installs
+- `skills/planning-with-files/` - For manual `~/.claude/skills/` installs
+
+---
+
+## [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
@@ -22,7 +335,6 @@ All notable changes to this project will be documented in this file.

 - **New Documentation**
  - `CHANGELOG.md` - This file
-  - `MIGRATION.md` - Guide for upgrading from v1.x

 - **Enhanced SKILL.md**
  - The 2-Action Rule (save findings after every 2 view/browser operations)
@@ -0,0 +1,97 @@
+# Contributors
+
+Thank you to everyone who has contributed to making `planning-with-files` better!
+
+## Project Author
+
+- **[Ahmad Othman Ammar Adi](https://github.com/OthmanAdi)** - Original creator and maintainer
+
+## Code Contributors
+
+These amazing people have contributed code, documentation, or significant improvements to the project:
+
+### Major Contributions
+
+- **[@kaichen](https://github.com/kaichen)** - [PR #9](https://github.com/OthmanAdi/planning-with-files/pull/9)
+  - Converted the repository to Claude Code plugin structure
+  - Enabled marketplace installation
+  - Followed official plugin standards
+  - **Impact:** Made the skill accessible to the masses
+
+- **[@fuahyo](https://github.com/fuahyo)** - [PR #12](https://github.com/OthmanAdi/planning-with-files/pull/12)
+  - Added "Build a todo app" walkthrough with 4 phases
+  - Created inline comments for templates (WHAT/WHY/WHEN/EXAMPLE)
+  - Developed Quick Start guide with ASCII reference tables
+  - Created workflow diagram showing task lifecycle
+  - **Impact:** Dramatically improved beginner onboarding
+
+- **[@lasmarois](https://github.com/lasmarois)** - [PR #33](https://github.com/OthmanAdi/planning-with-files/pull/33)
+  - Created session recovery feature for context preservation after `/clear`
+  - Built `session-catchup.py` script to analyze previous session JSONL files
+  - Enhanced PreToolUse hook to include Read/Glob/Grep operations
+  - Restructured SKILL.md for better session recovery workflow
+  - **Impact:** Solves context loss problem, enables seamless work resumption
+
+- **[@aimasteracc](https://github.com/aimasteracc)** - [PR #30](https://github.com/OthmanAdi/planning-with-files/pull/30)
+  - Added Kilocode IDE support and documentation
+  - Created PowerShell scripts for Windows compatibility
+  - Added `.kilocode/rules/` configuration
+  - Updated documentation for multi-IDE support
+  - **Impact:** Windows compatibility and IDE ecosystem expansion
+
+### Other Contributors
+
+- **[@tobrun](https://github.com/tobrun)** - [PR #3](https://github.com/OthmanAdi/planning-with-files/pull/3)
+  - Early directory structure improvements
+  - Helped identify optimal repository layout
+
+- **[@markocupic024](https://github.com/markocupic024)** - [PR #4](https://github.com/OthmanAdi/planning-with-files/pull/4)
+  - Cursor IDE support contribution
+  - Helped establish multi-IDE pattern
+
+- **Copilot SWE Agent** - [PR #16](https://github.com/OthmanAdi/planning-with-files/pull/16)
+  - Fixed template bundling in plugin.json
+  - Added `assets` field to ensure templates copy to cache
+  - **Impact:** Resolved template path issues
+
+## Community Forks
+
+These developers have created forks that extend the functionality:
+
+- **[@kmichels](https://github.com/kmichels)** - [multi-manus-planning](https://github.com/kmichels/multi-manus-planning)
+  - Multi-project support
+  - SessionStart git sync integration
+
+## Issue Reporters & Testers
+
+Thank you to everyone who reported issues, provided feedback, and helped test fixes:
+
+- [@mtuwei](https://github.com/mtuwei) - Issue #32 (Windows hook error)
+- [@JianweiWangs](https://github.com/JianweiWangs) - Issue #31 (Skill activation)
+- [@tingles2233](https://github.com/tingles2233) - Issue #29 (Plugin update issues)
+- [@st01cs](https://github.com/st01cs) - Issue #28 (Devis fork discussion)
+- [@wqh17101](https://github.com/wqh17101) - Issue #11 testing and confirmation
+
+And many others who have starred, forked, and shared this project!
+
+## How to Contribute
+
+We welcome contributions! Here's how you can help:
+
+1. **Report Issues** - Found a bug? Open an issue with details
+2. **Suggest Features** - Have an idea? Share it in discussions
+3. **Submit PRs** - Code improvements, documentation, examples
+4. **Share** - Tell others about planning-with-files
+5. **Create Forks** - Build on this work (with attribution)
+
+See our [repository](https://github.com/OthmanAdi/planning-with-files) for more details.
+
+## Recognition
+
+If you've contributed and don't see your name here, please open an issue! We want to recognize everyone who helps make this project better.
+
+---
+
+**Total Contributors:** 10+ and growing!
+
+*Last updated: January 17, 2026*
@@ -0,0 +1,119 @@
+## Help Us Test Session Management Features!
+
+I've implemented session management patterns from Anthropic's article ["Effective harnesses for long-running agents"](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) in the **`feature/anthropic-patterns`** branch.
+
+These features need testing before merging to main. **Your feedback is critical!**
+
+---
+
+## What's New
+
+### 1. Session Initialization Script
+Run at the start of every session:
+```bash
+bash scripts/init-session.sh
+```
+
+**What it does:**
+- ✅ Verifies planning files exist
+- ✅ Shows current phase and git status
+- ✅ Displays last commit
+- ✅ Logs session start to progress.md
+- ✅ Creates missing files if needed
+
+### 2. Pass/Fail Status Tracking
+Enhanced `task_plan.md` template with:
+- Status icons: ⏸️ Pending | 🔄 In Progress | ✅ Pass | ❌ Fail | ⏭️ Skipped
+- Test Results table for each phase
+- Git Checkpoints table to log commits
+- Phase Summary table for quick overview
+
+### 3. Git Checkpoint Workflow
+New documentation: `docs/git-checkpoints.md`
+- "One phase, one commit" pattern
+- Use git commits as rollback points
+- Integrates with task_plan.md
+
+### 4. Session-Start Verification
+Automated checklist that verifies:
+- Planning files present
+- Git working tree clean
+- Current branch status
+- Last commit information
+
+---
+
+## How to Test
+
+### 1. Checkout the Branch
+```bash
+cd your-planning-with-files-repo
+git fetch origin
+git checkout feature/anthropic-patterns
+```
+
+### 2. Try It In a Test Project
+```bash
+cd ~/your-test-project
+bash /path/to/planning-with-files/scripts/init-session.sh
+```
+
+### 3. Work Through a Multi-Phase Task
+- Let the script create planning files
+- Define some phases in task_plan.md
+- Complete a phase and test it
+- Mark it as ✅ Pass with test results
+- Commit: `git commit -m "feat(Phase 1): description"`
+- Log the commit hash in Git Checkpoints table
+- Start a new session and run init-session.sh again
+
+### 4. Read the Implementation Summary
+See `IMPLEMENTATION_SUMMARY.md` in the branch for full details.
+
+---
+
+## What We Need Feedback On
+
+1. **Does init-session.sh work on your system?**
+   - Unix/Mac: Does the bash script run smoothly?
+   - Windows: Does the PowerShell version work?
+
+2. **Is the new task_plan.md template helpful?**
+   - Are the status icons clear?
+   - Is the Test Results table useful?
+   - Does the Git Checkpoints table make sense?
+
+3. **Does the workflow feel natural?**
+   - Plan → Implement → Verify → Commit
+   - Does session recovery work when you restart?
+
+4. **Any bugs or issues?**
+   - Errors when running scripts?
+   - Confusing documentation?
+   - Missing features?
+
+5. **Suggestions for improvement?**
+   - What would make this better?
+   - Any patterns from the Anthropic article we missed?
+
+---
+
+## Related Issue
+
+This work resolves [Issue #19](https://github.com/OthmanAdi/planning-with-files/issues/19) requested by @wqh17101.
+
+---
+
+## Documentation
+
+- [Git Checkpoint Workflow](https://github.com/OthmanAdi/planning-with-files/blob/feature/anthropic-patterns/docs/git-checkpoints.md)
+- [Implementation Summary](https://github.com/OthmanAdi/planning-with-files/blob/feature/anthropic-patterns/IMPLEMENTATION_SUMMARY.md)
+- [Anthropic Article](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) (inspiration)
+
+---
+
+**Please test and share your experience!** Once we have enough feedback and approval, I'll merge this to main.
+
+Thank you!
+
+Ahmad
@@ -10,36 +10,66 @@ 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)
 [![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)
+[![Version](https://img.shields.io/badge/version-2.3.0-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)
+
+## Quick Install
+
+```bash
+/plugin marketplace add OthmanAdi/planning-with-files
+/plugin install planning-with-files@planning-with-files
+```
+
+See [docs/installation.md](docs/installation.md) for all installation methods.
+
+## Supported IDEs
+
+| IDE | Status | Installation Guide | Format |
+|-----|--------|-------------------|--------|
+| Claude Code | ✅ Full Support | [Installation](docs/installation.md) | Plugin + SKILL.md |
+| Cursor | ✅ Full Support | [Cursor Setup](docs/cursor.md) | Rules |
+| Kilocode | ✅ Full Support | [Kilocode Setup](docs/kilocode.md) | Rules |
+| OpenCode | ✅ Full Support | [OpenCode Setup](docs/opencode.md) | Personal/Project Skill |
+| Codex | ✅ Full Support | [Codex Setup](docs/codex.md) | Personal Skill |
+
+## 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 |
+| [Kilo Code Support](docs/kilocode.md) | Kilo Code integration guide |
+| [Codex Setup](docs/codex.md) | Codex IDE installation and usage |
+| [OpenCode Setup](docs/opencode.md) | OpenCode IDE installation, oh-my-opencode config |

 ## 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` |
+| Version | Features | Install |
+|---------|----------|---------|
+| **v2.3.0** (current) | Codex & OpenCode IDE support | `/plugin install planning-with-files@planning-with-files` |
+| **v2.2.2** | Restored skill activation language | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
+| **v2.2.1** | Session recovery after /clear, enhanced PreToolUse hook | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
+| **v2.2.0** | Kilo Code IDE support, Windows PowerShell support, OS-aware hooks | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
+| **v2.1.2** | Fix template cache issue (Issue #18) | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
+| **v2.1.0** | Claude Code v2.1 compatible, PostToolUse hook, user-invocable | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
+| **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` |

-## What's New in v2.0.0
-
- **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
-
-See [CHANGELOG.md](CHANGELOG.md) for details. Upgrading from v1.x? See [MIGRATION.md](MIGRATION.md).
+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

@@ -71,184 +101,114 @@ 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/
-```
-
-### 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:

 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.
+
+## Session Recovery (NEW in v2.2.0)
+
+When your context window fills up and you run `/clear`, this skill automatically recovers unsynced work from your previous session.
+
+### Optimal Workflow
+
+For the best experience, we recommend:
+
+1. **Disable auto-compact** in Claude Code settings (use full context window)
+2. **Start a fresh session** in your project
+3. **Run `/planning-with-files`** when ready to work on a complex task
+4. **Work until context fills up** (Claude will warn you)
+5. **Run `/clear`** to start fresh
+6. **Run `/planning-with-files`** again — it will automatically recover where you left off
+
+### How Recovery Works
+
+When you invoke `/planning-with-files`, the skill:
+
+1. Checks for previous session data (stored in `~/.claude/projects/`)
+2. Finds the last time planning files were updated
+3. Extracts conversation that happened after (potentially lost context)
+4. Shows a catchup report so you can sync planning files
+
+This means even if context filled up before you could update your planning files, the skill will recover that context in your next session.
+
+### Disabling Auto-Compact
+
+To use the full context window without automatic compaction:
+
+```bash
+# In your Claude Code settings or .claude/settings.json
+{
+  "autoCompact": false
+}
+```
+
+This lets you maximize context usage before manually clearing with `/clear`.
+
+## 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
 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

 ```
 planning-with-files/
-├── .claude-plugin/
-│   ├── plugin.json          # Plugin manifest
-│   └── marketplace.json     # Marketplace listing
-├── .cursor/
-│   └── rules/
-│       └── planning-with-files.mdc  # Cursor rules file
-├── skills/
+├── templates/               # Root-level templates (for CLAUDE_PLUGIN_ROOT)
+├── scripts/                 # Root-level scripts (for CLAUDE_PLUGIN_ROOT)
+├── docs/                    # Documentation
+│   ├── installation.md
+│   ├── quickstart.md
+│   ├── workflow.md
+│   ├── troubleshooting.md
+│   ├── cursor.md
+│   ├── windows.md
+│   ├── kilocode.md
+│   ├── codex.md
+│   └── opencode.md
+├── planning-with-files/     # Plugin skill folder
+│   ├── SKILL.md
+│   ├── templates/
+│   └── scripts/
+├── skills/                  # Legacy skill folder
 │   └── 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
+│       ├── SKILL.md
+│       ├── examples.md
+│       ├── reference.md
+│       ├── templates/
+│       └── scripts/
 │           ├── init-session.sh
-│           └── check-complete.sh
-├── CHANGELOG.md             # Version history
-├── MIGRATION.md             # Upgrade guide
+│           ├── check-complete.sh
+│           ├── init-session.ps1   # Windows PowerShell
+│           └── check-complete.ps1 # Windows PowerShell
+├── .codex/                  # Codex IDE installation guide
+│   └── INSTALL.md
+├── .opencode/               # OpenCode IDE installation guide
+│   └── INSTALL.md
+├── .claude-plugin/          # Plugin manifest
+├── .cursor/                 # Cursor rules
+├── .kilocode/               # Kilo Code rules
+│   └── rules/
+│       └── planning-with-files.md
+├── CHANGELOG.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 |
@@ -264,13 +224,31 @@ 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

+## Kilo Code Support
+
+This skill also supports Kilo Code AI through the `.kilocode/rules/` directory.
+
+The [`.kilocode/rules/planning-with-files.md`](.kilocode/rules/planning-with-files.md) file contains all the planning guidelines formatted for Kilo Code's rules system, providing the same Manus-style planning workflow for Kilo Code users.
+
+**Windows users:** The skill now includes PowerShell scripts ([`init-session.ps1`](skills/planning-with-files/scripts/init-session.ps1) and [`check-complete.ps1`](skills/planning-with-files/scripts/check-complete.ps1)) for native Windows support.
+
+See [docs/kilocode.md](docs/kilocode.md) for detailed Kilo Code integration guide.
+
+## Community Forks
+
+| Fork | Author | Features |
+|------|--------|----------|
+| [devis](https://github.com/st01cs/devis) | [@st01cs](https://github.com/st01cs) | Interview-first workflow, `/devis:intv` and `/devis:impl` commands, guaranteed activation |
+| [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,79 @@
+# Welcome to planning-with-files
+
+> **Work like Manus** — the AI agent company Meta acquired for **$2 billion**.
+
+This is a Claude Code skill that transforms your workflow to use persistent markdown files for planning, progress tracking, and knowledge storage.
+
+## What This Project Does
+
+Instead of relying on volatile context windows, planning-with-files teaches Claude to use **files as memory**:
+
+- `task_plan.md` - Your roadmap (phases, progress, decisions)
+- `findings.md` - Research and discoveries
+- `progress.md` - Session logs and test results
+
+When context fills up, you don't lose work. Everything important is on disk.
+
+## Why It Exists
+
+After 50+ tool calls, Claude forgets your original goals. This skill solves that by:
+- Re-reading the plan before major decisions (hooks)
+- Storing findings in files instead of context
+- Logging errors to prevent repetition
+- Verifying completion before stopping
+
+## Inspired By
+
+Manus AI pioneered this pattern and went from launch to $100M+ revenue in 8 months. Their secret? **Context engineering through persistent files.**
+
+## Community ❤️
+
+This project grew from **one developer's experiment** to **9,600+ stars** and **10+ contributors** in weeks.
+
+**Thank you to everyone who:**
+- ⭐ Starred the repo
+- 🔀 Forked and built on this work
+- 🐛 Reported issues and tested fixes
+- 💡 Suggested features and improvements
+- 🛠️ Contributed code, docs, and examples
+
+### Special Thanks
+
+- **[@kaichen](https://github.com/kaichen)** - Converted to Claude Code plugin, made it accessible to thousands
+- **[@fuahyo](https://github.com/fuahyo)** - Created beginner-friendly walkthrough and examples
+- **[@lasmarois](https://github.com/lasmarois)** - Built session recovery feature, saved countless hours
+- **[@aimasteracc](https://github.com/aimasteracc)** - Added Windows support and Kilocode integration
+- **[@wqh17101](https://github.com/wqh17101)** - Inspired Anthropic patterns integration
+
+And many more! See [CONTRIBUTORS.md](https://github.com/OthmanAdi/planning-with-files/blob/main/CONTRIBUTORS.md)
+
+## Growing Together
+
+What started as a simple 3-file pattern is now:
+- 5 IDE integrations (Claude Code, Cursor, Kilocode, OpenCode, Codex)
+- Session recovery after `/clear`
+- Git checkpoint workflows
+- Windows PowerShell support
+- Community forks and derivatives
+
+**None of this would exist without you.**
+
+## Get Involved
+
+- 💬 [Discussions](https://github.com/OthmanAdi/planning-with-files/discussions) - Share your experience
+- 🐛 [Issues](https://github.com/OthmanAdi/planning-with-files/issues) - Report bugs or request features
+- 🔀 [Pull Requests](https://github.com/OthmanAdi/planning-with-files/pulls) - Contribute improvements
+- ⭐ Star if this helps you work smarter
+
+## Quick Links
+
+- [Installation Guide](https://github.com/OthmanAdi/planning-with-files/blob/main/docs/installation.md)
+- [Quick Start](https://github.com/OthmanAdi/planning-with-files/blob/main/docs/quickstart.md)
+- [Examples](https://github.com/OthmanAdi/planning-with-files/blob/main/examples/README.md)
+- [Changelog](https://github.com/OthmanAdi/planning-with-files/blob/main/CHANGELOG.md)
+
+---
+
+**Built with appreciation for the open source community.**
+
+*Ahmad Othman Ammar Adi*
@@ -0,0 +1,52 @@
+# Codex IDE Support
+
+## Overview
+
+planning-with-files works with Codex as a personal skill in `~/.codex/skills/`.
+
+## Installation
+
+See [.codex/INSTALL.md](../.codex/INSTALL.md) for detailed installation instructions.
+
+### Quick Install
+
+```bash
+mkdir -p ~/.codex/skills
+cd ~/.codex/skills
+git clone https://github.com/OthmanAdi/planning-with-files.git
+```
+
+## Usage with Superpowers
+
+If you have [obra/superpowers](https://github.com/obra/superpowers) installed:
+
+```bash
+~/.codex/superpowers/.codex/superpowers-codex use-skill planning-with-files
+```
+
+## Usage without Superpowers
+
+Add to your `~/.codex/AGENTS.md`:
+
+```markdown
+## Planning with Files
+
+<IMPORTANT>
+For complex tasks (3+ steps, research, projects):
+1. Read skill: `cat ~/.codex/skills/planning-with-files/planning-with-files/SKILL.md`
+2. Create task_plan.md, findings.md, progress.md in your project directory
+3. Follow 3-file pattern throughout the task
+</IMPORTANT>
+```
+
+## Verification
+
+```bash
+ls -la ~/.codex/skills/planning-with-files/planning-with-files/SKILL.md
+```
+
+## Learn More
+
+- [Installation Guide](installation.md)
+- [Quick Start](quickstart.md)
+- [Workflow Diagram](workflow.md)
@@ -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,168 @@
+# 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.
+
+### Codex
+
+See [docs/codex.md](codex.md) for Codex IDE installation.
+
+### OpenCode
+
+See [docs/opencode.md](opencode.md) for OpenCode 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,233 @@
+# Kilo Code Support
+
+Planning with Files is fully supported on Kilo Code through native integration.
+
+## Quick Start
+
+1. Open your project in Kilo Code
+2. Rules load automatically from global (`~/.kilocode/rules/`) or project (`.kilocode/rules/`) directories
+3. Start a complex task — Kilo Code will automatically create planning files
+
+## Installation
+
+### Quick Install (Project-Level)
+
+Clone or copy the skill to your project's `.kilocode/skills/` directory:
+
+**Unix/Linux/macOS:**
+```bash
+# Option A: Clone the repository
+git clone https://github.com/OthmanAdi/planning-with-files.git
+
+# Copy the skill to Kilo Code's skills directory
+mkdir -p .kilocode/skills
+cp -r planning-with-files/skills/planning-with-files .kilocode/skills/planning-with-files
+
+# Copy the rules file (optional, but recommended)
+mkdir -p .kilocode/rules
+cp planning-with-files/.kilocode/rules/planning-with-files.md .kilocode/rules/planning-with-files.md
+```
+
+**Windows (PowerShell):**
+```powershell
+# Option A: Clone the repository
+git clone https://github.com/OthmanAdi/planning-with-files.git
+
+# Copy the skill to Kilo Code's skills directory
+New-Item -ItemType Directory -Force -Path .kilocode\skills
+Copy-Item -Recurse -Force planning-with-files\skills\planning-with-files .kilocode\skills\planning-with-files
+
+# Copy the rules file (optional, but recommended)
+New-Item -ItemType Directory -Force -Path .kilocode\rules
+Copy-Item -Force planning-with-files\.kilocode\rules\planning-with-files.md .kilocode\rules\planning-with-files.md
+
+# Copy PowerShell scripts (optional, but recommended)
+Copy-Item -Force planning-with-files\scripts\init-session.ps1 .kilocode\skills\planning-with-files\scripts\init-session.ps1
+Copy-Item -Force planning-with-files\scripts\check-complete.ps1 .kilocode\skills\planning-with-files\scripts\check-complete.ps1
+```
+
+### Manual Installation (Project-Level)
+
+Copy the skill directory to your project:
+
+**Unix/Linux/macOS:**
+```bash
+# From the cloned repository
+mkdir -p .kilocode/skills
+cp -r planning-with-files/skills/planning-with-files .kilocode/skills/planning-with-files
+
+# Copy the rules file (optional, but recommended)
+mkdir -p .kilocode/rules
+cp planning-with-files/.kilocode/rules/planning-with-files.md .kilocode/rules/planning-with-files.md
+```
+
+**Windows (PowerShell):**
+```powershell
+# From the cloned repository
+New-Item -ItemType Directory -Force -Path .kilocode\skills
+Copy-Item -Recurse -Force planning-with-files\skills\planning-with-files .kilocode\skills\planning-with-files
+
+# Copy the rules file (optional, but recommended)
+New-Item -ItemType Directory -Force -Path .kilocode\rules
+Copy-Item -Force planning-with-files\.kilocode\rules\planning-with-files.md .kilocode\rules\planning-with-files.md
+
+# Copy PowerShell scripts (optional, but recommended)
+Copy-Item -Force planning-with-files\scripts\init-session.ps1 .kilocode\skills\planning-with-files\scripts\init-session.ps1
+Copy-Item -Force planning-with-files\scripts\check-complete.ps1 .kilocode\skills\planning-with-files\scripts\check-complete.ps1
+```
+
+### Global Installation (User-Level)
+
+To make the skill available across all projects:
+
+**Unix/Linux/macOS:**
+```bash
+# Copy to global skills directory
+mkdir -p ~/.kilocode/skills
+cp -r planning-with-files/skills/planning-with-files ~/.kilocode/skills/planning-with-files
+
+# Copy the rules file (optional, but recommended)
+mkdir -p ~/.kilocode/rules
+cp planning-with-files/.kilocode/rules/planning-with-files.md ~/.kilocode/rules/planning-with-files.md
+```
+
+**Windows (PowerShell):**
+```powershell
+# Copy to global skills directory (replace YourUsername with your actual username)
+New-Item -ItemType Directory -Force -Path C:\Users\YourUsername\.kilocode\skills
+Copy-Item -Recurse -Force planning-with-files\skills\planning-with-files C:\Users\YourUsername\.kilocode\skills\planning-with-files
+
+# Copy the rules file (optional, but recommended)
+New-Item -ItemType Directory -Force -Path C:\Users\YourUsername\.kilocode\rules
+Copy-Item -Force planning-with-files\.kilocode\rules\planning-with-files.md C:\Users\YourUsername\.kilocode\rules\planning-with-files.md
+
+# Copy PowerShell scripts (optional, but recommended)
+Copy-Item -Force planning-with-files\scripts\init-session.ps1 C:\Users\YourUsername\.kilocode\skills\planning-with-files\scripts\init-session.ps1
+Copy-Item -Force planning-with-files\scripts\check-complete.ps1 C:\Users\YourUsername\.kilocode\skills\planning-with-files\scripts\check-complete.ps1
+```
+
+### Verifying Installation
+
+After installation, verify the skill is loaded:
+
+1. **Restart Kilo Code** (if needed)
+2. Ask the agent: "Do you have access to the planning-with-files skill?"
+3. The agent should confirm the skill is loaded
+4. Rules also load automatically from `~/.kilocode/rules/planning-with-files.md` (global) or `.kilocode/rules/planning-with-files.md` (project)
+
+**Testing PowerShell Scripts (Windows):**
+
+After installation, you can test the PowerShell scripts:
+
+```powershell
+# Test init-session.ps1
+.\.kilocode\skills\planning-with-files\scripts\init-session.ps1
+
+# Test check-complete.ps1
+.\.kilocode\skills\planning-with-files\scripts\check-complete.ps1
+```
+
+The scripts should create `task_plan.md`, `findings.md`, and `progress.md` files in your project root.
+
+### File Structure
+
+The installation consists of the skill directory and the rules file:
+
+**Skill Directory:**
+
+```
+~/.kilocode/skills/planning-with-files/          (Global)
+OR
+.kilocode/skills/planning-with-files/             (Project)
+├── SKILL.md              # Skill definition
+├── examples.md           # Real-world examples
+├── reference.md          # Advanced reference
+├── templates/            # Planning file templates
+│   ├── task_plan.md
+│   ├── findings.md
+│   └── progress.md
+└── scripts/              # Utility scripts
+    ├── init-session.sh    # Unix/Linux/macOS
+    ├── check-complete.sh  # Unix/Linux/macOS
+    ├── init-session.ps1  # Windows (PowerShell)
+    └── check-complete.ps1 # Windows (PowerShell)
+```
+
+**Rules File:**
+
+```
+~/.kilocode/rules/planning-with-files.md        (Global)
+OR
+.kilocode/rules/planning-with-files.md           (Project)
+```
+
+**Important**: The `name` field in `SKILL.md` must match the directory name (`planning-with-files`).
+
+## File Locations
+
+| Type | Global Location | Project Location |
+|------|-----------------|------------------|
+| **Rules** | `~/.kilocode/rules/planning-with-files.md` | `.kilocode/rules/planning-with-files.md` |
+| **Skill** | `~/.kilocode/skills/planning-with-files/SKILL.md` | `.kilocode/skills/planning-with-files/SKILL.md` |
+| **Templates** | `~/.kilocode/skills/planning-with-files/templates/` | `.kilocode/skills/planning-with-files/templates/` |
+| **Scripts (Unix/Linux/macOS)** | `~/.kilocode/skills/planning-with-files/scripts/*.sh` | `.kilocode/skills/planning-with-files/scripts/*.sh` |
+| **Scripts (Windows PowerShell)** | `~/.kilocode/skills/planning-with-files/scripts/*.ps1` | `.kilocode/skills/planning-with-files/scripts/*.ps1` |
+| **Your Files** | `task_plan.md`, `findings.md`, `progress.md` in project root |
+
+## Quick Commands
+
+**For Global Installation:**
+
+**Unix/Linux/macOS:**
+```bash
+# Initialize planning files
+~/.kilocode/skills/planning-with-files/scripts/init-session.sh
+
+# Verify task completion
+~/.kilocode/skills/planning-with-files/scripts/check-complete.sh
+```
+
+**Windows (PowerShell):**
+```powershell
+# Initialize planning files
+$env:USERPROFILE\.kilocode\skills\planning-with-files\scripts\init-session.ps1
+
+# Verify task completion
+$env:USERPROFILE\.kilocode\skills\planning-with-files\scripts\check-complete.ps1
+```
+
+**For Project Installation:**
+
+**Unix/Linux/macOS:**
+```bash
+# Initialize planning files
+./.kilocode/skills/planning-with-files/scripts/init-session.sh
+
+# Verify task completion
+./.kilocode/skills/planning-with-files/scripts/check-complete.sh
+```
+
+**Windows (PowerShell):**
+```powershell
+# Initialize planning files
+.\.kilocode\skills\planning-with-files\scripts\init-session.ps1
+
+# Verify task completion
+.\.kilocode\skills\planning-with-files\scripts\check-complete.ps1
+```
+
+## Migrating from Cursor/Windsurf
+
+Planning files are fully compatible. Simply copy your `task_plan.md`, `findings.md`, and `progress.md` files to your new project.
+
+## Additional Resources
+
+**For Global Installation:**
+- [Examples](~/.kilocode/skills/planning-with-files/examples.md) - Real-world examples
+- [Reference](~/.kilocode/skills/planning-with-files/reference.md) - Advanced reference documentation
+- [PowerShell Scripts](~/.kilocode/skills/planning-with-files/scripts/) - Utility scripts for Windows
+
+**For Project Installation:**
+- [Examples](.kilocode/skills/planning-with-files/examples.md) - Real-world examples
+- [Reference](.kilocode/skills/planning-with-files/reference.md) - Advanced reference documentation
+- [PowerShell Scripts](.kilocode/skills/planning-with-files/scripts/) - Utility scripts for Windows
@@ -0,0 +1,70 @@
+# OpenCode IDE Support
+
+## Overview
+
+planning-with-files works with OpenCode as a personal or project skill.
+
+## Installation
+
+See [.opencode/INSTALL.md](../.opencode/INSTALL.md) for detailed installation instructions.
+
+### Quick Install (Global)
+
+```bash
+mkdir -p ~/.config/opencode/skills
+cd ~/.config/opencode/skills
+git clone https://github.com/OthmanAdi/planning-with-files.git
+```
+
+### Quick Install (Project)
+
+```bash
+mkdir -p .opencode/skills
+cd .opencode/skills
+git clone https://github.com/OthmanAdi/planning-with-files.git
+```
+
+## Usage with Superpowers Plugin
+
+If you have [obra/superpowers](https://github.com/obra/superpowers) OpenCode plugin:
+
+```
+Use the use_skill tool with skill_name: "planning-with-files"
+```
+
+## Usage without Superpowers
+
+Manually read the skill file when starting complex tasks:
+
+```bash
+cat ~/.config/opencode/skills/planning-with-files/planning-with-files/SKILL.md
+```
+
+## oh-my-opencode Compatibility
+
+If using oh-my-opencode, ensure planning-with-files is not in the `disabled_skills` array:
+
+**~/.config/opencode/oh-my-opencode.json:**
+```json
+{
+  "disabled_skills": []
+}
+```
+
+## Verification
+
+**Global:**
+```bash
+ls -la ~/.config/opencode/skills/planning-with-files/planning-with-files/SKILL.md
+```
+
+**Project:**
+```bash
+ls -la .opencode/skills/planning-with-files/planning-with-files/SKILL.md
+```
+
+## Learn More
+
+- [Installation Guide](installation.md)
+- [Quick Start](quickstart.md)
+- [Workflow Diagram](workflow.md)
@@ -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,240 @@
+# Troubleshooting
+
+Common issues and their solutions.
+
+---
+
+## Templates not found in cache (after update)
+
+**Issue:** After updating to a new version, `/planning-with-files` fails with "template files not found in cache" or similar errors.
+
+**Why this happens:** Claude Code caches plugin files, and the cache may not refresh properly after an update.
+
+**Solutions:**
+
+### Solution 1: Clean reinstall (Recommended)
+
+```bash
+/plugin uninstall planning-with-files@planning-with-files
+/plugin marketplace add OthmanAdi/planning-with-files
+/plugin install planning-with-files@planning-with-files
+```
+
+### Solution 2: Clear Claude Code cache
+
+Restart Claude Code completely (close and reopen terminal/IDE).
+
+### Solution 3: Manual cache clear
+
+```bash
+# Find and remove cached plugin
+rm -rf ~/.claude/cache/plugins/planning-with-files
+```
+
+Then reinstall the plugin.
+
+**Note:** This was fixed in v2.1.2 by adding templates at the repo root level.
+
+---
+
+## 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

 ---

@@ -0,0 +1,42 @@
+# Check if all phases in task_plan.md are complete
+# Exit 0 if complete, exit 1 if incomplete
+# Used by Stop hook to verify task completion
+
+param(
+    [string]$PlanFile = "task_plan.md"
+)
+
+if (-not (Test-Path $PlanFile)) {
+    Write-Host "ERROR: $PlanFile not found"
+    Write-Host "Cannot verify completion without a task plan."
+    exit 1
+}
+
+Write-Host "=== Task Completion Check ==="
+Write-Host ""
+
+# Read file content
+$content = Get-Content $PlanFile -Raw
+
+# Count phases by status
+$TOTAL = ([regex]::Matches($content, "### Phase")).Count
+$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
+$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
+$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
+
+Write-Host "Total phases:   $TOTAL"
+Write-Host "Complete:       $COMPLETE"
+Write-Host "In progress:    $IN_PROGRESS"
+Write-Host "Pending:        $PENDING"
+Write-Host ""
+
+# Check completion
+if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
+    Write-Host "ALL PHASES COMPLETE"
+    exit 0
+} else {
+    Write-Host "TASK NOT COMPLETE"
+    Write-Host ""
+    Write-Host "Do not stop until all phases are complete."
+    exit 1
+}
@@ -0,0 +1,44 @@
+#!/bin/bash
+# Check if all phases in task_plan.md are complete
+# Exit 0 if complete, exit 1 if incomplete
+# Used by Stop hook to verify task completion
+
+PLAN_FILE="${1:-task_plan.md}"
+
+if [ ! -f "$PLAN_FILE" ]; then
+    echo "ERROR: $PLAN_FILE not found"
+    echo "Cannot verify completion without a task plan."
+    exit 1
+fi
+
+echo "=== Task Completion Check ==="
+echo ""
+
+# 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"
+echo "In progress:    $IN_PROGRESS"
+echo "Pending:        $PENDING"
+echo ""
+
+# Check completion
+if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
+    echo "ALL PHASES COMPLETE"
+    exit 0
+else
+    echo "TASK NOT COMPLETE"
+    echo ""
+    echo "Do not stop until all phases are complete."
+    exit 1
+fi
@@ -0,0 +1,120 @@
+# Initialize planning files for a new session
+# Usage: .\init-session.ps1 [project-name]
+
+param(
+    [string]$ProjectName = "project"
+)
+
+$DATE = Get-Date -Format "yyyy-MM-dd"
+
+Write-Host "Initializing planning files for: $ProjectName"
+
+# Create task_plan.md if it doesn't exist
+if (-not (Test-Path "task_plan.md")) {
+    @"
+# 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
+- [ ] Document in findings.md
+- **Status:** in_progress
+
+### Phase 2: Planning & Structure
+- [ ] Define approach
+- [ ] Create project structure
+- **Status:** pending
+
+### Phase 3: Implementation
+- [ ] Execute the plan
+- [ ] Write to files before executing
+- **Status:** pending
+
+### Phase 4: Testing & Verification
+- [ ] Verify requirements met
+- [ ] Document test results
+- **Status:** pending
+
+### Phase 5: Delivery
+- [ ] Review outputs
+- [ ] Deliver to user
+- **Status:** pending
+
+## Decisions Made
+| Decision | Rationale |
+|----------|-----------|
+
+## Errors Encountered
+| Error | Resolution |
+|-------|------------|
+"@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
+    Write-Host "Created task_plan.md"
+} else {
+    Write-Host "task_plan.md already exists, skipping"
+}
+
+# Create findings.md if it doesn't exist
+if (-not (Test-Path "findings.md")) {
+    @"
+# Findings & Decisions
+
+## Requirements
+-
+
+## Research Findings
+-
+
+## Technical Decisions
+| Decision | Rationale |
+|----------|-----------|
+
+## Issues Encountered
+| Issue | Resolution |
+|-------|------------|
+
+## Resources
+-
+"@ | Out-File -FilePath "findings.md" -Encoding UTF8
+    Write-Host "Created findings.md"
+} else {
+    Write-Host "findings.md already exists, skipping"
+}
+
+# Create progress.md if it doesn't exist
+if (-not (Test-Path "progress.md")) {
+    @"
+# Progress Log
+
+## Session: $DATE
+
+### Current Status
+- **Phase:** 1 - Requirements & Discovery
+- **Started:** $DATE
+
+### Actions Taken
+-
+
+### Test Results
+| Test | Expected | Actual | Status |
+|------|----------|--------|--------|
+
+### Errors
+| Error | Resolution |
+|-------|------------|
+"@ | Out-File -FilePath "progress.md" -Encoding UTF8
+    Write-Host "Created progress.md"
+} else {
+    Write-Host "progress.md already exists, skipping"
+}
+
+Write-Host ""
+Write-Host "Planning files initialized!"
+Write-Host "Files: task_plan.md, findings.md, progress.md"
@@ -0,0 +1,120 @@
+#!/bin/bash
+# Initialize planning files for a new session
+# Usage: ./init-session.sh [project-name]
+
+set -e
+
+PROJECT_NAME="${1:-project}"
+DATE=$(date +%Y-%m-%d)
+
+echo "Initializing planning files for: $PROJECT_NAME"
+
+# Create task_plan.md if it doesn't exist
+if [ ! -f "task_plan.md" ]; then
+    cat > task_plan.md << 'EOF'
+# 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
+- [ ] Document in findings.md
+- **Status:** in_progress
+
+### Phase 2: Planning & Structure
+- [ ] Define approach
+- [ ] Create project structure
+- **Status:** pending
+
+### Phase 3: Implementation
+- [ ] Execute the plan
+- [ ] Write to files before executing
+- **Status:** pending
+
+### Phase 4: Testing & Verification
+- [ ] Verify requirements met
+- [ ] Document test results
+- **Status:** pending
+
+### Phase 5: Delivery
+- [ ] Review outputs
+- [ ] Deliver to user
+- **Status:** pending
+
+## Decisions Made
+| Decision | Rationale |
+|----------|-----------|
+
+## Errors Encountered
+| Error | Resolution |
+|-------|------------|
+EOF
+    echo "Created task_plan.md"
+else
+    echo "task_plan.md already exists, skipping"
+fi
+
+# Create findings.md if it doesn't exist
+if [ ! -f "findings.md" ]; then
+    cat > findings.md << 'EOF'
+# Findings & Decisions
+
+## Requirements
+-
+
+## Research Findings
+-
+
+## Technical Decisions
+| Decision | Rationale |
+|----------|-----------|
+
+## Issues Encountered
+| Issue | Resolution |
+|-------|------------|
+
+## Resources
+-
+EOF
+    echo "Created findings.md"
+else
+    echo "findings.md already exists, skipping"
+fi
+
+# Create progress.md if it doesn't exist
+if [ ! -f "progress.md" ]; then
+    cat > progress.md << EOF
+# Progress Log
+
+## Session: $DATE
+
+### Current Status
+- **Phase:** 1 - Requirements & Discovery
+- **Started:** $DATE
+
+### Actions Taken
+-
+
+### Test Results
+| Test | Expected | Actual | Status |
+|------|----------|--------|--------|
+
+### Errors
+| Error | Resolution |
+|-------|------------|
+EOF
+    echo "Created progress.md"
+else
+    echo "progress.md already exists, skipping"
+fi
+
+echo ""
+echo "Planning files initialized!"
+echo "Files: task_plan.md, findings.md, progress.md"
@@ -0,0 +1,278 @@
+#!/usr/bin/env python3
+"""
+Session Catchup Script for planning-with-files
+
+Session-agnostic scanning: finds the most recent planning file update across
+ALL sessions, then collects all conversation from that point forward through
+all subsequent sessions until now.
+
+Usage: python3 session-catchup.py [project-path]
+"""
+
+import json
+import sys
+import os
+from pathlib import Path
+from typing import List, Dict, Optional, Tuple
+
+PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
+
+
+def get_project_dir(project_path: str) -> Path:
+    """Convert project path to Claude's storage path format."""
+    sanitized = project_path.replace('/', '-')
+    if not sanitized.startswith('-'):
+        sanitized = '-' + sanitized
+    sanitized = sanitized.replace('_', '-')
+    return Path.home() / '.claude' / 'projects' / sanitized
+
+
+def get_sessions_sorted(project_dir: Path) -> List[Path]:
+    """Get all session files sorted by modification time (newest first)."""
+    sessions = list(project_dir.glob('*.jsonl'))
+    main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
+    return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
+
+
+def get_session_first_timestamp(session_file: Path) -> Optional[str]:
+    """Get the timestamp of the first message in a session."""
+    try:
+        with open(session_file, 'r') as f:
+            for line in f:
+                try:
+                    data = json.loads(line)
+                    ts = data.get('timestamp')
+                    if ts:
+                        return ts
+                except:
+                    continue
+    except:
+        pass
+    return None
+
+
+def scan_for_planning_update(session_file: Path) -> Tuple[int, Optional[str]]:
+    """
+    Quickly scan a session file for planning file updates.
+    Returns (line_number, filename) of last update, or (-1, None) if none found.
+    """
+    last_update_line = -1
+    last_update_file = None
+
+    try:
+        with open(session_file, 'r') as f:
+            for line_num, line in enumerate(f):
+                if '"Write"' not in line and '"Edit"' not in line:
+                    continue
+
+                try:
+                    data = json.loads(line)
+                    if data.get('type') != 'assistant':
+                        continue
+
+                    content = data.get('message', {}).get('content', [])
+                    if not isinstance(content, list):
+                        continue
+
+                    for item in content:
+                        if item.get('type') != 'tool_use':
+                            continue
+                        tool_name = item.get('name', '')
+                        if tool_name not in ('Write', 'Edit'):
+                            continue
+
+                        file_path = item.get('input', {}).get('file_path', '')
+                        for pf in PLANNING_FILES:
+                            if file_path.endswith(pf):
+                                last_update_line = line_num
+                                last_update_file = pf
+                                break
+                except json.JSONDecodeError:
+                    continue
+    except Exception:
+        pass
+
+    return last_update_line, last_update_file
+
+
+def extract_messages_from_session(session_file: Path, after_line: int = -1) -> List[Dict]:
+    """
+    Extract conversation messages from a session file.
+    If after_line >= 0, only extract messages after that line.
+    If after_line < 0, extract all messages.
+    """
+    result = []
+
+    try:
+        with open(session_file, 'r') as f:
+            for line_num, line in enumerate(f):
+                if after_line >= 0 and line_num <= after_line:
+                    continue
+
+                try:
+                    msg = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+
+                msg_type = msg.get('type')
+                is_meta = msg.get('isMeta', False)
+
+                if msg_type == 'user' and not is_meta:
+                    content = msg.get('message', {}).get('content', '')
+                    if isinstance(content, list):
+                        for item in content:
+                            if isinstance(item, dict) and item.get('type') == 'text':
+                                content = item.get('text', '')
+                                break
+                        else:
+                            content = ''
+
+                    if content and isinstance(content, str):
+                        # Skip system/command messages
+                        if content.startswith(('<local-command', '<command-', '<task-notification')):
+                            continue
+                        if len(content) > 20:
+                            result.append({
+                                'role': 'user',
+                                'content': content,
+                                'line': line_num,
+                                'session': session_file.stem[:8]
+                            })
+
+                elif msg_type == 'assistant':
+                    msg_content = msg.get('message', {}).get('content', '')
+                    text_content = ''
+                    tool_uses = []
+
+                    if isinstance(msg_content, str):
+                        text_content = msg_content
+                    elif isinstance(msg_content, list):
+                        for item in msg_content:
+                            if item.get('type') == 'text':
+                                text_content = item.get('text', '')
+                            elif item.get('type') == 'tool_use':
+                                tool_name = item.get('name', '')
+                                tool_input = item.get('input', {})
+                                if tool_name == 'Edit':
+                                    tool_uses.append(f"Edit: {tool_input.get('file_path', 'unknown')}")
+                                elif tool_name == 'Write':
+                                    tool_uses.append(f"Write: {tool_input.get('file_path', 'unknown')}")
+                                elif tool_name == 'Bash':
+                                    cmd = tool_input.get('command', '')[:80]
+                                    tool_uses.append(f"Bash: {cmd}")
+                                elif tool_name == 'AskUserQuestion':
+                                    tool_uses.append("AskUserQuestion")
+                                else:
+                                    tool_uses.append(f"{tool_name}")
+
+                    if text_content or tool_uses:
+                        result.append({
+                            'role': 'assistant',
+                            'content': text_content[:600] if text_content else '',
+                            'tools': tool_uses,
+                            'line': line_num,
+                            'session': session_file.stem[:8]
+                        })
+    except Exception:
+        pass
+
+    return result
+
+
+def main():
+    project_path = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()
+    project_dir = get_project_dir(project_path)
+
+    if not project_dir.exists():
+        return
+
+    sessions = get_sessions_sorted(project_dir)
+    if len(sessions) < 2:
+        return
+
+    # Skip the current session (most recently modified = index 0)
+    previous_sessions = sessions[1:]
+
+    # Find the most recent planning file update across ALL previous sessions
+    # Sessions are sorted newest first, so we scan in order
+    update_session = None
+    update_line = -1
+    update_file = None
+    update_session_idx = -1
+
+    for idx, session in enumerate(previous_sessions):
+        line, filename = scan_for_planning_update(session)
+        if line >= 0:
+            update_session = session
+            update_line = line
+            update_file = filename
+            update_session_idx = idx
+            break
+
+    if not update_session:
+        # No planning file updates found in any previous session
+        return
+
+    # Collect ALL messages from the update point forward, across all sessions
+    all_messages = []
+
+    # 1. Get messages from the session with the update (after the update line)
+    messages_from_update_session = extract_messages_from_session(update_session, after_line=update_line)
+    all_messages.extend(messages_from_update_session)
+
+    # 2. Get ALL messages from sessions between update_session and current
+    # These are sessions[1:update_session_idx] (newer than update_session)
+    intermediate_sessions = previous_sessions[:update_session_idx]
+
+    # Process from oldest to newest for correct chronological order
+    for session in reversed(intermediate_sessions):
+        messages = extract_messages_from_session(session, after_line=-1)  # Get all messages
+        all_messages.extend(messages)
+
+    if not all_messages:
+        return
+
+    # Output catchup report
+    print("\n[planning-with-files] SESSION CATCHUP DETECTED")
+    print(f"Last planning update: {update_file} in session {update_session.stem[:8]}...")
+
+    sessions_covered = update_session_idx + 1
+    if sessions_covered > 1:
+        print(f"Scanning {sessions_covered} sessions for unsynced context")
+
+    print(f"Unsynced messages: {len(all_messages)}")
+
+    print("\n--- UNSYNCED CONTEXT ---")
+
+    # Show up to 100 messages
+    MAX_MESSAGES = 100
+    if len(all_messages) > MAX_MESSAGES:
+        print(f"(Showing last {MAX_MESSAGES} of {len(all_messages)} messages)\n")
+        messages_to_show = all_messages[-MAX_MESSAGES:]
+    else:
+        messages_to_show = all_messages
+
+    current_session = None
+    for msg in messages_to_show:
+        # Show session marker when it changes
+        if msg.get('session') != current_session:
+            current_session = msg.get('session')
+            print(f"\n[Session: {current_session}...]")
+
+        if msg['role'] == 'user':
+            print(f"USER: {msg['content'][:300]}")
+        else:
+            if msg.get('content'):
+                print(f"CLAUDE: {msg['content'][:300]}")
+            if msg.get('tools'):
+                print(f"  Tools: {', '.join(msg['tools'][:4])}")
+
+    print("\n--- RECOMMENDED ---")
+    print("1. Run: git diff --stat")
+    print("2. Read: task_plan.md, progress.md, findings.md")
+    print("3. Update planning files based on above context")
+    print("4. Continue with task")
+
+
+if __name__ == '__main__':
+    main()
@@ -1,50 +1,23 @@
 ---
 name: planning-with-files
-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:
-  PreToolUse:
-    - matcher: "Write|Edit|Bash"
-      hooks:
-        - type: command
-          command: "cat task_plan.md 2>/dev/null | head -30 || true"
-  Stop:
-    - hooks:
-        - type: command
-          command: "${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.sh"
+license: MIT
 ---

 # Planning with Files

 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`** 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
+1. **Create `task_plan.md`** — Use templates/task_plan.md as reference
+2. **Create `findings.md`** — Use templates/findings.md as reference
+3. **Create `progress.md`** — Use 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

 ```
@@ -84,68 +57,18 @@ After completing any phase:
 ### 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 |
-
 ## When to Use This Pattern

 **Use for:**
@@ -153,7 +76,6 @@ If you can answer these, your context management is solid:
 - Research tasks
 - Building/creating projects
 - Tasks spanning many tool calls
- Anything requiring organization

 **Skip for:**
 - Simple questions
@@ -162,23 +84,20 @@ If you can answer these, your context management is solid:

 ## Templates

-Copy these templates to start:
-
- [templates/task_plan.md](templates/task_plan.md) — Phase tracking
- [templates/findings.md](templates/findings.md) — Research storage
- [templates/progress.md](templates/progress.md) — Session logging
+- templates/task_plan.md — Phase tracking
+- templates/findings.md — Research storage
+- templates/progress.md — Session logging

 ## Scripts

-Helper scripts for automation:
-
- `scripts/init-session.sh` — Initialize all planning files
- `scripts/check-complete.sh` — Verify all phases complete
+- scripts/init-session.sh — Initialize all planning files
+- scripts/check-complete.sh — Verify all phases complete
+- scripts/session-catchup.py — Recover context from previous session

 ## Advanced Topics

- **Manus Principles:** See [reference.md](reference.md)
- **Real Examples:** See [examples.md](examples.md)
+- **Manus Principles:** See reference.md
+- **Real Examples:** See examples.md

 ## Anti-Patterns

@@ -0,0 +1,42 @@
+# Check if all phases in task_plan.md are complete
+# Exit 0 if complete, exit 1 if incomplete
+# Used by Stop hook to verify task completion
+
+param(
+    [string]$PlanFile = "task_plan.md"
+)
+
+if (-not (Test-Path $PlanFile)) {
+    Write-Host "ERROR: $PlanFile not found"
+    Write-Host "Cannot verify completion without a task plan."
+    exit 1
+}
+
+Write-Host "=== Task Completion Check ==="
+Write-Host ""
+
+# Read file content
+$content = Get-Content $PlanFile -Raw
+
+# Count phases by status
+$TOTAL = ([regex]::Matches($content, "### Phase")).Count
+$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
+$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
+$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
+
+Write-Host "Total phases:   $TOTAL"
+Write-Host "Complete:       $COMPLETE"
+Write-Host "In progress:    $IN_PROGRESS"
+Write-Host "Pending:        $PENDING"
+Write-Host ""
+
+# Check completion
+if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
+    Write-Host "ALL PHASES COMPLETE"
+    exit 0
+} else {
+    Write-Host "TASK NOT COMPLETE"
+    Write-Host ""
+    Write-Host "Do not stop until all phases are complete."
+    exit 1
+}
@@ -0,0 +1,120 @@
+# Initialize planning files for a new session
+# Usage: .\init-session.ps1 [project-name]
+
+param(
+    [string]$ProjectName = "project"
+)
+
+$DATE = Get-Date -Format "yyyy-MM-dd"
+
+Write-Host "Initializing planning files for: $ProjectName"
+
+# Create task_plan.md if it doesn't exist
+if (-not (Test-Path "task_plan.md")) {
+    @"
+# 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
+- [ ] Document in findings.md
+- **Status:** in_progress
+
+### Phase 2: Planning & Structure
+- [ ] Define approach
+- [ ] Create project structure
+- **Status:** pending
+
+### Phase 3: Implementation
+- [ ] Execute the plan
+- [ ] Write to files before executing
+- **Status:** pending
+
+### Phase 4: Testing & Verification
+- [ ] Verify requirements met
+- [ ] Document test results
+- **Status:** pending
+
+### Phase 5: Delivery
+- [ ] Review outputs
+- [ ] Deliver to user
+- **Status:** pending
+
+## Decisions Made
+| Decision | Rationale |
+|----------|-----------|
+
+## Errors Encountered
+| Error | Resolution |
+|-------|------------|
+"@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
+    Write-Host "Created task_plan.md"
+} else {
+    Write-Host "task_plan.md already exists, skipping"
+}
+
+# Create findings.md if it doesn't exist
+if (-not (Test-Path "findings.md")) {
+    @"
+# Findings & Decisions
+
+## Requirements
+-
+
+## Research Findings
+-
+
+## Technical Decisions
+| Decision | Rationale |
+|----------|-----------|
+
+## Issues Encountered
+| Issue | Resolution |
+|-------|------------|
+
+## Resources
+-
+"@ | Out-File -FilePath "findings.md" -Encoding UTF8
+    Write-Host "Created findings.md"
+} else {
+    Write-Host "findings.md already exists, skipping"
+}
+
+# Create progress.md if it doesn't exist
+if (-not (Test-Path "progress.md")) {
+    @"
+# Progress Log
+
+## Session: $DATE
+
+### Current Status
+- **Phase:** 1 - Requirements & Discovery
+- **Started:** $DATE
+
+### Actions Taken
+-
+
+### Test Results
+| Test | Expected | Actual | Status |
+|------|----------|--------|--------|
+
+### Errors
+| Error | Resolution |
+|-------|------------|
+"@ | Out-File -FilePath "progress.md" -Encoding UTF8
+    Write-Host "Created progress.md"
+} else {
+    Write-Host "progress.md already exists, skipping"
+}
+
+Write-Host ""
+Write-Host "Planning files initialized!"
+Write-Host "Files: task_plan.md, findings.md, progress.md"
@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""
+Session Catchup Script for planning-with-files
+
+Analyzes the previous session to find unsynced context after the last
+planning file update. Designed to run on SessionStart.
+
+Usage: python3 session-catchup.py [project-path]
+"""
+
+import json
+import sys
+import os
+from pathlib import Path
+from typing import List, Dict, Optional, Tuple
+from datetime import datetime
+
+PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
+
+
+def get_project_dir(project_path: str) -> Path:
+    """Convert project path to Claude's storage path format."""
+    sanitized = project_path.replace('/', '-')
+    if not sanitized.startswith('-'):
+        sanitized = '-' + sanitized
+    sanitized = sanitized.replace('_', '-')
+    return Path.home() / '.claude' / 'projects' / sanitized
+
+
+def get_sessions_sorted(project_dir: Path) -> List[Path]:
+    """Get all session files sorted by modification time (newest first)."""
+    sessions = list(project_dir.glob('*.jsonl'))
+    main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
+    return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
+
+
+def parse_session_messages(session_file: Path) -> List[Dict]:
+    """Parse all messages from a session file, preserving order."""
+    messages = []
+    with open(session_file, 'r') as f:
+        for line_num, line in enumerate(f):
+            try:
+                data = json.loads(line)
+                data['_line_num'] = line_num
+                messages.append(data)
+            except json.JSONDecodeError:
+                pass
+    return messages
+
+
+def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
+    """
+    Find the last time a planning file was written/edited.
+    Returns (line_number, filename) or (-1, None) if not found.
+    """
+    last_update_line = -1
+    last_update_file = None
+
+    for msg in messages:
+        msg_type = msg.get('type')
+
+        if msg_type == 'assistant':
+            content = msg.get('message', {}).get('content', [])
+            if isinstance(content, list):
+                for item in content:
+                    if item.get('type') == 'tool_use':
+                        tool_name = item.get('name', '')
+                        tool_input = item.get('input', {})
+
+                        if tool_name in ('Write', 'Edit'):
+                            file_path = tool_input.get('file_path', '')
+                            for pf in PLANNING_FILES:
+                                if file_path.endswith(pf):
+                                    last_update_line = msg['_line_num']
+                                    last_update_file = pf
+
+    return last_update_line, last_update_file
+
+
+def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
+    """Extract conversation messages after a certain line number."""
+    result = []
+    for msg in messages:
+        if msg['_line_num'] <= after_line:
+            continue
+
+        msg_type = msg.get('type')
+        is_meta = msg.get('isMeta', False)
+
+        if msg_type == 'user' and not is_meta:
+            content = msg.get('message', {}).get('content', '')
+            if isinstance(content, list):
+                for item in content:
+                    if isinstance(item, dict) and item.get('type') == 'text':
+                        content = item.get('text', '')
+                        break
+                else:
+                    content = ''
+
+            if content and isinstance(content, str):
+                if content.startswith(('<local-command', '<command-', '<task-notification')):
+                    continue
+                if len(content) > 20:
+                    result.append({'role': 'user', 'content': content, 'line': msg['_line_num']})
+
+        elif msg_type == 'assistant':
+            msg_content = msg.get('message', {}).get('content', '')
+            text_content = ''
+            tool_uses = []
+
+            if isinstance(msg_content, str):
+                text_content = msg_content
+            elif isinstance(msg_content, list):
+                for item in msg_content:
+                    if item.get('type') == 'text':
+                        text_content = item.get('text', '')
+                    elif item.get('type') == 'tool_use':
+                        tool_name = item.get('name', '')
+                        tool_input = item.get('input', {})
+                        if tool_name == 'Edit':
+                            tool_uses.append(f"Edit: {tool_input.get('file_path', 'unknown')}")
+                        elif tool_name == 'Write':
+                            tool_uses.append(f"Write: {tool_input.get('file_path', 'unknown')}")
+                        elif tool_name == 'Bash':
+                            cmd = tool_input.get('command', '')[:80]
+                            tool_uses.append(f"Bash: {cmd}")
+                        else:
+                            tool_uses.append(f"{tool_name}")
+
+            if text_content or tool_uses:
+                result.append({
+                    'role': 'assistant',
+                    'content': text_content[:600] if text_content else '',
+                    'tools': tool_uses,
+                    'line': msg['_line_num']
+                })
+
+    return result
+
+
+def main():
+    project_path = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()
+    project_dir = get_project_dir(project_path)
+
+    # Check if planning files exist (indicates active task)
+    has_planning_files = any(
+        Path(project_path, f).exists() for f in PLANNING_FILES
+    )
+
+    if not project_dir.exists():
+        # No previous sessions, nothing to catch up on
+        return
+
+    sessions = get_sessions_sorted(project_dir)
+    if len(sessions) < 1:
+        return
+
+    # Find a substantial previous session
+    target_session = None
+    for session in sessions:
+        if session.stat().st_size > 5000:
+            target_session = session
+            break
+
+    if not target_session:
+        return
+
+    messages = parse_session_messages(target_session)
+    last_update_line, last_update_file = find_last_planning_update(messages)
+
+    # Only output if there's unsynced content
+    if last_update_line < 0:
+        messages_after = extract_messages_after(messages, len(messages) - 30)
+    else:
+        messages_after = extract_messages_after(messages, last_update_line)
+
+    if not messages_after:
+        return
+
+    # Output catchup report
+    print("\n[planning-with-files] SESSION CATCHUP DETECTED")
+    print(f"Previous session: {target_session.stem}")
+
+    if last_update_line >= 0:
+        print(f"Last planning update: {last_update_file} at message #{last_update_line}")
+        print(f"Unsynced messages: {len(messages_after)}")
+    else:
+        print("No planning file updates found in previous session")
+
+    print("\n--- UNSYNCED CONTEXT ---")
+    for msg in messages_after[-15:]:  # Last 15 messages
+        if msg['role'] == 'user':
+            print(f"USER: {msg['content'][:300]}")
+        else:
+            if msg.get('content'):
+                print(f"CLAUDE: {msg['content'][:300]}")
+            if msg.get('tools'):
+                print(f"  Tools: {', '.join(msg['tools'][:4])}")
+
+    print("\n--- RECOMMENDED ---")
+    print("1. Run: git diff --stat")
+    print("2. Read: task_plan.md, progress.md, findings.md")
+    print("3. Update planning files based on above context")
+    print("4. Continue with task")
+
+
+if __name__ == '__main__':
+    main()
@@ -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*
@@ -1,58 +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 notes.md
+- [ ] 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
@@ -0,0 +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*
@@ -0,0 +1,114 @@
+# 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:
+  -
+- Files created/modified:
+  -
+
+## 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 |
+|----------|--------|
+| Where am I? | Phase X |
+| Where am I going? | Remaining phases |
+| What's the goal? | [goal statement] |
+| What have I learned? | See findings.md |
+| 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	72220d51b6	fix: remove ALL non-standard fields from SKILL.md - match Anthropic official format (v2.5.0) Only 3 fields allowed: - name - description - license Removed: - version (not supported) - user-invocable (not supported) - allowed-tools (not supported) - hooks (not supported in SKILL.md) This matches the exact format used by official Anthropic skills.	2026-01-20 12:00:02 +01:00
OthmanAdi	2ade778cf2	fix: folder structure - removed duplicate planning-with-files/ folder (v2.4.1)	2026-01-20 11:08:32 +01:00
OthmanAdi	3e08dd9bd5	fix: remove duplicate planning-with-files/ folder - only skills/ should exist	2026-01-20 11:08:10 +01:00
OthmanAdi	1e5066957a	fix: simplify SKILL.md to minimum spec - only name, description, license	2026-01-20 11:01:56 +01:00
OthmanAdi	ac76baea26	fix: SKILL.md frontmatter now complies with Agent Skills spec (fixes #39 ) BREAKING CHANGE: Removed non-standard frontmatter fields Changes: - Removed invalid 'hooks:' field (not supported in SKILL.md per spec) - Removed invalid top-level 'version:' (moved to metadata.version) - Removed 'user-invocable:' field (not in official spec) - Changed 'allowed-tools:' from YAML list to space-delimited string - Removed ${CLAUDE_PLUGIN_ROOT} variable references This should fix /planning-with-files slash command not appearing. Reference: https://agentskills.io/specification	2026-01-20 10:16:02 +01:00
OthmanAdi	7de9247951	fix: replace CLAUDE_PLUGIN_ROOT with IDE-specific paths for cross-platform compatibility Fixes #38 - Replaced ${CLAUDE_PLUGIN_ROOT} in documentation with explicit paths for Claude Code, Codex, and Cursor - The variable works in YAML hooks but not in user-facing commands - Users can now copy-paste the correct path for their IDE - Maintains backward compatibility with Claude Code while fixing Codex support	2026-01-18 10:46:02 +01:00
OthmanAdi	c5690231ac	chore: Remove internal analysis file from repo - Remove COMPREHENSIVE_ISSUE_ANALYSIS.md (internal notes) - This file was accidentally committed and should not be public	2026-01-18 00:35:22 +01:00
Nicolas MaroisandClaude Opus 4.5	3237ad2763	fix: Session-agnostic catchup scanning across all sessions (#37 ) The session-catchup.py script now properly scans across ALL sessions to find unsynced context since the last planning file update. Changes: - Skip the current session (most recently modified) - Find the most recent planning file update across all previous sessions - Collect ALL conversation from that point forward, across all sessions - Show session markers [Session: xxx...] when context spans multiple sessions - Include intermediate sessions that have no planning updates but have work - Show up to 100 messages (was 20), with note if truncated Example: If planning was updated in session A, then work continued in sessions B and C without updates, the catchup now shows context from A, B, and C. Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-18 00:27:32 +01:00
OthmanAdiandClaude Sonnet 4.5	c84f56574e	Release v2.3.0 - Multi-IDE support (Codex + OpenCode) - Version bump to 2.3.0 - Updated CHANGELOG with new features - Updated SKILL.md version fields New features: - Codex IDE support via personal skills - OpenCode IDE support via personal/project skills - oh-my-opencode compatibility - Based on real analysis of obra/superpowers Closes #27 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>	2026-01-17 22:55:23 +01:00
OthmanAdiandClaude Sonnet 4.5	4f2586691a	Update documentation for Codex and OpenCode support - Added Codex and OpenCode to IDE support table - Updated file structure diagram - Added documentation links - Updated installation guide with new IDE sections Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>	2026-01-17 22:55:19 +01:00
OthmanAdiandClaude Sonnet 4.5	1844bbb90f	Add OpenCode IDE support with real installation guide - Created .opencode/INSTALL.md with installation instructions - Global: ~/.config/opencode/skills/planning-with-files/ - Project: .opencode/skills/planning-with-files/ - Works with obra/superpowers plugin or standalone - oh-my-opencode compatibility documented - Added docs/opencode.md for user documentation Based on analysis of obra/superpowers OpenCode plugin Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>	2026-01-17 22:55:14 +01:00
OthmanAdiandClaude Sonnet 4.5	ab10960a4b	Add Codex IDE support with real installation guide - Created .codex/INSTALL.md with installation instructions - Skills install to ~/.codex/skills/planning-with-files/ - Works with obra/superpowers or standalone - Added docs/codex.md for user documentation Based on analysis of obra/superpowers Codex implementation Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>	2026-01-17 22:55:09 +01:00
OthmanAdiandClaude Sonnet 4.5	8ee4328ef8	Hotfix: Restore skill activation language lost in v2.2.1 merge - Restore full description in SKILL.md files - Description now includes activation context - Fixes issue where skill purpose was unclear Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>	2026-01-17 22:44:18 +01:00
OthmanAdi	ce59730881	Release v2.2.1: Session recovery after /clear Merging feature/session-catchup-recovery from @lasmarois (PR #33) This fast-follow release adds automatic session recovery for seamless work continuation after running /clear when context fills up. New Features: - Session recovery via session-catchup.py script - Analyzes previous session JSONL files in ~/.claude/projects/ - Finds last planning file update - Extracts unsynced conversation after that point - Automatic recovery when invoking /planning-with-files Enhanced Hooks: - PreToolUse now includes Read/Glob/Grep operations - Keeps task_plan.md in attention during research phases - Better context management throughout workflow Files Added: - scripts/session-catchup.py (all 3 locations) - Session recovery instructions in SKILL.md - README session recovery documentation Version Updates: - Version bumped to 2.2.1 in all manifests - Updated CHANGELOG.md with v2.2.1 release notes - Added @lasmarois to CONTRIBUTORS.md Conflicts resolved: - CHANGELOG: Combined v2.2.1 and v2.2.0 entries - README: Added session recovery to v2.2.1, kept v2.2.0 features - SKILL.md: Merged session recovery with existing hooks Contributors: - @lasmarois (session recovery implementation) - Ahmad Othman Ammar Adi (conflict resolution, version management)	2026-01-17 21:49:15 +01:00
OthmanAdi	74d37d96ff	Add devis to Community Forks section Recognition of @st01cs's devis project which adds: - Interview-first workflow before implementation - /devis:intv and /devis:impl commands for guaranteed activation - Extends planning-with-files with structured requirement gathering This addresses the community contribution mentioned in issue #28.	2026-01-17 21:44:20 +01:00
OthmanAdi	4606e643a9	Merge PR #30 : Add Kilo Code support and enhance Windows compatibility Merging feature/kilocode-support branch from @aimasteracc This merge combines: - Kilo Code IDE support (.kilocode/rules/ and docs) - Windows PowerShell scripts (extended to all locations) - OS-aware hook execution - Comprehensive documentation updates Changes from PR #30: - Added .kilocode/rules/planning-with-files.md - Added docs/kilocode.md for Kilo Code users - Added PowerShell scripts for Windows users - Updated .gitignore for planning files Changes from v2.2.0 base: - Extended PowerShell scripts to root and plugin folders - Added OS-aware Stop hook (auto-detects Windows) - Created CONTRIBUTORS.md - Created COMPREHENSIVE_ISSUE_ANALYSIS.md - Fixed issues #32 and #25 Conflicts resolved by: - Combining CHANGELOG entries for both contributions - Merging README version table descriptions - Keeping enhanced PowerShell scripts (all 3 locations) - Preserving all Kilo Code additions Contributors: - @aimasteracc (Kilo Code support, PowerShell scripts) - Ahmad Othman Ammar Adi (Windows compatibility, OS-aware hooks)	2026-01-17 21:35:06 +01:00
nicolasandClaude Opus 4.5	69ded714b7	feat: Add session recovery after /clear (v2.2.0) Automatically detect and recover unsynced work from previous sessions when context fills up and user runs /clear. New features: - session-catchup.py: Analyzes previous session JSONL to find unsynced context - Recovery triggered automatically when invoking /planning-with-files - PreToolUse hook now includes Read/Glob/Grep for better attention management Optimal workflow: 1. Disable auto-compact in Claude Code settings 2. Start fresh session 3. Run /planning-with-files when ready for complex task 4. Work until context fills up 5. Run /clear 6. Run /planning-with-files again — automatically recovers where you left off How recovery works: - SKILL.md instructs Claude to first run session-catchup.py - Script checks ~/.claude/projects/ for previous session JSONL - Finds last planning file update, extracts conversation after that point - Claude updates planning files based on catchup + git diff Changes: - SKILL.md: Added session recovery section, preserved all original content - README: Added optimal workflow and setup instructions - Removed SessionStart hook (doesn't work per Issue #24) - Version bumped to 2.2.0 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-17 15:28:08 -05:00
OthmanAdi	9d53d28be3	Release v2.2.0: Windows PowerShell support and OS-aware hooks This release adds comprehensive Windows compatibility and recognizes community contributors. Features: - PowerShell scripts (check-complete.ps1, init-session.ps1) - OS-aware hook execution with automatic fallback - Cross-platform script support (Windows, Mac, Linux) Fixes: - Issue #32: Stop hook error on Windows PowerShell - Issue #25: check-complete.sh not found errors - ${CLAUDE_PLUGIN_ROOT} resolution across platforms Documentation: - Added CONTRIBUTORS.md recognizing community contributions - Added COMPREHENSIVE_ISSUE_ANALYSIS.md with detailed issue research - Updated CHANGELOG.md with v2.2.0 changes - Updated README.md with new version info Technical Changes: - Created PowerShell equivalents for all bash scripts - Updated SKILL.md Stop hook to detect OS and use appropriate script - Scripts deployed to all three locations (root, plugin, skills) - Graceful fallback chain: pwsh → powershell → bash - Version bumped to 2.2.0 in all manifests This update enables Windows users to use planning-with-files without compatibility issues while maintaining full backwards compatibility for Unix/Linux/Mac users.	2026-01-17 21:20:30 +01:00
aisheng.yu	3acf5e4879	Add Kilocode support and documentation - Add .kilocode/rules/planning-with-files.md with planning rules - Update .gitignore for Kilocode patterns - Add docs/kilocode.md documentation - Update CHANGELOG.md with Kilocode support entry - Update README.md with Kilocode integration - Update SKILL.md files in planning-with-files and skills directories - Add PowerShell scripts (check-complete.ps1, init-session.ps1)	2026-01-16 06:57:34 +00:00
OthmanAdiandClaude Opus 4.5	dcb92c0a64	fix: add root-level templates/scripts for CLAUDE_PLUGIN_ROOT resolution (v2.1.2) Fixes #18 - Templates not found in cache after update Root cause: ${CLAUDE_PLUGIN_ROOT} resolves to repo root, but templates were only in subfolders (planning-with-files/ and skills/planning-with-files/). Solution: Added templates/ and scripts/ at repo root level so they're accessible regardless of how CLAUDE_PLUGIN_ROOT resolves. Changes: - Add templates/ directory at repo root - Add scripts/ directory at repo root - Bump version to 2.1.2 in all manifests - Update CHANGELOG with fix details - Update troubleshooting.md with cache clearing instructions - Update README file structure diagram Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-11 21:47:04 +01:00
OthmanAdi	8cdd48d33b	docs: update version to 2.1.1 in README and CHANGELOG	2026-01-10 20:15:57 +01:00
OthmanAdi	9b574e1016	Revert "fix: remove duplicate skills folder - use planning-with-files/ at root" This reverts commit `0b9e4aee89`.	2026-01-10 20:11:48 +01:00
OthmanAdi	0b9e4aee89	fix: remove duplicate skills folder - use planning-with-files/ at root	2026-01-10 20:08:33 +01:00
OthmanAdi	2b656d88d3	chore: bump version to 2.1.1	2026-01-10 20:07:53 +01:00
OthmanAdi	ee47cba0ef	fix: add plugin-compatible skill folder structure (v2.1.1) Fixes #15 - templates not found in plugin cache The plugin system expects skill files at repo root in a folder matching the skill name. Added planning-with-files/ folder with: - SKILL.md - templates/ (task_plan.md, findings.md, progress.md) - scripts/ (init-session.sh, check-complete.sh) Kept skills/planning-with-files/ for manual ~/.claude/skills/ installs.	2026-01-10 20:06:53 +01:00
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
fuahyo	67772c085d	docs: enhance beginner-friendliness with examples, templates, quick start, and workflow diagram	2026-01-09 17:46:53 +07:00