aia 1.0.0.pre.beta → 1.1.0

data/docs/mcp-integration.md

@@ -103,12 +103,14 @@ Safe file system operations with sandboxing:
 # Install filesystem MCP server
 npm install -g @anthropic-ai/mcp-server-filesystem
 
-# Configure with allowed paths
-mcp:
-  clients:
-    - name: filesystem
-      command: ["npx", "@anthropic-ai/mcp-server-filesystem"]
-      args: ["/home/user/projects", "/tmp/aia-workspace"]
+# Configure in ~/.config/aia/aia.yml
+mcp_servers:
+  - name: filesystem
+    command: npx
+    args:
+      - "@anthropic-ai/mcp-server-filesystem"
+      - /home/user/projects
+      - /tmp/aia-workspace
 ```
 
 **Capabilities**:
@@ -152,7 +154,7 @@ async def call_tool(name: str, arguments: dict):
 ### GitHub Analysis
 ```markdown
 # ~/.prompts/github_analysis.md
-/mcp github
+# Requires MCP server "github" configured in ~/.config/aia/aia.yml
 
 # GitHub Repository Analysis
 
@@ -179,7 +181,7 @@ Provide comprehensive analysis with actionable recommendations.
 ### File System Operations
 ```markdown
 # ~/.prompts/project_analysis.md
-/mcp filesystem
+# Requires MCP server "filesystem" configured in ~/.config/aia/aia.yml
 
 # Project Structure Analysis
 
@@ -206,7 +208,7 @@ Generate detailed project assessment with improvement suggestions.
 ### Database Schema Analysis
 ```markdown
 # ~/.prompts/database_analysis.md
-/mcp database
+# Requires MCP server "database" configured in ~/.config/aia/aia.yml
 
 # Database Schema Analysis
 
@@ -236,7 +238,7 @@ Provide recommendations for schema improvements and optimizations.
 ### Multi-Client Workflows
 ```markdown
 # ~/.prompts/full_project_audit.md
-/mcp github,filesystem,database
+# Requires MCP server "github" configured in ~/.config/aia/aia.yml,filesystem,database
 
 # Comprehensive Project Audit
 
@@ -276,26 +278,27 @@ Generate comprehensive audit report with prioritized recommendations.
 ```
 
 ### Conditional MCP Usage
-```ruby
-# ~/.prompts/adaptive_mcp.md
-/ruby
-project_type = '<%= project_type %>'
-has_database = '<%= has_database %>' == 'true'
-is_open_source = '<%= is_open_source %>' == 'true'
-
-mcp_clients = []
-mcp_clients << 'filesystem'  # Always analyze file structure
-mcp_clients << 'github' if is_open_source
-mcp_clients << 'database' if has_database
-
-puts "/mcp #{mcp_clients.join(',')}"
-puts "Selected MCP clients for #{project_type} project: #{mcp_clients.join(', ')}"
+
+Use `--mcp-use` on the command line to select which MCP servers to activate:
+
+```bash
+# Use only specific MCP servers for a prompt
+aia --mcp-use github,filesystem my_prompt
+
+# Skip specific servers
+aia --mcp-skip database my_prompt
 ```
 
+Within prompts, you can document which MCP servers are expected:
+
+```markdown
+# ~/.prompts/adaptive_analysis.md
+# Requires MCP servers: github, filesystem, database
+# Run with: aia --mcp-use github,filesystem,database adaptive_analysis
+
 # Adaptive Project Analysis
 
 Project type: <%= project_type %>
