Goal Seeking Agent Pattern

Goal-Seeking Agent Pattern Skill

1. What Are Goal-Seeking Agents?

Goal-seeking agents are autonomous AI agents that execute multi-phase objectives by:

1. Understanding High-Level Goals: Accept natural language objectives without explicit step-by-step instructions
2. Planning Execution: Break goals into phases with dependencies and success criteria
3. Autonomous Execution: Make decisions and adapt behavior based on intermediate results
4. Self-Assessment: Evaluate progress against success criteria and adjust approach
5. Resilient Operation: Handle failures gracefully and explore alternative solutions

Core Characteristics

Autonomy: Agents decide HOW to achieve goals, not just follow prescriptive steps

Adaptability: Adjust strategy based on runtime conditions and intermediate results

Goal-Oriented: Focus on outcomes (what to achieve) rather than procedures (how to achieve)

Multi-Phase: Complex objectives decomposed into manageable phases with dependencies

Self-Monitoring: Track progress, detect failures, and course-correct autonomously

Distinction from Traditional Agents

When Goal-Seeking Makes Sense

Goal-seeking agents excel when:

• Problem space is large: Many possible paths to success
• Context varies: Runtime conditions affect optimal approach
• Failures are expected: Need autonomous recovery without human intervention
• Objectives are clear: Success criteria well-defined but path is flexible
• Multi-step complexity: Requires coordination across phases with dependencies

When to Avoid Goal-Seeking

Use traditional agents or scripts when:

• Single deterministic path: Only one way to achieve goal
• Latency-critical: Need fastest possible execution (no decision overhead)
• Safety-critical: Human verification required at each step
• Simple workflow: Complexity of goal-seeking exceeds benefit
• Audit requirements: Need deterministic, reproducible execution

2. When to Use This Pattern

Problem Indicators

Use goal-seeking agents when you observe these patterns:

Pattern 1: Workflow Variability

Indicators:

• Same objective requires different approaches based on context
• Manual decisions needed at multiple points
• "It depends" answers when mapping workflow

Example: Release workflow that varies by:

• Environment (staging vs production)
• Change type (hotfix vs feature)
• Current system state (healthy vs degraded)

Solution: Goal-seeking agent evaluates context and adapts workflow

Pattern 2: Multi-Phase Complexity

Indicators:

• Objective requires 3-5+ distinct phases
• Phases have dependencies (output of phase N feeds phase N+1)
• Parallel execution opportunities exist
• Success criteria differ per phase

Example: Data pipeline with phases:

1. Data collection (multiple sources, parallel)
2. Transformation (depends on collection results)
3. Validation (depends on transformation output)
4. Publishing (conditional on validation pass)

Solution: Goal-seeking agent orchestrates phases, handles dependencies

Pattern 3: Autonomous Recovery Needed

Indicators:

• Failures are expected and recoverable
• Multiple retry/fallback strategies exist
• Human intervention is expensive or slow
• Can verify success programmatically

Example: CI diagnostic workflow:

• Test failures (retry with different approach)
• Environment issues (reconfigure and retry)
• Dependency conflicts (resolve and rerun)

Solution: Goal-seeking agent tries strategies until success or escalation

Pattern 4: Adaptive Decision Making

Indicators:

• Need to evaluate trade-offs at runtime
• Multiple valid solutions with different characteristics
• Optimization objectives (speed vs quality vs cost)
• Context-dependent best practices

Example: Fix agent pattern matching:

• QUICK mode for obvious issues
• DIAGNOSTIC mode for unclear problems
• COMPREHENSIVE mode for complex solutions

Solution: Goal-seeking agent selects strategy based on problem analysis

Pattern 5: Domain Expertise Required

Indicators:

• Requires specialized knowledge to execute
• Multiple domain-specific tools/approaches
• Best practices vary by domain
• Coordination of specialized sub-agents

Example: AKS SRE automation:

• Azure-specific operations (ARM, CLI)
• Kubernetes expertise (kubectl, YAML)
• Networking knowledge (CNI, ingress)
• Security practices (RBAC, Key Vault)

Solution: Goal-seeking agent with domain expertise coordinates specialized actions

Decision Framework

Use this 5-question framework to evaluate goal-seeking applicability:

Question 1: Is the objective well-defined but path flexible?

YES if:

• Clear success criteria exist
• Multiple valid approaches
• Runtime context affects optimal path

NO if:

