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

code

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

markdown

## 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:

markdown

## 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

code

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

code

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

markdown

## 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

markdown

**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

markdown

**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

markdown

## Execution Summary: [Task Name]

### ✓ Completed Tasks
- [Task 1]: Success
- [Task 2]: Success

### 📦 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

code

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

code

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

code

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

markdown

**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

markdown

**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

markdown

**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

markdown

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.