-Analysis scope: <%= mcp_clients.join(', ') %>
 
 Perform comprehensive analysis using available MCP clients to provide insights specific to this project type.
 ```
@@ -398,91 +401,45 @@ server.connect();
 
 ## MCP Security and Best Practices
 
-### Security Configuration
-```yaml
-# Secure MCP configuration
-mcp:
-  security:
-    sandbox_mode: true
-    allowed_operations: ["read", "list"]
-    blocked_operations: ["delete", "execute"]
-    
-  resource_limits:
-    max_file_size: 10485760  # 10MB
-    max_query_results: 1000
-    timeout_seconds: 30
-    
-  clients:
-    - name: filesystem
-      command: ["mcp-server-filesystem"]
-      args: ["/safe/path/only"]
-      security_context: "restricted"
-      
-    - name: database
-      command: ["database-mcp-server"]
-      security_context: "read_only"
-      env:
-        DB_READ_ONLY: "true"
-```
-
 ### Access Control
-```ruby
-# MCP access control in prompts
-/ruby
-user_role = '<%= user_role %>'
-allowed_mcp = case user_role
-             when 'admin'
-               ['github', 'filesystem', 'database']
-             when 'developer'
-               ['github', 'filesystem']  
-             when 'analyst'
-               ['database']
-             else
-               []
-             end
-
-if allowed_mcp.empty?
-  puts "No MCP access for role: #{user_role}"
-else
-  puts "/mcp #{allowed_mcp.join(',')}"
-  puts "MCP access granted: #{allowed_mcp.join(', ')}"
-end
-```
 
-## Performance Optimization
+Control which MCP servers are available using CLI flags:
 
-### Connection Pooling
-```yaml
-mcp:
-  connection_pooling:
-    enabled: true
-    max_connections: 5
-    idle_timeout: 300
-    
-  caching:
-    enabled: true
-    ttl: 3600  # 1 hour
-    max_size: 100  # Cache entries
+```bash
+# Allow only specific MCP servers
+aia --mcp-use github,filesystem --chat
+
+# Skip specific MCP servers
+aia --mcp-skip database --chat
+
+# Use --allowed-tools and --rejected-tools to filter MCP tools
+aia --mcp-use github --allowed-tools "github_*" --chat
 ```
 
-### Async Operations
-```python
-# Async MCP server for better performance
-import asyncio
-import aiohttp
-from mcp.server import Server
+### Server Configuration Security
 
-server = Server("async-service")
+Limit what each MCP server can access through its own configuration:
 
-@server.call_tool()
-async def call_tool(name: str, arguments: dict):
-    if name == "fetch_data":
-        async with aiohttp.ClientSession() as session:
-            async with session.get(arguments["url"]) as response:
-                data = await response.text()
-                return TextContent(type="text", text=data)
+```yaml
+# ~/.config/aia/aia.yml
+mcp_servers:
+  - name: filesystem
+    command: mcp-server-filesystem
+    args:
+      - /safe/path/only    # Restrict to specific directories
+
+  - name: database
+    command: database-mcp-server
+    env:
+      DB_READ_ONLY: "true"  # Use server-level env vars for restrictions
+      DATABASE_URL: "${DATABASE_URL}"
+    timeout: 8000
 ```
 
+### Parallel Connections
+
+When multiple MCP servers are configured, AIA connects to them in parallel using fiber-based concurrency (via the `simple_flow` gem) for faster startup.
+
 ## Troubleshooting MCP
 
 ### Common Issues
@@ -490,52 +447,31 @@ async def call_tool(name: str, arguments: dict):
 #### Client Connection Failures
 ```bash
 # Debug MCP client connections
-aia --debug --mcp github test_prompt
+aia --debug --mcp github.json test_prompt
 
-# Check client status
-aia --mcp-status
+# List configured servers to verify setup
+aia --mcp-list
 
-# Test individual client
-aia --test-mcp github
+# List MCP server tools to verify connectivity
+aia --mcp-list --list-tools
 ```
 
 #### Protocol Errors
+
+Enable detailed MCP logging via the logger configuration:
+
 ```yaml
-# Enable detailed MCP logging
-mcp:
-  logging:
-    level: debug
+# ~/.config/aia/aia.yml
+logger:
+  mcp:
     file: /tmp/aia-mcp.log
-    
-  error_handling:
-    retry_attempts: 3
-    retry_delay: 1000  # milliseconds
-    fallback_mode: graceful
+    level: debug
+    flush: true
 ```
 
-#### Performance Issues
+Or via CLI:
 ```bash
-# Monitor MCP performance
-aia --mcp-metrics github filesystem
-
-# Profile MCP operations
-aia --profile --mcp database analysis_prompt
-```
-
-### Debugging Tools
-```python
-# MCP debugging utilities
-async def debug_mcp_call(client, tool, args):
-    start_time = time.time()
-    try:
-        result = await client.call_tool(tool, args)
-        duration = time.time() - start_time
-        print(f"MCP call successful: {tool} in {duration:.2f}s")
-        return result
-    except Exception as e:
-        duration = time.time() - start_time
-        print(f"MCP call failed: {tool} after {duration:.2f}s - {e}")
-        raise
+aia --debug my_prompt  # Sets all loggers to debug level
 ```
 
 ## MCP Examples Repository
@@ -543,7 +479,7 @@ async def debug_mcp_call(client, tool, args):
 ### GitHub Repository Analysis
 ```markdown
 # ~/.prompts/mcp_examples/github_repo_health.md
