DEV Community: Richard Shade

gh-aw-fleet 0.2: cost and risk, fleet-wide

Richard Shade — Mon, 06 Jul 2026 10:33:35 +0000

The launch post ended on a cliffhanger: "a consumption rollup is in flight." Five patch releases later (v0.2.1 through v0.2.5), it's shipped, and on the way. We found a second question the per-repo tools couldn't answer along the way.

the rollup, finished

gh-aw-fleet consumption reads AI-credit usage straight from gh aw logs --json and rolls it up however you want to slice it:

# fleet-wide spend for the trailing 30 days, by cost center
gh-aw-fleet consumption --trailing 30d --by cost-center

# flag anything over its budget before the invoice does
gh-aw-fleet consumption --budget 500

USD is derived at a fixed $0.01 per AI credit, so a number that used to mean clicking through every repo's Discussions is now one command. --by repo, --by profile, or --by workflow if cost-center isn't the axis you care about; pass a repo name to drill into just its spend. The --budget flag (v0.2.5) is the payoff: instead of eyeballing a table for anything that looks high, the tool tells you which repos crossed a line you set.

why does Renovate keep touching gh-aw's pins?

Cost was the fleet-wide question I went looking for. This one found me.

gh aw upgrade pins gh-aw-actions to an SHA coupled to the compiler version baked into each workflow's lock-file metadata. Renovate and Dependabot don't know that: a grep of the fleet's own history for renovate / packageRules / gh-aw-actions turned up nothing. The tool that manages every repo's pins had zero visibility into the other bots that also touch those files.

It wasn't hypothetical. While building the scanner, rshade/finfocus#1246 showed up live: a Dependabot PR bumping gh-aw-actions 0.77.4 → 0.78.3, rewriting 9+ .lock.yml files it doesn't own. Renovate can be told to leave *.lock.yml alone entirely via matchFileNames; Dependabot has no file-glob ignore, only dependency-name, so its fix is narrower by construction. Two advisory scanners (v0.2.3) now warn if a managed repo's renovate.json or dependabot.yml is missing the rule, and hand you the exact block to paste in.

saying so, three times

A scanner nobody reads is a scanner that didn't run. Findings from deploy/sync/upgrade now surface on three independent surfaces:

stderr, above the summary
an interactive y/N prompt before anything commits (skippable with --yes, which bypasses only the prompt)
a ## Security Findings section in the PR body itself, so a teammate reviewing the diff sees what you saw in your terminal

--strict escalates a HIGH finding from a warning to a hard stop before anything lands. It's opt-in, so a routine run still doesn't need a flag to stay dry-run-first.

smaller things

pkg/fleet is a public package now, and the CLI runs on ax-go's config primitives instead of its own copy, the tool eating its own dogfood.
install.sh / install.ps1 one-liners, so onboarding a new operator doesn't start with a Go toolchain.
a real docs site, rshade.github.io/gh-aw-fleet, on the same rshade-theme as everything else here.

where it's at

v0.2.5, still pre-1.0. Cost and risk turned out to be the same shape of problem: something every per-repo tool is blind to, and the one place with a view across the whole fleet is fleet.json.

ax-go 0.2 and 0.3: contracts worth pinning

Richard Shade — Fri, 03 Jul 2026 02:28:09 +0000

Two ax-go releases landed close together, and they're really one idea in two halves. v0.2.0 let you pin just the contract an agent depends on, without the runtime behind it. v0.3.0 is the work that keeps that contract from moving once you've pinned it.

If you're new here: ax-go is the agentic-experience foundation under my Go CLIs. stdout is data, traces cross the plugin boundary, every human table has a JSON twin. The contract is the whole point, so the contract is what both releases are about.

v0.2.0: import-isolated contract packages

Go imports are all-or-nothing. There's no tree-shaking: import a package, and you compile in its entire transitive dependency graph, whether you call into it or not.

So until v0.2.0, reusing any ax-go contract (the error envelope, the exit codes, the __schema shapes) meant importing the root ax package. And ax is the full runtime: the OpenTelemetry SDK, zerolog and Loki, HTTP and gRPC instrumentation. A thin orchestrator that only wanted to emit a well-formed error envelope was paying for a telemetry stack it never started.

v0.2.0 carves four narrow packages out of the root:

contract: exit codes, mode resolution, context metadata, the success/error envelope, the strict JSON/NDJSON writers.
config: bounded Hujson reads and comment-preserving RFC 6902 patches.
schema: the ax-native and MCP-compatible schema builders, plus the __schema command.
id: UUID v4 idempotency keys and UUID v7 entity IDs.

Each depends on the standard library and not much else: never on the root facade, never on a runtime adapter. So the import you reach for matches the weight you take on:

