Zigma Flow -- Agent Workflow Runtime

A local, single-process TypeScript CLI that orchestrates multi-job workflows for Agent-assisted software development. It breaks complex tasks into discrete, auditable steps so an AI agent (like Claude Code) only handles one step at a time, preventing context overload and skipped gates.

• Quick Start
• How It Works
• CLI Commands
• code-change Workflow
• Customizing the Workflow
• Development

Quick Start

1. Install zigma-flow globally:

   npm install -g @zigma-ai/zigma-flow

2. Navigate to your project (or a fresh directory):

   cd my-project

3. Initialize zigma-flow:

   zigma-flow init

   This creates .zigma-flow/ with a default code-change workflow, Skill Pack prompts, and configuration. See the init reference for how init detects your project's package manager and scripts.

4. Validate the generated workflow:

   zigma-flow validate .zigma-flow/workflows/code-change.yml

   Expected output: Workflow is valid.

5. Try a fully automated run:

   zigma-flow invoke code-change --task "Add null check to parse function"

   The engine drives every job -- agent steps, script steps, and checks -- automatically, writing results to .zigma-flow/runs/.

6. Check the run status:

   zigma-flow inspect --latest

   Shows the status summary of the most recent run. Add --jobs for per-job detail, --events for the event log, or --artifacts to list outputs.

Package managers: This project uses pnpm for its own development (see Development). The init command auto-detects your project's lockfile and generates script steps (typecheck, lint, test) that use your project's own package manager. npm, yarn, and bun are all supported.

How It Works

A workflow is a DAG of jobs. Each job contains one or more steps, which are the smallest execution units. Steps come in four kinds: Agent steps (require LLM judgment), Script steps (shell commands), Check steps (deterministic validation), and Router steps (conditional branching). The workflow YAML lives in .zigma-flow/workflows/ and is read by the Engine at runtime.

The Engine owns all state transitions. Agents cannot directly modify workflow state; they can only emit signals in their report.json. The Engine evaluates signals against declared rules and decides whether to activate an optional job, retry a previous job, or continue normally. All state changes are written to an event log under .zigma-flow/runs/, making every run auditable and replayable.

For the language specification, see docs/workflow-language.md.

CLI Commands

Primary Commands

| Command | Purpose | |---------|---------| | init | Initialize .zigma-flow/ scaffold in the current directory | | validate <path> | Validate a workflow YAML or Skill Pack manifest | | invoke <workflow> --task <description> | Create and execute a workflow run to completion (unified lifecycle) | | invoke <workflow> --resume <run-id> | Resume an interrupted run | | invoke <workflow> --dry-run | Validate and plan without executing | | invoke <workflow> --trace | Verbose event-by-event output | | invoke <workflow> --pause-before <job.step> | Pause execution before a specific step (debugging) | | invoke <workflow> --stop-after <job.step> | Stop execution after a specific step (debugging) | | invoke <workflow> --save-all-prompts | Save every agent prompt to artifacts without pausing | | inspect [run-id] | Inspect a run: summary (default), --jobs, --events, --artifacts, --json | | inspect --latest | Inspect the most recent run | | resume [run-id] --job <id> --input key=value | Submit human input to resume a paused human step | | doctor | Diagnose common environment and configuration issues |

Advanced Commands

| Command | Purpose | |---------|---------| | retry --job <id> | Retry a failed job | | abort | Abort the current run | | list-runs | List all runs | | show <run-id> | Show detailed run information | | artifacts [run-id] | List artifacts produced by a run | | events [run-id] | List events recorded during a run | | verify-run [run-id] | Check run data integrity | | skill add <pack-path> | Register a local skill pack | | status | Show current run status (use inspect for richer output) |

Deprecated Commands

These commands still work but will be removed in v1.0.

| Command | Replacement | |---------|-------------| | run <workflow> | invoke <workflow> --task <description> | | run-all <workflow> | invoke <workflow> | | prompt --job <id> | invoke --pause-before <job.step> | | step --job <id> | invoke (automatic execution) | | next --job <id> | invoke (automatic advancement) | | check | invoke (automatic check execution) | | approve --job <id> | resume --job <id> --input decision=approve | | reject --job <id> --comment <msg> | resume --job <id> --input decision=reject --input comment="<msg>" |

For a complete reference of every subcommand and its options, see the workflow language reference at docs/workflow-language.md and the error code reference.

code-change Workflow

The built-in code-change workflow covers the full lifecycle of a code change: from understanding the task through implementation, validation, and review.

intake
  └── code-map
        └── risk-scan
              └── plan
                    ├── architecture-design [optional, signals]
                    └── implement (optional_needs: architecture-design)
                          ├── static-check
                          ├── unit-test
                          └── review
                                └── summarize

| Job | Kind | Description | |-----|------|-------------| | intake | Agent | Analyze the task description; produce an intake-summary artifact | | code-map | Agent | Map relevant files and modules; produce a code-map artifact | | risk-scan | Check | Validate that the code-map artifact exists and is well-formed | | plan | Agent | Create an implementation plan; may emit needs_architecture_design | | architecture-design | Agent | Produce architecture design (optional; activated by signal) | | implement | Agent | Implement the change; up to 3 retry attempts | | static-check | Script | Run typecheck and lint (pnpm typecheck && pnpm lint by default) | | unit-test | Script | Run the test suite (pnpm test:ci by default) | | review | Agent | Review the implementation; may emit review_rejected | | gate-merge | Human | Manual approval gate before final merge (optional) | | summarize | Agent | Produce a final change summary artifact |

Signals

• needs_architecture_design -- emitted by plan or review. The Engine activates the optional architecture-design job, which implement waits for before starting.
• review_rejected -- emitted by review. The Engine retries the implement job (up to 3 total attempts). If attempts are exhausted, the run fails.

Agent Backend Configuration

The agent backend (default: claude-code) is configured in .zigma-flow/config.json:

{
  "agent": {
    "backend": "claude-code",
    "backends": {
      "claude-code": {
        "command": "claude",
        "args": ["-p"],
        "timeout": 600000
      }
    },
    "parallelism": 4
  }
}

Parallelism controls how many read-only jobs run concurrently during invoke. Set agent.parallelism in the config or pass --parallelism <N> on the command line. The default is 4. Use --parallelism 1 for strictly sequential execution.

For advanced execution semantics, see the concurrency model documentation.

Customizing the Workflow

After zigma-flow init, edit .zigma-flow/workflows/code-change.yml to:

• Add new jobs by declaring them under jobs: and setting needs: dependencies.
• Change retry limits by updating retry.max_attempts on a job.
• Add new signals by declaring them under signals: with an action.
• Update script steps if your project uses different validation commands. The generated defaults use your detected package manager. The static-check and unit-test jobs can be changed to run custom scripts, lint rules, or test frameworks.

Skill Pack prompts and knowledge files live in .zigma-flow/skills/code-change/ and can be edited to match your project's conventions. See docs/workflow-language.md for the complete workflow schema reference.

Development

pnpm install
pnpm typecheck
pnpm test
pnpm build

Requirements: Node >= 20.11.0, pnpm 10+.

Project Layout

• src/ -- TypeScript source files (CLI entry point, Engine, init, etc.)

• tests/ -- Vitest test suite

• examples/ -- Runnable example projects

• docs/ -- Architecture, contracts, error codes, and wiki documentation

  • docs/architecture.md -- System design and module boundaries
  • docs/mvp-contracts.md -- MVP execution contracts
  • docs/error-codes.md -- Stable exit code reference

• .zigma-flow/ -- The project's own workflow configuration (dogfooding)