name: "Goal-Seeking Agent Pattern" version: 1.0.0 description: | 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. auto-detection: triggers: - "complex workflow" - "autonomous agent" - "goal-seeking" - "adaptive behavior" - "multi-phase processing" - "task automation design" - "autonomous decision-making" - "multi-step process" - "workflow orchestration" - "self-directed agent" allowed-tools: ["Read", "Grep", "Glob", "WebSearch"] target-agents: ["architect"] priority: "medium" complexity: "medium"

Goal-Seeking Agent Pattern Skill

1. What Are Goal-Seeking Agents?

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

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:

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

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

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 next steps
Provide diagnostic commands
Offer manual intervention points
Suggest rollback if needed

Enable Recovery:

Save execution state
Document failures
Provide resume capability
Offer manual override

Example Escalation:

escalate(
    reason="CI failure diagnosis unsuccessful after 5 iterations",
    context={
        "iterations": 5,
        "attempted_fixes": [
            "Import path corrections (iteration 1)",
            "Type annotation fixes (iteration 2)",
            "Test environment setup (iteration 3)",
            "Dependency version pins (iteration 4)",
            "Mock configuration (iteration 5)"
        ],
        "persistent_failures": [
            "test_integration.py::test_api_connection - Timeout",
            "test_models.py::test_validation - Assertion error"
        ],
        "system_state": "2 of 25 tests still failing",
        "ci_logs": "https://github.com/.../actions/runs/123456"
    },
    recommendations=[
        "Review test_api_connection timeout - may need increased timeout or mock",
        "Examine test_validation assertion - data structure may have changed",
        "Consider running tests locally with same environment as CI",
        "Check if recent changes affected integration test setup"
    ],
    next_steps={
        "manual_investigation": "Run failing tests locally with verbose output",
        "rollback_option": "git revert HEAD~5 if fixes made things worse",
        "resume_point": "Fix failures and run /amplihack:ci-diagnostic to resume"
    }
)

10. Example Workflow

Complete example: Building a goal-seeking agent for data pipeline automation

Step 1: Define Goal

# Goal: Automate Multi-Source Data Pipeline

## Objective

Collect data from multiple sources (S3, database, API), transform to common schema, validate quality, publish to data warehouse.

## Success Criteria

- All sources successfully ingested
- Data transformed to target schema
- Quality checks pass (completeness, accuracy)
- Data published to warehouse
- Pipeline completes within 30 minutes

## Constraints

- Must handle source unavailability gracefully
- No data loss (failed records logged)
- Idempotent (safe to re-run)
- Resource limits: 8GB RAM, 4 CPU cores

## Context

- Daily execution (automated schedule)
- Priority: High (blocking downstream analytics)
- Scale: Medium (100K-1M records per source)

Step 2: Analyze with PromptAnalyzer

from amplihack.goal_agent_generator import PromptAnalyzer

analyzer = PromptAnalyzer()
goal_definition = analyzer.analyze_text(goal_text)

# Result:
# goal_definition.goal = "Automate Multi-Source Data Pipeline"
# goal_definition.domain = "data-processing"
# goal_definition.complexity = "moderate"
# goal_definition.constraints = [
#     "Must handle source unavailability gracefully",
#     "No data loss (failed records logged)",
#     "Idempotent (safe to re-run)",
#     "Resource limits: 8GB RAM, 4 CPU cores"
# ]
# goal_definition.success_criteria = [
#     "All sources successfully ingested",
#     "Data transformed to target schema",
#     "Quality checks pass (completeness, accuracy)",
#     "Data published to warehouse",
#     "Pipeline completes within 30 minutes"
# ]

Step 3: Generate Plan with ObjectivePlanner

from amplihack.goal_agent_generator import ObjectivePlanner

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

# Result: 4-phase plan
# Phase 1: Data Collection (parallel)
#   - Collect from S3 (parallel-safe)
#   - Collect from database (parallel-safe)
#   - Collect from API (parallel-safe)
#   Duration: 15 minutes
#   Success: All sources attempted, failures logged
#
# Phase 2: Data Transformation (depends on Phase 1)
#   - Parse raw data
#   - Transform to common schema
#   - Handle missing fields
#   Duration: 15 minutes
#   Success: All records transformed or logged as failed
#
# Phase 3: Quality Validation (depends on Phase 2)
#   - Completeness check
#   - Accuracy validation
#   - Consistency verification
#   Duration: 5 minutes
#   Success: Quality thresholds met
#
# Phase 4: Data Publishing (depends on Phase 3)
#   - Load to warehouse
#   - Update metadata
#   - Generate report
#   Duration: 10 minutes
#   Success: Data in warehouse, report generated

Step 4: Synthesize Skills

from amplihack.goal_agent_generator import SkillSynthesizer

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

# Result: 3 skills
# Skill 1: data-collector
#   Capabilities: ["s3-read", "database-query", "api-fetch"]
#   Implementation: "native" (built-in)
#
# Skill 2: data-transformer
#   Capabilities: ["parsing", "schema-mapping", "validation"]
#   Implementation: "native" (built-in)
#
# Skill 3: data-publisher
#   Capabilities: ["warehouse-load", "metadata-update", "reporting"]
#   Implementation: "delegated" (delegates to warehouse tool)

Step 5: Assemble Agent

from amplihack.goal_agent_generator import AgentAssembler

assembler = AgentAssembler()
agent_bundle = assembler.assemble(
    goal_definition=goal_definition,
    execution_plan=execution_plan,
    skills=skills,
    bundle_name="multi-source-data-pipeline"
)

# Result: GoalAgentBundle
# - Name: multi-source-data-pipeline
# - Max turns: 12 (moderate complexity, 4 phases)
# - Initial prompt: Full execution plan with phases
# - Status: "ready"

Step 6: Package Agent

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/multi-source-data-pipeline")
)

# Creates agent package:
# .claude/agents/goal-driven/multi-source-data-pipeline/
# ├── agent.md           # Agent definition
# ├── prompt.md          # Execution prompt
# ├── metadata.json      # Bundle metadata
# ├── plan.yaml          # Execution plan (4 phases)
# └── skills.yaml        # 3 required skills

Step 7: Execute Agent (Auto-Mode)

# Execute via CLI
amplihack goal-agent-generator execute \
  --agent-path .claude/agents/goal-driven/multi-source-data-pipeline \
  --auto-mode \
  --max-turns 12

# Or programmatically:

from claude_code import execute_auto_mode

result = execute_auto_mode(
    initial_prompt=agent_bundle.auto_mode_config["initial_prompt"],
    max_turns=agent_bundle.auto_mode_config["max_turns"],
    working_dir=agent_bundle.auto_mode_config["working_dir"]
)

Step 8: Monitor Execution

Agent executes autonomously:

Phase 1: Data Collection [In Progress]
├── S3 Collection: ✓ COMPLETED (50K records, 5 minutes)
├── Database Collection: ✓ COMPLETED (75K records, 8 minutes)
└── API Collection: ✗ FAILED (timeout, retrying...)
    └── Retry 1: ✓ COMPLETED (25K records, 4 minutes)

Phase 1: ✓ COMPLETED (150K records total, 3 sources, 17 minutes)

Phase 2: Data Transformation [In Progress]
├── Parsing: ✓ COMPLETED (150K records parsed)
├── Schema Mapping: ✓ COMPLETED (148K records mapped, 2K failed)
└── Missing Fields: ✓ COMPLETED (defaults applied)

Phase 2: ✓ COMPLETED (148K records ready, 2K logged as failed, 12 minutes)

Phase 3: Quality Validation [In Progress]
├── Completeness: ✓ PASS (98.7% complete, threshold 95%)
├── Accuracy: ✓ PASS (99.2% accurate, threshold 98%)
└── Consistency: ✓ PASS (100% consistent)

Phase 3: ✓ COMPLETED (All checks passed, 4 minutes)

Phase 4: Data Publishing [In Progress]
├── Warehouse Load: ✓ COMPLETED (148K records loaded)
├── Metadata Update: ✓ COMPLETED (pipeline_run_id: 12345)
└── Report Generation: ✓ COMPLETED (report.html)

Phase 4: ✓ COMPLETED (Data published, 8 minutes)

