One-Line Summary: GOAP is a planning technique borrowed from game AI where the agent searches a graph of available actions for a sequence whose preconditions and effects connect the current world state to a goal — used in modern harnesses as a structured alternative to free-form chain-of-thought planning.
Prerequisites: Plan-and-execute, ReAct pattern, agent state management
Status: Module 04 anchor concept — first draft. Authoring backlog: bespoke
WalkthroughAHOGoalOrientedActionPlanning(A* search visualization with replanning) per the plan file.
What Is Goal-Oriented Action Planning?
GOAP comes from the games industry — F.E.A.R. (2005) is the canonical reference — where designers needed NPC behavior that looked plausible without hand-authoring every script. The trick: declare each action as a triple of (preconditions, effects, cost), declare the goal as a target world state, and let an A* search find the lowest-cost action sequence that produces it. Agents pick a plan that makes sense given what they can do and what they need to achieve, and they re-plan when reality diverges from the model.
In a harness setting, GOAP recurs because LLM planning is unreliable in long horizons. A model can produce a 10-step plan that sounds coherent and silently violates a precondition halfway through. GOAP replaces the LLM-as-planner with structured search over a tool/skill graph that the LLM only contributes to (proposing actions, scoring states), not arbitrates alone.
How It Works
Each available tool or skill is annotated with preconditions (what must be true to use it) and effects (what becomes true after). A planner — typically A* — searches from the current world state to the goal state through this action graph. The result is a sequence of actions with verified preconditions. When execution diverges (a tool fails, a precondition is violated), the planner re-plans from the new state. Ruflo's ruflo-goals plugin is a production implementation of this pattern; LangGraph users frequently write equivalent logic by hand on top of StateGraph.
Why It Matters
Free-form planning by an LLM gets worse with horizon length. Structured planning over a typed action graph is bounded by the graph, not the model's attention, so it scales differently. The cost is upfront work: every tool needs precondition/effect annotations, which is exactly the kind of contract most agent codebases avoid writing.
How Harnesses & Frameworks Implement This
| Harness / Framework | GOAP support | Mechanism |
|---|---|---|
| Claude Code | None natively | Implement as plugin |
| Claude Agent SDK | None natively | Custom planner |
| ruflo | First-class — ruflo-goals plugin | A* over annotated actions, adaptive replanning |
| LangGraph | DIY — graph nodes can encode preconditions | Use conditional edges as guards |
| AutoGen | None natively | Custom |
| CrewAI | Sequential/hierarchical only | N/A |
| OpenAI Agents SDK | None natively | DIY |
| Codex CLI | Implicit "plan mode" but not GOAP | LLM-driven, not search |
| Cursor | None | N/A |
Connections to Other Concepts
a-star-planner-for-agents.md— The search algorithm at GOAP's core.adaptive-replanning.md— How GOAP re-plans when reality diverges.plan-rollback-and-checkpointing.md— Recovery when re-planning from a corrupted state.plan-driven-vs-reactive-harnesses.md— Where GOAP-style planning sits on the spectrum.../../multi-skill-agent/05-task-decomposition-and-planning/plan-and-execute.md— Foundational coverage.
Further Reading
- Jeff Orkin, "Three States and a Plan: The A.I. of F.E.A.R." (2006) — The original GOAP paper from games.
- ruvnet, ruflo-goals documentation — Modern GOAP applied to agents.