Add Clawd CLI support (v2.9.0)

- Add .clawd/skills/planning-with-files/ skill bundle - Add docs/clawd.md installation guide - Update README with Clawd badge and documentation - Update plugin.json with new keywords for discoverability - Update all SKILL.md versions to 2.9.0 - Now supports 10+ AI coding assistants
Release v2.8.0 - Continue IDE support & POSIX sh fix
2026-01-26 01:14:37 +01:00 · 2026-01-26 01:05:01 +01:00 · 2026-01-26 01:01:16 +01:00 · 2026-01-26 01:01:03 +01:00 · 2026-01-25 01:05:04 +08:00 · 2026-01-24 01:55:49 +08:00
90 changed files with 9983 additions and 1527 deletions
@@ -0,0 +1,127 @@
+---
+name: planning-with-files
+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.
+license: MIT
+---
+
+# Planning with Files
+
+Work like Manus: Use persistent markdown files as your "working memory on disk."
+
+## Core Principle
+
+```
+Context Window = RAM (volatile, limited)
+Filesystem = Disk (persistent, unlimited)
+
+→ Anything important gets written to disk.
+```
+
+## Quick Start
+
+Before ANY complex task, create these three files:
+
+1. **task_plan.md** — Track phases and progress
+2. **findings.md** — Store research and discoveries
+3. **progress.md** — Session log and test results
+
+See references/ for starting templates.
+
+## 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.
+
+### 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
+```
+
+## When to Use This Pattern
+
+**Use for:**
+- Multi-step tasks (3+ steps)
+- Research tasks
+- Building/creating projects
+- Tasks spanning many tool calls
+
+**Skip for:**
+- Simple questions
+- Single-file edits
+- Quick lookups
+
+## Templates
+
+- references/task_plan.md — Phase tracking template
+- references/findings.md — Research storage template
+- references/progress.md — Session logging template
+
+## Advanced Topics
+
+- **Manus Principles:** See references.md for complete context engineering patterns
+- **Real Examples:** See examples.md for practical implementations
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| 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 |
+
+---
+
+**This pattern is why Manus went from launch to $2B acquisition in 8 months.**
@@ -1,7 +1,7 @@
 {
  "name": "planning-with-files",
-  "version": "2.2.2",
-  "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.9.0",
+  "description": "Manus-style persistent markdown files for planning, progress tracking, and knowledge storage. Works with Claude Code, Clawd CLI, Gemini CLI, Cursor, Continue, and 10+ AI coding assistants.",
  "author": {
    "name": "OthmanAdi",
    "url": "https://github.com/OthmanAdi"
@@ -15,7 +15,14 @@
    "markdown",
    "context-engineering",
    "task-management",
-    "hooks",
-    "templates"
+    "templates",
+    "clawd",
+    "clawdbot",
+    "clawdhub",
+    "gemini",
+    "cursor",
+    "continue",
+    "multi-ide",
+    "agent-skills"
  ]
 }
@@ -0,0 +1,180 @@
+---
+name: planning-with-files
+version: "2.9.0"
+description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls.
+homepage: https://github.com/OthmanAdi/planning-with-files
+user-invocable: true
+metadata: {"clawdbot":{"os":["darwin","linux","win32"]}}
+---
+
+# Planning with Files
+
+Work like Manus: Use persistent markdown files as your "working memory on disk."
+
+## Important: Where Files Go
+
+- **Templates** are in this skill's `templates/` folder
+- **Your planning files** go in **your project directory**
+
+| Location | What Goes There |
+|----------|-----------------|
+| Skill directory | Templates, scripts, reference docs |
+| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
+
+## Quick Start
+
+Before ANY complex task:
+
+1. **Create `task_plan.md`** — Use [templates/task_plan.md](templates/task_plan.md) as reference
+2. **Create `findings.md`** — Use [templates/findings.md](templates/findings.md) as reference
+3. **Create `progress.md`** — Use [templates/progress.md](templates/progress.md) as reference
+4. **Re-read plan before decisions** — Refreshes goals in attention window
+5. **Update after each phase** — Mark complete, log errors
+
+> **Note:** Planning files go in your project root, not the skill installation folder.
+
+## 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 |
+
+## 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
+
+## 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
+
+## Scripts
+
+Helper scripts for automation:
+
+- `scripts/init-session.sh` — Initialize all planning files
+- `scripts/check-complete.sh` — Verify all phases complete
+
+## Advanced Topics
+
+- **Manus Principles:** See [references/reference.md](references/reference.md)
+- **Real Examples:** See [references/examples.md](references/examples.md)
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| 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 |
+| Create files in skill directory | Create files in your project |
@@ -0,0 +1,202 @@
+# Examples: Planning with Files in Action
+
+## Example 1: Research Task
+
+**User Request:** "Research the benefits of morning exercise and write a summary"
+
+### Loop 1: Create Plan
+```bash
+Write task_plan.md
+```
+
+```markdown
+# Task Plan: Morning Exercise Benefits Research
+
+## Goal
+Create a research summary on the benefits of morning exercise.
+
+## Phases
+- [ ] Phase 1: Create this plan ✓
+- [ ] Phase 2: Search and gather sources
+- [ ] Phase 3: Synthesize findings
+- [ ] Phase 4: Deliver summary
+
+## Key Questions
+1. What are the physical health benefits?
+2. What are the mental health benefits?
+3. What scientific studies support this?
+
+## Status
+**Currently in Phase 1** - Creating plan
+```
+
+### Loop 2: Research
+```bash
+Read task_plan.md           # Refresh goals
+WebSearch "morning exercise benefits"
+Write notes.md              # Store findings
+Edit task_plan.md           # Mark Phase 2 complete
+```
+
+### Loop 3: Synthesize
+```bash
+Read task_plan.md           # Refresh goals
+Read notes.md               # Get findings
+Write morning_exercise_summary.md
+Edit task_plan.md           # Mark Phase 3 complete
+```
+
+### Loop 4: Deliver
+```bash
+Read task_plan.md           # Verify complete
+Deliver morning_exercise_summary.md
+```
+
+---
+
+## Example 2: Bug Fix Task
+
+**User Request:** "Fix the login bug in the authentication module"
+
+### task_plan.md
+```markdown
+# Task Plan: Fix Login Bug
+
+## Goal
+Identify and fix the bug preventing successful login.
+
+## Phases
+- [x] Phase 1: Understand the bug report ✓
+- [x] Phase 2: Locate relevant code ✓
+- [ ] Phase 3: Identify root cause (CURRENT)
+- [ ] Phase 4: Implement fix
+- [ ] Phase 5: Test and verify
+
+## Key Questions
+1. What error message appears?
+2. Which file handles authentication?
+3. What changed recently?
+
+## Decisions Made
+- Auth handler is in src/auth/login.ts
+- Error occurs in validateToken() function
+
+## Errors Encountered
+- [Initial] TypeError: Cannot read property 'token' of undefined
+  → Root cause: user object not awaited properly
+
+## Status
+**Currently in Phase 3** - Found root cause, preparing fix
+```
+
+---
+
+## Example 3: Feature Development
+
+**User Request:** "Add a dark mode toggle to the settings page"
+
+### The 3-File Pattern in Action
+
+**task_plan.md:**
+```markdown
+# Task Plan: Dark Mode Toggle
+
+## Goal
+Add functional dark mode toggle to settings.
+
+## Phases
+- [x] Phase 1: Research existing theme system ✓
+- [x] Phase 2: Design implementation approach ✓
+- [ ] Phase 3: Implement toggle component (CURRENT)
+- [ ] Phase 4: Add theme switching logic
+- [ ] Phase 5: Test and polish
+
+## Decisions Made
+- Using CSS custom properties for theme
+- Storing preference in localStorage
+- Toggle component in SettingsPage.tsx
+
+## Status
+**Currently in Phase 3** - Building toggle component
+```
+
+**notes.md:**
+```markdown
+# Notes: Dark Mode Implementation
+
+## Existing Theme System
+- Located in: src/styles/theme.ts
+- Uses: CSS custom properties
+- Current themes: light only
+
+## Files to Modify
+1. src/styles/theme.ts - Add dark theme colors
+2. src/components/SettingsPage.tsx - Add toggle
+3. src/hooks/useTheme.ts - Create new hook
+4. src/App.tsx - Wrap with ThemeProvider
+
+## Color Decisions
+- Dark background: #1a1a2e
+- Dark surface: #16213e
+- Dark text: #eaeaea
+```
+
+**dark_mode_implementation.md:** (deliverable)
+```markdown
+# Dark Mode Implementation
+
+## Changes Made
+
+### 1. Added dark theme colors
+File: src/styles/theme.ts
+...
+
+### 2. Created useTheme hook
+File: src/hooks/useTheme.ts
+...
+```
+
+---
+
+## Example 4: Error Recovery Pattern
+
+When something fails, DON'T hide it:
+
+### Before (Wrong)
+```
+Action: Read config.json
+Error: File not found
+Action: Read config.json  # Silent retry
+Action: Read config.json  # Another retry
+```
+
+### After (Correct)
+```
+Action: Read config.json
+Error: File not found
+
+# Update task_plan.md:
+## Errors Encountered
+- config.json not found → Will create default config
+
+Action: Write config.json (default config)
+Action: Read config.json
+Success!
+```
+
+---
+
+## The Read-Before-Decide Pattern
+
+**Always read your plan before major decisions:**
+
+```
+[Many tool calls have happened...]
+[Context is getting long...]
+[Original goal might be forgotten...]
+
+→ Read task_plan.md          # This brings goals back into attention!
+→ Now make the decision       # Goals are fresh in context
+```
+
+This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a "goal refresh" mechanism.
@@ -0,0 +1,218 @@
+# Reference: Manus Context Engineering Principles
+
+This skill is based on context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
+
+## The 6 Manus Principles
+
+### Principle 1: Design Around KV-Cache
+
+> "KV-cache hit rate is THE single most important metric for production AI agents."
+
+**Statistics:**
+- ~100:1 input-to-output token ratio
+- Cached tokens: $0.30/MTok vs Uncached: $3/MTok
+- 10x cost difference!
+
+**Implementation:**
+- Keep prompt prefixes STABLE (single-token change invalidates cache)
+- NO timestamps in system prompts
+- Make context APPEND-ONLY with deterministic serialization
+
+### Principle 2: Mask, Don't Remove
+
+Don't dynamically remove tools (breaks KV-cache). Use logit masking instead.
+
+**Best Practice:** Use consistent action prefixes (e.g., `browser_`, `shell_`, `file_`) for easier masking.
+
+### Principle 3: Filesystem as External Memory
+
+> "Markdown is my 'working memory' on disk."
+
+**The Formula:**
+```
+Context Window = RAM (volatile, limited)
+Filesystem = Disk (persistent, unlimited)
+```
+
+**Compression Must Be Restorable:**
+- Keep URLs even if web content is dropped
+- Keep file paths when dropping document contents
+- Never lose the pointer to full data
+
+### Principle 4: Manipulate Attention Through Recitation
+
+> "Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."
+
+**Problem:** After ~50 tool calls, models forget original goals ("lost in the middle" effect).
+
+**Solution:** Re-read `task_plan.md` before each decision. Goals appear in the attention window.
+
+```
+Start of context: [Original goal - far away, forgotten]
+...many tool calls...
+End of context: [Recently read task_plan.md - gets ATTENTION!]
+```
+
+### Principle 5: Keep the Wrong Stuff In
+
+> "Leave the wrong turns in the context."
+
+**Why:**
+- Failed actions with stack traces let model implicitly update beliefs
+- Reduces mistake repetition
+- Error recovery is "one of the clearest signals of TRUE agentic behavior"
+
+### Principle 6: Don't Get Few-Shotted
+
+> "Uniformity breeds fragility."
+
+**Problem:** Repetitive action-observation pairs cause drift and hallucination.
+
+**Solution:** Introduce controlled variation:
+- Vary phrasings slightly
+- Don't copy-paste patterns blindly
+- Recalibrate on repetitive tasks
+
+---
+
+## The 3 Context Engineering Strategies
+
+Based on Lance Martin's analysis of Manus architecture.
+
+### Strategy 1: Context Reduction
+
+**Compaction:**
+```
+Tool calls have TWO representations:
+├── FULL: Raw tool content (stored in filesystem)
+└── COMPACT: Reference/file path only
+
+RULES:
+- Apply compaction to STALE (older) tool results
+- Keep RECENT results FULL (to guide next decision)
+```
+
+**Summarization:**
+- Applied when compaction reaches diminishing returns
+- Generated using full tool results
+- Creates standardized summary objects
+
+### Strategy 2: Context Isolation (Multi-Agent)
+
+**Architecture:**
+```
+┌─────────────────────────────────┐
+│         PLANNER AGENT           │
+│  └─ Assigns tasks to sub-agents │
+├─────────────────────────────────┤
+│       KNOWLEDGE MANAGER         │
+│  └─ Reviews conversations       │
+│  └─ Determines filesystem store │
+├─────────────────────────────────┤
+│      EXECUTOR SUB-AGENTS        │
+│  └─ Perform assigned tasks      │
+│  └─ Have own context windows    │
+└─────────────────────────────────┘
+```
+
+**Key Insight:** Manus originally used `todo.md` for task planning but found ~33% of actions were spent updating it. Shifted to dedicated planner agent calling executor sub-agents.
+
+### Strategy 3: Context Offloading
+
+**Tool Design:**
+- Use <20 atomic functions total
+- Store full results in filesystem, not context
+- Use `glob` and `grep` for searching
+- Progressive disclosure: load information only as needed
+
+---
+
+## The Agent Loop
+
+Manus operates in a continuous 7-step loop:
+
+```
+┌─────────────────────────────────────────┐
+│  1. ANALYZE CONTEXT                      │
+│     - Understand user intent             │
+│     - Assess current state               │
+│     - Review recent observations         │
+├─────────────────────────────────────────┤
+│  2. THINK                                │
+│     - Should I update the plan?          │
+│     - What's the next logical action?    │
+│     - Are there blockers?                │
+├─────────────────────────────────────────┤
+│  3. SELECT TOOL                          │
+│     - Choose ONE tool                    │
+│     - Ensure parameters available        │
+├─────────────────────────────────────────┤
+│  4. EXECUTE ACTION                       │
+│     - Tool runs in sandbox               │
+├─────────────────────────────────────────┤
+│  5. RECEIVE OBSERVATION                  │
+│     - Result appended to context         │
+├─────────────────────────────────────────┤
+│  6. ITERATE                              │
+│     - Return to step 1                   │
+│     - Continue until complete            │
+├─────────────────────────────────────────┤
+│  7. DELIVER OUTCOME                      │
+│     - Send results to user               │
+│     - Attach all relevant files          │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## File Types Manus Creates
+
+| File | Purpose | When Created | When Updated |
+|------|---------|--------------|--------------|
+| `task_plan.md` | Phase tracking, progress | Task start | After completing phases |
+| `findings.md` | Discoveries, decisions | After ANY discovery | After viewing images/PDFs |
+| `progress.md` | Session log, what's done | At breakpoints | Throughout session |
+| Code files | Implementation | Before execution | After errors |
+
+---
+
+## Critical Constraints
+
+- **Single-Action Execution:** ONE tool call per turn. No parallel execution.
+- **Plan is Required:** Agent must ALWAYS know: goal, current phase, remaining phases
+- **Files are Memory:** Context = volatile. Filesystem = persistent.
+- **Never Repeat Failures:** If action failed, next action MUST be different
+- **Communication is a Tool:** Message types: `info` (progress), `ask` (blocking), `result` (terminal)
+
+---
+
+## Manus Statistics
+
+| Metric | Value |
+|--------|-------|
+| Average tool calls per task | ~50 |
+| Input-to-output token ratio | 100:1 |
+| Acquisition price | $2 billion |
+| Time to $100M revenue | 8 months |
+| Framework refactors since launch | 5 times |
+
+---
+
+## Key Quotes
+
+> "Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."
+
+> "if action_failed: next_action != same_action. Track what you tried. Mutate the approach."
+
+> "Error recovery is one of the clearest signals of TRUE agentic behavior."
+
+> "KV-cache hit rate is the single most important metric for a production-stage AI agent."
+
+> "Leave the wrong turns in the context."
+
+---
+
+## Source
+
+Based on Manus's official context engineering documentation:
+https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
@@ -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
@@ -1,6 +1,6 @@
 ---
 name: planning-with-files
-version: "2.2.2"
+version: "2.9.0"
 description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls. Now with automatic session recovery after /clear.
 user-invocable: true
 allowed-tools:
@@ -27,10 +27,29 @@ hooks:
    - hooks:
        - type: command
          command: |
-            if command -v pwsh &> /dev/null && [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" || "$OS" == "Windows_NT" ]]; then
-              pwsh -ExecutionPolicy Bypass -File "${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.ps1" 2>/dev/null || powershell -ExecutionPolicy Bypass -File "${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.ps1" 2>/dev/null || bash "${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.sh"
+            SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files}/scripts"
+
+            IS_WINDOWS=0
+            if [ "${OS-}" = "Windows_NT" ]; then
+              IS_WINDOWS=1
            else
-              bash "${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.sh"
+              UNAME_S="$(uname -s 2>/dev/null || echo '')"
+              case "$UNAME_S" in
+                CYGWIN*|MINGW*|MSYS*) IS_WINDOWS=1 ;;
+              esac
+            fi
+
+            if [ "$IS_WINDOWS" -eq 1 ]; then
+              if command -v pwsh >/dev/null 2>&1; then
+                pwsh -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
+                powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
+                sh "$SCRIPT_DIR/check-complete.sh"
+              else
+                powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
+                sh "$SCRIPT_DIR/check-complete.sh"
+              fi
+            else
+              sh "$SCRIPT_DIR/check-complete.sh"
            fi
 ---

@@ -43,7 +62,13 @@ Work like Manus: Use persistent markdown files as your "working memory on disk."
 **Before starting work**, check for unsynced context from a previous session:

 ```bash
-python3 ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
+# Linux/macOS (auto-detects python3 or python)
+$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
+```
+
+```powershell
+# Windows PowerShell
+python "$env:USERPROFILE\.codex\skills\planning-with-files\scripts\session-catchup.py" (Get-Location)
 ```

 If catchup report shows unsynced context:
@@ -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
@@ -0,0 +1,202 @@
+# Examples: Planning with Files in Action
+
+## Example 1: Research Task
+
+**User Request:** "Research the benefits of morning exercise and write a summary"
+
+### Loop 1: Create Plan
+```bash
+Write task_plan.md
+```
+
+```markdown
+# Task Plan: Morning Exercise Benefits Research
+
+## Goal
+Create a research summary on the benefits of morning exercise.
+
+## Phases
+- [ ] Phase 1: Create this plan ✓
+- [ ] Phase 2: Search and gather sources
+- [ ] Phase 3: Synthesize findings
+- [ ] Phase 4: Deliver summary
+
+## Key Questions
+1. What are the physical health benefits?
+2. What are the mental health benefits?
+3. What scientific studies support this?
+
+## Status
+**Currently in Phase 1** - Creating plan
+```
+
+### Loop 2: Research
+```bash
+Read task_plan.md           # Refresh goals
+WebSearch "morning exercise benefits"
+Write notes.md              # Store findings
+Edit task_plan.md           # Mark Phase 2 complete
+```
+
+### Loop 3: Synthesize
+```bash
+Read task_plan.md           # Refresh goals
+Read notes.md               # Get findings
+Write morning_exercise_summary.md
+Edit task_plan.md           # Mark Phase 3 complete
+```
+
+### Loop 4: Deliver
+```bash
+Read task_plan.md           # Verify complete
+Deliver morning_exercise_summary.md
+```
+
+---
+
+## Example 2: Bug Fix Task
+
+**User Request:** "Fix the login bug in the authentication module"
+
+### task_plan.md
+```markdown
+# Task Plan: Fix Login Bug
+
+## Goal
+Identify and fix the bug preventing successful login.
+
+## Phases
+- [x] Phase 1: Understand the bug report ✓
+- [x] Phase 2: Locate relevant code ✓
+- [ ] Phase 3: Identify root cause (CURRENT)
+- [ ] Phase 4: Implement fix
+- [ ] Phase 5: Test and verify
+
+## Key Questions
+1. What error message appears?
+2. Which file handles authentication?
+3. What changed recently?
+
+## Decisions Made
+- Auth handler is in src/auth/login.ts
+- Error occurs in validateToken() function
+
+## Errors Encountered
+- [Initial] TypeError: Cannot read property 'token' of undefined
+  → Root cause: user object not awaited properly
+
+## Status
+**Currently in Phase 3** - Found root cause, preparing fix
+```
+
+---
+
+## Example 3: Feature Development
+
+**User Request:** "Add a dark mode toggle to the settings page"
+
+### The 3-File Pattern in Action
+
+**task_plan.md:**
+```markdown
+# Task Plan: Dark Mode Toggle
+
+## Goal
+Add functional dark mode toggle to settings.
+
+## Phases
+- [x] Phase 1: Research existing theme system ✓
+- [x] Phase 2: Design implementation approach ✓
+- [ ] Phase 3: Implement toggle component (CURRENT)
+- [ ] Phase 4: Add theme switching logic
+- [ ] Phase 5: Test and polish
+
+## Decisions Made
+- Using CSS custom properties for theme
+- Storing preference in localStorage
+- Toggle component in SettingsPage.tsx
+
+## Status
+**Currently in Phase 3** - Building toggle component
+```
+
+**notes.md:**
+```markdown
+# Notes: Dark Mode Implementation
+
+## Existing Theme System
+- Located in: src/styles/theme.ts
+- Uses: CSS custom properties
+- Current themes: light only
+
+## Files to Modify
+1. src/styles/theme.ts - Add dark theme colors
+2. src/components/SettingsPage.tsx - Add toggle
+3. src/hooks/useTheme.ts - Create new hook
+4. src/App.tsx - Wrap with ThemeProvider
+
+## Color Decisions
+- Dark background: #1a1a2e
+- Dark surface: #16213e
+- Dark text: #eaeaea
+```
+
+**dark_mode_implementation.md:** (deliverable)
+```markdown
+# Dark Mode Implementation
+
+## Changes Made
+
+### 1. Added dark theme colors
+File: src/styles/theme.ts
+...
+
+### 2. Created useTheme hook
+File: src/hooks/useTheme.ts
+...
+```
+
+---
+
+## Example 4: Error Recovery Pattern
+
+When something fails, DON'T hide it:
+
+### Before (Wrong)
+```
+Action: Read config.json
+Error: File not found
+Action: Read config.json  # Silent retry
+Action: Read config.json  # Another retry
+```
+
+### After (Correct)
+```
+Action: Read config.json
+Error: File not found
+
+# Update task_plan.md:
+## Errors Encountered
+- config.json not found → Will create default config
+
+Action: Write config.json (default config)
+Action: Read config.json
+Success!
+```
+
+---
+
+## The Read-Before-Decide Pattern
+
+**Always read your plan before major decisions:**
+
+```
+[Many tool calls have happened...]
+[Context is getting long...]
+[Original goal might be forgotten...]
+
+→ Read task_plan.md          # This brings goals back into attention!
+→ Now make the decision       # Goals are fresh in context
+```
+
+This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a "goal refresh" mechanism.
@@ -0,0 +1,218 @@
+# Reference: Manus Context Engineering Principles
+
+This skill is based on context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
+
+## The 6 Manus Principles
+
+### Principle 1: Design Around KV-Cache
+
+> "KV-cache hit rate is THE single most important metric for production AI agents."
+
+**Statistics:**
+- ~100:1 input-to-output token ratio
+- Cached tokens: $0.30/MTok vs Uncached: $3/MTok
+- 10x cost difference!
+
+**Implementation:**
+- Keep prompt prefixes STABLE (single-token change invalidates cache)
+- NO timestamps in system prompts
+- Make context APPEND-ONLY with deterministic serialization
+
+### Principle 2: Mask, Don't Remove
+
+Don't dynamically remove tools (breaks KV-cache). Use logit masking instead.
+
+**Best Practice:** Use consistent action prefixes (e.g., `browser_`, `shell_`, `file_`) for easier masking.
+
+### Principle 3: Filesystem as External Memory
+
+> "Markdown is my 'working memory' on disk."
+
+**The Formula:**
+```
+Context Window = RAM (volatile, limited)
+Filesystem = Disk (persistent, unlimited)
+```
+
+**Compression Must Be Restorable:**
+- Keep URLs even if web content is dropped
+- Keep file paths when dropping document contents
+- Never lose the pointer to full data
+
+### Principle 4: Manipulate Attention Through Recitation
+
+> "Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."
+
+**Problem:** After ~50 tool calls, models forget original goals ("lost in the middle" effect).
+
+**Solution:** Re-read `task_plan.md` before each decision. Goals appear in the attention window.
+
+```
+Start of context: [Original goal - far away, forgotten]
+...many tool calls...
+End of context: [Recently read task_plan.md - gets ATTENTION!]
+```
+
+### Principle 5: Keep the Wrong Stuff In
+
+> "Leave the wrong turns in the context."
+
+**Why:**
+- Failed actions with stack traces let model implicitly update beliefs
+- Reduces mistake repetition
+- Error recovery is "one of the clearest signals of TRUE agentic behavior"
+
+### Principle 6: Don't Get Few-Shotted
+
+> "Uniformity breeds fragility."
+
+**Problem:** Repetitive action-observation pairs cause drift and hallucination.
+
+**Solution:** Introduce controlled variation:
+- Vary phrasings slightly
+- Don't copy-paste patterns blindly
+- Recalibrate on repetitive tasks
+
+---
+
+## The 3 Context Engineering Strategies
+
+Based on Lance Martin's analysis of Manus architecture.
+
+### Strategy 1: Context Reduction
+
+**Compaction:**
+```
+Tool calls have TWO representations:
+├── FULL: Raw tool content (stored in filesystem)
+└── COMPACT: Reference/file path only
+
+RULES:
+- Apply compaction to STALE (older) tool results
+- Keep RECENT results FULL (to guide next decision)
+```
+
+**Summarization:**
+- Applied when compaction reaches diminishing returns
+- Generated using full tool results
+- Creates standardized summary objects
+
+### Strategy 2: Context Isolation (Multi-Agent)
+
+**Architecture:**
+```
+┌─────────────────────────────────┐
+│         PLANNER AGENT           │
+│  └─ Assigns tasks to sub-agents │
+├─────────────────────────────────┤
+│       KNOWLEDGE MANAGER         │
+│  └─ Reviews conversations       │
+│  └─ Determines filesystem store │
+├─────────────────────────────────┤
+│      EXECUTOR SUB-AGENTS        │
+│  └─ Perform assigned tasks      │
+│  └─ Have own context windows    │
+└─────────────────────────────────┘
+```
+
+**Key Insight:** Manus originally used `todo.md` for task planning but found ~33% of actions were spent updating it. Shifted to dedicated planner agent calling executor sub-agents.
+
+### Strategy 3: Context Offloading
+
+**Tool Design:**
+- Use <20 atomic functions total
+- Store full results in filesystem, not context
+- Use `glob` and `grep` for searching
+- Progressive disclosure: load information only as needed
+
+---
+
+## The Agent Loop
+
+Manus operates in a continuous 7-step loop:
+
+```
+┌─────────────────────────────────────────┐
+│  1. ANALYZE CONTEXT                      │
+│     - Understand user intent             │
+│     - Assess current state               │
+│     - Review recent observations         │
+├─────────────────────────────────────────┤
+│  2. THINK                                │
+│     - Should I update the plan?          │
+│     - What's the next logical action?    │
+│     - Are there blockers?                │
+├─────────────────────────────────────────┤
+│  3. SELECT TOOL                          │
+│     - Choose ONE tool                    │
+│     - Ensure parameters available        │
+├─────────────────────────────────────────┤
+│  4. EXECUTE ACTION                       │
+│     - Tool runs in sandbox               │
+├─────────────────────────────────────────┤
+│  5. RECEIVE OBSERVATION                  │
+│     - Result appended to context         │
+├─────────────────────────────────────────┤
+│  6. ITERATE                              │
+│     - Return to step 1                   │
+│     - Continue until complete            │
+├─────────────────────────────────────────┤
+│  7. DELIVER OUTCOME                      │
+│     - Send results to user               │
+│     - Attach all relevant files          │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## File Types Manus Creates
+
+| File | Purpose | When Created | When Updated |
+|------|---------|--------------|--------------|
+| `task_plan.md` | Phase tracking, progress | Task start | After completing phases |
+| `findings.md` | Discoveries, decisions | After ANY discovery | After viewing images/PDFs |
+| `progress.md` | Session log, what's done | At breakpoints | Throughout session |
+| Code files | Implementation | Before execution | After errors |
+
+---
+
+## Critical Constraints
+
+- **Single-Action Execution:** ONE tool call per turn. No parallel execution.
+- **Plan is Required:** Agent must ALWAYS know: goal, current phase, remaining phases
+- **Files are Memory:** Context = volatile. Filesystem = persistent.
+- **Never Repeat Failures:** If action failed, next action MUST be different
+- **Communication is a Tool:** Message types: `info` (progress), `ask` (blocking), `result` (terminal)
+
+---
+
+## Manus Statistics
+
+| Metric | Value |
+|--------|-------|
+| Average tool calls per task | ~50 |
+| Input-to-output token ratio | 100:1 |
+| Acquisition price | $2 billion |
+| Time to $100M revenue | 8 months |
+| Framework refactors since launch | 5 times |
+
+---
+
+## Key Quotes
+
+> "Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."
+
+> "if action_failed: next_action != same_action. Track what you tried. Mutate the approach."
+
+> "Error recovery is one of the clearest signals of TRUE agentic behavior."
+
+> "KV-cache hit rate is the single most important metric for a production-stage AI agent."
+
+> "Leave the wrong turns in the context."
+
+---
+
+## Source
+
+Based on Manus's official context engineering documentation:
+https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
@@ -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,34 @@
+---
+name: planning-with-files
+description: 启动“Planning with Files”三文件工作流（task_plan.md / findings.md / progress.md）
+invokable: true
+---
+
+你将采用“Planning with Files”模式来完成接下来的工作：把计划、发现与进度持久化到 3 个 Markdown 文件里，以避免上下文漂移与遗忘。
+
+## 目标
+
+- 在项目根目录确保存在：task_plan.md、findings.md、progress.md
+- 所有关键决策、研究结论、错误与修复路径必须写入文件
+- 每完成一个阶段就更新 task_plan.md 的状态
+
+## 工作步骤
+
+1. 检查项目根目录是否已有 task_plan.md / findings.md / progress.md
+2. 如果不存在，先创建它们（可直接运行初始化脚本，或在 IDE 里新建同名文件）：
+   - macOS/Linux：bash .continue/skills/planning-with-files/scripts/init-session.sh
+   - Windows：powershell -ExecutionPolicy Bypass -File .continue/skills/planning-with-files/scripts/init-session.ps1
+3. 读取 task_plan.md，补全：
+   - Goal（1 句话）
+   - Phases（3-7 个阶段，带 Status: pending / in_progress / complete）
+   - Key Questions（需要回答的关键问题）
+4. 执行任务时遵守：
+   - 每 2 次“查看/搜索/浏览”后，立刻把发现写入 findings.md
+   - 每次重要决策前，先读取 task_plan.md 刷新目标
+   - 任何错误都记录在 task_plan.md 的 Errors Encountered，并写清楚尝试次数与解决方式
+5. 持续把本次会话的行动与验证结果写入 progress.md（包括命令、测试、输出）
+
+## 输出要求
+
+- 你的回答优先引用这些文件中的最新内容（而不是依赖聊天记忆）
+- 任务结束前，确保所有阶段均为 complete（或明确说明未完成原因与后续）
@@ -0,0 +1,83 @@
+---
+name: planning-with-files
+version: "2.9.0"
+description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls. Now with automatic session recovery after /clear.
+---
+
+# Planning with Files
+
+Work like Manus: Use persistent markdown files as your "working memory on disk."
+
+## FIRST: Check for Previous Session (v2.2.0)
+
+Before starting work, check for unsynced context from a previous session:
+
+```bash
+python3 .continue/skills/planning-with-files/scripts/session-catchup.py "$(pwd)" || python .continue/skills/planning-with-files/scripts/session-catchup.py "$(pwd)"
+```
+
+If catchup report shows unsynced context:
+1. Run `git diff --stat` to see actual code changes
+2. Read current planning files
+3. Update planning files based on catchup + git diff
+4. Then proceed with task
+
+## Quick Start
+
+Before any complex task:
+
+1. Create `task_plan.md`, `findings.md`, `progress.md` in your project root
+2. If they don't exist yet, initialize them using:
+   - macOS/Linux: `bash .continue/skills/planning-with-files/scripts/init-session.sh`
+   - Windows: `powershell -ExecutionPolicy Bypass -File .continue/skills/planning-with-files/scripts/init-session.ps1`
+3. Re-read `task_plan.md` before major decisions
+4. Update `task_plan.md` after each phase completes
+5. Write discoveries to `findings.md` (especially after web/search/image/PDF viewing)
+
+## 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`.
+
+### 2. The 2-Action Rule
+
+After every 2 view/browser/search operations, save key findings to text files.
+
+### 3. Read Before Decide
+
+Before major decisions, read `task_plan.md` to refresh goals.
+
+### 4. Update After Act
+
+After completing any phase, update statuses and log errors in `task_plan.md`.
+
+### 5. Log ALL Errors
+
+Every error goes in the plan file so you don't repeat it.
+
+### 6. Never Repeat Failures
+
+If an action failed, the next action must be different.
+
+## References
+
+- [reference.md](reference.md)
+- [examples.md](examples.md)
@@ -0,0 +1,202 @@
+# Examples: Planning with Files in Action
+
+## Example 1: Research Task
+
+**User Request:** "Research the benefits of morning exercise and write a summary"
+
+### Loop 1: Create Plan
+```bash
+Write task_plan.md
+```
+
+```markdown
+# Task Plan: Morning Exercise Benefits Research
+
+## Goal
+Create a research summary on the benefits of morning exercise.
+
+## Phases
+- [ ] Phase 1: Create this plan ✓
+- [ ] Phase 2: Search and gather sources
+- [ ] Phase 3: Synthesize findings
+- [ ] Phase 4: Deliver summary
+
+## Key Questions
+1. What are the physical health benefits?
+2. What are the mental health benefits?
+3. What scientific studies support this?
+
+## Status
+**Currently in Phase 1** - Creating plan
+```
+
+### Loop 2: Research
+```bash
+Read task_plan.md           # Refresh goals
+WebSearch "morning exercise benefits"
+Write notes.md              # Store findings
+Edit task_plan.md           # Mark Phase 2 complete
+```
+
+### Loop 3: Synthesize
+```bash
+Read task_plan.md           # Refresh goals
+Read notes.md               # Get findings
+Write morning_exercise_summary.md
+Edit task_plan.md           # Mark Phase 3 complete
+```
+
+### Loop 4: Deliver
+```bash
+Read task_plan.md           # Verify complete
+Deliver morning_exercise_summary.md
+```
+
+---
+
+## Example 2: Bug Fix Task
+
+**User Request:** "Fix the login bug in the authentication module"
+
+### task_plan.md
+```markdown
+# Task Plan: Fix Login Bug
+
+## Goal
+Identify and fix the bug preventing successful login.
+
+## Phases
+- [x] Phase 1: Understand the bug report ✓
+- [x] Phase 2: Locate relevant code ✓
+- [ ] Phase 3: Identify root cause (CURRENT)
+- [ ] Phase 4: Implement fix
+- [ ] Phase 5: Test and verify
+
+## Key Questions
+1. What error message appears?
+2. Which file handles authentication?
+3. What changed recently?
+
+## Decisions Made
+- Auth handler is in src/auth/login.ts
+- Error occurs in validateToken() function
+
+## Errors Encountered
+- [Initial] TypeError: Cannot read property 'token' of undefined
+  → Root cause: user object not awaited properly
+
+## Status
+**Currently in Phase 3** - Found root cause, preparing fix
+```
+
+---
+
+## Example 3: Feature Development
+
+**User Request:** "Add a dark mode toggle to the settings page"
+
+### The 3-File Pattern in Action
+
+**task_plan.md:**
+```markdown
+# Task Plan: Dark Mode Toggle
+
+## Goal
+Add functional dark mode toggle to settings.
+
+## Phases
+- [x] Phase 1: Research existing theme system ✓
+- [x] Phase 2: Design implementation approach ✓
+- [ ] Phase 3: Implement toggle component (CURRENT)
+- [ ] Phase 4: Add theme switching logic
+- [ ] Phase 5: Test and polish
+
+## Decisions Made
+- Using CSS custom properties for theme
+- Storing preference in localStorage
+- Toggle component in SettingsPage.tsx
+
+## Status
+**Currently in Phase 3** - Building toggle component
+```
+
+**notes.md:**
+```markdown
+# Notes: Dark Mode Implementation
+
+## Existing Theme System
+- Located in: src/styles/theme.ts
+- Uses: CSS custom properties
+- Current themes: light only
+
+## Files to Modify
+1. src/styles/theme.ts - Add dark theme colors
+2. src/components/SettingsPage.tsx - Add toggle
+3. src/hooks/useTheme.ts - Create new hook
+4. src/App.tsx - Wrap with ThemeProvider
+
+## Color Decisions
+- Dark background: #1a1a2e
+- Dark surface: #16213e
+- Dark text: #eaeaea
+```
+
+**dark_mode_implementation.md:** (deliverable)
+```markdown
+# Dark Mode Implementation
+
+## Changes Made
+
+### 1. Added dark theme colors
+File: src/styles/theme.ts
+...
+
+### 2. Created useTheme hook
+File: src/hooks/useTheme.ts
+...
+```
+
+---
+
+## Example 4: Error Recovery Pattern
+
+When something fails, DON'T hide it:
+
+### Before (Wrong)
+```
+Action: Read config.json
+Error: File not found
+Action: Read config.json  # Silent retry
+Action: Read config.json  # Another retry
+```
+
+### After (Correct)
+```
+Action: Read config.json
+Error: File not found
+
+# Update task_plan.md:
+## Errors Encountered
+- config.json not found → Will create default config
+
+Action: Write config.json (default config)
+Action: Read config.json
+Success!
+```
+
+---
+
+## The Read-Before-Decide Pattern
+
+Always read your plan before major decisions:
+
+```
+[Many tool calls have happened...]
+[Context is getting long...]
+[Original goal might be forgotten...]
+
+→ Read task_plan.md          # This brings goals back into attention!
+→ Now make the decision       # Goals are fresh in context
+```
+
+This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a "goal refresh" mechanism.
@@ -0,0 +1,218 @@
+# Reference: Manus Context Engineering Principles
+
+This skill is based on context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
+
+## The 6 Manus Principles
+
+### Principle 1: Design Around KV-Cache
+
+> "KV-cache hit rate is THE single most important metric for production AI agents."
+
+**Statistics:**
+- ~100:1 input-to-output token ratio
+- Cached tokens: $0.30/MTok vs Uncached: $3/MTok
+- 10x cost difference!
+
+**Implementation:**
+- Keep prompt prefixes STABLE (single-token change invalidates cache)
+- NO timestamps in system prompts
+- Make context APPEND-ONLY with deterministic serialization
+
+### Principle 2: Mask, Don't Remove
+
+Don't dynamically remove tools (breaks KV-cache). Use logit masking instead.
+
+**Best Practice:** Use consistent action prefixes (e.g., `browser_`, `shell_`, `file_`) for easier masking.
+
+### Principle 3: Filesystem as External Memory
+
+> "Markdown is my 'working memory' on disk."
+
+**The Formula:**
+```
+Context Window = RAM (volatile, limited)
+Filesystem = Disk (persistent, unlimited)
+```
+
+**Compression Must Be Restorable:**
+- Keep URLs even if web content is dropped
+- Keep file paths when dropping document contents
+- Never lose the pointer to full data
+
+### Principle 4: Manipulate Attention Through Recitation
+
+> "Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."
+
+**Problem:** After ~50 tool calls, models forget original goals ("lost in the middle" effect).
+
+**Solution:** Re-read `task_plan.md` before each decision. Goals appear in the attention window.
+
+```
+Start of context: [Original goal - far away, forgotten]
+...many tool calls...
+End of context: [Recently read task_plan.md - gets ATTENTION!]
+```
+
+### Principle 5: Keep the Wrong Stuff In
+
+> "Leave the wrong turns in the context."
+
+**Why:**
+- Failed actions with stack traces let model implicitly update beliefs
+- Reduces mistake repetition
+- Error recovery is "one of the clearest signals of TRUE agentic behavior"
+
+### Principle 6: Don't Get Few-Shotted
+
+> "Uniformity breeds fragility."
+
+**Problem:** Repetitive action-observation pairs cause drift and hallucination.
+
+**Solution:** Introduce controlled variation:
+- Vary phrasings slightly
+- Don't copy-paste patterns blindly
+- Recalibrate on repetitive tasks
+
+---
+
+## The 3 Context Engineering Strategies
+
+Based on Lance Martin's analysis of Manus architecture.
+
+### Strategy 1: Context Reduction
+
+**Compaction:**
+```
+Tool calls have TWO representations:
+├── FULL: Raw tool content (stored in filesystem)
+└── COMPACT: Reference/file path only
+
+RULES:
+- Apply compaction to STALE (older) tool results
+- Keep RECENT results FULL (to guide next decision)
+```
+
+**Summarization:**
+- Applied when compaction reaches diminishing returns
+- Generated using full tool results
+- Creates standardized summary objects
+
+### Strategy 2: Context Isolation (Multi-Agent)
+
+**Architecture:**
+```
+┌─────────────────────────────────┐
+│         PLANNER AGENT           │
+│  └─ Assigns tasks to sub-agents │
+├─────────────────────────────────┤
+│       KNOWLEDGE MANAGER         │
+│  └─ Reviews conversations       │
+│  └─ Determines filesystem store │
+├─────────────────────────────────┤
+│      EXECUTOR SUB-AGENTS        │
+│  └─ Perform assigned tasks      │
+│  └─ Have own context windows    │
+└─────────────────────────────────┘
+```
+
+**Key Insight:** Manus originally used `todo.md` for task planning but found ~33% of actions were spent updating it. Shifted to dedicated planner agent calling executor sub-agents.
+
+### Strategy 3: Context Offloading
+
+**Tool Design:**
+- Use <20 atomic functions total
+- Store full results in filesystem, not context
+- Use `glob` and `grep` for searching
+- Progressive disclosure: load information only as needed
+
+---
+
+## The Agent Loop
+
+Manus operates in a continuous 7-step loop:
+
+```
+┌─────────────────────────────────────────┐
+│  1. ANALYZE CONTEXT                      │
+│     - Understand user intent             │
+│     - Assess current state               │
+│     - Review recent observations         │
+├─────────────────────────────────────────┤
+│  2. THINK                                │
+│     - Should I update the plan?          │
+│     - What's the next logical action?    │
+│     - Are there blockers?                │
+├─────────────────────────────────────────┤
+│  3. SELECT TOOL                          │
+│     - Choose ONE tool                    │
+│     - Ensure parameters available        │
+├─────────────────────────────────────────┤
+│  4. EXECUTE ACTION                       │
+│     - Tool runs in sandbox               │
+├─────────────────────────────────────────┤
+│  5. RECEIVE OBSERVATION                  │
+│     - Result appended to context         │
+├─────────────────────────────────────────┤
+│  6. ITERATE                              │
+│     - Return to step 1                   │
+│     - Continue until complete            │
+├─────────────────────────────────────────┤
+│  7. DELIVER OUTCOME                      │
+│     - Send results to user               │
+│     - Attach all relevant files          │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## File Types Manus Creates
+
+| File | Purpose | When Created | When Updated |
+|------|---------|--------------|--------------|
+| `task_plan.md` | Phase tracking, progress | Task start | After completing phases |
+| `findings.md` | Discoveries, decisions | After any discovery | After viewing images/PDFs |
+| `progress.md` | Session log, what's done | At breakpoints | Throughout session |
+| Code files | Implementation | Before execution | After errors |
+
+---
+
+## Critical Constraints
+
+- Single-action execution: one tool call per turn
+- Plan is required: always know goal, current phase, remaining phases
+- Files are memory: context is volatile; filesystem is persistent
+- Never repeat failures: if action failed, next action must be different
+- Communication is a tool: message types include info, ask, result
+
+---
+
+## Manus Statistics
+
+| Metric | Value |
+|--------|-------|
+| Average tool calls per task | ~50 |
+| Input-to-output token ratio | 100:1 |
+| Acquisition price | $2 billion |
+| Time to $100M revenue | 8 months |
+| Framework refactors since launch | 5 times |
+
+---
+
+## Key Quotes
+
+> "Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."
+
+> "if action_failed: next_action != same_action. Track what you tried. Mutate the approach."
+
+> "Error recovery is one of the clearest signals of TRUE agentic behavior."
+
+> "KV-cache hit rate is the single most important metric for a production-stage AI agent."
+
+> "Leave the wrong turns in the context."
+
+---
+
+## Source
+
+Based on Manus's official context engineering documentation:
+https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
@@ -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,203 @@
+#!/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)
+
+    has_planning_files = any(
+        Path(project_path, f).exists() for f in PLANNING_FILES
+    )
+
+    if not project_dir.exists():
+        return
+
+    sessions = get_sessions_sorted(project_dir)
+    if len(sessions) < 1:
+        return
+
+    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)
+
+    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
+
+    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:]:
+        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()
@@ -0,0 +1,248 @@
+---
+name: planning-with-files
+version: "2.9.0"
+description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls. Now with automatic session recovery after /clear.
+user-invocable: true
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - WebFetch
+  - WebSearch
+hooks:
+  PreToolUse:
+    - matcher: "Write|Edit|Bash|Read|Glob|Grep"
+      hooks:
+        - type: command
+          command: "cat task_plan.md 2>/dev/null | head -30 || true"
+  PostToolUse:
+    - matcher: "Write|Edit"
+      hooks:
+        - type: command
+          command: "echo '[planning-with-files] File updated. If this completes a phase, update task_plan.md status.'"
+  Stop:
+    - hooks:
+        - type: command
+          command: |
+            SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files}/scripts"
+
+            IS_WINDOWS=0
+            if [ "${OS-}" = "Windows_NT" ]; then
+              IS_WINDOWS=1
+            else
+              UNAME_S="$(uname -s 2>/dev/null || echo '')"
+              case "$UNAME_S" in
+                CYGWIN*|MINGW*|MSYS*) IS_WINDOWS=1 ;;
+              esac
+            fi
+
+            if [ "$IS_WINDOWS" -eq 1 ]; then
+              if command -v pwsh >/dev/null 2>&1; then
+                pwsh -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
+                powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
+                sh "$SCRIPT_DIR/check-complete.sh"
+              else
+                powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
+                sh "$SCRIPT_DIR/check-complete.sh"
+              fi
+            else
+              sh "$SCRIPT_DIR/check-complete.sh"
+            fi
+---
+
+# Planning with Files
+
+Work like Manus: Use persistent markdown files as your "working memory on disk."
+
+## FIRST: Check for Previous Session (v2.2.0)
+
+**Before starting work**, check for unsynced context from a previous session:
+
+```bash
+# Linux/macOS (auto-detects python3 or python)
+$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
+```
+
+```powershell
+# Windows PowerShell
+python "$env:USERPROFILE\.cursor\skills\planning-with-files\scripts\session-catchup.py" (Get-Location)
+```
+
+If catchup report shows unsynced context:
+1. Run `git diff --stat` to see actual code changes
+2. Read current planning files
+3. Update planning files based on catchup + git diff
+4. Then proceed with task
+
+## Important: Where Files Go
+
+- **Templates** are in `${CLAUDE_PLUGIN_ROOT}/templates/`
+- **Your planning files** go in **your project directory**
+
+| Location | What Goes There |
+|----------|-----------------|
+| Skill directory (`${CLAUDE_PLUGIN_ROOT}/`) | Templates, scripts, reference docs |
+| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
+
+## Quick Start
+
+Before ANY complex task:
+
+1. **Create `task_plan.md`** — Use [templates/task_plan.md](templates/task_plan.md) as reference
+2. **Create `findings.md`** — Use [templates/findings.md](templates/findings.md) as reference
+3. **Create `progress.md`** — Use [templates/progress.md](templates/progress.md) as reference
+4. **Re-read plan before decisions** — Refreshes goals in attention window
+5. **Update after each phase** — Mark complete, log errors
+
+> **Note:** Planning files go in your project root, not the skill installation folder.
+
+## 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 |
+
+## 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
+
+## 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
+
+## Scripts
+
+Helper scripts for automation:
+
+- `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 (v2.2.0)
+
+## Advanced Topics
+
+- **Manus Principles:** See [reference.md](reference.md)
+- **Real Examples:** See [examples.md](examples.md)
+
+## 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 |
+| Create files in skill directory | Create files in your project |
@@ -0,0 +1,202 @@
+# Examples: Planning with Files in Action
+
+## Example 1: Research Task
+
+**User Request:** "Research the benefits of morning exercise and write a summary"
+
+### Loop 1: Create Plan
+```bash
+Write task_plan.md
+```
+
+```markdown
+# Task Plan: Morning Exercise Benefits Research
+
+## Goal
+Create a research summary on the benefits of morning exercise.
+
+## Phases
+- [ ] Phase 1: Create this plan ✓
+- [ ] Phase 2: Search and gather sources
+- [ ] Phase 3: Synthesize findings
+- [ ] Phase 4: Deliver summary
+
+## Key Questions
+1. What are the physical health benefits?
+2. What are the mental health benefits?
+3. What scientific studies support this?
+
+## Status
+**Currently in Phase 1** - Creating plan
+```
+
+### Loop 2: Research
+```bash
+Read task_plan.md           # Refresh goals
+WebSearch "morning exercise benefits"
+Write notes.md              # Store findings
+Edit task_plan.md           # Mark Phase 2 complete
+```
+
+### Loop 3: Synthesize
+```bash
+Read task_plan.md           # Refresh goals
+Read notes.md               # Get findings
+Write morning_exercise_summary.md
+Edit task_plan.md           # Mark Phase 3 complete
+```
+
+### Loop 4: Deliver
+```bash
+Read task_plan.md           # Verify complete
+Deliver morning_exercise_summary.md
+```
+
+---
+
+## Example 2: Bug Fix Task
+
+**User Request:** "Fix the login bug in the authentication module"
+
+### task_plan.md
+```markdown
+# Task Plan: Fix Login Bug
+
+## Goal
+Identify and fix the bug preventing successful login.
+
+## Phases
+- [x] Phase 1: Understand the bug report ✓
+- [x] Phase 2: Locate relevant code ✓
+- [ ] Phase 3: Identify root cause (CURRENT)
+- [ ] Phase 4: Implement fix
+- [ ] Phase 5: Test and verify
+
+## Key Questions
+1. What error message appears?
+2. Which file handles authentication?
+3. What changed recently?
+
+## Decisions Made
+- Auth handler is in src/auth/login.ts
+- Error occurs in validateToken() function
+
+## Errors Encountered
+- [Initial] TypeError: Cannot read property 'token' of undefined
+  → Root cause: user object not awaited properly
+
+## Status
+**Currently in Phase 3** - Found root cause, preparing fix
+```
+
+---
+
+## Example 3: Feature Development
+
+**User Request:** "Add a dark mode toggle to the settings page"
+
+### The 3-File Pattern in Action
+
+**task_plan.md:**
+```markdown
+# Task Plan: Dark Mode Toggle
+
+## Goal
+Add functional dark mode toggle to settings.
+
+## Phases
+- [x] Phase 1: Research existing theme system ✓
+- [x] Phase 2: Design implementation approach ✓
+- [ ] Phase 3: Implement toggle component (CURRENT)
+- [ ] Phase 4: Add theme switching logic
+- [ ] Phase 5: Test and polish
+
+## Decisions Made
+- Using CSS custom properties for theme
+- Storing preference in localStorage
+- Toggle component in SettingsPage.tsx
+
+## Status
+**Currently in Phase 3** - Building toggle component
+```
+
+**notes.md:**
+```markdown
+# Notes: Dark Mode Implementation
+
+## Existing Theme System
+- Located in: src/styles/theme.ts
+- Uses: CSS custom properties
+- Current themes: light only
+
+## Files to Modify
+1. src/styles/theme.ts - Add dark theme colors
+2. src/components/SettingsPage.tsx - Add toggle
+3. src/hooks/useTheme.ts - Create new hook
+4. src/App.tsx - Wrap with ThemeProvider
+
+## Color Decisions
+- Dark background: #1a1a2e
+- Dark surface: #16213e
+- Dark text: #eaeaea
+```
+
+**dark_mode_implementation.md:** (deliverable)
+```markdown
+# Dark Mode Implementation
+
+## Changes Made
+
+### 1. Added dark theme colors
+File: src/styles/theme.ts
+...
+
+### 2. Created useTheme hook
+File: src/hooks/useTheme.ts
+...
+```
+
+---
+
+## Example 4: Error Recovery Pattern
+
+When something fails, DON'T hide it:
+
+### Before (Wrong)
+```
+Action: Read config.json
+Error: File not found
+Action: Read config.json  # Silent retry
+Action: Read config.json  # Another retry
+```
+
+### After (Correct)
+```
+Action: Read config.json
+Error: File not found
+
+# Update task_plan.md:
+## Errors Encountered
+- config.json not found → Will create default config
+
+Action: Write config.json (default config)
+Action: Read config.json
+Success!
+```
+
+---
+
+## The Read-Before-Decide Pattern
+
+**Always read your plan before major decisions:**
+
+```
+[Many tool calls have happened...]
+[Context is getting long...]
+[Original goal might be forgotten...]
+
+→ Read task_plan.md          # This brings goals back into attention!
+→ Now make the decision       # Goals are fresh in context
+```
+
+This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a "goal refresh" mechanism.
@@ -0,0 +1,218 @@
+# Reference: Manus Context Engineering Principles
+
+This skill is based on context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
+
+## The 6 Manus Principles
+
+### Principle 1: Design Around KV-Cache
+
+> "KV-cache hit rate is THE single most important metric for production AI agents."
+
+**Statistics:**
+- ~100:1 input-to-output token ratio
+- Cached tokens: $0.30/MTok vs Uncached: $3/MTok
+- 10x cost difference!
+
+**Implementation:**
+- Keep prompt prefixes STABLE (single-token change invalidates cache)
+- NO timestamps in system prompts
+- Make context APPEND-ONLY with deterministic serialization
+
+### Principle 2: Mask, Don't Remove
+
+Don't dynamically remove tools (breaks KV-cache). Use logit masking instead.
+
+**Best Practice:** Use consistent action prefixes (e.g., `browser_`, `shell_`, `file_`) for easier masking.
+
+### Principle 3: Filesystem as External Memory
+
+> "Markdown is my 'working memory' on disk."
+
+**The Formula:**
+```
+Context Window = RAM (volatile, limited)
+Filesystem = Disk (persistent, unlimited)
+```
+
+**Compression Must Be Restorable:**
+- Keep URLs even if web content is dropped
+- Keep file paths when dropping document contents
+- Never lose the pointer to full data
+
+### Principle 4: Manipulate Attention Through Recitation
+
+> "Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."
+
+**Problem:** After ~50 tool calls, models forget original goals ("lost in the middle" effect).
+
+**Solution:** Re-read `task_plan.md` before each decision. Goals appear in the attention window.
+
+```
+Start of context: [Original goal - far away, forgotten]
+...many tool calls...
+End of context: [Recently read task_plan.md - gets ATTENTION!]
+```
+
+### Principle 5: Keep the Wrong Stuff In
+
+> "Leave the wrong turns in the context."
+
+**Why:**
+- Failed actions with stack traces let model implicitly update beliefs
+- Reduces mistake repetition
+- Error recovery is "one of the clearest signals of TRUE agentic behavior"
+
+### Principle 6: Don't Get Few-Shotted
+
+> "Uniformity breeds fragility."
+
+**Problem:** Repetitive action-observation pairs cause drift and hallucination.
+
+**Solution:** Introduce controlled variation:
+- Vary phrasings slightly
+- Don't copy-paste patterns blindly
+- Recalibrate on repetitive tasks
+
+---
+
+## The 3 Context Engineering Strategies
+
+Based on Lance Martin's analysis of Manus architecture.
+
+### Strategy 1: Context Reduction
+
+**Compaction:**
+```
+Tool calls have TWO representations:
+├── FULL: Raw tool content (stored in filesystem)
+└── COMPACT: Reference/file path only
+
+RULES:
+- Apply compaction to STALE (older) tool results
+- Keep RECENT results FULL (to guide next decision)
+```
+
+**Summarization:**
+- Applied when compaction reaches diminishing returns
+- Generated using full tool results
+- Creates standardized summary objects
+
+### Strategy 2: Context Isolation (Multi-Agent)
+
+**Architecture:**
+```
+┌─────────────────────────────────┐
+│         PLANNER AGENT           │
+│  └─ Assigns tasks to sub-agents │
+├─────────────────────────────────┤
+│       KNOWLEDGE MANAGER         │
+│  └─ Reviews conversations       │
+│  └─ Determines filesystem store │
+├─────────────────────────────────┤
+│      EXECUTOR SUB-AGENTS        │
+│  └─ Perform assigned tasks      │
+│  └─ Have own context windows    │
+└─────────────────────────────────┘
+```
+
+**Key Insight:** Manus originally used `todo.md` for task planning but found ~33% of actions were spent updating it. Shifted to dedicated planner agent calling executor sub-agents.
+
+### Strategy 3: Context Offloading
+
+**Tool Design:**
+- Use <20 atomic functions total
+- Store full results in filesystem, not context
+- Use `glob` and `grep` for searching
+- Progressive disclosure: load information only as needed
+
+---
+
+## The Agent Loop
+
+Manus operates in a continuous 7-step loop:
+
+```
+┌─────────────────────────────────────────┐
+│  1. ANALYZE CONTEXT                      │
+│     - Understand user intent             │
+│     - Assess current state               │
+│     - Review recent observations         │
+├─────────────────────────────────────────┤
+│  2. THINK                                │
+│     - Should I update the plan?          │
+│     - What's the next logical action?    │
+│     - Are there blockers?                │
+├─────────────────────────────────────────┤
+│  3. SELECT TOOL                          │
+│     - Choose ONE tool                    │
+│     - Ensure parameters available        │
+├─────────────────────────────────────────┤
+│  4. EXECUTE ACTION                       │
+│     - Tool runs in sandbox               │
+├─────────────────────────────────────────┤
+│  5. RECEIVE OBSERVATION                  │
+│     - Result appended to context         │
+├─────────────────────────────────────────┤
+│  6. ITERATE                              │
+│     - Return to step 1                   │
+│     - Continue until complete            │
+├─────────────────────────────────────────┤
+│  7. DELIVER OUTCOME                      │
+│     - Send results to user               │
+│     - Attach all relevant files          │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## File Types Manus Creates
+
+| File | Purpose | When Created | When Updated |
+|------|---------|--------------|--------------|
+| `task_plan.md` | Phase tracking, progress | Task start | After completing phases |
+| `findings.md` | Discoveries, decisions | After ANY discovery | After viewing images/PDFs |
+| `progress.md` | Session log, what's done | At breakpoints | Throughout session |
+| Code files | Implementation | Before execution | After errors |
+
+---
+
+## Critical Constraints
+
+- **Single-Action Execution:** ONE tool call per turn. No parallel execution.
+- **Plan is Required:** Agent must ALWAYS know: goal, current phase, remaining phases
+- **Files are Memory:** Context = volatile. Filesystem = persistent.
+- **Never Repeat Failures:** If action failed, next action MUST be different
+- **Communication is a Tool:** Message types: `info` (progress), `ask` (blocking), `result` (terminal)
+
+---
+
+## Manus Statistics
+
+| Metric | Value |
+|--------|-------|
+| Average tool calls per task | ~50 |
+| Input-to-output token ratio | 100:1 |
+| Acquisition price | $2 billion |
+| Time to $100M revenue | 8 months |
+| Framework refactors since launch | 5 times |
+
+---
+
+## Key Quotes
+
+> "Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."
+
+> "if action_failed: next_action != same_action. Track what you tried. Mutate the approach."
+
+> "Error recovery is one of the clearest signals of TRUE agentic behavior."
+
+> "KV-cache hit rate is the single most important metric for a production-stage AI agent."
+
+> "Leave the wrong turns in the context."
+
+---
+
+## Source
+
+Based on Manus's official context engineering documentation:
+https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
@@ -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
@@ -1,18 +1,13 @@
+---
+name: planning-with-files
+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.
+---
+
 # 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
+## Core Principle

 ```
 Context Window = RAM (volatile, limited)
