OthmanAdi/planning-with-files

⭐ 20,799  ·  Python  ·  GitHub Repo

Claude Code skill implementing Manus-style persistent markdown planning — the workflow pattern behind the $2B acquisition.

adal agent-skills antigravity claude claude-code claude-skills copilot copilot-skills

1-Sentence Summary

Persistent markdown planning for AI agents, replicating the workflow behind Meta's $2B Manus acquisition.

🔥 Key Capabilities & USP

• Persistent Markdown Planning: Maintains structured task_plan.md files that survive context clears and session resets. Solves the critical pain point of AI agents losing all task state when you clear the conversation or restart your IDE.
• Automatic Session Recovery: After /clear commands, the system automatically detects the lost context, checks session stores, and extracts recent conversation history to restore the plan. Eliminates the "blank slate" problem that plagues every agent-based workflow.
• Multi-Platform Support: Works across 17+ IDEs and tools including Claude Code, Cursor, GitHub Copilot, Gemini CLI, Codex, and more—each with dedicated hook configurations. One workflow, every environment.
• Parallel Plan Isolation: Supports multiple simultaneous plans in .planning/YYYY-MM-DD-slug/ directories with independent session tracking. Run complex, concurrent agent tasks without plan collisions.
• Security Hardening: Includes hash attestation (/plan-attest), prompt injection delimiters, and audited security fixes. Enterprise-grade safety for production agent workflows.

USP: This is the only open-source implementation of the Manus persistent planning pattern—the exact workflow architecture that drove a $2B acquisition. It's not just another task manager; it's the proven, acquisition-validated pattern for agentic coding.

Technical Architecture

Component	Technology	Purpose
Core Logic	Python + Shell Scripts	Plan creation, session tracking, recovery logic
Configuration	SKILL.md + hooks.json	Lifecycle hooks for agent integration
Storage	Markdown files (task_plan.md)	Human-readable, version-controllable plan persistence
Session Management	.planning/ directory structure	Parallel plan isolation with date-stamped slugs
IDE Integration	Per-IDE hooks.json, plugin.json	OS-aware hooks for Windows, Linux, macOS
Security	Hash attestation, prompt delimiters	Anti-tampering and injection prevention
Lifecycle Hooks	SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop	Full agent event lifecycle coverage

The architecture is plugin-based and event-driven: each IDE's agent triggers lifecycle hooks that the planning system intercepts, ensuring plans are created, updated, and recovered at the right moments.

Quick Start Guide

# Clone the repository
git clone https://github.com/OthmanAdi/planning-with-files.git
cd planning-with-files

# Install for Claude Code (primary target)
# Copy the SKILL.md and hooks to your Claude Code project root
cp -r planning-with-files/* /path/to/your/project/

# For Cursor, Copilot, or other IDEs, use the appropriate branch
git checkout cursor  # or copilot, gemini-cli, codex, etc.

# Initialize a new plan
# The agent will automatically create task_plan.md on first interaction

Setup logic: The project is a skill/plugin you drop into your project root. Each IDE has a dedicated configuration branch with the correct hooks.json and lifecycle setup. After copying the files, your agent will automatically begin using persistent markdown planning on the next session start.

Pros, Cons & Use Cases

Pros

• 96.7% benchmark pass rate—proven reliability in real agent workflows
• Active community with forks, extensions, and rapid iteration
• Automatic recovery from context clears—no more lost work
• Security-audited with hash attestation and injection defenses
• 17+ platform support with dedicated configurations per IDE

Cons

• Manual installation per IDE—no package manager install (yet)
• Version churn (v2.37.0+ with frequent updates) may require ongoing maintenance
• Some features are IDE-specific—not all capabilities work on every platform
• Shell compatibility issues on NixOS and other non-standard environments (shebang fix needed)

Who should NOT use this?

• Casual users who only run single-session agent prompts and never clear context
• Teams on locked-down enterprise environments where adding custom hooks to IDEs is prohibited
• Users of unsupported IDEs (e.g., niche or proprietary tools not in the 17+ supported list)
• Developers on NixOS without willingness to apply the documented shebang workaround

Ideal Use Cases

• Multi-session coding projects where you need to resume work after clearing agent context
• Complex, multi-step refactoring that requires structured task tracking across days
• CI/CD pipeline agents that need to maintain state across automated runs
• Teams standardizing on agent workflows who want a proven, acquisition-validated pattern
• Power users juggling multiple parallel agent tasks (e.g., backend + frontend + docs)

Community & Activity

This project is on fire. With 20,799 stars and a last update on May 10, 2026, it's not just popular—it's actively maintained and rapidly evolving. The community has already produced forks and extensions across multiple platforms, and the v2.37.0 release cadence shows a team that's shipping fast and fixing issues. The 96.7% benchmark pass rate isn't just a number—it's a signal that the community is stress-testing this in production and it's holding up. If you're building agentic workflows in 2026, this is the pattern to watch and adopt.