aios-core 2.1.0

package/.aios-core/development/tasks/add-mcp.md

@@ -0,0 +1,319 @@
+# Add MCP Server Task
+
+> Dynamically add MCP servers to Docker MCP Toolkit from the catalog.
+
+---
+
+## Task Definition
+
+```yaml
+task: addMcp()
+responsavel: Dev Agent / DevOps Agent
+responsavel_type: Agente
+atomic_layer: Infrastructure
+elicit: true
+
+**Entrada:**
+- campo: mcp_query
+  tipo: string
+  origem: User Input
+  obrigatorio: true
+  validacao: Search query for MCP catalog
+
+- campo: mcp_name
+  tipo: string
+  origem: User Selection
+  obrigatorio: true
+  validacao: Exact MCP server name from catalog
+
+- campo: credentials
+  tipo: object
+  origem: User Input
+  obrigatorio: false
+  validacao: API keys or tokens if required by MCP
+
+**Saida:**
+- campo: mcp_added
+  tipo: boolean
+  destino: Docker MCP configuration
+  persistido: true
+
+- campo: tools_available
+  tipo: array
+  destino: Console output
+  persistido: false
+```
+
+---
+
+## Pre-Conditions
+
+```yaml
+pre-conditions:
+  - [ ] Docker MCP Toolkit running
+    tipo: pre-condition
+    blocker: true
+    validacao: docker mcp gateway status succeeds
+    error_message: "Start gateway: docker mcp gateway run --watch"
+
+  - [ ] Dynamic MCP feature enabled
+    tipo: pre-condition
+    blocker: false
+    validacao: docker mcp feature list shows dynamic-tools
+    error_message: "Enable with: docker mcp feature enable dynamic-tools"
+```
+
+---
+
+## Interactive Elicitation
+
+### Step 1: Search MCP Catalog
+
+```
+ELICIT: MCP Search
+
+What MCP server are you looking for?
+
+Enter a search query (e.g., "notion", "slack", "database"):
+→ _______________
+
+[Searching Docker MCP catalog...]
+```
+
+### Step 2: Select from Results
+
+```
+ELICIT: MCP Selection
+
+Found {n} MCPs matching "{query}":
+
+1. mcp/notion
+   └─ Notion workspace integration
+   └─ Requires: NOTION_API_KEY
+
+2. mcp/postgres
+   └─ PostgreSQL database access
+   └─ Requires: DATABASE_URL
+
+3. mcp/sqlite
+   └─ SQLite database access
+   └─ Requires: None (local file)
+
+→ Select MCP to add (number or name): ___
+```
+
+### Step 3: Configure Credentials
+
+```
+ELICIT: Credentials Configuration
+
+The selected MCP requires authentication:
+
+MCP: mcp/{name}
+Required: {CREDENTIAL_NAME}
+
+Options:
+1. Set environment variable now
+2. Configure later (MCP may fail without credentials)
+3. Skip this MCP
+
+→ Choose option: ___
+
+[If option 1]
+Enter value for {CREDENTIAL_NAME}:
+→ _______________
+(This will be set as an environment variable)
+```
+
+### Step 4: Confirm Addition
+
+```
+ELICIT: Confirmation
+
+Ready to add MCP:
+
+Server: mcp/{name}
+Credentials: {configured/not configured}
+Preset: {preset to add to, if any}
+
+→ Proceed? (y/n): ___
+```
+
+---
+
+## Implementation Steps
+
+### 1. Search Catalog
+
+```bash
+# Search for MCPs
+docker mcp catalog search {query}
+
+# Example output:
+# mcp/notion    Notion workspace integration
+# mcp/postgres  PostgreSQL database access
+```
+
+### 2. Get MCP Details
+
+```bash
+# Get detailed info about an MCP
+docker mcp catalog info {mcp-name}
+
+# Shows: description, required credentials, tools provided
+```
+
+### 3. Add MCP Server
+
+```bash
+# Add the server
+docker mcp server add {mcp-name}
+
+# With environment variable
+docker mcp server add {mcp-name} --env NOTION_API_KEY=${NOTION_API_KEY}
+```
+
+### 4. Update Gordon Config (Optional)
+
+If adding to gordon-mcp.yml:
+
+```yaml
+# Add to .docker/mcp/gordon-mcp.yml
+services:
+  {mcp-name}:
+    image: mcp/{mcp-name}
+    environment:
+      - {CREDENTIAL_NAME}=${CREDENTIAL_NAME}
+    labels:
+      mcp.preset: "full,{custom}"
+```
+
+### 5. Verify Addition
+
+```bash
+# List tools from new MCP
+docker mcp tools ls | grep {mcp-name}
+
+# Test a tool
+docker mcp tools call {mcp-name}.{tool} --param value
+```
+
+### 6. Add to Preset (Optional)
+
+```bash
+# Add to existing preset
+docker mcp preset update {preset-name} --add-server {mcp-name}
+
+# Or create new preset including the MCP
+docker mcp preset create {new-preset} --servers fs,github,{mcp-name}
+```
+
+---
+
+## Post-Conditions
+
+```yaml
+post-conditions:
+  - [ ] MCP server added
+    tipo: post-condition
+    blocker: true
+    validacao: docker mcp server list includes new MCP
+    error_message: "MCP addition failed"
+
+  - [ ] Tools available
+    tipo: post-condition
+    blocker: true
+    validacao: docker mcp tools ls shows MCP tools
+    error_message: "MCP tools not available - check credentials"
+```
+
+---
+
+## Error Handling
+
+### Error: MCP Not Found
+
+```
+Resolution:
+1. Check spelling of MCP name
+2. Search with broader query: docker mcp catalog search "*"
+3. Check if MCP is in the registry: https://github.com/modelcontextprotocol/registry
+```
+
+### Error: Credentials Missing
+
+```
+Resolution:
+1. Set environment variable: export NOTION_API_KEY=your_key
+2. Add to .env file: NOTION_API_KEY=your_key
+3. Pass directly: docker mcp server add notion --env NOTION_API_KEY=key
+```
+
+### Error: MCP Fails to Start
+
+```
+Resolution:
+1. Check Docker logs: docker logs mcp-{name}
+2. Verify credentials are correct
+3. Check MCP documentation for specific requirements
+4. Try removing and re-adding: docker mcp server remove {name}
+```
+
+---
+
+## Success Output
+
+```
+✅ MCP Server Added Successfully!
+
+📦 Server: mcp/{name}
+🔧 Tools Added:
+   • {name}.tool1 - Description
+   • {name}.tool2 - Description
+   • {name}.tool3 - Description
+
+🔗 Status: Running
+📋 Preset: Added to 'aios-full'
+
+Next steps:
+1. Test tools: docker mcp tools call {name}.tool1 --param value
+2. Use in workflow: *mcp-workflow with {name} tools
+3. Add to other presets: docker mcp preset update aios-dev --add-server {name}
+```
+
+---
+
+## Common MCPs Reference
+
+| MCP | Purpose | Credentials | Popular Tools |
+|-----|---------|-------------|---------------|
+| `notion` | Notion workspace | NOTION_API_KEY | getPage, createPage, search |
+| `postgres` | PostgreSQL DB | DATABASE_URL | query, execute, listTables |
+| `sqlite` | SQLite DB | None | query, execute |
+| `slack` | Slack messaging | SLACK_BOT_TOKEN | sendMessage, listChannels |
+| `puppeteer` | Browser automation | None | navigate, screenshot, click |
+| `redis` | Redis cache | REDIS_URL | get, set, del |
+| `s3` | AWS S3 | AWS_* | upload, download, list |
+| `stripe` | Stripe payments | STRIPE_SECRET_KEY | createPayment, listCustomers |
+
+---
+
+## Metadata
+
+```yaml
+task: add-mcp
+version: 1.0.0
+story: Story 5.11 - Docker MCP Migration
+dependencies:
+  - Docker MCP Toolkit
+  - docker mcp gateway running
+tags:
+  - infrastructure
+  - mcp
+  - docker
+  - dynamic
+updated_at: 2025-12-08
+agents:
+  - dev
+  - devops
+```