@@ -21,6 +16,16 @@ Filesystem = Disk (persistent, unlimited)
 → Anything important gets written to disk.
 ```

+## Quick Start
+
+Before ANY complex task, create these three files:
+
+1. **task_plan.md** — Track phases and progress
+2. **findings.md** — Store research and discoveries
+3. **progress.md** — Session log and test results
+
+See [templates/](./templates/) for starting templates.
+
 ## File Purposes

 | File | Purpose | When to Update |
@@ -101,32 +106,6 @@ AFTER 3 FAILURES: Escalate to User
 | 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:**
@@ -141,13 +120,33 @@ Vary phrasings slightly. Don't copy-paste patterns blindly. Uniformity breeds fr
 - Single-file edits
 - Quick lookups

+## 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 |
+
 ## 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 |
+
+## Advanced Topics
+
+- **Manus Principles:** See [references.md](./references.md)
+- **Real Examples:** See [examples.md](./examples.md)
+
+---
+
+**This pattern is why Manus went from launch to $2B acquisition in 8 months.**
@@ -0,0 +1,202 @@
+# Examples: Planning with Files in Action
+
+## Example 1: Research Task
+
+**User Request:** "Research the benefits of morning exercise and write a summary"
+
+### Loop 1: Create Plan
+```bash
+Write task_plan.md
+```
+
+```markdown
+# Task Plan: Morning Exercise Benefits Research
+
+## Goal
+Create a research summary on the benefits of morning exercise.
+
+## Phases
+- [ ] Phase 1: Create this plan ✓
+- [ ] Phase 2: Search and gather sources
+- [ ] Phase 3: Synthesize findings
+- [ ] Phase 4: Deliver summary
+
+## Key Questions
+1. What are the physical health benefits?
+2. What are the mental health benefits?
+3. What scientific studies support this?
+
+## Status
+**Currently in Phase 1** - Creating plan
+```
+
+### Loop 2: Research
+```bash
+Read task_plan.md           # Refresh goals
+WebSearch "morning exercise benefits"
+Write notes.md              # Store findings
+Edit task_plan.md           # Mark Phase 2 complete
+```
+
+### Loop 3: Synthesize
+```bash
+Read task_plan.md           # Refresh goals
+Read notes.md               # Get findings
+Write morning_exercise_summary.md
+Edit task_plan.md           # Mark Phase 3 complete
+```
+
+### Loop 4: Deliver
+```bash
+Read task_plan.md           # Verify complete
+Deliver morning_exercise_summary.md
+```
+
+---
+
+## Example 2: Bug Fix Task
+
+**User Request:** "Fix the login bug in the authentication module"
+
+### task_plan.md
+```markdown
+# Task Plan: Fix Login Bug
+
+## Goal
+Identify and fix the bug preventing successful login.
+
+## Phases
+- [x] Phase 1: Understand the bug report ✓
+- [x] Phase 2: Locate relevant code ✓
+- [ ] Phase 3: Identify root cause (CURRENT)
+- [ ] Phase 4: Implement fix
+- [ ] Phase 5: Test and verify
+
+## Key Questions
+1. What error message appears?
+2. Which file handles authentication?
+3. What changed recently?
+
+## Decisions Made
+- Auth handler is in src/auth/login.ts
+- Error occurs in validateToken() function
+
+## Errors Encountered
+- [Initial] TypeError: Cannot read property 'token' of undefined
+  → Root cause: user object not awaited properly
+
+## Status
+**Currently in Phase 3** - Found root cause, preparing fix
+```
+
+---
+
+## Example 3: Feature Development
+
+**User Request:** "Add a dark mode toggle to the settings page"
+
+### The 3-File Pattern in Action
+
+**task_plan.md:**
+```markdown
+# Task Plan: Dark Mode Toggle
+
+## Goal
+Add functional dark mode toggle to settings.
+
+## Phases
+- [x] Phase 1: Research existing theme system ✓
+- [x] Phase 2: Design implementation approach ✓
+- [ ] Phase 3: Implement toggle component (CURRENT)
+- [ ] Phase 4: Add theme switching logic
+- [ ] Phase 5: Test and polish
+
+## Decisions Made
+- Using CSS custom properties for theme
+- Storing preference in localStorage
+- Toggle component in SettingsPage.tsx
+
+## Status
+**Currently in Phase 3** - Building toggle component
+```
+
+**notes.md:**
+```markdown
+# Notes: Dark Mode Implementation
+
+## Existing Theme System
+- Located in: src/styles/theme.ts
+- Uses: CSS custom properties
+- Current themes: light only
+
+## Files to Modify
+1. src/styles/theme.ts - Add dark theme colors
+2. src/components/SettingsPage.tsx - Add toggle
+3. src/hooks/useTheme.ts - Create new hook
+4. src/App.tsx - Wrap with ThemeProvider
+
+## Color Decisions
+- Dark background: #1a1a2e
+- Dark surface: #16213e
+- Dark text: #eaeaea
+```
+
+**dark_mode_implementation.md:** (deliverable)
+```markdown
+# Dark Mode Implementation
+
+## Changes Made
+
+### 1. Added dark theme colors
+File: src/styles/theme.ts
+...
+
+### 2. Created useTheme hook
+File: src/hooks/useTheme.ts
+...
+```
+
+---
+
+## Example 4: Error Recovery Pattern
+
+When something fails, DON'T hide it:
+
+### Before (Wrong)
+```
+Action: Read config.json
+Error: File not found
+Action: Read config.json  # Silent retry
+Action: Read config.json  # Another retry
+```
+
+### After (Correct)
+```
+Action: Read config.json
+Error: File not found
+
+# Update task_plan.md:
+## Errors Encountered
+- config.json not found → Will create default config
+
+Action: Write config.json (default config)
+Action: Read config.json
+Success!
+```
+
+---
+
+## The Read-Before-Decide Pattern
+
+**Always read your plan before major decisions:**
+
+```
+[Many tool calls have happened...]
+[Context is getting long...]
+[Original goal might be forgotten...]
+
+→ Read task_plan.md          # This brings goals back into attention!
+→ Now make the decision       # Goals are fresh in context
+```
+
+This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a "goal refresh" mechanism.
@@ -0,0 +1,218 @@
+# Reference: Manus Context Engineering Principles
+
+This skill is based on context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
+
+## The 6 Manus Principles
+
+### Principle 1: Design Around KV-Cache
+
+> "KV-cache hit rate is THE single most important metric for production AI agents."
+
+**Statistics:**
+- ~100:1 input-to-output token ratio
+- Cached tokens: $0.30/MTok vs Uncached: $3/MTok
+- 10x cost difference!
+
+**Implementation:**
+- Keep prompt prefixes STABLE (single-token change invalidates cache)
+- NO timestamps in system prompts
+- Make context APPEND-ONLY with deterministic serialization
+
+### Principle 2: Mask, Don't Remove
+
+Don't dynamically remove tools (breaks KV-cache). Use logit masking instead.
+
+**Best Practice:** Use consistent action prefixes (e.g., `browser_`, `shell_`, `file_`) for easier masking.
+
+### Principle 3: Filesystem as External Memory
+
+> "Markdown is my 'working memory' on disk."
+
+**The Formula:**
+```
+Context Window = RAM (volatile, limited)
+Filesystem = Disk (persistent, unlimited)
+```
+
+**Compression Must Be Restorable:**
+- Keep URLs even if web content is dropped
+- Keep file paths when dropping document contents
+- Never lose the pointer to full data
+
+### Principle 4: Manipulate Attention Through Recitation
+
+> "Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."
+
+**Problem:** After ~50 tool calls, models forget original goals ("lost in the middle" effect).
+
+**Solution:** Re-read `task_plan.md` before each decision. Goals appear in the attention window.
+
+```
+Start of context: [Original goal - far away, forgotten]
+...many tool calls...
+End of context: [Recently read task_plan.md - gets ATTENTION!]
+```
+
+### Principle 5: Keep the Wrong Stuff In
+
+> "Leave the wrong turns in the context."
+
+**Why:**
+- Failed actions with stack traces let model implicitly update beliefs
+- Reduces mistake repetition
+- Error recovery is "one of the clearest signals of TRUE agentic behavior"
+
+### Principle 6: Don't Get Few-Shotted
+
+> "Uniformity breeds fragility."
+
+**Problem:** Repetitive action-observation pairs cause drift and hallucination.
+
+**Solution:** Introduce controlled variation:
+- Vary phrasings slightly
+- Don't copy-paste patterns blindly
+- Recalibrate on repetitive tasks
+
+---
+
+## The 3 Context Engineering Strategies
+
+Based on Lance Martin's analysis of Manus architecture.
+
+### Strategy 1: Context Reduction
+
+**Compaction:**
+```
+Tool calls have TWO representations:
+├── FULL: Raw tool content (stored in filesystem)
+└── COMPACT: Reference/file path only
+
+RULES:
+- Apply compaction to STALE (older) tool results
+- Keep RECENT results FULL (to guide next decision)
+```
+
+**Summarization:**
+- Applied when compaction reaches diminishing returns
+- Generated using full tool results
+- Creates standardized summary objects
+
+### Strategy 2: Context Isolation (Multi-Agent)
+
+**Architecture:**
+```
+┌─────────────────────────────────┐
+│         PLANNER AGENT           │
+│  └─ Assigns tasks to sub-agents │
+├─────────────────────────────────┤
+│       KNOWLEDGE MANAGER         │
+│  └─ Reviews conversations       │
+│  └─ Determines filesystem store │
+├─────────────────────────────────┤
+│      EXECUTOR SUB-AGENTS        │
+│  └─ Perform assigned tasks      │
+│  └─ Have own context windows    │
+└─────────────────────────────────┘
+```
+
+**Key Insight:** Manus originally used `todo.md` for task planning but found ~33% of actions were spent updating it. Shifted to dedicated planner agent calling executor sub-agents.
+
+### Strategy 3: Context Offloading
+
+**Tool Design:**
+- Use <20 atomic functions total
+- Store full results in filesystem, not context
+- Use `glob` and `grep` for searching
+- Progressive disclosure: load information only as needed
+
+---
+
+## The Agent Loop
+
+Manus operates in a continuous 7-step loop:
+
+```
+┌─────────────────────────────────────────┐
+│  1. ANALYZE CONTEXT                      │
+│     - Understand user intent             │
+│     - Assess current state               │
+│     - Review recent observations         │
+├─────────────────────────────────────────┤
+│  2. THINK                                │
+│     - Should I update the plan?          │
+│     - What's the next logical action?    │
+│     - Are there blockers?                │
+├─────────────────────────────────────────┤
+│  3. SELECT TOOL                          │
+│     - Choose ONE tool                    │
+│     - Ensure parameters available        │
+├─────────────────────────────────────────┤
+│  4. EXECUTE ACTION                       │
+│     - Tool runs in sandbox               │
+├─────────────────────────────────────────┤
+│  5. RECEIVE OBSERVATION                  │
+│     - Result appended to context         │
+├─────────────────────────────────────────┤
+│  6. ITERATE                              │
+│     - Return to step 1                   │
+│     - Continue until complete            │
+├─────────────────────────────────────────┤
+│  7. DELIVER OUTCOME                      │
+│     - Send results to user               │
+│     - Attach all relevant files          │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## File Types Manus Creates
+
+| File | Purpose | When Created | When Updated |
+|------|---------|--------------|--------------|
+| `task_plan.md` | Phase tracking, progress | Task start | After completing phases |
+| `findings.md` | Discoveries, decisions | After ANY discovery | After viewing images/PDFs |
+| `progress.md` | Session log, what's done | At breakpoints | Throughout session |
+| Code files | Implementation | Before execution | After errors |
+
+---
+
+## Critical Constraints
+
+- **Single-Action Execution:** ONE tool call per turn. No parallel execution.
+- **Plan is Required:** Agent must ALWAYS know: goal, current phase, remaining phases
+- **Files are Memory:** Context = volatile. Filesystem = persistent.
+- **Never Repeat Failures:** If action failed, next action MUST be different
+- **Communication is a Tool:** Message types: `info` (progress), `ask` (blocking), `result` (terminal)
+
+---
+
+## Manus Statistics
+
+| Metric | Value |
+|--------|-------|
+| Average tool calls per task | ~50 |
+| Input-to-output token ratio | 100:1 |
+| Acquisition price | $2 billion |
+| Time to $100M revenue | 8 months |
+| Framework refactors since launch | 5 times |
+
+---
+
+## Key Quotes
+
+> "Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."
+
+> "if action_failed: next_action != same_action. Track what you tried. Mutate the approach."
+
+> "Error recovery is one of the clearest signals of TRUE agentic behavior."
+
+> "KV-cache hit rate is the single most important metric for a production-stage AI agent."
+
+> "Leave the wrong turns in the context."
+
+---
+
+## Source
+
+Based on Manus's official context engineering documentation:
+https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
@@ -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
@@ -1,23 +1,34 @@
 ---
