Compare commits

...
41 Commits
Author SHA1 Message Date
OthmanAdi 9fc3f3ff28 Update README for v2.15.0 release
- Added /plan:status command to commands table
- Updated version badge and release table
- Listed v2.15.0 highlights: status command + OpenCode fix
2026-02-08 16:06:50 +01:00
OthmanAdi 0c1ddd21c3 Fix OpenCode compatibility - detect IDE and show helpful message
OpenCode uses different session storage (.json at ~/.local/share/opencode/) than Claude Code (.jsonl at ~/.claude/projects/). Session catchup now detects the IDE and provides a clear workaround message instead of silently failing.

- Added IDE detection (checks env vars and directory structure)
- OpenCode users get helpful message to manually read planning files
- Claude Code functionality unchanged
- Updated OpenCode docs with known limitations section

Fixes #74
2026-02-08 16:05:59 +01:00
jonthebeef a233b1b430 Add /plan:status command for quick progress check
Adds visual status display with emoji icons, phase progress tracking, and error logging count. Thanks @jonthebeef for this thoughtful contribution!
2026-02-08 16:03:28 +01:00
OthmanAdi 61e6165e2f Move Supported IDEs to top collapsible section
- Moved to top with other collapsible sections
- Removed duplicate from original location
2026-02-06 15:17:32 +01:00
OthmanAdi 4e5084cde4 Make Supported IDEs section collapsible
- Added collapsible details/summary wrapper
- Header shows platform count (14 Platforms)
- Full table and legacy note preserved inside
2026-02-06 15:14:26 +01:00
OthmanAdi 0361bf17c4 Fix IDE-specific path references in SKILL.md files
- OpenCode: Replace CLAUDE_PLUGIN_ROOT with OPENCODE_SKILL_ROOT
- Kilocode: Replace CLAUDE_PLUGIN_ROOT with KILOCODE_SKILL_ROOT
- Cursor: Replace CLAUDE_PLUGIN_ROOT with CURSOR_SKILL_ROOT
- Update docs/opencode.md with oh-my-opencode configuration guide
- Add troubleshooting section for skill loading conflicts

