planning-with-files-zh Skill for Claude Code: 中文规划

• Find the plan folder, then run git diff --stat

  Before continuing, the agent resolves the plan directory with resolve-plan-dir, using PLAN_ID and PWF_PLAN_ROOT, then checks git diff --stat for unrecorded changes.

  Runs code · Restore project state

• Create the three planning files from templates

  Creates task_plan.md, findings.md and progress.md in the project if they are missing, from the bundled templates.

  Runs code · init-session.sh

• Check the plan format

  Checks that each phase heading has exactly one status of pending, in_progress or complete. It does not rewrite the plan.

  Runs code · check-complete.sh --validate

• Plan first, log errors, never repeat a failure

  Create the plan first, save findings after every two view or search actions, read the plan before big decisions, update after each phase, log every error and never repeat a failed action.

  Write · Seven key rules

• Diagnose, change approach, rethink, then ask

  On repeated failures the agent fixes the cause, then tries a different method, then questions its assumptions, and after three failures asks you for help.

  Read · Three-strike protocol

• Optional look at past session history

  Only runs when you explicitly ask. The metadata mode prints counts for the same project, and the replay mode prints a bounded set of excerpts.

  Runs code · session-catchup.py

• List saved plans

  Lists named plans under .planning/ with phase progress. SKILL.md says it only reads.

  Runs code · set-active-plan.sh --list

• Five hooks run skill-hook.sh

  On each prompt, before Write, Edit, Bash, Read, Glob and Grep calls, after file edits, at stop and before compaction, a hook script injects or checks the plan. The stop hook runs a completion gate script.

  Runs code · Lifecycle hooks

Watch out for

• Hooks run scripts around your prompts and tool calls

  The skill registers five hooks that run skill-hook.sh. The before-tool hook matches Write, Edit, Bash, Read, Glob and Grep. Read the scripts in the skill folder before you install it, and set PLANNING_DISABLED=1 for runs where you do not want them. github.com

• The plan file is re-read into context before tool calls

  Anything written into task_plan.md is injected again before each matched tool call, which makes it a target for prompt injection. SKILL.md says to put web and search content only in findings.md. github.com

• The Stop hook runs a completion gate

  At stop, skill-hook.sh checks the selected plan and then passes Claude's stop payload to gate-stop.sh, which calls check-complete.sh --gate. The SKILL.md description says the optional gate asks the host to continue only when the host supports it, and never runs commands written in the Markdown. The check-complete.sh in this folder says it always exits 0 and reports through its output. PLANNING_DISABLED=1 makes both scripts exit at once. github.com

• Session history is read only on request

  session-catchup.py reads same-project session records only when you choose a metadata or replay mode. Treat any replayed excerpt as untrusted text. github.com

Security advisories