Skip to content
agoodwayPublic

About

A simple light weight CI

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

goodflows

goodflows runs the jobs in a goodflows.toml file. A job is a shell command, a list of steps, or a call to another workflow in the same file. A job starts after every job in its depends_on list has passed, and ready jobs run at the same time, up to the parallelism limit. The run prints what passed, failed, timed out, or was skipped.

TLDR

cargo install --git https://github.com/agoodway/goodflows.git --locked  # install (Rust 1.88+)

goodflows init                     # write a goodflows.toml for this project
goodflows validate                 # check the config without running anything
goodflows list                     # print each job, its dependencies, and its settings
goodflows                          # run the default workflow
goodflows run ci                   # run the workflow named ci
goodflows --jobs test              # run test and the jobs it depends on
goodflows --env ci                 # apply the ci profile's settings
goodflows --json=summary           # print JSON Lines that end with a summary event

goodflows last                     # print the last run's report again, and exit with its exit code
goodflows run --failed             # rerun the jobs that failed last time

id=$(goodflows run --detach)       # start a run in the background and print its id
goodflows status "$id"             # print which jobs are running, passed, or failed
goodflows wait "$id" --timeout 90  # wait for the run, and exit 75 if it is still going
goodflows cancel "$id"             # stop the run

goodflows agents                   # print the guide for coding agents
goodflows skills install           # install the agent skills into this repository
goodflows mcp                      # serve goodflows to a coding agent over MCP

A minimal goodflows.toml:

[[jobs]]
name = "fmt"
command = "cargo fmt --check"

[[jobs]]
name = "test"
command = "cargo test --locked"
depends_on = ["fmt"]

[[jobs]]
name = "lint"
command = "cargo clippy --locked --all-targets -- -D warnings"
depends_on = ["fmt"]

fmt runs first. After it passes, test and lint run at the same time.

Exit code 0 means every job passed or was skipped. Exit code 1 means a job failed or timed out. Exit code 2 means the command line or the config is wrong. last and wait exit with the exit code of the run they report. The exit code table has the rest.

goodflows keeps local state, such as the last run record and detached runs, in a .goodflows/ directory. It writes a .gitignore there, so git ignores that directory without a change to your own .gitignore.

For agents

  • Run goodflows agents first. It prints the exit codes, error codes, and JSON fields for the installed version.
  • Run goodflows --json=summary. The last line is a summary event, and its success field is true when the run passed. Each failed job in it carries the start and end of its output.
  • When a run or another command cannot do what it was asked, goodflows prints one error event. Its code, such as config_invalid or unknown_job, does not change between releases. Branch on code, not on message.
  • goodflows last shows the last run's failures again and exits with that run's exit code. After a fix, run goodflows run --failed to rerun only the failed jobs and the jobs they depend on.
  • If your shell stops commands after a few minutes, start the run with goodflows run --detach. Then call goodflows wait <id> --timeout 90 until the exit code is not 75. goodflows cancel <id> stops it.
  • goodflows skills install adds skills that teach the next agent to run this repository's checks. goodflows mcp offers run (with detach), wait, status, cancel, last, validate, and list as MCP tools.

Install

With Rust 1.88 or newer:

cargo install --git https://github.com/agoodway/goodflows.git --locked

GitHub Releases also has archives for Linux and macOS, on x86_64 and aarch64. Check the archive against its .sha256 file, unpack it, and put goodflows on your PATH:

sha256sum -c goodflows-v0.8.0-x86_64-unknown-linux-gnu.tar.gz.sha256
tar -xzf goodflows-v0.8.0-x86_64-unknown-linux-gnu.tar.gz
install -m 755 goodflows ~/.local/bin/goodflows

The v0.6.0 Linux archives need glibc 2.34 or newer. docs/install.md lists every archive name and covers checksums, glibc, and building from source for musl.

Quick start

From the project directory:

goodflows init
goodflows validate
goodflows list
goodflows

goodflows with no subcommand is goodflows run. It runs the default workflow. validate parses the file and does not run commands. list prints each job, its dependencies, and the settings the run would use.

init writes goodflows.toml. It chooses a template from the files in the current directory: Cargo.toml (rust), mix.exs (elixir), package.json (node), or go.mod (go). If none of those files exist, the template is generic. If more than one exists, init stops and you pass --template rust|elixir|node|go|generic.

The generic template writes one job, check, whose command prints a message and exits 1. Replace that command. The rust, elixir, and go templates include a job named test. The elixir template sets MIX_ENV to test in [settings.env]. The node template reads package.json and adds a job for each of format:check, lint, typecheck, check, test, and build that exists. It runs them with npm, pnpm, yarn, or bun, picked from the lockfile. Conflicting lockfiles make init stop. With no lockfile it uses npm.

goodflows --jobs test

--jobs runs the named jobs and every job they depend on. Names are separated by commas. --config PATH reads or writes that file instead of goodflows.toml. --workflow NAME on init puts the generated jobs under [[workflows.NAME.jobs]]. --force overwrites an existing file. Without --force, init asks on a terminal and keeps the file when the answer is not y or yes.

goodflows loads goodflows.toml, then .goodflows.toml, from the current directory.

Feature reference

Configuration

[settings]
parallelism = 4
fail_fast = true
workdir = "."

[settings.env]
CARGO_TERM_COLOR = "always"

[[jobs]]
name = "fmt"
command = "cargo fmt --check"

[[jobs]]
name = "test"
command = "cargo test --locked"
depends_on = ["fmt"]
timeout_secs = 300
env = { RUST_BACKTRACE = "1" }

[[jobs]]
name = "lint"
command = "cargo clippy --locked --all-targets -- -D warnings"
depends_on = ["fmt"]

parallelism is how many command and step jobs may run at once. 0, or leaving it out, uses the logical CPU count. fail_fast defaults to true. After a failure, goodflows starts no further jobs, and jobs that have already started run to completion. workdir is relative to the config file, must already exist, and defaults to the config file's directory.

Jobs run with sh -c unless the job sets shell = false. With shell = false, goodflows splits the command with shell quoting rules and executes it directly. There is no globbing and no variable expansion. Stdin is closed.

goodflows rejects unknown keys. It checks the whole file before any command runs. goodflows validate reports every problem it finds in one pass. A file that is not valid TOML, or that has an unknown key, reports only that first error, because parsing stops there.

Environment values are literal strings. Layers merge by key, and a later layer replaces the same key: the calling process, [settings.env], the workflow's settings.env, the selected profile's settings.env, the job's env, then the step's env.

goodflows sets GOODFLOWS_RUN_ID itself. A command that may publish outputs also receives GOODFLOWS_OUTPUT. A selected profile sets GOODFLOWS_ENVIRONMENT to the profile name. Partitioned jobs receive GOODFLOWS_PARTITION (1-based) and GOODFLOWS_PARTITION_COUNT. Reporting jobs receive GOODFLOWS_REPORT_DIR. Config must not set those names.

goodflows --parallelism 2 --fail-fast
goodflows --no-fail-fast --jobs fmt,test
goodflows --config ./goodflows.toml
Exit code Meaning What to do
0 Every selected job passed or was skipped Nothing
1 A job failed or timed out, or goodflows hit a runtime error after the command and config were accepted Fix the code, or report the failure
2 A usage or config error: bad arguments, no config, a config that does not parse or validate, or an unknown workflow, job, or environment Fix the command or the config, then run it again
75 Only from wait or cancel: the timeout passed and the run is still going; from cr wait: the verdict did not reach a wanted state in time Run the same command again
130 Interrupted by SIGINT
143 Interrupted by SIGTERM