• Only one correct approach
• Path is deterministic
• Success criteria ambiguous

Example YES: "Ensure AKS cluster is production-ready" (many paths, clear criteria) Example NO: "Run specific kubectl command" (one path, prescriptive)

Question 2: Are there multiple phases with dependencies?

YES if:

• Objective naturally decomposes into 3-5+ phases
• Phase outputs feed subsequent phases
• Some phases can execute in parallel
• Failures in one phase affect downstream phases

NO if:

• Single-phase execution sufficient
• No inter-phase dependencies
• Purely sequential with no branching

Example YES: Data pipeline (collect → transform → validate → publish) Example NO: Format code with ruff (single atomic operation)

Question 3: Is autonomous recovery valuable?

YES if:

• Failures are common and expected
• Multiple recovery strategies exist
• Human intervention is expensive/slow
• Can verify success automatically

NO if:

• Failures are rare edge cases
• Manual investigation always required
• Safety-critical (human verification needed)
• Cannot verify success programmatically

Example YES: CI diagnostic workflow (try multiple fix strategies) Example NO: Deploy to production (human approval required)

Question 4: Does context significantly affect approach?

YES if:

• Environment differences change strategy
• Current system state affects decisions
• Trade-offs vary by situation (speed vs quality vs cost)
• Domain-specific best practices apply

NO if:

• Same approach works for all contexts
• No environmental dependencies
• No trade-off decisions needed

Example YES: Fix agent (quick vs diagnostic vs comprehensive based on issue) Example NO: Generate UUID (context-independent)

Question 5: Is the complexity justified?

YES if:

• Problem is repeated frequently (2+ times/week)
• Manual execution takes 30+ minutes
• High value from automation
• Maintenance cost is acceptable

NO if:

• One-off or rare problem
• Quick manual execution (< 5 minutes)
• Simple script suffices
• Maintenance cost exceeds benefit

Example YES: CI failure diagnosis (frequent, time-consuming, high value) Example NO: One-time data migration (rare, script sufficient)

Decision Matrix

| All 5 YES | Use Goal-Seeking Agent | | 4 YES, 1 NO | Probably use Goal-Seeking Agent | | 3 YES, 2 NO | Consider simpler agent or hybrid | | 2 YES, 3 NO | Traditional agent likely better | | 0-1 YES | Script or simple automation |

3. Architecture Pattern

Component Architecture

Goal-seeking agents have four core components:

# Component 1: Goal Definition
class GoalDefinition:
    """Structured representation of objective"""
    raw_prompt: str              # Natural language goal
    goal: str                    # Extracted primary objective
    domain: str                  # Problem domain (security, data, automation, etc.)
    constraints: list[str]       # Technical/operational constraints
    success_criteria: list[str]  # How to verify success
    complexity: str              # simple, moderate, complex
    context: dict                # Additional metadata

# Component 2: Execution Plan
class ExecutionPlan:
    """Multi-phase plan with dependencies"""
    goal_id: uuid.UUID
    phases: list[PlanPhase]
    total_estimated_duration: str
    required_skills: list[str]
    parallel_opportunities: list[list[str]]  # Phases that can run parallel
    risk_factors: list[str]

# Component 3: Plan Phase
class PlanPhase:
    """Individual phase in execution plan"""
    name: str
    description: str
    required_capabilities: list[str]
    estimated_duration: str
    dependencies: list[str]          # Names of prerequisite phases
    parallel_safe: bool              # Can execute in parallel
    success_indicators: list[str]    # How to verify phase completion

# Component 4: Skill Definition
class SkillDefinition:
    """Capability needed for execution"""
    name: str
    description: str
    capabilities: list[str]
    implementation_type: str  # "native" or "delegated"
    delegation_target: str    # Agent to delegate to

Execution Flow

