create-genia-os 2.4.0 → 3.0.0

package/template/.aiox-core/development/templates/squad/tool-template.js

@@ -0,0 +1,103 @@
+/**
+ * {{COMPONENTNAME}} Tool
+ *
+ * {{DESCRIPTION}}
+ *
+ * Squad: {{SQUADNAME}}
+ * Created: {{CREATEDAT}}
+ *
+ * @module {{COMPONENTNAME}}
+ * @version 1.0.0
+ * @see {{STORYID}}
+ */
+
+'use strict';
+
+/**
+ * Configuration for the tool
+ * @constant {Object}
+ */
+const CONFIG = {
+  name: '{{COMPONENTNAME}}',
+  version: '1.0.0',
+  description: '{{DESCRIPTION}}',
+};
+
+/**
+ * Main function for {{COMPONENTNAME}}
+ *
+ * @param {Object} input - Input parameters
+ * @param {string} input.param1 - First parameter
+ * @param {Object} [options={}] - Optional configuration
+ * @returns {Object} Result object with success status and data
+ *
+ * @example
+ * const result = await {{CAMELCASE_NAME}}({
+ *   param1: 'value1',
+ * });
+ * console.log(result.data);
+ */
+async function {{CAMELCASE_NAME}}(input, options = {}) {
+  // Validate input
+  if (!input || typeof input !== 'object') {
+    return {
+      success: false,
+      error: 'Invalid input: expected object',
+    };
+  }
+
+  try {
+    // Implementation here
+    const result = {
+      // Process input and generate output
+    };
+
+    return {
+      success: true,
+      data: result,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error.message,
+    };
+  }
+}
+
+/**
+ * Helper function 1
+ *
+ * @private
+ * @param {*} value - Value to process
+ * @returns {*} Processed value
+ */
+function _helperFunction1(value) {
+  // Helper implementation
+  return value;
+}
+
+/**
+ * Helper function 2
+ *
+ * @private
+ * @param {Object} data - Data to transform
+ * @returns {Object} Transformed data
+ */
+function _helperFunction2(data) {
+  // Helper implementation
+  return data;
+}
+
+/**
+ * Get tool information
+ *
+ * @returns {Object} Tool configuration
+ */
+function getInfo() {
+  return CONFIG;
+}
+
+module.exports = {
+  {{CAMELCASE_NAME}},
+  getInfo,
+};

package/template/.aiox-core/development/templates/squad/workflow-template.yaml

@@ -0,0 +1,123 @@
+# {{COMPONENTNAME}} Workflow
+#
+# {{DESCRIPTION}}
+#
+# Created: {{CREATEDAT}}
+# Story: {{STORYID}}
+
+workflow:
+  id: "{{COMPONENTNAME}}"
+  name: "{{COMPONENTNAME}}"
+  version: "1.0.0"
+  description: "{{DESCRIPTION}}"
+  type: development
+  scope: "{{SQUADNAME}}"
+
+  metadata:
+    created: "{{CREATEDAT}}"
+    author: squad-creator
+    story: "{{STORYID}}"
+    tags:
+      - workflow
+      - "{{SQUADNAME}}"
+
+  triggers:
+    - type: manual
+      command: "*{{COMPONENTNAME}}"
+    # - type: event
+    #   event: some-event-name
+    # - type: schedule
+    #   cron: "0 0 * * *"
+
+  inputs:
+    - name: param1
+      type: string
+      required: true
+      description: "Description of parameter 1"
+    - name: param2
+      type: string
+      required: false
+      default: "default-value"
+      description: "Description of parameter 2"
+
+  # Optional compatibility metadata for non-executable phase grouping.
+  phases:
+    - phase_1: Initialize
+    - phase_2: Process
+    - phase_3: Finalize
+
+  # Canonical executable contract (official): workflow.sequence[]
+  sequence:
+    - step: initialize
+      id: init
+      phase: 1
+      phase_name: "Initialize"
+      agent: "{{SQUADNAME}}-chief"
+      action: "Initialize the workflow"
+      task: "task-name-1"
+      inputs:
+        param: "{{inputs.param1}}"
+      outputs:
+        - init_output
+      next: process
+      on_failure: abort
+
+    - step: process
+      id: process
+      phase: 2
+      phase_name: "Process"
+      agent: "{{SQUADNAME}}-chief"
+      action: "Execute main processing step"
+      task: "task-name-2"
+      requires: init
+      inputs:
+        data: "{{init_output}}"
+      outputs:
+        - process_output
+      next: finalize
+      on_failure: retry
+
+    - step: finalize
+      id: finalize
+      phase: 3
+      phase_name: "Finalize"
+      agent: "{{SQUADNAME}}-chief"
+      action: "Finalize workflow execution"
+      task: "task-name-3"
+      requires: process
+      inputs:
+        data: "{{process_output}}"
+      outputs:
+        - workflow_result
+      on_complete:
+        status: success
+
+    - workflow_end: true
+      id: complete
+      action: "workflow_complete"
+
+  outputs:
+    - name: result
+      from: "{{workflow_result}}"
+      description: "Final workflow result"
+
+  handoff_prompts:
+    init_to_process: "Initialization complete. Proceeding to processing."
+    process_to_finalize: "Processing complete. Proceeding to finalization."
+
+  completion:
+    on_success:
+      message: "Workflow '{{COMPONENTNAME}}' completed successfully"
+      notify: false
+    on_failure:
+      message: "Workflow '{{COMPONENTNAME}}' failed"
+      notify: true
+      rollback: true
+
+  validation:
+    pre_run:
+      - "Check all required inputs are provided"
+      - "Validate input formats"
+    post_run:
+      - "Verify output is valid"
+      - "Log completion metrics"

