OthmanAdi/planning-with-files

Persistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60+ agents.

What it solves

AI coding agents는 often suffer from "volatile memory," where their task plans and progress is lost when the context window is reset (ethought: context window is lost, so I'll translate the concept) 컨텍스트 윈도우가 초기화될 때 (예: /clear를 통해), 압축될 때, 또는 충돌이 발생했을 때 작업 계획과 진행 상황이 손실되는 "휘발성 메모리" 문제를 겪는 경우가 많습니다. 이는 목표 드리프트(goal drift), 반복되는 실수, 그리고 사용자가 목표를 수동으로 다시 설명해야 하는 필요성으로 이어집니다.

How it works

휘발성 컨텍스트 윈도우에 할 일 목록을 유지하는 대신, 이 프로젝트는 "filesystem as memory" 방식을 구현합니다. 디스크에 세 가지 지속적인 Markdown 파일들을 유지합니다:

task_plan.md: 단계, 체크박스, 그리고 현재 재개 지점을 추적합니다.
findings.md: 연구 노트와 결정 사항을 저장합니다.
progress.md: 세션 활동과 테스트 결과를 기록합니다.

라이프사이클 훅(예: UserPromptSubmit 또는 SessionStart)은 각 턴의 시작 시 이 파일들로부터 관련 계획 컨텍스트를 에이전트의 윈도우로 자동 재주입(re-inject)하여, 계획이 컨텍스트 손실로부터 살아남고 모델의 어텐션 윈도우에 유지되도록 보장합니다.

Who it’s for

세션이나 컨텍스트 초기화 전반에 걸쳐 지속성이 필요되는 장기적이고 복잡한 작업을 위해 AI coding agents (예: Claude Code, Cursor, GitHub Copilot, 또는 Hermes Agent)를 사용하는 개발자들입니다.

Highlights

Persistence: /clear 명령, 충돌돌, 및 컨텍스트 압축 시에도 계획이 유지됩니다.
Agent Agnostic: Agent Skills 표준 및 여러 주요 도구에 대한 네이티브 플러그인을 통해 60개 이상의 에이전트와 호환됩니다.
Goal Stability: 매 턴마다 계획의 헤드(plan head)를 재주입하여 목표 드리프트(goal drift)를 방지합니다.
Integrity Checks: SHA-256 attestation을 사용하여 계획이 몰래 변조되었는지 감지합니다.
Completion Gating: 디스크 기반 계획의 모든 단계가 완료로 표시될 때까지 에이전트가 작업을 "done"으로 선언하는 것을 방지할 수 있습니다.