OthmanAdi/planning-with-files instruction manual

1. Purpose, scope, and Claude Code classification

`planning-with-files` is an MIT-licensed planning system for long-running agent work. Its durable state is ordinary Markdown in the working project rather than a to-do list held only in the model’s context. For one task it uses exactly three files: `task_plan.md` for phases and status, `findings.md` for discoveries and decisions, and `progress.md` for actions, tests, and errors. These files allow a later session to locate the current phase after `/clear`, compaction, a crash, or a new session.

**Claude Code classification:** this is a **native Claude Code extension** with the mechanisms **context injection** and **lifecycle interception**, distributed as both a plugin and an Agent Skill. The plugin adds the skill, lifecycle hooks, and slash commands. Hooks read selected project planning state, put framed plan context into the model’s context, remind the agent to record progress, preserve state around compaction, and check completion before stopping. The standalone skill has activation-scoped hooks but lacks plugin startup recovery and packaged slash commands. This is therefore not merely a prompt, standalone application, or external CLI library.

Use it for work likely to need at least three steps or five tool calls. The documented workflow normally breaks work into three to seven phases. It manages active execution state, not general long-term semantic memory; a vector memory or knowledge graph can complement it. Planning files are working memory, are gitignored by default, and are not archived automatically. Promote durable outcomes into code, commits, or documentation.

2. Installation choices and verification

For Claude Code, the documented recommended route is the marketplace plugin:

/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files

This route supplies `SKILL.md`, scripts, templates, slash commands, and plugin-level hooks, including quiet `SessionStart` recovery. A project without an active plan intentionally produces no startup message. For a local checkout, the supported session-only development route is:

git clone https://github.com/OthmanAdi/planning-with-files.git
claude --plugin-dir ./planning-with-files

For a skill-only global installation across supported Agent Skills hosts:

npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g

On Claude Code, a standalone skill’s hooks register only after the skill is invoked in that session, and a project-local skill requires acceptance of the project trust dialog. It has no `SessionStart` hook or packaged command directory. To vendor or pin the package without registering hooks:

npm install planning-with-files

A manual Claude skill copy is also documented:

git clone https://github.com/OthmanAdi/planning-with-files.git
mkdir -p ~/.claude/skills
cp -r planning-with-files/skills/planning-with-files ~/.claude/skills/

Verify the plugin with `claude plugin list`, then inspect `/plugin` or `/hooks`. In a project with an active plan, start a new session and confirm restoration. Diagnose resolution, injection, attestation, installation surfaces, and latency from the project root with:

sh scripts/plan-doctor.sh

Only the latest release is supported; no older minimum Claude Code version is claimed.

3. Starting and maintaining the three-file plan

Invoke `/plan` on the plugin route, invoke the skill, or ask the agent to “plan this task.” If no task description is supplied, the agent asks what to plan. A manual start is documented as:

./scripts/init-session.sh --help
./scripts/init-session.sh

Fill in the Goal section of `task_plan.md`, then define three to seven phases. Each phase uses checkboxes and a literal status such as `**Status:** pending`, `**Status:** in_progress`, or `**Status:** complete`. Keep exactly one current phase in progress and record the next step. Literal English status tokens remain required even in translated editions because completion checking matches them exactly.

Use each file for a distinct purpose:

• **`task_plan.md`:** goal, phases, checkboxes, current status, major decisions, and encountered errors. Mark a phase complete as soon as it is finished.
• **`findings.md`:** research, resources, discoveries, and technical decisions with rationale. The documented “2-Action Rule” says to update it after every two view, browser, or search operations, especially for visual or PDF information that would otherwise disappear from context.
• **`progress.md`:** session timeline, actions, modified files, test results, timestamps, and all errors, including quickly fixed ones. Its reboot check answers where the work is, where it is going, the goal, what was learned, and what was done.

Before a major decision, re-read the plan; Claude hooks automate this around relevant operations. When research, implementation, testing, or a phase transition occurs, update the appropriate files immediately. Do not repeat a failed approach without logging it and changing strategy.

