admin/SuperCharged-Claude-Code-Upgrade
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

SuperCharge Claude Code v1.0.0 - Complete Customization Package

Browse Source 
Features:
- 30+ Custom Skills (cognitive, development, UI/UX, autonomous agents)
- RalphLoop autonomous agent integration
- Multi-AI consultation (Qwen)
- Agent management system with sync capabilities
- Custom hooks for session management
- MCP servers integration
- Plugin marketplace setup
- Comprehensive installation script

Components:
- Skills: always-use-superpowers, ralph, brainstorming, ui-ux-pro-max, etc.
- Agents: 100+ agents across engineering, marketing, product, etc.
- Hooks: session-start-superpowers, qwen-consult, ralph-auto-trigger
- Commands: /brainstorm, /write-plan, /execute-plan
- MCP Servers: zai-mcp-server, web-search-prime, web-reader, zread
- Binaries: ralphloop wrapper

Installation: ./supercharge.sh
This commit is contained in:
uroma
2026-01-22 15:35:55 +00:00
Unverified
commit 7a491b1548
1013 changed files with 170070 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

337
skills/planning-with-files/CHANGELOG.md Normal file
View File

@@ -0,0 +1,337 @@
# Changelog
All notable changes to this project will be documented in this file.
## [2.3.0] - 2026-01-17
### Added
- **Codex IDE Support**
- Created `.codex/INSTALL.md` with installation instructions
- Skills install to `~/.codex/skills/planning-with-files/`
- Works with obra/superpowers or standalone
- Added `docs/codex.md` for user documentation
- Based on analysis of obra/superpowers Codex implementation
- **OpenCode IDE Support** (Issue #27)
- Created `.opencode/INSTALL.md` with installation instructions
- Global installation: `~/.config/opencode/skills/planning-with-files/`
- Project installation: `.opencode/skills/planning-with-files/`
- Works with obra/superpowers plugin or standalone
- oh-my-opencode compatibility documented
- Added `docs/opencode.md` for user documentation
- Based on analysis of obra/superpowers OpenCode plugin
### Changed
- Updated README.md with Supported IDEs table
- Updated README.md file structure diagram
- Updated docs/installation.md with Codex and OpenCode sections
- Version bump to 2.3.0
### Documentation
- Added Codex and OpenCode to IDE support table in README
- Created comprehensive installation guides for both IDEs
- Documented skill priority system for OpenCode
- Documented integration with superpowers ecosystem
### Research
This implementation is based on real analysis of:
- [obra/superpowers](https://github.com/obra/superpowers) repository
- Codex skill system and CLI architecture
- OpenCode plugin system and skill resolution
- Skill priority and override mechanisms
### Thanks
- @Realtyxxx for feedback on Issue #27 about OpenCode support
- obra for the superpowers reference implementation
---
## [2.2.2] - 2026-01-17
### Fixed
- **Restored Skill Activation Language** (PR #34)
- Restored the activation trigger in SKILL.md description
- Description now includes: "Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls"
- This language was accidentally removed during the v2.2.1 merge
- Helps Claude auto-activate the skill when detecting appropriate tasks
### Changed
- Updated version to 2.2.2 in all SKILL.md files and plugin.json
### Thanks
- Community members for catching this issue
---
## [2.2.1] - 2026-01-17
### Added
- **Session Recovery Feature** (PR #33 by @lasmarois)
- Automatically detect and recover unsynced work from previous sessions after `/clear`
- New `scripts/session-catchup.py` analyzes previous session JSONL files
- Finds last planning file update and extracts conversation that happened after
- Recovery triggered automatically when invoking `/planning-with-files`
- Pure Python stdlib implementation, no external dependencies
- **PreToolUse Hook Enhancement**
- Now triggers on Read/Glob/Grep in addition to Write/Edit/Bash
- Keeps task_plan.md in attention during research/exploration phases
- Better context management throughout workflow
### Changed
- SKILL.md restructured with session recovery as first instruction
- Description updated to mention session recovery feature
- README updated with session recovery workflow and instructions
### Documentation
- Added "Session Recovery" section to README
- Documented optimal workflow for context window management
- Instructions for disabling auto-compact in Claude Code settings
### Thanks
Special thanks to:
- @lasmarois for session recovery implementation (PR #33)
- Community members for testing and feedback
---
## [2.2.0] - 2026-01-17
### Added
- **Kilo Code Support** (PR #30 by @aimasteracc)
- Added Kilo Code IDE compatibility for the planning-with-files skill
- Created `.kilocode/rules/planning-with-files.md` with IDE-specific rules
- Added `docs/kilocode.md` comprehensive documentation for Kilo Code users
- Enables seamless integration with Kilo Code's planning workflow
- **Windows PowerShell Support** (Fixes #32, #25)
- Created `check-complete.ps1` - PowerShell equivalent of bash script
- Created `init-session.ps1` - PowerShell session initialization
- Scripts available in all three locations (root, plugin, skills)
- OS-aware hook execution with automatic fallback
- Improves Windows user experience with native PowerShell support
- **CONTRIBUTORS.md**
- Recognizes all community contributors
- Lists code contributors with their impact
- Acknowledges issue reporters and testers
- Documents community forks
### Fixed
- **Stop Hook Windows Compatibility** (Fixes #32)
- Hook now detects Windows environment automatically
- Uses PowerShell scripts on Windows, bash on Unix/Linux/Mac
- Graceful fallback if PowerShell not available
- Tested on Windows 11 PowerShell and Git Bash
- **Script Path Resolution** (Fixes #25)
- Improved `${CLAUDE_PLUGIN_ROOT}` handling across platforms
- Scripts now work regardless of installation method
- Added error handling for missing scripts
### Changed
- **SKILL.md Hook Configuration**
- Stop hook now uses multi-line command with OS detection
- Supports pwsh (PowerShell Core), powershell (Windows PowerShell), and bash
- Automatic fallback chain for maximum compatibility
- **Documentation Updates**
- Updated to support both Claude Code and Kilo Code environments
- Enhanced template compatibility across different AI coding assistants
- Updated `.gitignore` to include `findings.md` and `progress.md`
### Files Added
- `.kilocode/rules/planning-with-files.md` - Kilo Code IDE rules
- `docs/kilocode.md` - Kilo Code-specific documentation
- `scripts/check-complete.ps1` - PowerShell completion check (root level)
- `scripts/init-session.ps1` - PowerShell session init (root level)
- `planning-with-files/scripts/check-complete.ps1` - PowerShell (plugin level)
- `planning-with-files/scripts/init-session.ps1` - PowerShell (plugin level)
- `skills/planning-with-files/scripts/check-complete.ps1` - PowerShell (skills level)
- `skills/planning-with-files/scripts/init-session.ps1` - PowerShell (skills level)
- `CONTRIBUTORS.md` - Community contributor recognition
- `COMPREHENSIVE_ISSUE_ANALYSIS.md` - Detailed issue research and solutions
### Documentation
- Added Windows troubleshooting guidance
- Recognized community contributors in CONTRIBUTORS.md
- Updated README to reflect Windows and Kilo Code support
### Thanks
Special thanks to:
- @aimasteracc for Kilo Code support and PowerShell script contribution (PR #30)
- @mtuwei for reporting Windows compatibility issues (#32)
- All community members who tested and provided feedback
- Root cause: `${CLAUDE_PLUGIN_ROOT}` resolves to repo root, but templates were only in subfolders
- Added `templates/` and `scripts/` directories at repo root level
- Now templates are accessible regardless of how `CLAUDE_PLUGIN_ROOT` resolves
- Works for both plugin installs and manual installs
### Structure
After this fix, templates exist in THREE locations for maximum compatibility:
- `templates/` - At repo root (for `${CLAUDE_PLUGIN_ROOT}/templates/`)
- `planning-with-files/templates/` - For plugin marketplace installs
- `skills/planning-with-files/templates/` - For legacy `~/.claude/skills/` installs
### Workaround for Existing Users
If you still experience issues after updating:
1. Uninstall: `/plugin uninstall planning-with-files@planning-with-files`
2. Reinstall: `/plugin marketplace add OthmanAdi/planning-with-files`
3. Install: `/plugin install planning-with-files@planning-with-files`
---
## [2.1.1] - 2026-01-10
### Fixed
- **Plugin Template Path Issue** (Fixes #15)
- Templates weren't found when installed via plugin marketplace
- Plugin cache expected `planning-with-files/templates/` at repo root
- Added `planning-with-files/` folder at root level for plugin installs
- Kept `skills/planning-with-files/` for legacy `~/.claude/skills/` installs
### Structure
- `planning-with-files/` - For plugin marketplace installs
- `skills/planning-with-files/` - For manual `~/.claude/skills/` installs
---
## [2.1.0] - 2026-01-10
### Added
- **Claude Code v2.1 Compatibility**
- Updated skill to leverage all new Claude Code v2.1 features
- Requires Claude Code v2.1.0 or later
- **`user-invocable: true` Frontmatter**
- Skill now appears in slash command menu
- Users can manually invoke with `/planning-with-files`
- Auto-detection still works as before
- **`SessionStart` Hook**
- Notifies user when skill is loaded and ready
- Displays message at session start confirming skill availability
- **`PostToolUse` Hook**
- Runs after every Write/Edit operation
- Reminds Claude to update `task_plan.md` if a phase was completed
- Helps prevent forgotten status updates
- **YAML List Format for `allowed-tools`**
- Migrated from comma-separated string to YAML list syntax
- Cleaner, more maintainable frontmatter
- Follows Claude Code v2.1 best practices
### Changed
- Version bumped to 2.1.0 in SKILL.md, plugin.json, and README.md
- README.md updated with v2.1.0 features section
- Versions table updated to reflect new release
### Compatibility
- **Minimum Claude Code Version:** v2.1.0
- **Backward Compatible:** Yes (works with older Claude Code, but new hooks may not fire)
## [2.0.1] - 2026-01-09
### Fixed
- Planning files now correctly created in project directory, not skill installation folder
- Added "Important: Where Files Go" section to SKILL.md
- Added Troubleshooting section to README.md
### Thanks
- @wqh17101 for reporting and confirming the fix
## [2.0.0] - 2026-01-08
### Added
- **Hooks Integration** (Claude Code 2.1.0+)
- `PreToolUse` hook: Automatically reads `task_plan.md` before Write/Edit/Bash operations
- `Stop` hook: Verifies all phases are complete before stopping
- Implements Manus "attention manipulation" principle automatically
- **Templates Directory**
- `templates/task_plan.md` - Structured phase tracking template
- `templates/findings.md` - Research and discovery storage template
- `templates/progress.md` - Session logging with test results template
- **Scripts Directory**
- `scripts/init-session.sh` - Initialize all planning files at once
- `scripts/check-complete.sh` - Verify all phases are complete
- **New Documentation**
- `CHANGELOG.md` - This file
- **Enhanced SKILL.md**
- The 2-Action Rule (save findings after every 2 view/browser operations)
- The 3-Strike Error Protocol (structured error recovery)
- Read vs Write Decision Matrix
- The 5-Question Reboot Test
- **Expanded reference.md**
- The 3 Context Engineering Strategies (Reduction, Isolation, Offloading)
- The 7-Step Agent Loop diagram
- Critical constraints section
- Updated Manus statistics
### Changed
- SKILL.md restructured for progressive disclosure (<500 lines)
- Version bumped to 2.0.0 in all manifests
- README.md reorganized (Thank You section moved to top)
- Description updated to mention >5 tool calls threshold
### Preserved
- All v1.0.0 content available in `legacy` branch
- Original examples.md retained (proven patterns)
- Core 3-file pattern unchanged
- MIT License unchanged
## [1.0.0] - 2026-01-07
### Added
- Initial release
- SKILL.md with core workflow
- reference.md with 6 Manus principles
- examples.md with 4 real-world examples
- Plugin structure for Claude Code marketplace
- README.md with installation instructions
---
## Versioning
This project follows [Semantic Versioning](https://semver.org/):
- MAJOR: Breaking changes to skill behavior
- MINOR: New features, backward compatible
- PATCH: Bug fixes, documentation updates

97
skills/planning-with-files/CONTRIBUTORS.md Normal file
View File

@@ -0,0 +1,97 @@
# Contributors
Thank you to everyone who has contributed to making `planning-with-files` better!
## Project Author
- **[Ahmad Othman Ammar Adi](https://github.com/OthmanAdi)** - Original creator and maintainer
## Code Contributors
These amazing people have contributed code, documentation, or significant improvements to the project:
### Major Contributions
- **[@kaichen](https://github.com/kaichen)** - [PR #9](https://github.com/OthmanAdi/planning-with-files/pull/9)
- Converted the repository to Claude Code plugin structure
- Enabled marketplace installation
- Followed official plugin standards
- **Impact:** Made the skill accessible to the masses
- **[@fuahyo](https://github.com/fuahyo)** - [PR #12](https://github.com/OthmanAdi/planning-with-files/pull/12)
- Added "Build a todo app" walkthrough with 4 phases
- Created inline comments for templates (WHAT/WHY/WHEN/EXAMPLE)
- Developed Quick Start guide with ASCII reference tables
- Created workflow diagram showing task lifecycle
- **Impact:** Dramatically improved beginner onboarding
- **[@lasmarois](https://github.com/lasmarois)** - [PR #33](https://github.com/OthmanAdi/planning-with-files/pull/33)
- Created session recovery feature for context preservation after `/clear`
- Built `session-catchup.py` script to analyze previous session JSONL files
- Enhanced PreToolUse hook to include Read/Glob/Grep operations
- Restructured SKILL.md for better session recovery workflow
- **Impact:** Solves context loss problem, enables seamless work resumption
- **[@aimasteracc](https://github.com/aimasteracc)** - [PR #30](https://github.com/OthmanAdi/planning-with-files/pull/30)
- Added Kilocode IDE support and documentation
- Created PowerShell scripts for Windows compatibility
- Added `.kilocode/rules/` configuration
- Updated documentation for multi-IDE support
- **Impact:** Windows compatibility and IDE ecosystem expansion
### Other Contributors
- **[@tobrun](https://github.com/tobrun)** - [PR #3](https://github.com/OthmanAdi/planning-with-files/pull/3)
- Early directory structure improvements
- Helped identify optimal repository layout
- **[@markocupic024](https://github.com/markocupic024)** - [PR #4](https://github.com/OthmanAdi/planning-with-files/pull/4)
- Cursor IDE support contribution
- Helped establish multi-IDE pattern
- **Copilot SWE Agent** - [PR #16](https://github.com/OthmanAdi/planning-with-files/pull/16)
- Fixed template bundling in plugin.json
- Added `assets` field to ensure templates copy to cache
- **Impact:** Resolved template path issues
## Community Forks
These developers have created forks that extend the functionality:
- **[@kmichels](https://github.com/kmichels)** - [multi-manus-planning](https://github.com/kmichels/multi-manus-planning)
- Multi-project support
- SessionStart git sync integration
## Issue Reporters & Testers
Thank you to everyone who reported issues, provided feedback, and helped test fixes:
- [@mtuwei](https://github.com/mtuwei) - Issue #32 (Windows hook error)
- [@JianweiWangs](https://github.com/JianweiWangs) - Issue #31 (Skill activation)
- [@tingles2233](https://github.com/tingles2233) - Issue #29 (Plugin update issues)
- [@st01cs](https://github.com/st01cs) - Issue #28 (Devis fork discussion)
- [@wqh17101](https://github.com/wqh17101) - Issue #11 testing and confirmation
And many others who have starred, forked, and shared this project!
## How to Contribute
We welcome contributions! Here's how you can help:
1. **Report Issues** - Found a bug? Open an issue with details
2. **Suggest Features** - Have an idea? Share it in discussions
3. **Submit PRs** - Code improvements, documentation, examples
4. **Share** - Tell others about planning-with-files
5. **Create Forks** - Build on this work (with attribution)
See our [repository](https://github.com/OthmanAdi/planning-with-files) for more details.
## Recognition
If you've contributed and don't see your name here, please open an issue! We want to recognize everyone who helps make this project better.
---
**Total Contributors:** 10+ and growing!
*Last updated: January 17, 2026*

21
skills/planning-with-files/LICENSE Normal file
View File

@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 Ahmad Adi
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

128
skills/planning-with-files/MIGRATION.md Normal file
View File

@@ -0,0 +1,128 @@
# Migration Guide: v1.x to v2.0.0
## Overview
Version 2.0.0 adds hooks integration and enhanced templates while maintaining backward compatibility with existing workflows.
## What's New
### 1. Hooks (Automatic Behaviors)
v2.0.0 adds Claude Code hooks that automate key Manus principles:
| Hook | Trigger | Behavior |
|------|---------|----------|
| `PreToolUse` | Before Write/Edit/Bash | Reads `task_plan.md` to refresh goals |
| `Stop` | Before stopping | Verifies all phases are complete |
**Benefit:** You no longer need to manually remember to re-read your plan. The hook does it automatically.
### 2. Templates Directory
New templates provide structured starting points:
```
templates/
├── task_plan.md # Phase tracking with status fields
├── findings.md # Research storage with 2-action reminder
└── progress.md # Session log with 5-question reboot test
```
### 3. Scripts Directory
Helper scripts for common operations:
```
scripts/
├── init-session.sh # Creates all 3 planning files
└── check-complete.sh # Verifies task completion
```
## Migration Steps
### Step 1: Update the Plugin
```bash
# If installed via marketplace
/plugin update planning-with-files
# If installed manually
cd .claude/plugins/planning-with-files
git pull origin master
```
### Step 2: Existing Files Continue Working
Your existing `task_plan.md` files will continue to work. The hooks look for this file and gracefully handle its absence.
### Step 3: Adopt New Templates (Optional)
To use the new structured templates, you can either:
1. **Start fresh** with `./scripts/init-session.sh`
2. **Copy templates** from `templates/` directory
3. **Keep your existing format** - it still works
### Step 4: Update Phase Status Format (Recommended)
v2.0.0 templates use a more structured status format:
**v1.x format:**
```markdown
- [x] Phase 1: Setup ✓
- [ ] Phase 2: Implementation (CURRENT)
```
**v2.0.0 format:**
```markdown
### Phase 1: Setup
- **Status:** complete
### Phase 2: Implementation
- **Status:** in_progress
```
The new format enables the `check-complete.sh` script to automatically verify completion.
## Breaking Changes
**None.** v2.0.0 is fully backward compatible.
If you prefer the v1.x behavior without hooks, use the `legacy` branch:
```bash
git checkout legacy
```
## New Features to Adopt
### The 2-Action Rule
After every 2 view/browser/search operations, save findings to files:
```
WebSearch → WebSearch → MUST Write findings.md
```
### The 3-Strike Error Protocol
Structured error recovery:
1. Diagnose & Fix
2. Alternative Approach
3. Broader Rethink
4. Escalate to User
### The 5-Question Reboot Test
Your planning files should answer:
1. Where am I? → Current phase
2. Where am I going? → Remaining phases
3. What's the goal? → Goal statement
4. What have I learned? → findings.md
5. What have I done? → progress.md
## Questions?
Open an issue: https://github.com/OthmanAdi/planning-with-files/issues

276
skills/planning-with-files/README.md Normal file
View File

@@ -0,0 +1,276 @@
# Planning with Files
> **Work like Manus** — the AI agent company Meta acquired for **$2 billion**.
## Thank You
To everyone who starred, forked, and shared this skill — thank you. This project blew up in less than 24 hours, and the support from the community has been incredible.
If this skill helps you work smarter, that's all I wanted.
---
A Claude Code plugin that transforms your workflow to use persistent markdown files for planning, progress tracking, and knowledge storage — the exact pattern that made Manus worth billions.
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-Plugin-blue)](https://code.claude.com/docs/en/plugins)
[![Claude Code Skill](https://img.shields.io/badge/Claude%20Code-Skill-green)](https://code.claude.com/docs/en/skills)
[![Cursor Rules](https://img.shields.io/badge/Cursor-Rules-purple)](https://docs.cursor.com/context/rules-for-ai)
[![Version](https://img.shields.io/badge/version-2.3.0-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)
## Quick Install
```bash
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files
```
See [docs/installation.md](docs/installation.md) for all installation methods.
## Supported IDEs
| IDE | Status | Installation Guide | Format |
|-----|--------|-------------------|--------|
| Claude Code | ✅ Full Support | [Installation](docs/installation.md) | Plugin + SKILL.md |
| Cursor | ✅ Full Support | [Cursor Setup](docs/cursor.md) | Rules |
| Kilocode | ✅ Full Support | [Kilocode Setup](docs/kilocode.md) | Rules |
| OpenCode | ✅ Full Support | [OpenCode Setup](docs/opencode.md) | Personal/Project Skill |
| Codex | ✅ Full Support | [Codex Setup](docs/codex.md) | Personal Skill |
## Documentation
| Document | Description |
|----------|-------------|
| [Installation Guide](docs/installation.md) | All installation methods (plugin, manual, Cursor, Windows) |
| [Quick Start](docs/quickstart.md) | 5-step guide to using the pattern |
| [Workflow Diagram](docs/workflow.md) | Visual diagram of how files and hooks interact |
| [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions |
| [Cursor Setup](docs/cursor.md) | Cursor IDE-specific instructions |
| [Windows Setup](docs/windows.md) | Windows-specific notes |
| [Kilo Code Support](docs/kilocode.md) | Kilo Code integration guide |
| [Codex Setup](docs/codex.md) | Codex IDE installation and usage |
| [OpenCode Setup](docs/opencode.md) | OpenCode IDE installation, oh-my-opencode config |
## Versions
| Version | Features | Install |
|---------|----------|---------|
| **v2.3.0** (current) | Codex & OpenCode IDE support | `/plugin install planning-with-files@planning-with-files` |
| **v2.2.2** | Restored skill activation language | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v2.2.1** | Session recovery after /clear, enhanced PreToolUse hook | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v2.2.0** | Kilo Code IDE support, Windows PowerShell support, OS-aware hooks | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v2.1.2** | Fix template cache issue (Issue #18) | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v2.1.0** | Claude Code v2.1 compatible, PostToolUse hook, user-invocable | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v2.0.x** | Hooks, templates, scripts | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v1.0.0** (legacy) | Core 3-file pattern | `git clone -b legacy` |
See [CHANGELOG.md](CHANGELOG.md) for details.
## Why This Skill?
On December 29, 2025, [Meta acquired Manus for $2 billion](https://techcrunch.com/2025/12/29/meta-just-bought-manus-an-ai-startup-everyone-has-been-talking-about/). In just 8 months, Manus went from launch to $100M+ revenue. Their secret? **Context engineering**.
> "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
## The Problem
Claude Code (and most AI agents) suffer from:
- **Volatile memory** — TodoWrite tool disappears on context reset
- **Goal drift** — After 50+ tool calls, original goals get forgotten
- **Hidden errors** — Failures aren't tracked, so the same mistakes repeat
- **Context stuffing** — Everything crammed into context instead of stored
## The Solution: 3-File Pattern
For every complex task, create THREE files:
```
task_plan.md → Track phases and progress
findings.md → Store research and findings
progress.md → Session log and test results
```
### The Core Principle
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
```
## Usage
Once installed, Claude will automatically:
1. **Create `task_plan.md`** before starting complex tasks
2. **Re-read plan** before major decisions (via PreToolUse hook)
3. **Remind you** to update status after file writes (via PostToolUse hook)
4. **Store findings** in `findings.md` instead of stuffing context
5. **Log errors** for future reference
6. **Verify completion** before stopping (via Stop hook)
Or invoke manually with `/planning-with-files`.
See [docs/quickstart.md](docs/quickstart.md) for the full 5-step guide.
## Session Recovery (NEW in v2.2.0)
When your context window fills up and you run `/clear`, this skill automatically recovers unsynced work from your previous session.
### Optimal Workflow
For the best experience, we recommend:
1. **Disable auto-compact** in Claude Code settings (use full context window)
2. **Start a fresh session** in your project
3. **Run `/planning-with-files`** when ready to work on a complex task
4. **Work until context fills up** (Claude will warn you)
5. **Run `/clear`** to start fresh
6. **Run `/planning-with-files`** again — it will automatically recover where you left off
### How Recovery Works
When you invoke `/planning-with-files`, the skill:
1. Checks for previous session data (stored in `~/.claude/projects/`)
2. Finds the last time planning files were updated
3. Extracts conversation that happened after (potentially lost context)
4. Shows a catchup report so you can sync planning files
This means even if context filled up before you could update your planning files, the skill will recover that context in your next session.
### Disabling Auto-Compact
To use the full context window without automatic compaction:
```bash
# In your Claude Code settings or .claude/settings.json
{
"autoCompact": false
}
```
This lets you maximize context usage before manually clearing with `/clear`.
## Key Rules
1. **Create Plan First** — Never start without `task_plan.md`
2. **The 2-Action Rule** — Save findings after every 2 view/browser operations
3. **Log ALL Errors** — They help avoid repetition
4. **Never Repeat Failures** — Track attempts, mutate approach
## File Structure
```
planning-with-files/
├── templates/ # Root-level templates (for CLAUDE_PLUGIN_ROOT)
├── scripts/ # Root-level scripts (for CLAUDE_PLUGIN_ROOT)
├── docs/ # Documentation
│ ├── installation.md
│ ├── quickstart.md
│ ├── workflow.md
│ ├── troubleshooting.md
│ ├── cursor.md
│ ├── windows.md
│ ├── kilocode.md
│ ├── codex.md
│ └── opencode.md
├── planning-with-files/ # Plugin skill folder
│ ├── SKILL.md
│ ├── templates/
│ └── scripts/
├── skills/ # Legacy skill folder
│ └── planning-with-files/
│ ├── SKILL.md
│ ├── examples.md
│ ├── reference.md
│ ├── templates/
│ └── scripts/
│ ├── init-session.sh
│ ├── check-complete.sh
│ ├── init-session.ps1 # Windows PowerShell
│ └── check-complete.ps1 # Windows PowerShell
├── .codex/ # Codex IDE installation guide
│ └── INSTALL.md
├── .opencode/ # OpenCode IDE installation guide
│ └── INSTALL.md
├── .claude-plugin/ # Plugin manifest
├── .cursor/ # Cursor rules
├── .kilocode/ # Kilo Code rules
│ └── rules/
│ └── planning-with-files.md
├── CHANGELOG.md
├── LICENSE
└── README.md
```
## The Manus Principles
| Principle | Implementation |
|-----------|----------------|
| Filesystem as memory | Store in files, not context |
| Attention manipulation | Re-read plan before decisions (hooks) |
| Error persistence | Log failures in plan file |
| Goal tracking | Checkboxes show progress |
| Completion verification | Stop hook checks all phases |
## When to Use
**Use this pattern 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
## Kilo Code Support
This skill also supports Kilo Code AI through the `.kilocode/rules/` directory.
The [`.kilocode/rules/planning-with-files.md`](.kilocode/rules/planning-with-files.md) file contains all the planning guidelines formatted for Kilo Code's rules system, providing the same Manus-style planning workflow for Kilo Code users.
**Windows users:** The skill now includes PowerShell scripts ([`init-session.ps1`](skills/planning-with-files/scripts/init-session.ps1) and [`check-complete.ps1`](skills/planning-with-files/scripts/check-complete.ps1)) for native Windows support.
See [docs/kilocode.md](docs/kilocode.md) for detailed Kilo Code integration guide.
## Community Forks
| Fork | Author | Features |
|------|--------|----------|
| [devis](https://github.com/st01cs/devis) | [@st01cs](https://github.com/st01cs) | Interview-first workflow, `/devis:intv` and `/devis:impl` commands, guaranteed activation |
| [multi-manus-planning](https://github.com/kmichels/multi-manus-planning) | [@kmichels](https://github.com/kmichels) | Multi-project support, SessionStart git sync |
*Built something? Open an issue to get listed!*
## Acknowledgments
- **Manus AI** — For pioneering context engineering patterns
- **Anthropic** — For Claude Code, Agent Skills, and the Plugin system
- **Lance Martin** — For the detailed Manus architecture analysis
- Based on [Context Engineering for AI Agents](https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus)
## Contributing
Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Submit a pull request
## License
MIT License — feel free to use, modify, and distribute.
---
**Author:** [Ahmad Othman Ammar Adi](https://github.com/OthmanAdi)
## Star History
[![Star History Chart](https://api.star-history.com/svg?repos=OthmanAdi/planning-with-files&type=Date)](https://star-history.com/#OthmanAdi/planning-with-files&Date)

52
skills/planning-with-files/docs/codex.md Normal file
View File

@@ -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)

144
skills/planning-with-files/docs/cursor.md Normal file
View File

@@ -0,0 +1,144 @@
# Cursor IDE Setup
How to use planning-with-files with Cursor IDE.
---
## Installation
### Option 1: Copy rules directory
```bash
git clone https://github.com/OthmanAdi/planning-with-files.git
cp -r planning-with-files/.cursor .cursor
```
### Option 2: Manual setup
Create `.cursor/rules/planning-with-files.mdc` in your project with the content from this repo.
---
## Important Limitations
> **Note:** Hooks (PreToolUse, PostToolUse, Stop, SessionStart) are **Claude Code specific** and will NOT work in Cursor.
### What works in Cursor:
- Core 3-file planning pattern
- Templates (task_plan.md, findings.md, progress.md)
- All planning rules and guidelines
- The 2-Action Rule
- The 3-Strike Error Protocol
- Read vs Write Decision Matrix
### What doesn't work in Cursor:
- SessionStart hook (no startup notification)
- PreToolUse hook (no automatic plan re-reading)
- PostToolUse hook (no automatic reminders)
- Stop hook (no automatic completion verification)
---
## Manual Workflow for Cursor
Since hooks don't work in Cursor, you'll need to follow the pattern manually:
### 1. Create planning files first
Before any complex task:
```
Create task_plan.md, findings.md, and progress.md using the planning-with-files templates.
```
### 2. Re-read plan before decisions
Periodically ask:
```
Please read task_plan.md to refresh the goals before continuing.
```
### 3. Update files after phases
After completing work:
```
Update task_plan.md to mark this phase complete.
Update progress.md with what was done.
```
### 4. Verify completion manually
Before finishing:
```
Check task_plan.md - are all phases marked complete?
```
---
## Cursor Rules File
The `.cursor/rules/planning-with-files.mdc` file contains all the planning guidelines formatted for Cursor's rules system.
### File location
```
your-project/
├── .cursor/
│ └── rules/
│ └── planning-with-files.mdc
├── task_plan.md
├── findings.md
├── progress.md
└── ...
```
### Activating rules
Cursor automatically loads rules from `.cursor/rules/` when you open a project.
---
## Templates
The templates in `skills/planning-with-files/templates/` work in Cursor:
- `task_plan.md` - Phase tracking template
- `findings.md` - Research storage template
- `progress.md` - Session logging template
Copy them to your project root when starting a new task.
---
## Tips for Cursor Users
1. **Pin the planning files:** Keep task_plan.md open in a split view for easy reference.
2. **Add to .cursorrules:** You can also add planning guidelines to your project's `.cursorrules` file.
3. **Use explicit prompts:** Since there's no auto-detection, be explicit:
```
This is a complex task. Let's use the planning-with-files pattern.
Start by creating task_plan.md with the goal and phases.
```
4. **Check status regularly:** Without the Stop hook, manually verify completion before finishing.
---
## Migrating from Cursor to Claude Code
If you want full hook support, consider using Claude Code CLI:
1. Install Claude Code
2. Run `/plugin install planning-with-files@planning-with-files`
3. All hooks will work automatically
Your existing planning files (task_plan.md, etc.) are compatible with both.
---
## Need Help?
Open an issue at [github.com/OthmanAdi/planning-with-files/issues](https://github.com/OthmanAdi/planning-with-files/issues).

168
skills/planning-with-files/docs/installation.md Normal file
View File

@@ -0,0 +1,168 @@
# Installation Guide
Complete installation instructions for planning-with-files.
## Quick Install (Recommended)
```bash
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files
```
That's it! The skill is now active.
---
## Installation Methods
### 1. Claude Code Plugin (Recommended)
Install directly using the Claude Code CLI:
```bash
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files
```
**Advantages:**
- Automatic updates
- Proper hook integration
- Full feature support
---
### 2. Manual Installation
Clone or copy this repository into your project's `.claude/plugins/` directory:
#### Option A: Clone into plugins directory
```bash
mkdir -p .claude/plugins
git clone https://github.com/OthmanAdi/planning-with-files.git .claude/plugins/planning-with-files
```
#### Option B: Add as git submodule
```bash
git submodule add https://github.com/OthmanAdi/planning-with-files.git .claude/plugins/planning-with-files
```
#### Option C: Use --plugin-dir flag
```bash
git clone https://github.com/OthmanAdi/planning-with-files.git
claude --plugin-dir ./planning-with-files
```
---
### 3. Legacy Installation (Skills Only)
If you only want the skill without the full plugin structure:
```bash
git clone https://github.com/OthmanAdi/planning-with-files.git
cp -r planning-with-files/skills/* ~/.claude/skills/
```
---
### 4. One-Line Installer (Skills Only)
Extract just the skill directly into your current directory:
```bash
curl -L https://github.com/OthmanAdi/planning-with-files/archive/master.tar.gz | tar -xzv --strip-components=2 "planning-with-files-master/skills/planning-with-files"
```
Then move `planning-with-files/` to `~/.claude/skills/`.
---
## Verifying Installation
After installation, verify the skill is loaded:
1. Start a new Claude Code session
2. You should see: `[planning-with-files] Ready. Auto-activates for complex tasks, or invoke manually with /planning-with-files`
3. Or type `/planning-with-files` to manually invoke
---
## Updating
### Plugin Installation
```bash
/plugin update planning-with-files@planning-with-files
```
### Manual Installation
```bash
cd .claude/plugins/planning-with-files
git pull origin master
```
### Skills Only
```bash
cd ~/.claude/skills/planning-with-files
git pull origin master
```
---
## Uninstalling
### Plugin
```bash
/plugin uninstall planning-with-files@planning-with-files
```
### Manual
```bash
rm -rf .claude/plugins/planning-with-files
```
### Skills Only
```bash
rm -rf ~/.claude/skills/planning-with-files
```
---
## Requirements
- **Claude Code:** v2.1.0 or later (for full hook support)
- **Older versions:** Core functionality works, but hooks may not fire
---
## Platform-Specific Notes
### Windows
See [docs/windows.md](windows.md) for Windows-specific installation notes.
### Cursor
See [docs/cursor.md](cursor.md) for Cursor IDE installation.
### Codex
See [docs/codex.md](codex.md) for Codex IDE installation.
### OpenCode
See [docs/opencode.md](opencode.md) for OpenCode IDE installation.
---
## Need Help?
If installation fails, check [docs/troubleshooting.md](troubleshooting.md) or open an issue at [github.com/OthmanAdi/planning-with-files/issues](https://github.com/OthmanAdi/planning-with-files/issues).

233
skills/planning-with-files/docs/kilocode.md Normal file
View File

@@ -0,0 +1,233 @@
# Kilo Code Support
Planning with Files is fully supported on Kilo Code through native integration.
## Quick Start
1. Open your project in Kilo Code
2. Rules load automatically from global (`~/.kilocode/rules/`) or project (`.kilocode/rules/`) directories
3. Start a complex task — Kilo Code will automatically create planning files
## Installation
### Quick Install (Project-Level)
Clone or copy the skill to your project's `.kilocode/skills/` directory:
**Unix/Linux/macOS:**
```bash
# Option A: Clone the repository
git clone https://github.com/OthmanAdi/planning-with-files.git
# Copy the skill to Kilo Code's skills directory
mkdir -p .kilocode/skills
cp -r planning-with-files/skills/planning-with-files .kilocode/skills/planning-with-files
# Copy the rules file (optional, but recommended)
mkdir -p .kilocode/rules
cp planning-with-files/.kilocode/rules/planning-with-files.md .kilocode/rules/planning-with-files.md
```
**Windows (PowerShell):**
```powershell
# Option A: Clone the repository
git clone https://github.com/OthmanAdi/planning-with-files.git
# Copy the skill to Kilo Code's skills directory
New-Item -ItemType Directory -Force -Path .kilocode\skills
Copy-Item -Recurse -Force planning-with-files\skills\planning-with-files .kilocode\skills\planning-with-files
# Copy the rules file (optional, but recommended)
New-Item -ItemType Directory -Force -Path .kilocode\rules
Copy-Item -Force planning-with-files\.kilocode\rules\planning-with-files.md .kilocode\rules\planning-with-files.md
# Copy PowerShell scripts (optional, but recommended)
Copy-Item -Force planning-with-files\scripts\init-session.ps1 .kilocode\skills\planning-with-files\scripts\init-session.ps1
Copy-Item -Force planning-with-files\scripts\check-complete.ps1 .kilocode\skills\planning-with-files\scripts\check-complete.ps1
```
### Manual Installation (Project-Level)
Copy the skill directory to your project:
**Unix/Linux/macOS:**
```bash
# From the cloned repository
mkdir -p .kilocode/skills
cp -r planning-with-files/skills/planning-with-files .kilocode/skills/planning-with-files
# Copy the rules file (optional, but recommended)
mkdir -p .kilocode/rules
cp planning-with-files/.kilocode/rules/planning-with-files.md .kilocode/rules/planning-with-files.md
```
**Windows (PowerShell):**
```powershell
# From the cloned repository
New-Item -ItemType Directory -Force -Path .kilocode\skills
Copy-Item -Recurse -Force planning-with-files\skills\planning-with-files .kilocode\skills\planning-with-files
# Copy the rules file (optional, but recommended)
New-Item -ItemType Directory -Force -Path .kilocode\rules
Copy-Item -Force planning-with-files\.kilocode\rules\planning-with-files.md .kilocode\rules\planning-with-files.md
# Copy PowerShell scripts (optional, but recommended)
Copy-Item -Force planning-with-files\scripts\init-session.ps1 .kilocode\skills\planning-with-files\scripts\init-session.ps1
Copy-Item -Force planning-with-files\scripts\check-complete.ps1 .kilocode\skills\planning-with-files\scripts\check-complete.ps1
```
### Global Installation (User-Level)
To make the skill available across all projects:
**Unix/Linux/macOS:**
```bash
# Copy to global skills directory
mkdir -p ~/.kilocode/skills
cp -r planning-with-files/skills/planning-with-files ~/.kilocode/skills/planning-with-files
# Copy the rules file (optional, but recommended)
mkdir -p ~/.kilocode/rules
cp planning-with-files/.kilocode/rules/planning-with-files.md ~/.kilocode/rules/planning-with-files.md
```
**Windows (PowerShell):**
```powershell
# Copy to global skills directory (replace YourUsername with your actual username)
New-Item -ItemType Directory -Force -Path C:\Users\YourUsername\.kilocode\skills
Copy-Item -Recurse -Force planning-with-files\skills\planning-with-files C:\Users\YourUsername\.kilocode\skills\planning-with-files
# Copy the rules file (optional, but recommended)
New-Item -ItemType Directory -Force -Path C:\Users\YourUsername\.kilocode\rules
Copy-Item -Force planning-with-files\.kilocode\rules\planning-with-files.md C:\Users\YourUsername\.kilocode\rules\planning-with-files.md
# Copy PowerShell scripts (optional, but recommended)
Copy-Item -Force planning-with-files\scripts\init-session.ps1 C:\Users\YourUsername\.kilocode\skills\planning-with-files\scripts\init-session.ps1
Copy-Item -Force planning-with-files\scripts\check-complete.ps1 C:\Users\YourUsername\.kilocode\skills\planning-with-files\scripts\check-complete.ps1
```
### Verifying Installation
After installation, verify the skill is loaded:
1. **Restart Kilo Code** (if needed)
2. Ask the agent: "Do you have access to the planning-with-files skill?"
3. The agent should confirm the skill is loaded
4. Rules also load automatically from `~/.kilocode/rules/planning-with-files.md` (global) or `.kilocode/rules/planning-with-files.md` (project)
**Testing PowerShell Scripts (Windows):**
After installation, you can test the PowerShell scripts:
```powershell
# Test init-session.ps1
.\.kilocode\skills\planning-with-files\scripts\init-session.ps1
# Test check-complete.ps1
.\.kilocode\skills\planning-with-files\scripts\check-complete.ps1
```
The scripts should create `task_plan.md`, `findings.md`, and `progress.md` files in your project root.
### File Structure
The installation consists of the skill directory and the rules file:
**Skill Directory:**
```
~/.kilocode/skills/planning-with-files/ (Global)
OR
.kilocode/skills/planning-with-files/ (Project)
├── SKILL.md # Skill definition
├── examples.md # Real-world examples
├── reference.md # Advanced reference
├── templates/ # Planning file templates
│ ├── task_plan.md
│ ├── findings.md
│ └── progress.md
└── scripts/ # Utility scripts
├── init-session.sh # Unix/Linux/macOS
├── check-complete.sh # Unix/Linux/macOS
├── init-session.ps1 # Windows (PowerShell)
└── check-complete.ps1 # Windows (PowerShell)
```
**Rules File:**
```
~/.kilocode/rules/planning-with-files.md (Global)
OR
.kilocode/rules/planning-with-files.md (Project)
```
**Important**: The `name` field in `SKILL.md` must match the directory name (`planning-with-files`).
## File Locations
| Type | Global Location | Project Location |
|------|-----------------|------------------|
| **Rules** | `~/.kilocode/rules/planning-with-files.md` | `.kilocode/rules/planning-with-files.md` |
| **Skill** | `~/.kilocode/skills/planning-with-files/SKILL.md` | `.kilocode/skills/planning-with-files/SKILL.md` |
| **Templates** | `~/.kilocode/skills/planning-with-files/templates/` | `.kilocode/skills/planning-with-files/templates/` |
| **Scripts (Unix/Linux/macOS)** | `~/.kilocode/skills/planning-with-files/scripts/*.sh` | `.kilocode/skills/planning-with-files/scripts/*.sh` |
| **Scripts (Windows PowerShell)** | `~/.kilocode/skills/planning-with-files/scripts/*.ps1` | `.kilocode/skills/planning-with-files/scripts/*.ps1` |
| **Your Files** | `task_plan.md`, `findings.md`, `progress.md` in project root |
## Quick Commands
**For Global Installation:**
**Unix/Linux/macOS:**
```bash
# Initialize planning files
~/.kilocode/skills/planning-with-files/scripts/init-session.sh
# Verify task completion
~/.kilocode/skills/planning-with-files/scripts/check-complete.sh
```
**Windows (PowerShell):**
```powershell
# Initialize planning files
$env:USERPROFILE\.kilocode\skills\planning-with-files\scripts\init-session.ps1
# Verify task completion
$env:USERPROFILE\.kilocode\skills\planning-with-files\scripts\check-complete.ps1
```
**For Project Installation:**
**Unix/Linux/macOS:**
```bash
# Initialize planning files
./.kilocode/skills/planning-with-files/scripts/init-session.sh
# Verify task completion
./.kilocode/skills/planning-with-files/scripts/check-complete.sh
```
**Windows (PowerShell):**
```powershell
# Initialize planning files
.\.kilocode\skills\planning-with-files\scripts\init-session.ps1
# Verify task completion
.\.kilocode\skills\planning-with-files\scripts\check-complete.ps1
```
## Migrating from Cursor/Windsurf
Planning files are fully compatible. Simply copy your `task_plan.md`, `findings.md`, and `progress.md` files to your new project.
## Additional Resources
**For Global Installation:**
- [Examples](~/.kilocode/skills/planning-with-files/examples.md) - Real-world examples
- [Reference](~/.kilocode/skills/planning-with-files/reference.md) - Advanced reference documentation
- [PowerShell Scripts](~/.kilocode/skills/planning-with-files/scripts/) - Utility scripts for Windows
**For Project Installation:**
- [Examples](.kilocode/skills/planning-with-files/examples.md) - Real-world examples
- [Reference](.kilocode/skills/planning-with-files/reference.md) - Advanced reference documentation
- [PowerShell Scripts](.kilocode/skills/planning-with-files/scripts/) - Utility scripts for Windows

70
skills/planning-with-files/docs/opencode.md Normal file
View File

@@ -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)

162
skills/planning-with-files/docs/quickstart.md Normal file
View File

@@ -0,0 +1,162 @@
# Quick Start Guide
Follow these 5 steps to use the planning-with-files pattern.
---
## Step 1: Create Your Planning Files
**When:** Before starting any work on a complex task
**Action:** Create all three files using the templates:
```bash
# Option 1: Use the init script (if available)
./scripts/init-session.sh
# Option 2: Copy templates manually
cp templates/task_plan.md task_plan.md
cp templates/findings.md findings.md
cp templates/progress.md progress.md
```
**Update:** Fill in the Goal section in `task_plan.md` with your task description.
---
## Step 2: Plan Your Phases
**When:** Right after creating the files
**Action:** Break your task into 3-7 phases in `task_plan.md`
**Example:**
```markdown
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Research existing solutions
- **Status:** in_progress
### Phase 2: Implementation
- [ ] Write core code
- **Status:** pending
```
**Update:**
- `task_plan.md`: Define your phases
- `progress.md`: Note that planning is complete
---
## Step 3: Work and Document
**When:** Throughout the task
**Action:** As you work, update files:
| What Happens | Which File to Update | What to Add |
|--------------|---------------------|-------------|
| You research something | `findings.md` | Add to "Research Findings" |
| You view 2 browser/search results | `findings.md` | **MUST update** (2-Action Rule) |
| You make a technical decision | `findings.md` | Add to "Technical Decisions" with rationale |
| You complete a phase | `task_plan.md` | Change status: `in_progress` → `complete` |
| You complete a phase | `progress.md` | Log actions taken, files modified |
| An error occurs | `task_plan.md` | Add to "Errors Encountered" table |
| An error occurs | `progress.md` | Add to "Error Log" with timestamp |
**Example workflow:**
```
1. Research → Update findings.md
2. Research → Update findings.md (2nd time - MUST update now!)
3. Make decision → Update findings.md "Technical Decisions"
4. Implement code → Update progress.md "Actions taken"
5. Complete phase → Update task_plan.md status to "complete"
6. Complete phase → Update progress.md with phase summary
```
---
## Step 4: Re-read Before Decisions
**When:** Before making major decisions (automatic with hooks in Claude Code)
**Action:** The PreToolUse hook automatically reads `task_plan.md` before Write/Edit/Bash operations
**Manual reminder (if not using hooks):** Before important choices, read `task_plan.md` to refresh your goals
**Why:** After many tool calls, original goals can be forgotten. Re-reading brings them back into attention.
---
## Step 5: Complete and Verify
**When:** When you think the task is done
**Action:** Verify completion:
1. **Check `task_plan.md`**: All phases should have `**Status:** complete`
2. **Check `progress.md`**: All phases should be logged with actions taken
3. **Run completion check** (if using hooks, this happens automatically):
```bash
./scripts/check-complete.sh
```
**If not complete:** The Stop hook (or script) will prevent stopping. Continue working until all phases are done.
**If complete:** Deliver your work! All three planning files document your process.
---
## Quick Reference: When to Update Which File
```
┌─────────────────────────────────────────────────────────┐
│ task_plan.md │
│ Update when: │
│ • Starting task (create it first!) │
│ • Completing a phase (change status) │
│ • Making a major decision (add to Decisions table) │
│ • Encountering an error (add to Errors table) │
│ • Re-reading before decisions (automatic via hook) │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│ findings.md │
│ Update when: │
│ • Discovering something new (research, exploration) │
│ • After 2 view/browser/search operations (2-Action!) │
│ • Making a technical decision (with rationale) │
│ • Finding useful resources (URLs, docs) │
│ • Viewing images/PDFs (capture as text immediately!) │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│ progress.md │
│ Update when: │
│ • Starting a new phase (log start time) │
│ • Completing a phase (log actions, files modified) │
│ • Running tests (add to Test Results table) │
│ • Encountering errors (add to Error Log with timestamp)│
│ • Resuming after a break (update 5-Question Check) │
└─────────────────────────────────────────────────────────┘
```
---
## Common Mistakes to Avoid
| Don't | Do Instead |
|-------|------------|
| Start work without creating `task_plan.md` | Always create the plan file first |
| Forget to update `findings.md` after 2 browser operations | Set a reminder: "2 view/browser ops = update findings.md" |
| Skip logging errors because you fixed them quickly | Log ALL errors, even ones you resolved immediately |
| Repeat the same failed action | If something fails, log it and try a different approach |
| Only update one file | The three files work together - update them as a set |
---
## Next Steps
- See [examples/README.md](../examples/README.md) for complete walkthrough examples
- See [workflow.md](workflow.md) for the visual workflow diagram
- See [troubleshooting.md](troubleshooting.md) if you encounter issues

240
skills/planning-with-files/docs/troubleshooting.md Normal file
View File

@@ -0,0 +1,240 @@
# Troubleshooting
Common issues and their solutions.
---
## Templates not found in cache (after update)
**Issue:** After updating to a new version, `/planning-with-files` fails with "template files not found in cache" or similar errors.
**Why this happens:** Claude Code caches plugin files, and the cache may not refresh properly after an update.
**Solutions:**
### Solution 1: Clean reinstall (Recommended)
```bash
/plugin uninstall planning-with-files@planning-with-files
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files
```
### Solution 2: Clear Claude Code cache
Restart Claude Code completely (close and reopen terminal/IDE).
### Solution 3: Manual cache clear
```bash
# Find and remove cached plugin
rm -rf ~/.claude/cache/plugins/planning-with-files
```
Then reinstall the plugin.
**Note:** This was fixed in v2.1.2 by adding templates at the repo root level.
---
## Planning files created in wrong directory
**Issue:** When using `/planning-with-files`, the files (`task_plan.md`, `findings.md`, `progress.md`) are created in the skill installation directory instead of your project.
**Why this happens:** When the skill runs as a subagent, it may not inherit your terminal's current working directory.
**Solutions:**
### Solution 1: Specify your project path when invoking
```
/planning-with-files - I'm working in /path/to/my-project/, create all files there
```
### Solution 2: Add context before invoking
```
I'm working on the project at /path/to/my-project/
```
Then run `/planning-with-files`.
### Solution 3: Create a CLAUDE.md in your project root
```markdown
# Project Context
All planning files (task_plan.md, findings.md, progress.md)
should be created in this directory.
```
### Solution 4: Use the skill directly without subagent
```
Help me plan this task using the planning-with-files approach.
Create task_plan.md, findings.md, and progress.md here.
```
**Note:** This was fixed in v2.0.1. The skill instructions now explicitly specify that planning files should be created in your project directory, not the skill installation folder.
---
## Files not persisting between sessions
**Issue:** Planning files seem to disappear or aren't found when resuming work.
**Solution:** Make sure the files are in your project root, not in a temporary location.
Check with:
```bash
ls -la task_plan.md findings.md progress.md
```
If files are missing, they may have been created in:
- The skill installation folder (`~/.claude/skills/planning-with-files/`)
- A temporary directory
- A different working directory
---
## Hooks not triggering
**Issue:** The PreToolUse hook (which reads task_plan.md before actions) doesn't seem to run.
**Solution:**
1. **Check Claude Code version:**
```bash
claude --version
```
Hooks require Claude Code v2.1.0 or later for full support.
2. **Verify skill installation:**
```bash
ls ~/.claude/skills/planning-with-files/
```
or
```bash
ls .claude/plugins/planning-with-files/
```
3. **Check that task_plan.md exists:**
The PreToolUse hook runs `cat task_plan.md`. If the file doesn't exist, the hook silently succeeds (by design).
4. **Check for YAML errors:**
Run Claude Code with debug mode:
```bash
claude --debug
```
Look for skill loading errors.
---
## SessionStart hook not showing message
**Issue:** The "Ready" message doesn't appear when starting Claude Code.
**Solution:**
1. SessionStart hooks require Claude Code v2.1.0+
2. The hook only fires once per session
3. If you've already started a session, restart Claude Code
---
## PostToolUse hook not running
**Issue:** The reminder message after Write/Edit doesn't appear.
**Solution:**
1. PostToolUse hooks require Claude Code v2.1.0+
2. The hook only fires after successful Write/Edit operations
3. Check the matcher pattern: it's set to `"Write|Edit"` only
---
## Skill not auto-detecting complex tasks
**Issue:** Claude doesn't automatically use the planning pattern for complex tasks.
**Solution:**
1. **Manually invoke:**
```
/planning-with-files
```
2. **Trigger words:** The skill auto-activates based on its description. Try phrases like:
- "complex multi-step task"
- "research project"
- "task requiring many steps"
3. **Be explicit:**
```
This is a complex task that will require >5 tool calls.
Please use the planning-with-files pattern.
```
---
## Stop hook blocking completion
**Issue:** Claude won't stop because the Stop hook says phases aren't complete.
**Solution:**
1. **Check task_plan.md:** All phases should have `**Status:** complete`
2. **Manual override:** If you need to stop anyway:
```
Override the completion check - I want to stop now.
```
3. **Fix the status:** Update incomplete phases to `complete` if they're actually done.
---
## YAML frontmatter errors
**Issue:** Skill won't load due to YAML errors.
**Solution:**
1. **Check indentation:** YAML requires spaces, not tabs
2. **Check the first line:** Must be exactly `---` with no blank lines before it
3. **Validate YAML:** Use an online YAML validator
Common mistakes:
```yaml
# WRONG - tabs
hooks:
PreToolUse:
# CORRECT - spaces
hooks:
PreToolUse:
```
---
## Windows-specific issues
See [docs/windows.md](windows.md) for Windows-specific troubleshooting.
---
## Cursor-specific issues
See [docs/cursor.md](cursor.md) for Cursor IDE troubleshooting.
---
## Still stuck?
Open an issue at [github.com/OthmanAdi/planning-with-files/issues](https://github.com/OthmanAdi/planning-with-files/issues) with:
- Your Claude Code version (`claude --version`)
- Your operating system
- The command you ran
- What happened vs what you expected
- Any error messages

139
skills/planning-with-files/docs/windows.md Normal file
View File

@@ -0,0 +1,139 @@
# Windows Setup
Windows-specific installation and usage notes.
---
## Installation on Windows
### Via winget (Recommended)
Claude Code supports Windows Package Manager:
```powershell
winget install Anthropic.ClaudeCode
```
Then install the skill:
```
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files
```
### Manual Installation
```powershell
# Create plugins directory
mkdir -p $env:USERPROFILE\.claude\plugins
# Clone the repository
git clone https://github.com/OthmanAdi/planning-with-files.git $env:USERPROFILE\.claude\plugins\planning-with-files
```
### Skills Only
```powershell
git clone https://github.com/OthmanAdi/planning-with-files.git
Copy-Item -Recurse planning-with-files\skills\* $env:USERPROFILE\.claude\skills\
```
---
## Path Differences
| Unix/macOS | Windows |
|------------|---------|
| `~/.claude/skills/` | `%USERPROFILE%\.claude\skills\` |
| `~/.claude/plugins/` | `%USERPROFILE%\.claude\plugins\` |
| `.claude/plugins/` | `.claude\plugins\` |
---
## Shell Script Compatibility
The helper scripts (`init-session.sh`, `check-complete.sh`) are bash scripts.
### Option 1: Use Git Bash
If you have Git for Windows installed, run scripts in Git Bash:
```bash
./scripts/init-session.sh
```
### Option 2: Use WSL
```bash
wsl ./scripts/init-session.sh
```
### Option 3: Manual alternative
Instead of running scripts, manually create the files:
```powershell
# Copy templates to current directory
Copy-Item templates\task_plan.md .
Copy-Item templates\findings.md .
Copy-Item templates\progress.md .
```
---
## Hook Commands
The hooks use Unix-style commands. On Windows with Claude Code:
- Hooks run in a Unix-compatible shell environment
- Commands like `cat`, `head`, `echo` work automatically
- No changes needed to the skill configuration
---
## Common Windows Issues
### Path separators
If you see path errors, ensure you're using the correct separator:
```powershell
# Windows
$env:USERPROFILE\.claude\skills\
# Not Unix-style
~/.claude/skills/
```
### Line endings
If templates appear corrupted, check line endings:
```powershell
# Convert to Windows line endings if needed
(Get-Content template.md) | Set-Content -Encoding UTF8 template.md
```
### Permission errors
Run PowerShell as Administrator if you get permission errors:
```powershell
# Right-click PowerShell → Run as Administrator
```
---
## Terminal Recommendations
For best experience on Windows:
1. **Windows Terminal** - Modern terminal with good Unicode support
2. **Git Bash** - Unix-like environment on Windows
3. **WSL** - Full Linux environment
---
## Need Help?
Open an issue at [github.com/OthmanAdi/planning-with-files/issues](https://github.com/OthmanAdi/planning-with-files/issues).

209
skills/planning-with-files/docs/workflow.md Normal file
View File

@@ -0,0 +1,209 @@
# Workflow Diagram
This diagram shows how the three files work together and how hooks interact with them.
---
## Visual Workflow
```
┌─────────────────────────────────────────────────────────────────┐
│ TASK START │
│ User requests a complex task (>5 tool calls expected) │
└────────────────────────┬────────────────────────────────────────┘
│
▼
┌───────────────────────────────┐
│ STEP 1: Create task_plan.md │
│ (NEVER skip this step!) │
└───────────────┬───────────────┘
│
▼
┌───────────────────────────────┐
│ STEP 2: Create findings.md │
│ STEP 3: Create progress.md │
└───────────────┬───────────────┘
│
▼
┌────────────────────────────────────────────┐
│ WORK LOOP (Iterative) │
│ │
│ ┌──────────────────────────────────────┐ │
│ │ PreToolUse Hook (Automatic) │ │
│ │ → Reads task_plan.md before │ │
│ │ Write/Edit/Bash operations │ │
│ │ → Refreshes goals in attention │ │
│ └──────────────┬───────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ Perform work (tool calls) │ │
│ │ - Research → Update findings.md │ │
│ │ - Implement → Update progress.md │ │
│ │ - Make decisions → Update both │ │
│ └──────────────┬───────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ PostToolUse Hook (Automatic) │ │
│ │ → Reminds to update task_plan.md │ │
│ │ if phase completed │ │
│ └──────────────┬───────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ After 2 view/browser operations: │ │
│ │ → MUST update findings.md │ │
│ │ (2-Action Rule) │ │
│ └──────────────┬───────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ After completing a phase: │ │
│ │ → Update task_plan.md status │ │
│ │ → Update progress.md with details │ │
│ └──────────────┬───────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ If error occurs: │ │
│ │ → Log in task_plan.md │ │
│ │ → Log in progress.md │ │
│ │ → Document resolution │ │
│ └──────────────┬───────────────────────┘ │
│ │ │
│ └──────────┐ │
│ │ │
│ ▼ │
│ ┌──────────────────────┐ │
│ │ More work to do? │ │
│ └──────┬───────────────┘ │
│ │ │
│ YES ───┘ │
│ │ │
│ └──────────┐ │
│ │ │
└─────────────────────────┘ │
│
NO │
│ │
▼ │
┌──────────────────────────────────────┐
│ Stop Hook (Automatic) │
│ → Checks if all phases complete │
│ → Verifies task_plan.md status │
└──────────────┬───────────────────────┘
│
▼
┌──────────────────────────────────────┐
│ All phases complete? │
└──────────────┬───────────────────────┘
│
┌──────────┴──────────┐
│ │
YES NO
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ TASK COMPLETE │ │ Continue work │
│ Deliver files │ │ (back to loop) │
└─────────────────┘ └─────────────────┘
```
---
## Key Interactions
### Hooks
| Hook | When It Fires | What It Does |
|------|---------------|--------------|
| **SessionStart** | When Claude Code session begins | Notifies skill is ready |
| **PreToolUse** | Before Write/Edit/Bash operations | Reads `task_plan.md` to refresh goals |
| **PostToolUse** | After Write/Edit operations | Reminds to update phase status |
| **Stop** | When Claude tries to stop | Verifies all phases are complete |
### The 2-Action Rule
After every 2 view/browser/search operations, you MUST update `findings.md`.
```
Operation 1: WebSearch → Note results
Operation 2: WebFetch → MUST UPDATE findings.md NOW
Operation 3: Read file → Note findings
Operation 4: Grep search → MUST UPDATE findings.md NOW
```
### Phase Completion
When a phase is complete:
1. Update `task_plan.md`:
- Change status: `in_progress` → `complete`
- Mark checkboxes: `[ ]` → `[x]`
2. Update `progress.md`:
- Log actions taken
- List files created/modified
- Note any issues encountered
### Error Handling
When an error occurs:
1. Log in `task_plan.md` → Errors Encountered table
2. Log in `progress.md` → Error Log with timestamp
3. Document the resolution
4. Never repeat the same failed action
---
## File Relationships
```
┌─────────────────────────────────────────────────────────────────┐
│ task_plan.md │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Goal: What you're trying to achieve │ │
│ │ Phases: 3-7 steps with status tracking │ │
│ │ Decisions: Major choices made │ │
│ │ Errors: Problems encountered │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ PreToolUse hook reads this │
│ before every Write/Edit/Bash │
└─────────────────────────────────────────────────────────────────┘
│
┌────────────────────┼────────────────────┐
│ │ │
▼ │ ▼
┌─────────────────┐ │ ┌─────────────────┐
│ findings.md │ │ │ progress.md │
│ │ │ │ │
│ Research │◄───────────┘ │ Session log │
│ Discoveries │ │ Actions taken │
│ Tech decisions │ │ Test results │
│ Resources │ │ Error log │
└─────────────────┘ └─────────────────┘
```
---
## The 5-Question Reboot Test
If you can answer these questions, your context management is solid:
| Question | Answer Source |
|----------|---------------|
| Where am I? | Current phase in `task_plan.md` |
| Where am I going? | Remaining phases in `task_plan.md` |
| What's the goal? | Goal statement in `task_plan.md` |
| What have I learned? | `findings.md` |
| What have I done? | `progress.md` |
---
## Next Steps
- [Quick Start Guide](quickstart.md) - Step-by-step tutorial
- [Troubleshooting](troubleshooting.md) - Common issues and solutions

635
skills/planning-with-files/examples/README.md Normal file
View File

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

234
skills/planning-with-files/planning-with-files/SKILL.md Normal file
View File

@@ -0,0 +1,234 @@
---
name: planning-with-files
version: "2.3.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: |
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"
else
bash "${CLAUDE_PLUGIN_ROOT}/scripts/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
# Claude Code users
python3 ~/.claude/skills/planning-with-files/scripts/session-catchup.py "$(pwd)"
# Codex users
python3 ~/.codex/skills/planning-with-files/scripts/session-catchup.py "$(pwd)"
# Cursor users
python3 ~/.cursor/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
## Important: Where Files Go
**Templates location (based on your IDE):**
- Claude Code: `~/.claude/skills/planning-with-files/templates/`
- Codex: `~/.codex/skills/planning-with-files/templates/`
- Cursor: `~/.cursor/skills/planning-with-files/templates/`
**Your planning files** go in **your project directory**
| Location | What Goes There |
|----------|-----------------|
| Skill directory (`~/.claude/skills/planning-with-files/` or `~/.codex/skills/planning-with-files/`) | 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 |

202
skills/planning-with-files/planning-with-files/examples.md Normal file
View File

@@ -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.

218
skills/planning-with-files/planning-with-files/reference.md Normal file
View File

@@ -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

42
skills/planning-with-files/planning-with-files/scripts/check-complete.ps1 Normal file
View File

@@ -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
}

44
skills/planning-with-files/planning-with-files/scripts/check-complete.sh Normal file
View File

@@ -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

120
skills/planning-with-files/planning-with-files/scripts/init-session.ps1 Normal file
View File

@@ -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"

120
skills/planning-with-files/planning-with-files/scripts/init-session.sh Normal file
View File

@@ -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"

208
skills/planning-with-files/planning-with-files/scripts/session-catchup.py Executable file
View File

@@ -0,0 +1,208 @@
#!/usr/bin/env python3
"""
Session Catchup Script for planning-with-files
Analyzes the previous session to find unsynced context after the last
planning file update. Designed to run on SessionStart.
Usage: python3 session-catchup.py [project-path]
"""
import json
import sys
import os
from pathlib import Path
from typing import List, Dict, Optional, Tuple
from datetime import datetime
PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
def get_project_dir(project_path: str) -> Path:
"""Convert project path to Claude's storage path format."""
sanitized = project_path.replace('/', '-')
if not sanitized.startswith('-'):
sanitized = '-' + sanitized
sanitized = sanitized.replace('_', '-')
return Path.home() / '.claude' / 'projects' / sanitized
def get_sessions_sorted(project_dir: Path) -> List[Path]:
"""Get all session files sorted by modification time (newest first)."""
sessions = list(project_dir.glob('*.jsonl'))
main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
def parse_session_messages(session_file: Path) -> List[Dict]:
"""Parse all messages from a session file, preserving order."""
messages = []
with open(session_file, 'r') as f:
for line_num, line in enumerate(f):
try:
data = json.loads(line)
data['_line_num'] = line_num
messages.append(data)
except json.JSONDecodeError:
pass
return messages
def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
"""
Find the last time a planning file was written/edited.
Returns (line_number, filename) or (-1, None) if not found.
"""
last_update_line = -1
last_update_file = None
for msg in messages:
msg_type = msg.get('type')
if msg_type == 'assistant':
content = msg.get('message', {}).get('content', [])
if isinstance(content, list):
for item in content:
if item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if tool_name in ('Write', 'Edit'):
file_path = tool_input.get('file_path', '')
for pf in PLANNING_FILES:
if file_path.endswith(pf):
last_update_line = msg['_line_num']
last_update_file = pf
return last_update_line, last_update_file
def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
"""Extract conversation messages after a certain line number."""
result = []
for msg in messages:
if msg['_line_num'] <= after_line:
continue
msg_type = msg.get('type')
is_meta = msg.get('isMeta', False)
if msg_type == 'user' and not is_meta:
content = msg.get('message', {}).get('content', '')
if isinstance(content, list):
for item in content:
if isinstance(item, dict) and item.get('type') == 'text':
content = item.get('text', '')
break
else:
content = ''
if content and isinstance(content, str):
if content.startswith(('<local-command', '<command-', '<task-notification')):
continue
if len(content) > 20:
result.append({'role': 'user', 'content': content, 'line': msg['_line_num']})
elif msg_type == 'assistant':
msg_content = msg.get('message', {}).get('content', '')
text_content = ''
tool_uses = []
if isinstance(msg_content, str):
text_content = msg_content
elif isinstance(msg_content, list):
for item in msg_content:
if item.get('type') == 'text':
text_content = item.get('text', '')
elif item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if tool_name == 'Edit':
tool_uses.append(f"Edit: {tool_input.get('file_path', 'unknown')}")
elif tool_name == 'Write':
tool_uses.append(f"Write: {tool_input.get('file_path', 'unknown')}")
elif tool_name == 'Bash':
cmd = tool_input.get('command', '')[:80]
tool_uses.append(f"Bash: {cmd}")
else:
tool_uses.append(f"{tool_name}")
if text_content or tool_uses:
result.append({
'role': 'assistant',
'content': text_content[:600] if text_content else '',
'tools': tool_uses,
'line': msg['_line_num']
})
return result
def main():
project_path = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()
project_dir = get_project_dir(project_path)
# Check if planning files exist (indicates active task)
has_planning_files = any(
Path(project_path, f).exists() for f in PLANNING_FILES
)
if not project_dir.exists():
# No previous sessions, nothing to catch up on
return
sessions = get_sessions_sorted(project_dir)
if len(sessions) < 1:
return
# Find a substantial previous session
target_session = None
for session in sessions:
if session.stat().st_size > 5000:
target_session = session
break
if not target_session:
return
messages = parse_session_messages(target_session)
last_update_line, last_update_file = find_last_planning_update(messages)
# Only output if there's unsynced content
if last_update_line < 0:
messages_after = extract_messages_after(messages, len(messages) - 30)
else:
messages_after = extract_messages_after(messages, last_update_line)
if not messages_after:
return
# Output catchup report
print("\n[planning-with-files] SESSION CATCHUP DETECTED")
print(f"Previous session: {target_session.stem}")
if last_update_line >= 0:
print(f"Last planning update: {last_update_file} at message #{last_update_line}")
print(f"Unsynced messages: {len(messages_after)}")
else:
print("No planning file updates found in previous session")
print("\n--- UNSYNCED CONTEXT ---")
for msg in messages_after[-15:]: # Last 15 messages
if msg['role'] == 'user':
print(f"USER: {msg['content'][:300]}")
else:
if msg.get('content'):
print(f"CLAUDE: {msg['content'][:300]}")
if msg.get('tools'):
print(f" Tools: {', '.join(msg['tools'][:4])}")
print("\n--- RECOMMENDED ---")
print("1. Run: git diff --stat")
print("2. Read: task_plan.md, progress.md, findings.md")
print("3. Update planning files based on above context")
print("4. Continue with task")
if __name__ == '__main__':
main()

95
skills/planning-with-files/planning-with-files/templates/findings.md Normal file
View File

@@ -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*

114
skills/planning-with-files/planning-with-files/templates/progress.md Normal file
View File

@@ -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*

132
skills/planning-with-files/planning-with-files/templates/task_plan.md Normal file
View File

@@ -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

42
skills/planning-with-files/scripts/check-complete.ps1 Normal file
View File

@@ -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
}

44
skills/planning-with-files/scripts/check-complete.sh Normal file
View File

@@ -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

120
skills/planning-with-files/scripts/init-session.ps1 Normal file
View File

@@ -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"

120
skills/planning-with-files/scripts/init-session.sh Normal file
View File

@@ -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"

278
skills/planning-with-files/scripts/session-catchup.py Executable file
View File

@@ -0,0 +1,278 @@
#!/usr/bin/env python3
"""
Session Catchup Script for planning-with-files
Session-agnostic scanning: finds the most recent planning file update across
ALL sessions, then collects all conversation from that point forward through
all subsequent sessions until now.
Usage: python3 session-catchup.py [project-path]
"""
import json
import sys
import os
from pathlib import Path
from typing import List, Dict, Optional, Tuple
PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
def get_project_dir(project_path: str) -> Path:
"""Convert project path to Claude's storage path format."""
sanitized = project_path.replace('/', '-')
if not sanitized.startswith('-'):
sanitized = '-' + sanitized
sanitized = sanitized.replace('_', '-')
return Path.home() / '.claude' / 'projects' / sanitized
def get_sessions_sorted(project_dir: Path) -> List[Path]:
"""Get all session files sorted by modification time (newest first)."""
sessions = list(project_dir.glob('*.jsonl'))
main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
def get_session_first_timestamp(session_file: Path) -> Optional[str]:
"""Get the timestamp of the first message in a session."""
try:
with open(session_file, 'r') as f:
for line in f:
try:
data = json.loads(line)
ts = data.get('timestamp')
if ts:
return ts
except:
continue
except:
pass
return None
def scan_for_planning_update(session_file: Path) -> Tuple[int, Optional[str]]:
"""
Quickly scan a session file for planning file updates.
Returns (line_number, filename) of last update, or (-1, None) if none found.
"""
last_update_line = -1
last_update_file = None
try:
with open(session_file, 'r') as f:
for line_num, line in enumerate(f):
if '"Write"' not in line and '"Edit"' not in line:
continue
try:
data = json.loads(line)
if data.get('type') != 'assistant':
continue
content = data.get('message', {}).get('content', [])
if not isinstance(content, list):
continue
for item in content:
if item.get('type') != 'tool_use':
continue
tool_name = item.get('name', '')
if tool_name not in ('Write', 'Edit'):
continue
file_path = item.get('input', {}).get('file_path', '')
for pf in PLANNING_FILES:
if file_path.endswith(pf):
last_update_line = line_num
last_update_file = pf
break
except json.JSONDecodeError:
continue
except Exception:
pass
return last_update_line, last_update_file
def extract_messages_from_session(session_file: Path, after_line: int = -1) -> List[Dict]:
"""
Extract conversation messages from a session file.
If after_line >= 0, only extract messages after that line.
If after_line < 0, extract all messages.
"""
result = []
try:
with open(session_file, 'r') as f:
for line_num, line in enumerate(f):
if after_line >= 0 and line_num <= after_line:
continue
try:
msg = json.loads(line)
except json.JSONDecodeError:
continue
msg_type = msg.get('type')
is_meta = msg.get('isMeta', False)
if msg_type == 'user' and not is_meta:
content = msg.get('message', {}).get('content', '')
if isinstance(content, list):
for item in content:
if isinstance(item, dict) and item.get('type') == 'text':
content = item.get('text', '')
break
else:
content = ''
if content and isinstance(content, str):
# Skip system/command messages
if content.startswith(('<local-command', '<command-', '<task-notification')):
continue
if len(content) > 20:
result.append({
'role': 'user',
'content': content,
'line': line_num,
'session': session_file.stem[:8]
})
elif msg_type == 'assistant':
msg_content = msg.get('message', {}).get('content', '')
text_content = ''
tool_uses = []
if isinstance(msg_content, str):
text_content = msg_content
elif isinstance(msg_content, list):
for item in msg_content:
if item.get('type') == 'text':
text_content = item.get('text', '')
elif item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if tool_name == 'Edit':
tool_uses.append(f"Edit: {tool_input.get('file_path', 'unknown')}")
elif tool_name == 'Write':
tool_uses.append(f"Write: {tool_input.get('file_path', 'unknown')}")
elif tool_name == 'Bash':
cmd = tool_input.get('command', '')[:80]
tool_uses.append(f"Bash: {cmd}")
elif tool_name == 'AskUserQuestion':
tool_uses.append("AskUserQuestion")
else:
tool_uses.append(f"{tool_name}")
if text_content or tool_uses:
result.append({
'role': 'assistant',
'content': text_content[:600] if text_content else '',
'tools': tool_uses,
'line': line_num,
'session': session_file.stem[:8]
})
except Exception:
pass
return result
def main():
project_path = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()
project_dir = get_project_dir(project_path)
if not project_dir.exists():
return
sessions = get_sessions_sorted(project_dir)
if len(sessions) < 2:
return
# Skip the current session (most recently modified = index 0)
previous_sessions = sessions[1:]
# Find the most recent planning file update across ALL previous sessions
# Sessions are sorted newest first, so we scan in order
update_session = None
update_line = -1
update_file = None
update_session_idx = -1
for idx, session in enumerate(previous_sessions):
line, filename = scan_for_planning_update(session)
if line >= 0:
update_session = session
update_line = line
update_file = filename
update_session_idx = idx
break
if not update_session:
# No planning file updates found in any previous session
return
# Collect ALL messages from the update point forward, across all sessions
all_messages = []
# 1. Get messages from the session with the update (after the update line)
messages_from_update_session = extract_messages_from_session(update_session, after_line=update_line)
all_messages.extend(messages_from_update_session)
# 2. Get ALL messages from sessions between update_session and current
# These are sessions[1:update_session_idx] (newer than update_session)
intermediate_sessions = previous_sessions[:update_session_idx]
# Process from oldest to newest for correct chronological order
for session in reversed(intermediate_sessions):
messages = extract_messages_from_session(session, after_line=-1) # Get all messages
all_messages.extend(messages)
if not all_messages:
return
# Output catchup report
print("\n[planning-with-files] SESSION CATCHUP DETECTED")
print(f"Last planning update: {update_file} in session {update_session.stem[:8]}...")
sessions_covered = update_session_idx + 1
if sessions_covered > 1:
print(f"Scanning {sessions_covered} sessions for unsynced context")
print(f"Unsynced messages: {len(all_messages)}")
print("\n--- UNSYNCED CONTEXT ---")
# Show up to 100 messages
MAX_MESSAGES = 100
if len(all_messages) > MAX_MESSAGES:
print(f"(Showing last {MAX_MESSAGES} of {len(all_messages)} messages)\n")
messages_to_show = all_messages[-MAX_MESSAGES:]
else:
messages_to_show = all_messages
current_session = None
for msg in messages_to_show:
# Show session marker when it changes
if msg.get('session') != current_session:
current_session = msg.get('session')
print(f"\n[Session: {current_session}...]")
if msg['role'] == 'user':
print(f"USER: {msg['content'][:300]}")
else:
if msg.get('content'):
print(f"CLAUDE: {msg['content'][:300]}")
if msg.get('tools'):
print(f" Tools: {', '.join(msg['tools'][:4])}")
print("\n--- RECOMMENDED ---")
print("1. Run: git diff --stat")
print("2. Read: task_plan.md, progress.md, findings.md")
print("3. Update planning files based on above context")
print("4. Continue with task")
if __name__ == '__main__':
main()

223
skills/planning-with-files/skills/planning-with-files/SKILL.md Normal file
View File

@@ -0,0 +1,223 @@
---
name: planning-with-files
version: "2.3.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: |
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"
else
bash "${CLAUDE_PLUGIN_ROOT}/scripts/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
python3 ${CLAUDE_PLUGIN_ROOT}/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
## 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 |

202
skills/planning-with-files/skills/planning-with-files/examples.md Normal file
View File

@@ -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.

218
skills/planning-with-files/skills/planning-with-files/reference.md Normal file
View File

@@ -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

42
skills/planning-with-files/skills/planning-with-files/scripts/check-complete.ps1 Normal file
View File

@@ -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
}

44
skills/planning-with-files/skills/planning-with-files/scripts/check-complete.sh Normal file
View File

@@ -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

120
skills/planning-with-files/skills/planning-with-files/scripts/init-session.ps1 Normal file
View File

@@ -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"

120
skills/planning-with-files/skills/planning-with-files/scripts/init-session.sh Normal file
View File

@@ -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"

208
skills/planning-with-files/skills/planning-with-files/scripts/session-catchup.py Executable file
View File

@@ -0,0 +1,208 @@
#!/usr/bin/env python3
"""
Session Catchup Script for planning-with-files
Analyzes the previous session to find unsynced context after the last
planning file update. Designed to run on SessionStart.
Usage: python3 session-catchup.py [project-path]
"""
import json
import sys
import os
from pathlib import Path
from typing import List, Dict, Optional, Tuple
from datetime import datetime
PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
def get_project_dir(project_path: str) -> Path:
"""Convert project path to Claude's storage path format."""
sanitized = project_path.replace('/', '-')
if not sanitized.startswith('-'):
sanitized = '-' + sanitized
sanitized = sanitized.replace('_', '-')
return Path.home() / '.claude' / 'projects' / sanitized
def get_sessions_sorted(project_dir: Path) -> List[Path]:
"""Get all session files sorted by modification time (newest first)."""
sessions = list(project_dir.glob('*.jsonl'))
main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
def parse_session_messages(session_file: Path) -> List[Dict]:
"""Parse all messages from a session file, preserving order."""
messages = []
with open(session_file, 'r') as f:
for line_num, line in enumerate(f):
try:
data = json.loads(line)
data['_line_num'] = line_num
messages.append(data)
except json.JSONDecodeError:
pass
return messages
def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
"""
Find the last time a planning file was written/edited.
Returns (line_number, filename) or (-1, None) if not found.
"""
last_update_line = -1
last_update_file = None
for msg in messages:
msg_type = msg.get('type')
if msg_type == 'assistant':
content = msg.get('message', {}).get('content', [])
if isinstance(content, list):
for item in content:
if item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if tool_name in ('Write', 'Edit'):
file_path = tool_input.get('file_path', '')
for pf in PLANNING_FILES:
if file_path.endswith(pf):
last_update_line = msg['_line_num']
last_update_file = pf
return last_update_line, last_update_file
def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
"""Extract conversation messages after a certain line number."""
result = []
for msg in messages:
if msg['_line_num'] <= after_line:
continue
msg_type = msg.get('type')
is_meta = msg.get('isMeta', False)
if msg_type == 'user' and not is_meta:
content = msg.get('message', {}).get('content', '')
if isinstance(content, list):
for item in content:
if isinstance(item, dict) and item.get('type') == 'text':
content = item.get('text', '')
break
else:
content = ''
if content and isinstance(content, str):
if content.startswith(('<local-command', '<command-', '<task-notification')):
continue
if len(content) > 20:
result.append({'role': 'user', 'content': content, 'line': msg['_line_num']})
elif msg_type == 'assistant':
msg_content = msg.get('message', {}).get('content', '')
text_content = ''
tool_uses = []
if isinstance(msg_content, str):
text_content = msg_content
elif isinstance(msg_content, list):
for item in msg_content:
if item.get('type') == 'text':
text_content = item.get('text', '')
elif item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if tool_name == 'Edit':
tool_uses.append(f"Edit: {tool_input.get('file_path', 'unknown')}")
elif tool_name == 'Write':
tool_uses.append(f"Write: {tool_input.get('file_path', 'unknown')}")
elif tool_name == 'Bash':
cmd = tool_input.get('command', '')[:80]
tool_uses.append(f"Bash: {cmd}")
else:
tool_uses.append(f"{tool_name}")
if text_content or tool_uses:
result.append({
'role': 'assistant',
'content': text_content[:600] if text_content else '',
'tools': tool_uses,
'line': msg['_line_num']
})
return result
def main():
project_path = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()
project_dir = get_project_dir(project_path)
# Check if planning files exist (indicates active task)
has_planning_files = any(
Path(project_path, f).exists() for f in PLANNING_FILES
)
if not project_dir.exists():
# No previous sessions, nothing to catch up on
return
sessions = get_sessions_sorted(project_dir)
if len(sessions) < 1:
return
# Find a substantial previous session
target_session = None
for session in sessions:
if session.stat().st_size > 5000:
target_session = session
break
if not target_session:
return
messages = parse_session_messages(target_session)
last_update_line, last_update_file = find_last_planning_update(messages)
# Only output if there's unsynced content
if last_update_line < 0:
messages_after = extract_messages_after(messages, len(messages) - 30)
else:
messages_after = extract_messages_after(messages, last_update_line)
if not messages_after:
return
# Output catchup report
print("\n[planning-with-files] SESSION CATCHUP DETECTED")
print(f"Previous session: {target_session.stem}")
if last_update_line >= 0:
print(f"Last planning update: {last_update_file} at message #{last_update_line}")
print(f"Unsynced messages: {len(messages_after)}")
else:
print("No planning file updates found in previous session")
print("\n--- UNSYNCED CONTEXT ---")
for msg in messages_after[-15:]: # Last 15 messages
if msg['role'] == 'user':
print(f"USER: {msg['content'][:300]}")
else:
if msg.get('content'):
print(f"CLAUDE: {msg['content'][:300]}")
if msg.get('tools'):
print(f" Tools: {', '.join(msg['tools'][:4])}")
print("\n--- RECOMMENDED ---")
print("1. Run: git diff --stat")
print("2. Read: task_plan.md, progress.md, findings.md")
print("3. Update planning files based on above context")
print("4. Continue with task")
if __name__ == '__main__':
main()

95
skills/planning-with-files/skills/planning-with-files/templates/findings.md Normal file
View File

@@ -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*

114
skills/planning-with-files/skills/planning-with-files/templates/progress.md Normal file
View File

@@ -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*

132
skills/planning-with-files/skills/planning-with-files/templates/task_plan.md Normal file
View File

@@ -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

95
skills/planning-with-files/templates/findings.md Normal file
View File

@@ -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*

114
skills/planning-with-files/templates/progress.md Normal file
View File

@@ -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*

132
skills/planning-with-files/templates/task_plan.md Normal file
View File

@@ -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