GOAP Agent Skill

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

Quick Reference

• [Methodology](methodology.md) - Core GOAP planning cycle and phases
• [Execution Strategies](execution-strategies.md) - Parallel, Sequential, Swarm, Hybrid patterns
• [Skills Reference](skills.md) - Available skills by category
• [Agents Reference](agents.md) - Available task agents and capabilities
• [Patterns](patterns.md) - Common GOAP execution patterns
• [Examples](examples.md) - Complete GOAP workflow examples
• [ADR-022](../../../plans/adr/ADR-022-GOAP-Agent-System.md) - 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](skills.md) for complete skills list and [agents.md](agents.md) for agent capabilities.

Core Process

1. ANALYZE → Understand goals, constraints, resources

- Check ADRs: Read relevant ADRs from plans/adr/ before planning

1. 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)

1. STRATEGIZE → Choose execution pattern
2. COORDINATE → Assign to specialized agents
3. EXECUTE → Run with monitoring and quality gates
4. 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](methodology.md) for detailed phase-by-phase guidance and [patterns.md](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