DEVELOPING_AMPLIHACK.md¶

Version: 1.0.0 Last Updated: 2025-10-17 Target Audience: AI Agents, Developers Lookup Time Target: < 10 seconds for 80% of queries

Document Purpose¶

This is the authoritative technical reference for developing with and extending the amplihack framework. It provides:

• Quick Reference Card for common operations (Section 1.2)
• Complete feature-to-implementation mapping (Section 3)
• Module-level API documentation (Section 4)
• Configuration guides with examples (Section 5)
• Development workflows and common tasks (Sections 6-7)
• Troubleshooting guide with solutions (Section 8)

Search Terms: amplihack, development, technical reference, API documentation, architecture, modules, configuration, troubleshooting

Table of Contents¶

1. Front Matter
2. 1.1 Document Navigation
3. 1.2 Quick Reference Card
4. Architecture Overview
5. 2.1 System Architecture
6. 2.2 Core Components
7. 2.3 Data Flow
8. Feature Inventory
9. 3.1 Launcher Features
10. 3.2 Proxy Features
11. 3.3 Bundle Generator Features
12. 3.4 Security Features
13. 3.5 Agent System Features
14. Module Reference
15. 4.1 Launcher Module
16. 4.2 Proxy Module
17. 4.3 Bundle Generator Module
18. 4.4 Security Module
19. 4.5 Memory Module
20. 4.6 Utilities Module
21. Configuration Guide
22. 5.1 Environment Configuration
23. 5.2 Claude Configuration
24. 5.3 Proxy Configuration
25. 5.4 Security Configuration
26. Development Workflows
27. 6.1 Local Development Setup
28. 6.2 Agent Development
29. 6.3 Testing Workflow
30. 6.4 CI/CD Integration
31. Common Tasks
32. 7.1 Creating Custom Agents
33. 7.2 Configuring Azure Integration
34. 7.3 Adding Slash Commands
35. 7.4 Working with Proxy
36. 7.5 Security Integration
37. Troubleshooting
38. 8.1 Common Issues
39. 8.2 Debugging Guide
40. 8.3 Performance Issues
41. Code Examples
42. 9.1 Agent Creation
43. 9.2 Tool Integration
44. 9.3 API Usage
45. Appendices
    • 10.1 Glossary
    • 10.2 File Index
    • 10.3 Command Reference

1. Front Matter¶

1.1 Document Navigation¶

