planning-with-files

Organizes complex tasks into persistent markdown planning files with progress tracking and session recovery.

Updated Apr 6, 2026
One-click install
npx skills add https://github.com/QT-7274/dotfiles --skill planning-with-files-qt-7274
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: planning-with-files
Source: https://github.com/QT-7274/dotfiles/tree/main/planning-with-files
Command: npx skills add https://github.com/QT-7274/dotfiles --skill planning-with-files-qt-7274

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve? Long multi-step tasks cause AI agents to lose track of goals after many tool calls, and context resets like /clear wipe all working memory. This Skill persists plans, findings, and progress to markdown files on disk so work survives context loss and stays organized. ## Core Features & Use Cases - File-Based Planning: Creates task_plan.md, findings.md, and progress.md in your project directory to track phases, decisions, errors, and session logs. - Session Recovery: Recovers unsynced context from previous sessions after /clear by analyzing session history and git diffs. - Parallel Plan Isolation: Supports multiple concurrent plans under .planning/<date>-<slug>/ directories with an active-plan pointer and PLAN_ID pinning. - Plan Integrity Attestation: Locks task_plan.md with a SHA-256 hash so hooks block injection of tampered plan content. - Use Case: When asked to research a topic, fix a bug, or build a feature spanning many steps, the agent writes a phased plan first, logs findings after every discovery, and resumes seamlessly after compaction or session breaks. ## Quick Start Ask the agent to plan out and break down your multi-step project using planning files before starting any work.

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?▼

Write the plan to a persistent markdown file like task_plan.md and re-read it before major decisions. This keeps goals in the model's recent attention window even after dozens of tool calls, preventing the lost-in-the-middle effect.

How to recover agent context after running /clear in Claude Code?▼

Run the session-catchup.py script with your project path. It analyzes the previous session transcript, finds messages after the last planning file update, and recommends running git diff --stat plus re-reading task_plan.md, progress.md, and findings.md.

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.

Does planning-with-files work on Windows?▼

Yes. Every shell script has a PowerShell mirror, including init-session.ps1, check-complete.ps1, resolve-plan-dir.ps1, and attest-plan.ps1, so the workflow runs on Windows, macOS, and Linux.

When should I skip 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 context management matters.

How does the plan attestation protect against prompt injection?▼

Run /plan-attest or attest-plan.sh after approving a plan to store its SHA-256 hash. Hooks recompute the hash on every injection and block plan content with a PLAN TAMPERED warning if the file was modified without re-approval.