Verified Agent Skill record

planning-with-files · Planning With Files

A Manus-style persistent file-based planning skill for AI coding agents that maintains task_plan.md, findings.md, and progress.md on disk so work survives context loss and /clear. It uses hooks (UserPromptSubmit, PreToolUse, PostToolUse, Stop, PreCompact) to inject plan context, remind the agent to update progress after writes, and verify phase completion before stopping.

Tasks

Create task_plan.md, findings.md, and progress.md in your project root before beginning any complex task, using the skill's templates as reference.
When resuming a session, read existing planning files immediately and run session-catchup.py followed by git diff --stat to reconcile any unsynced context before proceeding.
After every 2 view, browser, or search operations, immediately save key findings to findings.md to prevent information loss.
After completing a phase, mark its status as complete in task_plan.md, log any errors encountered, and record what was done in progress.md.
If the same action fails, change the approach rather than repeating it; after three total failures, escalate the specific error and attempted resolutions to the user.

Inputs

task_plan.md
findings.md
progress.md
User prompt submissions
Tool invocations matching Write, Edit, Bash, Read, Glob, or Grep
Plan ID from $PLAN_ID environment variable or .planning/.active_plan

Outputs

task_plan.md with phases, progress, decisions, and logged errors
findings.md containing research and discoveries
progress.md serving as a session log with test results
Isolated plan directories under .planning/YYYY-MM-DD-<slug>/
SHA-256 attestation locking task_plan.md content (via attest-plan.sh)

Limitations and checks

The /plan-goal and /plan-loop slash commands are only available via the plugin install route, not the skill-only route
Slash commands carry disable-model-invocation: true, meaning the model will not auto-trigger them and must be typed manually
Some sessions may interpret disable-model-invocation: true as blocking the Skill tool entirely, requiring a manual fallback procedure
Planning files are created in the project root or isolated .planning/ directories, not in the skill installation folder
The protection model relies on the plan being re-read from disk after compaction, not on the plan surviving compaction in context
Verify that task_plan.md, findings.md, and progress.md exist in the project root (or the resolved active plan directory) before starting complex work.
Confirm that after completing a phase, the phase status in task_plan.md is updated from in_progress to complete and a corresponding entry has been added to progress.md.
Ensure every error encountered is logged in task_plan.md with the error description, attempt number, and resolution.