-/mcp github
+# Requires MCP server "github" configured in ~/.config/aia/aia.yml
 
 # GitHub Repository Health Check
 
@@ -580,7 +516,7 @@ Generate detailed health score with specific improvement recommendations.
 ### File System Audit
 ```markdown
 # ~/.prompts/mcp_examples/filesystem_audit.md
-/mcp filesystem
+# Requires MCP server "filesystem" configured in ~/.config/aia/aia.yml
 
 # File System Security and Organization Audit
 

data/docs/prompt_management.md

@@ -8,10 +8,15 @@ AIA provides sophisticated prompt management capabilities through the PM gem, en
 ```
 ~/.prompts/
 ├── README.md                    # Documentation for your prompt collection
-├── roles/                       # Role-based prompts for context setting
+├── roles/                       # Role definitions (LLM personality/persona)
 │   ├── assistant.md
 │   ├── code_expert.md
 │   └── teacher.md
+├── skills/                      # Skill definitions (task instructions)
+│   ├── code-review/
+│   │   └── SKILL.md             # YAML front matter + instruction body
+│   └── summarizer/
+│       └── SKILL.md
 ├── development/                 # Development-related prompts
 │   ├── code_review.md
 │   ├── debug_help.md
@@ -292,6 +297,88 @@ Current Task:
 Please provide guidance consistent with the project architecture and your role as <%= role %>.
 ```
 
+## Skills
+
+### Roles vs Skills
+
+These two concepts work together but serve distinct purposes:
+
+| Concept | Defines | Loaded from | Injected as |
+|---------|---------|-------------|-------------|
+| **Role** | LLM *personality* — who the model is | `~/.prompts/roles/<id>.md` | First, before skills and prompt |
+| **Skill** | Task *instructions* — how to approach the work | `~/.prompts/skills/<name>/SKILL.md` | After role, before user prompt |
+
+A **role** sets the persona: "You are a senior Ruby developer with deep expertise in performance optimization."
+
+A **skill** provides procedural guidance for that persona to follow when executing the user's request: "When reviewing code, always check for: N+1 queries, missing indexes, memory leaks, and security vulnerabilities. Present findings as a prioritized list."
+
+The assembled prompt order is:
+
+```
+1. Role content        ← WHO the LLM is (personality)
+2. Skill content(s)    ← HOW to approach the task (instructions)
+3. User prompt         ← WHAT to do (request)
+4. Context files       ← supporting material
+```
+
+### Skill File Format
+
+Each skill lives in its own subdirectory under `~/.prompts/skills/`. The subdirectory must contain a `SKILL.md` file with YAML front matter followed by the skill instruction body:
+
+```markdown
+---
+name: code-review
+description: Thorough code review focusing on correctness, security, and maintainability.
+user-invocable: true
+argument-hint: ["file or topic to review"]
+---
+
+When reviewing code, systematically check:
+
+1. **Correctness** — Does the logic match the stated intent? Are edge cases handled?
+2. **Security** — Are there injection risks, unsafe deserialization, or exposed secrets?
+3. **Performance** — Are there N+1 queries, unbounded loops, or unnecessary allocations?
+4. **Maintainability** — Is the code readable? Are names clear? Is complexity justified?
+
+Present findings as a prioritized list with file:line references where applicable.
+Always suggest a concrete fix, not just identification of the problem.
+```
+
+The YAML front matter is metadata only. Only the body (everything after the closing `---`) is injected into the prompt.
+
+### Using Skills
+
+```bash
+# Prepend a skill before the user prompt
+aia --skill code-review review_prompt my_code.rb
+
+# Combine role + skill for maximum context
+aia --role ruby_expert --skill code-review review_prompt my_code.rb
+
+# Multiple skills (applied in order)
+aia --skill code-review --skill security-audit review_prompt my_code.rb
+aia -s code-review,security-audit review_prompt my_code.rb
+
+# List available skills
+aia --list-skills
+
+# Use a skill from within a chat session
+/skill code-review
+```
+
+### Skills in Chat Mode
+
+In chat mode, use the `/skill` directive to inject a skill at any point in the conversation:
+
+```
+> /skill summarizer
+[Skill "summarizer" instructions are injected into the next message context]
+
+> Please summarize the discussion so far.
+```
+
+The `/skill` directive injects only the body content of `SKILL.md` — the YAML front matter is never sent to the LLM.
+
 ## Prompt Workflows and Pipelines
 
 ### Simple Workflows

data/docs/security.md

@@ -42,6 +42,53 @@ else
 fi
 ```
 
