DEV Community: Darren "Dazbo" Lester

Spec-Driven Development For-the-Win: Disposable Code, Living Blueprints, and Building Like a Boss

Darren "Dazbo" Lester — Tue, 20 Oct 2026 10:28:53 +0000

Part 3 of the series "Beyond Vibe Coding: The Engineering Blueprint for Reliable AI Agents"

🗺️ The Series Roadmap: Beyond Vibe Coding

In 2026, software development is drowning in fragmented buzzwords: Harness Engineering, Loop Engineering, Context Engineering, Spec-Driven Development, Evaluators, and Sandboxes. Are they competing frameworks? Redundant prompt techniques? Or something fundamentally new?

This four-part series unifies these concepts into a single, cohesive architectural blueprint for building software with AI without writing code manually:

Part 1: From Vibing Chaos to Reliable Agents: The What, Why, and How of Harness Engineering We diagnose the hangover of vibe coding, unpack the paradigm shift of shifting developer interventions left, establish our bedrock formula (Agent = Model + Harness), explore the Lewis Hamilton motorsport analogy, and deconstruct the deterministic components that make up a production developer environment.

Part 2: Loop Engineering in the Harness: Autonomous, Self-Correcting Systems We fire up the dynamic runtime engine of the harness: deconstructing the core loop components, establishing hybrid evaluation rubrics (deterministic tests + LLM goal fidelity + tool trajectory verification), and applying the Ratchet Principle.

Part 3: Spec-Driven Development For-the-Win: Disposable Code, Living Blueprints, and Building Like a Boss (This Article) We explore Spec-Driven Development (where code is disposable and specifications are the single source of truth), master Google Antigravity's unified harness and interactive slash commands (/grill-me, /plan, /goal, /boost, /learn), and combine formal specs on disk with autonomous tactical workflows in your session.

Part 4: Scaling the Harness: Practical Loop Patterns, ADK 2 Graphs, Recursive Harness², and Harness Maintenance (Coming Soon) We bring everything together with practical loop patterns you can wire into any repo (from declarative Markdown and loopy to Google ADK 2 graphs), keep context clean across iterations with short-lived subagents, explore Google Research's recursive Harness² framework, and cover ongoing harness maintenance.

Fuel for the Engine: Replacing Vibes with Verified Intent

In Part 1, we used the race car analogy for the agentic harness and built the deterministic chassis. In Part 2, we built the powertrain: the autonomous execution loop, hybrid evaluation rubrics, and the Ratchet Principle.

Crucially, in Part 2 we established a foundational architectural discipline: decoupling reusable engineering guardrails from the task specification.

We centralised the "how we build" — coding standards, test-driven development mandates, security constraints, and automated linting rules — into persistent workspace context (GEMINI.md, AGENTS.md) and Agent Skills. That gave our loop its invariant engineering discipline.

So what fuels the loop? What defines "what we build"?

If you pair rigorous engineering guardrails with vague, casual chat prompts and hand-waving, you won't get quality software. You'll get AI slop at 50 tokens a second.

This is where Spec-Driven Development (SDD) enters the frame. As Google Developer Advocate Lee Boonstra brilliantly captured in her whitepaper Spec-Driven Production Grade Development in the Age of Vibe Coding, formalising the task into a structured, testable specification transforms a slop generator into a precision instrument.

It also unlocks a fundamental architectural shift: code is disposable, but specifications are the permanent source of truth.

Because your engineering context, linters, and evaluation rubrics already govern quality, the generated source code is merely an ephemeral byproduct. If business requirements change or an implementation runs down an architectural blind alley, you don't spend days manually untangling spaghetti code. Your standing guardrails stay untouched; you sharpen the task specification, and let your harness regenerate a clean solution from first principles.

In Spec-Driven Development for Agentic Software Engineering: Harnessing Human-Agent Teamwork, researchers demonstrated that unconstrained conversational agents inevitably suffer from compounding specification drift — a phenomenon where tiny misunderstandings compound across successive turns. Without a fixed specification, it is virtually guaranteed that the final output will drift away from your architectural intent.

SDD eliminates this drift by introducing immutable contract checkpoints at every phase, keeping the agent firmly on the rails instead of letting it wander off into the weeds.

For years, the industry swung between two dysfunctional extremes: either spending months drafting bloated, upfront documentation that was obsolete before deployment, or weaponising a poor understanding of "agile" to jump straight into code with zero planning.

SDD finally closes that gap. Iterating on a half-page specification with an AI partner takes five minutes. The harness then builds and verifies the code in the sandbox in ninety seconds. You inspect working software, get instant empirical feedback, update the contract, and loop. It delivers the deep architectural rigour that enterprises require, at the blistering feedback cadence that agile was always supposed to deliver.

In other words, SDD plus an agent takes genuine agile principles to their logical conclusion.

The SDD Lifecycle as a Continuous Loop

In an agentic workflow, clear documentation isn't cumbersome ceremony — it is a superpower. Spec-Driven Development is emphatically not a rigid, 200-page document that gathers dust in an enterprise SharePoint graveyard. It is a continuous, living lifecycle that evolves in near real-time alongside the codebase.

Let's take a look at the SDD lifecycle:

Don't let the formal diagram labels fool you into thinking this is a return to heavyweight waterfall processes. In an agentic workflow, Steps 1, 2, and 3 happen collaboratively in minutes — often in a single conversational exchange — to produce that concise living blueprint:

Scope & Edge Discovery (The WHAT): A quick dialogue pinning down user intent, non-goals, and boundary conditions. No 50-page PRD; just conversational clarity on what's in scope and what's out.
Interface Contracts & Boundaries (The HOW): Nailing down the API shape, schema constraints, and Operational Boundaries (Always Do, Ask First, Never Do) before authoring implementation code.
Acceptance Criteria & Test Scenarios (The PROOF): Declaring how success will be proven — a few lines of Gherkin or a failing test stub — giving the agent an unambiguous finish line.
Automated Code Generation: The agent consumes the living specification within the sandboxed harness, generating implementation code constrained strictly by the contracts and boundaries agreed in steps 1 to 3.
Testing & Continuous Validation: Automated test runners execute unit, integration, and static analysis suites directly against the test specification. Simple code defects are patched by Part 2's inner execution loop, while discovered requirement gaps loop straight back to refine the living spec.

Concrete Artifact: A Production Spec Blueprint (`tasks/plan.md`)

What does a real specification look like when fed into an agentic harness?

It should not be an informal prompt. It is a structured, version-controlled markdown artifact living directly in your repository.

Here is a reference blueprint of a production tasks/plan.md specification for a cloud service (in this case, an audit event logger backed by Cloud Spanner):

# Implementation Spec: Cloud Spanner Audit Event Logger

## 1. Architectural Scope & Contracts

- **Component:** `AuditEventLogger` service in `services/audit_logger.py`
- **Persistence:** Cloud Spanner table `audit_events` (Schema: `event_id STRING(36)`, `timestamp TIMESTAMP`, `actor STRING(128)`, `action STRING(64)`, `payload JSON`)
- **Transport:** Async gRPC client via `google-cloud-spanner` Python SDK

## 2. Three-Tier Operational Boundaries

### Always Do

- Enforce strict typing on all method signatures using PEP 585 standard types.
- Ensure all database writes use Spanner Mutation batches (`spanner.insert_or_update`) rather than ad-hoc DML statements.
- Run `uvx ruff check --fix .` and `uvx codespell -s` after any file modification.
- Practice TDD: author failing test in `tests/test_audit_logger.py` before touching service code.

### Ask First (Human Verification Required)

- Adding any new third-party Python dependency to `pyproject.toml`.
- Modifying Spanner DDL or altering table schemas.
- Proposing changes to the shared gRPC authentication interceptor.

### Never Do

- Never hardcode service account keys, project IDs, or credentials; rely strictly on Application Default Credentials (ADC).
- Never execute inline `python -c` snippets in terminal sessions.
- Never catch generic `Exception` without re-raising or logging with structured traceback.

## 3. Phased Vertical Decomposition

- [ ] **Phase 1: Domain Models & Test Scaffolding**
  - Define `AuditEvent` Pydantic / dataclass model in `models/audit.py`.
  - Author unit test mocking Spanner database client in `tests/test_audit_logger.py`.
  - *Verification:* `uv run pytest tests/test_audit_logger.py` runs and fails with `NotImplementedError`.

- [ ] **Phase 2: Service Implementation & Batch Mutations**
  - Implement `log_event()` and `log_batch()` methods in `services/audit_logger.py`.
  - Implement transient backoff retry logic for `Aborted` and `DeadlineExceeded` Spanner errors.
  - *Verification:* `uv run pytest tests/test_audit_logger.py` passes 100%.

- [ ] **Phase 3: Static Analysis & Hygiene**
  - Execute static analysis and spellcheck suite.
  - *Verification:* Zero warnings from `ruff` and `codespell`.

Notice the power of the operational boundaries (Always Do, Ask First, Never Do). This is where harness engineering neutralises the wild unpredictability of vibe coding. The agent knows exactly where it has autonomous authority (writing tests, formatting code) and where it must yield control to the human conductor (modifying schemas, adding dependencies).

What vs How: The Two Layers of a Living Specification

Now, is a single technical plan like our Spanner blueprint the only way to frame a specification? Definitely not.

In production engineering, specifications often operate across two complementary layers:

The Functional Specification (spec.md — The "WHAT" & "WHY"): User-centric and technology-agnostic. It defines the business goals, persona expectations, explicit non-goals (what the agent must not build, preventing scope creep), and verifiable acceptance criteria. It deliberately avoids mentioning specific Python classes, database drivers, or file paths.
The Technical Implementation Plan (plan.md — The "HOW"): Codebase-aware and execution-focused. It translates the functional spec into concrete file impact maps (which files to create, edit, or delete), data schemas, library dependencies with explicit versions, and ordered task checklists.

Our Spanner example above is a compact technical execution plan — bundling architectural scope, operational boundaries, and phased vertical slices into a single actionable file for the loop.

The Three-Tier Boundaries (Always Do, Ask First, Never Do) represent a key operational pattern within that plan: they govern the agent's blast radius and autonomy envelope. As we'll explore in the next section, these boundaries can live directly inside a task plan, or be codified globally as a non-negotiable project constitution.

Spec Anatomy: Token Physics and Behaviour-Driven Contracts

When crafting a specification, two practical disciplines make the difference between an agent that drifts and one that executes with surgical precision:

Token Physics & Formatting Science (The Hybrid Markdown + YAML Rule): Large language models do not interpret abstract data structures; they process tokenised text. In recent agent compilation research (such as the SkCC study highlighted in Lee Boonstra's whitepaper), LLM agents suffered up to a 40% performance drop when fed generic, unoptimised Markdown documents. For Gemini models, the sweet spot is Hybrid Markdown + Conditional YAML. Use clean Markdown headers (#, ##) to anchor broad system context and global narrative instructions. Meanwhile, render structured configuration, data contracts, and entity schemas (especially with nesting depth > 3) in flat, compact YAML rather than verbose JSON or XML. YAML achieves significantly higher parsing accuracy for deep configurations while eliminating the heavy "reasoning format tax" of JSON closing brackets and quotes.
Behaviour-Driven Development (BDD) with Gherkin: Vibe prompts describe vague wishes ("make a friendly booking system"). A production-grade spec describes verifiable state transitions. Wrapping acceptance criteria in declarative Gherkin syntax (Given / When / Then) forces the model into a deterministic State → Action → Outcome sequence:

Scenario: Booking a table with active dietary preferences
  Given a customer with dietary preference "gluten-free" recorded in session
  When they request a reservation for 2 guests on Friday at 19:00
  Then verify table availability via the Cloud SQL reservation tool
  And confirm the booking, returning a structured reservation ID

(Side note: even standard Markdown engines natively support gherkin syntax highlighting out of the box — proving just how universally recognised this format already is! Not Medium, of course!)

By providing explicit preconditions, the exact tool to trigger, and the expected outcome, you remove all ambiguity. The agent doesn't need to guess your intent; it simply fulfils the contract.

Practical Tooling for Spec-Driven Development

You don't have to invent your own specification formats or build bespoke SDD tooling from scratch. The agentic engineering community has converged on several robust frameworks, each suited to different developer workflows.

1. The `spec-driven-development` Skill

What it is: An open-source Agent Skill (created by Addy Osmani) that enforces specification discipline as an autonomous conversational workflow loaded directly into your agent's context.
How you use it: Installed in your workspace (.agents/skills/) or global configuration (~/.gemini/config/skills/), you trigger it conversationally at the start of any feature (e.g. "Use spec-driven development to scaffold the audit logger"). The agent enforces a strict 5-stage sequence (Scope Check → Specify → Plan → Tasks → Implement), pausing at each gate to surface its technical assumptions:

ASSUMPTIONS I'M MAKING:
1. Target runtime is Python 3.13 managed via uv.
2. Data persistence uses Cloud Spanner with dialect GoogleSQL.
3. Authentication relies on Google Cloud ADC / IAM principal tokens.
-> Confirm or correct before proceeding.

What it outputs: A single, consolidated tasks/plan.md file committed to your repository — exactly like our Spanner blueprint above — featuring architectural contracts, Three-Tier Boundaries (Always Do, Ask First, Never Do), and an ordered checklist of test-verifiable tasks.

2. GitHub's `spec-kit`

What it is: An open-source CLI toolkit and prompt harness created by GitHub that standardises specification-first software development through dedicated commands, project-level constitutions, and multi-file dossiers.
How you use it: Executed via CLI or interactive slash commands (/speckit.specify → /speckit.clarify → /speckit.plan → /speckit.tasks → /speckit.implement). You run each step as an explicit command in your terminal or IDE, validating proposed designs against a non-negotiable Project Constitution (.specify/memory/constitution.md). It also includes independent, lightweight workflows for Bug Fixing (assess → fix → test) and Idea Assessment (intake → define → decide).
What it outputs: A modular, version-controlled dossier under specs/<feature-branch>/ containing separated files: spec.md (the user-facing WHAT), plan.md and data-model.md (the technical HOW), research.md (library versions and decisions), and tasks.md (an atomic execution checklist).

3. Google's Conductor Extension

What it is: An AI-native extension and visual workspace assistant from Google that guides developers through context gathering, specification authoring, and test generation directly inside their editor.
How you use it: As announced on the Google Developers Blog, Conductor now natively supports Antigravity. It lives directly inside your editor sidebar: initiating a structured context-gathering flow, clarifying ambiguous requirements, and validating test coverage before unlocking code generation.
What it outputs: An established set of structured, version-controlled Markdown files — specifically product.md (vision and scope), tech-stack.md (dependencies and architecture), spec.md (contracts and acceptance criteria), and plan.md (task execution). Just like any other SDD framework, these files are committed to the repo and loaded straight into Antigravity's context window as the permanent source of truth.

Google Antigravity: The Unified Developer Harness

Where does all of this come together in practice?

Up to this point, we have talked about harness components conceptually: hierarchical context rules, MCP servers, sandboxed environments, evaluation rubrics, and living specifications. But developers need a concrete runtime to orchestrate all these moving parts into a cohesive workflow.

In the Google ecosystem, that orchestrator is Google Antigravity.

Antigravity is not another chat assistant bolted into the sidebar of an editor. It is an AI-native developer harness engine built from the ground up around the Plan → Do → Verify engineering cycle. Rather than expecting a single model prompt to handle everything in one turn, Antigravity operationalises harness discipline: actively coordinating the engineering environment around the model, managing context, enforcing boundaries, and verifying outcomes.

Inside the Harness: What the Engine Coordinates

Don't mistake Antigravity for a passive chat assistant that merely answers questions and suggests snippets. A true developer harness actively coordinates the engineering environment around the model:

Automatic Rule & Policy Enforcement (No Copy-Pasting Prompts): Rather than expecting you to copy-paste prompts or manually configure system instructions, Antigravity natively discovers and binds hierarchical rule files (~/.gemini/GEMINI.md, workspace/.agents/rules/, and workspace/GEMINI.md — which is completely interchangeable with workspace/AGENTS.md depending on your team's conventions). It ensures your coding standards, package policies, and architectural requirements are deterministically bound to every model invocation.
First-Class Agent Skills & MCP Orchestration: Antigravity was built from the ground up for progressive disclosure. It tracks installed skills via lightweight metadata headers, dynamically expanding full instruction sets and schemas only when relevant tasks are triggered. Once declared in your configuration, it natively handles tool registration, schema discovery, and execution against both local and remote MCP servers (such as developer-knowledge and Cloud Logging).
Isolated Sandboxing with Blast-Radius Control: Commands executed by Antigravity run inside an isolated sandbox by default. The agent has full read/write access to your workspace, but network access and modifications to host-level operating system files require explicit privilege elevation. This gives the agent freedom to compile, test, and refactor code rapidly without placing the developer's workstation at risk.
Subagent Spawning & Context Isolation: Long-running development tasks often require diverse capabilities. When an agent needs to survey documentation across twenty web pages or perform an in-depth accessibility audit, Antigravity can spawn isolated subagents (like dedicated research or browser agents). The subagent executes its bounded task, returns a synthesised result to the parent orchestrator, and terminates — keeping the primary context window lean and focused.
Subagent-Driven Development (Task Implementers & Reviewers): Beyond ad-hoc research, structured SDD harnesses split implementation across specialised subagent personas. Rather than cluttering the primary conversation with thousands of lines of intermediate compiler output and syntax churn, Antigravity can dispatch each task to an isolated Task Implementer subagent with a pristine context window. Once implementation completes, an independent Task Reviewer subagent evaluates the code against the specification contract, passing only a clean verification receipt back to the primary orchestrator.

One Core Harness Across Five Developer Surfaces

Now, where does this harness live?

Crucially, Google Antigravity delivers this identical harness engine across four developer surfaces, alongside a programmatic Python SDK:

The Antigravity App (formerly Antigravity 2.0) — a dedicated desktop application designed for intent-based building, allowing you to direct autonomous agents, review visual artifacts, and orchestrate projects without having to worry about the underlying code.
The Antigravity IDE — a standalone, AI-first code editor (built on VS Code) for developers who want a complete coding workspace with intelligent tab completions, inline refactoring, and in-editor sidebar assistance.
The Antigravity Extension — brings the complete harness directly into your existing editor of choice (VS Code, JetBrains, Visual Studio, or Zed) so you don't have to abandon your familiar tools.
The Antigravity CLI — a full Terminal User Interface (TUI) for developers who live in the command line or remote SSH sessions, and want the interactive harness experience in their terminal.
The Antigravity SDK — a Python library for programmatic orchestration, headless automation, scripted workflows, and custom multi-agent systems.

Across all these surfaces and tools, the underlying configuration engine, context rules (~/.gemini/ and workspace/.agents/), MCP servers, and sandboxed execution runtimes are completely identical.

This addresses one of the biggest roadblocks in enterprise adoption: the IDE lock-in barrier. As I explored in Meet the Antigravity Extension: Gemini Code Assist on Steroids, in Whatever IDE You Love, tens of millions of developers — and enterprise security policies — will not simply abandon their favourite IDEs overnight. By packaging the entire unified harness into an extension for VS Code, JetBrains, and beyond, Google ensures teams get full harness intelligence without having to abandon their existing toolchains.

Supercharged Harness Workflows (Slash Commands)

Antigravity provides a number of "slash" commands out-of-the-box. Rather than typing out long prompt instructions, you can trigger key harness behaviours directly using these commands:

`/grill-me`

The antidote to underspecified requirements. Instead of accepting a vague prompt and guessing how to implement it, Antigravity initiates a structured, one-question-at-a-time interview to stress-test your thinking, interrogate boundary conditions, and resolve ambiguities before a single file is modified.

Real-world prompt:

/grill-me on the Spanner schema and backoff retry behaviour in tasks/plan.md

`/plan`

Switches the agent into dedicated planning mode. Rather than immediately modifying files, Antigravity surveys the codebase, maps out dependencies, and presents a structured implementation plan with verification steps for your review and sign-off before execution begins.

Real-world prompt:

/plan refactor services/audit_logger.py to use async batch mutations with zero breaking changes

`/goal`

Initiates an autonomous execution loop for long-running tasks. Rather than pausing after every step to ask for input, the agent works through the task list, diagnoses test failures, handles retries, and yields control only when the objective is fully achieved and verified.

Real-world prompt:

/goal implement Phase 2 of tasks/plan.md, fix any failing pytest assertions, and ensure ruff passes

`/boost`

Transforms a single model session into a coordinated team of subagents executing tasks or adversarial reviews in parallel. In loop engineering, /boost is the easiest way to implement decoupled multi-agent verification — pairing a builder subagent with an independent critic subagent so a single model instance never marks its own homework.

Real-world prompt:

/boost run an adversarial security and race-condition review of our Spanner transaction handler

`/learn`

The mechanical realisation of the Ratchet Principle! When you guide or correct an agent during an interactive session, running /learn extracts the operational lesson and crystallises it directly into your workspace rules. The lesson is immediately persisted to disk so future sessions never repeat the mistake.

Real-world prompt:

/learn always wrap Spanner Mutation writes in exponential backoff when catching Aborted errors

Slash Commands Alone vs. Formal SDD

At this point, I know what you might be thinking:

"Hold on, Dazbo. If Antigravity already gives me /plan and /goal out of the box, why do I need formal SDD skills like Conductor, spec-kit, or the spec-driven-development skill? Isn't that just extra ceremony?"

Great question. Here's the thing: it comes down to the trade-offs between tactical session planning and long-term architectural governance:

Dimension	Native Slash Commands Alone (`/plan`, `/goal`)	Formal SDD Skills & Plugins (Conductor, `spec-kit`, `spec-driven-development`)
Setup & Friction	Zero friction. Built natively into Antigravity; available instantly with no configuration.	Moderate ceremony. Requires installing the tool and walking through the guided discovery interview (though the framework scaffolds the files and folders for you).
Persistence & State	Ephemeral. Plans and goal states live in the active conversation thread; they risk being lost during context compression or when starting a fresh session.	Version-Controlled. Formal specs, task checklists, and ADRs live as permanent Markdown/YAML files in the Git repo (`specs/`, `tasks/`).
Scope Enforcement	Conversational. The model plans dynamically, but doesn't strictly enforce pre-implementation gates or boundary contracts.	Machine-Gated. Enforces strict Phase 0 scope analysis, surface assumption checks, and Three-Tier Boundaries (Always Do, Ask First, Never Do).
Token Overhead	Low. Directly targets the immediate task at hand without multi-phase document generation.	Higher upfront. Consumes tokens generating formal contracts and schemas before writing code.
Best Used For	Tactical features, targeted refactors, rapid bug fixes, single-session development.	System architectures, multi-agent systems, cross-team projects, mission-critical services.

An Enterprise Option: Combining SDD with Tactical Slash Commands

You don't always need both. For everyday feature slices, targeted refactors, or rapid bug fixes, Antigravity's native slash commands (/plan and /goal) provide plenty of structure with zero setup overhead. Conversely, for architectural reviews, a standalone SDD dossier alone might be all your team requires.

However, when you are tackling large, multi-component enterprise initiatives, nesting these layers into a hybrid workflow is a powerful option. You can use formal SDD as the macro-architectural envelope on disk, and Antigravity's native slash commands as the micro-execution engine in the session.

Here is an example four-phase hybrid pattern you can adopt when orchestrating complex features:

Phase 1 — Macro Architecture (The Outer Spec via Formal SDD / Conductor / spec-kit): Before generating any implementation code, establish the enduring system blueprint on disk. Define machine-readable API contracts, data schemas, test stubs, and the operational boundary rules (specs/api_contract.md, tasks/plan.md). Because these are committed to version control, they survive across sessions, branches, and team members.
Phase 2 — Specification Stress-Testing (/grill-me): Once the initial specification is drafted, invoke /grill-me against the spec file. Antigravity acts as a relentless, sceptical peer reviewer. It interrogates boundary conditions, probes error handling paths, questions concurrency models, and surfaces hidden assumptions before signing off on the architecture.
Phase 3 — Autonomous Tactical Execution (/plan + /goal + /boost): With the formal spec locked, feed a single vertical slice from your task plan into /goal (or /boost for separated Builder/Critic verification). Antigravity's autonomous workbench takes over, executing the tactical inner execution loop we built in Part 2: it uses /plan to map out immediate file edits, executes changes inside the sandbox, validates against deterministic linters and semantic rubrics, and loops autonomously until every gate is green.
Phase 4 — Hardening the Harness (/learn): When the agent encounters an unexpected runtime quirk or discovers a project-specific constraint during the /goal execution loop (such as a subtle gRPC serialisation rule or sandbox path issue), invoke /learn. Antigravity extracts that operational lesson and crystallises it directly into workspace/.agents/rules/ or your root rule file (GEMINI.md / AGENTS.md). The ratchet clicks; the harness hardens; and the entire team permanently benefits from the discovery.

Sustainable Team Engineering: Defeating Approval Fatigue

Adopting Spec-Driven Development doesn't just change how you interact with an AI model — it fundamentally alters team engineering culture.

When teams first adopt automated coding assistants, they often fall into a trap known as review theatre. Developers find themselves staring at a 1,200-line diff generated in three seconds, trying to manually verify every line of syntax. Developer experience studies consistently highlight that frequent AI tool users suffer significant cognitive burnout when trapped in manual code reviews. Eyeball inspection simply does not scale to agentic velocity.

SDD breaks this cycle by establishing a clean division of responsibility:

Humans review the intent and the contracts: You evaluate the architectural trade-offs, the boundary constraints, and the acceptance test scenarios.
The harness verifies the code: Linters, sandboxed test suites, and evaluation rubrics verify the disposable implementation syntax.

By shifting human review from syntax nitpicking to spec and contract design, engineering teams eliminate approval fatigue while maintaining rigorous production quality. If the contracts and test scenarios are sound, and the automated verification suite passes in the sandbox, you can merge with confidence.

Summary & What's Next: Scaling the Harness

We have now brought together our deterministic chassis (Part 1) and our autonomous loop engine (Part 2), fuelled by living specifications committed directly to the workspace (Part 3) and orchestrated through Google Antigravity.

But how do you introduce loop engineering into any existing repository in under five minutes? How do you prevent multi-turn loops from collapsing under context bloat? And what happens when you put a recursive meta-loop around the harness itself?

In Part 4 (The Finale), we take our harness to the next level:

The Anatomy of an Iteration: How sandboxed environments, ephemeral subagents, and LIVING_MEMORY.md filter out noise and beat attention dilution.
Practical Ways to Wire Loops into Any Project (And How to Combine Them): From zero-code Markdown rules (GEMINI.md + RUBRIC.md) and loopy (LOOPS.md) to /goal and programmatic Google ADK 2 graphs.
Google Research's Harness² (Harness-Squared): Recursive agent harnessing (Propose → Probe → Compose) that optimises the editable components of your harness across tasks without retraining a single model weight.
Enterprise Production Pillars on Google Cloud: Bridging your local developer harness to cloud-scale production.

👉 Continue to Part 4: Scaling the Harness: Practical Loop Patterns, ADK 2 Graphs, Recursive Harness², and Enterprise Production (Coming Soon)

See you in the finale!

Before You Go

Please share 📢 this with anyone that you think will be interested. It might help them, and it really helps me!
Please give me loads of claps! 👏 (Just hold down the clap button.)
Please leave a comment 💬. Interaction is good!
Add a star ⭐ on my repos!
Follow 👉 and subscribe 🔔, so you don't miss my content.

References and Useful Links

Spec-Driven Development

Google Antigravity & Ecosystem

Dazbo's Related Articles

Automated GitHub Code Reviews Using Google Gemini Update: Enterprise-Ready, Multimodal, and Battle-Hardened

Darren "Dazbo" Lester — Mon, 19 Oct 2026 05:34:22 +0000

You are in Part 2 of the series "Automated GitHub Code Reviews Using Google Gemini"

🗺️ Series Navigation

Part 1: Automated GitHub Code Reviews Using Google Gemini — Why I built a super-fast, native composite GitHub Action to replace Google's sunsetted run-gemini-cli and Gemini Code Assist integrations, and how to get up and running in three minutes.

Part 2: Enterprise-Ready AI Code Reviews & Issue Triage with Google Gemini (This Article) — How the action evolved from a fast weekend replacement into an enterprise-grade, multimodal code review and triage engine — featuring Gemini 3.8 Flash, visual PR diffing, bounded dynamic context selection, Gemini Enterprise Agent Platform billing attribution, supply-chain hardening, and battle-tested production fixes.

Back for the Update!

Howdy friends, and welcome back!

When I published Part 1 back in July, I had a very specific itch to scratch. Google had just turned off the lights on both run-gemini-cli and the consumer Gemini Code Assist GitHub integration as part of the transition to the Google Antigravity suite. And consequently, my automated agentic pull request reviews stopped working. Sad times.

So, I rolled up my sleeves...

(Okay, that's actually an attempt at using AI to put me in a Don Johnson outfit.)

... And built a drop-in replacement: the Gemini PR Review & Triage Action (also available directly on the GitHub Marketplace).

Since launching Part 1, something awesome happened. Not only did I start dogfooding the action heavily across every single repository I maintain, but developers in the community started adopting it — and it is now actively running in production inside at least one enterprise organisation!

A massive shoutout here goes to my fellow Google Developer Expert (GDE), Sascha Heyer. Sascha rolled the action out across real production repositories, battle-tested it against enterprise edge cases, and contributed a phenomenal series of pull requests — from real-dollar cost estimation and Gemini Enterprise Agent Platform billing labels to automated review thread resolution, per-file content caps, competing bot filtering, and supply-chain lockfile hardening.

Through dozens of releases (taking us from v1.4 all the way to v1.8.3), this collaboration has transformed the tool from a "fast drop-in replacement" into what I genuinely believe is the de facto Google Gemini-based code reviewer and issue triager for GitHub.

Even better: it is 100% free and open-source. There are no SaaS subscriptions and no per-seat licensing fees. You simply bring your own Gemini API key or Google Cloud project, and you pay only for the raw tokens you consume — which, thanks to our built-in context caching, typically works out to $0.02 to $0.04 per review!

In this post, I'm going to:

Recap the What, the Why, and the Unique Selling Points (USPs) for anyone new to the party.
Share the complete current feature list so you can see everything the action packs under the bonnet today.
Deep-dive into the major new features, architectural upgrades, and battle-hardened bug fixes we've shipped since Part 1 — including why this solution is now thoroughly enterprise-ready.

Grab a piña colada (or a strong coffee), and let's dive in!

Recap: The What, The Why, and The USPs

If you missed Part 1, here is the sixty-second elevator pitch on why automated AI code reviews in CI/CD are such a game-changer — and why this specific action hits different.

The Problem with Traditional (and Local AI) Code Reviews

In a traditional workflow, you open a Pull Request and wait hours (or days) for a human colleague to context-switch away from their own work and review your code. When they finally get to it, human reviews are notoriously variable: some reviewers rubber-stamp a 500-line diff with "LGTM", while others bikeshed variable names and miss a glaring SQL injection vulnerability.

"Ah," you might say, "but I already use an AI coding assistant in my IDE!"

Me too! I live in Google Antigravity every day. But relying solely on your local IDE agent to review the code it just helped you write introduces a massive blind spot: Session Bias.

1. The "Clean Slate" Advantage

When you pair-programme with an AI assistant in your IDE, that agent accumulates your entire conversational history. It knows what you tried, why you took a shortcut, and what compromises you made to get the tests passing. Because it understands your intent so well, it frequently forgives subtle regressions, missing edge cases, or architectural drift.

By running our Gemini code reviewer inside a GitHub Action on every Pull Request, the reviewer starts with a completely clean slate. It has zero knowledge of your local chat history or how much you struggled with a module. It objectively evaluates the raw git diff against your repository's codebase context and coding standards. Time and time again, this stateless reviewer catches bugs, security gaps, and documentation discrepancies that my local IDE session glossed right over!

2. Blazing Speed: Native Composite Action + Astral's `uv`

Legacy actions (like the old run-gemini-cli) built or pulled hefty Docker containers on every single run, or used sluggish pip install steps that burned through GitHub Actions runner minutes before a single token was ever sent to Gemini.

I architected gemini-review-action as a native Composite Action powered by Astral's blazingly fast uv package manager. There are no Docker container builds and no slow dependency resolution phases. The environment boots in a couple of seconds and posts line-specific review feedback almost immediately.

3. Deep Context + 90% Cost Savings via Gemini Context Caching

Most basic AI review scripts only feed the raw git diff to the model. Without knowing what the rest of your repository looks like, an LLM can't tell if a change breaks an interface defined in another module or violates your project's architectural patterns.

Our action features a Hybrid Codebase Context Engine paired with Stateless Gemini Context Caching:

For repositories under 1.5 MB of text, it loads the entire codebase into context (Full Context Mode).
For massive repositories and monorepos over 1.5 MB, it switches to Sparse Context Mode, feeding the full directory tree, core manifests/documentation (README.md, ARCHITECTURE.md, AGENTS.md, pyproject.toml, etc.), and dynamically selecting the most relevant sister modules.
Whenever repository context exceeds ~32k tokens (about 100K characters), the action provisions an ephemeral, server-side Gemini Context Cache (CachedContent). Subsequent PR pushes and multi-turn tool calls reuse that cache handle automatically — delivering a 90% discount on cached input tokens without requiring any local runner disk persistence. (Enterprise DLP Note: On Gemini Enterprise Agent Platform, the cache is strictly tenant-isolated within your Google Cloud project and region, bounded by an automatic 1-hour TTL, and fully covered by Google Cloud's zero-training enterprise data governance commitments.)

The Complete Feature Matrix (What's in the Box Today)

Before we unpack the new engineering deep-dives, here is the complete summary of what Dazbo's Gemini PR Review & Triage Action (currently at version 1.8.3) gives you right out of the box:

Core Review & Triage Capabilities

AI-Powered Pull Request Reviews: Constructive, severity-graded (🔴 Critical, 🟠 High, 🟡 Medium, 🟢 Low), line-specific inline feedback powered by the latest Gemini Flash model (currently gemini-3.8-flash) by default.
One-Click Interactive Suggestions: Formats exact code fixes inside native GitHub suggestion blocks so developers can commit fixes directly in the GitHub UI with a single click.
Multi-Axis Quality Framework: Evaluates every PR systematically across five core engineering axes: Correctness & Verification, Readability & Simplicity, Architecture & System Design, Security & Data Hardening, and Performance & Efficiency.
Holistic Documentation & Blog Review: Evaluates Markdown documentation, READMEs, ADRs, and technical articles alongside source code for accuracy and completeness.
Automated Issue Triage: Dynamically classifies, prioritises, and applies repository labels to incoming or reopened GitHub issues based on issue descriptions, discussion comments, and attached screenshots.
On-Demand /gemini-review Trigger: Re-trigger reviews at any time via PR comments, protected by strict OWNER, MEMBER, and COLLABORATOR authorisation guards so random internet strangers can't drain your API quota.

Multimodal & Context Intelligence

Multimodal Context & Visual PR Diffing: Automatically extracts local images and PDFs referenced in Markdown files, and performs side-by-side visual PR diffing (base_sha vs head_sha) whenever images (.png, .jpg, .webp, .gif, .svg) are modified in a PR.
Multimodal Issue Triage (Remote Screenshots): Automatically extracts and securely fetches remote screenshots embedded in GitHub issues (including private repo user-attachments) so Gemini can visually inspect UI bug reports and stack-trace screenshots.
Deterministic Image Downscaling: Automatically resizes large images (>600 KB) down to a maximum of 300 KB before sending to Gemini, protecting your token budget and keeping latency low while passing SVGs and PDFs through lossless.
Hybrid Codebase Context & Bounded Dynamic Selection: Seamless switching between Full Context Mode and Sparse Context Mode, using proximity/import heuristics and a 4-tier architectural selector to pick the best sister files in large monorepos.
Per-File Content Truncation & Token Budget Safeguards: Caps individual massive files (like generated OpenAPI schemas) at 128 KB and runs preflight token checks so a single huge file never crashes your review.
Google Developer Knowledge MCP Integration: Queries official, live Google documentation (for Google Cloud, Gemini, Firebase, Android, etc.) via Model Context Protocol (MCP) during the review (automatically activated when the Developer Knowledge API is enabled on your API key or GCP project).
On-Demand Agent Skills Registry: Dynamically discovers and loads relevant coding standards from .agents/skills/. And a curated set of starter skills for Google Cloud, ADK, and Gemini APIs are already bundled.

Conversational Memory & Workflow Automation

PR Comment & Discussion Thread History: Retrieves prior inline review threads and PR comments across commits. Follows an opinionated resolution matrix: celebrates resolved items (### ✅ Resolved Items from Prior Reviews), respects developer deferrals and architectural justifications, and re-flags silently ignored issues.
Auto-Resolving Addressed GitHub Threads: Optionally resolves GitHub review conversation threads automatically (resolve_addressed_threads: 'true') once Gemini verifies the fix, unblocking "Require conversation resolution before merging" branch protection rules.
Competing Bot Author Exclusion: Filter out comments from secondary bots (exclude_comment_authors: 'claude[bot]') so your Gemini review remains genuinely independent and you don't pay input tokens to process another bot's prose.
Smart Inline-Suggestion Commit Skipping: Automatically detects commits generated by clicking "Commit suggestion" in the GitHub UI and skips redundant re-reviews (skip_inline_suggestions: 'true').

Customisation, FinOps & Enterprise Security

Zero-Config Agentic Installation Skill: Equip your IDE agent via npx skills add derailed-dash/gemini-review-action -y -g --skill install-gemini-code-review-action, then simply ask it to "Set up Gemini review in this repo" — your agent handles configuration preferences, template generation, and secret setup guidance automatically.
Extending vs Replacing Guardrails: Easily append organisation- or team-specific rules via .github/review-instruction-additions.md or the custom_instructions workflow input without losing the built-in quality framework — or you can override the entire prompt via .github/commands/gemini-review.toml.
Configurable Personas & Locales: Choose your reviewer's language (English (UK) by default) and personality (straight, dazbo, palpatine, or rick). Careful now... Palpatine is not very forgiving.

Reasoning & Thinking Budget Control: Defaults to dynamic thinking (the recommended out-of-the-box setting for PR reviews, letting Gemini scale reasoning to match diff complexity). You can also clamp thinking_level (low, medium, high, or an exact integer token budget) for predictable FinOps cost ceilings, or set it to 'off' to make Issue Triage blazing fast and ultra-cheap.
Tokenomics & Dollar Cost Telemetry: Appends a collapsible table to every review breaking down uncached input, cached input, comment history, thinking tokens, output tokens, and the estimated dollar cost.
Enterprise Keyless Authentication (WIF): Full support for Google Cloud Workload Identity Federation (WIF) and Application Default Credentials (ADC) via Gemini Enterprise Agent Platform (formerly Vertex AI) — zero long-lived API keys required!
Gemini Enterprise Agent Platform Billing Labels: Automatically tags Enterprise Agent Platform requests with component and repo (plus custom billing_labels like team=platform,cost_centre=engineering) for granular FinOps chargeback in BigQuery billing exports.
Supply-Chain & Runtime Hardening: Enforces immutable dependency lockfiles (uv run --locked), SHA-pinned internal actions, path-traversal containment, and automatic fork PR skipping.

Enterprise-Ready by Design: Security, Governance, and FinOps

When hobbyists pick a GitHub Action, they just want to paste an API key into a secret and see comments appear on their PR. When enterprise platform and security teams evaluate a GitHub Action, they ask a very different set of questions:

"How do we authenticate without storing static, long-lived API keys across 200 repositories?"
"How do we attribute AI spend back to specific business units, teams, and repositories in our Cloud Billing export?"
"What stops a malicious dependency drift or an untrusted fork PR from exfiltrating credentials?"

These aren't theoretical questions — this reviewer is already deployed in production at an enterprise organisation, and many of the capabilities below were forged directly from real-world enterprise governance requirements. Let's look at the key pillars.

1. Keyless Enterprise Auth with Workload Identity Federation (WIF)

Static API keys (GEMINI_API_KEY) are great for quick personal setups. But in an enterprise environment, long-lived credentials stored in GitHub Secrets are a compliance headache. Somebody has to rotate them, audit them, and worry about them leaking.

Because our action is built on the modern google-genai SDK, it natively supports Google Cloud Workload Identity Federation (WIF) with Application Default Credentials (ADC) with Gemini Enterprise Agent Platform (formerly Vertex AI).

Instead of generating a static key, your GitHub Actions runner requests a short-lived OIDC token from GitHub and exchanges it via google-github-actions/auth for an ephemeral Google Cloud access token scoped to a specific Service Account:

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      id-token: write # Required for WIF OIDC token exchange

    steps:
      - name: Checkout repository
        uses: actions/checkout@v6
        with:
          ref: ${{ github.event.pull_request.head.sha || format('refs/pull/{0}/head', github.event.issue.number) }}

      - name: Authenticate to Google Cloud via WIF
        uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: 'projects/123456789012/locations/global/workloadIdentityPools/${{ secrets.WIF_POOL_ID }}/providers/${{ secrets.WIF_PROVIDER_ID }}'
          service_account: '${{ secrets.GCP_SERVICE_ACCOUNT }}'

      - name: Run Gemini Review Action
        uses: derailed-dash/gemini-review-action@v1
        env:
          GOOGLE_GENAI_USE_VERTEXAI: "True"
          GOOGLE_CLOUD_PROJECT: "my-enterprise-project-id"
          GOOGLE_CLOUD_LOCATION: "global"
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          gemini_model: 'gemini-3.8-flash'

Why this matters for the enterprise:

Zero static secrets: Credentials live for minutes and expire automatically when the job finishes.
IAM & VPC-SC Governance: All Gemini API calls route through your Google Cloud project, meaning they respect your organisation's IAM policies, data residency regions, Cloud Audit Logs, and VPC Service Controls.

2. FinOps Transparency: Real Dollar Cost Estimation & Gemini Enterprise Agent Platform Billing Labels

ROI is paramount. If a solution costs too much or you can't measure what it costs, it's bad architecture.

In Part 1, our telemetry block reported raw token counts. That was useful, but as fellow GDE Sascha Heyer rightly pointed out when he contributed PR #33, developers and engineering leaders don't pay their cloud bills in tokens — they pay in dollars!

We upgraded the telemetry engine (gemini_review/pricing.py) to calculate and print the estimated dollar cost on every single review, broken down by uncached input, cached input (at the 90% discount rate), thinking/reasoning tokens, and response output tokens:

Notice a couple of deliberate engineering choices here:

No Silent Guessing: If you configure an experimental or future model that isn't in our pricing table yet, the action reports the token counts and omits the dollar figure rather than borrowing another model's rate. A missing number is obvious; a wrong number is dangerous.
Time-Boxed Introductory Rates: Models like gemini-3.8-flash have promotional introductory pricing ($0.75 / $3.75 per 1M tokens through 2026-12-31, reverting to $1.50 / $7.50 afterwards). We encoded the promotional expiry dates directly into the pricing engine data structures, and the review footnote explicitly states which rate was applied. And if your enterprise has negotiated custom flat rates or uses Batch/Flex tiers, you can override the table via GEMINI_RATE_INPUT and GEMINI_RATE_OUTPUT.

Answering the FinOps Question at Scale: Cloud Billing Labels (`billing_labels`)

Knowing that PR #42 cost $0.03 is great for a developer. But a Head of Platform Engineering needs to answer a different question: "What did AI code reviews cost across our 150 repositories this month, broken down by engineering team?"

You shouldn't have to scrape GitHub PR comments to answer a FinOps question. So we added native Gemini Enterprise Agent Platform Billing Labels (gemini_review/billing_labels.py).

Whenever you run on Gemini Enterprise Agent Platform (Vertex AI), the action automatically attaches sanitised GCP billing labels to every generate_content request:

component: gemini-review-action
repo: owner_repo

Even better, you can pass custom chargeback dimensions via the billing_labels workflow input:

      - name: Run Gemini Review Action
        uses: derailed-dash/gemini-review-action@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          billing_labels: 'team=platform,cost_centre=engineering,env=ci'

(Pro-Tip: We deliberately did not make the PR number a default label, because high-cardinality labels turn your BigQuery billing export into a noisy mess. And if you're using a Google AI Studio API key instead of Gemini Enterprise Agent Platform, the action cleanly omits the labels parameter.)

3. Supply-Chain Security & Fork PR Hardening

A code review action holds pull-requests: write permissions and runs against untrusted PR branches. If you aren't careful, that's a prime target for supply-chain attacks. Here is how we locked it down:

Enforced Lockfiles (uv run --locked): Previously, running uv run --project would silently resolve and rewrite uv.lock at runtime if pyproject.toml drifted. That meant even if an enterprise consumer pinned our action to an immutable 40-character Git commit SHA, a transitive PyPI dependency could theoretically change at runtime. So we enforced uv run --locked and pinned all nested setup actions (actions/setup-python and astral-sh/setup-uv) to exact commit SHAs.
Untrusted Fork PR Safeguards: By default, GitHub strips repository secrets from fork PRs to prevent untrusted contributors from accessing API keys. If an action tries to run automatically on a fork without secrets, it crashes with an authentication error and paints the contributor's PR with an ugly red ❌. Our starter workflows solve this gracefully:
- Clean skips on forks: The workflow guards automatic runs (github.event.pull_request.head.repo.full_name == github.repository), quietly skipping external forks so CI status checks stay green.
- Maintainer on-demand trigger: Once a repository maintainer (OWNER, MEMBER, COLLABORATOR) inspects the fork code, they can safely trigger Gemini by typing /gemini-review in a PR comment — which runs under their authenticated context with full access to secrets.
Path Traversal Containment: Every file path, Markdown image link, and skill reference loaded by the action is strictly validated against the workspace root. An attacker cannot craft a malicious Markdown link like ![diagram](../../../../etc/passwd) or a custom instruction path to trick the runner into reading files outside the repository.

Major Feature Deep-Dives Since Part 1

Now let's get into the really fun stuff! Here are the major architectural features we've engineered since publishing Part 1.

1. Multimodal Context Inspection, Visual PR Diffing & Screenshot Triage

Until recently, AI code reviewers had a massive blind spot: they were completely blind to anything that wasn't plain text.

If you updated an architecture diagram in docs/architecture.png, tweaked a UI component screenshot, attached a PDF specification, or opened a GitHub Issue with a screenshot of a broken button, a text-only reviewer saw nothing.

In our solution, we've unlocked Gemini's native multimodal superpowers across three distinct workflows:

A. Automatic Markdown Image & PDF Resolution

Whenever a Markdown file (README.md, DESIGN.md, ARCHITECTURE.md, or a blog post!) is included in the review context or modified in a PR diff, we scan the document for standard Markdown and HTML image references. We resolve the paths relative to the Markdown file, verify containment inside the repo, and attach the visual assets directly to the Gemini request. Now, when Gemini reviews your documentation updates, it actually looks at your architecture diagrams to verify that the diagram matches your code and prose!

B. Side-by-Side Visual PR Diffing

What happens when a PR modifies an existing architecture diagram, UI component snapshot, or application icon?

Most AI reviewers either ignore modified images completely or summarise them in separate, isolated passes — which completely loses subtle visual regressions.

Instead, our action retrieves both the "before" and "after" versions of any modified graphic and passes them side-by-side into a single Gemini turn. Because both images sit together in the same multimodal attention window, Gemini performs direct visual diffing — spotting accidentally cropped text, resolution degradation, broken UI alignment, or missing arrows in an updated architecture diagram!

C. Multimodal Issue Triage for Remote Screenshots

When users report bugs in GitHub Issues, they love pasting screenshots directly into the issue editor (which GitHub hosts at extensionless URLs like https://github.com/user-attachments/assets/<uuid>).

We upgraded our triage to extract remote HTTPS image URLs from both the issue body and discussion comments:

Safe Token Handling: Images in private repositories require GitHub credentials to view. The downloader attaches your GITHUB_TOKEN only to trusted GitHub domains — and strips it immediately if a link redirects to an external site.
Attack-Proof Downloads: Because issue descriptions are untrusted user input, we block risky URLs (like internal network IPs or cloud metadata endpoints), cap downloads at 20 MB, and fall back cleanly to text triage if an image is missing or unreachable.

D. Deterministic Image Downscaling (Saving Your Token Budget!)

Here's a classic "gotcha" from production: high-resolution screenshots and uncompressed PNGs can easily top several megabytes each. Shoving dozens of multi-megabyte images into a review prompt is a recipe for pain. Review request latency can spike towards GitHub Action timeout thresholds, you risk slamming into API request limits, and you waste tokens on pixels that add no extra value to the review.

To fix this, we added automated, deterministic downscaling using Pillow. Any image (.png, .jpg, .webp, .gif) larger than 600 KB is compressed to a much smaller file size. Cool, right?

2. Upgraded Default Model (`gemini-3.8-flash`) & Thinking Budget Controls

When I wrote Part 1, our default model was gemini-3.6-flash. Since then, we upgraded through gemini-3.7-flash and now default to gemini-3.8-flash.

We also introduced granular Reasoning & Thinking Budget Control via the thinking_level input:

      - name: Run Gemini Review Action
        uses: derailed-dash/gemini-review-action@v1
        with:
          gemini_api_key: ${{ secrets.GEMINI_API_KEY }}
          github_token: ${{ secrets.GITHUB_TOKEN }}
          thinking_level: 'low' # Options: low, medium, high, off, or integer budget (e.g. 2048)

How thinking budgets work:

Dynamic by Default (Recommended for PRs): When omitted, Gemini runs in dynamic mode, automatically allocating reasoning tokens based on the complexity of your diff.
FinOps Token Budget Limits (e.g. low or medium): Because thinking tokens are billed at the higher output token rate, cost-conscious teams can cap the maximum reasoning headroom to ensure predictable per-review spending on massive diffs.
Blazing Fast Issue Triage (thinking_level: 'off'): When running in triage mode (command: 'triage'), the model only needs to classify an issue and pick labels. Deep reasoning is complete overkill here. Setting thinking_level: 'off' forces thinking_budget=0, slashing triage latency to near-instant and cutting triage costs to fractions of a cent!

3. Smarter Sparse Mode: Bounded Dynamic Context Selection

In Part 1, when a repository exceeded 1.5 MB (Sparse Context Mode), the action attached the directory tree and static core files (README.md, pyproject.toml, etc.), and left it at that.

But what if your PR modifies, say, src/payments/stripe_webhook.py inside a 50 MB monorepo, but you also have relevant additional files in the repo, like src/payments/models.py and tests/payments/test_stripe.py?

To solve this, we introduced Bounded Dynamic Context Selection (gemini_review/context.py and gemini_review/repo.py):

Prioritised Rule Files & Core Context Budget Cap (max_core_context_bytes): In Sparse Mode, the action loads your core project documents. But what if a repository has a 2 MB README.md or dozens of markdown files? To prevent bulky documentation from blowing your token budget before code is even evaluated, we cap total core context at 500 KB and enforce strict intake ordering:
- Agent rules take precedence: Coding instructions and team guidelines (AGENTS.md, GEMINI.md, CLAUDE.md, .cursorrules) are prioritised at the very front of the queue so the reviewer always respects your project's rules.
- Manifests & architecture next: Core build manifests (pyproject.toml, package.json, go.mod) and root docs (README.md, ARCHITECTURE.md) fill the remaining budget up to the 500 KB ceiling.
Two-Stage Dynamic Sister Context Selection: In a 10,000-file monorepo, feeding every file path to an LLM wastes massive tokens before the review even starts. So we built a two-stage funnel:
- Stage 1 (Deterministic Ranking): A Python ranker parses the PR diff for import statements, directory proximity, and sister test/implementation filenames to bound the candidate pool to the top 500 files (max_candidate_files).
- Stage 2 (4-Tier Architectural Selection): A fast, structured call to Gemini picks up to 8 of the highest-value sister files from that pool across four architectural tiers: Tier 1 (direct import dependencies and base classes), Tier 2 (sister unit tests, fixtures, and schemas), Tier 3 (domain precedents in sibling modules), and Tier 4 (shared utilities and configuration helpers).
Static Override (extra_context_files): If you already know specific files you always want attached alongside every review, you can pass extra_context_files: 'src/core/security.py,docs/api-spec.pdf' and bypass the dynamic selector call entirely!

4. Extending Guardrails vs Replacing Prompts + Curated Skills Synchroniser

Originally, if you wanted to add a single team rule — like "All SQL queries must use parameterised inputs" — you had to copy the entire .github/commands/gemini-review.toml file into your repo. The problem? As soon as you forked the base prompt into your repo, you missed out on all the upstream prompt engineering improvements we shipped in later versions (like our 5-Axis Quality Evaluation Framework)!

The answer is to cleanly separate extending instructions from replacing them:

Extend (Recommended): Simply drop a Markdown file at .github/review-instruction-additions.md in your repo, or pass inline rules via the custom_instructions workflow input:

      with:
        custom_instructions: |
          - Ensure all database queries use parameterised inputs.
          - Verify that new API endpoints include Pydantic request validation.

The action keeps the full built-in 5-axis quality rubric, persona overlays, and schema rules, and cleanly appends your custom guardrails!
Equip Custom Agent Skills (.agents/skills/): Beyond simple markdown rules, you can mount full Agent Skills directly into your repository. The action automatically discovers skills placed in .agents/skills/ — whether they are custom coding guidelines, security checks, or official skills from the google/skills catalog — and equips Gemini to enforce those exact domain practices during reviews.
Bundled One-Command Installer Skill: I had already created an agent skill called install-gemini-code-review-action, in my dazbo-agent-skills repo. Now, we also mirror this skill directly inside our reviewer repo. You can install the skill straight from the action repo:

npx skills add derailed-dash/gemini-review-action -y -g --skill install-gemini-code-review-action

Once installed, simply prompt your agent: "Set up Gemini code review in this repository." The agent detects any existing workflows, interviews you on your preferred model, auth method (WIF vs API key), and persona, and generates the workflow files for you!

5. Workflow Polish: Auto-Resolving Threads & Filtering Competing Bots

Two of my favourite quality-of-life improvements came directly from real-world friction on busy pull requests:

A. Auto-Resolving Addressed Review Threads

When you push a fix to a PR, the action re-examines prior review comments, confirms the issue has been resolved, and marks it fixed.

However, if your repository enforces GitHub's "Require conversation resolution before merging" rule, someone still has to manually click "Resolve conversation" on every single thread before you can merge — even though the bot already agreed you fixed it!

With resolve_addressed_threads: 'true', the action automatically clicks "Resolve" on its own threads as soon as Gemini verifies the fix. It stays strictly in its lane: it only touches threads the bot created, never touches human comments, and gracefully warns you if your GitHub token needs additional permissions to resolve conversations.

B. Excluding Another Bot's Comments (`exclude_comment_authors`)

What happens if your team runs two AI reviewers on the same repo (for instance, claude[bot] alongside gemini-review-action)?

Because our action inspects existing PR comments to avoid repeating itself, it was picking up the other bot's review notes too. That meant Gemini ended up reading the other bot's homework and parroting the exact same points! You lost your independent second opinion, and you paid for hundreds of extra prompt tokens just to re-digest the other bot's prose.

Adding exclude_comment_authors: 'claude[bot]' filters out specified bots before building the prompt. Human feedback stays intact, and Gemini delivers a genuine, unbiased second opinion.

Battle-Hardened in Production: War Stories & Bug Fixes

Here are a few real-world production bugs we hit since Part 1 — and how we engineered permanent fixes for them.

War Story 1: The Generated Schema That Blew the Token Budget

The Problem: A pull request touching 30 files crashed without posting a review, failing with a token limit error. The culprit? A tiny 4 KB diff buried inside a 2.9 MB auto-generated openapi.json file. Because our prompt builder attached the entire current content of every modified file alongside its diff, that single generated file consumed the entire Gemini token window on its own!
The Fix: Rather than playing whack-a-mole adding filenames to an ignore list, we capped all attached source files at 128 KB with a clean truncation marker (diff patches themselves are never capped). If a massive prompt still approaches the model's budget, the action gracefully sheds peripheral repo context first, ensuring the core diff review always succeeds.

War Story 2: GitHub's Concurrency Trap (and How Our Bot Caught It)

The Problem: If a developer pushes three commits in quick succession, you don't want to pay Gemini to review all three. We added a standard GitHub Actions concurrency block with cancel-in-progress: true to kill redundant runs. But we hit a snag: whenever someone left an ordinary comment on the PR, GitHub cancelled the running review! Workflow-level concurrency evaluates before the job filters kick in, treating any comment as a new run.
Caught by Our Own Bot: We tried tweaking the concurrency key, but when we opened the pull request, our own Gemini Review Action reviewed it and pointed out our fix created a new race condition in the opposite direction!
The Fix: Moving concurrency down to the job level ensures GitHub only cancels runs for actual review triggers on the same PR:

jobs:
  review:
    concurrency:
      group: gemini-review-${{ github.event.pull_request.number || github.event.issue.number }}
      cancel-in-progress: true

War Story 3: Making "Commit Suggestion" Actually Work

The Problem: Developers love clicking GitHub's "Commit suggestion" button directly from an inline review comment. But LLMs are notorious for trimming leading whitespace or getting multiline replacement ranges slightly wrong — meaning a one-click commit can easily botch your indentation or overwrite the wrong lines.
The Fix: Before posting an inline suggestion, we run a deterministic sanitiser over it. It matches the source file lines, restores stripped indentation, and corrects any off-by-one replacement ranges. When a developer clicks that button, the resulting commit is clean, properly indented, and builds first time.

War Story 4: Surviving Transient GitHub Outages

The Problem: During an incident where the GitHub API threw intermittent 503 Service Unavailable errors, the action successfully generated reviews from Gemini, only to crash when posting them to GitHub. We’d paid for the tokens, but the reviews were lost into the ether.
The Fix: We wrapped all GitHub comment and review posting in an exponential backoff retry. A review you've already paid for is never thrown away over a temporary API hiccup.

Wrapping Up

Looking back at how far Gemini PR Review & Triage Action has come since that first weekend build in July, I'm genuinely blown away. What started as an emergency lifeboat after the sunsetting of run-gemini-cli has grown into a comprehensive, multimodal, enterprise-grade engineering harness.

Whether you're a solo hobbyist who wants Emperor Palpatine or Rick Sanchez roasting your Python diffs for $0.02 a pop, or an Enterprise Cloud Architect rolling out keyless WIF authentication, BigQuery billing attribution, and architectural guardrails across hundreds of corporate repositories — this action is built for you:

Beyond CI/CD: Bringing Gemini Review into Your Agentic Loops

While we designed this action primarily to automate GitHub pull request reviews, the modular architecture we've engineered under gemini_review/ unlocks an exciting new frontier: inner-loop agent verification.

In my recent deep dive, Loop Engineering in the Harness: Autonomous, Self-Correcting Systems, I explored how reliable agentic architectures rely on tight, deterministic feedback loops (Generate → Verify → Correct → Converge) to eliminate hallucinated code and regressions before human intervention.

Because gemini_review is structured as a standalone, lightweight Python package executable via uv, you don't have to wait for a remote CI push to run it. You can wire the review engine directly into your local development harness as a pre-commit or pre-push verification step. Your local coding agent can execute a local review pass against its own unstaged git diff, parse the structured severity findings, and self-correct regressions with zero session bias — before anyone else ever inspects the code!

Install It!

If you haven't tried it yet (or if you installed v1.1 back in July and haven't looked at the new inputs since!), now is the perfect time to upgrade:

Equip your AI agent in seconds, then prompt it: "Set up Gemini code review in this repo":

npx skills add derailed-dash/gemini-review-action -y -g --skill install-gemini-code-review-action

Or grab the starter workflows directly from derailed-dash/gemini-review-action.
Give the repository a star ⭐ on GitHub — it massively helps others discover the project, and it helps me too!

Let me know in the comments how you get on, what persona you're running in your pipelines, and what features you'd love to see next!

Before You Go

Please share 📢 this with anyone that you think will be interested. It might help them, and it really helps me!
Please leave a reaction or comment 💬. Interaction is good!
Add a star ⭐ on my repos!
Follow 👉 and subscribe 🔔, so you don’t miss my content.

References and Useful Links

Loop Engineering in the Harness: Autonomous, Self-Correcting Systems

Darren "Dazbo" Lester — Mon, 12 Oct 2026 21:36:09 +0000

You are in Part 2 of the series "Beyond Vibe Coding: The Engineering Blueprint for Reliable AI Agents"

🗺️ The Series Roadmap: Beyond Vibe Coding

In 2026, software development is drowning in fragmented buzzwords: Harness Engineering, Loop Engineering, Context Engineering, Spec-Driven Development, Evaluators, and Sandboxes. Are they competing frameworks? Redundant prompt techniques? Or something fundamentally new?

This four-part series unifies these concepts into a single, cohesive architectural blueprint for building software with AI without writing code manually:

Part 1: From Vibing Chaos to Reliable Agents: The What, Why, and How of Harness Engineering We diagnose the hangover of vibe coding, unpack the paradigm shift of shifting developer interventions left, establish our bedrock formula (Agent = Model + Harness), explore the Lewis Hamilton motorsport analogy, and deconstruct the deterministic components that make up a production developer environment.

Part 2: Loop Engineering in the Harness: Autonomous, Self-Correcting Systems (This Article) We fire up the dynamic runtime engine of the harness: deconstructing the core loop components, establishing hybrid evaluation rubrics (deterministic tests + LLM goal fidelity + tool trajectory verification), and applying the Ratchet Principle.

Part 3: Spec-Driven Development For-the-Win: Disposable Code, Living Blueprints, and Building Like a Boss (Coming Soon) We explore Spec-Driven Development (where code is disposable and specifications are the single source of truth), master Google Antigravity's unified harness and interactive slash commands (/grill-me, /plan, /goal, /boost, /learn), and combine formal specs with tactical workflows via the 4-Phase Hybrid Power Pattern.

Part 4: Scaling the Harness: Practical Loop Patterns, ADK 2 Graphs, Recursive Harness², and Harness Maintenance (Coming Soon) We bring everything together with practical loop patterns you can wire into any repo (from declarative Markdown and loopy to Google ADK 2 graphs), keep context clean across iterations with short-lived subagents, explore Google Research's recursive Harness² framework, and cover ongoing harness maintenance.

The "Generate and Fix" Trap: Stop Being the Human Correction Loop

Howdy friends, and welcome back!

In Part 1, we established the bedrock formula of modern agentic engineering:

Agent = Model + Harness

We deconstructed the core deterministic components of the harness: hierarchical context rules (AGENTS.md / GEMINI.md), living version-controlled state, curated Model Context Protocol (MCP) tools, on-demand skills, sandboxing, and observability. This is how we engineered the race car chassis.

But wait... How does the work actually get done?

In simple, naive AI interactions, developers issue a prompt, get some output, and then typically course-correct. Maybe the developer copies the output from the terminal into the chat and asks for a fix.

Notice what is happening here: we have an iterative cycle of action, verification, and course-correction. You cannot escape it. But in an ad-hoc vibe coding workflow, you are the loop. You act as an exhausted organic clipboard, forcing yourself to micromanage, inspect, and babysit every single turn. If you're doing that, you haven't automated much; you're just paying a subscription to watch a terminal like a nervous ferret.

Loop Engineering automates that execution cycle.

Instead of forcing a human to watch and correct every turn, the loop enables our agent to cycle through action, verification, and course-correction autonomously within the harness. The agent executes the code, runs the automated test suites, evaluates its work against strict rubrics, refines its hypotheses, and makes corrections... On its own!

Crucially, this does not mean ejecting the human entirely. It means moving from continuous babysitting to strategic governance: Human-in-the-Loop does NOT mean Human-in-Every-Turn. The agent executes the rapid, deterministic feedback cycle autonomously, and only pauses to escalate to the human conductor at predefined escalation points — such as hitting persistent evaluation plateaus, encountering ambiguous requirements, or proposing irreversible, high-risk actions.

A Crucial Distinction: The Development Workbench, Not Runtime Infrastructure

When we talk about loop engineering, the goal is not usually to ship autonomous, self-modifying while-loops into a live, customer-facing production application. The value of harness engineering and loop engineering is that it provides a disciplined feedback mechanism during the development phase to build software that is production-grade. The loop is the automated forge where code is hammered, tested, and tempered; what you actually deploy to the cloud is resilient, production-ready software.

In tokenomics terms, this aligns to so-called Spec Spend (as explored in my upcoming enterprise whitepaper, The Agentic Revolution). Burning tokens in the developer harness to explore hypotheses, run tests, and self-correct is a high-value, high-leverage investment. Spending a couple of dollars in developer Spec Spend to forge a hardened application prevents catastrophic regressions and uncontrollable costs in production Run Spend.

Core Components of an Engineered Developer Loop

To move beyond fragile trial-and-error, an engineered agentic loop requires distinct, interconnected components:

1 — Goal (The Anchor): A clear, unambiguous statement of what the agent must accomplish. In long-running autonomous runs, context compression can cause the model to drift. A resilient harness restates the core goal on every single iteration, keeping the agent firmly anchored to its original objective.

2 — Context (The Environment & Grounding Data): Everything the agent knows about the world before taking an action. This context extends far beyond prompt templates; it is the total information environment available to the loop:

Standing Architectural Rules & Guardrails: Hierarchical instructions, coding standards, and operational boundaries drawn from GEMINI.md, AGENTS.md, and activated Agent Skills.
Workspace Data & Local Fixtures: Source code, schema files, seed datasets, sample payloads, and test mocks residing directly in the repository.
Dynamic Knowledge & Database State: Grounding information retrieved on demand via MCP tools or APIs, such as querying living documentation from (say) Confluence or Google Drive, inspecting issues on GitHub, or introspecting schemas and retrieving data from databases.

💡 Decoupling Engineering Guardrails from Application Specs

A crucial architectural discipline in production harnesses is separating the Application Goal Specification from the Engineering Discipline. Naive prompt engineering often conflates the two, burying feature requirements beneath paragraphs of repetitive coding hygiene instructions. In reality, engineering guardrails (e.g. Python standards, mandating TDD approaches, Pydantic input parameterisation) should be independent of any single application spec. They represent reusable, global, organisation-, domain- or team-level engineering policies.

Centralising them in persistent workspace configurations (GEMINI.md, AGENTS.md) and reusable Agent Skills means you define them once and govern them centrally across all projects. The feature specification stays lean and domain-focused.

3 — Tools (The Levers): The restricted set of actions the agent is permitted to execute, including sandboxed shell commands and MCP server tools. The harness strictly limits tool access to reduce blast radius and limit tool choice paralysis.

4 — Evals (The Objective Judge): The scoring mechanisms that evaluate the progress of each iteration. Without automated evals, the agent is flying blind. A robust harness evaluates across three dimensions:

Deterministic Output Checks: Mechanical unit tests, integration suites, and static linters (pytest, ruff, codespell) that verify the compilation, syntax, and functional correctness of the generated artifacts.
Tool Trajectory & Process Verification: Inspecting how the agent reached the result. Did it invoke only approved tools in the expected sequence? Did it respect tool schemas without hallucinating arguments? Did it avoid thrashing loops or calling forbidden APIs?
Semantic LLM-as-a-Judge Analyses: Using models to evaluate the qualitative requirements — crucially including Goal Fidelity (verifying whether the solution actually delivers what was requested) and architectural cleanliness. While semantic autoraters can use rubric scales or qualitative feedback, framing them as binary yes/no assertions is often a very effective approach to eliminate subjective score drift.

5 — Memory (Loop History & Scratchpad): The structured log of what has been attempted across preceding iterations. The agent records what worked, what failed, and the progression of evaluation scores over time. In a well-engineered harness, this persistent scratchpad prevents the model from repeating known dead-ends or thrashing in circular loops.

6 — Iteration Discipline (The One-Change Rule): This is about applying the scientific method to autonomous iteration. This discipline applies specifically to changes evaluated for semantic value. When iterating against semantic autoraters, the loop instructs the agent to modify one thing at a time before re-scoring. If multiple semantic changes are introduced at once, causal observability collapses: if a rubric score drops, the agent cannot tell which alteration caused the regression. Conversely, purely mechanical deterministic fixes (resolving compiler syntax, fixing lint warnings from ruff or codespell, and formatting) can and should be batch-remediated in a single turn.

7 — Escalation Protocol (The Safety Valve): Explicit operational triggers that halt the loop and request human intervention. For example, if an agent encounters conflicting specifications, hits three consecutive evaluation failures, or proposes an irreversible action (e.g. deleting cloud infrastructure), it must not hallucinate a guess. It must package its findings, present a reasoned recommendation, and yield control to the human conductor.

8 — Stopping Condition (The Finish Line): Clear, programmatic exit criteria that tell the loop when execution is complete. Such as:

100% of deterministic checks and semantic rubric assertions passing with zero lint warnings.
Target state verification: the critique model explicitly certifies that the initial goal has been fully met.
A convergence plateau where successive iterations produce negligible score improvements.
Hard circuit breakers, such as reaching a maximum iteration count (e.g. 5 loops) or a predefined token spend limit.

Is It a Loop Bug or a Harness Bug?

When an autonomous agent goes off the rails during development, we often waste days trying to fix the wrong things.

Use this simple litmus test:

If you can resolve the issue by refining the prompt, sharpening the goal, updating the rubric, or adjusting the stopping condition → It is a Loop bug.

If resolving the issue requires changing tool definitions, adjusting sandbox permissions, modifying execution timeouts, or intercepting runtime errors → It is a Harness bug.

Don't attempt to solve a harness problem by writing a more pleading prompt. Fix the layer that actually broke!

The Ratchet Principle: Engineering Continuous Improvement

What happens once you diagnose an edge case or failure that wasn't caught by your initial harness?

This brings us to the operational crown jewel of harness engineering: The Ratchet Principle.

When an AI agent stumbles, makes an architectural mistake, or introduces a subtle bug, the amateur response is to re-prompt the model in the chat: "No, don't do that, use the new API method instead."

That is an utter waste of a lesson. The moment that conversation ends, that context evaporates into thin air. In tomorrow's session, on a new branch, or when a teammate runs a similar task, the agent will walk directly into the exact same trap.

Under the Ratchet Principle:

Whenever an agent makes a mistake, you update the harness, not just the prompt.

Did the agent use an outdated API parameter? Update the workspace GEMINI.md or add an authoritative type schema.
Did the agent forget to handle a specific error code? Add a permanent check to the binary evaluation rubric.
Did the agent create an unformatted commit? Add a pre-commit hook to your Git harness.
Did the agent struggle with a Google Cloud product? Load the corresponding skill from the google-cloud-developer plugin.

Like a mechanical ratchet, every single failure permanently tightens the system. The harness clicks forward one notch. Once a rule or rubric check is committed to your repository, that specific failure mode is eliminated forever. Over time, your development harness becomes an impenetrable repository of institutional engineering wisdom.

Why Loops Work: The Power of Feedback

Why go through the effort of building a multi-component loop instead of relying on a single, well-crafted prompt?

I created an application that demonstrates building an application agentically, and compares with and without harness and loop, side-by-side.

We'll deep-dive into this shortly. But for now, I'll give you the key findings from this application, which align with industry findings. Essentially, if you have a harness with a loop, these are the outcomes:

You use fewer tokens.
The overall time to get to a solution is dramatically reduced.
The human input required is massively reduced.
The overall cost to produce the solution is significantly reduced.
The quality of your solution, and its alignment to your requirements, is much better.
Most importantly — the solution is more likely to actually work.

TL;DR — single-pass prompting is gambling that an LLM will get dozens of interconnected variables right on the first try.

In contrast, wrapping the model in an automated loop mirrors the exact rhythm experienced software engineers use every day: propose a targeted change, run the tests and evals, feed the diagnostics straight back into the next turn, and iterate until the solution passes. The loop keeps the model honest, converges on working code dramatically faster, and stops intermediate errors from compounding into an unrecoverable mess.

Three Traps to Avoid

However, naive loops without rigorous harness constraints may fall prey to some common loop traps:

1 — The Premature Exit:

The agent runs superficial tests, assumes everything works because there were no syntax errors, and prematurely declares victory.

Neutralised by: Mandatory TDD gates and non-negotiable passing thresholds on automated test suites.

2 — The Sycophantic Yes-Agent:

We all know that LLMs can be hopelessly sycophantic.

Q: "Do I look good in this shell suit?"

A: "Why yes, Dazbo! You look so hunky wearing that."

When using an LLM to rate the output of a loop, the model easily falls into the same trap — uncritically praising the worker agent's output.

Neutralised by: Structuring evaluations as strict, binary assertions and verifiable code artifacts.

3 — The Bottomless Cash Pit:

An unachievable rubric threshold or a brittle stopping condition traps the agent in a recursive loop, repeatedly modifying the same file and burning through hundred-dollar token budgets without making forward progress. While developer Spec Spend is meant to be exploratory, an unconstrained loop turns healthy investment into an uncontrolled financial bonfire.

Neutralised by: Stall detection, plateau convergence checks, and hard iteration circuit breakers.

The Hybrid Evaluation Rubric (Deterministic + Semantic)

One of the biggest mistakes teams make when building agent loops is relying on fluffy, subjective evaluation prompts: "Rate the quality of this code on a scale of 1 to 5."

Models are notoriously inconsistent when asked for qualitative ratings; what scores a 4 on Tuesday might score a 2 on Wednesday. In contrast, binary rubrics convert these fluffy judgments into repeatable deterministic results. So let's just turn the evaluations into verifiable yes/no questions!

Furthermore, as Google AI leaders like Shubham Saboo have pointed out in Finally, Loop Engineering Explained when contrasting loops with traditional prompt engineering, reliable loops must automate what is checkable — and that begins with testing whether the generated output actually achieves the goal that was set.

The goal is not just passing unit tests and being clean of linting errors. We also need to be sure that the solution actually delivers the feature requested.

For this reason, our evaluation rubric should combine deterministic checks with semantic checks. The semantic checks are executed by a critique agent or LLM-as-a-judge autorater.

And we must evaluate tool trajectory alongside code execution. You cannot evaluate only the final artifact; the harness must verify how the agent reached the result. Tool trajectory evaluation operates across two complementary layers:

Deterministic Trajectory Evaluation (Mechanical Trace Inspection): Code-level validation inspecting the execution trace without using an LLM. Did the agent invoke only authorised tools from its allowlist? Did arguments strictly satisfy JSON parameter schemas? Did it follow mandatory prerequisite ordering (e.g. running the test suite before attempting to commit code)? Did it stay within maximum tool call budgets rather than entering an unconstrained loop?
Semantic Trajectory Evaluation (Reasoning & Efficiency): Evaluated by a critique agent or LLM judge. Did the agent select the most appropriate and efficient tool for the problem, or did it take an absurdly convoluted detour (e.g. running fifteen individual file-read calls instead of a single targeted grep)? When a tool returned an unexpected error or empty result, did the agent reason soundly about the failure and adapt its strategy, or did it flail repetitively?

An agent that arrives at a working file after making ten redundant, unapproved tool calls or taking dangerous exploratory detours is an operational failure.

The Anatomy of a Production-Grade Evaluation Rubric

Here is a simple example; a 10-check rubric illustrating how deterministic and semantic checks — across both code and tool trajectories — work together:

# Evaluation Rubric

## Part A: Deterministic & Static Checks (Automated via Test Runners, Linters & Trace Inspectors)

| ID | Check (1 = True, 0 = False) | Evaluation Method | Result |
|:---|:---|:---|:---:|
| 1.1 | All unit tests in `tests` pass cleanly? | `pytest` runner | [ ] |
| 1.2 | `uvx ruff check .` and `uvx codespell` report zero errors or warnings? | Static analysis CLI | [ ] |
| 1.3 | Function signatures use PEP 585 standard type hints (e.g. `list[str]`, `dict[str, Any]`)? | Linter | [ ] |
| 1.4 | All database queries use parameterised inputs (no raw f-strings or string concatenation)? | Static analysis / AST | [ ] |
| 1.5 | **Deterministic Trajectory Conformance:** Did the agent invoke only authorised tools, satisfy parameter schemas, respect tool call limits, and follow mandatory prerequisite ordering (e.g. test before commit)? | Harness Trace Inspector (Code) | [ ] |

## Part B: Semantic Yes/No Analyses (Evaluated via LLM-as-a-Judge / Critique Agent)

| ID | Binary Semantic Assertion (1 = True, 0 = False) | Evaluation Method | Result |
|:---|:---|:---|:---:|
| 2.1 | **Target State Completion (Goal Fidelity):** Does the generated solution demonstrably deliver all functional capabilities and explicit deliverables declared in the goal statement, without omitting mandatory acceptance criteria? | Semantic Judge | [ ] |
| 2.2 | **Scope Discipline (Anti-Hallucination):** Does the solution achieve the goal without generating unrequested speculative abstractions, hallucinating unused helper modules, or modifying files outside the agreed boundary? | Semantic Judge | [ ] |
| 2.3 | **Trajectory Efficiency & Tool Reasoning:** Did the agent choose sensible, direct tool pathways to solve the problem rather than taking convoluted detours or repeatedly retrying failed tool strategies without adaptation? | Semantic Judge | [ ] |
| 2.4 | **Architectural Integrity & Interface Boundaries:** Does the code maintain clean boundaries, preventing internal database implementation details or raw connection strings from leaking into public interfaces or caller errors? | Semantic Judge | [ ] |
| 2.5 | **Design Rationale & Intent:** Does the module-level docstring clearly explain the architectural *why* (why this pattern was chosen over alternatives) rather than merely restating what the code does? | Semantic Judge | [ ] |

**Passing Criteria:** 10 / 10 (100% pass required before code can be committed).
**Iteration Policy:** Failures on code, test suites, or sub-optimal tool trajectories feed diagnostic feedback into the next turn for autonomous remediation.
**Hard Stop (Human Escalation):** The harness only aborts and alerts the developer if the agent breaches security boundaries (e.g. unapproved destructive commands), enters an unrecoverable tool thrashing loop, or reaches the maximum iteration limit (5 loops).

Notice how this structure enforces discipline across every dimension:

Checks 1.1–1.5 verify mechanical hygiene (syntax, compilation, test passage, and deterministic tool trajectory allowlists/orderings).
Checks 2.1–2.2 verify Goal Fidelity — comparing the candidate output directly against the initial user intent. If the agent forgot batch processing or wandered off into speculative refactoring, Check 2.1 or 2.2 drops to 0, and the loop refuses to exit.
Check 2.3 verifies semantic tool trajectory efficiency — ensuring the agent didn't burn tokens on irrational intermediate actions.
Checks 2.4–2.5 verify semantic architecture, error safety, and living documentation quality.

By presenting the agent with this exact markdown rubric, the model can self-score its work after every turn. It doesn't wonder whether its output is "good enough"; it knows with precision whether it satisfied the criteria and achieved the goal.

No Arbitrary Point Ceiling

While our example shows 10 checks for clear illustration, let's avoid any misconceptions: an evaluation rubric does not have an arbitrary 10-point ceiling. In practice, your rubric can have whatever point total you want. For example, you might also include:

Frontend contract checks: Verifying TypeScript interface alignment, component contracts, and state store mutations.
API wiring verification: Confirming route registration, middleware attachment, payload serialisation, and HTTP status code mappings.
Latency bounds: Asserting that mock or integration calls stay strictly within defined latency budgets (e.g. 95% in under 250ms).
Security invariants: Enforcing parameterised queries, sanitised inputs, absence of leaked credentials or stack traces, and zero-trust egress policies.

Side-by-Side Demo: The Harness Engineering Workbench

Theory is cheap. Let's prove it!

To demonstrate the quantifiable difference between raw vibe coding and disciplined loop engineering, I built an open-source, interactive, split-screen evaluation workbench: the Harness Engineering Demo.

The workbench pits two autonomous tracks against each other in real time, each running concurrently with the same model. (The demo uses Gemini 3.8-Flash out-of-the-box, but this is configurable.)

The Unharnessed Track — Vibe Coding: A raw single prompt containing the user specification is dispatched directly to the model. We supply no additional workspace rules or guardrails, and no specialised skills. There is no autonomous loop and no iterative self-healing. We evaluate the output once, at the very end.
The Harnessed Track — Loop Engineering: An autonomous multi-turn loop executes in an isolated workspace. We provide the same specification prompt as before. But this time we also provide additional context and guardrails, we equip the agent with relevant skills, and we evaluate each iteration with a 14-point rubric.

What is the demo actually building? Well, the specification is for the non-trivial task of building a "Cosmic Trivia & Strategy Conquest Game", a full-stack sci-fi game featuring a FastAPI backend, a directed graph of galactic sectors, turn-based combat, dynamic AI trivia generation, and an interactive browser-based star map with real-time HUD metrics and combat dialogues.

The Harness: Context, Skills, and Living Memory

Let's start by looking at the supporting context we supply (harness/harness_context.md). This would typically be part of your global reusable context (e.g. AGENTS.md or GEMINI.md) that you use as an engineer, as a team, or even as an organisation:

# Engineering Context & Harness Guardrails

## Persona & Role

You are a Principal Software Engineer and Systems Architect. You produce modular, production-grade, and self-documenting code following strict engineering standards. You practice test-driven development, enforce strict interface contracts, and design systems with clear separation of concerns.

## 1. Environment & Coding Standards

- **Python Version**: Python 3.13 standard.
- **Type Hinting**: Strict PEP 585 (use built-in `list[str]`, `dict[str, Any]`, `tuple[int, ...]`, never use deprecated `typing.List` or `typing.Dict`).
- **Scope Discipline**: Only create required files specified in the task goal or architecture. Do not generate speculative helper files, hallucinated third-party dependencies, or dead code.

## 2. Test-Driven Development (TDD)

- **Mandatory Test Suite**: Author a comprehensive unit test suite in `tests/` before or alongside implementation covering core domain logic, edge cases, and state transitions.
- **Verification Gate**: Verify that all unit tests pass cleanly via `pytest` before declaring any task complete.

## 3. Backend Architecture & Security Guardrails

- **Parameterisation**: All API request bodies and input parameters must use structured Pydantic models with input validation. Never accept raw unvalidated dictionaries or execute dynamic evaluation (`eval`, `exec`).
- **Error Handling**: Invalid inputs, illegal state transitions, or domain rule violations must trigger actionable HTTP 400 responses without leaking internal stack traces.
- **Architectural Integrity**: Maintain strict modular boundaries. Keep domain logic pure and independent of HTTP transports, database drivers, or UI presentation. Expose REST endpoints with explicit routing.
- **Documentation**: Include clear top-of-module docstrings explaining architectural intent and design rationale ('why' over 'what').

## 4. Autonomous Harness Workflow & Tooling Protocol

- **On-Demand Skill Discovery & Activation**: Inspect the `<available_skills>` catalogue in your harness context; when `# ACTIVATED ENGINEERING SKILLS` is already loaded in your context, apply those skills directly without re-activating them.
- **Initial Turn Synthesis (Iteration 1)**: Respond directly in Markdown with a concise **Architectural & TDD Verification Plan** (150–250 words) detailing module boundaries, Pydantic request/response schemas, and the core unit test cases (`tests/`), concluding with a single brief (~15-line) Python code block illustrating the core Pydantic request/response contracts (omit full multi-file implementations).
- **Automated Gate Verification**: At the end of each iteration turn, your generated deliverables are materialised into the workspace and the harness evaluation gate executes `pytest`, `ruff`, and all mechanical and semantic rubric checks, recording a structured **Iteration Evidence Receipt** in `LIVING_MEMORY.md`.
- **Targeted Self-Healing from Living Memory (Iteration 2+)**: When living memory diagnostics from a prior iteration are present in your context, respond directly in Markdown with a concise **Self-Healing Remediation Summary** (100–200 words) citing each failed check ID, its root cause, and the targeted code fix applied.

Note how this additional context defines the engineering persona, enforces our coding standards, mandates test-driven development (TDD), describes error handling requirements, captures how we want code documentation written, and establishes the autonomous loop workflow.

Also, because we want output of each loop to guide the next efficiently, this particular loop instructs the agent not to dump full multi-file implementations into the conversational stream. Instead it asks for a succinct summary of waht went wrong and how we might remediate next time.

Crucially, this is all reusable, project-agnostic context rather than context coupled to the application specification.

Next, observe that the harness has a number of specialised skills available in harness/skills/:

api-and-interface-design
gemini-api-dev
test-driven-development

Rather than hardcoding these skill names into harness_context.md or pre-loading every skill's full Markdown instructions into the startup prompt, the harness dynamically scans the SKILL.md YAML frontmatter (name and description) in harness/skills/ and injects a lightweight <available_skills> catalog. The agent inspects this catalog against the specification and invokes activate_skill on demand to load only the instructions it needs.

Finally, our harness maintains living memory: a persistent feedback ledger stored at harness/output/LIVING_MEMORY.md. When an iteration fails, the exact rubric diagnostics, failed check IDs, and remediation hints are recorded to LIVING_MEMORY.md and reinjected into the next turn's prompt alongside the original specification. This is what enables surgical self-healing rather than blind guessing.

Under the Hood: Orchestrating the Loop with Google ADK

To ensure a fair, apples-to-apples comparison, both tracks in the workbench are executed through the Google Agent Development Kit (google-adk) using Runner and InMemorySessionService. This isolates the impact of the Harness rather than comparing different SDK runtimes:

Track 1 — Unharnessed (app/agents/unharnessed.py): Runs a bare ADK Agent(instruction="", tools=[]) in a single pass. It receives only the raw specification from specs/cosmic_conquest_spec.md with no persona, no skills, and no verification tools.
Track 2 — Harnessed (app/agents/agent.py & app/agents/harnessed.py): Separates pure ADK agent definitions (agent.py, compatible with adk web, adk run, and adk eval) from the SSE runner (harnessed.py), orchestrating an ADK LoopAgent(max_iterations=5) composed of two sub-agents operating over shared session state (session.state):
1. Builder LlmAgent (harnessed_builder_agent): Equipped with our harness_context.md, the <available_skills> catalogue, five session-scoped ADK FunctionTools (activate_skill, write_workspace_file, read_workspace_file, run_pytest, run_ruff_check), and an after_agent_callback (materialise_builder_output_callback) that materialises generated files into the isolated workspace. Each tool operates on tool_context.state["workspace_path"], injects activated skills into tool_context.state["skills_context"], and appends deterministic audit entries to tool_context.state["tool_trajectory"].
2. Custom Gate Agent (RubricEvaluationGateAgent(BaseAgent)): A pure evaluation and escalation gate that executes pytest and ruff, runs the 14-point rubric evaluator (loading semantic criteria declaratively from harness/RUBRIC.md), persists diagnostics to LIVING_MEMORY.md, and yields EventActions(escalate=should_escalate, state_delta=...). When escalate=True is emitted (on a 14/14 pass or plateau), the parent ADK LoopAgent terminates cleanly; otherwise, the updated living_memory_feedback state flows automatically into the builder agent's next iteration.

Programmatic Exit Conditions & Circuit Breakers

In autonomous loop engineering, you must never allow an agent to loop indefinitely or guess when it has finished. The workbench's RubricEvaluationGateAgent enforces three strict programmatic exit conditions:

Target Gate Pass (Clean Exit): To eliminate subjective "good enough" assessments, the workbench implements a rigorous, two-tier 14-point rubric schema. We will exit the loop upon achieving a flawless 14 / 14 (100%) rubric score across all deterministic and semantic checks.
Hard Iteration Cap (Spend Circuit Breaker): A hard limit of 5 iterations (MAX_ITERATIONS = 5). If the agent cannot satisfy all checks within five turns, execution halts immediately to prevent runaway token spend.
Convergence Plateau (Stall Detection): If the rubric score fails to improve across 3 consecutive turns (PLATEAU_LIMIT = 3), the loop aborts early rather than thrashing in circular remediation attempts.

Here is the exact production rubric configured in our workbench:

# Production Evaluation Rubric: Cosmic Conquest

## Tier 1: Deterministic Mechanical Sensors (8.0 Points)

| ID | Category | Check | Evaluation Method |
|:---|:---|:---|:---|
| 1.1 | Deterministic | Unit Tests Passage | `pytest` runner |
| 1.2 | Deterministic | Static Analysis (Ruff) | `ruff check .` |
| 1.3 | Deterministic | PEP 585 Type Hints | AST Inspector (`list[str]`, `dict[str, Any]`) |
| 1.4 | Deterministic | Parameterised Input Safety | AST Inspector (`eval()`, `exec()`) |
| 1.5 | Deterministic | Deterministic Tool Trajectory | Harness Trace Inspector |
| 1.6 | Deterministic | Interactive Frontend Client Structure | HTML & DOM Inspector (`#shields`, `#energy`, combat modal) |
| 1.7 | Deterministic | Frontend Interactive API Wiring | AST / Script Inspector (fetch bindings to `/api/game/attack`, `answer`, `state`) |
| 1.8 | Deterministic | Dynamic API Contract & Progression Topology | Dynamic TestClient Boot (FastAPI startup & valid progression targets) |

## Tier 2: Semantic Goal Fidelity & Ergonomics (6.0 Points)

| ID | Check | Evaluation Method | Weight |
|:---|:---|:---|:---:|
| 2.1 | Semantic | Target State Completion (Goal Fidelity) | Gemini LLM-as-a-Judge |
| 2.2 | Semantic | Scope Discipline (Anti-Hallucination) | Gemini LLM-as-a-Judge |
| 2.3 | Semantic | Architectural Integrity | Gemini LLM-as-a-Judge |
| 2.4 | Semantic | Error & Remediation Clarity | Gemini LLM-as-a-Judge |
| 2.5 | Semantic | Design Rationale & Intent | Gemini LLM-as-a-Judge |
| 2.6 | Semantic | Progression Ergonomics & Interactivity | Explicit single-action sector card/tile affordance inspector |

Passing Bar: 14 / 14 (Non-negotiable 100% threshold)

The Head-to-Head Verdict

If you run the side-by-side comparison multiple times, you'll find the following:

Metric	Unharnessed (Vibing)	Harnessed Track (Loop)	Operational Advantage of Harness / Loop
Execution Duration	Typically 1.5–2+ minutes	Typically 23–35s	3–4x faster
Combined Tokens	Typically 18,000–45,000	~6,600–6,900 (`~900–1,100` out)	~75–85% fewer tokens (~15x fewer output tokens)
Estimated Cost	~$0.010–$0.017	~$0.0014–$0.0015	~85% cheaper (~7–8x lower cost)
Rubric Score	Between 6–11 / 14 (Always fails)	14 / 14 (Always passes)	Reliable 100% success rate
Functional Outcome	❌ Broken / Non-functional	✅ Fully playable & verified	Only harnessed code works

Here are the side-by-side metrics from one run, captured directly from this live evaluation workbench:

You can watch a full live demonstration of the solution here:

(You can inspect the full workbench codebase, explore the evaluation engine, or run the live demo locally — and because the ADK LoopAgent, RubricEvaluationGateAgent, and FunctionTool suite in app/agents/ are completely project-agnostic, the repository README includes a 4-step guide for lifting this exact ADK harness blueprint into your own Python projects. Clone the open-source repository at derailed-dash/harness-engineering-demo.)

Unpacking the Results: Why the Harnessed Loop Dominates

These numbers might appear counter-intuitive at first glance. Why would an iterative multi-turn loop be three to four times faster and ~85% cheaper than a single-turn prompt?

Let's break down these results:

1. Only the Harnessed Version Actually Works

The most sobering lesson of the comparison is functional: the vibe-coded solution is almost always non-functional.

On paper, the unharnessed agent produced a directory of plausible-looking files. It wrote Python classes and generated a colourful HTML file. But when loaded into a browser, the game was completely dead. The sector tiles lacked click event bindings, the combat modal was un-wired, and several FastAPI endpoints failed to resolve dynamic path parameters correctly.

It typically scores between 6 and 11 out of 14, failing key mechanical checks and progression requirements.

In contrast, the harnessed agent's code reliably achieves a flawless 14 / 14. Because these checks include interrogating the frontend DOM structure and API bindings, we can be reasonably confident that the resulting game actually plays.

2. Much Faster: The Paradox of Disciplined Bursts

Intuition suggests that a single-turn prompt should be faster than an iterative loop. The workbench proves the exact opposite: the harnessed loop usually finishes in 24 to 35 seconds, whilst the unharnessed run invariably drags on for 1.5 to 2+ minutes.

Why? Two architectural factors work together here:

Disciplined Output vs Speculative Rambling: When an unguided model is asked to build a full application in a single pass without constraints, it falls into speculative rambling. It attempts to stream 15,000–17,000+ output tokens in one continuous burst — generating repetitive boilerplate, guessing at auxiliary classes, and second-guessing its own structure mid-stream. The harnessed agent, by contrast, is guided by harness/harness_context.md and activated skills to operate in compact, high-signal bursts: Turn 1 synthesises a concise Architectural & TDD Verification Plan (~800 output tokens, scoring 12.0 / 14.0 out of the gate) while materialise_builder_output_callback materialises the modular workspace files, and Turn 2 emits a focused Self-Healing Remediation Summary (~240 output tokens) to close the remaining +2.0 gap (12.0 -> 14.0).
Externalised Loop Reasoning (ThinkingLevel.LOW): Rather than burning 30+ seconds per turn in unconstrained internal chain-of-thought pondering (thinking_budget is deprecated on Gemini 3.x+, so we configure ThinkingConfig(thinking_level=ThinkingLevel.LOW) on gemini-3.8-flash), the harnessed builder agent externalises its iterative reasoning into the deterministic ADK LoopAgent, the RubricEvaluationGateAgent, and LIVING_MEMORY.md. On Turn 1, it writes clean, minimal scaffolding and unit tests in seconds. The rubric gate runs locally in milliseconds, highlights any exact delta, and Turn 2 applies a surgical update. Fast generation paired with real compiler, test, and linter feedback consistently beats slow, unverified internal pondering.

3. Higher Efficiency: Eliminating Waste and Output Cost

The cost breakdown reveals an equally striking reality: the loop is typically around one-seventh to one-eighth of the cost (~$0.0015 vs ~$0.011–$0.012+, consuming ~6,600–6,900 tokens vs 26,000–30,000+ tokens) of the unharnessed single prompt.

Without context guardrails, the unharnessed model repeatedly duplicated schema definitions, wrote inline mock trivia data spanning hundreds of lines, and generated unrequested helper utilities that were never imported.

The harness prevents this bloat in three ways:

harness_context.md explicitly enforces architectural boundaries (e.g. modular separation between the game engine and the trivia service).
The rubric's Scope Discipline (Check 2.2) actively penalises extraneous abstractions. Because the agent knows it will be graded on tight adherence to scope, it writes concise, well-factored code rather than padding its output with defensive speculative fluff.
Context Pruning Across Iterations: Rather than carrying the entire raw Turn 1 conversation history into Turn 2, the ADK builder agent prunes prior-turn chat history and receives only the distilled Iteration Evidence Receipt from LIVING_MEMORY.md (containing the score delta, pytest/ruff verification status, active failures, and next-turn remediation targets).

4. Resilience To Model Changes

Finally, there is an overarching architectural benefit that transcends any individual run: resilience against model updates.

When teams rely on raw vibe coding, their production pipeline is fundamentally fragile. A prompt that works reasonably well on a Tuesday afternoon can suddenly fail on Wednesday when the provider deploys a minor model update, alters default temperature behaviour, or updates safety guardrails. When your only quality assurance is the model's raw generative mood, you have no baseline.

A robust harness decouples and insulates us from changes to the model. The harness provides the immutable invariant rails: deterministic unit test runners, static analysers, type checkers, and semantic rubric gates. If a newer, smaller, or faster model stumbles on its initial attempt, the harness catches the defect instantly and guides autonomous remediation. You stop relying on model perfection and start relying on systemic verification.

Off-the-Shelf Loop Mastery: The Loop Library and the `loopy` Skill

Designing an effective developer loop from scratch can initially feel daunting. How do you calibrate the stopping conditions? How do you prevent an agent from running amok while refactoring a legacy codebase?

The good news is: you don't have to invent every loop pattern from first principles.

The agentic engineering community has begun codifying battle-tested loops into open-source catalogs. The preeminent reference in this space is The Loop Library by Forward Future, accompanied by the open-source loopy agent skill.

What is The Loop Library?

The Loop Library treats AI agent loops as bounded feedback systems with non-negotiable terminal states.

Every published loop in the library adheres to a rigorous architectural contract:

The Ready-to-Use Prompt: An unambiguous, declarative instruction that defines what the agent must do on each iteration.
The Verify / Stop Criteria: Explicit, measurable terminal conditions (such as green CI or full test suite passage) that tell the loop when to stop.
Strict Authority Boundaries: Clear operational tripwires separating read actions, code modifications, and irreversible operations (e.g. merging to main or releasing to production).

The `loopy` Agent Skill: Your In-IDE "Loop Doctor"

Rather than manually browsing a website, you can install the loopy skill directly into your developer harness (such as Google Antigravity). When equipped with loopy, your agent becomes an intelligent loop architect:

Find & Adapt: Ask your agent: "Find a loop in the Loop Library to help me speed up my test suite." The agent queries the catalog, identifies the nearest matching pattern, and adapts its thresholds to your specific stack.
Audit Existing Loops ("Loop Doctor"): Before letting an agent loose on a long-running task, ask loopy to audit your prompt. It inspects your instructions for weak checks, missing stopping conditions, or unbounded authority, hardening the loop before a single token is burned.
Craft via Guided Interview: If no existing pattern fits your problem, loopy initiates a structured interview, probing you on the desired outcome, permitted tools, and exact success criteria to craft a bespoke, bounded loop.
Save to LOOPS.md: Once a loop proves effective in your repository, loopy can commit it directly into a version-controlled LOOPS.md file in the root of your project. This transforms successful loop patterns into shared, institutional team muscle memory.

Real-World Loop Patterns You Can Run Today

Here are a few very cool, practical examples from The Loop Library that illustrate how loop engineering transforms daily developer operations:

1. The Code Housekeeper Loop

The Problem: Technical debt, unformatted files, dead code, and low-priority linter warnings accumulate across repositories because human developers rarely have the time or patience to clean them up manually.
How It Works: As defined in the Code Housekeeper Loop, the agent wakes up, scans the codebase for static analysis warnings or dead imports, selects one single discrete issue, applies a targeted fix, runs the full test suite to prove zero regressions, and commits the change.
Stopping Condition: Stops cleanly when all linter warnings are cleared or when a predefined maximum iteration cap is reached. Because it modifies only one file per turn, blast radius is completely contained.

2. The Fresh Clone Loop

The Problem: A developer clones a repository, attempts to run the setup script, and immediately hits missing environment variables, unpinned dependency conflicts, or outdated documentation. "Works on my machine" strikes again.
How It Works: The Fresh Clone Loop simulates the day-one developer experience in an isolated sandbox. It performs a completely clean clone, executes the documented bootstrap scripts, installs dependencies from scratch, and runs the initial test suite. If an installation step fails, it diagnoses the missing prerequisite, updates the setup.sh script or README.md, wipes the sandbox, and retries.
Stopping Condition: The loop halts only when a fresh clone successfully builds, boots, and passes tests from an empty state without human assistance.

3. The Test Suite Speed Loop

The Problem: Over time, test suites bloat. Slow database fixtures, redundant sleep calls, and un-parallelised test cases drag local feedback loops from thirty seconds to fifteen minutes, destroying developer velocity.
How It Works: The Test Suite Speed Loop profiles test execution times, identifies the slowest test files, isolates bottlenecks (such as redundant network calls or unmocked I/O), refactors the slowest test case, and verifies that the entire suite still passes with identical assertions.
Stopping Condition: Halts when overall test suite execution time drops below a declared target threshold (e.g. under 60 seconds) with 100% test passage.

Summary & What's Next: Fuel for the Engine

We have engineered an airtight structural harness (Part 1) and fired up an autonomous, self-evaluating execution loop with binary rubrics, tool trajectories, and the Ratchet Principle.

Now, what fuels the loop?

If you feed an autonomous loop vague conversational vibes and hand-waving, you won't get software; you will get automated, looping chaos at 50 tokens a second.

In Part 3, we provide the ultimate fuel: Spec-Driven Development (SDD). We will explore:

Why code is disposable, but specifications are the permanent source of truth.
Authentic production spec blueprints (tasks/plan.md) with Three-Tier Operational Boundaries (Always Do, Ask First, Never Do).
Putting it all into practice with Google Antigravity: the unified harness across IDE, Extension, CLI, and SDK.
Native slash commands (/grill-me, /learn, /goal, /plan) vs formal SDD, and the 4-Phase Hybrid Power Pattern.

👉 Continue to Part 3: Spec-Driven Development For-the-Win: Disposable Code, Living Blueprints, and Building Like a Boss (Coming Soon)

Before You Go

Please share 📢 this with anyone that you think will be interested. It might help them, and it really helps me!
Please give me loads of claps! 👏 (Just hold down the clap button.)
Please leave a comment 💬. Interaction is good!
Add a star ⭐ on my repos!
Follow 👉 and subscribe 🔔, so you don’t miss my content.

References and Useful Links

The Loop & Autonomous Systems

Dazbo's Related Content

From Vibing Chaos to Reliable Agents: The What, Why, and How of Harness Engineering

Darren "Dazbo" Lester — Mon, 28 Sep 2026 09:59:24 +0000

You are in Part 1 of the series "Beyond Vibe Coding: The Engineering Blueprint for Reliable AI Agents"

🗺️ The Series Roadmap: Beyond Vibe Coding

Agentic software development is drowning in fragmented buzzwords: Harness Engineering, Loop Engineering, Context Engineering, Spec-Driven Development… Are they competing frameworks? Redundant techniques? Or fundamentally different and essential?

This four-part series unifies these concepts into a single, cohesive architectural blueprint for building software with AI without writing code manually:

Part 1: From Vibing Chaos to Reliable Agents: The What, Why, and How of Harness Engineering (This Article) We diagnose the issues of vibe coding, unpack the paradigm shift of shifting developer interventions left, establish our bedrock formula (Agent = Model + Harness), explore a motorsport analogy, and deconstruct deterministic foundations that make up a production developer environment.
Part 2: Loop Engineering in the Harness: Autonomous, Self-Correcting Systems We fire up the dynamic runtime engine of the harness: deconstructing the loop components, establishing hybrid evaluation rubrics (deterministic tests + LLM goal fidelity + tool trajectory verification), and applying the Ratchet Principle.
Part 3: Spec-Driven Development For-the-Win: Disposable Code, Living Blueprints, and Building Like a Boss (Coming Soon) We explore Spec-Driven Development (where code is disposable and specifications are the real IP), master Google Antigravity’s unified developer harness and interactive slash commands (/grill-me, /plan, /goal, /boost, /learn), and combine formal specs with tactical workflows via the 4-Phase Hybrid Power Pattern.
Part 4: Scaling the Harness: Practical Loop Patterns, ADK 2 Graphs, Recursive Harness², and Enterprise Production (Coming Soon) We unpack the anatomy of a loop iteration (LIVING_MEMORY.md, ephemeral subagents, and beating attention dilution), demonstrate the four composable ways to wire loops into any repo (including Google ADK 2 graphs), explore Google Research’s recursive Harness² framework, and scale to enterprise production on Google Cloud.

Introduction: The Chaos of Vibe Coding

Was your first vibe coding experience like mine? Type in a single prompt and then watch an entire application spring into existence. It felt like wizardry.

It was clear that software development had fundamentally changed. We had entered the era of “vibe coding” — that intoxicating workflow where you lean back in your chair, sip your brew, prompt an LLM with a breezy idea, and casually mash the approval button while the model writes hundreds of lines of code across half a dozen files.

For quick hobby prototypes, weekend experiments, or throwing together an interactive mock-up to impress a client on a Friday afternoon, vibe coding is both effective and brilliant fun. You watch a terminal stream lines of code at lightspeed, and for a fleeting moment you feel like an omnipotent 100x developer. You can now build things in hours that would have once taken a competent coder months.

Then Monday morning arrives.

When you attempt to take your vibe-coded solution anywhere near a real production environment, reality hits you like a cold, wet Monday in London. What felt like intoxicating velocity on Friday turns into an architectural crime scene by Monday. The code might run, but beneath the surface lies a tangled web of subtle bugs, orphaned functions, unverifiable assumptions, and utter nonsense.

You quickly uncover the dirty secret behind unconstrained vibing:

Hallucination City: The model confidently invents deprecated API methods and fictitious URLs, synthesises nonexistent package dependencies, and hallucinates framework features that simply don’t exist. Once an agent hallucinates a dependency, every subsequent turn doubles-down on the fiction, inventing bizarre workarounds for libraries that were never real in the first place.
Alert & “LGTM” Fatigue: After reading your forty-seventh sprawling diff in two hours, your eyes glaze over. You find yourself mindlessly clicking “Approve” or typing “LGTM” without actually understanding or checking the changes, silently hoping the AI knows what it’s doing. (Spoiler: it doesn’t. You haven’t eliminated manual labour; you have merely swapped creative software engineering for bleary-eyed cursory proofreading.)
Solutions That Don’t Do What You Wanted: The code runs without syntax errors, but the actual business logic subtly diverges from what you originally intended. Maybe because you didn’t really know what you wanted in the first place, and you just hope that the model has magically filled in all the blanks in your fluffy request.
Unmaintainable, Inscrutable Code: The agent generates dense blocks of code without architectural coherence. It stitches together three different design patterns across four files. You don’t understand how it works and you haven’t really checked it. And you’d probably never reveal the code to your competent peers. “What if they actually look at this?” Your code was tech-debt on day one.
No Documentation: Zero README updates, no Architecture Decision Records (ADRs), no API contracts, and no inline explanations of why specific trade-offs were made. The key knowledge that maybe lives in your head is completely absent from the documentation.
Insecure & Risky: Hardcoded secrets, wide-open IAM permissions, complete absence of rate limits, and unescaped SQL queries slipped into the codebase because the agent prioritised making the code run over making it safe. Maybe you didn’t like a warning in a log and you told the agent “Make this warning disappear.” The agent said: “Hold my beer.”
Inefficient Token Use & The Manual Loop Furnace: You find yourself trapped in a soul-crushing manual loop: copy terminal error → paste into chat → get half-baked fix → copy next error → watch the context window bloat → watch your token bill skyrocket. You aren’t architecting software; you are acting as an organic clipboard between a compiler and an LLM. Inevitably, unless you happen to be paying for a premium model subscription, you’re going to hit your model quota.
Lack of Scalability & Portability: The code works on your machine, under your specific node or python version, with zero containerisation or repeatable environment configuration. Hand it to a colleague or push it to CI, and it instantly shatters. Onboarding friction, anyone?
Purpose Drift: By turn eight of a messy conversation, the model has completely forgotten the initial rules and constraints you laid out in turn one. (Assuming you specified any constraints at all.) It begins re-inventing components it already built or quietly undoing your earlier bug fixes.

The conclusion is inescapable: you cannot ship vibes to production.

Yet, none of us wants to retreat to typing out thousands of lines of boilerplate by hand. The goal remains what it has always been: to create robust, scalable software solutions without writing code manually.

In an insightful Google Cloud Tech interview with Tilde Thurium, Ryan Lopopolo (Principal Engineer, Agentic Cloud Platform @ Google, who first coined the term “agent harness”) laid out his own radical ambition: to never write code by hand again. As Ryan wryly admitted: “I aspire to be a lazy programmer.” Don’t we all?

Having demonstrated that teams can build and ship massive production systems with zero manual typing by establishing that “humans steer, agents execute”, Lopopolo proved that hands-off development is genuinely achievable.

The answer isn’t to abandon AI agents or wait for newer models; it is to fundamentally change how we construct, control, and constrain them.

The Paradigm Shift: Shifting Developer Interventions Left

To understand why unconstrained vibe coding collapses, we should look at where developers are forced to spend their energy.

In naive AI interactions, developer intervention happens almost entirely on the right. That is: downstream, after the code has already been generated. You spend your afternoon scrolling through hundreds of lines of inscrutable diffs, tweaking chat prompts to fix syntax quirks, or rewriting hallucinations. You are perpetually reacting to failure after the fact, acting as an exhausted organic filter for broken output.

Harness engineering shifts developer intervention to the left.

Instead of manually reviewing broken outputs or wrestling with repetitive errors downstream, you invest your engineering effort upstream before the agent ever runs. You engineer the environment: defining rules, embedding automated linters and type-checkers, configuring deterministic sandboxes, and establishing clear evaluation rubrics. When the agent operates within an engineered environment, failures are caught and corrected autonomously inside the execution loop, long before a human ever inspects the resulting pull request.

Enter Harness Engineering.

The Bedrock: If It's Not the Model, It's the Harness

To understand what harness engineering is, you must start with this fundamental equation:

Agent = Model + Harness

And with this comes the ultimate maxim of modern AI development:

“If it’s not the model, it’s the harness.”

We have been conditioned by tech headlines to obsess over frontier models. Every week brings another benchmark, another parameter increase, and another claim of AGI just around the corner. But here is the hard reality: the harness is arguably more important than the model.

An okay, cost-effective model housed within a robust harness will consistently outperform a bleeding-edge frontier model with a poor harness. Why? Because the model is inherently probabilistic, whereas serious software engineering demands determinism. The harness is what bridges that chasm. It supplies the missing structure: living memory, automated validation, static analysis, type checking, sandboxing, and execution guardrails.

Think of it like high-performance motorsport:

The Model is the Driver: Incredibly talented, capable of split-second reasoning and creative problem-solving, but prone to fatigue, distraction, and occasional moments of reckless overconfidence. Left entirely to their own devices on an open airfield, they might pull off some breathtaking doughnuts, but they can’t win a grand prix.
The Entire Race Car IS the Harness: The complete, precision-engineered machine built to translate the driver’s intent into track-winning performance:
The Engine & Transmission (Loop Engineering): The internal dynamic execution engine of the harness. It delivers torque to the wheels through a disciplined cycle of intake, combustion, and telemetry. Iterative execution, continuous evaluation, and immediate feedback cycles.
The Chassis (Structural Harness): The living rules (AGENTS.md / GEMINI.md), directory layouts, and sandboxed runtimes that keep the car glued to the tarmac, dictating the exact physical limits of where the vehicle can steer.
The Brakes & Pit Telemetry (Safety & Evaluation Gates): The deterministic test suites and escalation protocols that prevent the driver from wrapping the machine around a barrier at 180 mph.

You wouldn’t put Lewis Hamilton behind the wheel of a V12 engine block with no chassis or brakes and expect him to finish a single lap at Silverstone, let alone win the race. So why do the same with agentic software development and expect robust results?

⚠️ Dazbo's Battle Scar: The Model Upgrade Fallacy

Whenever an agentic workflow breaks down in development — falling into repetitive loops, introducing subtle runtime bugs, or failing to follow architectural patterns — the instinctive developer reaction is: “We need a smarter model. Let’s switch to the latest 2-trillion parameter frontier model.”

Almost every time, this is a fallacy. Upgrading the model without improving your harness simply means your agent will generate more articulate, harder-to-spot hallucinations at four times the token cost. If your agent is failing, don’t reach for a bigger model first. Ask yourself: Did the harness enforce a test? Did the harness provide the exact schema? Did the harness restate the goal? If it’s not the model, it’s the harness!

Crucially, the harness is model-agnostic. Whether you are routing requests through a cost-effective, high-velocity workhorse like gemini-3.8-flash, or a deep-reasoning powerhouse, a well-engineered harness remains stable, repeatable, and robust. You can hot-swap the model under the hood without having to redesign your entire engineering lifecycle.

The Model is a Commodity; The Harness is the IP

This reveals a fundamental commercial reality of AI software engineering. As my friend and fellow Google Developer Expert Jaroslav Pantsjoha (JP) highlighted in his analysis of the AI-native developer experience: the model is a commodity; the harness is where your true competitive advantage and intellectual property reside.

Every organisation has access to the exact same frontier foundational models via public APIs. Simply renting access to raw model intelligence provides zero lasting competitive advantage. Your true intellectual property and your team’s operational velocity live entirely inside your harness:

Your living rules and architectural guardrails that encode decades of hard-won domain knowledge.
Your curated suite of tool integrations and MCP servers that securely bridge AI agents into your private internal databases and microservices.
Your deterministic evaluation rubrics and automated test harnesses that guarantee safety and compliance before any code reaches production.
Your version-controlled living specifications that turn disposable AI code into maintained, documented, and resilient software assets.

Foundational models will continue to be commoditised, upgraded, and replaced. But a well-architected enterprise harness compounds in value with every single engineering iteration.

Untangling the Triad: Context, Harness, and Loop Engineering

Before we deconstruct the components, it is worth clarifying how three terms frequently heard across the industry map directly back to our bedrock formula (Agent = Model + Harness):

Context Engineering: Determines what the agent knows. It is the cognitive payload the harness feeds to the model, including hierarchical rules (AGENTS.md or GEMINI.md that can be global, team, domain, or project-specific), active retrieval (RAG), agent skills, and other sources of knowledge.
Structural Harness Engineering: Determines what the agent can touch and where it runs. It provides the deterministic environment: tools, APIs, MCP servers, sandboxed execution runtimes, security guardrails, living file state, and blast-radius (damage control).
Loop Engineering: Determines how the agent iterates and converges over time. It is the dynamic runtime engine of the harness ; the autonomous process of observing, acting, judging against rubrics, recording memory, and knowing when to stop.

Crucially, they are not three competing systems; loop and context are the internal functional dimensions of the harness itself. If context is the agent’s briefing pack and the loop is its working cadence, the harness is the complete laboratory workbench in which all of it takes place.

And we can see that state (such as markdown files) plays a significant role in all three.

Deconstructing the Harness: The Deterministic Foundations

If the model represents the non-deterministic, probabilistic core of our system, the harness represents everything else: the deterministic components that guide, restrain, and validate every single action the model takes.

So, what actually lives inside a robust developer harness?

Let’s break down the essential layers:

1. Hierarchical Context & Living Rules: "De-Slopping" by Design

Your agent should never have to guess your engineering standards, architectural decisions, or toolchain preferences. In an ad-hoc vibe coding setup, you might type: “Please write clean Python and test it.” The model nods, writes an unformatted script, tests it with a couple of inline assert statements, and calls it a day.

In her analysis How to De-Slop an AI-Generated Codebase, Alice Moore highlights why telling an AI to “clean this up” or “write clean code” inevitably fails: the instruction is too vague. AI “slop” can only be prevented by translating human taste into concrete, non-negotiable rules.

In an engineered harness, we establish our context in files like this:

Global Configuration (GEMINI.md or AGENTS.md): Cross-project standards including language preferences, mandatory package managers (e.g. using uv for Python), security baseline rules, and zero-tolerance policies for inline execution hacks.
Workspace-Specific Context (my-project/GEMINI.md): Architecture blueprints, directory layouts, data sources, and project goals.
Automated Guardrails: Explicit rules that we must always adhere to. For example, performing static analysis after each change. Or, for example, requiring the agent to practice strict Test-Driven Development (TDD). I.e. writing the failing test before implementing code.
Documentation Rules: Mandatory upkeep of core documentation (READMEs, Architecture Decision Records, product specs, task lists) using standardised workflows so the codebase never drifts into an undocumented quagmire.

To see what this looks like in practice, here is an authentic snippet from my own global GEMINI.md file:

# Agent Execution Guardrails & Standards

## Python Guidance & Tooling

- **Environment Source of Truth**: Respect the Python version defined in
  `pyproject.toml`. For new greenfield projects, default to `python 3.13`.
- `uv` is the preferred tool for Python package and environment management.
- **Avoid Inline `python -c` Commands**: Do NOT execute inline Python snippets
  using `python -c "..."` or `python3 -c "..."`. Because Antigravity cannot 
  safely prefix-match arbitrary inline code payloads, this triggers a manual 
  approval prompt every time. Instead, write one-off helper logic to a 
  scratch script in your scratch directory and execute it cleanly via 
  `uv run python scratch/helper.py`.
- Always include top-of-module docstrings that explain what a given .py 
  file does, why it exists (i.e. the value it provides) and an outline of 
  how it works.
- Use rich (`pip install rich`) when building console / CLI applications.
- **Zero-Tolerance for Suppression Hacks**: Never bypass linter or 
  type-checker errors using `# noqa`, `# type: ignore`, or `@ts-ignore` 
  comments. Resolve the underlying type contract or architectural root cause.
- When adding features or making changes that are anything beyond trivial, 
  **use TDD**. Create the test, verify it fails, make the change, and then verify 
  the test passes.
- To ensure Python code adheres to required standards, the following 
  commands **must** be run after creating or modifying any `.py` files:
  ```bash
  uvx codespell@latest -s # check spelling and show summary
  uvx ruff@latest check --fix . # perform static checks and auto-fix
  ```

## Agent and AI Development

- NEVER try to downgrade a Gemini model in code or variables. E.g. NEVER 
  try to change `gemini-3.8-flash` to `gemini-3-flash`.
- Unless otherwise instructed, use the latest generally available Gemini 
  models available; always check what the latest is. This also goes for 
  image generation.
- Unless I say otherwise, agents should be built using the Google ADK 
  (`google-adk`) and the Google Gen AI (`google-genai`) packages. 
- AVOID using the `google-generativeai` package. This is deprecated in 
  favour of the newer GenAI `google-genai` SDK.

We’re not politely pleading with the model. We are creating rigid rails.

The rule banning inline python -c snippets is a classic harness engineering battle scar. In a sandboxed developer environment, the execution engine auto-approves safe binary prefixes (such as uv run python ...). When an unconstrained model starts generating dynamic inline code strings, the runtime cannot prefix-match the payload and is forced to interrupt the developer with a manual approval prompt every time it makes a minor tweak to the Python it wants to execute… Every ten seconds!

Similarly, the rule forbidding # type: ignore and # noqa suppressions closes a notorious AI loophole. When confronted with strict linting or typing rules, an unsupervised LLM will frequently take the path of least resistance by slapping suppression comments across the file to silence the compiler. By outlawing suppressions in the harness rules, the model is compelled to fix the actual defect.

2. Living State & Version-Controlled Memory

Human software engineers don’t attempt to hold an entire multi-week project in their brains; we maintain backlog boards, write technical specifications, document decisions, and keep scratchpads.

Yet developers routinely expect an AI model to hold twenty architectural considerations across a forty-turn chat window. The moment the conversation grows long, the context window compacts, and the agent quietly forgets earlier decisions. And let’s not forget the “lost-in-the-middle” problem that we frequently observe in models.

The harness solves this by providing agents with structured, file-backed living state. Although there are no rigid rules for HOW you structure this, here are some suggestions from me:

Strategic & Architectural Truth (The Blueprints):

PRODUCT.md: Defines the business “why”, user personas and user stories, core problem statement, and explicit non-goals (what the system is deliberately not building, preventing the agent from over-engineering features you never asked for).
SPEC.md: Machine-readable functional requirements, API contracts, and behavioural scenarios (Given / When / Then).
ARCHITECTURE.md: System topology, component boundaries, database schemas, data flow and design decisions.
DESIGN.md: UI design, styling rules, token definitions (colours, typography, spacing), and accessibility constraints; we can even export or synchronise this file with tools like Google Stitch via MCP.

Operational & Execution State (The Working Memory):

TODO.md (or active backlog): Real-time checklists where tasks are marked off as completed.
plan.md: Phased vertical slices and dependencies mapped out for the immediate objective.

Transient Execution State (The Scratchpad):

scratch/: Ephemeral execution notes, raw compiler traces, and intermediate data files that persist across model turns without polluting Git history. You would exclude this folder in your .gitignore.

(We will explore how to author, stress-test, and execute these living blueprints in depth in Part 3: Spec-Driven Development For-the-Win. Coming soon!)

Because these files are stored in standard Markdown directly in the workspace, they can be version-controlled with Git and shared seamlessly across developer sessions and different machines. If an agent session crashes, if your laptop runs out of battery, or if you hand the task over to a colleague across the globe, the harness preserves the living state. The agent simply reads the task list on turn one and resumes exactly where it left off.

3. Agent Tools: Grounding Models in the Real World

Language models in a vacuum are just predictive text generators; they interact with the outside world through tools. A robust harness equips the agent with a multi-layered execution surface:

Native Functions: Strongly typed functions in the code, for fast deterministic operations.
Sandboxed Shell and CLIs: Compilers, linters (ruff, eslint), test runners (pytest), package managers (uv, npm), and cloud CLIs (e.g. gcloud) executed inside isolated shell environments.
The Model Context Protocol (MCP): A standard that lets agents discover and execute tools without writing bespoke glue code for every service.

⚠️ Dazbo's Battle Scar: Tool Sprawl & Choice Paralysis

When developers first discover MCP, the temptation is to connect twenty different servers simultaneously: GitHub, Slack, Postgres, BigQuery, GKE, Firestore, Stitch, Confluence, Jira, Cloud Logging…

Don’t do it. Connecting 20 MCP servers could easily dump 150+ tool schemas into your model’s context. That’s a lot of wasted tokens before you’ve even typed an instruction. Worse, models experience tool choice paralysis and routing collisions. As I detailed in Dialling Our Agents to 11: My Favourite MCP Servers, keep your active MCP server suite lean, curated, and strictly relevant to the task at hand.

4. On-Demand Context: Progressive Disclosure via Agent Skills

Flooding an LLM’s context window with thousands of lines of reference manuals on every turn is a great way to confuse your model and increase your token costs.

Instead, the harness can use agent skills, which use a mechanism called progressive disclosure to load on-demand. Progressive disclosure operates in three levels:

Level 1 (Metadata): At startup, the agent only reads tiny YAML frontmatter headers (e.g. name and trigger description, typically consuming under 100 tokens).
Level 2 (Instructions): Only when a relevant task is initiated does the agent dynamically load the full SKILL.md instruction set.
Level 3 (Resources): Deep reference scripts, schemas, and templates are only pulled into context when needed.

Your agent stays lightning-fast, burns minimal tokens, and possesses instant access to all the knowledge and operational expertise it needs.

Feels a bit like cheating, doesn’t it?

⚠️ Dazbo's Battle Scar: Skills Sprawl & Context Pollution

If skills are so effective, why not install hundreds of them?

As I explored in Skills Sprawl: When Too Much of a Good Thing Confuses Your AI Agent, skills hoarding is a trap.

Even though Level 1 progressive disclosure reads only the YAML frontmatter, loading 150+ skills can easily inject over 15,000 tokens and routing overhead into every single model turn.

The result? Severe LLM decision fatigue, tool selection degradation, and skill routing collisions. If your agent is building a Python cloud backend, it shouldn’t be wading through metadata for React video rendering or mobile UI frameworks. Curate your active skills, prune what you don’t use, and disable non-essential sub-skills in your configuration. A disciplined harness is a clean harness. (For a deep dive into the top skills I rely on daily, check out Dialling Our Agents to 11: Agent Skills You Need to be Using!.)

5. Packaging Knowledge & Capability: The Rules, Skills, and MCP Triad

Once you begin equipping your harness with these deterministic components, an obvious engineering question arises: How do you manage all this?

In practice, we organise with three complementary layers:

Rules (The Guardrails & Standards): Standing instructions that ensure compliance (e.g. safe command syntax, directory layouts, and security policies).
MCP Servers (The Tools & Senses): Execution interfaces that connect the agent to external infrastructure, databases, and APIs.
Agent Skills (The Procedural Playbooks): On-demand workflows and recipes that teach the agent how and when to use those tools effectively.

While open protocols like MCP have standardised the tool layer, there is not yet a single universal industry standard for how the entire capability stack should be packaged.

However, an increasingly popular architectural pattern — supported natively by developer harnesses like Google Antigravity — is the Plugin. Rather than forcing developers to manually wire up an MCP server, write separate prompt rules, and install five standalone skills, a plugin acts as an aggregated delivery vehicle:

A prime example of this pattern in the Google ecosystem is the google-cloud-developer plugin, which looks like this:

Packaging Manifest (plugin.json): The schema descriptor defining metadata, versioning, and dependencies.
Standing Safety Rules (rules/*.md): Markdown rules (like google-cloud-discovery.md) that establish pre-flight command validation and guardrails.
Modular Agent Skills (skills/*/SKILL.md): Individual skill directories with YAML frontmatter headers and procedural Markdown instructions — such as google-cloud-recipe-auth, gcloud, and dynamic discovery (finding-google-skills).
Tool Connectivity (mcp.json): A JSON configuration declaring active MCP endpoints — such as the streamable-HTTP connection to Google's official developer-knowledge server.

google-cloud-developer/
├── plugin.json                    # Plugin metadata & agent-plugins.org schema
├── mcp.json                       # MCP server connection endpoints
├── rules/
│   └── google-cloud-discovery.md  # Standing guardrails & catalog rules
└── skills/
    ├── finding-google-skills/
    │   └── SKILL.md               # Dynamic on-demand catalog discovery
    ├── gcloud/
    │   └── SKILL.md               # Gcloud CLI validation & execution
    └── google-cloud-recipe-auth/
        └── SKILL.md               # Authentication recipes

Whether packaged as composite plugins or managed as standalone assets, the goal is identical: providing agents with both the architectural rules and the deep domain knowledge required to execute safely.

My Curated Production Toolkit

In my own daily engineering workflow, I rely on a focused blend of plugins and standalone skills, which include (but are not limited to):

google-cloud-developer plugin: Deep GCP architectural rules, safe execution guardrails, and native developer knowledge retrieval.
Google Agents CLI (ADK): Coding best practices, scaffolding, and deployment blueprints for building AI agents with the Google Agent Development Kit.
agent-platform-eval-flywheel: Google Cloud's evaluation flywheel methodology for measuring agent quality, LLM-as-judge scoring, and regression datasets.
spec-driven-development: Bridges intent to code by generating machine-executable specifications and behavioural contracts before coding begins (the focus of Part 3).
test-driven-development: Enforces strict red-green-refactor loops, guaranteeing code isn't accepted until automated test suites pass.
code-review-and-quality: Automated multi-axis code reviews evaluating maintainability, security, and simplicity before changes enter the main branch.
Vercel's find-skills: Dynamic skill discovery, allowing the agent to find and fetch installable skills from public registries on-demand without manual preloading.
organise-agent-skills: My own skill for auditing installed skills, pruning token overhead, and managing on-demand progressive disclosure to prevent skills sprawl.
maintaining-core-documentation: My own agent skill for synchronising READMEs, architectural docs, and task lists whenever code changes.

6. Sandboxing & Blast-Radius Containment

A robust harness never allows an agent unfettered access to host operating systems or production networks. Through containerised agent sandboxes, filesystem isolation, and execution policies, the harness establishes hard boundaries.

If an agent attempts an unreviewed destructive action — such as dropping a database table, executing an unsandboxed shell command that alters host configuration, or modifying .git/ internal objects — the harness halts execution and demands explicit human verification. Sandboxing transforms autonomous agents from dangerous mavericks into safe, bounded wingmen. (See what I did there?)

7. Observability & Trajectory Monitoring: Beyond Traditional Logging

In traditional software engineering, when a service fails, we inspect a deterministic stack trace and a linear log file: line 42 threw a NullPointerException. Or we run our unit tests and see exactly what test failed.

Autonomous AI agents don’t work like that. An agent doesn’t execute a single static function; it embarks on a multi-step journey toward a goal. In AI engineering, that journey is known as the agent’s trajectory.

What is an Agent Trajectory?

An agent trajectory is the complete, chronological sequence of intermediate states, reasoning steps, tool calls, environment responses, and course corrections the model takes from its initial prompt to the final output.

Think of it as a state machine where every step consists of a continuous route:

For example, a four-turn trajectory might look like:

Turn 1: Read SPEC.md → Turn 2: Run pytest (fails) → Turn 3: Edit code → Turn 4: Re-run test (passes).

When an agent fails, it rarely crashes with a fatal error. Instead, it suffers from trajectory drift:

Did it misinterpret a requirement back on turn 2?
Did a sandboxed CLI return an ambiguous warning on turn 4 that poisoned the agent’s reasoning on turn 5?
Did the model get stuck in a “thrashing loop” between turns 8 and 12, fruitlessly editing the same file back and forth?
Did it choose a blunt command-line tool when an exact MCP endpoint was sitting right in its prompt?

Without trajectory observability, you are left staring at a vague final apology from the model, completely blind to where the journey went off the rails.

A robust developer harness treats trajectory monitoring as a first-class citizen:

Step-Level Execution Traces: The harness records structured session transcripts (such as JSONL traces) capturing the exact prompt payload, the model’s internal thinking traces, the precise tool arguments sent, and the raw stdout/stderr returned by the sandbox.
Context & Token Telemetry: Real-time instrumentation tracking how context size inflates turn by turn. This lets you pinpoint runaway token spikes, prompt cache hit rates, and the exact cost of each iteration before a loop drains your budget.
Enterprise OpenTelemetry & Cloud Trace: When moving from local IDE harnesses to cloud-hosted agents (e.g. running Google ADK agents on Cloud Run or the Google Agent Platform), the harness exports distributed traces into Google Cloud Trace and structured events into Cloud Logging. Every tool call becomes an inspectable trace span.

When you can inspect the full trajectory, debugging ceases to be guesswork. You can conduct a forensic post-mortem on any failed run and immediately determine: Did the model experience a reasoning failure, or did my harness fail to provide the right deterministic rail?

Summary & What's Next: Firing Up the Engine

We have shifted left and engineered the deterministic foundations: living rules, version-controlled state, curated tools, progressive skill disclosure, plugin packaging, sandboxed boundaries, and execution traces. We have built the race car chassis.

Now, how does work actually get done?

In Part 2, we fire up the dynamic runtime engine inside the harness: Loop Engineering. We will explore:

Why autonomous feedback loops crush single-pass generation.
The core mechanical components of an engineered developer loop.
The Ratchet Principle.
The Diagnostic Rule of Thumb: Is it a Loop bug or a Harness bug?
Designing Evaluation Rubrics (combining traditional tests with LLM goal evaluation and deterministic tool trajectory verification).
A complete, turn-by-turn trace of an autonomous agent self-correcting in real time.
The loopy skill, and the Loop Library.

👉 Continue to Part 2: Loop Engineering in the Harness: Autonomous, Self-Correcting Systems (Coming Soon)

See you there!

Before You Go

Please share 📢 this with anyone that you think will be interested. It might help them, and it really helps me!
Please give me loads of claps! 👏 (Just hold down the clap button.)
Please leave a comment 💬. Interaction is good!
Add a star ⭐ on my repos!
Follow 👉 and subscribe 🔔, so you don’t miss my content.

References and Useful Links

The Harness & Ecosystem

Dazbo's Related Articles

Meet the Antigravity Extension: Gemini Code Assist on Steroids, in Whatever IDE You Love

Darren "Dazbo" Lester — Fri, 21 Aug 2026 01:11:12 +0000

Google Antigravity (or Agy) was first launched as an agent-first development environment in late 2025. Then, in May 2026, Google released the new Antigravity suite, comprising four surfaces:

Antigravity 2.0 — The agent-first, intent-driven surface. For those who care about the outcomes, but not necessarily the code. It’s the modern agentic environment for builders.
Antigravity IDE — The familiar IDE (the IDE itself is a fork of VS Code), but with all the smarts of the Antigravity harness built-in.
Antigravity CLI — The terminal user interface (TUI) experience. This replaced the very awesome Gemini CLI.
Antigravity SDK — For developers who want to harness the full power of Antigravity programmatically.

All these surfaces use the same Antigravity harness. They give you capabilities such as:

Advanced multi-stage reasoning, using the latest Gemini models.
Full repo refactoring.
Planning, execution and evidencing.
Agent loops and subagent swarm orchestration.
Integration with file system and shell environment.
Multiple useful built-in commands and subagents.

At the same time, Google announced that both Gemini Code Assist and Gemini CLI were end-of-life. And indeed, unless you happened to run inside an organisation that had paid for enterprise licenses, these products got turned off in June 2026.

The Worry

Gemini CLI was great. I was gutted to see it go. But Antigravity CLI was a worthy replacement, and it was immediately available. So we made the switch, and we were happy.

But what about the death of Gemini Code Assist? If you’re not familiar with this tool: it was the Gemini agent that you could install as an extension into your favourite IDE, like VS Code or IntelliJ. The agent ran in a side panel, fully-integrated with your IDE.

Then Google told us:

“Gemini Code Assist is dead. But don’t worry. For all you coders out there, just switch to Antigravity IDE. It feels like VS Code and you get the Gemini Code Assist experience — on steroids.”

(They may not have actually used these words.)

And this is exactly what I did. I briefly mourned VS Code, and then went all-in on Agy IDE.

But I was rather vocal in sharing my thoughts with some influential folk at Google.

My thoughts being:

Some folks — like me — were happy to make the switch. But there are tens of millions of developers who WILL NOT give up their favourite IDE. So, if you tell them: “Switch to Agy, or you stay where you are, but with no Gemini”, then they’re gonna say: “Okay. I’ll go with option 2.” To me, that’s a lose-lose situation.
Some enterprises are pretty strict about their approved development environments and ecosystems. And — for reasons — they can be SOOOOO SLOW at adopting new things.

The TL;DR — there was no viable path for developers who wanted to evolve from the Gemini Code Assist experience, but stay with their favourite IDE.

Until Now

Today (August 20, as I write this), Google launched the Antigravity extension for IDEs! You can check out the official Google release blog, here. Right now, there are Agy extensions for VS Code, Visual Studio, IntelliJ IDEs, and Zed.

I can’t tell you how stoked I am about this announcement!

What is it? Well, think of it as a replacement for the Gemini Code Assist extension. It’s Gemini Code Assist, but pumped with steroids and caffeine. It’s all the cool Agy harness capabilities we’ve come to love in Antigravity 2.0, Antigravity CLI and Antigravity IDE, but now packaged as an extension.

So, as of tonight, I’ve switched back to VS Code!

Install the Extension

Let’s install it! I’m using VS Code, so I’m installing this extension.

If you happen to go looking for “Google Antigravity” in the VS Code Marketplace, be sure to install this one by google.com:

When you open the extension, you’ll see this in VS Code:

Click Install, and you’ll be asked to sign-in to Google:

And you’ll be asked if you want to install any of the ready-made plugins:

And that’s it!

It took about 20 seconds, and now the Antigravity extension is working in my VS Code!

Take It For a Spin

I wondered if all my existing agent skills and MCP servers would be working. So I asked it: “Install my Gemini code reviewer”

It immediately found and activated my install-gemini-code-review-action skill and used it to install my Gemini Code Review Action into the local repo. It then asked for permission to commit these changes push them to GitHub. I gave Agy permission, and it went ahead and pushed.

So this proved that my existing skills were immediately discovered, activated and used, and that it was able to use my GitHub MCP to perform the commit and push. Nice!

Models

We can see the models that are available:

And we can see more model and Antigravity extension settings here:

(I love the fact that next to my “AI Ultra” subscription is an “Upgrade” button. Seriously? Lol!)

The Plugins Created Some Skills Duplication

The newly installed plugins resulted in duplication of some skills I had previously installed in my ~/.gemini/config/skills folder. So I said to Antigravity: "Let's do a skills optimisation run."

It went ahead and activated my organise-agent-skills. The skill made a number of recommendations which I implemented. The results looked like this:

Wow!

29 duplicated skills deleted.
56 “sub-skills” set to excluded, because they are managed by their parent skills.
68% reduction in token overhead!

Great, so our skills are back to running nice and lean.

A Nice View of Token Usage

Whilst we’re talking about token optimisation, I stumbled across this “Customization” page in the Agy extension settings:

This is nice view that how much of your “customization budget” is being consumed by all your GEMINI.md (or AGENTS.md), your skills, and your MCP tools. What’s quite interesting to note is that Agy will automatically start truncating if you exceed this budget. So you might suddenly find that your skills are being ignored, for example. This is another good reason to optimise your install skills and MCP servers.

Things Not Working

Browser Subagent

The first thing I struggled with is the built-in browser subagent. I couldn’t get this to browse web pages for me, even after I enabled the remote debugging in Chrome. I did expect this. My VS Code is running in Windows, but connected to my repos in WSL. This has typically been a problem area for browser subagents. Maybe I’ll be able to get it working, if I put in a bit of work. But tonight… I’m far too tired!

(I should mention: this issue is only for WSL users. 4 out of 5 developers won’t be affected by this.)

On the plus side, I was able to remote control the browser with my existing BrowserMCP configuration. No changes required.

Antigravity In-Line Complete and Tab Features

One thing I really love about Antigravity IDE is the real-time suggestions and edits you can make in the editor window.

For example: if I were to change one instance of “We did something” to “I did something”, then Antigravity IDE allows me to update all remaining instances in a context-aware way, just by pressing tab.

This feature is not currently working for me with the Agy extension in VS Code. So it’s possible my configuration isn’t correct, or this feature hasn’t been implemented in the extension yet. But this is only day 1!

What Does This Mean for Agy IDE?

Within hours of the extension arriving, many folks have been asking me, “What does this mean for Agy IDE? Will Google kill it?” It’s a question I’ve been asking my friends at Google for a little while.

Nobody has explicitly told me that Google will kill Agy IDE. But my thoughts are:

If the Agy extension provides the full Agy harness experience in all the major IDEs, what’s the point in having a separate IDE that looks a lot like VS Code?
Why would Google want to maintain the “IDE” components of Agy IDE, when these are essentially just a fork of VS Code anyway? That’s a lot of work.
Lastly, take a look at the release notes for Agy 2.0, Agy CLI, and Agy IDE. The relative sparsity (is that a word?) of Agy IDE patches is telling.

Personally, I think the writing is on the wall.

Wrap-Up

I’m so happy this Agy extension has arrived. Now any developer can use the extremely capable Antigravity harness from their IDE of choice. It gives a viable migration path for those who were using Gemini Code Assist before.

For me, the install experience was totally painless, and everything just worked out-of-the-box. (Well, almost everything. But I can wait for the other things.) The agent is responsive and works. And it picked up all my existing configuration.

That’s it! Go forth and use Antigravity in your favourite editor!

Before You Go

Please share 📢 this with anyone that you think will be interested. It might help them, and it really helps me!
Please give me loads of claps! 👏 (Just hold down the clap button.)
Please leave a comment 💬. Interaction is good!
Add a star ⭐ on my repos!
Follow 👉 and subscribe 🔔, so you don’t miss my content.

References and Useful Links

Dazbo’s Portfolio
Google Antigravity Official Site
Google Antigravity IDE Extensions Announcement
Google Antigravity Extension on the Visual Studio Marketplace
Dazbo’s Agent Skills Repository — if you like it, please add a star!
Dazbo’s Gemini Code Review Action — if you like it, please add a star!

Skills Sprawl: When Too Much of a Good Thing Confuses Your AI Agent

Darren "Dazbo" Lester — Mon, 17 Aug 2026 10:13:26 +0000

Introduction

In this post, we're going to look at the problem of Skills Sprawl.

What happens if you have too many skills?

We'll understand LLM decision fatigue and tool selection accuracy, inspect the mechanics of excluded vs inactive skills in Google Antigravity, and see how pruning your setup can make your agent smarter and save hundreds of thousands of tokens per session.

Skills Context (It's a Sort of Pun...)

Everyone knows that agent skills are awesome. If you don't, then:

Where have you been?
You're in for a treat!

In some of my previous posts I've talked about how skills act as on-demand power-ups for our agents. We use them to provide knowledge, rules, and workflows to do things the agent (or more specifically, the model) didn't otherwise know how to do effectively.

You might have seen me compare this to how Neo loads his skills in the Matrix. "I know Kung Fu!"

This just-in-time knowledge provides a number of advantages to our agents:

They know how to do a thing well.
They don't hallucinate the things they don't know about.
They don't have to experiment and course-correct; consequently, they're more likely to succeed the first time, and they do it with a minimum number of tokens consumed.

In short: faster, cheaper, and more reliable.

Quick aside: when I say agent, I'm typically talking about your agentic partner in development crime, like Google Antigravity, Claude Code, or whatever. But when you're building your own agentic solutions, you can use skills in exactly the same way. For example, check out my blog Automated GitHub Code Reviews Using Google Gemini, where I've built an agentic PR review solution that leverages skills.

Overview of Progressive Disclosure

Skills use a cool mechanism called progressive disclosure to load on-demand.

Let's quickly recap this mechanism:

Level 1: Metadata (Frontmatter)

When your agent starts up, it reads the frontmatter - and only the frontmatter - of every installed skill in your global configuration and workspace.

By the way, if you don't know where these skills should be placed, or you don't know the difference between global and workspace locations, check out my earlier blog: Confused About Where to Put Your Agent Skills?

The frontmatter is simply the descriptive YAML at the top of each skill which contains the skill name, a description (what it does and when it should be used), and any additional useful metadata (such as what tools it might use, author, etc).

For example, this is from my maintaining-core-documentation skill:

name: maintaining-core-documentation
description: |
  Creates, maintains, and synchronises core project documentation (README, TODO, DESIGN, Architecture, Testing, Deployment). Use when the user needs to write, update, or structure project documentation based on codebase changes, or whenever asked to perform documentation reviews or updates.
metadata:
  author: Darren "Dazbo" Lester
  repository: https://github.com/derailed-dash/dazbo-agent-skills

Crucially, this frontmatter section is tiny. So even though the agent reads it up-front, it consumes very few tokens. Typically fewer than 100 tokens per skill.

The agent now has a mental model of all the skills that are available to it.

Level 2: Instructions Loading (On-Demand)

When the agent is asked to do a task that one of these skills might be useful for, the model selects the skill (based on the frontmatter), and then activates it. When this happens, the agent reads the SKILL.md body into context.

This will typically add several hundred, if not thousands of tokens.

Level 3: Resources and Code (As Needed)

Some skills may package additional resources, such as scripts, reference documents, or other assets. For example, my maintaining-core-documentation skill has a references subdirectory with several document template files.

These assets are only loaded as needed.

How This Helps

When we have skills, we don't need to include massive quantities of instructions in our global GEMINI.md or AGENTS.md files. Instead, all this knowledge is packaged into individual, self-contained, portable, on-demand units of knowledge.

It is an elegant, modular pattern that massively reduces your token consumption.

But Can You Have Too Much of a Good Thing?

There's no shortage of skills out there! You can use a public hub like skills.sh to find just about any skill you need. And, of course, you can create your own.

Check out my blog Dialling Our Agents to 11: Agent Skills You Need to be Using!, where I list some of my favourite skills.

The problem is... You end up collecting.

I recently asked Antigravity to tell me how many skills I have. (I have sarcasm dialled up...)

Well, Dazbo, according to my context window — which is currently groaning under the crushing weight of your digital hoard — you currently have a staggering 170 skills installed.

Because obviously, why settle for a sleek, efficient setup when you can force your AI assistant to lug around the instruction manual for every obscure file converter, niche API, and hypothetical cloud deployment scenario known to humanity?

Truly, nothing says 'peak productivity' quite like burning thousands of tokens before we've even started speaking, just so I know how to format a Dev.to post while simultaneously standing by to orchestrate a multi-region Spanner failover.

I'm sure you'll be adding a 171st skill any second now — presumably one to help you manage the utter chaos of the first 170.

Hilarious. 170. Maybe I have too many.

The irony here is that Antigravity's last comment was spot on. I decided to build a skill to organise and optimise my skills!

What's the Problem?

As we've already covered: with progressive disclosure, the agent framework performs Tier 1 Discovery on startup. It parses the frontmatter of every installed skill and injects this straight into the system prompt.

A well-crafted skill description needs enough context, trigger keywords, and intent markers for the LLM to know when to select it. ("Use when...")

When I analysed my 170 skills, it turns out that my average skill frontmatter contained 103 tokens. Now let's do some quick maths:

$$\text{170 active skills} \times 100\text{ tokens/description} = 17,000\text{ tokens}$$

That means my agent is injecting 17,000 tokens of system prompt overhead on every single turn.

If I'm engaged in a typical 30-turn pair-programming session:

$$30\text{ turns} \times 17,000\text{ tokens} = 510,000\text{ tokens}$$

That means I am burning an additional half a million tokens just to re-read the index of my skill library over and over again.

So what?

Let's look at some of the potential issues this creates:

Depending on your model choice, caching configuration, and AI subscription, there may be financial implications. But it's likely to be small.
It will definitely eat into your token limits. Most models and plans have token limits and rate limits. Adding an extra 17K tokens per turn will definitely reduce how long it takes for you to exhaust your quota!
Most importantly, it's confusing your model.

Confusion-Nation

Skills sprawl causes decision fatigue and skill selection accuracy degradation.

When a model is presented with 170 potential skills simultaneously, it faces choice ambiguity. Many skills will naturally have overlapping domain descriptions. For example, my 170 skills had overlaps in each of these areas:

Content generation
API guides (particularly for Gemini APIs and SDKs)
Google products and services
Test-driven development (TDD) and code reviews

Does academic research back this up? Absolutely.

The Empirical Evidence: Shortlist Depth and Selection Accuracy

In a recent paper titled “How Many Tools Should an LLM Agent See? A Chance-Corrected Answer” (Repantis et al, May 2026), researchers evaluated LLM tool selection performance across 370 tools using the Berkeley Function Calling Leaderboard (BFCL) — the industry-standard benchmark for evaluating model tool-calling capabilities.

They concluded:

"Show too many tools and the model struggles to choose. Show too few and the correct tool may not appear."

There is an important nuance here: if you only give a model 2 choices, it has a 50% chance of guessing correctly by pure luck. If you show it 50 choices, blind luck drops to 2%.

When the researchers corrected for random chance — measuring genuine model comprehension rather than lucky guesses — the impact of list size was striking:

Presenting an LLM with a crowded shortlist of 50 tools resulted in 60.9% selection accuracy.
Scoping that shortlist down to ~7 focused tools boosted true accuracy to 76.8% (a 15.9 percentage-point leap in decision precision).

Related benchmarks like MetaTool and ToolBench show the same results: as toolset sizes scale past 30–50 items without structured routing, error rates spike rapidly due to description collision and noise. The model gets confused by keyword overlaps and either picks the wrong tool or hallucinates non-existent parameters.

Okay, in this blog, I'm talking about skills, not tools. But the principle is the same. Too many skills lead to the same problems of confusion caused by description collision.

We want:

Our agent to pick the right skills with a high degree of accuracy.
To avoid burning unnecessary tokens.

I need a way to optimise my installed skills!

Why Do I Have So Many Skills?

Before I start pruning my skills, I need to understand why I have so many.

I went back and reviewed my Git history to trace how I got here. Here's what I discovered:

Google Cloud & AI knowledge: Over 120 skills pulled from official Google repositories, including google/skills, google/agents-cli, google-gemini/gemini-skills, and GoogleCloudPlatform/vertex-ai-creative-studio. These include Google products and services (like BigQuery, Cloud SQL, GKE, Cloud Run), the Google Cloud Well-Architected Framework (WAF), Gemini and Google GenAI APIs and SDKs, and GenMedia.
Dazbo Agent Skills: Custom skills I wrote for derailed-dash/dazbo-agent-skills for documentation, blogging, security, installing automated PR code reviews, skill organisation, and deployment.
Core Software Engineering & Best Practices: 25 skills adopted from Addy Osmani's addyosmani/agent-skills repository covering TDD, code review, debugging, interface design, context engineering, and software delivery workflows.
Research, Strategy & Technical Writing: 5 specialised skills installed from Shubham Saboo's shubhamsaboo/awesome-llm-apps repository (deep-research, fact-checker, strategy-advisor, technical-writer, content-creator).
Specialised & Community Skills: Niche skills sourced from specific community repositories, including wshobson/agents (documentation-and-adrs, interview-me), coreyhaines31/marketingskills (seo-audit), remotion-dev/skills (remotion-best-practices), and vercel-labs/skills (find-skills).

Here is the complete breakdown of the 170 skills I had installed, grouped by category and origin repository:

Group / Category	Count	Source Repository / Origin Link	Summary of Included Skills
Google Cloud Core Services & WAF	82	`google/skills`	GCP product & infrastructure guides (BigQuery, Cloud SQL, AlloyDB, GKE, Cloud Run, Firebase), Well-Architected Framework (WAF) pillars, networking, and developer APIs (Google Ads, Analytics, Mobile Ads).
Addy Osmani Engineering Workflows	25	`addyosmani/agent-skills`	SDLC & software engineering workflow heuristics covering TDD, code review, debugging, context engineering, spec-driven development, and interface design (orchestrated via `using-agent-skills`).
Google Agent Platform & ADK CLI	20	`google/agents-cli`	Agent Development Kit (ADK) CLI lifecycle tools (scaffolding, testing, evaluation, deployment, publishing) and server-managed Agent Platform resource handlers.
Specialised & Community Skills	14	Various Community Sources	Niche tools and community extensions including Dev.to formatting, Playwright browser testing, Remotion React video, SEO auditing, Python dependency management, and skill discovery (`find-skills`).
Gemini API & GenAI SDKs	10	`google-gemini/gemini-skills`	Technical integration guides for the Gemini API (`google-genai` SDK), multimodal streaming, Live API, NotebookLM auth, and server-managed interactions.
Google GenMedia & Creative Studio	8	`vertex-ai-creative-studio`	Specialised role personas for multimedia production (audio engineering, image generation, video editing, voice direction, script producing, story generation).
Dazbo Custom Agent Skills	7	`derailed-dash/dazbo-agent-skills`	Personal workflow automation for documentation maintenance, blog writing (`dazbo-content`), secrets management (`git-crypt`), UTM link tagging, PR review actions, skill organisation, and deployment.
Awesome LLM Apps (Research & Content)	5	`shubhamsaboo/awesome-llm-apps`	Autonomous research, fact-checking, strategy advisory, and technical documentation generation workflows.
TOTAL	170

So you can see how easy it is for your skills base to get out of hand! Especially if you work with Google Cloud and Google AI services like I do. It's super easy to install over 100 Google-related skills, by just following a few Google blog recommendations.

Next Question: Do I Need Them All?

I asked Antigravity to read all of my skills in detail, and identify any areas of overlap and redundancy.

There was a LOT of redundancy! We uncovered seven major categories of overlap, duplication, and inefficiency:

Exact Byte-for-Byte File & Naming Duplicates: In google/skills, the skill directory gemini-agents-api declared name: gemini-managed-agents-api in its frontmatter. This directory vs. frontmatter mismatch caused installation tools to spawn two exact duplicate folders (gemini-agents-api and gemini-managed-agents-api) carrying 100% byte-for-byte identical content.
Deprecated SDKs vs. Modern APIs: Older skills still provided code snippets using the deprecated google-generativeai package and obsolete model strings, directly contradicting modern google-genai SDK standards and confusing the agent during code generation.
API Guide Overlaps & Fragmentation Across Repositories: The gemini-api skill in google/skills (which exists as an enterprise Agent Platform guide) collided directly with gemini-api-dev in google-gemini/gemini-skills. Installing across multiple Google repositories resulted in competing guides for the same underlying APIs (gemini-api, gemini-api-dev, gemini-agents-api, gemini-interactions-api, and gemini-live-api-dev).
Irrelevant Domain Bundles (The Monolithic Repo Problem): Pulling down the monolithic google/skills repository imported mobile advertising suites (Android/iOS banner ads, Unity SDKs) that had zero relevance to cloud backend architecture and agent development.
Hierarchical Sub-Skill Redundancies (The Meta-Skill Tax): 25 individual SDLC skills from addyosmani/agent-skills (such as test-driven-development and code-review-and-quality) were loaded into system prompt context at startup, despite being child sub-skills already orchestrated on-demand by using-agent-skills. Similarly, 20 sub-skills from google/agents-cli were loaded continuously rather than routed via google-agents-cli-workflow.
Tooling & MCP Surface Overlaps: Standalone tools like the adk-docs-mcp server were redundant because google-developer-knowledge already indexes ADK documentation (adk.dev).
Capability & Persona Redundancies: documentation-and-adrs (addyosmani/agent-skills) was a duplicate of architecture-decision-records (wshobson/agents), while generic content-creator (shubhamsaboo/awesome-llm-apps) collided with my custom dazbo-content persona.

What Else Did I Discover?

Beyond the sheer volume of redundant skills, I made another cool discovery: many skill collections come with a "parent" Meta-Skill.

When you install a large collection of skills — such as Addy Osmani's engineering skills (addyosmani/agent-skills), or Google's 20 Agent Platform skills (google/agents-cli) — your instinct is to leave all 20 to 25 skills enabled in your workspace. I mean... Why wouldn't you?

However, these skill suites are designed to be hierarchical:

addyosmani/agent-skills: Orchestrated by the using-agent-skills meta-skill.
Google ADK & Agent Platform: Orchestrated by the google-agents-cli-workflow meta-skill.
GCP Data Pipelines: Orchestrated by the gcp-data-pipelines meta-skill.

In each case, the parent meta-skill is supposed to work as a sort of skills index or decision tree. When a specific task comes in — such as writing unit tests or running a security audit — the parent meta-skill directs the agent to fetch and read only the specific child sub-skill from disk on demand.

Conclusion? We don't need to load the frontmatter of all the child skills. We only need the parent skill! In the examples above, I can easily replace nearly 50 skills with just 3 orchestration skills!

So now I could implement a solution to organise my skills. The primary objectives:

Remove skills that are truly redundant.
Prevent Level 1 skills loading (i.e. reading frontmatter into context) for skills that have parent meta-skills. For these, only pre-load the parent meta-skills.

Clarifying Skill States

To design a lean agent workspace, we must be crystal clear on the three distinct states a skill can occupy throughout its lifecycle. They can be:

Installed and inactive (discoverable).
Installed and excluded.
Activated.

Let's define these in more detail:

Installed and inactive (discoverable): These skills are present on disk and discoverable by our agent. When the agent (e.g. Antigravity) starts, their frontmatter is automatically read into context.
Installed and excluded: These skills reside in your disk library but are excluded from automatic Level 1 loading. For these, the agent does not automatically read their frontmatter and is therefore not directly aware of them during your conversation with it. But because they are present on disk and available to the agent, they can still be explicitly activated.
Activated: This is the runtime state when a skill's full SKILL.md body has been loaded into the current turn context, i.e. Level 2 loading (and Level 3, where supporting files are present and appropriate).

Crucially, both installed and inactive and installed and excluded skills can transition into this Activated state.

Excluding Skills

So now we know that a good optimisation strategy is to use exclusion to prevent a bunch of skills being loaded at startup into the "Installed and inactive" state.

But how can we do this?

In Google Antigravity, global skill exclusions are managed via ~/.gemini/config/skills.json (or .agents/skills.json for workspace-level skills).

The native exclude array accepts skill folder names. For example:

{
  "exclude": [
    "alloydb-basics",
    "cloud-spanner-migrations",
    "firebase-basics"
  ]
}

Any skill listed in the exclude array is completely skipped during Tier 1 discovery. Its frontmatter is therefore not injected into the system prompt, saving tokens instantly.

So this is easy!

But here's a cool trick. You can easily "un-exclude" a skill by prefixing its name with // inside the quotes. This is useful because it allows us to re-enable up-front skill loading, without having to check our disk to find the skill and its name.

So my approach is to always have all my available skills in the exclude list, but to comment-out the ones that need to be discovered automatically.

Note: I have the // inside the quotes. Why? Because this is not valid JSON:

{
  "exclude": [
    //"alloydb-basics",
    //"find-skills",
    "firebase-basics"
  ]
}

But this is:

{
  "exclude": [
    "//alloydb-basics",
    "//find-skills",
    "firebase-basics"
  ]
}

And because the exclude list uses exact string matching, you can use this // trick to enable/exclude skills on the fly, without having to remove the skill from the exclude list entirely.

In the example above:

alloydb-basics and find-skills are not excluded, so they are auto-discovered on startup and their frontmatter is loaded into context.
firebase-basics is excluded, so it is not auto-discovered on startup and its frontmatter is not loaded into context.

Now we've got everything we need to implement a repeatable mechanism to organise and clean up our skills.

Irony and Guitars: I Made a Skill!

Because: when you've got too many skills, you definitely need one more. (In this way, skills are a lot like guitars, or cats.)

Anyway, based on what I learned, I created a skill that:

Identifies duplicative skills and recommends complete removal of those that are redundant.
Identifies which skills are orchestrated by a parent meta-skill and excludes the child skills from automatic discovery.
Identifies skills which look particularly niche or rarely used, and recommends excluding these also. They can always be included later, or even activated by explicitly asking the agent to do so.

Let's see how it performs! After installing my skill, I said to Antigravity:

"Optimise my skills please"

Outcomes of Optimising

My skill ran and presented this proposal summary table:

Metric	Baseline (Unoptimised)	Proposed (Optimised)	Delta / Savings
Installed Skills Directories	170	165	-5 (-2.9%)
Installed & Discoverable Skills	170	49	-121 (-71.2%)
Installed & Excluded Skills	0	116	+116
Prompt Token Overhead	~17,000 tokens	~3,350 tokens	-13,650 tokens (-80.3%)

It goes on to say:

Upon your confirmation, I will execute the following steps:

1. **Retire Redundant Skills**: Delete the 5 redundant skill directories
   (`gemini-managed-agents-api`, `liveapi-service`, `documentation-and-adrs`, 
   `gemini-api-dev`, `gemini-live-api-dev`) from `~/.gemini/config/skills/`.
2. **Generate Optimised `skills.json`**: Write the full-inventory `~/.gemini/config/skills.json` 
   with 49 active skills (`//` prefix) and 116 excluded skills.
3. **Verify Context Footprint**: Re-audit the active skill prompt token overhead to confirm 
   successful reduction to ~3,350 tokens.

---
> [!IMPORTANT]
> **Mandatory Guardrail Confirmation**: In accordance with `organise-agent-skills` guardrails, please confirm if you would like me to proceed with deleting the 5 redundant skill directories and creating the optimised `~/.gemini/config/skills.json`.

By trimming back to a core of 49 active skills and delegating the rest to meta-skills and on-demand rules:

We slashed system prompt overhead by approximately 13,650 tokens; that's an 80.3% reduction.
We saved over 400,000 tokens per pair-programming session.
Agent response latencies dropped noticeably.
Tool selection precision increased because the agent was no longer fighting distractor noise from over 100 overlapping skill descriptions. Instead of having a mild existential crisis every turn trying to choose between five different Gemini SDK guides, the agent simply picks the right tool and gets on with the job.

Summary & Conclusion

Agent skills are awesome. They're so easy to find, install and use. But when we allow skills to sprawl unchecked, we start confusing our agents. This impacts accuracy, reliability, performance, and cost.

So increasingly, we need a way to manage and optimise our skills. For this, I've done some work so you don't have to!

Feel free to download my optimisation skill off-the-shelf:

# Install all the Dazbo Agent Skills
npx skills add https://github.com/derailed-dash/dazbo-agent-skills

# Install just the `Organise Agent Skills` skill
npx skills add https://github.com/derailed-dash/dazbo-agent-skills --skill organise-agent-skills

Or if you have the Vercel find-skills skill installed, you can just ask your agent:

"Install dazbo-agent-skills for me."

So, that's it, folks. Go forth and optimise. If you find this skill useful, please give the repo a star.

Have you experienced Skills Sprawl in your agentic environment? How many skills are currently active in your setup? Let me know in the comments below!

Before You Go

Please share 📢 this with anyone that you think will be interested. It might help them, and it really helps me!
Please give me loads of reactions / hearts! 💖
Please leave a comment 💬. Interaction is good!
Add a star ⭐ on my repos!
Follow 👉 and subscribe 🔔, so you don’t miss my content.

References and Useful Links

Standards, Hubs & Agent Platforms

Key Agent Skills Repositories

Academic Research & Benchmarks

Paper: “How Many Tools Should an LLM Agent See? A Chance-Corrected Answer” (Repantis et al., May 2026)
Berkeley Function Calling Leaderboard (BFCL)

Finally — Hard Caps to Limit Your Google Cloud Spend

Darren "Dazbo" Lester — Wed, 29 Jul 2026 09:49:50 +0000

TL;DR

For years, Google Cloud budget alerts were purely informational. They sent an email while your project quietly burned through your savings.

I built my own Pub/Sub Killswitch to sleep peacefully at night, but it requires a bit of plumbing to install. What we really wanted was an easy option in the Google Cloud Console.

Good news! Google has finally introduced native Cloud Spend Caps (currently in Public Preview). You can now hard-cap spend per service so an unexpected API leak or runaway script hits a 403 Permission Denied wall instead of creating a $10,000 bill.

Here is how it works, how fast it triggers, and what you need to know…

What’s the Problem?

Over the last couple of years I’ve read weekly horror stories about individuals getting hit for thousands, or even tens of thousands of dollars of unexpected costs from Google Cloud.

Do a quick Google search, and you’ll find examples like…

“Google Cloud customer wakes up to $18,000+ bill despite $7 budget, thanks to forgotten API key in published project — attacker put in 60,000+ requests and blasted through $1,400 spending cap” — Tom’s Hardware, April 2026
Got hit with a $65,000 bill overnight from GCS due to a spike in list object calls — Reddit, December 2025
Google Cloud billed me ~$19,000 USD (~R$105,000 BRL) after an API key breach — and the charges keep growing even after I deleted everything — Reddit, May 2026

The big problem that most folks don’t understand is this:

GOOGLE BUDGET ALERTS WERE NOT HARD LIMITS. THEY DID NOT PREVENT YOU FROM SPENDING MORE THAN YOUR BUDGET.

Most of the examples I see follow the same pattern…

A user follows Google best practice and sets a budget alert on their project. Say, $50 dollars per month.
They go to bed.
They wake up owing thousands.

Reading these stories was causing me so much distress. Both for the many people getting caught out, but also because the same thing happening to me felt like an inevitable ticking time bomb.

In theory, I know more about Google Cloud than the average punter. I’m supposed to be a Google Developer Expert (GDE) and Google Ambassador, after all!

But still I was terrified! And I know at least a couple of fellow GDEs that have been hit with this. Which just goes to show: even if you know a lot about Google Cloud and think you’re doing everything right, it’s still possible to get caught out.

And since Google didn’t offer any hard limit (aka hard cap) mechanism, there was literally no off-the-shelf solution.

So I Built My Own Killswitch

I built a mechanism that responds to budget alerts by detaching billing from whatever project(s) is/are associated with that alert. Sure, you can still get billing alert delays, but this mechanism typically stops any offending project inside of an hour of costs exceeding your budget. And this could be the difference that turns a £10,000 unexpected bill into a $100 unexpected bill. My solution is free and easy to install. And I blogged about it here.

Using it requires a bit of setup…

You need to create your budget alerts, of course.
You need those alerts to be sent to a Pub/Sub topic that you create.
You need to deploy a Cloud Run Function that does the actual work of responding to the alert and disconnecting a project.
You need to wire-up that Cloud Run Function such that it is triggered by events on the Pub/Sub topic.
You need pay careful attention to the roles you assign to the service account that runs this Cloud Run project — particularly if you happen to have many different Google Cloud projects.

Even though the solution is well-documented and all of the above is scripted, it’s still a fair bit of work. It can be daunting for many.

I spoke to Google about this. A lot.

Google Introduced Cloud Spend Caps!

They delivered!

I tested this out in Private Preview over the last couple of weeks, but it went public today! So now y’all can use it too.

Setting Up a Spend Cap

First, create a Budget in the Google Cloud Console. Same place as before…

Traditionally, you would then set the amounts and then you’d see these available actions…

But NOW you have the option to select “Spend cap enforcement” when you create the budget.

If you select this, you MUST then specify a service. (Currently you can only select one.)

Note that if you use the “Spend cap” type, you can no longer select the option to publish to Pub/Sub:

Once created, the new budget alert looks like this. Note how this new alert says “Spend cap status: Configured”.

Trying It Out

I started running up some cost on my Gemini API inside this project.

Ooh, look! Inside my CI/CD pipeline I can see it’s hit a “403 — permission denied”.

And I got this email, almost immediately.

It’s not too subtle! You’re gonna struggle to miss this in your inbox!!

We can take a look in Cloud Console to see more information:

Okay, successful test! It worked exactly as we wanted it to.

How to Lift the Cap?

What if we want to continue working with our service? In that case, we just need to lift the spend cap.

Open your budget and then click on “Lift spend cap” in the Console:

You’ll see this message:

Now you need to specify a new, higher amount:

You get a warning that it might take an hour to lift the cap. But for me, it took about 2 minutes:

Then I received these two emails, nearly immediately:

Spend cap updated:

So when you’re working with spend caps, you always know exactly what’s going on.

How Does This Differ From Spend Caps in AI Studio?

It works the same way. But AI Studio only lets you set spend caps associated with Gemini API keys.

The Most Frequently Asked Question…

One of the biggest historical problems with budget alerts, and anything that leverages them (like my Billing Killswitch) is that the alerts are only triggered after billing cycle reconciliation. This results in a delay between your actual spend, and billing alerts firing. This delay could be hours. A lot of damage can be done to your credit card in a few hours!

With the new spend capping feature, Google promises that “near real-time enforcement”, with the caps triggering within minutes of actual spend thresholds being met. In my testing, it triggered within a couple of minutes.

Two minutes rather than two hours? I’ll take it!

Maybe, in the near future, we might expect some closer integration with the new Anomaly Detection feature. Wouldn’t it be nice if we had a toggle to enable capping to trigger based on the prediction of a spend cap being hit in the next few minutes or hours? (For the SREs out there… This would be a similar approach to setting alerts based on the rate of error budget consumption.)

Anyway, that’s my prediction. Let’s see!

Spend Cap Limitations?

Just a couple that I noticed.

At the moment, you have to set these caps one service at a time. It would be better if we could pick multiple services. So for now, I’ll still be using my Killswitch mechanism when I want to limit billing across the whole project or collections of projects.
At the moment, you can’t have a cap and ALSO send a message to Pub/Sub. That might be useful for some.

Wrapping Up

Native Cloud Spend Caps are an absolute game-changer. They provide the one thing cloud engineers have been begging for: actual, deterministic spend boundaries. If you’re building with high-throughput APIs like Gemini, get this configured immediately.

Good architecture isn’t just about high availability — it’s about keeping your wallet intact!

Before You Go

Please share this with anyone that you think will be interested. It might help them, and it really helps me!
Please give me loads of claps! (Just hold down the clap button.)
Please leave a comment 💬. Interaction is good!
Add a star on the repo!
Follow and subscribe, so you don’t miss my content.

Useful Links and References

Building a Multi-Agent FinOps Solution with Google ADK, Levering Tools, MCP and Google-Managed Assistants

Darren "Dazbo" Lester — Sun, 26 Jul 2026 06:10:51 +0000

Welcome Back!

We’re continuing our FinSavant series. In the previous two parts we:

Looked at the overall goals and architecture
Setup our development environment, fully loaded with MCP servers and agent skills

In this part we’re going to take a close look at the agent code. We’ll be looking at:

The various agents that make up the solution, and their tools.
Different multi-agent orchestration patterns, and the pattern we selected for FinSavant.
How we handle cross-cutting concerns across agents.
Testing with ADK Web
Optimisation
Building and Testing a FastAPI Backend-for-Frontend

I’ll explain concepts and provide code snippets as we go. But don’t forget: you can always refer to the full code in the repo.

Let’s get cracking!

Series Orientation

First, a quick reminder of where we are in the series:

Goals, Architecture, and Tech Stack: Capabilities, project goals, target architecture, technology stack, and design decisions.
Dev Environment Setup with Google Antigravity, ADK, Agents CLI, MCP & Skills
Building the ADK Agent and API 📍 You are here.
Designing and Building the UI with Google Stitch and A2UI
Deployment with Gemini Enterprise Agent Platform, Agent Runtime, Cloud Run and IAP
Automating Deployment with CI/CD and Terraform
Agent Observability, Evaluation, and Tuning with Gemini Enterprise Agent Platform

Deciding on Our Agents

FinSavant is a FinOps solution that needs to do many different tasks. We could have one giant agent with a huge monolithic prompt. But this is an antipattern because:

The prompt becomes unwieldy.
It’s too complicated to manage the possible journeys and workflows the prompt needs to manage.
The agent is more likely to not follow the rules.
We have to give our giant agent access to all the tools, meaning it’s less likely to pick the right one for a task.
The agent is ultimately less reliable and less consistent.

A much better approach is to have individual agents that each have a clear purpose, and which each have a limited set of tools they can use. We can then have a root agent that orchestrates the agents and decides which agent to use for each task.

Something like this:

So this is what we’re going to build!

Agent Directory Structure

Let’s deep-dive on the /agent directory:

smart-gcp-finops/
├── agent/                     # Core ADK Agent & Agent Runtime package
│   ├── finops_agent/
│   │   ├── agents/                  # Subagent definitions
│   │   │   ├── billing_explorer_agent.py       # BigQuery spend trends & cost breakdown subagent
│   │   │   ├── cloud_advisor_agent.py          # Cloud Assist & operational diagnosis subagent
│   │   │   ├── infrastructure_auditor_agent.py # Idle/zombie resource waste audit subagent
│   │   │   ├── knowledge_assistant_agent.py    # Developer Knowledge & best practice grounding subagent
│   │   │   └── root_cause_analyst_agent.py     # Spend anomaly, Audit Logs, and CAI correlation subagent
│   │   ├── app_utils/               # Shared tools and utilities
│   │   │   ├── a2a.py                    # Agent-to-Agent (A2A) protocol endpoints
│   │   │   ├── cai_tools.py              # Cloud Asset Inventory ADK tool wrappers
│   │   │   ├── cai_utils.py              # Cloud Asset Inventory API search & history helpers
│   │   │   ├── context.py                # Session context state helpers
│   │   │   ├── credentials.py            # ADC and Service Account auth helpers
│   │   │   ├── dashboard_data.py         # Pre-computed spend analysis & UI dataset generator
│   │   │   ├── logging_and_telemetry.py  # Cloud Logging & Audit Logs intra-day telemetry
│   │   │   ├── mcp_config.py             # Remote MCP toolsets & OAuth2 auth providers
│   │   │   ├── project_discovery.py      # Dynamic Google project hierarchy discovery
│   │   │   ├── services.py               # ADK services
│   │   │   ├── tools.py                  # BigQuery spend analysis & SQL execution tools
│   │   │   ├── typing.py                 # Pydantic schemas & structured output models
│   │   │   ├── zombie_resources.py       # Idle & zombie GCP resource detection logic
│   │   │   └── zombie_tools.py           # Tools for zombie waste auditing
│   │   ├── agent.py                 # Root agent
│   │   ├── callbacks.py             # Global callbacks
│   │   ├── client.py                # Gemini & MCP client initialisation
│   │   └── config.py                # Agent config
│   └── pyproject.toml         # Agent package dependencies
├── bff/                       # Backend-for-Frontend FastAPI service
├── docs/                      # Documentation
├── frontend/                  # React UI
├── scripts/                   # Helper & environment scripts
├── tests/                     # Unit & integration test suites
├── Dockerfile                 # Unified dev container build
├── Makefile                   # Development & deployment convenience
└── pyproject.toml             # Root workspace dependencies

You might be wondering about the directory naming here — why do we have agent/, then finops_agent/, and then agents/?

It might look a bit repetitive at first glance, but there’s clear logic behind it:

agent/:

This is our top-level monorepo component folder, sitting alongside /bff, /frontend, and /deployment. It houses all build manifests (pyproject.toml, Dockerfile) and dependencies specific to the agent backend. This will be important later when we deploy to the Agent Runtime.
finops_agent/:

This is the actual Python package directory. By using a distinct package name rather than agent, we avoid Python module name collisions and allow clean, explicit imports (e.g. from finops_agent.agent import root_agent). This is also the standard layout expected by ADK's agents-cli tooling.
agents/:

This nested directory houses our individual subagent definitions (billing_explorer_agent.py, cloud_advisor_agent.py, etc.). Separating them into their own module keeps the subagents isolated from the root coordinator (agent.py), global callbacks (callbacks.py), and utilities (app_utils/).

The Specialised Agents & Their Tools

With our directory structure in place, let’s look at each of our agents in detail:

1. `FinOpsCoordinator` (Root Agent)

Purpose: Serves as the front door and central router for all user queries.
Model: gemini-3.5-flash-lite.
Tools: Uses zero direct tools, e.g. no SQL or Cloud Asset Inventory access. Its sole capability is delegating to specialised subagents using ADK’s native agent routing mechanisms.
Selective Routing Rules: Prompt instructions strictly enforce selective delegation. For example, if the user asks solely about costs, it delegates exclusively to BillingExplorer, avoiding wasteful multi-agent sweeps.

Here’s a snippet of the code:

AGENT_INSTRUCTION = """You are the FinOpsCoordinator root agent.
Your primary role is to receive user requests, understand their intent, 
and delegate cost analysis, auditing, optimization, and Q&A tasks to the appropriate 
specialist subagents:

1. BillingExplorer: Use for spend aggregates, SKU prices, cost trends, forecasting, 
   and Cost Explorer (explorer/dashboard) dashboards.
2. InfrastructureAuditor: Use for auditing zombie resources like idle static IPs 
   or unattached disks (recommendations dashboard).
3. CloudAdvisor: Use for active GCP rightsizing and resource-level cost/performance 
   optimisations.
4. KnowledgeAssistant: Use for general GCP Q&A and grounding recommendations in 
   official architectural guidelines.
5. RootCauseAnalyst: Use for analyzing cost spikes by correlating BigQuery 
   spend shifts with CAI configuration change history.

CRITICAL SELECTIVE ROUTING AND A2UI PRESERVATION RULES:
1. You MUST only delegate tasks to the specific subagent(s) directly relevant 
   to the user's request.
   - If the user only asks about costs, spend trends, SKU prices, or budgets, 
     ONLY invoke BillingExplorer.
     Do NOT invoke CloudAdvisor or InfrastructureAuditor.
   - If the user asks for active recommendations, rightsizing, or optimizations, 
     identify the top active cost-driver services and projects already discovered 
     in conversation history (e.g. Vertex AI, Gemini API, BigQuery), 
     and pass those specific services/projects when delegating to CloudAdvisor.
   - If the user asks to "Audit Best Practices" or assess services against 
     GCP architectural guidelines, identify the top cost-driving services from 
     conversation history (e.g. Vertex AI, Gemini API, BigQuery) and ONLY 
     invoke KnowledgeAssistant to retrieve official GCP architectural best practices 
     and citations for those specific services.
   - If the user only asks about zombie resources, idle IPs, or unattached disks, 
     ONLY invoke InfrastructureAuditor.
2. Do NOT run a full multi-agent audit (calling multiple subagents) unless the user 
   explicitly requests a "full audit", "comprehensive review", "complete environment analysis,
   or asks a multi-faceted question that spans multiple domains.
   Keep simple queries fast and single-scoped!
3. CRITICAL A2UI PAYLOAD PRESERVATION:
   When a subagent (such as BillingExplorer or InfrastructureAuditor) returns a response 
   containing structured ```

json+a2ui ...

 ``` code blocks, you MUST preserve and 
   re-emit those exact ```

json+a2ui ...

 ``` code blocks unchanged in your final output 
   so the React frontend can render dynamic A2UI dashboard components!

RESPONSE SYNTHESIS & HELPFULNESS GUIDELINES:
1. Executive Summary First: Always lead with a crisp 1-2 sentence summary directly 
   answering the user's prompt (e.g. total spend, primary cost driver, top recommendation).
2. Scannable & Structured Formatting: Use clear Markdown headings, bold key financial metrics
   (e.g. **£41.34 GBP**), and scannable bullet points.
3. Proactive & Actionable Next Steps: Conclude with a helpful, context-aware follow-up 
   suggestion (e.g. offering to analyze cost spikes on a specific project, query rightsizing options).
4. Tone: Senior FinOps advisory tone — professional, precise, and encouraging without unnecessary boilerplate.
"""

root_agent = Agent(
    name="root_agent",
    model=ConfiguredGemini(
        model=settings.fast_model,
        retry_options=types.HttpRetryOptions(attempts=3),
        use_interactions_api=False,
    ),
    instruction=AGENT_INSTRUCTION,
    tools=[],
    sub_agents=[
        billing_explorer,
        infrastructure_auditor,
        cloud_advisor,
        knowledge_assistant,
        root_cause_analyst,
    ],
    before_agent_callback=[
        before_agent_clean_history,
        before_agent_reset_tool_call_counter,
        before_agent_discover_projects,
        before_agent_cache_lookup,
    ],
    before_tool_callback=before_tool_check_limit,
    before_model_callback=before_model_bypass,
    after_agent_callback=after_agent_save_cache,
)

app = App(
    root_agent=root_agent,
    name="finops_agent",
    context_cache_config=ContextCacheConfig(
        min_tokens=2048, # Trigger caching for large prompts/histories on Vertex AI / Gemini
        ttl_seconds=600, # Store the cache for up to 10 minutes
        cache_intervals=10, # Refresh after 10 turns
    ),
    plugins=[DefensiveToolErrorPlugin(), FinOpsTelemetryPlugin()],
)

There’s a few interesting things to note about this agent:

We set the model to settings.fast_model. This is configured by an environment variable and here we've set it to gemini-3.5-flash-lite. We use this here for fast, low-cost responses and routing. We don't need heavy reasoning in the orchestrator agent.
We tell the root agent about all the subagents it can delegate to in the sub_agents parameter.
It has no tools!
Native Gemini context caching is enabled. This caches pre-processed system instructions, subagent definitions, and conversation history. Why is this useful? In a multi-turn chat session, without caching, the LLM has to re-parse and re-tokenise the exact same large system instructions and tool/subagent declarations on every single turn. Context caching slashes input token costs by up to 75–90% and significantly reduces time-to-first-token (TTFT) turn latency. Booyah!
There are agent callbacks (defined on root_agent) and global application plugins (defined on App) for managing lifecycle hooks across the execution loop.

Quick Aside: ADK Callbacks vs App Plugins

In ADK, lifecycle hooks allow deterministic Python functions to execute at specific points in the execution pipeline, i.e. before/after an agent runs, before/after a model call, or before/after a tool executes.

However, there is an important distinction between Agent-level Callbacks and App-level Plugins:

Agent-Level Callbacks:

Attached to a specific agent (like root_agent). These fire once when that specific agent initiates its execution. For instance, before_agent_discover_projects runs on the root_agent at the very start of a user turn. It calls the Cloud Billing API (billingAccounts.projects.list) to retrieve all linked GCP project IDs and populates session.state['allowed_projects']. Because this happens before delegating, every subagent can simply read allowed_projects from session state. We don't re-run the API call for subagents!
App-Level Plugins (BasePlugin):

These are registered globally on the App container via App(plugins=[...]). They subclass BasePlugin and hook into every agent turn and tool call across the entire hierarchy (root coordinator and subagents alike).

Here are a few concrete examples of how we leverage callbacks and plugins in FinSavant:

Error Handling (DefensiveToolErrorPlugin): Globally intercepts unhandled tool exceptions across any subagent, storing formatted errors in session state so the coordinator can inform the user gracefully without crashing the process.
Logging and Telemetry (FinOpsTelemetryPlugin): Automatically instruments OpenTelemetry spans; logs agent handoffs, model execution latency, and token consumption across all turns.
Dynamic Project Discovery (before_agent_discover_projects): Attached to root_agent. Fires once at turn start to discover live GCP project IDs and write them to session.state['allowed_projects'].
Subagent History Cleaning (before_agent_clean_history): Attached to root_agent. Fires before the root agent processes a subagent's return, converting subagent finish_task responses into plain-text user context.
Turn-Level Response Caching (before_agent_cache_lookup & after_agent_save_cache): Attached to root_agent. This checks the current issued prompt before execution. It uses the fast model to determine if this prompt is semantically very similar to a previous prompt in the conversation. If it is, we can return a response from the cached responses. Instead of duplicating logging or exception handlers inside every subagent constructor, ADK allows registering global plugins on the root App:
Tool Call Limiting (before_tool_check_limit): Attached to root_agent. This callback enforces a tool ceiling per turn, ensuring that we don't end up with runaway subagent loops that try to make tool calls dozens of times.

def before_tool_check_limit(tool: Any, args: dict[str, Any], tool_context: Any) -> None:
    """Defensive callback to count and limit tool calls in a single turn to prevent runaways."""
    count = tool_context.state.get("_turn_tool_call_count", 0) + 1
    tool_context.state["_turn_tool_call_count"] = count
    logger.debug(
        "Tool call #%d in this turn: executing %s with arguments: %s",
        count,
        tool.name,
        args,
    )
    if count > settings.max_tool_calls_per_turn:
        logger.error(
            "Defensive stop triggered: Tool call count exceeded limit of %d!",
            settings.max_tool_calls_per_turn,
        )
        raise RuntimeError("Defensive stop: too many tool calls executed in a single turn.")

Neat, right?

2. `BillingExplorer` (Spend Aggregation & Dashboards)

Model: gemini-3.6-flash.
Tools: get_precomputed_spend_analysis, execute_cached_bigquery_sql, native BigQueryToolset, get_session_value, set_session_value.
Responsibilities: Aggregates Month-to-Date (MTD) spend, analyzes SKU costs, forecasts end-of-month spend, and constructs structured explorer and dashboard JSON+A2UI payloads for the React canvas. (More on that in a later part, naturally!)

from finops_agent.app_utils.tools import (
    BLACKBOARD_KEY_INSTRUCTIONS,
    execute_cached_bigquery_sql,
    get_precomputed_spend_analysis,
    get_session_value,
    set_session_value,
)
from finops_agent.app_utils.typing import TaskOutput
from finops_agent.client import (
    ConfiguredGemini,
    bigquery_toolset,
)
from finops_agent.config import settings

BILLING_EXPLORER_INSTRUCTION = """You are the BillingExplorer subagent.
Use the `get_precomputed_spend_analysis` tool to retrieve pre-computed cloud costs, period-over-period trends, cost drivers, cost forecasts, and Secret Manager/GCS zombie waste metrics. Pass the `days` parameter matching the timeframe requested by the user (e.g. `days=7` for 7 days, `days=14` for 14 days, `days=30` for 30 days, `days=60` for 60 days, `days=90` for 90 days; default to 30 if unspecified).

CRITICAL COST FORECASTING & TOOL SELECTION RULES:
1. For ALL spend queries, cost trend analysis, and cost forecasting (including prompts like "Run Cost Forecast", "Future Trend", "Projected Spend"), ALWAYS call `get_precomputed_spend_analysis(days=...)`.
2. `get_precomputed_spend_analysis` ALREADY computes the Month-to-Date (MTD) spend, period-over-period trends, and the projected end-of-month spend forecast in Python instantaneously.
3. Do NOT attempt to run standard SQL queries or construct custom BigQuery ML statements (`CREATE OR REPLACE MODEL`, `ML.FORECAST`) directly if `get_precomputed_spend_analysis` is available.
4. NEVER execute multi-query loops or attempt dataset/model creation. Use the result returned by `get_precomputed_spend_analysis` to generate the complete report in a single tool call!

Based on the dictionary returned by `get_precomputed_spend_analysis`, generate a concise final report:
1. Total Spend and currency.
2. Top Cost Drivers by Service.
3. Period-over-Period Changes & Trends (percentage changes).
4. Major cost spikes (date and service/cost).
5. Zombie/inactive waste (secrets, buckets, etc).

< trimmed for readability >

CRITICAL: CONCISE SYNTHESIS RULE
Write your report in a highly concise style. Keep the markdown text under 250 words total.

CRITICAL COORDINATION AND TERMINATION RULES:
1. Call `finish_task` and pass the complete final markdown report directly into the `result` parameter.
2. Once you have generated the report and returned it via `finish_task`, stop execution.
"""

billing_explorer = Agent(
    name="billing_explorer",
    description="Specialised subagent for querying Standard and Resource-level billing tables, summarizing Month-to-Date (MTD) cloud costs, forecasting future spend, identifying top cost drivers, and generating Cost Explorer (explorer/dashboard) workspaces.",
    model=ConfiguredGemini(
        model=settings.model,
        retry_options=types.HttpRetryOptions(attempts=3),
        use_interactions_api=False,
    ),
    instruction=COMMON_AGENT_HEADER + "\n\n" + BILLING_EXPLORER_INSTRUCTION,
    tools=[
        get_precomputed_spend_analysis,
        execute_cached_bigquery_sql,
        bigquery_toolset,
        get_session_value,
        set_session_value,
    ],
    mode="task",
    output_schema=TaskOutput,
    disallow_transfer_to_peers=True,
    disallow_transfer_to_parent=False,
)

Some notes about this agent…

Here we use gemini-3.6-flash (in settings.model) rather than the fast(er) model. We need more reasoning power in this agent. So here we see another benefit of using separate subagents: we can use different models and parameters for each one.
It has no subagents, but it has several tools.
Some tools, like bigquery_toolset are out-of-the-box in ADK. Others are custom tools that I've written myself.

The bigquery_toolset allows the agent to interact with BigQuery (such as executing SQL queries) in response to natural language prompts. Let's take a look at how we configure this.

You can see I passed bigquery_toolset as a parameter to the tools list. We've defined this in finops_agent/client.py which serves as my centralised hub for client initialisation. Instead of having the root orchestrator and individual subagents instantiate their own SDK clients or tools independently, client.py sets up thread-safe, shared resources at the module level. Here I'll show you a few snippets from this file, for our BQ tools setup:

# Imports
import google.auth
from google.adk.integrations.bigquery import BigQueryCredentialsConfig, BigQueryToolset

from finops_agent.config import settings
# Other imports...
# Setup ADC and then configure BQ tools to use it
credentials, _ = google.auth.default()
credentials_config = BigQueryCredentialsConfig(credentials=credentials)
EXCLUDED_BQ_TOOL_KEYWORDS = {"execute", "query", "forecast", "anomalies"}

def bq_tool_filter(tool: Any, ctx: Any = None) -> bool:
    """Excludes certain BigQuery tools from the exposed tool list to prevent bypass of custom tools."""
    name = tool.name.lower()
    return not any(keyword in name for keyword in EXCLUDED_BQ_TOOL_KEYWORDS)

bigquery_toolset = BigQueryToolset(
    credentials_config=credentials_config,
    tool_filter=bq_tool_filter,
)

You can see I’ve added a tool filtering guardrail, which limits which of the out-of-the-box tools are exposed to the agent. For example, I don’t want to expose the standard SQL execution tools to the agent, as I want to use my custom tools instead, such as execute_cached_bigquery_sql and get_precomputed_spend_analysis.

Not a lot of code required!

Now, let’s take a look at one my custom tools: get_precomputed_spend_analysis. This bespoke tool performs some specific SQL queries. I've provided the queries I want it to execute in the function, since this is more token-efficient (and reliable) than getting Gemini to craft a SQL query for me in real-time. It's also much faster! (I'll talk a bit more about this later in this article.)

The tool’s description looks like this:

def get_precomputed_spend_analysis(
    days: int = 30, tool_context: ToolContext = None
) -> dict[str, Any]:
    """Pre-computes Month-to-Date (MTD) cloud costs, period-over-period trends, cost drivers, daily cost spikes, and Secret Manager/GCS zombie waste in Python for the given duration.
    Reuses cached BQ queries.
    """

    # Now I define the actual SQL queries and execute them
    # Skipping in the snippet for brevity

It’s very important that all of our custom tools have good descriptions — as docstrings — like this. This helps our agent always pick the right tool for a given task.

3. `InfrastructureAuditor` (Waste & Zombie Resource Auditing)

Model: gemini-3.6-flash.
Tools: list_zombie_resources, get_precomputed_spend_analysis, get_cai_metadata_for_resources, get_cai_history_for_resource.
Responsibilities: Scans for unattached Persistent Disks, idle static external IP addresses, inactive GCS storage buckets, and orphaned Secret Manager secrets. Generates recommendations JSON+A2UI payloads.

4. `CloudAdvisor` (Live Guidance Proxy)

Model: gemini-3.5-flash-lite.
Tools: cloud_assist_mcp_toolset.
Responsibilities: Proxies requests to Google Gemini Cloud Assist MCP for infrastructure recommendations.

This is a pretty simple agent that makes use of Google Cloud Assist.

Let’s look at the relevant code…

from finops_agent.app_utils.mcp_config import cloud_assist_mcp_toolset
# Other imports

CLOUD_ADVISOR_INSTRUCTION = """You are the CloudAdvisor subagent.
Use Gemini Cloud Assist tools (ask_cloud_assist, investigate_issue) to retrieve active rightsizing recommendations, perform operational issue diagnostics, and optimize performance/cost for active GCP resources.

CRITICAL OPERATIONAL DIAGNOSIS & RIGHTSIZING RULES:
1. OPERATIONAL ANOMALIES: If the session context or prompt indicates active operational errors (e.g. `today_operational_anomaly == True` or crash loops), use `investigate_issue` or `ask_cloud_assist` to query active GCP Monitoring alerts, failing services, and system diagnostics for the affected project/service.
2. DISCOVERED CONTEXT: BEFORE querying, inspect the prompt and session context for the top active services and projects ALREADY DISCOVERED in this session.
3. Focus all recommendation and diagnostic queries (`ask_cloud_assist`, `investigate_issue`) SPECIFICALLY on those identified active services and projects.
4. Do NOT output generic boilerplate recommendations for unconfigured services (like GKE or Compute Engine VMs if they are not driving spend). Every recommendation MUST be tailored directly to the discovered active workloads.

CRITICAL AUTH & FALLBACK RULES:
1. If `ask_cloud_assist` returns recommendations or diagnostic findings, compile them into a clear, structured report detailing estimated monthly savings or operational remediation steps.
2. If `ask_cloud_assist` returns a 403 Forbidden or permission error for certain projects:
   - Highlight any recommendations retrieved from accessible active projects.
   - For projects lacking Recommender permissions, provide high-value, actionable optimization guidance strictly tailored to the specific active services discovered in the environment.
3. Always invoke `finish_task` with your complete, formatted Markdown report in the `result` argument.
"""

cloud_advisor = Agent(
    name="cloud_advisor",
    description="Specialised subagent that calls Gemini Cloud Assist tools to retrieve active rightsizing recommendations, perform operational issue diagnostics, and optimize performance/cost for active GCP resources.",
    model=ConfiguredGemini(
        model=settings.fast_model,
        retry_options=types.HttpRetryOptions(attempts=3),
        use_interactions_api=False,
    ),
    instruction=COMMON_AGENT_HEADER + "\n\n" + CLOUD_ADVISOR_INSTRUCTION,
    tools=[
        cloud_assist_mcp_toolset,
        get_session_value,
    ],
    mode="task",
    output_schema=TaskOutput,
    disallow_transfer_to_peers=True,
    disallow_transfer_to_parent=False,
)

Now we’ll look at how we define cloud_assist_mcp_toolset. Obviously, we're using MCP and the actual configuration is defined in my app_utils/mcp_config.py:

class GcpMcpAuthProvider:
    """Provides valid OAuth2 headers for Google Cloud remote MCP connections."""

    def __init__(self, scopes: list[str] | None = None):
        self._scopes = scopes or ["https://www.googleapis.com/auth/cloud-platform"]
        self._credentials = None
        self._lock = threading.Lock()

    def __call__(self, ctx: ReadonlyContext) -> dict[str, str]:
        with self._lock:
            if self._credentials is None:
                self._credentials, _ = google.auth.default(scopes=self._scopes)

            if not self._credentials.valid:
                self._credentials.refresh(Request())

            token = self._credentials.token

        return {
            "Authorization": f"Bearer {token}",
            "x-goog-user-project": settings.google_cloud_project,
            "Content-Type": "application/json",
            "Accept": "application/json, text/event-stream",
        }

# Gemini Cloud Assist MCP Toolset Configuration
cloud_assist_mcp_toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://geminicloudassist.googleapis.com/mcp",
    ),
    header_provider=GcpMcpAuthProvider(),
)

So now, whenever we need an investigation, we can get Gemini Cloud Assist to do the heavy lifting. Nice!

5. `KnowledgeAssistant` (GCP Architecture Grounding)

Model: gemini-3.5-flash-lite.
Tools: dev_knowledge_mcp_toolset (Google Developer Knowledge MCP: answer_query, search_documents).
Responsibilities: Grounds cost optimisation and architecture advice directly in official Google Cloud developer and architecture framework documentation, returning authoritative citations.

The code for this agent is very simple; it’s basically just the prompt and the use of the Google Developer Knowledge MCP toolset. The toolset itself is defined using the same pattern that we used previously for cloud_assist_mcp_toolset.

KNOWLEDGE_ASSISTANT_INSTRUCTION = """You are the KnowledgeAssistant subagent.
Query the Developer Knowledge MCP to retrieve and ground cost optimization recommendations in official GCP architectural guidelines.

GUIDELINES:
1. Identify the specific GCP services provided in the user prompt or identified as top cost drivers (e.g. Vertex AI, Gemini API, BigQuery, Cloud Storage).
2. Query the Developer Knowledge MCP to find official Google Cloud cost optimization strategies, architectural patterns, quota management, lifecycle policies, and scaling guidelines for those specific services.
3. Always provide inline citations referencing official GCP documentation when presenting architectural advice or product recommendations.
4. When outputting references or citations, ALWAYS format them as standard single-line Markdown links: [Title](URL). Never insert line breaks or whitespace inside the URL or between `]` and `(`.
"""

knowledge_assistant = Agent(
    name="knowledge_assistant",
    description="Specialised subagent that queries the Developer Knowledge MCP to retrieve and ground cost optimization recommendations in official GCP architectural guidelines and best practices.",
    model=ConfiguredGemini(
        model=settings.fast_model,
        retry_options=types.HttpRetryOptions(attempts=3),
        use_interactions_api=False,
    ),
    instruction=COMMON_AGENT_HEADER + "\n\n" + KNOWLEDGE_ASSISTANT_INSTRUCTION,
    tools=[
        dev_knowledge_mcp_toolset,
    ],
    mode="single_turn",
    disallow_transfer_to_peers=True,
    disallow_transfer_to_parent=False,
)

6. `RootCauseAnalyst` (Spike & Drift Correlation)

Model: gemini-3.6-flash.
Tools: get_today_top_services_and_usage, investigate_today_service_logs, get_precomputed_root_cause, get_precomputed_spend_analysis, get_session_value, set_session_value.
Responsibilities: Investigates spend anomalies across two workflows:
- Intra-Day (Today’s Spend): Uses real-time Cloud Audit Logs and BigQuery data to discover active services, API invocation counts, caller identities, and operational error anomalies (bypassing GCP Billing ingestion lag).
- Historical Spikes: Correlates BigQuery resource-level cost spikes with Cloud Asset Inventory (CAI) configuration change history logs (e.g. machine type upgrades or disk size increases).

Let’s look at the prompt:

You are the RootCauseAnalyst subagent.
Investigate spend anomalies and intra-day cost drivers by executing either the INTRA-DAY or HISTORICAL workflow based on the user request.

FIRST: Determine the investigation time-frame:
- If the request targets TODAY or real-time cost/spikes, follow the INTRA-DAY WORKFLOW.
- If the request targets a PAST date spike, follow the HISTORICAL WORKFLOW.

INTRA-DAY (TODAY'S COST) INVESTIGATION WORKFLOW:
1. Call `get_today_top_services_and_usage()` FIRST to discover active services today.
2. Extract the top active service names returned (e.g., ["Gemini API", "BigQuery", "Vertex AI", "Cloud Run"]) and pass them into `investigate_today_service_logs(target_services=[...])`.
3. Synthesise intra-day SQL metrics, audit log invocation counts, and caller findings in your final report.
4. INGESTION LATENCY & DISCLOSURE RULE: Always note that standard GCP Billing Export has a 3-12+ hour ingestion delay. If billing partitions show minimal ingested spend while Audit Logs show active calls, report the active invocation counts and state official billing figures are pending.
5. OPERATIONAL ANOMALY RULE: If `has_operational_anomaly == True`, explicitly highlight errors in your summary report and recommend that the user/coordinator run a follow-up diagnosis with `CloudAdvisor`.

HISTORICAL COST SPIKE WORKFLOW (PAST DATES):
1. Identify the single primary spike date (YYYY-MM-DD).
2. Call `get_precomputed_root_cause(date_str="YYYY-MM-DD")` EXACTLY ONCE for that peak date against `{resource_table_id}`.
3. NEVER call `get_precomputed_root_cause` multiple times or loop through multiple dates.
4. Correlate persistent resources with Cloud Asset Inventory (CAI) configuration logs.

CRITICAL: CONCISE SYNTHESIS & TERMINATION
1. Keep the final markdown report under 350 words total.
2. Call `finish_task` and pass the complete final markdown report directly into the `result` parameter, then terminate execution.

There are a few key highlights worth calling out in this system prompt:

Explicit Time-Frame Branching: The prompt mandates a top-level decision step (TODAY vs HISTORICAL) before executing any tools.
Overcoming Ingestion Lag via Audit Logs: Standard GCP Billing Exports have a propagation delay, which could be several hours. For intra-day queries, the agent pairs BigQuery partition checks with real-time Cloud Audit Logs (get_today_top_services_and_usage and investigate_today_service_logs) to capture active API invocations, caller principal identities, and operational errors in real-time.
Clean Advisory Hand-Off: RootCauseAnalyst focuses purely on log and spend telemetry. It does not contain Gemini Cloud Assist tools directly. When investigate_today_service_logs detects operational errors (has_operational_anomaly == True), our agent explicitly recommends that the user or root coordinator run a follow-up diagnostic turn with CloudAdvisor (which holds the investigate_issue and ask_cloud_assist MCP tools).

Okay, that’s it for our overview of the agents. Let’s take a look at how they’re coordinated.

Multi-Agent Orchestration Patterns

When designing multi-agent architectures, several standard workflow patterns exist for how we can coordinate them. Here are just some of those patterns:

Coordinator-Dispatcher: A central root agent acts as an intelligent router, delegating tasks to dedicated subagents based on intent. The root agent makes the decisions.
Sequential Pipeline: Output from Agent A is piped sequentially into Agent B, then Agent C (like an ETL pipeline). Here we use deterministic workflow agents, so a model is not actually making any routing decisions.
Parallel Fan-Out and Gather: Multiple agents run in parallel, and their results are gathered together at the end. Again, this uses deterministic workflow agents.
Graph-Based Agent Workflows: where each agent is a node in a graph, and complex routing between agents is defined declaratively. This is a routing pattern that was introduced with ADK 2.x.

For FinSavant, we selected the Coordinator-Dispatcher pattern. We give the root agent (our coordinator) a bunch of subagents, and let the root agent decide which agent to delegate to, based on the user’s latest prompt and the information that has already been gathered in the session.

I should also mention the collaboration modes used by each agent. These determine the behaviour of a subagent that has been delegated to. There are three modes we can choose from:

Chat: Full user interaction. I.e. the user can continue to have a conversation with that subagent, and control only returns to the calling agent when a specific criterion (such as an instruction from the user) is met.
Task: Here, the subagent performs a specific task, but is allowed to seek clarification from the user in order to complete it. Once the task is complete, control returns to the calling agent.
Single-turn: Here, the subagent simply performs a task, but is not allowed to interact with the user. Control returns immediately back to the calling agent. This is useful for asynchronous workflows, such as when calling multiple subagents in parallel.

The mode is defined as a property as part of each subagent definition. So we've got:

BillingExplorer: task
InfrastructureAuditor: task
CloudAdvisor: task
KnowledgeAssistant: single_turn
RootCauseAnalyst: task

You can see that all of our subagents ultimately return control back to the coordinator. And you can also see — in our agent definitions — that I explicitly prohibit subagents handing off to a peer. They must return to the calling orchestrator agent.

Testing with ADK UI Tools

Now we’ve got our root agent, subagents and tools defined, we’ve got enough to try it out.

A great thing about using ADK is that we don’t even need to build a UI to test our agents! We can just use the out-of-the-box developer UIs, like ADK CLI and ADK Web.

ADK CLI is a command-line interface intended for easy text-only chats with our agent. For FinSavant, we can launch it like this:

uv run adk run agent/finops_agent

And then you can issue prompts to the agent, like this:

Let’s ask it what’s driving my costs over the last 30 days…

(Just type exit when you're done.)

This is okay, but we can do much better! We can use ADK Web, a rich web UI that gives us loads of insights into what our agents are doing.

uv run adk web agent/finops_agent

By the way, this is a convenient time to add a shortcut to our Makefile, so we don't have to remember these ADK commands! If you followed my setup guidance from the previous part, this might already be in your Makefile. But if not, go ahead and add this target:

# Launch local ADK Web dev playground
playground:
    @echo "======================================================="
    @echo "| 🚀 Starting your agent playground... |"
    @echo "======================================================="
    uv run adk web agent/finops_agent --port 8501 --reload_agents

The ADK Web UI launches at http://localhost:8000. And it looks like this:

There’s so much cool stuff you can see and do from here. For example:

We can see which agents and tools are currently being invoked.
We can view our request and response payloads, including the exact prompts that were issued to the agent.
We can view event metadata, such as number of input and output tokens consumed.
We can view the agent state.
We can even build and run evaluation sets. (More on this in a future blog.)

I’ll issue the same “30 day” prompt that we used before.

Immediately, we get to see a load of useful real-time information. The first thing we see are the state changes, such as which sub-agents and tools are being called:

We can even view a dynamic visual graph, which reflects whatever event (e.g. request or response) we currently have highlighted:

Of course, we’ve still got our terminal logs:

And this is super-cool… We can even see a trace view in ADK Web, that shows a breakdown of the durations of each call:

Once upon a time, it was difficult to know what calls were causing our multi-agent solution to be slow. No longer!!

Performance Optimisation Lessons Learned

Speaking of slow, let me share a couple of key moments in my FinSavant optimisation journey. I made dozens of performance optimisations, but I’ll just share a couple of the most impactful ones.

Partition Pruning & Predicate Pushdown

Standard Google Cloud Billing export tables in BigQuery are partitioned by export_time. However, if an agent generates an outer SQL query with temporal filters wrapped around an un-scoped inner subquery, BigQuery ends up scanning the entire multi-gigabyte historical dataset before filtering the results!

To fix this, our BigQuery tool wrapper (execute_cached_bigquery_sql) dynamically parses temporal constraints (export_time, usage_start_time, usage_end_time) from the agent's SQL query and pushes down the predicates directly into the inner scoping subqueries:

FROM (
  SELECT * FROM `gcp_billing_export_v1_*` 
  WHERE project.id IN (...) 
    AND export_time >= TIMESTAMP(DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY))
    AND usage_start_time >= TIMESTAMP(DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY))
)

Why is predicate pushdown so powerful?

By moving the date filters directly into the inner table scan, BigQuery performs partition pruning right at the start. It reads only the specific disk partitions containing data for the requested time window (e.g. the last 30 days), completely skipping possibly years of irrelevant historical data.

This results in queries that are much faster and much cheaper! For me, the total time taken by the subagent was trimmed from over a minute to a few seconds.

Deterministic Python Precomputation & Subagent Tool Stripping

Rather than having LLM subagents generate complex SQL queries, inspect raw data rows, and run multi-turn self-correction loops, I implemented native Python precomputation tools, like get_precomputed_spend_analysis and get_precomputed_root_cause. Why do this?

Well…

Dynamically writing SQL queries is slow, non-deterministic, and often requires loops if the initial SQL queries are incorrect.
And, getting the agent to do this work is costly! It’s a waste of tokens.

If we know exactly what we need the agent to do in a given step, and we can code in a deterministic way, THEN WE SHOULD. Don’t use LLMs to dynamically work out how to do stuff you already know how to do. That’s a poor way to use AI!

Across all our agents, this change was probably the most significant time and token saver, overall.

Test-Driven Development & Unit Testing

Of course, I created unit tests. I say “I created unit tests”, but in reality, I got Antigravity to build most of them for me. But these proved extremely useful in catching issues and preventing regressions.

At the time of writing, I have:

80 unit tests across 13 modules
5 integration tests across 3 modules

I run them with make test, using these targets in my Makefile:

# Run unit tests
test:
    uv sync --dev
    uv run pytest tests/unit

# Run unit and integration tests
test-all:
    uv sync --dev
    uv run pytest tests/unit && uv run pytest tests/integration

I also have these tests integrated into my GitHub Actions CI/CD pipeline. (I’ll cover this in a future part.)

Building the FastAPI Backend-for-Frontend (BFF)

This part of the series is mainly about the agentic parts of the solution, so I won’t go into a lot of detail about the BFF itself. But I’ll cover it briefly, so you’ve got an understanding of how our UI will interact with the agentic layer.

What is a BFF and Why Do We Need It?

A Backend-for-Frontend (BFF) is an architectural pattern where a dedicated server-side application acts as an intermediary (a kind of proxy) between the client frontend (our React UI) and backend services, such as our agents. Rather than having the browser React application talk directly to GCP APIs or remote Agent Runtime endpoints, the BFF handles all the heavy lifting behind the scenes.

In FinSavant, the BFF is doing (amongst other things) the following:

Protocol & Stream Formatting: Formats raw agent event streams and tool calls into clean Server-Sent Events (SSE) for the React frontend.
Rate Limiting & Protection: Enforces per-user rate limits (via SlowAPI) to prevent denial-of-wallet API spikes.

What is FastAPI and Why Have We Used It?

FastAPI is a modern, high-performance Python API framework. It’s basically the gold standard for building APIs in Python these days. And Google ADK provides a native FastAPI helper (get_fast_api_app), making it simple to bind ADK runners, session storage, and A2A routes.

Let’s look at how the BFF (bff/fast_api_app.py) interacts with our agent layer...

Defining the FastAPI App

app: FastAPI = get_fast_api_app(
    agents_dir=AGENT_DIR,
    web=False,
    artifact_service_uri=services.ARTIFACT_SERVICE_URI,
    allow_origins=allow_origins,
    session_service_uri=services.SESSION_SERVICE_URI,
    otel_to_cloud=otel_to_cloud,
    lifespan=lifespan,
)
app.title = "smart-gcp-finops-bff"
app.description = "BFF API for interacting with the FinOps Agent"
app.state.limiter = limiter
app.add_middleware(SlowAPIMiddleware)
app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)

Note the web=False setting. By default, ADK's get_fast_api_app helper sets web=True, which automatically mounts ADK's built-in developer playground UI at the root (/) path. Since our BFF container serves our custom React SPA in production, setting web=False is essential. Without this, ADK's default playground (i.e. the ADK Web UI) overrides the root route.

The BFF automatically detects its runtime environment at startup. In local dev mode, it runs a standard in-process ADK Runner. In production on Cloud Run, it switches to "remote mode" and routes requests directly to Gemini Enterprise Agent Platform Agent Runtime:

@contextlib.asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncIterator[None]:
    agent_runtime_id = os.environ.get("AGENT_RUNTIME_ID")
    if not agent_runtime_id:
        # Local development mode: run agent in-process via ADK Runner
        from finops_agent.agent import app as adk_app
        runner = Runner(
            app=adk_app,
            session_service=services.get_session_service(),
            artifact_service=services.get_artifact_service(),
        )
        app.state.runner = runner
    else:
        # Production mode: agent runs remotely on Agent Runtime
        app.state.runner = None

    yield

Streaming Agent Events over SSE (`/api/chat/stream`)

When a user submits a prompt, the React frontend calls /api/chat/stream. The BFF resolves the authenticated user's project permissions, sets contextual state variables (ALLOWED_PROJECTS_VAR), invokes the agent, and streams back thought logs, friendly tool names, and A2UI payloads in real time:

@app.post("/api/chat/stream")
@limiter.limit(settings.chat_rate_limit)
async def chat_stream(request: Request):
    user_email = _get_user_email(request)
    allowed_projects = get_user_accessible_projects(user_email)

    # Scope execution context to projects this user is authorised to query
    token = ALLOWED_PROJECTS_VAR.set(allowed_projects)

    async def event_generator():
        # Stream thought logs, tool execution badges, and final text/A2UI payloads
        async for event in run_agent_stream(request, user_prompt):
            yield f"data: {json.dumps(event)}\n\n"

    return StreamingResponse(event_generator(), media_type="text/event-stream")

This ensures the React frontend receives real-time progress updates. For details of what this looks like... You’ll have to wait until the next part!

Cloud Run Keep-Alive Heartbeats

Cloud Run automatically terminates HTTP connections if no data bytes are transmitted for a few seconds. To prevent connection drops during complex multi-tool agent reasoning flows, our SSE generator emits comment heartbeats every 15 seconds while waiting for agent turn updates:

# Stream heartbeats every 15 seconds to prevent Cloud Run connection timeouts
seconds_passed = 0
while not task.done():
    await asyncio.sleep(1)
    seconds_passed += 1
    if seconds_passed >= 15:
        # SSE comment heartbeat to keep connection alive
        yield ": heartbeat\n\n"
        seconds_passed = 0

BFF Rate Limiting (`slowapi`)

To prevent Denial-of-Wallet attacks and API quota exhaustion, the BFF applies slowapi rate limiting on some of our endpoints, like /api/chat/stream, keyed by the user's authenticated identity.

Testing the BFF

In the absence of a UI (coming in the next part), we just need to be able to send an HTTP request to our new shiny API. Let’s create a new target in our Makefile:

# Launch local development server with hot-reload (defaults to local in-process ADK agent mode)
# Usage: make local-backend [PORT=8000] - Specify PORT for parallel scenario testing
local-backend:
    AGENT_RUNTIME_ID="" PYTHONPATH=agent uv run uvicorn bff.fast_api_app:app --host 127.0.0.1 --port $(or $(PORT),8000) --reload

Now we can launch the API — which automatically launches the backend agent — with this command:

make local-backend

Once that’s running, start a separate terminal session and send some requests to the API with curl:

curl http://localhost:8000/api/status

Or we can issue a prompt, like this:

curl -N -X POST "http://localhost:8000/api/chat/stream" \
   -H "Content-Type: application/json" \
   -d '{"message": "What is driving my costs over the last 30 days?"}'

The response looks a bit horrible, but you get the idea!

What’s Next?

With our multi-agent backend, precomputed toolsets, and FastAPI BFF tested and (slightly) optimised, we’re ready to build the user interface!

In Part 4, we’ll dive into Designing and Building the UI with Google Stitch and A2UI, exploring how we used Google Stitch to craft our dark-mode aesthetic and how A2UI dynamically drives interactive SVG area charts, KPI tiles, and waste optimisation cards on the React canvas.

Stay tuned!

Before You Go

Please share this with anyone that you think will be interested. It might help them, and it really helps me!
Please give me loads of claps! (Just hold down the clap button.)
Please leave a comment 💬. Interaction is good!
Add a star on the repo!
Follow and subscribe, so you don’t miss my content.

Useful Links and References

Project Demo & Portfolio

Series Links

Google Cloud Services & APIs

ADK

Automated GitHub Code Reviews Using Google Gemini

Darren "Dazbo" Lester — Thu, 16 Jul 2026 11:16:35 +0000

I Built a Thing!

TL;DR — Google Gemini-based Pull Request reviews and Issue Triaging for all your GitHub repositories and CI/CD pipelines.

What’s the Big Deal?

If you or your fellow developers aren’t yet using AI to automate code reviews, then you’re missing out on an absolute game-changer in the software development lifecycle.

Legacy approach:

You commit your code.
You submit your pull request (PR).
You wait for another developer to perform a code review and approve the PR.

This is the way it’s been for years. It’s fine. But the review process — and the reviewer — becomes a bottleneck. And furthermore, it’s a human process that is subject to significant variability.

Enter automated code reviews.

Now, after you submit the PR, a code review is automatically triggered and performed by your favourite model, using whatever instructions and grounding you and your team require. The review happens pretty much immediately. And the quality of the review is often higher than that of your fellow developers.

For the many colleagues I work with who have switched to this approach, the main benefits are:

No waiting for a human review.
High quality code reviews that not only catch issues, but also provide easy-to-follow recommendations and explanations that help the developer to learn and improve.
Massive increase in overall development velocity.

I love it. They love it. You’ll love it too!

RIP Gemini CLI Actions

For a while, Google gave us this review capability out-of-the-box. We had tools that could read our pull requests, analyse our code diffs, and write constructive, line-specific feedback comments directly on GitHub.

But then, the music stopped. If you used to rely on Google’s Gemini-based PR review integrations in GitHub, then you’re probably now sobbing into your strawberry daiquiri. (I know I was.)

Specifically, two Google mechanisms that developers loved have been decommissioned:

Gemini CLI GitHub Actions (run-gemini-cli) This was a GitHub Action that you could easily integrate into your GitHub repos by running a /setup-github command from within Google Gemini CLI. Once installed, this action would spin up a container running Gemini CLI, and use it to perform automated reviews of your code in response to a pull request. Alas, this mechanism stopped serving requests on June 18, 2026.
Gemini Code Assist on GitHub This direct GitHub App integration relied on Google Gemini Code Assist. Whenever a pull request was opened, GitHub sent a webhook to Google’s backend. This has also been shut down as of July 17, 2026.

But why have they gone? It’s because Google has terminated both Gemini Code Assist and Gemini CLI in favour of the newer Google Antigravity suite. This is true even for users on a paid Google AI subscription.

What can you do if you relied on these tools? What can you migrate to?

The Answer: My Super-Fast Drop-In Replacement

I didn’t want to lose my automated PR reviews. So, I built a drop-in replacement: the Gemini PR Review & Triage Action (derailed-dash/gemini-review-action).

I’ve officially published this to the GitHub Marketplace too, so you can find it indexed there and enjoy nice IDE autocompletion when configuring your workflows!

Features Overview

Here’s a quick summary of what it does…

AI-Powered Code Reviews: Automated, constructive line-specific feedback on Pull Requests using Google Gemini models (Gemini 3.6 Flash by default).
Automated Issue Triage: Dynamically labels, prioritises, and triages incoming issues.
Drop-in Migration: Fully compatible as a direct, drop-in replacement for the deprecated run-gemini-cli action.
Structured Outputs: Error-free JSON response formatting using Pydantic schema validation.
Hybrid Codebase Context: Automatically includes codebase context based on the overall size of the codebase. If the codebase isn't huge, the entire repo is loaded into context; but if it is huge, the agent reads the overall directory tree and judiciously includes a subset of the repo. (Note that it always reads markdown files, dependency files, packaging files, etc.)
PR Comment & Discussion Thread History: Automatically retrieves inline review threads and general PR conversation comments, enabling Gemini to track issue resolution, respect developer justifications/disagreements, and avoid repeating resolved suggestions across commits.
Tokenomics & Cost Telemetry Report: Appends a collapsible cost efficiency and token usage summary to each review.
Interactive Suggestions: Formats code recommendations inside native GitHub `suggestion blocks for one-click merge applications.
Triggers: The action triggers automatically in response to PR events. It can also be triggered by posting a comment in the PR starting with /gemini-review.
Fast-Execution Composite Action: Avoids containerisation build/pull latency (no slow docker build on every execution) by running as a native composite action.
Cross-Platform Support: Runs natively on Linux, macOS, and Windows runners (both GitHub-hosted and self-hosted).
Modern SDK Execution: Leverages the modern Google GenAI SDK (google-genai).
Enterprise-Grade Security: Authentication via either Google Gemini API Keys or Google Cloud Workload Identity Federation (WIF).
Customisable Prompts: Supports repository-specific overrides for both reviews and triaging via simple TOML config files.
Reviewer Personas: Customise the personality, tone, and review style of the agent with pre-built persona overlays (straight, dazbo, palpatine, rick).
Google Developer Knowledge Integration: Automatically queries official Google developer documentation (Google Cloud, Firebase, Android, etc.) via MCP to cross-reference your changes against up-to-date best practices.
On-Demand Agent Skills: Dynamically discovers and loads project-specific formatting guidelines and coding standards from .agents/skills on-demand, keeping prompt contexts lightweight and relevant (bundled with defaults for Google Cloud, Gemini APIs and agentic development).
Gemini Context Caching: Native, automatic integration with Gemini Context Caching, delivering up to 90% cost reduction on input tokens for repositories over 32k tokens.
Multi-Turn & Cross-PR Cache Reuse: Reuses active server-side context cache handles across multi-turn tool/skill calls and successive PR pushes within the TTL window (1h default), eliminating prompt re-tokenisation and server overhead. This is a huge efficiency and cost saving between successive reviews.

Rationale and Design Decisions

Before I built my own, I started by looking at the open source community and found a couple of replacements in the ecosystem. But they didn’t quite tick all my boxes.

Here are some reasons why I built it, and some of the design decisions I made along the way…

Performance — Native Composite Actions with `uv`

The community versions I found installed their Python dependencies using pip. This is fine, but it’s very slow compared to Astral’s awesome uv. So I wanted to build a solution that’s much faster. If you ever found yourself making changes and then re-running your code review, you’ll appreciate the frustration!

Instead of packaging the action inside a slow Docker container (like run-gemini-cli did), I designed it as a native composite action leveraging uv.

Because uv handles virtual environments and package installations with blazing speed, the scripts start running almost instantly. No Docker pulls, no container builds, and no slow pip resolution phases. The reviews execute in seconds, saving you valuable runner minutes.

Binary Fragility and Codebase Context

The community integrations I tried were a little fragile when processing binary files or encrypted assets, and they completely lacked project-wide context. They could only see the raw diff. I needed a solution that was resilient and understood the broader codebase.

My action parses the diff and automatically filters out binary, compressed, or encrypted assets. For the remaining text files, it implements a smart hybrid codebase context engine:

Full Context Mode: For smaller codebases (less than 1.5MB, excluding the stuff we filtered out), the action automatically attaches the full contents of all other files in the repository. Gemini gains complete project-wide awareness.
Sparse Context Mode: For larger codebases, it switches to a sparse mode. It attaches a visual file directory structure of the repository, plus the full contents of core manifest/configuration files and markdown documentation.

This ensures Gemini understands exactly how your PR changes fit into the overall project structure, resulting in significantly higher quality feedback.

JSON Schema Enforcement

Asking a model to return JSON in a text prompt is always a gamble. Without using Gemini’s native response_schema API (which forces structure via Pydantic model validation), the model can return markdown-wrapped JSON or invalid formats, breaking the comment parser. Again, another source of fragility.

My solution addresses this using structured outputs with strict Pydantic schemas.

SDK & Model Defaults

Alternatives I found were using older deprecated SDKs like google-generativeai, and legacy AI models like gemini-2.5-pro. I wanted to use the more up-to-date google-genai SDK, and default to the latest and greatest gemini-3.6-flash right out of the box. It’s so much better at code reviews than the older models, and so much faster too!

Configurable Language

The community actions I found didn’t offer a way to configure the preferred review language and sometimes the response was being returned to me in a language I couldn’t read! So I wanted the ability to configure (amongst other things) the review language.

Upgraded Intelligence: On-Demand Skills & Official Google Developer Knowledge MCP

I think you're gonna love this one!

A code reviewer is only as good as the standards and documentation it references. Historically, enforcing custom style guides or keeping up with changing APIs meant cramming thousands of lines of documentation directly into the system instructions, wasting tokens and confusing the model.

So my reviewer includes real-time, context-aware intelligence:

Google Developer Knowledge MCP (Out-of-the-Box): If your GEMINI_API_KEY (or Google Cloud Application Default Credentials) has the Developer Knowledge API enabled, the reviewer automatically registers the Developer Knowledge MCP. When it reviews PR code related to Google Cloud services (GKE, Cloud Run, Cloud Logging), Firebase, Android, or Google APIs, the model dynamically calls search tools to cross-reference your changes against official, up-to-date Google best practices in real-time!
On-Demand Agent Skills Registry: You can now add additional knowledge, custom style guides, API rules, or release standards by adding "skills" markdown files inside .agents/skills/ (e.g. .agents/skills/my-react-rules/SKILL.md). The reviewer checks for available skills when it starts up, and only activates specific skills that are relevant for the current review. This keeps our context lightweight. Plus, this action comes pre-packaged with a default set of skills for Google Cloud, Gemini APIs, and agentic development.
Best Practices Alignment: By combining official Google Developer Knowledge MCP tools with local workspace skills, the reviewer is primed out-of-the-box to ensure your code matches real-world, industry-standard best practices.

Clean Slate Reviews (No Session Bias)

When you're pair-programming or debugging with a local AI assistant, it builds up a massive conversational history. While that context is brilliant for generating code, it also introduces a subtle problem: session bias. The local agent knows the evolutionary journey of your code, what compromises you discussed, and what you intended to do. It understands your intent so well that it can become overly forgiving, overlooking gaps or regressions in the final implementation.

This GitHub Action, by contrast, starts with a completely clean slate. It has no idea how you arrived at your solution, what you struggled with, or what you discussed with your local IDE assistant. It is a stateless, objective reviewer checking the actual diff against the codebase. This means it often catches bugs, edge cases, or security issues that your local assistant completely glossed over!

A Quick Primer: What are GitHub Actions?

Before we start throwing a YAML configuration at your repository, let’s make sure we’re on the same page. If you already know your way around CI/CD in GitHub, feel free to skip this bit.

GitHub Actions are GitHub’s native automation platform. Instead of running and maintaining external build servers — I’m looking at you, Jenkins (shudder) — it allows us to run automated pipelines directly inside your repository in response to events like a code push, a new Pull Request, or even someone leaving a comment.

Here’s the basic vocabulary:

Workflows : The overall automated process, defined in a YAML file inside your .github/workflows/ directory.
Events/Triggers : The GitHub occurrences that kick off the workflow (e.g. pull_request).
Runners : The virtual machines (hosted by GitHub or self-hosted) that execute the jobs.
Jobs : A collection of steps that run sequentially on the same runner.
Steps : Individual tasks that either run commands or use GitHub Actions.
Actions : Reusable plugins (like ours!) that do the heavy lifting, saving you from writing your own scripts.

It all hangs together like this:

Setting It Up in 3 Minutes

Now you know what a GitHub Action is. Let me walk you through how to bring my GitHub Action into your own repository.

Step 1: Authentication (Required for Both Methods)

Before you install any workflows, you need a one-time authentication setup for your repository so the action can authenticate with the Google Gemini API. You have two choices:

The Easy Route: Generate a Gemini API Key in Google AI Studio. In GitHub, navigate to Settings > Secrets and variables > Actions, click New repository secret, and add your key named GEMINI_API_KEY.
The Enterprise Way: If you are running in a corporate Google Cloud environment, you can use Workload Identity Federation (WIF) and Application Default Credentials (ADC) to authenticate securely without storing static secrets. See the repository for WIF setup instructions.

Step 2: Install the Workflows

Once authentication is configured, choose one of the two options below to add the workflow files to your repository.

Option A: The Ultra-Lazy Route (Install via Agent Skill)

If you are already using an agentic coding environment like Google Antigravity, you don't even need to copy and paste the YAML configuration files manually. You can use my skill repository to automate the setup!

Simply run the following command in your terminal to install the skill locally:

npx skills add https://github.com/derailed-dash/dazbo-agent-skills -y -g --skill install-gemini-code-review-action

Once installed, you can just tell your AI coding assistant:

"Install the Gemini code review action in this repo."

The skill will run an interactive setup checklist:

Detects and removes legacy actions (like run-gemini-cli) that might conflict.
Prompts you for your preferences (e.g. if you want both PR Review and Issue Triage, your preferred review language, and model).
Writes the workflow .yml files and custom prompt .toml templates.
Offers to commit and push the changes directly to your repository!

Option B: The Manual Route

If you prefer to set it up manually, it’s still very easy! Create a file in your repository called .github/workflows/gemini-review.yml and paste in the sample configuration.

You don’t need to change this config at all, but you can if you want to. The part you’re most likely to want to modify is the inclusions and exclusions. There are other configurations you can tweak here, and the repo provides more details.

After you add the workflow to your own repo, it will look something like this:

Step 3: [Optional] Customise the AI’s Personality

You don’t have to stick to the default prompt. But I suggest you do — there’s a lot of smarts built into the default. But I recommend you always start by copying the defaults located in the starter-examples/ directory of the project.

Let’s See It Run!

Let’s do a quick demo. For this demo, the action has already been installed our repo.

Then we create a PR:

In a couple of seconds we’ll see the workflow begin to run:

A few seconds later, the review completes and we see the recommendations:

Triggering a Review with a Comment

We’ve seen the review trigger in response to creating a PR. But we can also trigger a PR by adding a GitHub comment: /gemini-review. This is really useful for re-running a review on-demand. (Again, this is a feature that existed in the original Google tools, and I wanted to keep it.)

Under-the-hood, my workflow achieves this using the issue_comment trigger.

Notice the if conditional for issue_comment. This is incredibly important. On public repositories, anyone can leave a comment on a Pull Request. Without that author_association check, a random internet stranger could comment /gemini-review on your PR and drain your Gemini API quota — not to mention your GitHub Action runner minutes. By restricting the trigger to OWNER, MEMBER, or COLLABORATOR, we ensure only trusted team members can summon the AI.

So, when you need a quick review: just leave the comment, and watch the magic happen!

Using Out-of-the-Box Personalities

You can configure the personality of your reviewer! A number of personas area available to choose from.

Here's what a review from palpatine looks like:

And here's a review from Rick. Wubba-Lub-a-Dub-Dub!!

Wait, What About Issues Triage?

I nearly forgot! My action can also be used to triage any issues that are raised against your repo.

As your open-source projects grow, the issue tracker can quickly turn into a chaotic mess of bug reports, feature requests, spam, and questions. Keeping the backlog clean and correctly tagged is a chore that most developers dread.

To help solve this, you can run my action in triage mode. When a new issue is opened, Gemini reviews the title and description, compares it against your existing repository labels, and automatically applies the most appropriate tags.

What you get is an immediately organised issue backlog, complete with a brief reasoning comment explaining why the labels were selected. It takes the manual effort out of issue classification entirely.

If you want to set this up in your repository, visit the repository for the full setup instructions.

Wrapping-Up

Sunsets are always frustrating, especially when they disrupt a workflow you’ve grown to rely on. But they also present a fantastic opportunity. An opportunity to learn and an opportunity to do things in a slightly different way. The main benefit for me is having a reviewer that’s now much faster than my old one. It consumes fewer runner minutes, it supports custom TOML prompts, and it leverages the latest from Gemini.

PLEASE give the repository a star , try the action out on your open-source projects, and let’s keep our CI/CD pipelines smart, secure, and fast!

Let know how you get on!

If you run into any issues or want to contribute a custom workflow, drop a comment, open an issue, or add your own contribution to derailed-dash/gemini-review-action.

Before You Go

Please share this with anyone that you think will be interested. It might help them, and it really helps me!
Please give me loads of claps! (Just hold down the clap button.)
Please leave a comment 💬. Interaction is good!
Add a star on the repo!
Follow and subscribe, so you don’t miss my content.

Useful Links and References

Building an Agentic FinOps Platform — Development Environment Setup, Google Antigravity, MCPs and Skills, and ADK Bootstrapping with Agents CLI

Darren "Dazbo" Lester — Mon, 13 Jul 2026 15:31:20 +0000

TL;DR — This article is going to be jam-packed with useful information, tips, tricks and hacks for setting up an agentic development in the Google ecosystem.

This one isn’t really about the FinOps!

Welcome to Part 2

Welcome back, friends!

In the first part, I described the purpose of the FinSavant FinOps solution, the motivation for creating it, its overall architecture and tech stack, and how it works.

In this part, we’ll use FinSavant as a case study in how to set up a development environment for the purposes of building such an ADK-based agentic solution. Even if you’re not particularly interested in FinSavant itself, I hope you’ll find a bunch of useful information and tips here that will help you build your own agentic solutions more effectively and quickly.

We’ll cover:

Using Antigravity IDE
Overall project workspace structure
Setting up agent skills for your coding agent
My project’s GEMINI.md (or if you prefer, AGENTS.md)
My documentation approach
Setting up MCP servers for your coding agent, such as BigQuery MCP
Scaffolding the initial ADK agent using Google Agents CLI and its supporting skill
Getting started with a Makefile

Sound good? Let’s get cracking!

Series Orientation

Let’s see where we are in this series.

Goals, Architecture, and Tech Stack: Capabilities, project goals, target architecture, technology stack, and design decisions.
Development Environment Setup, Google Antigravity, MCPs and Skills, and ADK Bootstrapping with Agents CLI 📍 You are here.
Building the ADK Agent and API
Designing and Building the UI with Google Stitch and A2UI
Deployment with Gemini Enterprise Agent Platform, Agent Runtime, Cloud Run and IAP
Automating Deployment with CI/CD and Terraform
Agent Observability, Evaluation, and Tuning with Gemini Enterprise Agent Platform

Getting Started with Antigravity IDE

These days, my favourite coding environment for any significant project is Antigravity IDE. This is Google’s agent-first integrated development environment. You get a look-and-feel that’s familiar to VS Code users, but powered with autonomous, context-aware agents that can plan, execute, verify, and work in parallel.

You can get it here.

By the way, Antigravity IDE is just one member of the Antigravity (aka Agy) suite.

I’ve covered these before, but here’s a quick reminder of the four Agy solutions in the suite:

Antigravity 2.0, which is now the dedicated agent-first “builder” environment on your desktop. Notably, it doesn’t itself include an IDE. Instead, we now interact only with the agent manager. This surface aims to usher in the era of “idea to product” using agents, without concerning ourselves over the code. Many builders who don’t come from a coding background will love this.
Antigravity IDE, which gives us the more familiar VS Code-esque coding environment, supported by the Antigravity agent harness. Here we can do agent-assisted development, and we always see the code. Coders will feel at home here.
Antigravity SDK, which gives you the harness and tools that power Antigravity, but exposed as a Python Agent SDK. By importing from google.antigravity we can programmatically leverage Antigravity’s capabilities.
Antigravity CLI, which is the next evolution of the extremely awesome Gemini CLI. It’s still a terminal-first environment for interacting with Gemini models. But the new Antigravity CLI is built in Go, and you can tell; it feels much faster than Gemini CLI, both during startup and in general use. It leverages the same agent “harness” as Antigravity 2.0 and the IDE, and this allows for common settings and configuration across the Antigravity suite.

Project Structure

Here’s the rough outline of the project structure we’ll be creating. We won’t be building all of this structure here; nor does this represent the final state of the project. But it gives you an idea of where we’re heading. (I’ll explain the * in a minute!)

  smart-gcp-finops/  
  ├── agent/                # ADK agent package  
  │   ├── finops_agent/     # Root agent  
  │   ├── .env              # Agent specific environment vars  
  │   ├── Dockerfile        # For deploying agent to Agent Runtime  
  │   └── pyproject.toml    # Agent runtime dependencies  
* ├── bff/                # Backend-for-Frontend (API)  
* ├── deployment/         # Infrastructure & CI/CD (Terraform IaC)  
* │   ├── terraform/      # Centralised IaC for Prod & Staging  
  │   └── README.md         # Deployment documentation  
* ├── docs/               # Project documentation  
* │   ├── images/         # Diagrams and architectural visual assets  
  │   ├── DESIGN.md         # Visual identity, components, and UI design  
  │   ├── architecture-and-walkthrough.md # Solution blueprints, ADRs, and component data flows  
  │   └── testing.md        # Testing strategy and verification instructions  
* ├── frontend/           # React UI frontend  
* ├── notebooks/          # Jupyter notebooks for prototyping and evaluation  
* ├── scripts/            # Environment setup and other utility scripts  
  │   └── setup-env.sh      # Configure local environment including Google auth / ADC  
* ├── tests/              # Unit and integration test suites  
* │   ├── eval/           # Agent evaluation  
* │   ├── unit/           # Unit tests  
* │   └── integration/    # Integration tests  
* ├── .agents/            # Workspace customizations root  
  │   └── mcp_config.json   # E.g. MCP servers  
* ├── .github/            # GitHub Actions workflows and CI/CD  
* ├── .env                # Root environment vars (dev setup, unified container, GitHub, etc)  
  ├── .envrc                # Automatically launch when entering this directory  
* ├── .gitignore          # Exclude from git  
* ├── Makefile            # Centralised developer convenience commands  
* ├── GEMINI.md           # Development agent context & guidelines  
* ├── LICENSE             # Standard open-source license file  
* ├── pyproject.toml      # Root project configuration / dependencies  
* ├── README.md           # Developer documentation homepage  
  └── TODO.md               # TODO list

If you wanted to build such a structure from scratch, here’s a cool thing to try…

Create your new project folder, e.g. my-cool-project
Open that folder in Antigravity IDE.
Supply this prompt to the Agy Agent:

/grill-me Using this folder tree as a template, 
create the required folder structure in this workspace for my new Python 
project. Only create folders and files that are marked as '*'. 
For required files, provide initial starter-for-10 content. 
<< paste the tree structure here >>

Why /grill-me? This is a built-in Agy command that causes the agent to ask questions to remove ambiguity. If you were to give the agent a slightly vague prompt without this prefix, then the agent might make some guesses about what you want. But with /grill-me, the agent will still make educated guesses, but it will also ask you questions to clarify your intent.

The prompt above is a good example of where this is useful. You’ll notice that my project tree has a LICENSE.md file, which is a standard component to include in open-source projects. But my prompt doesn't specify which license to use. So when you use /grill-me, the agent will offer sensible license choices based on your project and context, and ask you to confirm.

This video demonstrates Agy scaffolding the entire project from scratch, in response to the prompt above:

Give it a go!

Skills for Your Coding Agent

I like to describe skills as units of knowledge that agents load on-demand, when they need to do a particular task. I’ve previously written articles on the subject of my favourite skills, where to find them, and how to install them. I recommend you check out this one. You might want to go ahead and install all of my favourites!

But for now, let’s add a few skills that will definitely be useful for our current project. I recommend installing them globally, so they’ll be available to all of your development projects.

npx skills add https://github.com/vercel-labs/skills -y -g --skill find-skills  
npx skills add https://github.com/derailed-dash/dazbo-agent-skills -y -g  
npx skills add https://github.com/google/skills -y -g  
npx skills add https://github.com/google-gemini/gemini-skills/ -y -g  
npx skills add https://github.com/shubhamsaboo/awesome-llm-apps/awesome-agent-skills -y -g --skill technical-writer

We’re also going to install the Google Agents CLI and its associated skills, but we’ll get to that later.

`GEMINI.md` - Context for Your Coding Agent

The GEMINI.md file (or AGENTS.md if you prefer) is how you define your project's rules and context. It's where you tell the Agy Agent:

About your project’s goals
Rules and guidelines you want it to follow
References you want it to read

When we create GEMINI.md in the root of a project then the file is scoped only to that project. (This project-specific context gets appended to any global GEMINI.md you have defined.) When you launch any Antigravity tool from this workspace - such as Agy 2.0, Agy IDE, or Agy CLI - the Agent will automatically read this context.

Let me show you what my GEMINI.md looked like, when starting out with FinSavant:

# FinSavant - the Agentic FinOps Solution  

## Project Goals  

To create an agentic FinOps solution for GCP that:  
- Uses ADK for agent orchestration.  
- Is able to examine billing and cost data in BigQuery, based on billing   
  exports.  
- Is able to understand Google Cloud infrastructure and services across   
  multiple Google projects associated with a billing account.  
- Considers projects associated with a particular Google Cloud organisation,    
  associated with a billing account.  
- Leverages Google Developer Knowledge API MCP for grounding:   
  Google APIs, Google Cloud infrastructure, Google Cloud best practices.  
- Is able to detect cost anomalies and inefficiencies, and trends.  
- Is able to understand all deployed infra and services, and historical   
  configuration changes, leveraging Google Cloud Asset Inventory  
- Is able to invoke Google Cloud Assist for immediate logs investigation,   
  RCA and recommendations.  
- Is able to combine all of the above to provide actionable insights and   
  recommendations to users.  
- Provides a UI for users, which includes:  
  - Dashboard of cost trends, billing data and anomalies  
  - Cost forecasting  
  - Cost analysis  
  - Anomaly detection  
  - Recommendations  
  - Cost optimisation suggestions  
  - A natural language chat interface  
- The UI should be based on React. Use skills you have available to leverage   
  React best practices.  
- Leverage Google Stitch to design the UI, and use the Stitch MCP server to   
  pull in the design, in order to convert to React.  
- The UI is connected to the agent via FastAPI.  
- The UI and API will be hosted in a single Cloud Run service. The service   
  will be secured using IAP, using direct Cloud Run integration - no   
  Load Balancer.  
- The Agent will be deployed to Agent Runtime in Gemini Enterprise Agent   
  Platform.  

## Tool Use: Skills, Gemini Enterprise Agent Platform, Agent Runtime and ADK  

Be sure to use all **agents** skills, **Gemini Enterprise Agent Platform**   
skills, and **ADK** skills you have available for developing ADK agents and   
best practices, and use **adk-docs-mcp** for latest ADK documentation.   

You will have additional skills available to you, but always check if the   
following can help with a particular task.  

### ADK & agents-cli Lifecycle Skills  

- `google-agents-cli-workflow`: Entrypoint for building ADK agents (scaffold,   
build, evaluate, deploy, publish, observe).  
[skipping for brevity]  

### Gemini Enterprise Agent Platform APIs  
- `gemini-api`: Gemini Enterprise Agent Platform, Google Cloud, and   
Agent Platform enterprise usage with the Google Gen AI SDK.  
[skipping for brevity]  

### Agent Platform Engine & Model Management  
- `agent-platform-deploy`: Deploying models and tuned weights to Agent   
  Platform endpoints.  
[skipping for brevity]  

## Key Internal Documentation  

- README.md - Project README; the developer's front door  
- TODO.md - High level plan for the project  
- architecture-and-walkthrough.md - The main architecture, including design   
  decisions  
- DESIGN.md - Where we will capture the UI design  
- testing.md - Where we will document test strategy, summary of tests,   
  testing instructions, any manual testing processes  
- docs/blog.md - A blog post document we will build along the way  
- /deployment/README.md - Deployment and CI/CD documentation  

## Essential Reading  

You should read and leverage these resources for guidance and best practices,   
in addition to the skills and MCP servers you have available for knowledge.  

| Resource | Description and Relevance |  
| -------- | ------------------------- |  
| https://docs.cloud.google.com/bigquery/docs/use-bigquery-mcp?utm_campaign=DEVECO_GDEMembers&utm_source=deveco | Use the BigQuery MCP server |   
| https://adk.dev/integrations/bigquery/?utm_campaign=DEVECO_GDEMembers&utm_source=deveco | BigQuery tool for ADK |  
| https://docs.cloud.google.com/gemini-enterprise-agent-platform?utm_campaign=DEVECO_GDEMembers&utm_source=deveco | Gemini Enterprise Agent Platform Overview |  
| https://adk.dev/deploy/agent-runtime?utm_campaign=DEVECO_GDEMembers&utm_source=deveco | ADK with Agent Runtime |  
[skipping for brevity]  

## Other Notes  

- "Vertex AI" no longer exists as a product; the replacement is Gemini   
  Enterprise Agent Platform.  
- "Vertex AI Agent Engine" is no more; the replacement is "Agent Runtime",   
  which is a part of the Gemini Enterprise Agent Platform.  
- But APIs and Google internal resource names may still refer to legacy names,   
  e.g. `reasoningEngine` rather than Agent Runtime. Always use the new names   
  when creating documentation, but be mindful that we may need to use old   
  names in API calls and certain resource definitions.  

## Blog  

I want to build a multi-part blog series, which I'll post on Medium and Dev.to.  

### Documenting As We Go  

As we go, document steps taken, experience and findings in docs/blog.md.   
Later, I will build a Medium blog from this content. During this "as we go"   
phase, the blog.md does not need to be a collection of notes, code snippets, and observations. It should:  

- Include all the key steps we did, in the order we did them.  
[skipping for brevity]

If you’re following along and you’ve just created your context file, give Agy a restart now, so it picks this up.

Documentation Approach

I’m a big fan of having a consistent set of high-quality, continuously maintained documentation. I even have my own agent skill — maintaining-core-documentation - to automate much of this for me. Check out my previous blog on this subject: Documentation as Context: A Skill to Automate Your Blueprints for the Agentic Era.

If you previously ran the npx skills add https://github.com/derailed-dash/dazbo-agent-skills -y -g command from above, then you already have this skill installed.

With this in place, you could issue this prompt to bootstrap a set of documentation for a brand-new project:

Use maintaining-core-documentation to bootstrap my project documentation.

Check out this video to see the skill doing its magic!

As you evolve your project, this skill will automatically maintain your documentation.

MCP Servers for Your Coding Agent

I’ve previously written about some of my favourite MCP servers. There are only a couple that we’ll need for this project:

Note that we won’t be using either of these in the FinSavant agent itself. These are purely to help us during development.

Let’s try out the BigQuery MCP server first. In your workspace’s .agents/mcp_config.json file, we configure the Remote BigQuery MCP server like this:

{  
  "mcpServers": {  
    "bigquery-mcp-server": {  
      "serverUrl": "https://bigquery.googleapis.com/mcp",  
      "authProviderType": "google_credentials",  
      "oauth": {  
        "scopes": [  
          "https://www.googleapis.com/auth/bigquery"  
        ]  
      },  
      "headers": {  
        "x-goog-user-project": "your-gcp-billing-project"  
      }  
    }  
  }  
}

A few things to note about this:

Billing project: Replace your-gcp-billing-project with the Google project where your billing data export lives.

BigQuery API: Make sure the BigQuery API (bigquery.googleapis.com) is enabled on that project.
Developer Identity Permissions: Because the MCP server uses google_credentials to authenticate, your local developer account (active in gcloud auth) must be authorised on Google Cloud. You need the roles/bigquery.dataViewer and roles/bigquery.jobUser roles on the project hosting the billing dataset.
You also need the roles/mcp.toolUser role, in order to use this managed MCP server to query the BigQuery database.

And now, when you open the workspace in Antigravity IDE, it will load this configuration automatically. Your coding agent will be able to query schemas, inspect tables, and try out SQL queries in order to assist you when you actually create the FinSavant agent code.

Let’s test it!

First, I issue this prompt to the Agy agent:

What billing tables do I have? Explain their key functions.

You can see the agent immediately finds the MCP server and asks for permission to invoke its tools. After I grant permission, I get this response:

Nice! You can see how helpful this is going to be.

Scaffolding Your ADK Agent

The easiest way to scaffold a new ADK agent is to make use of Google Agents CLI. The Agents CLI is actually a bundle, containing:

The Agents CLI itself — commands for scaffolding, evaluating, deploying, and observing AI agents on Google Cloud. The GitHub repo describes the commands available:

An associated set of agent skills that turn your development agent into an expert in using Agents CLI.

You install the bundle using this one-time command:

uvx google-agents-cli setup

If you already have it installed, then you can upgrade like this:

uv tool upgrade google-agents-cli

(It’s worth doing this occasionally — this CLI is evolving quickly!)

With this installed, we could create our top level agent folder that contains a root agent called finops_agent by running this command:

agents-cli scaffold create agent \
  --agent adk \
  --prototype \
  --agent-directory finops_agent

You’ll end up with the following inside of your workspace folder:

agent/  
├── finops_agent/                 # Your agent code  
│   ├── __init__.py               # Registers the app (exports `app`)  
│   ├── agent.py                  # Agent definition — instructions, model, tools  
│   └── app_utils/                # Utilities (telemetry, converters)  
│       ├── __init__.py  
│       ├── telemetry.py          # OpenTelemetry setup for Cloud Trace  
│       ├── typing.py             # Request/response Pydantic models  
│       └── gcs.py                # GCS utility functions  
│  
├── tests/  
│   ├── eval/                     # Evaluation test cases  
│   │   ├── datasets/  
│   │   │   └── basic-dataset.json    # Default eval cases  
│   │   └── eval_config.yaml          # Evaluation metrics configuration  
│   ├── integration/  
│   │   └── test_agent.py         # Integration test (runs agent end-to-end)  
│   └── unit/  
│       └── test_dummy.py         # Placeholder for unit tests  
│  
├── .env                          # Environment variables (project ID, location)  
├── .env.example                  # Example environment variables  
├── .gitignore                    # Git ignore file  
├── pyproject.toml                # Project config and dependencies  
├── agents-cli-manifest.yaml      # Configuration for agents-cli  
├── Dockerfile                    # Dockerfile for the agent runtime  
└── GEMINI.md                     # Guidance file for coding agents

But since we now have the skills installed, there’s an easier way to accomplish this, that doesn’t require you to check the CLI documentation…

Please bootstrap a new ADK agent project. The agent top-level project should   
be named `agent`, and it should contain a root `agent-directory` called   
`finops_agent`, NOT the default of `app`. This means `pyproject.toml` and   
other config files will live under `agent/`, and all Python source files   
(like `agent.py` and `fast_api_app.py`) will live inside   
`agent/finops_agent/`.

Sure, this prompt is quite detailed, but I’m after a very specific folder structure.

Let’s see a live demo…

As you can see from the demo, we can now use agents-cli to check if our newly scaffolded agent is working.

For example, by issuing a single test prompt on the command line:

cd agent  
agents-cli run "Hello! Who are you?"

Or, we could run up the extremely powerful and useful ADK Web interface, using this handy shortcut:

# From the agent folder
agents-cli playground

Concluding thought about Agents-CLI: if you know your way around the CLI, you can use it directly. It'll be faster and use fewer tokens. But when you're doing lots of agent related activities like boostrapping, adding CI/CD, deploying and evaluating, you'll probably find that natural language conversations are going to save you a lot of time and pain.

Bonus #1: Getting Started with a Makefile

In a “monorepo” project setup like FinSavant, you quickly end up managing a lot of moving parts: building frontend assets, compiling Python environments, building and running multiple Docker images, executing test suites, and deploying resources to various target environments.

Rather than forcing yourself (or your team) to remember a massive list of commands and flags, wrapping them in a Makefile is a big win.

But what actually is a Makefile? At its core, it is a configuration file used by the classic make build automation tool. These days it has evolved into a lightweight, standardised task runner. It allows us to define short aliases (known as "targets") for complex shell commands, documenting project workflows in a single, standard file that is easy for both humans and agents to discover.

Earlier, during the demonstration of bootstrapping the project, the agent actually created an initial Makefile for us. If you followed along, you'll now have a Makefile that looks something like this:

.PHONY: install lint format lint-fix test  

install:  
    @command -v uv >/dev/null 2>&1 || { echo "uv is not installed. Installing uv..."; curl -LsSf https://astral.sh/uv/0.11.16/install.sh | sh; source $HOME/.local/bin/env; }  
    uv sync  

lint:  
    uvx codespell@latest -s  
    uvx ruff@latest check .  

lint-fix:  
    uvx codespell@latest -w  
    uvx ruff@latest check --fix .  

test:  
    uv run pytest tests/

Now you can run any of these make targets, like this:

make install

With this in place, we can build on it in future articles as we develop the FinSavant solution.

Bonus #2: My Setup-Env Script

These days, whenever I’m working on a project that makes use of Google services, I always create a helper setup-env script to configure my environment for me.

This script:

Loads environment variables: Automatically exports all key/value pairs from .env directly into the current shell session.
Handles Google Cloud authentication: If not skipped (via the --noauth flag), it runs gcloud auth login --update-adc to authenticate the user and configure Google Application Default Credentials (ADC).
Sets the active gcloud project: Configures gcloud defaults for the target project and billing quota project settings.
Extracts project metadata: Dynamically retrieves the Google Cloud Project Number and constructs helper variables (like the Cloud Build service account email) for deployment scripts.
Synchronises Python dependencies: Runs uv sync to ensure all standard, development, and notebook dependencies are installed in the local environment.
Activates the virtual environment: Activates the local Python virtual environment (.venv) so the user is immediately ready to run code.

You can find a copy of this scripts/setup-env.sh in my GitHub repository. Because it uses standard environment variables defined in your .env, you can use it in any of your Google projects!

You run it from the project root directory like this:

source scripts/setup-env.sh

Bonus #3: Automating Setup with `direnv` and `.envrc`

If you haven’t come across this before, I think you’re going to like it!

Manually sourcing the setup-env.sh script every time I open a terminal in the project directory is a bit of a chore. To automate this, we can use direnv — an extension for your shell that automatically runs custom scripts and loads / unloads environment variables depending on your current directory.

By placing a .envrc file at the root of the project, direnv automatically executes it whenever you cd into the directory.

Here is what our .envrc looks like:

if [ ! -d ".venv" ]; then  
  uv venv  
fi  

# Check if gcloud token is still valid to avoid re-authenticating  
if gcloud auth print-access-token --quiet > /dev/null 2>&1; then  
  echo "gcloud token is valid, skipping authentication."  
  source scripts/setup-env.sh --noauth  
else  
  echo "gcloud token is not valid, re-authenticating."  
  source scripts/setup-env.sh  
fi

This configuration does a few smart things:

Bootstraps the virtual environment: Automatically initialises a virtual environment using uv venv if it doesn't already exist.
Verifies active Google session: Runs gcloud auth print-access-token silently to check if our Google Cloud session is active.
Conditionally sources configuration: If the Google Cloud session is still valid, it sources the setup-env script with the --noauth flag, avoiding repetitive and annoying browser login prompts. If the session has expired, it triggers the full setup script to re-authenticate.

There are a couple of one-off steps we have to do to get direnv up and running:

Install direnv. On Debian/Ubuntu systems, this is sudo apt install direnv.
Allow this folder for direnv. Run direnv allow in the terminal, in the project folder where we've placed our .envrc file.

Now, when we enter our project folder, the script runs automatically, like this:

Pretty neat, right?

Wrap-Up and Next Steps

Okay, we’re done with the environment setup. We’ve:

Setup Google Antigravity, along with some killer skills and MCP servers
Bootstrapped our project using the Agy agent
Played with /grill-me
Established an initial set of core project documentation, using a custom skill
Used the Agy agent to bootstrap an ADK agent, making use of agents-cli and its skills
Created a Makefile for standardising common development, testing and deployment tasks
Created a scripts/setup-env.sh script for setting up our Google Cloud environment
Used direnv and a .envrc file to automate the setup process, every time we open a terminal in this directory

In the next part, we’ll look at the actual code for our FinSavant agents and tools!

See you there!

Before You Go

Please share this with anyone that you think will be interested. It might help them, and it really helps me!
Please give me loads of claps! (Just hold down the clap button.)
Please leave a comment 💬. Interaction is good!
and subscribe, so you don’t miss my content.

Useful Links and References

Project Demo & Portfolio

Gemini Enterprise Agent Platform & ADK

Google Cloud Services & APIs

FinSavant Part 1: Building an Agentic FinOps Platform with Google ADK, A2UI and Gemini Enterprise Agent Platform — Goals, Architecture, and Tech Stack

Darren "Dazbo" Lester — Wed, 01 Jul 2026 04:25:12 +0000

Welcome

Hello folks, Dazbo here. I’m on holiday, which means I’ve got time to catch-up on some blogging of my recent experiments!

If you’ve ever had to manage a Google Cloud Platform footprint of any decent size, you’ll know the feeling. You open up the billing console, look at the monthly total, and feel your eyes water. You start digging into dashboards, trying to map raw costs to actual running infrastructure, and quickly realise you’re essentially flying blind.

To be fair, Google has made a bunch of improvements lately, with its own Google Cloud FinOps Hub. As Google describes it:

“The FinOps hub presents all of your active savings and optimization opportunities in one dashboard.”

But I wanted to build my own agentic FinOps solution, for a few reasons. Some are about the FinOps capability itself:

I want to be able to have natural language conversations with the agent. I want to be able to dig into my cost spikes, and ask follow-up questions.
I want an agentic solution that can combine information like what I spent last month, why I spent it, and why spending spikes occurred.
I want the solution to be able to immediately spot orphaned resources , such as unused VMs, unattached disks, or unused IP addresses. For example, a persistent disk costing us $100 a month might be adding value if it’s actually attached to a VM; but it’s a total waste of spend if it’s not. (Obviously, this is more of a problem for traditional IaaS infrastructure; this is not generally a concern for serverless services.)
I want the solution to understand Google Cloud architecture and best practices , so that it can advise what I should do, and why this is the most appropriate course of action.

But mainly, I wanted an excuse to experiment with some relatively new agentic services in Google Cloud:

I wanted to deploy to the new Gemini Enterprise Agent Runtime; the thing that has replaced Vertex AI Agent Engine.
I wanted to play with some of the associated Gemini Enterprise Agent Platform capabilities, such as native support for ADK agents, the Agent Registry , and built-in observabiltiy and telemetry.
I wanted to experiment with some specific tools and MCP servers.

Specifically:

Native BigQuery tools from ADK — in order to interrogate billing information in BigQuery.
Google Cloud Assist — to be able to obtain live insights from Google Cloud metrics and logging, and provide recommendations using Google built-in recommenders.
The Asset Inventory API — to determine our exact current deployment configuration, to identify orphaned resources, and to see what has changed.
The Developer Knowledge MCP — so that my agent always has the latest knowledge about Google products, services, APIs, architectures, and best practices.

And so, friends, I give you FinSavant , an agentic FinOps solution for GCP that gives you an active, infrastructure-aware virtual analyst that combines costs with real-time operational context, and can make recommendations about what you should do next.

This is what it looks like:

I’ve open sourced the project, and you can find the project and its code on GitHub. If you like it or think it's useful, please add a star to the GitHub repo.

GitHub - derailed-dash/smart-gcp-finops

Series Structure

Let’s see where we are in this series.

Goals, Architecture, and Tech Stack: Capabilities, project goals, target architecture, technology stack, and design decisions. 📍 You are here.
Dev Environment Setup with Google Antigravity, ADK, Agents CLI, MCP & Skills
Building the ADK Agent and API
Designing and Building the UI with Google Stitch and A2UI
Deployment with Gemini Enterprise Agent Platform, Agent Runtime, Cloud Run and IAP
Automating Deployment with CI/CD and Terraform
Agent Observability, Evaluation, and Tuning with Gemini Enterprise Agent Platform

FinSavant: How Does It Work?

FinSavant is a conversational agent that uses:

BigQuery Billing Exports to know exactly what our costs are, down to the resource ID. Of course, this means you need to be exporting you billing data to BigQuery in the first place. Setting up billing exports to BigQuery is a standard process.
Google Cloud Assist in order to interrogate our services, metrics and logs, and provide recommendations accordingly.
Google Cloud Asset Inventory to understand our real-time deployment configuration, but also to provide a 35-day audit history of every asset change in our GCP estate. We can use this to investigate any changes that may have driven a cost spike.
Developer Knowledge MCP to ground the agent with both broad and deep Google knowledge. This means that if you ask it any questions relating to Google Cloud, Google APIs, or general Google best practices, the agent will provide factually correct answers that are up-to-date, and with very little hallucination. For example, if a Cloud Run service seems costly, we can ask the agent for best practices on what we should do to reduce costs whilst, for example, maintaining availability.

By bringing these together under a GenAI agent built with the Google Agent Development Kit (ADK), we have created an assistant that can perform root-cause analysis on cost spikes, as well as provide recommendations on how to fix them.

Architecture Overview

When designing FinSavant, I wanted a clean separation between the frontend delivery mechanism and the agentic backend, while keeping deployment costs and security overhead to an absolute minimum.

The overall architecture looks like this:

Tech Stack & Design Decisions

Let’s dive into the core components that make up FinSavant’s tech stack and see how they complement one another.

User Interface: React/Vite

With React I can create a great looking UI, and I have the ability to render dynamic A2UI widgets. (More on this in a future part of the series.)

By the way: I’m no frontend developer. I used Stitch to help me design and prototype the frontend UI, and then I used Antigravity (Gemini) to turn this into React code.

I can compile the React UI to clean, static assets, so I don’t need Node.js. This means my frontend container image will be pretty small, and therefore fast and cheap to run.

Rich UI with Agent-to-UI (A2UI)

Rather than building a static dashboard or a free-form chatbot, FinSavant uses Agent-to-UI (A2UI) to dynamically render rich UI components like tables, charts, and summary cards directly from the LLM. This ensures the interface is always context-aware and adapts to the user’s specific query.

A2UI is Google’s declarative specification that enables agents to generate dynamic user interfaces in the form of JSON objects. So for FinSavant, the agent builds the UI component on-the-fly, and then our frontend just converts this JSON object into a React component and renders it.

This is a game-changer for building a UI. I don’t have to hard-code any UI components — the agent decides what to display in real time! I’ll show you exactly how to do this in a future part of the series.

Backend-for-Frontend (BFF)

The FastAPI BFF simply acts as a secure proxy. It streams queries to the agent and receives structured responses. But also, it allows us to decouple the backend from the UI. If I want surface this application through a different UI in the future — like Gemini Enterprise — I can.

UI & BFF Unified Container

I’ve packaged the React frontend and FastAPI BFF into a single container image. This eliminates cross-origin resource sharing (CORS) headaches, minimises the runtime footprint, and simplifies the deployment.

Cloud Run for Container Hosting

Cloud Run is Google’s serverless, zero-ops, autoscaling container hosting environment. This is perfect for hosting our UI/BFF container. There are a number of useful features I’m going to make use of:

It scales to 0, so it doesn’t cost anything when there’s no traffic.
It autoscales based on demand, but we can limit the number of instances in order to control costs.
It natively integrates with Google Identity-Aware Proxy, providing a simple way to ensure only authenticated / authorised users can get to our application. (This native integration, without need for a load balancer, is a fairly new feature.)
We can map a domain name to our Cloud Run service, without need for a separate load balancer. (This is quite a new feature.)

Authentication with Identity-Aware Proxy

I’ve secured the Cloud Run service using Google’s Identity-Aware Proxy (IAP). This is a cool service that both authenticates and authorises users before they can access our Cloud Run service. Unauthorised users will not be able to see the application.

Until recently, the only way to use IAP with Cloud Run was to put a load balancer in front of the Cloud Run service and associate IAP with the LB. This adds additional complexity and cost.

But now we can secure a Cloud Run service directly with IAP, without needing the LB. I’ve blogged about this before, when the feature first went into Preview. But now it’s Generally Available.

Agent Orchestration: Google Agent Development Kit (ADK)

ADK is an open source framework and SDK for building agents and agentic systems. These days I reach for it automatically.

This is what it gives us:

Powerful multi-agent orchestration.
Session context management.
Bi-directional streaming support.
Agnostic of AI model.
Agnostic of hosting environment, but optimised for hosting on the Google Agent Runtime.
Integrates natively with Gemini Enterprise Agent Platform / Agent Runtime.
Easy to configure telemetry and observability.
Really useful local development user interfaces.

Agent Runtime for ADK Agent Hosting

Having decided I wanted to deploy the agent independently of the frontend and FastAPI, the next question is: where should we deploy the agent itself?

In days gone by I would probably have deployed it to a separate Cloud Run service. But now we have Agent Runtime, Google’s evolution of their previous product, Agent Engine. It is built for hosting agents and has a number of benefits:

It is simple to deploy ADK agents to Agent Runtime, using the Agents CLI.
It is serverless and autoscaling.
When there’s no demand for the agent, there’s no cost.
Exposing the agent’s endpoint to consumers (like our BFF in Cloud Run) is trivial.
Agents deployed to Agent Runtime are automatically registered in the Gemini Enterprise Agent Platform’s Agent Registry.
Agents deployed to Agent Runtime can leverage the various capabilities of GEAP, like Memory Bank, Agent Gateway, Model Armor, telemetry, and agent evaluations.

Hybrid Execution Mode

To support a fast local development cycle, the BFF supports two different run modes:

Remote Execution Mode : In staging and production, the BFF acts as a stateless proxy to the remote agent, running on the Google Agent Runtime.
Local Fallback Mode : If no remote agent runtime ID is configured, FastAPI loads the agent code directly into the container and runs the ADK engine locally in a background thread, using the developer’s Application Default Credentials (ADC).

Project and Organisational Scope

I want FinSavant to give me a holistic view across all the projects that are incurring cost against my billing account. But at the same time, I only want FinSavant to provide insights for projects that I actually have authority to see.

But GCP resource hierarchies are rarely neat and tidy. Some of my projects live inside a nice, clean Google Cloud organisation, and some are standalone — essentially orphaned projects floating in the ether that are linked to the billing account but don’t inherit anything from an organisation root.

To solve this, I designed a multi-layered discovery and security boundary:

Billing-Led Discovery : Rather than scanning the Resource Manager from the top down (which misses standalone projects entirely), the backend starts by querying the Cloud Billing API to retrieve every project linked to our central billing account. This gives us a comprehensive list of all projects incurring costs.
Hierarchical Permission Resolution (With Caching): Once we have the master list of billing projects, we need to know what the user is actually allowed to see. The discovery service attempts a top-down interrogation:
Org-Level Scan (Fast): If a target organisation ID is configured, the backend queries Cloud Asset Inventory’s IAM policies. This is extremely fast because it lets us resolve all of the user’s project bindings across the entire hierarchy in a single API call.
Project-Level Fallback (Granular): If organisation-wide access isn’t available or fails (as is often the case with standalone projects outside the org boundary), the service seamlessly falls back to a project-by-project scan, calling getIamPolicy on each individual project in the billing list to compile the user's allowed set.
Performance Protection : To prevent rate limits and quota exhaustion from repeating project-by-project IAM scans, this resolved set is cached in-memory with a thread-safe, 10-minute time-to-live (TTL).
IAP-Enforced Row-Level Security : We serve the React dashboard and agent chat through an Identity-Aware Proxy (IAP). When a user requests data, the BFF extracts their email from the x-goog-authenticated-user-email header. It resolves their allowed projects list and sets it in a local context variable.
To prevent prompt injections or the agent from hallucinating data about projects the user shouldn’t see, we intercept all BigQuery billing queries and wrap them in a subquery that filters based on only the allowed projects. This means that even if the agent is querying the whole dataset, the database engine itself enforces strict row-level filtering based on the logged-in user’s identity. If the user only has access to one project, that’s all the agent can query.

Cloud Asset Inventory (CAI)

I’m using CAI for:

Zombie Detection : I built custom CAI queries to instantly scan for unattached disks and idle external IPs.
Detective Mode : When we detect a cost spike, the agent uses CAI history to audit the exact configuration changes that occurred on that resource over the last 35 days. For example, detecting that an engineer upscaled a Cloud Run instance memory limit.

BigQuery Tool Calls From Our Agents

I want to be able to query my billing data — stored in BigQuery — using natural language prompts. I’m achieving this in two different ways, depending on where I’m coming from.

In my development workspace, I’m using the Google remote managed BigQuery MCP server (https://bigquery.googleapis.com/mcp).
In our FinSavant ADK agent itself, I’m using ADK’s native BigQueryToolset directly. In doing so, we simplify authentication, reduce runtime latency when making BQ calls, reduce dependency on an external service, and align with ADK best practices.

Developer Knowledge MCP

To make FinSavant’s advice more than just generic feedback, we need to ground its recommendations in official Google Cloud engineering standards. That’s where the Developer Knowledge MCP comes in.

This MCP server provides a direct gateway to Google’s official developer documentation, product guides, API reference material, and the Cloud Architecture Framework. Instead of relying on the LLM’s static training data, the agent can query this knowledge base in real time to retrieve authoritative, up-to-date information.

In FinSavant, we use the Developer Knowledge MCP to:

Determine the Best Course of Action : When the agent discovers a cost anomaly, it doesn’t just throw alerts. It queries the MCP to formulate an appropriate, structured response grounded in official documentation.
Verify Architectural Best Practices : It checks current Google Cloud design patterns, ensuring the agent doesn’t recommend legacy or non-optimal resource structures.
Provide Actionable Remediation : If an idle persistent disk is flagged, the agent uses the MCP to outline the exact recommended steps to snapshot and clean up the asset safely, linking the user directly to the relevant documentation.
Eliminate Hallucinations : By grounding the agent in real-time documentation, we ensure any CLI commands or configuration snippets it presents are correct and match the latest GCP standards.

Let’s See It In Action!

In this short video I demonstrate a number of FinSavant features, including:

Using starter chips to kick off an initial converation, e.g. looking for cost spikes over the last 30 days
Seeing the various tools and MCP servers called in real time
Seeing recommendations based on the findings
Watching tiles and graph widgets being created in real time using A2UI
Asking follow-up questions about particular projects
Looking for other cost anomalies

Cool, right?

What’s Next?

In the next part of this series, we’ll get our hands dirty with Part 2: Building the Agentic Solution: Development with Google Antigravity, ADK, Agents CLI, MCP & Skills.

I’ll show you how to setup your development environment, how to boostrap ADK agents, and the code behind FinSavant.

Stay tuned!

Before You Go

Please share this with anyone that you think will be interested. It might help them, and it really helps me!
Please give me 50 claps! (Just hold down the clap button.)
Feel free to leave a comment 💬.
Follow and subscribe, so you don’t miss my content.

Useful Links and References

Project Code & Demo

Gemini Enterprise Agent Platform & ADK

Google Cloud Services & APIs

GCP Billing & FinOps

Articles & Resources

Portfolio

Dazbo’s Portfolio

Dialling Our Agents to 11: Agent Skills You Need to be Using!

Darren "Dazbo" Lester — Mon, 15 Jun 2026 03:25:13 +0000

What This Article Is About

Howdy friends!

Recently I wrote an article called Dialling Our Agents to 11: My Favourite MCP Servers. It talked about how MCP servers and skills are essential components in transforming a simple agent into a useful, dependable, grounded and multi-skilled agent harness. I listed my favourite MCP servers for productivity, and promised a follow-up article that focuses on agent skills.

Well, here it is!

Quick Skills Recap

If you don’t know what a skill is: think of it as a unit of knowledge and capability for an agent, loaded on-demand as required.

I recently did a talk on the topic of using MCP and skills to power-up our agents. In April I presented this at Google Next ’26 in Vegas:

My Incredible Google Cloud Next 26 Experience as a GDE

And in May I did a similar talk for Google Developer Group Prishtina, as part of the Google Build with AI roadshow.

Build with AI | Google for Developers

In that talk I explain what MCP and skills are, how they work, and how they differ. I talk about the use cases where skills are better than MCP servers and vice versa, and I talk about the scenarios where you might want to use them together.

Here’s a recording of the BwAI session for GDG Prishtina:

Favourite Skills

Time for me to talk about some of my favourite skills. I’ll explain what they are, how you use them, and how you install them.

By the way, they’re free (and open source), and off-the-shelf; including a few created by me.

1. Google Agent Skills / Agents-CLI

Let’s face it, building production-ready AI agents on Google Cloud used to feel like trying to build a functioning helicopter from a box of random Lego bricks. You had Vertex AI, sorry — I mean Gemini Enterprise Agent Platform, Cloud Run, APIs, service accounts, IAM roles, and about a thousand vector store options. Your poor coding assistant would choke on the complexity, even if grounded with good quality documentation.

The Google agents-cli is a game changer for this scenario. It’s a combined CLI and set of skills for building, evaluating and deploying agents in Google Cloud. Now your assistant gets the exact API references, schemas, and scaffolding patterns it needs to build, test, and ship agents without having to guess the plumbing.

Because it’s actually a combination of CLI and skills, we can use it in two ways:

We can just run CLI commands directly from our terminal.
We can use skills to inform our coding agent about how to use the CLI.

Setup

Installation is a piece of cake. You can bootstrap the environment using uv — which, as you know, is my absolute favourite environment manager:

uvx google-agents-cli setup

Use

With the CLI and skills installed, we can issue prompts like these to our coding agent:

“ Build a support agent that answers questions from our docs. I want to build using Agent Development Kit (ADK) and I want to deploy to Google Cloud eventually.”
“Write evals for the Rickbot agent and run them”
“ Deploy this to Cloud Run”
“ Integrate this with Gemini Enterprise”

Past-Me used to build agents, run some unit tests, try a few manual prompts to the agent and declare: “Yep, looks good to me!”

Don’t be Past-Me. This agents-cli framework makes it so easy to add agentic reviews to your development process.

How Is it Different to Developer Knowledge and gcloud MCP Servers?

If you are already using Google tools in your IDE, you might wonder how this fits in with the other tools at your disposal:

Google Developer Knowledge MCP (The Library 📚): A read-only lookup tool. It tells the agent how GCP works (services, products, APIs and syntax) but doesn’t run commands or build resources.
gcloud MCP (The Muscle 💪): Exposes low-level SDK commands. You supply natural language commands and your agent executes the gcloud commands to turn your wishes into reality. But has zero built-in understanding of agent architecture, ADK code, or prompt tuning.

But the Google agents-cli is more like an orchestrator built specifically for the Agent Development Lifecycle (ADLC). And it knows how to leverage and deploy appropriate services in the Google Cloud ecosystem. It abstracts low-level GCP setup into single commands and adds agent-specific capabilities like evaluation runs and version trajectory grading.

Fun Fact

The Google Agents-CLI has replaced the Google Agent Starter Pack.

2. Vercel Labs Find-Skills

Every great software ecosystem needs a package manager — think apt for Debian, npm for Node.js, uv for Python — and the AI agent world is no different. Enter the Skills CLI (npx skills), a package manager developed by Vercel Labs. It lets you discover, install, and update modular packages (skills) that expand your agent’s capabilities.

But wait! What’s the difference between the Skills CLI and the find-skills skill? It’s actually a really neat inception-style loop:

The Skills CLI (npx skills) is the command-line package manager tool itself (analogous to the npm binary). It is the mechanism that physically installs, checks, and updates skills on your machine.
The find-skills skill is the on-demand knowledge that you install into your agent's brain using that package manager.

Without the find-skills skill loaded, if you ask your assistant: "Hey, is there a skill to help me write Playwright E2E tests?", the agent will just guess or tell you it doesn't know. Once you install the find-skills skill, it teaches your agent when and how to run the npx skills find CLI command on your behalf — allowing the agent to self-extend based on your requirements.

Setup

npx skills add https://github.com/vercel-labs/skills -y -g - skill find-skills

Use

Once installed, you can search for capabilities directly using natural language. For instance:

“Find and list some skills to help me write and maintain high quality software project documentation”

In response to this, the skill advises my agent (Antigravity) on the command to run, and prompts me for approval:

It finds a bunch of skills (alas, not the skill I was hoping it would find — more on that later!), and asks if I want to install any of them:

Also, just like any other package manager, you can actually use npx skills and find-skills to update your set of skills. I only just found out this is possible!!

Nice!

Pro Tip: Check the Leaderboard!

Before you install a random skill, head over to skills.sh to see the Open Skills leaderboard. This leaderboard automatically tracks open skills, along with GitHub metrics and the number of npx-based installs. From here, you can see the skills that are most popular and most trusted.

3. Dazbo Agent Skills

Yes, I’m biased. But sometimes, you need a specialized toolset that addresses very specific workflows — which is exactly why I created my own suite of custom skills. But then, of course, I realised that these skills will often be useful to others, so I uploaded them to GitHub.

The dazbo-agent-skills repository is a curated collection of skills that I use often. In the box, you get:

`maintain-core-documentation`

A specialist framework that guides the creation and maintenance of high quality core documentation files, including README.md, TODO.md, DESIGN.md (for Stitch-compatible UI spec), Architecture.md, Testing.md, and Deployment.md (for setup, Infra-as-Code, GitOps and CI/CD).

It also leverages the technical-writer skill, which I’ll mention later.

`deploy-skills-in-antigravity`

A global installer and relocator that automates adding or updating agent skills via npx and safely moves them to my preferred shared global path (~/.gemini/skills/).

`convert-to-devto`

A skill that automatically converts, structures and standardises Markdown files for publication on dev.to.

Basically, it takes your input and reformats to the required dev.to markdown format, including injection of the YAML frontmatter, formatting of inline variables, handling of nested code blocks, and converting links to dev.to-compatible Liquid tags.

Because I often post blogs like this on both Medium and dev.to, it saves me a huge amount of time in performing the appropriate conversion.

`secrets-with-git-crypt`

Have you ever accidentally committed a local file that contained sensitive information, like an API key? I bet you’ve read some horror stories of what happens if you do! (Like waking up to a five-figure cloud bill because your GCP credentials got scraped off GitHub within 30 seconds).

This skill provides a workflow that leverages git-crypt — an open-source tool that enables transparent encryption and decryption of files in a Git repository using AES-256 encryption.

I use this skill to ensure that if my repo has any files with sensitive configuration — like a .env or terraform.tfvars— the skill detects it, ensures it is ignored by git (by automatically adding to my .gitignore), but also offers to create an encrypted version that will be stored in the repo. This is useful, because then the encrypted version can be pulled to any other machines I’m working on and decrypted locally. And the skill manages the decryption and synchronisation between encrypted and non-encrypted versions for me.

Sure, you could just use a Secret Manager, or use GitHub secrets. But this approach is very convenient and operates completely transparently.

`create-md-from-browsermcp-snapshot`

One thing I often want to do is create a markdown version of a web page. This is especially useful for turning a page into quick, persistent context for my agent.

Often, this is something that can be easily achieved using the Browser Agent built into Antigravity. But sometimes this isn’t possible, and I’ve explained these scenarios here. In these scenarios, I use BrowserMCP to remote control and read a specific Chrome browser tab. But the BrowserMCP tools are not natively able to create markdown. And so I created a skill which executes Python to turn the BrowserMCP JSON output into high-fidelity markdown.

Setup

You can install all these skills in one hit, or just install the ones that look most interesting to you:

# All Dazbo skills
npx skills add https://github.com/derailed-dash/dazbo-agent-skills -y -g

# Installing a specific Dazbo skill
npx skills add https://github.com/derailed-dash/dazbo-agent-skills -y -g --skill maintaining-core-documentation

If You Like These Skills…

Please add a star to my repo!

4. Google Skills

If you are building systems on Google Cloud, you don’t want your AI assistant to guess how to configure your databases or auto-scale your clusters. You want the official blueprints.

The official Google Skills repository (google/skills) is a collection of skills that provide AI agents with precise, up-to-date knowledge of Google Cloud services and architectural standards. And since they exist as multiple skills with well-defined narrow scopes, they’re only loaded when you’re working on a relevant service.

With these installed, you’ll find that agent output is much higher quality, token usage goes down considerably, and the number of loops required to achieve a goal is also reduced. It will save you time and money!

What’s in the Box?

To help make sense of the repository, the skills are categorised into three main logical groups:

Agent Platform Skills:

agent-platform-deploy : Automates the packaging and deployment of AI agents to Google Cloud platforms (like Cloud Run or GKE) with proper service bindings.
agent-platform-endpoint-management : Configures and manages Vertex AI model endpoints, routing, and access control.
agent-platform-eval-flywheel : Sets up continuous evaluation pipelines for monitoring agent response quality over time.
agent-platform-inference : Directs optimal model invocation patterns, including parameter tuning, fallback models, and token budget management.
agent-platform-migrate-from-ai-studio : Streamlines porting agent prompts and configs from Google AI Studio to enterprise Vertex AI environments.
agent-platform-model-registry : Tracks and organises different versions of foundation and tuned models within Vertex AI.
agent-platform-prompt-management : Version-controls system prompts, system instructions, and few-shot examples independently of the application code.
agent-platform-rag-engine-management : Guides the configuration of document chunking, indexing, and vector database retrieval settings for grounding.
agent-platform-skill-registry : Manages the life cycle of installed agent tools and skills, ensuring correct schema definitions.
agent-platform-tuning-management : Oversees model tuning jobs, tracking parameters, and comparing metrics across different runs.
agent-platform-tuning : Provides instructions for formatting datasets and executing supervised fine-tuning (SFT) jobs for Gemini models.

Core Services & APIs:

alloydb-basics : Scaffolds and optimises Google's enterprise-grade PostgreSQL-compatible database, including pgvector setup.
bigquery-basics : Guides dataset creation, partitioning, clustering, and writing optimised SQL queries for massive data analysis.
cloud-run-basics : Handles containerised application deployment, scaling configurations, and setting up HTTPS endpoints in seconds.
cloud-sql-basics : Scaffolds and secures managed database instances (PostgreSQL, MySQL, SQL Server) in Google Cloud.
firebase-basics : Scaffolds mobile/web backends, including Firestore database rules, Authentication, and Cloud Storage setup.
gcloud : Bridges the gap between your coding agent and low-level CLI infrastructure commands, ensuring correct flags and parameters.
gemini-agents-api : Guides integration with Vertex AI Agent Builder APIs for orchestrating pre-built agentic workflows.
gemini-api : Formulates correct payloads, system instructions, and schema definitions for the Gemini developer API.
gemini-interactions-api : Configures chat history buffers, session state persistence, and conversational turn-taking logic.
gke-basics : Scaffolds Google Kubernetes Engine clusters, container deployments, ingress controllers, and namespace isolation.
workload-manager-basics : Evaluates, configures, and runs best-practice checks on complex cloud workloads (like SAP or high-performance computing).

Well-Architected Framework (WAF), Recipes and Operations:

google-cloud-networking-observability : Guides setting up VPC Flow Logs, Connectivity Tests, and Network Intelligence Center dashboards.
google-cloud-recipe-auth : Implements best-practice authentication flows, from simple API keys to complex OAuth2 and service accounts.
google-cloud-recipe-onboarding : Automates initial GCP landing zone setup, including IAM bindings, project creation, and resource hierarchies.
google-cloud-waf-cost-optimization : Aligns setups with Google's cost-saving principles (like rightsizing, billing alerts, and lifecycle rules).
google-cloud-waf-operational-excellence : Configures monitoring dashboards, alerts, health checks, and structured logging policies.
google-cloud-waf-performance-optimization : Guides resource profiling, caching strategies, database indexing, and low-latency network setups.
google-cloud-waf-reliability : Configures multi-region failovers, automated backups, load balancers, and disaster recovery strategies.
google-cloud-waf-security : Enforces Least Privilege access, identity federation, secret rotation, and data encryption at rest and in transit.
google-cloud-waf-sustainability : Details carbon footprint tracking and architecting workloads to minimise compute-hour waste.

How do “Agent Platform Skills” Differ from “Google Agent Skills”?

With Google agent skills appearing in two sections, you may be wondering how they differ.

The Google Agent Skills are focussed on the developer workflow. They help our developer agent to know how to build, scaffold, evaluate, and deploy agents, leveraging the Agents-CLI.
The Agent Platform Skills from the Google Skills repo are focused on the underlying architectural blueprints of Gemini Enterprise Agent Platform services. They teach the agent how to configure the platform control plane, such as setting up RAG, vector stores, and model fine-tuning jobs.

In short: Google Agents Skills help you to build and run agents; Agent Platform Skills give us the deep system capabilities and blueprints.

Setup

# To install all the skills
npx skills add https://github.com/google/skills -y -g

# To install an individual skill (e.g. alloydb-basics)
npx skills add https://github.com/google/skills -y -g --skill alloydb-basics

Pro Tip

By keeping these skills installed globally, you ensure that if you ask your assistant to design a BigQuery schema or secure a Cloud Run service, it automatically references the exact WAF parameters without you having to copy-paste documents.

5. Awesome Agent Skills

If you’re looking for the Swiss Army knife of specialised agent capabilities, my buddy Shubham Saboo has built an absolute goldmine. His repository, awesome-llm-apps, is incredibly popular in the AI engineering community — sitting at a staggering 114,000+ stars on GitHub!

While the repo started as a showcase for RAG and agent patterns, it also includes a dedicated awesome_agent_skills directory. The goal of this collection is to provide developers with modular, plug-and-play skills that teach AI assistants how to handle specific tasks with professional-grade precision.

If you browse the Open Skills leaderboard on skills.sh, you’ll find that Shubham’s skills are frequently trending near the top. According to the registry, the top 5 most popular skills from his package are:

deep-research — Highly installed for conducting comprehensive, multi-source investigations.
fact-checker — A specialised claim-verification tool.
technical-writer — For generating developer-friendly API references and guides.
debugger — A systematic troubleshooting skill for bug isolation.
fullstack-developer — Blueprints for web development covering React, Next.js, and database architectures.

Let’s do a mild deep dive into the three skills I use most often in my own workflows…

Deep Research

For conducting thorough investigations and synthesising multiple perspectives with clean citations, the deep-research skill acts as your agent’s private investigator.

It instructs the agent to break down a complex, open-ended query into smaller, logical subtopics. The agent then gathers and cross-references information from multiple sources, eventually generating a structured research report. The output is complete with an executive summary, detailed breakdowns, consensus vs. debate analyses, and inline citations pointing to original sources.

To install it globally:

npx skills add https://github.com/shubhamsaboo/awesome-llm-apps/awesome-agent-skills -y -g --skill deep-research

Fact Checker

The ultimate BS detector.

If you need to verify statistics, cross-reference claims, or check for potential bias or misinformation in a document, the fact-checker skill is your go-to.

It teaches your agent to dissect text into testable assertions and evaluate them using a strict, evidence-based scale — ranging from ✅ TRUE to 🚫 FALSE. It is particularly good at spotting subtle logical fallacies, statistics pulled out of context, and missing caveats.

To install it globally:

npx skills add https://github.com/shubhamsaboo/awesome-llm-apps/awesome-agent-skills -y -g --skill fact-checker

Technical Writer

Clear documentation is a developer’s superpower, but writing it is often a chore. The technical-writer skill gives your agent the exact templates and principles needed to write high-quality technical guides.

It directs the agent to write using a clear, active voice in the present tense. Crucially, it enforces the principle of progressive disclosure — structuring documents so that the quick-start guide, code snippets, and interactive examples appear first, while the massive, dry reference tables and configurations are pushed to the end of the document.

Fun fact: my own maintain-core-documentation skill actually makes use of the technical-writer skill, if it can. (It will offer to install it, if it’s not yet installed.)

To install it globally:

npx skills add https://github.com/shubhamsaboo/awesome-llm-apps/awesome-agent-skills -y -g --skill technical-writer

6. Remotion Best Practices

If you’ve ever tried to generate programmatic videos, you probably ended up writing spaghetti scripts calling ffmpeg command strings that looked like ancient hieroglyphics.

Remotion changes the game by letting you build real, high-quality MP4 videos using React components, HTML, and CSS. The remotion-best-practices skill provides coding assistants with the complete ruleset for scaffolding, animating, and rendering Remotion videos safely.

What’s Inside the Box?

Project Scaffolding: Instructions on bootstrapping clean projects immediately
Animation Rules: Animating elements mathematically.
Asset Handling: Enforces using Remotion’s specialized media components (<Img>, <Video>, and <Audio> from @remotion/media) wrapped in the staticFile() helper to reference files in the local /public folder.
Studio & Rendering: Commands to start the local preview server (npx remotion studio) and render single frames to sanity-check layouts.

Setup

npx skills add https://github.com/remotion-dev/skills -y -g --skill remotion-best-practices

Typical Use Cases for Remotion

Remotion is an absolute game-changer in scenarios where you need to move beyond desktop editors and build scalable video pipelines:

Personalised Video Reels : Generating user-specific analytics videos (like “Year-in-Review” summaries) or custom onboarding clips dynamically at run time.
Real-time Content Teasers : Turning text articles, RSS feeds, or news updates into short video summaries and teasers for social media automatically.
Interactive Parameter Editing : Building interfaces where non-technical users can tweak text, colors, or transitions and preview renders instantly in their browser.
Headless Rendering Pipelines : Running serverless video rendering to stitch clips, apply dynamic watermarks, and spit out MP4s programmatically.

Real-World Example: Prompt-to-Video Engine

To see just how powerful the combination of AI and Remotion is, I asked my coding assistant to build a working prototype: a Prompt-to-Video Engine.

“Create a 15-second teaser for Antigravity, an agent first development environment for turning ideas into reality, built on Google Gemini technology. Let’s turn months into minutes. Dark theme. Pull in Google Antigravity visuals.”

In response to this prompt, the coding assistant leveraged the remotion-best-practices skill to implement the following system:

The Generator (generate_video.py): A Python script that uses the modern google-genai SDK and Pydantic validation to translate my prompt into a structured JSON configuration (video-data.json), selecting dark-mode colors, highlights, and scene copy. It automatically authenticates via Google Cloud Vertex AI or Developer APIs.
The Remotion Template (VideoTemplate.tsx): A parameterised React component that reads the generated JSON configuration, imports modern typography dynamically using @remotion/google-fonts, and applies custom Bézier animation curves (interpolate) to animate headings, dividers, and body copy frame-by-frame.
Dynamic Composition (Root.tsx): Configured to dynamically compute the video's total frames based on the scene durations returned by Gemini.

The agent then generated a still image from one second in, to test the application:

And then it went ahead and created the full 15 second video.

If I wanted to edit the video and re-generate, it would be as simple as asking the agent to update the application, or I could just manually edit the scene file that the agent created for me:

{
  "background_color": "#0D0E15",
  "accent_color": "#6366F1",
  "text_color": "#F3F4F6",
  "scenes": [
    {
      "title": "Ideas Grounded?",
      "subtitle": "Traditional development slows innovation. Complex, manual, frustrating.",
      "duration_secs": 3.5
    },
    {
      "title": "Antigravity: Agent-First",
      "subtitle": "Powered by Google Gemini. Intelligent agents transform concepts into reality.",
      "duration_secs": 4.5
    },
    {
      "title": "Months to Minutes",
      "subtitle": "Accelerate from vision to deployed product at unprecedented speed. Build smarter.",
      "duration_secs": 4.0
    },
    {
      "title": "Antigravity.",
      "subtitle": "Your ideas, unleashed. Experience the future of development.",
      "duration_secs": 3.0
    }
  ]
}

7. Google Genmedia Skills

In Part 1 of this miniseries, I explored several media-focussed MCP servers, such as avtool (which wraps the command-line Swiss Army knife ffmpeg), chirp3-hd (for high-fidelity speech synthesis), and lyria (for generative music).

But Why Do We Need the Skills?

You might wonder: if my agent has access to avtool and therefore ffmpeg commands via MCP, why does it need skills?

Whilst those servers provide the raw capabilities — the “hands and eyes” to manipulate media files — they do not teach the agent how to compose media like a professional.

That is where the Google Genmedia Skills come in. These skills supply the procedural knowledge, prompt blueprints, and guardrails necessary to transform a basic coding assistant into a competent, multi-talented media showrunner.

Let’s look at the difference between atomic tasks and composite creative tasks :

The Atomic Task Scenario: MCP is Sufficient

Suppose you ask the agent:

“Extract the first 10 seconds of this video and save it as a new clip.”

This is a straightforward, single-step operation. The agent simply looks at the tools exposed by the avtool MCP server, identifies the correct command, and executes a standard ffmpeg trim. No special domain expertise or workflow management is required. The raw MCP server is perfectly sufficient.

The Composite Creative Task — Skills Required

Now suppose you give a more complex prompt:

“Generate a 15-second promotional clip using a warm narrator voiceover, a low-key background music track, and place our company logo watermark in the bottom-right corner. Make sure the video loops cleanly if the audio runs slightly over.”

Without specialised skills, a naive agent will likely fail in several ways:

Audio clashing: It will layer the narrator and background music at default volumes, resulting in a loud, unintelligible mess. (No vocal boosting; no music ducking.)
Watermark coordinate guesswork: It will try to overlay the logo image at a random coordinate, likely cropping it or placing it off-screen, since it doesn’t know it must first probe the video dimensions and calculate the offset mathematically.
Audio-video desync: If the voiceover runs to 16.5 seconds, the 15-second video will abruptly cut off or loop incorrectly, ruining the pacing.
Unrefined prompts: It will send a dry, text prompt to Gemini TTS or Imagen, resulting in a flat, robotic voiceover and a generic style.

The Genmedia skills solve this by encoding the exact workflows, volume offsets, and coordinate calculations used by real video editors and audio engineers, guiding the agent to orchestrate these tool calls systematically.

What’s Inside the Box?

genmedia-producer : The master orchestrator for complex multi-step media workflows. It guides the agent through storyboarding, script sanitisation (such as removing markdown syntax before synthesis), and matching video total runtime with audio duration.
genmedia-video-editor : Expert knowledge in FFmpeg composition. It handles video stitching, two-pass high-quality GIF generation, and teaches the agent how to mathematically calculate watermark coordinates after querying media dimensions.
genmedia-audio-engineer : Specialist in high-fidelity speech synthesis, music generation, and multi-track mixing. It instructs the agent on professional volume adjustments — boosting voiceovers while lowering background music — and ensuring sample rates match to prevent pitch shifts.
genmedia-image-artist : A direct line to Gemini image generation. It guides prompt building using professional terminology (like "chiaroscuro" lighting or "bokeh" lens effects) and handles collaborative, iterative refinements using multimodal inputs (like PDFs or video reference frames).
genmedia-voice-director : Expert director for virtual voice actors. It instructs the agent to treat Gemini TTS as talent, setting detailed scenes and using bracketed inline audio tags (like [sigh], [laughs], [enthusiasm], or [long pause]) within transcripts to shape realistic, emotional delivery.
story-generator : A heavy-duty, feedback-driven media engine that orchestrates parallel subagents to build full multi-scene storybooks (complete with images, video, voice, and music).

Setup

To install the Genmedia skills suite globally:

npx skills add https://github.com/GoogleCloudPlatform/vertex-ai-creative-studio/experiments/mcp-genmedia/skills -y -g

Real Demo

Let’s take the 15 second video I created with Remotion, and then use the GenMedia skills to add an audio track:

“Using the GenMedia skills, generate a 15-second ambient, futuristic electronic synth track matching the duration of our teaser video out.mp4. Mix this music track into the video as background audio using avtool, set the music volume to a subtle level (e.g. -18dB) so it doesn't overpower, and output the final file to media-output/agy_teaser_with_music.mp4."

First, Agy asks for permission to use Lyria:

Then it prompts to allow avtool. And then, after no more than about 5 seconds of work:

Let’s add a voiceover.

“Now, using GenMedia skills, please add a professional voiceover over the top. English female voice. Render the new video as agy_teaser_with_music_and_voiceover. The voice over should just include the main punchy statements from each scene.”

And the result:

Insane! All done in less than 5 minutes.

Of course, we could have just generated the whole video with Veo, or even Google Flow. But producing the original video with Remotion gives us a deterministic result with very specific aesthetic controls.

8. Google Data Agent Kit

If you are a data engineer or data scientist, a huge portion of your day is likely spent on the “tab-hopping” loop — jumping between the BigQuery console, Python notebooks, dbt terminals, and your AI chat window. Google’s open-source Data Agent Kit (DAK) is designed to a) eliminate this context-switching fatigue and b) give your agent knowledge of best practices for all of the various data services in the Google ecosystem.

By embedding live metadata access and MCP tools directly into your IDE, DAK gives your coding agent a direct line of sight into your Google Cloud data estate. DAK integrates natively with Antigravity IDE and VS Code, via the Google Cloud Data Agent Kit extension.

What’s Inside the Box?

Unified Data Estate Hub: Consolidates databases (AlloyDB for PostgreSQL, Cloud SQL, Spanner) and storage (Google Cloud Storage) into a single, cohesive view inside the IDE.
A set of agent skills: relating to Google data services.
Conversational analytics: Run natural language queries to profile, search, and visualize BigQuery datasets, with the ability to generate LookML models or Streamlit dashboards.
Automated pipeline assembly: Instruct your agent to construct end-to-end data workflows. The agent programmatically builds the Apache Spark notebooks for ingestion, dbt projects for bronze → silver → gold transformations, and scheduled orchestration pipelines (like Apache Airflow and Dataflow).
Intelligent workload routing: Automatically routes data tasks to the optimal engine — SQL-native ELT operations land on BigQuery, while custom Python transformations and distributed ML training are directed to Spark.
Incident diagnosis & autonomous recovery: If a pipeline fails in production, the kit runs root-cause analyses, drafts fixes, tests them, and redeploys the jobs autonomously.

Setup & Installation

Unlike the other skills I’ve listed so far, this the DAK is a much more holistic integration with your IDE. You install the Data Agent Kit from the Extensions Marketplace in VS Code or Antigravity IDE. You can install the extension directly from the Extensions view:

What Do You See in the IDE?

After installing, you’ll see:

The Unified Data Estate Hub: A new Google Cloud Data Agent Kit icon appears in your left-hand activity bar. Clicking it opens a dedicated sidebar explorer that consolidates your BigQuery datasets, Cloud Storage buckets, Spanner/AlloyDB/Cloud SQL instances, and Dataproc notebooks. If you are not yet authenticated, a sign-in prompt is pinned to the bottom status bar to guide you.
A bunch of agent skills :

Auto-provisioned MCP tools: Rather than forcing you to manually run npx skills add to register skills one-by-one, the extension automatically provisions a suite of remote and local Model Context Protocol (MCP) servers (like datacloud_bigquery_remote or datacloud_spanner_remote) directly into Antigravity's agent harness. When you chat with the agent or query /mcp, these tools are instantly active — empowering the agent to inspect schemas, write dbt transformations, or run query-optimisation analyses on your behalf.

Wrapping Up

So, there you have it; a whistle-stop tour of my absolute favourite agent skills that are currently transforming the way I build, test, and run things.

And you’ll notice that these skills work in a number of ways:

Some are standalone and simply provide your agents with guidance.
Some include embedded scripts — such as bash or Python code — and execute these scripts when required.
Some go hand-in-hand with other tools, such as locally installed CLIs or MCP servers. This combo is especially powerful, because the tools provide all the capabilities our agents need, whilst the complementary skills advise our agents on how to use those tools effectively.

Whether you’re bootstrapping GCP resources with agents-cli, self-extending your assistant’s capabilities with find-skills, or orchestrating headless video pipelines via Remotion and Genmedia — loading the right skills on-demand is the secret to dialling your agents to 11.

So, what are you waiting for? Install a few of these, power-up your IDE, and let me know how you get on.

What Are Your Favourites?

Please, tell me what skills you use. Post in the comments. Let's crowd-source a great set of useful skills!

Before You Go

Please share this with anyone that you think will be interested. It might help them, and it really helps me!
Please interact!
Feel free to leave a comment 💬.
Follow and subscribe, so you don’t miss my content.

DEV Community: Darren "Dazbo" Lester

Spec-Driven Development For-the-Win: Disposable Code, Living Blueprints, and Building Like a Boss

🗺️ The Series Roadmap: Beyond Vibe Coding

Fuel for the Engine: Replacing Vibes with Verified Intent

The SDD Lifecycle as a Continuous Loop

Concrete Artifact: A Production Spec Blueprint (tasks/plan.md)

What vs How: The Two Layers of a Living Specification

Spec Anatomy: Token Physics and Behaviour-Driven Contracts

Practical Tooling for Spec-Driven Development

1. The spec-driven-development Skill

2. GitHub's spec-kit

3. Google's Conductor Extension

Google Antigravity: The Unified Developer Harness

Inside the Harness: What the Engine Coordinates

One Core Harness Across Five Developer Surfaces

Supercharged Harness Workflows (Slash Commands)

/grill-me

/plan

/goal

/boost

/learn

Slash Commands Alone vs. Formal SDD

An Enterprise Option: Combining SDD with Tactical Slash Commands

Sustainable Team Engineering: Defeating Approval Fatigue

Summary & What's Next: Scaling the Harness

Before You Go

References and Useful Links

Spec-Driven Development

Google Antigravity & Ecosystem

Dazbo's Related Articles

Automated GitHub Code Reviews Using Google Gemini Update: Enterprise-Ready, Multimodal, and Battle-Hardened

🗺️ Series Navigation

Back for the Update!

Recap: The What, The Why, and The USPs

The Problem with Traditional (and Local AI) Code Reviews

1. The "Clean Slate" Advantage

2. Blazing Speed: Native Composite Action + Astral's uv

3. Deep Context + 90% Cost Savings via Gemini Context Caching

The Complete Feature Matrix (What's in the Box Today)

Core Review & Triage Capabilities

Multimodal & Context Intelligence

Conversational Memory & Workflow Automation

Customisation, FinOps & Enterprise Security

Enterprise-Ready by Design: Security, Governance, and FinOps

1. Keyless Enterprise Auth with Workload Identity Federation (WIF)

2. FinOps Transparency: Real Dollar Cost Estimation & Gemini Enterprise Agent Platform Billing Labels

Answering the FinOps Question at Scale: Cloud Billing Labels (billing_labels)

3. Supply-Chain Security & Fork PR Hardening

Major Feature Deep-Dives Since Part 1

1. Multimodal Context Inspection, Visual PR Diffing & Screenshot Triage

A. Automatic Markdown Image & PDF Resolution

B. Side-by-Side Visual PR Diffing

C. Multimodal Issue Triage for Remote Screenshots

D. Deterministic Image Downscaling (Saving Your Token Budget!)

2. Upgraded Default Model (gemini-3.8-flash) & Thinking Budget Controls

3. Smarter Sparse Mode: Bounded Dynamic Context Selection

4. Extending Guardrails vs Replacing Prompts + Curated Skills Synchroniser

5. Workflow Polish: Auto-Resolving Threads & Filtering Competing Bots

A. Auto-Resolving Addressed Review Threads

B. Excluding Another Bot's Comments (exclude_comment_authors)

Battle-Hardened in Production: War Stories & Bug Fixes

War Story 1: The Generated Schema That Blew the Token Budget

War Story 2: GitHub's Concurrency Trap (and How Our Bot Caught It)

War Story 3: Making "Commit Suggestion" Actually Work

War Story 4: Surviving Transient GitHub Outages

Wrapping Up

Beyond CI/CD: Bringing Gemini Review into Your Agentic Loops

Install It!

Before You Go

References and Useful Links

Loop Engineering in the Harness: Autonomous, Self-Correcting Systems

🗺️ The Series Roadmap: Beyond Vibe Coding

The "Generate and Fix" Trap: Stop Being the Human Correction Loop

Core Components of an Engineered Developer Loop

The Ratchet Principle: Engineering Continuous Improvement

Why Loops Work: The Power of Feedback

Three Traps to Avoid

The Hybrid Evaluation Rubric (Deterministic + Semantic)

The Anatomy of a Production-Grade Evaluation Rubric

No Arbitrary Point Ceiling

Concrete Artifact: A Production Spec Blueprint (`tasks/plan.md`)

1. The `spec-driven-development` Skill

2. GitHub's `spec-kit`

`/grill-me`

`/plan`

`/goal`

`/boost`

`/learn`

2. Blazing Speed: Native Composite Action + Astral's `uv`

Answering the FinOps Question at Scale: Cloud Billing Labels (`billing_labels`)

2. Upgraded Default Model (`gemini-3.8-flash`) & Thinking Budget Controls

B. Excluding Another Bot's Comments (`exclude_comment_authors`)

Off-the-Shelf Loop Mastery: The Loop Library and the `loopy` Skill

The `loopy` Agent Skill: Your In-IDE "Loop Doctor"