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

• Understanding High-Level Goals: Accept natural language objectives without explicit step-by-step instructions

• Planning Execution: Break goals into phases with dependencies and success criteria

• Autonomous Execution: Make decisions and adapt behavior based on intermediate results

• Self-Assessment: Evaluate progress against success criteria and adjust approach

• 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

| Follows fixed workflow | Adapts workflow to context

| Prescriptive steps | Outcome-oriented objectives

| Human intervention on failure | Autonomous recovery attempts

| Single-phase execution | Multi-phase with dependencies

| Rigid decision tree | Dynamic strategy adjustment

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:

• Data collection (multiple sources, parallel)

• Transformation (depends on collection results)

• Validation (depends on transformation output)

• 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

from amplihack.goal_agent_generator import (
    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:

from amplihack.goal_agent_generator import 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:

from amplihack.goal_agent_generator import 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:

from amplihack.goal_agent_generator import 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:

from amplihack.goal_agent_generator import 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:

from amplihack.goal_agent_generator import 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:
from amplihack.goal_agent_generator import (
    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"<span class="token pu