┌─────────────────────────────────────────────────────────────┐
│ 1. GOAL ANALYSIS                                            │
│                                                             │
│  Input: Natural language objective                         │
│  Process: Extract goal, domain, constraints, criteria      │
│  Output: GoalDefinition                                    │
│                                                             │
│  [PromptAnalyzer.analyze_text(prompt)]                    │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 2. PLANNING                                                 │
│                                                             │
│  Input: GoalDefinition                                     │
│  Process: Decompose into phases, identify dependencies     │
│  Output: ExecutionPlan                                     │
│                                                             │
│  [ObjectivePlanner.generate_plan(goal_definition)]        │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 3. SKILL SYNTHESIS                                          │
│                                                             │
│  Input: ExecutionPlan                                      │
│  Process: Map capabilities to skills, identify agents      │
│  Output: list[SkillDefinition]                            │
│                                                             │
│  [SkillSynthesizer.synthesize(execution_plan)]            │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 4. AGENT ASSEMBLY                                           │
│                                                             │
│  Input: GoalDefinition, ExecutionPlan, Skills              │
│  Process: Combine into executable bundle                   │
│  Output: GoalAgentBundle                                   │
│                                                             │
│  [AgentAssembler.assemble(goal, plan, skills)]            │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 5. EXECUTION (Auto-Mode)                                    │
│                                                             │
│  Input: GoalAgentBundle                                    │
│  Process: Execute phases, monitor progress, adapt          │
│  Output: Success or escalation                             │
│                                                             │
│  [Auto-mode with initial_prompt from bundle]              │
└─────────────────────────────────────────────────────────────┘

Phase Dependency Management

Phases can have three relationship types:

Sequential Dependency: Phase B depends on Phase A completion

Phase A → Phase B → Phase C

Parallel Execution: Phases can run concurrently

Phase A ──┬→ Phase B ──┐
          └→ Phase C ──┴→ Phase D

Conditional Branching: Phase selection based on results

Phase A → [Decision] → Phase B (success path)
                    └→ Phase C (recovery path)

State Management

Goal-seeking agents maintain state across phases:

class AgentState:
    """Runtime state for goal-seeking agent"""
    current_phase: str
    completed_phases: list[str]
    phase_results: dict[str, Any]  # Output from each phase
    failures: list[FailureRecord]  # Track what didn't work
    retry_count: int
    total_duration: timedelta
    context: dict                  # Shared context across phases

Error Handling

Three error recovery strategies:

Retry with Backoff: Same approach, exponential delay

for attempt in range(MAX_RETRIES):
    try:
        result = execute_phase(phase)
        break
    except RetryableError as e:
        wait_time = INITIAL_DELAY * (2 ** attempt)
        sleep(wait_time)

Alternative Strategy: Different approach to same goal

for strategy in STRATEGIES:
    try:
        result = execute_phase(phase, strategy)
        break
    except StrategyFailedError:
        continue  # Try next strategy
else:
    escalate_to_human("All strategies exhausted")

Graceful Degradation: Accept partial success

try:
    result = execute_phase_optimal(phase)
except OptimalFailedError:
    result = execute_phase_fallback(phase)  # Lower quality but works

4. Integration with goal_agent_generator

The goal_agent_generator module provides the implementation for goal-seeking agents. Here's how to integrate:

Core API

// use amplihack_goal_agent_generator:: (
    PromptAnalyzer,
    ObjectivePlanner,
    SkillSynthesizer,
    AgentAssembler,
    GoalAgentPackager,
)

# Step 1: Analyze natural language goal
analyzer = PromptAnalyzer()
goal_definition = analyzer.analyze_text("""
Automate AKS cluster production readiness verification.
Check security, networking, monitoring, and compliance.
Generate report with actionable recommendations.
""")

# Step 2: Generate execution plan
planner = ObjectivePlanner()
execution_plan = planner.generate_plan(goal_definition)

# Step 3: Synthesize required skills
synthesizer = SkillSynthesizer()
skills = synthesizer.synthesize(execution_plan)

# Step 4: Assemble complete agent
assembler = AgentAssembler()
agent_bundle = assembler.assemble(
    goal_definition=goal_definition,
    execution_plan=execution_plan,
    skills=skills,
    bundle_name="aks-readiness-checker"
)

# Step 5: Package for deployment
packager = GoalAgentPackager()
packager.package(
    bundle=agent_bundle,
    output_dir=".claude/agents/goal-driven/aks-readiness-checker"
)

CLI Integration

# Generate agent from prompt file
amplihack goal-agent-generator create \
  --prompt ./prompts/aks-readiness.md \
  --output .claude/agents/goal-driven/aks-readiness-checker

# Generate agent from inline prompt
amplihack goal-agent-generator create \
  --inline "Automate CI failure diagnosis and fix iteration" \
  --output .claude/agents/goal-driven/ci-fixer

# List generated agents
amplihack goal-agent-generator list

# Test agent execution
amplihack goal-agent-generator test \
  --agent-path .claude/agents/goal-driven/ci-fixer \
  --dry-run

