Workpackage System Overview

Workpackage API Reference

This document provides a comprehensive API reference for the Sigao CLI Workpackage Automation system.

Workpackage API Reference

This document provides a comprehensive API reference for the Sigao CLI Workpackage Automation system.

Core Classes

WorkpackageModule

Main entry point for the workpackage system.

import WorkpackageModule from '@sigaostudios/sigao-cli/workpackage';

Constructor

new WorkpackageModule(config, options)

Parameters:

  • config (Object) - Module configuration
  • options (Object) - Runtime options
    • dryRun (boolean) - Preview mode without execution
    • logLevel (string) - Logging verbosity: 'error', 'warn', 'info', 'debug'
    • outputDir (string) - Output directory path

Methods

executeWorkpackage(packagePath, options)

Executes a workpackage from a JSON file.

const result = await module.executeWorkpackage('my-workpackage.json', {
  dryRun: false,
  outputDir: './output'
});

Returns: Promise

{
  success: boolean,
  workpackages: {
    total: number,
    completed: number,
    failed: number
  },
  duration: number,
  outputDir: string
}

Validation API

WorkpackageValidator

Validates workpackage JSON against the schema.

import { WorkpackageValidator } from '@sigaostudios/sigao-cli/workpackage/validator';

Constructor

const validator = new WorkpackageValidator(options)

Parameters:

  • options (Object) - Optional configuration
    • schemaPath (string) - Custom schema file path
    • strict (boolean) - Enable strict validation

Methods

validate(data)

Validates workpackage data.

const result = validator.validate(workpackageData);
if (!result.valid) {
  console.error('Validation errors:', result.errors);
}

Returns: ValidationResult

{
  valid: boolean,
  errors: Array<{
    path: string,
    message: string,
    keyword: string,
    params: Object
  }>
}
addCustomValidator(name, validator)

Adds a custom validation rule.

validator.addCustomValidator('taskLimit', {
  validate: (data) => data.tasks.length <= 10,
  message: 'Workpackage cannot have more than 10 tasks'
});

Context API

ContextManager

Manages execution context throughout the workpackage lifecycle.

import { ContextManager } from '@sigaostudios/sigao-cli/workpackage/context';

Constructor

const contextManager = new ContextManager(options)

Parameters:

  • options (Object)
    • workingDir (string) - Working directory path
    • outputDir (string) - Output directory for context files

Methods

setGlobalContext(context)

Sets project-wide context.

contextManager.setGlobalContext({
  project: {
    name: 'my-app',
    version: '1.0.0'
  },
  environment: {
    node: process.version
  }
});
getGlobalContext()

Retrieves global context.

const context = contextManager.getGlobalContext();

Returns: GlobalContext object

setUowContext(workpackageId, context)

Sets unit-of-work context for a workpackage.

contextManager.setUowContext('WP-01-SETUP', {
  startTime: new Date(),
  currentTaskIndex: 0,
  outputs: []
});
getUowContext(workpackageId)

Retrieves UoW context.

const uowContext = contextManager.getUowContext('WP-01-SETUP');

Returns: UowContext object

getCumulativeSummary()

Gets aggregated summary of recent tasks.

const summary = contextManager.getCumulativeSummary();
// Returns last 10 task summaries

Returns: CumulativeSummary object

UI Components API

UIComponent

Base class for UI components (singleton pattern).

import { UIComponent } from '@sigaostudios/sigao-cli/workpackage/ui';

Static Methods

getInstance()

Gets the singleton instance.

const ui = UIComponent.getInstance();

Methods

formatSuccess(message)

Formats success message with checkmark.

ui.formatSuccess('Task completed'); // ✓ Task completed
formatError(message)

Formats error message with X mark.

ui.formatError('Task failed'); // ✗ Task failed
formatInfo(message)

Formats info message with info symbol.

ui.formatInfo('Processing...'); // ℹ Processing...
formatWarning(message)

Formats warning message with warning symbol.

ui.formatWarning('Deprecated'); // ⚠ Deprecated

WorkpackageUI

Main UI controller for workpackage execution.

import { WorkpackageUI } from '@sigaostudios/sigao-cli/workpackage/ui';

Constructor

const ui = new WorkpackageUI(options)

Parameters:

  • options (Object)
    • interactive (boolean) - Enable interactive mode
    • colors (boolean) - Enable colored output

Methods

showMenu(workpackages)

Displays interactive workpackage selection menu.