-description: Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use for multi-step tasks, research, or anything requiring >5 tool calls.
-globs:
-alwaysApply: false
+name: planning-with-files
+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.
 ---

 # Planning with Files

 Work like Manus: Use persistent markdown files as your "working memory on disk."

+## Important: Where Files Go
+
+- **Templates** are in this skill's `templates/` folder
+- **Your planning files** go in **your project directory**
+
+| Location | What Goes There |
+|----------|-----------------|
+| Skill directory | Templates, scripts, reference docs |
+| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
+
 ## 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
+1. **Create `task_plan.md`** — Use [templates/task_plan.md](templates/task_plan.md) as reference
+2. **Create `findings.md`** — Use [templates/findings.md](templates/findings.md) as reference
+3. **Create `progress.md`** — Use [templates/progress.md](templates/progress.md) as reference
 4. **Re-read plan before decisions** — Refreshes goals in attention window
 5. **Update after each phase** — Mark complete, log errors

+> **Note:** Planning files go in your project root, not the skill installation folder.
+
 ## The Core Pattern

 ```
@@ -119,20 +130,6 @@ If you can answer these, your context management is solid:
 | 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:**
@@ -147,13 +144,33 @@ Vary phrasings slightly. Don't copy-paste patterns blindly. Uniformity breeds fr
 - Single-file edits
 - Quick lookups

+## 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
+
+## Scripts
+
+Helper scripts for automation:
+
+- `scripts/init-session.sh` — Initialize all planning files
+- `scripts/check-complete.sh` — Verify all phases complete
+
+## Advanced Topics
+
+- **Manus Principles:** See [references/reference.md](references/reference.md)
+- **Real Examples:** See [references/examples.md](references/examples.md)
+
 ## 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 |
+| Create files in skill directory | Create files in your project |
@@ -0,0 +1,202 @@
+# Examples: Planning with Files in Action
+
+## Example 1: Research Task
+
+**User Request:** "Research the benefits of morning exercise and write a summary"
+
+### Loop 1: Create Plan
+```bash
+Write task_plan.md
+```
+
+```markdown
+# Task Plan: Morning Exercise Benefits Research
+
+## Goal
+Create a research summary on the benefits of morning exercise.
+
+## Phases
+- [ ] Phase 1: Create this plan ✓
+- [ ] Phase 2: Search and gather sources
+- [ ] Phase 3: Synthesize findings
+- [ ] Phase 4: Deliver summary
+
+## Key Questions
+1. What are the physical health benefits?
+2. What are the mental health benefits?
+3. What scientific studies support this?
+
+## Status
+**Currently in Phase 1** - Creating plan
+```
+
+### Loop 2: Research
+```bash
+Read task_plan.md           # Refresh goals
+WebSearch "morning exercise benefits"
+Write notes.md              # Store findings
+Edit task_plan.md           # Mark Phase 2 complete
+```
+
+### Loop 3: Synthesize
+```bash
+Read task_plan.md           # Refresh goals
+Read notes.md               # Get findings
+Write morning_exercise_summary.md
+Edit task_plan.md           # Mark Phase 3 complete
+```
+
+### Loop 4: Deliver
+```bash
+Read task_plan.md           # Verify complete
+Deliver morning_exercise_summary.md
+```
+
+---
+
+## Example 2: Bug Fix Task
+
+**User Request:** "Fix the login bug in the authentication module"
+
+### task_plan.md
+```markdown
+# Task Plan: Fix Login Bug
+
+## Goal
+Identify and fix the bug preventing successful login.
+
+## Phases
+- [x] Phase 1: Understand the bug report ✓
+- [x] Phase 2: Locate relevant code ✓
+- [ ] Phase 3: Identify root cause (CURRENT)
+- [ ] Phase 4: Implement fix
+- [ ] Phase 5: Test and verify
+
+## Key Questions
+1. What error message appears?
+2. Which file handles authentication?
+3. What changed recently?
+
+## Decisions Made
+- Auth handler is in src/auth/login.ts
+- Error occurs in validateToken() function
+
+## Errors Encountered
+- [Initial] TypeError: Cannot read property 'token' of undefined
+  → Root cause: user object not awaited properly
+
+## Status
+**Currently in Phase 3** - Found root cause, preparing fix
+```
+
+---
+
+## Example 3: Feature Development
+
+**User Request:** "Add a dark mode toggle to the settings page"
+
+### The 3-File Pattern in Action
+
+**task_plan.md:**
+```markdown
+# Task Plan: Dark Mode Toggle
+
+## Goal
+Add functional dark mode toggle to settings.
+
+## Phases
+- [x] Phase 1: Research existing theme system ✓
+- [x] Phase 2: Design implementation approach ✓
+- [ ] Phase 3: Implement toggle component (CURRENT)
+- [ ] Phase 4: Add theme switching logic
+- [ ] Phase 5: Test and polish
+
+## Decisions Made
+- Using CSS custom properties for theme
+- Storing preference in localStorage
+- Toggle component in SettingsPage.tsx
+
+## Status
+**Currently in Phase 3** - Building toggle component
+```
+
+**notes.md:**
+```markdown
+# Notes: Dark Mode Implementation
+
+## Existing Theme System
+- Located in: src/styles/theme.ts
+- Uses: CSS custom properties
+- Current themes: light only
+
+## Files to Modify
+1. src/styles/theme.ts - Add dark theme colors
+2. src/components/SettingsPage.tsx - Add toggle
+3. src/hooks/useTheme.ts - Create new hook
+4. src/App.tsx - Wrap with ThemeProvider
+
+## Color Decisions
+- Dark background: #1a1a2e
+- Dark surface: #16213e
+- Dark text: #eaeaea
+```
+
+**dark_mode_implementation.md:** (deliverable)
+```markdown
+# Dark Mode Implementation
+
+## Changes Made
+
+### 1. Added dark theme colors
+File: src/styles/theme.ts
+...
+
+### 2. Created useTheme hook
+File: src/hooks/useTheme.ts
+...
+```
+
+---
+
+## Example 4: Error Recovery Pattern
+
+When something fails, DON'T hide it:
+
+### Before (Wrong)
+```
+Action: Read config.json
+Error: File not found
+Action: Read config.json  # Silent retry
+Action: Read config.json  # Another retry
+```
+
+### After (Correct)
+```
+Action: Read config.json
+Error: File not found
+
+# Update task_plan.md:
+## Errors Encountered
+- config.json not found → Will create default config
+
+Action: Write config.json (default config)
+Action: Read config.json
+Success!
+```
+
+---
+
+## The Read-Before-Decide Pattern
+
+**Always read your plan before major decisions:**
+
+```
+[Many tool calls have happened...]
+[Context is getting long...]
+[Original goal might be forgotten...]
+
+→ Read task_plan.md          # This brings goals back into attention!
+→ Now make the decision       # Goals are fresh in context
+```
+
+This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a "goal refresh" mechanism.
@@ -0,0 +1,218 @@
+# Reference: Manus Context Engineering Principles
+
+This skill is based on context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
+
+## The 6 Manus Principles
+
+### Principle 1: Design Around KV-Cache
+
+> "KV-cache hit rate is THE single most important metric for production AI agents."
+
+**Statistics:**
+- ~100:1 input-to-output token ratio
+- Cached tokens: $0.30/MTok vs Uncached: $3/MTok
+- 10x cost difference!
+
+**Implementation:**
+- Keep prompt prefixes STABLE (single-token change invalidates cache)
+- NO timestamps in system prompts
+- Make context APPEND-ONLY with deterministic serialization
+
+### Principle 2: Mask, Don't Remove
+
+Don't dynamically remove tools (breaks KV-cache). Use logit masking instead.
+
+**Best Practice:** Use consistent action prefixes (e.g., `browser_`, `shell_`, `file_`) for easier masking.
+
+### Principle 3: Filesystem as External Memory
+
+> "Markdown is my 'working memory' on disk."
+
+**The Formula:**
+```
+Context Window = RAM (volatile, limited)
+Filesystem = Disk (persistent, unlimited)
+```
+
+**Compression Must Be Restorable:**
+- Keep URLs even if web content is dropped
+- Keep file paths when dropping document contents
+- Never lose the pointer to full data
+
+### Principle 4: Manipulate Attention Through Recitation
+
+> "Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."
+
+**Problem:** After ~50 tool calls, models forget original goals ("lost in the middle" effect).
+
+**Solution:** Re-read `task_plan.md` before each decision. Goals appear in the attention window.
+
+```
+Start of context: [Original goal - far away, forgotten]
+...many tool calls...
+End of context: [Recently read task_plan.md - gets ATTENTION!]
+```
+
+### Principle 5: Keep the Wrong Stuff In
+
+> "Leave the wrong turns in the context."
+
+**Why:**
+- Failed actions with stack traces let model implicitly update beliefs
+- Reduces mistake repetition
+- Error recovery is "one of the clearest signals of TRUE agentic behavior"
+
+### Principle 6: Don't Get Few-Shotted
+
+> "Uniformity breeds fragility."
+
+**Problem:** Repetitive action-observation pairs cause drift and hallucination.
+
+**Solution:** Introduce controlled variation:
+- Vary phrasings slightly
+- Don't copy-paste patterns blindly
+- Recalibrate on repetitive tasks
+
+---
+
+## The 3 Context Engineering Strategies
+
+Based on Lance Martin's analysis of Manus architecture.
+
+### Strategy 1: Context Reduction
+
+**Compaction:**
+```
+Tool calls have TWO representations:
+├── FULL: Raw tool content (stored in filesystem)
+└── COMPACT: Reference/file path only
+
+RULES:
+- Apply compaction to STALE (older) tool results
+- Keep RECENT results FULL (to guide next decision)
+```
+
+**Summarization:**
+- Applied when compaction reaches diminishing returns
+- Generated using full tool results
+- Creates standardized summary objects
+
+### Strategy 2: Context Isolation (Multi-Agent)
+
+**Architecture:**
+```
+┌─────────────────────────────────┐
+│         PLANNER AGENT           │
+│  └─ Assigns tasks to sub-agents │
+├─────────────────────────────────┤
+│       KNOWLEDGE MANAGER         │
+│  └─ Reviews conversations       │
+│  └─ Determines filesystem store │
+├─────────────────────────────────┤
+│      EXECUTOR SUB-AGENTS        │
+│  └─ Perform assigned tasks      │
+│  └─ Have own context windows    │
+└─────────────────────────────────┘
+```
+
+**Key Insight:** Manus originally used `todo.md` for task planning but found ~33% of actions were spent updating it. Shifted to dedicated planner agent calling executor sub-agents.
+
+### Strategy 3: Context Offloading
+
+**Tool Design:**
+- Use <20 atomic functions total
+- Store full results in filesystem, not context
+- Use `glob` and `grep` for searching
+- Progressive disclosure: load information only as needed
+
+---
+
+## The Agent Loop
+
+Manus operates in a continuous 7-step loop:
+
+```
+┌─────────────────────────────────────────┐
+│  1. ANALYZE CONTEXT                      │
+│     - Understand user intent             │
+│     - Assess current state               │
+│     - Review recent observations         │
+├─────────────────────────────────────────┤
+│  2. THINK                                │
+│     - Should I update the plan?          │
+│     - What's the next logical action?    │
+│     - Are there blockers?                │
+├─────────────────────────────────────────┤
+│  3. SELECT TOOL                          │
+│     - Choose ONE tool                    │
+│     - Ensure parameters available        │
+├─────────────────────────────────────────┤
+│  4. EXECUTE ACTION                       │
+│     - Tool runs in sandbox               │
+├─────────────────────────────────────────┤
+│  5. RECEIVE OBSERVATION                  │
+│     - Result appended to context         │
+├─────────────────────────────────────────┤
+│  6. ITERATE                              │
+│     - Return to step 1                   │
+│     - Continue until complete            │
+├─────────────────────────────────────────┤
+│  7. DELIVER OUTCOME                      │
+│     - Send results to user               │
+│     - Attach all relevant files          │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## File Types Manus Creates
+
+| File | Purpose | When Created | When Updated |
+|------|---------|--------------|--------------|
+| `task_plan.md` | Phase tracking, progress | Task start | After completing phases |
+| `findings.md` | Discoveries, decisions | After ANY discovery | After viewing images/PDFs |
+| `progress.md` | Session log, what's done | At breakpoints | Throughout session |
+| Code files | Implementation | Before execution | After errors |
+
+---
+
+## Critical Constraints
+
+- **Single-Action Execution:** ONE tool call per turn. No parallel execution.
+- **Plan is Required:** Agent must ALWAYS know: goal, current phase, remaining phases
+- **Files are Memory:** Context = volatile. Filesystem = persistent.
+- **Never Repeat Failures:** If action failed, next action MUST be different
+- **Communication is a Tool:** Message types: `info` (progress), `ask` (blocking), `result` (terminal)
+
+---
+
+## Manus Statistics
+
+| Metric | Value |
+|--------|-------|
+| Average tool calls per task | ~50 |
+| Input-to-output token ratio | 100:1 |
+| Acquisition price | $2 billion |
+| Time to $100M revenue | 8 months |
+| Framework refactors since launch | 5 times |
+
+---
+
+## Key Quotes
+
+> "Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."
+
+> "if action_failed: next_action != same_action. Track what you tried. Mutate the approach."
+
+> "Error recovery is one of the clearest signals of TRUE agentic behavior."
+
+> "KV-cache hit rate is the single most important metric for a production-stage AI agent."
+
+> "Leave the wrong turns in the context."
+
+---
+
+## Source
+
+Based on Manus's official context engineering documentation:
+https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
@@ -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,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
@@ -0,0 +1,248 @@
+---
+name: planning-with-files
+version: "2.9.0"
+description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls. Now with automatic session recovery after /clear.
+user-invocable: true
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - WebFetch
+  - WebSearch
+hooks:
+  PreToolUse:
+    - matcher: "Write|Edit|Bash|Read|Glob|Grep"
+      hooks:
+        - type: command
+          command: "cat task_plan.md 2>/dev/null | head -30 || true"
+  PostToolUse:
+    - matcher: "Write|Edit"
+      hooks:
+        - type: command
+          command: "echo '[planning-with-files] File updated. If this completes a phase, update task_plan.md status.'"
+  Stop:
+    - hooks:
+        - type: command
+          command: |
+            SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files}/scripts"
+
+            IS_WINDOWS=0
+            if [ "${OS-}" = "Windows_NT" ]; then
+              IS_WINDOWS=1
+            else
+              UNAME_S="$(uname -s 2>/dev/null || echo '')"
+              case "$UNAME_S" in
+                CYGWIN*|MINGW*|MSYS*) IS_WINDOWS=1 ;;
+              esac
+            fi
+
+            if [ "$IS_WINDOWS" -eq 1 ]; then
+              if command -v pwsh >/dev/null 2>&1; then
+                pwsh -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
+                powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
+                sh "$SCRIPT_DIR/check-complete.sh"
+              else
+                powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
+                sh "$SCRIPT_DIR/check-complete.sh"
+              fi
+            else
+              sh "$SCRIPT_DIR/check-complete.sh"
+            fi
+---
+
+# Planning with Files
+
+Work like Manus: Use persistent markdown files as your "working memory on disk."
+
+## FIRST: Check for Previous Session (v2.2.0)
+
+**Before starting work**, check for unsynced context from a previous session:
+
+```bash
+# Linux/macOS (auto-detects python3 or python)
+$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
+```
+
+```powershell
+# Windows PowerShell
+python "$env:USERPROFILE\.kilocode\skills\planning-with-files\scripts\session-catchup.py" (Get-Location)
+```
+
+If catchup report shows unsynced context:
+1. Run `git diff --stat` to see actual code changes
+2. Read current planning files
+3. Update planning files based on catchup + git diff
+4. Then proceed with task
+
+## Important: Where Files Go
+
+- **Templates** are in `${CLAUDE_PLUGIN_ROOT}/templates/`
+- **Your planning files** go in **your project directory**
+
+| Location | What Goes There |
+|----------|-----------------|
+| Skill directory (`${CLAUDE_PLUGIN_ROOT}/`) | Templates, scripts, reference docs |
+| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
+
+## Quick Start
+
+Before ANY complex task:
+
+1. **Create `task_plan.md`** — Use [templates/task_plan.md](templates/task_plan.md) as reference
+2. **Create `findings.md`** — Use [templates/findings.md](templates/findings.md) as reference
+3. **Create `progress.md`** — Use [templates/progress.md](templates/progress.md) as reference
+4. **Re-read plan before decisions** — Refreshes goals in attention window
+5. **Update after each phase** — Mark complete, log errors
+
+> **Note:** Planning files go in your project root, not the skill installation folder.
+
+## 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 |
+
+## 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
+
+## 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
+
+## Scripts
+
+Helper scripts for automation:
+
+- `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 (v2.2.0)
+
+## Advanced Topics
+
+- **Manus Principles:** See [reference.md](reference.md)
+- **Real Examples:** See [examples.md](examples.md)
+
+## 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 |
+| Create files in skill directory | Create files in your project |
@@ -0,0 +1,202 @@
+# Examples: Planning with Files in Action
+
+## Example 1: Research Task
+
+**User Request:** "Research the benefits of morning exercise and write a summary"
+
+### Loop 1: Create Plan
+```bash
+Write task_plan.md
+```
+
+```markdown
+# Task Plan: Morning Exercise Benefits Research
+
+## Goal
+Create a research summary on the benefits of morning exercise.
+
+## Phases
+- [ ] Phase 1: Create this plan ✓
+- [ ] Phase 2: Search and gather sources
+- [ ] Phase 3: Synthesize findings
+- [ ] Phase 4: Deliver summary
+
+## Key Questions
+1. What are the physical health benefits?
+2. What are the mental health benefits?
+3. What scientific studies support this?
+
+## Status
+**Currently in Phase 1** - Creating plan
+```
+
+### Loop 2: Research
+```bash
+Read task_plan.md           # Refresh goals
+WebSearch "morning exercise benefits"
+Write notes.md              # Store findings
+Edit task_plan.md           # Mark Phase 2 complete
+```
+
+### Loop 3: Synthesize
+```bash
+Read task_plan.md           # Refresh goals
+Read notes.md               # Get findings
+Write morning_exercise_summary.md
+Edit task_plan.md           # Mark Phase 3 complete
+```
+
+### Loop 4: Deliver
+```bash
+Read task_plan.md           # Verify complete
+Deliver morning_exercise_summary.md
+```
+
+---
+
+## Example 2: Bug Fix Task
+
+**User Request:** "Fix the login bug in the authentication module"
+
+### task_plan.md
+```markdown
+# Task Plan: Fix Login Bug
+
+## Goal
+Identify and fix the bug preventing successful login.
+
+## Phases
+- [x] Phase 1: Understand the bug report ✓
+- [x] Phase 2: Locate relevant code ✓
+- [ ] Phase 3: Identify root cause (CURRENT)
+- [ ] Phase 4: Implement fix
+- [ ] Phase 5: Test and verify
+
+## Key Questions
+1. What error message appears?
+2. Which file handles authentication?
+3. What changed recently?
+
+## Decisions Made
+- Auth handler is in src/auth/login.ts
+- Error occurs in validateToken() function
+
+## Errors Encountered
+- [Initial] TypeError: Cannot read property 'token' of undefined
+  → Root cause: user object not awaited properly
+
+## Status
+**Currently in Phase 3** - Found root cause, preparing fix
+```
+
+---
+
+## Example 3: Feature Development
+
+**User Request:** "Add a dark mode toggle to the settings page"
+
+### The 3-File Pattern in Action
+
+**task_plan.md:**
+```markdown
+# Task Plan: Dark Mode Toggle
+
+## Goal
+Add functional dark mode toggle to settings.
+
+## Phases
+- [x] Phase 1: Research existing theme system ✓
+- [x] Phase 2: Design implementation approach ✓
+- [ ] Phase 3: Implement toggle component (CURRENT)
+- [ ] Phase 4: Add theme switching logic
+- [ ] Phase 5: Test and polish
+
+## Decisions Made
+- Using CSS custom properties for theme
+- Storing preference in localStorage
+- Toggle component in SettingsPage.tsx
+
+## Status
+**Currently in Phase 3** - Building toggle component
+```
+
+**notes.md:**
+```markdown
+# Notes: Dark Mode Implementation
+
+## Existing Theme System
+- Located in: src/styles/theme.ts
+- Uses: CSS custom properties
+- Current themes: light only
+
+## Files to Modify
+1. src/styles/theme.ts - Add dark theme colors
+2. src/components/SettingsPage.tsx - Add toggle
+3. src/hooks/useTheme.ts - Create new hook
+4. src/App.tsx - Wrap with ThemeProvider
+
+## Color Decisions
+- Dark background: #1a1a2e
+- Dark surface: #16213e
+- Dark text: #eaeaea
+```
+
+**dark_mode_implementation.md:** (deliverable)
+```markdown
+# Dark Mode Implementation
+
+## Changes Made
+
+### 1. Added dark theme colors
+File: src/styles/theme.ts
+...
+
+### 2. Created useTheme hook
+File: src/hooks/useTheme.ts
+...
+```
+
+---
+
+## Example 4: Error Recovery Pattern
+
+When something fails, DON'T hide it:
+
+### Before (Wrong)
+```
+Action: Read config.json
+Error: File not found
+Action: Read config.json  # Silent retry
+Action: Read config.json  # Another retry
+```
+
+### After (Correct)
+```
+Action: Read config.json
+Error: File not found
+
+# Update task_plan.md:
+## Errors Encountered
+- config.json not found → Will create default config
+
+Action: Write config.json (default config)
+Action: Read config.json
+Success!
+```
+
+---
+
+## The Read-Before-Decide Pattern
+
+**Always read your plan before major decisions:**
+
+```
+[Many tool calls have happened...]
+[Context is getting long...]
+[Original goal might be forgotten...]
+
+→ Read task_plan.md          # This brings goals back into attention!
+→ Now make the decision       # Goals are fresh in context
+```
+
+This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a "goal refresh" mechanism.
@@ -0,0 +1,218 @@
+# Reference: Manus Context Engineering Principles
+
+This skill is based on context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
+
+## The 6 Manus Principles
+
+### Principle 1: Design Around KV-Cache
+
+> "KV-cache hit rate is THE single most important metric for production AI agents."
+
+**Statistics:**
+- ~100:1 input-to-output token ratio
+- Cached tokens: $0.30/MTok vs Uncached: $3/MTok
+- 10x cost difference!
+
+**Implementation:**
+- Keep prompt prefixes STABLE (single-token change invalidates cache)
+- NO timestamps in system prompts
+- Make context APPEND-ONLY with deterministic serialization
+
+### Principle 2: Mask, Don't Remove
+
+Don't dynamically remove tools (breaks KV-cache). Use logit masking instead.
+
+**Best Practice:** Use consistent action prefixes (e.g., `browser_`, `shell_`, `file_`) for easier masking.
+
+### Principle 3: Filesystem as External Memory
+
+> "Markdown is my 'working memory' on disk."
+
+**The Formula:**
+```
+Context Window = RAM (volatile, limited)
+Filesystem = Disk (persistent, unlimited)
+```
+
+**Compression Must Be Restorable:**
+- Keep URLs even if web content is dropped
+- Keep file paths when dropping document contents
+- Never lose the pointer to full data
+
+### Principle 4: Manipulate Attention Through Recitation
+
+> "Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."
+
+**Problem:** After ~50 tool calls, models forget original goals ("lost in the middle" effect).
+
+**Solution:** Re-read `task_plan.md` before each decision. Goals appear in the attention window.
+
+```
+Start of context: [Original goal - far away, forgotten]
+...many tool calls...
+End of context: [Recently read task_plan.md - gets ATTENTION!]
+```
+
+### Principle 5: Keep the Wrong Stuff In
+
+> "Leave the wrong turns in the context."
+
+**Why:**
+- Failed actions with stack traces let model implicitly update beliefs
+- Reduces mistake repetition
+- Error recovery is "one of the clearest signals of TRUE agentic behavior"
+
+### Principle 6: Don't Get Few-Shotted
+
+> "Uniformity breeds fragility."
+
+**Problem:** Repetitive action-observation pairs cause drift and hallucination.
+
+**Solution:** Introduce controlled variation:
+- Vary phrasings slightly
+- Don't copy-paste patterns blindly
+- Recalibrate on repetitive tasks
+
+---
+
+## The 3 Context Engineering Strategies
+
+Based on Lance Martin's analysis of Manus architecture.
+
+### Strategy 1: Context Reduction
+
+**Compaction:**
+```
+Tool calls have TWO representations:
+├── FULL: Raw tool content (stored in filesystem)
+└── COMPACT: Reference/file path only
+
+RULES:
+- Apply compaction to STALE (older) tool results
+- Keep RECENT results FULL (to guide next decision)
+```
+
+**Summarization:**
+- Applied when compaction reaches diminishing returns
+- Generated using full tool results
+- Creates standardized summary objects
+
+### Strategy 2: Context Isolation (Multi-Agent)
+
+**Architecture:**
+```
+┌─────────────────────────────────┐
+│         PLANNER AGENT           │
+│  └─ Assigns tasks to sub-agents │
+├─────────────────────────────────┤
+│       KNOWLEDGE MANAGER         │
+│  └─ Reviews conversations       │
+│  └─ Determines filesystem store │
+├─────────────────────────────────┤
+│      EXECUTOR SUB-AGENTS        │
+│  └─ Perform assigned tasks      │
+│  └─ Have own context windows    │
+└─────────────────────────────────┘
+```
+
+**Key Insight:** Manus originally used `todo.md` for task planning but found ~33% of actions were spent updating it. Shifted to dedicated planner agent calling executor sub-agents.
+
+### Strategy 3: Context Offloading
+
+**Tool Design:**
+- Use <20 atomic functions total
+- Store full results in filesystem, not context
+- Use `glob` and `grep` for searching
+- Progressive disclosure: load information only as needed
+
+---
+
+## The Agent Loop
+
+Manus operates in a continuous 7-step loop:
+
+```
+┌─────────────────────────────────────────┐
+│  1. ANALYZE CONTEXT                      │
+│     - Understand user intent             │
+│     - Assess current state               │
+│     - Review recent observations         │
+├─────────────────────────────────────────┤
+│  2. THINK                                │
+│     - Should I update the plan?          │
+│     - What's the next logical action?    │
+│     - Are there blockers?                │
+├─────────────────────────────────────────┤
+│  3. SELECT TOOL                          │
+│     - Choose ONE tool                    │
+│     - Ensure parameters available        │
+├─────────────────────────────────────────┤
+│  4. EXECUTE ACTION                       │
+│     - Tool runs in sandbox               │
+├─────────────────────────────────────────┤
+│  5. RECEIVE OBSERVATION                  │
+│     - Result appended to context         │
+├─────────────────────────────────────────┤
+│  6. ITERATE                              │
+│     - Return to step 1                   │
+│     - Continue until complete            │
+├─────────────────────────────────────────┤
+│  7. DELIVER OUTCOME                      │
+│     - Send results to user               │
+│     - Attach all relevant files          │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## File Types Manus Creates
+
+| File | Purpose | When Created | When Updated |
+|------|---------|--------------|--------------|
+| `task_plan.md` | Phase tracking, progress | Task start | After completing phases |
+| `findings.md` | Discoveries, decisions | After ANY discovery | After viewing images/PDFs |
+| `progress.md` | Session log, what's done | At breakpoints | Throughout session |
+| Code files | Implementation | Before execution | After errors |
+
+---
+
+## Critical Constraints
+
+- **Single-Action Execution:** ONE tool call per turn. No parallel execution.
+- **Plan is Required:** Agent must ALWAYS know: goal, current phase, remaining phases
+- **Files are Memory:** Context = volatile. Filesystem = persistent.
+- **Never Repeat Failures:** If action failed, next action MUST be different
+- **Communication is a Tool:** Message types: `info` (progress), `ask` (blocking), `result` (terminal)
+
+---
+
+## Manus Statistics
+
+| Metric | Value |
+|--------|-------|
+| Average tool calls per task | ~50 |
+| Input-to-output token ratio | 100:1 |
+| Acquisition price | $2 billion |
+| Time to $100M revenue | 8 months |
+| Framework refactors since launch | 5 times |
+
+---
+
+## Key Quotes
+
+> "Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."
+
+> "if action_failed: next_action != same_action. Track what you tried. Mutate the approach."
+
+> "Error recovery is one of the clearest signals of TRUE agentic behavior."
+
+> "KV-cache hit rate is the single most important metric for a production-stage AI agent."
+
+> "Leave the wrong turns in the context."
+
+---
+
+## Source
+
+Based on Manus's official context engineering documentation:
+https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
@@ -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
@@ -0,0 +1,248 @@
+---
+name: planning-with-files
+version: "2.9.0"
+description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls. Now with automatic session recovery after /clear.
+user-invocable: true
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - WebFetch
+  - WebSearch
+hooks:
+  PreToolUse:
+    - matcher: "Write|Edit|Bash|Read|Glob|Grep"
+      hooks:
+        - type: command
+          command: "cat task_plan.md 2>/dev/null | head -30 || true"
+  PostToolUse:
+    - matcher: "Write|Edit"
+      hooks:
+        - type: command
+          command: "echo '[planning-with-files] File updated. If this completes a phase, update task_plan.md status.'"
+  Stop:
+    - hooks:
+        - type: command
+          command: |
+            SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files}/scripts"
+
+            IS_WINDOWS=0
+            if [ "${OS-}" = "Windows_NT" ]; then
+              IS_WINDOWS=1
+            else
+              UNAME_S="$(uname -s 2>/dev/null || echo '')"
+              case "$UNAME_S" in
+                CYGWIN*|MINGW*|MSYS*) IS_WINDOWS=1 ;;
+              esac
+            fi
+
+            if [ "$IS_WINDOWS" -eq 1 ]; then
+              if command -v pwsh >/dev/null 2>&1; then
+                pwsh -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
+                powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
+                sh "$SCRIPT_DIR/check-complete.sh"
+              else
+                powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
+                sh "$SCRIPT_DIR/check-complete.sh"
+              fi
+            else
+              sh "$SCRIPT_DIR/check-complete.sh"
+            fi
+---
+
+# Planning with Files
+
+Work like Manus: Use persistent markdown files as your "working memory on disk."
+
+## FIRST: Check for Previous Session (v2.2.0)
+
+**Before starting work**, check for unsynced context from a previous session:
+
+```bash
+# Linux/macOS (auto-detects python3 or python)
+$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
+```
+
+```powershell
+# Windows PowerShell
+python "$env:USERPROFILE\.opencode\skills\planning-with-files\scripts\session-catchup.py" (Get-Location)
+```
+
+If catchup report shows unsynced context:
+1. Run `git diff --stat` to see actual code changes
+2. Read current planning files
+3. Update planning files based on catchup + git diff
+4. Then proceed with task
+
+## Important: Where Files Go
+
+- **Templates** are in `${CLAUDE_PLUGIN_ROOT}/templates/`
+- **Your planning files** go in **your project directory**
+
+| Location | What Goes There |
+|----------|-----------------|
+| Skill directory (`${CLAUDE_PLUGIN_ROOT}/`) | Templates, scripts, reference docs |
+| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
+
+## Quick Start
+
+Before ANY complex task:
+
+1. **Create `task_plan.md`** — Use [templates/task_plan.md](templates/task_plan.md) as reference
+2. **Create `findings.md`** — Use [templates/findings.md](templates/findings.md) as reference
+3. **Create `progress.md`** — Use [templates/progress.md](templates/progress.md) as reference
+4. **Re-read plan before decisions** — Refreshes goals in attention window
+5. **Update after each phase** — Mark complete, log errors
+
+> **Note:** Planning files go in your project root, not the skill installation folder.
+
+## 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 |
+
+## 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
+
+## 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
+
+## Scripts
+
+Helper scripts for automation:
+
+- `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 (v2.2.0)
+
+## Advanced Topics
+
+- **Manus Principles:** See [reference.md](reference.md)
+- **Real Examples:** See [examples.md](examples.md)
+
+## 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 |
+| Create files in skill directory | Create files in your project |
@@ -0,0 +1,202 @@
+# Examples: Planning with Files in Action
+
+## Example 1: Research Task
+
+**User Request:** "Research the benefits of morning exercise and write a summary"
+
+### Loop 1: Create Plan
+```bash
+Write task_plan.md
+```
+
+```markdown
+# Task Plan: Morning Exercise Benefits Research
+
+## Goal
+Create a research summary on the benefits of morning exercise.
+
+## Phases
+- [ ] Phase 1: Create this plan ✓
+- [ ] Phase 2: Search and gather sources
+- [ ] Phase 3: Synthesize findings
+- [ ] Phase 4: Deliver summary
+
+## Key Questions
+1. What are the physical health benefits?
+2. What are the mental health benefits?
+3. What scientific studies support this?
+
+## Status
+**Currently in Phase 1** - Creating plan
+```
+
+### Loop 2: Research
+```bash
+Read task_plan.md           # Refresh goals
+WebSearch "morning exercise benefits"
+Write notes.md              # Store findings
+Edit task_plan.md           # Mark Phase 2 complete
+```
+
+### Loop 3: Synthesize
+```bash
+Read task_plan.md           # Refresh goals
+Read notes.md               # Get findings
+Write morning_exercise_summary.md
+Edit task_plan.md           # Mark Phase 3 complete
+```
+
+### Loop 4: Deliver
+```bash
+Read task_plan.md           # Verify complete
+Deliver morning_exercise_summary.md
+```
+
+---
+
+## Example 2: Bug Fix Task
+
+**User Request:** "Fix the login bug in the authentication module"
+
+### task_plan.md
+```markdown
+# Task Plan: Fix Login Bug
+
+## Goal
+Identify and fix the bug preventing successful login.
+
+## Phases
+- [x] Phase 1: Understand the bug report ✓
+- [x] Phase 2: Locate relevant code ✓
+- [ ] Phase 3: Identify root cause (CURRENT)
+- [ ] Phase 4: Implement fix
+- [ ] Phase 5: Test and verify
+
+## Key Questions
+1. What error message appears?
+2. Which file handles authentication?
+3. What changed recently?
+
+## Decisions Made
+- Auth handler is in src/auth/login.ts
+- Error occurs in validateToken() function
+
+## Errors Encountered
+- [Initial] TypeError: Cannot read property 'token' of undefined
+  → Root cause: user object not awaited properly
+
+## Status
+**Currently in Phase 3** - Found root cause, preparing fix
+```
+
+---
+
+## Example 3: Feature Development
+
+**User Request:** "Add a dark mode toggle to the settings page"
+
+### The 3-File Pattern in Action
+
+**task_plan.md:**
+```markdown
+# Task Plan: Dark Mode Toggle
+
+## Goal
+Add functional dark mode toggle to settings.
+
+## Phases
+- [x] Phase 1: Research existing theme system ✓
+- [x] Phase 2: Design implementation approach ✓
+- [ ] Phase 3: Implement toggle component (CURRENT)
+- [ ] Phase 4: Add theme switching logic
+- [ ] Phase 5: Test and polish
+
+## Decisions Made
+- Using CSS custom properties for theme
+- Storing preference in localStorage
+- Toggle component in SettingsPage.tsx
+
+## Status
+**Currently in Phase 3** - Building toggle component
+```
+
+**notes.md:**
+```markdown
+# Notes: Dark Mode Implementation
+
+## Existing Theme System
+- Located in: src/styles/theme.ts
+- Uses: CSS custom properties
+- Current themes: light only
+
+## Files to Modify
+1. src/styles/theme.ts - Add dark theme colors
+2. src/components/SettingsPage.tsx - Add toggle
+3. src/hooks/useTheme.ts - Create new hook
+4. src/App.tsx - Wrap with ThemeProvider
+
+## Color Decisions
+- Dark background: #1a1a2e
+- Dark surface: #16213e
+- Dark text: #eaeaea
+```
+
+**dark_mode_implementation.md:** (deliverable)
+```markdown
+# Dark Mode Implementation
+
+## Changes Made
+
+### 1. Added dark theme colors
+File: src/styles/theme.ts
+...
+
+### 2. Created useTheme hook
+File: src/hooks/useTheme.ts
+...
+```
+
+---
+
+## Example 4: Error Recovery Pattern
+
+When something fails, DON'T hide it:
+
+### Before (Wrong)
+```
+Action: Read config.json
+Error: File not found
+Action: Read config.json  # Silent retry
+Action: Read config.json  # Another retry
+```
+
+### After (Correct)
+```
+Action: Read config.json
+Error: File not found
+
+# Update task_plan.md:
+## Errors Encountered
+- config.json not found → Will create default config
+
+Action: Write config.json (default config)
+Action: Read config.json
+Success!
+```
+
+---
+
+## The Read-Before-Decide Pattern
+
+**Always read your plan before major decisions:**
+
+```
+[Many tool calls have happened...]
+[Context is getting long...]
+[Original goal might be forgotten...]
+
+→ Read task_plan.md          # This brings goals back into attention!
+→ Now make the decision       # Goals are fresh in context
+```
+
+This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a "goal refresh" mechanism.
@@ -0,0 +1,218 @@
+# Reference: Manus Context Engineering Principles
+
+This skill is based on context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
+
+## The 6 Manus Principles
+
+### Principle 1: Design Around KV-Cache
+
+> "KV-cache hit rate is THE single most important metric for production AI agents."
+
+**Statistics:**
+- ~100:1 input-to-output token ratio
+- Cached tokens: $0.30/MTok vs Uncached: $3/MTok
+- 10x cost difference!
+
+**Implementation:**
+- Keep prompt prefixes STABLE (single-token change invalidates cache)
+- NO timestamps in system prompts
+- Make context APPEND-ONLY with deterministic serialization
+
+### Principle 2: Mask, Don't Remove
+
+Don't dynamically remove tools (breaks KV-cache). Use logit masking instead.
+
+**Best Practice:** Use consistent action prefixes (e.g., `browser_`, `shell_`, `file_`) for easier masking.
+
+### Principle 3: Filesystem as External Memory
+
+> "Markdown is my 'working memory' on disk."
+
+**The Formula:**
+```
+Context Window = RAM (volatile, limited)
+Filesystem = Disk (persistent, unlimited)
+```
+
+**Compression Must Be Restorable:**
+- Keep URLs even if web content is dropped
+- Keep file paths when dropping document contents
+- Never lose the pointer to full data
+
+### Principle 4: Manipulate Attention Through Recitation
+
+> "Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."
+
+**Problem:** After ~50 tool calls, models forget original goals ("lost in the middle" effect).
+
+**Solution:** Re-read `task_plan.md` before each decision. Goals appear in the attention window.
+
+```
+Start of context: [Original goal - far away, forgotten]
+...many tool calls...
+End of context: [Recently read task_plan.md - gets ATTENTION!]
+```
+
+### Principle 5: Keep the Wrong Stuff In
+
+> "Leave the wrong turns in the context."
+
+**Why:**
+- Failed actions with stack traces let model implicitly update beliefs
+- Reduces mistake repetition
+- Error recovery is "one of the clearest signals of TRUE agentic behavior"
+
+### Principle 6: Don't Get Few-Shotted
+
+> "Uniformity breeds fragility."
+
+**Problem:** Repetitive action-observation pairs cause drift and hallucination.
+
+**Solution:** Introduce controlled variation:
+- Vary phrasings slightly
+- Don't copy-paste patterns blindly
+- Recalibrate on repetitive tasks
+
+---
+
+## The 3 Context Engineering Strategies
+
+Based on Lance Martin's analysis of Manus architecture.
+
+### Strategy 1: Context Reduction
+
+**Compaction:**
+```
+Tool calls have TWO representations:
+├── FULL: Raw tool content (stored in filesystem)
+└── COMPACT: Reference/file path only
+
+RULES:
+- Apply compaction to STALE (older) tool results
+- Keep RECENT results FULL (to guide next decision)
+```
+
+**Summarization:**
+- Applied when compaction reaches diminishing returns
+- Generated using full tool results
+- Creates standardized summary objects
+
+### Strategy 2: Context Isolation (Multi-Agent)
+
+**Architecture:**
+```
+┌─────────────────────────────────┐
+│         PLANNER AGENT           │
+│  └─ Assigns tasks to sub-agents │
+├─────────────────────────────────┤
+│       KNOWLEDGE MANAGER         │
+│  └─ Reviews conversations       │
+│  └─ Determines filesystem store │
+├─────────────────────────────────┤
+│      EXECUTOR SUB-AGENTS        │
+│  └─ Perform assigned tasks      │
+│  └─ Have own context windows    │
+└─────────────────────────────────┘
+```
+
+**Key Insight:** Manus originally used `todo.md` for task planning but found ~33% of actions were spent updating it. Shifted to dedicated planner agent calling executor sub-agents.
+
+### Strategy 3: Context Offloading
+
+**Tool Design:**
+- Use <20 atomic functions total
+- Store full results in filesystem, not context
+- Use `glob` and `grep` for searching
+- Progressive disclosure: load information only as needed
+
+---
+
+## The Agent Loop
+
+Manus operates in a continuous 7-step loop:
+
+```
+┌─────────────────────────────────────────┐
+│  1. ANALYZE CONTEXT                      │
+│     - Understand user intent             │
+│     - Assess current state               │
+│     - Review recent observations         │
+├─────────────────────────────────────────┤
+│  2. THINK                                │
+│     - Should I update the plan?          │
+│     - What's the next logical action?    │
+│     - Are there blockers?                │
+├─────────────────────────────────────────┤
+│  3. SELECT TOOL                          │
+│     - Choose ONE tool                    │
+│     - Ensure parameters available        │
+├─────────────────────────────────────────┤
+│  4. EXECUTE ACTION                       │
+│     - Tool runs in sandbox               │
+├─────────────────────────────────────────┤
+│  5. RECEIVE OBSERVATION                  │
+│     - Result appended to context         │
+├─────────────────────────────────────────┤
+│  6. ITERATE                              │
+│     - Return to step 1                   │
+│     - Continue until complete            │
+├─────────────────────────────────────────┤
+│  7. DELIVER OUTCOME                      │
+│     - Send results to user               │
+│     - Attach all relevant files          │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## File Types Manus Creates
+
+| File | Purpose | When Created | When Updated |
+|------|---------|--------------|--------------|
+| `task_plan.md` | Phase tracking, progress | Task start | After completing phases |
+| `findings.md` | Discoveries, decisions | After ANY discovery | After viewing images/PDFs |
+| `progress.md` | Session log, what's done | At breakpoints | Throughout session |
+| Code files | Implementation | Before execution | After errors |
+
+---
+
+## Critical Constraints
+
+- **Single-Action Execution:** ONE tool call per turn. No parallel execution.
+- **Plan is Required:** Agent must ALWAYS know: goal, current phase, remaining phases
+- **Files are Memory:** Context = volatile. Filesystem = persistent.
+- **Never Repeat Failures:** If action failed, next action MUST be different
+- **Communication is a Tool:** Message types: `info` (progress), `ask` (blocking), `result` (terminal)
+
+---
+
+## Manus Statistics
+
+| Metric | Value |
+|--------|-------|
+| Average tool calls per task | ~50 |
+| Input-to-output token ratio | 100:1 |
+| Acquisition price | $2 billion |
+| Time to $100M revenue | 8 months |
+| Framework refactors since launch | 5 times |
+
+---
+
+## Key Quotes
+
+> "Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."
+
+> "if action_failed: next_action != same_action. Track what you tried. Mutate the approach."
+
+> "Error recovery is one of the clearest signals of TRUE agentic behavior."
+
+> "KV-cache hit rate is the single most important metric for a production-stage AI agent."
+
+> "Leave the wrong turns in the context."
+
+---
+
+## Source
+
+Based on Manus's official context engineering documentation:
+https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
@@ -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
@@ -2,6 +2,214 @@

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