PromptAnalyzer Details

Extracts structured information from natural language:

// use amplihack_goal_agent_generator:: PromptAnalyzer
from pathlib import Path

analyzer = PromptAnalyzer()

# From file
goal_def = analyzer.analyze(Path("./prompts/my-goal.md"))

# From text
goal_def = analyzer.analyze_text("Deploy and monitor microservices to AKS")

# GoalDefinition contains:
print(goal_def.goal)               # "Deploy and monitor microservices to AKS"
print(goal_def.domain)             # "deployment"
print(goal_def.constraints)        # ["Zero downtime", "Rollback capability"]
print(goal_def.success_criteria)   # ["All pods running", "Metrics visible"]
print(goal_def.complexity)         # "moderate"
print(goal_def.context)            # {"priority": "high", "scale": "medium"}

Domain classification:

• data-processing: Data transformation, analysis, ETL
• security-analysis: Vulnerability scanning, audits
• automation: Workflow automation, scheduling
• testing: Test generation, validation
• deployment: Release, publishing, distribution
• monitoring: Observability, alerting
• integration: API connections, webhooks
• reporting: Dashboards, metrics, summaries

Complexity determination:

• simple: Single-phase, < 50 words, basic operations
• moderate: 2-4 phases, 50-150 words, some coordination
• complex: 5+ phases, > 150 words, sophisticated orchestration

ObjectivePlanner Details

Generates multi-phase execution plans:

// use amplihack_goal_agent_generator:: ObjectivePlanner

planner = ObjectivePlanner()
plan = planner.generate_plan(goal_definition)

# ExecutionPlan contains:
for i, phase in enumerate(plan.phases, 1):
    print(f"Phase {i}: {phase.name}")
    print(f"  Description: {phase.description}")
    print(f"  Duration: {phase.estimated_duration}")
    print(f"  Capabilities: {', '.join(phase.required_capabilities)}")
    print(f"  Dependencies: {', '.join(phase.dependencies)}")
    print(f"  Parallel Safe: {phase.parallel_safe}")
    print(f"  Success Indicators: {phase.success_indicators}")

print(f"\nTotal Duration: {plan.total_estimated_duration}")
print(f"Required Skills: {', '.join(plan.required_skills)}")
print(f"Parallel Opportunities: {plan.parallel_opportunities}")
print(f"Risk Factors: {plan.risk_factors}")

Phase templates by domain:

• data-processing: Collection → Transformation → Analysis → Reporting
• security-analysis: Reconnaissance → Vulnerability Detection → Risk Assessment → Reporting
• automation: Setup → Workflow Design → Execution → Validation
• testing: Test Planning → Implementation → Execution → Results Analysis
• deployment: Pre-deployment → Deployment → Verification → Post-deployment
• monitoring: Setup Monitors → Data Collection → Analysis → Alerting

SkillSynthesizer Details

Maps capabilities to skills:

// use amplihack_goal_agent_generator:: SkillSynthesizer

synthesizer = SkillSynthesizer()
skills = synthesizer.synthesize(execution_plan)

# list[SkillDefinition]
for skill in skills:
    print(f"Skill: {skill.name}")
    print(f"  Description: {skill.description}")
    print(f"  Capabilities: {', '.join(skill.capabilities)}")
    print(f"  Type: {skill.implementation_type}")
    if skill.implementation_type == "delegated":
        print(f"  Delegates to: {skill.delegation_target}")

Capability mapping:

• data-* → data-processor skill
• security-*, vulnerability-* → security-analyzer skill
• test-* → tester skill
• deploy-* → deployer skill
• monitor-*, alert-* → monitor skill
• report-*, document-* → documenter skill

AgentAssembler Details

Combines components into executable bundle:

// use amplihack_goal_agent_generator:: AgentAssembler

assembler = AgentAssembler()
bundle = assembler.assemble(
    goal_definition=goal_definition,
    execution_plan=execution_plan,
    skills=skills,
    bundle_name="custom-agent"  # Optional, auto-generated if omitted
)

# GoalAgentBundle contains:
print(bundle.id)                    # UUID
print(bundle.name)                  # "custom-agent" or auto-generated
print(bundle.version)               # "1.0.0"
print(bundle.status)                # "ready"
print(bundle.auto_mode_config)      # Configuration for auto-mode execution
print(bundle.metadata)              # Domain, complexity, skills, etc.

