# Goal Seeking Agent Pattern

> Guides architects on when and how to use goal-seeking agents as a design pattern. This skill helps evaluate whether autonomous agents are appropriate for a given problem, how to structure their objectives, integrate with goal_agent_generator, and reference real amplihack examples like AKS SRE automation, CI diagnostics, pre-commit workflows, and fix-agent pattern matching.

- Skill: `rysweet/goal-seeking-agent-pattern` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds add rysweet/goal-seeking-agent-pattern`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rysweet/goal-seeking-agent-pattern/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: rysweet (https://skillmd.com/u/rysweet)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/rysweet/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

| Traditional Agent             | Goal-Seeking Agent            |
| ----------------------------- | ----------------------------- |
| 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:

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:

```python
# 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:

```python
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

```python
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

```python
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

```python
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

```python
use amplihack_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

```bash
# 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:

```python
use amplihack_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:

```python
use amplihack_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:

```python
use amplihack_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:

```python
use amplihack_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:

```python
use amplihack_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**:

```python
# 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**:

```python
# 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_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**:

```python
# 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**:

```python
# 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**:

```python
# 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**:

```python
# 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**:

```python
# 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**:

```python
# 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

```python
# 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

```python
# 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

```python
# 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

```python
# 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

```python
# 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

```python
from claude_agent_sdk import AgentContext, create_agent
use amplihack_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

| Dimension            | Goal-Seeking Agent                    | Traditional Agent         |
| -------------------- | ------------------------------------- | ------------------------- |
| **Flexibility**      | High - adapts to context              | Low - fixed workflow      |
| **Development Time** | Moderate - define goals & phases      | Low - script steps        |
| **Execution Time**   | Higher - decision overhead            | Lower - direct execution  |
| **Maintenance**      | Lower - self-adapting                 | Higher - manual updates   |
| **Debuggability**    | Harder - dynamic behavior             | Easier - predictable flow |
| **Reusability**      | High - same agent, different contexts | Low - context-specific    |
| **Failure Handling** | Autonomous recovery                   | Manual intervention       |
| **Complexity**       | Higher - multi-phase coordination     | Lower - linear execution  |

### 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**:

```python
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**:

```python
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**:

```python
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**:

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

### Uncertainty Detection

**Low Confidence**:

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

**Conflicting Strategies**:

```python
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**:

```python
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**:

```python
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**:

- Recommen

…(truncated)