forza 0.2.0

Configurable workflow orchestrator for agent driven software development
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
94
95
96
97
98
99
100
101
102
103
104
105
106

# forza

[![Crates.io](https://img.shields.io/crates/v/forza.svg)](https://crates.io/crates/forza)
[![docs.rs](https://docs.rs/forza/badge.svg)](https://docs.rs/forza)
[![License](https://img.shields.io/crates/l/forza.svg)](LICENSE-MIT)
[![CI](https://github.com/joshrotenberg/forza/actions/workflows/ci.yml/badge.svg)](https://github.com/joshrotenberg/forza/actions/workflows/ci.yml)

Configurable workflow orchestrator for agent driven software development.

## How it works

```
GitHub Issue  →  Triage  →  Workflow  →  Stages  →  Pull Request
```

Point it at a GitHub issue, it decides if the issue is ready, picks a workflow template, executes stages (plan, implement, test, review), and opens a PR. Each stage runs a bounded agent session in an isolated git worktree.

## Quick start

```bash
# Process a single issue
forza issue 123

# Preview without executing
forza issue 123 --dry-run
# Example output:
#   Would run workflow 'bug' for issue #123: Fix login crash
#   Stages: plan → implement → test → review → open_pr
#   Estimated cost: $0.80 - $1.50 (avg $1.05, based on 3 previous bug runs)
#   (cost line shown only when historical run data exists)

# Poll for eligible issues
forza run

# Watch mode (continuous polling)
forza watch --interval 300
```

## Configuration

Forza uses a `forza.toml` (or `runner.toml`) config with named routes:

```toml
[global]
repo = "owner/name"
model = "claude-sonnet-4-6"
gate_label = "runner:ready"

[routes.bugfix]
type = "issue"
label = "bug"
workflow = "bug"
concurrency = 1
poll_interval = 60

[routes.features]
type = "issue"
label = "enhancement"
workflow = "feature"
concurrency = 2
poll_interval = 300
```

## Concepts

### Route
A named lane that maps a type (issue/pr) + label to a workflow. Each route has its own concurrency and polling frequency.

### Workflow Template
The stage chain for a type of work. Built-in templates:

| Template | Stages |
|----------|--------|
| **bug** | plan → implement → test → review → open_pr |
| **feature** | plan → implement → test → review → open_pr |
| **chore** | implement → test → open_pr |
| **research** | research → comment |

### Stage
A bounded unit of work. Each stage has a kind, a prompt, tool scoping, and retry policy.

### Lease
GitHub labels that prevent duplicate work: `runner:ready` → `runner:in-progress` → `runner:complete`.

## Architecture

Three separated layers:

```
┌─────────────────────────────────────────────────────┐
│  Platform (github.rs)                                │
│  Issues, PRs, comments, labels via gh CLI            │
├─────────────────────────────────────────────────────┤
│  Domain (config, triage, planner, workflow)           │
│  Orchestration — what to do and when                 │
├─────────────────────────────────────────────────────┤
│  Execution (executor, isolation)                     │
│  Agent invocation and work isolation                 │
└─────────────────────────────────────────────────────┘
```

Agent-agnostic via the `AgentAdapter` trait. Claude is the default, pluggable for other agents.

## Status

MVP working. 12+ runs, 100% success rate. Processing its own issues to build itself.