# Auto-mode configuration
config = bundle.auto_mode_config
print(config["max_turns"])          # Based on complexity
print(config["initial_prompt"])     # Generated execution prompt
print(config["success_criteria"])   # From goal definition
print(config["constraints"])        # From goal definition

Auto-mode configuration:

• max_turns: 5 (simple), 10 (moderate), 15 (complex), +20% per extra phase
• initial_prompt: Full markdown prompt with goal, plan, success criteria
• working_dir: Current directory
• sdk: "claude" (default)
• ui_mode: False (headless by default)

GoalAgentPackager Details

Packages bundle for deployment:

// use amplihack_goal_agent_generator:: GoalAgentPackager
from pathlib import Path

packager = GoalAgentPackager()
packager.package(
    bundle=agent_bundle,
    output_dir=Path(".claude/agents/goal-driven/my-agent")
)

# Creates:
# .claude/agents/goal-driven/my-agent/
# ├── agent.md           # Agent definition
# ├── prompt.md          # Initial prompt
# ├── metadata.json      # Bundle metadata
# ├── plan.yaml          # Execution plan
# └── skills.yaml        # Required skills

5. Recent Amplihack Examples

Real goal-seeking agents from the amplihack project:

Example 1: AKS SRE Automation (Issue #1293)

Problem: Manual AKS cluster operations are time-consuming and error-prone

Goal-Seeking Solution:

# Goal: Automate AKS production readiness verification
goal = """
Verify AKS cluster production readiness:
- Security: RBAC, network policies, Key Vault integration
- Networking: Ingress, DNS, load balancers
- Monitoring: Container Insights, alerts, dashboards
- Compliance: Azure Policy, resource quotas
Generate actionable report with recommendations.
"""

# Agent decomposes into phases:
# 1. Security Audit (parallel): RBAC check, network policies, Key Vault
# 2. Networking Validation (parallel): Ingress test, DNS resolution, LB health
# 3. Monitoring Verification (parallel): Metrics, logs, alerts configured
# 4. Compliance Check (depends on 1-3): Azure Policy, quotas, best practices
# 5. Report Generation (depends on 4): Markdown report with findings

# Agent adapts based on findings:
# - If security issues found: Suggest fixes, offer to apply
# - If monitoring missing: Generate alert templates
# - If compliance violations: List remediation steps

Key Characteristics:

• Autonomous: Checks multiple systems without step-by-step instructions
• Adaptive: Investigation depth varies by findings
• Multi-Phase: Parallel security/networking/monitoring, sequential reporting
• Domain Expert: Azure + Kubernetes knowledge embedded
• Self-Assessing: Validates each check, aggregates results

Implementation:

# Located in: .claude/agents/amplihack/specialized/azure-kubernetes-expert.md
# Uses knowledge base: .claude/data/azure_aks_expert/

# Integrates with goal_agent_generator:
// use amplihack_goal_agent_generator:: (
    PromptAnalyzer, ObjectivePlanner, AgentAssembler
)

analyzer = PromptAnalyzer()
goal_def = analyzer.analyze_text(goal)

planner = ObjectivePlanner()
plan = planner.generate_plan(goal_def)  # Generates 5-phase plan

# Domain-specific customization:
plan.phases[0].required_capabilities = [
    "rbac-audit", "network-policy-check", "key-vault-integration"
]

Lessons Learned:

• Domain expertise critical for complex infrastructure
• Parallel execution significantly reduces total time
• Actionable recommendations increase agent value
• Comprehensive knowledge base (Q&A format) enables autonomous decisions

Example 2: CI Diagnostic Workflow

Problem: CI failures require manual diagnosis and fix iteration

Goal-Seeking Solution:

# Goal: Diagnose CI failure and iterate fixes until success
goal = """
CI pipeline failing after push.
Diagnose failures, apply fixes, push updates, monitor CI.
Iterate until all checks pass.
Stop at mergeable state without auto-merging.
"""

# Agent decomposes into phases:
# 1. CI Status Monitoring: Check current CI state
# 2. Failure Diagnosis: Analyze logs, compare environments
# 3. Fix Application: Apply fixes based on failure patterns
# 4. Push and Wait: Commit fixes, push, wait for CI re-run
# 5. Success Verification: Confirm all checks pass

# Iterative loop:
# Phases 2-4 repeat until success or max iterations (5)

Key Characteristics:

