Workpackage System Overview

Getting Started with Workpackages

This guide will walk you through setting up and running your first workpackage in under 10 minutes!

Getting Started with Workpackages

This guide will walk you through setting up and running your first workpackage in under 10 minutes!

Prerequisites

Before you begin, ensure you have:

  • Node.js 18+ installed (Download)
  • npm or yarn package manager
  • Git for version control
  • A terminal/command prompt

Step 1: Install Sigao CLI

Global Installation (Recommended)

npm install -g @sigaostudios/sigao-cli

Local Project Installation

cd your-project
npm install --save-dev @sigaostudios/sigao-cli

Verify Installation

sigao --version
# Output: @sigaostudios/sigao-cli version X.X.X

sigao work --help
# Should display workpackage command help

Step 2: Install Claude CLI

The workpackage system uses Claude (Anthropic's AI assistant) to execute tasks.

Installation Methods

Configure Claude CLI

# Set your API key (get one from https://console.anthropic.com/)
claude auth login

# Test the connection
claude --version

Step 3: Run Your First Workpackage

Let's start with a simple example that creates a "Hello World" project.

Option 1: Use Built-in Example

# Navigate to your project directory
cd my-project

# Run the simple example
npx sigao work node_modules/@sigaostudios/sigao-cli/examples/workpackages/simple.json

Option 2: Create Your Own

Create a file named hello-workpackage.json:

[
  {
    "id": "WP-01-HELLO",
    "title": "Hello World Setup",
    "depends_on": [],
    "tasks": [
      {
        "task": "Create a hello.js file that prints 'Hello from Workpackages!'",
        "acceptance": "File exists and contains the message",
        "test": "node hello.js | grep -q 'Hello from Workpackages!'"
      },
      {
        "task": "Create a README.md explaining what the hello.js file does",
        "acceptance": "README exists with clear explanation",
        "test": "test -f README.md && grep -q 'hello.js' README.md"
      }
    ],
    "deliverables": ["hello.js", "README.md"],
    "agent": "claude",
    "status": "ready"
  }
]

Run your workpackage:

sigao work hello-workpackage.json

# For more complex tasks, use the Opus model
sigao work hello-workpackage.json --model opus

What to Expect

When you run a workpackage, you'll see:

1. Validation Phase

Validating workpackage...
✓ Schema validation passed
✓ Found 1 workpackage with 2 tasks

2. Interactive Menu (if multiple workpackages)

? Select workpackages to execute: (Press <space> to select)
❯◉ WP-01-HELLO - Hello World Setup

3. Execution Progress

Starting workpackage execution...

Executing WP-01-HELLO - Hello World Setup
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Task 1/2: Create a hello.js file
Status: Running Claude... (5s)

✓ Task completed successfully
✓ Acceptance test passed

4. Summary Report

Workpackage Execution Complete!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ WP-01-HELLO: 2/2 tasks completed

Output saved to: .sigao/workpackage/run-2024-01-15-143022/

Understanding the Output

After execution, check the .sigao directory:

.sigao/
└── workpackage/
    └── run-2024-01-15-143022/
        ├── status.json          # Execution status
        ├── tasks/
        │   ├── task-001.md      # Claude's response for task 1
        │   └── task-002.md      # Claude's response for task 2
        └── summary.md           # Human-readable summary

Common First-Time Issues

Claude CLI Not Found

If you get claude: command not found, ensure Claude CLI is in your PATH:

export PATH="$PATH:/path/to/claude"

API Key Issues

If you see Authentication required, configure your Claude API key:

claude auth login

Permission Denied

For permission errors, fix npm permissions or use sudo (carefully):

sudo npm install -g @sigaostudios/sigao-cli

Next Steps

Now that you've run your first workpackage:

  1. Explore Examples: Check out more complex examples in examples/workpackages/
  2. Read the User Guide: Learn about advanced features in the User Guide
  3. Create Custom Workpackages: Design your own automation workflows
  4. Join the Community: Share your workpackages and learn from others

Quick Tips

  • Dry Run First: Use --dry-run to preview what will happen
  • Save Outputs: Use --output-dir to organize outputs by project
  • Debug Mode: Use --log-level debug for detailed execution logs
  • Version Control: Commit your workpackage JSON files to Git

Getting Help

Workpackage Developer Guide

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

Troubleshooting Guide

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