+## Code Execution Directives
+
+AIA includes directives that execute code directly on your machine. Understand their security implications:
+
+### /ruby Directive
+
+The `/ruby` directive executes arbitrary Ruby code using `eval()` with your full user permissions. It can read files, make network calls, modify your filesystem, and execute system commands.
+
+```
+# These execute with YOUR permissions:
+/ruby File.read('/etc/hosts')
+/ruby system('whoami')
+/ruby Dir.glob('**/*')
+```
+
+**Mitigations**:
+- Only run prompts from trusted sources
+- Review any prompt file before executing if it contains `/ruby` directives
+- Be cautious with prompts shared by others or downloaded from the internet
+
+### /shell Directive
+
+The `/shell` directive executes system commands with your user permissions:
+
+```
+# Executes directly in your shell:
+/shell ls -la
+/shell cat /path/to/file
+```
+
+**Mitigations**:
+- Same precautions as `/ruby` — only use with trusted prompts
+- Consider the implications of any shell command before running it
+
+### ERB Processing
+
+Prompts with `.md` extension are processed through ERB, which also executes Ruby code:
+
+```markdown
+The current user is: <%= `whoami`.strip %>
+Today's date is: <%= Date.today %>
+```
+
+**Mitigations**:
+- Review prompt files before running them, especially from untrusted sources
+- ERB processing is always enabled and cannot be disabled per-prompt
+
 ## Prompt Security
 
 ### Input Sanitization
