goap-agent

name	goap-agent
description	Invoke for complex multi-step tasks requiring intelligent planning and multi-agent coordination. Use when tasks need decomposition, dependency mapping, parallel/sequential/swarm/iterative execution strategies, or coordination of multiple specialized agents.

GOAP Agent Skill

Goal-Oriented Action Planning for complex multi-step tasks with intelligent planning and multi-agent coordination.

Quick Reference

• Methodology - Core GOAP planning cycle and phases
• Execution Strategies - Parallel, Sequential, Swarm, Hybrid patterns
• Skills Reference - Available skills by category
• Agents Reference - Available task agents and capabilities
• Patterns - Common GOAP execution patterns
• Examples - Complete GOAP workflow examples
• ADR-022 - Architecture Decision Record

When to Use

• Complex multi-step tasks (5+ distinct steps)
• Cross-domain problems (storage, API, testing, documentation)
• Tasks requiring parallel/sequential execution
• Quality-critical work with validation checkpoints
• Large refactors or architectural changes

CRITICAL: Skills vs Task Agents

Skills (via Skill tool): Instruction sets that guide Claude directly Agents (via Task tool): Autonomous sub-processes that execute tasks

Example:

• WRONG: Task(subagent_type="code-quality", ...) → ERROR!
• CORRECT: Skill(command="code-quality") → SUCCESS

See skills.md for complete skills list and agents.md for agent capabilities.

Core Process

1. ANALYZE → Understand goals, constraints, resources
   • Check ADRs: Read relevant ADRs from plans/adr/ before planning
2. DECOMPOSE → Break into atomic tasks with dependencies
   • Task Decomposition: Create goal hierarchy with success criteria (see patterns.md)
   • Dependency Types: Sequential (A→B), Parallel (A─┐B─┐), Converging (A─┐B─┼─>D)
3. STRATEGIZE → Choose execution pattern
4. COORDINATE → Assign to specialized agents
5. EXECUTE → Run with monitoring and quality gates
6. SYNTHESIZE → Aggregate results and validate success

PR Monitoring Guardrail

• During EXECUTE/SYNTHESIZE for PR work, always verify statusCheckRollup on the latest head SHA.
• Treat an empty required-check rollup as a blocker and document it in plans/STATUS/VALIDATION_LATEST.md.
• Avoid adding plans-only follow-up commits until remediation checks are attached.

See methodology.md for detailed phase-by-phase guidance and patterns.md for common execution patterns.

ADR Integration Workflow

MANDATORY: Always check ADRs in plans/adr/ before creating execution plans:

Step 1: ADR Discovery

# List all ADRs to identify relevant ones
ls plans/adr/ADR-*.md

Step 2: Read Relevant ADRs

• Search for ADRs related to your task domain
• Note architectural decisions and constraints
• Check ADR status (Accepted/Implemented vs Deprecated)

Step 3: Incorporate into Planning

• Use ADR constraints when decomposing tasks
• Reference ADRs in execution plans
• Ensure compliance with architectural decisions

Step 4: Update Progress in plans/

• Create/update execution plan files in plans/
• Document progress, blockers, and decisions
• Link to relevant ADRs in plan files