Skip to main content
command CX Codex

plan · othmanadi — Claude Code command: what it does, how to install

Starts Manus-style file-based planning for complex engineering workflows. Generates task_plan.md, findings.md, and progress.md or restores an active session.

MIT ★ 28,179 updated 2026-11-04

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files
Open on GitHub

What plan does

Running this command invokes the planning-with-files:planning-with-files skill and inspects existing project directories. It detects the target directory using resolve-plan-dir.sh (or resolve-plan-dir.ps1 on PowerShell). If an active directory is found, the agent reads task_plan.md, findings.md, and progress.md without rewriting earlier progress.

Starting a fresh task triggers init-session.sh to create an isolated .planning/<id>/ directory. Each file serves a distinct role: task_plan.md stores phases and decisions, findings.md holds technical discoveries, and progress.md tracks execution history. Every ### Phase N: Name heading must contain exactly one **Status:** line.

The plan layout is verified by check-complete.sh --validate. If multiple plan directories exist without a selection, the script stops with PWF_PLAN_AMBIGUOUS_V1, requiring PLAN_ID=<slug> to pinpoint the active plan.

What it helps with

  • break down multi-step tasks into phases tracked in task_plan.md
  • store research notes in findings.md without cluttering source code
  • log ongoing agent execution details inside progress.md
  • resume interrupted work sessions without overwriting active plans

Example prompts for the agent

  • /plan
  • /planning-with-files:plan
  • Start task planning with /plan

How to install plan

1Plugin marketplace

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

2Manually: put the files in place

.claude/commands/planning-with-files-plan.md

The built-in /plan overrides a file with the same name, so the file is renamed. Call it with /planning-with-files-plan. For all projects use ~/.claude/commands/

Questions about plan

How to install plan in Claude Code?

Add the repository using /plugin marketplace add OthmanAdi/planning-with-files, then run /plugin install planning-with-files@planning-with-files.

What does the plan command do?

It coordinates file-backed session planning by managing task_plan.md, findings.md, and progress.md. This maintains structured context across execution phases.

What happens if multiple plans exist in the workspace?

The resolve-plan-dir.sh check flags PWF_PLAN_AMBIGUOUS_V1 and pauses execution. You must set PLAN_ID=<slug> so the command targets the exact plan directory.

Source text

plan.md · MIT
---
description: "Start Manus-style file-based planning. Creates task_plan.md, findings.md, progress.md for complex tasks."
---

Invoke the planning-with-files:planning-with-files skill and follow it exactly as presented to you.

Restore before creating. If `PWF_PLAN_ROOT` is set, validate it as an absolute existing project root; refuse an invalid root pin before reading or creating files. Otherwise the project root is the current directory. Resolve the selected task with `sh ${CLAUDE_PLUGIN_ROOT}/scripts/resolve-plan-dir.sh` (PowerShell: `& "$env:CLAUDE_PLUGIN_ROOT\scripts\resolve-plan-dir.ps1"`):
- A printed directory is the selected task. Resume it: read its `task_plan.md`, `findings.md`, and `progress.md` and preserve them; never overwrite existing planning files.
- Empty output with non-empty `PLAN_ID` means the plan selector was rejected. Stop and ask the user to correct the pin. Do not fall back to the root or another plan.
- Empty output where `resolve-plan-dir.sh --check-ambiguity` (PowerShell: `-CheckAmbiguity`) prints `PWF_PLAN_AMBIGUOUS_V1` means multiple plans exist without a selector. Stop and ask the user to set `PLAN_ID=<slug>`.
- Otherwise empty output is the legacy project-root convention: resume `task_plan.md` from the validated project root (`PWF_PLAN_ROOT` when set), if it exists. A valid root pin alone does not reject a legacy root plan.

Only for a new task, run the initializer from the validated project root, including when `PWF_PLAN_ROOT` points away from the host cwd: `sh ${CLAUDE_PLUGIN_ROOT}/scripts/init-session.sh` (PowerShell: `init-session.ps1`). Pass a task name for an isolated `.planning/<id>/` plan and pin the host with its printed `PLAN_ID`. `.planning/.active_plan` is a shared default; it does not bind a parallel session.
- `task_plan.md`: for phases, progress, and decisions
- `findings.md`: for research and discoveries
- `progress.md`: for session logging

Keep each `### Phase N: Name` heading with exactly one `**Status:**` line, then validate the selected plan's explicit path with `sh ${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.sh --validate path/to/task_plan.md` (PowerShell: `check-complete.ps1 -Validate -PlanFile path/to/task_plan.md`). If an existing plan fails validation, report it instead of rewriting it.

Then guide the user through the planning workflow.

© OthmanAdi · MIT · OthmanAdi/planning-with-files

Similar slash commands

All slash commands for Agent setup: memory, context, orchestration →

plan by other authors comes first.

plan OthmanAdi Loads the planning-with-files skill and starts planning in the current project. Handy when you want to begin a new plan or continue an existing one. CX Codex +1 ★ 28,179repo stars plan Affaan Mustafa Command invokes a planner sub-agent that breaks down the task into phases, assesses risks, and waits for confirmation before touching any code. CX Codex +1 ★ 6,739repo stars plan disler Turns a task description into a step-by-step implementation plan saved under specs/. Useful when a feature needs thinking through before any code. CX Codex +1 ★ 3,990repo stars plan CloudAI-X Creates and maintains a structured PLAN.md file in your project root to track phases, task dependencies, and progress logs. CX Codex +1 ★ 1,424repo stars plan OthmanAdi Creates task_plan.md, findings.md and progress.md in the project root, so the goal, research and session log sit next to the code. CX Codex +1 ★ 540repo stars speckit-tasks github-spec-kit speckit-tasks is a Claude Code skill that builds an actionable, dependency-ordered tasks.md from feature design docs. Runs during the project planning phase. CX Codex +1 2,500installs screenshot-synthesizer davila7 screenshot-synthesizer merges UI, interaction, and business analysis results into a single Markdown development task checklist. CX Codex 346installs ce-plan EveryInc ce-plan builds structured technical implementation plans without touching production code. Useful when scoping features before passing work to execution agents. CX Codex +1 4,000installs speckit-plan github-spec-kit speckit-plan executes implementation planning workflows inside spec-kit projects to produce research notes and interface contracts. CX Codex +1 2,600installs re0-plan LilMGenius The re0-plan Claude Code skill creates a paperthin iteration folder and seeds it with planning files. It runs on request when a new build cycle starts in the repository. CX Codex +1 1,400installs plan-task NeoLabHQ plan-task turns a rough task spec into a plan with acceptance criteria, an architecture overview and verifiable phases, each gated by a judge. CX Codex +1 1,300installs

From the same set14

The whole set →
planning-with-files planning-with-files keeps a task plan, findings and progress in project Markdown files. It suits agent work that needs 5+ tool calls. CX Codex +1 49,300installs plan Loads the planning-with-files skill and starts planning in the current project. Handy when you want to begin a new plan or continue an existing one. CX Codex +1 ★ 28,179repo stars pwf pwf is a Claude Code command that plans tasks through three project files. The agent invokes it for a request to map out work. CX Codex +1 ★ 28,179repo stars pwf The pwf command sets up the planning-with-files workflow, generating a task plan, findings log and progress file for the current project. CX Codex +1 ★ 28,179repo stars status Displays current task phases, completion percentage, and errors from task_plan.md. Runs when you need a quick status check without loading companion files into context. CX Codex +1 ★ 28,179repo stars plan-doctor The plan-doctor command for Claude Code checks planning-with-files plan lookup, injection, and attestation. Run it when hooks go silent or on a new machine. CX Codex +1 ★ 28,179repo stars plan-goal plan-goal builds a completion condition out of task_plan.md and feeds it to /goal, so the agent keeps moving through the whole plan. CX Codex +1 ★ 28,179repo stars plan-attest plan-attest locks the active task_plan.md file using a SHA-256 hash. Built-in hooks prevent plan injection into model prompts whenever the file content diverges from the attested hash. CX Codex +1 ★ 28,179repo stars

More in the catalog

Project sponsors

Companies that keep this analytics open