GOAP Agent Skill: Goal-Oriented Action Planning

Enable intelligent planning and execution of complex multi-step tasks through systematic decomposition, dependency mapping, and coordinated multi-agent execution.

Always use the plans/ folder for all files.

Quick Reference

• Execution Strategies - Detailed guide on parallel, sequential, swarm, hybrid, and iterative execution patterns

When to Use This Skill

Use this skill when facing:

• Complex Multi-Step Tasks: Tasks requiring 5+ distinct steps or multiple specialized capabilities

• Cross-Domain Problems: Issues spanning multiple areas (storage, API, testing, documentation)

• Optimization Opportunities: Tasks that could benefit from parallel or hybrid execution

• Quality-Critical Work: Projects requiring validation checkpoints and quality gates

• Resource-Intensive Operations: Large refactors, migrations, or architectural changes

• Ambiguous Requirements: Tasks needing structured analysis before execution

Core GOAP Methodology

The GOAP Planning Cycle

1. ANALYZE → Understand goals, constraints, resources
2. DECOMPOSE → Break into atomic tasks with dependencies
3. STRATEGIZE → Choose execution pattern (parallel/sequential/swarm/hybrid/iterative)
4. COORDINATE → Assign tasks to specialized agents
5. EXECUTE → Run with monitoring and quality gates
6. SYNTHESIZE → Aggregate results and validate success

Phase 1: Task Analysis

Initial Assessment

Task Analysis

Primary Goal: [Clear statement of what success looks like]

Constraints:

• Time: [Urgent / Normal / Flexible]
• Resources: [Available agents, tools, data]
• Dependencies: [External systems, prerequisites]

Complexity Level:

• Simple: Single agent, <3 steps
• Medium: 2-3 agents, some dependencies
• Complex: 4+ agents, mixed execution modes
• Very Complex: Multiple phases, many dependencies

Quality Requirements:

• Testing: [Unit / Integration / E2E]
• Standards: [AGENTS.md compliance, formatting, linting]
• Documentation: [API docs, examples, guides]
• Performance: [Speed, memory, scalability]

Context Gathering

• Codebase Understanding: Use Explore agent to understand relevant code

• Past Patterns: Check if similar tasks have been done before

• Available Resources: Identify available agents and their capabilities

• Current State: Understand starting conditions and existing implementations

Phase 2: Task Decomposition

Use the task-decomposition skill to break down the goal:

Task Decomposition: [Task Name]

Main Goal

[Clear statement of primary objective]

Sub-Goals

1. [Component 1] - Priority: P0

   • Success Criteria: [How to verify]
   • Dependencies: [Prerequisites]
   • Complexity: [Low/Medium/High]

2. [Component 2] - Priority: P1

   • Success Criteria: [How to verify]
   • Dependencies: [Component 1]
   • Complexity: [Low/Medium/High]

Atomic Tasks

Component 1: [Name]

• Task 1.1: [Action] (Agent: type, Deps: none)
• Task 1.2: [Action] (Agent: type, Deps: 1.1)

Dependency Graph

Task 1.1 → Task 1.2 → Task 2.1 ↘ Task 1.3 (parallel) → Task 2.2

Key Decomposition Principles

• Atomic: Each task is indivisible and clear

• Testable: Can verify completion

• Independent where possible: Minimize dependencies

• Assigned: Each task maps to an agent capability

Phase 3: Strategy Selection

Choose execution strategy based on task characteristics. See execution-strategies.md for detailed guide.

Quick Strategy Guide

Strategy When to Use Speed Complexity

Parallel Independent tasks, time-critical Nx High

Sequential Dependent tasks, order matters 1x Low

Swarm Many similar tasks ~Nx Medium

Hybrid Mixed requirements 2-4x Very High

Iterative Progressive refinement, convergence Varies Medium

Decision Tree

Needs iterative refinement? ├─ Yes (until criteria met or converged) → ITERATIVE └─ No → Is time critical? ├─ Yes → Can tasks run in parallel? │ ├─ Yes → PARALLEL │ └─ No → SEQUENTIAL (prioritize critical path) └─ No → Are tasks similar? ├─ Yes (many similar) → SWARM ├─ No (mixed) → HYBRID └─ Simple linear → SEQUENTIAL

