Workpackage System Overview

Workpackage User Guide

This comprehensive guide covers everything you need to know about using the Sigao CLI Workpackage Automation system effectively.

Workpackage User Guide

This comprehensive guide covers everything you need to know about using the Sigao CLI Workpackage Automation system effectively.

Understanding Workpackages

What is a Workpackage?

A workpackage is a JSON file that defines a structured set of development tasks. Each workpackage contains:

  • Metadata: ID, title, and dependencies
  • Tasks: Individual units of work with acceptance criteria
  • Context: Information shared across tasks
  • Deliverables: Expected output files

Key Concepts

Tasks

The atomic units of work. Each task has:

  • Description: What Claude should do
  • Acceptance Criteria: How to verify success
  • Test Command: Automated verification

Dependencies

Workpackages can depend on others, creating execution chains:

"depends_on": ["WP-01-SETUP", "WP-02-CONFIG"]

Context

Shared information accessible to all tasks:

  • Global Context: Project-wide settings
  • UoW Context: Workpackage-specific data

Workpackage Structure

Basic Structure

[
  {
    "id": "WP-01-FEATURE",
    "title": "Implement User Authentication",
    "depends_on": [],
    "global_context": {
      "project": "my-app",
      "framework": "express"
    },
    "uow_context": {
      "feature": "authentication",
      "approach": "JWT-based"
    },
    "tasks": [
      {
        "task": "Create user model with email and password fields",
        "acceptance": "User model exists with proper validation",
        "test": "npm test -- user.model.test.js"
      }
    ],
    "deliverables": [
      "src/models/User.js",
      "tests/user.model.test.js"
    ],
    "agent": "claude",
    "status": "ready"
  }
]

Field Reference

Required Fields

FieldTypeDescription
idstringUnique identifier (format: WP-XX-NAME)
titlestringHuman-readable title
depends_onarrayList of dependency IDs
tasksarrayList of task objects
deliverablesarrayExpected output files
agentstringAI agent to use (currently "claude")
statusstringready, in_progress, completed, failed

Optional Fields

FieldTypeDescription
global_contextobjectProject-wide context
uow_contextobjectWorkpackage-specific context

Running Workpackages

Basic Execution

sigao work my-workpackage.json

Command Options

Model Selection

Choose which Claude model to use:

# Use latest Opus model for complex tasks
sigao work my-workpackage.json --model opus

# Use latest Sonnet model (default)
sigao work my-workpackage.json --model sonnet

# Use specific model version
sigao work my-workpackage.json --model claude-opus-4-20250514

Model recommendations:

  • Sonnet (default): Fast and efficient for most tasks
  • Opus: More capable for complex reasoning and large refactors
  • Specific versions: Lock to a particular model for consistency

Dry Run Mode

Preview what will happen without executing:

sigao work my-workpackage.json --dry-run

Output:

DRY RUN MODE - No changes will be made

Would execute:
- WP-01-SETUP: 3 tasks
- WP-02-FEATURE: 5 tasks
Total: 8 tasks across 2 workpackages

Output Directory

Specify where to save outputs:

sigao work my-workpackage.json --output-dir ./my-outputs

Logging Levels

Control verbosity:

# Options: error, warn, info (default), debug
sigao work my-workpackage.json --log-level debug

Interactive Features

Workpackage Selection

When multiple workpackages are available:

? Select workpackages to execute: (Press <space> to select, <a> to toggle all)
 ◉ WP-01-SETUP - Project Setup
❯◯ WP-02-API - API Implementation
 ◯ WP-03-FRONTEND - Frontend Development

Manual Intervention

Some tasks may require manual steps:

⚠️  Manual Intervention Required
Task: Configure database connection
Please update config/database.js with your credentials
Press Enter when ready to continue...

Understanding Output

Directory Structure

.sigao/
└── workpackage/
    └── run-2024-01-15-143022/
        ├── status.json              # Machine-readable status
        ├── summary.md               # Human-readable summary
        ├── tasks/
        │   ├── WP-01-SETUP/
        │   │   ├── task-001.md      # Task output
        │   │   ├── task-001.test    # Test results
        │   │   └── task-001.log     # Execution log
        │   └── WP-02-API/
        │       └── ...
        └── logs/
            └── execution.log        # Full execution log

Status File Format

{
  "runId": "run-2024-01-15-143022",
  "startTime": "2024-01-15T14:30:22Z",
  "endTime": "2024-01-15T14:45:18Z",
  "workpackages": {
    "WP-01-SETUP": {
      "status": "completed",
      "tasks": {
        "total": 3,
        "completed": 3,
        "failed": 0
      }
    }
  }
}

Reading Task Outputs

Each task output includes:

  1. Claude's Response: The generated code or actions
  2. Files Created/Modified: List of affected files
  3. Test Results: Output from acceptance tests
  4. Execution Metadata: Timing, memory usage, etc.

Example task output:

# Task: Create Express server setup

## Response
I'll create a basic Express server with middleware configuration.

## Actions Taken
1. Created `src/server.js` with Express setup
2. Added middleware for JSON parsing, CORS, and security
3. Created `src/config/index.js` for configuration

## Files Modified
- src/server.js (created)
- src/config/index.js (created)
- package.json (updated dependencies)

## Test Results
✓ Server starts on port 3000
✓ Health check endpoint responds
✓ Middleware properly configured

