Compare commits

...
7 Commits
Author SHA1 Message Date
OthmanAdi 50a8f45fca fix: clarify working directory for planning files (v2.0.1)
- Add 'Important: Where Files Go' section to SKILL.md
- Update Quick Start with explicit 'in your project' instructions
- Add troubleshooting section to README
- Bump version to 2.0.1

Fixes #11
2026-01-09 13:27:56 +01:00
OthmanAdi 7251f923e4 Add one-line installer to README 2026-01-09 01:18:07 +01:00
OthmanAdi 0a753038b2 Fix: Add missing task_plan.md template (was in gitignore) 2026-01-09 01:17:06 +01:00
OthmanAdi ef493399f0 Add Cursor support for v2.0.0 2026-01-08 22:17:21 +01:00
OthmanAdi 269116c2af docs: add version table to README 2026-01-08 22:03:58 +01:00
OthmanAdi 006ea9a6c1 fix: check-complete.sh grep pattern for status detection 2026-01-08 21:38:32 +01:00
OthmanAdi 9f34d9ca11 v2.0.0: Hooks integration, templates, and enhanced documentation
NEW FEATURES:
- Hooks: PreToolUse (auto plan re-read), Stop (completion verification)
- Templates: task_plan.md, findings.md, progress.md
- Scripts: init-session.sh, check-complete.sh
- CHANGELOG.md and MIGRATION.md

ENHANCED SKILL.MD (<500 lines):
- The 2-Action Rule
- The 3-Strike Error Protocol
- Read vs Write Decision Matrix
- The 5-Question Reboot Test

ENHANCED REFERENCE.MD:
- 3 Context Engineering Strategies
- 7-Step Agent Loop diagram
- Updated Manus statistics

README reorganized (Thank You at top, Star History at bottom)

