Planning With Files
Keeps task plans, findings, and progress in files for multi-step agent work.
Install
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g -a claude-code -y- Repository
- OthmanAdi/planning-with-files27.8k
- Category
- AI and agents
- Updated
- 5d ago
- License
- MIT
- Context cost
- Mediumabout 3,000 tokens
- Runs scripts
- Yes, review before use
What it does
Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject selected project planning context. Automatic recovery reads project planning files only. Explicit session-catchup.py --metadata reads same-project local agent session records and emits aggregate counts only; --replay may emit bounded nonce-framed excerpts. Optional gated mode can request continuation only when the host supports it and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls.
Planning with Files
Work like Manus: Use persistent markdown files as your "working memory on disk."
FIRST: Restore Project State
Before continuing, resolve the plan this task owns:
- Use the installed
scripts/resolve-plan-dir.sh(or.ps1) with the task'sPLAN_IDandPWF_PLAN_ROOT. Readtask_plan.md,progress.md, andfindings.mdfrom that one selected directory. A roottask_plan.mdmust not override a selected.planning/<id>/plan. - If an explicit selector is rejected, or multiple named plans exist without
PLAN_ID, stop plan recovery and correct the pin. Do not fall back to another task. Use the legacy project-root files only when no selector or named plan applies. - Run
git diff --statto see code changes that may not yet be recorded in the planning files.
All planning filenames below refer to this selected directory, even when the shell runs elsewhere. For parallel tasks, pin each host before starting it or use separate worktrees. A worker joining an existing task uses its assigned plan; it must not create or overwrite a competing root plan.
Automatic recovery stops there. Bare session-catchup.py and lifecycle hooks do not inspect agent session stores. Only when the user explicitly asks to consult local session history, choose one of these modes:
# Linux/macOS, auto-detects skill directory (plugin env or default install path)
SKILL_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/planning-with-files}"
# Same-project counts only; no transcript excerpts
$(command -v python3 || command -v python) "${SKILL_DIR}/scripts/session-catchup.py" --metadata "$(pwd)"
# Explicit bounded replay; emits nonce-framed same-project excerpts
$(command -v python3 || command -v python) "${SKILL_DIR}/scripts/session-catchup.py" --replay "$(pwd)"