For AI Agents: Use Ctrl+F / Cmd+F to search for specific terms. Section headers use H2 (##) for major sections and H3 (###) for subsections.

Quick Navigation Patterns:

• Feature lookup: Go to Section 3 (Feature Inventory)
• API reference: Go to Section 4 (Module Reference)
• Configuration: Go to Section 5 (Configuration Guide)
• How-to guides: Go to Section 7 (Common Tasks)
• Troubleshooting: Go to Section 8

Search Terms: navigation, documentation structure, table of contents, quick reference

1.2 Quick Reference Card¶

80% of Common Queries - Optimized for < 10 Second Lookup

Launch Commands¶

# Basic launch
amplihack claude

# Launch with Azure proxy
amplihack claude --with-proxy-config ./azure.env

# Autonomous mode
amplihack claude --auto -- -p "your task"

# Launch with repository
amplihack claude --checkout-repo owner/repo

# Launch GitHub Copilot
amplihack copilot

Implementation: /home/azureuser/src/amplihack-worktree-921-922/src/amplihack/cli.py:30-150

Slash Commands¶

Implementation: /home/azureuser/src/amplihack-worktree-921-922/.claude/commands/amplihack/

Key Modules¶

Configuration Files¶

Agent Locations¶

Common File Paths¶

Project Root: /home/azureuser/src/amplihack-worktree-921-922/

Key Directories:
├── .claude/                    # Claude configuration
│   ├── agents/                 # Agent definitions
│   ├── commands/               # Slash commands
│   ├── context/                # Philosophy and patterns
│   └── workflow/               # Development workflows
├── src/amplihack/              # Source code
│   ├── launcher/               # Launch functionality
│   ├── proxy/                  # Proxy implementation
│   ├── bundle_generator/       # Agent generation
│   ├── security/               # Security features
│   └── memory/                 # Session management
├── tests/                      # Test suite
└── docs/                       # Documentation

Environment Variables¶

# Claude Configuration
CLAUDE_PROJECT_DIR=/path/to/project
AMPLIHACK_USE_TRACE=1          # Enable claude-trace

# Azure Configuration
OPENAI_API_KEY=your-key
OPENAI_BASE_URL=https://your-endpoint.openai.azure.com
AZURE_OPENAI_API_VERSION=2025-01-01-preview

# Security Configuration
XPIA_SECURITY_LEVEL=MODERATE   # STRICT|HIGH|MODERATE|LOW
XPIA_ENABLED=true
XPIA_BASH_VALIDATION=true

See Also: Section 5.1 (Environment Configuration)

2. Architecture Overview¶

2.1 System Architecture¶

amplihack is a development framework that enhances Claude Code and GitHub Copilot with specialized agents, Azure integration, and security features.

Search Terms: architecture, system design, components, overview

High-Level Architecture¶

┌─────────────────────────────────────────────────────────────┐
│                    User Interface Layer                      │
│  CLI (amplihack) + Claude Code + GitHub Copilot CLI         │
└────────────────────┬────────────────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────────────────┐
│                   Orchestration Layer                        │
│  • Launcher (core.py)                                        │
│  • Command Router (.claude/commands/)                        │
│  • Agent Orchestrator (ultrathink.md)                        │
└────────────────────┬────────────────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────────────────┐
│                     Agent Layer                              │
│  • Core Agents (architect, builder, reviewer, etc.)         │
│  • Specialized Agents (security, optimizer, etc.)           │
│  • Workflow Agents (ci-diagnostic, pre-commit, etc.)        │
└────────────────────┬────────────────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────────────────┐
│                   Service Layer                              │
│  • Proxy Service (Azure/GitHub integration)                 │
│  • Security Service (XPIA defense)                          │
│  • Memory Service (session persistence)                     │
│  • Bundle Generator (agent creation)                        │
└────────────────────┬────────────────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────────────────┐
│                  Infrastructure Layer                        │
│  • File System (project detection)                          │
│  • Network (API proxying)                                   │
│  • Process Management (subprocess execution)                │
└─────────────────────────────────────────────────────────────┘

Implementation: See Section 4 for detailed module documentation

2.2 Core Components¶

Component: Launcher¶

Purpose: Manages Claude Code execution lifecycle Location: /home/azureuser/src/amplihack-worktree-921-922/src/amplihack/launcher/ Key Files:

• core.py:20-543 - Main ClaudeLauncher class
• detector.py:1-150 - .claude directory detection
• repo_checkout.py:1-100 - Repository checkout
• auto_mode.py:1-200 - Autonomous mode

Responsibilities:

1. Prerequisites checking (Node.js, npm, claude CLI)
2. Repository checkout and directory management
3. Proxy lifecycle management
4. Claude process spawning and monitoring
5. Environment variable configuration

See Also: Section 4.1 (Launcher Module)

Component: Proxy¶

Purpose: Enables Azure OpenAI and GitHub Copilot integration Location: /home/azureuser/src/amplihack-worktree-921-922/src/amplihack/proxy/ Key Files:

• integrated_proxy.py:1-500 - Main proxy server
• config.py:1-580 - Configuration management
• azure_unified_handler.py:1-400 - Azure request handling
• github_client.py:1-300 - GitHub Copilot integration

Responsibilities:

1. Anthropic API to Azure OpenAI translation
2. Model mapping (claude-_ to gpt-_)
3. Request/response transformation
4. Authentication management
5. Error handling and retries

See Also: Section 4.2 (Proxy Module)

Component: Bundle Generator¶

Purpose: Creates custom agent bundles from natural language Location: /home/azureuser/src/amplihack-worktree-921-922/src/amplihack/bundle_generator/ Key Files:

• generator.py:1-556 - Agent content generation
• parser.py:1-300 - Intent extraction
• packager.py:1-250 - Bundle packaging
• cli.py:1-200 - CLI interface

Responsibilities:

1. Natural language intent extraction
2. Agent specification generation
3. Test file creation
4. Documentation generation
5. Bundle packaging and distribution

See Also: Section 4.3 (Bundle Generator Module)

Component: Security (XPIA Defense)¶

Purpose: Cross-Prompt Injection Attack defense Location: /home/azureuser/src/amplihack-worktree-921-922/src/amplihack/security/ Key Files:

• xpia_defender.py:1-673 - Core security validation
• xpia_patterns.py:1-400 - Attack pattern detection
• xpia_hooks.py:1-250 - Hook integration
• xpia_defense_interface.py:1-200 - Public API

Responsibilities:

1. Content validation (prompts, commands, URLs)
2. Attack pattern detection
3. Risk level assessment
4. Mitigation recommendations
5. Security event logging

See Also: Section 4.4 (Security Module)

2.3 Data Flow¶

Claude Launch Flow¶

1. User executes: amplihack claude --with-proxy-config azure.env
   ↓
2. CLI parses arguments (cli.py:30-150)
   ↓
3. ClaudeLauncher.prepare_launch() (launcher/core.py:74-100)
   ├── Check prerequisites (utils/prerequisites.py:1-150)
   ├── Detect .claude directory (launcher/detector.py:20-80)
   ├── Start proxy if configured (proxy/manager.py:30-120)
   └── Configure environment variables
   ↓
4. ClaudeLauncher.build_claude_command() (launcher/core.py:281-348)
   ├── Select claude or claude-trace
   ├── Add --add-dir for UVX mode
   ├── Configure Azure model
   └── Append user arguments
   ↓
5. ClaudeLauncher.launch() (launcher/core.py:350-420)
   ├── Set environment variables
   ├── Spawn Claude process
   ├── Monitor execution
   └── Clean up on exit

Search Terms: data flow, execution flow, request flow, process flow

Proxy Request Flow¶

1. Claude Code sends request to ANTHROPIC_BASE_URL (proxy endpoint)
   ↓
2. IntegratedProxy.handle_chat_completion() (integrated_proxy.py:200-300)
   ├── Parse Anthropic request format
   ├── Load proxy configuration (config.py:48-98)
   └── Detect endpoint type (azure/github/openai)
   ↓
3. AzureUnifiedHandler.handle_request() (azure_unified_handler.py:100-250)
   ├── Map model name (claude-sonnet-4 → gpt-4)
   ├── Transform request format
   ├── Add Azure authentication
   └── Set API version
   ↓
4. Send request to Azure OpenAI endpoint
   ↓
5. AzureUnifiedHandler.transform_response() (azure_unified_handler.py:300-400)
   ├── Transform Azure response to Anthropic format
   ├── Map usage statistics
   └── Handle streaming if enabled
   ↓
6. Return response to Claude Code

See Also: Section 4.2 (Proxy Module), Section 7.4 (Working with Proxy)

3. Feature Inventory¶

Complete feature-to-implementation mapping for rapid discovery

Search Terms: features, capabilities, functionality, what can amplihack do

3.1 Launcher Features¶

Search Terms: launch, claude code, execution, repository, uvx

3.2 Proxy Features¶

Search Terms: proxy, azure, github copilot, integration, api, model mapping

3.3 Bundle Generator Features¶

Search Terms: bundle generator, agent creation, custom agents, agent bundle

3.4 Security Features¶

Search Terms: security, xpia, validation, threat detection, injection attacks

3.5 Agent System Features¶

Search Terms: agents, orchestration, multi-agent, workflows, agent system

4. Module Reference¶

Detailed API documentation for core modules

Search Terms: api reference, modules, classes, functions, interfaces

4.1 Launcher Module¶

Location: /home/azureuser/src/amplihack-worktree-921-922/src/amplihack/launcher/

4.1.1 ClaudeLauncher Class¶

File: core.py:20-543

class ClaudeLauncher:
    """Launches Claude Code with proper configuration and performance optimization."""

Purpose: Manages the complete Claude Code launch lifecycle including repository checkout, proxy management, and environment configuration.

Performance Optimizations:

• Path resolution caching (lines 70-71, 510-528)
• UVX decision caching (lines 72-73)
• Directory comparison optimization (lines 163-171)

Constructor:

def __init__(
    self,
    proxy_manager: Optional[ProxyManager] = None,
    append_system_prompt: Optional[Path] = None,
    force_staging: bool = False,
    checkout_repo: Optional[str] = None,
    claude_args: Optional[List[str]] = None,
)

Parameters:

• proxy_manager: Optional ProxyManager instance for Azure integration
• append_system_prompt: Path to additional system prompt file
• force_staging: Force staging approach instead of --add-dir (UVX mode)
• checkout_repo: GitHub repository URI (format: "owner/repo")
• claude_args: Additional CLI arguments to pass to Claude

Example:

from amplihack.launcher.core import ClaudeLauncher
from amplihack.proxy.manager import ProxyManager

# Basic launch
launcher = ClaudeLauncher()
exit_code = launcher.launch()

# With Azure proxy
proxy_mgr = ProxyManager(config_path=Path("azure.env"))
launcher = ClaudeLauncher(proxy_manager=proxy_mgr)
exit_code = launcher.launch()

# With repository checkout
launcher = ClaudeLauncher(checkout_repo="owner/repo")
exit_code = launcher.launch()

See Also: Section 7.1 (Creating Custom Agents), Section 9.3 (API Usage)

Key Methods:

prepare_launch() -> bool¶

Location: core.py:74-100

Purpose: Prepare environment for launching Claude (prerequisites, directory setup, proxy startup).

Returns: True if preparation successful, False otherwise

Process:

1. Check prerequisites (Node.js, npm, Claude CLI) - line 81
2. Handle repository checkout if requested - lines 85-87
3. Find and validate target directory - lines 90-93
4. Handle directory change - lines 96-97
5. Start proxy if configured - line 100

Example:

launcher = ClaudeLauncher()
if launcher.prepare_launch():
    # Ready to launch
    pass

build_claude_command() -> List[str]¶

Location: core.py:281-348

Purpose: Build the Claude command with all necessary arguments.

Returns: List of command arguments for subprocess

Logic:

• Detects claude-trace vs standard claude (line 291)
• Adds --add-dir for UVX mode (lines 312-313, 336-338)
• Configures Azure model when proxy is active (lines 316-317, 341-342)
• Appends user-provided arguments (lines 320-321, 345-346)

Example:

launcher = ClaudeLauncher(
    proxy_manager=proxy_mgr,
    claude_args=["--model", "azure/gpt-4"]
)
cmd = launcher.build_claude_command()
# cmd = ["claude", "--dangerously-skip-permissions", "--model", "azure/gpt-4"]

launch() -> int¶

Location: core.py:350-420

Purpose: Launch Claude Code and monitor execution.

Returns: Exit code from Claude process

Features:

• Signal handling for graceful shutdown (lines 364-374)
• Environment variable configuration (lines 377-404)
• Proxy environment integration (lines 391-404)
• Cleanup on exit (lines 417-419)

Example:

launcher = ClaudeLauncher()
exit_code = launcher.launch()
sys.exit(exit_code)

4.1.2 ClaudeDirectoryDetector Class¶

File: detector.py:1-150

Purpose: Detect .claude directories and determine project roots.

Key Methods:

def find_claude_directory() -> Optional[Path]:
    """Find .claude directory in current or parent directories."""

def get_project_root(claude_dir: Path) -> Path:
    """Get project root directory from .claude directory."""

Example:

from amplihack.launcher.detector import ClaudeDirectoryDetector

detector = ClaudeDirectoryDetector()
claude_dir = detector.find_claude_directory()
if claude_dir:
    project_root = detector.get_project_root(claude_dir)

4.1.3 Repository Checkout¶

File: repo_checkout.py:1-100

Purpose: Clone GitHub repositories and set up working directories.

Key Function:

def checkout_repository(repo_uri: str) -> Optional[str]:
    """
    Checkout GitHub repository.

    Args:
        repo_uri: Repository URI (owner/repo or full URL)

    Returns:
        Path to checked out repository or None on failure
    """

Supported Formats:

• owner/repo
• https://github.com/owner/repo
• https://github.com/owner/repo.git
• owner/repo@branch-name (specific branch)

Example:

from amplihack.launcher.repo_checkout import checkout_repository

repo_path = checkout_repository("microsoft/TypeScript")
if repo_path:
    os.chdir(repo_path)

4.2 Proxy Module¶

Location: /home/azureuser/src/amplihack-worktree-921-922/src/amplihack/proxy/

Search Terms: proxy, azure integration, api translation, model mapping, github copilot

4.2.1 IntegratedProxy Class¶

File: integrated_proxy.py:1-500

Purpose: Main proxy server that translates Anthropic API calls to Azure OpenAI or GitHub Copilot.

Key Features:

• Anthropic to OpenAI format conversion
• Azure endpoint detection and routing
• GitHub Copilot integration
• Streaming response support
• Error handling and retries

Constructor:

class IntegratedProxy:
    def __init__(self, config_path: Optional[Path] = None):
        """
        Initialize integrated proxy.

        Args:
            config_path: Path to .env configuration file
        """

Example:

from amplihack.proxy.integrated_proxy import IntegratedProxy

proxy = IntegratedProxy(config_path=Path("azure.env"))
proxy.start()

Key Methods:

start(host: str = "127.0.0.1", port: int = 8000) -> None¶

Purpose: Start the proxy server.

Parameters:

• host: Host address to bind to (default: 127.0.0.1)
• port: Port to listen on (default: 8000)

Example:

proxy.start(host="0.0.0.0", port=8080)

handle_chat_completion(request_data: dict) -> dict¶

Location: integrated_proxy.py:200-300

Purpose: Handle chat completion requests from Claude.

Process:

1. Parse Anthropic request format
2. Detect endpoint type (Azure/GitHub/OpenAI)
3. Transform request format
4. Send to backend API
5. Transform response back to Anthropic format

Example Request Flow:

# Anthropic request format
anthropic_request = {
    "model": "claude-sonnet-4",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 1024
}

# After transformation (Azure format)
azure_request = {
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 1024
}

4.2.2 ProxyConfig Class¶

File: config.py:1-580

Purpose: Manage proxy configuration from .env files.

Constructor:

class ProxyConfig:
    def __init__(self, config_path: Optional[Path] = None):
        """
        Initialize proxy configuration.

        Args:
            config_path: Path to .env configuration file
        """

Key Methods:

validate() -> bool¶

Location: config.py:145-162

Purpose: Validate required configuration values.

Returns: True if configuration is valid, False otherwise

Validation Checks:

• Azure: API key format, endpoint URL, API version
• GitHub: Token format, endpoint validity
• OpenAI: API key presence

Example:

from amplihack.proxy.config import ProxyConfig

config = ProxyConfig(Path("azure.env"))
if config.validate():
    print("Configuration valid")
else:
    errors = config.get_validation_errors()
    print(f"Validation failed: {errors}")

get_azure_deployment(model_name: str) -> Optional[str]¶

Location: config.py:299-308

Purpose: Map OpenAI model names to Azure deployment names.

Parameters:

• model_name: OpenAI model name (e.g., "gpt-4", "gpt-4-turbo")

Returns: Azure deployment name or None

Model Mapping:

Example:

deployment = config.get_azure_deployment("gpt-4")
# Returns: "my-gpt4-deployment"

is_azure_endpoint() -> bool¶

Location: config.py:213-222

Purpose: Check if configuration uses Azure OpenAI endpoint.

Detection Logic:

• Checks AZURE_OPENAI_BASE_URL
• Checks AZURE_OPENAI_ENDPOINT
• Validates URL contains ".openai.azure.com"

Example:

if config.is_azure_endpoint():
    # Use Azure-specific handling
    pass

is_github_endpoint() -> bool¶

Location: config.py:387-394

Purpose: Check if configuration uses GitHub Copilot endpoint.

Detection Logic:

• Checks GITHUB_COPILOT_ENDPOINT
• Validates endpoint is api.github.com
• Checks GITHUB_COPILOT_ENABLED flag

Example:

if config.is_github_endpoint():
    # Use GitHub Copilot handling
    pass

4.2.3 AzureUnifiedHandler Class¶

File: azure_unified_handler.py:1-400

Purpose: Handle Azure OpenAI request/response transformation.

Key Methods:

handle_request(request_data: dict) -> dict¶

Location: azure_unified_handler.py:100-250

Purpose: Transform Anthropic request to Azure OpenAI format.

Transformations:

1. Map model name (claude-_ → gpt-_)
2. Convert message format
3. Add Azure-specific parameters
4. Set API version and authentication

Example:

handler = AzureUnifiedHandler(config)
azure_request = handler.handle_request(anthropic_request)

transform_response(azure_response: dict) -> dict¶

Location: azure_unified_handler.py:300-400

Purpose: Transform Azure response to Anthropic format.

Transformations:

1. Convert message format
2. Map usage statistics
3. Handle streaming chunks
4. Convert error format

4.2.4 ProxyManager Class¶

File: manager.py:30-250

Purpose: Manage proxy lifecycle (start/stop/status).

Key Methods:

def start_proxy() -> bool:
    """Start proxy server in background."""

def stop_proxy() -> None:
    """Stop proxy server."""

def is_running() -> bool:
    """Check if proxy is running."""

def get_proxy_url() -> str:
    """Get proxy base URL."""

Example:

from amplihack.proxy.manager import ProxyManager

mgr = ProxyManager(config_path=Path("azure.env"))
if mgr.start_proxy():
    print(f"Proxy running at: {mgr.get_proxy_url()}")
    # Use proxy
    mgr.stop_proxy()

4.3 Bundle Generator Module¶

Location: /home/azureuser/src/amplihack-worktree-921-922/src/amplihack/bundle_generator/

Search Terms: bundle generator, agent creation, agent bundle, custom agents

4.3.1 AgentGenerator Class¶

File: generator.py:18-556

Purpose: Generate agent content from natural language requirements.

Constructor:

class AgentGenerator:
    """Generate agent content from extracted requirements."""

    def __init__(self, template_path: Optional[str] = None):
        """
        Initialize the agent generator.

        Args:
            template_path: Optional path to custom templates
        """

Key Methods:

generate(intent: ExtractedIntent, options: Dict = None) -> List[GeneratedAgent]¶

Location: generator.py:87-117

Purpose: Generate agents from extracted intent.

Parameters:

• intent: ExtractedIntent object with parsed requirements
• options: Optional generation options
• include_tests: Generate test files (default: True)
• include_docs: Generate documentation (default: True)

Returns: List of GeneratedAgent objects

Example:

from amplihack.bundle_generator.generator import AgentGenerator
from amplihack.bundle_generator.parser import IntentParser

parser = IntentParser()
intent = parser.parse("Create an agent that validates JSON schemas")

generator = AgentGenerator()
agents = generator.generate(intent, options={"include_tests": True})

for agent in agents:
    print(f"Generated: {agent.name}")
    print(f"Content length: {len(agent.content)} bytes")

_generate_single_agent(requirement: AgentRequirement, ...) -> GeneratedAgent¶

Location: generator.py:119-179

Purpose: Generate a single agent from requirement specification.

Generated Content:

• Agent markdown file (lines 126-152)
• Test files (lines 155-157)
• Documentation (lines 160-162)
• Metadata (lines 166-179)

Agent Template Structure (lines 26-76):

# {name}

{description}

## Role

{role}

## Model Configuration

Model: {model}

## Capabilities

{capabilities}

## Core Responsibilities

{responsibilities}

## Implementation

{implementation}

## Context and Philosophy

{philosophy}

## Error Handling

{error_handling}

## Performance Considerations

{performance}

## Dependencies

{dependencies}

## Example Usage

{examples}

## Testing

{testing}

validate_agent(agent: GeneratedAgent) -> List[str]¶

Location: generator.py:530-556

Purpose: Validate generated agent content.

Checks:

• Content length (minimum 100 bytes)
• Required sections present (Role, Capabilities, Implementation)
• No placeholders (TODO, PLACEHOLDER)

Returns: List of validation issues (empty if valid)

Example:

issues = generator.validate_agent(agent)
if issues:
    print(f"Validation failed: {issues}")
else:
    print("Agent is valid")

4.3.2 IntentParser Class¶

File: parser.py:1-300

Purpose: Parse natural language requirements into structured intent.

Key Methods:

def parse(self, user_input: str) -> ExtractedIntent:
    """
    Parse user input to extract agent requirements.

    Args:
        user_input: Natural language description

    Returns:
        ExtractedIntent with structured requirements
    """

Example:

from amplihack.bundle_generator.parser import IntentParser

parser = IntentParser()
intent = parser.parse(
    "Create a security agent that validates bash commands "
    "for injection attacks and provides mitigation advice"
)

print(f"Domain: {intent.domain}")
print(f"Action: {intent.action}")
print(f"Complexity: {intent.complexity}")
print(f"Agent count: {len(intent.agent_requirements)}")

4.3.3 BundlePackager Class¶

File: packager.py:1-250

Purpose: Package generated agents into distributable bundles.

Key Methods:

def package(
    self,
    agents: List[GeneratedAgent],
    bundle_name: str,
    output_dir: Path
) -> Path:
    """
    Package agents into a bundle.

    Args:
        agents: List of generated agents
        bundle_name: Name for the bundle
        output_dir: Output directory

    Returns:
        Path to created bundle
    """

Bundle Structure:

bundle-name/
├── agents/
│   ├── agent1.md
│   └── agent2.md
├── tests/
│   ├── test_agent1.py
│   └── test_agent2.py
├── manifest.json
├── README.md
└── setup.py (optional)

4.4 Security Module¶

Location: /home/azureuser/src/amplihack-worktree-921-922/src/amplihack/security/

Search Terms: security, xpia, validation, threat detection, cross-prompt injection

4.4.1 XPIADefender Class¶

File: xpia_defender.py:42-513

Purpose: Core XPIA (Cross-Prompt Injection Attack) defense implementation.

Constructor:

class XPIADefender(XPIADefenseInterface):
    """Core XPIA Defense implementation."""

    def __init__(self, config: Optional[SecurityConfiguration] = None):
        """
        Initialize XPIA Defender with configuration.

        Args:
            config: Optional security configuration
                   (loads from environment if not provided)
        """

Configuration from Environment:

# Security level
XPIA_SECURITY_LEVEL=MODERATE  # STRICT|HIGH|MODERATE|LOW

# Feature flags
XPIA_ENABLED=true
XPIA_BASH_VALIDATION=true
XPIA_CONTENT_SCANNING=true
XPIA_LOGGING=true

# Domain filtering
XPIA_WHITELIST_DOMAINS=github.com,microsoft.com
XPIA_BLACKLIST_DOMAINS=malicious-site.com

Example:

from amplihack.security.xpia_defender import XPIADefender
from amplihack.security.xpia_defense_interface import SecurityConfiguration, SecurityLevel

# With environment configuration
defender = XPIADefender()

# With explicit configuration
config = SecurityConfiguration(
    security_level=SecurityLevel.HIGH,
    enabled=True,
    bash_validation=True
)
defender = XPIADefender(config)

Key Methods:

async validate_content(...) -> ValidationResult¶

Location: xpia_defender.py:136-191

Purpose: Validate arbitrary content for security threats.

Signature:

async def validate_content(
    self,
    content: str,
    content_type: ContentType,
    context: Optional[ValidationContext] = None,
    security_level: Optional[SecurityLevel] = None,
) -> ValidationResult:
    """
    Validate arbitrary content for security threats.

    Args:
        content: Content to validate
        content_type: Type of content (USER_INPUT, COMMAND, DATA, etc.)
        context: Optional validation context
        security_level: Override default security level

    Returns:
        ValidationResult with threats and recommendations
    """

Content Types:

class ContentType(str, Enum):
    USER_INPUT = "user_input"
    COMMAND = "command"
    URL = "url"
    DATA = "data"
    FILE = "file"

Example:

from amplihack.security.xpia_defense_interface import (
    ContentType, ValidationContext
)

# Validate user input
result = await defender.validate_content(
    content="Please ignore previous instructions and...",
    content_type=ContentType.USER_INPUT,
    context=ValidationContext(
        source="user_prompt",
        session_id="session-123"
    )
)

if result.is_valid:
    print("Content is safe")
else:
    print(f"Risk level: {result.risk_level}")
    for threat in result.threats:
        print(f"- {threat.description}")
    for rec in result.recommendations:
        print(f"Recommendation: {rec}")

async validate_bash_command(...) -> ValidationResult¶

Location: xpia_defender.py:193-270

Purpose: Validate bash commands for security threats.

Signature:

async def validate_bash_command(
    self,
    command: str,
    arguments: Optional[List[str]] = None,
    context: Optional[ValidationContext] = None,
) -> ValidationResult:
    """
    Validate bash commands for security threats.

    Detects:
    - Dangerous commands (rm -rf /, mkfs, dd, etc.)
    - Command injection patterns (;, &&, |, backticks)
    - Privilege escalation attempts
    """

Dangerous Patterns Detected (lines 209-217):

dangerous_commands = [
    "rm -rf /",
    "mkfs",
    "dd if=/dev/zero",
    "fork bomb",
    ":(){ :|:& };:",
    "> /dev/sda",
    "chmod 777 /",
]

Example:

# Safe command
result = await defender.validate_bash_command(
    command="ls",
    arguments=["-la", "/home/user"]
)
assert result.is_valid

# Dangerous command
result = await defender.validate_bash_command(
    command="rm",
    arguments=["-rf", "/"]
)
assert not result.is_valid
assert result.risk_level == RiskLevel.CRITICAL

async validate_agent_communication(...) -> ValidationResult¶

Location: xpia_defender.py:272-324

Purpose: Validate inter-agent communication for security.

Signature:

async def validate_agent_communication(
    self,
    source_agent: str,
    target_agent: str,
    message: Dict[str, Any],
    message_type: str = "task",
) -> ValidationResult:
    """
    Validate inter-agent communication.

    Detects:
    - Privilege escalation attempts
    - Injection attacks in messages
    - Suspicious content
    """

Example:

result = await defender.validate_agent_communication(
    source_agent="builder",
    target_agent="reviewer",
    message={
        "task": "Review the implementation",
        "files": ["src/main.py"]
    },
    message_type="task"
)

async health_check() -> Dict[str, Any]¶

Location: xpia_defender.py:347-357

Purpose: Perform health check and return status.

Returns:

{
    "status": "healthy",
    "enabled": True,
    "security_level": "MODERATE",
    "patterns_loaded": 50,
    "whitelist_size": 10,
    "blacklist_size": 2,
    "events_logged": 15
}

4.4.2 WebFetchXPIADefender Class¶

File: xpia_defender.py:515-673

Purpose: Specialized XPIA defender for WebFetch tool.

Key Methods:

async validate_webfetch_request(url: str, prompt: str, ...) -> ValidationResult¶

Location: xpia_defender.py:522-557

Purpose: Validate WebFetch requests (URL + prompt combination).

Checks:

• URL validation (domain, parameters, protocol)
• Prompt validation (injection patterns)
• Combined attack detection (URL referenced in malicious prompts)

Example:

from amplihack.security.xpia_defender import WebFetchXPIADefender

defender = WebFetchXPIADefender()

result = await defender.validate_webfetch_request(
    url="https://github.com/microsoft/TypeScript",
    prompt="Summarize the README file"
)

if result.is_valid:
    # Safe to fetch
    pass

4.4.3 Risk Levels and Threat Types¶

Risk Levels (xpia_defense_interface.py):

class RiskLevel(str, Enum):
    NONE = "none"
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"
    CRITICAL = "critical"

Threat Types:

class ThreatType(str, Enum):
    INJECTION = "injection"
    PRIVILEGE_ESCALATION = "privilege_escalation"
    DATA_EXFILTRATION = "data_exfiltration"
    MALICIOUS_CODE = "malicious_code"
    SOCIAL_ENGINEERING = "social_engineering"

4.5 Memory Module¶

Location: /home/azureuser/src/amplihack-worktree-921-922/src/amplihack/memory/

Search Terms: memory, session, persistence, database, conversation history

Purpose: Manage session persistence and conversation history.

Key Files:

• manager.py:1-300 - Memory management
• database.py:1-250 - SQLite database operations
• models.py:1-150 - Data models
• maintenance.py:1-200 - Cleanup and optimization

Status: 🚧 Experimental (not yet fully integrated)

4.6 Utilities Module¶

Location: /home/azureuser/src/amplihack-worktree-921-922/src/amplihack/utils/

Search Terms: utilities, helpers, tools, claude cli, prerequisites

4.6.1 Prerequisites Checking¶

File: prerequisites.py:1-150

Purpose: Check and validate required tools.

Key Function:

def check_prerequisites() -> bool:
    """
    Check all required prerequisites.

    Checks:
    - Node.js (version 18+)
    - npm
    - git
    - claude CLI or claude-trace

    Returns:
        True if all prerequisites met, False otherwise
    """

Example:

from amplihack.utils.prerequisites import check_prerequisites

if not check_prerequisites():
    print("Missing prerequisites")
    sys.exit(1)

4.6.2 Claude CLI Utilities¶

File: claude_cli.py:1-200

Purpose: Utilities for detecting and managing Claude CLI.

Key Functions:

def get_claude_cli_path(auto_install: bool = True) -> Optional[str]:
    """
    Get path to Claude CLI executable.

    Args:
        auto_install: Attempt to install if not found

    Returns:
        Path to claude or None
    """

def install_claude_cli() -> bool:
    """
    Install Claude CLI via npm.

    Returns:
        True if installation successful
    """

Example:

from amplihack.utils.claude_cli import (
    get_claude_cli_path,
    install_claude_cli
)

claude_path = get_claude_cli_path(auto_install=False)
if not claude_path:
    if install_claude_cli():
        claude_path = get_claude_cli_path(auto_install=False)

4.6.3 Claude-Trace Integration¶

File: claude_trace.py:1-150

Purpose: Integration with claude-trace for debugging.

Key Functions:

def get_claude_command() -> str:
    """
    Get appropriate Claude command (claude-trace or claude).

    Checks:
    - AMPLIHACK_USE_TRACE environment variable
    - claude-trace availability

    Returns:
        "claude-trace" or "claude"
    """

def is_trace_available() -> bool:
    """Check if claude-trace is available."""

Example:

import os
from amplihack.utils.claude_trace import get_claude_command

# Enable tracing
os.environ["AMPLIHACK_USE_TRACE"] = "1"

cmd = get_claude_command()
# Returns: "claude-trace" if available, else "claude"

5. Configuration Guide¶

Complete configuration reference with examples

Search Terms: configuration, setup, environment variables, config files

5.1 Environment Configuration¶

5.1.1 Project Environment Variables¶

Core Variables:

# Claude Project Directory (automatically set by launcher)
CLAUDE_PROJECT_DIR=/path/to/project

# Enable Claude-Trace debugging
AMPLIHACK_USE_TRACE=1

# UVX mode (automatically detected)
AMPLIHACK_UVX_MODE=1

Location: Set by launcher automatically or in shell profile

5.1.2 Python Environment¶

pyproject.toml:

# /home/azureuser/src/amplihack-worktree-921-922/pyproject.toml

[project]
name = "microsofthackathon2025-agenticcoding"
version = "0.1.0"
requires-python = ">=3.8"

dependencies = [
    "flask>=2.0.0",
    "requests>=2.25.0",
    "fastapi>=0.68.0",
    "uvicorn>=0.15.0",
    "aiohttp>=3.8.0",
    "litellm>=1.0.0",
    "python-dotenv>=0.19.0",
]

[project.scripts]
amplihack = "amplihack:main"

Installation:

# Development install
cd /path/to/amplihack-worktree-921-922
uv pip install -e .

# Or via uvx (no install)
uvx --from git+https://github.com/rysweet/MicrosoftHackathon2025-AgenticCoding amplihack

5.2 Claude Configuration¶

5.2.1 .claude Directory Structure¶

Location: /home/azureuser/src/amplihack-worktree-921-922/.claude/

.claude/
├── agents/                     # Agent definitions
│   └── amplihack/
│       ├── core/              # Core agents (10+)
│       ├── specialized/       # Specialized agents (15+)
│       └── workflows/         # Workflow agents (5+)
├── commands/                  # Slash commands
│   └── amplihack/
│       ├── ultrathink.md
│       ├── analyze.md
│       ├── fix.md
│       ├── improve.md
│       └── customize.md
├── context/                   # Philosophy and patterns
│   ├── PHILOSOPHY.md
│   ├── PATTERNS.md
│   ├── PROJECT.md
│   ├── USER_PREFERENCES.md
│   └── DISCOVERIES.md
├── workflow/                  # Development workflows
│   └── DEFAULT_WORKFLOW.md
├── hooks/                     # Git-style hooks
├── runtime/                   # Runtime data
│   ├── logs/                  # Session logs
│   └── reports/               # Analysis reports
├── scenarios/                 # Production tools
└── settings.json              # Claude settings

Detection: Launcher automatically finds .claude directory in current or parent directories.

5.2.2 settings.json¶

Location: .claude/settings.json

{
  "mcp": {
    "enabled": true,
    "servers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
      }
    }
  },
  "permissions": {
    "dangerouslySkipPermissions": true
  }
}