const selected = await ui.showMenu(workpackages);
// Returns array of selected workpackage IDs
showProgress(current, total, message)

Shows progress indicator.

ui.showProgress(5, 10, 'Processing tasks');
// [████████████████████░░░░░░░░░░░░░░░░░░░░] 50% | Processing tasks
showStatus(workpackageId, status, details)

Displays workpackage status.

ui.showStatus('WP-01-SETUP', 'completed', {
  tasks: { total: 5, completed: 5 },
  duration: 12500
});

ProcessIndicator

Shows real-time process execution status.

import { ProcessIndicator } from '@sigaostudios/sigao-cli/workpackage/ui';

Constructor

const indicator = new ProcessIndicator(name, options)

Parameters:

  • name (string) - Process name to display
  • options (Object)
    • showMemory (boolean) - Show memory usage after 30s
    • updateInterval (number) - Update interval in ms

Methods

start()

Starts the indicator.

indicator.start();
// Shows: ProcessName (0s)
stop(success)

Stops the indicator.

indicator.stop(true);  // Shows success state
indicator.stop(false); // Shows failure state

Claude Integration API

ClaudeInterface

Manages interaction with Claude CLI.

import { ClaudeInterface } from '@sigaostudios/sigao-cli/workpackage/claude';

Constructor

const claude = new ClaudeInterface(options)

Parameters:

  • options (Object)
    • claudeCommand (string) - Claude CLI command path
    • timeout (number) - Execution timeout in ms
    • maxRetries (number) - Maximum retry attempts

Methods

isInstalled()

Checks if Claude CLI is installed.

const installed = await claude.isInstalled();

Returns: Promise

executeTask(prompt, options)

Executes a task with Claude.

const result = await claude.executeTask(prompt, {
  timeout: 300000,
  context: { /* additional context */ }
});

Returns: Promise

{
  success: boolean,
  output: string,
  duration: number,
  retries: number
}

PromptBuilder

Builds prompts from templates.

import { PromptBuilder } from '@sigaostudios/sigao-cli/workpackage/claude';

Methods

buildPrompt(task, context)

Builds a complete prompt for a task.

const prompt = promptBuilder.buildPrompt(task, {
  global: globalContext,
  uow: uowContext,
  cumulative: cumulativeSummary
});

Returns: string - Formatted prompt

loadTemplate(name)

Loads a prompt template.

const template = await promptBuilder.loadTemplate('task-execution');
renderTemplate(template, data)

Renders a template with data.

const rendered = promptBuilder.renderTemplate(template, {
  task: taskDescription,
  context: contextData
});

Orchestration API

WorkpackageOrchestrator

Main orchestration controller.

import { WorkpackageOrchestrator } from '@sigaostudios/sigao-cli/workpackage/orchestrator';

Constructor

const orchestrator = new WorkpackageOrchestrator(options)

Parameters:

  • options (Object)
    • dryRun (boolean) - Preview mode
    • parallel (boolean) - Enable parallel execution
    • maxConcurrent (number) - Max concurrent tasks

Methods

executeWorkpackages(workpackages)

Executes an array of workpackages.

const result = await orchestrator.executeWorkpackages(workpackages);

Returns: Promise

handleDependencies(workpackages)

Resolves and orders workpackages by dependencies.

const ordered = orchestrator.handleDependencies(workpackages);

Returns: Array - Ordered workpackages

TaskExecutor

Executes individual tasks.

import { TaskExecutor } from '@sigaostudios/sigao-cli/workpackage/orchestrator';

Methods

executeTask(task, context)

Executes a single task.

const result = await executor.executeTask(task, context);

Returns: Promise

{
  success: boolean,
  output: string,
  testResult: TestResult,
  duration: number,
  error?: Error
}
runAcceptanceTest(command, options)

Runs task acceptance test.

const testResult = await executor.runAcceptanceTest('npm test', {
  timeout: 60000
});

Returns: Promise

DependencyResolver

Resolves workpackage dependencies.

import { DependencyResolver } from '@sigaostudios/sigao-cli/workpackage/orchestrator';

Methods

resolve(workpackages)

Resolves dependencies and returns execution order.

const resolved = resolver.resolve(workpackages);

Returns: Array - Ordered by dependencies

detectCycles(workpackages)

Detects circular dependencies.

const cycles = resolver.detectCycles(workpackages);
if (cycles.length > 0) {
  throw new Error(`Circular dependencies: ${cycles.join(', ')}`);
}

