planning-with-files

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

1|Updated May 16, 2026
One-click install
npx skills add https://github.com/ludotype/game-adventurertown --skill planning-with-files-ludotype
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: planning-with-files
Source: https://github.com/ludotype/game-adventurertown/tree/main/.agent/skills/planning-with-files
Command: npx skills add https://github.com/ludotype/game-adventurertown --skill planning-with-files-ludotype

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 treats the filesystem as external memory, persisting plans, findings, and progress in markdown files so work survives context resets, compaction, and /clear. ## Core Features & Use Cases - Three-File Planning Pattern: Creates task_plan.md (phases and decisions), findings.md (research and discoveries), and progress.md (session log) in your project directory. - Session Recovery: A session-catchup script detects unsynced context from previous Claude Code, Codex, or OpenCode sessions after /clear. - Parallel Plan Isolation: Supports multiple concurrent plans under .planning/<date>-<slug>/ with an active-plan pointer and PLAN_ID pinning. - Tamper Protection: Optional SHA-256 attestation locks the plan file; hooks block injection of plan content if the file diverges from the approved hash. - Use Case: When asked to break down a research project or multi-phase build, the agent creates the three planning files first, re-reads the plan before decisions, and logs every error to avoid repeating failures. ## 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?▼

Write the plan to persistent markdown files (task_plan.md, findings.md, progress.md) and re-read the plan before major decisions. This keeps goals in the model's attention window even after dozens of tool calls or context compaction.

How do I recover agent context after /clear or session restart?▼

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 plan tamper protection work?▼

Run attest-plan.sh (or the /plan-attest command) after approving a plan. Hooks compute a SHA-256 of task_plan.md on every injection and block the content with a [PLAN TAMPERED] warning if the hash diverges, until you re-attest.

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 context loss is a real risk.