planning-with-files

Organizes complex multi-step tasks using persistent markdown planning files on disk.

2|Updated May 30, 2026
One-click install
npx skills add https://github.com/virahitvin8/crafty-gis --skill planning-with-files-virahitvin8
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: planning-with-files
Source: https://github.com/virahitvin8/crafty-gis/tree/main/GIT_STAR/assignment-generator/antigravity-skills-main/antigravity-skills-main/skills/planning-with-files
Command: npx skills add https://github.com/virahitvin8/crafty-gis --skill planning-with-files-virahitvin8

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Long agent sessions lose track of goals because context windows are volatile and limited. This Skill implements Manus-style file-based planning, storing task plans, findings, and progress logs as markdown files on disk so work survives context resets, /clear commands, and compaction. ## Core Features & Use Cases - Persistent Planning Files: Creates and maintains task_plan.md, findings.md, and progress.md in your project directory as external working memory. - Session Recovery: A session-catchup script detects unsynced context from previous sessions after /clear, supporting Claude Code, Codex, and OpenCode session stores. - Parallel Plan Isolation: Supports multiple concurrent plans under .planning/<date>-<slug>/ directories with an active-plan pointer and PLAN_ID pinning. - Tamper Protection: Optional SHA-256 attestation locks the plan file so hooks block injection if the plan is modified without re-approval. - Use Case: When asked to plan a multi-phase research or refactoring project, the agent writes a phased task_plan.md first, logs discoveries to findings.md after every search, and updates progress.md after each phase so the work can resume cleanly at any point. ## Quick Start Ask the agent to plan out your multi-step project using planning files, for example: "Plan and track the backend refactor using task_plan.md, findings.md, and progress.md."

Frequently Asked Questions about planning-with-files

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I keep an AI agent on track during long multi-step tasks?

Use file-based planning: write a task_plan.md with phases before starting, update findings.md after discoveries, and log progress.md throughout. Re-reading the plan before decisions keeps goals in the model's attention window across many tool calls.

How do I recover agent context after /clear or context compaction?

Run the session-catchup.py script with your project path. It scans previous Claude Code, Codex, or OpenCode sessions for work done after the last planning file update, then recommends running git diff --stat and re-reading the planning files.

Can I run multiple planning sessions in the same repository?

Yes. Run init-session.sh with a project name to create an isolated plan under .planning/<date>-<slug>/. Switch between plans with set-active-plan.sh or pin a terminal with the PLAN_ID environment variable.

How does the skill prevent prompt injection through plan files?

Hook output wraps plan content in BEGIN/END PLAN DATA markers treated as data only. Optionally, attest-plan.sh stores a SHA-256 hash of task_plan.md, and hooks block injection with a PLAN TAMPERED warning if the file diverges.

When should I not use file-based planning?

Skip it for simple questions, single-file edits, and quick lookups. The pattern is designed for tasks with three or more steps, research work, or anything spanning many tool calls where state persistence matters.