create-genia-os 2.4.0 → 3.0.0

package/template/.aiox-core/development/tasks/run-workflow.md

@@ -0,0 +1,387 @@
+---
+
+## 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 (AIOX Task Format V1.0)
+
+```yaml
+task: runWorkflow()
+responsavel: Orion (Commander)
+responsavel_type: Agente
+atomic_layer: Config
+
+**Entrada:**
+- campo: workflow_name
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Must match an existing workflow YAML file
+
+- campo: target_context
+  tipo: string
+  origem: User Input
+  obrigatório: false
+  validação: Must be "core", "squad", or "hybrid". Default: "core"
+
+- campo: squad_name
+  tipo: string
+  origem: User Input
+  obrigatório: false (required when target_context="squad" or "hybrid")
+  validação: Must be kebab-case, squad must exist in squads/
+
+- campo: action
+  tipo: string
+  origem: User Input
+  obrigatório: false
+  validação: Must be "start", "continue", "status", "skip", or "abort". Default: "continue"
+
+- campo: mode
+  tipo: string
+  origem: User Input
+  obrigatório: false
+  validação: Must be "guided" or "engine". Default: "guided"
+
+**Saída:**
+- campo: workflow_state
+  tipo: object
+  destino: File system (.aiox/{instance-id}-state.yaml)
+  persistido: true
+
+- campo: next_steps
+  tipo: array
+  destino: Output
+  persistido: false
+
+- campo: handoff_prompt
+  tipo: string
+  destino: Output
+  persistido: false
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] workflow_name must resolve to an existing YAML file
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check workflow file exists at resolved path
+    error_message: "Pre-condition failed: Workflow '{workflow_name}' not found"
+  - [ ] For action=continue/status/skip/abort, an active state file must exist
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check .aiox/{instance-id}-state.yaml exists with status=active
+    error_message: "Pre-condition failed: No active workflow instance found"
+  - [ ] When target_context="squad" or "hybrid", squad directory must exist
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      If target_context is "squad" or "hybrid", verify squads/{squad_name}/ exists
+    error_message: "Pre-condition failed: Squad '{squad_name}' not found"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] State file created/updated and next steps displayed
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify state file exists and output was generated
+    error_message: "Post-condition failed: State file not written or output missing"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Action executed correctly; state persisted; next steps shown
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert action was completed and state reflects the change
+    error_message: "Acceptance criterion not met: Action execution failed"
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+> **Note:** The tools below are conceptual patterns executed by the AI agent at runtime (file reads, YAML parsing, state management). They are NOT standalone JS scripts — the agent implements this logic inline using its native tools (Read, Write, Glob, etc.).
+
+- **Tool:** workflow-state-manager
+  - **Purpose:** Create, load, save, and query workflow state
+  - **Implementation:** AI agent reads/writes `.aiox/{instance-id}-state.yaml` files directly
+
+- **Tool:** workflow-validator
+  - **Purpose:** Validate workflow YAML before starting
+  - **Implementation:** AI agent validates structure, sequence, and references inline
+
+- **Tool:** file-system
+  - **Purpose:** YAML file reading and state persistence
+  - **Implementation:** Native Read/Write/Glob tools
+
+---
+
+## Error Handling
+
+**Strategy:** abort
+
+**Common Errors:**
+
+1. **Error:** Workflow Not Found
+   - **Cause:** Specified workflow_name doesn't resolve to a YAML file
+   - **Resolution:** Check name and target context
+   - **Recovery:** List available workflows
+
+2. **Error:** No Active Instance
+   - **Cause:** Trying to continue/status/skip/abort without an active state
+   - **Resolution:** Start the workflow first with action=start
+   - **Recovery:** Show available state files
+
+3. **Error:** Step Not Optional
+   - **Cause:** Trying to skip a non-optional step
+   - **Resolution:** Complete the step or abort the workflow
+   - **Recovery:** Show which steps are optional
+
+---
+
+## Performance
+
+**Expected Metrics:**
+
+```yaml
+duration_expected: 1-3 min (estimated)
+cost_estimated: $0.001-0.005
+token_usage: ~500-1,500 tokens
+```
+
+---
+
+## Metadata
+
+```yaml
+story: N/A
+version: 1.0.0
+dependencies:
+  - run-workflow-engine.md
+tags:
+  - workflow
+  - execution
+  - automation
+  - state-management
+updated_at: 2026-01-31
+```
+
+---
+
+# Run Workflow Task
+
+## Purpose
+
+To provide guided workflow automation with file-based state persistence. Tracks workflow progress across sessions, suggests next concrete actions, and maintains continuity. NOT a full execution engine — a "guided automation" approach where the human remains the orchestrator.
+
+## Prerequisites
+
+- Target workflow YAML must exist at the resolved path
+- For engine mode: `run-workflow-engine.md` task must exist at `.aiox-core/development/tasks/run-workflow-engine.md`
+- State directory `.aiox/` must be writable
+
+## Elicitation Points
+
+The following inputs are collected before execution:
+
+1. **workflow_name** — Which workflow to run (required)
+2. **target_context** — Where to look for the workflow: `core`, `squad`, or `hybrid` (default: `core`)
+3. **squad_name** — Required when target_context is `squad` or `hybrid`
+4. **action** — What to do: `start`, `continue`, `status`, `skip`, `abort` (default: `continue`)
+5. **mode** — Execution mode: `guided` (persona-switch) or `engine` (real subagent spawning) (default: `guided`)
+
+## Task Execution
+
+### Mode Dispatch
+
+**BEFORE processing any action**, check the `mode` parameter:
+
+```
+IF mode == "engine":
+  Delegate ENTIRELY to run-workflow-engine.md task.
+  Pass all parameters: workflow_name, target_context, squad_name, action.
+  The engine task handles everything from here — do NOT continue below.
+  STOP.
+
+ELSE (mode == "guided" or not specified):
+  Continue with existing guided automation logic below.
+```
+
+---
+
+
+### Action: `start`
+
+Initialize a new workflow execution.
+
+1. **Resolve workflow file path** based on target_context:
+   - `core` → `.aiox-core/development/workflows/{workflow_name}.yaml`
+   - `squad` → `squads/{squad_name}/workflows/{workflow_name}.yaml`
+   - `hybrid` → `squads/{squad_name}/workflows/{workflow_name}.yaml`
+
+2. **Validate workflow** using WorkflowValidator:
+   - Must pass validation before starting
+   - Display any warnings
+
+3. **Create state file** using WorkflowStateManager.createState():
+   - Generates unique instance ID
+   - Builds step list from workflow sequence
+   - Writes state to `.aiox/{instance-id}-state.yaml`
+
+4. **Show step 1 instructions:**
+   ```text
+   === Workflow Started: {workflow_name} ===
+   Instance: {instance_id}
+
+   Step 1/{total}: {phase}
+   Agent: @{agent}
+   Action: {action description}
+   Notes: {step notes}
+
+   To execute this step:
+   1. Activate agent: @{agent}
+   2. {specific instructions based on action}
+
+   When done, run: *run-workflow {workflow_name} continue
+   ```
+
+### Action: `continue` (default)
+
+Resume from current step.
+
+1. **Find active state file** for this workflow
+2. **Load state** using WorkflowStateManager.loadState()
+3. **Get current step** — if current step is still pending, show its instructions
+4. **If current step was completed externally**, mark completed and advance:
+   - Confirm with user: "Did you complete step {N}? (y/n)"
+   - On yes: markStepCompleted() → advanceStep() → show next step
+   - On no: re-display current step instructions
+
+5. **Show next step instructions** with pre-populated agent/command:
+   ```text
+   Step {N}/{total}: {phase}
+   Agent: @{agent}
+   Action: {action}
+
+   Suggested command: @{agent}
+   Handoff: {handoff_prompt if available}
+
+   When done, run: *run-workflow {workflow_name} continue
+   ```
+
+6. **Save updated state**
+
+### Action: `status`
+
+Show progress summary.
+
+1. **Load state**
+2. **Generate status report** using WorkflowStateManager.generateStatusReport():
+   - Visual progress bar
+   - Step checklist with icons
+   - Artifact status
+   - Decision log
+
+### Action: `skip`
+
+Skip current step (only if optional).
+
+1. **Load state**
+2. **Verify current step is optional** — error if not
+3. **Mark step skipped** using WorkflowStateManager.markStepSkipped()
+4. **Advance to next step** using WorkflowStateManager.advanceStep()
+5. **Show next step instructions**
+6. **Save updated state**
+
+### Action: `abort`
+
+Abort workflow execution.
+
+1. **Load state**
+2. **Set status to 'aborted'**
+3. **Generate cleanup notes:**
+   ```text
+   === Workflow Aborted: {workflow_name} ===
+   Instance: {instance_id}
+   Progress: {completed}/{total} steps completed
+
+   Artifacts created:
+   - {list of created artifacts}
+
+   State file preserved at: .aiox/{instance-id}-state.yaml
+   (Delete manually if no longer needed)
+   ```
+4. **Save final state**
+
+## Multi-Session Continuity
+
+The state file persists between sessions. To continue a workflow:
+
+1. User starts new Claude Code session
+2. Activates @aiox-master
+3. Runs `*run-workflow {name} continue`
+4. System loads state, shows current step
+5. User executes step (possibly in new agent session)
+6. Returns and runs `continue` again
+
+The `generateHandoffContext()` method produces markdown suitable for inclusion in session handoff documents.
+
+## Output Format
+
+All actions produce structured output with:
+- Status header
+- Progress indicator
+- Current step details
+- Suggested next commands
+- Handoff prompt (when transitioning between agents)

package/template/.aiox-core/development/tasks/search-mcp.md

@@ -0,0 +1,309 @@
+# Search MCP Catalog Task
+
+> Search and discover available MCP servers in the Docker MCP Toolkit catalog.
+
+---
+
+## Task Definition
+
+```yaml
+task: searchMcp()
+responsavel: DevOps Agent
+responsavel_type: Agente
+atomic_layer: Infrastructure
+elicit: true
+
+**Entrada:**
+- campo: search_query
+  tipo: string
+  origem: User Input
+  obrigatorio: true
+  validacao: Search query for MCP catalog (e.g., "notion", "database", "slack")
+
+**Saida:**
+- campo: mcp_results
+  tipo: array
+  destino: Console output
+  persistido: false
+
+- campo: mcp_details
+  tipo: object
+  destino: Console output (if user selects an MCP)
+  persistido: false
+```
+
+---
+
+## Pre-Conditions
+
+```yaml
+pre-conditions:
+  - [ ] Docker MCP Toolkit running
+    tipo: pre-condition
+    blocker: true
+    validacao: docker mcp --version succeeds
+    error_message: "Docker MCP Toolkit required. Enable in Docker Desktop settings."
+
+  - [ ] Docker daemon running
+    tipo: pre-condition
+    blocker: true
+    validacao: docker info succeeds
+    error_message: "Start Docker Desktop before running this task"
+```
+
+---
+
+## Interactive Elicitation
+
+### Step 1: Search Query
+
+```
+ELICIT: MCP Search Query
+
+What type of MCP server are you looking for?
+
+Examples:
+  • "notion" - Workspace and document management
+  • "database" - Database integrations (postgres, mysql, sqlite)
+  • "slack" - Team messaging
+  • "browser" - Browser automation (puppeteer, playwright)
+  • "storage" - Cloud storage (s3, gcs)
+  • "*" - List all available MCPs
+
+→ Enter search query: _______________
+```
+
+### Step 2: Display Results
+
+```
+ELICIT: Search Results
+
+Found {n} MCPs matching "{query}":
+
+┌─────────────────────────────────────────────────────────────────┐
+│ #  │ MCP Name        │ Description                             │
+├─────────────────────────────────────────────────────────────────┤
+│ 1  │ mcp/notion      │ Notion workspace integration            │
+│ 2  │ mcp/postgres    │ PostgreSQL database access              │
+│ 3  │ mcp/sqlite      │ SQLite local database                   │
+│ 4  │ mcp/mysql       │ MySQL database access                   │
+└─────────────────────────────────────────────────────────────────┘
+
+Options:
+  • Enter a number to see details
+  • Type "add {number}" to add the MCP
+  • Type "search {query}" to search again
+  • Type "exit" to finish
+
+→ Select option: ___
+```
+
+### Step 3: Show MCP Details (Optional)
+
+```
+ELICIT: MCP Details
+
+📦 mcp/{name}
+
+Description: {full_description}
+
+🔧 Tools Provided:
+   • tool1 - Description of tool1
+   • tool2 - Description of tool2
+   • tool3 - Description of tool3
+
+🔑 Required Credentials:
+   • {CREDENTIAL_NAME} - {description}
+   • (none) - if no credentials needed
+
+📋 Example Usage:
+   docker mcp server add {name}
+   docker mcp tools call {name}.{tool} --param value
+
+Options:
+  • Type "add" to add this MCP
+  • Type "back" to return to results
+  • Type "exit" to finish
+
+→ Select option: ___
+```
+
+---
+
+## Implementation Steps
+
+### 1. Search the Catalog
+
+```bash
+# Basic search
+docker mcp catalog search {query}
+
+# Example: Search for "notion"
+docker mcp catalog search notion
+
+# List all MCPs
+docker mcp catalog search "*"
+
+# Example output:
+# NAME           DESCRIPTION
+# 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}
+
+# Example: Get notion details
+docker mcp catalog info notion
+
+# Example output:
+# Name: mcp/notion
+# Description: Notion workspace integration
+# Tools:
+#   - getPage: Retrieve a Notion page
+#   - createPage: Create a new page
+#   - search: Search Notion workspace
+# Environment:
+#   - NOTION_API_KEY (required)
+```
+
+### 3. Filter by Category (if supported)
+
+```bash
+# Search by category
+docker mcp catalog search --category database
+docker mcp catalog search --category productivity
+docker mcp catalog search --category automation
+```
+
+---
+
+## Post-Conditions
+
+```yaml
+post-conditions:
+  - [ ] Search results displayed
+    tipo: post-condition
+    blocker: false
+    validacao: User can see matching MCPs or "no results" message
+    error_message: "Search failed - check Docker MCP connection"
+```
+
+---
+
+## Error Handling
+
+### Error: No Results Found
+
+```
+Resolution:
+1. Try a broader search query
+2. Use wildcards: docker mcp catalog search "*database*"
+3. Check available categories: docker mcp catalog categories
+4. Browse full catalog: docker mcp catalog search "*"
+```
+
+### Error: Docker MCP Not Available
+
+```
+Resolution:
+1. Verify Docker Desktop 4.50+ is installed
+2. Enable MCP Toolkit: Docker Desktop > Settings > Extensions > MCP Toolkit
+3. Restart Docker Desktop
+4. Verify: docker mcp --version
+```
+
+### Error: Catalog Timeout
+
+```
+Resolution:
+1. Check internet connection
+2. Docker MCP catalog requires network access
+3. Retry: docker mcp catalog search {query}
+4. Check Docker proxy settings if behind firewall
+```
+
+---
+
+## Success Output
+
+```
+✅ MCP Catalog Search Complete
+
+🔍 Query: "{query}"
+📦 Results: {n} MCPs found
+
+┌─────────────────────────────────────────────────────────────────┐
+│ MCP Name        │ Description              │ Credentials       │
+├─────────────────────────────────────────────────────────────────┤
+│ mcp/notion      │ Notion workspace         │ NOTION_API_KEY    │
+│ mcp/postgres    │ PostgreSQL access        │ DATABASE_URL      │
+│ mcp/sqlite      │ SQLite local DB          │ None              │
+└─────────────────────────────────────────────────────────────────┘
+
+Next steps:
+1. View details: *search-mcp → select number
+2. Add an MCP: *add-mcp {name}
+3. List enabled MCPs: *list-mcps
+```
+
+---
+
+## Common Search Examples
+
+| Search Query | Finds | Use Case |
+|--------------|-------|----------|
+| `notion` | Notion workspace MCP | Document management |
+| `database` | postgres, mysql, sqlite, redis | Database access |
+| `slack` | Slack messaging MCP | Team communication |
+| `browser` | puppeteer, playwright | Browser automation |
+| `storage` | s3, gcs, azure-blob | Cloud storage |
+| `github` | GitHub API MCP | Repository management |
+| `*` | All available MCPs | Browse full catalog |
+
+---
+
+## Related Commands
+
+| Command | Description |
+|---------|-------------|
+| `*add-mcp` | Add an MCP server to Docker MCP Toolkit |
+| `*list-mcps` | List currently enabled MCPs |
+| `*remove-mcp` | Remove an MCP from Docker MCP Toolkit |
+| `*setup-mcp-docker` | Initial Docker MCP Toolkit setup |
+
+---
+
+## Performance
+
+```yaml
+duration_expected: 1-2 minutes
+cost_estimated: $0 (local Docker operation)
+token_usage: ~200-500 tokens
+```
+
+---
+
+## Metadata
+
+```yaml
+task: search-mcp
+version: 1.0.0
+story: Story 6.14 - MCP Governance Consolidation
+dependencies:
+  - Docker MCP Toolkit
+  - Docker Desktop 4.50+
+tags:
+  - infrastructure
+  - mcp
+  - docker
+  - discovery
+  - catalog
+created_at: 2025-12-17
+updated_at: 2025-12-17
+agents:
+  - devops
+```