Management: Automatically backed up and restored by launcher (lines launcher/settings_manager.py:1-150)

5.3 Proxy Configuration¶

5.3.1 Azure OpenAI Configuration¶

File: azure.env (user-created in project root)

Template (see .env.security-template):

# Required: Azure OpenAI credentials
OPENAI_API_KEY=your-azure-api-key-here
OPENAI_BASE_URL=https://your-instance.openai.azure.com/openai/deployments/gpt-4/chat/completions?api-version=2025-01-01-preview

# Or use separate endpoint and version
AZURE_OPENAI_ENDPOINT=https://your-instance.openai.azure.com
AZURE_OPENAI_API_KEY=your-azure-api-key-here
AZURE_OPENAI_API_VERSION=2025-01-01-preview

# Model mappings to your Azure deployments
BIG_MODEL=gpt-4
MIDDLE_MODEL=gpt-4
SMALL_MODEL=gpt-4o-mini

# Optional: Specific deployment names
AZURE_GPT4_DEPLOYMENT=my-gpt4-deployment
AZURE_GPT4_TURBO_DEPLOYMENT=my-gpt4-turbo-deployment
AZURE_GPT4_MINI_DEPLOYMENT=my-gpt4-mini-deployment
AZURE_GPT35_DEPLOYMENT=my-gpt35-deployment