Returns: Array - Cycle descriptions

Event System API

Event Types

import { EventTypes } from '@sigaostudios/sigao-cli/workpackage/events';

// Available event types:
EventTypes.EXECUTION_START
EventTypes.EXECUTION_END
EventTypes.WORKPACKAGE_START
EventTypes.WORKPACKAGE_END
EventTypes.TASK_START
EventTypes.TASK_END
EventTypes.TEST_START
EventTypes.TEST_END

Event Emitter

The orchestrator extends EventEmitter:

orchestrator.on(EventTypes.TASK_START, (data) => {
  console.log(`Task started: ${data.task}`);
});

orchestrator.on(EventTypes.TASK_END, (data) => {
  console.log(`Task ${data.success ? 'completed' : 'failed'}`);
});

Event Data Structures

EXECUTION_START

{
  timestamp: Date,
  workpackageCount: number,
  totalTasks: number
}

TASK_START

{
  timestamp: Date,
  workpackageId: string,
  taskIndex: number,
  task: string
}

TASK_END

{
  timestamp: Date,
  workpackageId: string,
  taskIndex: number,
  task: string,
  success: boolean,
  duration: number,
  output?: string,
  error?: Error
}

Type Definitions

IWorkPackage

interface IWorkPackage {
  id: string;              // WP-XX-NAME format
  title: string;
  depends_on: string[];
  global_context?: IGlobalContext;
  uow_context?: IUowContext;
  tasks: ITask[];
  deliverables: string[];
  agent: string;
  status: WorkPackageStatus;
}

ITask

interface ITask {
  task: string;          // Task description
  acceptance: string;    // Acceptance criteria
  test: string;         // Test command
}

IGlobalContext

interface IGlobalContext {
  [key: string]: any;    // Project-wide configuration
}

IUowContext

interface IUowContext {
  [key: string]: any;    // Workpackage-specific data
}

WorkPackageStatus

type WorkPackageStatus = 'ready' | 'in_progress' | 'completed' | 'failed';

ExecutionResult

interface ExecutionResult {
  success: boolean;
  workpackages: {
    total: number;
    completed: number;
    failed: number;
    skipped: number;
  };
  tasks: {
    total: number;
    completed: number;
    failed: number;
  };
  duration: number;
  outputDir: string;
  errors?: Error[];
}

TaskResult

interface TaskResult {
  success: boolean;
  output: string;
  testResult: {
    passed: boolean;
    output: string;
    exitCode: number;
  };
  duration: number;
  retries: number;
  error?: Error;
}

Usage Examples

Basic Execution

import { executeWorkpackage } from '@sigaostudios/sigao-cli/workpackage';

// Execute a workpackage
const result = await executeWorkpackage('my-project.json', {
  dryRun: false,
  logLevel: 'info',
  outputDir: './output'
});

if (result.success) {
  console.log(`Completed ${result.tasks.completed} tasks`);
} else {
  console.error(`Failed with ${result.tasks.failed} errors`);
}

Custom Event Handling

import { WorkpackageOrchestrator, EventTypes } from '@sigaostudios/sigao-cli/workpackage';

const orchestrator = new WorkpackageOrchestrator();

// Track progress
orchestrator.on(EventTypes.TASK_END, (data) => {
  updateProgressBar(data.taskIndex, data.totalTasks);
});

// Handle errors
orchestrator.on(EventTypes.EXECUTION_ERROR, (error) => {
  sendErrorNotification(error);
});

await orchestrator.executeWorkpackages(workpackages);

Context Manipulation

import { ContextManager } from '@sigaostudios/sigao-cli/workpackage/context';

const context = new ContextManager();

// Set up context
context.setGlobalContext({
  project: 'my-app',
  environment: 'development',
  features: ['auth', 'api', 'ui']
});

// Update during execution
context.updateUowContext('WP-01', {
  currentTask: 2,
  outputs: ['file1.js', 'file2.js']
});

// Get cumulative summary
const summary = context.getCumulativeSummary();
console.log(`Last ${summary.tasks.length} tasks completed`);

Workpackage System Overview

The Sigao AI DevKit's workpackage system provides a powerful automation framework for executing complex development tasks using AI assistance. This system allows you to define structured sets of tasks that Claude (Anthropic's AI assistant) can execute sequentially, with built-in validation, testing, and dependency management.

Workpackage Developer Guide

This guide is for developers who want to extend, customize, or contribute to the Sigao CLI Workpackage Automation system.