Handling Failures

Understanding Error Types

Task Failures

When a task fails, you'll see:

✗ Task 2/5 failed: Create database connection
Error: Connection timeout to localhost:5432

Test Failures

When acceptance tests fail:

✓ Task completed
✗ Acceptance test failed
Expected: File contains "export default"
Actual: File contains "module.exports"

Recovery Strategies

1. Automatic Retry

Tasks automatically retry on transient failures:

Task failed: Network error
Retrying (attempt 2/3)... ✓ Success

2. Manual Intervention

For non-recoverable errors:

✗ Database connection failed
Options:
1. Fix the issue and retry
2. Skip this task
3. Abort execution
Choice:

3. Resume from Failure

Resume execution from where it failed:

# Original execution
sigao work my-workpackage.json
# Failed at task 3

# Resume from task 3
sigao work my-workpackage.json --resume

Common Failure Scenarios

Missing Dependencies

Error: Cannot find module 'express'
Solution: Run npm install first

Permission Issues

Error: EACCES: permission denied
Solution: Check file permissions or run with appropriate privileges

Test Command Failures

Error: Command 'npm test' not found
Solution: Ensure test scripts are defined in package.json

Advanced Features

Using Context Effectively

Global Context

Share project-wide information:

"global_context": {
  "project_name": "my-app",
  "node_version": "18",
  "database": "postgresql",
  "testing_framework": "jest"
}

UoW Context

Workpackage-specific data:

"uow_context": {
  "module": "authentication",
  "dependencies": ["bcrypt", "jsonwebtoken"],
  "test_users": [
    {"email": "test@example.com", "role": "admin"}
  ]
}

Complex Dependencies

Linear Dependencies

// WP-02 runs after WP-01
{
  "id": "WP-02-API",
  "depends_on": ["WP-01-SETUP"]
}

Multiple Dependencies

// WP-04 waits for both WP-02 and WP-03
{
  "id": "WP-04-INTEGRATION",
  "depends_on": ["WP-02-BACKEND", "WP-03-FRONTEND"]
}

Custom Test Commands

Shell Commands

{
  "test": "grep -q 'TODO' README.md && echo 'Found TODO' || echo 'No TODOs'"
}

Node Scripts

{
  "test": "node -e \"require('./src/validator').validate() || process.exit(1)\""
}

Multiple Checks

{
  "test": "npm test && npm run lint && npm audit"
}

Best Practices

1. Write Clear Task Descriptions

{
  "task": "Make API"
}

2. Use Specific Acceptance Criteria

{
  "acceptance": "API works"
}

3. Make Tests Deterministic

{
  "test": "curl https://api.example.com/test"
}

4. Organize Workpackages Logically

workpackages/
├── 01-setup/
│   └── infrastructure.json
├── 02-backend/
│   ├── database.json
│   └── api.json
└── 03-frontend/
    └── ui-components.json

5. Version Control Your Workpackages

git add workpackages/
git commit -m "Add authentication workpackage"

Examples

Example 1: Simple File Creation

[
  {
    "id": "WP-01-DOCS",
    "title": "Create Documentation",
    "tasks": [
      {
        "task": "Create README.md with project overview, installation, and usage sections",
        "acceptance": "README has all required sections",
        "test": "test -f README.md && grep -q '## Installation' README.md"
      }
    ],
    "deliverables": ["README.md"],
    "agent": "claude",
    "status": "ready"
  }
]

Example 2: Full Stack Feature

[
  {
    "id": "WP-01-USER-API",
    "title": "User Management API",
    "global_context": {
      "framework": "express",
      "database": "mongodb",
      "auth": "jwt"
    },
    "tasks": [
      {
        "task": "Create User model with Mongoose schema",
        "acceptance": "Model has email, password, createdAt fields",
        "test": "node -e \"require('./models/User.js')\""
      },
      {
        "task": "Implement user registration endpoint POST /api/users",
        "acceptance": "Endpoint validates input and hashes password",
        "test": "npm test -- auth.test.js"
      },
      {
        "task": "Add JWT authentication middleware",
        "acceptance": "Middleware verifies tokens and sets req.user",
        "test": "npm test -- middleware.test.js"
      }
    ],
    "deliverables": [
      "models/User.js",
      "routes/users.js",
      "middleware/auth.js",
      "tests/*.test.js"
    ],
    "agent": "claude",
    "status": "ready"
  }
]

Example 3: Error Recovery

See examples/workpackages/error-handling.json for patterns like:

  • Network error simulation
  • Retry mechanisms
  • Graceful degradation
  • Manual intervention points

Troubleshooting Quick Reference

IssueSolution
"Claude not found"Install Claude CLI: npm install -g @anthropic/claude-cli
"Invalid workpackage"Validate JSON syntax and required fields
"Test failed"Check test command manually, ensure dependencies installed
"Permission denied"Check file permissions, run with appropriate user
"Out of memory"Increase Node.js memory: NODE_OPTIONS='--max-old-space-size=4096'

Getting Help

  • Check the Troubleshooting Guide for detailed solutions
  • Review Example Workpackages in the repository
  • Use --log-level debug for detailed execution logs
  • Save outputs with --output-dir for analysis

Troubleshooting Guide

This guide helps you resolve common issues with the Sigao CLI Workpackage Automation system.

Tools & Configuration

Set up and configure your development environment for AI-first development.