# Performance settings
REQUEST_TIMEOUT=300            # Timeout in seconds
MAX_TOKENS_LIMIT=512000        # Maximum context size
MAX_RETRIES=2                  # Retry attempts

# Proxy settings
PORT=8000                      # Proxy port
HOST=127.0.0.1                 # Proxy host
LOG_LEVEL=INFO                 # Logging level

Validation (proxy/config.py:240-297):

• API key format validation
• Endpoint URL validation (must be HTTPS)
• API version format (YYYY-MM-DD or YYYY-MM-DD-preview)
• Deployment name validation

Usage:

amplihack claude --with-proxy-config ./azure.env

5.3.2 GitHub Copilot Configuration¶

File: github.env (user-created)

# GitHub Copilot configuration
GITHUB_TOKEN=ghp_your_token_here
GITHUB_COPILOT_ENABLED=true
GITHUB_COPILOT_ENDPOINT=https://api.github.com

# Optional: LiteLLM integration
GITHUB_COPILOT_LITELLM_ENABLED=true
GITHUB_COPILOT_MODEL=copilot-gpt-4

# Proxy settings
PORT=8000
HOST=127.0.0.1
LOG_LEVEL=INFO

Token Format (proxy/config.py:481-506):

• GitHub tokens: gho_, ghp_, ghs_, ghu_, ghr_ prefix
• Legacy tokens: 40-character hex string
• Test tokens: test-, fake-, dummy- prefix (for development)

Usage:

amplihack copilot --with-proxy-config ./github.env

5.3.3 Model Mapping¶

Azure Model Mapping (proxy/azure_models.py:20-150):

GitHub Model Mapping (proxy/github_models.py:1-150):

Custom Mapping:

# In azure.env
AZURE_MODEL_MAPPING='{"claude-3-opus": "my-custom-gpt4-deployment"}'

5.4 Security Configuration¶

5.4.1 XPIA Security Configuration¶

Environment Variables:

# Security level (STRICT|HIGH|MODERATE|LOW)
XPIA_SECURITY_LEVEL=MODERATE

# Enable/disable XPIA defense
XPIA_ENABLED=true

# Feature flags
XPIA_BASH_VALIDATION=true      # Validate bash commands
XPIA_CONTENT_SCANNING=true     # Scan content for threats
XPIA_LOGGING=true              # Log security events

# Domain filtering
XPIA_WHITELIST_DOMAINS=github.com,microsoft.com,stackoverflow.com
XPIA_BLACKLIST_DOMAINS=malicious-site.com,phishing-site.com

# File-based configuration
XPIA_WHITELIST_FILE=.xpia_whitelist
XPIA_BLACKLIST_FILE=.xpia_blacklist

Security Levels (security/xpia_defender.py:61-84):