@@ -368,96 +415,47 @@ sanitize_environment() {
 ## Tool and MCP Security
 
 ### Tool Access Control
-```yaml
-# Secure tool configuration
-tools:
-  security:
-    default_policy: deny
-    audit_log: /var/log/aia-tools.log
-    
-  allowed_tools:
-    - name: file_reader
-      max_file_size: 1048576  # 1MB
-      allowed_extensions: [.txt, .md, .json]
-      allowed_directories: [/home/user/safe, /tmp/workspace]
-      
-    - name: web_client  
-      allowed_domains: [api.github.com, api.openai.com]
-      max_request_size: 1048576
-      timeout: 30
-      
-  blocked_tools:
-    - system_admin
-    - file_writer
-    - shell_executor
-```
 
-### MCP Security Configuration
-```yaml
-# Secure MCP configuration
-mcp:
-  security:
-    sandbox_mode: true
-    network_isolation: true
-    file_system_jail: /tmp/mcp-sandbox
-    
-  resource_limits:
-    max_memory: 256MB
-    max_cpu_time: 30s
-    max_file_descriptors: 100
-    
-  clients:
-    - name: github
-      security_profile: network_readonly
-      allowed_operations: [read, list]
-      rate_limit: 100/hour
-      
-    - name: filesystem
-      security_profile: filesystem_readonly  
-      jail_directory: /home/user/safe
-      max_file_size: 10MB
-```
+Use CLI flags to control which tools and MCP servers are available:
 
-## Environment-Specific Security
+```bash
+# Allow only specific tools
+aia --allowed-tools file_reader,web_client --chat
 
-### Development Environment
-```yaml
-# ~/.aia/dev_security.yml
-security:
-  level: relaxed
-  allow_debug: true
-  allow_local_files: true
-  allowed_models: [gpt-3.5-turbo, gpt-4]
-  log_all_requests: true
-```
+# Block specific tools
+aia --rejected-tools shell_executor --chat
 
-### Production Environment  
-```yaml
-# ~/.aia/prod_security.yml
-security:
-  level: strict
-  allow_debug: false
-  allow_local_files: false
-  allowed_models: [gpt-3.5-turbo]  # Cost control
-  content_filtering: strict
-  audit_logging: enabled
-  network_restrictions: strict
+# Control MCP server access
+aia --mcp-use github,filesystem --chat
+aia --mcp-skip database --chat
 ```
 
-### Shared/Multi-user Environment
+### MCP Server Configuration Security
+
+Restrict MCP server capabilities through their configuration:
+
 ```yaml
-# ~/.aia/shared_security.yml
-security:
-  level: paranoid
-  user_isolation: true
-  resource_quotas:
-    max_requests_per_hour: 100
-    max_tokens_per_day: 50000
-  content_filtering: aggressive
-  tool_restrictions: strict
-  mcp_disabled: true
+# ~/.config/aia/aia.yml
+mcp_servers:
+  - name: filesystem
+    command: mcp-server-filesystem
+    args:
+      - /safe/path/only    # Restrict to specific directories
+
+  - name: database
+    command: database-mcp-server
+    env:
+      DB_READ_ONLY: "true"  # Use server-level restrictions
+      DATABASE_URL: "${DATABASE_URL}"
+    timeout: 8000
 ```
 
+### Environment-Specific Tips
+
+- **Development**: Use `--debug` and verbose logging to monitor tool/MCP behavior
+- **Production scripts**: Use `--mcp-use` and `--allowed-tools` to restrict available capabilities
+- **Shared environments**: Use environment variables for API keys; avoid storing secrets in config files
+
 ## Monitoring and Auditing
 
 ### Security Logging

data/docs/tools-and-mcp-examples.md

@@ -8,7 +8,7 @@ This comprehensive collection showcases real-world examples of RubyLLM tools and
 
 #### Advanced Log Analyzer
 ```ruby
-# ~/.aia/tools/log_analyzer.rb
+# ~/.config/aia/tools/log_analyzer.rb
 require 'time'
 require 'json'
 
@@ -177,7 +177,7 @@ end
 
 #### Configuration File Manager
 ```ruby
-# ~/.aia/tools/config_manager.rb
+# ~/.config/aia/tools/config_manager.rb
 require 'yaml'
 require 'json'
 require 'fileutils'
@@ -350,7 +350,7 @@ end
 
 #### Code Quality Analyzer
 ```ruby
-# ~/.aia/tools/code_quality.rb
+# ~/.config/aia/tools/code_quality.rb
 class CodeQualityAnalyzer < RubyLLM::Tool
   description "Analyzes code quality metrics, complexity, and best practices"
   
@@ -972,7 +972,8 @@ if __name__ == "__main__":
 ```markdown
 # ~/.prompts/full_stack_analysis.md
 /tools file_analyzer.rb,code_quality.rb,config_manager.rb
-/mcp github,filesystem,database
+# Requires MCP servers: github, filesystem, database
+# Run with: aia --mcp-use github,filesystem,database --tools file_analyzer.rb,code_quality.rb,config_manager.rb full_stack_analysis
 
 # Full-Stack Application Analysis
 
@@ -1031,7 +1032,8 @@ Generate comprehensive analysis with actionable insights for each identified are
 ```markdown
 # ~/.prompts/devops_pipeline_analysis.md
 /tools log_analyzer.rb,config_manager.rb
-/mcp github,filesystem
+# Requires MCP servers: github, filesystem
+# Run with: aia --mcp-use github,filesystem --tools log_analyzer.rb,config_manager.rb devops_pipeline_analysis
 
 # DevOps Pipeline Analysis
 
@@ -1081,7 +1083,7 @@ Provide implementation timeline and impact assessment for each recommendation.
 
 ### Multi-Environment Consistency Checker
 ```ruby
-# ~/.aia/tools/environment_checker.rb
+# ~/.config/aia/tools/environment_checker.rb
 class EnvironmentChecker < RubyLLM::Tool
   description "Compares configurations and deployments across multiple environments"
   

data/docs/workflows-and-pipelines.md

@@ -510,12 +510,8 @@ Pipeline optimized for <%= complexity %> analysis with <%= selected_pipeline.len
 
 #### Workflow Interruption
 ```bash
-# Resume interrupted workflow
-export WORKFLOW_ID="previous_workflow_id"
-aia --resume-workflow $WORKFLOW_ID
-
-# Or restart from specific stage
-aia --pipeline "failed_stage,remaining_stages" --resume-from failed_stage
+# Restart from a specific stage by specifying the remaining pipeline
+aia --pipeline "failed_stage,remaining_stages" input_file
 ```
 
 #### Context Size Issues

data/examples/.gitignore

@@ -0,0 +1 @@
+output/