Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 OthmanAdi
|
2ade778cf2 | ||
|
OthmanAdi
|
3e08dd9bd5 | ||
|
OthmanAdi
|
1e5066957a | ||
|
OthmanAdi
|
ac76baea26 | ||
|
OthmanAdi
|
7de9247951 | ||
|
OthmanAdi
|
c5690231ac | ||
|
Nicolas MaroisandClaude Opus 4.5
|
3237ad2763 | ||
|
OthmanAdiandClaude Sonnet 4.5
|
c84f56574e | ||
|
OthmanAdiandClaude Sonnet 4.5
|
4f2586691a | ||
|
OthmanAdiandClaude Sonnet 4.5
|
1844bbb90f | ||
|
OthmanAdiandClaude Sonnet 4.5
|
ab10960a4b |
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "planning-with-files",
|
||||
"version": "2.2.2",
|
||||
"description": "Manus-style persistent markdown files for planning, progress tracking, and knowledge storage. Includes hooks for automatic plan re-reading and completion verification. Use when starting complex tasks, multi-step projects, research tasks, or when you want structured output.",
|
||||
"version": "2.4.1",
|
||||
"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.",
|
||||
"author": {
|
||||
"name": "OthmanAdi",
|
||||
"url": "https://github.com/OthmanAdi"
|
||||
@@ -15,7 +15,6 @@
|
||||
"markdown",
|
||||
"context-engineering",
|
||||
"task-management",
|
||||
"hooks",
|
||||
"templates"
|
||||
]
|
||||
}
|
||||
|
||||
@@ -0,0 +1,92 @@
|
||||
# Installing planning-with-files for Codex
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Codex IDE installed
|
||||
- Git installed (optional, for cloning)
|
||||
|
||||
## Installation
|
||||
|
||||
### Option 1: Clone Repository (Recommended)
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.codex/skills
|
||||
cd ~/.codex/skills
|
||||
git clone https://github.com/OthmanAdi/planning-with-files.git
|
||||
```
|
||||
|
||||
### Option 2: Manual Copy
|
||||
|
||||
1. Download or clone this repository
|
||||
2. Copy the entire `planning-with-files/` directory to `~/.codex/skills/`
|
||||
3. Ensure the structure matches:
|
||||
```
|
||||
~/.codex/skills/planning-with-files/
|
||||
├── planning-with-files/
|
||||
│ ├── SKILL.md
|
||||
│ ├── templates/
|
||||
│ └── scripts/
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### If Using Superpowers
|
||||
|
||||
If you have [obra/superpowers](https://github.com/obra/superpowers) installed:
|
||||
|
||||
```bash
|
||||
~/.codex/superpowers/.codex/superpowers-codex use-skill planning-with-files
|
||||
```
|
||||
|
||||
Superpowers will find it in your personal skills directory.
|
||||
|
||||
### If NOT Using Superpowers
|
||||
|
||||
Manually read the skill file when starting complex tasks:
|
||||
|
||||
```bash
|
||||
cat ~/.codex/skills/planning-with-files/planning-with-files/SKILL.md
|
||||
```
|
||||
|
||||
Or add to your `~/.codex/AGENTS.md`:
|
||||
|
||||
```markdown
|
||||
## Planning with Files
|
||||
|
||||
<IMPORTANT>
|
||||
For complex multi-step tasks (3+ steps, research, building projects):
|
||||
1. Read the planning-with-files skill: `cat ~/.codex/skills/planning-with-files/planning-with-files/SKILL.md`
|
||||
2. Create task_plan.md, findings.md, progress.md in your project directory
|
||||
3. Follow the 3-file pattern throughout the task
|
||||
</IMPORTANT>
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
Check that the skill exists:
|
||||
|
||||
```bash
|
||||
ls -la ~/.codex/skills/planning-with-files/planning-with-files/SKILL.md
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Skill not found
|
||||
|
||||
- Verify path: `~/.codex/skills/planning-with-files/planning-with-files/SKILL.md`
|
||||
- Check file exists and is readable
|
||||
- Ensure SKILL.md has proper YAML frontmatter
|
||||
|
||||
### Scripts not executing
|
||||
|
||||
**Windows users:**
|
||||
- Use PowerShell versions: `*.ps1`
|
||||
- Set execution policy: `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`
|
||||
|
||||
**Unix/Mac users:**
|
||||
- Make scripts executable: `chmod +x ~/.codex/skills/planning-with-files/scripts/*.sh`
|
||||
|
||||
## Getting Help
|
||||
|
||||
- Issues: https://github.com/OthmanAdi/planning-with-files/issues
|
||||
- Documentation: https://github.com/OthmanAdi/planning-with-files
|
||||
@@ -0,0 +1,139 @@
|
||||
# Installing planning-with-files for OpenCode
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- OpenCode.ai installed
|
||||
- Git installed (optional, for cloning)
|
||||
|
||||
## Installation
|
||||
|
||||
### Option 1: Global Installation (All Projects)
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.config/opencode/skills
|
||||
cd ~/.config/opencode/skills
|
||||
git clone https://github.com/OthmanAdi/planning-with-files.git
|
||||
```
|
||||
|
||||
### Option 2: Project-Specific Installation
|
||||
|
||||
```bash
|
||||
# In your OpenCode project root
|
||||
mkdir -p .opencode/skills
|
||||
cd .opencode/skills
|
||||
git clone https://github.com/OthmanAdi/planning-with-files.git
|
||||
```
|
||||
|
||||
### Option 3: Manual Copy
|
||||
|
||||
**For global installation:**
|
||||
1. Download or clone this repository
|
||||
2. Copy to `~/.config/opencode/skills/planning-with-files/`
|
||||
|
||||
**For project installation:**
|
||||
1. Download or clone this repository
|
||||
2. Copy to `.opencode/skills/planning-with-files/` in your project
|
||||
|
||||
## File Structure
|
||||
|
||||
After installation:
|
||||
|
||||
```
|
||||
~/.config/opencode/skills/planning-with-files/ (or .opencode/skills/planning-with-files/)
|
||||
├── planning-with-files/
|
||||
│ ├── SKILL.md # Main skill file
|
||||
│ ├── templates/
|
||||
│ │ ├── task_plan.md
|
||||
│ │ ├── findings.md
|
||||
│ │ └── progress.md
|
||||
│ └── scripts/
|
||||
│ ├── check-complete.sh
|
||||
│ ├── check-complete.ps1
|
||||
│ ├── init-session.sh
|
||||
│ ├── init-session.ps1
|
||||
│ └── session-catchup.py
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### If Using Superpowers Plugin
|
||||
|
||||
If you have [obra/superpowers](https://github.com/obra/superpowers) installed as an OpenCode plugin:
|
||||
|
||||
```
|
||||
Use the use_skill tool with skill_name: "planning-with-files"
|
||||
```
|
||||
|
||||
OpenCode will find it automatically (personal skills override superpowers skills).
|
||||
|
||||
### If NOT Using Superpowers
|
||||
|
||||
You can still manually load the skill:
|
||||
|
||||
1. Navigate to `~/.config/opencode/skills/planning-with-files/planning-with-files/`
|
||||
2. Read SKILL.md
|
||||
3. Follow the instructions for creating task_plan.md, findings.md, progress.md
|
||||
|
||||
Or create a custom tool/command to load it.
|
||||
|
||||
## Skill Priority
|
||||
|
||||
If installed as:
|
||||
- **Project skill** (`.opencode/skills/planning-with-files/`) - Highest priority
|
||||
- **Personal skill** (`~/.config/opencode/skills/planning-with-files/`) - Medium priority
|
||||
- If superpowers has a planning-with-files skill - Lowest priority
|
||||
|
||||
Project skills override personal skills, which override superpowers skills.
|
||||
|
||||
## Verification
|
||||
|
||||
**Global installation:**
|
||||
```bash
|
||||
ls -la ~/.config/opencode/skills/planning-with-files/planning-with-files/SKILL.md
|
||||
```
|
||||
|
||||
**Project installation:**
|
||||
```bash
|
||||
ls -la .opencode/skills/planning-with-files/planning-with-files/SKILL.md
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Skill not loading
|
||||
|
||||
1. Verify SKILL.md exists at the correct path
|
||||
2. Check YAML frontmatter is valid:
|
||||
```yaml
|
||||
---
|
||||
name: planning-with-files
|
||||
description: ...
|
||||
---
|
||||
```
|
||||
3. If using superpowers plugin, use `find_skills` tool to verify it's discovered
|
||||
|
||||
### Scripts not executing
|
||||
|
||||
**Windows:**
|
||||
- Use PowerShell versions: `*.ps1`
|
||||
- Set execution policy: `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`
|
||||
|
||||
**Unix/Mac:**
|
||||
- Make executable: `chmod +x ~/.config/opencode/skills/planning-with-files/scripts/*.sh`
|
||||
|
||||
### oh-my-opencode Blocking
|
||||
|
||||
If using oh-my-opencode and the skill isn't recognized:
|
||||
|
||||
1. Check `~/.config/opencode/oh-my-opencode.json`
|
||||
2. Ensure planning-with-files is NOT in `disabled_skills` array:
|
||||
```json
|
||||
{
|
||||
"disabled_skills": []
|
||||
}
|
||||
```
|
||||
3. Restart OpenCode
|
||||
|
||||
## Getting Help
|
||||
|
||||
- Issues: https://github.com/OthmanAdi/planning-with-files/issues
|
||||
- Documentation: https://github.com/OthmanAdi/planning-with-files
|
||||
@@ -2,6 +2,101 @@
|
||||
|
||||
All notable changes to this project will be documented in this file.
|
||||
|
||||
## [2.4.0] - 2026-01-20
|
||||
|
||||
### Fixed
|
||||
|
||||
- **CRITICAL: Fixed SKILL.md frontmatter to comply with official Agent Skills spec** (Issue #39)
|
||||
- Removed invalid `hooks:` field from SKILL.md frontmatter (not supported by spec)
|
||||
- Removed invalid top-level `version:` field (moved to `metadata.version`)
|
||||
- Removed `user-invocable:` field (not in official spec)
|
||||
- Changed `allowed-tools:` from YAML list to space-delimited string per spec
|
||||
- This fixes `/planning-with-files` slash command not appearing for users
|
||||
|
||||
### Changed
|
||||
|
||||
- SKILL.md frontmatter now follows [Agent Skills Specification](https://agentskills.io/specification)
|
||||
- Version now stored in `metadata.version` field
|
||||
- Removed `${CLAUDE_PLUGIN_ROOT}` variable references from SKILL.md (use relative paths)
|
||||
- Updated plugin.json to v2.4.0
|
||||
|
||||
### Technical Details
|
||||
|
||||
The previous SKILL.md used non-standard frontmatter fields:
|
||||
```yaml
|
||||
# OLD (broken)
|
||||
version: "2.3.0" # NOT supported at top level
|
||||
user-invocable: true # NOT in official spec
|
||||
hooks: # NOT supported in SKILL.md
|
||||
PreToolUse: ...
|
||||
```
|
||||
|
||||
Now uses spec-compliant format:
|
||||
```yaml
|
||||
# NEW (fixed)
|
||||
name: planning-with-files
|
||||
description: ...
|
||||
license: MIT
|
||||
metadata:
|
||||
version: "2.4.0"
|
||||
author: OthmanAdi
|
||||
allowed-tools: Read Write Edit Bash Glob Grep WebFetch WebSearch
|
||||
```
|
||||
|
||||
### Thanks
|
||||
|
||||
- @wqh17101 for identifying the issue in #39
|
||||
- @dalisoft and @zoffyzhang for reporting the problem
|
||||
|
||||
## [2.3.0] - 2026-01-17
|
||||
|
||||
### Added
|
||||
|
||||
- **Codex IDE Support**
|
||||
- Created `.codex/INSTALL.md` with installation instructions
|
||||
- Skills install to `~/.codex/skills/planning-with-files/`
|
||||
- Works with obra/superpowers or standalone
|
||||
- Added `docs/codex.md` for user documentation
|
||||
- Based on analysis of obra/superpowers Codex implementation
|
||||
|
||||
- **OpenCode IDE Support** (Issue #27)
|
||||
- Created `.opencode/INSTALL.md` with installation instructions
|
||||
- Global installation: `~/.config/opencode/skills/planning-with-files/`
|
||||
- Project installation: `.opencode/skills/planning-with-files/`
|
||||
- Works with obra/superpowers plugin or standalone
|
||||
- oh-my-opencode compatibility documented
|
||||
- Added `docs/opencode.md` for user documentation
|
||||
- Based on analysis of obra/superpowers OpenCode plugin
|
||||
|
||||
### Changed
|
||||
|
||||
- Updated README.md with Supported IDEs table
|
||||
- Updated README.md file structure diagram
|
||||
- Updated docs/installation.md with Codex and OpenCode sections
|
||||
- Version bump to 2.3.0
|
||||
|
||||
### Documentation
|
||||
|
||||
- Added Codex and OpenCode to IDE support table in README
|
||||
- Created comprehensive installation guides for both IDEs
|
||||
- Documented skill priority system for OpenCode
|
||||
- Documented integration with superpowers ecosystem
|
||||
|
||||
### Research
|
||||
|
||||
This implementation is based on real analysis of:
|
||||
- [obra/superpowers](https://github.com/obra/superpowers) repository
|
||||
- Codex skill system and CLI architecture
|
||||
- OpenCode plugin system and skill resolution
|
||||
- Skill priority and override mechanisms
|
||||
|
||||
### Thanks
|
||||
|
||||
- @Realtyxxx for feedback on Issue #27 about OpenCode support
|
||||
- obra for the superpowers reference implementation
|
||||
|
||||
---
|
||||
|
||||
## [2.2.2] - 2026-01-17
|
||||
|
||||
### Fixed
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,119 @@
|
||||
## Help Us Test Session Management Features!
|
||||
|
||||
I've implemented session management patterns from Anthropic's article ["Effective harnesses for long-running agents"](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) in the **`feature/anthropic-patterns`** branch.
|
||||
|
||||
These features need testing before merging to main. **Your feedback is critical!**
|
||||
|
||||
---
|
||||
|
||||
## What's New
|
||||
|
||||
### 1. Session Initialization Script
|
||||
Run at the start of every session:
|
||||
```bash
|
||||
bash scripts/init-session.sh
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
- ✅ Verifies planning files exist
|
||||
- ✅ Shows current phase and git status
|
||||
- ✅ Displays last commit
|
||||
- ✅ Logs session start to progress.md
|
||||
- ✅ Creates missing files if needed
|
||||
|
||||
### 2. Pass/Fail Status Tracking
|
||||
Enhanced `task_plan.md` template with:
|
||||
- Status icons: ⏸️ Pending | 🔄 In Progress | ✅ Pass | ❌ Fail | ⏭️ Skipped
|
||||
- Test Results table for each phase
|
||||
- Git Checkpoints table to log commits
|
||||
- Phase Summary table for quick overview
|
||||
|
||||
### 3. Git Checkpoint Workflow
|
||||
New documentation: `docs/git-checkpoints.md`
|
||||
- "One phase, one commit" pattern
|
||||
- Use git commits as rollback points
|
||||
- Integrates with task_plan.md
|
||||
|
||||
### 4. Session-Start Verification
|
||||
Automated checklist that verifies:
|
||||
- Planning files present
|
||||
- Git working tree clean
|
||||
- Current branch status
|
||||
- Last commit information
|
||||
|
||||
---
|
||||
|
||||
## How to Test
|
||||
|
||||
### 1. Checkout the Branch
|
||||
```bash
|
||||
cd your-planning-with-files-repo
|
||||
git fetch origin
|
||||
git checkout feature/anthropic-patterns
|
||||
```
|
||||
|
||||
### 2. Try It In a Test Project
|
||||
```bash
|
||||
cd ~/your-test-project
|
||||
bash /path/to/planning-with-files/scripts/init-session.sh
|
||||
```
|
||||
|
||||
### 3. Work Through a Multi-Phase Task
|
||||
- Let the script create planning files
|
||||
- Define some phases in task_plan.md
|
||||
- Complete a phase and test it
|
||||
- Mark it as ✅ Pass with test results
|
||||
- Commit: `git commit -m "feat(Phase 1): description"`
|
||||
- Log the commit hash in Git Checkpoints table
|
||||
- Start a new session and run init-session.sh again
|
||||
|
||||
### 4. Read the Implementation Summary
|
||||
See `IMPLEMENTATION_SUMMARY.md` in the branch for full details.
|
||||
|
||||
---
|
||||
|
||||
## What We Need Feedback On
|
||||
|
||||
1. **Does init-session.sh work on your system?**
|
||||
- Unix/Mac: Does the bash script run smoothly?
|
||||
- Windows: Does the PowerShell version work?
|
||||
|
||||
2. **Is the new task_plan.md template helpful?**
|
||||
- Are the status icons clear?
|
||||
- Is the Test Results table useful?
|
||||
- Does the Git Checkpoints table make sense?
|
||||
|
||||
3. **Does the workflow feel natural?**
|
||||
- Plan → Implement → Verify → Commit
|
||||
- Does session recovery work when you restart?
|
||||
|
||||
4. **Any bugs or issues?**
|
||||
- Errors when running scripts?
|
||||
- Confusing documentation?
|
||||
- Missing features?
|
||||
|
||||
5. **Suggestions for improvement?**
|
||||
- What would make this better?
|
||||
- Any patterns from the Anthropic article we missed?
|
||||
|
||||
---
|
||||
|
||||
## Related Issue
|
||||
|
||||
This work resolves [Issue #19](https://github.com/OthmanAdi/planning-with-files/issues/19) requested by @wqh17101.
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
- [Git Checkpoint Workflow](https://github.com/OthmanAdi/planning-with-files/blob/feature/anthropic-patterns/docs/git-checkpoints.md)
|
||||
- [Implementation Summary](https://github.com/OthmanAdi/planning-with-files/blob/feature/anthropic-patterns/IMPLEMENTATION_SUMMARY.md)
|
||||
- [Anthropic Article](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) (inspiration)
|
||||
|
||||
---
|
||||
|
||||
**Please test and share your experience!** Once we have enough feedback and approval, I'll merge this to main.
|
||||
|
||||
Thank you!
|
||||
|
||||
Ahmad
|
||||
@@ -16,7 +16,7 @@ A Claude Code plugin that transforms your workflow to use persistent markdown fi
|
||||
[](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)
|
||||
[](https://github.com/OthmanAdi/planning-with-files/releases)
|
||||
|
||||
## Quick Install
|
||||
|
||||
@@ -27,6 +27,16 @@ A Claude Code plugin that transforms your workflow to use persistent markdown fi
|
||||
|
||||
See [docs/installation.md](docs/installation.md) for all installation methods.
|
||||
|
||||
## Supported IDEs
|
||||
|
||||
| IDE | Status | Installation Guide | Format |
|
||||
|-----|--------|-------------------|--------|
|
||||
| Claude Code | ✅ Full Support | [Installation](docs/installation.md) | Plugin + SKILL.md |
|
||||
| Cursor | ✅ Full Support | [Cursor Setup](docs/cursor.md) | Rules |
|
||||
| Kilocode | ✅ Full Support | [Kilocode Setup](docs/kilocode.md) | Rules |
|
||||
| OpenCode | ✅ Full Support | [OpenCode Setup](docs/opencode.md) | Personal/Project Skill |
|
||||
| Codex | ✅ Full Support | [Codex Setup](docs/codex.md) | Personal Skill |
|
||||
|
||||
## Documentation
|
||||
|
||||
| Document | Description |
|
||||
@@ -38,12 +48,15 @@ See [docs/installation.md](docs/installation.md) for all installation methods.
|
||||
| [Cursor Setup](docs/cursor.md) | Cursor IDE-specific instructions |
|
||||
| [Windows Setup](docs/windows.md) | Windows-specific notes |
|
||||
| [Kilo Code Support](docs/kilocode.md) | Kilo Code integration guide |
|
||||
| [Codex Setup](docs/codex.md) | Codex IDE installation and usage |
|
||||
| [OpenCode Setup](docs/opencode.md) | OpenCode IDE installation, oh-my-opencode config |
|
||||
|
||||
## Versions
|
||||
|
||||
| Version | Features | Install |
|
||||
|---------|----------|---------|
|
||||
| **v2.2.2** (current) | Restored skill activation language | `/plugin install planning-with-files@planning-with-files` |
|
||||
| **v2.3.0** (current) | Codex & OpenCode IDE support | `/plugin install planning-with-files@planning-with-files` |
|
||||
| **v2.2.2** | Restored skill activation language | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
|
||||
| **v2.2.1** | Session recovery after /clear, enhanced PreToolUse hook | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
|
||||
| **v2.2.0** | Kilo Code IDE support, Windows PowerShell support, OS-aware hooks | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
|
||||
| **v2.1.2** | Fix template cache issue (Issue #18) | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
|
||||
@@ -162,7 +175,9 @@ planning-with-files/
|
||||
│ ├── troubleshooting.md
|
||||
│ ├── cursor.md
|
||||
│ ├── windows.md
|
||||
│ └── kilocode.md
|
||||
│ ├── kilocode.md
|
||||
│ ├── codex.md
|
||||
│ └── opencode.md
|
||||
├── planning-with-files/ # Plugin skill folder
|
||||
│ ├── SKILL.md
|
||||
│ ├── templates/
|
||||
@@ -178,6 +193,10 @@ planning-with-files/
|
||||
│ ├── check-complete.sh
|
||||
│ ├── init-session.ps1 # Windows PowerShell
|
||||
│ └── check-complete.ps1 # Windows PowerShell
|
||||
├── .codex/ # Codex IDE installation guide
|
||||
│ └── INSTALL.md
|
||||
├── .opencode/ # OpenCode IDE installation guide
|
||||
│ └── INSTALL.md
|
||||
├── .claude-plugin/ # Plugin manifest
|
||||
├── .cursor/ # Cursor rules
|
||||
├── .kilocode/ # Kilo Code rules
|
||||
|
||||
@@ -0,0 +1,79 @@
|
||||
# Welcome to planning-with-files
|
||||
|
||||
> **Work like Manus** — the AI agent company Meta acquired for **$2 billion**.
|
||||
|
||||
This is a Claude Code skill that transforms your workflow to use persistent markdown files for planning, progress tracking, and knowledge storage.
|
||||
|
||||
## What This Project Does
|
||||
|
||||
Instead of relying on volatile context windows, planning-with-files teaches Claude to use **files as memory**:
|
||||
|
||||
- `task_plan.md` - Your roadmap (phases, progress, decisions)
|
||||
- `findings.md` - Research and discoveries
|
||||
- `progress.md` - Session logs and test results
|
||||
|
||||
When context fills up, you don't lose work. Everything important is on disk.
|
||||
|
||||
## Why It Exists
|
||||
|
||||
After 50+ tool calls, Claude forgets your original goals. This skill solves that by:
|
||||
- Re-reading the plan before major decisions (hooks)
|
||||
- Storing findings in files instead of context
|
||||
- Logging errors to prevent repetition
|
||||
- Verifying completion before stopping
|
||||
|
||||
## Inspired By
|
||||
|
||||
Manus AI pioneered this pattern and went from launch to $100M+ revenue in 8 months. Their secret? **Context engineering through persistent files.**
|
||||
|
||||
## Community ❤️
|
||||
|
||||
This project grew from **one developer's experiment** to **9,600+ stars** and **10+ contributors** in weeks.
|
||||
|
||||
**Thank you to everyone who:**
|
||||
- ⭐ Starred the repo
|
||||
- 🔀 Forked and built on this work
|
||||
- 🐛 Reported issues and tested fixes
|
||||
- 💡 Suggested features and improvements
|
||||
- 🛠️ Contributed code, docs, and examples
|
||||
|
||||
### Special Thanks
|
||||
|
||||
- **[@kaichen](https://github.com/kaichen)** - Converted to Claude Code plugin, made it accessible to thousands
|
||||
- **[@fuahyo](https://github.com/fuahyo)** - Created beginner-friendly walkthrough and examples
|
||||
- **[@lasmarois](https://github.com/lasmarois)** - Built session recovery feature, saved countless hours
|
||||
- **[@aimasteracc](https://github.com/aimasteracc)** - Added Windows support and Kilocode integration
|
||||
- **[@wqh17101](https://github.com/wqh17101)** - Inspired Anthropic patterns integration
|
||||
|
||||
And many more! See [CONTRIBUTORS.md](https://github.com/OthmanAdi/planning-with-files/blob/main/CONTRIBUTORS.md)
|
||||
|
||||
## Growing Together
|
||||
|
||||
What started as a simple 3-file pattern is now:
|
||||
- 5 IDE integrations (Claude Code, Cursor, Kilocode, OpenCode, Codex)
|
||||
- Session recovery after `/clear`
|
||||
- Git checkpoint workflows
|
||||
- Windows PowerShell support
|
||||
- Community forks and derivatives
|
||||
|
||||
**None of this would exist without you.**
|
||||
|
||||
## Get Involved
|
||||
|
||||
- 💬 [Discussions](https://github.com/OthmanAdi/planning-with-files/discussions) - Share your experience
|
||||
- 🐛 [Issues](https://github.com/OthmanAdi/planning-with-files/issues) - Report bugs or request features
|
||||
- 🔀 [Pull Requests](https://github.com/OthmanAdi/planning-with-files/pulls) - Contribute improvements
|
||||
- ⭐ Star if this helps you work smarter
|
||||
|
||||
## Quick Links
|
||||
|
||||
- [Installation Guide](https://github.com/OthmanAdi/planning-with-files/blob/main/docs/installation.md)
|
||||
- [Quick Start](https://github.com/OthmanAdi/planning-with-files/blob/main/docs/quickstart.md)
|
||||
- [Examples](https://github.com/OthmanAdi/planning-with-files/blob/main/examples/README.md)
|
||||
- [Changelog](https://github.com/OthmanAdi/planning-with-files/blob/main/CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
**Built with appreciation for the open source community.**
|
||||
|
||||
*Ahmad Othman Ammar Adi*
|
||||
@@ -0,0 +1,52 @@
|
||||
# Codex IDE Support
|
||||
|
||||
## Overview
|
||||
|
||||
planning-with-files works with Codex as a personal skill in `~/.codex/skills/`.
|
||||
|
||||
## Installation
|
||||
|
||||
See [.codex/INSTALL.md](../.codex/INSTALL.md) for detailed installation instructions.
|
||||
|
||||
### Quick Install
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.codex/skills
|
||||
cd ~/.codex/skills
|
||||
git clone https://github.com/OthmanAdi/planning-with-files.git
|
||||
```
|
||||
|
||||
## Usage with Superpowers
|
||||
|
||||
If you have [obra/superpowers](https://github.com/obra/superpowers) installed:
|
||||
|
||||
```bash
|
||||
~/.codex/superpowers/.codex/superpowers-codex use-skill planning-with-files
|
||||
```
|
||||
|
||||
## Usage without Superpowers
|
||||
|
||||
Add to your `~/.codex/AGENTS.md`:
|
||||
|
||||
```markdown
|
||||
## Planning with Files
|
||||
|
||||
<IMPORTANT>
|
||||
For complex tasks (3+ steps, research, projects):
|
||||
1. Read skill: `cat ~/.codex/skills/planning-with-files/planning-with-files/SKILL.md`
|
||||
2. Create task_plan.md, findings.md, progress.md in your project directory
|
||||
3. Follow 3-file pattern throughout the task
|
||||
</IMPORTANT>
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
ls -la ~/.codex/skills/planning-with-files/planning-with-files/SKILL.md
|
||||
```
|
||||
|
||||
## Learn More
|
||||
|
||||
- [Installation Guide](installation.md)
|
||||
- [Quick Start](quickstart.md)
|
||||
- [Workflow Diagram](workflow.md)
|
||||
@@ -153,6 +153,14 @@ See [docs/windows.md](windows.md) for Windows-specific installation notes.
|
||||
|
||||
See [docs/cursor.md](cursor.md) for Cursor IDE installation.
|
||||
|
||||
### Codex
|
||||
|
||||
See [docs/codex.md](codex.md) for Codex IDE installation.
|
||||
|
||||
### OpenCode
|
||||
|
||||
See [docs/opencode.md](opencode.md) for OpenCode IDE installation.
|
||||
|
||||
---
|
||||
|
||||
## Need Help?
|
||||
|
||||
@@ -0,0 +1,70 @@
|
||||
# OpenCode IDE Support
|
||||
|
||||
## Overview
|
||||
|
||||
planning-with-files works with OpenCode as a personal or project skill.
|
||||
|
||||
## Installation
|
||||
|
||||
See [.opencode/INSTALL.md](../.opencode/INSTALL.md) for detailed installation instructions.
|
||||
|
||||
### Quick Install (Global)
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.config/opencode/skills
|
||||
cd ~/.config/opencode/skills
|
||||
git clone https://github.com/OthmanAdi/planning-with-files.git
|
||||
```
|
||||
|
||||
### Quick Install (Project)
|
||||
|
||||
```bash
|
||||
mkdir -p .opencode/skills
|
||||
cd .opencode/skills
|
||||
git clone https://github.com/OthmanAdi/planning-with-files.git
|
||||
```
|
||||
|
||||
## Usage with Superpowers Plugin
|
||||
|
||||
If you have [obra/superpowers](https://github.com/obra/superpowers) OpenCode plugin:
|
||||
|
||||
```
|
||||
Use the use_skill tool with skill_name: "planning-with-files"
|
||||
```
|
||||
|
||||
## Usage without Superpowers
|
||||
|
||||
Manually read the skill file when starting complex tasks:
|
||||
|
||||
```bash
|
||||
cat ~/.config/opencode/skills/planning-with-files/planning-with-files/SKILL.md
|
||||
```
|
||||
|
||||
## oh-my-opencode Compatibility
|
||||
|
||||
If using oh-my-opencode, ensure planning-with-files is not in the `disabled_skills` array:
|
||||
|
||||
**~/.config/opencode/oh-my-opencode.json:**
|
||||
```json
|
||||
{
|
||||
"disabled_skills": []
|
||||
}
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
**Global:**
|
||||
```bash
|
||||
ls -la ~/.config/opencode/skills/planning-with-files/planning-with-files/SKILL.md
|
||||
```
|
||||
|
||||
**Project:**
|
||||
```bash
|
||||
ls -la .opencode/skills/planning-with-files/planning-with-files/SKILL.md
|
||||
```
|
||||
|
||||
## Learn More
|
||||
|
||||
- [Installation Guide](installation.md)
|
||||
- [Quick Start](quickstart.md)
|
||||
- [Workflow Diagram](workflow.md)
|
||||
@@ -1,223 +0,0 @@
|
||||
---
|
||||
name: planning-with-files
|
||||
version: "2.2.2"
|
||||
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls. Now with automatic session recovery after /clear.
|
||||
user-invocable: true
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Edit
|
||||
- Bash
|
||||
- Glob
|
||||
- Grep
|
||||
- WebFetch
|
||||
- WebSearch
|
||||
hooks:
|
||||
PreToolUse:
|
||||
- matcher: "Write|Edit|Bash|Read|Glob|Grep"
|
||||
hooks:
|
||||
- type: command
|
||||
command: "cat task_plan.md 2>/dev/null | head -30 || true"
|
||||
PostToolUse:
|
||||
- matcher: "Write|Edit"
|
||||
hooks:
|
||||
- type: command
|
||||
command: "echo '[planning-with-files] File updated. If this completes a phase, update task_plan.md status.'"
|
||||
Stop:
|
||||
- hooks:
|
||||
- type: command
|
||||
command: |
|
||||
if command -v pwsh &> /dev/null && [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" || "$OS" == "Windows_NT" ]]; then
|
||||
pwsh -ExecutionPolicy Bypass -File "${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.ps1" 2>/dev/null || powershell -ExecutionPolicy Bypass -File "${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.ps1" 2>/dev/null || bash "${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.sh"
|
||||
else
|
||||
bash "${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.sh"
|
||||
fi
|
||||
---
|
||||
|
||||
# Planning with Files
|
||||
|
||||
Work like Manus: Use persistent markdown files as your "working memory on disk."
|
||||
|
||||
## FIRST: Check for Previous Session (v2.2.0)
|
||||
|
||||
**Before starting work**, check for unsynced context from a previous session:
|
||||
|
||||
```bash
|
||||
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
|
||||
```
|
||||
|
||||
If catchup report shows unsynced context:
|
||||
1. Run `git diff --stat` to see actual code changes
|
||||
2. Read current planning files
|
||||
3. Update planning files based on catchup + git diff
|
||||
4. Then proceed with task
|
||||
|
||||
## Important: Where Files Go
|
||||
|
||||
- **Templates** are in `${CLAUDE_PLUGIN_ROOT}/templates/`
|
||||
- **Your planning files** go in **your project directory**
|
||||
|
||||
| Location | What Goes There |
|
||||
|----------|-----------------|
|
||||
| Skill directory (`${CLAUDE_PLUGIN_ROOT}/`) | Templates, scripts, reference docs |
|
||||
| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
|
||||
|
||||
## Quick Start
|
||||
|
||||
Before ANY complex task:
|
||||
|
||||
1. **Create `task_plan.md`** — Use [templates/task_plan.md](templates/task_plan.md) as reference
|
||||
2. **Create `findings.md`** — Use [templates/findings.md](templates/findings.md) as reference
|
||||
3. **Create `progress.md`** — Use [templates/progress.md](templates/progress.md) as reference
|
||||
4. **Re-read plan before decisions** — Refreshes goals in attention window
|
||||
5. **Update after each phase** — Mark complete, log errors
|
||||
|
||||
> **Note:** Planning files go in your project root, not the skill installation folder.
|
||||
|
||||
## The Core Pattern
|
||||
|
||||
```
|
||||
Context Window = RAM (volatile, limited)
|
||||
Filesystem = Disk (persistent, unlimited)
|
||||
|
||||
→ Anything important gets written to disk.
|
||||
```
|
||||
|
||||
## File Purposes
|
||||
|
||||
| File | Purpose | When to Update |
|
||||
|------|---------|----------------|
|
||||
| `task_plan.md` | Phases, progress, decisions | After each phase |
|
||||
| `findings.md` | Research, discoveries | After ANY discovery |
|
||||
| `progress.md` | Session log, test results | Throughout session |
|
||||
|
||||
## Critical Rules
|
||||
|
||||
### 1. Create Plan First
|
||||
Never start a complex task without `task_plan.md`. Non-negotiable.
|
||||
|
||||
### 2. The 2-Action Rule
|
||||
> "After every 2 view/browser/search operations, IMMEDIATELY save key findings to text files."
|
||||
|
||||
This prevents visual/multimodal information from being lost.
|
||||
|
||||
### 3. Read Before Decide
|
||||
Before major decisions, read the plan file. This keeps goals in your attention window.
|
||||
|
||||
### 4. Update After Act
|
||||
After completing any phase:
|
||||
- Mark phase status: `in_progress` → `complete`
|
||||
- Log any errors encountered
|
||||
- Note files created/modified
|
||||
|
||||
### 5. Log ALL Errors
|
||||
Every error goes in the plan file. This builds knowledge and prevents repetition.
|
||||
|
||||
```markdown
|
||||
## Errors Encountered
|
||||
| Error | Attempt | Resolution |
|
||||
|-------|---------|------------|
|
||||
| FileNotFoundError | 1 | Created default config |
|
||||
| API timeout | 2 | Added retry logic |
|
||||
```
|
||||
|
||||
### 6. Never Repeat Failures
|
||||
```
|
||||
if action_failed:
|
||||
next_action != same_action
|
||||
```
|
||||
Track what you tried. Mutate the approach.
|
||||
|
||||
## The 3-Strike Error Protocol
|
||||
|
||||
```
|
||||
ATTEMPT 1: Diagnose & Fix
|
||||
→ Read error carefully
|
||||
→ Identify root cause
|
||||
→ Apply targeted fix
|
||||
|
||||
ATTEMPT 2: Alternative Approach
|
||||
→ Same error? Try different method
|
||||
→ Different tool? Different library?
|
||||
→ NEVER repeat exact same failing action
|
||||
|
||||
ATTEMPT 3: Broader Rethink
|
||||
→ Question assumptions
|
||||
→ Search for solutions
|
||||
→ Consider updating the plan
|
||||
|
||||
AFTER 3 FAILURES: Escalate to User
|
||||
→ Explain what you tried
|
||||
→ Share the specific error
|
||||
→ Ask for guidance
|
||||
```
|
||||
|
||||
## Read vs Write Decision Matrix
|
||||
|
||||
| Situation | Action | Reason |
|
||||
|-----------|--------|--------|
|
||||
| Just wrote a file | DON'T read | Content still in context |
|
||||
| Viewed image/PDF | Write findings NOW | Multimodal → text before lost |
|
||||
| Browser returned data | Write to file | Screenshots don't persist |
|
||||
| Starting new phase | Read plan/findings | Re-orient if context stale |
|
||||
| Error occurred | Read relevant file | Need current state to fix |
|
||||
| Resuming after gap | Read all planning files | Recover state |
|
||||
|
||||
## The 5-Question Reboot Test
|
||||
|
||||
If you can answer these, your context management is solid:
|
||||
|
||||
| Question | Answer Source |
|
||||
|----------|---------------|
|
||||
| Where am I? | Current phase in task_plan.md |
|
||||
| Where am I going? | Remaining phases |
|
||||
| What's the goal? | Goal statement in plan |
|
||||
| What have I learned? | findings.md |
|
||||
| What have I done? | progress.md |
|
||||
|
||||
## When to Use This Pattern
|
||||
|
||||
**Use for:**
|
||||
- Multi-step tasks (3+ steps)
|
||||
- Research tasks
|
||||
- Building/creating projects
|
||||
- Tasks spanning many tool calls
|
||||
- Anything requiring organization
|
||||
|
||||
**Skip for:**
|
||||
- Simple questions
|
||||
- Single-file edits
|
||||
- Quick lookups
|
||||
|
||||
## Templates
|
||||
|
||||
Copy these templates to start:
|
||||
|
||||
- [templates/task_plan.md](templates/task_plan.md) — Phase tracking
|
||||
- [templates/findings.md](templates/findings.md) — Research storage
|
||||
- [templates/progress.md](templates/progress.md) — Session logging
|
||||
|
||||
## Scripts
|
||||
|
||||
Helper scripts for automation:
|
||||
|
||||
- `scripts/init-session.sh` — Initialize all planning files
|
||||
- `scripts/check-complete.sh` — Verify all phases complete
|
||||
- `scripts/session-catchup.py` — Recover context from previous session (v2.2.0)
|
||||
|
||||
## Advanced Topics
|
||||
|
||||
- **Manus Principles:** See [reference.md](reference.md)
|
||||
- **Real Examples:** See [examples.md](examples.md)
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
| Don't | Do Instead |
|
||||
|-------|------------|
|
||||
| Use TodoWrite for persistence | Create task_plan.md file |
|
||||
| State goals once and forget | Re-read plan before decisions |
|
||||
| Hide errors and retry silently | Log errors to plan file |
|
||||
| Stuff everything in context | Store large content in files |
|
||||
| Start executing immediately | Create plan file FIRST |
|
||||
| Repeat failed actions | Track attempts, mutate approach |
|
||||
| Create files in skill directory | Create files in your project |
|
||||
@@ -1,202 +0,0 @@
|
||||
# Examples: Planning with Files in Action
|
||||
|
||||
## Example 1: Research Task
|
||||
|
||||
**User Request:** "Research the benefits of morning exercise and write a summary"
|
||||
|
||||
### Loop 1: Create Plan
|
||||
```bash
|
||||
Write task_plan.md
|
||||
```
|
||||
|
||||
```markdown
|
||||
# Task Plan: Morning Exercise Benefits Research
|
||||
|
||||
## Goal
|
||||
Create a research summary on the benefits of morning exercise.
|
||||
|
||||
## Phases
|
||||
- [ ] Phase 1: Create this plan ✓
|
||||
- [ ] Phase 2: Search and gather sources
|
||||
- [ ] Phase 3: Synthesize findings
|
||||
- [ ] Phase 4: Deliver summary
|
||||
|
||||
## Key Questions
|
||||
1. What are the physical health benefits?
|
||||
2. What are the mental health benefits?
|
||||
3. What scientific studies support this?
|
||||
|
||||
## Status
|
||||
**Currently in Phase 1** - Creating plan
|
||||
```
|
||||
|
||||
### Loop 2: Research
|
||||
```bash
|
||||
Read task_plan.md # Refresh goals
|
||||
WebSearch "morning exercise benefits"
|
||||
Write notes.md # Store findings
|
||||
Edit task_plan.md # Mark Phase 2 complete
|
||||
```
|
||||
|
||||
### Loop 3: Synthesize
|
||||
```bash
|
||||
Read task_plan.md # Refresh goals
|
||||
Read notes.md # Get findings
|
||||
Write morning_exercise_summary.md
|
||||
Edit task_plan.md # Mark Phase 3 complete
|
||||
```
|
||||
|
||||
### Loop 4: Deliver
|
||||
```bash
|
||||
Read task_plan.md # Verify complete
|
||||
Deliver morning_exercise_summary.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example 2: Bug Fix Task
|
||||
|
||||
**User Request:** "Fix the login bug in the authentication module"
|
||||
|
||||
### task_plan.md
|
||||
```markdown
|
||||
# Task Plan: Fix Login Bug
|
||||
|
||||
## Goal
|
||||
Identify and fix the bug preventing successful login.
|
||||
|
||||
## Phases
|
||||
- [x] Phase 1: Understand the bug report ✓
|
||||
- [x] Phase 2: Locate relevant code ✓
|
||||
- [ ] Phase 3: Identify root cause (CURRENT)
|
||||
- [ ] Phase 4: Implement fix
|
||||
- [ ] Phase 5: Test and verify
|
||||
|
||||
## Key Questions
|
||||
1. What error message appears?
|
||||
2. Which file handles authentication?
|
||||
3. What changed recently?
|
||||
|
||||
## Decisions Made
|
||||
- Auth handler is in src/auth/login.ts
|
||||
- Error occurs in validateToken() function
|
||||
|
||||
## Errors Encountered
|
||||
- [Initial] TypeError: Cannot read property 'token' of undefined
|
||||
→ Root cause: user object not awaited properly
|
||||
|
||||
## Status
|
||||
**Currently in Phase 3** - Found root cause, preparing fix
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example 3: Feature Development
|
||||
|
||||
**User Request:** "Add a dark mode toggle to the settings page"
|
||||
|
||||
### The 3-File Pattern in Action
|
||||
|
||||
**task_plan.md:**
|
||||
```markdown
|
||||
# Task Plan: Dark Mode Toggle
|
||||
|
||||
## Goal
|
||||
Add functional dark mode toggle to settings.
|
||||
|
||||
## Phases
|
||||
- [x] Phase 1: Research existing theme system ✓
|
||||
- [x] Phase 2: Design implementation approach ✓
|
||||
- [ ] Phase 3: Implement toggle component (CURRENT)
|
||||
- [ ] Phase 4: Add theme switching logic
|
||||
- [ ] Phase 5: Test and polish
|
||||
|
||||
## Decisions Made
|
||||
- Using CSS custom properties for theme
|
||||
- Storing preference in localStorage
|
||||
- Toggle component in SettingsPage.tsx
|
||||
|
||||
## Status
|
||||
**Currently in Phase 3** - Building toggle component
|
||||
```
|
||||
|
||||
**notes.md:**
|
||||
```markdown
|
||||
# Notes: Dark Mode Implementation
|
||||
|
||||
## Existing Theme System
|
||||
- Located in: src/styles/theme.ts
|
||||
- Uses: CSS custom properties
|
||||
- Current themes: light only
|
||||
|
||||
## Files to Modify
|
||||
1. src/styles/theme.ts - Add dark theme colors
|
||||
2. src/components/SettingsPage.tsx - Add toggle
|
||||
3. src/hooks/useTheme.ts - Create new hook
|
||||
4. src/App.tsx - Wrap with ThemeProvider
|
||||
|
||||
## Color Decisions
|
||||
- Dark background: #1a1a2e
|
||||
- Dark surface: #16213e
|
||||
- Dark text: #eaeaea
|
||||
```
|
||||
|
||||
**dark_mode_implementation.md:** (deliverable)
|
||||
```markdown
|
||||
# Dark Mode Implementation
|
||||
|
||||
## Changes Made
|
||||
|
||||
### 1. Added dark theme colors
|
||||
File: src/styles/theme.ts
|
||||
...
|
||||
|
||||
### 2. Created useTheme hook
|
||||
File: src/hooks/useTheme.ts
|
||||
...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example 4: Error Recovery Pattern
|
||||
|
||||
When something fails, DON'T hide it:
|
||||
|
||||
### Before (Wrong)
|
||||
```
|
||||
Action: Read config.json
|
||||
Error: File not found
|
||||
Action: Read config.json # Silent retry
|
||||
Action: Read config.json # Another retry
|
||||
```
|
||||
|
||||
### After (Correct)
|
||||
```
|
||||
Action: Read config.json
|
||||
Error: File not found
|
||||
|
||||
# Update task_plan.md:
|
||||
## Errors Encountered
|
||||
- config.json not found → Will create default config
|
||||
|
||||
Action: Write config.json (default config)
|
||||
Action: Read config.json
|
||||
Success!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The Read-Before-Decide Pattern
|
||||
|
||||
**Always read your plan before major decisions:**
|
||||
|
||||
```
|
||||
[Many tool calls have happened...]
|
||||
[Context is getting long...]
|
||||
[Original goal might be forgotten...]
|
||||
|
||||
→ Read task_plan.md # This brings goals back into attention!
|
||||
→ Now make the decision # Goals are fresh in context
|
||||
```
|
||||
|
||||
This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a "goal refresh" mechanism.
|
||||
@@ -1,218 +0,0 @@
|
||||
# Reference: Manus Context Engineering Principles
|
||||
|
||||
This skill is based on context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
|
||||
|
||||
## The 6 Manus Principles
|
||||
|
||||
### Principle 1: Design Around KV-Cache
|
||||
|
||||
> "KV-cache hit rate is THE single most important metric for production AI agents."
|
||||
|
||||
**Statistics:**
|
||||
- ~100:1 input-to-output token ratio
|
||||
- Cached tokens: $0.30/MTok vs Uncached: $3/MTok
|
||||
- 10x cost difference!
|
||||
|
||||
**Implementation:**
|
||||
- Keep prompt prefixes STABLE (single-token change invalidates cache)
|
||||
- NO timestamps in system prompts
|
||||
- Make context APPEND-ONLY with deterministic serialization
|
||||
|
||||
### Principle 2: Mask, Don't Remove
|
||||
|
||||
Don't dynamically remove tools (breaks KV-cache). Use logit masking instead.
|
||||
|
||||
**Best Practice:** Use consistent action prefixes (e.g., `browser_`, `shell_`, `file_`) for easier masking.
|
||||
|
||||
### Principle 3: Filesystem as External Memory
|
||||
|
||||
> "Markdown is my 'working memory' on disk."
|
||||
|
||||
**The Formula:**
|
||||
```
|
||||
Context Window = RAM (volatile, limited)
|
||||
Filesystem = Disk (persistent, unlimited)
|
||||
```
|
||||
|
||||
**Compression Must Be Restorable:**
|
||||
- Keep URLs even if web content is dropped
|
||||
- Keep file paths when dropping document contents
|
||||
- Never lose the pointer to full data
|
||||
|
||||
### Principle 4: Manipulate Attention Through Recitation
|
||||
|
||||
> "Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."
|
||||
|
||||
**Problem:** After ~50 tool calls, models forget original goals ("lost in the middle" effect).
|
||||
|
||||
**Solution:** Re-read `task_plan.md` before each decision. Goals appear in the attention window.
|
||||
|
||||
```
|
||||
Start of context: [Original goal - far away, forgotten]
|
||||
...many tool calls...
|
||||
End of context: [Recently read task_plan.md - gets ATTENTION!]
|
||||
```
|
||||
|
||||
### Principle 5: Keep the Wrong Stuff In
|
||||
|
||||
> "Leave the wrong turns in the context."
|
||||
|
||||
**Why:**
|
||||
- Failed actions with stack traces let model implicitly update beliefs
|
||||
- Reduces mistake repetition
|
||||
- Error recovery is "one of the clearest signals of TRUE agentic behavior"
|
||||
|
||||
### Principle 6: Don't Get Few-Shotted
|
||||
|
||||
> "Uniformity breeds fragility."
|
||||
|
||||
**Problem:** Repetitive action-observation pairs cause drift and hallucination.
|
||||
|
||||
**Solution:** Introduce controlled variation:
|
||||
- Vary phrasings slightly
|
||||
- Don't copy-paste patterns blindly
|
||||
- Recalibrate on repetitive tasks
|
||||
|
||||
---
|
||||
|
||||
## The 3 Context Engineering Strategies
|
||||
|
||||
Based on Lance Martin's analysis of Manus architecture.
|
||||
|
||||
### Strategy 1: Context Reduction
|
||||
|
||||
**Compaction:**
|
||||
```
|
||||
Tool calls have TWO representations:
|
||||
├── FULL: Raw tool content (stored in filesystem)
|
||||
└── COMPACT: Reference/file path only
|
||||
|
||||
RULES:
|
||||
- Apply compaction to STALE (older) tool results
|
||||
- Keep RECENT results FULL (to guide next decision)
|
||||
```
|
||||
|
||||
**Summarization:**
|
||||
- Applied when compaction reaches diminishing returns
|
||||
- Generated using full tool results
|
||||
- Creates standardized summary objects
|
||||
|
||||
### Strategy 2: Context Isolation (Multi-Agent)
|
||||
|
||||
**Architecture:**
|
||||
```
|
||||
┌─────────────────────────────────┐
|
||||
│ PLANNER AGENT │
|
||||
│ └─ Assigns tasks to sub-agents │
|
||||
├─────────────────────────────────┤
|
||||
│ KNOWLEDGE MANAGER │
|
||||
│ └─ Reviews conversations │
|
||||
│ └─ Determines filesystem store │
|
||||
├─────────────────────────────────┤
|
||||
│ EXECUTOR SUB-AGENTS │
|
||||
│ └─ Perform assigned tasks │
|
||||
│ └─ Have own context windows │
|
||||
└─────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Key Insight:** Manus originally used `todo.md` for task planning but found ~33% of actions were spent updating it. Shifted to dedicated planner agent calling executor sub-agents.
|
||||
|
||||
### Strategy 3: Context Offloading
|
||||
|
||||
**Tool Design:**
|
||||
- Use <20 atomic functions total
|
||||
- Store full results in filesystem, not context
|
||||
- Use `glob` and `grep` for searching
|
||||
- Progressive disclosure: load information only as needed
|
||||
|
||||
---
|
||||
|
||||
## The Agent Loop
|
||||
|
||||
Manus operates in a continuous 7-step loop:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 1. ANALYZE CONTEXT │
|
||||
│ - Understand user intent │
|
||||
│ - Assess current state │
|
||||
│ - Review recent observations │
|
||||
├─────────────────────────────────────────┤
|
||||
│ 2. THINK │
|
||||
│ - Should I update the plan? │
|
||||
│ - What's the next logical action? │
|
||||
│ - Are there blockers? │
|
||||
├─────────────────────────────────────────┤
|
||||
│ 3. SELECT TOOL │
|
||||
│ - Choose ONE tool │
|
||||
│ - Ensure parameters available │
|
||||
├─────────────────────────────────────────┤
|
||||
│ 4. EXECUTE ACTION │
|
||||
│ - Tool runs in sandbox │
|
||||
├─────────────────────────────────────────┤
|
||||
│ 5. RECEIVE OBSERVATION │
|
||||
│ - Result appended to context │
|
||||
├─────────────────────────────────────────┤
|
||||
│ 6. ITERATE │
|
||||
│ - Return to step 1 │
|
||||
│ - Continue until complete │
|
||||
├─────────────────────────────────────────┤
|
||||
│ 7. DELIVER OUTCOME │
|
||||
│ - Send results to user │
|
||||
│ - Attach all relevant files │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Types Manus Creates
|
||||
|
||||
| File | Purpose | When Created | When Updated |
|
||||
|------|---------|--------------|--------------|
|
||||
| `task_plan.md` | Phase tracking, progress | Task start | After completing phases |
|
||||
| `findings.md` | Discoveries, decisions | After ANY discovery | After viewing images/PDFs |
|
||||
| `progress.md` | Session log, what's done | At breakpoints | Throughout session |
|
||||
| Code files | Implementation | Before execution | After errors |
|
||||
|
||||
---
|
||||
|
||||
## Critical Constraints
|
||||
|
||||
- **Single-Action Execution:** ONE tool call per turn. No parallel execution.
|
||||
- **Plan is Required:** Agent must ALWAYS know: goal, current phase, remaining phases
|
||||
- **Files are Memory:** Context = volatile. Filesystem = persistent.
|
||||
- **Never Repeat Failures:** If action failed, next action MUST be different
|
||||
- **Communication is a Tool:** Message types: `info` (progress), `ask` (blocking), `result` (terminal)
|
||||
|
||||
---
|
||||
|
||||
## Manus Statistics
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Average tool calls per task | ~50 |
|
||||
| Input-to-output token ratio | 100:1 |
|
||||
| Acquisition price | $2 billion |
|
||||
| Time to $100M revenue | 8 months |
|
||||
| Framework refactors since launch | 5 times |
|
||||
|
||||
---
|
||||
|
||||
## Key Quotes
|
||||
|
||||
> "Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."
|
||||
|
||||
> "if action_failed: next_action != same_action. Track what you tried. Mutate the approach."
|
||||
|
||||
> "Error recovery is one of the clearest signals of TRUE agentic behavior."
|
||||
|
||||
> "KV-cache hit rate is the single most important metric for a production-stage AI agent."
|
||||
|
||||
> "Leave the wrong turns in the context."
|
||||
|
||||
---
|
||||
|
||||
## Source
|
||||
|
||||
Based on Manus's official context engineering documentation:
|
||||
https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
|
||||
@@ -1,42 +0,0 @@
|
||||
# Check if all phases in task_plan.md are complete
|
||||
# Exit 0 if complete, exit 1 if incomplete
|
||||
# Used by Stop hook to verify task completion
|
||||
|
||||
param(
|
||||
[string]$PlanFile = "task_plan.md"
|
||||
)
|
||||
|
||||
if (-not (Test-Path $PlanFile)) {
|
||||
Write-Host "ERROR: $PlanFile not found"
|
||||
Write-Host "Cannot verify completion without a task plan."
|
||||
exit 1
|
||||
}
|
||||
|
||||
Write-Host "=== Task Completion Check ==="
|
||||
Write-Host ""
|
||||
|
||||
# Read file content
|
||||
$content = Get-Content $PlanFile -Raw
|
||||
|
||||
# Count phases by status
|
||||
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
|
||||
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
|
||||
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
|
||||
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
|
||||
|
||||
Write-Host "Total phases: $TOTAL"
|
||||
Write-Host "Complete: $COMPLETE"
|
||||
Write-Host "In progress: $IN_PROGRESS"
|
||||
Write-Host "Pending: $PENDING"
|
||||
Write-Host ""
|
||||
|
||||
# Check completion
|
||||
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
|
||||
Write-Host "ALL PHASES COMPLETE"
|
||||
exit 0
|
||||
} else {
|
||||
Write-Host "TASK NOT COMPLETE"
|
||||
Write-Host ""
|
||||
Write-Host "Do not stop until all phases are complete."
|
||||
exit 1
|
||||
}
|
||||
@@ -1,44 +0,0 @@
|
||||
#!/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
|
||||
@@ -1,120 +0,0 @@
|
||||
# Initialize planning files for a new session
|
||||
# Usage: .\init-session.ps1 [project-name]
|
||||
|
||||
param(
|
||||
[string]$ProjectName = "project"
|
||||
)
|
||||
|
||||
$DATE = Get-Date -Format "yyyy-MM-dd"
|
||||
|
||||
Write-Host "Initializing planning files for: $ProjectName"
|
||||
|
||||
# Create task_plan.md if it doesn't exist
|
||||
if (-not (Test-Path "task_plan.md")) {
|
||||
@"
|
||||
# Task Plan: [Brief Description]
|
||||
|
||||
## Goal
|
||||
[One sentence describing the end state]
|
||||
|
||||
## Current Phase
|
||||
Phase 1
|
||||
|
||||
## Phases
|
||||
|
||||
### Phase 1: Requirements & Discovery
|
||||
- [ ] Understand user intent
|
||||
- [ ] Identify constraints
|
||||
- [ ] Document in findings.md
|
||||
- **Status:** in_progress
|
||||
|
||||
### Phase 2: Planning & Structure
|
||||
- [ ] Define approach
|
||||
- [ ] Create project structure
|
||||
- **Status:** pending
|
||||
|
||||
### Phase 3: Implementation
|
||||
- [ ] Execute the plan
|
||||
- [ ] Write to files before executing
|
||||
- **Status:** pending
|
||||
|
||||
### Phase 4: Testing & Verification
|
||||
- [ ] Verify requirements met
|
||||
- [ ] Document test results
|
||||
- **Status:** pending
|
||||
|
||||
### Phase 5: Delivery
|
||||
- [ ] Review outputs
|
||||
- [ ] Deliver to user
|
||||
- **Status:** pending
|
||||
|
||||
## Decisions Made
|
||||
| Decision | Rationale |
|
||||
|----------|-----------|
|
||||
|
||||
## Errors Encountered
|
||||
| Error | Resolution |
|
||||
|-------|------------|
|
||||
"@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
|
||||
Write-Host "Created task_plan.md"
|
||||
} else {
|
||||
Write-Host "task_plan.md already exists, skipping"
|
||||
}
|
||||
|
||||
# Create findings.md if it doesn't exist
|
||||
if (-not (Test-Path "findings.md")) {
|
||||
@"
|
||||
# Findings & Decisions
|
||||
|
||||
## Requirements
|
||||
-
|
||||
|
||||
## Research Findings
|
||||
-
|
||||
|
||||
## Technical Decisions
|
||||
| Decision | Rationale |
|
||||
|----------|-----------|
|
||||
|
||||
## Issues Encountered
|
||||
| Issue | Resolution |
|
||||
|-------|------------|
|
||||
|
||||
## Resources
|
||||
-
|
||||
"@ | Out-File -FilePath "findings.md" -Encoding UTF8
|
||||
Write-Host "Created findings.md"
|
||||
} else {
|
||||
Write-Host "findings.md already exists, skipping"
|
||||
}
|
||||
|
||||
# Create progress.md if it doesn't exist
|
||||
if (-not (Test-Path "progress.md")) {
|
||||
@"
|
||||
# Progress Log
|
||||
|
||||
## Session: $DATE
|
||||
|
||||
### Current Status
|
||||
- **Phase:** 1 - Requirements & Discovery
|
||||
- **Started:** $DATE
|
||||
|
||||
### Actions Taken
|
||||
-
|
||||
|
||||
### Test Results
|
||||
| Test | Expected | Actual | Status |
|
||||
|------|----------|--------|--------|
|
||||
|
||||
### Errors
|
||||
| Error | Resolution |
|
||||
|-------|------------|
|
||||
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
|
||||
Write-Host "Created progress.md"
|
||||
} else {
|
||||
Write-Host "progress.md already exists, skipping"
|
||||
}
|
||||
|
||||
Write-Host ""
|
||||
Write-Host "Planning files initialized!"
|
||||
Write-Host "Files: task_plan.md, findings.md, progress.md"
|
||||
@@ -1,120 +0,0 @@
|
||||
#!/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"
|
||||
@@ -1,208 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Session Catchup Script for planning-with-files
|
||||
|
||||
Analyzes the previous session to find unsynced context after the last
|
||||
planning file update. Designed to run on SessionStart.
|
||||
|
||||
Usage: python3 session-catchup.py [project-path]
|
||||
"""
|
||||
|
||||
import json
|
||||
import sys
|
||||
import os
|
||||
from pathlib import Path
|
||||
from typing import List, Dict, Optional, Tuple
|
||||
from datetime import datetime
|
||||
|
||||
PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
|
||||
|
||||
|
||||
def get_project_dir(project_path: str) -> Path:
|
||||
"""Convert project path to Claude's storage path format."""
|
||||
sanitized = project_path.replace('/', '-')
|
||||
if not sanitized.startswith('-'):
|
||||
sanitized = '-' + sanitized
|
||||
sanitized = sanitized.replace('_', '-')
|
||||
return Path.home() / '.claude' / 'projects' / sanitized
|
||||
|
||||
|
||||
def get_sessions_sorted(project_dir: Path) -> List[Path]:
|
||||
"""Get all session files sorted by modification time (newest first)."""
|
||||
sessions = list(project_dir.glob('*.jsonl'))
|
||||
main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
|
||||
return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
|
||||
|
||||
|
||||
def parse_session_messages(session_file: Path) -> List[Dict]:
|
||||
"""Parse all messages from a session file, preserving order."""
|
||||
messages = []
|
||||
with open(session_file, 'r') as f:
|
||||
for line_num, line in enumerate(f):
|
||||
try:
|
||||
data = json.loads(line)
|
||||
data['_line_num'] = line_num
|
||||
messages.append(data)
|
||||
except json.JSONDecodeError:
|
||||
pass
|
||||
return messages
|
||||
|
||||
|
||||
def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
|
||||
"""
|
||||
Find the last time a planning file was written/edited.
|
||||
Returns (line_number, filename) or (-1, None) if not found.
|
||||
"""
|
||||
last_update_line = -1
|
||||
last_update_file = None
|
||||
|
||||
for msg in messages:
|
||||
msg_type = msg.get('type')
|
||||
|
||||
if msg_type == 'assistant':
|
||||
content = msg.get('message', {}).get('content', [])
|
||||
if isinstance(content, list):
|
||||
for item in content:
|
||||
if item.get('type') == 'tool_use':
|
||||
tool_name = item.get('name', '')
|
||||
tool_input = item.get('input', {})
|
||||
|
||||
if tool_name in ('Write', 'Edit'):
|
||||
file_path = tool_input.get('file_path', '')
|
||||
for pf in PLANNING_FILES:
|
||||
if file_path.endswith(pf):
|
||||
last_update_line = msg['_line_num']
|
||||
last_update_file = pf
|
||||
|
||||
return last_update_line, last_update_file
|
||||
|
||||
|
||||
def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
|
||||
"""Extract conversation messages after a certain line number."""
|
||||
result = []
|
||||
for msg in messages:
|
||||
if msg['_line_num'] <= after_line:
|
||||
continue
|
||||
|
||||
msg_type = msg.get('type')
|
||||
is_meta = msg.get('isMeta', False)
|
||||
|
||||
if msg_type == 'user' and not is_meta:
|
||||
content = msg.get('message', {}).get('content', '')
|
||||
if isinstance(content, list):
|
||||
for item in content:
|
||||
if isinstance(item, dict) and item.get('type') == 'text':
|
||||
content = item.get('text', '')
|
||||
break
|
||||
else:
|
||||
content = ''
|
||||
|
||||
if content and isinstance(content, str):
|
||||
if content.startswith(('<local-command', '<command-', '<task-notification')):
|
||||
continue
|
||||
if len(content) > 20:
|
||||
result.append({'role': 'user', 'content': content, 'line': msg['_line_num']})
|
||||
|
||||
elif msg_type == 'assistant':
|
||||
msg_content = msg.get('message', {}).get('content', '')
|
||||
text_content = ''
|
||||
tool_uses = []
|
||||
|
||||
if isinstance(msg_content, str):
|
||||
text_content = msg_content
|
||||
elif isinstance(msg_content, list):
|
||||
for item in msg_content:
|
||||
if item.get('type') == 'text':
|
||||
text_content = item.get('text', '')
|
||||
elif item.get('type') == 'tool_use':
|
||||
tool_name = item.get('name', '')
|
||||
tool_input = item.get('input', {})
|
||||
if tool_name == 'Edit':
|
||||
tool_uses.append(f"Edit: {tool_input.get('file_path', 'unknown')}")
|
||||
elif tool_name == 'Write':
|
||||
tool_uses.append(f"Write: {tool_input.get('file_path', 'unknown')}")
|
||||
elif tool_name == 'Bash':
|
||||
cmd = tool_input.get('command', '')[:80]
|
||||
tool_uses.append(f"Bash: {cmd}")
|
||||
else:
|
||||
tool_uses.append(f"{tool_name}")
|
||||
|
||||
if text_content or tool_uses:
|
||||
result.append({
|
||||
'role': 'assistant',
|
||||
'content': text_content[:600] if text_content else '',
|
||||
'tools': tool_uses,
|
||||
'line': msg['_line_num']
|
||||
})
|
||||
|
||||
return result
|
||||
|
||||
|
||||
def main():
|
||||
project_path = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()
|
||||
project_dir = get_project_dir(project_path)
|
||||
|
||||
# Check if planning files exist (indicates active task)
|
||||
has_planning_files = any(
|
||||
Path(project_path, f).exists() for f in PLANNING_FILES
|
||||
)
|
||||
|
||||
if not project_dir.exists():
|
||||
# No previous sessions, nothing to catch up on
|
||||
return
|
||||
|
||||
sessions = get_sessions_sorted(project_dir)
|
||||
if len(sessions) < 1:
|
||||
return
|
||||
|
||||
# Find a substantial previous session
|
||||
target_session = None
|
||||
for session in sessions:
|
||||
if session.stat().st_size > 5000:
|
||||
target_session = session
|
||||
break
|
||||
|
||||
if not target_session:
|
||||
return
|
||||
|
||||
messages = parse_session_messages(target_session)
|
||||
last_update_line, last_update_file = find_last_planning_update(messages)
|
||||
|
||||
# Only output if there's unsynced content
|
||||
if last_update_line < 0:
|
||||
messages_after = extract_messages_after(messages, len(messages) - 30)
|
||||
else:
|
||||
messages_after = extract_messages_after(messages, last_update_line)
|
||||
|
||||
if not messages_after:
|
||||
return
|
||||
|
||||
# Output catchup report
|
||||
print("\n[planning-with-files] SESSION CATCHUP DETECTED")
|
||||
print(f"Previous session: {target_session.stem}")
|
||||
|
||||
if last_update_line >= 0:
|
||||
print(f"Last planning update: {last_update_file} at message #{last_update_line}")
|
||||
print(f"Unsynced messages: {len(messages_after)}")
|
||||
else:
|
||||
print("No planning file updates found in previous session")
|
||||
|
||||
print("\n--- UNSYNCED CONTEXT ---")
|
||||
for msg in messages_after[-15:]: # Last 15 messages
|
||||
if msg['role'] == 'user':
|
||||
print(f"USER: {msg['content'][:300]}")
|
||||
else:
|
||||
if msg.get('content'):
|
||||
print(f"CLAUDE: {msg['content'][:300]}")
|
||||
if msg.get('tools'):
|
||||
print(f" Tools: {', '.join(msg['tools'][:4])}")
|
||||
|
||||
print("\n--- RECOMMENDED ---")
|
||||
print("1. Run: git diff --stat")
|
||||
print("2. Read: task_plan.md, progress.md, findings.md")
|
||||
print("3. Update planning files based on above context")
|
||||
print("4. Continue with task")
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
@@ -1,95 +0,0 @@
|
||||
# Findings & Decisions
|
||||
<!--
|
||||
WHAT: Your knowledge base for the task. Stores everything you discover and decide.
|
||||
WHY: Context windows are limited. This file is your "external memory" - persistent and unlimited.
|
||||
WHEN: Update after ANY discovery, especially after 2 view/browser/search operations (2-Action Rule).
|
||||
-->
|
||||
|
||||
## Requirements
|
||||
<!--
|
||||
WHAT: What the user asked for, broken down into specific requirements.
|
||||
WHY: Keeps requirements visible so you don't forget what you're building.
|
||||
WHEN: Fill this in during Phase 1 (Requirements & Discovery).
|
||||
EXAMPLE:
|
||||
- Command-line interface
|
||||
- Add tasks
|
||||
- List all tasks
|
||||
- Delete tasks
|
||||
- Python implementation
|
||||
-->
|
||||
<!-- Captured from user request -->
|
||||
-
|
||||
|
||||
## Research Findings
|
||||
<!--
|
||||
WHAT: Key discoveries from web searches, documentation reading, or exploration.
|
||||
WHY: Multimodal content (images, browser results) doesn't persist. Write it down immediately.
|
||||
WHEN: After EVERY 2 view/browser/search operations, update this section (2-Action Rule).
|
||||
EXAMPLE:
|
||||
- Python's argparse module supports subcommands for clean CLI design
|
||||
- JSON module handles file persistence easily
|
||||
- Standard pattern: python script.py <command> [args]
|
||||
-->
|
||||
<!-- Key discoveries during exploration -->
|
||||
-
|
||||
|
||||
## Technical Decisions
|
||||
<!--
|
||||
WHAT: Architecture and implementation choices you've made, with reasoning.
|
||||
WHY: You'll forget why you chose a technology or approach. This table preserves that knowledge.
|
||||
WHEN: Update whenever you make a significant technical choice.
|
||||
EXAMPLE:
|
||||
| Use JSON for storage | Simple, human-readable, built-in Python support |
|
||||
| argparse with subcommands | Clean CLI: python todo.py add "task" |
|
||||
-->
|
||||
<!-- Decisions made with rationale -->
|
||||
| Decision | Rationale |
|
||||
|----------|-----------|
|
||||
| | |
|
||||
|
||||
## Issues Encountered
|
||||
<!--
|
||||
WHAT: Problems you ran into and how you solved them.
|
||||
WHY: Similar to errors in task_plan.md, but focused on broader issues (not just code errors).
|
||||
WHEN: Document when you encounter blockers or unexpected challenges.
|
||||
EXAMPLE:
|
||||
| Empty file causes JSONDecodeError | Added explicit empty file check before json.load() |
|
||||
-->
|
||||
<!-- Errors and how they were resolved -->
|
||||
| Issue | Resolution |
|
||||
|-------|------------|
|
||||
| | |
|
||||
|
||||
## Resources
|
||||
<!--
|
||||
WHAT: URLs, file paths, API references, documentation links you've found useful.
|
||||
WHY: Easy reference for later. Don't lose important links in context.
|
||||
WHEN: Add as you discover useful resources.
|
||||
EXAMPLE:
|
||||
- Python argparse docs: https://docs.python.org/3/library/argparse.html
|
||||
- Project structure: src/main.py, src/utils.py
|
||||
-->
|
||||
<!-- URLs, file paths, API references -->
|
||||
-
|
||||
|
||||
## Visual/Browser Findings
|
||||
<!--
|
||||
WHAT: Information you learned from viewing images, PDFs, or browser results.
|
||||
WHY: CRITICAL - Visual/multimodal content doesn't persist in context. Must be captured as text.
|
||||
WHEN: IMMEDIATELY after viewing images or browser results. Don't wait!
|
||||
EXAMPLE:
|
||||
- Screenshot shows login form has email and password fields
|
||||
- Browser shows API returns JSON with "status" and "data" keys
|
||||
-->
|
||||
<!-- CRITICAL: Update after every 2 view/browser operations -->
|
||||
<!-- Multimodal content must be captured as text immediately -->
|
||||
-
|
||||
|
||||
---
|
||||
<!--
|
||||
REMINDER: The 2-Action Rule
|
||||
After every 2 view/browser/search operations, you MUST update this file.
|
||||
This prevents visual information from being lost when context resets.
|
||||
-->
|
||||
*Update this file after every 2 view/browser/search operations*
|
||||
*This prevents visual information from being lost*
|
||||
@@ -1,114 +0,0 @@
|
||||
# Progress Log
|
||||
<!--
|
||||
WHAT: Your session log - a chronological record of what you did, when, and what happened.
|
||||
WHY: Answers "What have I done?" in the 5-Question Reboot Test. Helps you resume after breaks.
|
||||
WHEN: Update after completing each phase or encountering errors. More detailed than task_plan.md.
|
||||
-->
|
||||
|
||||
## Session: [DATE]
|
||||
<!--
|
||||
WHAT: The date of this work session.
|
||||
WHY: Helps track when work happened, useful for resuming after time gaps.
|
||||
EXAMPLE: 2026-01-15
|
||||
-->
|
||||
|
||||
### Phase 1: [Title]
|
||||
<!--
|
||||
WHAT: Detailed log of actions taken during this phase.
|
||||
WHY: Provides context for what was done, making it easier to resume or debug.
|
||||
WHEN: Update as you work through the phase, or at least when you complete it.
|
||||
-->
|
||||
- **Status:** in_progress
|
||||
- **Started:** [timestamp]
|
||||
<!--
|
||||
STATUS: Same as task_plan.md (pending, in_progress, complete)
|
||||
TIMESTAMP: When you started this phase (e.g., "2026-01-15 10:00")
|
||||
-->
|
||||
- Actions taken:
|
||||
<!--
|
||||
WHAT: List of specific actions you performed.
|
||||
EXAMPLE:
|
||||
- Created todo.py with basic structure
|
||||
- Implemented add functionality
|
||||
- Fixed FileNotFoundError
|
||||
-->
|
||||
-
|
||||
- Files created/modified:
|
||||
<!--
|
||||
WHAT: Which files you created or changed.
|
||||
WHY: Quick reference for what was touched. Helps with debugging and review.
|
||||
EXAMPLE:
|
||||
- todo.py (created)
|
||||
- todos.json (created by app)
|
||||
- task_plan.md (updated)
|
||||
-->
|
||||
-
|
||||
|
||||
### Phase 2: [Title]
|
||||
<!--
|
||||
WHAT: Same structure as Phase 1, for the next phase.
|
||||
WHY: Keep a separate log entry for each phase to track progress clearly.
|
||||
-->
|
||||
- **Status:** pending
|
||||
- Actions taken:
|
||||
-
|
||||
- Files created/modified:
|
||||
-
|
||||
|
||||
## Test Results
|
||||
<!--
|
||||
WHAT: Table of tests you ran, what you expected, what actually happened.
|
||||
WHY: Documents verification of functionality. Helps catch regressions.
|
||||
WHEN: Update as you test features, especially during Phase 4 (Testing & Verification).
|
||||
EXAMPLE:
|
||||
| Add task | python todo.py add "Buy milk" | Task added | Task added successfully | ✓ |
|
||||
| List tasks | python todo.py list | Shows all tasks | Shows all tasks | ✓ |
|
||||
-->
|
||||
| Test | Input | Expected | Actual | Status |
|
||||
|------|-------|----------|--------|--------|
|
||||
| | | | | |
|
||||
|
||||
## Error Log
|
||||
<!--
|
||||
WHAT: Detailed log of every error encountered, with timestamps and resolution attempts.
|
||||
WHY: More detailed than task_plan.md's error table. Helps you learn from mistakes.
|
||||
WHEN: Add immediately when an error occurs, even if you fix it quickly.
|
||||
EXAMPLE:
|
||||
| 2026-01-15 10:35 | FileNotFoundError | 1 | Added file existence check |
|
||||
| 2026-01-15 10:37 | JSONDecodeError | 2 | Added empty file handling |
|
||||
-->
|
||||
<!-- Keep ALL errors - they help avoid repetition -->
|
||||
| Timestamp | Error | Attempt | Resolution |
|
||||
|-----------|-------|---------|------------|
|
||||
| | | 1 | |
|
||||
|
||||
## 5-Question Reboot Check
|
||||
<!--
|
||||
WHAT: Five questions that verify your context is solid. If you can answer these, you're on track.
|
||||
WHY: This is the "reboot test" - if you can answer all 5, you can resume work effectively.
|
||||
WHEN: Update periodically, especially when resuming after a break or context reset.
|
||||
|
||||
THE 5 QUESTIONS:
|
||||
1. Where am I? → Current phase in task_plan.md
|
||||
2. Where am I going? → Remaining phases
|
||||
3. What's the goal? → Goal statement in task_plan.md
|
||||
4. What have I learned? → See findings.md
|
||||
5. What have I done? → See progress.md (this file)
|
||||
-->
|
||||
<!-- If you can answer these, context is solid -->
|
||||
| Question | Answer |
|
||||
|----------|--------|
|
||||
| Where am I? | Phase X |
|
||||
| Where am I going? | Remaining phases |
|
||||
| What's the goal? | [goal statement] |
|
||||
| What have I learned? | See findings.md |
|
||||
| What have I done? | See above |
|
||||
|
||||
---
|
||||
<!--
|
||||
REMINDER:
|
||||
- Update after completing each phase or encountering errors
|
||||
- Be detailed - this is your "what happened" log
|
||||
- Include timestamps for errors to track when issues occurred
|
||||
-->
|
||||
*Update after completing each phase or encountering errors*
|
||||
@@ -1,132 +0,0 @@
|
||||
# Task Plan: [Brief Description]
|
||||
<!--
|
||||
WHAT: This is your roadmap for the entire task. Think of it as your "working memory on disk."
|
||||
WHY: After 50+ tool calls, your original goals can get forgotten. This file keeps them fresh.
|
||||
WHEN: Create this FIRST, before starting any work. Update after each phase completes.
|
||||
-->
|
||||
|
||||
## Goal
|
||||
<!--
|
||||
WHAT: One clear sentence describing what you're trying to achieve.
|
||||
WHY: This is your north star. Re-reading this keeps you focused on the end state.
|
||||
EXAMPLE: "Create a Python CLI todo app with add, list, and delete functionality."
|
||||
-->
|
||||
[One sentence describing the end state]
|
||||
|
||||
## Current Phase
|
||||
<!--
|
||||
WHAT: Which phase you're currently working on (e.g., "Phase 1", "Phase 3").
|
||||
WHY: Quick reference for where you are in the task. Update this as you progress.
|
||||
-->
|
||||
Phase 1
|
||||
|
||||
## Phases
|
||||
<!--
|
||||
WHAT: Break your task into 3-7 logical phases. Each phase should be completable.
|
||||
WHY: Breaking work into phases prevents overwhelm and makes progress visible.
|
||||
WHEN: Update status after completing each phase: pending → in_progress → complete
|
||||
-->
|
||||
|
||||
### Phase 1: Requirements & Discovery
|
||||
<!--
|
||||
WHAT: Understand what needs to be done and gather initial information.
|
||||
WHY: Starting without understanding leads to wasted effort. This phase prevents that.
|
||||
-->
|
||||
- [ ] Understand user intent
|
||||
- [ ] Identify constraints and requirements
|
||||
- [ ] Document findings in findings.md
|
||||
- **Status:** in_progress
|
||||
<!--
|
||||
STATUS VALUES:
|
||||
- pending: Not started yet
|
||||
- in_progress: Currently working on this
|
||||
- complete: Finished this phase
|
||||
-->
|
||||
|
||||
### Phase 2: Planning & Structure
|
||||
<!--
|
||||
WHAT: Decide how you'll approach the problem and what structure you'll use.
|
||||
WHY: Good planning prevents rework. Document decisions so you remember why you chose them.
|
||||
-->
|
||||
- [ ] Define technical approach
|
||||
- [ ] Create project structure if needed
|
||||
- [ ] Document decisions with rationale
|
||||
- **Status:** pending
|
||||
|
||||
### Phase 3: Implementation
|
||||
<!--
|
||||
WHAT: Actually build/create/write the solution.
|
||||
WHY: This is where the work happens. Break into smaller sub-tasks if needed.
|
||||
-->
|
||||
- [ ] Execute the plan step by step
|
||||
- [ ] Write code to files before executing
|
||||
- [ ] Test incrementally
|
||||
- **Status:** pending
|
||||
|
||||
### Phase 4: Testing & Verification
|
||||
<!--
|
||||
WHAT: Verify everything works and meets requirements.
|
||||
WHY: Catching issues early saves time. Document test results in progress.md.
|
||||
-->
|
||||
- [ ] Verify all requirements met
|
||||
- [ ] Document test results in progress.md
|
||||
- [ ] Fix any issues found
|
||||
- **Status:** pending
|
||||
|
||||
### Phase 5: Delivery
|
||||
<!--
|
||||
WHAT: Final review and handoff to user.
|
||||
WHY: Ensures nothing is forgotten and deliverables are complete.
|
||||
-->
|
||||
- [ ] Review all output files
|
||||
- [ ] Ensure deliverables are complete
|
||||
- [ ] Deliver to user
|
||||
- **Status:** pending
|
||||
|
||||
## Key Questions
|
||||
<!--
|
||||
WHAT: Important questions you need to answer during the task.
|
||||
WHY: These guide your research and decision-making. Answer them as you go.
|
||||
EXAMPLE:
|
||||
1. Should tasks persist between sessions? (Yes - need file storage)
|
||||
2. What format for storing tasks? (JSON file)
|
||||
-->
|
||||
1. [Question to answer]
|
||||
2. [Question to answer]
|
||||
|
||||
## Decisions Made
|
||||
<!--
|
||||
WHAT: Technical and design decisions you've made, with the reasoning behind them.
|
||||
WHY: You'll forget why you made choices. This table helps you remember and justify decisions.
|
||||
WHEN: Update whenever you make a significant choice (technology, approach, structure).
|
||||
EXAMPLE:
|
||||
| Use JSON for storage | Simple, human-readable, built-in Python support |
|
||||
-->
|
||||
| Decision | Rationale |
|
||||
|----------|-----------|
|
||||
| | |
|
||||
|
||||
## Errors Encountered
|
||||
<!--
|
||||
WHAT: Every error you encounter, what attempt number it was, and how you resolved it.
|
||||
WHY: Logging errors prevents repeating the same mistakes. This is critical for learning.
|
||||
WHEN: Add immediately when an error occurs, even if you fix it quickly.
|
||||
EXAMPLE:
|
||||
| FileNotFoundError | 1 | Check if file exists, create empty list if not |
|
||||
| JSONDecodeError | 2 | Handle empty file case explicitly |
|
||||
-->
|
||||
| Error | Attempt | Resolution |
|
||||
|-------|---------|------------|
|
||||
| | 1 | |
|
||||
|
||||
## Notes
|
||||
<!--
|
||||
REMINDERS:
|
||||
- Update phase status as you progress: pending → in_progress → complete
|
||||
- Re-read this plan before major decisions (attention manipulation)
|
||||
- Log ALL errors - they help avoid repetition
|
||||
- Never repeat a failed action - mutate your approach instead
|
||||
-->
|
||||
- Update phase status as you progress: pending → in_progress → complete
|
||||
- Re-read this plan before major decisions (attention manipulation)
|
||||
- Log ALL errors - they help avoid repetition
|
||||
+180
-110
@@ -2,8 +2,9 @@
|
||||
"""
|
||||
Session Catchup Script for planning-with-files
|
||||
|
||||
Analyzes the previous session to find unsynced context after the last
|
||||
planning file update. Designed to run on SessionStart.
|
||||
Session-agnostic scanning: finds the most recent planning file update across
|
||||
ALL sessions, then collects all conversation from that point forward through
|
||||
all subsequent sessions until now.
|
||||
|
||||
Usage: python3 session-catchup.py [project-path]
|
||||
"""
|
||||
@@ -13,7 +14,6 @@ import sys
|
||||
import os
|
||||
from pathlib import Path
|
||||
from typing import List, Dict, Optional, Tuple
|
||||
from datetime import datetime
|
||||
|
||||
PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
|
||||
|
||||
@@ -34,106 +34,147 @@ def get_sessions_sorted(project_dir: Path) -> List[Path]:
|
||||
return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
|
||||
|
||||
|
||||
def parse_session_messages(session_file: Path) -> List[Dict]:
|
||||
"""Parse all messages from a session file, preserving order."""
|
||||
messages = []
|
||||
with open(session_file, 'r') as f:
|
||||
for line_num, line in enumerate(f):
|
||||
try:
|
||||
data = json.loads(line)
|
||||
data['_line_num'] = line_num
|
||||
messages.append(data)
|
||||
except json.JSONDecodeError:
|
||||
pass
|
||||
return messages
|
||||
def get_session_first_timestamp(session_file: Path) -> Optional[str]:
|
||||
"""Get the timestamp of the first message in a session."""
|
||||
try:
|
||||
with open(session_file, 'r') as f:
|
||||
for line in f:
|
||||
try:
|
||||
data = json.loads(line)
|
||||
ts = data.get('timestamp')
|
||||
if ts:
|
||||
return ts
|
||||
except:
|
||||
continue
|
||||
except:
|
||||
pass
|
||||
return None
|
||||
|
||||
|
||||
def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
|
||||
def scan_for_planning_update(session_file: Path) -> Tuple[int, Optional[str]]:
|
||||
"""
|
||||
Find the last time a planning file was written/edited.
|
||||
Returns (line_number, filename) or (-1, None) if not found.
|
||||
Quickly scan a session file for planning file updates.
|
||||
Returns (line_number, filename) of last update, or (-1, None) if none found.
|
||||
"""
|
||||
last_update_line = -1
|
||||
last_update_file = None
|
||||
|
||||
for msg in messages:
|
||||
msg_type = msg.get('type')
|
||||
try:
|
||||
with open(session_file, 'r') as f:
|
||||
for line_num, line in enumerate(f):
|
||||
if '"Write"' not in line and '"Edit"' not in line:
|
||||
continue
|
||||
|
||||
if msg_type == 'assistant':
|
||||
content = msg.get('message', {}).get('content', [])
|
||||
if isinstance(content, list):
|
||||
for item in content:
|
||||
if item.get('type') == 'tool_use':
|
||||
try:
|
||||
data = json.loads(line)
|
||||
if data.get('type') != 'assistant':
|
||||
continue
|
||||
|
||||
content = data.get('message', {}).get('content', [])
|
||||
if not isinstance(content, list):
|
||||
continue
|
||||
|
||||
for item in content:
|
||||
if item.get('type') != 'tool_use':
|
||||
continue
|
||||
tool_name = item.get('name', '')
|
||||
tool_input = item.get('input', {})
|
||||
if tool_name not in ('Write', 'Edit'):
|
||||
continue
|
||||
|
||||
if tool_name in ('Write', 'Edit'):
|
||||
file_path = tool_input.get('file_path', '')
|
||||
for pf in PLANNING_FILES:
|
||||
if file_path.endswith(pf):
|
||||
last_update_line = msg['_line_num']
|
||||
last_update_file = pf
|
||||
file_path = item.get('input', {}).get('file_path', '')
|
||||
for pf in PLANNING_FILES:
|
||||
if file_path.endswith(pf):
|
||||
last_update_line = line_num
|
||||
last_update_file = pf
|
||||
break
|
||||
except json.JSONDecodeError:
|
||||
continue
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
return last_update_line, last_update_file
|
||||
|
||||
|
||||
def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
|
||||
"""Extract conversation messages after a certain line number."""
|
||||
def extract_messages_from_session(session_file: Path, after_line: int = -1) -> List[Dict]:
|
||||
"""
|
||||
Extract conversation messages from a session file.
|
||||
If after_line >= 0, only extract messages after that line.
|
||||
If after_line < 0, extract all messages.
|
||||
"""
|
||||
result = []
|
||||
for msg in messages:
|
||||
if msg['_line_num'] <= after_line:
|
||||
continue
|
||||
|
||||
msg_type = msg.get('type')
|
||||
is_meta = msg.get('isMeta', False)
|
||||
|
||||
if msg_type == 'user' and not is_meta:
|
||||
content = msg.get('message', {}).get('content', '')
|
||||
if isinstance(content, list):
|
||||
for item in content:
|
||||
if isinstance(item, dict) and item.get('type') == 'text':
|
||||
content = item.get('text', '')
|
||||
break
|
||||
else:
|
||||
content = ''
|
||||
|
||||
if content and isinstance(content, str):
|
||||
if content.startswith(('<local-command', '<command-', '<task-notification')):
|
||||
try:
|
||||
with open(session_file, 'r') as f:
|
||||
for line_num, line in enumerate(f):
|
||||
if after_line >= 0 and line_num <= after_line:
|
||||
continue
|
||||
if len(content) > 20:
|
||||
result.append({'role': 'user', 'content': content, 'line': msg['_line_num']})
|
||||
|
||||
elif msg_type == 'assistant':
|
||||
msg_content = msg.get('message', {}).get('content', '')
|
||||
text_content = ''
|
||||
tool_uses = []
|
||||
try:
|
||||
msg = json.loads(line)
|
||||
except json.JSONDecodeError:
|
||||
continue
|
||||
|
||||
if isinstance(msg_content, str):
|
||||
text_content = msg_content
|
||||
elif isinstance(msg_content, list):
|
||||
for item in msg_content:
|
||||
if item.get('type') == 'text':
|
||||
text_content = item.get('text', '')
|
||||
elif item.get('type') == 'tool_use':
|
||||
tool_name = item.get('name', '')
|
||||
tool_input = item.get('input', {})
|
||||
if tool_name == 'Edit':
|
||||
tool_uses.append(f"Edit: {tool_input.get('file_path', 'unknown')}")
|
||||
elif tool_name == 'Write':
|
||||
tool_uses.append(f"Write: {tool_input.get('file_path', 'unknown')}")
|
||||
elif tool_name == 'Bash':
|
||||
cmd = tool_input.get('command', '')[:80]
|
||||
tool_uses.append(f"Bash: {cmd}")
|
||||
msg_type = msg.get('type')
|
||||
is_meta = msg.get('isMeta', False)
|
||||
|
||||
if msg_type == 'user' and not is_meta:
|
||||
content = msg.get('message', {}).get('content', '')
|
||||
if isinstance(content, list):
|
||||
for item in content:
|
||||
if isinstance(item, dict) and item.get('type') == 'text':
|
||||
content = item.get('text', '')
|
||||
break
|
||||
else:
|
||||
tool_uses.append(f"{tool_name}")
|
||||
content = ''
|
||||
|
||||
if text_content or tool_uses:
|
||||
result.append({
|
||||
'role': 'assistant',
|
||||
'content': text_content[:600] if text_content else '',
|
||||
'tools': tool_uses,
|
||||
'line': msg['_line_num']
|
||||
})
|
||||
if content and isinstance(content, str):
|
||||
# Skip system/command messages
|
||||
if content.startswith(('<local-command', '<command-', '<task-notification')):
|
||||
continue
|
||||
if len(content) > 20:
|
||||
result.append({
|
||||
'role': 'user',
|
||||
'content': content,
|
||||
'line': line_num,
|
||||
'session': session_file.stem[:8]
|
||||
})
|
||||
|
||||
elif msg_type == 'assistant':
|
||||
msg_content = msg.get('message', {}).get('content', '')
|
||||
text_content = ''
|
||||
tool_uses = []
|
||||
|
||||
if isinstance(msg_content, str):
|
||||
text_content = msg_content
|
||||
elif isinstance(msg_content, list):
|
||||
for item in msg_content:
|
||||
if item.get('type') == 'text':
|
||||
text_content = item.get('text', '')
|
||||
elif item.get('type') == 'tool_use':
|
||||
tool_name = item.get('name', '')
|
||||
tool_input = item.get('input', {})
|
||||
if tool_name == 'Edit':
|
||||
tool_uses.append(f"Edit: {tool_input.get('file_path', 'unknown')}")
|
||||
elif tool_name == 'Write':
|
||||
tool_uses.append(f"Write: {tool_input.get('file_path', 'unknown')}")
|
||||
elif tool_name == 'Bash':
|
||||
cmd = tool_input.get('command', '')[:80]
|
||||
tool_uses.append(f"Bash: {cmd}")
|
||||
elif tool_name == 'AskUserQuestion':
|
||||
tool_uses.append("AskUserQuestion")
|
||||
else:
|
||||
tool_uses.append(f"{tool_name}")
|
||||
|
||||
if text_content or tool_uses:
|
||||
result.append({
|
||||
'role': 'assistant',
|
||||
'content': text_content[:600] if text_content else '',
|
||||
'tools': tool_uses,
|
||||
'line': line_num,
|
||||
'session': session_file.stem[:8]
|
||||
})
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
return result
|
||||
|
||||
@@ -142,53 +183,82 @@ def main():
|
||||
project_path = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()
|
||||
project_dir = get_project_dir(project_path)
|
||||
|
||||
# Check if planning files exist (indicates active task)
|
||||
has_planning_files = any(
|
||||
Path(project_path, f).exists() for f in PLANNING_FILES
|
||||
)
|
||||
|
||||
if not project_dir.exists():
|
||||
# No previous sessions, nothing to catch up on
|
||||
return
|
||||
|
||||
sessions = get_sessions_sorted(project_dir)
|
||||
if len(sessions) < 1:
|
||||
if len(sessions) < 2:
|
||||
return
|
||||
|
||||
# Find a substantial previous session
|
||||
target_session = None
|
||||
for session in sessions:
|
||||
if session.stat().st_size > 5000:
|
||||
target_session = session
|
||||
# Skip the current session (most recently modified = index 0)
|
||||
previous_sessions = sessions[1:]
|
||||
|
||||
# Find the most recent planning file update across ALL previous sessions
|
||||
# Sessions are sorted newest first, so we scan in order
|
||||
update_session = None
|
||||
update_line = -1
|
||||
update_file = None
|
||||
update_session_idx = -1
|
||||
|
||||
for idx, session in enumerate(previous_sessions):
|
||||
line, filename = scan_for_planning_update(session)
|
||||
if line >= 0:
|
||||
update_session = session
|
||||
update_line = line
|
||||
update_file = filename
|
||||
update_session_idx = idx
|
||||
break
|
||||
|
||||
if not target_session:
|
||||
if not update_session:
|
||||
# No planning file updates found in any previous session
|
||||
return
|
||||
|
||||
messages = parse_session_messages(target_session)
|
||||
last_update_line, last_update_file = find_last_planning_update(messages)
|
||||
# Collect ALL messages from the update point forward, across all sessions
|
||||
all_messages = []
|
||||
|
||||
# Only output if there's unsynced content
|
||||
if last_update_line < 0:
|
||||
messages_after = extract_messages_after(messages, len(messages) - 30)
|
||||
else:
|
||||
messages_after = extract_messages_after(messages, last_update_line)
|
||||
# 1. Get messages from the session with the update (after the update line)
|
||||
messages_from_update_session = extract_messages_from_session(update_session, after_line=update_line)
|
||||
all_messages.extend(messages_from_update_session)
|
||||
|
||||
if not messages_after:
|
||||
# 2. Get ALL messages from sessions between update_session and current
|
||||
# These are sessions[1:update_session_idx] (newer than update_session)
|
||||
intermediate_sessions = previous_sessions[:update_session_idx]
|
||||
|
||||
# Process from oldest to newest for correct chronological order
|
||||
for session in reversed(intermediate_sessions):
|
||||
messages = extract_messages_from_session(session, after_line=-1) # Get all messages
|
||||
all_messages.extend(messages)
|
||||
|
||||
if not all_messages:
|
||||
return
|
||||
|
||||
# Output catchup report
|
||||
print("\n[planning-with-files] SESSION CATCHUP DETECTED")
|
||||
print(f"Previous session: {target_session.stem}")
|
||||
print(f"Last planning update: {update_file} in session {update_session.stem[:8]}...")
|
||||
|
||||
if last_update_line >= 0:
|
||||
print(f"Last planning update: {last_update_file} at message #{last_update_line}")
|
||||
print(f"Unsynced messages: {len(messages_after)}")
|
||||
else:
|
||||
print("No planning file updates found in previous session")
|
||||
sessions_covered = update_session_idx + 1
|
||||
if sessions_covered > 1:
|
||||
print(f"Scanning {sessions_covered} sessions for unsynced context")
|
||||
|
||||
print(f"Unsynced messages: {len(all_messages)}")
|
||||
|
||||
print("\n--- UNSYNCED CONTEXT ---")
|
||||
for msg in messages_after[-15:]: # Last 15 messages
|
||||
|
||||
# Show up to 100 messages
|
||||
MAX_MESSAGES = 100
|
||||
if len(all_messages) > MAX_MESSAGES:
|
||||
print(f"(Showing last {MAX_MESSAGES} of {len(all_messages)} messages)\n")
|
||||
messages_to_show = all_messages[-MAX_MESSAGES:]
|
||||
else:
|
||||
messages_to_show = all_messages
|
||||
|
||||
current_session = None
|
||||
for msg in messages_to_show:
|
||||
# Show session marker when it changes
|
||||
if msg.get('session') != current_session:
|
||||
current_session = msg.get('session')
|
||||
print(f"\n[Session: {current_session}...]")
|
||||
|
||||
if msg['role'] == 'user':
|
||||
print(f"USER: {msg['content'][:300]}")
|
||||
else:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: planning-with-files
|
||||
version: "2.2.2"
|
||||
version: "2.4.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. Now with automatic session recovery after /clear.
|
||||
user-invocable: true
|
||||
allowed-tools:
|
||||
|
||||
Reference in New Issue
Block a user