The Goal Module provides Goal-Oriented Action Planning (GOAP) capabilities for dynamically creating intelligent plans to achieve complex objectives. Using gaming AI techniques, it discovers novel solutions by combining actions in creative ways, with adaptive replanning and multi-step reasoning.

# Initialize goal module in current project
npx claude-flow@alpha goal init

# Force overwrite existing module
npx claude-flow@alpha goal init --force

# Install to custom directory
npx claude-flow@alpha goal init --target ./my-agents/goal

Running npx claude-flow@alpha goal init creates:

.claude/agents/goal/
└── goal-planner.md    # Complete GOAP agent definition

• Dynamic Planning: A* search algorithms for optimal paths through state spaces
• Precondition Analysis: Evaluate action requirements and dependencies
• Effect Prediction: Model how actions change world state
• Adaptive Replanning: Adjust plans based on execution results
• Goal Decomposition: Break complex objectives into sub-goals
• Cost Optimization: Find the most efficient path considering action costs
• Novel Solution Discovery: Combine known actions in creative ways
• Mixed Execution: Blend LLM-based reasoning with deterministic code
• Tool Group Management: Match actions to available tools and capabilities
• Domain Modeling: Work with strongly-typed state representations
• Continuous Learning: Update planning strategies based on feedback

• Analyze current world state (what is true now)
• Define goal state (what should be true)
• Identify the gap between current and goal states

• Inventory available actions with their preconditions and effects
• Determine which actions are currently applicable
• Calculate action costs and priorities

• Use A* pathfinding to search through possible action sequences
• Evaluate paths based on cost and heuristic distance to goal
• Generate optimal plan that transforms current state to goal state

• Observe: Monitor current state and execution progress
• Orient: Analyze changes and deviations from expected state
• Decide: Determine if replanning is needed
• Act: Execute next action or trigger replanning

• Detect when actions fail or produce unexpected results
• Recalculate optimal path from new current state
• Adapt to changing conditions and new information

# Create a deployment plan
@agent-goal-planner "Create deployment plan for production"

# Complex multi-step planning
@agent-goal-planner "Plan migration from monolith to microservices architecture"

# Adaptive workflow planning
@agent-goal-planner "Design CI/CD pipeline with automatic rollback capabilities"

@agent-goal-planner "Deploy this application with all dependencies, tests passing, and monitoring enabled"

The agent will generate a plan like:

1. Analyze dependencies (enables: dependencies_known)
2. Install dependencies (requires: dependencies_known, enables: dependencies_installed)
3. Write tests (requires: dependencies_installed, enables: tests_written)
4. Run tests (requires: tests_written, enables: tests_passed)
5. Build application (requires: tests_passed, enables: built)
6. Deploy application (requires: built, enables: deployed)
7. Setup monitoring (requires: deployed, enables: monitoring_active)

@agent-goal-planner "Refactor legacy codebase to modern architecture with full test coverage"

The agent will plan:

1. Analyze codebase (enables: understood)
2. Write tests for legacy code (enables: tested)
3. Document current behavior (enables: documented)
4. Plan refactoring strategy (requires: documented, tested, enables: plan_ready)
5. Execute refactoring (requires: plan_ready, enables: refactored)
6. Verify tests pass (requires: refactored, tested, validates goal)

• A Pathfinding*: 0.1-1.1ms for typical plans
• State Evaluation: Real-time processing
• Replanning: Dynamic adaptation in <500ms

• LLM Actions: Creative tasks, natural language processing
• Code Actions: Deterministic operations, calculations
• Hybrid Actions: Combined AI reasoning with code execution

• Parallel Action Identification: Detect concurrent execution opportunities
• Cost Analysis: Optimize for time, resources, or custom metrics
• Heuristic Tuning: Adjustable planning strategies

# Combine planning with learning
@agent-goal-planner "Create deployment strategy"
@agent-safla-neural "Learn from deployment outcomes and improve future plans"

# Distributed execution of planned tasks
@agent-goal-planner "Break down project into parallel tasks"
# Then use swarm to execute in parallel

Based on extensive testing, the GOAP module has proven capabilities in:

1. A Pathfinding*

   • Heuristic-based optimal path finding
   • Cost function: f(n) = g(n) + h(n)
   • Plans found in 0.1-1.1ms with optimal costs

2. OODA Loop Execution

   • Real-time state monitoring
   • Dynamic deviation detection
   • Automatic replanning triggers
   • Execution cycle tracking

3. Adaptive Replanning

   • Security requirements added mid-execution
   • New action integration without restart
   • Goal state modification support
   • Seamless plan updates

4. Mixed Execution Strategies

   • LLM Tasks: Code generation, documentation
   • Code Tasks: Testing, deployment, compilation
   • Hybrid Tasks: Security analysis, optimization

5. Complex Scenarios

   • Web application deployment pipelines
   • Infrastructure provisioning workflows
   • CI/CD automation with rollback
   • Microservices orchestration

All GOAP agent capabilities and configuration are built into the agent definition itself in goal-planner.md. No separate configuration files are needed.

1. Module Already Exists

   npx claude-flow@alpha goal init --force

2. Custom Directory Setup

   npx claude-flow@alpha goal init --target ./custom/agents/goal

3. Planning Takes Too Long

   • Simplify goal states
   • Break complex goals into sub-goals
   • Use hierarchical planning for complex scenarios

1. Goal Definition

   • Be specific about desired end states
   • Include measurable success criteria
   • Consider intermediate checkpoints

2. Action Design

   • Keep actions atomic and focused
   • Define clear preconditions and effects
   • Assign realistic cost values

3. Replanning Strategy

   • Set appropriate replanning thresholds
   • Monitor for infinite replanning loops
   • Log replanning decisions for debugging

The GOAP system has been extensively tested with these demonstrations:

• goap-planner.js - Core GOAP engine implementation
• goap-final-demo.js - Comprehensive demonstration
• working-goap-demo.js - Working examples
• interactive-goap.js - Interactive simulator
• deployment-scenario.js - Real-world deployment cases
• README-GOAP.md - Complete technical documentation

• Explore Neural Module for self-learning systems
• Learn about Swarm Coordination
• Read Agent System Overview
• View SPARC Methodology

Goal Module v1.0.0 - Part of Claude Flow Enterprise Platform