Total Execution: ✓ SUCCESS (41 minutes, all success criteria met)

Step 9: Review Results

# Pipeline Execution Report

## Summary

- **Status**: SUCCESS
- **Duration**: 41 minutes (estimated: 30 minutes)
- **Records Processed**: 150K ingested, 148K published
- **Success Rate**: 98.7%

## Phase Results

### Phase 1: Data Collection

- S3: 50K records (5 min)
- Database: 75K records (8 min)
- API: 25K records (4 min, 1 retry)

### Phase 2: Data Transformation

- Successfully transformed: 148K records
- Failed transformations: 2K records (logged to failed_records.log)
- Failure reasons: Schema mismatch (1.5K), Invalid data (500)

### Phase 3: Quality Validation

- Completeness: 98.7% ✓
- Accuracy: 99.2% ✓
- Consistency: 100% ✓

### Phase 4: Data Publishing

- Warehouse load: Success
- Pipeline run ID: 12345
- Report: report.html

## Issues Encountered

1. API timeout (Phase 1): Resolved with retry
2. 2K transformation failures: Logged for manual review

## Recommendations

1. Investigate schema mismatches in API data
2. Add validation for API data format
3. Consider increasing timeout for API calls

Step 10: Iteration (If Needed)

If pipeline fails, agent adapts:

# Example: API source completely unavailable
if phase1_result["api"]["status"] == "unavailable":
    # Agent adapts: continues with partial data
    log_warning("API source unavailable, continuing with S3 + database")
    proceed_to_phase2_with_partial_data()

    # Report notes partial data
    add_to_report("Data incomplete: API source unavailable")

# Example: Quality validation fails
if phase3_result["completeness"] < THRESHOLD:
    # Agent tries recovery: fetch missing data
    missing_records = identify_missing_records()
    retry_collection_for_missing(missing_records)
    rerun_transformation()
    rerun_validation()

    # If still fails after retry, escalate
    if still_below_threshold:
        escalate("Quality threshold not met after retry")

11. Related Patterns

Goal-seeking agents relate to and integrate with other patterns:

Debate Pattern (Multi-Agent Decision Making)

When to Combine:

Goal-seeking agent faces complex decision with trade-offs
Multiple valid approaches exist
Need consensus from different perspectives

Example:

# Goal-seeking agent reaches decision point
if len(viable_strategies) > 1:
    # Invoke debate pattern
    result = invoke_debate(
        question="Which data transformation approach?",
        perspectives=["performance", "accuracy", "simplicity"],
        context=current_state
    )

    # Use debate result to select strategy
    selected_strategy = result.consensus

N-Version Pattern (Redundant Implementation)

When to Combine:

Goal-seeking agent executing critical phase
Error cost is high
Multiple independent implementations possible

Example:

# Critical security validation phase
if phase.is_critical():
    # Generate N versions
    results = generate_n_versions(
        phase=phase,
        n=3,
        independent=True
    )

    # Use voting or comparison to select result
    validated_result = compare_and_validate(results)

Cascade Pattern (Fallback Strategies)

When to Combine:

Goal-seeking agent has preferred approach but needs fallbacks
Quality/performance trade-offs exist
Graceful degradation desired

Example:

# Data transformation with fallback
try:
    # Optimal: ML-based transformation
    result = ml_transform(data)
except MLModelUnavailable:
    try:
        # Pragmatic: Rule-based transformation
        result = rule_based_transform(data)
    except RuleEngineError:
        # Minimal: Manual templates
        result = template_transform(data)

Investigation Workflow (Knowledge Discovery)

When to Combine:

Goal requires understanding existing system
Need to discover architecture or patterns
Knowledge excavation before execution

Example:

# Before automating deployment, understand current system
if goal.requires_system_knowledge():
    # Run investigation workflow
    investigation = run_investigation_workflow(
        scope="deployment pipeline",
        depth="comprehensive"
    )

    # Use findings to inform goal-seeking execution
    adapt_plan_based_on_investigation(investigation.findings)

Document-Driven Development (Specification First)

When to Combine:

Goal-seeking agent generates or modifies code
Clear specifications prevent drift
Documentation is single source of truth

Example:

# Goal: Implement new feature
if goal.involves_code_changes():
    # DDD Phase 1: Generate specifications
    specs = generate_specifications(goal)

    # DDD Phase 2: Review and approve specs
    await human_review(specs)

    # Goal-seeking agent implements from specs
    implementation = execute_from_specifications(specs)

Pre-Commit / CI Diagnostic (Quality Gates)

When to Combine:

Goal-seeking agent makes code changes
Need to ensure quality before commit/push
Automated validation and fixes

Example:

# After goal-seeking agent generates code
if changes_made:
    # Run pre-commit diagnostic
    pre_commit_result = run_pre_commit_diagnostic()

    if pre_commit_result.has_failures():
        # Agent fixes issues
        apply_pre_commit_fixes(pre_commit_result.failures)

    # After push, run CI diagnostic
    ci_result = run_ci_diagnostic_workflow()

    if ci_result.has_failures():
        # Agent iterates fixes
        iterate_ci_fixes_until_pass(ci_result)

12. Quality Standards

Goal-seeking agents must meet these quality standards:

Correctness

Success Criteria Verification:

Agent verifies all success criteria before completion
Intermediate phase results validated
No silent failures (all errors logged and handled)

Testing Coverage:

Happy path tested (all success criteria met)
Failure scenarios tested (phase failures, retries)
Edge cases identified and tested
Integration with real systems validated

Resilience

Error Handling:

Retry logic with exponential backoff
Alternative strategies for common failures
Graceful degradation when optimal path unavailable
Clear escalation criteria

State Management:

State persisted across phase boundaries
Resume capability after failures
Idempotent execution (safe to re-run)
Cleanup on abort

Performance

Efficiency:

Phases execute in parallel when possible
No unnecessary work (skip completed phases on retry)
Resource usage within limits (memory, CPU, time)
Timeout limits enforced

Latency:

Decision overhead acceptable for use case
No blocking waits (async where possible)
Progress reported (no black box periods)

Observability

Logging:

Phase transitions logged
Decisions logged with reasoning
Errors logged with context
Results logged with metrics

Metrics:

Duration per phase tracked
Success/failure rates tracked
Resource usage monitored
Quality metrics reported

Tracing:

Execution flow traceable
Correlations across phases maintained
Debugging information sufficient

Usability

Documentation:

Goal clearly stated
Success criteria documented
Usage examples provided
Integration guide complete

User Experience:

Clear progress reporting
Actionable error messages
Human-readable outputs
Easy to invoke and monitor

Philosophy Compliance

Ruthless Simplicity:

No unnecessary phases or complexity
Simplest approach that works
No premature optimization

Single Responsibility:

Each phase has one clear job
No overlapping responsibilities
Clean phase boundaries

Modularity:

Skills are reusable across agents
Phases are independent
Clear interfaces (inputs/outputs)

Regeneratable:

Can be rebuilt from specifications
No hardcoded magic values
Configuration externalized

13. Getting Started

Quick Start: Build Your First Goal-Seeking Agent

Step 1: Install amplihack (if not already)

pip install amplihack

Step 2: Write a goal prompt

cat > my-goal.md << 'EOF'
# Goal: Automated Security Audit

Check application for common security issues:
- SQL injection vulnerabilities
- XSS vulnerabilities
- Insecure dependencies
- Missing security headers

Generate report with severity levels and remediation steps.
EOF

Step 3: Generate agent

amplihack goal-agent-generator create \
  --prompt my-goal.md \
  --output .claude/agents/goal-driven/security-auditor

Step 4: Review generated plan

cat .claude/agents/goal-driven/security-auditor/plan.yaml

Step 5: Execute agent

amplihack goal-agent-generator execute \
  --agent-path .claude/agents/goal-driven/security-auditor \
  --auto-mode

Common Use Cases

Use Case 1: Workflow Automation

# Create release automation agent
echo "Automate release workflow: tag, build, test, deploy to staging" | \
  amplihack goal-agent-generator create --inline --output .claude/agents/goal-driven/release-automator

Use Case 2: Data Pipeline