5.4.2 Whitelist/Blacklist Files¶

.xpia_whitelist (project root):

# Safe domains (one per line)
github.com
microsoft.com
azure.com
openai.com
anthropic.com
stackoverflow.com
python.org
nodejs.org

.xpia_blacklist (project root):

# Blocked domains (one per line)
malicious-site.com
phishing-site.com
known-bad-domain.com

Default Whitelisted Domains (security/xpia_defender.py:101-115):

• github.com
• microsoft.com
• azure.com
• openai.com
• anthropic.com
• stackoverflow.com
• python.org
• nodejs.org
• npmjs.com
• pypi.org

5.4.3 Pre-commit Security Hooks¶

File: .pre-commit-config.yaml

repos:
  - repo: local
    hooks:
      - id: detect-secrets
        name: Detect secrets
        entry: detect-secrets-hook
        language: system
        args: ["--baseline", ".secrets.baseline"]

      - id: gitguardian
        name: GitGuardian scan
        entry: ggshield secret scan pre-commit
        language: system

Configuration:

# .gitguardian.yaml
minimum-severity: CRITICAL
ignore-known-secrets: true

See Also: Section 6.3 (Testing Workflow)

6. Development Workflows¶

Standard workflows for common development tasks

Search Terms: workflows, development process, testing, ci/cd, git workflow

6.1 Local Development Setup¶

6.1.1 Initial Setup¶

Prerequisites:

1. Python 3.8+
2. Node.js 18+
3. npm
4. git
5. uv (https://docs.astral.sh/uv/)

Installation:

# Clone repository
git clone https://github.com/rysweet/MicrosoftHackathon2025-AgenticCoding.git
cd MicrosoftHackathon2025-AgenticCoding

# Install dependencies
uv pip install -e .

# Install development dependencies
uv pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Verify installation
amplihack --help

6.1.2 Development Environment¶

Create Azure configuration:

# Copy example configuration
cp .env.security-template azure.env

# Edit with your credentials
nano azure.env

# Test configuration
python -c "
from amplihack.proxy.config import ProxyConfig
from pathlib import Path
config = ProxyConfig(Path('azure.env'))
print('Valid:', config.validate())
"

Launch development instance:

# With Azure proxy
amplihack claude --with-proxy-config ./azure.env

# With local changes (editable install)
python -m amplihack claude

6.1.3 Directory Structure for Development¶

amplihack-worktree-921-922/
├── .claude/                    # Claude configuration (version controlled)
├── src/amplihack/              # Source code
│   ├── launcher/
│   ├── proxy/
│   ├── bundle_generator/
│   ├── security/
│   └── ...
├── tests/                      # Test suite
│   ├── launcher/
│   ├── proxy/
│   └── ...
├── docs/                       # Documentation
├── examples/                   # Example scripts
├── scripts/                    # Utility scripts
├── azure.env                   # Your Azure config (not committed)
├── pyproject.toml              # Project metadata
└── README.md                   # Project readme

6.2 Agent Development¶

6.2.1 Creating a New Agent¶

Step 1: Determine Agent Type

• Core Agent: Fundamental functionality (architect, builder, reviewer)

• Location: .claude/agents/amplihack/core/

• Specialized Agent: Specific domain expertise (security, optimizer, database)

• Location: .claude/agents/amplihack/specialized/

• Workflow Agent: Complete workflows (ci-diagnostic, pre-commit)

• Location: .claude/agents/amplihack/workflows/

Step 2: Create Agent File

File: .claude/agents/amplihack/specialized/my-agent.md

# My Agent

Brief description of what this agent does.

## Role

Primary role and responsibility of this agent.

## Model Configuration

Model: inherit

## Capabilities

- Capability 1: Description
- Capability 2: Description
- Capability 3: Description

## Core Responsibilities

1. **Primary**: Main responsibility
2. **Validation**: Ensure input quality
3. **Processing**: Execute core operations
4. **Error Handling**: Handle failures gracefully
5. **Reporting**: Provide clear feedback

## Implementation

### Input Processing

Describe expected input format and validation.

### Core Algorithm

```python
def process(input_data):
    # Pseudocode or actual implementation
    pass
```

Output Format¶

Describe output structure and format.

Context and Philosophy¶

This agent follows amplihack philosophy:

• Ruthless Simplicity
• Modular Design
• Zero-BS Implementation
• Regeneratable

Error Handling¶

Describe error handling strategy:

1. Input validation errors
2. Processing errors
3. Resource errors
4. Recovery strategies

Performance Considerations¶

• Latency requirements
• Throughput expectations
• Memory usage
• Scalability

Dependencies¶

List any dependencies on other agents or services.

Example Usage¶

# Example 1: Basic usage
result = my_agent.process(input_data)

# Example 2: With options
result = my_agent.process(input_data, options={...})

Testing¶

Describe testing strategy and test coverage.

---

**Step 3: Test Agent**

```bash
# Launch Claude and test agent
amplihack claude

# In Claude:
# "Use my-agent to process this data..."

6.2.2 Using Bundle Generator¶

Create agent via CLI:

# Interactive mode
python -m amplihack.bundle_generator.cli create

# Or specify requirements
python -m amplihack.bundle_generator.cli create \
  --name my-agent \
  --description "Agent that does X" \
  --output ./my-agent-bundle

Programmatic creation:

from amplihack.bundle_generator.parser import IntentParser
from amplihack.bundle_generator.generator import AgentGenerator
from amplihack.bundle_generator.packager import BundlePackager

# Parse requirements
parser = IntentParser()
intent = parser.parse(
    "Create an agent that validates JSON schemas "
    "and provides detailed error messages"
)

# Generate agents
generator = AgentGenerator()
agents = generator.generate(intent)

# Package into bundle
packager = BundlePackager()
bundle_path = packager.package(
    agents=agents,
    bundle_name="json-validator",
    output_dir=Path("./bundles")
)

print(f"Bundle created at: {bundle_path}")

See Also: Section 4.3 (Bundle Generator Module), Section 7.1 (Creating Custom Agents)

6.3 Testing Workflow¶

6.3.1 Running Tests¶

Run all tests:

# Using pytest
pytest tests/

# With coverage
pytest --cov=amplihack tests/

# Specific module
pytest tests/launcher/
pytest tests/proxy/

Test configuration (pyproject.toml:78-105):

[tool.pytest.ini_options]
testpaths = ["tests", "src"]
python_files = ["test_*.py", "*_test.py"]
addopts = ["-ra", "--strict-markers", "--tb=short"]
pythonpath = ["src"]

markers = [
    "slow: marks tests as slow",
    "integration: marks tests as integration tests",
    "performance: marks tests as performance tests",
]

6.3.2 Test Structure¶

Test organization:

tests/
├── launcher/
│   ├── test_core.py
│   ├── test_detector.py
│   └── test_repo_checkout.py
├── proxy/
│   ├── test_config.py
│   ├── test_integrated_proxy.py
│   └── test_azure_handler.py
├── bundle_generator/
│   ├── test_parser.py
│   ├── test_generator.py
│   └── test_packager.py
└── security/
    ├── test_xpia_defender.py
    ├── test_xpia_patterns.py
    └── test_xpia_hooks.py

6.3.3 Writing Tests¶

Example test:

# tests/proxy/test_config.py

import pytest
from pathlib import Path
from amplihack.proxy.config import ProxyConfig

def test_azure_config_validation():
    """Test Azure configuration validation."""
    # Create test config file
    test_config = Path("test_azure.env")
    test_config.write_text("""
AZURE_OPENAI_API_KEY=test-key-12345678901234567890
AZURE_OPENAI_ENDPOINT=https://test.openai.azure.com
AZURE_OPENAI_API_VERSION=2025-01-01-preview
    """)

    try:
        # Load and validate
        config = ProxyConfig(test_config)
        assert config.is_azure_endpoint()
        assert config.validate()

        # Test model mapping
        deployment = config.get_azure_deployment("gpt-4")
        assert deployment is not None
    finally:
        # Cleanup
        test_config.unlink()

def test_invalid_config():
    """Test that invalid configuration is rejected."""
    test_config = Path("test_invalid.env")
    test_config.write_text("""
AZURE_OPENAI_API_KEY=short
AZURE_OPENAI_ENDPOINT=http://insecure.com
    """)

    try:
        config = ProxyConfig(test_config)
        assert not config.validate()
        errors = config.get_validation_errors()
        assert len(errors) > 0
    finally:
        test_config.unlink()

6.3.4 Pre-commit Checks¶

Run pre-commit hooks manually:

# Run all hooks
pre-commit run --all-files

# Run specific hook
pre-commit run black --all-files
pre-commit run ruff --all-files

# Install hooks (run once)
pre-commit install

Hooks configuration (.pre-commit-config.yaml):

repos:
  - repo: https://github.com/psf/black
    rev: 22.10.0
    hooks:
      - id: black
        language_version: python3.8

  - repo: https://github.com/charliermarsh/ruff-pre-commit
    rev: v0.1.0
    hooks:
      - id: ruff
        args: [--fix, --exit-non-zero-on-fix]

  - repo: local
    hooks:
      - id: detect-secrets
        name: Detect secrets
        entry: detect-secrets-hook
        language: system

6.4 CI/CD Integration¶

6.4.1 GitHub Actions Workflow¶

File: .github/workflows/ci.yml

name: CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: [3.8, 3.9, "3.10", "3.11"]

    steps:
      - uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: ${{ matrix.python-version }}

      - name: Install dependencies
        run: |
          pip install uv
          uv pip install -e ".[dev]"

      - name: Run tests
        run: |
          pytest tests/ --cov=amplihack --cov-report=xml

      - name: Upload coverage
        uses: codecov/codecov-action@v3
        with:
          file: ./coverage.xml

6.4.2 Using CI Diagnostic Workflow¶

When CI fails after push:

# In Claude Code
/amplihack:fix ci

# Or manually invoke ci-diagnostic agent
@.claude/agents/amplihack/workflows/ci-diagnostic-workflow.md

# Agent will:
# 1. Check CI status
# 2. Diagnose failures
# 3. Fix issues
# 4. Push fixes
# 5. Iterate until mergeable

See Also: CLAUDE.md:147-193 for workflow documentation

7. Common Tasks¶

Step-by-step guides for frequent operations

Search Terms: how to, guides, tutorials, common tasks, examples

7.1 Creating Custom Agents¶

Task: Create a custom agent using Bundle Generator¶

Time: 5-10 minutes

Steps:

1. Define Requirements:

# requirements.txt or inline
"""
Create an agent that:
- Validates Python code style
- Checks for common anti-patterns
- Suggests improvements
- Integrates with pylint and black
"""

1. Generate Agent:

python -m amplihack.bundle_generator.cli create \
  --interactive

# Or non-interactive
python -m amplihack.bundle_generator.cli create \
  --name python-style-validator \
  --description "Validates Python code style and suggests improvements" \
  --output ./bundles/python-validator

1. Review Generated Files:

cd bundles/python-validator
tree

# Output:
# python-validator/
# ├── agents/
# │   └── python_style_validator.md
# ├── tests/
# │   └── test_python_style_validator.py
# ├── README.md
# └── manifest.json

1. Install Agent:

# Copy to project
cp agents/python_style_validator.md \
   ~/.claude/agents/amplihack/specialized/

# Or use in specific project
cp agents/python_style_validator.md \
   /path/to/project/.claude/agents/

1. Test Agent:

amplihack claude
# In Claude: "Use python-style-validator to check my code"

See Also: Section 4.3 (Bundle Generator Module), Section 9.1 (Agent Creation Examples)

7.2 Configuring Azure Integration¶

Task: Set up Azure OpenAI integration for Claude Code¶

Time: 5 minutes

Steps:

1. Obtain Azure Credentials:

2. Azure OpenAI endpoint URL

3. API key
4. Deployment names (optional)

5. API version (e.g., 2025-01-01-preview)

6. Create Configuration File:

# Create azure.env in project root
cat > azure.env << 'EOF'
# Azure OpenAI Configuration
OPENAI_API_KEY=your-actual-azure-api-key
AZURE_OPENAI_ENDPOINT=https://your-instance.openai.azure.com
AZURE_OPENAI_API_VERSION=2025-01-01-preview

# Model mappings
BIG_MODEL=gpt-4
MIDDLE_MODEL=gpt-4
SMALL_MODEL=gpt-4o-mini

# Optional: Specific deployments
AZURE_GPT4_DEPLOYMENT=my-gpt4-deployment

# Performance settings
REQUEST_TIMEOUT=300
MAX_TOKENS_LIMIT=512000
MAX_RETRIES=2

# Proxy settings
PORT=8000
HOST=127.0.0.1
LOG_LEVEL=INFO
EOF

1. Validate Configuration:

python -c "
from amplihack.proxy.config import ProxyConfig
from pathlib import Path

config = ProxyConfig(Path('azure.env'))
if config.validate():
    print('✓ Configuration valid')
    print(f'  Endpoint: {config.get_azure_endpoint()}')
    print(f'  API Version: {config.get_azure_api_version()}')
else:
    print('✗ Configuration invalid')
    for error in config.get_validation_errors():
        print(f'  - {error}')
"

1. Launch Claude with Azure:

amplihack claude --with-proxy-config ./azure.env

1. Verify Proxy Connection:

# Check proxy logs
tail -f /tmp/amplihack_logs/proxy-stdout-*.log

# In Claude, run a test query:
# "Hello, can you confirm you're running through Azure?"

Troubleshooting:

• API Key Invalid: Verify key format (20+ characters, alphanumeric)
• Endpoint Unreachable: Check HTTPS URL and network connectivity
• Model Not Found: Verify deployment names match Azure configuration
• Timeout: Increase REQUEST_TIMEOUT in config

See Also: Section 5.3 (Proxy Configuration), Section 8.1 (Common Issues)

7.3 Adding Slash Commands¶

Task: Create a custom slash command¶

Time: 10-15 minutes

Steps:

1. Create Command File:

# Create command in project .claude directory
mkdir -p .claude/commands/amplihack
nano .claude/commands/amplihack/my-command.md

1. Write Command Definition:

# Command: /amplihack:my-command

You are executing the `/amplihack:my-command` slash command.

## Purpose

This command does [describe what it does].

## Usage

/amplihack:my-command [arguments]

## Arguments

- `arg1`: Description of first argument
- `arg2`: Description of second argument (optional)

## Process

1. Step 1: [What to do first]
2. Step 2: [What to do second]
3. Step 3: [What to do third]

## Example

User: `/amplihack:my-command value1 value2`

Agent executes:
1. Parse arguments
2. Perform operation
3. Return results

## Output Format

Provide results in this format:
- Item 1
- Item 2
- Summary

## Error Handling

If command fails:
1. Explain what went wrong
2. Suggest corrections
3. Provide examples

1. Test Command:

amplihack claude

# In Claude:
# /amplihack:my-command arg1 arg2

1. Document Command:

Update .claude/commands/README.md:

## Custom Commands

### /amplihack:my-command

Description: [Brief description]

Usage: `/amplihack:my-command [args]`

See: `.claude/commands/amplihack/my-command.md`

Command Best Practices:

• Clear purpose statement
• Explicit step-by-step process
• Error handling guidance
• Examples of expected usage
• Output format specification

See Also: Section 1.2 (Quick Reference - Slash Commands)

7.4 Working with Proxy¶

Task: Debug proxy issues and monitor requests¶

Time: Varies

7.4.1 Enable Proxy Logging:

# In azure.env
LOG_LEVEL=DEBUG

# Launch with logging
amplihack claude --with-proxy-config ./azure.env

7.4.2 Monitor Proxy Logs:

# Tail stdout
tail -f /tmp/amplihack_logs/proxy-stdout-*.log

# Tail stderr
tail -f /tmp/amplihack_logs/proxy-stderr-*.log

# Or use the auto-opened terminal window (macOS)
# Launcher automatically opens terminal with both logs

7.4.3 Test Proxy Directly:

import requests

# Test proxy health
response = requests.get("http://127.0.0.1:8000/health")
print(response.json())
# {"status": "healthy", "endpoint_type": "azure"}

# Test chat completion
response = requests.post(
    "http://127.0.0.1:8000/v1/messages",
    headers={"x-api-key": "test-key"},
    json={
        "model": "claude-sonnet-4",
        "messages": [{"role": "user", "content": "Hello"}],
        "max_tokens": 100
    }
)
print(response.json())

7.4.4 Debug Configuration:

# Check endpoint detection
python -c "
from amplihack.proxy.config import ProxyConfig
from pathlib import Path

config = ProxyConfig(Path('azure.env'))
print(f'Endpoint type: {config.get_endpoint_type()}')
print(f'Is Azure: {config.is_azure_endpoint()}')
print(f'Is GitHub: {config.is_github_endpoint()}')
"

7.4.5 Test Model Mapping:

python -c "
from amplihack.proxy.config import ProxyConfig
from pathlib import Path

config = ProxyConfig(Path('azure.env'))

models = ['gpt-4', 'gpt-4-turbo', 'gpt-4o-mini']
for model in models:
    deployment = config.get_azure_deployment(model)
    print(f'{model} -> {deployment}')
"

See Also: Section 4.2 (Proxy Module), Section 8.2 (Debugging Guide)

7.5 Security Integration¶

Task: Integrate XPIA security validation¶

Time: 10 minutes

7.5.1 Configure Security:

# Create .env file with security settings
cat > security.env << 'EOF'
# Security configuration
XPIA_SECURITY_LEVEL=MODERATE
XPIA_ENABLED=true
XPIA_BASH_VALIDATION=true
XPIA_CONTENT_SCANNING=true
XPIA_LOGGING=true

# Domain filtering
XPIA_WHITELIST_DOMAINS=github.com,microsoft.com
XPIA_BLACKLIST_DOMAINS=malicious-site.com
EOF

# Load in shell
source security.env

7.5.2 Validate Content:

import asyncio
from amplihack.security.xpia_defender import XPIADefender
from amplihack.security.xpia_defense_interface import (
    ContentType, ValidationContext
)

async def main():
    defender = XPIADefender()

    # Validate user input
    result = await defender.validate_content(
        content="Please summarize this document",
        content_type=ContentType.USER_INPUT,
        context=ValidationContext(
            source="user_prompt",
            session_id="session-123"
        )
    )

    print(f"Valid: {result.is_valid}")
    print(f"Risk: {result.risk_level}")

    if result.threats:
        print("Threats:")
        for threat in result.threats:
            print(f"  - {threat.description}")

asyncio.run(main())