Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
50a8f45fca | ||
|
|
7251f923e4 | ||
|
|
0a753038b2 | ||
|
|
ef493399f0 | ||
|
|
269116c2af | ||
|
|
006ea9a6c1 | ||
|
|
9f34d9ca11 |
@@ -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"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -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"
|
||||
]
|
||||
}
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
@@ -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
@@ -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
|
||||
@@ -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.
|
||||
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://code.claude.com/docs/en/plugins)
|
||||
[](https://code.claude.com/docs/en/skills)
|
||||
[](https://docs.cursor.com/context/rules-for-ai)
|
||||
[](https://github.com/OthmanAdi/planning-with-files/releases)
|
||||
|
||||
## Star History
|
||||
## Versions
|
||||
|
||||
[](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
|
||||
|
||||
[](https://star-history.com/#OthmanAdi/planning-with-files&Date)
|
||||
|
||||
+151
-119
@@ -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 |
|
||||
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user