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 $2B Manus acquisition workflow pattern.

🔥 Key Capabilities & USP

• Persistent Markdown Planning: Solves the critical pain point of AI agent context loss by maintaining a task_plan.md file that survives across sessions. No more fragmented conversations or forgotten task states.
• Session Recovery: Automatically resurrects lost context after /clear commands by extracting data from IDE session stores. This is a game-changer for long-running, complex agent tasks.
• Multi-Platform Support: Works across 17+ IDEs including Claude Code, Cursor, GitHub Copilot, Gemini CLI, and Codex. One skill, every major agent platform.
• Parallel Plan Isolation: Run multiple concurrent plans with dedicated .planning/YYYY-MM-DD-slug/ directories and session attachment gating. No cross-contamination between tasks.
• Hash Attestation Security: SHA-256 hash locking of plan files with tamper detection hooks. Enterprise-grade integrity for agent workflows.

USP: This is the exact workflow pattern behind Meta's $2B Manus acquisition, now open-source and accessible to every developer. With a 96.7% benchmark pass rate and proven A/B blind test wins, it's not just theoretical—it's battle-tested.

Technical Architecture

Component	Description
Plugin Architecture	SKILL.md configuration files drive all behavior. Plug-and-play for any agent framework.
Lifecycle Hooks	Five hooks: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop. Full control over agent execution flow.
Shell Script Core	Lightweight shell scripts for session initialization, plan resolution, and active plan management. Zero heavy dependencies.
IDE Integration Layer	OS-aware hook execution with dedicated configurations for each of the 17+ supported IDEs.
Security Layer	SHA-256 hash attestation with tamper detection. Plan files are cryptographically locked.

Language: Python (primary), with shell script integration for hook management.

Quick Start Guide

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

# Install the skill for your IDE (example for Claude Code)
# Copy the SKILL.md and hook scripts to your project's .claude/ directory
cp -r skills/claude-code/* .claude/

# Initialize a planning session
# The system will create a task_plan.md in your project root

For multi-IDE setups, configure the appropriate hook directory:

# For Cursor
cp -r skills/cursor/* .cursor/

# For GitHub Copilot
cp -r skills/copilot/* .github/copilot/

Pros, Cons & Use Cases

Pros

• Proven Performance: 96.7% benchmark pass rate with documented A/B blind test wins
• Massive Ecosystem: 17+ IDE support with active community forks and extensions
• Security Audited: Hash attestation and tamper detection built-in
• Session Recovery: Unique ability to recover context after session resets—a critical feature no other tool offers

Cons

• Complex Multi-IDE Setup: Installation across multiple IDEs requires understanding different hook systems and directory structures
• Learning Curve: Requires familiarity with agent hook systems and lifecycle management
• Version Regression Risk: Changelog notes version-specific regression issues that may require pinning

Who should NOT use this?

• Single-session users: If your agent tasks complete in one session, the persistence overhead isn't justified
• Non-agent developers: This is specifically for AI coding agents—not for traditional software development workflows
• Minimalist setups: If you avoid configuration files and hook systems, the complexity will outweigh the benefits

Ideal Use Cases

• Long-running agent tasks: Codebase refactoring, multi-step debugging, or feature development spanning hours or days
• Multi-agent orchestration: Teams of AI agents working on parallel tasks that need shared, persistent state
• Enterprise CI/CD pipelines: Automated code review, testing, and deployment workflows requiring session resilience
• Research & prototyping: Complex experiments where context continuity is critical for reproducibility

Community & Activity

This project is on fire with 20,799 stars—a clear signal of massive community validation. The active ecosystem includes dedicated forks and extensions across the 17+ supported IDEs, with contributors building on the Manus-style pattern.

The last update on May 10, 2026 shows active maintenance, and the changelog indicates ongoing refinement with version-specific fixes. With topics spanning from Claude and Copilot to Hermes and Mastra, the project has already become a cross-platform standard for persistent agent planning.

If you're building anything with AI coding agents, this isn't just a tool—it's quickly becoming the infrastructure layer for production-grade agent workflows.