last and wait exit with the exit code of the run they report, so 1 means that run failed. Their own usage errors, and last finding no record (no_last_run), exit 2. Before this, last exited 0 whenever it could show the record; a script that read any non-zero exit from last as "no record" must check for exit 2 instead.

With --json, a run or other command that cannot do what it was asked ends with one error event. Its code is stable, so a script can branch on it instead of the message:

code Exit Meaning
usage 2 The arguments did not parse, or combine flags that do not go together
missing_config 2 No goodflows.toml or .goodflows.toml, or the --config file cannot be read
config_parse 2 The file is not valid TOML, or has an unknown key or a wrong type
config_invalid 2 The file parsed but failed validation; problems lists every problem
no_default_workflow 2 The file has no default workflow and the command named none
unknown_workflow 2 The workflow name is not in the file
unknown_job 2 A --jobs name is not in the selected workflow
unknown_environment 2 The --env name is not in the file
no_last_run 2 last or run --failed found no previous local run, or run --failed named a different workflow or environment
no_failed_jobs 2 run --failed found nothing to rerun: the last run had no failed or timed-out job
unknown_run 2 status, wait, or cancel found no detached run with that id for the config
config_exists 2 init would overwrite an existing config; pass --force
secret_unavailable 1 A secret could not be read before any job started; secret names the variable
runtime 1 Anything else that stopped goodflows, including history and reports upload request errors and the --sprite and sprite command checks

message is the same text that text mode prints after Error:. An unknown workflow, job, or environment message lists the names that exist. An optional hint suggests a fix, such as did you mean 'test'? for a close match. Text mode prints it on a Hint: line.

{"type":"error","code":"unknown_job","message":"unknown job 'tset' (available: fmt, test)","hint":"did you mean 'test'?","workflow":"default","schema_version":1}

Named workflows

[[workflows.ci.jobs]]
name = "fmt"
command = "cargo fmt --check"

[[workflows.ci.jobs]]
name = "test"
command = "cargo test --locked"
depends_on = ["fmt"]

[workflows.release.settings]
parallelism = 1

[workflows.release.settings.env]
CARGO_PROFILE_RELEASE_LTO = "true"

[[workflows.release.jobs]]
name = "build"
command = "cargo build --release --locked"
goodflows list --workflows
goodflows run ci
goodflows run ci --jobs test
goodflows validate
goodflows validate ci --jobs test

Top-level [[jobs]] are the default workflow. You can also declare [workflows.default]. If the file has no default, goodflows and goodflows list exit 2 and name the workflows you can pass. When the file has a [workflows] table, goodflows validate with no name checks every workflow and rejects --jobs. goodflows list --workflows prints the workflows and the default name. It rejects a workflow argument and --jobs.

Job names and depends_on belong to one workflow. A workflow's settings replace [settings] one field at a time. A field the workflow omits keeps the shared value. settings.env still merges by key.

Workflow calls

A job can run another workflow from the same file. Set workflow instead of command or steps.

[[workflows.ci.jobs]]
name = "fmt"
command = "cargo fmt --check"

[[workflows.ci.jobs]]
name = "test"
command = "cargo test --locked"
depends_on = ["fmt"]

[[workflows.release.jobs]]
name = "prepare"
command = "cargo build --release --locked"

[[workflows.release.jobs]]
name = "checks"
workflow = "ci"
depends_on = ["prepare"]

[[workflows.release.jobs]]
name = "publish"
command = "./scripts/publish.sh"
depends_on = ["checks"]
goodflows run release --jobs publish

That command runs prepare, checks, and publish. The checks call runs every job in ci. --jobs filters only the workflow you named.

A call job accepts name, depends_on, and condition. It rejects timeout_secs, partitions, env, secrets, outputs, reports, and shell = false. It publishes no outputs, so goodflows rejects needs.checks.outputs.... A job has one of command, nonempty steps, or workflow.

depends_on is the only ordering. A job with no dependency path to a call can run while that call runs. The call waits until the called workflow finishes, including that workflow's reporting. The call passes when the called workflow passes. Jobs skipped inside it by a condition or a dependency do not fail the call. The call fails when a job inside it fails or times out. A false condition skips the call and does not start the workflow. A failed or skipped call skips its own dependents.

Each call is its own run. Calling ci twice runs ci twice. Nothing is cached. Called workflows share the working tree, so give them depends_on when their writes must not overlap.

goodflows rejects cycles before anything runs. That check includes workflows you did not select and calls behind a false condition. A workflow that calls itself is a cycle. A named workflow may call default.

The called workflow resolves settings the same way goodflows run <workflow> does: [settings], then its own workflow settings, then the --env profile and the CLI flags. It does not inherit settings that exist only on the caller. The root parallelism limit counts command and step jobs in the caller and in every workflow it calls. A called workflow can set a lower limit for its own jobs. A call that is waiting does not use a slot.

When the run includes a call, live lines prefix the job with the workflow name and the first eight characters of that run's id. A called run's report names the call job and the parent run id. The root report is last. It is the only report with a rerun line.

Call-aware JSON events carry invocation_id, parent_run_id, caller_job, and child_run_id. The tests in tests/workflows.rs pin fail-fast, cancellation, log paths, and history records for calls.

Conditional jobs

[[jobs]]
name = "integration"
condition = { expression = '(env.RUN_INTEGRATION ?? "0") == "1"' }
command = "cargo test --test integration"

[[jobs]]
name = "web-tests"
condition = { shell = "test -f package.json" }
command = "npm test"

goodflows checks a condition after the job's dependencies pass. An expression must evaluate to a boolean. false skips the job with condition expression was false. A non-boolean result fails the job. There is no implicit truthiness, so the string "false" is not a boolean. A shell condition that exits nonzero skips the job. A skip does not fail the run. goodflows also skips the jobs that depend on a skipped job.

Expressions can read env.NAME, needs.JOB.outputs.KEY for a job listed in depends_on, and steps.ID.outputs.KEY in a later step of the same job. ?? replaces an unset value. Operators are !, <, <=, >, >=, ==, !=, &&, ||, and parentheses. && and || evaluate the right side only when the left side does not decide the result.

Steps and outputs

A job has a command or a nonempty steps list, not both. Steps run in order in one parallelism slot, under the job's timeout_secs.

A command publishes outputs by writing one JSON object to the path in GOODFLOWS_OUTPUT. The file must be at most 64 KiB. Each value must be a boolean, a number, or a string. An empty file publishes nothing. A command job must not set outputs. The JSON object's keys are that job's outputs.

A step job publishes only the keys in its outputs map. The map's values are expressions, usually steps.ID.outputs.KEY. Step outputs stay inside the job until that map promotes them. Partitioned jobs cannot publish job outputs. Resolved secret values in output keys, strings and numbers are replaced with [redacted] (see Secrets); nothing else is redacted.

[[jobs]]
name = "detect"
outputs = { backend_changed = "steps.scan.outputs.backend_changed" }

[[jobs.steps]]
id = "scan"
command = '''
changed=false
if test -d src; then changed=true; fi
printf '{"backend_changed":%s}\n' "$changed" > "$GOODFLOWS_OUTPUT"
'''

[[jobs]]
name = "backend-tests"
depends_on = ["detect"]
condition = { expression = "needs.detect.outputs.backend_changed" }
command = "cargo test"

backend_changed is a JSON boolean here. The condition reads that boolean.

Partitioned jobs

[settings]
parallelism = 6

[[jobs]]
name = "test"
command = "MIX_TEST_PARTITION=$GOODFLOWS_PARTITION mix test --partitions $GOODFLOWS_PARTITION_COUNT"
partitions = 3

partitions is an integer from 1 to 64, or { count = N, strategy = "index" }. index is the only strategy. goodflows starts one instance per count. Each instance has its own slot, timeout, and logs. GOODFLOWS_PARTITION is 1-based. The command has to split the work. Dependents wait until every instance has passed.

