DEV Community: Richard Shade

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.