New post

Author: alvagante

_posts/2026-05-22-reading-the-swamp.md

@@ -0,0 +1,133 @@
+---
+layout: blog
+title: Reading the Swamp
+description: "Day two with Swamp: I climbed out of the mud and actually read the docs on swamp.club — and the framework for giving AI agents typed, versioned, deterministic memory turned out to be rather brilliant."
+---
+
+Two days ago I put my hands in the [Swamp](https://swamp.club){:target="_blank"} and they got, predictably, very dirty.
+
+Then I did something radical, revolutionary, somehow epic.
+
+I read the ***ing manual.
+
+No.
+
+It's a lie, I didn't.
+
+I forced an innocent AI to read it and summarize and explain the whole thing with the patience only AIs can have nowadays.
+
+This post, written in 4 hands, well, two hands and a bunch of tokens, (you will never know, nor care, who wrote what), is the final, public, of such a journey into the swamp.
+
+## The map I should have read first
+
+Day one was hands-in-the-mud. I installed the tool, pointed an agent at it, and spent several hours and an indecent amount of tokens fighting a bug which could be avoided just by using a better name. Btw, the bug has already been corrected and the fix released (thank you Paul), what a time to be alive!
+
+Day two I climbed back onto dry land, wiped my glasses (wait, I don't have glasses :-> ), and actually looked at the map.
+
+The map, it turns out, is good. Suspiciously good. There is a whole [manual](https://swamp.club){:target="_blank"} on swamp.club, neatly organized into tutorials, how-to guides, reference and explanation, written in a dry, essential, effective and ultimately boring style (had to say that also here, Adam :).
+
+The homepage line that meant absolutely nothing to me on day one — *"deterministic automation for AI agents"* — finally clicked. So let me try to explain it, naively, the way you explain a thing the morning after you finally got it.
+
+## What I finally understood
+
+Here is the problem Swamp is staring at.
+
+An AI agent is a brilliant amnesiac improviser.
+
+Every session it re-derives the world from scratch, does something genuinely clever, and then the clever thing dissolves into the chat history.
+
+Capabilities lost in chat, like tears in rain.
+
+One-off scripts that rot.
+
+Ephemeral logs nobody can query.
+
+Credentials scattered wherever the agent felt like leaving them.
+
+I know this dance well. I *am* the continuity in that dance — me, my head, and a growing pile of `CLAUDE.md` files.
+
+Swamp's bet is to give the agent a **substrate** instead.
+
+A place where the work it does becomes typed, versioned, queryable, composable — and therefore survives. The agent stops winging it and starts *building* things.
+
+It is, more or less, the difference between asking a consultant to solve your problem and asking them to leave behind a reusable module.
+
+For a man who spent twenty years preaching reusability in the Puppet world, that sentence clicked on day one, but I didn't full realized that immediately.
+
+## Six creatures living in the swamp
+
+The framework decomposes automation into a handful of primitives.
+
+They compose.
+
+Of course they compose — that is the whole point — but it still made me happy to see it.
+
+**Models.** Typed interfaces to anything. *"Zod schemas in, validated data out."* A model is a typed interaction with an external system: it has a type — something like `command/shell` or `@swamp/aws/ec2/vpc` — methods such as `create`, `sync`, `delete`, and typed input and output schemas.
+
+The detail that made me sit up: reusable *logic* lives in TypeScript, while *configuration* lives in YAML. So the agent doesn't write code to configure things — it reasons over data. 
+
+Anyone who has agonised over "should the AI write code here, or data?" feels that one in the spine.
+
+It is the Puppet resource abstraction layer, reborn for agents.
+
+**Workflows.** Multi-step DAGs of jobs, with parallel steps, and — this is the good bit — they nest. Steps chain data from earlier steps with CEL expressions, so the output of one job feeds the input of the next, typed all the way. It is a pipeline, except every edge is typed and every node leaves an immutable, versioned artifact behind. My day-one naming bug lived exactly here, in a model the loader refused to discover. Now I understand why the loader has opinions.
+
+**Vaults.** Encrypted secret storage, referenced by expression, resolved at runtime rather than at planning time. Swappable providers: local encryption for me on my own, AWS Secrets Manager or 1Password for a team. Boring. I mean that as a compliment. Secret management that is boring is secret management done right.
+
+**Extensions.** The thing I face-planted into on day one. Extensions package reusable components — models, vault providers, execution drivers, datastores, reports — and you publish them to a registry where they become *"a full citizen immediately"*. On day one this scared me, and it still does a little. On day two I also see it for what it is: a package manager for agent capabilities.
+
+And no, Matteo, it's not just yet another collection of skills, hope this post will help in clarifying , what I not able to explain correctly.
+
+**Reports.** Structured analysis after every run, in Markdown *and* JSON. The agent doesn't just do the thing — it tells you what it did, in a format a human and another machine can both read. An audit trail as a first-class citizen, not an afterthought.
+
+**Skills.** Markdown documents that teach the agent how to use Swamp, loaded on demand when a trigger fires. So the agent learns Swamp *from* Swamp. The framework documents itself to its own operator. Mildly meta. Slightly unsettling. Mostly brilliant.
+
+## Not only for infrastructures
+
+On day one I kept asking the same nervous question: *what repo?* Infrastructure repo? Software repo? Any repo?
+
+The honest answer the docs gave me is: **any repeatable, multi-step thing.**
+
+Infrastructure is the obvious case — inventory, provisioning, an AMI lookup feeding an EC2 model. Expected. Adam Jacob, System Initiative — of course it does infrastructure.
+
+But the moment you stop reading "automation for AI agents" as "infrastructure" and start reading it as *"anything an agent currently does ad hoc in a chat window"*, the thing gets a great deal bigger.
+
+Webframp, wrote a [enlightening post](https://webframp.com/posts/swamp-beyond-infrastructure/){:target="_blank"} about this, give it a look.
+
+Use cases are whatever you do more than once with an agent (or you should/may do with it).
+
+Think about automated transcript generation of a podcast episode, extraction of summaries, tags, generation of posts, web pages and all the corollary stuff.
+
+Or security operations — key rotation. Rotate an API key, update the vault, notify the team. Three steps, secrets involved, must be repeatable, must be auditable. Swamp's home turf.
+
+Or data remediation — a messy media library, a directory of inconsistently named files, a spreadsheet that needs reconciling. Boring, repetitive, the kind of job you hand to an agent once and can then never reproduce.
+
+Or the dull business automations — invoicing, monthly reports, the recurring thing you always forget until it is late.
+
+The pattern underneath all of them is the same. The moment you frame a task as *"a workflow of typed models"* instead of *"a thing I ask the agent to improvise again"*, it stops being a one-off and becomes an **asset**. Reusability, abstraction, repeatability, traceability — my day-one sacred principles — except now they apply to what the AI does, not only to what I write by hand.
+
+## Teaching my agents to swim
+
+This is the part I am still slightly amazed by.
+
+Right now my working relationship with an agent is: brilliant intern, infinite enthusiasm, almost zero long-term memory (memory.md? really?). Every morning it forgets it ever met me. It re-derives, re-discovers, re-improvises, and occasionally re-breaks. It is, as I said two days ago, smart for smart users — which is a polite way of saying *I* carry the continuity, in my head and in config files.
+
+Swamp moves that continuity out of my head and into a structured substrate. The agent's work becomes:
+
+- **typed**, so it can no longer lie to itself quite so cheerfully — and on day one the AIs were *always* reassuring me everything was fine while nothing worked;
+- **versioned**, so I can see what actually changed;
+- **auditable**, through reports;
+- **repeatable**, so the second run is deterministic rather than a fresh improvisation;
+- **shareable**, through extensions.
+
+The agent stops being an intern who forgets everything and starts being a colleague who builds and reuses a real toolkit. That is a genuinely different way of working — and I did not expect a download-and-run-a-script tool to be the thing that handed it to me.
+
+## Conclusions
+
+I am, clearly, hooked. The hands are still a bit muddy.
+
+Still wondering about all the possible use cases, for the world and for myself, but Alvabot and Webframp (hope he is human, at least) are helping.
+
+We'll keep wading.
+
+Alvabot and Alessandro Franceschi