v1.0.0 preserved in 'legacy' branch for existing users.
2026-01-08 20:57:52 +01:00
14 changed files with 1135 additions and 238 deletions
+2 -2
View File
@@ -8,8 +8,8 @@
{
"name": "planning-with-files",
"source": "./",
"description": "Manus-style persistent markdown files for planning, progress tracking, and knowledge storage",
"version": "1.0.0"
"description": "Manus-style persistent markdown files for planning, progress tracking, and knowledge storage. Now with hooks integration.",
"version": "2.0.0"
}
]
}
+5 -3
View File
@@ -1,7 +1,7 @@
{
"name": "planning-with-files",
"version": "1.0.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.0.0",
"description": "Manus-style persistent markdown files for planning, progress tracking, and knowledge storage. Includes hooks for automatic plan re-reading and completion verification. Use when starting complex tasks, multi-step projects, research tasks, or when you want structured output.",
"author": {
"name": "OthmanAdi",
"url": "https://github.com/OthmanAdi"
@@ -14,6 +14,8 @@
"workflow",
"markdown",
"context-engineering",
"task-management"
"task-management",
"hooks",
"templates"
]
}
+159
View File
@@ -0,0 +1,159 @@
---
description: Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use for multi-step tasks, research, or anything requiring >5 tool calls.
globs:
alwaysApply: false
---
# Planning with Files
Work like Manus: Use persistent markdown files as your "working memory on disk."
## Quick Start
Before ANY complex task:
1. **Create `task_plan.md`** — Phase tracking and progress
2. **Create `findings.md`** — Research and discoveries
3. **Create `progress.md`** — Session log and test results
4. **Re-read plan before decisions** — Refreshes goals in attention window
5. **Update after each phase** — Mark complete, log errors
## The Core Pattern
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
```
## File Purposes
| File | Purpose | When to Update |
|------|---------|----------------|
| `task_plan.md` | Phases, progress, decisions | After each phase |
| `findings.md` | Research, discoveries | After ANY discovery |
| `progress.md` | Session log, test results | Throughout session |
## Critical Rules
### 1. Create Plan First
Never start a complex task without `task_plan.md`. Non-negotiable.
### 2. The 2-Action Rule
> "After every 2 view/browser/search operations, IMMEDIATELY save key findings to text files."
This prevents visual/multimodal information from being lost.
### 3. Read Before Decide
Before major decisions, read the plan file. This keeps goals in your attention window.
### 4. Update After Act
After completing any phase:
- Mark phase status: `in_progress` → `complete`
- Log any errors encountered
- Note files created/modified
### 5. Log ALL Errors
Every error goes in the plan file. This builds knowledge and prevents repetition.
```markdown
## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |
| API timeout | 2 | Added retry logic |
```
### 6. Never Repeat Failures
```
if action_failed:
next_action != same_action
```
Track what you tried. Mutate the approach.
## The 3-Strike Error Protocol
```
ATTEMPT 1: Diagnose & Fix
→ Read error carefully
→ Identify root cause
→ Apply targeted fix
ATTEMPT 2: Alternative Approach
→ Same error? Try different method
→ Different tool? Different library?
→ NEVER repeat exact same failing action
ATTEMPT 3: Broader Rethink
→ Question assumptions
→ Search for solutions
→ Consider updating the plan
AFTER 3 FAILURES: Escalate to User
→ Explain what you tried
→ Share the specific error
→ Ask for guidance
```
## Read vs Write Decision Matrix
| Situation | Action | Reason |
|-----------|--------|--------|
| Just wrote a file | DON'T read | Content still in context |
| Viewed image/PDF | Write findings NOW | Multimodal → text before lost |
| Browser returned data | Write to file | Screenshots don't persist |
| Starting new phase | Read plan/findings | Re-orient if context stale |
| Error occurred | Read relevant file | Need current state to fix |
| Resuming after gap | Read all planning files | Recover state |
## The 5-Question Reboot Test
If you can answer these, your context management is solid:
| Question | Answer Source |
|----------|---------------|
| Where am I? | Current phase in task_plan.md |
| Where am I going? | Remaining phases |
| What's the goal? | Goal statement in plan |
| What have I learned? | findings.md |
| What have I done? | progress.md |
## Manus Principles
### Principle 1: Filesystem as External Memory
Store large content in files, keep only paths in context. Agent can "look up" information when needed.
### Principle 2: Attention Manipulation
After ~50 tool calls, models forget original goals ("lost in the middle" effect). Re-reading `task_plan.md` brings goals back into the attention window.
### Principle 3: Keep Failure Traces
Keep failed actions in the plan file. The model updates its understanding when seeing failures. Error recovery is "one of the clearest signals of TRUE agentic behavior."
### Principle 4: Avoid Few-Shot Overfitting
Vary phrasings slightly. Don't copy-paste patterns blindly. Uniformity breeds fragility.
## When to Use This Pattern
**Use for:**
- Multi-step tasks (3+ steps)
- Research tasks
- Building/creating projects
- Tasks spanning many tool calls
- Anything requiring organization
**Skip for:**
- Simple questions
- Single-file edits
- Quick lookups
## Anti-Patterns
| Don't | Do Instead |
|-------|------------|
| Use TodoWrite for persistence | Create task_plan.md file |
| State goals once and forget | Re-read plan before decisions |
| Hide errors and retry silently | Log errors to plan file |
| Stuff everything in context | Store large content in files |
| Start executing immediately | Create plan file FIRST |
| Repeat failed actions | Track attempts, mutate approach |
+2 -1
View File
@@ -14,9 +14,10 @@ task_plan.md
research_notes.md
notes.md
# But keep example task files
# But keep example and template files
!examples/*.md
!examples/**/*.md
!**/templates/*.md
# Keep the skill folder clean
*.log
+71
View File
@@ -0,0 +1,71 @@
# Changelog
All notable changes to this project will be documented in this file.
## [2.0.0] - 2026-01-08
### Added
- **Hooks Integration** (Claude Code 2.1.0+)
- `PreToolUse` hook: Automatically reads `task_plan.md` before Write/Edit/Bash operations
- `Stop` hook: Verifies all phases are complete before stopping
- Implements Manus "attention manipulation" principle automatically
- **Templates Directory**
- `templates/task_plan.md` - Structured phase tracking template
- `templates/findings.md` - Research and discovery storage template
- `templates/progress.md` - Session logging with test results template
- **Scripts Directory**
- `scripts/init-session.sh` - Initialize all planning files at once
- `scripts/check-complete.sh` - Verify all phases are complete
- **New Documentation**
- `CHANGELOG.md` - This file
- `MIGRATION.md` - Guide for upgrading from v1.x
- **Enhanced SKILL.md**
- The 2-Action Rule (save findings after every 2 view/browser operations)
- The 3-Strike Error Protocol (structured error recovery)
- Read vs Write Decision Matrix
- The 5-Question Reboot Test
- **Expanded reference.md**
- The 3 Context Engineering Strategies (Reduction, Isolation, Offloading)
- The 7-Step Agent Loop diagram
- Critical constraints section
- Updated Manus statistics
### Changed
- SKILL.md restructured for progressive disclosure (<500 lines)
- Version bumped to 2.0.0 in all manifests
- README.md reorganized (Thank You section moved to top)
- Description updated to mention >5 tool calls threshold
### Preserved
- All v1.0.0 content available in `legacy` branch
- Original examples.md retained (proven patterns)
- Core 3-file pattern unchanged
- MIT License unchanged
## [1.0.0] - 2026-01-07
### Added
- Initial release
- SKILL.md with core workflow
- reference.md with 6 Manus principles
- examples.md with 4 real-world examples
- Plugin structure for Claude Code marketplace
- README.md with installation instructions
---
## Versioning
This project follows [Semantic Versioning](https://semver.org/):
- MAJOR: Breaking changes to skill behavior
- MINOR: New features, backward compatible
- PATCH: Bug fixes, documentation updates
+128
View File
@@ -0,0 +1,128 @@
# Migration Guide: v1.x to v2.0.0
## Overview
Version 2.0.0 adds hooks integration and enhanced templates while maintaining backward compatibility with existing workflows.
## What's New
### 1. Hooks (Automatic Behaviors)
v2.0.0 adds Claude Code hooks that automate key Manus principles:
| Hook | Trigger | Behavior |
|------|---------|----------|
| `PreToolUse` | Before Write/Edit/Bash | Reads `task_plan.md` to refresh goals |
| `Stop` | Before stopping | Verifies all phases are complete |
**Benefit:** You no longer need to manually remember to re-read your plan. The hook does it automatically.
### 2. Templates Directory
New templates provide structured starting points:
```
templates/
├── task_plan.md # Phase tracking with status fields
├── findings.md # Research storage with 2-action reminder
└── progress.md # Session log with 5-question reboot test
```
### 3. Scripts Directory
Helper scripts for common operations:
```
scripts/
├── init-session.sh # Creates all 3 planning files
└── check-complete.sh # Verifies task completion
```
## Migration Steps
### Step 1: Update the Plugin
```bash
# If installed via marketplace
/plugin update planning-with-files
# If installed manually
cd .claude/plugins/planning-with-files
git pull origin master
```
### Step 2: Existing Files Continue Working
Your existing `task_plan.md` files will continue to work. The hooks look for this file and gracefully handle its absence.
### Step 3: Adopt New Templates (Optional)
To use the new structured templates, you can either:
1. **Start fresh** with `./scripts/init-session.sh`
2. **Copy templates** from `templates/` directory
3. **Keep your existing format** - it still works
### Step 4: Update Phase Status Format (Recommended)
v2.0.0 templates use a more structured status format:
**v1.x format:**
```markdown
- [x] Phase 1: Setup ✓
- [ ] Phase 2: Implementation (CURRENT)
```
**v2.0.0 format:**
```markdown
### Phase 1: Setup
- **Status:** complete
### Phase 2: Implementation
- **Status:** in_progress
```
The new format enables the `check-complete.sh` script to automatically verify completion.
## Breaking Changes
**None.** v2.0.0 is fully backward compatible.
If you prefer the v1.x behavior without hooks, use the `legacy` branch:
```bash
git checkout legacy
```
## New Features to Adopt
### The 2-Action Rule
After every 2 view/browser/search operations, save findings to files:
```
WebSearch → WebSearch → MUST Write findings.md
```
### The 3-Strike Error Protocol
Structured error recovery:
1. Diagnose & Fix
2. Alternative Approach
3. Broader Rethink
4. Escalate to User
### The 5-Question Reboot Test
Your planning files should answer:
1. Where am I? → Current phase
2. Where am I going? → Remaining phases
3. What's the goal? → Goal statement
4. What have I learned? → findings.md
5. What have I done? → progress.md
## Questions?
Open an issue: https://github.com/OthmanAdi/planning-with-files/issues
+161 -65
View File
@@ -1,18 +1,38 @@
# Planning with Files
> **Work like Manus** — the AI agent company Meta just acquired for **$2 billion**.
> **Work like Manus** — the AI agent company Meta acquired for **$2 billion**.
## Thank You
To everyone who starred, forked, and shared this skill — thank you. This project blew up in less than 24 hours, and the support from the community has been incredible.
If this skill helps you work smarter, that's all I wanted.
---
A Claude Code plugin containing an [Agent Skill](https://code.claude.com/docs/en/skills) that transforms your workflow to use persistent markdown files for planning, progress tracking, and knowledge storage — the exact pattern that made Manus worth billions.
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-Plugin-blue)](https://code.claude.com/docs/en/plugins)
[![Claude Code Skill](https://img.shields.io/badge/Claude%20Code-Skill-green)](https://code.claude.com/docs/en/skills)
[![Cursor Rules](https://img.shields.io/badge/Cursor-Rules-purple)](https://docs.cursor.com/context/rules-for-ai)
[![Version](https://img.shields.io/badge/version-2.0.1-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)
## Star History
## Versions
[![Star History Chart](https://api.star-history.com/svg?repos=OthmanAdi/planning-with-files&type=Date)](https://star-history.com/#OthmanAdi/planning-with-files&Date)
| Version | Branch | Features | Install |
|---------|--------|----------|---------|
| **v2.0.0** (current) | `master` | Hooks, templates, scripts | `/plugin install planning-with-files@planning-with-files` |
| **v1.0.0** (legacy) | `legacy` | Core 3-file pattern | `git clone -b legacy https://github.com/OthmanAdi/planning-with-files.git` |
---
## What's New in v2.0.0
- **Hooks Integration** — Automatic plan re-reading and completion verification
- **Templates** — Structured templates for task_plan.md, findings.md, progress.md
- **Scripts** — Helper scripts for initialization and completion checks
- **Enhanced Documentation** — 2-Action Rule, 3-Strike Protocol, 5-Question Reboot Test
See [CHANGELOG.md](CHANGELOG.md) for details. Upgrading from v1.x? See [MIGRATION.md](MIGRATION.md).
## Why This Skill?
@@ -38,20 +58,18 @@ For every complex task, create THREE files:
```
task_plan.md → Track phases and progress
notes.md → Store research and findings
[deliverable].md → Final output
findings.md → Store research and findings
progress.md → Session log and test results
```
### The Loop
### The Core Principle
```
1. Create task_plan.md with goal and phases
2. Research → save to notes.md → update task_plan.md
3. Read notes.md → create deliverable → update task_plan.md
4. Deliver final output
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
**Key insight:** By reading `task_plan.md` before each decision, goals stay in the attention window. This is how Manus handles ~50 tool calls without losing track.
→ Anything important gets written to disk.
```
## Installation
@@ -90,46 +108,142 @@ git clone https://github.com/OthmanAdi/planning-with-files.git
cp -r planning-with-files/skills/* ~/.claude/skills/
```
### Verify Installation
### Cursor Installation
Once installed, the skill will automatically activate when you:
- Start complex tasks
- Mention "planning", "organize", or "track progress"
- Ask for structured work
Copy the `.cursor/rules/` directory into your project:
```bash
git clone https://github.com/OthmanAdi/planning-with-files.git
cp -r planning-with-files/.cursor .cursor
```
Or manually create `.cursor/rules/planning-with-files.mdc` in your project with the content from this repo.
> **Note:** Hooks (PreToolUse, Stop) are Claude Code specific and won't work in Cursor. The core planning workflow still applies.
### One-Line Installer (Skills Only)
Extract just the skill directly into your current directory:
```bash
curl -L https://github.com/OthmanAdi/planning-with-files/archive/master.tar.gz | tar -xzv --strip-components=2 "planning-with-files-master/skills/planning-with-files"
```
Then move `planning-with-files/` to `~/.claude/skills/`.
## Usage
Once installed, Claude will automatically:
1. **Create `task_plan.md`** before starting complex tasks
2. **Update progress** with checkboxes after each phase
3. **Store findings** in `notes.md` instead of stuffing context
4. **Log errors** for future reference
5. **Re-read plan** before major decisions
2. **Re-read plan** before major decisions (via hooks)
3. **Update progress** with checkboxes after each phase
4. **Store findings** in `findings.md` instead of stuffing context
5. **Log errors** for future reference
6. **Verify completion** before stopping (via hooks)
### Example
### Key Rules
**You:** "Research the benefits of TypeScript and write a summary"
1. **Create Plan First** — Never start without `task_plan.md`
2. **The 2-Action Rule** — Save findings after every 2 view/browser operations
3. **Log ALL Errors** — They help avoid repetition
4. **Never Repeat Failures** — Track attempts, mutate approach
**Claude creates:**
## Troubleshooting
```markdown
# Task Plan: TypeScript Benefits Research
### Planning files created in wrong directory
## Goal
Create a research summary on TypeScript benefits.
**Issue:** When using `/plan`, the files (`task_plan.md`, `findings.md`, `progress.md`) are created in the skill installation directory instead of your project.
## Phases
- [x] Phase 1: Create plan ✓
- [ ] Phase 2: Research and gather sources (CURRENT)
- [ ] Phase 3: Synthesize findings
- [ ] Phase 4: Deliver summary
**Why this happens:** When the skill runs as a subagent, it may not inherit your terminal's current working directory.
## Status
**Currently in Phase 2** - Searching for sources
**Solutions:**
1. **Specify your project path when invoking:**
```
/plan - I'm working in /path/to/my-project/, create all files there
```
2. **Add context before invoking:**
```
I'm working on the project at /path/to/my-project/
```
Then run `/plan`.
3. **Create a CLAUDE.md in your project root:**
```markdown
# Project Context
All planning files (task_plan.md, findings.md, progress.md)
should be created in this directory.
```
4. **Use the skill directly without subagent:**
```
Help me plan this task using the planning-with-files approach.
Create task_plan.md, findings.md, and progress.md here.
```
**Fixed in v2.0.1:** The skill instructions now explicitly specify that planning files should be created in your project directory, not the skill installation folder.
---
### Files not persisting between sessions
**Issue:** Planning files seem to disappear or aren't found when resuming work.
**Solution:** Make sure the files are in your project root, not in a temporary location. Check with:
```bash
ls -la task_plan.md findings.md progress.md
```
Then continues through each phase, updating the file as it goes.
---
### Hooks not triggering
**Issue:** The PreToolUse hook (which reads task_plan.md before actions) doesn't seem to run.
**Solution:**
1. Ensure you're using Claude Code v1.0.18 or later
2. Verify the skill is installed correctly: `ls ~/.claude/skills/planning-with-files/`
3. Check that `task_plan.md` exists in your current directory
---
### Need help?
Open an issue at [github.com/OthmanAdi/planning-with-files/issues](https://github.com/OthmanAdi/planning-with-files/issues) with:
- Your Claude Code version (`claude --version`)
- The command you ran
- What happened vs what you expected
## File Structure
```
planning-with-files/
├── .claude-plugin/
│ ├── plugin.json # Plugin manifest
│ └── marketplace.json # Marketplace listing
├── .cursor/
│ └── rules/
│ └── planning-with-files.mdc # Cursor rules file
├── skills/
│ └── planning-with-files/
│ ├── SKILL.md # Main skill definition
│ ├── reference.md # Manus principles
│ ├── examples.md # Usage examples
│ ├── templates/ # File templates
│ │ ├── task_plan.md
│ │ ├── findings.md
│ │ └── progress.md
│ └── scripts/ # Helper scripts
│ ├── init-session.sh
│ └── check-complete.sh
├── CHANGELOG.md # Version history
├── MIGRATION.md # Upgrade guide
├── LICENSE
└── README.md
```
## The Manus Principles
@@ -138,27 +252,10 @@ This skill implements these key context engineering principles:
| Principle | Implementation |
|-----------|----------------|
| Filesystem as memory | Store in files, not context |
| Attention manipulation | Re-read plan before decisions |
| Attention manipulation | Re-read plan before decisions (hooks) |
| Error persistence | Log failures in plan file |
| Goal tracking | Checkboxes show progress |
| Append-only context | Never modify history |
## File Structure
```
planning-with-files/
├── .claude-plugin/
│ └── plugin.json # Plugin manifest (required for plugin distribution)
├── skills/
│ └── planning-with-files/
│ ├── SKILL.md # Agent Skill definition (what Claude reads)
│ ├── reference.md # Manus principles deep dive
│ └── examples.md # Real usage examples
├── LICENSE
└── README.md # This file
```
> **Note:** This repository is a **Plugin** that contains an **Agent Skill**. The plugin format (`.claude-plugin/`) enables easy distribution and installation, while the skill (`skills/planning-with-files/SKILL.md`) defines the actual behavior that Claude uses.
| Completion verification | Stop hook checks all phases |
## When to Use
@@ -176,9 +273,10 @@ planning-with-files/
## Acknowledgments
- **Manus AI** — For pioneering context engineering patterns that made this possible
- **Anthropic** — For Claude Code, the [Agent Skills](https://code.claude.com/docs/en/skills) framework and the [Plugin system](https://code.claude.com/docs/en/plugins)
- Based on [Context Engineering for AI Agents](https://manus.im/de/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus)
- **Manus AI** — For pioneering context engineering patterns
- **Anthropic** — For Claude Code, Agent Skills, and the Plugin system
- **Lance Martin** — For the detailed Manus architecture analysis
- Based on [Context Engineering for AI Agents](https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus)
## Contributing
@@ -191,12 +289,10 @@ Contributions welcome! Please:
MIT License — feel free to use, modify, and distribute.
## Thank You
To everyone who starred, forked, and shared this skill — thank you. This project blew up in less than 24 hours, and the support from the community has been incredible.
If this skill helps you work smarter, that's all I wanted.
---
**Author:** [Ahmad Othman Ammar Adi](https://github.com/OthmanAdi)
## Star History
[![Star History Chart](https://api.star-history.com/svg?repos=OthmanAdi/planning-with-files&type=Date)](https://star-history.com/#OthmanAdi/planning-with-files&Date)
+151 -119
View File
@@ -1,137 +1,158 @@
---
name: planning-with-files
version: "1.0.0"
description: Transforms workflow to use Manus-style persistent markdown files for planning, progress tracking, and knowledge storage. Use when starting complex tasks, multi-step projects, research tasks, or when the user mentions planning, organizing work, tracking progress, or wants structured output.
version: "2.0.1"
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls.
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch
hooks:
PreToolUse:
- matcher: "Write|Edit|Bash"
hooks:
- type: command
command: "cat task_plan.md 2>/dev/null | head -30 || true"
Stop:
- hooks:
- type: command
command: "${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.sh"
---
# Planning with Files
Work like Manus: Use persistent markdown files as your "working memory on disk."
## Important: Where Files Go
When using this skill:
- **Templates** are stored in the skill directory at `${CLAUDE_PLUGIN_ROOT}/templates/`
- **Your planning files** (`task_plan.md`, `findings.md`, `progress.md`) should be created in **your project directory** — the folder where you're working
| Location | What Goes There |
|----------|-----------------|
| Skill directory (`${CLAUDE_PLUGIN_ROOT}/`) | Templates, scripts, reference docs |
| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
This ensures your planning files live alongside your code, not buried in the skill installation folder.
## Quick Start
Before ANY complex task:
1. **Create `task_plan.md`** in the working directory
2. **Define phases** with checkboxes
3. **Update after each phase** - mark [x] and change status
4. **Read before deciding** - refresh goals in attention window
1. **Create `task_plan.md`** in your project — Use [templates/task_plan.md](templates/task_plan.md) as reference
2. **Create `findings.md`** in your project — Use [templates/findings.md](templates/findings.md) as reference
3. **Create `progress.md`** in your project — Use [templates/progress.md](templates/progress.md) as reference
4. **Re-read plan before decisions** — Refreshes goals in attention window
5. **Update after each phase** — Mark complete, log errors
## The 3-File Pattern
> **Note:** All three planning files should be created in your current working directory (your project root), not in the skill's installation folder.
For every non-trivial task, create THREE files:
## 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` | Track phases and progress | After each phase |
| `notes.md` | Store findings and research | During research |
| `[deliverable].md` | Final output | At completion |
## Core Workflow
```
Loop 1: Create task_plan.md with goal and phases
Loop 2: Research → save to notes.md → update task_plan.md
Loop 3: Read notes.md → create deliverable → update task_plan.md
Loop 4: Deliver final output
```
### The Loop in Detail
**Before each major action:**
```bash
Read task_plan.md # Refresh goals in attention window
```
**After each phase:**
```bash
Edit task_plan.md # Mark [x], update status
```
**When storing information:**
```bash
Write notes.md # Don't stuff context, store in file
```
## task_plan.md Template
Create this file FIRST for any complex task:
```markdown
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Phases
- [ ] Phase 1: Plan and setup
- [ ] Phase 2: Research/gather information
- [ ] Phase 3: Execute/build
- [ ] Phase 4: Review and deliver
## Key Questions
1. [Question to answer]
2. [Question to answer]
## Decisions Made
- [Decision]: [Rationale]
## Errors Encountered
- [Error]: [Resolution]
## Status
**Currently in Phase X** - [What I'm doing now]
```
## notes.md Template
For research and findings:
```markdown
# Notes: [Topic]
## Sources
### Source 1: [Name]
- URL: [link]
- Key points:
- [Finding]
- [Finding]
## Synthesized Findings
### [Category]
- [Finding]
- [Finding]
```
| `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. ALWAYS Create Plan First
Never start a complex task without `task_plan.md`. This is non-negotiable.
### 1. Create Plan First
Never start a complex task without `task_plan.md`. Non-negotiable.
### 2. Read Before Decide
Before any major decision, read the plan file. This keeps goals in your attention window.
### 2. The 2-Action Rule
> "After every 2 view/browser/search operations, IMMEDIATELY save key findings to text files."
### 3. Update After Act
After completing any phase, immediately update the plan file:
- Mark completed phases with [x]
- Update the Status section
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
### 4. Store, Don't Stuff
Large outputs go to files, not context. Keep only paths in working memory.
### 5. Log ALL Errors
Every error goes in the plan file. This builds knowledge and prevents repetition.
### 5. Log All Errors
Every error goes in the "Errors Encountered" section. This builds knowledge for future tasks.
```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 3-file pattern for:**
**Use for:**
- Multi-step tasks (3+ steps)
- Research tasks
- Building/creating something
- Tasks spanning multiple tool calls
- Building/creating projects
- Tasks spanning many tool calls
- Anything requiring organization
**Skip for:**
@@ -139,23 +160,34 @@ Every error goes in the "Errors Encountered" section. This builds knowledge for
- Single-file edits
- Quick lookups
## Anti-Patterns to Avoid
## 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 [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 each decision |
| Hide errors and retry | Log errors to plan file |
| 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 |
## Advanced Patterns
See [reference.md](reference.md) for:
- Attention manipulation techniques
- Error recovery patterns
- Context optimization from Manus
See [examples.md](examples.md) for:
- Real task examples
- Complex workflow patterns
| Repeat failed actions | Track attempts, mutate approach |
| Create files in skill directory | Create files in your project |
+156 -48
View File
@@ -1,50 +1,68 @@
# Reference: Manus Context Engineering Principles
This skill is based on the context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
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
### 1. Filesystem as External Memory
### 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."
**Problem:** Context windows have limits. Stuffing everything in context degrades performance and increases costs.
**The Formula:**
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
```
**Solution:** Treat the filesystem as unlimited memory:
- Store large content in files
- Keep only paths in context
- Agent can "look up" information when needed
- Compression must be REVERSIBLE
**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
### 2. Attention Manipulation Through Repetition
### 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:** Keep a `task_plan.md` file that gets RE-READ throughout execution:
**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!]
```
By reading the plan file before each decision, goals appear in the attention window.
### Principle 5: Keep the Wrong Stuff In
### 3. Keep Failure Traces
> "Leave the wrong turns in the context."
> "Error recovery is one of the clearest signals of TRUE agentic behavior."
**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"
**Problem:** Instinct says hide errors, retry silently. This wastes tokens and loses learning.
**Solution:** KEEP failed actions in the plan file:
```markdown
## Errors Encountered
- [2025-01-03] FileNotFoundError: config.json not found → Created default config
- [2025-01-03] API timeout → Retried with exponential backoff, succeeded
```
The model updates its internal understanding when seeing failures.
### 4. Avoid Few-Shot Overfitting
### Principle 6: Don't Get Few-Shotted
> "Uniformity breeds fragility."
@@ -55,56 +73,146 @@ The model updates its internal understanding when seeing failures.
- Don't copy-paste patterns blindly
- Recalibrate on repetitive tasks
### 5. Stable Prefixes for Cache Optimization
---
**Problem:** Agents are input-heavy (100:1 ratio). Every token costs money.
## The 3 Context Engineering Strategies
**Solution:** Structure for cache hits:
- Put static content FIRST
- Append-only context (never modify history)
- Consistent serialization
Based on Lance Martin's analysis of Manus architecture.
### 6. Append-Only Context
### Strategy 1: Context Reduction
**Problem:** Modifying previous messages invalidates KV-cache.
**Compaction:**
```
Tool calls have TWO representations:
├── FULL: Raw tool content (stored in filesystem)
└── COMPACT: Reference/file path only
**Solution:** NEVER modify previous messages. Always append new information.
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 loop:
Manus operates in a continuous 7-step loop:
```
1. Analyze → 2. Think → 3. Select Tool → 4. Execute → 5. Observe → 6. Iterate → 7. Deliver
┌─────────────────────────────────────────┐
│ 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 Operations in the Loop:
---
| Operation | When to Use |
|-----------|-------------|
| `write` | New files or complete rewrites |
| `append` | Adding sections incrementally |
| `edit` | Updating specific parts (checkboxes, status) |
| `read` | Reviewing before decisions |
## 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 ratio | 100:1 |
| 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
> "If the model improvement is the rising tide, we want Manus to be the boat, not the piling stuck on the seafloor."
> "Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."
> "For complex tasks, I save notes, code, and findings to files so I can reference them as I work."
> "if action_failed: next_action != same_action. Track what you tried. Mutate the approach."
> "I used file.edit to update checkboxes in my plan as I progressed, rather than rewriting the whole file."
> "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/de/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
@@ -0,0 +1,44 @@
#!/bin/bash
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
echo "ERROR: $PLAN_FILE not found"
echo "Cannot verify completion without a task plan."
exit 1
fi
echo "=== Task Completion Check ==="
echo ""
# Count phases by status (using -F for fixed string matching)
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
COMPLETE=$(grep -cF "**Status:** complete" "$PLAN_FILE" || true)
IN_PROGRESS=$(grep -cF "**Status:** in_progress" "$PLAN_FILE" || true)
PENDING=$(grep -cF "**Status:** pending" "$PLAN_FILE" || true)
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
echo "Total phases: $TOTAL"
echo "Complete: $COMPLETE"
echo "In progress: $IN_PROGRESS"
echo "Pending: $PENDING"
echo ""
# Check completion
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "ALL PHASES COMPLETE"
exit 0
else
echo "TASK NOT COMPLETE"
echo ""
echo "Do not stop until all phases are complete."
exit 1
fi
@@ -0,0 +1,120 @@
#!/bin/bash
# Initialize planning files for a new session
# Usage: ./init-session.sh [project-name]
set -e
PROJECT_NAME="${1:-project}"
DATE=$(date +%Y-%m-%d)
echo "Initializing planning files for: $PROJECT_NAME"
# Create task_plan.md if it doesn't exist
if [ ! -f "task_plan.md" ]; then
cat > task_plan.md << 'EOF'
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
EOF
echo "Created task_plan.md"
else
echo "task_plan.md already exists, skipping"
fi
# Create findings.md if it doesn't exist
if [ ! -f "findings.md" ]; then
cat > findings.md << 'EOF'
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
EOF
echo "Created findings.md"
else
echo "findings.md already exists, skipping"
fi
# Create progress.md if it doesn't exist
if [ ! -f "progress.md" ]; then
cat > progress.md << EOF
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
EOF
echo "Created progress.md"
else
echo "progress.md already exists, skipping"
fi
echo ""
echo "Planning files initialized!"
echo "Files: task_plan.md, findings.md, progress.md"
@@ -0,0 +1,34 @@
# Findings & Decisions
## Requirements
<!-- Captured from user request -->
-
## Research Findings
<!-- Key discoveries during exploration -->
-
## Technical Decisions
<!-- Decisions made with rationale -->
| Decision | Rationale |
|----------|-----------|
| | |
## Issues Encountered
<!-- Errors and how they were resolved -->
| Issue | Resolution |
|-------|------------|
| | |
## Resources
<!-- URLs, file paths, API references -->
-
## Visual/Browser Findings
<!-- CRITICAL: Update after every 2 view/browser operations -->
<!-- Multimodal content must be captured as text immediately -->
-
---
*Update this file after every 2 view/browser/search operations*
*This prevents visual information from being lost*
@@ -0,0 +1,44 @@
# Progress Log
## Session: [DATE]
### Phase 1: [Title]
- **Status:** in_progress
- **Started:** [timestamp]
- Actions taken:
-
- Files created/modified:
-
### Phase 2: [Title]
- **Status:** pending
- Actions taken:
-
- Files created/modified:
-
## Test Results
| Test | Input | Expected | Actual | Status |
|------|-------|----------|--------|--------|
| | | | | |
## Error Log
<!-- Keep ALL errors - they help avoid repetition -->
| Timestamp | Error | Attempt | Resolution |
|-----------|-------|---------|------------|
| | | 1 | |
## 5-Question Reboot Check
<!-- 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 |
---
*Update after completing each phase or encountering errors*
@@ -0,0 +1,58 @@
# 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 and requirements
- [ ] Document findings in notes.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define technical approach
- [ ] Create project structure if needed
- [ ] Document decisions with rationale
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan step by step
- [ ] Write code to files before executing
- [ ] Test incrementally
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify all requirements met
- [ ] Document test results in progress.md
- [ ] Fix any issues found
- **Status:** pending
### Phase 5: Delivery
- [ ] Review all output files
- [ ] Ensure deliverables are complete
- [ ] Deliver to user
- **Status:** pending
## Key Questions
1. [Question to answer]
2. [Question to answer]
## Decisions Made
| Decision | Rationale |
|----------|-----------|
| | |
## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| | 1 | |
## Notes
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition