OthmanAdi/planning-with-files installation guide

Install `planning-with-files` on macOS Tahoe (Apple silicon)

What this repository is

`OthmanAdi/planning-with-files` is a **Claude Code extension**, not a standalone application. More specifically, it is a native Claude Code plugin that combines:

• a planning skill (`SKILL.md`);
• lifecycle hooks that inject selected planning context into Claude Code;
• slash commands such as `/plan` and `/plan-doctor`;
• an optional completion gate that can ask Claude Code to continue while a plan still contains an `in_progress` phase.

A useful catalog classification is:

• **Install mode:** Claude extension
• **Mechanisms:** context injection and lifecycle interception
• **Setup effort:** low
• **Confidence:** high

This classification is supported by the repository’s documented Claude Code plugin route and its `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, and Stop-related behavior. It does not replace Claude Code. It extends an existing Claude Code installation.

The extension maintains three Markdown files in the project where you work:

• `task_plan.md` for phases, checkboxes, and task status;
• `findings.md` for research and decisions;
• `progress.md` for actions, tests, and errors.

These files live on disk, so they can remain available after `/clear`, compaction, a crash, or a new session. The plugin’s hooks can put selected plan information back into model context.

Before you begin

You need a working installation of the **current stable Claude Code release**. The repository does not claim an older minimum compatible version and does not provide a first-party Claude Code installation procedure, so this guide does not invent one.

Open Terminal from **Applications → Utilities → Terminal** if you need to check Claude Code, but perform the recommended installation itself inside Claude Code’s interactive interface.

The supplied repository files do not document any separate Apple-silicon package, Rosetta requirement, Homebrew dependency, compiler, or macOS Tahoe-specific workaround. Therefore, use the normal Claude Code plugin route below. This guide cannot claim that Tahoe has a separately tested compatibility receipt; it can only follow the repository’s documented macOS-capable plugin procedure.

Recommended installation

The repository recommends the plugin route because it installs the skill, hooks, and slash commands together. Open Claude Code, then enter these two lines **one at a time** in Claude Code, not in the ordinary macOS shell:

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

The first line adds the repository as a Claude Code plugin marketplace. The second installs the named plugin from that marketplace.

When installation finishes, start a new Claude Code session so its plugin-level lifecycle hooks are loaded from startup. The repository says this route provides automatic updates, proper hook integration, and the full feature set.

A project that does not contain an active plan should produce no startup message. That silence is intentional and does not by itself mean installation failed.

Verify the installation

From Terminal, the repository documents this command for listing installed Claude Code plugins:

claude plugin list

Confirm that `planning-with-files` appears. You can also inspect the plugin from Claude Code’s `/plugin` or `/hooks` interface.

Next, open Claude Code in a project where you want to use file-based planning. Invoke the plugin with:

/plan

Describe a multi-step task when prompted. The skill should create or maintain the three planning files in that project. For a simple, single task, they normally appear at the project root:

task_plan.md
findings.md
progress.md

The repository says these are working-memory files and are gitignored by default. They are not automatically archived when work finishes. Preserve important outcomes in your code, commits, or permanent documentation rather than assuming the planning files are a final deliverable.

To check the integration and hook behavior, use the plugin’s documented doctor command inside Claude Code:

/plan-doctor

The doctor checks plan resolution, injection, attestation, installation surfaces, and per-fire latency. If no plan is active, first create one with `/plan`, then run the doctor again.

Confirm recovery behavior

After creating a plan, make sure `task_plan.md` contains phases with status markers such as `pending`, `in_progress`, and `complete`. Continue the task long enough for `progress.md` and `findings.md` to receive useful information.

The plugin route registers lifecycle hooks at startup. According to the repository, startup, resume, clear, and post-compaction events restore selected active-plan context from project files. You can therefore use Claude Code’s normal `/clear` behavior and then continue the task. The extension should resolve and re-read the project’s planning state rather than depending only on the erased conversation context.

Automatic recovery reads project planning files only. It does **not** automatically inspect Claude Code’s transcript store. The repository has explicit metadata and replay modes for same-project local history, but those are optional advanced actions and are unnecessary for a normal installation test.

How to use it day to day

Use `/plan` at the start of a complex task, or ask Claude to plan the task. The repository describes automatic self-triggering for multi-step work, but skill-description triggering can be probabilistic. Explicitly invoking `/plan` is the clearest way to begin.

During work, the intended pattern is:

1. Keep phases and current status in `task_plan.md`.
2. Record discoveries and decisions in `findings.md`.
3. Record actions, validation results, and errors in `progress.md`.
4. Mark each phase `complete` only after its work and checks finish.

The hooks re-inject selected plan context, remind the agent after relevant writes, and preserve planning information around compaction. Optional gated mode can hold completion while a phase remains `in_progress`, but the repository describes caps and stall detection intended to prevent an incomplete plan from trapping a session indefinitely.

For several unrelated tasks in one repository, the extension supports isolated directories under `.planning/` and an active-plan selector. That is an advanced workflow; begin with the three root files unless you actually need concurrent plans.

Security and privacy considerations

Treat the planning files as content that may enter model context. If you paste material from websites, issue reports, logs, or other untrusted sources into a plan, it remains untrusted even though it is now in a local Markdown file. The repository specifically identifies prompt injection through plan content as a security concern.

Automatic hooks can read selected project planning state and inject it into Claude Code’s context. Claude Code may then send that context to its configured model provider. Do not place secrets in `task_plan.md`, `findings.md`, or `progress.md` unless you are willing for them to be handled as model context.

The repository supports SHA-256 plan attestation and blocks injection when an attested plan no longer matches its approved hash. This can help detect unexpected plan changes, but it is not a general sandbox or a substitute for reviewing files and permissions.

Project-local standalone skills depend on Claude Code’s project trust dialog, but the recommended plugin route registers its lifecycle descriptor at startup. Review the plugin and its hooks if your project handles sensitive material. Only the latest released version is supported by the repository’s security policy.

Updating

Inside Claude Code, use the documented plugin update command:

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

Because only the latest release is supported, update before reporting a suspected repository vulnerability or debugging behavior from an old release. After updating, start a new Claude Code session so the current plugin code and hook definitions are loaded.

Uninstalling

Inside Claude Code, remove the plugin with:

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

This removes the plugin integration. The repository does not document that plugin uninstall automatically deletes planning files already created in your projects, so review those ordinary Markdown files separately. Do not use an undocumented cleanup command.

If installation does not work

First run:

claude plugin list

Then check the plugin in Claude Code’s `/plugin` and `/hooks` views. Remember that no startup output is expected in a project without an active plan. Create a plan with `/plan`, start a new session, and run:

/plan-doctor

If the plugin is absent, repeat the two recommended marketplace commands exactly. If it is present but hooks still do not behave as expected, consult the repository’s `docs/troubleshooting.md` or open a GitHub issue at `https://github.com/OthmanAdi/planning-with-files/issues`.

For suspected security vulnerabilities, do not file a public issue first. The repository asks users to report privately through GitHub Private Vulnerability Reporting in its Security tab.