import "github.com/rshade/ax-go/contract"  // just the shapes
import ax "github.com/rshade/ax-go"          // the shapes plus the runtime

The root ax package still works unchanged. It becomes a thin facade that re-exports every moved type:

type Error = contract.Error

That's a type alias, not a new type, and the distinction does real work: ax.Error and contract.Error are the same type. So errors.As(err, *contract.Error) still matches an error built deep inside the runtime. Identity survives the split, and upgrading from v0.1.0 is a go get -u and nothing else.

The boundary is a test, not a promise. Each contract package ships an import-isolation test that runs go list -deps and fails the build if a forbidden runtime import (the root facade, the OTel SDK, Loki, the HTTP or gRPC instrumentation) shows up in its graph. CI enforces the isolation; I don't have to remember to.

v0.3.0: keeping the contract from drifting

Splitting the contract out is half the promise. The other half is that the shapes you pin don't move underneath you. v0.3.0 is the guardrails.

Coverage floors. Every contract package now has its own coverage floor enforced in CI, alongside a repo-wide one. The packages a thin consumer pins are exactly the packages that shouldn't quietly lose test coverage.

A compatibility matrix and a CONTRIBUTING guide. The README now spells out which Go versions and which ax-go versions are supported, so "can I depend on this" has a written answer instead of a guess. CONTRIBUTING documents how the contract surface is allowed to change, and how it isn't.

A gate on breaking changes. Public-API changes now run through go-apidiff in CI, so a breaking change to an exported contract can't merge without tripping a gate. The pin you depend on can't move by accident.

the docs site

Both releases ship against a real home now: rshade.github.io/ax-go, an Astro Starlight site built on the shared rshade-theme. Same tokens as finfocus, because they came from the same shop.

where it's at

Still pre-1.0, still pinnable. v0.2.0 let you pin just the contract; v0.3.0 is the work that keeps pinning it safe. An agent shouldn't have to compile a telemetry stack to read an exit code, and it shouldn't wake up to find the code moved underneath it either.

agentic experience for Go

Richard Shade — Sat, 20 Jun 2026 01:58:54 +0000

Years ago at RightScale I learned more about distributed systems from broken log files than from any design doc. A request came in the front door, fanned out through a workflow service, hit a plugin, and the plugin called some cloud API. When it failed, the only way to find where was to line up the logs of every service it passed through. So we threaded a trace ID from the frontend all the way to the cloud call and back. With it, a failure was a search query. Without it, you were guessing.

the lesson came back

It stuck. I just had to learn it twice.

Building finfocus, a FinOps CLI that talks to cloud providers through gRPC plugins, I hit the same wall. Except this time there was a second reader who couldn't follow the logs: the agent. I'd ask Claude to find why a plugin call failed, and it would dig through the finfocus logs, reach the gRPC boundary, and find nothing on the other side. Unconnected traces, or no traces at all. I'd reached for zerolog early, but I'd wired it up wrong. The CLI logged. The plugin logged. Nothing tied the two together, so neither of us could see across the boundary.

Once the trace ID actually crossed that boundary, troubleshooting got fast. The agent could make a call, follow it from the finfocus CLI through the gRPC plugin and back, and tell me which side broke. Bug hunting went from a séance to a grep.

the second wall

The next problem was stranger. finfocus has a TUI: pretty tables, built for human eyes. Ask an agent to read one and it gets the numbers wrong, because a table is laid out for a person, not a parser. Back then, agents were bad at this.

So every command that renders a table also got a --json that runs the same function as the table does. Two renderings, one source of truth: pretty for humans, structured for agents. They can't disagree about the total, because the total is computed once.

canonizing it

Then I did all of it again in gh-aw-fleet.

By the time I was copying the same plumbing into a third project (stream separation, trace propagation, structured errors, a JSON twin for every human view), the question answered itself. Why am I rewriting this per repo? Canonize it once, let other people use it, and get the wisdom of the crowd (and the clankers) to make it better.

That's ax-go: Agentic Experience for Go.

what it is

ax-go is a single Go package (github.com/rshade/ax-go, imported as ax) that encodes the conventions a CLI needs so an agent can use it as reliably as a human can. The rules I kept rediscovering, written down once:

stdout is data, stderr is everything else. The final JSON payload is the only thing on stdout. Logs, progress, and error envelopes go to stderr. An agent pipes stdout into a parser; you still read the logs.
Traces that cross the boundary. W3C Trace Context rides context.Context through OpenTelemetry, so one call stays correlated from the CLI to whatever it calls.
Same input, same bytes. Two runs on the same input produce byte-identical stdout. An agent diffs outputs to catch drift, which is the machine version of trust.
A __schema command. Every tool can describe its own commands, flags, and types as JSON, so an agent grounds itself instead of guessing. There's an MCP adapter too.
Agent-safety primitives. An auto-generated --idempotency-key so a retried create can't run twice, a universal --dry-run, deterministic exit codes, and a structured error envelope.

where it's at

It's released and pre-1.0. v0.1.0 is the pinnable tag, with output contracts already frozen in code and pinned by golden tests, so the shapes an agent depends on won't move underneath it.

It starts with what I use: zerolog and OpenTelemetry. Other structured loggers and output formats will follow, but I'd rather ship the opinions I've tested in finfocus and gh-aw-fleet than guess at the ones I haven't. It's the common DNA for my own tools first. If it's useful to yours, even better.

Years later, I'm still threading trace IDs across plugin boundaries. The only difference is who's reading them now.

where did the knife come from

Richard Shade — Thu, 18 Jun 2026 01:28:54 +0000

In third grade I had to write a how-to for making a peanut butter and jelly sandwich. I thought I'd nailed it. Four steps:

Get the bread.
Get the peanut butter and the jelly.
Spread the peanut butter on one slice, the jelly on the other.
Put them together.

My teacher read it, looked up, and asked one question:

Where did the knife come from?

I had the vision. I'd skipped the environment. The knife was real in my head (I'd seen it in the drawer that morning) so I assumed it was real on the page. It wasn't.

three phases of getting this wrong with LLMs

When I started taking prompt engineering seriously last year, I realized I was repeating the third-grade mistake. The arc was familiar enough that I think most people walk it.

Phase one: the one-liner. Single sentence. Expect the model to read your mind. When it fails, fight with it in the next turn instead of fixing the prompt.

Phase two: the notebook. Start saving prompts that worked. Notice that consistency matters. Notice that some prompts are doing work the model can't actually do without more setup around it.

Phase three: the environment. Realize the prompt isn't an instruction. It's a room. The model can only use what's in the room. If the knife isn't in the room, the sandwich doesn't get made, no matter how clearly you described the spreading motion.

what I write now

Three things stacked on top of each other:

Context: where the ingredients live. What the model has access to.
Constraints: how to use the tools, and how not to.
Acceptance criteria: what "finished sandwich" actually looks like, in enough detail that the model can self-check.

There's no magic word. There's no clever phrasing trick. Prompt engineering is the same skill as writing a good bug report or a clear design doc: assume the reader doesn't have your context, then put the context in the document.

where the copilot credits went

Richard Shade — Tue, 16 Jun 2026 02:16:01 +0000

A couple weeks ago I introduced gh-aw-fleet and ended on a confession: I went in solving a drift-tracking problem and walked out with a FinOps one. That was foreshadowing. The bill has since arrived, and I'm late to writing about it, which is about right. The hot takes have burned out and FinOps X has packed up, and what's left is the one question worth keeping: where did the credits actually go?

what changed

On June 1, GitHub moved Copilot to usage-based billing. Premium request units are gone; in their place are AI Credits metered against token consumption: input, output, and cached, at each model's API rate. The sticker prices didn't move (Pro+ is still $39, Business still $19 a seat), but the math underneath did: every chat turn, every agentic session, every Copilot code review now draws down a credit balance. Reviewing a PR with Copilot bills against your Actions minutes too.

The reaction was about what you'd expect. People watched a month of credits evaporate in an afternoon and called it meter shock.

Now point that meter at a fleet. I run a dozen-odd repos with agentic workflows on them (code review, daily doc updates, malicious-code scans), and every one of them is now a little metered faucet.

why you can't see it

The per-repo tools answer the wrong question. gh aw sees one repo. The Actions UI sees one repo. Nothing sums it across the fleet, so the credits drain quietly and the first time you see the total is on the invoice. That's the same blind spot drift detection had before status: the problem was never any single repo, it's that nobody was looking across all of them at once.

where the credits went

The same fleet.json that declares which repos get which workflows is the natural place to attribute what those workflows cost. It already knows the repo, the profile, and (if you set one) the cost center. That's every dimension you'd want to slice spend by, sitting right there in the config.

So that's what gh-aw-fleet consumption does. It reads the credits each workflow burned straight from gh aw logs --json and rolls them up along whichever axis you ask for: the whole fleet, or scoped to a single repo. There's no dollar field to read. Under the new model the unit is the AI credit, so that's the column, with USD derived at the published rate of a cent per credit.

Across the repos I run in the open, finfocus was the worst offender, so I pointed consumption at it, grouped by workflow, and let it name the culprit:

gh-aw-fleet consumption rshade/finfocus --by workflow --trailing 7d

WORKFLOW                          AIC       COST
Agentic Dependabot Bundler        2295.78   $22.96
Daily Documentation Updater        796.54    $7.97
Agentic Workflow Audit Agent       487.23    $4.87
Daily Malicious Code Scan Agent    385.92    $3.86
Sub-Issue Closer                   313.61    $3.14
Code Simplifier                    137.49    $1.37

That's one of my own repos, one week: ~4,400 credits, about forty-four dollars. And the rollup answers the question in the title: one workflow, the Agentic Dependabot Bundler, is $22.96 of that. A single agent is more than half the bill.

None of this appeared overnight. It arrived one release at a time: a billing diagnostic, then the cost_center and tier fields, then the rollup, then reading credits straight from the logs, then scoping it to a single repo. I was building toward a bill I knew was coming.

the point

Here's what makes it land harder than a personal billing gripe. At this year's FinOps X, the FinOps Foundation and the Linux Foundation announced their intent to form a Tokenomics Foundation: open standards for AI token economics, the first job being to extend the FOCUS cost spec to cover token billing. The conference is even renaming itself Tokenomicon for 2027. The unit of account is officially becoming the token.

My rollup agrees with them. There was no dollar figure to read. The honest unit under usage-based Copilot is the credit, and the dollars are a cent-apiece derivation on top. I didn't build a standards body. I built a subcommand. But it turns out I was hand-rolling, for one fleet, the thing a dozen of the biggest names in the industry just agreed needs a spec: when the unit of work is a fleet, the unit of cost is too. And nothing else in the stack was going to tell me that one dependency bundler was quietly eating half my credits.

introducing gh-aw-fleet

Richard Shade — Mon, 15 Jun 2026 01:22:31 +0000

I started using GitHub Agentic Workflows a couple months ago: small Claude/Copilot agents that run inside your CI for code review, daily doc updates, malicious-code scans, and PR fixes. You author them in markdown, they compile to GitHub Actions, and an AI agent does the work on each run.

Got the first few repos working and hit the question: how am I actually tracking what's deployed on each of these? What version? What profile? What's drifted?

So I built a tool.

what it is

gh-aw-fleet is a declarative fleet manager for GitHub Agentic Workflows. One fleet.json declares your repos and which "profiles" of workflows they get; the CLI reconciles (deploy, sync, upgrade, add), all dry-run by default. It's a thin orchestrator around gh aw, gh, and git, not a fork.

It never rewrites workflow markdown. It answers one question (who gets what workflow, when, and from which profile) and dispatches the actual file work to gh aw. Every operation that touches a repo opens a PR there. Nothing force-pushes or commits to main.

# check drift across the whole fleet, no clones, read-only
gh-aw-fleet status

# bring a repo in line with its declared profile (PR, after a dry-run)
gh-aw-fleet sync acme/widgets --apply

The dry-run gate is the part I lean on most. deploy, sync, and upgrade print exactly what they'd do and change nothing until you add --apply. When you're touching a dozen repos at once, "show me first" is the difference between a tool you trust and one you babysit.

the part I didn't see coming

Usage-based Copilot billing lands 2026-06-01. Every deployed workflow burns credits at metered rates, and the per-repo tools (gh aw, the Actions UI) can't see across the fleet to tell you where the credits went.

The same fleet.json that declares which repos get which workflows turns out to be the natural place to attribute that consumption: by repo, by profile, or by cost center. A consumption rollup is in flight. I went in solving a drift-tracking problem and walked out with a FinOps one.

what's shipped since launch

v0.1.0 shipped April 21 with the core reconcile loop. It's at v0.2.0 now, and the gap is mostly about trusting the tool against more repos:

status / drift detection: see what's out of line across the fleet without cloning anything, and gate a CI job on it.
JSON output + structured logging: -o json on the read commands, zerolog underneath, so you can pipe results into jq or an aggregator.
resumable deploys: pick a half-finished deploy back up at the commit or push gate instead of starting over.
a Layer-1 security scanner: secrets and structural rules checked before anything ships.
observability-plus profile + an HTTP 402 billing diagnostic: early groundwork for the billing story above.
HuJSON config: comments and trailing commas in fleet.json, so you can document why a pin is set right next to the pin.

where it's at

v0.2.0, still pre-1.0: the CLI flags and the fleet.json schema may move before 1.0. But I'm already using it to manage my own repos, and it's working great.

hello, world

Richard Shade — Sun, 14 Jun 2026 23:54:44 +0000

A blog is a long-running argument with yourself about what you actually believe. I've been meaning to start one for years.

This is mine. It will be about FinOps and Pulumi (my day job), AI tooling and agent design, infrastructure war stories that deserve to exist outside Slack threads, and occasionally brisket and ham radio, because a blog without a person behind it is just SEO.

Up next: a story about a third-grade peanut butter sandwich assignment, and why it explains most of what I think people get wrong about prompt engineering in their first six months.

More soon. 73.