Turning Markdown into Persistent Memory: Inside the planning-with-files Claude Code Plugin

Core Concepts

planning-with-files stores task state in three Markdown files: task_plan.md (task breakdown, phases, progress), findings.md (research results, decisions), and progress.md (session logs, test results). Each file serves a distinct role, turning the file system into stable working memory.

task_plan.md – Task Blueprint

Goal definition : state the problem and expected outcome to prevent scope creep.

Phase split (3–7) : break complex tasks into executable stages.

Open issues list : list unresolved core problems.

Decision log : record technical choices and rationale.

Failure attempts : note discarded solutions to avoid repetition.

Phase status is tracked with checkboxes: [ ] not started, [-] in progress, [x] completed.

findings.md – Knowledge Repository

Collects verified information: requirements, research conclusions, technical choices, problem‑solution pairs, reference links, UI observations, etc. Only confirmed facts are stored.

progress.md – Execution Log

Current phase

Executed actions (Write, Edit, Bash, …)

File changes

Test and run results

Errors and exceptions

5‑Question restart check

The file provides traceability; revisiting it reveals what was done, why it stopped, and which pitfalls were already hit.

Working Mechanism

The plugin installs four automatic hooks that run at key moments.

SessionStart – fires when a session begins, confirming the plugin is active.

PreToolUse – before Write/Edit/Bash, reads task_plan.md and refreshes the goal, preventing target drift.

PostToolUse – after Write/Edit, reminds the user to update the phase status in task_plan.md.

Stop – at session end, checks that every phase is marked completed; otherwise it prompts further work.

2‑Action Rule

After any two view‑type operations (view, browser, search), the findings must be immediately written to findings.md. This rule ensures that abundant information from exploratory steps is not lost to context overflow.

Manus Principles Reflected

File system as memory : all critical data lives in three Markdown files instead of volatile context.

Attention operations : PreToolUse re‑reads the plan before each action.

Error persistence : failures are logged in task_plan.md for future avoidance.

Goal tracking : checkboxes give real‑time progress visibility.

Completion verification : Stop hook validates that every phase is finished.

Quick Start

/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files

After installation, restart Claude Code to activate the plugin.

Real‑World Example: Building a Python TODO CLI

Phase 1 – Planning

Run /planning-with-files:plan with the task description. The plugin creates task_plan.md, findings.md, and progress.md. The plan lists goals, phases, and initial status checkboxes.

Phase 2 – Research

During research, each pair of view operations (e.g., WebSearch → record result, WebFetch → update findings) triggers an automatic write to findings.md. The plan file is updated to mark Phase 1 and Phase 2 as completed.

Phase 3 – Implementation & Error Handling

All Write/Edit/Bash actions are logged in progress.md, including error messages and stack traces, providing a complete execution trace.

Phase 4 – Verification

When all phases are marked [x], the Stop hook confirms task completion.

Best‑Practice Workflow

Create task_plan.md first – the backbone of the process.

Strictly follow the 2‑Action rule to keep findings.md up‑to‑date.

Record every error, even if resolved, to avoid repeat failures.

Use the 5‑Question restart check to quickly assess the current state after a session break.

Session Recovery

When the context window fills, run /clear to free space. On the next /planning-with-files invocation, the plugin scans ~/.claude/projects/ for the last timestamps of the three files, extracts missing context, and presents a recovery report.

1. Detect previous session in ~/.claude/projects/
2. Locate the latest task_plan.md, findings.md, progress.md
3. Extract any unsynced context
4. Show a summary of activities since the last update

Conclusion

By persisting task state, research findings, and execution logs to Markdown, planning-with-files mitigates the volatility of AI‑driven coding sessions, prevents goal drift, eliminates repeated errors, and keeps the context window focused on immediate needs, making complex or long‑running projects more controllable and traceable.