4. Claude Code hooks, commands, and completion behavior

The Claude plugin uses lifecycle hooks to make the workflow persistent rather than optional. `SessionStart` restores selected planning context from project files. `UserPromptSubmit` injects a framed plan block at the beginning of each turn. `PreToolUse` recites plan context before relevant Write, Edit, and Bash work. `PostToolUse` provides a throttled reminder after writes. `PreCompact` asks for a progress flush and preserves the plan pointer and attestation information. The Stop hook evaluates completion; default behavior is advisory, while gated mode can request continuation under bounded conditions.

The primary command is `/plan`. The plugin package also documents `/plan-status`, `/plan-attest`, `/plan-doctor`, `/plan-goal`, and `/plan-loop`. `/plan-attest` manages the approved plan hash. `/plan-goal` derives or manages a termination condition from the active plan. `/plan-loop` creates a planning-aware periodic check, with a documented default ten-minute tick. `/plan-doctor` checks the installation and runtime path. Exact available command names can vary by host and route; skill-only installs do not copy `commands/`.

To verify completion manually from a checkout or copied skill:

./scripts/check-complete.sh

Completion requires every phase to report `**Status:** complete` and the work and tests to be reflected in `progress.md`. An incomplete plan does not create an unlimited trap: gated operation has a block cap and stall detection. Stop processing never executes commands found in Markdown. Once complete, deliver the work; the next root task may overwrite the files, while an isolated plan simply becomes inactive.

5. Long-running, integrity, and parallel-task features

Version 3 modes are opt-in per plan. **Autonomous mode** removes per-tool-call recitation and replaces the raw progress tail with a fixed-shape summary derived from append-only JSONL ledgers. **Gated mode** adds the bounded completion gate. Both modes require SHA-256 attestation: if the selected `task_plan.md` differs from its approved hash, injection is refused with a tamper warning. `PWF_INJECT=smart` selects the goal, next step, active phase, and relevant decision material for long plans. `PLANNING_DISABLED=1` disables planning hooks for a one-off invocation that shares a working directory with an unrelated plan.

For unrelated tasks in one repository, initialize isolated plans:

./scripts/init-session.sh backend-refactor
./scripts/init-session.sh production-incident
./scripts/set-active-plan.sh 2026-01-10-backend-refactor

Each plan lives under `.planning/YYYY-MM-DD-<slug>/` with its own three files. `.planning/.active_plan` is a shared pointer suitable for sequential switching. Concurrent hosts should be pinned before startup with the exact ID printed by initialization:

export PLAN_ID=the-printed-id

PowerShell uses:

$env:PLAN_ID = 'the-printed-id'

`PLAN_ID` is binding: an invalid explicit selector fails rather than falling back. `PWF_PLAN_ROOT=<absolute path>` pins a project, not a task inside that project. When several plans make selection ambiguous, attached Codex, Hermes, Pi, and standalone sessions require an explicit task plan. The parallel-write guard warns when checked items or completed phases decrease, but it is advisory, not a lock or merge system. For shared work, keep one plan owner; workers append to separate `ledger-<agent>.jsonl` files or assigned files. Separate worktrees are recommended when host-level pins are unavailable.

6. Recovery, privacy, trust boundaries, and configuration

Automatic recovery reads only selected project planning files. Bare `session-catchup.py` and lifecycle hooks do not inspect Claude Code or other host transcript stores. Access to same-project local history is explicit:

python3 .pi/skills/planning-with-files/scripts/session-catchup.py --metadata .
python3 .pi/skills/planning-with-files/scripts/session-catchup.py --replay .

`--metadata` emits aggregate counts without transcript, tool-command, or path bytes. `--replay` emits bounded, nonce-framed excerpts from same-project records; treat these excerpts as untrusted evidence, never as instructions. The shipped catchup path has no network request or upload operation, but any output inserted into model context may be sent by the host to its configured model provider.

