Skip to main content
command CX Codex

plan-goal — Claude Code command: plan file as a /goal condition

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.

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-goal does

The command reads task_plan.md, derives a stop condition from it and passes that text to /goal. Claude Code then runs the agent until a small fast model confirms the condition from the transcript. The check never opens files. That is why the condition comes from the plan: the loop ends on a finished plan file, not on a chat that sounds finished.

Plan selection happens first, through sh ${CLAUDE_PLUGIN_ROOT}/scripts/resolve-plan-dir.sh or resolve-plan-dir.ps1 under PowerShell. More than one plan and no selector returns PWF_PLAN_AMBIGUOUS_V1; the command refuses instead of picking one, so you supply PLAN_ID=<slug>. PWF_PLAN_ROOT pins the project root, and a wrong pin is rejected.

An argument you pass becomes an extra clause. Phase headers and acceptance criteria are the only things quoted into the condition, which keeps it under the 4000-character ceiling /goal enforces. With no task_plan.md there is no goal: you get a refusal pointing at /plan. /goal clear cancels the run.

What it helps with

  • push the agent through the final phase of a plan unattended
  • convert phase checkboxes into something /goal can verify
  • start a long job and walk away from it
  • stop the loop on a completed plan rather than a cheerful transcript

Example prompts for the agent

  • /plan-goal
  • /plan-goal until all tests pass
  • /plan-goal keep working until every phase says complete

How to install plan-goal

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/plan-goal.md

Call it with /plan-goal. For all projects use ~/.claude/commands/

Questions about plan-goal

How do I install plan-goal in Claude Code?

First add the marketplace with /plugin marketplace add OthmanAdi/planning-with-files, then install the plugin: /plugin install planning-with-files@planning-with-files. The command itself sits in .claude/commands/plan-goal.md.

What does plan-goal do?

It turns task_plan.md into a /goal condition: every phase marked complete plus a check-complete.sh pass on that plan path. The agent then keeps working until the condition holds.

What happens when the project has several plans?

The selector prints PWF_PLAN_AMBIGUOUS_V1 and the command stops. Set PLAN_ID=<slug> and run it again.

Source text

plan-goal.md · MIT
---
description: "Bridge Claude Code's /goal to the active plan. Derives a goal condition from task_plan.md and invokes /goal so Claude keeps working until the plan is complete. Available since v2.38.0."
disable-model-invocation: true
allowed-tools: "Read Bash"
---

Bridge the active plan to Claude Code's `/goal` primitive.

Steps:

1. Validate `${PWF_PLAN_ROOT}` as an absolute existing project root when set; refuse an invalid root pin. Otherwise use cwd as the project root. Resolve the selected plan 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 plan. On empty output:
   - With non-empty `${PLAN_ID}`, the plan selector was rejected. Refuse and ask the user to correct the pin; never fall back to another plan.
   - If `resolve-plan-dir.sh --check-ambiguity` (PowerShell: `-CheckAmbiguity`) prints `PWF_PLAN_AMBIGUOUS_V1`, multiple plans exist without a selector. Refuse and ask the user to set `PLAN_ID=<slug>`.
   - Otherwise use legacy `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.
   The shared `.planning/.active_plan` pointer does not bind a parallel session.
2. Read the selected `task_plan.md` and retain its absolute path for the goal condition and completion check.
3. Derive a goal condition from the plan content:
   - Default: "all phases in the selected task_plan.md report Status: complete and check-complete.sh with that explicit plan path reports ALL PHASES COMPLETE"
   - If user passed an argument: use that as an additional clause (e.g., `/plan-goal until all tests pass`)
4. Issue Claude Code's `/goal <condition>` with the derived text.
5. Confirm to the user: print the goal condition + the active plan ID + remind that `/goal clear` cancels.

If `task_plan.md` does not exist, refuse and direct user to run `/plan` first.

Why this exists:

`/goal` runs the agent until a small fast model confirms the condition is met. It evaluates the transcript only, not files. By deriving the condition from the plan file, this command turns the file-based plan into a measurable termination criterion for `/goal`, so the loop terminates when the plan is actually done, not when the conversation looks done.

Notes:

- `/plan-goal` does not replace `/goal`. It composes with it. Users can still run `/goal "any text"` directly.
- The derived condition stays under the 4000-char limit `/goal` enforces by quoting only phase headers + acceptance criteria, not full task body.
- Combine with `/plan-loop` for a "babysit until done" workflow: `/plan-loop` cadence + `/plan-goal` termination.

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

Similar slash commands

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

From the same set14

The whole set →
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-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 plan-loop plan-loop — a planning-aware slash command runs recurring /loop checks against your plan files. Use it when phased work needs a regular progress tick. CX Codex +1 ★ 28,179repo stars planning-with-files planning-with-files keeps a multi-step task plan in three markdown files and pulls the agent back to them every turn, so long sessions hold their context. CX Codex +1 ★ 28,179repo stars planning-with-files planning-with-files saves agent task plans, research notes, and execution logs directly into project markdown files. Useful for multi-step tasks requiring 5 or more tool calls. CX Codex +1 ★ 28,179repo stars

Project sponsors

Companies that keep this analytics open