• Iterative: Repeats fix cycle until success
• Autonomous Recovery: Tries multiple fix strategies
• State Management: Tracks attempted fixes, avoids repeating failures
• Pattern Matching: Recognizes common CI failure types
• Escalation: Reports to user after max iterations

Implementation:

# Located in: .claude/agents/amplihack/specialized/ci-diagnostic-workflow.md

# Fix iteration loop:
MAX_ITERATIONS = 5
iteration = 0

while iteration < MAX_ITERATIONS:
    status = check_ci_status()

    if status["conclusion"] == "success":
        break

    # Diagnose failures
    failures = analyze_ci_logs(status)

    # Apply pattern-matched fixes
    for failure in failures:
        if "test" in failure["type"]:
            fix_test_failure(failure)
        elif "lint" in failure["type"]:
            fix_lint_failure(failure)
        elif "type" in failure["type"]:
            fix_type_failure(failure)

    # Commit and push
    git_commit_and_push(f"fix: CI iteration {iteration + 1}")

    # Wait for CI re-run
    wait_for_ci_completion()

    iteration += 1

if iteration >= MAX_ITERATIONS:
    escalate_to_user("CI still failing after 5 iterations")

Lessons Learned:

• Iteration limits prevent infinite loops
• Pattern matching (test/lint/type) enables targeted fixes
• Smart waiting (exponential backoff) reduces wait time
• Never auto-merge: human approval always required

Example 3: Pre-Commit Diagnostic Workflow

Problem: Pre-commit hooks fail with unclear errors

Goal-Seeking Solution:

# Goal: Fix pre-commit hook failures before commit
goal = """
Pre-commit hooks failing.
Diagnose issues (formatting, linting, type checking).
Apply fixes locally, re-run hooks.
Ensure all hooks pass before allowing commit.
"""

# Agent decomposes into phases:
# 1. Hook Failure Analysis: Identify which hooks failed
# 2. Environment Check: Compare local vs pre-commit versions
# 3. Targeted Fixes: Apply fixes per hook type
# 4. Hook Re-run: Validate fixes, iterate if needed
# 5. Commit Readiness: Confirm all hooks pass

Key Characteristics:

• Pre-Push Focus: Fixes issues before pushing to CI
• Tool Version Management: Ensures local matches pre-commit config
• Hook-Specific Fixes: Tailored approach per hook type
• Fast Iteration: No wait for CI, immediate feedback

Implementation:

# Located in: .claude/agents/amplihack/specialized/pre-commit-diagnostic.md

# Hook failure patterns:
HOOK_FIXES = {
    "ruff": lambda: subprocess.run(["ruff", "check", "--fix", "."]),
    "black": lambda: subprocess.run(["black", "."]),
    "mypy": lambda: add_type_ignores(),
    "trailing-whitespace": lambda: subprocess.run(["pre-commit", "run", "trailing-whitespace", "--all-files"]),
}

# Execution:
failed_hooks = detect_failed_hooks()

for hook in failed_hooks:
    if hook in HOOK_FIXES:
        HOOK_FIXES[hook]()
    else:
        generic_fix(hook)

# Re-run to verify
rerun_result = subprocess.run(["pre-commit", "run", "--all-files"])
if rerun_result.returncode == 0:
    print("All hooks passing, ready to commit!")

Lessons Learned:

• Pre-commit fixes are faster than CI iteration
• Tool version mismatches are common culprit
• Automated fixes for 80% of cases
• Remaining 20% escalate with clear diagnostics

Example 4: Fix-Agent Pattern Matching

Problem: Different issues require different fix approaches

Goal-Seeking Solution:

# Goal: Select optimal fix strategy based on problem context
goal = """
Analyze issue and select fix mode:
- QUICK: Obvious fixes (< 5 min)
- DIAGNOSTIC: Unclear root cause (investigation)
- COMPREHENSIVE: Complex issues (full workflow)
"""

# Agent decomposes into phases:
# 1. Issue Analysis: Classify problem type and complexity
# 2. Mode Selection: Choose QUICK/DIAGNOSTIC/COMPREHENSIVE
# 3. Fix Execution: Apply mode-appropriate strategy
# 4. Validation: Verify fix resolves issue

Key Characteristics:

• Context-Aware: Selects strategy based on problem analysis
• Multi-Mode: Three fix modes for different complexity levels
• Pattern Recognition: Learns from past fixes
• Adaptive: Escalates complexity if initial mode fails

Implementation:

