A brief history of Squeaky Clean

Introduction

Welcome to the Squeaky Clean blog, where I write about all things Squeaky and Clean. If you care about clean architecture, about where AI-assisted development is heading, or about the unglamorous work that has to happen before generated code can be trusted, I think you’ll find something here worth your time. If you’re not familiar with Clean Code or SOLID principles, I’ve shared recommended reading below. Now, on to the history of Squeaky Clean.

Chapter 1: Origins in laziness

Squeaky Clean started when I got tired of repeating the same Clean Code/SOLID constraints to every codegen agent I interacted with. My prompts almost always contained some variation of:

“Using Clean Architecture/SOLID principles, decompose the architecture into small files. Maximum of one class per file, 3-5 methods per class, and 1-3 arguments per method (leaning toward 1 most of the time). Fan out sub-agents inline with the architecture to maximize agent parallelization leveraging right-sized models.”

This almost always had the effect of dramatically mitigating hallucination, increasing end to end wall-clock velocity, and simplifying future changes. Basically, all of the benefits teams of human programmers using Clean Architecture/SOLID have enjoyed for decades.

Chapter 2: Physical boundaries for scaling

I understood well enough that if each file served a single small purpose, and the file structure mirrored the architecture, agents implementing a change would have an easier time targeting which file needs to be updated and only change the code that required it. That there would be a “physical barrier” at the file system level that would reduce the likelihood that an agent would open and potentially pollute an unrelated file.

Eventually, I asked myself an important question. Can these benefits scale? As a programmer, I knew over-engineering was a thing. You can implement so many abstractions and achieve such extreme granularity that your application becomes too complicated to maintain. But, what if it’s only too complicated for a human to maintain? What if, when it comes to agentic codegen, extremely granular modularity just maximizes parallelization and wall-clock delivery velocity while minimizing per-agent token footprint and mitigating hallucination? What kind of agent spec would operate well here?

Chapter 3: Applying Clean to Agent Specs

The agent spec would need to elicit knowledge of Clean Architecture/Code, SOLID princples, Gang of Four patterns, and domain-driven design. It would need to know when to apply these principles, how to implement any of the individual 27 GoF patterns, how to define domain boundaries, how to use dependency injection, etc. It would also need to apply them to multiple programming languages. This was turning into one gnarly monolithic agent spec… and what do we do with monoliths?

*** WE LEAVE THEM ALONE LEST WE FACE THE WRATH OF ANCIENT SEMANTIC ERROR ***

Wait, no. We are strong, we are brave, we drink (coffee) and we know things. We… decompose… yes, we decompose the monolith. But, how to decompose?

Well, what if I applied Clean Architecture/SOLID principles to the agent specs themselves? What would that look like? I could make them composable, hyper-granular, pattern-specific, and language-specific. An agent specializing solely in Java strategy patterns, another in TypeScript abstract factories, another in Python adapters, and so on. The clean agentic modularity would effectively mirror that of the target application. These agents would also have small, singular responsibilities. Consequently, they would also have a pretty minimal input and output token footprint, and could be optimized to perform their sole function more reliably.

Chapter 4: Squib is a deterministically parsed architectural DSL for clean agent coordination

My first thought was simply to generate a library of these granular agent specs. To do so, I wrote a script that would compose concrete agent specs from a set of abstract modules. That part was easy enough. But, when I went to put the agents into use, I realized I was missing coordination.

Quick aside: “Software Architecture: The Hard Parts (aka. Hard Parts)” is one of my favorite books on software architecture. It introduced the three C’s of distributed transactions (which agentic workflows are also subject to). One of those C’s stands for “coordination,” which describes how independent components of a system exchange information and sequence tasks. Orchestration and choreography are two contrasting implementation strategies of coordination.

After a fair amount of experimentation, I settled on orchestation as my coordination strategy. However, I hit a road block trying to optimize my sub-agents. The architectural orchestrator was still a high-parameter model, and was stepping in to solve mistakes made by the low-tier agents, confounding my data. Even worse, it would often violate clean architecture principles and ignore my extreme constraints.

This led me to develop a harness. Not just any harness, a dynamic one that a high-parameter model could build up front non-deterministically, but would then execute deterministically at runtime. It would need a concise, self-consistent, and composable grammar that would define the target applications modularity, granularity, and module dependencies.

That last criteria, in concert with dependency injection, unlocked coordinated one-shot parallelization and eventually led to cross-service contracts. However, the most important thing about Squib is that it is parsed deterministically. Squib parsing is really fast and pepper sprays the code base with deterministically coordinated hyper-granular pattern-specific agents routed directly where they are needed.

In conclusion

Squeaky Clean is the product of all of these different components (and a few more) working in concert. It is a work in progress and should be treated like an active research project more than a production ready agent harness. It is also entirely open source and we’re looking for contributors.