planning-with-files

Implements a three-file markdown-based external memory system (task_plan.md, findings.md, progress.md) that persists across AI agent context window resets and session boundaries. The system treats the filesystem as non-volatile disk storage analogous to RAM, automatically serializing agent state, decisions, and discoveries to markdown files that survive /clear commands and context loss. Each file serves a distinct purpose: task_plan.md tracks phases and decisions, findings.md captures research and technical decisions, progress.md logs session history and test results.

Enforces a structured markdown schema across three files with specific sections and update frequencies: task_plan.md tracks phases, decisions, and error logs (updated after phase completion); findings.md captures research discoveries and technical decisions (updated every 2 view/browser operations); progress.md logs session history and test results (updated throughout session). Each file has a defined structure with headers, status indicators, and timestamp tracking, creating a queryable state representation that agents can read before deciding on next actions.

Decomposes complex tasks into explicit phases tracked in task_plan.md with status indicators (not-started, in-progress, complete, blocked). Each phase has a clear objective, success criteria, and dependencies on prior phases. The system uses phase boundaries to scope context windows, create git checkpoints, and trigger state updates. Agents read the current phase from task_plan.md before deciding on actions, ensuring work stays focused on the current phase rather than drifting across multiple objectives. Phase completion triggers automatic updates to task_plan.md and can trigger git commits, creating explicit checkpoints in the project history.

Maintains findings.md as a searchable reference of research discoveries, technical decisions, and their rationale. Agents update findings.md after every 2 view/browser operations or significant discoveries, recording: what was discovered, why it matters, what decision was made, and what alternatives were considered. This creates a queryable knowledge base that agents can reference before making similar decisions, avoiding redundant research and enabling consistent decision-making across sessions. Findings are organized by topic or decision category, making them searchable without requiring full file reads. The pattern enables agents to build institutional knowledge that persists across sessions and can be shared with other agents.

Maintains progress.md as a session log that records all actions taken, test results, and session history throughout the agent's work. Entries are timestamped and include: what action was taken, what the result was, what was learned, and what comes next. Progress.md grows throughout the session and serves as a detailed audit trail of everything the agent did. Unlike task_plan.md (which tracks phases) and findings.md (which tracks discoveries), progress.md tracks the moment-by-moment execution history. This enables agents to review what was attempted in prior sessions, understand why certain approaches were taken, and avoid repeating failed attempts.

Implements a critical workflow pattern where agents must read the three markdown files (task_plan.md, findings.md, progress.md) before making decisions or taking actions. This pattern breaks the stateless agent loop by forcing agents to check current state, previous decisions, and error history before proceeding. The pattern is enforced through hook system automation and critical rules that prevent agents from acting without first consulting the persistent state files, creating a synchronous decision-making loop tied to filesystem state.

Enables agents to recover from context window resets, /clear commands, or session interruptions by reading the three markdown files to reconstruct the prior session state. When a session resumes, the agent reads task_plan.md to identify the last completed phase, findings.md to understand prior discoveries and decisions, and progress.md to review session history and test results. This restoration process reconstructs the agent's understanding of project state without re-running prior work, allowing seamless continuation from the last known checkpoint.

Integrates git commits as explicit checkpoints in the agent workflow, allowing agents to create git snapshots after completing phases or achieving milestones. The workflow uses git commits to mark stable states in the three markdown files and project code, enabling rollback to prior states if errors are discovered. Agents can reference git commit hashes in task_plan.md and progress.md, creating a version-controlled audit trail of state changes. This pattern combines filesystem persistence with git's version control, providing both recovery and history tracking.

Implements a hook system that automatically triggers actions at specific points in the agent workflow, such as after phase completion, before tool execution, or on error conditions. Hooks can enforce critical rules (e.g., read-before-decide), update markdown files automatically, or trigger git commits. The system uses event-based triggers tied to agent actions, allowing automation of repetitive state management tasks without requiring explicit agent instructions. Hooks are defined in configuration and executed by the agent platform (Claude Code, Cursor, Continue) when conditions are met.

Implements the six Manus principles that define the agent loop architecture: (1) persistent external memory via markdown files, (2) read-before-decide pattern, (3) phase-based task decomposition, (4) error tracking and recovery, (5) context engineering for KV-cache optimization, and (6) session management with checkpoints. These principles work together to create a stateful agent loop where each iteration reads state, makes decisions informed by prior discoveries, executes actions, logs results, and updates persistent state. The architecture treats the agent as a state machine with explicit transitions between phases rather than a stateless function.

Implements context engineering strategies to optimize token usage and KV-cache efficiency in agent loops. The system uses phase-based decomposition to keep context windows focused on current phase, reads only relevant sections of markdown files to minimize token consumption, and structures prompts to maximize KV-cache reuse across multiple agent turns. Context engineering includes strategies like: keeping task_plan.md concise by archiving completed phases, using findings.md as a searchable reference to avoid re-reading full progress logs, and structuring progress.md with clear section boundaries for efficient parsing. These strategies reduce token consumption and improve response latency by optimizing what context is loaded into the KV-cache.

Provides platform-specific implementations of the planning-with-files pattern for Claude Code, Cursor, Continue IDEs, Kilocode, and other agent platforms. Each platform has specific integration points: Claude Code uses .claude-plugin/plugin.json for skill configuration, Cursor and Continue use similar plugin systems, Kilocode uses its own skill registry. The system provides helper scripts and configuration templates for each platform, enabling agents to use the three-file pattern without reimplementing core logic. Platform-specific guides document how to initialize the skill, configure hooks, and adapt the pattern to platform constraints.

Implements a structured error recovery pattern where agents log failures in task_plan.md error logs, analyze root causes in findings.md, and document recovery strategies in progress.md. When an error occurs, the agent records: what failed, why it failed, what was attempted, and what recovery strategy was used. This creates a queryable error history that agents can reference before attempting similar actions, preventing repeated failures. The pattern includes anti-patterns documentation that identifies common failure modes (e.g., reading findings.md without acting on it, skipping error log checks) and provides recovery strategies for each.