Workflow

workflow is a CLI-first workflow runner for AI agents.

This repository is not positioned as a reusable Go library. The product is the workflow-cli binary and its package-based execution model for components, modules, workflows, and workflow builders.

Package Model

The repository now uses a self-contained workspace layout:

workspace.yaml
components/
  title_uppercase/
    component.yaml
modules/
  analyze-document-mod/
    module.yaml
    components/
      local_content_word_count/
        component.yaml
workflows/
  doc-processor-workflow/
    workflow.yaml

• A global component package lives at components/<name>/component.yaml
• A module package lives at modules/<name>/module.yaml
• A module can include local component packages under modules/<name>/components/
• A workflow package lives at workflows/<name>/workflow.yaml
• A component package can be run and tested standalone when it defines run.manifest

Global and local components are both supported:

• Global components are loaded from the workspace components/ directory and any extra --components-dir paths
• Local components belong to one module package and are only registered for that module at runtime

Build And Test

Run from the repository root:

make build
make test

The build output is:

./workflow-cli

make test includes:

• unit tests
• command-level tests
• end-to-end tests that build the real CLI binary
• clean-workspace e2e coverage for init, scaffold, test, and run

Bootstrap A Workspace

Initialize a new workspace:

./workflow-cli init ./my-workspace

Scaffold a global component package:

./workflow-cli scaffold component title_uppercase

Scaffold a module package with a local component:

./workflow-cli scaffold module analyze-document-mod

Scaffold a workflow package that references a module package:

./workflow-cli scaffold workflow doc-processor-workflow --module analyze-document-mod

Run Packages

Run a standalone global component package:

./workflow-cli run component title_uppercase

Run a module package:

./workflow-cli run module analyze-document-mod

Run a workflow package:

./workflow-cli run workflow doc-processor-workflow

Run every workflow package in a directory:

./workflow-cli run workflow --dir ./workflows/

Run only selected workflow packages from a directory:

./workflow-cli run workflow --dir ./workflows/ --name doc-processor-workflow

Emit structured JSON for agents:

./workflow-cli run workflow doc-processor-workflow --json

Write the report to a stable handoff file:

./workflow-cli run workflow doc-processor-workflow --report-file ./tmp/run-report.json

Test Packages

Test a standalone component package:

./workflow-cli test component title_uppercase

Test a module package:

./workflow-cli test module analyze-document-mod

Test a workflow package:

./workflow-cli test workflow doc-processor-workflow

Package tests execute the real package and compare the result against test.expect in the package manifest.

Build A Workflow From Source

workflow-cli build workflow compiles a concise workflow source file into a runnable workflow manifest by executing the built-in workflow package at workflows/module-builder/workflow.yaml.

Example:

./workflow-cli build workflow ./example/module-source.yaml --output ./tmp/generated-workflow.yaml

The built-in builder itself is package-based:

• workflow package: workflows/module-builder/
• module package: modules/module-builder/
• local builder components: modules/module-builder/components/

Legacy Compatibility

The package model is the default direction, but the CLI still supports legacy runnable workflow files and the older source example files.

Execution Examples Run a single Workflow via file:

./workflow-cli run workflow ./example/workflow.yaml

Run an entire directory of workflows:

./workflow-cli run workflow --dir ./example/

Run only specific workflows from a directory by name:

./workflow-cli run workflow --dir ./example/ --name doc-processor-workflow

Isolate and run a single Module inside a workflow file:

./workflow-cli run module ./example/workflow.yaml --module-id analyze-document-mod

Reports For Agents

Each run, test, and build command writes a JSON artifact under .workflow/reports/ unless --report-file is set.

The report includes:

• workflow and module status
• timestamps and durations
• retry counts
• per-component step attempts
• execution events
• final manifest data

Repository Layout

• workspace.yaml: workspace root configuration
• components/: global component packages
• modules/: module packages, including module-local components
• workflows/: workflow packages and built-in workflows
• example/: legacy compatibility examples for raw workflow/source files
• cmd/workflow/: CLI entrypoint and command wiring
• pkg/: lower-level runtime packages used by the CLI
• AGENTS.md: repository guidance for AI coding agents

Commit Format

Use this format for commits:

{commit type}({any file/package}): {commit message}

Examples:

feat(cmd/workflow): add workflow package scaffolding
fix(modules/module-builder): load package builder in build command
docs(README.md): document package-first workspace layout
test(e2e): cover init and scaffold flows