# Located in: .claude/agents/amplihack/specialized/fix-agent.md

# Mode selection logic:
def select_fix_mode(issue: Issue) -> FixMode:
    if issue.is_obvious() and issue.scope == "single-file":
        return FixMode.QUICK
    elif issue.root_cause_unclear():
        return FixMode.DIAGNOSTIC
    elif issue.is_complex() or issue.requires_architecture_change():
        return FixMode.COMPREHENSIVE
    else:
        return FixMode.DIAGNOSTIC  # Default to investigation

# Pattern frequency (from real usage):
FIX_PATTERNS = {
    "import": 0.15,      # Import errors (15%)
    "config": 0.12,      # Configuration issues (12%)
    "test": 0.18,        # Test failures (18%)
    "ci": 0.20,          # CI/CD problems (20%)
    "quality": 0.25,     # Code quality (linting, types) (25%)
    "logic": 0.10,       # Logic errors (10%)
}

# Template-based fixes for common patterns:
if issue.pattern == "import":
    apply_template("import-fix-template", issue)
elif issue.pattern == "config":
    apply_template("config-fix-template", issue)
# ... etc

Lessons Learned:

• Pattern matching enables template-based fixes (80% coverage)
• Mode selection reduces over-engineering (right-sized approach)
• Diagnostic mode critical for unclear issues (root cause analysis)
• Usage data informs template priorities

6. Design Checklist

Use this checklist when designing goal-seeking agents:

Goal Definition

• Objective is clear and well-defined
• Success criteria are measurable and verifiable
• Constraints are explicit (time, resources, safety)
• Domain is identified (impacts phase templates)
• Complexity is estimated (simple/moderate/complex)

Phase Design

• Decomposed into 3-5 phases (not too granular, not too coarse)
• Phase dependencies are explicit
• Parallel execution opportunities identified
• Each phase has clear success indicators
• Phase durations are estimated

Skill Mapping

• Required capabilities identified per phase
• Skills mapped to existing agents or tools
• Delegation targets specified
• No missing capabilities

Error Handling

• Retry strategies defined (max attempts, backoff)
• Alternative strategies identified
• Escalation criteria clear (when to ask for help)
• Graceful degradation options (fallback approaches)

State Management

• State tracked across phases
• Phase results stored for downstream use
• Failure history maintained
• Context shared appropriately

Testing

• Success scenarios tested
• Failure recovery tested
• Edge cases identified
• Performance validated (duration, resource usage)

Documentation

• Goal clearly documented
• Phase descriptions complete
• Usage examples provided
• Integration points specified

Philosophy Compliance

• Ruthless simplicity (no unnecessary complexity)
• Single responsibility per phase
• No over-engineering (right-sized solution)
• Regeneratable (clear specifications)

7. Agent SDK Integration (Future)

When the Agent SDK Skill is integrated, goal-seeking agents can leverage:

Enhanced Autonomy

# Agent SDK provides enhanced context management
from claude_agent_sdk import AgentContext, Tool

class GoalSeekingAgent:
    def __init__(self, context: AgentContext):
        self.context = context
        self.state = {}

    async def execute_phase(self, phase: PlanPhase):
        # SDK provides tools, memory, delegation
        tools = self.context.get_tools(phase.required_capabilities)
        memory = self.context.get_memory()

        # Execute with SDK support
        result = await phase.execute(tools, memory)

        # Store in context for downstream phases
        self.context.store_result(phase.name, result)

Tool Discovery

# SDK enables dynamic tool discovery
available_tools = context.discover_tools(capability="data-processing")

# Select optimal tool for task
tool = context.select_tool(
    capability="data-transformation",
    criteria={"performance": "high", "accuracy": "required"}
)

Memory Management

# SDK provides persistent memory across sessions
context.memory.store("deployment-history", deployment_record)
previous = context.memory.retrieve("deployment-history")

# Enables learning from past executions
if previous and previous.failed:
    # Avoid previous failure strategy
    strategy = select_alternative_strategy(previous.failure_reason)

Agent Delegation

# SDK simplifies agent-to-agent delegation
result = await context.delegate(
    agent="security-analyzer",
    task="audit-rbac-policies",
    input={"cluster": cluster_name}
)

# Parallel delegation
results = await context.delegate_parallel([
    ("security-analyzer", "audit-rbac-policies"),
    ("network-analyzer", "validate-ingress"),
    ("monitoring-validator", "check-metrics")
])

Observability