# Create ETL pipeline agent
echo "Extract from sources, transform to schema, validate quality, load to warehouse" | \
  amplihack goal-agent-generator create --inline --output .claude/agents/goal-driven/etl-pipeline

Use Case 3: Diagnostic Workflow

# Create performance diagnostic agent
echo "Diagnose application performance issues, identify bottlenecks, suggest optimizations" | \
  amplihack goal-agent-generator create --inline --output .claude/agents/goal-driven/perf-diagnostic

Learning Resources

Documentation:

Review examples in .claude/skills/goal-seeking-agent-pattern/examples/
Read real agent implementations in .claude/agents/amplihack/specialized/
Check integration guide in .claude/skills/goal-seeking-agent-pattern/templates/integration_guide.md

Practice:

Start simple: Build single-phase agent (e.g., file formatter)
Add complexity: Build multi-phase agent (e.g., test generator + runner)
Add autonomy: Build agent with error recovery (e.g., CI fixer)
Build production: Build full goal-seeking agent (e.g., deployment pipeline)

Get Help:

Review decision framework (Section 2)
Check design checklist (Section 6)
Study real examples (Section 5)
Ask architect agent for guidance

Next Steps

After building your first goal-seeking agent:

Test thoroughly: Cover success, failure, and edge cases
Monitor in production: Track metrics, logs, failures
Iterate: Refine based on real usage
Document learnings: Update DISCOVERIES.md with insights
Share patterns: Add successful approaches to PATTERNS.md

Success Indicators:

Agent completes goal autonomously 80%+ of time
Failures escalate with clear context
Execution time is acceptable
Users trust agent to run autonomously

Remember: Goal-seeking agents should be ruthlessly simple, focused on clear objectives, and adaptive to context. Start simple, add complexity only when justified, and always verify against success criteria.

Goal-Seeking Agent Pattern

$ Installer

Goal-Seeking Agent Pattern Skill

1. What Are Goal-Seeking Agents?

Core Characteristics

Distinction from Traditional Agents

When Goal-Seeking Makes Sense

When to Avoid Goal-Seeking

2. When to Use This Pattern

Problem Indicators

Pattern 1: Workflow Variability

Pattern 2: Multi-Phase Complexity

Pattern 3: Autonomous Recovery Needed

Pattern 4: Adaptive Decision Making

Pattern 5: Domain Expertise Required

Decision Framework

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

Question 2: Are there multiple phases with dependencies?

Question 3: Is autonomous recovery valuable?

Question 4: Does context significantly affect approach?

Question 5: Is the complexity justified?

Decision Matrix

3. Architecture Pattern

Component Architecture

Execution Flow

Phase Dependency Management

State Management

Error Handling

4. Integration with goal_agent_generator

Core API

CLI Integration

PromptAnalyzer Details

ObjectivePlanner Details

SkillSynthesizer Details

AgentAssembler Details

GoalAgentPackager Details

5. Recent Amplihack Examples

Example 1: AKS SRE Automation (Issue #1293)

Example 2: CI Diagnostic Workflow

Example 3: Pre-Commit Diagnostic Workflow

Example 4: Fix-Agent Pattern Matching

6. Design Checklist

Goal Definition

Phase Design

Skill Mapping

Error Handling

State Management

Testing

Documentation

Philosophy Compliance

7. Agent SDK Integration (Future)

Enhanced Autonomy

Tool Discovery

Memory Management

Agent Delegation

Observability

Integration Example

8. Trade-Off Analysis

Goal-Seeking vs Traditional Agents

When to Choose Each

Cost-Benefit Analysis

9. When to Escalate

Hard Limits Reached

Safety Boundaries

Uncertainty Detection

Unexpected Conditions

Escalation Best Practices

10. Example Workflow

Step 1: Define Goal

Step 2: Analyze with PromptAnalyzer

Step 3: Generate Plan with ObjectivePlanner

Step 4: Synthesize Skills

Step 5: Assemble Agent

Step 6: Package Agent

Step 7: Execute Agent (Auto-Mode)

Step 8: Monitor Execution

Step 9: Review Results

Step 10: Iteration (If Needed)

11. Related Patterns

Debate Pattern (Multi-Agent Decision Making)