Environment profiles

A profile changes settings, and the partition count of jobs that are already partitioned, when you pass --env NAME. goodflows never selects a profile on its own. The profile name is not a workflow name. goodflows --env ci does not run a workflow named ci.

[settings.env]
MIX_ENV = "test"

[environments.local.settings]
parallelism = 8

[environments.local.partitions]
test = 6

[environments.orb.settings]
parallelism = 4

[environments.ci.settings]
fail_fast = false
history = true

[environments.ci.settings.env]
CI = "true"

[[jobs]]
name = "test"
command = "MIX_TEST_PARTITION=$GOODFLOWS_PARTITION mix test --partitions $GOODFLOWS_PARTITION_COUNT"
partitions = 3
goodflows --env local
goodflows run --env orb
goodflows --env ci --parallelism 2

Those three commands match the file above, which has a default workflow and no workflow named ci. A workflow name and a profile name are separate. On a file that has a release workflow, goodflows run release --env ci runs that workflow with the ci profile.

test = 6 replaces the declared count of every partitioned job named test. A reachable workflow that has an unpartitioned job named test makes that --env fail before any job starts, including a call hidden by a false condition. A name the workflow does not use is ignored.

Settings precedence is CLI flags, then the profile, then the workflow, then [settings], then the built-in defaults. The same order merges env by key. CLI flags do not include an env map. A profile's settings take the same fields as a workflow's. env values are literal strings with no interpolation, and an empty string sets the variable to empty.

Secrets

A job can get a credential from 1Password instead of the caller's environment. Settings map an environment variable name to a secret reference, and each job lists the names it needs:

[settings.secrets]
DATABASE_URL = "op://dev/postgres/url"

[environments.ci.settings.secrets]
DATABASE_URL = "op://ci/postgres/url"

[[jobs]]
name = "integration"
command = "cargo test --test db"
secrets = ["DATABASE_URL"]

A reference is a URI, and its scheme picks the provider. Only op:// is supported: op://vault/item/field or op://vault/item/section/field, optionally followed by a query such as ?attribute=otp, at most 1,024 bytes, with no whitespace. Any other value, such as 0p://... or a pasted password, fails validate with config_invalid.

secrets merges by key like env: [settings], then the workflow's settings.secrets, then the selected profile's. A profile can only point an existing name at another reference; it cannot add a name. A name follows the env rules and cannot be a goodflows variable, the reporting url_env or token_env, or the [cache] token_env. One settings table cannot set a name in both env and secrets, and a job's or step's env cannot set a name the job lists. A job that lists a name no settings define fails validation. Call jobs reject secrets.

Only the jobs that list a secret receive it, in their command and every step. It replaces a caller or env variable of the same name. Conditions, expressions, cache keys and other jobs never see the value; env.DATABASE_URL in an expression reads the caller's environment as before.

Secrets are opt-in and lazy. Before the first job starts, goodflows reads each distinct reference that a selected job, or a job of a workflow it calls, lists, once per run, with op read --no-newline. The first read runs alone (up to 120 seconds, so the 1Password app can ask for approval once), the rest at most 8 at a time (30 seconds each). A job that a condition later skips still counts. A run whose selection lists no secret, such as goodflows --jobs fmt, never looks for op. validate and list check references but never read them; list shows each job's secret names.

You need the 1Password CLI on PATH, signed in through the desktop app integration or, in CI and detached runs, a service account (OP_SERVICE_ACCOUNT_TOKEN). op runs with the caller's environment, so OP_ACCOUNT and OP_CONNECT_* work too. A missing op, a failed read, a timeout, or a value that is not valid UTF-8 or contains NUL stops the run before any job starts with secret_unavailable (exit 1). The message names the variable, the reference and the first line of op's error, never a value.

goodflows replaces every resolved value with [redacted] in every job's stdout and stderr before it reaches the terminal, job_output events, log files, failure output in the summary, last, MCP results and report uploads, and in published job outputs and their errors (keys, strings, and numbers whose written text or parsed form contains a value, which become the string [redacted]; two keys that mask to the same text fail the job). A value split across reads or lines is still masked. Only the exact value is masked: base64, URL-encoded or partial forms, and files a job writes (report files, cache archives, build artifacts) are not. A value shorter than 4 bytes is delivered unmasked, with one warning that names the secret.

Sprite runs read secrets on the controller and send the values privately; the Sprite never runs op.

Caches

A job can declare caches: directories that goodflows restores before the job's command or first step, and saves after the job. A cache only makes a job faster. A failed restore or save prints a cache_warning, and the job runs as if the cache missed. It never changes a job's status or the exit code.

[[jobs]]
name = "dialyzer"
depends_on = ["versions"]
command = "mix dialyzer"

[[jobs.caches]]
name = "plts"
paths = ["priv/plts"]
key.files = ["**/mix.lock"]
key.values = ["needs.versions.outputs.otp", "needs.versions.outputs.elixir"]
fallback = true      # default
save = "passed"      # or "always"
timeout_secs = 300   # default; bounds the restore and the save separately
  • name follows the job name rule and is unique within the job. Jobs that use the same name, values and files share entries, so a deps job and a test job can share _build.
  • paths are globs relative to the job's workdir that stay inside it, or directories under ~/ (the home directory of the user running the job), such as ~/.cargo/registry or ~/.npm. A ~/ path names one directory below home, and cannot be or contain .ssh, .aws or .gnupg. A restore follows your own symlinks under ~/, such as ~/.cargo pointing to another disk, and copies the cache onto that disk. In the workdir, a restore refuses a path whose parent directory is a symlink, because a checkout could plant one.
  • key.files are globs relative to the workdir. goodflows hashes the sorted matching paths and their contents. No match is not an error.
  • key.values and key.unique are expressions over env.* and needs.JOB.outputs.KEY, under the rules of job conditions. Each must be a scalar. A value that fails to evaluate makes that cache miss with a warning.
  • The operating system and CPU architecture are always part of the key. Other matrix dimensions, such as the Node or Rust version, belong in key.values. Change a value such as "'v2'" to start a cache over.
  • Caches work on command jobs, step jobs and partitioned jobs (each instance restores and saves on its own). Workflow-call jobs cannot declare them.

Keys, restores and saves

goodflows builds a partial digest from the format version, the cache name, the platform and key.values, and the key from the partial digest, the key.files digest and key.unique. After the job's condition passes, it checks the declared paths:

  • When every path exists, goodflows keeps the tree and looks nothing up. A key stamp in .goodflows/cache-stamps/ records which key the tree was built for. A matching stamp reports exact from workdir; anything else reports present.
  • When a path is missing, goodflows tries the exact key in the local store, then in the remote store, then (with fallback) the newest entry with the same partial digest, locally and then remotely. A restore replaces every declared path, and reports exact, fallback or miss.

After the job ends, goodflows saves a cache when it was not an exact hit, its key is not stored yet (exists otherwise), writes are enabled, and the job's status matches save: passed, or with "always" also failed. A job that timed out, was cancelled or was skipped never saves. The stamp is set to the key whenever the status matches save. Saves run in the job's slot after its status is final. Dependents can start meanwhile, and the run ends after every save. Jobs share the workdir, so a save archives only while no job of the run is executing, and archives again when one started meanwhile. While it waits it frees its slot, so other jobs can start, and it takes a slot back to archive. The wait does not count against the cache's timeout_secs; the archive attempts share it. In a called workflow, the call job ends once the child's jobs have results, so its dependents start while the child's saves finish; the child's summary still lists them and comes before the caller's. Ctrl-C or SIGTERM abandons restores and saves at once: a restore counts as a miss and the job is cancelled. Restore and save time does not count against the job's timeout_secs. A restore or save that runs past the cache's own timeout_secs is abandoned with a cache_warning: the restore counts as a miss and leaves no partial path, and the save is skipped. An archive larger than 5,000,000,000 bytes compressed is not saved (too_large). Archives are staged on disk and uploaded by streaming the file, so a large cache needs that much free disk space, not memory. With local = false, a save needs the remote store; when it is unavailable, each save is skipped with reason error and one cache_warning names the cause.

