planning-with-files

Maintains persistent markdown planning files on disk so agent work survives context loss and session resets.

2|Updated Jul 25, 2026
One-click install
npx skills add https://github.com/ankaboot-source/boucle --skill planning-with-files-ankaboot-source
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: planning-with-files
Source: https://github.com/ankaboot-source/boucle/tree/main/.jcode/skills/planning-with-files
Command: npx skills add https://github.com/ankaboot-source/boucle --skill planning-with-files-ankaboot-source

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? AI coding agents lose their working memory when the context window fills, a session is compacted, or /clear is run, causing repeated work and lost progress on multi-step tasks. This Skill stores the plan, findings, and progress in markdown files on disk so work can be resumed at any point. ## Core Features & Use Cases - Persistent planning files: Creates and maintains task_plan.md, findings.md, and progress.md in the project directory, with templates for phase tracking, research storage, and session logging. - Hook-based context injection: UserPromptSubmit, PreToolUse, PostToolUse, Stop, and PreCompact hooks re-inject plan state automatically, with SHA-256 attestation to block tampered plan content. - Parallel and autonomous modes: Supports isolated plans under .planning/ for concurrent tasks, plus autonomous and gated modes with ledger summaries and a completion gate for long-running agent loops. - Use Case: An agent running a multi-hour refactor is interrupted by context compaction; on the next turn it re-reads task_plan.md and progress.md, verifies the attested plan hash, and continues from the exact in-progress phase. ## Quick Start Ask the agent to plan out your multi-step project using planning files, for example: "Create a task plan with phases for refactoring the authentication module and track progress in planning files."

Frequently Asked Questions about planning-with-files

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

FAQPage Schema
How do I make an AI coding agent remember progress after /clear?▼

Write the plan to disk in task_plan.md, findings.md, and progress.md before starting work. The skill's hooks re-inject these files on each turn, and the session-catchup script restores unsynced context from the previous session.

How do I run multiple agent tasks in parallel in the same repo?▼

Run init-session.sh with a task name to create an isolated plan under .planning/YYYY-MM-DD-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, it ships PowerShell variants of its hook scripts and detects Windows environments (MINGW, MSYS, CYGWIN) to run the .ps1 versions. Python is required for the session-catchup script on all platforms.

How does the skill prevent prompt injection through plan files?▼

Plan content is wrapped in BEGIN/END delimiters and treated as data, and an optional SHA-256 attestation locks the approved plan. If the file diverges from the attested hash, injection is blocked with a tamper warning.

When should I not use file-based planning?▼

Skip it for simple questions, single-file edits, and quick lookups where creating planning files adds overhead without benefit. It is designed for tasks with three or more steps or many tool calls.