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.