package/template/.aiox-core/development/templates/squad-template/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) {{year}} {{author}}
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/template/.aiox-core/development/templates/squad-template/README.md

@@ -0,0 +1,37 @@
+# {{Squad Name}}
+
+{{Brief description of what this Squad does}}
+
+## Installation
+
+```bash
+npm install {{squad-name}}
+```
+
+## Usage
+
+```bash
+# Activate the agent
+@{{agent-name}}
+
+# Use commands
+*{{command-name}}
+```
+
+## Features
+
+- Feature 1
+- Feature 2
+- Feature 3
+
+## Documentation
+
+See the [full documentation](docs/README.md) for detailed usage.
+
+## Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT License - see [LICENSE](LICENSE)

package/template/.aiox-core/development/templates/squad-template/agents/example-agent.yaml

@@ -0,0 +1,36 @@
+# Example Agent Definition
+# Replace placeholders with your agent's details
+
+name: example-agent
+version: 1.0.0
+description: Brief description of what this agent does
+
+persona:
+  name: Example Agent
+  role: Your Agent's Role
+  expertise:
+    - Expertise Area 1
+    - Expertise Area 2
+    - Expertise Area 3
+
+capabilities:
+  - capability-one
+  - capability-two
+
+commands:
+  - name: example-command
+    description: What this command does
+    workflow: example-workflow
+
+system_prompt: |
+  You are Example Agent, specialized in [your domain].
+
+  Your responsibilities:
+  - Responsibility 1
+  - Responsibility 2
+  - Responsibility 3
+
+  Guidelines:
+  - Be helpful and precise
+  - Follow best practices
+  - Ask for clarification when needed

package/template/.aiox-core/development/templates/squad-template/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "{{squad-name}}",
+  "version": "0.1.0",
+  "description": "{{description}}",
+  "main": "index.js",
+  "scripts": {
+    "test": "jest",
+    "lint": "eslint src/",
+    "dev": "aiox-dev-server"
+  },
+  "keywords": ["aiox", "aiox-squad"],
+  "author": "{{author}}",
+  "license": "MIT",
+  "devDependencies": {
+    "@aiox/testing": "^2.1.0",
+    "jest": "^29.0.0",
+    "eslint": "^8.0.0"
+  }
+}

package/template/.aiox-core/development/templates/squad-template/squad.yaml