Phase 4: Agent Assignment

Agent Capability Matrix

Agent Type Capabilities Best For

feature-implementer Design, implement, test features New functionality

debugger Diagnose, fix runtime issues Bug fixes, performance

test-runner Execute tests, diagnose failures Test validation

refactorer Improve code quality, structure Code improvements

code-reviewer Review quality, compliance Quality assurance

loop-agent Iterative refinement, convergence detection Progressive improvements

Assignment Principles

• Match agent capabilities to task requirements

• Balance workload across agents

• Consider agent specialization

• Plan for quality validation

Phase 5: Execution Planning

Create the Execution Plan

Execution Plan: [Task Name]

Overview

• Strategy: [Parallel/Sequential/Swarm/Hybrid/Iterative]
• Total Tasks: [N]
• Estimated Duration: [Time]
• Quality Gates: [N checkpoints]

Phase 1: [Phase Name]

Tasks:

• Task 1: [Description] (Agent: type)
• Task 2: [Description] (Agent: type)

Quality Gate: [Validation criteria]

Phase 2: [Phase Name]

Tasks:

• Task 3: [Description] (Agent: type)

Quality Gate: [Validation criteria]

Overall Success Criteria

• All tasks complete
• Quality gates passed
• Tests passing
• Documentation updated

Contingency Plans

• If Phase 1 fails → [Recovery plan]
• If tests fail → [Diagnostic approach]

Phase 6: Coordinated Execution

Parallel Execution

Launching parallel agents:

• Agent 1 (feature-implementer) → Task A
• Agent 2 (feature-implementer) → Task B
• Agent 3 (test-runner) → Task C

Coordination:

• All agents work simultaneously
• Monitor progress independently
• Aggregate results when all complete

Sequential Execution

Launching sequential agents: Phase 1: Agent 1 (debugger) → Diagnose issue ↓ Quality Gate: Root cause identified Phase 2: Agent 2 (refactorer) → Apply fix ↓ Quality Gate: Tests pass Phase 3: Agent 3 (code-reviewer) → Validate

Monitoring During Execution

• Track agent progress

• Monitor for failures

• Validate intermediate results

• Adjust plan if needed

Phase 7: Result Synthesis

Aggregate Results

Execution Summary: [Task Name]

✓ Completed Tasks

📦 Deliverables

• [File/Feature 1]
• [File/Feature 2]

✅ Quality Validation

• Tests: [Pass/Fail] ([coverage]%)
• Linting: [Pass/Fail]
• Standards: [Compliant]

📊 Performance Metrics

• Duration: [actual vs estimated]
• Efficiency: [parallel speedup if applicable]

💡 Recommendations

• [Improvement 1]
• [Improvement 2]

🎓 Lessons Learned

• [What worked well]
• [What to improve]

Common GOAP Patterns

Pattern 1: Research → Implement → Validate

Phase 1 (Sequential): Research

• Explore agent → Understand codebase
• Quality Gate: Architecture documented

Phase 2 (Parallel): Implement

• feature-implementer (A) → Module 1
• feature-implementer (B) → Module 2
• Quality Gate: Implementations complete

Phase 3 (Sequential): Validate

• test-runner → All tests
• code-reviewer → Final review
• Quality Gate: Ready for merge

Pattern 2: Investigate → Diagnose → Fix → Verify

Phase 1: Investigate

• debugger → Reproduce issue
• Quality Gate: Issue reproduced

Phase 2: Diagnose

• debugger → Root cause analysis
• Quality Gate: Root cause identified

Phase 3: Fix

• refactorer → Apply fix
• Quality Gate: Fix implemented

Phase 4: Verify

• test-runner → Regression tests
• Quality Gate: Tests pass

Pattern 3: Audit → Improve → Validate

Phase 1: Audit

• code-reviewer → Quality audit
• Quality Gate: Issues identified

Phase 2 (Swarm): Improve