# SDK provides built-in tracing and metrics
with context.trace("data-transformation"):
    result = transform_data(input_data)

context.metrics.record("transformation-duration", duration)
context.metrics.record("transformation-accuracy", accuracy)

Integration Example

from claude_agent_sdk import AgentContext, create_agent
// use amplihack_goal_agent_generator:: GoalAgentBundle

# Create SDK-enabled goal-seeking agent
def create_goal_agent(bundle: GoalAgentBundle) -> Agent:
    context = AgentContext(
        name=bundle.name,
        version=bundle.version,
        capabilities=bundle.metadata["required_capabilities"]
    )

    # Register phases as agent tasks
    for phase in bundle.execution_plan.phases:
        context.register_task(
            name=phase.name,
            capabilities=phase.required_capabilities,
            executor=create_phase_executor(phase)
        )

    # Create agent with SDK
    agent = create_agent(context)

    # Execute goal
    return agent

# Usage:
agent = create_goal_agent(agent_bundle)
result = await agent.execute(bundle.auto_mode_config["initial_prompt"])

8. Trade-Off Analysis

Goal-Seeking vs Traditional Agents

When to Choose Each

Choose Goal-Seeking when:

• Problem space is large with many valid approaches
• Context varies significantly across executions
• Autonomous recovery is valuable
• Reusability across contexts is important
• Development time investment is justified

Choose Traditional when:

• Single deterministic path exists
• Performance is critical (low latency required)
• Simplicity is paramount
• One-off or rare execution
• Debugging and auditability are critical

Cost-Benefit Analysis

Goal-Seeking Costs:

• Higher development time (define goals, phases, capabilities)
• Increased execution time (decision overhead)
• More complex testing (dynamic behavior)
• Harder debugging (non-deterministic paths)

Goal-Seeking Benefits:

• Autonomous operation (less human intervention)
• Adaptive to context (works in varied conditions)
• Reusable across problems (same agent, different goals)
• Self-recovering (handles failures gracefully)

Break-Even Point: Goal-seeking justified when problem is:

• Repeated 2+ times per week, OR
• Takes 30+ minutes manual execution, OR
• Requires expert knowledge hard to document, OR
• High value from autonomous recovery

9. When to Escalate

Goal-seeking agents should escalate to humans when:

Hard Limits Reached

Max Iterations Exceeded:

if iteration_count >= MAX_ITERATIONS:
    escalate(
        reason="Reached maximum iterations without success",
        context={
            "iterations": iteration_count,
            "attempted_strategies": attempted_strategies,
            "last_error": last_error
        }
    )

Timeout Exceeded:

if elapsed_time > MAX_DURATION:
    escalate(
        reason="Execution time exceeded limit",
        context={
            "elapsed": elapsed_time,
            "max_allowed": MAX_DURATION,
            "completed_phases": completed_phases
        }
    )

Safety Boundaries

Destructive Operations:

if operation.is_destructive() and not operation.has_approval():
    escalate(
        reason="Destructive operation requires human approval",
        operation=operation.description,
        impact=operation.estimate_impact()
    )

Production Changes:

if target_environment == "production":
    escalate(
        reason="Production deployments require human verification",
        changes=proposed_changes,
        rollback_plan=rollback_strategy
    )

Uncertainty Detection

Low Confidence:

if decision_confidence < CONFIDENCE_THRESHOLD:
    escalate(
        reason="Confidence below threshold for autonomous decision",
        decision=decision_description,
        confidence=decision_confidence,
        alternatives=alternative_options
    )

Conflicting Strategies:

if len(viable_strategies) > 1 and not clear_winner:
    escalate(
        reason="Multiple viable strategies, need human judgment",
        strategies=viable_strategies,
        trade_offs=strategy_trade_offs
    )

Unexpected Conditions

Unrecognized Errors:

if error_type not in KNOWN_ERROR_PATTERNS:
    escalate(
        reason="Encountered unknown error pattern",
        error=error_details,
        context=execution_context,
        recommendation="Manual investigation required"
    )

Environment Mismatch:

if detected_environment != expected_environment:
    escalate(
        reason="Environment mismatch detected",
        expected=expected_environment,
        detected=detected_environment,
        risk="Potential for incorrect behavior"
    )

Escalation Best Practices

Provide Context:

• What was attempted
• What failed and why
• What alternatives were considered
• Current system state

Suggest Actions:

• Recommend

…(truncated)