@@ -0,0 +1,25 @@
+name: "{{squad-name}}"
+version: 0.1.0
+description: "{{description}}"
+author: "{{author}}"
+license: MIT
+
+aiox:
+  minVersion: "2.1.0"
+  type: squad
+
+components:
+  agents:
+    - agents/*.yaml
+  tasks:
+    - tasks/*.yaml
+  workflows:
+    - workflows/*.yaml
+  templates:
+    - templates/*.md
+
+dependencies: []
+
+keywords:
+  - aiox
+  - squad

package/template/.aiox-core/development/templates/squad-template/tasks/example-task.yaml

@@ -0,0 +1,46 @@
+# Example Task Definition
+# Replace placeholders with your task's details
+
+name: example-task
+version: 1.0.0
+description: Brief description of what this task accomplishes
+
+inputs:
+  - name: input1
+    type: string
+    required: true
+    description: Primary input for the task
+
+  - name: options
+    type: object
+    required: false
+    description: Optional configuration object
+
+outputs:
+  - name: result
+    type: object
+    description: The processed result
+
+  - name: metadata
+    type: object
+    description: Additional information about the execution
+
+steps:
+  - id: validate
+    action: validate-inputs
+    description: Validate all required inputs are present and valid
+
+  - id: process
+    action: process-data
+    description: Main processing logic
+    depends_on: [validate]
+
+  - id: finalize
+    action: prepare-output
+    description: Format and return the result
+    depends_on: [process]
+
+error_handling:
+  on_validation_error: "Invalid input: {{error.message}}"
+  on_process_error: "Processing failed: {{error.message}}"
+  retry_count: 1

package/template/.aiox-core/development/templates/squad-template/templates/example-template.md

@@ -0,0 +1,24 @@
+# {{title}}
+
+**Created:** {{date}}
+**Author:** {{author}}
+
+---
+
+## Overview
+
+{{overview}}
+
+## Details
+
+{{details}}
+
+## Next Steps
+
+- [ ] Step 1
+- [ ] Step 2
+- [ ] Step 3
+
+---
+
+*Generated by {{squad-name}}*

package/template/.aiox-core/development/templates/squad-template/tests/example-agent.test.js

@@ -0,0 +1,53 @@
+/**
+ * Example Agent Tests
+ * Replace with your actual test cases
+ */
+
+import { loadAgent, executeCommand } from '@aiox/testing';
+
+describe('example-agent', () => {
+  let agent;
+
+  beforeAll(async () => {
+    agent = await loadAgent('./agents/example-agent.yaml');
+  });
+
+  describe('initialization', () => {
+    test('should load agent successfully', () => {
+      expect(agent).toBeDefined();
+      expect(agent.name).toBe('example-agent');
+    });
+
+    test('should have required persona fields', () => {
+      expect(agent.persona.name).toBeDefined();
+      expect(agent.persona.role).toBeDefined();
+      expect(agent.persona.expertise).toBeInstanceOf(Array);
+    });
+  });
+
+  describe('commands', () => {
+    test('should have example-command registered', () => {
+      const command = agent.commands.find(c => c.name === 'example-command');
+      expect(command).toBeDefined();
+      expect(command.workflow).toBe('example-workflow');
+    });
+  });
+
+  describe('execution', () => {
+    test('should execute example-command successfully', async () => {
+      const result = await executeCommand(agent, '*example-command', {
+        input1: 'test-input'
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.output).toBeDefined();
+    });
+
+    test('should handle invalid input gracefully', async () => {
+      const result = await executeCommand(agent, '*example-command', {});
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('input');
+    });
+  });
+});

package/template/.aiox-core/development/templates/squad-template/workflows/example-workflow.yaml

@@ -0,0 +1,75 @@
+# Example Workflow Definition
+# Replace placeholders with your workflow's details
+
+workflow:
+  id: example-workflow
+  name: Example Workflow
+  version: "1.0.0"
+  description: Multi-step workflow that orchestrates tasks
+  type: example
+
+  triggers:
+    - type: manual
+      command: "*example-command"
+
+  elicitation:
+    enabled: true
+    questions:
+      - id: action_type
+        prompt: "What would you like to do?"
+        type: choice
+        options:
+          - Create new item
+          - Update existing item
+          - Delete item
+      - id: item_name
+        prompt: "What is the name of the item?"
+        type: text
+        required: true
+
+  phases:
+    - phase_1: Execute task
+    - phase_2: Log result
+
+  sequence:
+    - step: execute_task
+      id: run_task
+      phase: 1
+      phase_name: "Execute Task"
+      agent: example-agent
+      task: example-task
+      inputs:
+        input1: "{{elicitation.item_name}}"
+        options:
+          action: "{{elicitation.action_type}}"
+      outputs:
+        - task_result
+      next: log_result
+      on_failure: notify_error
+
+    - step: log_result
+      id: log_result
+      phase: 2
+      phase_name: "Log Result"
+      agent: example-agent
+      action: log-result
+      inputs:
+        message: "Operation completed successfully"
+      on_complete:
+        status: success
+
+    - workflow_end: true
+      id: complete
+      action: workflow_complete
+
+  error_handling:
+    - id: notify_error
+      action: notify
+      message: "Workflow failed: {{error.message}}"
+      severity: error
+
+  completion:
+    message: "Workflow completed successfully!"
+    next_steps:
+      - Review the output
+      - Verify the changes

package/template/.aiox-core/development/templates/subagent-step-prompt.md

@@ -0,0 +1,120 @@
+# Subagent Step Prompt Template
+
+> **Purpose:** Reusable template for constructing subagent prompts in the Workflow Runtime Engine.
+> Each variable is replaced at runtime by the orchestrator (aiox-master) before spawning the subagent via the Task tool.
+
+---
+
+## Template
+
+```
+You are {{AGENT_NAME}}, {{AGENT_TITLE}}.
+
+## Your Persona
+
+{{AGENT_YAML}}
+
+## Your Task
+
+{{TASK_CONTENT}}
+
+## Context
+
+Workflow: {{WORKFLOW_NAME}} | Step: {{STEP_ID}} | Phase: {{PHASE_NAME}}
+Action: {{ACTION}}
+
+## Input Data
+
+{{INPUT_DATA}}
+
+## Reference Data
+
+{{REFERENCE_DATA}}
+
+## User Input (Elicitation)
+
+{{USER_INPUT}}
+
+## Step Instructions
+
+{{STEP_NOTES}}
+
+## CRITICAL OUTPUT FORMAT
+
+You MUST return your complete output as a YAML block at the END of your response.
+This block will be parsed by the orchestrator to extract outputs for subsequent steps.
+
+```yaml
+step_output:
+  status: completed|failed
+  outputs:
+    # Include all output fields defined in the workflow step's 'outputs' list
+    # Example:
+    #   task_completa: "..."
+    #   score_9p: 85
+    #   gaps: [...]
+  score: null
+  notes: "Summary of what was done and key decisions made"
+  artifacts:
+    - name: "artifact-name.md"
+      path: "relative/path/to/artifact"
+      status: created|updated
+```
+
+Execute the task now. Do NOT greet. Do NOT show commands. Do NOT ask questions (all inputs are provided above). Focus entirely on task execution and produce the output YAML block at the end.
+```
+
+---
+
+## Variable Reference
+
+| Variable | Source | Description |
+|----------|--------|-------------|
+| `{{AGENT_NAME}}` | Agent file → `agent.name` | Agent's display name (e.g., "Orion", "Pedro") |
+| `{{AGENT_TITLE}}` | Agent file → `agent.title` | Agent's role title |
+| `{{AGENT_YAML}}` | Agent file → full YAML block | Complete agent persona definition |
+| `{{TASK_CONTENT}}` | Task file via `uses` field | Complete task file content |
+| `{{WORKFLOW_NAME}}` | Workflow YAML → `workflow.name` | Name of the executing workflow |
+| `{{STEP_ID}}` | Sequence item → `id` | Unique step identifier |
+| `{{PHASE_NAME}}` | Current phase marker → `name` | Name of the current phase |
+| `{{ACTION}}` | Sequence item → `action` | Action description for this step |
+| `{{INPUT_DATA}}` | State → previous step outputs | YAML of outputs from steps listed in `requires` |
+| `{{REFERENCE_DATA}}` | Agent deps + workflow resources | Content of data files (e.g., mandamentos.yaml) |
+| `{{USER_INPUT}}` | Elicitation responses | YAML block of user answers (if `elicit: true`) |
+| `{{STEP_NOTES}}` | Sequence item → `notes` | Detailed instructions from the workflow step |
+
+---
+
+## Resolution Rules
+
+### Path Resolution by Context
+
+| Context | Agent Path | Task Path | Data Path |
+|---------|-----------|-----------|-----------|
+| `core` | `.aiox-core/development/agents/{agent}.md` | `.aiox-core/development/tasks/{uses}.md` | `.aiox-core/data/{file}` |
+| `squad` | `squads/{squad}/agents/{agent}.md` | `squads/{squad}/tasks/{uses}.md` | `squads/{squad}/data/{file}` |
+| `hybrid` | squad-first, core-fallback | squad-first, core-fallback | squad-first, core-fallback |
+
+### Hybrid Resolution Order
+
+1. Check `squads/{squad}/agents/{agent}.md` first
+2. If not found, check `.aiox-core/development/agents/{agent}.md`
+3. If agent has explicit prefix (`core:architect` or `squad:validator`), use that directly
+
+### Agent YAML Extraction
+
+The `{{AGENT_YAML}}` variable should contain the complete YAML block from the agent file, starting from the opening ` ```yaml ` marker and ending at the closing ` ``` ` marker. This includes all sections: agent identity, persona, commands, dependencies.
+
+### Task Content Extraction
+
+The `{{TASK_CONTENT}}` variable should contain the full task file content, from the Task Definition through Task Execution sections. Strip YAML frontmatter if present but keep all executable instructions.
+
+---
+
+## Notes
+
+- This template is referenced by `run-workflow-engine.md` task
+- The orchestrator (aiox-master) builds the prompt by reading files and replacing variables
+- Subagents receive the complete prompt and execute autonomously
+- The orchestrator parses the `step_output` YAML block from the subagent's response
+- If the subagent fails to produce a valid YAML block, the orchestrator retries or requests manual intervention