package/.aios-core/development/tasks/advanced-elicitation.md

@@ -0,0 +1,319 @@
+# advanced-elicitation
+
+## Execution Modes
+
+**Choose your execution mode:**
+
+### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
+- Autonomous decision making with logging
+- Minimal user interaction
+- **Best for:** Simple, deterministic tasks
+
+### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
+- Explicit decision checkpoints
+- Educational explanations
+- **Best for:** Learning, complex decisions
+
+### 3. Pre-Flight Planning - Comprehensive Upfront Planning
+- Task analysis phase (identify all ambiguities)
+- Zero ambiguity execution
+- **Best for:** Ambiguous requirements, critical work
+
+**Parameter:** `mode` (optional, default: `interactive`)
+
+---
+
+## Task Definition (AIOS Task Format V1.0)
+
+```yaml
+task: advancedElicitation()
+responsible: Atlas (Decoder)
+responsible_type: Agent
+atomic_layer: Strategy
+
+inputs:
+  - field: task
+    type: string
+    source: User Input
+    required: true
+    validation: Must be registered task
+
+  - field: parameters
+    type: object
+    source: User Input
+    required: false
+    validation: Valid task parameters
+
+  - field: mode
+    type: string
+    source: User Input
+    required: false
+    validation: yolo|interactive|pre-flight
+
+outputs:
+  - field: execution_result
+    type: object
+    destination: Memory
+    persisted: false
+
+  - field: logs
+    type: array
+    destination: File (.ai/logs/*)
+    persisted: true
+
+  - field: state
+    type: object
+    destination: State management
+    persisted: true
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Task is registered; required parameters provided; dependencies met
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check task is registered; required parameters provided; dependencies met
+    error_message: "Pre-condition failed: Task is registered; required parameters provided; dependencies met"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Task completed; exit code 0; expected outputs created
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify task completed; exit code 0; expected outputs created
+    error_message: "Post-condition failed: Task completed; exit code 0; expected outputs created"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Task completed as expected; side effects documented
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert task completed as expected; side effects documented
+    error_message: "Acceptance criterion not met: Task completed as expected; side effects documented"
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** task-runner
+  - **Purpose:** Task execution and orchestration
+  - **Source:** .aios-core/core/task-runner.js
+
+- **Tool:** logger
+  - **Purpose:** Execution logging and error tracking
+  - **Source:** .aios-core/utils/logger.js
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** execute-task.js
+  - **Purpose:** Generic task execution wrapper
+  - **Language:** JavaScript
+  - **Location:** .aios-core/scripts/execute-task.js
+
+---
+
+## Error Handling
+
+**Strategy:** retry
+
+**Common Errors:**
+
+1. **Error:** Task Not Found
+   - **Cause:** Specified task not registered in system
+   - **Resolution:** Verify task name and registration
+   - **Recovery:** List available tasks, suggest similar
+
+2. **Error:** Invalid Parameters
+   - **Cause:** Task parameters do not match expected schema
+   - **Resolution:** Validate parameters against task definition
+   - **Recovery:** Provide parameter template, reject execution
+
+3. **Error:** Execution Timeout
+   - **Cause:** Task exceeds maximum execution time
+   - **Resolution:** Optimize task or increase timeout
+   - **Recovery:** Kill task, cleanup resources, log state
+
+---
+
+## Performance
+
+**Expected Metrics:**
+
+```yaml
+duration_expected: 5-20 min (estimated)
+cost_estimated: $0.003-0.015
+token_usage: ~2,000-8,000 tokens
+```
+
+**Optimization Notes:**
+- Iterative analysis with depth limits; cache intermediate results; batch similar operations
+
+---
+
+## Metadata
+
+```yaml
+story: N/A
+version: 1.0.0
+dependencies:
+  - N/A
+tags:
+  - automation
+  - workflow
+updated_at: 2025-11-17
+```
+
+---
+
+## Purpose
+
+- Provide optional reflective and brainstorming actions to enhance content quality
+- Enable deeper exploration of ideas through structured elicitation techniques
+- Support iterative refinement through multiple analytical perspectives
+- Usable during template-driven document creation or any chat conversation
+
+## Usage Scenarios
+
+### Scenario 1: Template Document Creation
+
+After outputting a section during document creation:
+
+1. **Section Review**: Ask user to review the drafted section
+2. **Offer Elicitation**: Present 9 carefully selected elicitation methods
+3. **Simple Selection**: User types a number (0-8) to engage method, or 9 to proceed
+4. **Execute & Loop**: Apply selected method, then re-offer choices until user proceeds
+
+### Scenario 2: General Chat Elicitation
+
+User can request advanced elicitation on any agent output:
+
+- User says "do advanced elicitation" or similar
+- Agent selects 9 relevant methods for the context
+- Same simple 0-9 selection process
+
+## Task Instructions
+
+### 1. Intelligent Method Selection
+
+**Context Analysis**: Before presenting options, analyze:
+
+- **Content Type**: Technical specs, user stories, architecture, requirements, etc.
+- **Complexity Level**: Simple, moderate, or complex content
+- **Stakeholder Needs**: Who will use this information
+- **Risk Level**: High-impact decisions vs routine items
+- **Creative Potential**: Opportunities for innovation or alternatives
+
+**Method Selection Strategy**:
+
+1. **Always Include Core Methods** (choose 3-4):
+   - Expand or Contract for Audience
+   - Critique and Refine
+   - Identify Potential Risks
+   - Assess Alignment with Goals
+
+2. **Context-Specific Methods** (choose 4-5):
+   - **Technical Content**: Tree of Thoughts, ReWOO, Meta-Prompting
+   - **User-Facing Content**: Agile Team Perspective, Stakeholder Roundtable
+   - **Creative Content**: Innovation Tournament, Escape Room Challenge
+   - **Strategic Content**: Red Team vs Blue Team, Hindsight Reflection
+
+3. **Always Include**: "Proceed / No Further Actions" as option 9
+
+### 2. Section Context and Review
+
+When invoked after outputting a section:
+
+1. **Provide Context Summary**: Give a brief 1-2 sentence summary of what the user should look for in the section just presented
+
+2. **Explain Visual Elements**: If the section contains diagrams, explain them briefly before offering elicitation options
+
+3. **Clarify Scope Options**: If the section contains multiple distinct items, inform the user they can apply elicitation actions to:
+   - The entire section as a whole
+   - Individual items within the section (specify which item when selecting an action)
+
+### 3. Present Elicitation Options
+
+**Review Request Process:**
+
+- Ask the user to review the drafted section
+- In the SAME message, inform them they can suggest direct changes OR select an elicitation method
+- Present 9 intelligently selected methods (0-8) plus "Proceed" (9)
+- Keep descriptions short - just the method name
+- Await simple numeric selection
+
+**Action List Presentation Format:**
+
+```text
+**Advanced Elicitation Options**
+Choose a number (0-8) or 9 to proceed:
+
+0. [Method Name]
+1. [Method Name]
+2. [Method Name]
+3. [Method Name]
+4. [Method Name]
+5. [Method Name]
+6. [Method Name]
+7. [Method Name]
+8. [Method Name]
+9. Proceed / No Further Actions
+```
+
+**Response Handling:**
+
+- **Numbers 0-8**: Execute the selected method, then re-offer the choice
+- **Number 9**: Proceed to next section or continue conversation
+- **Direct Feedback**: Apply user's suggested changes and continue
+
+### 4. Method Execution Framework
+
+**Execution Process:**
+
+1. **Retrieve Method**: Access the specific elicitation method from the elicitation-methods data file
+2. **Apply Context**: Execute the method from your current role's perspective
+3. **Provide Results**: Deliver insights, critiques, or alternatives relevant to the content
+4. **Re-offer Choice**: Present the same 9 options again until user selects 9 or gives direct feedback
+
+**Execution Guidelines:**
+
+- **Be Concise**: Focus on actionable insights, not lengthy explanations
+- **Stay Relevant**: Tie all elicitation back to the specific content being analyzed
+- **Identify Personas**: For multi-persona methods, clearly identify which viewpoint is speaking
+- **Maintain Flow**: Keep the process moving efficiently
+