zig-core 0.5.7

Core library for zig — workflow orchestration engine for AI coding agents
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

# zig run

Execute a `.zug` workflow file.

## Synopsis

```
zig run <workflow> [prompt] [--no-resources]
```

## Description

Parses a `.zug` workflow file, validates it, resolves the step DAG, and
executes each step by delegating to `zag`. Steps are grouped into
parallelizable tiers using topological sorting — steps within the same tier
run concurrently when their dependencies are satisfied.

## Arguments

| Argument   | Description                                              |
|------------|----------------------------------------------------------|
| `workflow` | Name or path of the workflow to run                      |
| `prompt`   | Optional context prompt injected into every workflow step|

## Flags

| Flag             | Description                                                                                  |
|------------------|----------------------------------------------------------------------------------------------|
| `--no-resources` | Disable the `<resources>` block normally injected into each step's system prompt. Useful when you want a workflow to run with no global / cwd / inline resource advertisements at all. See `zig man resources`. |

## Workflow Resolution

The `workflow` argument is resolved in this order:

1. Literal path as given (e.g., `./my-workflow.zug`)
2. With `.zug` extension appended (e.g., `my-workflow` → `my-workflow.zug`)
3. Under `./workflows/` directory (e.g., `workflows/my-workflow`)
4. Under `./workflows/` with `.zug` appended (e.g., `workflows/my-workflow.zug`)
5. Under `~/.zig/workflows/` global directory
6. Under `~/.zig/workflows/` with `.zug` appended

## Execution Model

1. The workflow file is parsed and validated
2. Variable constraints are checked before execution begins
3. Steps are sorted into tiers using Kahn's algorithm (topological sort)
4. Steps within the same tier run concurrently (auto-parallelized); a single-step tier runs sequentially with live output streaming
5. Race groups within a tier run in parallel; the first to finish wins and the rest are cancelled
6. Variable substitution (`${var}`) is applied to prompts and system prompts before execution
7. Step outputs are captured and can be:
   - Injected into dependent steps via `inject_context`
   - Extracted into variables via `saves` selectors
8. Conditions are evaluated to determine whether steps should run or be skipped
9. The `next` field enables loops by jumping back to earlier steps
10. A maximum of 100 loop iterations is enforced to prevent infinite loops
11. Each run is logged as a zig session under `~/.zig/` — use `zig listen` to tail

## Failure Handling

Each step can configure its failure behavior with `on_failure`:

| Policy     | Behavior                                        |
|------------|-------------------------------------------------|
| `fail`     | Abort the entire workflow (default)              |
| `continue` | Skip the failed step and continue                |
| `retry`    | Retry the step up to `max_retries` times         |

## Examples

```bash
# Run a workflow by name
zig run code-review

# Run a workflow file directly
zig run ./workflows/deploy.zug

# Run with additional context
zig run code-review "focus on the authentication module"

# Run without injecting any resource advertisements
zig run code-review --no-resources
```

## Prerequisites

- `zag` must be installed and available on PATH

## See Also

- `zig man zug` — the `.zug` file format
- `zig man variables` — variable substitution and data flow
- `zig man conditions` — condition expressions
- `zig man resources` — managing reference files for agents