+## [2.9.0] - 2026-01-26
+
+### Added
+
+- **Clawd CLI Support**
+  - Added Clawd CLI integration for workspace and local skills
+  - Created `.clawd/skills/planning-with-files/` skill bundle
+  - Full templates, scripts, and references included
+  - Cross-platform support (macOS, Linux, Windows)
+  - Added `docs/clawd.md` installation guide
+  - Added Clawd CLI badge to README
+
+### Changed
+
+- Updated plugin.json description to highlight multi-IDE support
+- Added new keywords: clawd, clawdbot, clawdhub, gemini, cursor, continue, multi-ide, agent-skills
+- Now supports 10+ AI coding assistants
+
+---
+
+## [2.8.0] - 2026-01-26
+
+### Added
+
+- **Continue IDE Support** (PR #56 by @murphyXu)
+  - Added Continue.dev integration for VS Code and JetBrains IDEs
+  - Created `.continue/skills/planning-with-files/` skill bundle
+  - Created `.continue/prompts/planning-with-files.prompt` slash command (Chinese)
+  - Added `docs/continue.md` installation guide
+  - Added `scripts/check-continue.sh` validator
+  - Full templates, scripts, and references included
+
+### Fixed
+
+- **POSIX sh Compatibility** (PR #57 by @SaladDay)
+  - Fixed Stop hook failures on Debian/Ubuntu systems using dash as `/bin/sh`
+  - Replaced bash-only syntax (`[[`, `&>`) with POSIX-compliant constructs
+  - Added shell-agnostic Windows detection using `uname -s` and `$OS`
+  - Applied fix to all 5 IDE-specific SKILL.md files
+  - Addresses issue reported by @aqlkzf in #32
+
+### Thanks
+
+- @murphyXu for Continue IDE integration (PR #56)
+- @SaladDay for POSIX sh compatibility fix (PR #57)
+
+---
+
+## [2.7.1] - 2026-01-22
+
+### Fixed
+
+- **Dynamic Python Command Detection** (Issue #41 by @wqh17101)
+  - Replaced hardcoded `python3` with dynamic detection: `$(command -v python3 || command -v python)`
+  - Added Windows PowerShell commands using `python` directly
+  - Fixed in all 5 IDE-specific SKILL.md files (Claude Code, Codex, Cursor, Kilocode, OpenCode)
+  - Resolves compatibility issues on Windows/Anaconda where only `python` exists
+
+### Thanks
+
+- @wqh17101 for reporting and suggesting the fix (Issue #41)
+
+---
+
+## [2.7.0] - 2026-01-22
+
+### Added
+
+- **Gemini CLI Support** (Issue #52)
+  - Native Agent Skills support for Google Gemini CLI v0.23+
+  - Created `.gemini/skills/planning-with-files/` directory structure
+  - SKILL.md formatted for Gemini CLI compatibility
+  - Full templates, scripts, and references included
+  - Added `docs/gemini.md` installation guide
+  - Added Gemini CLI badge to README
+
+### Documentation
+
+- Updated README with Gemini CLI in supported IDEs table
+- Updated file structure diagram
+- Added Gemini CLI to documentation table
+
+### Thanks
+
+- @airclear for requesting Gemini CLI support (Issue #52)
+
+---
+
+## [2.6.0] - 2026-01-22
+
+### Added
+
+- **Start Command** (PR #51 by @Guozihong)
+  - New `/planning-with-files:start` command for easier activation
+  - No longer requires copying skills to `~/.claude/skills/` folder
+  - Works directly after plugin installation
+  - Added `commands/start.md` file
+
+### Fixed
+
+- **Stop Hook Path Resolution** (PR #49 by @fahmyelraie)
+  - Fixed "No such file or directory" error when `CLAUDE_PLUGIN_ROOT` is not set
+  - Added fallback path: `$HOME/.claude/plugins/planning-with-files/scripts`
+  - Made `check-complete.sh` executable (chmod +x)
+  - Applied fix to all IDE-specific SKILL.md files (Codex, Cursor, Kilocode, OpenCode)
+
+### Thanks
+
+- @fahmyelraie for the path resolution fix (PR #49)
+- @Guozihong for the start command feature (PR #51)
+
+---
+
+## [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
@@ -39,6 +39,19 @@ These amazing people have contributed code, documentation, or significant improv
  - Updated documentation for multi-IDE support
  - **Impact:** Windows compatibility and IDE ecosystem expansion

+- **[@SaladDay](https://github.com/SaladDay)** - [PR #57](https://github.com/OthmanAdi/planning-with-files/pull/57)
+  - Fixed Stop hook POSIX sh compatibility for Debian/Ubuntu
+  - Replaced bashisms (`[[`, `&>`) with POSIX constructs
+  - Added shell-agnostic Windows detection using `uname -s`
+  - **Impact:** Fixes hook failures on systems using dash as `/bin/sh`
+
+- **[@murphyXu](https://github.com/murphyXu)** - [PR #56](https://github.com/OthmanAdi/planning-with-files/pull/56)
+  - Added Continue IDE integration (VS Code / JetBrains)
+  - Created `.continue/skills/` and `.continue/prompts/` structure
+  - Added Chinese language slash command prompt
+  - Created `docs/continue.md` installation guide
+  - **Impact:** Expands IDE support to Continue.dev ecosystem
+
 ### Other Contributors

 - **[@tobrun](https://github.com/tobrun)** - [PR #3](https://github.com/OthmanAdi/planning-with-files/pull/3)
@@ -94,4 +107,4 @@ If you've contributed and don't see your name here, please open an issue! We wan

 **Total Contributors:** 10+ and growing!

-*Last updated: January 17, 2026*
+*Last updated: January 26, 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
@@ -15,18 +15,57 @@ A Claude Code plugin that transforms your workflow to use persistent markdown fi
 [![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.2.2-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)
+[![Cursor Skills](https://img.shields.io/badge/Cursor-Skills-purple)](https://docs.cursor.com/context/skills)
+[![Kilocode Skills](https://img.shields.io/badge/Kilocode-Skills-orange)](https://kilo.ai/docs/agent-behavior/skills)
+[![Gemini CLI](https://img.shields.io/badge/Gemini%20CLI-Skills-4285F4)](https://geminicli.com/docs/cli/skills/)
+[![Clawd CLI](https://img.shields.io/badge/Clawd%20CLI-Skills-FF6B6B)](https://docs.clawd.bot/tools/skills)
+[![Version](https://img.shields.io/badge/version-2.9.0-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)
+[![SkillCheck Validated](https://img.shields.io/badge/SkillCheck-Validated-4c1)](https://getskillcheck.com)

 ## Quick Install

 ```bash
-/plugin marketplace add OthmanAdi/planning-with-files
-/plugin install planning-with-files@planning-with-files
+# Install the plugin
+claude plugins install OthmanAdi/planning-with-files
+```
+
+That's it! Now use `/planning-with-files:start` in Claude Code.
+
+**Alternative:** If you want `/planning-with-files` (without `:start`), copy skills to your local folder:
+
+```bash
+# Optional: Copy skills for /planning-with-files command
+cp -r ~/.claude/plugins/cache/planning-with-files/planning-with-files/*/skills/planning-with-files ~/.claude/skills/
+```
+
+**Windows (PowerShell):**
+```powershell
+# Install the plugin
+claude plugins install OthmanAdi/planning-with-files
+
+# Optional: Copy skills for /planning-with-files command
+Copy-Item -Recurse -Path "$env:USERPROFILE\.claude\plugins\cache\planning-with-files\planning-with-files\*\skills\planning-with-files" -Destination "$env:USERPROFILE\.claude\skills\"
 ```

 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 |
+| Gemini CLI | ✅ Full Support | [Gemini Setup](docs/gemini.md) | Agent Skills |
+| Clawd CLI | ✅ Full Support | [Clawd Setup](docs/clawd.md) | Workspace/Local Skills |
+| Cursor | ✅ Full Support | [Cursor Setup](docs/cursor.md) | Skills |
+| Continue | ✅ Full Support | [Continue Setup](docs/continue.md) | Skills + Prompt files |
+| Kilocode | ✅ Full Support | [Kilocode Setup](docs/kilocode.md) | Skills |
+| OpenCode | ✅ Full Support | [OpenCode Setup](docs/opencode.md) | Personal/Project Skill |
+| Codex | ✅ Full Support | [Codex Setup](docs/codex.md) | Personal Skill |
+| FactoryAI Droid | ✅ Full Support | [Factory Setup](docs/factory.md) | Workspace/Personal Skill |
+| Antigravity | ✅ Full Support | [Antigravity Setup](docs/antigravity.md) | Workspace/Personal Skill |
+
+> **Note:** If your IDE uses the legacy Rules system instead of Skills, see the [`legacy-rules-support`](https://github.com/OthmanAdi/planning-with-files/tree/legacy-rules-support) branch.
+
 ## Documentation

 | Document | Description |
@@ -35,15 +74,29 @@ See [docs/installation.md](docs/installation.md) for all installation methods.
 | [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 |
+| [Gemini CLI Setup](docs/gemini.md) | Google Gemini CLI integration guide |
+| [Clawd CLI Setup](docs/clawd.md) | Clawd CLI integration guide |
 | [Cursor Setup](docs/cursor.md) | Cursor IDE-specific instructions |
+| [Continue Setup](docs/continue.md) | Continue integration guide (skills + slash prompt) |
 | [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 |
+| [FactoryAI Droid Setup](docs/factory.md) | FactoryAI Droid integration guide |
+| [Antigravity Setup](docs/antigravity.md) | Antigravity IDE integration guide |

 ## Versions

 | Version | Features | Install |
 |---------|----------|---------|
-| **v2.2.2** (current) | Restored skill activation language | `/plugin install planning-with-files@planning-with-files` |
+| **v2.9.0** (current) | Clawd CLI support | `claude plugins install OthmanAdi/planning-with-files` |
+| **v2.8.0** | Continue IDE support, POSIX sh compatibility fix | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
+| **v2.7.1** | Dynamic Python detection fix | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
+| **v2.7.0** | Gemini CLI support | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
+| **v2.6.0** | Start command (`/planning-with-files:start`), path resolution fix | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
+| **v2.5.0** | Fixed autocomplete - SKILL.md matches Anthropic format | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
+| **v2.3.0** | Codex & OpenCode IDE support | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
+| **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) |
@@ -99,7 +152,7 @@ Once installed, Claude will automatically:
 5. **Log errors** for future reference
 6. **Verify completion** before stopping (via Stop hook)

-Or invoke manually with `/planning-with-files`.
+Or invoke manually with `/planning-with-files:start` (or `/planning-with-files` if you copied skills).

 See [docs/quickstart.md](docs/quickstart.md) for the full 5-step guide.

@@ -153,6 +206,8 @@ This lets you maximize context usage before manually clearing with `/clear`.

 ```
 planning-with-files/
+├── commands/                # Plugin commands
+│   └── start.md             # /planning-with-files:start command
 ├── templates/               # Root-level templates (for CLAUDE_PLUGIN_ROOT)
 ├── scripts/                 # Root-level scripts (for CLAUDE_PLUGIN_ROOT)
 ├── docs/                    # Documentation
@@ -160,9 +215,12 @@ planning-with-files/
 │   ├── quickstart.md
 │   ├── workflow.md
 │   ├── troubleshooting.md
+│   ├── gemini.md            # Gemini CLI setup
 │   ├── cursor.md
 │   ├── windows.md
-│   └── kilocode.md
+│   ├── kilocode.md
+│   ├── codex.md
+│   └── opencode.md
 ├── planning-with-files/     # Plugin skill folder
 │   ├── SKILL.md
 │   ├── templates/
@@ -178,11 +236,18 @@ planning-with-files/
 │           ├── check-complete.sh
 │           ├── init-session.ps1   # Windows PowerShell
 │           └── check-complete.ps1 # Windows PowerShell
+├── .gemini/                 # Gemini CLI skills
+│   └── skills/
+│       └── planning-with-files/
+├── .codex/                  # Codex IDE skills
+│   └── skills/
+├── .opencode/               # OpenCode IDE skills
+│   └── skills/
 ├── .claude-plugin/          # Plugin manifest
-├── .cursor/                 # Cursor rules
-├── .kilocode/               # Kilo Code rules
-│   └── rules/
-│       └── planning-with-files.md
+├── .cursor/                 # Cursor skills
+│   └── skills/
+├── .kilocode/               # Kilo Code skills
+│   └── skills/
 ├── CHANGELOG.md
 ├── LICENSE
 └── README.md
@@ -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,6 @@
+---
+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. Now with automatic session recovery after /clear"
+disable-model-invocation: true
+---
+
+Invoke the planning-with-files:planning-with-files skill and follow it exactly as presented to you
@@ -0,0 +1,265 @@
+# Antigravity IDE Setup
+
+Using planning-with-files with [Google Antigravity](https://antigravity.google/).
+
+---
+
+## Installation
+
+Antigravity auto-discovers skills from `.agent/skills/` directories. Two installation methods:
+
+### Method 1: Workspace Installation (Recommended)
+
+Share the skill with your entire team by adding it to your repository:
+
+```bash
+# In your project repository
+git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files
+
+# Copy the Antigravity skill to your repo
+cp -r /tmp/planning-with-files/.agent .
+
+# Commit to share with team
+git add .agent/
+git commit -m "Add planning-with-files skill for Antigravity"
+git push
+
+# Clean up
+rm -rf /tmp/planning-with-files
+```
+
+Now everyone on your team using Antigravity will have access to the skill!
+
+### Method 2: Personal Installation
+
+Install just for yourself:
+
+```bash
+# Clone the repo
+git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files
+
+# Copy to your personal Antigravity skills folder
+mkdir -p ~/.gemini/antigravity/skills
+cp -r /tmp/planning-with-files/.agent/skills/planning-with-files ~/.gemini/antigravity/skills/
+
+# Clean up
+rm -rf /tmp/planning-with-files
+```
+
+### Verification
+
+Restart your Antigravity session, then the skill will auto-activate when you work on complex tasks.
+
+No slash command needed - Antigravity automatically invokes skills based on your task description!
+
+---
+
+## How It Works
+
+### Auto-Activation
+
+Antigravity scans your task and automatically activates the skill when you:
+- Mention "complex task" or "multi-step project"
+- Request planning or organization
+- Start research tasks
+- Work on projects requiring >5 steps
+
+### Trigger Phrases
+
+Increase auto-activation likelihood by using these phrases:
+- "Create a task plan for..."
+- "This is a multi-step project..."
+- "I need planning for..."
+- "Help me organize this complex task..."
+
+### Example Request
+
+```
+I need to build a REST API with authentication,
+database integration, and comprehensive testing.
+This is a complex multi-step project that will
+require careful planning.
+```
+
+Antigravity will automatically invoke `planning-with-files` and create the three planning files.
+
+---
+
+## The Three Files
+
+Once activated, the skill creates:
+
+| File | Purpose | Location |
+|------|---------|----------|
+| `task_plan.md` | Phases, progress, decisions | Your project root |
+| `findings.md` | Research, discoveries | Your project root |
+| `progress.md` | Session log, test results | Your project root |
+
+### Templates
+
+The skill includes starter templates in `.agent/skills/planning-with-files/references/`:
+- `task_plan.md` — Phase tracking template
+- `findings.md` — Research storage template
+- `progress.md` — Session logging template
+
+---
+
+## Usage Pattern
+
+### 1. Start Complex Task
+
+Describe your task with complexity indicators:
+
+```
+I'm building a user authentication system.
+This is a multi-phase project requiring database
+setup, API endpoints, testing, and documentation.
+```
+
+### 2. Skill Auto-Activates
+
+Antigravity invokes `planning-with-files` and creates the planning files.
+
+### 3. Work Through Phases
+
+The AI will:
+- ✅ Create `task_plan.md` with phases
+- ✅ Update progress as work completes
+- ✅ Store research in `findings.md`
+- ✅ Log actions in `progress.md`
+- ✅ Re-read plans before major decisions
+
+### 4. Track Everything
+
+All important information gets written to disk, not lost in context window.
+
+---
+
+## Skill Features
+
+### The 3-Strike Error Protocol
+
+When errors occur, the AI:
+1. **Attempt 1:** Diagnose and fix
+2. **Attempt 2:** Try alternative approach
+3. **Attempt 3:** Broader rethink
+4. **After 3 failures:** Escalate to you
+
+### The 2-Action Rule
+
+After every 2 search/view operations, findings are saved to `findings.md`.
+
+Prevents losing visual/multimodal information.
+
+### Read Before Decide
+
+Before major decisions, the AI re-reads planning files to refresh goals.
+
+Prevents goal drift in long sessions.
+
+---
+
+## Team Workflow
+
+### Workspace Skills (Recommended)
+
+With workspace installation (`.agent/skills/`):
+- ✅ Everyone on team has the skill
+- ✅ Consistent planning across projects
+- ✅ Version controlled with your repo
+- ✅ Changes sync via git
+
+### Personal Skills
+
+With personal installation (`~/.gemini/antigravity/skills/`):
+- ✅ Use across all your projects
+- ✅ Keep it even if you switch teams
+- ❌ Not shared with teammates
+
+---
+
+## Why This Works
+
+This pattern is why Manus AI (acquired by Meta for $2 billion) succeeded:
+
+> "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
+
+**Key insight:** Context window = RAM (volatile). Filesystem = Disk (persistent).
+
+Write important information to disk, not context.
+
+---
+
+## Troubleshooting
+
+### Skill Not Activating?
+
+1. **Add trigger phrases:** Use "complex task", "multi-step", "planning" in your request
+2. **Be explicit:** Mention number of phases or complexity
+3. **Restart Antigravity:** Agent rescans skills on restart
+
+### Files Not Created?
+
+Check:
+- Current directory is writable
+- No file permission issues
+- Agent has file system access
+
+### Need Templates?
+
+Templates are in:
+- **Workspace:** `.agent/skills/planning-with-files/references/`
+- **Personal:** `~/.gemini/antigravity/skills/planning-with-files/references/`
+
+Copy them to your project root and customize.
+
+---
+
+## Advanced: Customization
+
+### Modify the Skill
+
+Edit `.agent/skills/planning-with-files/SKILL.md` to customize:
+- Change trigger phrases in description
+- Adjust planning patterns
+- Add team-specific rules
+
+### Add Custom Templates
+
+Place custom templates in:
+```
+.agent/skills/planning-with-files/references/
+```
+
+Antigravity will reference them automatically.
+
+---
+
+## Agent Skills Standard
+
+This skill follows the [Agent Skills Specification](https://agentskills.io/specification), an open standard for AI coding assistants.
+
+The same skill format works across:
+- Google Antigravity
+- Claude Code
+- Cursor
+- And other Agent Skills-compatible IDEs
+
+---
+
+## Support
+
+- **GitHub Issues:** https://github.com/OthmanAdi/planning-with-files/issues
+- **Antigravity Docs:** https://antigravity.google/docs/skills
+- **Agent Skills Spec:** https://agentskills.io/specification
+- **Author:** [@OthmanAdi](https://github.com/OthmanAdi)
+
+---
+
+## See Also
+
+- [Quick Start Guide](quickstart.md)
+- [Workflow Diagram](workflow.md)
+- [Manus Principles](../skills/planning-with-files/reference.md)
+- [Real Examples](../skills/planning-with-files/examples.md)
@@ -0,0 +1,128 @@
+# Clawd CLI Setup
+
+How to use planning-with-files with [Clawd CLI](https://clawd.bot).
+
+---
+
+## What This Integration Adds
+
+- Workspace skill: `.clawd/skills/planning-with-files/`
+- Full templates, scripts, and reference documentation
+- Cross-platform support (macOS, Linux, Windows)
+
+Clawd CLI supports three skill locations (in precedence order):
+1. **Workspace skills** (highest priority): `<workspace>/skills/`
+2. **Managed/local skills**: `~/.clawdbot/skills/`
+3. **Bundled skills** (lowest priority): shipped with install
+
+---
+
+## Installation (Workspace, recommended)
+
+Copy the skill to your project:
+
+```bash
+# Clone the repo
+git clone https://github.com/OthmanAdi/planning-with-files.git
+
+# Copy the Clawd skill to your workspace
+cp -r planning-with-files/.clawd/skills/planning-with-files skills/
+
+# Clean up
+rm -rf planning-with-files
+```
+
+---
+
+## Installation (Global)
+
+Install to your local Clawd skills directory:
+
+```bash
+# Clone the repo
+git clone https://github.com/OthmanAdi/planning-with-files.git
+
+# Copy to global Clawd skills
+mkdir -p ~/.clawdbot/skills
+cp -r planning-with-files/.clawd/skills/planning-with-files ~/.clawdbot/skills/
+
+# Clean up
+rm -rf planning-with-files
+```
+
+---
+
+## Installation (ClawdHub)
+
+If available on ClawdHub:
+
+```bash
+clawdhub install planning-with-files
+```
+
+---
+
+## Verify Installation
+
+```bash
+# List all skills
+clawdbot skills list
+
+# Check if planning-with-files is loaded
+clawdbot skills info planning-with-files
+```
+
+---
+
+## Usage
+
+1. Start a Clawd session in your project directory
+2. For complex tasks, the skill will guide you to create:
+   - `task_plan.md` — Phase tracking and decisions
+   - `findings.md` — Research and discoveries
+   - `progress.md` — Session log and test results
+3. Follow the workflow: plan first, update after each phase
+
+---
+
+## Helper Scripts
+
+From your project root:
+
+```bash
+# Initialize all planning files
+bash skills/planning-with-files/scripts/init-session.sh
+
+# Or on Windows PowerShell
+powershell -ExecutionPolicy Bypass -File skills/planning-with-files/scripts/init-session.ps1
+
+# Verify all phases are complete
+bash skills/planning-with-files/scripts/check-complete.sh
+```
+
+---
+
+## Configuration (Optional)
+
+Configure the skill in `~/.clawdbot/clawdbot.json`:
+
+```json5
+{
+  skills: {
+    entries: {
+      "planning-with-files": {
+        enabled: true
+      }
+    }
+  }
+}
+```
+
+---
+
+## Notes
+
+- Clawd CLI snapshots eligible skills when a session starts
+- Workspace skills take precedence over bundled skills
+- The skill works on all platforms: macOS, Linux, and Windows
+- Planning files are tool-agnostic and work across Claude Code, Cursor, and other IDEs
@@ -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,74 @@
+# Continue Setup
+
+How to use planning-with-files with Continue (VS Code / JetBrains).
+
+---
+
+## What This Integration Adds
+
+- Project-level skill: `.continue/skills/planning-with-files/`
+- Project-level slash command prompt: `.continue/prompts/planning-with-files.prompt` (Markdown)
+
+Continue supports both **project-level** (`<repo>/.continue/...`) and **global** (`~/.continue/...`) locations.
+
+---
+
+## Installation (Project-level, recommended)
+
+In your project root:
+
+```bash
+git clone https://github.com/OthmanAdi/planning-with-files.git
+cp -r planning-with-files/.continue .continue
+```
+
+Restart Continue (or reload the IDE) so it picks up the new files.
+
+---
+
+## Installation (Global)
+
+Copy the skill and prompt into your global Continue directory:
+
+```bash
+git clone https://github.com/OthmanAdi/planning-with-files.git
+mkdir -p ~/.continue/skills ~/.continue/prompts
+cp -r planning-with-files/.continue/skills/planning-with-files ~/.continue/skills/
+cp planning-with-files/.continue/prompts/planning-with-files.prompt ~/.continue/prompts/
+```
+
+Restart Continue (or reload the IDE) so it picks up the new files.
+
+---
+
+## Usage
+
+1. In Continue chat, run:
+   - `/planning-with-files`
+2. The prompt will guide you to:
+   - Ensure `task_plan.md`, `findings.md`, `progress.md` exist in your repo root
+   - Update these files throughout the task
+
+---
+
+## Helper Scripts (Optional)
+
+From your project root:
+
+```bash
+# Create task_plan.md / findings.md / progress.md (if missing)
+bash .continue/skills/planning-with-files/scripts/init-session.sh
+
+# Verify all phases marked complete (expects task_plan.md format)
+bash .continue/skills/planning-with-files/scripts/check-complete.sh
+
+# Recover unsynced context from last Claude Code session (if you also use Claude Code)
+python3 .continue/skills/planning-with-files/scripts/session-catchup.py "$(pwd)"
+```
+
+---
+
+## Notes & Limitations
+
+- Continue does not run Claude Code hooks (PreToolUse/PostToolUse/Stop). The workflow is manual: re-read `task_plan.md` before decisions and update it after each phase.
+- The three planning files are tool-agnostic and can be used across Claude Code, Cursor, Gemini CLI, and Continue.
@@ -0,0 +1,252 @@
+# FactoryAI Droid Setup
+
+Using planning-with-files with [FactoryAI Droid](https://docs.factory.ai/).
+
+---
+
+## Installation
+
+FactoryAI Droid auto-discovers skills from `.factory/skills/` directories. Two installation methods:
+
+### Method 1: Workspace Installation (Recommended)
+
+Share the skill with your entire team by adding it to your repository:
+
+```bash
+# In your project repository
+git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files
+
+# Copy the Factory skill to your repo
+cp -r /tmp/planning-with-files/.factory .
+
+# Commit to share with team
+git add .factory/
+git commit -m "Add planning-with-files skill for Factory Droid"
+git push
+
+# Clean up
+rm -rf /tmp/planning-with-files
+```
+
+Now everyone on your team using Factory Droid will have access to the skill!
+
+### Method 2: Personal Installation
+
+Install just for yourself:
+
+```bash
+# Clone the repo
+git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files
+
+# Copy to your personal Factory skills folder
+mkdir -p ~/.factory/skills
+cp -r /tmp/planning-with-files/.factory/skills/planning-with-files ~/.factory/skills/
+
+# Clean up
+rm -rf /tmp/planning-with-files
+```
+
+### Verification
+
+Restart your Factory Droid session, then the skill will auto-activate when you work on complex tasks.
+
+No slash command needed - Factory Droid automatically invokes skills based on your task description!
+
+---
+
+## How It Works
+
+### Auto-Activation
+
+Factory Droid scans your task and automatically activates the skill when you:
+- Mention "complex task" or "multi-step project"
+- Request planning or organization
+- Start research tasks
+- Work on projects requiring >5 steps
+
+### Trigger Phrases
+
+Increase auto-activation likelihood by using these phrases:
+- "Create a task plan for..."
+- "This is a multi-step project..."
+- "I need planning for..."
+- "Help me organize this complex task..."
+
+### Example Request
+
+```
+I need to build a REST API with authentication,
+database integration, and comprehensive testing.
+This is a complex multi-step project that will
+require careful planning.
+```
+
+Factory Droid will automatically invoke `planning-with-files` and create the three planning files.
+
+---
+
+## The Three Files
+
+Once activated, the skill creates:
+
+| File | Purpose | Location |
+|------|---------|----------|
+| `task_plan.md` | Phases, progress, decisions | Your project root |
+| `findings.md` | Research, discoveries | Your project root |
+| `progress.md` | Session log, test results | Your project root |
+
+### Templates
+
+The skill includes starter templates in `.factory/skills/planning-with-files/templates/`:
+- `task_plan.md` — Phase tracking template
+- `findings.md` — Research storage template
+- `progress.md` — Session logging template
+
+---
+
+## Usage Pattern
+
+### 1. Start Complex Task
+
+Describe your task with complexity indicators:
+
+```
+I'm building a user authentication system.
+This is a multi-phase project requiring database
+setup, API endpoints, testing, and documentation.
+```
+
+### 2. Skill Auto-Activates
+
+Factory Droid invokes `planning-with-files` and creates the planning files.
+
+### 3. Work Through Phases
+
+The AI will:
+- ✅ Create `task_plan.md` with phases
+- ✅ Update progress as work completes
+- ✅ Store research in `findings.md`
+- ✅ Log actions in `progress.md`
+- ✅ Re-read plans before major decisions
+
+### 4. Track Everything
+
+All important information gets written to disk, not lost in context window.
+
+---
+
+## Skill Features
+
+### The 3-Strike Error Protocol
+
+When errors occur, the AI:
+1. **Attempt 1:** Diagnose and fix
+2. **Attempt 2:** Try alternative approach
+3. **Attempt 3:** Broader rethink
+4. **After 3 failures:** Escalate to you
+
+### The 2-Action Rule
+
+After every 2 search/view operations, findings are saved to `findings.md`.
+
+Prevents losing visual/multimodal information.
+
+### Read Before Decide
+
+Before major decisions, the AI re-reads planning files to refresh goals.
+
+Prevents goal drift in long sessions.
+
+---
+
+## Team Workflow
+
+### Workspace Skills (Recommended)
+
+With workspace installation (`.factory/skills/`):
+- ✅ Everyone on team has the skill
+- ✅ Consistent planning across projects
+- ✅ Version controlled with your repo
+- ✅ Changes sync via git
+
+### Personal Skills
+
+With personal installation (`~/.factory/skills/`):
+- ✅ Use across all your projects
+- ✅ Keep it even if you switch teams
+- ❌ Not shared with teammates
+
+---
+
+## Why This Works
+
+This pattern is why Manus AI (acquired by Meta for $2 billion) succeeded:
+
+> "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
+
+**Key insight:** Context window = RAM (volatile). Filesystem = Disk (persistent).
+
+Write important information to disk, not context.
+
+---
+
+## Troubleshooting
+
+### Skill Not Activating?
+
+1. **Add trigger phrases:** Use "complex task", "multi-step", "planning" in your request
+2. **Be explicit:** Mention number of phases or complexity
+3. **Restart Droid:** Factory Droid rescans skills on restart
+
+### Files Not Created?
+
+Check:
+- Current directory is writable
+- No file permission issues
+- Droid has file system access
+
+### Need Templates?
+
+Templates are in:
+- **Workspace:** `.factory/skills/planning-with-files/templates/`
+- **Personal:** `~/.factory/skills/planning-with-files/templates/`
+
+Copy them to your project root and customize.
+
+---
+
+## Advanced: Customization
+
+### Modify the Skill
+
+Edit `.factory/skills/planning-with-files/SKILL.md` to customize:
+- Change trigger phrases in description
+- Adjust planning patterns
+- Add team-specific rules
+
+### Add Custom Templates
+
+Place custom templates in:
+```
+.factory/skills/planning-with-files/templates/
+```
+
+Factory Droid will reference them automatically.
+
+---
+
+## Support
+
+- **GitHub Issues:** https://github.com/OthmanAdi/planning-with-files/issues
+- **Factory Docs:** https://docs.factory.ai/cli/configuration/skills
+- **Author:** [@OthmanAdi](https://github.com/OthmanAdi)
+
+---
+
+## See Also
+
+- [Quick Start Guide](quickstart.md)
+- [Workflow Diagram](workflow.md)
+- [Manus Principles](../skills/planning-with-files/references.md)
+- [Real Examples](../skills/planning-with-files/examples.md)
@@ -0,0 +1,176 @@
+# Gemini CLI Setup
+
+This guide explains how to install and use planning-with-files with [Gemini CLI](https://geminicli.com/).
+
+## Prerequisites
+
+- Gemini CLI v0.23 or later
+- Agent Skills enabled in settings
+
+## Enable Agent Skills
+
+Agent Skills is an experimental feature. Enable it first:
+
+```bash
+# Open settings
+gemini /settings
+
+# Search for "Skills" → Toggle "Agent Skills" to true → Press Esc to save
+```
+
+Or edit `~/.gemini/settings.json`:
+
+```json
+{
+  "experimental": {
+    "skills": true
+  }
+}
+```
+
+## Installation Methods
+
+### Method 1: Install from GitHub (Recommended)
+
+```bash
+gemini skills install https://github.com/OthmanAdi/planning-with-files --path .gemini/skills/planning-with-files
+```
+
+### Method 2: Manual Installation (User-level)
+
+```bash
+# Clone the repository
+git clone https://github.com/OthmanAdi/planning-with-files.git
+
+# Copy to Gemini skills folder
+cp -r planning-with-files/.gemini/skills/planning-with-files ~/.gemini/skills/
+```
+
+### Method 3: Manual Installation (Workspace-level)
+
+For project-specific installation:
+
+```bash
+# In your project directory
+mkdir -p .gemini/skills
+
+# Copy skill
+cp -r /path/to/planning-with-files/.gemini/skills/planning-with-files .gemini/skills/
+```
+
+## Verify Installation
+
+```bash
+# List all skills
+gemini skills list
+
+# Should show:
+# - planning-with-files: Implements Manus-style file-based planning...
+```
+
+Or in an interactive session:
+
+```
+/skills list
+```
+
+## Skill Discovery Tiers
+
+Skills are loaded from three locations with this precedence:
+
+| Tier | Location | Scope |
+|------|----------|-------|
+| Workspace | `.gemini/skills/` | Project-specific (highest priority) |
+| User | `~/.gemini/skills/` | All projects |
+| Extension | Bundled with extensions | Lowest priority |
+
+Higher-precedence locations override lower ones when names conflict.
+
+## Usage
+
+### Automatic Activation
+
+Gemini will automatically detect when to use this skill based on the task description. For complex multi-step tasks, it will prompt you:
+
+```
+Gemini wants to activate skill: planning-with-files
+Purpose: Implements Manus-style file-based planning for complex tasks
+Allow? [y/n]
+```
+
+### Manual Activation
+
+You can also manually enable/disable skills:
+
+```
+/skills enable planning-with-files
+/skills disable planning-with-files
+/skills reload
+```
+
+## How It Works
+
+1. **Session Start**: Gemini loads skill names and descriptions
+2. **Task Detection**: When you describe a complex task, Gemini matches it to the skill
+3. **Activation Prompt**: You approve the skill activation
+4. **Instructions Loaded**: Full SKILL.md content is added to context
+5. **Execution**: Gemini follows the planning workflow
+
+## Skill Structure
+
+```
+.gemini/skills/planning-with-files/
+├── SKILL.md              # Main skill instructions
+├── templates/
+│   ├── task_plan.md      # Phase tracking template
+│   ├── findings.md       # Research storage template
+│   └── progress.md       # Session logging template
+├── scripts/
+│   ├── init-session.sh   # Initialize planning files
+│   ├── check-complete.sh # Verify completion
+│   ├── init-session.ps1  # Windows PowerShell version
+│   └── check-complete.ps1
+└── references/
+    ├── reference.md      # Manus principles
+    └── examples.md       # Real-world examples
+```
+
+## Sharing Skills with Claude Code
+
+If you use both Gemini CLI and Claude Code, you can share skills:
+
+```bash
+# Create symlink (Linux/macOS)
+ln -s ~/.claude/skills ~/.gemini/skills
+
+# Or copy between them
+cp -r ~/.claude/skills/planning-with-files ~/.gemini/skills/
+```
+
+## Troubleshooting
+
+### Skill not appearing
+
+1. Check skills are enabled: `gemini /settings` → Search "Skills"
+2. Verify installation: `gemini skills list`
+3. Reload skills: `/skills reload`
+
+### Skill not activating
+
+- Make sure your task description matches the skill's purpose
+- Try manually enabling: `/skills enable planning-with-files`
+
+### Path issues on Windows
+
+Use PowerShell:
+
+```powershell
+# Copy to user skills
+Copy-Item -Recurse -Path ".\.gemini\skills\planning-with-files" -Destination "$env:USERPROFILE\.gemini\skills\"
+```
+
+## Resources
+
+- [Gemini CLI Documentation](https://geminicli.com/docs/)
+- [Agent Skills Guide](https://geminicli.com/docs/cli/skills/)
+- [Skills Tutorial](https://geminicli.com/docs/cli/tutorials/skills-getting-started/)
@@ -153,6 +153,14 @@ See [docs/windows.md](windows.md) for Windows-specific installation notes.

 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?
@@ -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,34 @@
+#!/bin/bash
+
+set -euo pipefail
+
+missing=0
+
+require_file() {
+  local path="$1"
+  if [ ! -f "$path" ]; then
+    echo "Missing: $path"
+    missing=1
+  fi
+}
+
+require_file ".continue/prompts/planning-with-files.prompt"
+require_file ".continue/skills/planning-with-files/SKILL.md"
+require_file ".continue/skills/planning-with-files/examples.md"
+require_file ".continue/skills/planning-with-files/reference.md"
+require_file ".continue/skills/planning-with-files/scripts/init-session.sh"
+require_file ".continue/skills/planning-with-files/scripts/init-session.ps1"
+require_file ".continue/skills/planning-with-files/scripts/check-complete.sh"
+require_file ".continue/skills/planning-with-files/scripts/check-complete.ps1"
+require_file ".continue/skills/planning-with-files/scripts/session-catchup.py"
+
+if [ "$missing" -ne 0 ]; then
+  exit 1
+fi
+
+case ".continue/prompts/planning-with-files.prompt" in
+  *.prompt) ;;
+  *) echo "Prompt file must end with .prompt"; exit 1 ;;
+esac
+
+echo "Continue integration files look OK."
@@ -2,8 +2,9 @@
 """
 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.
+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]
 """
@@ -13,7 +14,6 @@ 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']

@@ -34,106 +34,147 @@ def get_sessions_sorted(project_dir: Path) -> List[Path]:
    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 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 find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
+def scan_for_planning_update(session_file: Path) -> Tuple[int, Optional[str]]:
    """
-    Find the last time a planning file was written/edited.
-    Returns (line_number, filename) or (-1, None) if not found.
+    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

-    for msg in messages:
-        msg_type = msg.get('type')
+    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

-        if msg_type == 'assistant':
-            content = msg.get('message', {}).get('content', [])
-            if isinstance(content, list):
-                for item in content:
-                    if item.get('type') == 'tool_use':
+                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', '')
-                        tool_input = item.get('input', {})
+                        if tool_name not in ('Write', 'Edit'):
+                            continue

-                        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
+                        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_after(messages: List[Dict], after_line: int) -> List[Dict]:
-    """Extract conversation messages after a certain line number."""
+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 = []
-    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')):
+    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
-                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 = []
+                try:
+                    msg = json.loads(line)
+                except json.JSONDecodeError:
+                    continue

-            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}")
+                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:
-                            tool_uses.append(f"{tool_name}")
+                            content = ''

-            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']
-                })
+                    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

@@ -142,53 +183,82 @@ 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:
+    if len(sessions) < 2:
        return

-    # Find a substantial previous session
-    target_session = None
-    for session in sessions:
-        if session.stat().st_size > 5000:
-            target_session = session
+    # 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 target_session:
+    if not update_session:
+        # No planning file updates found in any previous session
        return

-    messages = parse_session_messages(target_session)
-    last_update_line, last_update_file = find_last_planning_update(messages)
+    # Collect ALL messages from the update point forward, across all sessions
+    all_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)
+    # 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)

-    if not messages_after:
+    # 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"Previous session: {target_session.stem}")
+    print(f"Last planning update: {update_file} in session {update_session.stem[:8]}...")

-    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")
+    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 ---")
-    for msg in messages_after[-15:]:  # Last 15 messages
+
+    # 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:
@@ -1,6 +1,6 @@
 ---
 name: planning-with-files
-version: "2.2.2"
+version: "2.9.0"
 description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls. Now with automatic session recovery after /clear.
 user-invocable: true
 allowed-tools:
@@ -27,10 +27,29 @@ hooks:
    - hooks:
        - type: command
          command: |
-            if command -v pwsh &> /dev/null && [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" || "$OS" == "Windows_NT" ]]; then
-              pwsh -ExecutionPolicy Bypass -File "${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.ps1" 2>/dev/null || powershell -ExecutionPolicy Bypass -File "${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.ps1" 2>/dev/null || bash "${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.sh"
+            SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files}/scripts"
+
+            IS_WINDOWS=0
+            if [ "${OS-}" = "Windows_NT" ]; then
+              IS_WINDOWS=1
            else
-              bash "${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.sh"
+              UNAME_S="$(uname -s 2>/dev/null || echo '')"
+              case "$UNAME_S" in
+                CYGWIN*|MINGW*|MSYS*) IS_WINDOWS=1 ;;
+              esac
+            fi
+
+            if [ "$IS_WINDOWS" -eq 1 ]; then
+              if command -v pwsh >/dev/null 2>&1; then
+                pwsh -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
+                powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
+                sh "$SCRIPT_DIR/check-complete.sh"
+              else
+                powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
+                sh "$SCRIPT_DIR/check-complete.sh"
+              fi
+            else
+              sh "$SCRIPT_DIR/check-complete.sh"
            fi
 ---

@@ -43,7 +62,13 @@ Work like Manus: Use persistent markdown files as your "working memory on disk."
 **Before starting work**, check for unsynced context from a previous session:

 ```bash
-python3 ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
+# Linux/macOS
+$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
+```
+
+```powershell
+# Windows PowerShell
+& (Get-Command python -ErrorAction SilentlyContinue).Source "$env:USERPROFILE\.claude\skills\planning-with-files\scripts\session-catchup.py" (Get-Location)
 ```

 If catchup report shows unsynced context:
Author	SHA1	Message	Date
OthmanAdi	28c255f774	Add Clawd CLI support (v2.9.0) - Add .clawd/skills/planning-with-files/ skill bundle - Add docs/clawd.md installation guide - Update README with Clawd badge and documentation - Update plugin.json with new keywords for discoverability - Update all SKILL.md versions to 2.9.0 - Now supports 10+ AI coding assistants	2026-01-26 01:14:37 +01:00
OthmanAdi	3dc1601319	Release v2.8.0 - Continue IDE support & POSIX sh fix - Add Continue IDE integration (PR #56 by @murphyXu) - Fix POSIX sh compatibility for Debian/Ubuntu (PR #57 by @SaladDay) - Update all SKILL.md versions to 2.8.0 - Update CONTRIBUTORS.md with new contributors - Update CHANGELOG.md with v2.8.0 release notes	2026-01-26 01:05:01 +01:00
Ahmad Othman Ammar Adi.	65dcd7e956	Merge pull request #56 from murphyXu/feat/continue-integration Merging Continue IDE integration. Thank you @murphyXu for this contribution!	2026-01-26 01:01:16 +01:00
Ahmad Othman Ammar Adi.	b16830f113	Merge pull request #57 from SaladDay/fix/stop-hook-posix-sh Merging POSIX sh compatibility fix. Thank you @SaladDay for this contribution!	2026-01-26 01:01:03 +01:00
saladday	1c2dc407d1	Fix Stop hook for POSIX sh (dash)	2026-01-25 01:05:04 +08:00
mannaxu	4271a5425b	Add Continue integration (skills + prompt) - Add .continue/skills planning-with-files bundle - Add .continue/prompts slash command (.prompt Markdown) - Add docs/continue.md and README entry - Add scripts/check-continue.sh validator	2026-01-24 01:55:49 +08:00
OthmanAdi	47dcfbb3f1	Fix dynamic Python command detection (v2.7.1) - Replaced hardcoded python3 with: $(command -v python3 \|\| command -v python) - Added Windows PowerShell commands using python directly - Fixed in all 5 IDE-specific SKILL.md files Fixes #41	2026-01-22 14:37:09 +01:00
OthmanAdi	a210eb6b4f	Add Gemini CLI support (v2.7.0) - Added .gemini/skills/planning-with-files/ with full skill structure - Created SKILL.md formatted for Gemini CLI Agent Skills - Included templates, scripts, and references - Added docs/gemini.md installation guide - Updated README with Gemini CLI in supported IDEs - Added Gemini CLI badge Closes #52	2026-01-22 14:33:09 +01:00
OthmanAdi	aff7ee924a	Release v2.6.0 - Start command and path resolution fix - Added /planning-with-files:start command (PR #51 by @Guozihong) - Fixed Stop hook path when CLAUDE_PLUGIN_ROOT is not set (PR #49 by @fahmyelraie) - Updated README with simplified installation - Updated version to 2.6.0	2026-01-22 13:54:53 +01:00
Ahmad Othman Ammar Adi.	6765b507a5	Add the start command (#51 ) Add the start command	2026-01-22 13:52:47 +01:00
Ahmad Othman Ammar Adi.	3d2661ec3b	Fix Stop hook path resolution when CLAUDE_PLUGIN_ROOT is not set (#49 ) Fix Stop hook path resolution when CLAUDE_PLUGIN_ROOT is not set	2026-01-22 13:52:36 +01:00
guozihong	23fb821571	Add the start command, which can be used through /planning-with-files:start in claudecode without the need to copy skills	2026-01-22 17:47:21 +08:00
fahmyelraie	d019234778	Fix Stop hook path resolution when CLAUDE_PLUGIN_ROOT is not set The Stop hook was failing with "No such file or directory" error when CLAUDE_PLUGIN_ROOT was not properly set in the environment, resulting in the script path resolving to "/scripts/check-complete.sh" instead of the full path. Changes: - Add SCRIPT_DIR variable with fallback to explicit path - Use $HOME/.claude/plugins/planning-with-files/scripts as fallback when CLAUDE_PLUGIN_ROOT is not set - Make check-complete.sh executable (chmod +x) - Apply fix to both Unix and Windows paths in the hook command This ensures the Stop hook runs successfully even when CLAUDE_PLUGIN_ROOT is not available in the shell environment. Fixes the error: "bash: /scripts/check-complete.sh: No such file or directory"	2026-01-21 13:30:59 -08:00
Olga Safonova	207f807434	Add SkillCheck validation badge (#46 ) Your skill passed SkillCheck validation against the agentskills specification. Validation details: - Status: PASS - Passed checks: 49 - Only 1 minor suggestion (cosmetic) Badge links to getskillcheck.com for verification. authored-by: Olga Safonova <olgasafonova@Olgas-MacBook-Pro.local>	2026-01-21 18:25:46 +01:00
OthmanAdi	9442a6ecf5	Add proper Skills support for OpenCode and Codex, update badges - Created .opencode/skills/planning-with-files/ with SKILL.md, templates, docs - Created .codex/skills/planning-with-files/ with proper structure: - SKILL.md at root - scripts/ folder with all scripts - references/ folder with reference.md and examples.md - assets/ folder with templates - Removed old INSTALL.md files (were just instructions, not skills) - Updated README badges: Cursor Rules -> Cursor Skills - Added Kilocode Skills badge	2026-01-20 18:12:55 +01:00
OthmanAdi	e0845fa57f	Move Cursor and Kilocode from Rules to Skills format - Moved .cursor/rules/ to .cursor/skills/ (proper Skills format) - Moved .kilocode/rules/ to .kilocode/skills/ (proper Skills format) - Both now use SKILL.md with full content (223 lines) - Added templates, examples.md, and reference.md to both - Updated README: Rules -> Skills for Cursor and Kilocode - Added note about legacy-rules-support branch for users on Rules system	2026-01-20 18:03:33 +01:00
OthmanAdi	a58cc049d4	Update Cursor and Kilocode rules with session recovery and file location guidance - Added session recovery section with manual git-based approach - Added file location guidance (create in project root, not .cursor/.kilocode) - Adapted content for IDEs without plugin script access	2026-01-20 17:56:42 +01:00
OthmanAdi	cd0fc7c915	Add Antigravity IDE support - Created .agent/skills/planning-with-files/ directory structure - Added SKILL.md following Agent Skills Specification - Copied templates to references/ folder (Antigravity convention) - Copied references.md and examples.md for documentation - Created comprehensive docs/antigravity.md installation guide - Added Antigravity to README.md supported IDEs table - Closes #40	2026-01-20 17:36:42 +01:00
OthmanAdiandClaude Sonnet 4.5	2ed7ea7f91	Revert SKILL.md to v2.4.1 - restore full content - Restored all body content (session catchup, decision matrices, detailed protocols) - Restored all header fields (version, hooks, user-invocable, allowed-tools) - File restored from 113 lines to 223 lines - The autocomplete fix was installation location, not SKILL.md format Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>	2026-01-20 12:40:28 +01:00
OthmanAdiandClaude Sonnet 4.5	97a85b6272	Add FactoryAI Droid support - Created .factory/skills/planning-with-files/ directory structure - Added SKILL.md with Factory-compatible format (name, description only) - Copied templates (task_plan.md, findings.md, progress.md) - Copied references.md and examples.md for documentation - Created comprehensive docs/factory.md installation guide - Added FactoryAI Droid to README.md supported IDEs table - Closes #44 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>	2026-01-20 12:31:53 +01:00
OthmanAdi	6df713fc7d	docs: update install instructions with skills folder copy step (fixes autocomplete)	2026-01-20 12:22:34 +01:00
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