aia 0.9.11 → 0.9.12

data/docs/examples/index.md

@@ -0,0 +1,277 @@
+# Examples
+
+This section contains comprehensive examples demonstrating AIA's capabilities across different use cases and domains.
+
+## Example Categories
+
+### [Prompts](prompts/index.md)
+Real-world prompt examples covering:
+- **Development**: Code review, documentation, debugging
+- **Writing**: Blog posts, technical documentation, creative writing
+- **Analysis**: Data analysis, report generation, research
+- **Automation**: System administration, workflow automation
+- **Learning**: Educational prompts, concept explanations
+
+### [Tools](tools/index.md)
+Custom Ruby tools that extend AIA's functionality:
+- **File Processing**: Advanced file operations and analysis
+- **Web Integration**: HTTP clients, API interactions, web scraping
+- **Data Analysis**: Statistical analysis, data transformation
+- **Development Tools**: Code analysis, testing utilities
+- **System Integration**: OS interaction, external service integration
+
+### [MCP Clients](mcp/index.md)
+Model Context Protocol client examples:
+- **GitHub Integration**: Repository management, issue tracking
+- **File System Access**: Safe file operations with sandboxing
+- **Database Connectivity**: SQL querying, data manipulation
+- **API Integrations**: Third-party service connections
+- **Development Environments**: IDE and editor integrations
+
+## Getting Started with Examples
+
+### 1. Browse by Use Case
+
+Each example includes:
+- **Purpose**: What the example demonstrates
+- **Prerequisites**: Required setup or dependencies
+- **Usage**: How to run the example
+- **Customization**: How to adapt for your needs
+- **Related Examples**: Similar or complementary examples
+
+### 2. Copy and Modify
+
+All examples are designed to be:
+- **Copyable**: Ready to use with minimal setup
+- **Modifiable**: Easy to customize for your specific needs
+- **Educational**: Well-commented and explained
+- **Production-Ready**: Following best practices
+
+### 3. Combine Examples
+
+Many examples can be combined:
+- Use multiple prompts in a workflow
+- Combine tools for complex operations
+- Chain MCP clients for advanced integrations
+
+## Quick Start Examples
+
+### Simple Code Review
+```bash
+# Copy the code review prompt
+cp docs/examples/prompts/development/code_review.txt ~/.prompts/
+
+# Use it on your code
+aia code_review src/main.rb
+```
+
+### Data Analysis Workflow
+```bash
+# Copy the analysis pipeline
+cp docs/examples/prompts/analysis/data_pipeline.txt ~/.prompts/
+
+# Run the complete workflow
+aia --pipeline "extract_data,analyze_data,generate_report" dataset.csv
+```
+
+### Custom Tool Integration
+```bash
+# Copy a useful tool
+cp docs/examples/tools/file_analyzer.rb ~/.aia/tools/
+
+# Use it in a prompt
+aia --tools ~/.aia/tools/file_analyzer.rb analyze_project
+```
+
+## Example Structure
+
+Each example directory contains:
+
+```
+category/
+├── README.md           # Category overview and index
+├── basic/              # Simple, beginner-friendly examples
+├── intermediate/       # More complex examples
+├── advanced/          # Expert-level examples
+└── specialized/       # Domain-specific examples
+```
+
+Individual examples include:
+- **Source file** (`.txt`, `.rb`, `.json`, etc.)
+- **Documentation** (`README.md` or inline comments)
+- **Usage examples** with sample inputs/outputs
+- **Customization guide**
+
+## Contributing Examples
+
+We welcome example contributions! See our [contribution guidelines](../contributing.md) for:
+- Example standards and format
+- Documentation requirements
+- Testing and validation
+- Submission process
+
+## Example Categories Overview
+
+### [Prompts Examples](prompts/index.md)
+
+#### Development
+- Code review and optimization prompts
+- Documentation generation
+- Debugging assistance
+- Architecture analysis
+- Testing strategy prompts
+
+#### Writing  
+- Technical documentation templates
+- Blog post generation
+- Creative writing prompts
+- Content editing and improvement
+- Style guide enforcement
+
+#### Analysis
+- Data analysis workflows
+- Research methodology prompts
+- Report generation templates
+- Comparative analysis
+- Trend identification
+
+#### Automation
+- System monitoring prompts
+- Deployment workflows
+- Log analysis automation
+- Maintenance task prompts
+- Alert and notification templates
+
+### [Tools Examples](tools/index.md)
+
+#### File Processing
+- Log file analyzers
+- Configuration file processors  
+- Code metrics calculators
+- Document converters
+- Archive handlers
+
+#### Web Integration
+- HTTP API clients
+- Web scraping tools
+- Content fetchers
+- Social media integrations
+- Webhook handlers
+
+#### Data Analysis
+- Statistical calculators
+- Data visualizers
+- CSV/JSON processors
+- Database query tools
+- Report generators
+
+#### Development
+- Code quality analyzers
+- Dependency checkers
+- Performance profilers
+- Test runners
+- Deployment tools
+
+### [MCP Examples](mcp/index.md)
+
+#### GitHub Integration
+- Repository analysis
+- Issue management
+- Pull request automation
+- Code review workflows
+- Project tracking
+
+#### File System
+- Safe file operations
+- Directory analysis
+- Permission management
+- Backup utilities
+- Sync operations
+
+#### Database
+- Query builders
+- Schema analysis
+- Data migration tools
+- Performance monitoring
+- Backup and restore
+
+#### API Integration
+- REST client wrappers
+- Authentication handlers
+- Rate limiting tools
+- Response processors
+- Error handling
+
+## Best Practices from Examples
+
+### Prompt Design
+1. **Clear Structure**: Use sections and headers
+2. **Parameterization**: Make prompts reusable with variables
+3. **Context Inclusion**: Provide relevant background information
+4. **Output Formatting**: Specify desired response format
+5. **Error Handling**: Account for edge cases
+
+### Tool Development
+1. **Single Responsibility**: Each tool should do one thing well
+2. **Error Handling**: Robust error management and user feedback
+3. **Documentation**: Clear usage instructions and examples
+4. **Testing**: Include test cases and validation
+5. **Configuration**: Support customization through parameters
+
+### MCP Integration
+1. **Security**: Follow security best practices
+2. **Sandboxing**: Limit access to necessary resources only
+3. **Performance**: Optimize for responsiveness
+4. **Compatibility**: Ensure cross-platform operation
+5. **Monitoring**: Include logging and metrics
+
+## Advanced Usage Patterns
+
+### Multi-Stage Workflows
+Examples demonstrating complex multi-step processes:
+- Data ingestion → processing → analysis → reporting
+- Code development → testing → documentation → deployment
+- Research → analysis → writing → review → publication
+
+### Model Comparison
+Examples showing how to:
+- Compare outputs from different AI models
+- Choose optimal models for specific tasks
+- Implement fallback strategies
+- Combine results from multiple models
+
+### Dynamic Configuration
+Examples of:
+- Runtime configuration adjustment
+- Environment-specific settings
+- User preference adaptation
+- Performance optimization
+
+## Testing Examples
+
+All examples include testing approaches:
+- **Unit Tests**: For individual components
+- **Integration Tests**: For complete workflows
+- **Performance Tests**: For optimization validation
+- **User Acceptance Tests**: For real-world scenarios
+
+## Troubleshooting Guide
+
+Common issues and solutions:
+- **Permission Errors**: File access and execution permissions
+- **Missing Dependencies**: Required gems, tools, or services
+- **Configuration Issues**: API keys, paths, and settings
+- **Performance Problems**: Memory, CPU, and network optimization
+- **Compatibility Issues**: Version mismatches and platform differences
+
+## Related Documentation
+
+- [Getting Started](../guides/getting-started.md) - Basic AIA usage
+- [CLI Reference](../cli-reference.md) - Command-line options
+- [Directives Reference](../directives-reference.md) - Prompt directives
+- [Configuration](../configuration.md) - Setup and configuration
+- [Advanced Prompting](../advanced-prompting.md) - Expert techniques
+
+---
+
+Ready to explore? Start with the [Prompts Examples](prompts/index.md) to see AIA in action!