skills.rest
gtbauke
gtbaukeCOMMUNITY
Explore all skills by this author →
GitHub

planning-with-files

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

Updated Feb 20, 2026
Search Tags:#workflow#planning#markdown#context management#task tracking#session recovery#agent memory
One-click install
npx skills add https://github.com/gtbauke/bj-utils --skill planning-with-files-gtbauke
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: planning-with-files
Source: https://github.com/gtbauke/bj-utils/tree/main/.agent/skills/planning-with-files
Command: npx skills add https://github.com/gtbauke/bj-utils --skill planning-with-files-gtbauke

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve? Long tasks with many tool calls cause AI agents to lose track of goals, repeat failed actions, and forget discoveries when context resets. This Skill stores plans, findings, and progress in persistent markdown files so work survives context loss and session breaks. ## Core Features & Use Cases - File-Based Planning: Creates task_plan.md, findings.md, and progress.md in your project directory to track phases, decisions, and errors. - Session Recovery: Detects unsynced context from previous sessions via a catchup script and restores state after /clear or restarts. - Hook-Driven Reminders: Uses UserPromptSubmit, PreToolUse, PostToolUse, and Stop hooks to re-inject the plan into context and prompt progress updates. - Use Case: When asked to research a topic and build a report across 50+ tool calls, the Skill maintains a phase checklist, logs every error, and resumes cleanly after interruptions. ## Quick Start Ask the AI to plan out and break down your multi-step project using file-based planning 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?▼

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

How does planning-with-files recover after a session reset?▼

The session-catchup.py script parses the previous session transcript, finds the last planning file update, and reports unsynced messages. You then run git diff, read the planning files, and update them before continuing.

When should I use file-based planning versus simple todo lists?▼

Use it for tasks with three or more steps, research work, or anything spanning many tool calls. Skip it for simple questions, single-file edits, or quick lookups where persistent state adds overhead.

Does planning-with-files work on Windows?▼

Yes. It ships both Bash and PowerShell versions of its init-session and check-complete scripts, and the Stop hook tries PowerShell first with a shell fallback.

Why should web search results not go into task_plan.md?▼

A PreToolUse hook re-reads task_plan.md before every tool call, so untrusted external content there is repeatedly injected into context, amplifying prompt injection risk. External content belongs in findings.md only.

Related Skills

Explore More Product & Management Skills→
TheSoftwareHouseTheSoftwareHouse
282

task-analysis

Analyze task descriptions to identify gaps and generate a task brief.

Official
Advanced
TomekNoconTomekNocon

implement-spec

Automates end-to-end spec implementation by coordinating subagents.

Community
Advanced
sergsevensergseven

external-research

Aggregate Jira, Confluence, and GitHub research into a findings document.

Community
Advanced
alishangtianalishangtian

manus

Persist task_plan.md, findings.md, and progress.md to disk for session recovery.

Community
Advanced