Fixes #73
2026-02-06 15:10:12 +01:00
OthmanAdi abc11dd858 Consolidate Versions and Session Recovery into collapsible section
- New collapsible 'Releases & Session Recovery' section at top
- Shows key version highlights in compact table
- Session recovery info condensed with pro tip
- Removed duplicate sections from bottom of README
- Cleaner, more scannable layout
2026-02-06 14:57:01 +01:00
OthmanAdi c7e3b71bb8 Move Community Forks up and make both sections collapsible
- Thank You section now collapsible with attention-grabbing header
- Community Forks moved to top, collapsible with engaging header
- Added @ mention for RioTheGreat-ai
- Linked 'Open an issue' directly to issues page
2026-02-06 14:53:27 +01:00
Ahmad Othman Ammar Adi. 8adf37c6f8 Merge pull request #72 from RioTheGreat-ai/master 2026-02-06 13:35:16 +01:00
Ahmad Othman Ammar Adi. eb27664be1 Merge pull request #70 from codelyc/master 2026-02-06 13:34:36 +01:00
RioLabs ab208d9d92 Add AgentFund to community forks/extensions 2026-02-06 04:13:27 +00:00
codelyc 7082c7f41f fix: update codebuddy paths and codex usage docs
Change-Id: I28fb0e5f6a88427370ff1bd079c4951311be5815
2026-02-05 10:59:44 +08:00
OthmanAdi 8a49fdb03a Reorder README: prioritize value proposition and core concepts
Move Why This Skill, The Problem, The Solution, Manus Principles,
Usage, Key Rules, and When to Use sections above the fold.
Move IDE tables, Documentation, Session Recovery, and Versions
to the reference section at the bottom.
Remove redundant Kilo Code Support section (already in Supported IDEs table).
2026-02-04 23:40:44 +01:00
OthmanAdi 7f73508511 Add sync script for IDE folders, fix drift across 6 IDEs (fixes #53, #47)
Added scripts/sync-ide-folders.py — a maintainer tool that syncs shared
files (templates, scripts, references) from the canonical source
(skills/planning-with-files/) to all 13 IDE-specific folders.

Features:
- Preserves each IDE's unique structure and SKILL.md frontmatter
- Handles all structural variations (flat refs, subdir refs, asset dirs)
- Supports --dry-run (preview) and --verify (CI drift detection)
- Covers .cursor, .gemini, .codex, .openclaw, .kilocode, .adal, .pi,
  .continue, .codebuddy, .factory, .agent, .opencode, .kiro

First sync fixed drift in 6 IDE folders:
- .adal, .continue, .pi: updated session-catchup.py
- .continue: updated examples.md, reference.md
- .codebuddy: added missing templates/
- .gemini, .openclaw: added missing session-catchup.py

Thanks to @back1ply for proposing the deduplication approach (#53)
and @snowbedding for requesting Anthropic-style structure (#47).
2026-02-04 23:22:44 +01:00
OthmanAdi 0225360606 Rename .moltbot/ to .openclaw/, fix clawdhub-publish leak, add .gitignore entries
- Renamed .moltbot/ directory to .openclaw/ to match the OpenClaw rebrand
  (PR #65 only renamed docs/moltbot.md but missed the IDE directory)
- Updated SKILL.md metadata from moltbot to openclaw
- Removed accidentally committed clawdhub-publish/scripts/ from tracking
- Added clawdhub-publish/ and .claude/ to .gitignore
- Added .openclaw/ to README directory tree
2026-02-04 22:16:31 +01:00
OthmanAdi 0b033eb025 Add Cursor hooks support — preToolUse, postToolUse, stop (fixes #61)
Cursor now supports hooks natively via .cursor/hooks.json. Added:
- hooks.json config with preToolUse, postToolUse, and stop hooks
- Hook scripts in bash (.sh) and PowerShell (.ps1)
- hooks.windows.json for native PowerShell users
- Rewrote docs/cursor.md — removed "hooks don't work" limitation,
  documented full hook support including auto-continuation via stop hook
- Updated README Cursor format from "Skills" to "Skills + Hooks"

The stop hook is the highlight: it checks task_plan.md completion and
uses Cursor's followup_message to auto-continue the agent if phases
are incomplete (capped at 3 retries via loop_limit).

Thanks to @sulsDotK for reporting that Cursor now supports hooks.
2026-02-04 22:03:37 +01:00
OthmanAdi 9ec4d413b6 Fix incorrect plugin install command in README (fixes #59)
Changed from the non-existent `claude plugins install` command to the
correct slash command format: `/plugin marketplace add` followed by
`/plugin install`. Matches docs/installation.md and docs/troubleshooting.md.
2026-02-04 21:37:09 +01:00
OthmanAdi b96b42a9e5 Fix stop hook error, docs inconsistency, add Plan Cascade (fixes #68, #69)
- check-complete.sh/.ps1: Always exit 0 — incomplete task is a normal
  state, not an error. Uses stdout for informational status reporting.
  Fixes stop hook error in Claude Code. (#68)
- README.md, docs/quickstart.md: Clarify that the AI creates planning
  files (not the user manually). Align all docs on workflow. (#69)
- README.md: Add Plan Cascade by @Taoidle to Community Forks (#63)
- Updated all 21 check-complete script copies across IDE folders
2026-02-04 21:30:07 +01:00
OthmanAdi 16fd096f4f Fix check-complete scripts and kilocode docs (fixes #45, #62)
- check-complete.sh/.ps1: Add fallback for [complete] inline bracket
  status format in addition to existing **Status:** bold format
- Updated all 21 script copies across IDE folders
- docs/kilocode.md: Remove all references to non-existent
  .kilocode/rules/ directory (migrated to skills/ in v2.10.0)
- README.md: Update Kilo Code section to reference .kilocode/skills/
2026-02-04 21:22:53 +01:00
OthmanAdi 727fdfb72c Release v2.14.0 - Pi Agent support, Codex fix, OpenClaw docs
- Add Pi Agent integration (PR #67 by @ttttmr)
- Fix Codex skill path references (PR #66 by @codelyc)
- Update Moltbot docs to OpenClaw (PR #65 by @AZLabsAI, fixes #64)
- Update version badge to v2.14.0
- Update README: OpenClaw branding, version table
- Update CHANGELOG with v2.14.0 entry
2026-02-04 20:31:07 +01:00
Ahmad Othman Ammar Adi. b8274d23f8 Merge pull request #67 from ttttmr/master
Add Pi Agent support
2026-02-04 17:44:48 +01:00
Ahmad Othman Ammar Adi. 60e06093be Merge pull request #66 from codelyc/master
Fix codex skill path references
2026-02-04 17:40:52 +01:00
Ahmad Othman Ammar Adi. 7230d7f9d3 Merge pull request #65 from AZLabsAI/fix/moltbot-docs-openclaw-rename
docs: update moltbot.md to use OpenClaw naming and paths
2026-02-04 17:38:58 +01:00
linyuchiandClaude Sonnet 4.5 672e2515c2 Fix codex skill path references
- Update SKILL.md to use correct paths (~/.codex/skills/planning-with-files/)
- Replace CLAUDE_PLUGIN_ROOT references with absolute paths
- Add missing template files (findings.md, progress.md, task_plan.md)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Change-Id: I5b59bc1f54473f8af8c884b7c0cc1683de93a7ad
2026-02-04 19:32:31 +08:00
ttttmr 1089d65c60 Add Pi Agent support 2026-02-04 19:26:21 +08:00
TH33_ORACL3andCursor 28e89aae11 docs: rename moltbot.md to openclaw.md
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-03 19:21:37 +02:00
TH33_ORACL3andCursor cbf393a516 docs: update moltbot.md to use OpenClaw naming and paths
The product has been renamed from Moltbot to OpenClaw. This commit updates:

- Title and website link (molt.bot → openclaw.ai)
- Skills directory paths (~/.clawdbot/ → ~/.openclaw/)
- Config file path (moltbot.json → openclaw.json)
- CLI commands (moltbot → openclaw)
- All references to the product name

Fixes #64

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-03 19:20:33 +02:00
OthmanAdi c1a24568cd Update version badge to v2.13.0 2026-01-27 22:22:58 +01:00
OthmanAdi 92915d58ac Rebrand Clawd CLI to Moltbot (v2.13.0)
- Renamed .clawd/ to .moltbot/
- Renamed docs/clawd.md to docs/moltbot.md
- Updated all references: Clawd CLI → Moltbot
- Updated URLs: clawd.bot → molt.bot
- Updated CLI commands: clawdbot → moltbot
- Updated README badges, IDE table, documentation links
- Updated CHANGELOG
2026-01-27 22:21:41 +01:00
OthmanAdi a917aa1482 Fix AdaL SKILL.md format and update docs
- Simplified SKILL.md to match AdaL format (name + description only)
- Added /plugin marketplace installation method to docs/adal.md
- Added /skills and /plugin command documentation
- Fixed script paths in docs
- Added ZWkang to CONTRIBUTORS.md for CodeBuddy PR #60
2026-01-27 22:00:17 +01:00
OthmanAdi 76e954bc47 Add AdaL CLI / Sylph AI support (v2.12.0)
- Added .adal/skills/planning-with-files/ folder with full skill structure
- Created SKILL.md, templates, scripts, and references for AdaL
- Added docs/adal.md installation guide
- Updated README.md with AdaL in supported IDEs table
- Added AdaL CLI badge
2026-01-27 21:57:17 +01:00
kang f973f64864 Add CodeBuddy integration with planning-with-files skill (#60)
Thanks @ZWkang for this quality contribution! 🎉

Great work on:
- Full CodeBuddy integration with proper skill format
- Cross-platform scripts (Windows + Unix)
- Comprehensive documentation
- Clean, well-organized code

Welcome to the planning-with-files contributors! 🙌
2026-01-27 21:41:52 +01:00
OthmanAdi 76d46fdaf8 Add /plan command for easier autocomplete (v2.11.0)
- Added commands/plan.md for /planning-with-files:plan command
- Users can type /plan to find command in autocomplete
- Addresses Issue #39 and Discussion #36
- Updated README with new command table
- Updated CHANGELOG
2026-01-26 01:55:41 +01:00
OthmanAdi 539d5a3bbc Add Kiro support with native steering files (v2.10.0)
- Add .kiro/steering/ with planning-workflow.md, planning-rules.md, planning-templates.md
- Add .kiro/scripts/ with init and check-complete scripts
- Add docs/kiro.md installation guide
- Update README with Kiro badge and documentation
- Update plugin.json with Kiro keywords
- Now supports 11+ AI coding assistants

Closes #55
2026-01-26 01:40:15 +01:00
OthmanAdi 28c255f774 Add Clawd CLI support (v2.9.0)
- Add .clawd/skills/planning-with-files/ skill bundle
- Add docs/clawd.md installation guide
- Update README with Clawd badge and documentation
- Update plugin.json with new keywords for discoverability
- Update all SKILL.md versions to 2.9.0
- Now supports 10+ AI coding assistants
2026-01-26 01:14:37 +01:00
OthmanAdi 3dc1601319 Release v2.8.0 - Continue IDE support & POSIX sh fix
- Add Continue IDE integration (PR #56 by @murphyXu)
- Fix POSIX sh compatibility for Debian/Ubuntu (PR #57 by @SaladDay)
- Update all SKILL.md versions to 2.8.0
- Update CONTRIBUTORS.md with new contributors
- Update CHANGELOG.md with v2.8.0 release notes
2026-01-26 01:05:01 +01:00
Ahmad Othman Ammar Adi. 65dcd7e956 Merge pull request #56 from murphyXu/feat/continue-integration
Merging Continue IDE integration. Thank you @murphyXu for this contribution!
2026-01-26 01:01:16 +01:00
Ahmad Othman Ammar Adi. b16830f113 Merge pull request #57 from SaladDay/fix/stop-hook-posix-sh
Merging POSIX sh compatibility fix. Thank you @SaladDay for this contribution!
2026-01-26 01:01:03 +01:00
saladday 1c2dc407d1 Fix Stop hook for POSIX sh (dash) 2026-01-25 01:05:04 +08:00
mannaxu 4271a5425b Add Continue integration (skills + prompt)
- Add .continue/skills planning-with-files bundle

- Add .continue/prompts slash command (.prompt Markdown)

- Add docs/continue.md and README entry

- Add scripts/check-continue.sh validator
2026-01-24 01:55:49 +08:00
OthmanAdi 47dcfbb3f1 Fix dynamic Python command detection (v2.7.1)
- Replaced hardcoded python3 with: $(command -v python3 || command -v python)
- Added Windows PowerShell commands using python directly
- Fixed in all 5 IDE-specific SKILL.md files

Fixes #41
2026-01-22 14:37:09 +01:00
112 changed files with 11088 additions and 530 deletions
+175
View File
@@ -0,0 +1,175 @@
---
name: planning-with-files
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls.
---
# Planning with Files
Work like Manus: Use persistent markdown files as your "working memory on disk."
## Quick Start
Before ANY complex task:
1. **Create `task_plan.md`** — 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 (execute via bash):
- `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
To use scripts:
```bash
bash scripts/init-session.sh
bash scripts/check-complete.sh
python scripts/session-catchup.py $(pwd)
```
## Advanced Topics
- **Manus Principles:** See [references/reference.md](references/reference.md)
- **Real Examples:** See [references/examples.md](references/examples.md)
## Anti-Patterns
| Don't | Do Instead |
|-------|------------|
| Use TodoWrite for persistence | Create task_plan.md file |
| State goals once and forget | Re-read plan before decisions |
| Hide errors and retry silently | Log errors to plan file |
| Stuff everything in context | Store large content in files |
| Start executing immediately | Create plan file FIRST |
| Repeat failed actions | Track attempts, mutate approach |
| Create files in skill directory | Create files in your project |
@@ -0,0 +1,202 @@
# Examples: Planning with Files in Action
## Example 1: Research Task
**User Request:** "Research the benefits of morning exercise and write a summary"
### Loop 1: Create Plan
```bash
Write task_plan.md
```
```markdown
# Task Plan: Morning Exercise Benefits Research
## Goal
Create a research summary on the benefits of morning exercise.
## Phases
- [ ] Phase 1: Create this plan ✓
- [ ] Phase 2: Search and gather sources
- [ ] Phase 3: Synthesize findings
- [ ] Phase 4: Deliver summary
## Key Questions
1. What are the physical health benefits?
2. What are the mental health benefits?
3. What scientific studies support this?
## Status
**Currently in Phase 1** - Creating plan
```
### Loop 2: Research
```bash
Read task_plan.md # Refresh goals
WebSearch "morning exercise benefits"
Write notes.md # Store findings
Edit task_plan.md # Mark Phase 2 complete
```
### Loop 3: Synthesize
```bash
Read task_plan.md # Refresh goals
Read notes.md # Get findings
Write morning_exercise_summary.md
Edit task_plan.md # Mark Phase 3 complete
```
### Loop 4: Deliver
```bash
Read task_plan.md # Verify complete
Deliver morning_exercise_summary.md
```
---
## Example 2: Bug Fix Task
**User Request:** "Fix the login bug in the authentication module"
### task_plan.md
```markdown
# Task Plan: Fix Login Bug
## Goal
Identify and fix the bug preventing successful login.
## Phases
- [x] Phase 1: Understand the bug report ✓
- [x] Phase 2: Locate relevant code ✓
- [ ] Phase 3: Identify root cause (CURRENT)
- [ ] Phase 4: Implement fix
- [ ] Phase 5: Test and verify
## Key Questions
1. What error message appears?
2. Which file handles authentication?
3. What changed recently?
## Decisions Made
- Auth handler is in src/auth/login.ts
- Error occurs in validateToken() function
## Errors Encountered
- [Initial] TypeError: Cannot read property 'token' of undefined
→ Root cause: user object not awaited properly
## Status
**Currently in Phase 3** - Found root cause, preparing fix
```
---
## Example 3: Feature Development
**User Request:** "Add a dark mode toggle to the settings page"
### The 3-File Pattern in Action
**task_plan.md:**
```markdown
# Task Plan: Dark Mode Toggle
## Goal
Add functional dark mode toggle to settings.
## Phases
- [x] Phase 1: Research existing theme system ✓
- [x] Phase 2: Design implementation approach ✓
- [ ] Phase 3: Implement toggle component (CURRENT)
- [ ] Phase 4: Add theme switching logic
- [ ] Phase 5: Test and polish
## Decisions Made
- Using CSS custom properties for theme
- Storing preference in localStorage
- Toggle component in SettingsPage.tsx
## Status
**Currently in Phase 3** - Building toggle component
```
**notes.md:**
```markdown
# Notes: Dark Mode Implementation
## Existing Theme System
- Located in: src/styles/theme.ts
- Uses: CSS custom properties
- Current themes: light only
## Files to Modify
1. src/styles/theme.ts - Add dark theme colors
2. src/components/SettingsPage.tsx - Add toggle
3. src/hooks/useTheme.ts - Create new hook
4. src/App.tsx - Wrap with ThemeProvider
## Color Decisions
- Dark background: #1a1a2e
- Dark surface: #16213e
- Dark text: #eaeaea
```
**dark_mode_implementation.md:** (deliverable)
```markdown
# Dark Mode Implementation
## Changes Made
### 1. Added dark theme colors
File: src/styles/theme.ts
...
### 2. Created useTheme hook
File: src/hooks/useTheme.ts
...
```
---
## Example 4: Error Recovery Pattern
When something fails, DON'T hide it:
### Before (Wrong)
```
Action: Read config.json
Error: File not found
Action: Read config.json # Silent retry
Action: Read config.json # Another retry
```
### After (Correct)
```
Action: Read config.json
Error: File not found
# Update task_plan.md:
## Errors Encountered
- config.json not found → Will create default config
Action: Write config.json (default config)
Action: Read config.json
Success!
```
---
## The Read-Before-Decide Pattern
**Always read your plan before major decisions:**
```
[Many tool calls have happened...]
[Context is getting long...]
[Original goal might be forgotten...]
→ Read task_plan.md # This brings goals back into attention!
→ Now make the decision # Goals are fresh in context
```
This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a "goal refresh" mechanism.
@@ -0,0 +1,218 @@
# Reference: Manus Context Engineering Principles
This skill is based on context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
## The 6 Manus Principles
### Principle 1: Design Around KV-Cache
> "KV-cache hit rate is THE single most important metric for production AI agents."
**Statistics:**
- ~100:1 input-to-output token ratio
- Cached tokens: $0.30/MTok vs Uncached: $3/MTok
- 10x cost difference!
**Implementation:**
- Keep prompt prefixes STABLE (single-token change invalidates cache)
- NO timestamps in system prompts
- Make context APPEND-ONLY with deterministic serialization
### Principle 2: Mask, Don't Remove
Don't dynamically remove tools (breaks KV-cache). Use logit masking instead.
**Best Practice:** Use consistent action prefixes (e.g., `browser_`, `shell_`, `file_`) for easier masking.
### Principle 3: Filesystem as External Memory
> "Markdown is my 'working memory' on disk."
**The Formula:**
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
```
**Compression Must Be Restorable:**
- Keep URLs even if web content is dropped
- Keep file paths when dropping document contents
- Never lose the pointer to full data
### Principle 4: Manipulate Attention Through Recitation
> "Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."
**Problem:** After ~50 tool calls, models forget original goals ("lost in the middle" effect).
**Solution:** Re-read `task_plan.md` before each decision. Goals appear in the attention window.
```
Start of context: [Original goal - far away, forgotten]
...many tool calls...
End of context: [Recently read task_plan.md - gets ATTENTION!]
```
### Principle 5: Keep the Wrong Stuff In
> "Leave the wrong turns in the context."
**Why:**
- Failed actions with stack traces let model implicitly update beliefs
- Reduces mistake repetition
- Error recovery is "one of the clearest signals of TRUE agentic behavior"
### Principle 6: Don't Get Few-Shotted
> "Uniformity breeds fragility."
**Problem:** Repetitive action-observation pairs cause drift and hallucination.
**Solution:** Introduce controlled variation:
- Vary phrasings slightly
- Don't copy-paste patterns blindly
- Recalibrate on repetitive tasks
---
## The 3 Context Engineering Strategies
Based on Lance Martin's analysis of Manus architecture.
### Strategy 1: Context Reduction
**Compaction:**
```
Tool calls have TWO representations:
├── FULL: Raw tool content (stored in filesystem)
└── COMPACT: Reference/file path only
RULES:
- Apply compaction to STALE (older) tool results
- Keep RECENT results FULL (to guide next decision)
```
**Summarization:**
- Applied when compaction reaches diminishing returns
- Generated using full tool results
- Creates standardized summary objects
### Strategy 2: Context Isolation (Multi-Agent)
**Architecture:**
```
┌─────────────────────────────────┐
│ PLANNER AGENT │
│ └─ Assigns tasks to sub-agents │
├─────────────────────────────────┤
│ KNOWLEDGE MANAGER │
│ └─ Reviews conversations │
│ └─ Determines filesystem store │
├─────────────────────────────────┤
│ EXECUTOR SUB-AGENTS │
│ └─ Perform assigned tasks │
│ └─ Have own context windows │
└─────────────────────────────────┘
```
**Key Insight:** Manus originally used `todo.md` for task planning but found ~33% of actions were spent updating it. Shifted to dedicated planner agent calling executor sub-agents.
### Strategy 3: Context Offloading
**Tool Design:**
- Use <20 atomic functions total
- Store full results in filesystem, not context
- Use `glob` and `grep` for searching
- Progressive disclosure: load information only as needed
---
## The Agent Loop
Manus operates in a continuous 7-step loop:
```
┌─────────────────────────────────────────┐
│ 1. ANALYZE CONTEXT │
│ - Understand user intent │
│ - Assess current state │
│ - Review recent observations │
├─────────────────────────────────────────┤
│ 2. THINK │
│ - Should I update the plan? │
│ - What's the next logical action? │
│ - Are there blockers? │
├─────────────────────────────────────────┤
│ 3. SELECT TOOL │
│ - Choose ONE tool │
│ - Ensure parameters available │
├─────────────────────────────────────────┤
│ 4. EXECUTE ACTION │
│ - Tool runs in sandbox │
├─────────────────────────────────────────┤
│ 5. RECEIVE OBSERVATION │
│ - Result appended to context │
├─────────────────────────────────────────┤
│ 6. ITERATE │
│ - Return to step 1 │
│ - Continue until complete │
├─────────────────────────────────────────┤
│ 7. DELIVER OUTCOME │
│ - Send results to user │
│ - Attach all relevant files │
└─────────────────────────────────────────┘
```
---
## File Types Manus Creates
| File | Purpose | When Created | When Updated |
|------|---------|--------------|--------------|
| `task_plan.md` | Phase tracking, progress | Task start | After completing phases |
| `findings.md` | Discoveries, decisions | After ANY discovery | After viewing images/PDFs |
| `progress.md` | Session log, what's done | At breakpoints | Throughout session |
| Code files | Implementation | Before execution | After errors |
---
## Critical Constraints
- **Single-Action Execution:** ONE tool call per turn. No parallel execution.
- **Plan is Required:** Agent must ALWAYS know: goal, current phase, remaining phases
- **Files are Memory:** Context = volatile. Filesystem = persistent.
- **Never Repeat Failures:** If action failed, next action MUST be different
- **Communication is a Tool:** Message types: `info` (progress), `ask` (blocking), `result` (terminal)
---
## Manus Statistics
| Metric | Value |
|--------|-------|
| Average tool calls per task | ~50 |
| Input-to-output token ratio | 100:1 |
| Acquisition price | $2 billion |
| Time to $100M revenue | 8 months |
| Framework refactors since launch | 5 times |
---
## Key Quotes
> "Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."
> "if action_failed: next_action != same_action. Track what you tried. Mutate the approach."
> "Error recovery is one of the clearest signals of TRUE agentic behavior."
> "KV-cache hit rate is the single most important metric for a production-stage AI agent."
> "Leave the wrong turns in the context."
---
## Source
Based on Manus's official context engineering documentation:
https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
@@ -0,0 +1,44 @@
# Check if all phases in task_plan.md are complete
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
param(
[string]$PlanFile = "task_plan.md"
)
if (-not (Test-Path $PlanFile)) {
Write-Host "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
}
# Read file content
$content = Get-Content $PlanFile -Raw
# Count total phases
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
# Check for **Status:** format first
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
# Fallback: check for [complete] inline format if **Status:** not found
if ($COMPLETE -eq 0 -and $IN_PROGRESS -eq 0 -and $PENDING -eq 0) {
$COMPLETE = ([regex]::Matches($content, "\[complete\]")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\[in_progress\]")).Count
$PENDING = ([regex]::Matches($content, "\[pending\]")).Count
}
# Report status (always exit 0 — incomplete task is a normal state)
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
} else {
Write-Host "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if ($IN_PROGRESS -gt 0) {
Write-Host "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
}
if ($PENDING -gt 0) {
Write-Host "[planning-with-files] $PENDING phase(s) pending."
}
}
exit 0
@@ -0,0 +1,46 @@
#!/bin/bash
# Check if all phases in task_plan.md are complete
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
echo "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
fi
# Count total phases
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
# Check for **Status:** format first
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)
# Fallback: check for [complete] inline format if **Status:** not found
if [ "$COMPLETE" -eq 0 ] && [ "$IN_PROGRESS" -eq 0 ] && [ "$PENDING" -eq 0 ]; then
COMPLETE=$(grep -c "\[complete\]" "$PLAN_FILE" || true)
IN_PROGRESS=$(grep -c "\[in_progress\]" "$PLAN_FILE" || true)
PENDING=$(grep -c "\[pending\]" "$PLAN_FILE" || true)
fi
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
# Report status (always exit 0 — incomplete task is a normal state)
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
else
echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if [ "$IN_PROGRESS" -gt 0 ]; then
echo "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
fi
if [ "$PENDING" -gt 0 ]; then
echo "[planning-with-files] $PENDING phase(s) pending."
fi
fi
exit 0
@@ -0,0 +1,34 @@
#!/bin/bash
set -euo pipefail
missing=0
require_file() {
local path="$1"
if [ ! -f "$path" ]; then
echo "Missing: $path"
missing=1
fi
}
require_file ".continue/prompts/planning-with-files.prompt"
require_file ".continue/skills/planning-with-files/SKILL.md"
require_file ".continue/skills/planning-with-files/examples.md"
require_file ".continue/skills/planning-with-files/reference.md"
require_file ".continue/skills/planning-with-files/scripts/init-session.sh"
require_file ".continue/skills/planning-with-files/scripts/init-session.ps1"
require_file ".continue/skills/planning-with-files/scripts/check-complete.sh"
require_file ".continue/skills/planning-with-files/scripts/check-complete.ps1"
require_file ".continue/skills/planning-with-files/scripts/session-catchup.py"
if [ "$missing" -ne 0 ]; then
exit 1
fi
case ".continue/prompts/planning-with-files.prompt" in
*.prompt) ;;
*) echo "Prompt file must end with .prompt"; exit 1 ;;
esac
echo "Continue integration files look OK."
@@ -0,0 +1,120 @@
# Initialize planning files for a new session
# Usage: .\init-session.ps1 [project-name]
param(
[string]$ProjectName = "project"
)
$DATE = Get-Date -Format "yyyy-MM-dd"
Write-Host "Initializing planning files for: $ProjectName"
# Create task_plan.md if it doesn't exist
if (-not (Test-Path "task_plan.md")) {
@"
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
Write-Host "Created task_plan.md"
} else {
Write-Host "task_plan.md already exists, skipping"
}
# Create findings.md if it doesn't exist
if (-not (Test-Path "findings.md")) {
@"
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
"@ | Out-File -FilePath "findings.md" -Encoding UTF8
Write-Host "Created findings.md"
} else {
Write-Host "findings.md already exists, skipping"
}
# Create progress.md if it doesn't exist
if (-not (Test-Path "progress.md")) {
@"
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
Write-Host "Created progress.md"
} else {
Write-Host "progress.md already exists, skipping"
}
Write-Host ""
Write-Host "Planning files initialized!"
Write-Host "Files: task_plan.md, findings.md, progress.md"
@@ -0,0 +1,120 @@
#!/bin/bash
# Initialize planning files for a new session
# Usage: ./init-session.sh [project-name]
set -e
PROJECT_NAME="${1:-project}"
DATE=$(date +%Y-%m-%d)
echo "Initializing planning files for: $PROJECT_NAME"
# Create task_plan.md if it doesn't exist
if [ ! -f "task_plan.md" ]; then
cat > task_plan.md << 'EOF'
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
EOF
echo "Created task_plan.md"
else
echo "task_plan.md already exists, skipping"
fi
# Create findings.md if it doesn't exist
if [ ! -f "findings.md" ]; then
cat > findings.md << 'EOF'
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
EOF
echo "Created findings.md"
else
echo "findings.md already exists, skipping"
fi
# Create progress.md if it doesn't exist
if [ ! -f "progress.md" ]; then
cat > progress.md << EOF
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
EOF
echo "Created progress.md"
else
echo "progress.md already exists, skipping"
fi
echo ""
echo "Planning files initialized!"
echo "Files: task_plan.md, findings.md, progress.md"
@@ -0,0 +1,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()
@@ -0,0 +1,95 @@
# Findings & Decisions
<!--
WHAT: Your knowledge base for the task. Stores everything you discover and decide.
WHY: Context windows are limited. This file is your "external memory" - persistent and unlimited.
WHEN: Update after ANY discovery, especially after 2 view/browser/search operations (2-Action Rule).
-->
## Requirements
<!--
WHAT: What the user asked for, broken down into specific requirements.
WHY: Keeps requirements visible so you don't forget what you're building.
WHEN: Fill this in during Phase 1 (Requirements & Discovery).
EXAMPLE:
- Command-line interface
- Add tasks
- List all tasks
- Delete tasks
- Python implementation
-->
<!-- Captured from user request -->
-
## Research Findings
<!--
WHAT: Key discoveries from web searches, documentation reading, or exploration.
WHY: Multimodal content (images, browser results) doesn't persist. Write it down immediately.
WHEN: After EVERY 2 view/browser/search operations, update this section (2-Action Rule).
EXAMPLE:
- Python's argparse module supports subcommands for clean CLI design
- JSON module handles file persistence easily
- Standard pattern: python script.py <command> [args]
-->
<!-- Key discoveries during exploration -->
-
## Technical Decisions
<!--
WHAT: Architecture and implementation choices you've made, with reasoning.
WHY: You'll forget why you chose a technology or approach. This table preserves that knowledge.
WHEN: Update whenever you make a significant technical choice.
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
| argparse with subcommands | Clean CLI: python todo.py add "task" |
-->
<!-- Decisions made with rationale -->
| Decision | Rationale |
|----------|-----------|
| | |
## Issues Encountered
<!--
WHAT: Problems you ran into and how you solved them.
WHY: Similar to errors in task_plan.md, but focused on broader issues (not just code errors).
WHEN: Document when you encounter blockers or unexpected challenges.
EXAMPLE:
| Empty file causes JSONDecodeError | Added explicit empty file check before json.load() |
-->
<!-- Errors and how they were resolved -->
| Issue | Resolution |
|-------|------------|
| | |
## Resources
<!--
WHAT: URLs, file paths, API references, documentation links you've found useful.
WHY: Easy reference for later. Don't lose important links in context.
WHEN: Add as you discover useful resources.
EXAMPLE:
- Python argparse docs: https://docs.python.org/3/library/argparse.html
- Project structure: src/main.py, src/utils.py
-->
<!-- URLs, file paths, API references -->
-
## Visual/Browser Findings
<!--
WHAT: Information you learned from viewing images, PDFs, or browser results.
WHY: CRITICAL - Visual/multimodal content doesn't persist in context. Must be captured as text.
WHEN: IMMEDIATELY after viewing images or browser results. Don't wait!
EXAMPLE:
- Screenshot shows login form has email and password fields
- Browser shows API returns JSON with "status" and "data" keys
-->
<!-- CRITICAL: Update after every 2 view/browser operations -->
<!-- Multimodal content must be captured as text immediately -->
-
---
<!--
REMINDER: The 2-Action Rule
After every 2 view/browser/search operations, you MUST update this file.
This prevents visual information from being lost when context resets.
-->
*Update this file after every 2 view/browser/search operations*
*This prevents visual information from being lost*
@@ -0,0 +1,114 @@
# Progress Log
<!--
WHAT: Your session log - a chronological record of what you did, when, and what happened.
WHY: Answers "What have I done?" in the 5-Question Reboot Test. Helps you resume after breaks.
WHEN: Update after completing each phase or encountering errors. More detailed than task_plan.md.
-->
## Session: [DATE]
<!--
WHAT: The date of this work session.
WHY: Helps track when work happened, useful for resuming after time gaps.
EXAMPLE: 2026-01-15
-->
### Phase 1: [Title]
<!--
WHAT: Detailed log of actions taken during this phase.
WHY: Provides context for what was done, making it easier to resume or debug.
WHEN: Update as you work through the phase, or at least when you complete it.
-->
- **Status:** in_progress
- **Started:** [timestamp]
<!--
STATUS: Same as task_plan.md (pending, in_progress, complete)
TIMESTAMP: When you started this phase (e.g., "2026-01-15 10:00")
-->
- Actions taken:
<!--
WHAT: List of specific actions you performed.
EXAMPLE:
- Created todo.py with basic structure
- Implemented add functionality
- Fixed FileNotFoundError
-->
-
- Files created/modified:
<!--
WHAT: Which files you created or changed.
WHY: Quick reference for what was touched. Helps with debugging and review.
EXAMPLE:
- todo.py (created)
- todos.json (created by app)
- task_plan.md (updated)
-->
-
### Phase 2: [Title]
<!--
WHAT: Same structure as Phase 1, for the next phase.
WHY: Keep a separate log entry for each phase to track progress clearly.
-->
- **Status:** pending
- Actions taken:
-
- Files created/modified:
-
## Test Results
<!--
WHAT: Table of tests you ran, what you expected, what actually happened.
WHY: Documents verification of functionality. Helps catch regressions.
WHEN: Update as you test features, especially during Phase 4 (Testing & Verification).
EXAMPLE:
| Add task | python todo.py add "Buy milk" | Task added | Task added successfully | ✓ |
| List tasks | python todo.py list | Shows all tasks | Shows all tasks | ✓ |
-->
| Test | Input | Expected | Actual | Status |
|------|-------|----------|--------|--------|
| | | | | |
## Error Log
<!--
WHAT: Detailed log of every error encountered, with timestamps and resolution attempts.
WHY: More detailed than task_plan.md's error table. Helps you learn from mistakes.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| 2026-01-15 10:35 | FileNotFoundError | 1 | Added file existence check |
| 2026-01-15 10:37 | JSONDecodeError | 2 | Added empty file handling |
-->
<!-- Keep ALL errors - they help avoid repetition -->
| Timestamp | Error | Attempt | Resolution |
|-----------|-------|---------|------------|
| | | 1 | |
## 5-Question Reboot Check
<!--
WHAT: Five questions that verify your context is solid. If you can answer these, you're on track.
WHY: This is the "reboot test" - if you can answer all 5, you can resume work effectively.
WHEN: Update periodically, especially when resuming after a break or context reset.
THE 5 QUESTIONS:
1. Where am I? → Current phase in task_plan.md
2. Where am I going? → Remaining phases
3. What's the goal? → Goal statement in task_plan.md
4. What have I learned? → See findings.md
5. What have I done? → See progress.md (this file)
-->
<!-- If you can answer these, context is solid -->
| Question | Answer |
|----------|--------|
| Where am I? | Phase X |
| Where am I going? | Remaining phases |
| What's the goal? | [goal statement] |
| What have I learned? | See findings.md |
| What have I done? | See above |
---
<!--
REMINDER:
- Update after completing each phase or encountering errors
- Be detailed - this is your "what happened" log
- Include timestamps for errors to track when issues occurred
-->
*Update after completing each phase or encountering errors*
@@ -0,0 +1,132 @@
# Task Plan: [Brief Description]
<!--
WHAT: This is your roadmap for the entire task. Think of it as your "working memory on disk."
WHY: After 50+ tool calls, your original goals can get forgotten. This file keeps them fresh.
WHEN: Create this FIRST, before starting any work. Update after each phase completes.
-->
## Goal
<!--
WHAT: One clear sentence describing what you're trying to achieve.
WHY: This is your north star. Re-reading this keeps you focused on the end state.
EXAMPLE: "Create a Python CLI todo app with add, list, and delete functionality."
-->
[One sentence describing the end state]
## Current Phase
<!--
WHAT: Which phase you're currently working on (e.g., "Phase 1", "Phase 3").
WHY: Quick reference for where you are in the task. Update this as you progress.
-->
Phase 1
## Phases
<!--
WHAT: Break your task into 3-7 logical phases. Each phase should be completable.
WHY: Breaking work into phases prevents overwhelm and makes progress visible.
WHEN: Update status after completing each phase: pending → in_progress → complete
-->
### Phase 1: Requirements & Discovery
<!--
WHAT: Understand what needs to be done and gather initial information.
WHY: Starting without understanding leads to wasted effort. This phase prevents that.
-->
- [ ] Understand user intent
- [ ] Identify constraints and requirements
- [ ] Document findings in findings.md
- **Status:** in_progress
<!--
STATUS VALUES:
- pending: Not started yet
- in_progress: Currently working on this
- complete: Finished this phase
-->
### Phase 2: Planning & Structure
<!--
WHAT: Decide how you'll approach the problem and what structure you'll use.
WHY: Good planning prevents rework. Document decisions so you remember why you chose them.
-->
- [ ] Define technical approach
- [ ] Create project structure if needed
- [ ] Document decisions with rationale
- **Status:** pending
### Phase 3: Implementation
<!--
WHAT: Actually build/create/write the solution.
WHY: This is where the work happens. Break into smaller sub-tasks if needed.
-->
- [ ] Execute the plan step by step
- [ ] Write code to files before executing
- [ ] Test incrementally
- **Status:** pending
### Phase 4: Testing & Verification
<!--
WHAT: Verify everything works and meets requirements.
WHY: Catching issues early saves time. Document test results in progress.md.
-->
- [ ] Verify all requirements met
- [ ] Document test results in progress.md
- [ ] Fix any issues found
- **Status:** pending
### Phase 5: Delivery
<!--
WHAT: Final review and handoff to user.
WHY: Ensures nothing is forgotten and deliverables are complete.
-->
- [ ] Review all output files
- [ ] Ensure deliverables are complete
- [ ] Deliver to user
- **Status:** pending
## Key Questions
<!--
WHAT: Important questions you need to answer during the task.
WHY: These guide your research and decision-making. Answer them as you go.
EXAMPLE:
1. Should tasks persist between sessions? (Yes - need file storage)
2. What format for storing tasks? (JSON file)
-->
1. [Question to answer]
2. [Question to answer]
## Decisions Made
<!--
WHAT: Technical and design decisions you've made, with the reasoning behind them.
WHY: You'll forget why you made choices. This table helps you remember and justify decisions.
WHEN: Update whenever you make a significant choice (technology, approach, structure).
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
-->
| Decision | Rationale |
|----------|-----------|
| | |
## Errors Encountered
<!--
WHAT: Every error you encounter, what attempt number it was, and how you resolved it.
WHY: Logging errors prevents repeating the same mistakes. This is critical for learning.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| FileNotFoundError | 1 | Check if file exists, create empty list if not |
| JSONDecodeError | 2 | Handle empty file case explicitly |
-->
| Error | Attempt | Resolution |
|-------|---------|------------|
| | 1 | |
## Notes
<!--
REMINDERS:
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
- Never repeat a failed action - mutate your approach instead
-->
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
+14 -3
View File
@@ -1,7 +1,7 @@
{
"name": "planning-with-files",
"version": "2.7.0",
"description": "Manus-style persistent markdown files for planning, progress tracking, and knowledge storage. Use when starting complex tasks, multi-step projects, research tasks, or when you want structured output.",
"version": "2.11.0",
"description": "Manus-style persistent markdown files for planning, progress tracking, and knowledge storage. Works with Claude Code, Kiro, Clawd CLI, Gemini CLI, Cursor, Continue, and 11+ AI coding assistants.",
"author": {
"name": "OthmanAdi",
"url": "https://github.com/OthmanAdi"
@@ -15,6 +15,17 @@
"markdown",
"context-engineering",
"task-management",
"templates"
"templates",
"clawd",
"clawdbot",
"clawdhub",
"kiro",
"kiro-steering",
"amazon-kiro",
"gemini",
"cursor",
"continue",
"multi-ide",
"agent-skills"
]
}
@@ -0,0 +1,248 @@
---
name: planning-with-files
version: "2.10.0"
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls. Now with automatic session recovery after /clear.
user-invocable: true
allowed-tools:
- Read
- Write
- Edit
- Bash
- Glob
- Grep
- WebFetch
- WebSearch
hooks:
PreToolUse:
- matcher: "Write|Edit|Bash|Read|Glob|Grep"
hooks:
- type: command
command: "cat task_plan.md 2>/dev/null | head -30 || true"
PostToolUse:
- matcher: "Write|Edit"
hooks:
- type: command
command: "echo '[planning-with-files] File updated. If this completes a phase, update task_plan.md status.'"
Stop:
- hooks:
- type: command
command: |
SCRIPT_DIR="${CODEBUDDY_PLUGIN_ROOT:-$HOME/.codebuddy/skills/planning-with-files}/scripts"
IS_WINDOWS=0
if [ "${OS-}" = "Windows_NT" ]; then
IS_WINDOWS=1
else
UNAME_S="$(uname -s 2>/dev/null || echo '')"
case "$UNAME_S" in
CYGWIN*|MINGW*|MSYS*) IS_WINDOWS=1 ;;
esac
fi
if [ "$IS_WINDOWS" -eq 1 ]; then
if command -v pwsh >/dev/null 2>&1; then
pwsh -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
sh "$SCRIPT_DIR/check-complete.sh"
else
powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
sh "$SCRIPT_DIR/check-complete.sh"
fi
else
sh "$SCRIPT_DIR/check-complete.sh"
fi
---
# Planning with Files
Work like Manus: Use persistent markdown files as your "working memory on disk."
## FIRST: Check for Previous Session (v2.2.0)
**Before starting work**, check for unsynced context from a previous session:
```bash
# Linux/macOS (auto-detects python3 or python)
$(command -v python3 || command -v python) ${CODEBUDDY_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
```
```powershell
# Windows PowerShell
python "$env:USERPROFILE\.codebuddy\skills\planning-with-files\scripts\session-catchup.py" (Get-Location)
```
If catchup report shows unsynced context:
1. Run `git diff --stat` to see actual code changes
2. Read current planning files
3. Update planning files based on catchup + git diff
4. Then proceed with task
## Important: Where Files Go
- **Templates** are in `${CODEBUDDY_PLUGIN_ROOT}/templates/`
- **Your planning files** go in **your project directory**
| Location | What Goes There |
|----------|-----------------|
| Skill directory (`${CODEBUDDY_PLUGIN_ROOT}/`) | Templates, scripts, reference docs |
| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
## Quick Start
Before ANY complex task:
1. **Create `task_plan.md`** — Use [templates/task_plan.md](templates/task_plan.md) as reference
2. **Create `findings.md`** — Use [templates/findings.md](templates/findings.md) as reference
3. **Create `progress.md`** — Use [templates/progress.md](templates/progress.md) as reference
4. **Re-read plan before decisions** — Refreshes goals in attention window
5. **Update after each phase** — Mark complete, log errors
> **Note:** Planning files go in your project root, not the skill installation folder.
## The Core Pattern
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
```
## File Purposes
| File | Purpose | When to Update |
|------|---------|----------------|
| `task_plan.md` | Phases, progress, decisions | After each phase |
| `findings.md` | Research, discoveries | After ANY discovery |
| `progress.md` | Session log, test results | Throughout session |
## Critical Rules
### 1. Create Plan First
Never start a complex task without `task_plan.md`. Non-negotiable.
### 2. The 2-Action Rule
> "After every 2 view/browser/search operations, IMMEDIATELY save key findings to text files."
This prevents visual/multimodal information from being lost.
### 3. Read Before Decide
Before major decisions, read the plan file. This keeps goals in your attention window.
### 4. Update After Act
After completing any phase:
- Mark phase status: `in_progress` → `complete`
- Log any errors encountered
- Note files created/modified
### 5. Log ALL Errors
Every error goes in the plan file. This builds knowledge and prevents repetition.
```markdown
## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |
| API timeout | 2 | Added retry logic |
```
### 6. Never Repeat Failures
```
if action_failed:
next_action != same_action
```
Track what you tried. Mutate the approach.
## The 3-Strike Error Protocol
```
ATTEMPT 1: Diagnose & Fix
→ Read error carefully
→ Identify root cause
→ Apply targeted fix
ATTEMPT 2: Alternative Approach
→ Same error? Try different method
→ Different tool? Different library?
→ NEVER repeat exact same failing action
ATTEMPT 3: Broader Rethink
→ Question assumptions
→ Search for solutions
→ Consider updating the plan
AFTER 3 FAILURES: Escalate to User
→ Explain what you tried
→ Share the specific error
→ Ask for guidance
```
## Read vs Write Decision Matrix
| Situation | Action | Reason |
|-----------|--------|--------|
| Just wrote a file | DON'T read | Content still in context |
| Viewed image/PDF | Write findings NOW | Multimodal → text before lost |
| Browser returned data | Write to file | Screenshots don't persist |
| Starting new phase | Read plan/findings | Re-orient if context stale |
| Error occurred | Read relevant file | Need current state to fix |
| Resuming after gap | Read all planning files | Recover state |
## The 5-Question Reboot Test
If you can answer these, your context management is solid:
| Question | Answer Source |
|----------|---------------|
| Where am I? | Current phase in task_plan.md |
| Where am I going? | Remaining phases |
| What's the goal? | Goal statement in plan |
| What have I learned? | findings.md |
| What have I done? | progress.md |
## When to Use This Pattern
**Use for:**
- Multi-step tasks (3+ steps)
- Research tasks
- Building/creating projects
- Tasks spanning many tool calls
- Anything requiring organization
**Skip for:**
- Simple questions
- Single-file edits
- Quick lookups
## Templates
Copy these templates to start:
- [templates/task_plan.md](templates/task_plan.md) — Phase tracking
- [templates/findings.md](templates/findings.md) — Research storage
- [templates/progress.md](templates/progress.md) — Session logging
## Scripts
Helper scripts for automation:
- `scripts/init-session.sh` — Initialize all planning files
- `scripts/check-complete.sh` — Verify all phases complete
- `scripts/session-catchup.py` — Recover context from previous session (v2.2.0)
## Advanced Topics
- **Manus Principles:** See [reference.md](reference.md)
- **Real Examples:** See [examples.md](examples.md)
## Anti-Patterns
| Don't | Do Instead |
|-------|------------|
| Use TodoWrite for persistence | Create task_plan.md file |
| State goals once and forget | Re-read plan before decisions |
| Hide errors and retry silently | Log errors to plan file |
| Stuff everything in context | Store large content in files |
| Start executing immediately | Create plan file FIRST |
| Repeat failed actions | Track attempts, mutate approach |
| Create files in skill directory | Create files in your project |
@@ -0,0 +1,95 @@
# Findings & Decisions
<!--
WHAT: Your knowledge base for the task. Stores everything you discover and decide.
WHY: Context windows are limited. This file is your "external memory" - persistent and unlimited.
WHEN: Update after ANY discovery, especially after 2 view/browser/search operations (2-Action Rule).
-->
## Requirements
<!--
WHAT: What the user asked for, broken down into specific requirements.
WHY: Keeps requirements visible so you don't forget what you're building.
WHEN: Fill this in during Phase 1 (Requirements & Discovery).
EXAMPLE:
- Command-line interface
- Add tasks
- List all tasks
- Delete tasks
- Python implementation
-->
<!-- Captured from user request -->
-
## Research Findings
<!--
WHAT: Key discoveries from web searches, documentation reading, or exploration.
WHY: Multimodal content (images, browser results) doesn't persist. Write it down immediately.
WHEN: After EVERY 2 view/browser/search operations, update this section (2-Action Rule).
EXAMPLE:
- Python's argparse module supports subcommands for clean CLI design
- JSON module handles file persistence easily
- Standard pattern: python script.py <command> [args]
-->
<!-- Key discoveries during exploration -->
-
## Technical Decisions
<!--
WHAT: Architecture and implementation choices you've made, with reasoning.
WHY: You'll forget why you chose a technology or approach. This table preserves that knowledge.
WHEN: Update whenever you make a significant technical choice.
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
| argparse with subcommands | Clean CLI: python todo.py add "task" |
-->
<!-- Decisions made with rationale -->
| Decision | Rationale |
|----------|-----------|
| | |
## Issues Encountered
<!--
WHAT: Problems you ran into and how you solved them.
WHY: Similar to errors in task_plan.md, but focused on broader issues (not just code errors).
WHEN: Document when you encounter blockers or unexpected challenges.
EXAMPLE:
| Empty file causes JSONDecodeError | Added explicit empty file check before json.load() |
-->
<!-- Errors and how they were resolved -->
| Issue | Resolution |
|-------|------------|
| | |
## Resources
<!--
WHAT: URLs, file paths, API references, documentation links you've found useful.
WHY: Easy reference for later. Don't lose important links in context.
WHEN: Add as you discover useful resources.
EXAMPLE:
- Python argparse docs: https://docs.python.org/3/library/argparse.html
- Project structure: src/main.py, src/utils.py
-->
<!-- URLs, file paths, API references -->
-
## Visual/Browser Findings
<!--
WHAT: Information you learned from viewing images, PDFs, or browser results.
WHY: CRITICAL - Visual/multimodal content doesn't persist in context. Must be captured as text.
WHEN: IMMEDIATELY after viewing images or browser results. Don't wait!
EXAMPLE:
- Screenshot shows login form has email and password fields
- Browser shows API returns JSON with "status" and "data" keys
-->
<!-- CRITICAL: Update after every 2 view/browser operations -->
<!-- Multimodal content must be captured as text immediately -->
-
---
<!--
REMINDER: The 2-Action Rule
After every 2 view/browser/search operations, you MUST update this file.
This prevents visual information from being lost when context resets.
-->
*Update this file after every 2 view/browser/search operations*
*This prevents visual information from being lost*
@@ -0,0 +1,114 @@
# Progress Log
<!--
WHAT: Your session log - a chronological record of what you did, when, and what happened.
WHY: Answers "What have I done?" in the 5-Question Reboot Test. Helps you resume after breaks.
WHEN: Update after completing each phase or encountering errors. More detailed than task_plan.md.
-->
## Session: [DATE]
<!--
WHAT: The date of this work session.
WHY: Helps track when work happened, useful for resuming after time gaps.
EXAMPLE: 2026-01-15
-->
### Phase 1: [Title]
<!--
WHAT: Detailed log of actions taken during this phase.
WHY: Provides context for what was done, making it easier to resume or debug.
WHEN: Update as you work through the phase, or at least when you complete it.
-->
- **Status:** in_progress
- **Started:** [timestamp]
<!--
STATUS: Same as task_plan.md (pending, in_progress, complete)
TIMESTAMP: When you started this phase (e.g., "2026-01-15 10:00")
-->
- Actions taken:
<!--
WHAT: List of specific actions you performed.
EXAMPLE:
- Created todo.py with basic structure
- Implemented add functionality
- Fixed FileNotFoundError
-->
-
- Files created/modified:
<!--
WHAT: Which files you created or changed.
WHY: Quick reference for what was touched. Helps with debugging and review.
EXAMPLE:
- todo.py (created)
- todos.json (created by app)
- task_plan.md (updated)
-->
-
### Phase 2: [Title]
<!--
WHAT: Same structure as Phase 1, for the next phase.
WHY: Keep a separate log entry for each phase to track progress clearly.
-->
- **Status:** pending
- Actions taken:
-
- Files created/modified:
-
## Test Results
<!--
WHAT: Table of tests you ran, what you expected, what actually happened.
WHY: Documents verification of functionality. Helps catch regressions.
WHEN: Update as you test features, especially during Phase 4 (Testing & Verification).
EXAMPLE:
| Add task | python todo.py add "Buy milk" | Task added | Task added successfully | ✓ |
| List tasks | python todo.py list | Shows all tasks | Shows all tasks | ✓ |
-->
| Test | Input | Expected | Actual | Status |
|------|-------|----------|--------|--------|
| | | | | |
## Error Log
<!--
WHAT: Detailed log of every error encountered, with timestamps and resolution attempts.
WHY: More detailed than task_plan.md's error table. Helps you learn from mistakes.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| 2026-01-15 10:35 | FileNotFoundError | 1 | Added file existence check |
| 2026-01-15 10:37 | JSONDecodeError | 2 | Added empty file handling |
-->
<!-- Keep ALL errors - they help avoid repetition -->
| Timestamp | Error | Attempt | Resolution |
|-----------|-------|---------|------------|
| | | 1 | |
## 5-Question Reboot Check
<!--
WHAT: Five questions that verify your context is solid. If you can answer these, you're on track.
WHY: This is the "reboot test" - if you can answer all 5, you can resume work effectively.
WHEN: Update periodically, especially when resuming after a break or context reset.
THE 5 QUESTIONS:
1. Where am I? → Current phase in task_plan.md
2. Where am I going? → Remaining phases
3. What's the goal? → Goal statement in task_plan.md
4. What have I learned? → See findings.md
5. What have I done? → See progress.md (this file)
-->
<!-- If you can answer these, context is solid -->
| Question | Answer |
|----------|--------|
| Where am I? | Phase X |
| Where am I going? | Remaining phases |
| What's the goal? | [goal statement] |
| What have I learned? | See findings.md |
| What have I done? | See above |
---
<!--
REMINDER:
- Update after completing each phase or encountering errors
- Be detailed - this is your "what happened" log
- Include timestamps for errors to track when issues occurred
-->
*Update after completing each phase or encountering errors*
@@ -0,0 +1,132 @@
# Task Plan: [Brief Description]
<!--
WHAT: This is your roadmap for the entire task. Think of it as your "working memory on disk."
WHY: After 50+ tool calls, your original goals can get forgotten. This file keeps them fresh.
WHEN: Create this FIRST, before starting any work. Update after each phase completes.
-->
## Goal
<!--
WHAT: One clear sentence describing what you're trying to achieve.
WHY: This is your north star. Re-reading this keeps you focused on the end state.
EXAMPLE: "Create a Python CLI todo app with add, list, and delete functionality."
-->
[One sentence describing the end state]
## Current Phase
<!--
WHAT: Which phase you're currently working on (e.g., "Phase 1", "Phase 3").
WHY: Quick reference for where you are in the task. Update this as you progress.
-->
Phase 1
## Phases
<!--
WHAT: Break your task into 3-7 logical phases. Each phase should be completable.
WHY: Breaking work into phases prevents overwhelm and makes progress visible.
WHEN: Update status after completing each phase: pending → in_progress → complete
-->
### Phase 1: Requirements & Discovery
<!--
WHAT: Understand what needs to be done and gather initial information.
WHY: Starting without understanding leads to wasted effort. This phase prevents that.
-->
- [ ] Understand user intent
- [ ] Identify constraints and requirements
- [ ] Document findings in findings.md
- **Status:** in_progress
<!--
STATUS VALUES:
- pending: Not started yet
- in_progress: Currently working on this
- complete: Finished this phase
-->
### Phase 2: Planning & Structure
<!--
WHAT: Decide how you'll approach the problem and what structure you'll use.
WHY: Good planning prevents rework. Document decisions so you remember why you chose them.
-->
- [ ] Define technical approach
- [ ] Create project structure if needed
- [ ] Document decisions with rationale
- **Status:** pending
### Phase 3: Implementation
<!--
WHAT: Actually build/create/write the solution.
WHY: This is where the work happens. Break into smaller sub-tasks if needed.
-->
- [ ] Execute the plan step by step
- [ ] Write code to files before executing
- [ ] Test incrementally
- **Status:** pending
### Phase 4: Testing & Verification
<!--
WHAT: Verify everything works and meets requirements.
WHY: Catching issues early saves time. Document test results in progress.md.
-->
- [ ] Verify all requirements met
- [ ] Document test results in progress.md
- [ ] Fix any issues found
- **Status:** pending
### Phase 5: Delivery
<!--
WHAT: Final review and handoff to user.
WHY: Ensures nothing is forgotten and deliverables are complete.
-->
- [ ] Review all output files
- [ ] Ensure deliverables are complete
- [ ] Deliver to user
- **Status:** pending
## Key Questions
<!--
WHAT: Important questions you need to answer during the task.
WHY: These guide your research and decision-making. Answer them as you go.
EXAMPLE:
1. Should tasks persist between sessions? (Yes - need file storage)
2. What format for storing tasks? (JSON file)
-->
1. [Question to answer]
2. [Question to answer]
## Decisions Made
<!--
WHAT: Technical and design decisions you've made, with the reasoning behind them.
WHY: You'll forget why you made choices. This table helps you remember and justify decisions.
WHEN: Update whenever you make a significant choice (technology, approach, structure).
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
-->
| Decision | Rationale |
|----------|-----------|
| | |
## Errors Encountered
<!--
WHAT: Every error you encounter, what attempt number it was, and how you resolved it.
WHY: Logging errors prevents repeating the same mistakes. This is critical for learning.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| FileNotFoundError | 1 | Check if file exists, create empty list if not |
| JSONDecodeError | 2 | Handle empty file case explicitly |
-->
| Error | Attempt | Resolution |
|-------|---------|------------|
| | 1 | |
## Notes
<!--
REMINDERS:
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
- Never repeat a failed action - mutate your approach instead
-->
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
@@ -0,0 +1,202 @@
# Examples: Planning with Files in Action
## Example 1: Research Task
**User Request:** "Research the benefits of morning exercise and write a summary"
### Loop 1: Create Plan
```bash
Write task_plan.md
```
```markdown
# Task Plan: Morning Exercise Benefits Research
## Goal
Create a research summary on the benefits of morning exercise.
## Phases
- [ ] Phase 1: Create this plan ✓
- [ ] Phase 2: Search and gather sources
- [ ] Phase 3: Synthesize findings
- [ ] Phase 4: Deliver summary
## Key Questions
1. What are the physical health benefits?
2. What are the mental health benefits?
3. What scientific studies support this?
## Status
**Currently in Phase 1** - Creating plan
```
### Loop 2: Research
```bash
Read task_plan.md # Refresh goals
WebSearch "morning exercise benefits"
Write notes.md # Store findings
Edit task_plan.md # Mark Phase 2 complete
```
### Loop 3: Synthesize
```bash
Read task_plan.md # Refresh goals
Read notes.md # Get findings
Write morning_exercise_summary.md
Edit task_plan.md # Mark Phase 3 complete
```
### Loop 4: Deliver
```bash
Read task_plan.md # Verify complete
Deliver morning_exercise_summary.md
```
---
## Example 2: Bug Fix Task
**User Request:** "Fix the login bug in the authentication module"
### task_plan.md
```markdown
# Task Plan: Fix Login Bug
## Goal
Identify and fix the bug preventing successful login.
## Phases
- [x] Phase 1: Understand the bug report ✓
- [x] Phase 2: Locate relevant code ✓
- [ ] Phase 3: Identify root cause (CURRENT)
- [ ] Phase 4: Implement fix
- [ ] Phase 5: Test and verify
## Key Questions
1. What error message appears?
2. Which file handles authentication?
3. What changed recently?
## Decisions Made
- Auth handler is in src/auth/login.ts
- Error occurs in validateToken() function
## Errors Encountered
- [Initial] TypeError: Cannot read property 'token' of undefined
→ Root cause: user object not awaited properly
## Status
**Currently in Phase 3** - Found root cause, preparing fix
```
---
## Example 3: Feature Development
**User Request:** "Add a dark mode toggle to the settings page"
### The 3-File Pattern in Action
**task_plan.md:**
```markdown
# Task Plan: Dark Mode Toggle
## Goal
Add functional dark mode toggle to settings.
## Phases
- [x] Phase 1: Research existing theme system ✓
- [x] Phase 2: Design implementation approach ✓
- [ ] Phase 3: Implement toggle component (CURRENT)
- [ ] Phase 4: Add theme switching logic
- [ ] Phase 5: Test and polish
## Decisions Made
- Using CSS custom properties for theme
- Storing preference in localStorage
- Toggle component in SettingsPage.tsx
## Status
**Currently in Phase 3** - Building toggle component
```
**notes.md:**
```markdown
# Notes: Dark Mode Implementation
## Existing Theme System
- Located in: src/styles/theme.ts
- Uses: CSS custom properties
- Current themes: light only
## Files to Modify
1. src/styles/theme.ts - Add dark theme colors
2. src/components/SettingsPage.tsx - Add toggle
3. src/hooks/useTheme.ts - Create new hook
4. src/App.tsx - Wrap with ThemeProvider
## Color Decisions
- Dark background: #1a1a2e
- Dark surface: #16213e
- Dark text: #eaeaea
```
**dark_mode_implementation.md:** (deliverable)
```markdown
# Dark Mode Implementation
## Changes Made
### 1. Added dark theme colors
File: src/styles/theme.ts
...
### 2. Created useTheme hook
File: src/hooks/useTheme.ts
...
```
---
## Example 4: Error Recovery Pattern
When something fails, DON'T hide it:
### Before (Wrong)
```
Action: Read config.json
Error: File not found
Action: Read config.json # Silent retry
Action: Read config.json # Another retry
```
### After (Correct)
```
Action: Read config.json
Error: File not found
# Update task_plan.md:
## Errors Encountered
- config.json not found → Will create default config
Action: Write config.json (default config)
Action: Read config.json
Success!
```
---
## The Read-Before-Decide Pattern
**Always read your plan before major decisions:**
```
[Many tool calls have happened...]
[Context is getting long...]
[Original goal might be forgotten...]
→ Read task_plan.md # This brings goals back into attention!
→ Now make the decision # Goals are fresh in context
```
This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a "goal refresh" mechanism.
@@ -0,0 +1,218 @@
# Reference: Manus Context Engineering Principles
This skill is based on context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
## The 6 Manus Principles
### Principle 1: Design Around KV-Cache
> "KV-cache hit rate is THE single most important metric for production AI agents."
**Statistics:**
- ~100:1 input-to-output token ratio
- Cached tokens: $0.30/MTok vs Uncached: $3/MTok
- 10x cost difference!
**Implementation:**
- Keep prompt prefixes STABLE (single-token change invalidates cache)
- NO timestamps in system prompts
- Make context APPEND-ONLY with deterministic serialization
### Principle 2: Mask, Don't Remove
Don't dynamically remove tools (breaks KV-cache). Use logit masking instead.
**Best Practice:** Use consistent action prefixes (e.g., `browser_`, `shell_`, `file_`) for easier masking.
### Principle 3: Filesystem as External Memory
> "Markdown is my 'working memory' on disk."
**The Formula:**
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
```
**Compression Must Be Restorable:**
- Keep URLs even if web content is dropped
- Keep file paths when dropping document contents
- Never lose the pointer to full data
### Principle 4: Manipulate Attention Through Recitation
> "Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."
**Problem:** After ~50 tool calls, models forget original goals ("lost in the middle" effect).
**Solution:** Re-read `task_plan.md` before each decision. Goals appear in the attention window.
```
Start of context: [Original goal - far away, forgotten]
...many tool calls...
End of context: [Recently read task_plan.md - gets ATTENTION!]
```
### Principle 5: Keep the Wrong Stuff In
> "Leave the wrong turns in the context."
**Why:**
- Failed actions with stack traces let model implicitly update beliefs
- Reduces mistake repetition
- Error recovery is "one of the clearest signals of TRUE agentic behavior"
### Principle 6: Don't Get Few-Shotted
> "Uniformity breeds fragility."
**Problem:** Repetitive action-observation pairs cause drift and hallucination.
**Solution:** Introduce controlled variation:
- Vary phrasings slightly
- Don't copy-paste patterns blindly
- Recalibrate on repetitive tasks
---
## The 3 Context Engineering Strategies
Based on Lance Martin's analysis of Manus architecture.
### Strategy 1: Context Reduction
**Compaction:**
```
Tool calls have TWO representations:
├── FULL: Raw tool content (stored in filesystem)
└── COMPACT: Reference/file path only
RULES:
- Apply compaction to STALE (older) tool results
- Keep RECENT results FULL (to guide next decision)
```
**Summarization:**
- Applied when compaction reaches diminishing returns
- Generated using full tool results
- Creates standardized summary objects
### Strategy 2: Context Isolation (Multi-Agent)
**Architecture:**
```
┌─────────────────────────────────┐
│ PLANNER AGENT │
│ └─ Assigns tasks to sub-agents │
├─────────────────────────────────┤
│ KNOWLEDGE MANAGER │
│ └─ Reviews conversations │
│ └─ Determines filesystem store │
├─────────────────────────────────┤
│ EXECUTOR SUB-AGENTS │
│ └─ Perform assigned tasks │
│ └─ Have own context windows │
└─────────────────────────────────┘
```
**Key Insight:** Manus originally used `todo.md` for task planning but found ~33% of actions were spent updating it. Shifted to dedicated planner agent calling executor sub-agents.
### Strategy 3: Context Offloading
**Tool Design:**
- Use <20 atomic functions total
- Store full results in filesystem, not context
- Use `glob` and `grep` for searching
- Progressive disclosure: load information only as needed
---
## The Agent Loop
Manus operates in a continuous 7-step loop:
```
┌─────────────────────────────────────────┐
│ 1. ANALYZE CONTEXT │
│ - Understand user intent │
│ - Assess current state │
│ - Review recent observations │
├─────────────────────────────────────────┤
│ 2. THINK │
│ - Should I update the plan? │
│ - What's the next logical action? │
│ - Are there blockers? │
├─────────────────────────────────────────┤
│ 3. SELECT TOOL │
│ - Choose ONE tool │
│ - Ensure parameters available │
├─────────────────────────────────────────┤
│ 4. EXECUTE ACTION │
│ - Tool runs in sandbox │
├─────────────────────────────────────────┤
│ 5. RECEIVE OBSERVATION │
│ - Result appended to context │
├─────────────────────────────────────────┤
│ 6. ITERATE │
│ - Return to step 1 │
│ - Continue until complete │
├─────────────────────────────────────────┤
│ 7. DELIVER OUTCOME │
│ - Send results to user │
│ - Attach all relevant files │
└─────────────────────────────────────────┘
```
---
## File Types Manus Creates
| File | Purpose | When Created | When Updated |
|------|---------|--------------|--------------|
| `task_plan.md` | Phase tracking, progress | Task start | After completing phases |
| `findings.md` | Discoveries, decisions | After ANY discovery | After viewing images/PDFs |
| `progress.md` | Session log, what's done | At breakpoints | Throughout session |
| Code files | Implementation | Before execution | After errors |
---
## Critical Constraints
- **Single-Action Execution:** ONE tool call per turn. No parallel execution.
- **Plan is Required:** Agent must ALWAYS know: goal, current phase, remaining phases
- **Files are Memory:** Context = volatile. Filesystem = persistent.
- **Never Repeat Failures:** If action failed, next action MUST be different
- **Communication is a Tool:** Message types: `info` (progress), `ask` (blocking), `result` (terminal)
---
## Manus Statistics
| Metric | Value |
|--------|-------|
| Average tool calls per task | ~50 |
| Input-to-output token ratio | 100:1 |
| Acquisition price | $2 billion |
| Time to $100M revenue | 8 months |
| Framework refactors since launch | 5 times |
---
## Key Quotes
> "Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."
> "if action_failed: next_action != same_action. Track what you tried. Mutate the approach."
> "Error recovery is one of the clearest signals of TRUE agentic behavior."
> "KV-cache hit rate is the single most important metric for a production-stage AI agent."
> "Leave the wrong turns in the context."
---
## Source
Based on Manus's official context engineering documentation:
https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
@@ -0,0 +1,44 @@
# Check if all phases in task_plan.md are complete
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
param(
[string]$PlanFile = "task_plan.md"
)
if (-not (Test-Path $PlanFile)) {
Write-Host "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
}
# Read file content
$content = Get-Content $PlanFile -Raw
# Count total phases
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
# Check for **Status:** format first
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
# Fallback: check for [complete] inline format if **Status:** not found
if ($COMPLETE -eq 0 -and $IN_PROGRESS -eq 0 -and $PENDING -eq 0) {
$COMPLETE = ([regex]::Matches($content, "\[complete\]")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\[in_progress\]")).Count
$PENDING = ([regex]::Matches($content, "\[pending\]")).Count
}
# Report status (always exit 0 — incomplete task is a normal state)
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
} else {
Write-Host "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if ($IN_PROGRESS -gt 0) {
Write-Host "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
}
if ($PENDING -gt 0) {
Write-Host "[planning-with-files] $PENDING phase(s) pending."
}
}
exit 0
@@ -0,0 +1,46 @@
#!/bin/bash
# Check if all phases in task_plan.md are complete
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
echo "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
fi
# Count total phases
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
# Check for **Status:** format first
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)
# Fallback: check for [complete] inline format if **Status:** not found
if [ "$COMPLETE" -eq 0 ] && [ "$IN_PROGRESS" -eq 0 ] && [ "$PENDING" -eq 0 ]; then
COMPLETE=$(grep -c "\[complete\]" "$PLAN_FILE" || true)
IN_PROGRESS=$(grep -c "\[in_progress\]" "$PLAN_FILE" || true)
PENDING=$(grep -c "\[pending\]" "$PLAN_FILE" || true)
fi
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
# Report status (always exit 0 — incomplete task is a normal state)
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
else
echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if [ "$IN_PROGRESS" -gt 0 ]; then
echo "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
fi
if [ "$PENDING" -gt 0 ]; then
echo "[planning-with-files] $PENDING phase(s) pending."
fi
fi
exit 0
@@ -0,0 +1,120 @@
# Initialize planning files for a new session
# Usage: .\init-session.ps1 [project-name]
param(
[string]$ProjectName = "project"
)
$DATE = Get-Date -Format "yyyy-MM-dd"
Write-Host "Initializing planning files for: $ProjectName"
# Create task_plan.md if it doesn't exist
if (-not (Test-Path "task_plan.md")) {
@"
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
Write-Host "Created task_plan.md"
} else {
Write-Host "task_plan.md already exists, skipping"
}
# Create findings.md if it doesn't exist
if (-not (Test-Path "findings.md")) {
@"
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
"@ | Out-File -FilePath "findings.md" -Encoding UTF8
Write-Host "Created findings.md"
} else {
Write-Host "findings.md already exists, skipping"
}
# Create progress.md if it doesn't exist
if (-not (Test-Path "progress.md")) {
@"
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
Write-Host "Created progress.md"
} else {
Write-Host "progress.md already exists, skipping"
}
Write-Host ""
Write-Host "Planning files initialized!"
Write-Host "Files: task_plan.md, findings.md, progress.md"
@@ -0,0 +1,120 @@
#!/bin/bash
# Initialize planning files for a new session
# Usage: ./init-session.sh [project-name]
set -e
PROJECT_NAME="${1:-project}"
DATE=$(date +%Y-%m-%d)
echo "Initializing planning files for: $PROJECT_NAME"
# Create task_plan.md if it doesn't exist
if [ ! -f "task_plan.md" ]; then
cat > task_plan.md << 'EOF'
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
EOF
echo "Created task_plan.md"
else
echo "task_plan.md already exists, skipping"
fi
# Create findings.md if it doesn't exist
if [ ! -f "findings.md" ]; then
cat > findings.md << 'EOF'
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
EOF
echo "Created findings.md"
else
echo "findings.md already exists, skipping"
fi
# Create progress.md if it doesn't exist
if [ ! -f "progress.md" ]; then
cat > progress.md << EOF
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
EOF
echo "Created progress.md"
else
echo "progress.md already exists, skipping"
fi
echo ""
echo "Planning files initialized!"
echo "Files: task_plan.md, findings.md, progress.md"
@@ -0,0 +1,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 CodeBuddy's storage path format."""
sanitized = project_path.replace('/', '-')
if not sanitized.startswith('-'):
sanitized = '-' + sanitized
sanitized = sanitized.replace('_', '-')
return Path.home() / '.codebuddy' / '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"CODEBUDDY: {msg['content'][:300]}")
if msg.get('tools'):
print(f" Tools: {', '.join(msg['tools'][:4])}")
print("\n--- RECOMMENDED ---")
print("1. Run: git diff --stat")
print("2. Read: task_plan.md, progress.md, findings.md")
print("3. Update planning files based on above context")
print("4. Continue with task")
if __name__ == '__main__':
main()
@@ -0,0 +1,95 @@
# Findings & Decisions
<!--
WHAT: Your knowledge base for the task. Stores everything you discover and decide.
WHY: Context windows are limited. This file is your "external memory" - persistent and unlimited.
WHEN: Update after ANY discovery, especially after 2 view/browser/search operations (2-Action Rule).
-->
## Requirements
<!--
WHAT: What the user asked for, broken down into specific requirements.
WHY: Keeps requirements visible so you don't forget what you're building.
WHEN: Fill this in during Phase 1 (Requirements & Discovery).
EXAMPLE:
- Command-line interface
- Add tasks
- List all tasks
- Delete tasks
- Python implementation
-->
<!-- Captured from user request -->
-
## Research Findings
<!--
WHAT: Key discoveries from web searches, documentation reading, or exploration.
WHY: Multimodal content (images, browser results) doesn't persist. Write it down immediately.
WHEN: After EVERY 2 view/browser/search operations, update this section (2-Action Rule).
EXAMPLE:
- Python's argparse module supports subcommands for clean CLI design
- JSON module handles file persistence easily
- Standard pattern: python script.py <command> [args]
-->
<!-- Key discoveries during exploration -->
-
## Technical Decisions
<!--
WHAT: Architecture and implementation choices you've made, with reasoning.
WHY: You'll forget why you chose a technology or approach. This table preserves that knowledge.
WHEN: Update whenever you make a significant technical choice.
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
| argparse with subcommands | Clean CLI: python todo.py add "task" |
-->
<!-- Decisions made with rationale -->
| Decision | Rationale |
|----------|-----------|
| | |
## Issues Encountered
<!--
WHAT: Problems you ran into and how you solved them.
WHY: Similar to errors in task_plan.md, but focused on broader issues (not just code errors).
WHEN: Document when you encounter blockers or unexpected challenges.
EXAMPLE:
| Empty file causes JSONDecodeError | Added explicit empty file check before json.load() |
-->
<!-- Errors and how they were resolved -->
| Issue | Resolution |
|-------|------------|
| | |
## Resources
<!--
WHAT: URLs, file paths, API references, documentation links you've found useful.
WHY: Easy reference for later. Don't lose important links in context.
WHEN: Add as you discover useful resources.
EXAMPLE:
- Python argparse docs: https://docs.python.org/3/library/argparse.html
- Project structure: src/main.py, src/utils.py
-->
<!-- URLs, file paths, API references -->
-
## Visual/Browser Findings
<!--
WHAT: Information you learned from viewing images, PDFs, or browser results.
WHY: CRITICAL - Visual/multimodal content doesn't persist in context. Must be captured as text.
WHEN: IMMEDIATELY after viewing images or browser results. Don't wait!
EXAMPLE:
- Screenshot shows login form has email and password fields
- Browser shows API returns JSON with "status" and "data" keys
-->
<!-- CRITICAL: Update after every 2 view/browser operations -->
<!-- Multimodal content must be captured as text immediately -->
-
---
<!--
REMINDER: The 2-Action Rule
After every 2 view/browser/search operations, you MUST update this file.
This prevents visual information from being lost when context resets.
-->
*Update this file after every 2 view/browser/search operations*
*This prevents visual information from being lost*
@@ -0,0 +1,114 @@
# Progress Log
<!--
WHAT: Your session log - a chronological record of what you did, when, and what happened.
WHY: Answers "What have I done?" in the 5-Question Reboot Test. Helps you resume after breaks.
WHEN: Update after completing each phase or encountering errors. More detailed than task_plan.md.
-->
## Session: [DATE]
<!--
WHAT: The date of this work session.
WHY: Helps track when work happened, useful for resuming after time gaps.
EXAMPLE: 2026-01-15
-->
### Phase 1: [Title]
<!--
WHAT: Detailed log of actions taken during this phase.
WHY: Provides context for what was done, making it easier to resume or debug.
WHEN: Update as you work through the phase, or at least when you complete it.
-->
- **Status:** in_progress
- **Started:** [timestamp]
<!--
STATUS: Same as task_plan.md (pending, in_progress, complete)
TIMESTAMP: When you started this phase (e.g., "2026-01-15 10:00")
-->
- Actions taken:
<!--
WHAT: List of specific actions you performed.
EXAMPLE:
- Created todo.py with basic structure
- Implemented add functionality
- Fixed FileNotFoundError
-->
-
- Files created/modified:
<!--
WHAT: Which files you created or changed.
WHY: Quick reference for what was touched. Helps with debugging and review.
EXAMPLE:
- todo.py (created)
- todos.json (created by app)
- task_plan.md (updated)
-->
-
### Phase 2: [Title]
<!--
WHAT: Same structure as Phase 1, for the next phase.
WHY: Keep a separate log entry for each phase to track progress clearly.
-->
- **Status:** pending
- Actions taken:
-
- Files created/modified:
-
## Test Results
<!--
WHAT: Table of tests you ran, what you expected, what actually happened.
WHY: Documents verification of functionality. Helps catch regressions.
WHEN: Update as you test features, especially during Phase 4 (Testing & Verification).
EXAMPLE:
| Add task | python todo.py add "Buy milk" | Task added | Task added successfully | ✓ |
| List tasks | python todo.py list | Shows all tasks | Shows all tasks | ✓ |
-->
| Test | Input | Expected | Actual | Status |
|------|-------|----------|--------|--------|
| | | | | |
## Error Log
<!--
WHAT: Detailed log of every error encountered, with timestamps and resolution attempts.
WHY: More detailed than task_plan.md's error table. Helps you learn from mistakes.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| 2026-01-15 10:35 | FileNotFoundError | 1 | Added file existence check |
| 2026-01-15 10:37 | JSONDecodeError | 2 | Added empty file handling |
-->
<!-- Keep ALL errors - they help avoid repetition -->
| Timestamp | Error | Attempt | Resolution |
|-----------|-------|---------|------------|
| | | 1 | |
## 5-Question Reboot Check
<!--
WHAT: Five questions that verify your context is solid. If you can answer these, you're on track.
WHY: This is the "reboot test" - if you can answer all 5, you can resume work effectively.
WHEN: Update periodically, especially when resuming after a break or context reset.
THE 5 QUESTIONS:
1. Where am I? → Current phase in task_plan.md
2. Where am I going? → Remaining phases
3. What's the goal? → Goal statement in task_plan.md
4. What have I learned? → See findings.md
5. What have I done? → See progress.md (this file)
-->
<!-- If you can answer these, context is solid -->
| Question | Answer |
|----------|--------|
| Where am I? | Phase X |
| Where am I going? | Remaining phases |
| What's the goal? | [goal statement] |
| What have I learned? | See findings.md |
| What have I done? | See above |
---
<!--
REMINDER:
- Update after completing each phase or encountering errors
- Be detailed - this is your "what happened" log
- Include timestamps for errors to track when issues occurred
-->
*Update after completing each phase or encountering errors*
@@ -0,0 +1,132 @@
# Task Plan: [Brief Description]
<!--
WHAT: This is your roadmap for the entire task. Think of it as your "working memory on disk."
WHY: After 50+ tool calls, your original goals can get forgotten. This file keeps them fresh.
WHEN: Create this FIRST, before starting any work. Update after each phase completes.
-->
## Goal
<!--
WHAT: One clear sentence describing what you're trying to achieve.
WHY: This is your north star. Re-reading this keeps you focused on the end state.
EXAMPLE: "Create a Python CLI todo app with add, list, and delete functionality."
-->
[One sentence describing the end state]
## Current Phase
<!--
WHAT: Which phase you're currently working on (e.g., "Phase 1", "Phase 3").
WHY: Quick reference for where you are in the task. Update this as you progress.
-->
Phase 1
## Phases
<!--
WHAT: Break your task into 3-7 logical phases. Each phase should be completable.
WHY: Breaking work into phases prevents overwhelm and makes progress visible.
WHEN: Update status after completing each phase: pending → in_progress → complete
-->
### Phase 1: Requirements & Discovery
<!--
WHAT: Understand what needs to be done and gather initial information.
WHY: Starting without understanding leads to wasted effort. This phase prevents that.
-->
- [ ] Understand user intent
- [ ] Identify constraints and requirements
- [ ] Document findings in findings.md
- **Status:** in_progress
<!--
STATUS VALUES:
- pending: Not started yet
- in_progress: Currently working on this
- complete: Finished this phase
-->
### Phase 2: Planning & Structure
<!--
WHAT: Decide how you'll approach the problem and what structure you'll use.
WHY: Good planning prevents rework. Document decisions so you remember why you chose them.
-->
- [ ] Define technical approach
- [ ] Create project structure if needed
- [ ] Document decisions with rationale
- **Status:** pending
### Phase 3: Implementation
<!--
WHAT: Actually build/create/write the solution.
WHY: This is where the work happens. Break into smaller sub-tasks if needed.
-->
- [ ] Execute the plan step by step
- [ ] Write code to files before executing
- [ ] Test incrementally
- **Status:** pending
### Phase 4: Testing & Verification
<!--
WHAT: Verify everything works and meets requirements.
WHY: Catching issues early saves time. Document test results in progress.md.
-->
- [ ] Verify all requirements met
- [ ] Document test results in progress.md
- [ ] Fix any issues found
- **Status:** pending
### Phase 5: Delivery
<!--
WHAT: Final review and handoff to user.
WHY: Ensures nothing is forgotten and deliverables are complete.
-->
- [ ] Review all output files
- [ ] Ensure deliverables are complete
- [ ] Deliver to user
- **Status:** pending
## Key Questions
<!--
WHAT: Important questions you need to answer during the task.
WHY: These guide your research and decision-making. Answer them as you go.
EXAMPLE:
1. Should tasks persist between sessions? (Yes - need file storage)
2. What format for storing tasks? (JSON file)
-->
1. [Question to answer]
2. [Question to answer]
## Decisions Made
<!--
WHAT: Technical and design decisions you've made, with the reasoning behind them.
WHY: You'll forget why you made choices. This table helps you remember and justify decisions.
WHEN: Update whenever you make a significant choice (technology, approach, structure).
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
-->
| Decision | Rationale |
|----------|-----------|
| | |
## Errors Encountered
<!--
WHAT: Every error you encounter, what attempt number it was, and how you resolved it.
WHY: Logging errors prevents repeating the same mistakes. This is critical for learning.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| FileNotFoundError | 1 | Check if file exists, create empty list if not |
| JSONDecodeError | 2 | Handle empty file case explicitly |
-->
| Error | Attempt | Resolution |
|-------|---------|------------|
| | 1 | |
## Notes
<!--
REMINDERS:
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
- Never repeat a failed action - mutate your approach instead
-->
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
+32 -8
View File
@@ -1,6 +1,6 @@
---
name: planning-with-files
version: "2.4.1"
version: "2.10.0"
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls. Now with automatic session recovery after /clear.
user-invocable: true
allowed-tools:
@@ -27,11 +27,29 @@ hooks:
- hooks:
- type: command
command: |
SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files}/scripts"
if command -v pwsh &> /dev/null && [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" || "$OS" == "Windows_NT" ]]; then
pwsh -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null || powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null || bash "$SCRIPT_DIR/check-complete.sh"
SCRIPT_DIR="${CODEX_SKILL_ROOT:-$HOME/.codex/skills/planning-with-files}/scripts"
IS_WINDOWS=0
if [ "${OS-}" = "Windows_NT" ]; then
IS_WINDOWS=1
else
bash "$SCRIPT_DIR/check-complete.sh"
UNAME_S="$(uname -s 2>/dev/null || echo '')"
case "$UNAME_S" in
CYGWIN*|MINGW*|MSYS*) IS_WINDOWS=1 ;;
esac
fi
if [ "$IS_WINDOWS" -eq 1 ]; then
if command -v pwsh >/dev/null 2>&1; then
pwsh -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
sh "$SCRIPT_DIR/check-complete.sh"
else
powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
sh "$SCRIPT_DIR/check-complete.sh"
fi
else
sh "$SCRIPT_DIR/check-complete.sh"
fi
---
@@ -44,7 +62,13 @@ Work like Manus: Use persistent markdown files as your "working memory on disk."
**Before starting work**, check for unsynced context from a previous session:
```bash
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
# Linux/macOS (auto-detects python3 or python)
$(command -v python3 || command -v python) ~/.codex/skills/planning-with-files/scripts/session-catchup.py "$(pwd)"
```
```powershell
# Windows PowerShell
python "$env:USERPROFILE\.codex\skills\planning-with-files\scripts\session-catchup.py" (Get-Location)
```
If catchup report shows unsynced context:
@@ -55,12 +79,12 @@ If catchup report shows unsynced context:
## Important: Where Files Go
- **Templates** are in `${CLAUDE_PLUGIN_ROOT}/templates/`
- **Templates** are in `~/.codex/skills/planning-with-files/templates/`
- **Your planning files** go in **your project directory**
| Location | What Goes There |
|----------|-----------------|
| Skill directory (`${CLAUDE_PLUGIN_ROOT}/`) | Templates, scripts, reference docs |
| Skill directory (`~/.codex/skills/planning-with-files/`) | Templates, scripts, reference docs |
| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
## Quick Start
@@ -1,42 +1,44 @@
# 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
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
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 "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
}
Write-Host "=== Task Completion Check ==="
Write-Host ""
# Read file content
$content = Get-Content $PlanFile -Raw
# Count phases by status
# Count total phases
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
# Check for **Status:** format first
$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
# Fallback: check for [complete] inline format if **Status:** not found
if ($COMPLETE -eq 0 -and $IN_PROGRESS -eq 0 -and $PENDING -eq 0) {
$COMPLETE = ([regex]::Matches($content, "\[complete\]")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\[in_progress\]")).Count
$PENDING = ([regex]::Matches($content, "\[pending\]")).Count
}
# Report status (always exit 0 — incomplete task is a normal state)
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
} else {
Write-Host "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if ($IN_PROGRESS -gt 0) {
Write-Host "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
}
if ($PENDING -gt 0) {
Write-Host "[planning-with-files] $PENDING phase(s) pending."
}
}
exit 0
@@ -1,44 +1,46 @@
#!/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
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
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
echo "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
fi
echo "=== Task Completion Check ==="
echo ""
# Count phases by status (using -F for fixed string matching)
# Count total phases
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
# Check for **Status:** format first
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)
# Fallback: check for [complete] inline format if **Status:** not found
if [ "$COMPLETE" -eq 0 ] && [ "$IN_PROGRESS" -eq 0 ] && [ "$PENDING" -eq 0 ]; then
COMPLETE=$(grep -c "\[complete\]" "$PLAN_FILE" || true)
IN_PROGRESS=$(grep -c "\[in_progress\]" "$PLAN_FILE" || true)
PENDING=$(grep -c "\[pending\]" "$PLAN_FILE" || true)
fi
# 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
# Report status (always exit 0 — incomplete task is a normal state)
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "ALL PHASES COMPLETE"
exit 0
echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
else
echo "TASK NOT COMPLETE"
echo ""
echo "Do not stop until all phases are complete."
exit 1
echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if [ "$IN_PROGRESS" -gt 0 ]; then
echo "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
fi
if [ "$PENDING" -gt 0 ]; then
echo "[planning-with-files] $PENDING phase(s) pending."
fi
fi
exit 0
@@ -0,0 +1,95 @@
# Findings & Decisions
<!--
WHAT: Your knowledge base for the task. Stores everything you discover and decide.
WHY: Context windows are limited. This file is your "external memory" - persistent and unlimited.
WHEN: Update after ANY discovery, especially after 2 view/browser/search operations (2-Action Rule).
-->
## Requirements
<!--
WHAT: What the user asked for, broken down into specific requirements.
WHY: Keeps requirements visible so you don't forget what you're building.
WHEN: Fill this in during Phase 1 (Requirements & Discovery).
EXAMPLE:
- Command-line interface
- Add tasks
- List all tasks
- Delete tasks
- Python implementation
-->
<!-- Captured from user request -->
-
## Research Findings
<!--
WHAT: Key discoveries from web searches, documentation reading, or exploration.
WHY: Multimodal content (images, browser results) doesn't persist. Write it down immediately.
WHEN: After EVERY 2 view/browser/search operations, update this section (2-Action Rule).
EXAMPLE:
- Python's argparse module supports subcommands for clean CLI design
- JSON module handles file persistence easily
- Standard pattern: python script.py <command> [args]
-->
<!-- Key discoveries during exploration -->
-
## Technical Decisions
<!--
WHAT: Architecture and implementation choices you've made, with reasoning.
WHY: You'll forget why you chose a technology or approach. This table preserves that knowledge.
WHEN: Update whenever you make a significant technical choice.
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
| argparse with subcommands | Clean CLI: python todo.py add "task" |
-->
<!-- Decisions made with rationale -->
| Decision | Rationale |
|----------|-----------|
| | |
## Issues Encountered
<!--
WHAT: Problems you ran into and how you solved them.
WHY: Similar to errors in task_plan.md, but focused on broader issues (not just code errors).
WHEN: Document when you encounter blockers or unexpected challenges.
EXAMPLE:
| Empty file causes JSONDecodeError | Added explicit empty file check before json.load() |
-->
<!-- Errors and how they were resolved -->
| Issue | Resolution |
|-------|------------|
| | |
## Resources
<!--
WHAT: URLs, file paths, API references, documentation links you've found useful.
WHY: Easy reference for later. Don't lose important links in context.
WHEN: Add as you discover useful resources.
EXAMPLE:
- Python argparse docs: https://docs.python.org/3/library/argparse.html
- Project structure: src/main.py, src/utils.py
-->
<!-- URLs, file paths, API references -->
-
## Visual/Browser Findings
<!--
WHAT: Information you learned from viewing images, PDFs, or browser results.
WHY: CRITICAL - Visual/multimodal content doesn't persist in context. Must be captured as text.
WHEN: IMMEDIATELY after viewing images or browser results. Don't wait!
EXAMPLE:
- Screenshot shows login form has email and password fields
- Browser shows API returns JSON with "status" and "data" keys
-->
<!-- CRITICAL: Update after every 2 view/browser operations -->
<!-- Multimodal content must be captured as text immediately -->
-
---
<!--
REMINDER: The 2-Action Rule
After every 2 view/browser/search operations, you MUST update this file.
This prevents visual information from being lost when context resets.
-->
*Update this file after every 2 view/browser/search operations*
*This prevents visual information from being lost*
@@ -0,0 +1,114 @@
# Progress Log
<!--
WHAT: Your session log - a chronological record of what you did, when, and what happened.
WHY: Answers "What have I done?" in the 5-Question Reboot Test. Helps you resume after breaks.
WHEN: Update after completing each phase or encountering errors. More detailed than task_plan.md.
-->
## Session: [DATE]
<!--
WHAT: The date of this work session.
WHY: Helps track when work happened, useful for resuming after time gaps.
EXAMPLE: 2026-01-15
-->
### Phase 1: [Title]
<!--
WHAT: Detailed log of actions taken during this phase.
WHY: Provides context for what was done, making it easier to resume or debug.
WHEN: Update as you work through the phase, or at least when you complete it.
-->
- **Status:** in_progress
- **Started:** [timestamp]
<!--
STATUS: Same as task_plan.md (pending, in_progress, complete)
TIMESTAMP: When you started this phase (e.g., "2026-01-15 10:00")
-->
- Actions taken:
<!--
WHAT: List of specific actions you performed.
EXAMPLE:
- Created todo.py with basic structure
- Implemented add functionality
- Fixed FileNotFoundError
-->
-
- Files created/modified:
<!--
WHAT: Which files you created or changed.
WHY: Quick reference for what was touched. Helps with debugging and review.
EXAMPLE:
- todo.py (created)
- todos.json (created by app)
- task_plan.md (updated)
-->
-
### Phase 2: [Title]
<!--
WHAT: Same structure as Phase 1, for the next phase.
WHY: Keep a separate log entry for each phase to track progress clearly.
-->
- **Status:** pending
- Actions taken:
-
- Files created/modified:
-
## Test Results
<!--
WHAT: Table of tests you ran, what you expected, what actually happened.
WHY: Documents verification of functionality. Helps catch regressions.
WHEN: Update as you test features, especially during Phase 4 (Testing & Verification).
EXAMPLE:
| Add task | python todo.py add "Buy milk" | Task added | Task added successfully | ✓ |
| List tasks | python todo.py list | Shows all tasks | Shows all tasks | ✓ |
-->
| Test | Input | Expected | Actual | Status |
|------|-------|----------|--------|--------|
| | | | | |
## Error Log
<!--
WHAT: Detailed log of every error encountered, with timestamps and resolution attempts.
WHY: More detailed than task_plan.md's error table. Helps you learn from mistakes.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| 2026-01-15 10:35 | FileNotFoundError | 1 | Added file existence check |
| 2026-01-15 10:37 | JSONDecodeError | 2 | Added empty file handling |
-->
<!-- Keep ALL errors - they help avoid repetition -->
| Timestamp | Error | Attempt | Resolution |
|-----------|-------|---------|------------|
| | | 1 | |
## 5-Question Reboot Check
<!--
WHAT: Five questions that verify your context is solid. If you can answer these, you're on track.
WHY: This is the "reboot test" - if you can answer all 5, you can resume work effectively.
WHEN: Update periodically, especially when resuming after a break or context reset.
THE 5 QUESTIONS:
1. Where am I? → Current phase in task_plan.md
2. Where am I going? → Remaining phases
3. What's the goal? → Goal statement in task_plan.md
4. What have I learned? → See findings.md
5. What have I done? → See progress.md (this file)
-->
<!-- If you can answer these, context is solid -->
| Question | Answer |
|----------|--------|
| Where am I? | Phase X |
| Where am I going? | Remaining phases |
| What's the goal? | [goal statement] |
| What have I learned? | See findings.md |
| What have I done? | See above |
---
<!--
REMINDER:
- Update after completing each phase or encountering errors
- Be detailed - this is your "what happened" log
- Include timestamps for errors to track when issues occurred
-->
*Update after completing each phase or encountering errors*
@@ -0,0 +1,132 @@
# Task Plan: [Brief Description]
<!--
WHAT: This is your roadmap for the entire task. Think of it as your "working memory on disk."
WHY: After 50+ tool calls, your original goals can get forgotten. This file keeps them fresh.
WHEN: Create this FIRST, before starting any work. Update after each phase completes.
-->
## Goal
<!--
WHAT: One clear sentence describing what you're trying to achieve.
WHY: This is your north star. Re-reading this keeps you focused on the end state.
EXAMPLE: "Create a Python CLI todo app with add, list, and delete functionality."
-->
[One sentence describing the end state]
## Current Phase
<!--
WHAT: Which phase you're currently working on (e.g., "Phase 1", "Phase 3").
WHY: Quick reference for where you are in the task. Update this as you progress.
-->
Phase 1
## Phases
<!--
WHAT: Break your task into 3-7 logical phases. Each phase should be completable.
WHY: Breaking work into phases prevents overwhelm and makes progress visible.
WHEN: Update status after completing each phase: pending → in_progress → complete
-->
### Phase 1: Requirements & Discovery
<!--
WHAT: Understand what needs to be done and gather initial information.
WHY: Starting without understanding leads to wasted effort. This phase prevents that.
-->
- [ ] Understand user intent
- [ ] Identify constraints and requirements
- [ ] Document findings in findings.md
- **Status:** in_progress
<!--
STATUS VALUES:
- pending: Not started yet
- in_progress: Currently working on this
- complete: Finished this phase
-->
### Phase 2: Planning & Structure
<!--
WHAT: Decide how you'll approach the problem and what structure you'll use.
WHY: Good planning prevents rework. Document decisions so you remember why you chose them.
-->
- [ ] Define technical approach
- [ ] Create project structure if needed
- [ ] Document decisions with rationale
- **Status:** pending
### Phase 3: Implementation
<!--
WHAT: Actually build/create/write the solution.
WHY: This is where the work happens. Break into smaller sub-tasks if needed.
-->
- [ ] Execute the plan step by step
- [ ] Write code to files before executing
- [ ] Test incrementally
- **Status:** pending
### Phase 4: Testing & Verification
<!--
WHAT: Verify everything works and meets requirements.
WHY: Catching issues early saves time. Document test results in progress.md.
-->
- [ ] Verify all requirements met
- [ ] Document test results in progress.md
- [ ] Fix any issues found
- **Status:** pending
### Phase 5: Delivery
<!--
WHAT: Final review and handoff to user.
WHY: Ensures nothing is forgotten and deliverables are complete.
-->
- [ ] Review all output files
- [ ] Ensure deliverables are complete
- [ ] Deliver to user
- **Status:** pending
## Key Questions
<!--
WHAT: Important questions you need to answer during the task.
WHY: These guide your research and decision-making. Answer them as you go.
EXAMPLE:
1. Should tasks persist between sessions? (Yes - need file storage)
2. What format for storing tasks? (JSON file)
-->
1. [Question to answer]
2. [Question to answer]
## Decisions Made
<!--
WHAT: Technical and design decisions you've made, with the reasoning behind them.
WHY: You'll forget why you made choices. This table helps you remember and justify decisions.
WHEN: Update whenever you make a significant choice (technology, approach, structure).
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
-->
| Decision | Rationale |
|----------|-----------|
| | |
## Errors Encountered
<!--
WHAT: Every error you encounter, what attempt number it was, and how you resolved it.
WHY: Logging errors prevents repeating the same mistakes. This is critical for learning.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| FileNotFoundError | 1 | Check if file exists, create empty list if not |
| JSONDecodeError | 2 | Handle empty file case explicitly |
-->
| Error | Attempt | Resolution |
|-------|---------|------------|
| | 1 | |
## Notes
<!--
REMINDERS:
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
- Never repeat a failed action - mutate your approach instead
-->
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
@@ -0,0 +1,34 @@
---
name: planning-with-files
description: 启动“Planning with Files”三文件工作流(task_plan.md / findings.md / progress.md)
invokable: true
---
你将采用“Planning with Files”模式来完成接下来的工作:把计划、发现与进度持久化到 3 个 Markdown 文件里,以避免上下文漂移与遗忘。
## 目标
- 在项目根目录确保存在:task_plan.md、findings.md、progress.md
- 所有关键决策、研究结论、错误与修复路径必须写入文件
- 每完成一个阶段就更新 task_plan.md 的状态
## 工作步骤
1. 检查项目根目录是否已有 task_plan.md / findings.md / progress.md
2. 如果不存在,先创建它们(可直接运行初始化脚本,或在 IDE 里新建同名文件):
- macOS/Linux:bash .continue/skills/planning-with-files/scripts/init-session.sh
- Windows:powershell -ExecutionPolicy Bypass -File .continue/skills/planning-with-files/scripts/init-session.ps1
3. 读取 task_plan.md,补全:
- Goal(1 句话)
- Phases(3-7 个阶段,带 Status: pending / in_progress / complete)
- Key Questions(需要回答的关键问题)
4. 执行任务时遵守:
- 每 2 次“查看/搜索/浏览”后,立刻把发现写入 findings.md
- 每次重要决策前,先读取 task_plan.md 刷新目标
- 任何错误都记录在 task_plan.md 的 Errors Encountered,并写清楚尝试次数与解决方式
5. 持续把本次会话的行动与验证结果写入 progress.md(包括命令、测试、输出)
## 输出要求
- 你的回答优先引用这些文件中的最新内容(而不是依赖聊天记忆)
- 任务结束前,确保所有阶段均为 complete(或明确说明未完成原因与后续)
@@ -0,0 +1,83 @@
---
name: planning-with-files
version: "2.10.0"
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls. Now with automatic session recovery after /clear.
---
# Planning with Files
Work like Manus: Use persistent markdown files as your "working memory on disk."
## FIRST: Check for Previous Session (v2.2.0)
Before starting work, check for unsynced context from a previous session:
```bash
python3 .continue/skills/planning-with-files/scripts/session-catchup.py "$(pwd)" || python .continue/skills/planning-with-files/scripts/session-catchup.py "$(pwd)"
```
If catchup report shows unsynced context:
1. Run `git diff --stat` to see actual code changes
2. Read current planning files
3. Update planning files based on catchup + git diff
4. Then proceed with task
## Quick Start
Before any complex task:
1. Create `task_plan.md`, `findings.md`, `progress.md` in your project root
2. If they don't exist yet, initialize them using:
- macOS/Linux: `bash .continue/skills/planning-with-files/scripts/init-session.sh`
- Windows: `powershell -ExecutionPolicy Bypass -File .continue/skills/planning-with-files/scripts/init-session.ps1`
3. Re-read `task_plan.md` before major decisions
4. Update `task_plan.md` after each phase completes
5. Write discoveries to `findings.md` (especially after web/search/image/PDF viewing)
## The Core Pattern
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
```
## File Purposes
| File | Purpose | When to Update |
|------|---------|----------------|
| `task_plan.md` | Phases, progress, decisions | After each phase |
| `findings.md` | Research, discoveries | After any discovery |
| `progress.md` | Session log, test results | Throughout session |
## Critical Rules
### 1. Create Plan First
Never start a complex task without `task_plan.md`.
### 2. The 2-Action Rule
After every 2 view/browser/search operations, save key findings to text files.
### 3. Read Before Decide
Before major decisions, read `task_plan.md` to refresh goals.
### 4. Update After Act
After completing any phase, update statuses and log errors in `task_plan.md`.
### 5. Log ALL Errors
Every error goes in the plan file so you don't repeat it.
### 6. Never Repeat Failures
If an action failed, the next action must be different.
## References
- [reference.md](reference.md)
- [examples.md](examples.md)
@@ -0,0 +1,202 @@
# Examples: Planning with Files in Action
## Example 1: Research Task
**User Request:** "Research the benefits of morning exercise and write a summary"
### Loop 1: Create Plan
```bash
Write task_plan.md
```
```markdown
# Task Plan: Morning Exercise Benefits Research
## Goal
Create a research summary on the benefits of morning exercise.
## Phases
- [ ] Phase 1: Create this plan ✓
- [ ] Phase 2: Search and gather sources
- [ ] Phase 3: Synthesize findings
- [ ] Phase 4: Deliver summary
## Key Questions
1. What are the physical health benefits?
2. What are the mental health benefits?
3. What scientific studies support this?
## Status
**Currently in Phase 1** - Creating plan
```
### Loop 2: Research
```bash
Read task_plan.md # Refresh goals
WebSearch "morning exercise benefits"
Write notes.md # Store findings
Edit task_plan.md # Mark Phase 2 complete
```
### Loop 3: Synthesize
```bash
Read task_plan.md # Refresh goals
Read notes.md # Get findings
Write morning_exercise_summary.md
Edit task_plan.md # Mark Phase 3 complete
```
### Loop 4: Deliver
```bash
Read task_plan.md # Verify complete
Deliver morning_exercise_summary.md
```
---
## Example 2: Bug Fix Task
**User Request:** "Fix the login bug in the authentication module"
### task_plan.md
```markdown
# Task Plan: Fix Login Bug
## Goal
Identify and fix the bug preventing successful login.
## Phases
- [x] Phase 1: Understand the bug report ✓
- [x] Phase 2: Locate relevant code ✓
- [ ] Phase 3: Identify root cause (CURRENT)
- [ ] Phase 4: Implement fix
- [ ] Phase 5: Test and verify
## Key Questions
1. What error message appears?
2. Which file handles authentication?
3. What changed recently?
## Decisions Made
- Auth handler is in src/auth/login.ts
- Error occurs in validateToken() function
## Errors Encountered
- [Initial] TypeError: Cannot read property 'token' of undefined
→ Root cause: user object not awaited properly
## Status
**Currently in Phase 3** - Found root cause, preparing fix
```
---
## Example 3: Feature Development
**User Request:** "Add a dark mode toggle to the settings page"
### The 3-File Pattern in Action
**task_plan.md:**
```markdown
# Task Plan: Dark Mode Toggle
## Goal
Add functional dark mode toggle to settings.
## Phases
- [x] Phase 1: Research existing theme system ✓
- [x] Phase 2: Design implementation approach ✓
- [ ] Phase 3: Implement toggle component (CURRENT)
- [ ] Phase 4: Add theme switching logic
- [ ] Phase 5: Test and polish
## Decisions Made
- Using CSS custom properties for theme
- Storing preference in localStorage
- Toggle component in SettingsPage.tsx
## Status
**Currently in Phase 3** - Building toggle component
```
**notes.md:**
```markdown
# Notes: Dark Mode Implementation
## Existing Theme System
- Located in: src/styles/theme.ts
- Uses: CSS custom properties
- Current themes: light only
## Files to Modify
1. src/styles/theme.ts - Add dark theme colors
2. src/components/SettingsPage.tsx - Add toggle
3. src/hooks/useTheme.ts - Create new hook
4. src/App.tsx - Wrap with ThemeProvider
## Color Decisions
- Dark background: #1a1a2e
- Dark surface: #16213e
- Dark text: #eaeaea
```
**dark_mode_implementation.md:** (deliverable)
```markdown
# Dark Mode Implementation
## Changes Made
### 1. Added dark theme colors
File: src/styles/theme.ts
...
### 2. Created useTheme hook
File: src/hooks/useTheme.ts
...
```
---
## Example 4: Error Recovery Pattern
When something fails, DON'T hide it:
### Before (Wrong)
```
Action: Read config.json
Error: File not found
Action: Read config.json # Silent retry
Action: Read config.json # Another retry
```
### After (Correct)
```
Action: Read config.json
Error: File not found
# Update task_plan.md:
## Errors Encountered
- config.json not found → Will create default config
Action: Write config.json (default config)
Action: Read config.json
Success!
```
---
## The Read-Before-Decide Pattern
**Always read your plan before major decisions:**
```
[Many tool calls have happened...]
[Context is getting long...]
[Original goal might be forgotten...]
→ Read task_plan.md # This brings goals back into attention!
→ Now make the decision # Goals are fresh in context
```
This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a "goal refresh" mechanism.
@@ -0,0 +1,218 @@
# Reference: Manus Context Engineering Principles
This skill is based on context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
## The 6 Manus Principles
### Principle 1: Design Around KV-Cache
> "KV-cache hit rate is THE single most important metric for production AI agents."
**Statistics:**
- ~100:1 input-to-output token ratio
- Cached tokens: $0.30/MTok vs Uncached: $3/MTok
- 10x cost difference!
**Implementation:**
- Keep prompt prefixes STABLE (single-token change invalidates cache)
- NO timestamps in system prompts
- Make context APPEND-ONLY with deterministic serialization
### Principle 2: Mask, Don't Remove
Don't dynamically remove tools (breaks KV-cache). Use logit masking instead.
**Best Practice:** Use consistent action prefixes (e.g., `browser_`, `shell_`, `file_`) for easier masking.
### Principle 3: Filesystem as External Memory
> "Markdown is my 'working memory' on disk."
**The Formula:**
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
```
**Compression Must Be Restorable:**
- Keep URLs even if web content is dropped
- Keep file paths when dropping document contents
- Never lose the pointer to full data
### Principle 4: Manipulate Attention Through Recitation
> "Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."
**Problem:** After ~50 tool calls, models forget original goals ("lost in the middle" effect).
**Solution:** Re-read `task_plan.md` before each decision. Goals appear in the attention window.
```
Start of context: [Original goal - far away, forgotten]
...many tool calls...
End of context: [Recently read task_plan.md - gets ATTENTION!]
```
### Principle 5: Keep the Wrong Stuff In
> "Leave the wrong turns in the context."
**Why:**
- Failed actions with stack traces let model implicitly update beliefs
- Reduces mistake repetition
- Error recovery is "one of the clearest signals of TRUE agentic behavior"
### Principle 6: Don't Get Few-Shotted
> "Uniformity breeds fragility."
**Problem:** Repetitive action-observation pairs cause drift and hallucination.
**Solution:** Introduce controlled variation:
- Vary phrasings slightly
- Don't copy-paste patterns blindly
- Recalibrate on repetitive tasks
---
## The 3 Context Engineering Strategies
Based on Lance Martin's analysis of Manus architecture.
### Strategy 1: Context Reduction
**Compaction:**
```
Tool calls have TWO representations:
├── FULL: Raw tool content (stored in filesystem)
└── COMPACT: Reference/file path only
RULES:
- Apply compaction to STALE (older) tool results
- Keep RECENT results FULL (to guide next decision)
```
**Summarization:**
- Applied when compaction reaches diminishing returns
- Generated using full tool results
- Creates standardized summary objects
### Strategy 2: Context Isolation (Multi-Agent)
**Architecture:**
```
┌─────────────────────────────────┐
│ PLANNER AGENT │
│ └─ Assigns tasks to sub-agents │
├─────────────────────────────────┤
│ KNOWLEDGE MANAGER │
│ └─ Reviews conversations │
│ └─ Determines filesystem store │
├─────────────────────────────────┤
│ EXECUTOR SUB-AGENTS │
│ └─ Perform assigned tasks │
│ └─ Have own context windows │
└─────────────────────────────────┘
```
**Key Insight:** Manus originally used `todo.md` for task planning but found ~33% of actions were spent updating it. Shifted to dedicated planner agent calling executor sub-agents.
### Strategy 3: Context Offloading
**Tool Design:**
- Use <20 atomic functions total
- Store full results in filesystem, not context
- Use `glob` and `grep` for searching
- Progressive disclosure: load information only as needed
---
## The Agent Loop
Manus operates in a continuous 7-step loop:
```
┌─────────────────────────────────────────┐
│ 1. ANALYZE CONTEXT │
│ - Understand user intent │
│ - Assess current state │
│ - Review recent observations │
├─────────────────────────────────────────┤
│ 2. THINK │
│ - Should I update the plan? │
│ - What's the next logical action? │
│ - Are there blockers? │
├─────────────────────────────────────────┤
│ 3. SELECT TOOL │
│ - Choose ONE tool │
│ - Ensure parameters available │
├─────────────────────────────────────────┤
│ 4. EXECUTE ACTION │
│ - Tool runs in sandbox │
├─────────────────────────────────────────┤
│ 5. RECEIVE OBSERVATION │
│ - Result appended to context │
├─────────────────────────────────────────┤
│ 6. ITERATE │
│ - Return to step 1 │
│ - Continue until complete │
├─────────────────────────────────────────┤
│ 7. DELIVER OUTCOME │
│ - Send results to user │
│ - Attach all relevant files │
└─────────────────────────────────────────┘
```
---
## File Types Manus Creates
| File | Purpose | When Created | When Updated |
|------|---------|--------------|--------------|
| `task_plan.md` | Phase tracking, progress | Task start | After completing phases |
| `findings.md` | Discoveries, decisions | After ANY discovery | After viewing images/PDFs |
| `progress.md` | Session log, what's done | At breakpoints | Throughout session |
| Code files | Implementation | Before execution | After errors |
---
## Critical Constraints
- **Single-Action Execution:** ONE tool call per turn. No parallel execution.
- **Plan is Required:** Agent must ALWAYS know: goal, current phase, remaining phases
- **Files are Memory:** Context = volatile. Filesystem = persistent.
- **Never Repeat Failures:** If action failed, next action MUST be different
- **Communication is a Tool:** Message types: `info` (progress), `ask` (blocking), `result` (terminal)
---
## Manus Statistics
| Metric | Value |
|--------|-------|
| Average tool calls per task | ~50 |
| Input-to-output token ratio | 100:1 |
| Acquisition price | $2 billion |
| Time to $100M revenue | 8 months |
| Framework refactors since launch | 5 times |
---
## Key Quotes
> "Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."
> "if action_failed: next_action != same_action. Track what you tried. Mutate the approach."
> "Error recovery is one of the clearest signals of TRUE agentic behavior."
> "KV-cache hit rate is the single most important metric for a production-stage AI agent."
> "Leave the wrong turns in the context."
---
## Source
Based on Manus's official context engineering documentation:
https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
@@ -0,0 +1,44 @@
# Check if all phases in task_plan.md are complete
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
param(
[string]$PlanFile = "task_plan.md"
)
if (-not (Test-Path $PlanFile)) {
Write-Host "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
}
# Read file content
$content = Get-Content $PlanFile -Raw
# Count total phases
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
# Check for **Status:** format first
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
# Fallback: check for [complete] inline format if **Status:** not found
if ($COMPLETE -eq 0 -and $IN_PROGRESS -eq 0 -and $PENDING -eq 0) {
$COMPLETE = ([regex]::Matches($content, "\[complete\]")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\[in_progress\]")).Count
$PENDING = ([regex]::Matches($content, "\[pending\]")).Count
}
# Report status (always exit 0 — incomplete task is a normal state)
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
} else {
Write-Host "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if ($IN_PROGRESS -gt 0) {
Write-Host "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
}
if ($PENDING -gt 0) {
Write-Host "[planning-with-files] $PENDING phase(s) pending."
}
}
exit 0
@@ -0,0 +1,46 @@
#!/bin/bash
# Check if all phases in task_plan.md are complete
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
echo "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
fi
# Count total phases
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
# Check for **Status:** format first
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)
# Fallback: check for [complete] inline format if **Status:** not found
if [ "$COMPLETE" -eq 0 ] && [ "$IN_PROGRESS" -eq 0 ] && [ "$PENDING" -eq 0 ]; then
COMPLETE=$(grep -c "\[complete\]" "$PLAN_FILE" || true)
IN_PROGRESS=$(grep -c "\[in_progress\]" "$PLAN_FILE" || true)
PENDING=$(grep -c "\[pending\]" "$PLAN_FILE" || true)
fi
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
# Report status (always exit 0 — incomplete task is a normal state)
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
else
echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if [ "$IN_PROGRESS" -gt 0 ]; then
echo "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
fi
if [ "$PENDING" -gt 0 ]; then
echo "[planning-with-files] $PENDING phase(s) pending."
fi
fi
exit 0
@@ -0,0 +1,120 @@
# Initialize planning files for a new session
# Usage: .\init-session.ps1 [project-name]
param(
[string]$ProjectName = "project"
)
$DATE = Get-Date -Format "yyyy-MM-dd"
Write-Host "Initializing planning files for: $ProjectName"
# Create task_plan.md if it doesn't exist
if (-not (Test-Path "task_plan.md")) {
@"
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
Write-Host "Created task_plan.md"
} else {
Write-Host "task_plan.md already exists, skipping"
}
# Create findings.md if it doesn't exist
if (-not (Test-Path "findings.md")) {
@"
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
"@ | Out-File -FilePath "findings.md" -Encoding UTF8
Write-Host "Created findings.md"
} else {
Write-Host "findings.md already exists, skipping"
}
# Create progress.md if it doesn't exist
if (-not (Test-Path "progress.md")) {
@"
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
Write-Host "Created progress.md"
} else {
Write-Host "progress.md already exists, skipping"
}
Write-Host ""
Write-Host "Planning files initialized!"
Write-Host "Files: task_plan.md, findings.md, progress.md"
@@ -0,0 +1,120 @@
#!/bin/bash
# Initialize planning files for a new session
# Usage: ./init-session.sh [project-name]
set -e
PROJECT_NAME="${1:-project}"
DATE=$(date +%Y-%m-%d)
echo "Initializing planning files for: $PROJECT_NAME"
# Create task_plan.md if it doesn't exist
if [ ! -f "task_plan.md" ]; then
cat > task_plan.md << 'EOF'
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
EOF
echo "Created task_plan.md"
else
echo "task_plan.md already exists, skipping"
fi
# Create findings.md if it doesn't exist
if [ ! -f "findings.md" ]; then
cat > findings.md << 'EOF'
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
EOF
echo "Created findings.md"
else
echo "findings.md already exists, skipping"
fi
# Create progress.md if it doesn't exist
if [ ! -f "progress.md" ]; then
cat > progress.md << EOF
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
EOF
echo "Created progress.md"
else
echo "progress.md already exists, skipping"
fi
echo ""
echo "Planning files initialized!"
echo "Files: task_plan.md, findings.md, progress.md"
@@ -0,0 +1,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()
+26
View File
@@ -0,0 +1,26 @@
{
"version": 1,
"hooks": {
"preToolUse": [
{
"command": ".cursor/hooks/pre-tool-use.sh",
"matcher": "Write|Edit|Shell|Read",
"timeout": 5
}
],
"postToolUse": [
{
"command": ".cursor/hooks/post-tool-use.sh",
"matcher": "Write|Edit",
"timeout": 5
}
],
"stop": [
{
"command": ".cursor/hooks/stop.sh",
"timeout": 10,
"loop_limit": 3
}
]
}
}
+26
View File
@@ -0,0 +1,26 @@
{
"version": 1,
"hooks": {
"preToolUse": [
{
"command": "powershell -ExecutionPolicy Bypass -File .cursor/hooks/pre-tool-use.ps1",
"matcher": "Write|Edit|Shell|Read",
"timeout": 5
}
],
"postToolUse": [
{
"command": "powershell -ExecutionPolicy Bypass -File .cursor/hooks/post-tool-use.ps1",
"matcher": "Write|Edit",
"timeout": 5
}
],
"stop": [
{
"command": "powershell -ExecutionPolicy Bypass -File .cursor/hooks/stop.ps1",
"timeout": 10,
"loop_limit": 3
}
]
}
}
+5
View File
@@ -0,0 +1,5 @@
# planning-with-files: Post-tool-use hook for Cursor (PowerShell)
# Reminds the agent to update task_plan.md after file modifications.
Write-Output "[planning-with-files] File updated. If this completes a phase, update task_plan.md status."
exit 0
+6
View File
@@ -0,0 +1,6 @@
#!/bin/bash
# planning-with-files: Post-tool-use hook for Cursor
# Reminds the agent to update task_plan.md after file modifications.
echo "[planning-with-files] File updated. If this completes a phase, update task_plan.md status."
exit 0
+12
View File
@@ -0,0 +1,12 @@
# planning-with-files: Pre-tool-use hook for Cursor (PowerShell)
# Reads the first 30 lines of task_plan.md to keep goals in context.
# Returns {"decision": "allow"} — this hook never blocks tools.
$PlanFile = "task_plan.md"
if (Test-Path $PlanFile) {
Get-Content $PlanFile -TotalCount 30 | Write-Host
}
Write-Output '{"decision": "allow"}'
exit 0
+14
View File
@@ -0,0 +1,14 @@
#!/bin/bash
# planning-with-files: Pre-tool-use hook for Cursor
# Reads the first 30 lines of task_plan.md to keep goals in context.
# Returns {"decision": "allow"} — this hook never blocks tools.
PLAN_FILE="task_plan.md"
if [ -f "$PLAN_FILE" ]; then
# Log plan context to stderr (visible in Cursor's hook logs)
head -30 "$PLAN_FILE" >&2
fi
echo '{"decision": "allow"}'
exit 0
+33
View File
@@ -0,0 +1,33 @@
# planning-with-files: Stop hook for Cursor (PowerShell)
# Checks if all phases in task_plan.md are complete.
# Returns followup_message to auto-continue if phases are incomplete.
# Always exits 0 — uses JSON stdout for control.
$PlanFile = "task_plan.md"
if (-not (Test-Path $PlanFile)) {
exit 0
}
$content = Get-Content $PlanFile -Raw
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
# Check for **Status:** format first
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
# Fallback: check for [complete] inline format
if ($COMPLETE -eq 0 -and $IN_PROGRESS -eq 0 -and $PENDING -eq 0) {
$COMPLETE = ([regex]::Matches($content, "\[complete\]")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\[in_progress\]")).Count
$PENDING = ([regex]::Matches($content, "\[pending\]")).Count
}
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
exit 0
} else {
Write-Host "{`"followup_message`": `"[planning-with-files] Task incomplete ($COMPLETE/$TOTAL phases done). Read task_plan.md and continue working on the remaining phases.`"}"
exit 0
}
+42
View File
@@ -0,0 +1,42 @@
#!/bin/bash
# planning-with-files: Stop hook for Cursor
# Checks if all phases in task_plan.md are complete.
# Returns followup_message to auto-continue if phases are incomplete.
# Always exits 0 — uses JSON stdout for control.
PLAN_FILE="task_plan.md"
if [ ! -f "$PLAN_FILE" ]; then
# No plan file = no planning session, allow stop
exit 0
fi
# Count total phases
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
# Check for **Status:** format first
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)
# Fallback: check for [complete] inline format
if [ "$COMPLETE" -eq 0 ] && [ "$IN_PROGRESS" -eq 0 ] && [ "$PENDING" -eq 0 ]; then
COMPLETE=$(grep -c "\[complete\]" "$PLAN_FILE" || true)
IN_PROGRESS=$(grep -c "\[in_progress\]" "$PLAN_FILE" || true)
PENDING=$(grep -c "\[pending\]" "$PLAN_FILE" || true)
fi
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
# All phases complete, allow stop
exit 0
else
# Phases incomplete — auto-continue via followup_message
echo "{\"followup_message\": \"[planning-with-files] Task incomplete ($COMPLETE/$TOTAL phases done). Read task_plan.md and continue working on the remaining phases.\"}"
exit 0
fi
+32 -8
View File
@@ -1,6 +1,6 @@
---
name: planning-with-files
version: "2.4.1"
version: "2.10.0"
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls. Now with automatic session recovery after /clear.
user-invocable: true
allowed-tools:
@@ -27,11 +27,29 @@ hooks:
- hooks:
- type: command
command: |
SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files}/scripts"
if command -v pwsh &> /dev/null && [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" || "$OS" == "Windows_NT" ]]; then
pwsh -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null || powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null || bash "$SCRIPT_DIR/check-complete.sh"
SCRIPT_DIR="${CURSOR_SKILL_ROOT:-.cursor/skills/planning-with-files}/scripts"
IS_WINDOWS=0
if [ "${OS-}" = "Windows_NT" ]; then
IS_WINDOWS=1
else
bash "$SCRIPT_DIR/check-complete.sh"
UNAME_S="$(uname -s 2>/dev/null || echo '')"
case "$UNAME_S" in
CYGWIN*|MINGW*|MSYS*) IS_WINDOWS=1 ;;
esac
fi
if [ "$IS_WINDOWS" -eq 1 ]; then
if command -v pwsh >/dev/null 2>&1; then
pwsh -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
sh "$SCRIPT_DIR/check-complete.sh"
else
powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
sh "$SCRIPT_DIR/check-complete.sh"
fi
else
sh "$SCRIPT_DIR/check-complete.sh"
fi
---
@@ -44,7 +62,13 @@ Work like Manus: Use persistent markdown files as your "working memory on disk."
**Before starting work**, check for unsynced context from a previous session:
```bash
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
# Linux/macOS (auto-detects python3 or python)
$(command -v python3 || command -v python) .cursor/skills/planning-with-files/scripts/session-catchup.py "$(pwd)"
```
```powershell
# Windows PowerShell
python "$env:USERPROFILE\.cursor\skills\planning-with-files\scripts\session-catchup.py" (Get-Location)
```
If catchup report shows unsynced context:
@@ -55,12 +79,12 @@ If catchup report shows unsynced context:
## Important: Where Files Go
- **Templates** are in `${CLAUDE_PLUGIN_ROOT}/templates/`
- **Templates** are in `.cursor/skills/planning-with-files/templates/`
- **Your planning files** go in **your project directory**
| Location | What Goes There |
|----------|-----------------|
| Skill directory (`${CLAUDE_PLUGIN_ROOT}/`) | Templates, scripts, reference docs |
| Skill directory (`.cursor/skills/planning-with-files/`) | Templates, scripts, reference docs |
| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
## Quick Start
@@ -1,42 +1,44 @@
# 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
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
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 "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
}
Write-Host "=== Task Completion Check ==="
Write-Host ""
# Read file content
$content = Get-Content $PlanFile -Raw
# Count phases by status
# Count total phases
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
# Check for **Status:** format first
$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
# Fallback: check for [complete] inline format if **Status:** not found
if ($COMPLETE -eq 0 -and $IN_PROGRESS -eq 0 -and $PENDING -eq 0) {
$COMPLETE = ([regex]::Matches($content, "\[complete\]")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\[in_progress\]")).Count
$PENDING = ([regex]::Matches($content, "\[pending\]")).Count
}
# Report status (always exit 0 — incomplete task is a normal state)
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
} else {
Write-Host "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if ($IN_PROGRESS -gt 0) {
Write-Host "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
}
if ($PENDING -gt 0) {
Write-Host "[planning-with-files] $PENDING phase(s) pending."
}
}
exit 0
@@ -1,44 +1,46 @@
#!/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
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
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
echo "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
fi
echo "=== Task Completion Check ==="
echo ""
# Count phases by status (using -F for fixed string matching)
# Count total phases
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
# Check for **Status:** format first
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)
# Fallback: check for [complete] inline format if **Status:** not found
if [ "$COMPLETE" -eq 0 ] && [ "$IN_PROGRESS" -eq 0 ] && [ "$PENDING" -eq 0 ]; then
COMPLETE=$(grep -c "\[complete\]" "$PLAN_FILE" || true)
IN_PROGRESS=$(grep -c "\[in_progress\]" "$PLAN_FILE" || true)
PENDING=$(grep -c "\[pending\]" "$PLAN_FILE" || true)
fi
# 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
# Report status (always exit 0 — incomplete task is a normal state)
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "ALL PHASES COMPLETE"
exit 0
echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
else
echo "TASK NOT COMPLETE"
echo ""
echo "Do not stop until all phases are complete."
exit 1
echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if [ "$IN_PROGRESS" -gt 0 ]; then
echo "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
fi
if [ "$PENDING" -gt 0 ]; then
echo "[planning-with-files] $PENDING phase(s) pending."
fi
fi
exit 0
@@ -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()
+6
View File
@@ -21,6 +21,12 @@ notes.md
!examples/**/*.md
!**/templates/*.md
# ClawdHub publish folder (managed separately)
clawdhub-publish/
# Claude session files
.claude/
# Keep the skill folder clean
*.log
*.tmp
+32 -8
View File
@@ -1,6 +1,6 @@
---
name: planning-with-files
version: "2.4.1"
version: "2.10.0"
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls. Now with automatic session recovery after /clear.
user-invocable: true
allowed-tools:
@@ -27,11 +27,29 @@ hooks:
- hooks:
- type: command
command: |
SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files}/scripts"
if command -v pwsh &> /dev/null && [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" || "$OS" == "Windows_NT" ]]; then
pwsh -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null || powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null || bash "$SCRIPT_DIR/check-complete.sh"
SCRIPT_DIR="${KILOCODE_SKILL_ROOT:-$HOME/.kilocode/skills/planning-with-files}/scripts"
IS_WINDOWS=0
if [ "${OS-}" = "Windows_NT" ]; then
IS_WINDOWS=1
else
bash "$SCRIPT_DIR/check-complete.sh"
UNAME_S="$(uname -s 2>/dev/null || echo '')"
case "$UNAME_S" in
CYGWIN*|MINGW*|MSYS*) IS_WINDOWS=1 ;;
esac
fi
if [ "$IS_WINDOWS" -eq 1 ]; then
if command -v pwsh >/dev/null 2>&1; then
pwsh -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
sh "$SCRIPT_DIR/check-complete.sh"
else
powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
sh "$SCRIPT_DIR/check-complete.sh"
fi
else
sh "$SCRIPT_DIR/check-complete.sh"
fi
---
@@ -44,7 +62,13 @@ Work like Manus: Use persistent markdown files as your "working memory on disk."
**Before starting work**, check for unsynced context from a previous session:
```bash
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
# Linux/macOS (auto-detects python3 or python)
$(command -v python3 || command -v python) ~/.kilocode/skills/planning-with-files/scripts/session-catchup.py "$(pwd)"
```
```powershell
# Windows PowerShell
python "$env:USERPROFILE\.kilocode\skills\planning-with-files\scripts\session-catchup.py" (Get-Location)
```
If catchup report shows unsynced context:
@@ -55,12 +79,12 @@ If catchup report shows unsynced context:
## Important: Where Files Go
- **Templates** are in `${CLAUDE_PLUGIN_ROOT}/templates/`
- **Templates** are in `~/.kilocode/skills/planning-with-files/templates/`
- **Your planning files** go in **your project directory**
| Location | What Goes There |
|----------|-----------------|
| Skill directory (`${CLAUDE_PLUGIN_ROOT}/`) | Templates, scripts, reference docs |
| Skill directory (`~/.kilocode/skills/planning-with-files/`) | Templates, scripts, reference docs |
| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
## Quick Start
+44
View File
@@ -0,0 +1,44 @@
# Check if all phases in task_plan.md are complete
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
param(
[string]$PlanFile = "task_plan.md"
)
if (-not (Test-Path $PlanFile)) {
Write-Host "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
}
# Read file content
$content = Get-Content $PlanFile -Raw
# Count total phases
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
# Check for **Status:** format first
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
# Fallback: check for [complete] inline format if **Status:** not found
if ($COMPLETE -eq 0 -and $IN_PROGRESS -eq 0 -and $PENDING -eq 0) {
$COMPLETE = ([regex]::Matches($content, "\[complete\]")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\[in_progress\]")).Count
$PENDING = ([regex]::Matches($content, "\[pending\]")).Count
}
# Report status (always exit 0 — incomplete task is a normal state)
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
} else {
Write-Host "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if ($IN_PROGRESS -gt 0) {
Write-Host "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
}
if ($PENDING -gt 0) {
Write-Host "[planning-with-files] $PENDING phase(s) pending."
}
}
exit 0
+46
View File
@@ -0,0 +1,46 @@
#!/bin/bash
# Check if all phases in task_plan.md are complete
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
echo "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
fi
# Count total phases
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
# Check for **Status:** format first
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)
# Fallback: check for [complete] inline format if **Status:** not found
if [ "$COMPLETE" -eq 0 ] && [ "$IN_PROGRESS" -eq 0 ] && [ "$PENDING" -eq 0 ]; then
COMPLETE=$(grep -c "\[complete\]" "$PLAN_FILE" || true)
IN_PROGRESS=$(grep -c "\[in_progress\]" "$PLAN_FILE" || true)
PENDING=$(grep -c "\[pending\]" "$PLAN_FILE" || true)
fi
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
# Report status (always exit 0 — incomplete task is a normal state)
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
else
echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if [ "$IN_PROGRESS" -gt 0 ]; then
echo "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
fi
if [ "$PENDING" -gt 0 ]; then
echo "[planning-with-files] $PENDING phase(s) pending."
fi
fi
exit 0
+120
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
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"
+71
View File
@@ -0,0 +1,71 @@
# Planning Rules
Critical rules for effective file-based planning.
## Rule 1: Create Plan First
Never start a complex task without `task_plan.md`. Non-negotiable.
## Rule 2: The 2-Action Rule
After every 2 view/browser/search operations, IMMEDIATELY save key findings to `findings.md`.
This prevents visual/multimodal information from being lost.
## Rule 3: Read Before Decide
Before major decisions, read `task_plan.md`. This keeps goals in your attention window.
## Rule 4: Update After Act
After completing any phase:
- Mark phase status: `in_progress` → `complete`
- Log any errors encountered
- Note files created/modified
## Rule 5: Log ALL Errors
Every error goes in the plan file with this format:
```markdown
## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |
| API timeout | 2 | Added retry logic |
```
## Rule 6: Never Repeat Failures
If an action failed, the next action must be different. Track what you tried and 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
→ 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
```
## 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 |
+88
View File
@@ -0,0 +1,88 @@
# Planning File Templates
Copy these templates to your project root when starting complex tasks.
## task_plan.md Template
```markdown
# Task Plan
## Goal
[One sentence describing the end state]
## Current Phase
Phase X: [Name] - [Status]
## Phases
### Phase 1: [Name]
**Status:** pending | in_progress | complete
- [ ] Step 1
- [ ] Step 2
### Phase 2: [Name]
**Status:** pending
- [ ] Step 1
- [ ] Step 2
## Key Questions
- Question 1?
- Question 2?
## Decisions Made
| Decision | Rationale | Date |
|----------|-----------|------|
## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
```
## findings.md Template
```markdown
# Findings
## Requirements
- Requirement 1
- Requirement 2
## Research Findings
### [Topic 1]
- Finding 1
- Finding 2
## Technical Decisions
| Decision | Options Considered | Chosen | Why |
|----------|-------------------|--------|-----|
## Resources
- [Resource 1](url)
- [Resource 2](url)
```
## progress.md Template
```markdown
# Progress Log
## Session: [Date]
**Phase:** [Current phase]
**Start Time:** [Time]
### Actions Taken
1. Action 1
2. Action 2
### Files Modified
- `file1.js` — Added feature X
- `file2.py` — Fixed bug Y
### Test Results
| Test | Input | Expected | Actual | Status |
|------|-------|----------|--------|--------|
### Error Log
| Time | Error | Attempt | Resolution |
|------|-------|---------|------------|
```
+43
View File
@@ -0,0 +1,43 @@
# Planning with Files Workflow
Use persistent markdown files as your "working memory on disk" — the Manus pattern that made a $2B acquisition.
## The Core Pattern
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
```
## Required Files
Create these three files in your project root before starting complex tasks:
| 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 |
## Quick Start
1. **Create `task_plan.md`** with goal, phases, and status tracking
2. **Create `findings.md`** for research and technical decisions
3. **Create `progress.md`** for session logging
4. **Re-read plan before decisions** — keeps goals in attention
5. **Update after each phase** — mark complete, log errors
## When to Use This Pattern
**Use for:**
- Multi-step tasks (3+ steps)
- Research tasks
- Building/creating projects
- Tasks spanning many tool calls
**Skip for:**
- Simple questions
- Single-file edits
- Quick lookups
@@ -0,0 +1,180 @@
---
name: planning-with-files
version: "2.10.0"
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls.
homepage: https://github.com/OthmanAdi/planning-with-files
user-invocable: true
metadata: {"openclaw":{"os":["darwin","linux","win32"]}}
---
# Planning with Files
Work like Manus: Use persistent markdown files as your "working memory on disk."
## Important: Where Files Go
- **Templates** are in this skill's `templates/` folder
- **Your planning files** go in **your project directory**
| Location | What Goes There |
|----------|-----------------|
| Skill directory | Templates, scripts, reference docs |
| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
## Quick Start
Before ANY complex task:
1. **Create `task_plan.md`** — Use [templates/task_plan.md](templates/task_plan.md) as reference
2. **Create `findings.md`** — Use [templates/findings.md](templates/findings.md) as reference
3. **Create `progress.md`** — Use [templates/progress.md](templates/progress.md) as reference
4. **Re-read plan before decisions** — Refreshes goals in attention window
5. **Update after each phase** — Mark complete, log errors
> **Note:** Planning files go in your project root, not the skill installation folder.
## The Core Pattern
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
```
## File Purposes
| File | Purpose | When to Update |
|------|---------|----------------|
| `task_plan.md` | Phases, progress, decisions | After each phase |
| `findings.md` | Research, discoveries | After ANY discovery |
| `progress.md` | Session log, test results | Throughout session |
## Critical Rules
### 1. Create Plan First
Never start a complex task without `task_plan.md`. Non-negotiable.
### 2. The 2-Action Rule
> "After every 2 view/browser/search operations, IMMEDIATELY save key findings to text files."
This prevents visual/multimodal information from being lost.
### 3. Read Before Decide
Before major decisions, read the plan file. This keeps goals in your attention window.
### 4. Update After Act
After completing any phase:
- Mark phase status: `in_progress` → `complete`
- Log any errors encountered
- Note files created/modified
### 5. Log ALL Errors
Every error goes in the plan file. This builds knowledge and prevents repetition.
```markdown
## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |
| API timeout | 2 | Added retry logic |
```
### 6. Never Repeat Failures
```
if action_failed:
next_action != same_action
```
Track what you tried. Mutate the approach.
## The 3-Strike Error Protocol
```
ATTEMPT 1: Diagnose & Fix
→ Read error carefully
→ Identify root cause
→ Apply targeted fix
ATTEMPT 2: Alternative Approach
→ Same error? Try different method
→ Different tool? Different library?
→ NEVER repeat exact same failing action
ATTEMPT 3: Broader Rethink
→ Question assumptions
→ Search for solutions
→ Consider updating the plan
AFTER 3 FAILURES: Escalate to User
→ Explain what you tried
→ Share the specific error
→ Ask for guidance
```
## Read vs Write Decision Matrix
| Situation | Action | Reason |
|-----------|--------|--------|
| Just wrote a file | DON'T read | Content still in context |
| Viewed image/PDF | Write findings NOW | Multimodal → text before lost |
| Browser returned data | Write to file | Screenshots don't persist |
| Starting new phase | Read plan/findings | Re-orient if context stale |
| Error occurred | Read relevant file | Need current state to fix |
| Resuming after gap | Read all planning files | Recover state |
## The 5-Question Reboot Test
If you can answer these, your context management is solid:
| Question | Answer Source |
|----------|---------------|
| Where am I? | Current phase in task_plan.md |
| Where am I going? | Remaining phases |
| What's the goal? | Goal statement in plan |
| What have I learned? | findings.md |
| What have I done? | progress.md |
## When to Use This Pattern
**Use for:**
- Multi-step tasks (3+ steps)
- Research tasks
- Building/creating projects
- Tasks spanning many tool calls
- Anything requiring organization
**Skip for:**
- Simple questions
- Single-file edits
- Quick lookups
## Templates
Copy these templates to start:
- [templates/task_plan.md](templates/task_plan.md) — Phase tracking
- [templates/findings.md](templates/findings.md) — Research storage
- [templates/progress.md](templates/progress.md) — Session logging
## Scripts
Helper scripts for automation:
- `scripts/init-session.sh` — Initialize all planning files
- `scripts/check-complete.sh` — Verify all phases complete
## Advanced Topics
- **Manus Principles:** See [references/reference.md](references/reference.md)
- **Real Examples:** See [references/examples.md](references/examples.md)
## Anti-Patterns
| Don't | Do Instead |
|-------|------------|
| State goals once and forget | Re-read plan before decisions |
| Hide errors and retry silently | Log errors to plan file |
| Stuff everything in context | Store large content in files |
| Start executing immediately | Create plan file FIRST |
| Repeat failed actions | Track attempts, mutate approach |
| Create files in skill directory | Create files in your project |
@@ -0,0 +1,202 @@
# Examples: Planning with Files in Action
## Example 1: Research Task
**User Request:** "Research the benefits of morning exercise and write a summary"
### Loop 1: Create Plan
```bash
Write task_plan.md
```
```markdown
# Task Plan: Morning Exercise Benefits Research
## Goal
Create a research summary on the benefits of morning exercise.
## Phases
- [ ] Phase 1: Create this plan ✓
- [ ] Phase 2: Search and gather sources
- [ ] Phase 3: Synthesize findings
- [ ] Phase 4: Deliver summary
## Key Questions
1. What are the physical health benefits?
2. What are the mental health benefits?
3. What scientific studies support this?
## Status
**Currently in Phase 1** - Creating plan
```
### Loop 2: Research
```bash
Read task_plan.md # Refresh goals
WebSearch "morning exercise benefits"
Write notes.md # Store findings
Edit task_plan.md # Mark Phase 2 complete
```
### Loop 3: Synthesize
```bash
Read task_plan.md # Refresh goals
Read notes.md # Get findings
Write morning_exercise_summary.md
Edit task_plan.md # Mark Phase 3 complete
```
### Loop 4: Deliver
```bash
Read task_plan.md # Verify complete
Deliver morning_exercise_summary.md
```
---
## Example 2: Bug Fix Task
**User Request:** "Fix the login bug in the authentication module"
### task_plan.md
```markdown
# Task Plan: Fix Login Bug
## Goal
Identify and fix the bug preventing successful login.
## Phases
- [x] Phase 1: Understand the bug report ✓
- [x] Phase 2: Locate relevant code ✓
- [ ] Phase 3: Identify root cause (CURRENT)
- [ ] Phase 4: Implement fix
- [ ] Phase 5: Test and verify
## Key Questions
1. What error message appears?
2. Which file handles authentication?
3. What changed recently?
## Decisions Made
- Auth handler is in src/auth/login.ts
- Error occurs in validateToken() function
## Errors Encountered
- [Initial] TypeError: Cannot read property 'token' of undefined
→ Root cause: user object not awaited properly
## Status
**Currently in Phase 3** - Found root cause, preparing fix
```
---
## Example 3: Feature Development
**User Request:** "Add a dark mode toggle to the settings page"
### The 3-File Pattern in Action
**task_plan.md:**
```markdown
# Task Plan: Dark Mode Toggle
## Goal
Add functional dark mode toggle to settings.
## Phases
- [x] Phase 1: Research existing theme system ✓
- [x] Phase 2: Design implementation approach ✓
- [ ] Phase 3: Implement toggle component (CURRENT)
- [ ] Phase 4: Add theme switching logic
- [ ] Phase 5: Test and polish
## Decisions Made
- Using CSS custom properties for theme
- Storing preference in localStorage
- Toggle component in SettingsPage.tsx
## Status
**Currently in Phase 3** - Building toggle component
```
**notes.md:**
```markdown
# Notes: Dark Mode Implementation
## Existing Theme System
- Located in: src/styles/theme.ts
- Uses: CSS custom properties
- Current themes: light only
## Files to Modify
1. src/styles/theme.ts - Add dark theme colors
2. src/components/SettingsPage.tsx - Add toggle
3. src/hooks/useTheme.ts - Create new hook
4. src/App.tsx - Wrap with ThemeProvider
## Color Decisions
- Dark background: #1a1a2e
- Dark surface: #16213e
- Dark text: #eaeaea
```
**dark_mode_implementation.md:** (deliverable)
```markdown
# Dark Mode Implementation
## Changes Made
### 1. Added dark theme colors
File: src/styles/theme.ts
...
### 2. Created useTheme hook
File: src/hooks/useTheme.ts
...
```
---
## Example 4: Error Recovery Pattern
When something fails, DON'T hide it:
### Before (Wrong)
```
Action: Read config.json
Error: File not found
Action: Read config.json # Silent retry
Action: Read config.json # Another retry
```
### After (Correct)
```
Action: Read config.json
Error: File not found
# Update task_plan.md:
## Errors Encountered
- config.json not found → Will create default config
Action: Write config.json (default config)
Action: Read config.json
Success!
```
---
## The Read-Before-Decide Pattern
**Always read your plan before major decisions:**
```
[Many tool calls have happened...]
[Context is getting long...]
[Original goal might be forgotten...]
→ Read task_plan.md # This brings goals back into attention!
→ Now make the decision # Goals are fresh in context
```
This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a "goal refresh" mechanism.
@@ -0,0 +1,218 @@
# Reference: Manus Context Engineering Principles
This skill is based on context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
## The 6 Manus Principles
### Principle 1: Design Around KV-Cache
> "KV-cache hit rate is THE single most important metric for production AI agents."
**Statistics:**
- ~100:1 input-to-output token ratio
- Cached tokens: $0.30/MTok vs Uncached: $3/MTok
- 10x cost difference!
**Implementation:**
- Keep prompt prefixes STABLE (single-token change invalidates cache)
- NO timestamps in system prompts
- Make context APPEND-ONLY with deterministic serialization
### Principle 2: Mask, Don't Remove
Don't dynamically remove tools (breaks KV-cache). Use logit masking instead.
**Best Practice:** Use consistent action prefixes (e.g., `browser_`, `shell_`, `file_`) for easier masking.
### Principle 3: Filesystem as External Memory
> "Markdown is my 'working memory' on disk."
**The Formula:**
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
```
**Compression Must Be Restorable:**
- Keep URLs even if web content is dropped
- Keep file paths when dropping document contents
- Never lose the pointer to full data
### Principle 4: Manipulate Attention Through Recitation
> "Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."
**Problem:** After ~50 tool calls, models forget original goals ("lost in the middle" effect).
**Solution:** Re-read `task_plan.md` before each decision. Goals appear in the attention window.
```
Start of context: [Original goal - far away, forgotten]
...many tool calls...
End of context: [Recently read task_plan.md - gets ATTENTION!]
```
### Principle 5: Keep the Wrong Stuff In
> "Leave the wrong turns in the context."
**Why:**
- Failed actions with stack traces let model implicitly update beliefs
- Reduces mistake repetition
- Error recovery is "one of the clearest signals of TRUE agentic behavior"
### Principle 6: Don't Get Few-Shotted
> "Uniformity breeds fragility."
**Problem:** Repetitive action-observation pairs cause drift and hallucination.
**Solution:** Introduce controlled variation:
- Vary phrasings slightly
- Don't copy-paste patterns blindly
- Recalibrate on repetitive tasks
---
## The 3 Context Engineering Strategies
Based on Lance Martin's analysis of Manus architecture.
### Strategy 1: Context Reduction
**Compaction:**
```
Tool calls have TWO representations:
├── FULL: Raw tool content (stored in filesystem)
└── COMPACT: Reference/file path only
RULES:
- Apply compaction to STALE (older) tool results
- Keep RECENT results FULL (to guide next decision)
```
**Summarization:**
- Applied when compaction reaches diminishing returns
- Generated using full tool results
- Creates standardized summary objects
### Strategy 2: Context Isolation (Multi-Agent)
**Architecture:**
```
┌─────────────────────────────────┐
│ PLANNER AGENT │
│ └─ Assigns tasks to sub-agents │
├─────────────────────────────────┤
│ KNOWLEDGE MANAGER │
│ └─ Reviews conversations │
│ └─ Determines filesystem store │
├─────────────────────────────────┤
│ EXECUTOR SUB-AGENTS │
│ └─ Perform assigned tasks │
│ └─ Have own context windows │
└─────────────────────────────────┘
```
**Key Insight:** Manus originally used `todo.md` for task planning but found ~33% of actions were spent updating it. Shifted to dedicated planner agent calling executor sub-agents.
### Strategy 3: Context Offloading
**Tool Design:**
- Use <20 atomic functions total
- Store full results in filesystem, not context
- Use `glob` and `grep` for searching
- Progressive disclosure: load information only as needed
---
## The Agent Loop
Manus operates in a continuous 7-step loop:
```
┌─────────────────────────────────────────┐
│ 1. ANALYZE CONTEXT │
│ - Understand user intent │
│ - Assess current state │
│ - Review recent observations │
├─────────────────────────────────────────┤
│ 2. THINK │
│ - Should I update the plan? │
│ - What's the next logical action? │
│ - Are there blockers? │
├─────────────────────────────────────────┤
│ 3. SELECT TOOL │
│ - Choose ONE tool │
│ - Ensure parameters available │
├─────────────────────────────────────────┤
│ 4. EXECUTE ACTION │
│ - Tool runs in sandbox │
├─────────────────────────────────────────┤
│ 5. RECEIVE OBSERVATION │
│ - Result appended to context │
├─────────────────────────────────────────┤
│ 6. ITERATE │
│ - Return to step 1 │
│ - Continue until complete │
├─────────────────────────────────────────┤
│ 7. DELIVER OUTCOME │
│ - Send results to user │
│ - Attach all relevant files │
└─────────────────────────────────────────┘
```
---
## File Types Manus Creates
| File | Purpose | When Created | When Updated |
|------|---------|--------------|--------------|
| `task_plan.md` | Phase tracking, progress | Task start | After completing phases |
| `findings.md` | Discoveries, decisions | After ANY discovery | After viewing images/PDFs |
| `progress.md` | Session log, what's done | At breakpoints | Throughout session |
| Code files | Implementation | Before execution | After errors |
---
## Critical Constraints
- **Single-Action Execution:** ONE tool call per turn. No parallel execution.
- **Plan is Required:** Agent must ALWAYS know: goal, current phase, remaining phases
- **Files are Memory:** Context = volatile. Filesystem = persistent.
- **Never Repeat Failures:** If action failed, next action MUST be different
- **Communication is a Tool:** Message types: `info` (progress), `ask` (blocking), `result` (terminal)
---
## Manus Statistics
| Metric | Value |
|--------|-------|
| Average tool calls per task | ~50 |
| Input-to-output token ratio | 100:1 |
| Acquisition price | $2 billion |
| Time to $100M revenue | 8 months |
| Framework refactors since launch | 5 times |
---
## Key Quotes
> "Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."
> "if action_failed: next_action != same_action. Track what you tried. Mutate the approach."
> "Error recovery is one of the clearest signals of TRUE agentic behavior."
> "KV-cache hit rate is the single most important metric for a production-stage AI agent."
> "Leave the wrong turns in the context."
---
## Source
Based on Manus's official context engineering documentation:
https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
@@ -0,0 +1,44 @@
# Check if all phases in task_plan.md are complete
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
param(
[string]$PlanFile = "task_plan.md"
)
if (-not (Test-Path $PlanFile)) {
Write-Host "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
}
# Read file content
$content = Get-Content $PlanFile -Raw
# Count total phases
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
# Check for **Status:** format first
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
# Fallback: check for [complete] inline format if **Status:** not found
if ($COMPLETE -eq 0 -and $IN_PROGRESS -eq 0 -and $PENDING -eq 0) {
$COMPLETE = ([regex]::Matches($content, "\[complete\]")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\[in_progress\]")).Count
$PENDING = ([regex]::Matches($content, "\[pending\]")).Count
}
# Report status (always exit 0 — incomplete task is a normal state)
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
} else {
Write-Host "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if ($IN_PROGRESS -gt 0) {
Write-Host "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
}
if ($PENDING -gt 0) {
Write-Host "[planning-with-files] $PENDING phase(s) pending."
}
}
exit 0
@@ -0,0 +1,46 @@
#!/bin/bash
# Check if all phases in task_plan.md are complete
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
echo "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
fi
# Count total phases
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
# Check for **Status:** format first
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)
# Fallback: check for [complete] inline format if **Status:** not found
if [ "$COMPLETE" -eq 0 ] && [ "$IN_PROGRESS" -eq 0 ] && [ "$PENDING" -eq 0 ]; then
COMPLETE=$(grep -c "\[complete\]" "$PLAN_FILE" || true)
IN_PROGRESS=$(grep -c "\[in_progress\]" "$PLAN_FILE" || true)
PENDING=$(grep -c "\[pending\]" "$PLAN_FILE" || true)
fi
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
# Report status (always exit 0 — incomplete task is a normal state)
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
else
echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if [ "$IN_PROGRESS" -gt 0 ]; then
echo "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
fi
if [ "$PENDING" -gt 0 ]; then
echo "[planning-with-files] $PENDING phase(s) pending."
fi
fi
exit 0
@@ -0,0 +1,120 @@
# Initialize planning files for a new session
# Usage: .\init-session.ps1 [project-name]
param(
[string]$ProjectName = "project"
)
$DATE = Get-Date -Format "yyyy-MM-dd"
Write-Host "Initializing planning files for: $ProjectName"
# Create task_plan.md if it doesn't exist
if (-not (Test-Path "task_plan.md")) {
@"
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
Write-Host "Created task_plan.md"
} else {
Write-Host "task_plan.md already exists, skipping"
}
# Create findings.md if it doesn't exist
if (-not (Test-Path "findings.md")) {
@"
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
"@ | Out-File -FilePath "findings.md" -Encoding UTF8
Write-Host "Created findings.md"
} else {
Write-Host "findings.md already exists, skipping"
}
# Create progress.md if it doesn't exist
if (-not (Test-Path "progress.md")) {
@"
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
Write-Host "Created progress.md"
} else {
Write-Host "progress.md already exists, skipping"
}
Write-Host ""
Write-Host "Planning files initialized!"
Write-Host "Files: task_plan.md, findings.md, progress.md"
@@ -0,0 +1,120 @@
#!/bin/bash
# Initialize planning files for a new session
# Usage: ./init-session.sh [project-name]
set -e
PROJECT_NAME="${1:-project}"
DATE=$(date +%Y-%m-%d)
echo "Initializing planning files for: $PROJECT_NAME"
# Create task_plan.md if it doesn't exist
if [ ! -f "task_plan.md" ]; then
cat > task_plan.md << 'EOF'
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
EOF
echo "Created task_plan.md"
else
echo "task_plan.md already exists, skipping"
fi
# Create findings.md if it doesn't exist
if [ ! -f "findings.md" ]; then
cat > findings.md << 'EOF'
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
EOF
echo "Created findings.md"
else
echo "findings.md already exists, skipping"
fi
# Create progress.md if it doesn't exist
if [ ! -f "progress.md" ]; then
cat > progress.md << EOF
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
EOF
echo "Created progress.md"
else
echo "progress.md already exists, skipping"
fi
echo ""
echo "Planning files initialized!"
echo "Files: task_plan.md, findings.md, progress.md"
@@ -0,0 +1,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()
@@ -0,0 +1,95 @@
# Findings & Decisions
<!--
WHAT: Your knowledge base for the task. Stores everything you discover and decide.
WHY: Context windows are limited. This file is your "external memory" - persistent and unlimited.
WHEN: Update after ANY discovery, especially after 2 view/browser/search operations (2-Action Rule).
-->
## Requirements
<!--
WHAT: What the user asked for, broken down into specific requirements.
WHY: Keeps requirements visible so you don't forget what you're building.
WHEN: Fill this in during Phase 1 (Requirements & Discovery).
EXAMPLE:
- Command-line interface
- Add tasks
- List all tasks
- Delete tasks
- Python implementation
-->
<!-- Captured from user request -->
-
## Research Findings
<!--
WHAT: Key discoveries from web searches, documentation reading, or exploration.
WHY: Multimodal content (images, browser results) doesn't persist. Write it down immediately.
WHEN: After EVERY 2 view/browser/search operations, update this section (2-Action Rule).
EXAMPLE:
- Python's argparse module supports subcommands for clean CLI design
- JSON module handles file persistence easily
- Standard pattern: python script.py <command> [args]
-->
<!-- Key discoveries during exploration -->
-
## Technical Decisions
<!--
WHAT: Architecture and implementation choices you've made, with reasoning.
WHY: You'll forget why you chose a technology or approach. This table preserves that knowledge.
WHEN: Update whenever you make a significant technical choice.
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
| argparse with subcommands | Clean CLI: python todo.py add "task" |
-->
<!-- Decisions made with rationale -->
| Decision | Rationale |
|----------|-----------|
| | |
## Issues Encountered
<!--
WHAT: Problems you ran into and how you solved them.
WHY: Similar to errors in task_plan.md, but focused on broader issues (not just code errors).
WHEN: Document when you encounter blockers or unexpected challenges.
EXAMPLE:
| Empty file causes JSONDecodeError | Added explicit empty file check before json.load() |
-->
<!-- Errors and how they were resolved -->
| Issue | Resolution |
|-------|------------|
| | |
## Resources
<!--
WHAT: URLs, file paths, API references, documentation links you've found useful.
WHY: Easy reference for later. Don't lose important links in context.
WHEN: Add as you discover useful resources.
EXAMPLE:
- Python argparse docs: https://docs.python.org/3/library/argparse.html
- Project structure: src/main.py, src/utils.py
-->
<!-- URLs, file paths, API references -->
-
## Visual/Browser Findings
<!--
WHAT: Information you learned from viewing images, PDFs, or browser results.
WHY: CRITICAL - Visual/multimodal content doesn't persist in context. Must be captured as text.
WHEN: IMMEDIATELY after viewing images or browser results. Don't wait!
EXAMPLE:
- Screenshot shows login form has email and password fields
- Browser shows API returns JSON with "status" and "data" keys
-->
<!-- CRITICAL: Update after every 2 view/browser operations -->
<!-- Multimodal content must be captured as text immediately -->
-
---
<!--
REMINDER: The 2-Action Rule
After every 2 view/browser/search operations, you MUST update this file.
This prevents visual information from being lost when context resets.
-->
*Update this file after every 2 view/browser/search operations*
*This prevents visual information from being lost*
@@ -0,0 +1,114 @@
# Progress Log
<!--
WHAT: Your session log - a chronological record of what you did, when, and what happened.
WHY: Answers "What have I done?" in the 5-Question Reboot Test. Helps you resume after breaks.
WHEN: Update after completing each phase or encountering errors. More detailed than task_plan.md.
-->
## Session: [DATE]
<!--
WHAT: The date of this work session.
WHY: Helps track when work happened, useful for resuming after time gaps.
EXAMPLE: 2026-01-15
-->
### Phase 1: [Title]
<!--
WHAT: Detailed log of actions taken during this phase.
WHY: Provides context for what was done, making it easier to resume or debug.
WHEN: Update as you work through the phase, or at least when you complete it.
-->
- **Status:** in_progress
- **Started:** [timestamp]
<!--
STATUS: Same as task_plan.md (pending, in_progress, complete)
TIMESTAMP: When you started this phase (e.g., "2026-01-15 10:00")
-->
- Actions taken:
<!--
WHAT: List of specific actions you performed.
EXAMPLE:
- Created todo.py with basic structure
- Implemented add functionality
- Fixed FileNotFoundError
-->
-
- Files created/modified:
<!--
WHAT: Which files you created or changed.
WHY: Quick reference for what was touched. Helps with debugging and review.
EXAMPLE:
- todo.py (created)
- todos.json (created by app)
- task_plan.md (updated)
-->
-
### Phase 2: [Title]
<!--
WHAT: Same structure as Phase 1, for the next phase.
WHY: Keep a separate log entry for each phase to track progress clearly.
-->
- **Status:** pending
- Actions taken:
-
- Files created/modified:
-
## Test Results
<!--
WHAT: Table of tests you ran, what you expected, what actually happened.
WHY: Documents verification of functionality. Helps catch regressions.
WHEN: Update as you test features, especially during Phase 4 (Testing & Verification).
EXAMPLE:
| Add task | python todo.py add "Buy milk" | Task added | Task added successfully | ✓ |
| List tasks | python todo.py list | Shows all tasks | Shows all tasks | ✓ |
-->
| Test | Input | Expected | Actual | Status |
|------|-------|----------|--------|--------|
| | | | | |
## Error Log
<!--
WHAT: Detailed log of every error encountered, with timestamps and resolution attempts.
WHY: More detailed than task_plan.md's error table. Helps you learn from mistakes.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| 2026-01-15 10:35 | FileNotFoundError | 1 | Added file existence check |
| 2026-01-15 10:37 | JSONDecodeError | 2 | Added empty file handling |
-->
<!-- Keep ALL errors - they help avoid repetition -->
| Timestamp | Error | Attempt | Resolution |
|-----------|-------|---------|------------|
| | | 1 | |
## 5-Question Reboot Check
<!--
WHAT: Five questions that verify your context is solid. If you can answer these, you're on track.
WHY: This is the "reboot test" - if you can answer all 5, you can resume work effectively.
WHEN: Update periodically, especially when resuming after a break or context reset.
THE 5 QUESTIONS:
1. Where am I? → Current phase in task_plan.md
2. Where am I going? → Remaining phases
3. What's the goal? → Goal statement in task_plan.md
4. What have I learned? → See findings.md
5. What have I done? → See progress.md (this file)
-->
<!-- If you can answer these, context is solid -->
| Question | Answer |
|----------|--------|
| Where am I? | Phase X |
| Where am I going? | Remaining phases |
| What's the goal? | [goal statement] |
| What have I learned? | See findings.md |
| What have I done? | See above |
---
<!--
REMINDER:
- Update after completing each phase or encountering errors
- Be detailed - this is your "what happened" log
- Include timestamps for errors to track when issues occurred
-->
*Update after completing each phase or encountering errors*
@@ -0,0 +1,132 @@
# Task Plan: [Brief Description]
<!--
WHAT: This is your roadmap for the entire task. Think of it as your "working memory on disk."
WHY: After 50+ tool calls, your original goals can get forgotten. This file keeps them fresh.
WHEN: Create this FIRST, before starting any work. Update after each phase completes.
-->
## Goal
<!--
WHAT: One clear sentence describing what you're trying to achieve.
WHY: This is your north star. Re-reading this keeps you focused on the end state.
EXAMPLE: "Create a Python CLI todo app with add, list, and delete functionality."
-->
[One sentence describing the end state]
## Current Phase
<!--
WHAT: Which phase you're currently working on (e.g., "Phase 1", "Phase 3").
WHY: Quick reference for where you are in the task. Update this as you progress.
-->
Phase 1
## Phases
<!--
WHAT: Break your task into 3-7 logical phases. Each phase should be completable.
WHY: Breaking work into phases prevents overwhelm and makes progress visible.
WHEN: Update status after completing each phase: pending → in_progress → complete
-->
### Phase 1: Requirements & Discovery
<!--
WHAT: Understand what needs to be done and gather initial information.
WHY: Starting without understanding leads to wasted effort. This phase prevents that.
-->
- [ ] Understand user intent
- [ ] Identify constraints and requirements
- [ ] Document findings in findings.md
- **Status:** in_progress
<!--
STATUS VALUES:
- pending: Not started yet
- in_progress: Currently working on this
- complete: Finished this phase
-->
### Phase 2: Planning & Structure
<!--
WHAT: Decide how you'll approach the problem and what structure you'll use.
WHY: Good planning prevents rework. Document decisions so you remember why you chose them.
-->
- [ ] Define technical approach
- [ ] Create project structure if needed
- [ ] Document decisions with rationale
- **Status:** pending
### Phase 3: Implementation
<!--
WHAT: Actually build/create/write the solution.
WHY: This is where the work happens. Break into smaller sub-tasks if needed.
-->
- [ ] Execute the plan step by step
- [ ] Write code to files before executing
- [ ] Test incrementally
- **Status:** pending
### Phase 4: Testing & Verification
<!--
WHAT: Verify everything works and meets requirements.
WHY: Catching issues early saves time. Document test results in progress.md.
-->
- [ ] Verify all requirements met
- [ ] Document test results in progress.md
- [ ] Fix any issues found
- **Status:** pending
### Phase 5: Delivery
<!--
WHAT: Final review and handoff to user.
WHY: Ensures nothing is forgotten and deliverables are complete.
-->
- [ ] Review all output files
- [ ] Ensure deliverables are complete
- [ ] Deliver to user
- **Status:** pending
## Key Questions
<!--
WHAT: Important questions you need to answer during the task.
WHY: These guide your research and decision-making. Answer them as you go.
EXAMPLE:
1. Should tasks persist between sessions? (Yes - need file storage)
2. What format for storing tasks? (JSON file)
-->
1. [Question to answer]
2. [Question to answer]
## Decisions Made
<!--
WHAT: Technical and design decisions you've made, with the reasoning behind them.
WHY: You'll forget why you made choices. This table helps you remember and justify decisions.
WHEN: Update whenever you make a significant choice (technology, approach, structure).
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
-->
| Decision | Rationale |
|----------|-----------|
| | |
## Errors Encountered
<!--
WHAT: Every error you encounter, what attempt number it was, and how you resolved it.
WHY: Logging errors prevents repeating the same mistakes. This is critical for learning.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| FileNotFoundError | 1 | Check if file exists, create empty list if not |
| JSONDecodeError | 2 | Handle empty file case explicitly |
-->
| Error | Attempt | Resolution |
|-------|---------|------------|
| | 1 | |
## Notes
<!--
REMINDERS:
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
- Never repeat a failed action - mutate your approach instead
-->
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
+32 -8
View File
@@ -1,6 +1,6 @@
---
name: planning-with-files
version: "2.4.1"
version: "2.10.0"
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls. Now with automatic session recovery after /clear.
user-invocable: true
allowed-tools:
@@ -27,11 +27,29 @@ hooks:
- hooks:
- type: command
command: |
SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files}/scripts"
if command -v pwsh &> /dev/null && [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" || "$OS" == "Windows_NT" ]]; then
pwsh -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null || powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null || bash "$SCRIPT_DIR/check-complete.sh"
SCRIPT_DIR="${OPENCODE_SKILL_ROOT:-$HOME/.config/opencode/skills/planning-with-files}/scripts"
IS_WINDOWS=0
if [ "${OS-}" = "Windows_NT" ]; then
IS_WINDOWS=1
else
bash "$SCRIPT_DIR/check-complete.sh"
UNAME_S="$(uname -s 2>/dev/null || echo '')"
case "$UNAME_S" in
CYGWIN*|MINGW*|MSYS*) IS_WINDOWS=1 ;;
esac
fi
if [ "$IS_WINDOWS" -eq 1 ]; then
if command -v pwsh >/dev/null 2>&1; then
pwsh -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
sh "$SCRIPT_DIR/check-complete.sh"
else
powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
sh "$SCRIPT_DIR/check-complete.sh"
fi
else
sh "$SCRIPT_DIR/check-complete.sh"
fi
---
@@ -44,7 +62,13 @@ Work like Manus: Use persistent markdown files as your "working memory on disk."
**Before starting work**, check for unsynced context from a previous session:
```bash
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
# Linux/macOS (auto-detects python3 or python)
$(command -v python3 || command -v python) ~/.config/opencode/skills/planning-with-files/scripts/session-catchup.py "$(pwd)"
```
```powershell
# Windows PowerShell
python "$env:USERPROFILE\.opencode\skills\planning-with-files\scripts\session-catchup.py" (Get-Location)
```
If catchup report shows unsynced context:
@@ -55,12 +79,12 @@ If catchup report shows unsynced context:
## Important: Where Files Go
- **Templates** are in `${CLAUDE_PLUGIN_ROOT}/templates/`
- **Templates** are in `~/.config/opencode/skills/planning-with-files/templates/`
- **Your planning files** go in **your project directory**
| Location | What Goes There |
|----------|-----------------|
| Skill directory (`${CLAUDE_PLUGIN_ROOT}/`) | Templates, scripts, reference docs |
| Skill directory (`~/.config/opencode/skills/planning-with-files/`) | Templates, scripts, reference docs |
| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
## Quick Start
+81
View File
@@ -0,0 +1,81 @@
# Pi Planning With Files
> **Work like Manus** — Use persistent markdown files as your "working memory on disk."
A [Pi Coding Agent](https://pi.dev) skill that transforms your workflow to use persistent markdown files for planning, progress tracking, and knowledge storage.
## The Problem
Most AI agents suffer from:
- **Volatile memory** — Context resets lose history
- **Goal drift** — Long tasks lose focus
- **Hidden errors** — Failures aren't tracked
## The Solution
For every complex task, create THREE files:
- `task_plan.md` (Phases & Progress)
- `findings.md` (Research & Notes)
- `progress.md` (Session Log)
---
## Installation
### Pi Install
```bash
pi install npm:pi-planning-with-files
```
### Manual Install
1. Navigate to your project root.
2. Create the `.pi/skills` directory if it doesn't exist.
3. Copy the `planning-with-files` skill folder into `.pi/skills/`.
---
## Usage
Pi Agent automatically discovers skills in `.pi/skills` or installed via NPM.
### Start Planning
Ask Pi:
```
Use the planning-with-files skill to help me with this task.
```
Or:
```
Start by creating task_plan.md.
```
## Important Limitations
> **Note:** Hooks (PreToolUse, PostToolUse, Stop) are **Claude Code specific** and are not currently supported in Pi Agent.
### What works in Pi Agent:
- 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
- Session Recovery (via `session-catchup.py`)
### Session Recovery
If you clear context, recover your state:
```bash
python3 .pi/skills/planning-with-files/scripts/session-catchup.py .
```
## File Structure
When installed, the skill provides templates to create:
```
your-project/
├── task_plan.md
├── findings.md
├── progress.md
```
+204
View File
@@ -0,0 +1,204 @@
---
name: pi-planning-with-files
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls
---
# Planning with Files
Work like Manus: Use persistent markdown files as your "working memory on disk."
## FIRST: Check for Previous Session
**Before starting work**, check for unsynced context from a previous session:
> **Note:** The `scripts/` directory is inside this skill's installation folder.
```bash
# Linux/macOS
python scripts/session-catchup.py "$(pwd)"
```
```powershell
# Windows PowerShell
python scripts\session-catchup.py" (Get-Location)
```
**If you cannot find the script:**
Ask Pi to locate it for you:
`Run the session-catchup.py script from the planning-with-files skill`
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 `templates/` inside this skill
- **Your planning files** go in **your project directory**
| Location | What Goes There |
|----------|-----------------|
| Skill directory | Templates, scripts, reference docs |
| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
## Quick Start
Before ANY complex task:
1. **Create `task_plan.md`** — Use [templates/task_plan.md](templates/task_plan.md) as reference
2. **Create `findings.md`** — Use [templates/findings.md](templates/findings.md) as reference
3. **Create `progress.md`** — Use [templates/progress.md](templates/progress.md) as reference
4. **Re-read plan before decisions** — Refreshes goals in attention window
5. **Update after each phase** — Mark complete, log errors
> **Note:** Planning files go in your project root, not the skill installation folder.
## The Core Pattern
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
```
## File Purposes
| File | Purpose | When to Update |
|------|---------|----------------|
| `task_plan.md` | Phases, progress, decisions | After each phase |
| `findings.md` | Research, discoveries | After ANY discovery |
| `progress.md` | Session log, test results | Throughout session |
## Critical Rules
### 1. Create Plan First
Never start a complex task without `task_plan.md`. Non-negotiable.
### 2. The 2-Action Rule
> "After every 2 view/browser/search operations, IMMEDIATELY save key findings to text files."
This prevents visual/multimodal information from being lost.
### 3. Read Before Decide
Before major decisions, read the plan file. This keeps goals in your attention window.
### 4. Update After Act
After completing any phase:
- Mark phase status: `in_progress` → `complete`
- Log any errors encountered
- Note files created/modified
### 5. Log ALL Errors
Every error goes in the plan file. This builds knowledge and prevents repetition.
```markdown
## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |
| API timeout | 2 | Added retry logic |
```
### 6. Never Repeat Failures
```
if action_failed:
next_action != same_action
```
Track what you tried. Mutate the approach.
## The 3-Strike Error Protocol
```
ATTEMPT 1: Diagnose & Fix
→ Read error carefully
→ Identify root cause
→ Apply targeted fix
ATTEMPT 2: Alternative Approach
→ Same error? Try different method
→ Different tool? Different library?
→ NEVER repeat exact same failing action
ATTEMPT 3: Broader Rethink
→ Question assumptions
→ Search for solutions
→ Consider updating the plan
AFTER 3 FAILURES: Escalate to User
→ Explain what you tried
→ Share the specific error
→ Ask for guidance
```
## Read vs Write Decision Matrix
| Situation | Action | Reason |
|-----------|--------|--------|
| Just wrote a file | DON'T read | Content still in context |
| Viewed image/PDF | Write findings NOW | Multimodal → text before lost |
| Browser returned data | Write to file | Screenshots don't persist |
| Starting new phase | Read plan/findings | Re-orient if context stale |
| Error occurred | Read relevant file | Need current state to fix |
| Resuming after gap | Read all planning files | Recover state |
## The 5-Question Reboot Test
If you can answer these, your context management is solid:
| Question | Answer Source |
|----------|---------------|
| Where am I? | Current phase in task_plan.md |
| Where am I going? | Remaining phases |
| What's the goal? | Goal statement in plan |
| What have I learned? | findings.md |
| What have I done? | progress.md |
## When to Use This Pattern
**Use for:**
- Multi-step tasks (3+ steps)
- Research tasks
- Building/creating projects
- Tasks spanning many tool calls
- Anything requiring organization
**Skip for:**
- Simple questions
- Single-file edits
- Quick lookups
## Templates
Copy these templates to start:
- [templates/task_plan.md](templates/task_plan.md) — Phase tracking
- [templates/findings.md](templates/findings.md) — Research storage
- [templates/progress.md](templates/progress.md) — Session logging
## Scripts
Helper scripts for automation:
- `scripts/init-session.sh` — Initialize all planning files
- `scripts/check-complete.sh` — Verify all phases complete
- `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
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.
@@ -0,0 +1,35 @@
{
"name": "pi-planning-with-files",
"version": "1.0.1",
"description": "Manus-style file-based planning for Pi Coding Agent",
"keywords": [
"pi-package",
"planning",
"manus",
"agent",
"pi-skill"
],
"pi": {
"skills": [
"SKILL.md"
]
},
"files": [
"README.md",
"SKILL.md",
"examples.md",
"reference.md",
"scripts/",
"templates/"
],
"repository": {
"type": "git",
"url": "git+https://github.com/ttttmr/planning-with-files.git"
},
"author": "",
"license": "MIT",
"bugs": {
"url": "https://github.com/ttttmr/planning-with-files/issues"
},
"homepage": "https://github.com/ttttmr/planning-with-files#readme"
}
+218
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
@@ -0,0 +1,44 @@
# Check if all phases in task_plan.md are complete
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
param(
[string]$PlanFile = "task_plan.md"
)
if (-not (Test-Path $PlanFile)) {
Write-Host "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
}
# Read file content
$content = Get-Content $PlanFile -Raw
# Count total phases
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
# Check for **Status:** format first
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
# Fallback: check for [complete] inline format if **Status:** not found
if ($COMPLETE -eq 0 -and $IN_PROGRESS -eq 0 -and $PENDING -eq 0) {
$COMPLETE = ([regex]::Matches($content, "\[complete\]")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\[in_progress\]")).Count
$PENDING = ([regex]::Matches($content, "\[pending\]")).Count
}
# Report status (always exit 0 — incomplete task is a normal state)
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
} else {
Write-Host "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if ($IN_PROGRESS -gt 0) {
Write-Host "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
}
if ($PENDING -gt 0) {
Write-Host "[planning-with-files] $PENDING phase(s) pending."
}
}
exit 0
@@ -0,0 +1,46 @@
#!/bin/bash
# Check if all phases in task_plan.md are complete
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
echo "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
fi
# Count total phases
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
# Check for **Status:** format first
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)
# Fallback: check for [complete] inline format if **Status:** not found
if [ "$COMPLETE" -eq 0 ] && [ "$IN_PROGRESS" -eq 0 ] && [ "$PENDING" -eq 0 ]; then
COMPLETE=$(grep -c "\[complete\]" "$PLAN_FILE" || true)
IN_PROGRESS=$(grep -c "\[in_progress\]" "$PLAN_FILE" || true)
PENDING=$(grep -c "\[pending\]" "$PLAN_FILE" || true)
fi
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
# Report status (always exit 0 — incomplete task is a normal state)
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
else
echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if [ "$IN_PROGRESS" -gt 0 ]; then
echo "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
fi
if [ "$PENDING" -gt 0 ]; then
echo "[planning-with-files] $PENDING phase(s) pending."
fi
fi
exit 0
@@ -0,0 +1,120 @@
# Initialize planning files for a new session
# Usage: .\init-session.ps1 [project-name]
param(
[string]$ProjectName = "project"
)
$DATE = Get-Date -Format "yyyy-MM-dd"
Write-Host "Initializing planning files for: $ProjectName"
# Create task_plan.md if it doesn't exist
if (-not (Test-Path "task_plan.md")) {
@"
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
Write-Host "Created task_plan.md"
} else {
Write-Host "task_plan.md already exists, skipping"
}
# Create findings.md if it doesn't exist
if (-not (Test-Path "findings.md")) {
@"
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
"@ | Out-File -FilePath "findings.md" -Encoding UTF8
Write-Host "Created findings.md"
} else {
Write-Host "findings.md already exists, skipping"
}
# Create progress.md if it doesn't exist
if (-not (Test-Path "progress.md")) {
@"
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
Write-Host "Created progress.md"
} else {
Write-Host "progress.md already exists, skipping"
}
Write-Host ""
Write-Host "Planning files initialized!"
Write-Host "Files: task_plan.md, findings.md, progress.md"
@@ -0,0 +1,120 @@
#!/bin/bash
# Initialize planning files for a new session
# Usage: ./init-session.sh [project-name]
set -e
PROJECT_NAME="${1:-project}"
DATE=$(date +%Y-%m-%d)
echo "Initializing planning files for: $PROJECT_NAME"
# Create task_plan.md if it doesn't exist
if [ ! -f "task_plan.md" ]; then
cat > task_plan.md << 'EOF'
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
EOF
echo "Created task_plan.md"
else
echo "task_plan.md already exists, skipping"
fi
# Create findings.md if it doesn't exist
if [ ! -f "findings.md" ]; then
cat > findings.md << 'EOF'
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
EOF
echo "Created findings.md"
else
echo "findings.md already exists, skipping"
fi
# Create progress.md if it doesn't exist
if [ ! -f "progress.md" ]; then
cat > progress.md << EOF
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
EOF
echo "Created progress.md"
else
echo "progress.md already exists, skipping"
fi
echo ""
echo "Planning files initialized!"
echo "Files: task_plan.md, findings.md, progress.md"
+208
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()
@@ -0,0 +1,95 @@
# Findings & Decisions
<!--
WHAT: Your knowledge base for the task. Stores everything you discover and decide.
WHY: Context windows are limited. This file is your "external memory" - persistent and unlimited.
WHEN: Update after ANY discovery, especially after 2 view/browser/search operations (2-Action Rule).
-->
## Requirements
<!--
WHAT: What the user asked for, broken down into specific requirements.
WHY: Keeps requirements visible so you don't forget what you're building.
WHEN: Fill this in during Phase 1 (Requirements & Discovery).
EXAMPLE:
- Command-line interface
- Add tasks
- List all tasks
- Delete tasks
- Python implementation
-->
<!-- Captured from user request -->
-
## Research Findings
<!--
WHAT: Key discoveries from web searches, documentation reading, or exploration.
WHY: Multimodal content (images, browser results) doesn't persist. Write it down immediately.
WHEN: After EVERY 2 view/browser/search operations, update this section (2-Action Rule).
EXAMPLE:
- Python's argparse module supports subcommands for clean CLI design
- JSON module handles file persistence easily
- Standard pattern: python script.py <command> [args]
-->
<!-- Key discoveries during exploration -->
-
## Technical Decisions
<!--
WHAT: Architecture and implementation choices you've made, with reasoning.
WHY: You'll forget why you chose a technology or approach. This table preserves that knowledge.
WHEN: Update whenever you make a significant technical choice.
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
| argparse with subcommands | Clean CLI: python todo.py add "task" |
-->
<!-- Decisions made with rationale -->
| Decision | Rationale |
|----------|-----------|
| | |
## Issues Encountered
<!--
WHAT: Problems you ran into and how you solved them.
WHY: Similar to errors in task_plan.md, but focused on broader issues (not just code errors).
WHEN: Document when you encounter blockers or unexpected challenges.
EXAMPLE:
| Empty file causes JSONDecodeError | Added explicit empty file check before json.load() |
-->
<!-- Errors and how they were resolved -->
| Issue | Resolution |
|-------|------------|
| | |
## Resources
<!--
WHAT: URLs, file paths, API references, documentation links you've found useful.
WHY: Easy reference for later. Don't lose important links in context.
WHEN: Add as you discover useful resources.
EXAMPLE:
- Python argparse docs: https://docs.python.org/3/library/argparse.html
- Project structure: src/main.py, src/utils.py
-->
<!-- URLs, file paths, API references -->
-
## Visual/Browser Findings
<!--
WHAT: Information you learned from viewing images, PDFs, or browser results.
WHY: CRITICAL - Visual/multimodal content doesn't persist in context. Must be captured as text.
WHEN: IMMEDIATELY after viewing images or browser results. Don't wait!
EXAMPLE:
- Screenshot shows login form has email and password fields
- Browser shows API returns JSON with "status" and "data" keys
-->
<!-- CRITICAL: Update after every 2 view/browser operations -->
<!-- Multimodal content must be captured as text immediately -->
-
---
<!--
REMINDER: The 2-Action Rule
After every 2 view/browser/search operations, you MUST update this file.
This prevents visual information from being lost when context resets.
-->
*Update this file after every 2 view/browser/search operations*
*This prevents visual information from being lost*
@@ -0,0 +1,114 @@
# Progress Log
<!--
WHAT: Your session log - a chronological record of what you did, when, and what happened.
WHY: Answers "What have I done?" in the 5-Question Reboot Test. Helps you resume after breaks.
WHEN: Update after completing each phase or encountering errors. More detailed than task_plan.md.
-->
## Session: [DATE]
<!--
WHAT: The date of this work session.
WHY: Helps track when work happened, useful for resuming after time gaps.
EXAMPLE: 2026-01-15
-->
### Phase 1: [Title]
<!--
WHAT: Detailed log of actions taken during this phase.
WHY: Provides context for what was done, making it easier to resume or debug.
WHEN: Update as you work through the phase, or at least when you complete it.
-->
- **Status:** in_progress
- **Started:** [timestamp]
<!--
STATUS: Same as task_plan.md (pending, in_progress, complete)
TIMESTAMP: When you started this phase (e.g., "2026-01-15 10:00")
-->
- Actions taken:
<!--
WHAT: List of specific actions you performed.
EXAMPLE:
- Created todo.py with basic structure
- Implemented add functionality
- Fixed FileNotFoundError
-->
-
- Files created/modified:
<!--
WHAT: Which files you created or changed.
WHY: Quick reference for what was touched. Helps with debugging and review.
EXAMPLE:
- todo.py (created)
- todos.json (created by app)
- task_plan.md (updated)
-->
-
### Phase 2: [Title]
<!--
WHAT: Same structure as Phase 1, for the next phase.
WHY: Keep a separate log entry for each phase to track progress clearly.
-->
- **Status:** pending
- Actions taken:
-
- Files created/modified:
-
## Test Results
<!--
WHAT: Table of tests you ran, what you expected, what actually happened.
WHY: Documents verification of functionality. Helps catch regressions.
WHEN: Update as you test features, especially during Phase 4 (Testing & Verification).
EXAMPLE:
| Add task | python todo.py add "Buy milk" | Task added | Task added successfully | ✓ |
| List tasks | python todo.py list | Shows all tasks | Shows all tasks | ✓ |
-->
| Test | Input | Expected | Actual | Status |
|------|-------|----------|--------|--------|
| | | | | |
## Error Log
<!--
WHAT: Detailed log of every error encountered, with timestamps and resolution attempts.
WHY: More detailed than task_plan.md's error table. Helps you learn from mistakes.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| 2026-01-15 10:35 | FileNotFoundError | 1 | Added file existence check |
| 2026-01-15 10:37 | JSONDecodeError | 2 | Added empty file handling |
-->
<!-- Keep ALL errors - they help avoid repetition -->
| Timestamp | Error | Attempt | Resolution |
|-----------|-------|---------|------------|
| | | 1 | |
## 5-Question Reboot Check
<!--
WHAT: Five questions that verify your context is solid. If you can answer these, you're on track.
WHY: This is the "reboot test" - if you can answer all 5, you can resume work effectively.
WHEN: Update periodically, especially when resuming after a break or context reset.
THE 5 QUESTIONS:
1. Where am I? → Current phase in task_plan.md
2. Where am I going? → Remaining phases
3. What's the goal? → Goal statement in task_plan.md
4. What have I learned? → See findings.md
5. What have I done? → See progress.md (this file)
-->
<!-- If you can answer these, context is solid -->
| Question | Answer |
|----------|--------|
| Where am I? | Phase X |
| Where am I going? | Remaining phases |
| What's the goal? | [goal statement] |
| What have I learned? | See findings.md |
| What have I done? | See above |
---
<!--
REMINDER:
- Update after completing each phase or encountering errors
- Be detailed - this is your "what happened" log
- Include timestamps for errors to track when issues occurred
-->
*Update after completing each phase or encountering errors*
@@ -0,0 +1,132 @@
# Task Plan: [Brief Description]
<!--
WHAT: This is your roadmap for the entire task. Think of it as your "working memory on disk."
WHY: After 50+ tool calls, your original goals can get forgotten. This file keeps them fresh.
WHEN: Create this FIRST, before starting any work. Update after each phase completes.
-->
## Goal
<!--
WHAT: One clear sentence describing what you're trying to achieve.
WHY: This is your north star. Re-reading this keeps you focused on the end state.
EXAMPLE: "Create a Python CLI todo app with add, list, and delete functionality."
-->
[One sentence describing the end state]
## Current Phase
<!--
WHAT: Which phase you're currently working on (e.g., "Phase 1", "Phase 3").
WHY: Quick reference for where you are in the task. Update this as you progress.
-->
Phase 1
## Phases
<!--
WHAT: Break your task into 3-7 logical phases. Each phase should be completable.
WHY: Breaking work into phases prevents overwhelm and makes progress visible.
WHEN: Update status after completing each phase: pending → in_progress → complete
-->
### Phase 1: Requirements & Discovery
<!--
WHAT: Understand what needs to be done and gather initial information.
WHY: Starting without understanding leads to wasted effort. This phase prevents that.
-->
- [ ] Understand user intent
- [ ] Identify constraints and requirements
- [ ] Document findings in findings.md
- **Status:** in_progress
<!--
STATUS VALUES:
- pending: Not started yet
- in_progress: Currently working on this
- complete: Finished this phase
-->
### Phase 2: Planning & Structure
<!--
WHAT: Decide how you'll approach the problem and what structure you'll use.
WHY: Good planning prevents rework. Document decisions so you remember why you chose them.
-->
- [ ] Define technical approach
- [ ] Create project structure if needed
- [ ] Document decisions with rationale
- **Status:** pending
### Phase 3: Implementation
<!--
WHAT: Actually build/create/write the solution.
WHY: This is where the work happens. Break into smaller sub-tasks if needed.
-->
- [ ] Execute the plan step by step
- [ ] Write code to files before executing
- [ ] Test incrementally
- **Status:** pending
### Phase 4: Testing & Verification
<!--
WHAT: Verify everything works and meets requirements.
WHY: Catching issues early saves time. Document test results in progress.md.
-->
- [ ] Verify all requirements met
- [ ] Document test results in progress.md
- [ ] Fix any issues found
- **Status:** pending
### Phase 5: Delivery
<!--
WHAT: Final review and handoff to user.
WHY: Ensures nothing is forgotten and deliverables are complete.
-->
- [ ] Review all output files
- [ ] Ensure deliverables are complete
- [ ] Deliver to user
- **Status:** pending
## Key Questions
<!--
WHAT: Important questions you need to answer during the task.
WHY: These guide your research and decision-making. Answer them as you go.
EXAMPLE:
1. Should tasks persist between sessions? (Yes - need file storage)
2. What format for storing tasks? (JSON file)
-->
1. [Question to answer]
2. [Question to answer]
## Decisions Made
<!--
WHAT: Technical and design decisions you've made, with the reasoning behind them.
WHY: You'll forget why you made choices. This table helps you remember and justify decisions.
WHEN: Update whenever you make a significant choice (technology, approach, structure).
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
-->
| Decision | Rationale |
|----------|-----------|
| | |
## Errors Encountered
<!--
WHAT: Every error you encounter, what attempt number it was, and how you resolved it.
WHY: Logging errors prevents repeating the same mistakes. This is critical for learning.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| FileNotFoundError | 1 | Check if file exists, create empty list if not |
| JSONDecodeError | 2 | Handle empty file case explicitly |
-->
| Error | Attempt | Resolution |
|-------|---------|------------|
| | 1 | |
## Notes
<!--
REMINDERS:
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
- Never repeat a failed action - mutate your approach instead
-->
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
+146
View File
@@ -2,6 +2,152 @@
All notable changes to this project will be documented in this file.
## [2.14.0] - 2026-02-04
### Added
- **Pi Agent Support** (PR #67 by @ttttmr)
- Full Pi Agent (pi.dev) integration
- Created `.pi/skills/planning-with-files/` skill bundle
- Added `package.json` for NPM installation (`pi install npm:pi-planning-with-files`)
- Full templates, scripts, and references included
- Cross-platform support (macOS, Linux, Windows)
- Added `docs/pi-agent.md` installation guide
- Added Pi Agent badge to README
- Note: Hooks are Claude Code-specific and not supported in Pi Agent
### Fixed
- **Codex Skill Path References** (PR #66 by @codelyc)
- Replaced broken `CLAUDE_PLUGIN_ROOT` references with correct Codex paths (`~/.codex/skills/planning-with-files/`)
- Added missing template files to `.codex/skills/planning-with-files/templates/`
### Changed
- **OpenClaw Docs Update** (PR #65 by @AZLabsAI, fixes #64)
- Renamed `docs/moltbot.md` to `docs/openclaw.md`
- Updated all paths from `~/.clawdbot/` to `~/.openclaw/`
- Updated CLI commands from `moltbot` to `openclaw`
- Updated website link from `molt.bot` to `openclaw.ai`
- Updated README: Moltbot badge and references updated to OpenClaw
- Version badge updated to v2.14.0
### Thanks
- @ttttmr for Pi Agent integration (PR #67)
- @codelyc for Codex path fix (PR #66)
- @AZLabsAI for OpenClaw docs update (PR #65)
---
## [2.11.0] - 2026-01-26
### Added
- **`/plan` Command for Easier Autocomplete** (Issue #39)
- Added `commands/plan.md` creating `/planning-with-files:plan` command
- Users can now type `/plan` and see the command in autocomplete
- Shorter alternative to `/planning-with-files:start`
- Works immediately after plugin installation - no extra setup required
### Usage
After installing the plugin, you have two command options:
| Command | How to Find | Works Since |
|---------|-------------|-------------|
| `/planning-with-files:plan` | Type `/plan` | v2.11.0 |
| `/planning-with-files:start` | Type `/planning` | v2.6.0 |
### Thanks
- @wqh17101 for persistent reminders in Discussion #36
- @dalisoft, @zoffyzhang, @yyuziyu for feedback and workarounds in Issue #39
- Community for patience while we found the right solution
---
## [2.10.0] - 2026-01-26
### Added
- **Kiro Support** (Issue #55 by @453783374)
- Native Kiro steering files integration
- Created `.kiro/steering/` with planning workflow, rules, and templates
- Added helper scripts in `.kiro/scripts/`
- Added `docs/kiro.md` installation guide
- Added Kiro badge to README
### Note
Kiro uses **Steering Files** (`.kiro/steering/*.md`) instead of the standard `SKILL.md` format. The steering files are automatically loaded by Kiro in every interaction.
---
## [2.9.0] - 2026-01-26
### Added
- **Moltbot Support** (formerly Clawd CLI)
- Added Moltbot integration for workspace and local skills
- Created `.moltbot/skills/planning-with-files/` skill bundle
- Full templates, scripts, and references included
- Cross-platform support (macOS, Linux, Windows)
- Added `docs/moltbot.md` installation guide
- Added Moltbot badge to README
### Changed
- Updated plugin.json description to highlight multi-IDE support
- Added new keywords: moltbot, gemini, cursor, continue, multi-ide, agent-skills
- Now supports 10+ AI coding assistants
---
## [2.8.0] - 2026-01-26
### Added
- **Continue IDE Support** (PR #56 by @murphyXu)
- Added Continue.dev integration for VS Code and JetBrains IDEs
- Created `.continue/skills/planning-with-files/` skill bundle
- Created `.continue/prompts/planning-with-files.prompt` slash command (Chinese)
- Added `docs/continue.md` installation guide
- Added `scripts/check-continue.sh` validator
- Full templates, scripts, and references included
### Fixed
- **POSIX sh Compatibility** (PR #57 by @SaladDay)
- Fixed Stop hook failures on Debian/Ubuntu systems using dash as `/bin/sh`
- Replaced bash-only syntax (`[[`, `&>`) with POSIX-compliant constructs
- Added shell-agnostic Windows detection using `uname -s` and `$OS`
- Applied fix to all 5 IDE-specific SKILL.md files
- Addresses issue reported by @aqlkzf in #32
### Thanks
- @murphyXu for Continue IDE integration (PR #56)
- @SaladDay for POSIX sh compatibility fix (PR #57)
---
## [2.7.1] - 2026-01-22
### Fixed
- **Dynamic Python Command Detection** (Issue #41 by @wqh17101)
- Replaced hardcoded `python3` with dynamic detection: `$(command -v python3 || command -v python)`
- Added Windows PowerShell commands using `python` directly
- Fixed in all 5 IDE-specific SKILL.md files (Claude Code, Codex, Cursor, Kilocode, OpenCode)
- Resolves compatibility issues on Windows/Anaconda where only `python` exists
### Thanks
- @wqh17101 for reporting and suggesting the fix (Issue #41)
---
## [2.7.0] - 2026-01-22
### Added
+22 -2
View File
@@ -39,6 +39,26 @@ These amazing people have contributed code, documentation, or significant improv
- Updated documentation for multi-IDE support
- **Impact:** Windows compatibility and IDE ecosystem expansion
- **[@SaladDay](https://github.com/SaladDay)** - [PR #57](https://github.com/OthmanAdi/planning-with-files/pull/57)
- Fixed Stop hook POSIX sh compatibility for Debian/Ubuntu
- Replaced bashisms (`[[`, `&>`) with POSIX constructs
- Added shell-agnostic Windows detection using `uname -s`
- **Impact:** Fixes hook failures on systems using dash as `/bin/sh`
- **[@murphyXu](https://github.com/murphyXu)** - [PR #56](https://github.com/OthmanAdi/planning-with-files/pull/56)
- Added Continue IDE integration (VS Code / JetBrains)
- Created `.continue/skills/` and `.continue/prompts/` structure
- Added Chinese language slash command prompt
- Created `docs/continue.md` installation guide
- **Impact:** Expands IDE support to Continue.dev ecosystem
- **[@ZWkang](https://github.com/ZWkang)** - [PR #60](https://github.com/OthmanAdi/planning-with-files/pull/60)
- Added CodeBuddy IDE integration (Tencent Cloud AI coding assistant)
- Created `.codebuddy/skills/` folder with full skill structure
- Added templates, scripts, and references for CodeBuddy
- Created `docs/codebuddy.md` installation guide
- **Impact:** Expands IDE support to CodeBuddy ecosystem
### Other Contributors
- **[@tobrun](https://github.com/tobrun)** - [PR #3](https://github.com/OthmanAdi/planning-with-files/pull/3)
@@ -92,6 +112,6 @@ If you've contributed and don't see your name here, please open an issue! We wan
---
**Total Contributors:** 10+ and growing!
**Total Contributors:** 11+ and growing!
*Last updated: January 17, 2026*
*Last updated: January 27, 2026*
+163 -150
View File
@@ -2,12 +2,88 @@
> **Work like Manus** — the AI agent company Meta acquired for **$2 billion**.
## Thank You
<details>
<summary><strong>💬 A Note from the Author</strong></summary>
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.
</details>
<details>
<summary><strong>🌍 See What the Community Built</strong></summary>
| 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 |
| [plan-cascade](https://github.com/Taoidle/plan-cascade) | [@Taoidle](https://github.com/Taoidle) | Multi-level task orchestration, parallel execution, multi-agent collaboration |
| [agentfund-skill](https://github.com/RioTheGreat-ai/agentfund-skill) | [@RioTheGreat-ai](https://github.com/RioTheGreat-ai) | Crowdfunding for AI agents with milestone-based escrow on Base |
*Built something? [Open an issue](https://github.com/OthmanAdi/planning-with-files/issues) to get listed!*
</details>
<details>
<summary><strong>📦 Releases & Session Recovery</strong></summary>
### Current Version: v2.15.0
| Version | Highlights |
|---------|------------|
| **v2.15.0** | `/plan:status` command, OpenCode compatibility fix |
| **v2.14.0** | Pi Agent support, OpenClaw docs update, Codex path fix |
| **v2.11.0** | `/plan` command for easier autocomplete |
| **v2.10.0** | Kiro steering files support |
| **v2.7.0** | Gemini CLI support |
| **v2.2.0** | Session recovery, Windows PowerShell, OS-aware hooks |
[View all releases](https://github.com/OthmanAdi/planning-with-files/releases) · [CHANGELOG](CHANGELOG.md)
---
### Session Recovery
When your context fills up and you run `/clear`, this skill **automatically recovers** your previous session.
**How it works:**
1. Checks for previous session data in `~/.claude/projects/`
2. Finds when planning files were last updated
3. Extracts conversation that happened after (potentially lost context)
4. Shows a catchup report so you can sync
**Pro tip:** Disable auto-compact to maximize context before clearing:
```json
{ "autoCompact": false }
```
</details>
<details>
<summary><strong>🛠️ Supported IDEs (14 Platforms)</strong></summary>
| IDE | Status | Installation Guide | Format |
|-----|--------|-------------------|--------|
| Claude Code | ✅ Full Support | [Installation](docs/installation.md) | Plugin + SKILL.md |
| Gemini CLI | ✅ Full Support | [Gemini Setup](docs/gemini.md) | Agent Skills |
| OpenClaw | ✅ Full Support | [OpenClaw Setup](docs/openclaw.md) | Workspace/Local Skills |
| Kiro | ✅ Full Support | [Kiro Setup](docs/kiro.md) | Steering Files |
| Cursor | ✅ Full Support | [Cursor Setup](docs/cursor.md) | Skills + Hooks |
| Continue | ✅ Full Support | [Continue Setup](docs/continue.md) | Skills + Prompt files |
| Kilocode | ✅ Full Support | [Kilocode Setup](docs/kilocode.md) | Skills |
| OpenCode | ✅ Full Support | [OpenCode Setup](docs/opencode.md) | Personal/Project Skill |
| Codex | ✅ Full Support | [Codex Setup](docs/codex.md) | Personal Skill |
| FactoryAI Droid | ✅ Full Support | [Factory Setup](docs/factory.md) | Workspace/Personal Skill |
| Antigravity | ✅ Full Support | [Antigravity Setup](docs/antigravity.md) | Workspace/Personal Skill |
| CodeBuddy | ✅ Full Support | [CodeBuddy Setup](docs/codebuddy.md) | Workspace/Personal Skill |
| AdaL CLI (Sylph AI) | ✅ Full Support | [AdaL Setup](docs/adal.md) | Personal/Project Skills |
| Pi Agent | ✅ Full Support | [Pi Agent Setup](docs/pi-agent.md) | Agent Skills |
> **Note:** If your IDE uses the legacy Rules system instead of Skills, see the [`legacy-rules-support`](https://github.com/OthmanAdi/planning-with-files/tree/legacy-rules-support) branch.
</details>
---
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.
@@ -18,86 +94,44 @@ A Claude Code plugin that transforms your workflow to use persistent markdown fi
[![Cursor Skills](https://img.shields.io/badge/Cursor-Skills-purple)](https://docs.cursor.com/context/skills)
[![Kilocode Skills](https://img.shields.io/badge/Kilocode-Skills-orange)](https://kilo.ai/docs/agent-behavior/skills)
[![Gemini CLI](https://img.shields.io/badge/Gemini%20CLI-Skills-4285F4)](https://geminicli.com/docs/cli/skills/)
[![Version](https://img.shields.io/badge/version-2.7.0-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)
[![OpenClaw](https://img.shields.io/badge/OpenClaw-Skills-FF6B6B)](https://openclaw.ai)
[![Kiro](https://img.shields.io/badge/Kiro-Steering-00D4AA)](https://kiro.dev/docs/cli/steering/)
[![AdaL CLI](https://img.shields.io/badge/AdaL%20CLI-Skills-9B59B6)](https://docs.sylph.ai/features/plugins-and-skills)
[![Pi Agent](https://img.shields.io/badge/Pi%20Agent-Skills-FF4081)](https://pi.dev)
[![Version](https://img.shields.io/badge/version-2.15.0-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)
[![SkillCheck Validated](https://img.shields.io/badge/SkillCheck-Validated-4c1)](https://getskillcheck.com)
## Quick Install
```bash
# Install the plugin
claude plugins install OthmanAdi/planning-with-files
In Claude Code, run:
```
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files
```
That's it! Now use `/planning-with-files:start` in Claude Code.
That's it! Now use one of these commands in Claude Code:
**Alternative:** If you want `/planning-with-files` (without `:start`), copy skills to your local folder:
| Command | Autocomplete | Description |
|---------|--------------|-------------|
| `/planning-with-files:plan` | Type `/plan` | Start planning session (v2.11.0+) |
| `/planning-with-files:status` | Type `/plan:status` | Show planning progress at a glance (v2.15.0+) |
| `/planning-with-files:start` | Type `/planning` | Original start command |
**Alternative:** If you want `/planning-with-files` (without prefix), copy skills to your local folder:
**macOS/Linux:**
```bash
# Optional: Copy skills for /planning-with-files command
cp -r ~/.claude/plugins/cache/planning-with-files/planning-with-files/*/skills/planning-with-files ~/.claude/skills/
```
**Windows (PowerShell):**
```powershell
# Install the plugin
claude plugins install OthmanAdi/planning-with-files
# Optional: Copy skills for /planning-with-files command
Copy-Item -Recurse -Path "$env:USERPROFILE\.claude\plugins\cache\planning-with-files\planning-with-files\*\skills\planning-with-files" -Destination "$env:USERPROFILE\.claude\skills\"
```
See [docs/installation.md](docs/installation.md) for all installation methods.
## Supported IDEs
| IDE | Status | Installation Guide | Format |
|-----|--------|-------------------|--------|
| Claude Code | ✅ Full Support | [Installation](docs/installation.md) | Plugin + SKILL.md |
| Gemini CLI | ✅ Full Support | [Gemini Setup](docs/gemini.md) | Agent Skills |
| Cursor | ✅ Full Support | [Cursor Setup](docs/cursor.md) | Skills |
| Kilocode | ✅ Full Support | [Kilocode Setup](docs/kilocode.md) | Skills |
| OpenCode | ✅ Full Support | [OpenCode Setup](docs/opencode.md) | Personal/Project Skill |
| Codex | ✅ Full Support | [Codex Setup](docs/codex.md) | Personal Skill |
| FactoryAI Droid | ✅ Full Support | [Factory Setup](docs/factory.md) | Workspace/Personal Skill |
| Antigravity | ✅ Full Support | [Antigravity Setup](docs/antigravity.md) | Workspace/Personal Skill |
> **Note:** If your IDE uses the legacy Rules system instead of Skills, see the [`legacy-rules-support`](https://github.com/OthmanAdi/planning-with-files/tree/legacy-rules-support) branch.
## Documentation
| Document | Description |
|----------|-------------|
| [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 |
| [Gemini CLI Setup](docs/gemini.md) | Google Gemini CLI integration guide |
| [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 |
| [FactoryAI Droid Setup](docs/factory.md) | FactoryAI Droid integration guide |
| [Antigravity Setup](docs/antigravity.md) | Antigravity IDE integration guide |
## Versions
| Version | Features | Install |
|---------|----------|---------|
| **v2.7.0** (current) | Gemini CLI support | `claude plugins install OthmanAdi/planning-with-files` |
| **v2.6.0** | Start command (`/planning-with-files:start`), path resolution fix | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v2.5.0** | Fixed autocomplete - SKILL.md matches Anthropic format | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v2.3.0** | Codex & OpenCode IDE support | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v2.2.2** | Restored skill activation language | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v2.2.1** | Session recovery after /clear, enhanced PreToolUse hook | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v2.2.0** | Kilo Code IDE support, Windows PowerShell support, OS-aware hooks | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v2.1.2** | Fix template cache issue (Issue #18) | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **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**.
@@ -133,60 +167,35 @@ Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
```
## 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 |
## Usage
Once installed, Claude will automatically:
Once installed, the AI agent will:
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)
1. **Ask for your task** if no description is provided
2. **Create `task_plan.md`, `findings.md`, and `progress.md`** in your project directory
3. **Re-read plan** before major decisions (via PreToolUse hook)
4. **Remind you** to update status after file writes (via PostToolUse hook)
5. **Store findings** in `findings.md` instead of stuffing context
6. **Log errors** for future reference
7. **Verify completion** before stopping (via Stop hook)
Or invoke manually with `/planning-with-files:start` (or `/planning-with-files` if you copied skills).
Invoke with:
- `/planning-with-files:plan` - Type `/plan` to find in autocomplete (v2.11.0+)
- `/planning-with-files:start` - Type `/planning` to find in autocomplete
- `/planning-with-files` - Only if you copied skills to `~/.claude/skills/`
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`
@@ -194,11 +203,25 @@ This lets you maximize context usage before manually clearing with `/clear`.
3. **Log ALL Errors** — They help avoid repetition
4. **Never Repeat Failures** — Track attempts, mutate approach
## 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
## File Structure
```
planning-with-files/
├── commands/ # Plugin commands
│ ├── plan.md # /planning-with-files:plan command (v2.11.0+)
│ └── start.md # /planning-with-files:start command
├── templates/ # Root-level templates (for CLAUDE_PLUGIN_ROOT)
├── scripts/ # Root-level scripts (for CLAUDE_PLUGIN_ROOT)
@@ -236,56 +259,46 @@ planning-with-files/
├── .opencode/ # OpenCode IDE skills
│ └── skills/
├── .claude-plugin/ # Plugin manifest
├── .cursor/ # Cursor skills
├── .cursor/ # Cursor skills + hooks
│ ├── hooks.json # Hook configuration
│ ├── hooks/ # Hook scripts (bash + PowerShell)
│ └── skills/
├── .kilocode/ # Kilo Code skills
│ └── skills/
├── .openclaw/ # OpenClaw skills
│ └── skills/
├── .adal/ # AdaL CLI / Sylph AI skills
│ └── skills/
├── .pi/ # Pi Agent skills
│ └── skills/
│ └── planning-with-files/
├── CHANGELOG.md
├── LICENSE
└── README.md
```
## The Manus Principles
## Documentation
| 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!*
| 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 |
| [Gemini CLI Setup](docs/gemini.md) | Google Gemini CLI integration guide |
| [OpenClaw Setup](docs/openclaw.md) | OpenClaw integration guide |
| [Kiro Setup](docs/kiro.md) | Kiro steering files integration |
| [Cursor Setup](docs/cursor.md) | Cursor IDE-specific instructions |
| [Continue Setup](docs/continue.md) | Continue integration guide (skills + slash prompt) |
| [Windows Setup](docs/windows.md) | Windows-specific notes |
| [Kilo Code Support](docs/kilocode.md) | Kilo Code integration guide |
| [Codex Setup](docs/codex.md) | Codex IDE installation and usage |
| [OpenCode Setup](docs/opencode.md) | OpenCode IDE installation, oh-my-opencode config |
| [FactoryAI Droid Setup](docs/factory.md) | FactoryAI Droid integration guide |
| [Antigravity Setup](docs/antigravity.md) | Antigravity IDE integration guide |
| [CodeBuddy Setup](docs/codebuddy.md) | CodeBuddy IDE integration guide |
| [AdaL CLI Setup](docs/adal.md) | AdaL CLI / Sylph AI integration guide |
| [Pi Agent Setup](docs/pi-agent.md) | Pi Agent integration guide |
## Acknowledgments
+12
View File
@@ -0,0 +1,12 @@
---
description: "Start Manus-style file-based planning. Creates task_plan.md, findings.md, progress.md for complex tasks."
---
Invoke the planning-with-files:planning-with-files skill and follow it exactly as presented to you.
Create the three planning files in the current project directory if they don't exist:
- task_plan.md — for phases, progress, and decisions
- findings.md — for research and discoveries
- progress.md — for session logging
Then guide the user through the planning workflow.
+49
View File
@@ -0,0 +1,49 @@
---
description: "Show current planning status at a glance - phases, progress, and any logged errors."
---
Read task_plan.md from the current project directory and display a compact status summary.
## What to Show
1. **Current Phase**: Extract from "## Current Phase" section
2. **Phase Progress**: Count phases and their status (pending/in_progress/complete)
3. **Phase List**: Show each phase with status icon
4. **Errors**: Count entries in "## Errors Encountered" table if present
5. **Files Check**: Confirm which planning files exist
## Status Icons
- `[ ]` or "pending" → ⏸️
- "in_progress" → 🔄
- `[x]` or "complete" → ✅
- "failed" or "blocked" → ❌
## Output Format
```
📋 Planning Status
Current: Phase {N} of {total} ({percent}%)
Status: {status_icon} {status_text}
{icon} Phase 1: {name}
{icon} Phase 2: {name} ← you are here
{icon} Phase 3: {name}
...
Files: task_plan.md {✓|✗} | findings.md {✓|✗} | progress.md {✓|✗}
Errors logged: {count}
```
## If No Planning Files Exist
```
📋 No planning files found
Run /plan to start a new planning session.
```
## Keep It Brief
This is a quick status check, not a full report. Show just enough to answer "where am I?" without re-reading all the files.
+190
View File
@@ -0,0 +1,190 @@
# AdaL CLI / Sylph AI Setup
How to use planning-with-files with AdaL CLI (Sylph AI).
---
## About AdaL
[AdaL](https://docs.sylph.ai/) is a CLI tool from SylphAI that brings AI-powered coding assistance to your terminal. AdaL skills are **compatible with Claude Code skills**, so you can use the same skill format.
---
## Installation
### Option 1: Via Plugin Marketplace (Recommended)
```bash
# Add the marketplace (one-time setup)
/plugin marketplace add OthmanAdi/planning-with-files
# Browse and install via dialog
/plugin
# Or install directly
/plugin install planning-with-files@planning-with-files
```
### Option 2: Copy to personal skills directory
```bash
git clone https://github.com/OthmanAdi/planning-with-files.git
cp -r planning-with-files/.adal/skills/planning-with-files ~/.adal/skills/
```
### Option 3: Copy to project skills directory
```bash
git clone https://github.com/OthmanAdi/planning-with-files.git
cp -r planning-with-files/.adal/skills/planning-with-files .adal/skills/
```
### Option 4: Windows (PowerShell)
```powershell
git clone https://github.com/OthmanAdi/planning-with-files.git
Copy-Item -Recurse -Path "planning-with-files\.adal\skills\planning-with-files" -Destination "$env:USERPROFILE\.adal\skills\"
```
---
## Skill Locations
AdaL supports three skill sources:
| Source | Location | Use Case |
|--------|----------|----------|
| Personal | `~/.adal/skills/` | Your custom skills (highest priority) |
| Project | `.adal/skills/` | Team skills shared via git |
| Plugin | `~/.adal/plugin-cache/` | External skills from GitHub (lowest priority) |
---
## Using /skills Command
In AdaL, view all active skills with:
```
/skills
```
This shows skills from all sources (personal, project, plugins):
```
> Skills (Page 1/1)
Personal (~/.adal/skills/):
planning-with-files
Project (.adal/skills/):
(none)
Plugins:
(none)
```
---
## Using /plugin Commands
Manage external skills from GitHub:
| Command | Description |
|---------|-------------|
| `/plugin marketplace add <owner/repo>` | Add a marketplace (one-time setup) |
| `/plugin` | Browse available plugins and marketplaces |
| `/plugin install <plugin>@<marketplace>` | Install a plugin |
| `/plugin uninstall <plugin>@<marketplace>` | Uninstall a plugin |
| `/plugin marketplace remove <name>` | Remove a marketplace |
---
## File Structure
```
your-project/
├── .adal/
│ └── skills/
│ └── planning-with-files/
│ ├── SKILL.md
│ ├── templates/
│ │ ├── task_plan.md
│ │ ├── findings.md
│ │ └── progress.md
│ ├── scripts/
│ │ ├── init-session.sh
│ │ ├── init-session.ps1
│ │ ├── check-complete.sh
│ │ ├── check-complete.ps1
│ │ └── session-catchup.py
│ └── references/
│ ├── examples.md
│ └── reference.md
├── task_plan.md ← Your planning files go here
├── findings.md
├── progress.md
└── ...
```
---
## Templates
The templates in `.adal/skills/planning-with-files/templates/` work in AdaL:
- `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.
---
## Scripts
Helper scripts for manual execution (AdaL executes scripts via bash):
```bash
# Initialize planning files
bash ~/.adal/skills/planning-with-files/scripts/init-session.sh
# Check task completion
bash ~/.adal/skills/planning-with-files/scripts/check-complete.sh
# Session recovery
python ~/.adal/skills/planning-with-files/scripts/session-catchup.py $(pwd)
```
Windows PowerShell:
```powershell
# Initialize planning files
powershell -File "$env:USERPROFILE\.adal\skills\planning-with-files\scripts\init-session.ps1"
# Check task completion
powershell -File "$env:USERPROFILE\.adal\skills\planning-with-files\scripts\check-complete.ps1"
```
---
## Tips for AdaL Users
1. **Use /skills command:** Verify planning-with-files is active after installation.
2. **Use explicit prompts:** Be explicit when starting complex tasks:
```
This is a complex task. Let's use the planning-with-files pattern.
Start by creating task_plan.md with the goal and phases.
```
3. **Pin planning files:** Keep task_plan.md open for easy reference.
4. **Re-read plan before decisions:** Periodically ask AdaL to read task_plan.md to refresh goals.
5. **Check status regularly:** Verify all phases are complete before finishing.
---
## Need Help?
- AdaL Documentation: [docs.sylph.ai](https://docs.sylph.ai/)
- Open an issue at [github.com/OthmanAdi/planning-with-files/issues](https://github.com/OthmanAdi/planning-with-files/issues)
+265
View File
@@ -0,0 +1,265 @@
# CodeBuddy IDE Setup
Using planning-with-files with [CodeBuddy](https://codebuddy.ai/).
---
## Installation
CodeBuddy auto-discovers skills from `.codebuddy/skills/` directories. Two installation methods:
### Method 1: Workspace Installation (Recommended)
Share the skill with your entire team by adding it to your repository:
```bash
# In your project repository
git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files
# Copy the CodeBuddy skill to your repo
cp -r /tmp/planning-with-files/.codebuddy .
# Commit to share with team
git add .codebuddy/
git commit -m "Add planning-with-files skill for CodeBuddy"
git push
# Clean up
rm -rf /tmp/planning-with-files
```
Now everyone on your team using CodeBuddy will have access to the skill!
### Method 2: Personal Installation
Install just for yourself:
```bash
# Clone the repo
git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files
# Copy to your personal CodeBuddy skills folder
mkdir -p ~/.codebuddy/skills
cp -r /tmp/planning-with-files/.codebuddy/skills/planning-with-files ~/.codebuddy/skills/
# Clean up
rm -rf /tmp/planning-with-files
```
### Verification
Restart your CodeBuddy session, then the skill will auto-activate when you work on complex tasks.
No slash command needed - CodeBuddy automatically invokes skills based on your task description!
---
## How It Works
### Auto-Activation
CodeBuddy scans your task and automatically activates the skill when you:
- Mention "complex task" or "multi-step project"
- Request planning or organization
- Start research tasks
- Work on projects requiring >5 steps
### Trigger Phrases
Increase auto-activation likelihood by using these phrases:
- "Create a task plan for..."
- "This is a multi-step project..."
- "I need planning for..."
- "Help me organize this complex task..."
### Example Request
```
I need to build a REST API with authentication,
database integration, and comprehensive testing.
This is a complex multi-step project that will
require careful planning.
```
CodeBuddy will automatically invoke `planning-with-files` and create the three planning files.
---
## The Three Files
Once activated, the skill creates:
| File | Purpose | Location |
|------|---------|----------|
| `task_plan.md` | Phases, progress, decisions | Your project root |
| `findings.md` | Research, discoveries | Your project root |
| `progress.md` | Session log, test results | Your project root |
### Templates
The skill includes starter templates in `.codebuddy/skills/planning-with-files/references/`:
- `task_plan.md` — Phase tracking template
- `findings.md` — Research storage template
- `progress.md` — Session logging template
---
## Usage Pattern
### 1. Start Complex Task
Describe your task with complexity indicators:
```
I'm building a user authentication system.
This is a multi-phase project requiring database
setup, API endpoints, testing, and documentation.
```
### 2. Skill Auto-Activates
CodeBuddy invokes `planning-with-files` and creates the planning files.
### 3. Work Through Phases
The AI will:
- ✅ Create `task_plan.md` with phases
- ✅ Update progress as work completes
- ✅ Store research in `findings.md`
- ✅ Log actions in `progress.md`
- ✅ Re-read plans before major decisions
### 4. Track Everything
All important information gets written to disk, not lost in context window.
---
## Skill Features
### The 3-Strike Error Protocol
When errors occur, the AI:
1. **Attempt 1:** Diagnose and fix
2. **Attempt 2:** Try alternative approach
3. **Attempt 3:** Broader rethink
4. **After 3 failures:** Escalate to you
### The 2-Action Rule
After every 2 search/view operations, findings are saved to `findings.md`.
Prevents losing visual/multimodal information.
### Read Before Decide
Before major decisions, the AI re-reads planning files to refresh goals.
Prevents goal drift in long sessions.
---
## Team Workflow
### Workspace Skills (Recommended)
With workspace installation (`.codebuddy/skills/`):
- ✅ Everyone on team has the skill
- ✅ Consistent planning across projects
- ✅ Version controlled with your repo
- ✅ Changes sync via git
### Personal Skills
With personal installation (`~/.codebuddy/skills/`):
- ✅ Use across all your projects
- ✅ Keep it even if you switch teams
- ❌ Not shared with teammates
---
## Why This Works
This pattern is why Manus AI (acquired by Meta for $2 billion) succeeded:
> "Markdown is my 'working memory' on disk. Since I process information iteratively and my active context has limits, Markdown files serve as scratch pads for notes, checkpoints for progress, building blocks for final deliverables."
> — Manus AI
**Key insight:** Context window = RAM (volatile). Filesystem = Disk (persistent).
Write important information to disk, not context.
---
## Troubleshooting
### Skill Not Activating?
1. **Add trigger phrases:** Use "complex task", "multi-step", "planning" in your request
2. **Be explicit:** Mention number of phases or complexity
3. **Restart CodeBuddy:** Agent rescans skills on restart
### Files Not Created?
Check:
- Current directory is writable
- No file permission issues
- Agent has file system access
### Need Templates?
Templates are in:
- **Workspace:** `.codebuddy/skills/planning-with-files/references/`
- **Personal:** `~/.codebuddy/skills/planning-with-files/references/`
Copy them to your project root and customize.
---
## Advanced: Customization
### Modify the Skill
Edit `.codebuddy/skills/planning-with-files/SKILL.md` to customize:
- Change trigger phrases in description
- Adjust planning patterns
- Add team-specific rules
### Add Custom Templates
Place custom templates in:
```
.codebuddy/skills/planning-with-files/references/
```
CodeBuddy will reference them automatically.
---
## Agent Skills Standard
This skill follows the [Agent Skills Specification](https://agentskills.io/specification), an open standard for AI coding assistants.
The same skill format works across:
- CodeBuddy
- Claude Code
- Cursor
- And other Agent Skills-compatible IDEs
---
## Support
- **GitHub Issues:** https://github.com/OthmanAdi/planning-with-files/issues
- **CodeBuddy Docs:** https://www.codebuddy.ai/docs/ide/Features/Skills
- **Agent Skills Spec:** https://agentskills.io/specification
- **Author:** [@OthmanAdi](https://github.com/OthmanAdi)
---
## See Also
- [Quick Start Guide](quickstart.md)
- [Workflow Diagram](workflow.md)
- [Manus Principles](../skills/planning-with-files/reference.md)
- [Real Examples](../skills/planning-with-files/examples.md)
+36 -6
View File
@@ -6,14 +6,44 @@ 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.
Codex auto-discovers skills from `.codex/skills/` directories. Two installation methods:
### Quick Install
### Method 1: Workspace Installation (Recommended)
Share the skill with your entire team by adding it to your repository:
```bash
# In your project repository
git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files
# Copy the Codex skill to your repo
cp -r /tmp/planning-with-files/.codex .
# Commit to share with team
git add .codex/
git commit -m "Add planning-with-files skill for Codex"
git push
# Clean up
rm -rf /tmp/planning-with-files
```
Now everyone on your team using Codex will have access to the skill!
### Method 2: Personal Installation
Install just for yourself:
```bash
# Clone the repo
git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files
# Copy to your personal Codex skills folder
mkdir -p ~/.codex/skills
cd ~/.codex/skills
git clone https://github.com/OthmanAdi/planning-with-files.git
cp -r /tmp/planning-with-files/.codex/skills/planning-with-files ~/.codex/skills/
# Clean up
rm -rf /tmp/planning-with-files
```
## Usage with Superpowers
@@ -33,7 +63,7 @@ Add to your `~/.codex/AGENTS.md`:
<IMPORTANT>
For complex tasks (3+ steps, research, projects):
1. Read skill: `cat ~/.codex/skills/planning-with-files/planning-with-files/SKILL.md`
1. Read skill: `cat ~/.codex/skills/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>
@@ -42,7 +72,7 @@ For complex tasks (3+ steps, research, projects):
## Verification
```bash
ls -la ~/.codex/skills/planning-with-files/planning-with-files/SKILL.md
ls -la ~/.codex/skills/planning-with-files/SKILL.md
```
## Learn More
+74
View File
@@ -0,0 +1,74 @@
# Continue Setup
How to use planning-with-files with Continue (VS Code / JetBrains).
---
## What This Integration Adds
- Project-level skill: `.continue/skills/planning-with-files/`
- Project-level slash command prompt: `.continue/prompts/planning-with-files.prompt` (Markdown)
Continue supports both **project-level** (`<repo>/.continue/...`) and **global** (`~/.continue/...`) locations.
---
## Installation (Project-level, recommended)
In your project root:
```bash
git clone https://github.com/OthmanAdi/planning-with-files.git
cp -r planning-with-files/.continue .continue
```
Restart Continue (or reload the IDE) so it picks up the new files.
---
## Installation (Global)
Copy the skill and prompt into your global Continue directory:
```bash
git clone https://github.com/OthmanAdi/planning-with-files.git
mkdir -p ~/.continue/skills ~/.continue/prompts
cp -r planning-with-files/.continue/skills/planning-with-files ~/.continue/skills/
cp planning-with-files/.continue/prompts/planning-with-files.prompt ~/.continue/prompts/
```
Restart Continue (or reload the IDE) so it picks up the new files.
---
## Usage
1. In Continue chat, run:
- `/planning-with-files`
2. The prompt will guide you to:
- Ensure `task_plan.md`, `findings.md`, `progress.md` exist in your repo root
- Update these files throughout the task
---
## Helper Scripts (Optional)
From your project root:
```bash
# Create task_plan.md / findings.md / progress.md (if missing)
bash .continue/skills/planning-with-files/scripts/init-session.sh
# Verify all phases marked complete (expects task_plan.md format)
bash .continue/skills/planning-with-files/scripts/check-complete.sh
# Recover unsynced context from last Claude Code session (if you also use Claude Code)
python3 .continue/skills/planning-with-files/scripts/session-catchup.py "$(pwd)"
```
---
## Notes & Limitations
- Continue does not run Claude Code hooks (PreToolUse/PostToolUse/Stop). The workflow is manual: re-read `task_plan.md` before decisions and update it after each phase.
- The three planning files are tool-agnostic and can be used across Claude Code, Cursor, Gemini CLI, and Continue.
+105 -76
View File
@@ -1,113 +1,148 @@
# Cursor IDE Setup
How to use planning-with-files with Cursor IDE.
How to use planning-with-files with Cursor IDE — now with full hook support.
---
## Installation
### Option 1: Copy rules directory
### Option 1: Copy .cursor directory (Recommended)
```bash
git clone https://github.com/OthmanAdi/planning-with-files.git
cp -r planning-with-files/.cursor .cursor
```
This copies the skill files, hooks config, and hook scripts to your project.
### Option 2: Manual setup
Create `.cursor/rules/planning-with-files.mdc` in your project with the content from this repo.
1. Copy `.cursor/skills/planning-with-files/` to your project
2. Copy `.cursor/hooks.json` to your project
3. Copy `.cursor/hooks/` directory to your project
---
## Important Limitations
## Hooks Support
> **Note:** Hooks (PreToolUse, PostToolUse, Stop, SessionStart) are **Claude Code specific** and will NOT work in Cursor.
Cursor now supports hooks natively via `.cursor/hooks.json`. This skill includes three hooks that mirror the Claude Code experience:
### What works in Cursor:
| Hook | Purpose | Cursor Feature |
|------|---------|----------------|
| `preToolUse` | Re-reads task_plan.md before tool operations | Keeps goals in context |
| `postToolUse` | Reminds to update plan after file edits | Prevents forgetting updates |
| `stop` | Checks if all phases are complete | **Auto-continues** if incomplete |
- 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
### How the Stop Hook Works
### What doesn't work in Cursor:
The stop hook is the most powerful feature. When the agent tries to stop:
- SessionStart hook (no startup notification)
- PreToolUse hook (no automatic plan re-reading)
- PostToolUse hook (no automatic reminders)
- Stop hook (no automatic completion verification)
1. It checks `task_plan.md` for phase completion status
2. If all phases are complete → allows the agent to stop
3. If phases are incomplete → sends a `followup_message` that auto-prompts the agent to keep working
---
This means the agent **cannot stop until all phases are done** (up to `loop_limit` of 3 retries).
## 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
### Hook Files
```
your-project/
├── .cursor/
│ └── rules/
│ └── planning-with-files.mdc
├── task_plan.md
│ ├── hooks.json ← Hook configuration
│ ├── hooks/
│ │ ├── pre-tool-use.sh ← Pre-tool-use script
│ │ ├── post-tool-use.sh ← Post-tool-use script
│ │ ├── stop.sh ← Completion check script
│ │ ├── pre-tool-use.ps1 ← PowerShell versions
│ │ ├── post-tool-use.ps1
│ │ └── stop.ps1
│ └── skills/
│ └── planning-with-files/
│ ├── SKILL.md
│ ├── examples.md
│ ├── reference.md
│ └── templates/
├── task_plan.md ← Your planning files (created per task)
├── findings.md
├── progress.md
└── ...
```
### Activating rules
---
Cursor automatically loads rules from `.cursor/rules/` when you open a project.
## Windows Setup
The default `hooks.json` uses bash scripts (works on macOS, Linux, and Windows with Git Bash).
**If you need native PowerShell**, rename the config files:
```powershell
# Back up the default config
Rename-Item .cursor\hooks.json hooks.unix.json
# Use the PowerShell config
Rename-Item .cursor\hooks.windows.json hooks.json
```
The `.cursor/hooks.windows.json` file uses PowerShell to execute the `.ps1` hook scripts directly.
---
## What Each Hook Does
### PreToolUse Hook
**Triggers:** Before Write, Edit, Shell, or Read operations
**What it does:** Reads the first 30 lines of `task_plan.md` and logs them to stderr for context. Always returns `{"decision": "allow"}` — it never blocks tools.
**Claude Code equivalent:** `cat task_plan.md 2>/dev/null | head -30 || true`
### PostToolUse Hook
**Triggers:** After Write or Edit operations
**What it does:** Outputs a reminder to update `task_plan.md` if a phase was completed.
**Claude Code equivalent:** `echo '[planning-with-files] File updated...'`
### Stop Hook
**Triggers:** When the agent tries to stop working
**What it does:**
1. Counts total phases (`### Phase` headers) in `task_plan.md`
2. Counts completed phases (supports both `**Status:** complete` and `[complete]` formats)
3. If incomplete, returns `followup_message` to auto-continue
4. Capped at 3 retries via `loop_limit` to prevent infinite loops
**Claude Code equivalent:** `scripts/check-complete.sh` — but Cursor's version is **more powerful** because it can auto-continue the agent instead of just reporting status.
---
## Skill Files
The `.cursor/skills/planning-with-files/SKILL.md` file contains all the planning guidelines:
- Core 3-file planning pattern
- Templates (task_plan.md, findings.md, progress.md)
- The 2-Action Rule
- The 3-Strike Error Protocol
- Read vs Write Decision Matrix
Cursor automatically loads skills from `.cursor/skills/` when you open a project.
---
## Templates
The templates in `skills/planning-with-files/templates/` work in Cursor:
The templates in `.cursor/skills/planning-with-files/templates/` are used when starting a new task:
- `task_plan.md` - Phase tracking template
- `findings.md` - Research storage template
- `progress.md` - Session logging template
Copy them to your project root when starting a new task.
The agent copies these to your project root when starting a new planning session.
---
@@ -115,27 +150,21 @@ Copy them to your project root when starting a new task.
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.
2. **Trust the hooks:** The stop hook will prevent premature completion — you don't need to manually verify phase status.
3. **Use explicit prompts:** Since there's no auto-detection, be explicit:
3. **Use explicit prompts for complex tasks:**
```
This is a complex task. Let's use the planning-with-files pattern.
Start by creating task_plan.md with the goal and phases.
```
4. **Check status regularly:** Without the Stop hook, manually verify completion before finishing.
4. **Check hook logs:** If hooks aren't working, check Cursor's output panel for hook execution logs.
---
## Migrating from Cursor to Claude Code
## Compatibility with 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.
Your planning files (task_plan.md, findings.md, progress.md) are fully compatible between Cursor and Claude Code. You can switch between them without any changes to your planning files.
---
+7 -57
View File
@@ -5,7 +5,7 @@ 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
2. Skills load automatically from global (`~/.kilocode/skills/`) or project (`.kilocode/skills/`) directories
3. Start a complex task — Kilo Code will automatically create planning files
## Installation
@@ -21,11 +21,7 @@ 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
cp -r planning-with-files/.kilocode/skills/planning-with-files .kilocode/skills/planning-with-files
```
**Windows (PowerShell):**
@@ -35,15 +31,7 @@ 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
Copy-Item -Recurse -Force planning-with-files\.kilocode\skills\planning-with-files .kilocode\skills\planning-with-files
```
### Manual Installation (Project-Level)
@@ -54,26 +42,14 @@ Copy the skill directory to your project:
```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
cp -r planning-with-files/.kilocode/skills/planning-with-files .kilocode/skills/planning-with-files
```
**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
Copy-Item -Recurse -Force planning-with-files\.kilocode\skills\planning-with-files .kilocode\skills\planning-with-files
```
### Global Installation (User-Level)
@@ -84,26 +60,14 @@ To make the skill available across all projects:
```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
cp -r planning-with-files/.kilocode/skills/planning-with-files ~/.kilocode/skills/planning-with-files
```
**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
Copy-Item -Recurse -Force planning-with-files\.kilocode\skills\planning-with-files C:\Users\YourUsername\.kilocode\skills\planning-with-files
```
### Verifying Installation
@@ -113,7 +77,6 @@ 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):**
@@ -131,10 +94,6 @@ The scripts should create `task_plan.md`, `findings.md`, and `progress.md` files
### File Structure
The installation consists of the skill directory and the rules file:
**Skill Directory:**
```
~/.kilocode/skills/planning-with-files/ (Global)
OR
@@ -153,21 +112,12 @@ OR
└── 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` |
+114
View File
@@ -0,0 +1,114 @@
# Kiro Setup
How to use planning-with-files with [Kiro](https://kiro.dev).
---
## Important: Kiro Uses Steering Files
Kiro doesn't use the standard `SKILL.md` format. Instead, it uses **Steering Files** — markdown documents in `.kiro/steering/` that provide persistent project knowledge.
See: [Kiro Steering Docs](https://kiro.dev/docs/cli/steering/)
---
## What This Integration Adds
```
.kiro/
├── steering/
│ ├── planning-workflow.md # Core workflow and quick start
│ ├── planning-rules.md # Critical rules and error protocols
│ └── planning-templates.md # Templates for task_plan, findings, progress
└── scripts/
├── init-session.sh # Initialize planning files (Bash)
├── init-session.ps1 # Initialize planning files (PowerShell)
├── check-complete.sh # Verify phases complete (Bash)
└── check-complete.ps1 # Verify phases complete (PowerShell)
```
---
## Installation (Workspace)
Copy to your project:
```bash
git clone https://github.com/OthmanAdi/planning-with-files.git
cp -r planning-with-files/.kiro .kiro
rm -rf planning-with-files
```
---
## Installation (Global)
Copy to your global Kiro config:
```bash
git clone https://github.com/OthmanAdi/planning-with-files.git
mkdir -p ~/.kiro/steering ~/.kiro/scripts
cp planning-with-files/.kiro/steering/* ~/.kiro/steering/
cp planning-with-files/.kiro/scripts/* ~/.kiro/scripts/
rm -rf planning-with-files
```
Global steering applies to all your projects.
---
## Usage
1. Start Kiro in your project
2. For complex tasks, create the planning files:
```bash
# Using the init script
bash .kiro/scripts/init-session.sh
# Or manually create:
# - task_plan.md
# - findings.md
# - progress.md
```
3. The steering files automatically guide Kiro to:
- Create plans before complex tasks
- Update findings after research
- Log progress and errors
- Follow the 3-strike error protocol
---
## How Steering Works
Kiro loads steering files automatically in every interaction. The planning guidance becomes part of Kiro's project understanding without you needing to explain it each time.
| File | Purpose |
|------|---------|
| `planning-workflow.md` | Core pattern and quick start |
| `planning-rules.md` | Critical rules and error handling |
| `planning-templates.md` | Copy-paste templates |
---
## Helper Scripts
```bash
# Initialize all planning files
bash .kiro/scripts/init-session.sh
# Windows PowerShell
powershell -ExecutionPolicy Bypass -File .kiro/scripts/init-session.ps1
# Verify all phases complete
bash .kiro/scripts/check-complete.sh
```
---
## Notes
- Steering files are loaded automatically — no manual invocation needed
- Workspace steering (`.kiro/`) takes priority over global (`~/.kiro/`)
- Planning files (`task_plan.md`, etc.) go in your project root, not in `.kiro/`

Some files were not shown because too many files have changed in this diff Show More