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.

Quick Reference

• Execution Strategies - Detailed guide on parallel, sequential, swarm, and hybrid 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)
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

1. Codebase Understanding: Use Explore agent to understand relevant code
2. Past Patterns: Check if similar tasks have been done before
3. Available Resources: Identify available agents and their capabilities
4. 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

Decision Tree

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

Assignment Principles

1. Match agent capabilities to task requirements
2. Balance workload across agents
3. Consider agent specialization
4. Plan for quality validation

Phase 5: Execution Planning

Create the Execution Plan

## Execution Plan: [Task Name]

### Overview
- Strategy: [Parallel/Sequential/Swarm/Hybrid]
- 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
- [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

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
• All specialized agents (feature-implementer, debugger, test-runner, 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:

1. Pause execution
2. Re-analyze with new information
3. Adjust plan (tasks, dependencies, strategy)
4. 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:

1. Structured Analysis: Understand goals, constraints, and context
2. Intelligent Decomposition: Break into atomic, testable tasks
3. Strategic Execution: Choose optimal execution pattern
4. Quality Assurance: Validate at checkpoints
5. Coordinated Agents: Leverage specialized capabilities
6. Continuous Learning: Improve from each execution

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