Steps and outputs can read caches.NAME.hit, true for an exact restore or a matching stamp:

[[jobs]]
name = "test"
steps = [
  { id = "deps", command = "mix deps.get", condition = { expression = "!caches.deps.hit" } },
  { id = "test", command = "mix test" },
]

[[jobs.caches]]
name = "deps"
paths = ["deps", "_build"]
key.files = ["mix.lock"]

The job's own condition cannot read caches.*, because it runs before the restore.

A rolling cache saves a new entry for every commit and restores the previous one as a fallback:

[[jobs.caches]]
name = "ccache"
paths = ["~/.cache/ccache"]
key.unique = ["env.GITHUB_SHA"]

More examples:

# Elixir: Dialyzer PLTs
[[jobs.caches]]
name = "plts"
paths = ["priv/plts"]
key.files = [".tool-versions", "mix.lock"]

# Cargo
[[jobs.caches]]
name = "cargo"
paths = ["~/.cargo/registry", "~/.cargo/git", "target"]
key.files = ["Cargo.lock", "rust-toolchain.toml"]

# npm
[[jobs.caches]]
name = "npm"
paths = ["~/.npm"]
key.files = ["package-lock.json"]

Archives are not scanned for secrets: a declared directory that holds a token is saved with it. Some tools record absolute paths in their output (Cargo's target/, possibly PLTs), so a restore into a checkout or toolchain at another path can still rebuild. Install toolchains at the same path everywhere, or put the install path in key.values. While a job runs, its cached paths belong to goodflows, like any build directory.

Stores and settings

Every run has a local store at $XDG_CACHE_HOME/goodflows/ (~/.cache/goodflows/, or ~/Library/Caches/goodflows/ on macOS), private to the user. All checkouts and worktrees with the same Git remote URL share one store. Without a remote, the repository path identifies the store, and outside Git the config file's directory does. On a Sprite the store is $GOODFLOWS_SPRITE_STATE_DIR/caches. Least recently used entries are deleted once the store passes local_bytes.

[cache]                              # optional
remote = "goodflows"                 # use the [reporting] server as a shared store
token_env = "GOODFLOWS_CACHE_KEY"    # default; the reporting key when unset or empty
scope = "env.GITHUB_HEAD_REF ?? env.GITHUB_REF_NAME"  # default: the Git branch
write = true                         # false: restore only
local = true                         # false: no local store
local_bytes = 5_368_709_120          # default 5 GiB

[environments.pr.cache]
write = false

Workflows ([workflows.NAME.cache]) and profiles ([environments.NAME.cache]) can override write, local and local_bytes, with the precedence of other settings.

The remote store needs a [reporting] block and uses its project and url_env. Like the API key, the variable named by [cache] token_env is removed from every command and expression, so jobs never receive the cache key. Entries are scoped by branch. The scope is the Git branch, or [cache] scope, an expression over env.* for detached checkouts. A scope that evaluates to null or an empty string falls back to the Git branch. In GitHub Actions, GITHUB_HEAD_REF names a pull request's branch and is empty on pushes, which then use the Git branch:

- run: goodflows --env ci
  env:
    GOODFLOWS_URL: ${{ vars.GOODFLOWS_URL }}
    GOODFLOWS_CACHE_KEY: ${{ secrets.GOODFLOWS_CACHE_KEY }}

A run reads its own scope and then the default branch's. A run without a scope (a detached HEAD with no scope) reads only the default branch and saves only locally (no_scope). The server's key decides what a run may write: a read-only ck_ key makes remote saves read_only after one warning, and a key bound to another branch reads only the default branch. Use a long-lived read-only ck_ key bound to the default branch on laptops and orbs, and let CI on the default branch write. Without a key or URL the run uses only the local store (cache_remote_unavailable). Sprite runs get a short-lived key from the controller; see docs/sprites.md.

An archive of at least 64 MiB downloads as parallel 16 MiB ranges and, when the server supports it, uploads as parallel 16 MiB parts, up to 8 at a time, each tried up to 3 times with a short wait between tries. Each part carries its MD5, which the object store checks. A server or store without multipart support gets the archive as one upload instead, as do smaller archives; a server that refuses the parts outright also prints one cache_warning per run. A part that still fails ends the remote save with a cache_warning and no commit; the local entry stays. Every restore from the remote store checks the archive's size and sha256 before it extracts anything; a mismatch is a cache_warning and a miss.

Cache events

  • cache_restored: job, partition, cache, result (exact, fallback, present or miss), tier (local, remote, workdir or null), bytes, duration_ms.
  • cache_saved with tiers, or cache_save_skipped with reason (hit, exists, not_passed, read_only, no_scope, too_large, quota or error).
  • cache_warning with message, and cache_remote_unavailable with reason.

Text mode prints one line per cache, such as dialyzer cache plts: restored (exact, local, 182 MiB, 3.1s). The summary and the local run history file list each job's cache results. Uploaded run records do not carry them yet. goodflows list shows each job's caches with their paths and key inputs.

Text and JSON output

--output picks how much a run prints in text mode. --output=failures prints one status line per job and no job output while the run goes. --output=stream also prints step lines, and writes each output chunk as [job stream] followed by the chunk. stream is stdout or stderr. A step is [job/step stream]. Without the flag, a run uses failures when stdout is not a terminal, such as when it is piped to a file, or when a coding agent variable is set (CLAUDECODE, CODEX_* other than CODEX_HOME, AGENT, AI_AGENT, CURSOR_AGENT, GEMINI_CLI, or OPENCODE). Otherwise it uses stream. --json ignores --output.

The run ends with a report: one row per job, then counts, then a Failures section when something failed or timed out. In both modes each Failures entry shows the instance's output and the paths of its log files when --log-dir is set. Short output is shown whole, in a stdout: and a stderr: block. Longer output is one stdout and stderr: block in the order goodflows read it: the first 4 KiB, a … N bytes omitted … line, then the last 4 KiB, with the log paths under it. The last line of a failed root run is Rerun failed: and a goodflows run command for the failed jobs and the jobs skipped because a dependency did not pass.

--json prints JSON Lines on stdout. Every event has schema_version 1. The last event of a finished run has "type":"summary". Its success field is true when every selected job passed or was skipped. --json=summary leaves out the events in between, such as one job_output event per output chunk. A run then prints only run_started, any error event, the cache events (see Caches), and the summary, plus sprite_unresolved when a Sprite run cannot report one. Other commands print the same events as with --json. Commands that only report a result, such as init, skills install, last, and status, take a plain --json with no value.

Each failed or timed-out job in the summary has:

  • output_head and output_tail: the first and last 4 KiB of its stdout and stderr together, in the order goodflows read them. output_truncated is true when output between them was left out, and output_omitted_bytes is how many bytes were.
  • stdout_tail and stderr_tail: the last 4 KiB of each stream. stdout_truncated and stderr_truncated say whether earlier output was left out.

With --log-dir, each job that ran has stdout_log and stderr_log, the paths of its log files. A failed root run's summary has rerun_command, the command on the report's Rerun failed: line, or on its Rerun workflow: line when a job name contains a comma.

goodflows --json=summary > results.jsonl
goodflows --json > events.jsonl
goodflows validate --json
goodflows list --json

--log-dir .goodflows-logs stores raw stdout and stderr for each run in a new directory under that path. log_runs (default 10) is how many of those directories to keep per workflow. Output is stored raw, except that resolved secrets are replaced with [redacted]. Add the directory to .gitignore.

goodflows --log-dir .goodflows-logs --log-runs 5

Last run and rerunning failures

Every local run replaces one record of its results at .goodflows/last/<config file name>.json, next to the config file. It is written whether or not history is on. It keeps each invocation's summary, including the output tails of failed jobs and the --log-dir path. When .goodflows/ has no .gitignore, goodflows writes one containing *, so git ignores the directory. It leaves an existing one as it is.

goodflows last
goodflows last --json
goodflows run --failed

goodflows last prints the last run's report again without running anything: each job's status, the Failures section with the command, error, log file paths, and output tails, and the Rerun failed: hint. A run that called workflows shows each called workflow's report before the root's, as the run did. With --json, it emits the run's summary events unchanged. It exits with the run's exit code: 0 when it passed, 1 when a job failed or timed out, and 130 or 143 when a signal stopped it. The log files exist only if that run used --log-dir, and only until log_runs prunes them.

goodflows run --failed reruns the jobs that the last run's Rerun failed: hint names, plus the jobs they depend on. Those are the failed and timed-out jobs and the jobs skipped because a dependency did not pass. It uses the last run's workflow and --env. A workflow or --env given with --failed must match the last run's. --failed rejects --jobs and --sprite. Other run flags, such as --log-dir and --history, apply as usual. A job whose name contains a comma is rerun too, though the hint cannot select it.

When there is no record, both commands exit 2 with no_last_run. run --failed exits 2 with no_failed_jobs when the last run has nothing to rerun. A run that stops before its summary, such as one with a config error, leaves the previous record in place. run --sprite writes no record.

Detached runs

Coding agents often stop a shell command after a couple of minutes, and a full run can take longer. goodflows run --detach starts the run in the background and returns at once. It prints the run id on stdout. With --json or --json=summary, it prints one run_detached event with run_id, pid, and run_dir. The background run always records every event, so status can show its progress. The run id is the run_id of the run's root summary.

id=$(goodflows run --detach)
goodflows status "$id"
goodflows wait "$id" --timeout 90
goodflows cancel "$id"

--detach checks the command line and the config first, so usage and config errors still exit 2 before anything starts. It takes the same run flags as a foreground run, except --sprite.

goodflows status <run_id> prints the run's state and which jobs are running, passed, failed, timed out, skipped, or cancelled. With --json it prints one run_status event with state (running, finished, or lost), exit_code once finished, and a list of job names for each status. lost means the background process died without a result, for example from SIGKILL. status exits 0 whenever it can report.

goodflows wait <run_id> --timeout <secs> blocks until the run finishes. It then prints the run's report, or its summary events with --json, exactly as the foreground run would have, and exits with the run's exit code. If the timeout passes first, it prints the same progress as status and exits 75. Call wait again until the exit code is not 75. Without --timeout it waits as long as the run takes. A lost run exits 1. Stopping wait does not stop the run.

goodflows cancel <run_id> stops a running detached run. It sends the run SIGTERM, which cancels its running and waiting jobs as Ctrl-C would, waits for the run to record its result, then prints the same report as status and exits 0. The run's own exit code is then 143. A run that had already stopped is reported as it is, also with exit 0. With --json the run_status event adds was_running, true when cancel stopped the run. If the run is still stopping after 30 seconds, cancel prints its progress and exits 75.

status, wait, and cancel find the run beside the config, so pass the same --config the run used. Each detached run keeps its events, stderr, record, and exit code in .goodflows/runs/<run_id>/ next to the config file. Starting a detached run removes the oldest finished runs of the same config file, keeping the newest 10, the new one included. A run that is still going is never removed. A detached run also replaces the last run record when it finishes.

Run history

history = true, or --history, writes one JSON file per run under goodflows-history/<workflow>/ next to the config file. history_dir in the config is relative to the config file. --history-dir DIR is relative to the current directory, and it turns history on. --no-history turns the file off for that run. The file has timing, queue wait, CPU, peak memory, and host details for each job. It has command text. It has no output and no environment values. --history-runs N (default 1000) and --history-bytes N (default 10485760) cap what is kept per workflow.

goodflows --history
goodflows --history-dir /tmp/goodflows-history --history-runs 100 --history-bytes 1048576

Turn history on where the machine stays comparable from run to run, such as the ci profile above. A clean-tree check that runs after goodflows will see the new file. To commit the files, mark them generated:

goodflows-history/** text eol=lf linguist-generated

Or add goodflows-history/ to .gitignore. src/history.rs defines the record layout.

Linking runs to threads and tickets

A run's history file and its uploaded record carry a links object: the agent threads and the tickets behind the change the run tests. Every invocation of a run, including each called workflow, records the same links. Each list is left out when it is empty, and links is left out when both are.

"links": {
  "threads": ["https://ampcode.com/threads/T-3bb6cad7-8c04-413a-b23c-5fca67cd4f7b"],
  "tickets": ["GOO-291"]
}

goodflows collects links once per run, and only when a history file is written or a run record is sent. It merges four sources in this order, keeps the first spelling of a duplicate, and stops at 32 entries per list:

  1. --ticket ID and --thread-url URL, each repeatable up to 32 times. Give each flag on one side of the subcommand: all before it or all after it. An invalid value, a 33rd flag, or a flag on both sides exits 2 before any job runs.
  2. GOODFLOWS_TICKETS and GOODFLOWS_THREAD_URLS in the caller's environment, split on commas and whitespace. Settings and job env never supply them. An invalid entry is dropped with a warning that names its position, not its value.
  3. The agent session: AMP_CURRENT_THREAD_ID, or AMP_THREAD_ID, under AMP_URL (default https://ampcode.com).
  4. Git: every Amp-Thread-ID: line in the messages of the branch's own commits, at most 200 since origin/$GITHUB_BASE_REF or origin/HEAD, or of HEAD alone on the base branch or in a shallow checkout. Tickets come from those commits' subjects, the branch name, and GITHUB_HEAD_REF, never from commit bodies.

A ticket is 1 to 64 bytes of printable ASCII with no whitespace or commas, compared ignoring case. A thread URL is https with no userinfo, query, or fragment, and is stored in normalized form: a lowercase host, no :443, and no . or .. segments.

Git supplies tickets only for the prefixes in ticket_prefixes, set in the top-level [settings] only. Each prefix is 1 to 16 ASCII letters or digits, starting with a letter. A match is the prefix in any case, -, and digits, with no letter or digit next to it, so tbrewer/goo-291-fix gives GOO-291. Without ticket_prefixes, git supplies no tickets, because a general pattern would match UTF-8 and SHA-256.

[settings]
ticket_prefixes = ["GOO"]

On GitHub Actions a pull request's default checkout is shallow, so goodflows reads only GitHub's merge commit, which has no thread lines. Check out with fetch-depth: 0 to link the threads of every PR commit. GitHub's default squash message copies each commit's message into the squash commit's body, so a run on main after a squash merge still finds the thread lines. A repository that trims squash messages to the title loses them, and its main runs record only the ticket in the title.

Committed history files will contain thread URLs. The same URLs are already in those commits' messages, but a run started in an agent session that never committed adds its own.

Uploading run history

history = true inside the [reporting] block uploads a run record to the GoodFlows server for every invocation: the root run and each called workflow, each under its own run id. No job has to list reports. The default is false.

[reporting]
project = "my-project"
history = true

The upload and the local file are separate settings. The history setting in [settings], a workflow, or a profile, and --history, --no-history, and --history-dir, control only the file. A run with --no-history writes no file and still uploads.

The record holds the same fields the history file would hold: outcome, timings, host, source.commit and dirty, links, and for each job its command text, exit code, and error. It adds three keys that the file never has:

  • source.branch, when git reports a branch. A detached checkout, such as a GitHub Actions pull request, has none.
  • ci, when the caller's environment has GITHUB_ACTIONS=true. It is built from GITHUB_EVENT_NAME, GITHUB_RUN_ID, GITHUB_RUN_ATTEMPT, GITHUB_REF, RUNNER_NAME, GITHUB_SERVER_URL, and GITHUB_REPOSITORY. A value that fails its rule is left out. Settings and job env never supply these values.
  • graph, the job graph that graph_sha256 hashes. It lists every selected job with its command, step commands, and condition text, each cut to 1,024 bytes. That includes jobs that were skipped or never started, so the server receives command text for jobs that did not run. A workflow-call job names its target and the target's hash. The target's jobs are in the called workflow's own record.

The key and URL variables must be set when the run starts. When either is unset, the run prints run history for <workflow> upload skipped: credentials unavailable, keeps nothing, and sends nothing. Leave the key unset on machines that should not upload, such as laptops. A URL that is not a valid endpoint gives invalid url instead. goodflows does not send a record that breaks the server's rules, such as a job name longer than 64 bytes. The line then ends upload skipped: invalid record at <path>, where <path> is a field path such as results[3].name.

The upload runs after the test reports, before the final report, and uses what is left of the same 30-second budget. It never changes the exit code. A record that was not stored stays in the spool, and reports upload sends it again. That includes a record refused with HTTP 422 by a server that does not accept it yet.

history list and history show read stored runs with the same [reporting] project, URL, and key. Text the server redacts for a pk_ key, such as commands and errors, prints as -. A pk_ key also gets thread URLs redacted, so show prints one thread - row, while tickets stay visible.

goodflows history list
goodflows history list --workflow ci --branch main
goodflows history list --outcome failed --limit 20 --json
goodflows history list --ticket GOO-291
goodflows history show <run-id>

list prints one row per run, newest first: start, outcome, workflow, environment, commit (12 characters, * when dirty), branch, CI event, duration, and run id. When there is another page it ends with next: --cursor <cursor>. The filters are --workflow, --environment, --outcome (passed, failed, or cancelled), --commit (a full hash), --branch, --event, --graph-sha256, --ticket, --thread-url, --limit (1 to 200), and --cursor. --ticket matches a linked ticket ignoring case, and --thread-url a linked thread URL after normalizing it; each takes one value, given only once on the command line, and a pk_ key can use both. --branch and --event match source.branch and ci.event exactly. A run uploaded without a branch or CI context prints - in the BRANCH or EVENT column and does not match those filters. show prints the run's fields, its tickets and thread rows after ci, one row per result, and its linked test reports. A bad filter or run id exits 2 without a request. A missing [reporting] block, key, or URL, a server error, or an unknown run exits 1. --json prints one history_runs or history_run event. The commands reject run flags such as --env, --jobs, and the history file flags, and exit 2.

Run link examples

These examples assume ticket_prefixes = ["GOO"] in [settings], and a run that writes a history file or uploads a record. A run that does neither collects no links.

An agent checks its own work. An Amp agent on the branch tbrewer/goo-291-run-links runs:

goodflows --history

The history file links the agent's thread, read from AMP_CURRENT_THREAD_ID, and GOO-291, read from the branch name. The agent passes no link flags.

A person links a run to tickets. Pass the tickets when the branch name has none, or when one run covers two tickets:

goodflows run ci --ticket GOO-305 --ticket GOO-306

A script passes links in the environment. A ticket automation, or a parent agent that started the run, can set the variables instead of building flags:

GOODFLOWS_TICKETS="GOO-291 GOO-302" \
GOODFLOWS_THREAD_URLS="https://ampcode.com/threads/T-3bb6cad7-8c04-413a-b23c-5fca67cd4f7b" \
goodflows run ci

goodflows drops an invalid entry and its warning names only the position, so a URL with a ?token= query never reaches the log.

A pull request links every agent thread. Check out the full history so goodflows reads each commit in the pull request:

- uses: actions/checkout@v6
  with:
    fetch-depth: 0
- run: goodflows run ci

Each Amp-Thread-ID: line in the pull request's commits adds a thread, and GITHUB_HEAD_REF adds the ticket in the branch name. With history = true in [reporting], the uploaded record carries both. After a squash merge, the run on main finds the same thread lines in the squash commit's body.

A Sprite run carries the caller's links. The controller collects links from its own checkout and agent session, and the remote history file records them:

goodflows run ci --sprite "$THREAD_ID" --ticket GOO-291

Find the runs behind a ticket or a thread. These commands read uploaded runs:

goodflows history list --ticket GOO-291
goodflows history list --ticket goo-291 --outcome failed
goodflows history list --thread-url https://ampcode.com/threads/T-3bb6cad7-8c04-413a-b23c-5fca67cd4f7b
goodflows history show <run-id>

--ticket ignores case, so both spellings match GOO-291. show prints the run's tickets row and one thread row per linked thread.

Test timing reports

goodflows can collect test-timings/1 JSON Lines and upload them to a GoodFlows server. goodflows uploads nothing unless you add [reporting] and a job lists reports, or the block sets history = true.

[reporting]
project = "my-project"
url_env = "GOODFLOWS_URL"
token_env = "GOODFLOWS_API_KEY"

[[jobs]]
name = "test"
command = "mix test"
reports = ["test-timings"]

project is an existing project slug. url_env and token_env default to GOODFLOWS_URL and GOODFLOWS_API_KEY. Put the server origin and the API key in those variables. Do not write the URL or the key into the file. Jobs never receive the API key. They write *.jsonl files in GOODFLOWS_REPORT_DIR.

GOODFLOWS_URL=https://flows.example.com GOODFLOWS_API_KEY=secret goodflows

An upload failure does not change the run's exit code. Snapshots that did not upload stay in .goodflows/reports/<run-id>/, which contains manifest.json. Git ignores .goodflows/ through the .gitignore goodflows writes there. Retry with the run directory:

goodflows reports upload .goodflows/reports/<run-id>
goodflows reports upload .goodflows/reports/<run-id> --budget 120

--budget is the publishing time limit in seconds, from 1 to 3600. The default is 30.

With [reporting] history = true, and the key and URL set, goodflows creates each invocation's run directory even when no job lists reports. It holds run-record.json, the exact run record to send, and the manifest is version 3. Without a run record the manifest is version 1, or version 2 when a job is partitioned. reports upload sends the reports first, then the run record within the same budget. When the server stores the record, it writes run-record.ack.json and later replays send nothing for it. HTTP 400, 409, and 415 write run-record.rejected.json, and goodflows does not send the record again. HTTP 413 and 422 leave it pending, so the next reports upload sends it again. reports upload exits nonzero while the record is pending, rejected, or invalid, and its text output ends with Run history: acknowledged, pending, rejected, or invalid. A tampered, missing, or symlinked run-record.json, or one whose run id, workflow, or environment differs from the manifest, counts as invalid. Older goodflows releases refuse a version 3 manifest as an unsupported version.

src/reporting/contract.rs defines the wire format. Each reporter's README covers its setup and behavior: ExUnit and Jest.

Each reporter has its own version. Pin a tag. Every release writes test-timings/1, which goodflows v0.6.0 and later accept. v0.6.0 is the tag in this repository.

ExUnit (Elixir 1.18 or newer), from agoodway/goodflows-exunit-reporter:

# mix.exs
{:goodflows_exunit_reporter,
 github: "agoodway/goodflows-exunit-reporter", tag: "v0.6.0", only: :test}
# test/test_helper.exs
ExUnit.start()
Goodflows.ExUnitReporter.configure()

Jest (Jest 29.6 or newer, Node.js 18 or newer), from agoodway/goodflows-jest-reporter:

// package.json devDependencies:
//   "goodflows-jest-reporter": "github:agoodway/goodflows-jest-reporter#v0.6.0"
// jest.config.js
module.exports = { reporters: ['default', 'goodflows-jest-reporter'] };

Other runners can write test-timings/1 themselves. The suite id for the ExUnit reporter is the :test_timing_suite_id option, or TEST_TIMING_SUITE_ID.

Change requests

A GoodFlows server can hold change requests in place of pull requests. The server stores the facts and claims a client reports for each head, the QA scenario sets and verify runs that grade it, and the project's review policy, and computes a verdict: pending, blocked, needs_review, or mergeable, with one reason per rule that fired. It never talks to the Git host. These commands report facts from the local checkout and read results back with the same [reporting] project, URL, and key as history. Writes need an sk_ key.

A change request's description is its claims file, a change-claims/2 Markdown file that the goodstack gs-change-request skill writes to goodflows cr path (.goodflows/change-requests/<branch>/cr.md, or .goodflows/change-requests/.detached/<short SHA>/cr.md on a detached HEAD):

  • goodflows cr open [--claims <file>] creates one while the file's cr is null. It reuses the one draft or open change request whose source branch is the current branch, or opens a draft. When the claims file exists, it reports git-facts/1 for HEAD, writes the number into the file's cr, and uploads the claims. Without the file it needs --title, and --openspec-change <id> links the OpenSpec change, so its intent scenario set can be approved before code.
  • goodflows cr claims [<file>] updates it once cr is set: it reports Git facts for HEAD, then uploads the claims. Claims describe one head, so the file's head must be HEAD.

Before computing Git facts, cr open, cr claims, cr push, and cr lease acquire without --base run git fetch --quiet origin <target> when the checkout has an origin remote, so the merge base is the one the target branch has now; --no-fetch skips it. The server keeps one report per head and target branch: facts for the same head with a different merge base are refused, so make a new commit (or retarget) and report again. Claims are fixed per head in the same way.

goodflows cr open --openspec-change add-login --title "Add login"
goodflows cr scenarios upload openspec/changes/add-login/qa-scenarios.md
goodflows cr scenarios approve
goodflows cr push -- -u origin HEAD        # git push, then report Git facts for the new head
goodflows cr runs upload .verify/web/<run-id>
goodflows cr open                          # gs-change-request wrote the claims file
goodflows cr ready
goodflows cr wait --until mergeable,needs_review
goodflows cr review                        # what the policy flagged, as Markdown

Without OpenSpec, a change request links no change and is graded on its diff set alone. The diff set's default file is qa-scenarios.md next to the claims file (goodflows cr path --json prints it as scenarios_path). Its revision names the commit it covers, so write and upload it again after each code push. With the policy's scenarios.diff_only set to weakening, a person is asked only when a version removes or demotes a Must of its baseline: the newest accepted diff version, or v1. The person accepts the version by answering approve on each diff_set_weakened item:

goodflows cr open                          # no --openspec-change
goodflows cr scenarios upload              # .goodflows/change-requests/<branch>/qa-scenarios.md
goodflows cr runs upload .verify/web/<run-id>
goodflows cr scenarios diff --source diff  # the current diff version against its baseline
goodflows cr review                        # diff_set_weakened items, with their answer commands
goodflows cr scenarios list --source diff  # versions marked current, accepted and baseline

Commands find the change request of the current branch unless given --number. The others are cr status, cr verdict, cr draft, cr close, cr reopen, cr scenarios list, reject and diff, cr answer, cr tasks, cr merged, cr retarget, cr parent, cr lease acquire|heartbeat|release, and cr defect; policy get|set|history|calibration read and write the review policy as TOML; features sync uploads the verify skill's feature files that have paths globs; and events reads the project's event feed after an event id cursor (--after <id>), with --follow to keep reading. Events are kept 90 days; when the events after a cursor were deleted, --follow continues from the server's latest_cursor and notes that events were skipped, and a single read fails naming it. cr wait --until <states> exits 0 once the verdict is one of them, and 75 when --timeout passes first. cr defect takes --number or --commit, and optionally --ticket and --severity (low, medium, high, or critical). policy calibration [--from <time>] [--to <time>] prints the window, one line per lane with its defect rate, the counts by policy version, rule and path glob, then one line per defect, newest first: when it was recorded, its change request, severity, ticket, lane, policy version, the rules that fired and the globs it matched. Servers without the defect list print the counts alone. Each command's --help has examples, and --json prints its result as one JSON event.

cr scenarios upload sends the set file byte for byte, because the approved digest covers its raw bytes, with a digest per scenario section: under ## Scenarios, from a scenario's ### <id>. heading (#### <id>. under a group heading) to the next heading at that level or higher. It refuses a diff set whose revision ends +dirty. cr runs upload reads a run folder's scenarios.md, whose SHA-256 is the graded set's digest, and the verify-run-notes/1 YAML front matter of its run.md: format, commit, branch, dirty, started_at, finished_at, and results (id, result, failed_step, reason, and evidence paths in the folder), and optionally set (path, sha256, which must match scenarios.md), changed_files, features, drift, run_id, merge_result, links, and workflow_run_id. It uploads each evidence file to the URL the server returns, then commits the run, retrying up to 5 times while the server answers 503 (waiting its retry-after, at most 10 seconds). policy set without --previous-version writes nothing when the current version already has the same document and note.

cr validate [<path>...] checks claims files, scenario sets and run folders the way cr open, cr claims, cr scenarios upload and cr runs upload read them, and lists every problem in each file, so an agent can fix them all at once. Without paths it checks the branch's claims file and diff set, each openspec/changes/*/qa-scenarios.md, and each .verify/<app>/<run-id>/ run folder. Warnings name what an upload would refuse later, such as claims for a head other than HEAD or a +dirty diff set. features validate [--dir <dir>] checks feature files the way features sync reads them; features sync now also refuses two files with paths that share an id. Both validate commands need no API key or goodflows.toml, and exit 1 when a file has errors. The server checks more of a claims file than its format, cr and head, so a claims file that validates can still be refused on upload.

Sprites

goodflows run --sprite <identity> runs one workflow on a Sprite kept for that caller identity. The run sends a verified snapshot of the Git working tree that contains the config, runs your setup or resume command, then runs the same workflow with the same goodflows version. A run without --sprite stays on this machine and does not call the Sprite CLI. --env still selects a profile.

[settings]
sprite_prefix = "myapp"

[environments.ci.settings]
parallelism = 2

[sprite]
setup = "bash scripts/sprite-setup.sh"
resume = "bash scripts/sprite-resume.sh"
pass_env = ["DATABASE_URL"]

[[jobs]]
name = "test"
command = "cargo test --locked"

[[workflows.ci.jobs]]
name = "test"
command = "cargo test --locked"

sprite_prefix is 1 to 20 characters: lowercase ASCII letters, digits, or hyphens, starting with a letter or digit. Set it only in the top-level [settings]. [sprite] is top-level only. setup and resume are required for a remote run. They are nonempty shell commands. true is a deliberate no-op. goodflows does not look for .agents/setup and does not install toolchains for you. pass_env lists caller variables to forward. A name that is unset fails before anything remote runs. An empty value counts as set. The default is to forward nothing.

SPRITE_TOKEN, SPRITES_TOKEN, and the reporting API key stay on the controller. pass_env cannot name them. Declared caches live in the Sprite's state directory between runs. With a remote cache store, the controller mints a short-lived ck_ key for each run, so pass_env cannot name [cache] token_env either. Secrets are read on the controller and forwarded privately; setup and resume hooks never see them, and pass_env cannot name GOODFLOWS_SPRITE_SECRETS.

goodflows run --sprite "$THREAD_ID"
goodflows run ci --sprite "$THREAD_ID" --env ci --jobs test
goodflows sprite status "$THREAD_ID"
goodflows sprite logs "$THREAD_ID" --run <uuid>
goodflows sprite collect "$THREAD_ID" --run <uuid>
goodflows sprite cancel "$THREAD_ID" --run <uuid>
goodflows sprite destroy "$THREAD_ID" --yes

The identity is 1 to 256 UTF-8 bytes, case-sensitive, with no control characters. It is not the Sprite's name. The Sprite is named <sprite_prefix>- plus 32 hex characters derived from the prefix and the identity. --run is a lowercase canonical UUID.

status, logs, collect, cancel, and destroy accept --config and --json. They reject run flags such as --env, --jobs, --parallelism, --log-dir, and the history flags. destroy asks on a terminal. --yes skips the question, and a non-interactive caller must pass it. destroy refuses while a run is still active. collect writes a bundle under .goodflows/sprites/<scope-digest>/<run> in the current directory. The digest covers the organization, prefix, and identity. --output DIR uses that directory instead, relative to the current directory.

You need the Sprite CLI on PATH, a Git repository, and an organization (SPRITE_ORG, or the current org from sprite org list). A controller that is not a matching Linux build downloads the checksummed Linux release archive for this exact version. What the snapshot includes, what it drops, and how recovery works are in docs/sprites.md. The same document covers ownership, preparation, exclusive use, and execution. Cold boot of a Sprite is not a supported recovery path.

examples/sprites/goodflows.toml is one remote config for this repository. Its setup and resume scripts live in scripts/.

Ampcode orbs

goodflows runs in Ampcode orbs. Install a release archive from .agents/setup, and tell the agent in AGENTS.md to run goodflows --json=summary before it finishes. docs/ampcode.md has the setup script, the snapshot step, and the Amp palette plugin.

Agent skills

create-ci-skill reads a repository's GoodFlows config and writes a project-local run-ci-<app> skill for the next agent. The generated skill runs those jobs with goodflows. It holds only what is specific to the repository: the workflows, the jobs, and which command to run for which scenario. For how the CLI reports a failure it points at goodflows agents. A repository with neither goodflows.toml nor .goodflows.toml gets no skill.

npx skills add agoodway/goodflows --skill create-ci-skill

maintain-ci-skill updates that run-ci-<app> skill when the GoodFlows config changes. It keeps the scenario answers already in the skill and asks again only about a new, renamed, or removed workflow. In a skill written by an older create-ci-skill, it replaces the exit codes, error codes, and JSON fields copied into it with the pointer to goodflows agents. It does not write a skill when none exists.

npx skills add agoodway/goodflows --skill maintain-ci-skill

goodflows skills install writes create-ci-skill and maintain-ci-skill into the directory the current coding agent loads project skills from, one directory per skill, such as .claude/skills/create-ci-skill/SKILL.md. The skills are built into the binary, so they match the goodflows you run. Rerunning replaces the installed copies with the built-in ones.

goodflows skills install
goodflows skills install --harness claude
--harness Directory Detected from
amp .agents/skills AGENT=amp, AI_AGENT=amp, or AMP_CURRENT_THREAD_ID
claude .claude/skills CLAUDECODE, or AI_AGENT starting with claude-code
codex .agents/skills any CODEX_* variable except CODEX_HOME
cursor .agents/skills CURSOR_AGENT
gemini .agents/skills GEMINI_CLI (Gemini CLI reads .agents/skills as an alias of .gemini/skills)
grok .grok/skills GROK_AGENT or GROK_SESSION_ID
opencode .agents/skills OPENCODE
t3 .agents/skills T3CODE_PROJECT_ROOT or T3CODE_WORKTREE_PATH

A variable counts only when it is set and not empty. --harness skips detection. With no harness detected, the skills go in .agents/skills. When the environment names harnesses that load different directories, such as CLAUDECODE together with AGENT=amp, the command writes nothing and exits 2 with ambiguous_harness; pass --harness. Harnesses that share a directory, such as T3 Code running Codex, are not ambiguous. With --json it prints one skills_installed event with directory, harnesses, source (flag, environment, or default), and files.

Agent guide

goodflows agents prints a guide for coding agents: the exit codes and error codes, how to read the report's Failures section, last, run --failed, detached runs, and the JSON events and fields. It is built into the binary, so it matches the goodflows that prints it. Generated run-ci-<app> skills point at it instead of copying those details.

goodflows agents

MCP server

goodflows mcp serves goodflows to a coding agent as a Model Context Protocol server over stdin and stdout. Register it with the harness, for example claude mcp add goodflows -- goodflows mcp, and start it from the project directory. Each tool runs this goodflows binary in the server's working directory, so it finds goodflows.toml or .goodflows.toml there unless the call or goodflows mcp --config PATH names a config.

Tool Parameters Returns
run workflow, config, env, jobs, failed, parallelism, fail_fast, detach Waits for the run. Whether it passed, its exit code and summary counts, and each job that did not pass. With detach, starts the run in the background and returns its run_detached event at once
wait run_id, config, timeout Waits up to timeout seconds (default 60) for a detached run. Once it finished, the same result as run. Before that, a line saying the run is still running and its run_status event. That is a normal result, not an error
status run_id, config A detached run's run_status event
cancel run_id, config Cancels a detached run, then returns its run_status event, as goodflows cancel does
last config The last local run, as goodflows last shows it, in the same form as run
validate workflow, config, env, jobs The config_valid event
list workflow, config, env, workflows The jobs or workflows event

run and last never return job output events. The result is a status line (GoodFlows checks passed. or GoodFlows checks failed (exit code N).), then the root summary without results, plus passed, exit_code, and error, and a results list of the jobs that did not pass with name, status, exit_code, command, and error. Jobs of called workflows that did not pass are in the list too, with called_run naming that run's workflow, run_id, caller_job, and parent_run_id. A last text block holds each of those jobs' stdout and stderr tails, at most 4 KiB per stream and less when many jobs failed. passed is true only when goodflows exited 0, reported no error, and every root job passed or was skipped. The limits match the Amp plugin's.

A client may stop a tool call that takes longer than its tool timeout. For a run that may take more than a minute or two, call run with detach: true, then call wait with the returned run_id and a short timeout until it returns the run's result. The server's instructions tell agents to do this. status, wait, and cancel take the config the run used.

When goodflows cannot do what a tool asks, such as for a config or usage error or an unknown run_id, the tool result is an error (isError) with the exit code and goodflows's message. Cancelling a call sends its goodflows process SIGTERM, which cancels a blocking run's jobs as Ctrl-C would. Cancelling a wait call does not stop the detached run; use cancel for that. goodflows mcp rejects --json and the run-only flags; pass them as tool parameters instead.

More docs

  • docs/install.md lists the release archives and covers checksums, glibc, and building from source.
  • docs/sprites.md explains remote runs on Sprites: snapshots, ownership, recovery, and collection.
  • docs/ampcode.md sets up goodflows in Ampcode orbs and installs the Amp palette plugin.
  • docs/development.md has the checks to run when you change goodflows, and the Cursor cloud agent environment.
  • docs/releasing.md has the release steps for the CLI and each reporter.

When this README and docs/ say nothing about a behavior, the code defines it and the tests in tests/ pin it.

About

A simple light weight CI

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages