# goal-planner

goal-planner — a GOAP planner subagent that turns a goal into an ordered set of actions and reworks the plan when a step fails.

- subagent · `type=agent` · Claude Code, Codex, Cursor · ★ 850 repo stars
- Author: ruvnet
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/ruvnet/agentic-flow/tree/HEAD/.claude/agents/goal/goal-planner.md
- Updated: 2026-10-26
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/agents/goal-planner

## What it does

This subagent treats planning as a search problem. You give it the current state and the state you want; each action carries preconditions, effects and a price. An A* search then picks the sequence with the lowest total cost rather than the first one that happens to fit.

Scope is what separates the modes: run one action, plan inside a fixed set of actions, or roam across everything available and split a large objective into smaller ones. Once execution starts, results get compared against the expected state on an OODA loop and the route is recalculated on a mismatch. A step can be handed to code, to the model, or to a blend of both, and an action may name tool groups such as `grep` or a profiler plus a fallback for when they are missing.

What the search works on is preconditions you can verify and effects that show up in the state. Loose action definitions give you a plan built on guesswork. The agent file lives at `.claude/agents/goal-planner.md`.

## Install

### Claude Code (native platform)

**Manually: put the files in place**
- File: `.claude/agents/goal-planner.md` — For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

### Codex

**Manually: put the files in place**
- File: `.codex/agents/goal-planner.toml` — Codex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/

### Cursor

**Manually: put the files in place**
- File: `.cursor/agents/goal-planner.md` — Cursor also reads .claude/agents/

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/ruvnet/agentic-flow/tree/HEAD/.claude/agents/goal/goal-planner.md

## When to use it
- break a vague goal like getting an app production-ready into ordered steps
- spot which preconditions block a deploy before running it
- rebuild the plan when one step fails or returns something unexpected
- pick the cheapest route when several action sequences reach the goal
- tie each action to the tools it needs, with a fallback if they are absent

## Example prompts
- Use the goal-planner subagent to map out a deploy plan with all its dependencies.
- Have goal-planner split “make the legacy module production-ready” into steps with checks.
- Ask goal-planner to replan after the test run fails.

## Similar
- [goal-plan](https://affpapa.org/en/nevibecode/skills/goal-plan.md) — skill · 771 installs
- [financial-goal-planner](https://affpapa.org/en/nevibecode/skills/financial-goal-planner.md) — skill · 373 installs
- [plannotator-setup-goal](https://affpapa.org/en/nevibecode/skills/plannotator-setup-goal.md) — skill · 13600 installs
- [plan-goal](https://affpapa.org/en/nevibecode/commands/plan-goal.md) — command · ★ 28179 repo stars
- [goal-setting-okrs](https://affpapa.org/en/nevibecode/skills/goal-setting-okrs.md) — skill · 538 installs
- [swarm-planner](https://affpapa.org/en/nevibecode/skills/swarm-planner.md) — skill · 1200 installs

From the same set: [ruvnet/agentic-flow](https://affpapa.org/en/nevibecode/by/ruvnet/agentic-flow.md) — 76 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
