@exellix/ai-tasks 8.4.1 → 8.4.3

package/.docs/building-skill-execution-orchestrator.md

@@ -0,0 +1,968 @@
+# Building an External Package for Skill Execution Orchestration
+
+This guide explains how to create an external package that uses `@woroces/ai-skills`'s `runTask` method to orchestrate skill execution with different execution strategies. This package will handle running skills, manage execution strategies, coordinate workflows, and provide a higher-level API for task orchestration.
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Architecture](#architecture)
+3. [Prerequisites](#prerequisites)
+4. [Project Setup](#project-setup)
+5. [Core Components](#core-components)
+6. [Execution Strategy System](#execution-strategy-system)
+7. [Skill Execution Manager](#skill-execution-manager)
+8. [Workflow Orchestration](#workflow-orchestration)
+9. [Complete Implementation](#complete-implementation)
+10. [Usage Examples](#usage-examples)
+11. [Advanced Features](#advanced-features)
+12. [Testing](#testing)
+
+---
+
+## Overview
+
+### What This Package Does
+
+This external package provides:
+
+- **Skill Execution Orchestration**: Manages the execution of skills using `runTask`
+- **Execution Strategy Management**: Handles different execution strategies (DIRECT, and extensible for future types)
+- **Workflow Coordination**: Manages multi-step skill execution workflows
+- **Memory Management**: Tracks and manages `jobMemory` and `taskMemory` across executions
+- **Error Handling & Retry Logic**: Robust error handling with configurable retry strategies
+- **Result Aggregation**: Combines results from multiple skill executions
+
+### Key Concepts
+
+- **Task**: A single skill execution request with a specific execution strategy
+- **Execution Strategy**: How a task should be executed (currently `DIRECT`, designed to support more)
+- **Workflow**: A sequence of tasks that execute in order, with memory passed between them
+- **Job**: A collection of workflows or tasks that share the same `jobId` and `jobMemory`
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│         Your External Package                            │
+│                                                          │
+│  ┌──────────────────────────────────────────────────┐  │
+│  │  SkillExecutionOrchestrator                       │  │
+│  │  - Manages execution strategies                   │  │
+│  │  - Coordinates workflows                          │  │
+│  │  - Handles memory management                      │  │
+│  └──────────────────────────────────────────────────┘  │
+│                        │                                 │
+│                        ▼                                 │
+│  ┌──────────────────────────────────────────────────┐  │
+│  │  ExecutionStrategyManager                         │  │
+│  │  - DIRECT strategy handler                         │  │
+│  │  - Extensible for future strategies               │  │
+│  └──────────────────────────────────────────────────┘  │
+│                        │                                 │
+│                        ▼                                 │
+│  ┌──────────────────────────────────────────────────┐  │
+│  │  @woroces/ai-skills                                │  │
+│  │  - XeonoxSkillsClient.runTask()                   │  │
+│  │  - Handles gateway, registry, parsing            │  │
+│  └──────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Prerequisites
+
+- Node.js >= 18.0.0
+- TypeScript knowledge
+- Understanding of `@woroces/ai-skills` package
+- Access to GitHub Package Registry
+- Understanding of execution memory management concepts
+
+---
+
+## Project Setup
+
+### Step 1: Initialize Project
+
+```bash
+mkdir skill-execution-orchestrator
+cd skill-execution-orchestrator
+npm init -y
+```
+
+### Step 2: Install Dependencies
+
+```bash
+# Core dependencies
+npm install @woroces/ai-skills @athenices/execution-memory-manager
+
+# Development dependencies
+npm install --save-dev typescript @types/node ts-node jest @types/jest ts-jest
+```
+
+### Step 3: Configure TypeScript
+
+Create `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}
+```
+
+### Step 4: Configure npm Registry
+
+Create `.npmrc`:
+
+```
+@woroces:registry=https://npm.pkg.github.com
+@athenices:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
+```
+
+---
+
+## Core Components
+
+### 1. Execution Strategy Interface
+
+Create `src/strategies/execution-strategy.ts`:
+
+```typescript
+import { RunTaskRequest, RunSkillResponse } from "@woroces/ai-skills";
+
+/**
+ * Base interface for execution strategies.
+ * 
+ * Each strategy defines how a task should be executed.
+ * Currently supports DIRECT, but designed to be extensible.
+ */
+export interface IExecutionStrategy {
+  /**
+   * Execute a task using this strategy.
+   * 
+   * @param request The task request
+   * @returns Promise resolving to the execution result
+   */
+  execute<TParsed = any>(
+    request: RunTaskRequest
+  ): Promise<RunSkillResponse<TParsed>>;
+
+  /**
+   * Get the strategy name/type.
+   */
+  getType(): string;
+
+  /**
+   * Check if this strategy can handle the given request.
+   */
+  canHandle(request: RunTaskRequest): boolean;
+}
+```
+
+### 2. Direct Execution Strategy
+
+Create `src/strategies/direct-strategy.ts`:
+
+```typescript
+import { 
+  XeonoxSkillsClient, 
+  RunTaskRequest, 
+  RunSkillResponse, 
+  ExecutionType 
+} from "@woroces/ai-skills";
+import type { IExecutionStrategy } from "./execution-strategy";
+
+/**
+ * Direct execution strategy.
+ * 
+ * Executes tasks by directly passing through to the skill executor.
+ * This is the simplest and most common execution strategy.
+ */
+export class DirectExecutionStrategy implements IExecutionStrategy {
+  private client: XeonoxSkillsClient;
+
+  constructor(client: XeonoxSkillsClient) {
+    this.client = client;
+  }
+
+  async execute<TParsed = any>(
+    request: RunTaskRequest
+  ): Promise<RunSkillResponse<TParsed>> {
+    // Ensure execution type is set to DIRECT
+    const taskRequest: RunTaskRequest = {
+      ...request,
+      executionType: ExecutionType.DIRECT
+    };
+
+    return this.client.runTask<TParsed>(taskRequest);
+  }
+
+  getType(): string {
+    return ExecutionType.DIRECT;
+  }
+
+  canHandle(request: RunTaskRequest): boolean {
+    return request.executionType === ExecutionType.DIRECT || 
+           !request.executionType; // Default to DIRECT if not specified
+  }
+}
+```
+
+### 3. Execution Strategy Manager
+
+Create `src/strategies/strategy-manager.ts`:
+
+```typescript
+import { RunTaskRequest, RunSkillResponse, ExecutionType } from "@woroces/ai-skills";
+import type { IExecutionStrategy } from "./execution-strategy";
+import { DirectExecutionStrategy } from "./direct-strategy";
+import { XeonoxSkillsClient } from "@woroces/ai-skills";
+
+/**
+ * Manages execution strategies.
+ * 
+ * Responsible for:
+ * - Registering available strategies
+ * - Selecting the appropriate strategy for a task
+ * - Providing extensibility for future strategy types
+ */
+export class ExecutionStrategyManager {
+  private strategies: Map<string, IExecutionStrategy> = new Map();
+  private defaultStrategy: IExecutionStrategy;
+
+  constructor(client: XeonoxSkillsClient) {
+    // Register default DIRECT strategy
+    const directStrategy = new DirectExecutionStrategy(client);
+    this.defaultStrategy = directStrategy;
+    this.strategies.set(ExecutionType.DIRECT, directStrategy);
+  }
+
+  /**
+   * Register a new execution strategy.
+   */
+  registerStrategy(strategy: IExecutionStrategy): void {
+    this.strategies.set(strategy.getType(), strategy);
+  }
+
+  /**
+   * Get the appropriate strategy for a task request.
+   */
+  getStrategy(request: RunTaskRequest): IExecutionStrategy {
+    // Try to find a strategy that can handle this request
+    for (const strategy of this.strategies.values()) {
+      if (strategy.canHandle(request)) {
+        return strategy;
+      }
+    }
+
+    // Fall back to default (DIRECT)
+    return this.defaultStrategy;
+  }
+
+  /**
+   * Execute a task using the appropriate strategy.
+   */
+  async execute<TParsed = any>(
+    request: RunTaskRequest
+  ): Promise<RunSkillResponse<TParsed>> {
+    const strategy = this.getStrategy(request);
+    return strategy.execute<TParsed>(request);
+  }
+
+  /**
+   * Get all registered strategy types.
+   */
+  getAvailableStrategies(): string[] {
+    return Array.from(this.strategies.keys());
+  }
+}
+```
+
+---
+
+## Skill Execution Manager
+
+Create `src/skill-execution-manager.ts`:
+
+```typescript
+import { 
+  XeonoxSkillsClient, 
+  RunTaskRequest, 
+  RunSkillResponse, 
+  ExecutionType 
+} from "@woroces/ai-skills";
+import type { XeonoxSkillsClientOptions } from "@woroces/ai-skills";
+import type { JobHistory, TaskHistory } from "@athenices/execution-memory-manager";
+import { ExecutionStrategyManager } from "./strategies/strategy-manager";
+
+/**
+ * Options for skill execution.
+ */
+export interface SkillExecutionOptions {
+  jobId?: string;
+  agentId?: string;
+  timeoutMs?: number;
+  retryConfig?: RetryConfig;
+}
+
+/**
+ * Retry configuration for failed executions.
+ */
+export interface RetryConfig {
+  maxRetries?: number;
+  retryDelayMs?: number;
+  retryableErrors?: string[];
+}
+
+/**
+ * Skill Execution Manager
+ * 
+ * High-level manager for executing skills with different strategies.
+ * Handles:
+ * - Strategy selection and execution
+ * - Memory management
+ * - Error handling and retries
+ * - Result tracking
+ */
+export class SkillExecutionManager {
+  private client: XeonoxSkillsClient;
+  private strategyManager: ExecutionStrategyManager;
+  private jobMemory: Map<string, JobHistory> = new Map();
+  private taskMemory: Map<string, TaskHistory> = new Map();
+
+  constructor(options?: XeonoxSkillsClientOptions) {
+    this.client = new XeonoxSkillsClient(options);
+    this.strategyManager = new ExecutionStrategyManager(this.client);
+  }
+
+  /**
+   * Execute a single skill.
+   * 
+   * @param skillKey The skill to execute (e.g., "skills/professional-answer")
+   * @param input The input data for the skill
+   * @param options Execution options
+   */
+  async executeSkill<TParsed = any>(
+    skillKey: string,
+    input: Record<string, any> | string,
+    options?: SkillExecutionOptions
+  ): Promise<RunSkillResponse<TParsed>> {
+    const jobId = options?.jobId || `job-${Date.now()}`;
+    
+    // Get or initialize memory for this job
+    const jobMemory = this.jobMemory.get(jobId);
+    const taskMemory = this.taskMemory.get(jobId) || {};
+
+    const taskRequest: RunTaskRequest = {
+      skillKey,
+      input,
+      executionType: ExecutionType.DIRECT,
+      jobId,
+      agentId: options?.agentId,
+      timeoutMs: options?.timeoutMs,
+      jobMemory,
+      taskMemory
+    };
+
+    // Execute with retry logic if configured
+    if (options?.retryConfig) {
+      return this.executeWithRetry<TParsed>(taskRequest, options.retryConfig);
+    }
+
+    const result = await this.strategyManager.execute<TParsed>(taskRequest);
+    
+    // Update memory with this execution
+    this.updateMemory(jobId, result);
+
+    return result;
+  }
+
+  /**
+   * Execute a skill with variables/context.
+   */
+  async executeSkillWithContext<TParsed = any>(
+    skillKey: string,
+    input: Record<string, any> | string,
+    variables?: Record<string, any>,
+    context?: Record<string, any> | string,
+    options?: SkillExecutionOptions
+  ): Promise<RunSkillResponse<TParsed>> {
+    const jobId = options?.jobId || `job-${Date.now()}`;
+    const jobMemory = this.jobMemory.get(jobId);
+    const taskMemory = this.taskMemory.get(jobId) || {};
+
+    const taskRequest: RunTaskRequest = {
+      skillKey,
+      input,
+      variables,
+      context,
+      executionType: ExecutionType.DIRECT,
+      jobId,
+      agentId: options?.agentId,
+      timeoutMs: options?.timeoutMs,
+      jobMemory,
+      taskMemory
+    };
+
+    if (options?.retryConfig) {
+      return this.executeWithRetry<TParsed>(taskRequest, options.retryConfig);
+    }
+
+    const result = await this.strategyManager.execute<TParsed>(taskRequest);
+    this.updateMemory(jobId, result);
+
+    return result;
+  }
+
+  /**
+   * Execute a task with a specific execution strategy.
+   */
+  async executeTask<TParsed = any>(
+    taskRequest: RunTaskRequest
+  ): Promise<RunSkillResponse<TParsed>> {
+    const jobId = taskRequest.jobId || `job-${Date.now()}`;
+    
+    // Ensure memory is attached
+    const enrichedRequest: RunTaskRequest = {
+      ...taskRequest,
+      jobId,
+      jobMemory: taskRequest.jobMemory || this.jobMemory.get(jobId),
+      taskMemory: taskRequest.taskMemory || this.taskMemory.get(jobId)
+    };
+
+    const result = await this.strategyManager.execute<TParsed>(enrichedRequest);
+    this.updateMemory(jobId, result);
+
+    return result;
+  }
+
+  /**
+   * Execute with retry logic.
+   */
+  private async executeWithRetry<TParsed = any>(
+    request: RunTaskRequest,
+    config: RetryConfig
+  ): Promise<RunSkillResponse<TParsed>> {
+    const maxRetries = config.maxRetries || 3;
+    const retryDelay = config.retryDelayMs || 1000;
+    const retryableErrors = config.retryableErrors || [];
+
+    let lastError: Error | null = null;
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        return await this.strategyManager.execute<TParsed>(request);
+      } catch (error: any) {
+        lastError = error;
+
+        // Check if error is retryable
+        const isRetryable = retryableErrors.length === 0 || 
+          retryableErrors.some(pattern => 
+            error.message?.includes(pattern) || 
+            error.code === pattern
+          );
+
+        if (!isRetryable || attempt === maxRetries) {
+          throw error;
+        }
+
+        // Wait before retrying
+        await new Promise(resolve => setTimeout(resolve, retryDelay * (attempt + 1)));
+      }
+    }
+
+    throw lastError || new Error("Execution failed after retries");
+  }
+
+  /**
+   * Update memory with execution result.
+   */
+  private updateMemory(jobId: string, result: RunSkillResponse<any>): void {
+    // Update job memory (history of all task results)
+    const currentJobMemory = this.jobMemory.get(jobId) || {};
+    const updatedJobMemory: JobHistory = {
+      ...currentJobMemory,
+      [result.skillKey]: {
+        result: result.parsed,
+        metadata: result.metadata,
+        timestamp: Date.now()
+      }
+    };
+    this.jobMemory.set(jobId, updatedJobMemory);
+
+    // Update task memory (history of skills executed)
+    const currentTaskMemory = this.taskMemory.get(jobId) || {};
+    const updatedTaskMemory: TaskHistory = {
+      ...currentTaskMemory,
+      [result.skillKey]: {
+        activityId: result.metadata.activityId,
+        timestamp: Date.now()
+      }
+    };
+    this.taskMemory.set(jobId, updatedTaskMemory);
+  }
+
+  /**
+   * Get job memory for a specific job.
+   */
+  getJobMemory(jobId: string): JobHistory | undefined {
+    return this.jobMemory.get(jobId);
+  }
+
+  /**
+   * Get task memory for a specific job.
+   */
+  getTaskMemory(jobId: string): TaskHistory | undefined {
+    return this.taskMemory.get(jobId);
+  }
+
+  /**
+   * Clear memory for a job.
+   */
+  clearMemory(jobId: string): void {
+    this.jobMemory.delete(jobId);
+    this.taskMemory.delete(jobId);
+  }
+
+  /**
+   * Get available execution strategies.
+   */
+  getAvailableStrategies(): string[] {
+    return this.strategyManager.getAvailableStrategies();
+  }
+}
+```
+
+---
+
+## Workflow Orchestration
+
+Create `src/workflow-orchestrator.ts`:
+
+```typescript
+import { 
+  RunTaskRequest, 
+  RunSkillResponse, 
+  ExecutionType 
+} from "@woroces/ai-skills";
+import { SkillExecutionManager } from "./skill-execution-manager";
+import type { SkillExecutionOptions } from "./skill-execution-manager";
+
+/**
+ * Definition of a single step in a workflow.
+ */
+export interface WorkflowStep {
+  skillKey: string;
+  input: Record<string, any> | string;
+  variables?: Record<string, any>;
+  context?: Record<string, any> | string;
+  executionType?: ExecutionType;
+  condition?: (previousResults: RunSkillResponse<any>[]) => boolean;
+}
+
+/**
+ * Workflow execution result.
+ */
+export interface WorkflowResult {
+  jobId: string;
+  steps: Array<{
+    step: WorkflowStep;
+    result: RunSkillResponse<any>;
+    success: boolean;
+    error?: Error;
+  }>;
+  success: boolean;
+  finalResult?: RunSkillResponse<any>;
+}
+
+/**
+ * Workflow Orchestrator
+ * 
+ * Manages execution of multi-step workflows where:
+ * - Steps execute in sequence
+ * - Memory is passed between steps
+ * - Conditional execution is supported
+ * - Results are aggregated
+ */
+export class WorkflowOrchestrator {
+  private executionManager: SkillExecutionManager;
+
+  constructor(executionManager: SkillExecutionManager) {
+    this.executionManager = executionManager;
+  }
+
+  /**
+   * Execute a workflow (sequence of steps).
+   */
+  async executeWorkflow(
+    steps: WorkflowStep[],
+    options?: SkillExecutionOptions
+  ): Promise<WorkflowResult> {
+    const jobId = options?.jobId || `workflow-${Date.now()}`;
+    const results: WorkflowResult['steps'] = [];
+    let previousResults: RunSkillResponse<any>[] = [];
+
+    for (const step of steps) {
+      // Check condition if provided
+      if (step.condition && !step.condition(previousResults)) {
+        results.push({
+          step,
+          result: {} as RunSkillResponse<any>,
+          success: false,
+          error: new Error("Step condition not met")
+        });
+        continue;
+      }
+
+      try {
+        // Build input that can reference previous results
+        const enrichedInput = this.enrichInputWithPreviousResults(
+          step.input,
+          previousResults
+        );
+
+        // Execute the step
+        const taskRequest: RunTaskRequest = {
+          skillKey: step.skillKey,
+          input: enrichedInput,
+          variables: step.variables,
+          context: step.context,
+          executionType: step.executionType || ExecutionType.DIRECT,
+          jobId,
+          agentId: options?.agentId,
+          timeoutMs: options?.timeoutMs,
+          jobMemory: this.executionManager.getJobMemory(jobId),
+          taskMemory: this.executionManager.getTaskMemory(jobId)
+        };
+
+        const result = await this.executionManager.executeTask(taskRequest);
+        previousResults.push(result);
+
+        results.push({
+          step,
+          result,
+          success: true
+        });
+      } catch (error: any) {
+        results.push({
+          step,
+          result: {} as RunSkillResponse<any>,
+          success: false,
+          error
+        });
+
+        // Optionally stop on error
+        break;
+      }
+    }
+
+    const success = results.every(r => r.success);
+    const finalResult = previousResults.length > 0 
+      ? previousResults[previousResults.length - 1] 
+      : undefined;
+
+    return {
+      jobId,
+      steps: results,
+      success,
+      finalResult
+    };
+  }
+
+  /**
+   * Enrich input with results from previous steps.
+   */
+  private enrichInputWithPreviousResults(
+    input: Record<string, any> | string,
+    previousResults: RunSkillResponse<any>[]
+  ): Record<string, any> | string {
+    if (typeof input === 'string') {
+      // Simple string replacement for previous results
+      let enriched = input;
+      previousResults.forEach((result, index) => {
+        enriched = enriched.replace(
+          new RegExp(`\\$\\{step${index + 1}\\}`, 'g'),
+          JSON.stringify(result.parsed)
+        );
+      });
+      return enriched;
+    }
+
+    // For object inputs, merge previous results
+    const enriched: Record<string, any> = { ...input };
+    
+    // Add previous results as $previousSteps array
+    enriched.$previousSteps = previousResults.map(r => r.parsed);
+    
+    // Add individual step results as $step1, $step2, etc.
+    previousResults.forEach((result, index) => {
+      enriched[`$step${index + 1}`] = result.parsed;
+    });
+
+    return enriched;
+  }
+}
+```
+
+---
+
+## Complete Implementation
+
+### Main Entry Point
+
+Create `src/index.ts`:
+
+```typescript
+// Core exports
+export { SkillExecutionManager } from "./skill-execution-manager";
+export { WorkflowOrchestrator } from "./workflow-orchestrator";
+export { ExecutionStrategyManager } from "./strategies/strategy-manager";
+
+// Strategy exports
+export { DirectExecutionStrategy } from "./strategies/direct-strategy";
+export type { IExecutionStrategy } from "./strategies/execution-strategy";
+
+// Type exports
+export type { SkillExecutionOptions, RetryConfig } from "./skill-execution-manager";
+export type { WorkflowStep, WorkflowResult } from "./workflow-orchestrator";
+
+// Re-export from @woroces/ai-skills for convenience
+export type { 
+  RunTaskRequest, 
+  RunSkillResponse, 
+  ExecutionType 
+} from "@woroces/ai-skills";
+export { ExecutionType } from "@woroces/ai-skills";
+```
+
+---
+
+## Usage Examples
+
+### Example 1: Basic Skill Execution
+
+```typescript
+import { SkillExecutionManager } from "skill-execution-orchestrator";
+
+const manager = new SkillExecutionManager({
+  enableContentRegistry: true,
+  contentRegistryLocalPath: "./.metadata"
+});
+
+// Execute a single skill
+const result = await manager.executeSkill(
+  "skills/professional-answer",
+  { question: "What is AI?" },
+  {
+    jobId: "job-123",
+    agentId: "agent-abc"
+  }
+);
+
+console.log("Answer:", result.parsed);
+```
+
+### Example 2: Skill Execution with Context
+
+```typescript
+const result = await manager.executeSkillWithContext(
+  "skills/professional-decision",
+  { scenario: "Should we migrate to cloud?" },
+  { orgName: "TechCorp", department: "Engineering" },
+  { industry: "Technology", size: "Enterprise" },
+  {
+    jobId: "job-456",
+    timeoutMs: 30000
+  }
+);
+```
+
+### Example 3: Workflow Execution
+
+```typescript
+import { SkillExecutionManager, WorkflowOrchestrator } from "skill-execution-orchestrator";
+import { ExecutionType } from "@woroces/ai-skills";
+
+const manager = new SkillExecutionManager();
+const orchestrator = new WorkflowOrchestrator(manager);
+
+// Define a workflow
+const workflow = [
+  {
+    skillKey: "skills/professional-answer",
+    input: { question: "What are the benefits of cloud migration?" },
+    executionType: ExecutionType.DIRECT
+  },
+  {
+    skillKey: "skills/professional-decision",
+    input: { scenario: "Based on the analysis, should we migrate?" },
+    variables: { orgName: "TechCorp" },
+    // Only execute if first step succeeded
+    condition: (results) => results.length > 0 && results[0].parsed
+  }
+];
+
+// Execute workflow
+const workflowResult = await orchestrator.executeWorkflow(workflow, {
+  jobId: "workflow-789"
+});
+
+if (workflowResult.success) {
+  console.log("Workflow completed:", workflowResult.finalResult);
+} else {
+  console.error("Workflow failed:", workflowResult.steps);
+}
+```
+
+### Example 4: With Retry Logic
+
+```typescript
+const result = await manager.executeSkill(
+  "skills/professional-answer",
+  { question: "Complex question here" },
+  {
+    jobId: "job-retry",
+    retryConfig: {
+      maxRetries: 3,
+      retryDelayMs: 2000,
+      retryableErrors: ["timeout", "rate limit", "network"]
+    }
+  }
+);
+```
+
+---
+
+## Advanced Features
+
+### Custom Execution Strategy
+
+You can extend the system with custom strategies:
+
+```typescript
+import { IExecutionStrategy, ExecutionStrategyManager } from "skill-execution-orchestrator";
+import { RunTaskRequest, RunSkillResponse } from "@woroces/ai-skills";
+
+class ParallelExecutionStrategy implements IExecutionStrategy {
+  async execute<TParsed = any>(
+    request: RunTaskRequest
+  ): Promise<RunSkillResponse<TParsed>> {
+    // Custom parallel execution logic
+    // This is a placeholder for future implementation
+    throw new Error("Parallel execution not yet implemented");
+  }
+
+  getType(): string {
+    return "parallel";
+  }
+
+  canHandle(request: RunTaskRequest): boolean {
+    return request.executionType === "parallel";
+  }
+}
+
+// Register the strategy
+const manager = new SkillExecutionManager();
+// Access strategy manager and register (would need to expose this)
+```
+
+---
+
+## Testing
+
+### Unit Tests Example
+
+Create `src/skill-execution-manager.test.ts`:
+
+```typescript
+import { SkillExecutionManager } from "./skill-execution-manager";
+import { ExecutionType } from "@woroces/ai-skills";
+
+describe("SkillExecutionManager", () => {
+  let manager: SkillExecutionManager;
+
+  beforeEach(() => {
+    manager = new SkillExecutionManager({
+      enableContentRegistry: true,
+      contentRegistryLocalPath: "./.metadata"
+    });
+  });
+
+  test("should execute a skill", async () => {
+    const result = await manager.executeSkill(
+      "skills/professional-answer",
+      { question: "Test question" },
+      { jobId: "test-job" }
+    );
+
+    expect(result).toBeDefined();
+    expect(result.skillKey).toBe("skills/professional-answer");
+    expect(result.flexMd).toBeDefined();
+  });
+
+  test("should manage job memory", async () => {
+    const jobId = "memory-test";
+    
+    await manager.executeSkill(
+      "skills/professional-answer",
+      { question: "First question" },
+      { jobId }
+    );
+
+    const memory = manager.getJobMemory(jobId);
+    expect(memory).toBeDefined();
+  });
+});
+```
+
+---
+
+## Summary
+
+You've now created an external package that:
+
+1. ✅ Uses `runTask` from `@woroces/ai-skills` for skill execution
+2. ✅ Manages different execution strategies (extensible architecture)
+3. ✅ Handles skill execution with memory management
+4. ✅ Provides workflow orchestration for multi-step processes
+5. ✅ Includes retry logic and error handling
+6. ✅ Offers a clean, high-level API
+
+### Key Benefits
+
+- **Separation of Concerns**: Your package handles orchestration, `@woroces/ai-skills` handles execution
+- **Extensibility**: Easy to add new execution strategies
+- **Memory Management**: Automatic tracking of job and task memory
+- **Workflow Support**: Built-in support for multi-step processes
+- **Error Resilience**: Configurable retry logic
+
+### Next Steps
+
+1. Add more execution strategies (parallel, sequential with dependencies, etc.)
+2. Implement workflow visualization
+3. Add result caching
+4. Implement workflow templates/presets
+5. Add monitoring and metrics collection
+
+---
+
+**Questions?** Refer to the `@woroces/ai-skills` documentation for details on the underlying execution system.