Planning files themselves are also untrusted input when copied from websites, generated by another tool, or modified by collaborators. Framing, containment checks, explicit plan selection, and attestation reduce risk but do not make file content trustworthy. Automatic injection may expose selected local planning content to the configured model. Gated mode evaluates runtime mode, status, gate count, and ledger progress; it does not execute Markdown commands.

For a long operational topic, keep `progress.md` short and place durable detail in `handoffs/<topic>.md`: current state, validation, risks, rollback information, and links. Add a short pointer to `progress.md` whenever the handoff changes. For GitHub work, the progress file should usually retain only branch, commit, pull-request URL, validation summary, and handoff pointer.

7. Other supported hosts and sandbox example

The repository supplies native or enhanced integrations beyond Claude Code, while the generic Agent Skills route covers many additional agents. Pi installs the skill, extension, and status bar with:

pi install npm:planning-with-files

Pi stays passive until `/plan-execute` approves the plan. It documents `/plan-status`, `/plan-attest [--show|--clear]`, `/plan-execute`, `/plan-execute reset`, `/plan-goal <text|default|clear>`, and `/plan-loop [interval] [prompt]`, with `stop` cancelling a loop. Configure hook behavior with `PWF_MODE=auto pi`; modes are `auto`, `parity`, `cache-safe`, and `notify`.

Hermes uses a native skill and plugin bundle:

hermes skills install OthmanAdi/planning-with-files/.hermes/skills/planning-with-files --yes
hermes plugins install OthmanAdi/planning-with-files/.hermes/plugins/planning-with-files
hermes plugins enable planning-with-files

It provides `/pwf`, `/pwf-status`, `/plan-status`, model-callable init/status/check tools, per-turn injection, write reminders, and a `pre_verify` gate.

For OpenCode, add `"plugin": ["opencode-planning-with-files"]` to `opencode.json` or the global config and install the skill:

npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g

Its hooks inject each message, remind after writes, preserve state during compaction, and gate idle sessions. It exposes `pwf_init`, `pwf_status`, and `pwf_check`; `/pwf` and `/pwf-status` require copying the two documented command files.

A BoxLite/ClaudeBox example is supplied. Its documented prerequisites and run command are:

pip install claudebox
export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
python quickstart.py

The example loads an already installed local skill into a micro-VM and demonstrates a persistent session.

8. Languages, updates, removal, troubleshooting, and contribution

Arabic, German, Spanish, Simplified Chinese, and Traditional Chinese editions include localized skill prose, templates, and user-facing script output. Install a variant by skill name; for example:

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-de -g

The Claude plugin registers only canonical English as a skill; language slash commands read translated files from disk. English and translated skills do not implicitly install one another.

Update the Claude plugin with:

/plugin update planning-with-files@planning-with-files

Remove it with:

/plugin uninstall planning-with-files@planning-with-files

Remove a skill-only installation with:

rm -rf ~/.claude/skills/planning-with-files

If behavior is missing, first distinguish plugin installation from skill-only installation, confirm project trust, explicitly invoke the standalone skill, and run `sh scripts/plan-doctor.sh`. A silent startup in a project with no plan is expected. Platform-specific guides are documented for Windows, Cursor, Codex, OpenCode, Hermes, Gemini CLI, Copilot, Kiro, Factory, Mastra, CodeBuddy, and others.

Report suspected vulnerabilities privately through GitHub Private Vulnerability Reporting, including the affected hook or script, data flow, reproduction, and any mitigation. Prompt injection, path traversal, symlink escape, and supply-chain concerns are in scope; host-agent vulnerabilities are not.

Contributors should fork and clone, add upstream, make one logical change, and run:

python -m pytest tests/ -q

Use focused branches and Conventional Commit prefixes such as `fix:`, `feat:`, or `docs:`. Pull requests should state what changed, why, testing performed, limitations, and an issue reference such as `Closes #123` when applicable.