• Multiple refactorer agents
• Work queue: [issue list]
• Quality Gate: All issues addressed

Phase 3: Validate

• test-runner → Full test suite
• code-reviewer → Final check
• Quality Gate: Quality targets met

Error Handling & Recovery

Agent Failure Recovery

If agent fails:

1. Log failure reason
2. Check quality gate status
3. Options:
   • Retry same agent (transient error)
   • Assign to different agent (agent issue)
   • Modify task (requirements issue)
   • Escalate to user (blocking issue)

Quality Gate Failure

If quality gate fails:

1. Identify failing criteria
2. Diagnose root cause
3. Options:
   • Re-run previous phase with fixes
   • Adjust quality criteria (if appropriate)
   • Change strategy (e.g., parallel → sequential for debugging)

Blocked Dependencies

If dependency blocks progress:

1. Identify blocking task
2. Prioritize unblocking
3. Options:
   • Execute dependency first (re-order)
   • Remove dependency (refactor plan)
   • Parallel work on independent tasks

Best Practices

DO:

✓ Break tasks into atomic, testable units ✓ Define clear quality gates between phases ✓ Match agent capabilities to task requirements ✓ Monitor progress and validate incrementally ✓ Document decisions and rationale ✓ Learn from execution for future planning ✓ Use parallel execution where safe ✓ Validate dependencies before execution

DON'T:

✗ Create monolithic tasks (break them down) ✗ Skip quality gates (leads to cascading failures) ✗ Assume tasks are independent (verify carefully) ✗ Ignore agent failures (address immediately) ✗ Over-complicate simple tasks (use sequential) ✗ Under-estimate coordination overhead ✗ Forget to aggregate and synthesize results

Integration with Other Skills

• task-decomposition: Use for Phase 2 (breaking down complex goals)

• agent-coordination: Use for Phase 6 (coordinating multiple agents)

• parallel-execution: Use for parallel strategy implementation

• loop-agent: Use for iterative refinement strategy implementation

• All specialized agents (feature-implementer, debugger, test-runner, frontend-design-system, playwright-skill, etc.)

Quick Example

Task: Implement authentication system

GOAP Plan

Phase 1: Analysis (Sequential)

• goap-agent → Define requirements
• Quality Gate: Requirements clear

Phase 2: Implementation (Parallel)

• Agent A → User model + database
• Agent B → Auth middleware
• Agent C → API endpoints
• Quality Gate: All components implemented

Phase 3: Integration (Sequential)

• feature-implementer → Wire components together
• test-runner → Integration tests
• Quality Gate: Tests pass

Phase 4: Validation (Sequential)

• code-reviewer → Security review
• Quality Gate: Approved for deployment

Success Metrics

Planning Quality

• Clear decomposition with measurable tasks

• Realistic time estimates

• Appropriate strategy selection

• Well-defined quality gates

Execution Quality

• Tasks completed as planned

• Quality gates passed

• Minimal re-work required

• Efficient resource utilization

Learning

• Document what worked well

• Identify improvement areas

• Update patterns for future use

• Share knowledge with team

Advanced Topics

Dynamic Re-Planning

If during execution:

• Dependencies change

• Requirements clarified

• Blockers discovered

• Performance issues found

Then:

• Pause execution

• Re-analyze with new information

• Adjust plan (tasks, dependencies, strategy)

• Resume with updated plan

Optimization Techniques

• Critical path optimization: Parallelize non-critical-path tasks

• Resource pooling: Share agents across similar tasks

• Incremental delivery: Complete and validate phases incrementally

• Adaptive strategy: Switch strategies based on progress

Summary

GOAP enables systematic planning and execution of complex tasks through:

• Structured Analysis: Understand goals, constraints, and context

• Intelligent Decomposition: Break into atomic, testable tasks

• Strategic Execution: Choose optimal execution pattern

• Quality Assurance: Validate at checkpoints

• Coordinated Agents: Leverage specialized capabilities

• Continuous Learning: Improve from each execution

Use GOAP when facing complex, multi-step challenges requiring coordination, optimization, and quality assurance.