DEV Community: Willem van Heemstra

Santa Augmentcode Intent Ep.4

Willem van Heemstra — Mon, 25 May 2026 14:31:40 +0000

Every Elf Gets a Workbench — Isolated Workspaces 🔨

Accompanying source code repository: Santa Augmentcode Intent

In the early Workshop days, all the Elves shared one big table. It seemed efficient. It was a disaster. Jingle would sand a wheel just as Jangle reached for it. Twinkle’s paint would end up on Tinkle’s train set. The great Christmas Collision of 1889 — I do not wish to speak of it. The solution was obvious in retrospect: give every Elf their own workbench. Isolated, private, but connected to the same Master Gift List.Augment Intent does the same thing. It just calls them workspaces.

The Problem With Sharing a Codebase

When multiple agents — or indeed multiple humans — work on the same set of files at the same time, collisions are inevitable. Agent A modifies auth-middleware.ts at line 47. Agent B modifies the same file at line 52. Neither agent knows the other is there. The merge conflict that results is not a bug in either agent’s reasoning. It is a coordination failure — the absence of isolation.

Git was designed for humans working mostly in series. A branch is opened, worked on for days or weeks, then merged. The assumption is that the pace of change is human-paced.

AI agents are not human-paced. They can modify dozens of files in minutes. Under parallel multi-agent execution, the conflict rate rises faster than any team can manage manually.

Intent solves this with isolated workspaces backed by Git worktrees.

What Is a Git Worktree?

A worktree is a lesser-known Git feature that allows you to check out multiple branches of the same repository simultaneously, each in its own directory. Unlike opening two terminal windows and hoping for the best, worktrees are a first-class Git concept: they share the repository’s object store, so no data is duplicated, but each worktree has its own working tree and index.

# Classic git workflow (one checkout)
git checkout feat/jwt-auth
# ... work, commit, push

# Git worktree (multiple simultaneous checkouts)
git worktree add ../api-gateway-worktree feat/jwt-auth
git worktree add ../auth-service-worktree feat/auth-service
# Both directories exist simultaneously, sharing one .git object store

Intent automates all of this. When the Coordinator spawns a Specialist, Intent creates a dedicated worktree for that agent automatically. The Elf gets its own workbench. Other Elves cannot see its in-progress files. The files are isolated until the Elf is done and the Coordinator integrates the work.

The Elf Workbench in Practice

Imagine the Coordinator has spawned three Specialist Agents for the JWT authentication task from Episode 3:

Workshop Floor
├── Auth Token Elf          → worktree: feat/auth-token-service
├── Gateway Middleware Elf  → worktree: feat/gateway-middleware
└── Test Suite Elf          → worktree: feat/integration-tests (waiting)

Each worktree contains a copy of the relevant files at the point the Elf starts. Changes made by Auth Token Elf in auth-service/src/token-service.ts are invisible to Gateway Middleware Elf until they are explicitly integrated. There are no accidental clobberings. No race conditions on file writes.

The Coordinator tracks the state of each worktree. When both implementation Elves complete, it orchestrates the merge — resolving any conflicts at the spec level (because the interface contracts were declared there) rather than discovering them at the file level.

Resumable Sessions: The Workshop Is Open When You Return

There is another form of isolation that Father Christmas values enormously: temporal isolation. The ability to close the Workshop at night and find it exactly as you left it in the morning.

In most AI tools, closing the window ends the session. Context is lost. Agents forget. You start over.

Intent’s workspaces are resumable. When you close the application and reopen it the next morning, every agent is exactly where it was. The spec is unchanged. The worktrees are intact. The in-progress commits are safe. The Elves are waiting at their workbenches, ready to continue.

This is possible because Intent uses auto-commit — as agents complete units of work, their changes are committed to their branch automatically. The persistent state is the git history itself, which survives any restart.

Intent workspace state on close:
├── spec: JWT auth — 6/9 tasks complete
├── Auth Token Elf: feat/auth-token-service — all commits saved
├── Gateway Middleware Elf: feat/gateway-middleware — all commits saved
└── Test Suite Elf: feat/integration-tests — waiting to start

Intent workspace state on reopen (next morning):
└── [identical to above — nothing lost]

For Father Christmas, this means I can step away from the Workshop on December 23rd for a brief rest, return on the 24th, and find every Elf at their bench with their gifts half-wrapped exactly as I left them. The Workshop never forgets.

The Unified Window: Code, Browser, Terminal, Git

Isolation does not mean fragmentation. Intent keeps everything visible in one window:

The code editor shows the active agent’s files.
The built-in Chrome browser previews localhost changes in real time.
The terminal runs builds, tests, and scripts.
Git integration handles staging, committing, and branch management.

You do not need to switch between VS Code, iTerm, Chrome, and SourceTree. The Workshop floor is one room with everything on it.

This matters for agent work because agents need to see results immediately. A Specialist that modifies a React component can open the browser preview in the same window, verify the rendering, and either commit or adjust — without handing off to a human to check.

SIPOC: Isolated Workspace Management

	S — Suppliers	I — Inputs	P — Process	O — Outputs	C — Customers
Who/What	Coordinator, Git repository, file system	Task assignment, branch name, starting file state	Coordinator spawns agent → Intent creates worktree → Agent works in isolation → Auto-commit saves progress → Coordinator integrates on completion	Isolated branch per agent, no conflicts, resumable state	Coordinator Agent, Developer, CI/CD pipeline
Workshop	Father Christmas, the main toy vault	Elf assignment, workbench materials	Santa assigns bench → Elf gets private materials → works without interruption → gifts stored safely → Santa integrates at end	No collisions, no broken gifts, always resumable	Quality Control, Head Elf Pepper, the Sleigh

Practical Tip: When to Merge

Father Christmas has one firm rule about workbenches: an Elf’s work stays on their bench until it is finished and verified. Premature merges cause half-built toys to appear in the main inventory, confusing other Elves.

In Intent terms: the Coordinator should not merge a Specialist’s branch until:

The Specialist has reported completion.
The Verifier Agent has confirmed compliance with the spec.
Any interface contracts with other Elves have been respected.

The spec is the checklist. When all boxes are ticked, the merge is safe.

What Comes Next

In Episode 5, Father Christmas will explain Spec-Driven Development — the philosophical shift that puts the living spec at the centre of the workflow and uses it to ensure everything finishes in time for Christmas. This is the why behind everything we have built so far.

A tidy workbench is the sign of an organised mind. And an organised Workshop is the sign of gifts arriving on time.Ho ho ho! 🎅

Part of the Santa Augmentcode Intent series. Published on dev.to under the the-software-s-journey organisation.

Santa Augmentcode Intent Ep.8

Willem van Heemstra — Mon, 25 May 2026 14:31:04 +0000

The Gifts Are Under the Tree — From Spec to Merged PR 🎄

Accompanying source code repository: Santa Augmentcode Intent

Every year, on the morning of December 25th, I allow myself one quiet moment before the sleigh is unpacked and the Thank-You Letters start arriving. I sit in the empty Workshop, still warm from the night’s work, and look at the bare shelves where the gifts used to be. They are gone because they were delivered. Every one of them. On time, as specified, to the right address. That moment — that quiet confirmation that everything worked — is what we have been building towards in this entire series. Today, we deliver.

The Complete Picture

Over the past seven episodes, we have assembled all the pieces of the Intent workshop:

Episode 1: The Workshop and what Intent is.
Episode 2: The Living Spec — the source of truth.
Episode 3: Santa the Coordinator and the Specialist Elves.
Episode 4: Isolated workspaces and resumable sessions.
Episode 5: Spec-Driven Development and finishing on time.
Episode 6: The Context Engine — the Workshop Library.
Episode 7: Multi-agent orchestration in waves.

Now we put them all together and walk through a complete Intent session, from the moment Head Elf Pepper opens the application to the moment the pull request is merged.

The Scenario

Goal: Add a real-time gift delivery progress dashboard to the North Pole’s internal web application. The dashboard should show live sleigh position, remaining delivery count, and an estimated completion time. It must work on tablets and update every 30 seconds.

Constraints:

Use the existing Reindeer GPS API (v2)
No changes to the Delivery Manifest microservice
Safari / iPad compatible
Must pass existing end-to-end test suite

Step 1: Open Intent and Set the Goal

Pepper opens Intent on her MacBook. She types into the Coordinator:

We need a real-time gift delivery dashboard. Show sleigh position
on a map, remaining delivery count, and estimated completion time.
Updates every 30 seconds. Must work on iPad Safari.
Use Reindeer GPS API v2. No changes to Delivery Manifest Service.

The Coordinator reads this prompt alongside the Context Engine’s analysis of the codebase. It knows the existing frontend stack (React, TypeScript), the API patterns used elsewhere in the project, and the existing test suite structure.

Step 2: The Coordinator Drafts the Living Spec

Within seconds, the Coordinator produces:

## Gift Delivery Dashboard — Living Spec

### Goal
Real-time dashboard showing sleigh position, delivery count,
and ETA. Updates every 30 seconds. iPad Safari compatible.

### Success Criteria
- [ ] Map renders in < 1s on iPad Safari
- [ ] Position updates within 30s of GPS data change
- [ ] Delivery count matches Manifest API response
- [ ] ETA calculated from current position + remaining stops
- [ ] All existing e2e tests pass
- [ ] Lighthouse accessibility score ≥ 90

### Constraints
- Reindeer GPS API v2 (existing auth token pattern)
- Delivery Manifest Service: read-only, no new endpoints
- Safari / iPad: no Chrome-only APIs

### Architecture
- New React component: `<DeliveryDashboard />`
- GPS polling service (30s interval, exponential backoff on fail)
- Map: Leaflet.js (already in dependencies — see package.json)
- Offline fallback: show last known position with staleness indicator

### Tasks
- [ ] GPS Polling Service — GPS Elf
- [ ] Map Component — Map Elf
- [ ] Delivery Count & ETA Widget — Data Elf
- [ ] Safari/iPad CSS fixes — Responsive Elf
- [ ] Integration tests — Test Elf (starts after GPS + Map done)
- [ ] Accessibility audit — A11y Elf (background)

### Decisions
(none yet)

Pepper reads the spec. She adds one clarification: “ETA should display in local Workshop time, not UTC.” The Coordinator updates the spec and records the decision.

Review time: 4 minutes. No code written yet. One important decision already captured.

Step 3: Intent Creates Isolated Workspaces

The Coordinator identifies the dependency graph:

GPS Elf and Map Elf can start in parallel immediately.
Data Elf can start immediately (it only reads from the Manifest API).
Responsive Elf can start once Map Elf has a working component.
Test Elf starts after GPS Elf and Map Elf complete.
A11y Elf runs as a background agent throughout.

Intent creates five Git worktrees:

feat/dashboard-gps-service        ← GPS Elf
feat/dashboard-map-component      ← Map Elf
feat/dashboard-data-widgets       ← Data Elf
feat/dashboard-responsive         ← Responsive Elf (waiting)
feat/dashboard-tests              ← Test Elf (waiting)

Wave 1 agents — GPS Elf, Map Elf, Data Elf — start simultaneously. The A11y Elf begins in the background.

Step 4: Wave 1 Runs

Pepper watches the Intent window. Three agent conversations are active. Code appears in the Changes panel. The spec’s task list updates as work progresses.

GPS Elf implements the polling service, using the existing auth token pattern it found via the Context Engine:

// gps-polling.service.ts
export class GpsPollingService {
  private interval = 30_000;
  private backoff = 1;

  async startPolling(onUpdate: (pos: SleighPosition) => void) {
    const poll = async () => {
      try {
        const pos = await reindeerGpsApi.getCurrentPosition();
        onUpdate(pos);
        this.backoff = 1;
      } catch {
        this.backoff = Math.min(this.backoff * 2, 8);
      }
      setTimeout(poll, this.interval * this.backoff);
    };
    poll();
  }
}

The spec updates: ✅ GPS Polling Service — GPS Elf — done.

Map Elf creates the <DeliveryMap /> component using Leaflet.js, which it found already installed in package.json via the Context Engine. It does not install a duplicate library.

Data Elf builds the delivery count and ETA widget, correctly calling the Manifest API’s read-only endpoint and displaying ETA in Workshop local time (it read the spec decision).

Step 5: Handoffs and Wave 2

Both GPS Elf and Map Elf report completion. The spec records the interfaces they produced:

### Decisions
- GPS service exposes: `startPolling(cb: (SleighPosition) => void)`
- Map component props: `{ position: SleighPosition; zoom?: number }`

The Coordinator briefs Responsive Elf with the updated spec and the actual component structure. No guesswork. Test Elf receives both the GPS service interface and the Map component props, plus the existing e2e test patterns from the Context Engine.

Wave 2 begins. Responsive Elf adds Safari/iPad CSS. Test Elf writes integration tests.

Step 6: The Verifier Checks Everything

Wave 2 complete. The Coordinator spawns the Verifier Elf with the full spec and all five implementations.

Verifier’s report:

✅ Map renders in < 1s on iPad Safari — confirmed (Lighthouse: 0.7s)
✅ Position updates within 30s — confirmed
✅ Delivery count matches Manifest API — confirmed
✅ ETA in Workshop local time — confirmed
✅ Existing e2e tests pass — confirmed
✅ Lighthouse accessibility score ≥ 90 — confirmed (score: 94)
⚠️  Minor: GPS service does not log polling errors to existing
    structured logger (see logger.ts — used throughout codebase)

The warning is real and useful. The Context Engine told the Verifier about logger.ts. A generic agent would have missed it.

The Coordinator sends the GPS Elf back for a five-minute fix. It adds one line:

} catch (err) {
  logger.warn('GPS polling failed', { error: err, backoff: this.backoff });

Re-verification: all green.

Step 7: The Pull Request

The Coordinator integrates all five worktrees into a single branch feat/delivery-dashboard and opens a pull request. The PR description is generated from the Living Spec:

## Gift Delivery Dashboard

Implements real-time dashboard (sleigh position, delivery count, ETA).

### Changes
- New: `GpsPollingService` with 30s polling + exponential backoff
- New: `<DeliveryMap />` using existing Leaflet.js dependency
- New: `<DeliveryStats />` widget with ETA in Workshop local time
- New: iPad/Safari responsive CSS
- New: Integration test suite (12 tests, all passing)

### Verified Against Spec
All 6 success criteria confirmed by Verifier Agent.
Existing e2e suite: all passing.

### Decisions Recorded
- ETA displayed in Workshop local time (not UTC) — per Pepper, Dec 3
- Used existing Leaflet.js (not installed new mapping library)
- GPS errors logged via existing structured logger (logger.ts)

Pepper reviews the spec (4 minutes). She reviews the diff (10 minutes, because the spec told her exactly what to look for). She approves.

Total elapsed time: 47 minutes. Zero rework. Christmas safe.

What We Built Together

Over this series, Father Christmas and Head Elf Pepper have explained every layer of Intent:

Concept	What It Does	Workshop Equivalent
Living Spec	Source of truth, auto-updated	Master Gift List
Coordinator Agent	Plans, delegates, manages handoffs	Father Christmas
Specialist Agents	Execute focused tasks in parallel	Craft Elves
Isolated Workspaces	No collisions between parallel agents	Private workbenches
Spec-Driven Development	Plan first, code follows	Write the List before carving begins
Context Engine	Deep codebase knowledge for every agent	The Workshop Library
Multi-Agent Orchestration	Waves, handoffs, background agents	Workshop floor choreography
Resumable Sessions	State preserved across restarts	Workshop never forgets

SIPOC: The Complete Intent Workflow

	S — Suppliers	I — Inputs	P — Process	O — Outputs	C — Customers
Who/What	Developer, Coordinator, Specialists, Context Engine, AI models	Goal statement, codebase, constraints, model selection	Spec → Review → Wave 1 agents → Handoffs → Wave 2 → Verifier → PR	Verified code, living spec, decision log, merged PR	Engineering team, product owner, CI/CD, end users
Workshop	Pepper, Father Christmas, all Elves, the Library	Gift order, Workshop constraints, quality standards	Write List → Agree → Parallel building → Handoffs → QC → Sleigh	All gifts delivered correctly, on time, to every child	Children of the world

Getting Started

Intent is available in public beta for macOS. Download it here. It uses your existing Augment credits. You can also bring Claude Code, Codex, or OpenCode if you already have subscriptions.

Augment’s documentation is at docs.augmentcode.com. Their manifesto — The End of Linear Work — is worth reading before your first session.

One More Sleigh Stop

We have reached the point where the gifts are wrapped, the sleigh is loaded, and the Workshop itself is humming beautifully. But Head Elf Pepper asked me one more excellent question over a final cup of cocoa: *“Santa, what if I want some of this magic outside Intent itself? What if I want Claude Code, the Augment Context Engine, RTK, and LiteLLM working together on a machine of my own?”*Quite right, Pepper. One more stop, then. One more lesson before the reindeer sleep.

In the next episode, Father Christmas steps just beyond the Workshop walls to show how Intent’s principles carry into an external, token-aware coding stack: Claude Code + Augment Context Engine MCP + RTK + LiteLLM on a Mac Mini M4 Pro.

Part of the [*Santa Augmentcode Intent](https://dev.to/wvanheemstra/series/37310) series. Published on [*dev.to](https://dev.to)* under the [*the-software-s-journey](https://dev.to/the-software-s-journey)* organisation.*

Santa Augmentcode Intent Ep.1

Willem van Heemstra — Mon, 25 May 2026 14:30:58 +0000

Santa’s Secret Weapon: Welcome to the Workshop! 🎅

Accompanying source code repository: Santa Augmentcode Intent

Ho ho ho! Come in, come in — the fire is warm and the cocoa is hot. Pull up a stool and let Father Christmas tell you a story. Not about reindeer, not about presents — but about the most magical piece of software to land in the Workshop since the invention of the Nice List.

The Problem With Being Father Christmas

Every year it is the same. December arrives like an avalanche, and suddenly Father Christmas has more tasks than minutes.

The chimneys of the world do not care that Jingle-Bell the Elf is busy repainting the rocking horses while Twinkle the Elf is still debugging the train set firmware. The world expects one coordinated, perfectly wrapped result under every tree by Christmas morning.

For centuries, I managed this with clipboards, coloured yarn on a corkboard, and a great deal of shouting across the workshop floor. Then, this year, Head Elf Pepper handed me a laptop and said: “Santa, you need to see Augment Intent.”

Reader, I wept a single dignified tear into my beard.

What Is Augment Intent?

Augment Intent is a macOS developer workspace designed for the age of AI agents. It is not merely a chat window where you ask a single Elf to do one thing. It is a coordinated workshop where:

A Coordinator (that would be me, Father Christmas) breaks down a complex goal into a living Spec.
Specialist Agents (my Elves) run in parallel, each tackling their portion of the work.
A Verifier Agent checks that what was built actually matches the Spec.
The entire workspace — code, browser, terminal, git — lives in one window, and the state persists when you close the lid.

In short: it is the North Pole Workshop, but running on silicon instead of snowflakes.

The North Pole Analogy, Explained

Before we dive into the technical magic in later episodes, let me introduce the cast of characters you will meet throughout this series.

The Workshop	Augment Intent
Father Christmas	Coordinator Agent
Head Elf Pepper	You, the Developer
The Elves	Specialist Agents (Implement, Verify, Debug, Review…)
The Master Gift List	The Living Spec
Each Elf’s Workbench	Isolated Workspace / Git Worktree
The Workshop Floor	Intent’s unified window
The Context Engine	The Workshop’s shared knowledge of every toy design, material, and elf skill

The magic of Christmas has always been parallelism with coordination. Teddy-bear Elves do not wait for train-set Elves to finish. They work simultaneously, guided by the same Master Gift List. That is precisely what Intent enables for software development.

What This Series Covers

Over the coming episodes, Father Christmas will walk you through Intent one concept at a time, always in the style of a cosy fireside chat. Here is the full gift list:

Episode	Topic
1	Welcome to the Workshop (you are here!)
2	The Master Gift List — Living Specs
3	Santa & the Elves — Coordinator vs Specialist Agents
4	Every Elf Has a Workbench — Isolated Workspaces
5	Finishing in Time for Christmas — Spec-Driven Development
6	The Context Engine — The Workshop Knows Every Toy
7	Parallel Elves, No Chaos — Multi-Agent Orchestration
8	The Delivery — From Spec to Merged Pull Request
9	Beyond the Workshop — Intent Meets an External Agent Stack

SIPOC: The Workshop at a Glance

Before any Elf touches a piece of wood, Father Christmas draws the SIPOC on the big blackboard. Here is Intent’s SIPOC.

	S — Suppliers	I — Inputs	P — Process	O — Outputs	C — Customers
Who/What provides	Developer intent, codebase, models (Claude Opus, Sonnet, GPT…)	Task description, repository files, rules & guidelines	Spec creation → Coordinator planning → Parallel agent execution → Verification	Working code, updated spec, pull request	Engineering team, end users, CI/CD pipeline
Workshop equivalent	Head Elf Pepper, the toy blueprints, the Elf skill registry	The gift order, the raw materials, the Elf roster	Santa writes the Master List → assigns Elves → Elves build in parallel → quality check	Wrapped, labelled gifts → sleigh	Children of the world

Why Should You Care?

You may be thinking: “Santa, I already have VS Code and a single agent. Why do I need a whole workshop?”

Fair question. The answer is the same reason I do not gift-wrap eight billion presents with one pair of hands. Beyond a certain complexity, serial work with a single agent creates a bottleneck. The agent re-explains context, loses state between sessions, and cannot parallelise.

As Augment’s own manifesto puts it: parallel execution is no longer the hard part — coordination is. Intent solves the coordination problem.

Getting Started

Intent is currently in public beta for macOS. You can download it here. It works with your existing Augment credits, and you can even bring Claude Code, Codex, or OpenCode if you already have a subscription for those.

In the next episode, Father Christmas will introduce The Master Gift List — the Living Spec that keeps every Elf pointed at the same star.

Until then: stay warm, write good specs, and remember — Christmas is only ever early for developers who plan ahead.Ho ho ho! 🎅

Part of the Santa Augmentcode Intent series. Published on dev.to under the the-software-s-journey organisation.

Santa Augmentcode Intent Ep.9

Willem van Heemstra — Mon, 25 May 2026 14:30:21 +0000

Beyond the Workshop — Intent Meets an External Agent Stack 🎅

Accompanying solution repository: augment-claude-litellm-rtk

Not every job can be done at the main workbench. Sometimes Father Christmas must leave the Workshop entirely — to inspect a toy factory in Helsinki, advise a biscuit plant in Brussels, or help a Mac Mini in a quiet study learn some manners. On such occasions, I cannot carry the whole North Pole on my back. But I can carry its discipline. And that, dear reader, is what this final episode is about.

When the Workshop Must Travel

Throughout this series, we have talked about Augment Intent as though it were the whole Workshop in one warm, glowing window. And in many ways, it is.

But Head Elf Pepper, being both brilliant and troublesome in equal measure, asked the obvious next question:

“Santa, what if I want some of these advantages when I am working with an external agent stack? What if I want semantic retrieval, slimmer shell output, and model routing without abandoning good engineering discipline?”

An excellent question. The answer is not to copy Intent feature-for-feature in a panic. The answer is to assemble a practical travelling toolkit that preserves the same principles:

use the right context, not just more context,
keep noisy output from flooding the model window,
maintain clear verification steps,
and route models sensibly rather than treating every task as if it requires a royal audience with the most expensive intelligence in the kingdom.

That is precisely what the solution in augment-claude-litellm-rtk offers.

The Travelling Kit: Four Tools in One Case

The repository documents a concrete setup for a token-aware coding stack on macOS Apple Silicon, especially a Mac Mini M4 Pro.

Its four main pieces are:

Claude Code as the external coding agent
Augment Context Engine MCP for semantic codebase retrieval
RTK for reducing verbose shell output before it reaches the model context
LiteLLM as a local AI gateway for routing, budgets, testing, and future expansion

In Workshop terms:

Travelling Kit	Workshop Equivalent
Claude Code	The senior travelling Elf who can actually do the work
Augment Context Engine MCP	The portable Workshop Library
RTK	The Elf who edits rambling reports down to what matters
LiteLLM	The dispatch office that decides which sleigh goes where

The magic here is not the individual tools alone. It is the fact that each one solves a different form of waste.

Why Context Quality Beats Context Quantity

One of the deepest lessons from Intent is that retrieval quality matters more than brute-force stuffing.

If you hand an agent an entire warehouse of scrolls, you have not made it wise. You have merely made it late.

The Augment Context Engine MCP matters because it gives an external agent stack something much closer to the Workshop Library from Episode 6: a way to retrieve the relevant architectural memory at the right moment. Instead of pasting huge files and hoping for the best, the agent can ask for the meaningful part of the codebase.

That is not a luxury. It is cost control, latency control, and correctness control, all disguised as tidiness.

The Hidden Token Tax: Shell Output

Now let Father Christmas tell you about a villain rarely invited into respectable technical architecture diagrams: the verbose shell command.

The shell is useful, of course. But many tools speak like overexcited uncles after mulled wine. They print logs, warnings, duplicate context, and endless lines of output that an agent then dutifully drags into the model context window like muddy boots across a clean floor.

This is where RTK enters the scene.

RTK helps reduce shell output before it hits the model context. In other words, it trims the transcript to what is materially useful. That is splendidly important. Every token wasted on irrelevant command noise is a token not spent on reasoning.

Or, to put it in festive terms: if the reindeer are hauling boilerplate logs, they are not hauling presents.

The Gateway Question: Why LiteLLM Belongs in the Story

The LiteLLM part of this setup deserves a careful, honest explanation.

The repository is admirably clear about this: the fully documented and officially supported core path is Claude Code + Augment Context Engine MCP + RTK. LiteLLM is included because it is useful and production-worthy, but not every environment clearly guarantees a direct Claude Code → LiteLLM base-URL workflow.

That honesty matters.

In the Workshop, we do not claim a sleigh can land on a roof it has never tested. We say what is proven, what is practical, and what is ready for future expansion.

LiteLLM still brings real value here because it gives you:

a local AI gateway,
a place for routing and budget control,
support for OpenAI-compatible tools and scripts,
and a staging ground for future direct integration paths.

It is not smoke and mirrors. It is infrastructure with proper manners.

What the Finished Setup Looks Like

After following the repository, the machine ends up with a rather handsome set of capabilities:

Homebrew-installed prerequisites
Python 3.12 for LiteLLM
Node.js for auggie
Auggie CLI installed and ready
Claude Code installed and authenticated
Augment MCP registered inside Claude Code
rtk installed and initialized for Claude Code shell usage
PostgreSQL 17 running locally for the LiteLLM UI backend
LiteLLM Proxy on http://127.0.0.1:4000
LiteLLM admin UI at http://127.0.0.1:4000/ui
verification scripts and example prompts

That is not merely “a bunch of tools installed.” It is a composed operator’s station.

The Architecture, as Father Christmas Would Draw It

Developer
   │
   ▼
Claude Code
   ├── Augment Context Engine MCP  → retrieves relevant code context
   ├── RTK                         → compresses noisy shell output
   └── LiteLLM Proxy               → routes requests, tracks budgets, enables expansion
                                      │
                                      ▼
                                  Model providers / compatible tools

You will notice something familiar here.

Intent taught us that coordination beats improvisation. This stack applies the same lesson in a looser environment. The coordination is not provided by one integrated application window now; it is provided by a carefully assembled toolchain whose pieces each have a distinct job.

The Recommended Order Matters

The repository even has the decency to tell you the correct order in which to approach the setup:

architecture
prerequisites
install Claude Code
install Auggie and the MCP connection
install RTK
install LiteLLM
verification
daily usage
troubleshooting

This is not administrative fussiness. It is Workshop thinking.

Good systems are built in the right order because later steps depend on earlier truths. Episode 7 taught us about orchestration waves. The same logic applies here, only now the “agents” are installations, services, scripts, and runtime expectations.

Fast Path for the Impatient Elf

For those who cannot resist pulling the ribbon before reading the card, the repository also gives a direct setup path:

cd /path/to/your/workspace
chmod +x scripts/*.sh
./scripts/install_prereqs.sh
./scripts/install_auggie.sh
./scripts/install_rtk.sh
./scripts/setup_litellm.sh

Then you manually complete the sign-ins, register the MCP server, restart Claude Code, and run the verification script.

Even the “fast path” still respects the discipline of verification. That is how you know serious engineers packed this travelling case.

Why This Is a Perfect Episode 9

If Episode 8 showed the ideal, integrated flow of work inside Intent, Episode 9 answers the natural follow-up:

What do the same principles look like when the Workshop goes mobile?

The answer is reassuringly consistent:

preserve semantic retrieval,
reduce irrelevant context,
separate proven paths from aspirational ones,
verify the stack end-to-end,
and make room for future routing sophistication without lying about what is already supported.

That is excellent engineering. Also, I am pleased to report, excellent Christmas engineering.

SIPOC: The Travelling Stack

	S — Suppliers	I — Inputs	P — Process	O — Outputs	C — Customers
Who/What	Developer, Claude Code, Augment MCP, RTK, LiteLLM, local services	Repository, shell commands, MCP registration, local config, verification scripts	Install prerequisites → connect MCP → trim shell output → route through gateway → verify stack	Working token-aware coding environment, lower context waste, future-ready routing setup	Solo developers, engineering teams, cost-conscious operators
Workshop	Father Christmas, travelling Elf, portable library, dispatch desk, tidy stenographer	Tool chest, route map, sleigh rules, checked inventory	Pack the case → bring the right books → shorten the chatter → dispatch the right sleigh → inspect before departure	A reliable travelling workshop that still behaves like the North Pole	Every workshop beyond the snow line

A Final Word from Father Christmas

The true sign of a good Workshop is not that it works only in its own building. It is that its principles survive the journey. Intent taught us to coordinate, retrieve wisely, verify carefully, and keep the plan honest. This external stack shows those same values travelling well: the right agent, the right context, less wasted chatter, and an honest gateway for the road ahead. If you can carry that discipline with you, then you are not merely using clever tools. You are building like the North Pole.

This concludes the [*Santa Augmentcode Intent](https://dev.to/wvanheemstra/series/37310) series. All nine episodes are available on [*dev.to](https://dev.to)* under the [*the-software-s-journey](https://dev.to/the-software-s-journey)* organisation.*

Thank you for reading. May your specs be living, your context relevant, and your token bills modest. Ho ho ho! 🎅

Santa Augmentcode Intent Ep.6

Willem van Heemstra — Mon, 25 May 2026 14:30:15 +0000

The Workshop Knows Every Toy — The Context Engine 🧠

Accompanying source code repository: Santa Augmentcode Intent

People often ask: how do the Elves know how to build anything? We do not run a formal university. There is no Elf Academy. The answer is the Workshop Library — a living collection of every toy blueprint, every material data sheet, every technique manual, and every lesson learned from every Christmas since 843 AD. When an Elf sits down at their workbench, they are not starting from scratch. They are standing on twelve centuries of accumulated knowledge. Augment calls their version of this the Context Engine. I call it essential.

The Problem Every AI Tool Has

Most AI coding tools share one fundamental limitation: they know a great deal about programming in general, and almost nothing about your codebase in particular.

Ask a generic AI assistant to add a feature to your application and it will produce something that compiles — but may ignore your naming conventions, duplicate utilities you already have, conflict with an architecture decision made six months ago, or violate a security pattern your team spent weeks establishing.

The AI does not know what it does not know. And what it does not know is everything specific to you.

What the Context Engine Does

Augment’s Context Engine solves this by maintaining a live, semantic understanding of your entire stack — not just the files you have open, but everything:

Code: every file, class, function, interface across the whole repository.
Dependencies: the libraries you use and how you use them.
Documentation: inline comments, READMEs, architecture docs.
Style: your naming conventions, code patterns, formatting preferences.
Recent changes: what has changed, when, and why (from commit messages and PRs).
Issues: open tickets and known problems in the tracker.

The Context Engine does not just store this as flat text. It builds semantic understanding — it knows that UserAuthService depends on TokenRepository, that the codebase uses dependency injection everywhere, that the team agreed six weeks ago to use RS256 for all signing operations.

When a Specialist Agent is spawned in Intent, it does not receive a raw dump of your entire codebase (which would exceed any model’s context window). The Context Engine curates the relevant context: from 4,456 potential sources, it selects the 682 actually relevant to this task. The Elf gets the right blueprints for the toy it is building, not the entire library.

The North Pole Library Analogy

Imagine your Workshop contains twelve centuries of toy designs. Before the Context Engine, an Elf would walk to the Library, spend an hour searching, find three relevant blueprints, and guess at the rest. Slow, incomplete, error-prone.

With the Context Engine, the Library is live and intelligent. The moment an Elf is assigned to build a toy locomotive, the Library automatically surfaces:

Every locomotive built in the past ten years (with the code patterns used).
The wheel standard the Workshop adopted in 2019.
The paint specification that applies to all wheeled toys.
The safety test that all vehicles must pass.
The in-progress work by the Gauge Elf that this locomotive’s tracks must match.

The Elf starts with full situational awareness. It will not accidentally use the old wheel standard. It will not duplicate the paint specification utility someone wrote three years ago. It will not create a track gauge that conflicts with the in-progress work next door.

Why This Matters for Multi-Agent Work

In single-agent workflows, limited context is an inconvenience. The agent produces slightly generic code that needs tidying.

In multi-agent workflows, limited context is a coordination failure. If Agent A does not know that Agent B is using RS256 signing, Agent A might implement its own signing with a different algorithm. The Verifier will catch this — but only after both agents have done significant work that now needs to be reconciled.

The Context Engine prevents this by ensuring all agents share the same understanding of the codebase from the start. When the Coordinator drafts the spec, it can declare “use RS256 for signing — see existing pattern in *auth/signing.ts”* because it has that knowledge available. Every Specialist that reads the spec inherits that context.

Context Engine vs Vanilla Models: The Numbers

Augment published benchmarks comparing agent performance on the Elasticsearch repository (3.6 million lines of Java, 2,187 contributors). Their agents — powered by the Context Engine — outperformed other tools on a blind evaluation of 500 agent-generated pull requests:

Criterion	Augment	Others
Overall	Outperforms	Underperforms
Correctness	+14.8	-9 to -12
Code Reuse	Notable	Below baseline
Best Practice adherence	Strong	Weakest area

The largest gap was in code reuse and best practice adherence — exactly the dimensions where knowing the codebase matters most. Any model can write code that compiles. Knowing when to reuse an existing utility instead of writing a new one requires context.

How the Context Engine Feeds Intent Specifically

Inside Intent, the Context Engine serves three distinct consumers:

The Coordinator uses it to write a better spec. When it knows the existing architecture, it can propose task decompositions that respect real dependencies rather than imagined ones.

The Specialists use it to write better code. They know the patterns, the utilities, the interfaces they must respect.

The Verifier uses it to catch spec violations that are only visible with codebase knowledge. “This code bypasses the existing rate-limiting middleware” is only a useful comment if the Verifier knows that middleware exists.

SIPOC: Context Engine in Action

	S — Suppliers	I — Inputs	P — Process	O — Outputs	C — Customers
Who/What	Repository, CI/CD history, docs, issues, recent changes	Raw codebase files, dependency manifests, commit history, tickets	Index → Semantic analysis → Relevance ranking → Context curation per task	Curated, task-relevant context for each agent	Coordinator Agent, all Specialist Agents, Verifier Agent
Workshop	The Workshop Library (12 centuries of blueprints)	Every toy design, material spec, historical decisions	Library catalogues → Semantic search → Relevant blueprints selected per Elf	Exactly the right materials and references for each workbench	Every Elf, Father Christmas, Quality Control

A Note on Privacy

Father Christmas takes privacy seriously. So does Augment. The Context Engine processes your codebase to build its index, and Augment’s Trust Center documents how data is handled. For enterprise teams with sensitive codebases, it is worth reviewing before you hand the Library over to the Engine.

What Comes Next

In Episode 7, we bring everything together: multiple Elves, working simultaneously, without chaos. Multi-Agent Orchestration — the art of running a parallel workshop without collision, confusion, or Christmas catastrophe.

An Elf without context is an Elf making expensive guesses. Give them the Library. Give them the Context Engine. Watch them build miracles.Ho ho ho! 🎅

Part of the Santa Augmentcode Intent series. Published on dev.to under the the-software-s-journey organisation.

Santa Augmentcode Intent Ep.5

Willem van Heemstra — Mon, 25 May 2026 14:29:38 +0000

Finishing Before Christmas — Spec-Driven Development 📜

Accompanying source code repository: Santa Augmentcode Intent

Do you know why Christmas always arrives on time? Not because I am superhuman. Not because the reindeer are faster than physics should allow. Christmas arrives on time because of one inviolable rule in the North Pole: nothing gets built until we agree, in writing, on what done looks like. We call it the Master Gift List. The world calls it Spec-Driven Development. The result is the same: no surprises on Christmas morning.

The Old Way: Code First, Regret Later

There is a seductive pattern in software development that I call Build First, Discover Later. It goes like this:

Someone has a rough idea.
A developer (or, increasingly, an agent) starts building immediately.
Halfway through, the stakeholder sees a demo and says: “That is not what I meant at all.”
Everything is reworked. The deadline slips. Someone’s Christmas is ruined.

I have witnessed this pattern in the Workshop. A zealous Elf, eager to begin, starts carving a rocking horse before Father Christmas has decided whether it should be red or blue, large or small, with or without a mane. Three hours later, the horse is red, large, and maned — and the child’s letter clearly specified blue, small, no mane.

The problem is not the Elf’s carving ability. The problem is that work began before intent was explicit.

What Is Spec-Driven Development?

Spec-Driven Development (SDD) is a workflow practice, not a programming paradigm. It has one central principle:

The spec is the primary artifact. Code is the result of executing it.

In SDD, you do not write code and then document it. You write a spec — a precise, executable description of what you intend to build — and then agents (or humans) implement it. The spec comes first. The spec stays current. The spec is what gets reviewed.

Augment Intent was built around this principle. Their product manifesto states it plainly: at that point, the plan becomes the product.

The Three Pillars of SDD in Intent

Pillar 1: Write the Spec Before Any Code

The Coordinator Agent will not spawn Specialists until a spec exists. This is not bureaucracy — it is discipline. A spec written before implementation captures the human’s intent (what success looks like, what constraints exist, what decisions have been made) rather than narrating code that has already been written.

A good pre-implementation spec answers:

What is the goal, measured how?
What must not change (frozen modules, existing contracts, budget)?
What does “done” look like in a test?
Which parts depend on which others?

Pillar 2: The Spec Updates as Work Progresses

A spec that does not evolve becomes fiction. Intent’s living spec updates automatically as agents complete tasks, record decisions, and encounter new constraints. When you return to the spec after a day of agent work, it reflects what was actually built, not what was originally planned.

This closes the gap that traditionally exists between the plan and the product. In most organisations, that gap is enormous and filled with undocumented decisions, tribal knowledge, and polite disagreements about what the requirements “really meant.”

Pillar 3: Review the Spec, Not Just the Code

Code review is expensive. Reviewing a 2,000-line pull request is difficult, slow, and error-prone. Reviewing a spec is cheap. A well-structured spec can be reviewed in minutes, catching fundamental misalignments before a single line of code is written.

SDD moves the review point earlier in the pipeline. You review intent first. Implementation follows. This is why Intent has the Verifier Agent checking output against the spec — because the spec is the ground truth, and the code is measured against it.

The Christmas Deadline as a Forcing Function

Father Christmas has one advantage over most product teams: an unmovable deadline. Christmas is December 25th. Always. Everywhere. It does not slip. It does not move to accommodate a stakeholder who changed their mind in November.

This deadline is a gift (pun intended). It forces the Workshop to be explicit about scope from the very beginning. We cannot add “one more toy” on December 20th without removing something else. Every addition requires a trade-off. The Master Gift List enforces this.

SDD imposes the same discipline on software teams. When the spec defines the scope, additions are visible. You can see exactly what is in and what is out. Scope creep does not happen silently — it requires a spec change, which requires a decision, which requires a conversation. That conversation, had early, is cheap. Had at 11pm on December 24th, it is catastrophic.

SDD vs Traditional Approaches

Aspect	Traditional	Spec-Driven
Source of truth	Code	Living Spec
When specs are written	After or alongside code	Before code
Spec accuracy over time	Drifts (document rot)	Stays current (auto-updated)
Agent alignment	Re-explain each session	Automatic via spec
Review point	Code review only	Spec review + code review
Scope control	Implicit, often invisible	Explicit, requires spec change
Refactoring cost	Break and fix	Spec-guided

SIPOC: Spec-Driven Development Workflow

	S — Suppliers	I — Inputs	P — Process	O — Outputs	C — Customers
Who/What	Product owner, developer, Coordinator Agent	Business goal, constraints, success criteria	Write spec → Review spec → Spawn agents → Agents implement → Spec updates → Verifier checks	Working software that matches intent, accurate documentation, decision log	Engineering team, product owner, QA, end users
Workshop	Management, Head Elf Pepper, Father Christmas	Child’s wish list, Workshop constraints, quality standards	Write the Master List → Agree on scope → Elves build → List updates → QC checks	Gifts that match the wish list, accurate gift manifest, no surprises	Children, parents, Father Christmas himself

A Worked Example: The Christmas Eve Delivery App

Let us say Head Elf Pepper wants to build a real-time delivery tracker for the sleigh. The old way:

Pepper: "Build a delivery tracker."
Agent: [builds something]
Pepper: "That is not what I wanted."
[Repeat until December 24th.]

The SDD way:

## Christmas Eve Delivery Tracker — Spec

### Goal
Real-time map showing sleigh position and remaining deliveries,
updating every 30 seconds, accessible on elves' tablets.

### Success Criteria
- [ ] Map renders in < 1 second on standard tablet browser
- [ ] Position updates within 30s of sleigh movement
- [ ] Remaining house count is accurate (matches manifest)
- [ ] Works offline (last known position shown if signal lost)

### Constraints
- Must use existing Reindeer GPS API (v2)
- No server-side changes to Delivery Manifest Service
- Must work in Safari (elves use iPads)

### Out of Scope (v1)
- Historical route replay
- Per-gift tracking
- Weather overlay

### Tasks
- [ ] Implement GPS polling service — Tracker Elf
- [ ] Build map component — Map Elf
- [ ] Integrate manifest API — Data Elf
- [ ] Offline fallback — Resilience Elf
- [ ] Integration tests — Test Elf

This spec takes ten minutes to write and saves days of rework. The Elves know exactly what to build. Pepper reviews the spec and agrees it is correct before a line of code is written. The Verifier knows exactly what to check.

This is SDD. This is how Christmas gets delivered on time.

What Comes Next

In Episode 6, Father Christmas will explain the Context Engine — the magical knowledge base that ensures every Elf in the Workshop understands every toy design, every material property, and every past decision. Without it, SDD is impossible at scale.

The plan is the product. Everything else is wrapping paper.Ho ho ho! 🎅

Part of the Santa Augmentcode Intent series. Published on dev.to under the the-software-s-journey organisation.

Santa Augmentcode Intent Ep.2

Willem van Heemstra — Mon, 25 May 2026 14:29:32 +0000

The Master Gift List That Writes Itself 🎄

Accompanying source code repository: Santa Augmentcode Intent

Every year, on the first of December, I sit at my great oak desk and open the Master Gift List. In the old days, I wrote it once and hoped for the best. By the fifteenth, it bore little resemblance to reality. An Elf had improvised. A supplier had changed a toy’s colour. Three children had written amended letters. The List lied to me — and I only found out on Christmas Eve.No more.

The Problem With Static Specifications

In software, as in Christmas, requirements arrive in waves. The product owner changes her mind. The designer refines the mockup. The security review adds three new constraints.

Traditional specifications — whether a Confluence page, a Notion doc, or a PDF handed over at the start of a sprint — share one fatal flaw: they are written once and then abandoned. The moment the first line of code is committed, the spec begins to drift. By the time you ship, nobody is quite sure what the original intention was.

Fred Brooks called this “document rot.” Father Christmas calls it “the Lying List,” and it has ruined more Christmas Eves than I care to admit.

The Living Spec: What Intent Does Differently

In Augment Intent, the specification is not a document you write and forget. It is a living spec — a Markdown file that lives inside your workspace and evolves as work progresses.

Here is how it works:

1. You seed the spec. Head Elf Pepper (that is you) types a goal into the Coordinator. The Coordinator drafts an initial spec: requirements, architecture decisions, task breakdown, success criteria.

2. The spec is the source of truth. Every Specialist Agent receives the spec as its briefing. Not a copy of a chat history. Not a vague summary. The actual, versioned spec.

3. As Elves complete tasks, the spec updates. When the Auth Agent finishes the token service, the spec marks that task complete. When the API Agent discovers a complication, the spec records the decision. The spec stays accurate because it is being written by the same agents that are doing the work.

4. When you change your mind, the update propagates. If Pepper changes a constraint mid-flight, the Coordinator updates the spec and re-briefs any Elves whose work is affected. No more Elves building to an outdated design.

A Tale of Two Lists

Let me show you the difference in concrete terms.

The Old Way (Static List):

Ticket XMAS-1234
Title: Improve gift delivery speed
Description: Make it faster. Children are waiting.
Assigned to: @delivery-elf

This ticket is, forgive my language, useless to an agent. What does “faster” mean? Faster than last year? Faster than a competitor? Faster per route, or faster in aggregate? An Elf handed this will make a reasonable guess — and the guess may be entirely wrong.

The New Way (Living Spec):

## Gift Delivery Optimisation — Living Spec

### Goal
Reduce average per-route delivery time by 20% vs Christmas 2024.

### Success Criteria
- [ ] Route calculation completes in < 200ms
- [ ] Zero missed deliveries in smoke test (1,000 houses)
- [ ] Sleigh fuel consumption unchanged or reduced

### Constraints
- Must work with existing reindeer harness API (v3.2)
- No changes to the chimney-descent module (frozen until Jan)

### Tasks
- [x] Profile current route-calculation bottleneck — Dasher Agent
- [ ] Implement A* pathfinding — Prancer Agent (in progress)
- [ ] Integration test against 2024 route dataset — Blitzen Agent
- [ ] Update delivery manifest schema — Rudolph Agent

### Decisions
- 2025-12-03: Chose A* over Dijkstra for weighted graph support
- 2025-12-05: Excluded Antarctic routes from v1 scope

This spec is machine-executable. Every Elf knows what “done” means. Every constraint is explicit. Every decision is recorded. And when Prancer finishes A*, the spec will tick that box and Blitzen will know it is time to start testing.

SIPOC: The Living Spec Process

	S — Suppliers	I — Inputs	P — Process	O — Outputs	C — Customers
Who/What	Developer (Head Elf Pepper), Coordinator Agent, Specialist Agents	Initial goal statement, codebase context, model selection	Goal → Coordinator drafts spec → Agents execute & update → Spec reflects reality	Always-accurate living spec, completed task list, decision log	All Specialist Agents, human reviewers, future contributors
Workshop	Pepper, Father Christmas, the Elves	“Deliver all gifts 20% faster”	Santa writes the List → Elves build → List updates as gifts are wrapped	A gift list that is always true	Every Elf, every Quality Inspector, the Head of Logistics

Why This Matters for Parallel Work

Here is the key insight. When three Elves work simultaneously on different parts of the toy, each one needs to know:

What the other two are building.
Which interfaces they must respect.
What has already been decided.

Without a living spec, each Elf improvises. The train set’s power connector uses a different voltage than the controller the second Elf built. Integration collapses at the last minute.

With a living spec, those interfaces are declared upfront. When the first Elf changes something, the spec records it, and the second Elf’s briefing updates. The spec is the coordination mechanism.

As Augment’s manifesto puts it: once you are running multiple agents in parallel, the spec stops being process and starts being infrastructure.

Practical Notes: Writing a Good Spec Seed

Father Christmas has learned, through decades of painful experience, that the quality of the output depends entirely on the quality of the intent put in. Here are my rules for seeding a Living Spec:

Name the goal, not the solution. Write “reduce onboarding drop-off by 20%”, not “add a progress bar to the onboarding screen”.
State the constraints explicitly. Frozen modules, existing APIs, budget limits — write them down before any Elf starts.
Define done. A measurable success criterion is worth a hundred vague requirements.
Record decisions as they are made. An undocumented decision is an ambiguity waiting to cause a merge conflict.

What Is Coming Next

In Episode 3, Father Christmas will introduce the most important relationship in the Workshop: Santa the Coordinator and the Elves as Specialist Agents. We will examine who does what, how handoffs work, and why the Verifier Elf might be the most important Elf in the building.

The Master Gift List is only as good as the team that follows it. Fortunately, my team is excellent.Ho ho ho! 🎅

Part of the Santa Augmentcode Intent series. Published on dev.to under the the-software-s-journey organisation.

Santa Augmentcode Intent Ep.3

Willem van Heemstra — Mon, 25 May 2026 14:28:55 +0000

Santa Plans, Elves Build — Coordinator & Specialist Agents 🧝

Accompanying source code repository: Santa Augmentcode Intent

A common misconception about the North Pole is that I build all the toys. I do not. I tried that once in 1742. It was catastrophic. What I do — what I have always done — is understand what needs to be built, break it into sensible pieces, assign the right Elf to each piece, and make sure the whole thing comes together correctly. That is the job of Father Christmas. And, as it turns out, that is also the job of the Coordinator Agent in Augment Intent.

The Fundamental Division of Labour

There is a reason the Workshop has roles. An Elf who is brilliant at carving wooden horses may be hopeless at soldering circuit boards. Mixing roles creates chaos. Clear roles create Christmas.

Augment Intent formalises this insight into a three-part agent architecture:

Role	Intent Name	North Pole Equivalent
Plans, delegates, aligns	Coordinator	Father Christmas
Executes a specific task	Specialist / Implementor	Craft Elves
Checks output against the spec	Verifier	Quality Control Elves
Explores feasibility	Investigate Agent	Scout Elves
Finds and fixes failures	Debug Agent	Repair Elves
Reviews code quality	Code Review Agent	Senior Elves

Each role is available as a named Specialist inside Intent. You can use the built-in roster or bring your own.

What the Coordinator Does

The Coordinator is the first Agent you interact with in Intent. You give it a goal — in plain language — and it does the following:

Step 1 — Draft the Living Spec. The Coordinator reads your goal, consults the Context Engine (the Workshop’s knowledge of your entire codebase), and produces a structured spec with requirements, constraints, success criteria, and a proposed task breakdown.

Step 2 — Decompose into parallel tasks. The Coordinator identifies which parts of the work can run simultaneously. Building the token service does not depend on the gateway middleware being ready. Both can start at once. The Coordinator maps these dependencies explicitly.

Step 3 — Spawn and brief Specialists. For each task, the Coordinator creates a Specialist Agent, hands it the relevant portion of the spec, and grants it access to the appropriate files. The Specialist gets what it needs — nothing more, nothing less.

Step 4 — Manage handoffs. When Specialist A finishes and Specialist B depends on that result, the Coordinator orchestrates the handoff. The spec updates, B gets the new context, and work continues without human involvement.

Step 5 — Run the Verifier. Once implementation is complete, the Coordinator spawns the Verifier Agent, which checks the output against the spec’s success criteria. If something fails, the Coordinator sends it back to the relevant Specialist.

What the Specialists Do

Specialists are focused. Each one has a single job and the full Context Engine behind it.

An Implement Specialist receives a task like “add JWT validation middleware to the API gateway” along with the relevant spec section, the existing middleware code, and the interface contracts agreed with other Specialists. It writes the code, commits it to its isolated branch, and reports back to the Coordinator.

A Verify Specialist receives the spec’s success criteria and the completed implementation. It runs tests, checks edge cases, and returns a structured verdict: pass, fail, or pass-with-caveats.

A Debug Specialist receives a failing test, a stack trace, and the relevant code. Its only job is to find and fix the root cause.

None of these Specialists needs to know about the other tasks in the session. The Coordinator holds the big picture. The Specialists hold deep focus.

The Conversation Pattern

Here is a simplified transcript of how a session looks, using the North Pole analogy:

Head Elf Pepper → Coordinator:
"We need JWT authentication across the API gateway and auth service.
Tokens issued by auth-service, validated by gateway middleware.
Support refresh tokens and rate-limit the token endpoint."

Coordinator:
"Understood. I have drafted the spec. I am spawning three Elves:
• Auth Token Elf — implements issuance and refresh in auth-service
• Gateway Middleware Elf — implements validation in api-gateway
• Test Suite Elf — writes integration tests (starts after both finish)
Auth Token Elf and Gateway Middleware Elf are running in parallel now."

[20 minutes pass]

Auth Token Elf → Coordinator:
"Token issuance and refresh complete. Endpoints documented in spec."

Gateway Middleware Elf → Coordinator:
"JWT validation middleware complete. RS256 signing, expiry handling done."

Coordinator → Test Suite Elf:
"Both implementation Elves are done. Here is the updated spec.
Please write integration tests covering token issuance, refresh, expiry,
and rate limiting."

[Test Suite Elf runs]

Coordinator → Verify Elf:
"All tasks complete. Please verify against spec success criteria."

Verify Elf → Coordinator:
"Passed: 8/9 criteria. FAILED: rate limiting returns 429 but does not
include Retry-After header (spec line 14)."

Coordinator → Gateway Middleware Elf:
"Please fix: add Retry-After header to 429 responses."

No human needed to manage any of that. Pepper set the goal. Father Christmas ran the workshop.

Choosing the Right Model for Each Role

One of Intent’s most practical features is that you can assign different AI models to different roles. Not every task benefits from the most powerful (and most expensive) model.

Task	Recommended Model Tier	Why
Coordinator — initial architecture	Opus (high reasoning)	Complex decomposition requires deep thinking
Implementor — routine code	Sonnet (fast, efficient)	Well-scoped tasks need speed, not heavy reasoning
Verifier	Sonnet or Opus	Depends on spec complexity
Debug	Opus	Root-cause analysis benefits from thorough reasoning

Father Christmas always uses his best judgment for the biggest decisions and delegates the routine work to whichever Elf is quickest. Intent works the same way.

SIPOC: Coordinator → Specialists → Verifier

	S — Suppliers	I — Inputs	P — Process	O — Outputs	C — Customers
Who/What	Developer, Context Engine, AI models	Goal statement, living spec, codebase, model selection	Coordinator plans → Specialists implement in parallel → Verifier checks → loop until done	Verified, spec-compliant implementation, merged PR	Engineering team, product owner, end users
Workshop	Pepper, the Workshop’s knowledge base, Elf skill roster	“Implement JWT auth”	Santa assigns → Elves build simultaneously → QC Elf inspects → rework if needed	Wrapped, quality-checked gifts ready for the sleigh	Children worldwide

What Can Go Wrong (And How Intent Handles It)

Even the best Workshop has incidents. An Elf misunderstands a spec line. A dependency is not available. A test fails unexpectedly.

Intent’s response is always to route the problem back through the spec. The Coordinator does not panic. It reads the failure report, updates the spec with the new constraint or decision, and re-briefs the relevant Specialist. The loop closes cleanly.

The developer only needs to intervene when the Coordinator surfaces a decision that requires human judgment — a product question, a risk acceptance, a business constraint that was not in the original spec. Everything else is handled in the Workshop.

What Comes Next

In Episode 4, we will visit each Elf’s private workbench — the isolated workspace that Intent creates for every agent, ensuring no two Elves ever clobber each other’s work. Git worktrees, parallel branches, and the magic of resumable sessions.

Every great team needs great coordination. I have been coordinating for over a thousand years. I am pleased that software has finally caught up.Ho ho ho! 🎅

Part of the Santa Augmentcode Intent series. Published on dev.to under the the-software-s-journey organisation.

Santa Augmentcode Intent Ep.7

Willem van Heemstra — Mon, 25 May 2026 14:28:49 +0000

Parallel Elves, Zero Chaos — Multi-Agent Orchestration 🎁

Accompanying source code repository: Santa Augmentcode Intent

The secret to running a smooth Workshop is understanding the difference between work that can happen at the same time and work that cannot. You cannot paint a toy before it is carved. You cannot test a toy before it is assembled. But you can absolutely carve a hundred toys simultaneously, paint them in parallel once each is carved, and run quality checks in a third wave. The key is knowing the dependencies. The key, always, is the spec.

From Solo Agent to Agent Orchestra

In the early days of AI-assisted coding, the workflow was simple: one developer, one agent, one task at a time. The agent typed fast, but the work was serial. Task A finished before Task B started.

This is like running the North Pole Workshop with one Elf. Technically sufficient. Practically absurd.

The shift to multi-agent work is not simply “run more agents.” It is a fundamentally different coordination challenge. Fred Brooks described it for humans in The Mythical Man-Month: adding more workers to a project does not automatically accelerate it, because communication overhead grows and integration becomes the dominant cost. AI agents do not repeal this dynamic — they accelerate it.

Intent’s multi-agent orchestration is the answer to Brooks’ challenge, applied to AI agents.

The Three-Wave Pattern

Father Christmas has observed that most Workshop tasks fall into three waves of parallelism. Intent reflects this naturally.

Wave 1 — Parallel ImplementationTasks that are independent of each other can start simultaneously. The Auth Token Elf and the Gateway Middleware Elf do not need each other’s output. They start at the same time, work on separate worktrees, and finish independently.

Wave 2 — Dependent IntegrationTasks that depend on Wave 1 completing. The Test Suite Elf cannot write meaningful integration tests until both implementation Elves are done. It waits for its inputs, then starts immediately when they arrive.

Wave 3 — Verification and ReviewThe Verifier and Code Review Elves run after Wave 2. They check everything against the spec, catch remaining issues, and produce the final verdict.

Wave 1 (parallel):
  Auth Token Elf ─────────────────────── done ──┐
  Gateway Middleware Elf ──────────────── done ──┤

Wave 2 (parallel, starts after Wave 1):          │
  Test Suite Elf ◄──────────────────────────────┤
  Docs Generator Elf ◄──────────────────────────┘

Wave 3 (after Wave 2):
  Verifier Elf ◄──────────────── checks all ──► Report
  Code Review Elf ◄────────────────────────── Review

The Coordinator manages these waves automatically, based on the dependency graph in the spec. No human needs to tell it when Wave 2 can start. The spec encodes that information.

Background Agents: The Night Shift

Intent also supports background agents — Elves who work quietly while you are focused elsewhere.

In the JWT authentication example from Episode 3, while the two main implementation Elves are doing their headline work, three background Elves are running simultaneously:

Lint & Type Check Elf: continuously checking that changes do not break type safety or style rules.
Test Suite Elf: writing tests in the background as interfaces are published.
Docs Generator Elf: updating API documentation as endpoint signatures emerge.

These background agents do not block the main flow. They run in their own worktrees, produce their own commits, and report back to the Coordinator when done. The Coordinator integrates their output into the final pull request.

In the Workshop, these are the Elves who quietly restock materials, update the inventory, and prepare the packaging while the headline crafting is happening. They are not glamorous. They are indispensable.

Handling Handoffs Gracefully

The most fragile moment in any multi-agent workflow is the handoff: when one agent’s output becomes another agent’s input.

Without orchestration, handoffs fail silently. Agent A finishes and commits. Agent B starts and discovers Agent A’s interface is different from what the spec described. Confusion, rework, delay.

Intent handles handoffs through the spec. When Agent A completes, it updates the spec with the actual interface it produced. The Coordinator reads this update and re-briefs Agent B with the accurate information before it starts. Agent B always starts with the truth.

This is analogous to a baton in a relay race. The baton is the spec. The Coordinator ensures it is passed correctly. No dropped batons. No Christmas Eve disasters.

When to Use Which Specialist

Intent ships with a default set of Specialists. Here is Father Christmas’s guide to deploying them:

Specialist	When to Use	North Pole Role
Investigate	Before writing the spec — explore feasibility	Scout Elves assessing a new toy design
Implement	Core code production	Craft Elves at their workbenches
Verify	After implementation — check against spec	Quality Control Elves
Critique	Review the spec before coding starts	Senior Elves challenging the design
Debug	When tests fail or behaviour is wrong	Repair Elves
Code Review	Automated PR review with codebase context	Senior Elves reviewing finished work

The rule is: never skip Investigate for genuinely novel tasks, and never skip Verify before merging. Skipping these is how gifts arrive with missing parts.

Bringing Your Own Elves

Intent is designed to be open. You can bring your own specialist agents — Claude Code, OpenAI Codex, or OpenCode — and integrate them into the orchestration. If your team has built a custom agent that specialises in your domain (a “Security Review Elf” that knows your specific compliance requirements, for example), it can be plugged in as a Specialist.

Father Christmas respects specialisation. The best Toy Locomotive Elf is not the best Rag Doll Elf. The Workshop thrives because it matches the right Elf to the right toy.

SIPOC: Multi-Agent Orchestration

	S — Suppliers	I — Inputs	P — Process	O — Outputs	C — Customers
Who/What	Coordinator, all Specialist Agents, Context Engine, spec	Task dependency graph, agent roster, model selections, codebase	Identify parallelism → Wave 1 agents start → Handoffs via spec → Wave 2 starts → Background agents run → Verifier checks → PR ready	Verified, integrated pull request; updated spec; decision log	Developer, CI/CD, code reviewers, end users
Workshop	Father Christmas, all Elves, the Library	Dependency chart, Elf skills, material availability	Independent tasks start together → Handoffs recorded in Master List → Dependent tasks start when inputs ready → QC checks everything	All gifts built correctly, verified, packaged, on the sleigh	Children, parents, Christmas morning

The Mythical Man-Month, Solved (Partially)

Brooks was right: coordination is the dominant cost. Adding more agents to a poorly organised task makes it worse.

But Brooks was writing about human coordination, with its communication overhead and context-switching costs. Intent changes the calculus. When the spec is the coordination layer — when every agent is briefed from the same living document, when handoffs are managed by the Coordinator, when each agent has its own isolated workspace — the overhead of adding an agent is dramatically lower than adding a human.

Not zero. Not magic. But dramatically lower.

This is how the North Pole gets better every year. We do not just add Elves. We improve the coordination. The Workshop gets smarter, not just bigger.

What Comes Next

In our final episode, Father Christmas walks you through the complete journey: from first prompt to merged pull request. We bring together the spec, the Coordinator, the Elves, the workbenches, the Context Engine, and the orchestration — and we ship.

An orchestra without a conductor is noise. With a conductor, it is music. The spec is the score. The Coordinator is the conductor. The Elves are the musicians. And the result, when everything works, is Christmas.Ho ho ho! 🎅

Part of the Santa Augmentcode Intent series. Published on dev.to under the the-software-s-journey organisation.

Santa Augmentcode Intent Ep.9

Willem van Heemstra — Fri, 24 Apr 2026 07:25:48 +0000

Beyond the Workshop — Intent Meets an External Agent Stack 🎅

Accompanying solution repository: augment-claude-litellm-rtk

Not every job can be done at the main workbench. Sometimes Father Christmas must leave the Workshop entirely — to inspect a toy factory in Helsinki, advise a biscuit plant in Brussels, or help a Mac Mini in a quiet study learn some manners. On such occasions, I cannot carry the whole North Pole on my back. But I can carry its discipline. And that, dear reader, is what this final episode is about.

When the Workshop Must Travel

Throughout this series, we have talked about Augment Intent as though it were the whole Workshop in one warm, glowing window. And in many ways, it is.

But Head Elf Pepper, being both brilliant and troublesome in equal measure, asked the obvious next question:

An excellent question. The answer is not to copy Intent feature-for-feature in a panic. The answer is to assemble a practical travelling toolkit that preserves the same principles:

use the right context, not just more context,
keep noisy output from flooding the model window,
maintain clear verification steps,
and route models sensibly rather than treating every task as if it requires a royal audience with the most expensive intelligence in the kingdom.

That is precisely what the solution in augment-claude-litellm-rtk offers.

The Travelling Kit: Four Tools in One Case

The repository documents a concrete setup for a token-aware coding stack on macOS Apple Silicon, especially a Mac Mini M4 Pro.

Its four main pieces are:

Claude Code as the external coding agent
Augment Context Engine MCP for semantic codebase retrieval
RTK for reducing verbose shell output before it reaches the model context
LiteLLM as a local AI gateway for routing, budgets, testing, and future expansion

In Workshop terms:

Travelling Kit	Workshop Equivalent
Claude Code	The senior travelling Elf who can actually do the work
Augment Context Engine MCP	The portable Workshop Library
RTK	The Elf who edits rambling reports down to what matters
LiteLLM	The dispatch office that decides which sleigh goes where

The magic here is not the individual tools alone. It is the fact that each one solves a different form of waste.

Why Context Quality Beats Context Quantity

One of the deepest lessons from Intent is that retrieval quality matters more than brute-force stuffing.

If you hand an agent an entire warehouse of scrolls, you have not made it wise. You have merely made it late.

That is not a luxury. It is cost control, latency control, and correctness control, all disguised as tidiness.

The Hidden Token Tax: Shell Output

Now let Father Christmas tell you about a villain rarely invited into respectable technical architecture diagrams: the verbose shell command.

This is where RTK enters the scene.

Or, to put it in festive terms: if the reindeer are hauling boilerplate logs, they are not hauling presents.

The Gateway Question: Why LiteLLM Belongs in the Story

The LiteLLM part of this setup deserves a careful, honest explanation.

That honesty matters.

In the Workshop, we do not claim a sleigh can land on a roof it has never tested. We say what is proven, what is practical, and what is ready for future expansion.

LiteLLM still brings real value here because it gives you:

a local AI gateway,
a place for routing and budget control,
support for OpenAI-compatible tools and scripts,
and a staging ground for future direct integration paths.

It is not smoke and mirrors. It is infrastructure with proper manners.

What the Finished Setup Looks Like

After following the repository, the machine ends up with a rather handsome set of capabilities:

Homebrew-installed prerequisites
Python 3.12 for LiteLLM
Node.js for auggie
Auggie CLI installed and ready
Claude Code installed and authenticated
Augment MCP registered inside Claude Code
rtk installed and initialized for Claude Code shell usage
PostgreSQL 17 running locally for the LiteLLM UI backend
LiteLLM Proxy on http://127.0.0.1:4000
LiteLLM admin UI at http://127.0.0.1:4000/ui
verification scripts and example prompts

That is not merely “a bunch of tools installed.” It is a composed operator’s station.

The Architecture, as Father Christmas Would Draw It

Developer
   │
   ▼
Claude Code
   ├── Augment Context Engine MCP  → retrieves relevant code context
   ├── RTK                         → compresses noisy shell output
   └── LiteLLM Proxy               → routes requests, tracks budgets, enables expansion
                                      │
                                      ▼
                                  Model providers / compatible tools

You will notice something familiar here.

The Recommended Order Matters

The repository even has the decency to tell you the correct order in which to approach the setup:

architecture
prerequisites
install Claude Code
install Auggie and the MCP connection
install RTK
install LiteLLM
verification
daily usage
troubleshooting

This is not administrative fussiness. It is Workshop thinking.

Fast Path for the Impatient Elf

For those who cannot resist pulling the ribbon before reading the card, the repository also gives a direct setup path:

cd /path/to/your/workspace
chmod +x scripts/*.sh
./scripts/install_prereqs.sh
./scripts/install_auggie.sh
./scripts/install_rtk.sh
./scripts/setup_litellm.sh

Then you manually complete the sign-ins, register the MCP server, restart Claude Code, and run the verification script.

Even the “fast path” still respects the discipline of verification. That is how you know serious engineers packed this travelling case.

Why This Is a Perfect Episode 9

If Episode 8 showed the ideal, integrated flow of work inside Intent, Episode 9 answers the natural follow-up:

What do the same principles look like when the Workshop goes mobile?

The answer is reassuringly consistent:

preserve semantic retrieval,
reduce irrelevant context,
separate proven paths from aspirational ones,
verify the stack end-to-end,
and make room for future routing sophistication without lying about what is already supported.

That is excellent engineering. Also, I am pleased to report, excellent Christmas engineering.

SIPOC: The Travelling Stack

	S — Suppliers	I — Inputs	P — Process	O — Outputs	C — Customers
Who/What	Developer, Claude Code, Augment MCP, RTK, LiteLLM, local services	Repository, shell commands, MCP registration, local config, verification scripts	Install prerequisites → connect MCP → trim shell output → route through gateway → verify stack	Working token-aware coding environment, lower context waste, future-ready routing setup	Solo developers, engineering teams, cost-conscious operators
Workshop	Father Christmas, travelling Elf, portable library, dispatch desk, tidy stenographer	Tool chest, route map, sleigh rules, checked inventory	Pack the case → bring the right books → shorten the chatter → dispatch the right sleigh → inspect before departure	A reliable travelling workshop that still behaves like the North Pole	Every workshop beyond the snow line

A Final Word from Father Christmas

The true sign of a good Workshop is not that it works only in its own building. It is that its principles survive the journey. Intent taught us to coordinate, retrieve wisely, verify carefully, and keep the plan honest. This external stack shows those same values travelling well: the right agent, the right context, less wasted chatter, and an honest gateway for the road ahead. If you can carry that discipline with you, then you are not merely using clever tools. You are building like the North Pole.

Thank you for reading. May your specs be living, your context relevant, and your token bills modest. Ho ho ho! 🎅

Santa Augmentcode Intent Ep.8

Willem van Heemstra — Fri, 24 Apr 2026 07:25:42 +0000

The Gifts Are Under the Tree — From Spec to Merged PR 🎄

Accompanying source code repository: Santa Augmentcode Intent

Every year, on the morning of December 25th, I allow myself one quiet moment before the sleigh is unpacked and the Thank-You Letters start arriving. I sit in the empty Workshop, still warm from the night’s work, and look at the bare shelves where the gifts used to be. They are gone because they were delivered. Every one of them. On time, as specified, to the right address. That moment — that quiet confirmation that everything worked — is what we have been building towards in this entire series. Today, we deliver.

The Complete Picture

Over the past seven episodes, we have assembled all the pieces of the Intent workshop:

Episode 1: The Workshop and what Intent is.
Episode 2: The Living Spec — the source of truth.
Episode 3: Santa the Coordinator and the Specialist Elves.
Episode 4: Isolated workspaces and resumable sessions.
Episode 5: Spec-Driven Development and finishing on time.
Episode 6: The Context Engine — the Workshop Library.
Episode 7: Multi-agent orchestration in waves.

Now we put them all together and walk through a complete Intent session, from the moment Head Elf Pepper opens the application to the moment the pull request is merged.

The Scenario

Constraints:

Use the existing Reindeer GPS API (v2)
No changes to the Delivery Manifest microservice
Safari / iPad compatible
Must pass existing end-to-end test suite

Step 1: Open Intent and Set the Goal

Pepper opens Intent on her MacBook. She types into the Coordinator:

We need a real-time gift delivery dashboard. Show sleigh position
on a map, remaining delivery count, and estimated completion time.
Updates every 30 seconds. Must work on iPad Safari.
Use Reindeer GPS API v2. No changes to Delivery Manifest Service.

Step 2: The Coordinator Drafts the Living Spec

Within seconds, the Coordinator produces:

## Gift Delivery Dashboard — Living Spec

### Goal
Real-time dashboard showing sleigh position, delivery count,
and ETA. Updates every 30 seconds. iPad Safari compatible.

### Success Criteria
- [ ] Map renders in < 1s on iPad Safari
- [ ] Position updates within 30s of GPS data change
- [ ] Delivery count matches Manifest API response
- [ ] ETA calculated from current position + remaining stops
- [ ] All existing e2e tests pass
- [ ] Lighthouse accessibility score ≥ 90

### Constraints
- Reindeer GPS API v2 (existing auth token pattern)
- Delivery Manifest Service: read-only, no new endpoints
- Safari / iPad: no Chrome-only APIs

### Architecture
- New React component: `<DeliveryDashboard />`
- GPS polling service (30s interval, exponential backoff on fail)
- Map: Leaflet.js (already in dependencies — see package.json)
- Offline fallback: show last known position with staleness indicator

### Tasks
- [ ] GPS Polling Service — GPS Elf
- [ ] Map Component — Map Elf
- [ ] Delivery Count & ETA Widget — Data Elf
- [ ] Safari/iPad CSS fixes — Responsive Elf
- [ ] Integration tests — Test Elf (starts after GPS + Map done)
- [ ] Accessibility audit — A11y Elf (background)

### Decisions
(none yet)

Pepper reads the spec. She adds one clarification: “ETA should display in local Workshop time, not UTC.” The Coordinator updates the spec and records the decision.

Review time: 4 minutes. No code written yet. One important decision already captured.

Step 3: Intent Creates Isolated Workspaces

The Coordinator identifies the dependency graph:

GPS Elf and Map Elf can start in parallel immediately.
Data Elf can start immediately (it only reads from the Manifest API).
Responsive Elf can start once Map Elf has a working component.
Test Elf starts after GPS Elf and Map Elf complete.
A11y Elf runs as a background agent throughout.

Intent creates five Git worktrees:

feat/dashboard-gps-service        ← GPS Elf
feat/dashboard-map-component      ← Map Elf
feat/dashboard-data-widgets       ← Data Elf
feat/dashboard-responsive         ← Responsive Elf (waiting)
feat/dashboard-tests              ← Test Elf (waiting)

Wave 1 agents — GPS Elf, Map Elf, Data Elf — start simultaneously. The A11y Elf begins in the background.

Step 4: Wave 1 Runs

Pepper watches the Intent window. Three agent conversations are active. Code appears in the Changes panel. The spec’s task list updates as work progresses.

GPS Elf implements the polling service, using the existing auth token pattern it found via the Context Engine:

// gps-polling.service.ts
export class GpsPollingService {
  private interval = 30_000;
  private backoff = 1;

  async startPolling(onUpdate: (pos: SleighPosition) => void) {
    const poll = async () => {
      try {
        const pos = await reindeerGpsApi.getCurrentPosition();
        onUpdate(pos);
        this.backoff = 1;
      } catch {
        this.backoff = Math.min(this.backoff * 2, 8);
      }
      setTimeout(poll, this.interval * this.backoff);
    };
    poll();
  }
}

The spec updates: ✅ GPS Polling Service — GPS Elf — done.

Map Elf creates the <DeliveryMap /> component using Leaflet.js, which it found already installed in package.json via the Context Engine. It does not install a duplicate library.

Data Elf builds the delivery count and ETA widget, correctly calling the Manifest API’s read-only endpoint and displaying ETA in Workshop local time (it read the spec decision).

Step 5: Handoffs and Wave 2

Both GPS Elf and Map Elf report completion. The spec records the interfaces they produced:

### Decisions
- GPS service exposes: `startPolling(cb: (SleighPosition) => void)`
- Map component props: `{ position: SleighPosition; zoom?: number }`

Wave 2 begins. Responsive Elf adds Safari/iPad CSS. Test Elf writes integration tests.

Step 6: The Verifier Checks Everything

Wave 2 complete. The Coordinator spawns the Verifier Elf with the full spec and all five implementations.

Verifier’s report:

✅ Map renders in < 1s on iPad Safari — confirmed (Lighthouse: 0.7s)
✅ Position updates within 30s — confirmed
✅ Delivery count matches Manifest API — confirmed
✅ ETA in Workshop local time — confirmed
✅ Existing e2e tests pass — confirmed
✅ Lighthouse accessibility score ≥ 90 — confirmed (score: 94)
⚠️  Minor: GPS service does not log polling errors to existing
    structured logger (see logger.ts — used throughout codebase)

The warning is real and useful. The Context Engine told the Verifier about logger.ts. A generic agent would have missed it.

The Coordinator sends the GPS Elf back for a five-minute fix. It adds one line:

} catch (err) {
  logger.warn('GPS polling failed', { error: err, backoff: this.backoff });

Re-verification: all green.

Step 7: The Pull Request

The Coordinator integrates all five worktrees into a single branch feat/delivery-dashboard and opens a pull request. The PR description is generated from the Living Spec:

## Gift Delivery Dashboard

Implements real-time dashboard (sleigh position, delivery count, ETA).

### Changes
- New: `GpsPollingService` with 30s polling + exponential backoff
- New: `<DeliveryMap />` using existing Leaflet.js dependency
- New: `<DeliveryStats />` widget with ETA in Workshop local time
- New: iPad/Safari responsive CSS
- New: Integration test suite (12 tests, all passing)

### Verified Against Spec
All 6 success criteria confirmed by Verifier Agent.
Existing e2e suite: all passing.

### Decisions Recorded
- ETA displayed in Workshop local time (not UTC) — per Pepper, Dec 3
- Used existing Leaflet.js (not installed new mapping library)
- GPS errors logged via existing structured logger (logger.ts)

Pepper reviews the spec (4 minutes). She reviews the diff (10 minutes, because the spec told her exactly what to look for). She approves.

Total elapsed time: 47 minutes. Zero rework. Christmas safe.

What We Built Together

Over this series, Father Christmas and Head Elf Pepper have explained every layer of Intent:

Concept	What It Does	Workshop Equivalent
Living Spec	Source of truth, auto-updated	Master Gift List
Coordinator Agent	Plans, delegates, manages handoffs	Father Christmas
Specialist Agents	Execute focused tasks in parallel	Craft Elves
Isolated Workspaces	No collisions between parallel agents	Private workbenches
Spec-Driven Development	Plan first, code follows	Write the List before carving begins
Context Engine	Deep codebase knowledge for every agent	The Workshop Library
Multi-Agent Orchestration	Waves, handoffs, background agents	Workshop floor choreography
Resumable Sessions	State preserved across restarts	Workshop never forgets

SIPOC: The Complete Intent Workflow

	S — Suppliers	I — Inputs	P — Process	O — Outputs	C — Customers
Who/What	Developer, Coordinator, Specialists, Context Engine, AI models	Goal statement, codebase, constraints, model selection	Spec → Review → Wave 1 agents → Handoffs → Wave 2 → Verifier → PR	Verified code, living spec, decision log, merged PR	Engineering team, product owner, CI/CD, end users
Workshop	Pepper, Father Christmas, all Elves, the Library	Gift order, Workshop constraints, quality standards	Write List → Agree → Parallel building → Handoffs → QC → Sleigh	All gifts delivered correctly, on time, to every child	Children of the world

Getting Started

Intent is available in public beta for macOS. Download it here. It uses your existing Augment credits. You can also bring Claude Code, Codex, or OpenCode if you already have subscriptions.

Augment’s documentation is at docs.augmentcode.com. Their manifesto — The End of Linear Work — is worth reading before your first session.

One More Sleigh Stop

We have reached the point where the gifts are wrapped, the sleigh is loaded, and the Workshop itself is humming beautifully. But Head Elf Pepper asked me one more excellent question over a final cup of cocoa: *“Santa, what if I want some of this magic outside Intent itself? What if I want Claude Code, the Augment Context Engine, RTK, and LiteLLM working together on a machine of my own?”*Quite right, Pepper. One more stop, then. One more lesson before the reindeer sleep.

Santa Augmentcode Intent Ep.9

Willem van Heemstra — Sun, 19 Apr 2026 19:38:45 +0000

Beyond the Workshop — Intent Meets an External Agent Stack 🎅

Accompanying solution repository: augment-claude-litellm-rtk

Not every job can be done at the main workbench. Sometimes Father Christmas must leave the Workshop entirely — to inspect a toy factory in Helsinki, advise a biscuit plant in Brussels, or help a Mac Mini in a quiet study learn some manners. On such occasions, I cannot carry the whole North Pole on my back. But I can carry its discipline. And that, dear reader, is what this final episode is about.

When the Workshop Must Travel

Throughout this series, we have talked about Augment Intent as though it were the whole Workshop in one warm, glowing window. And in many ways, it is.

But Head Elf Pepper, being both brilliant and troublesome in equal measure, asked the obvious next question:

An excellent question. The answer is not to copy Intent feature-for-feature in a panic. The answer is to assemble a practical travelling toolkit that preserves the same principles:

use the right context, not just more context,
keep noisy output from flooding the model window,
maintain clear verification steps,
and route models sensibly rather than treating every task as if it requires a royal audience with the most expensive intelligence in the kingdom.

That is precisely what the solution in augment-claude-litellm-rtk offers.

The Travelling Kit: Four Tools in One Case

The repository documents a concrete setup for a token-aware coding stack on macOS Apple Silicon, especially a Mac Mini M4 Pro.

Its four main pieces are:

Claude Code as the external coding agent
Augment Context Engine MCP for semantic codebase retrieval
RTK for reducing verbose shell output before it reaches the model context
LiteLLM as a local AI gateway for routing, budgets, testing, and future expansion

In Workshop terms:

Travelling Kit	Workshop Equivalent
Claude Code	The senior travelling Elf who can actually do the work
Augment Context Engine MCP	The portable Workshop Library
RTK	The Elf who edits rambling reports down to what matters
LiteLLM	The dispatch office that decides which sleigh goes where

The magic here is not the individual tools alone. It is the fact that each one solves a different form of waste.

Why Context Quality Beats Context Quantity

One of the deepest lessons from Intent is that retrieval quality matters more than brute-force stuffing.

If you hand an agent an entire warehouse of scrolls, you have not made it wise. You have merely made it late.

That is not a luxury. It is cost control, latency control, and correctness control, all disguised as tidiness.

The Hidden Token Tax: Shell Output

Now let Father Christmas tell you about a villain rarely invited into respectable technical architecture diagrams: the verbose shell command.

This is where RTK enters the scene.

Or, to put it in festive terms: if the reindeer are hauling boilerplate logs, they are not hauling presents.

The Gateway Question: Why LiteLLM Belongs in the Story

The LiteLLM part of this setup deserves a careful, honest explanation.

That honesty matters.

In the Workshop, we do not claim a sleigh can land on a roof it has never tested. We say what is proven, what is practical, and what is ready for future expansion.

LiteLLM still brings real value here because it gives you:

a local AI gateway,
a place for routing and budget control,
support for OpenAI-compatible tools and scripts,
and a staging ground for future direct integration paths.

It is not smoke and mirrors. It is infrastructure with proper manners.

What the Finished Setup Looks Like

After following the repository, the machine ends up with a rather handsome set of capabilities:

Homebrew-installed prerequisites
Python 3.12 for LiteLLM
Node.js for auggie
Auggie CLI installed and ready
Claude Code installed and authenticated
Augment MCP registered inside Claude Code
rtk installed and initialized for Claude Code shell usage
PostgreSQL 17 running locally for the LiteLLM UI backend
LiteLLM Proxy on http://127.0.0.1:4000
LiteLLM admin UI at http://127.0.0.1:4000/ui
verification scripts and example prompts

That is not merely “a bunch of tools installed.” It is a composed operator’s station.

The Architecture, as Father Christmas Would Draw It

Developer
   │
   ▼
Claude Code
   ├── Augment Context Engine MCP  → retrieves relevant code context
   ├── RTK                         → compresses noisy shell output
   └── LiteLLM Proxy               → routes requests, tracks budgets, enables expansion
                                      │
                                      ▼
                                  Model providers / compatible tools

You will notice something familiar here.

The Recommended Order Matters

The repository even has the decency to tell you the correct order in which to approach the setup:

architecture
prerequisites
install Claude Code
install Auggie and the MCP connection
install RTK
install LiteLLM
verification
daily usage
troubleshooting

This is not administrative fussiness. It is Workshop thinking.

Fast Path for the Impatient Elf

For those who cannot resist pulling the ribbon before reading the card, the repository also gives a direct setup path:

cd /path/to/your/workspace
chmod +x scripts/*.sh
./scripts/install_prereqs.sh
./scripts/install_auggie.sh
./scripts/install_rtk.sh
./scripts/setup_litellm.sh

Then you manually complete the sign-ins, register the MCP server, restart Claude Code, and run the verification script.

Even the “fast path” still respects the discipline of verification. That is how you know serious engineers packed this travelling case.

Why This Is a Perfect Episode 9

If Episode 8 showed the ideal, integrated flow of work inside Intent, Episode 9 answers the natural follow-up:

What do the same principles look like when the Workshop goes mobile?

The answer is reassuringly consistent:

preserve semantic retrieval,
reduce irrelevant context,
separate proven paths from aspirational ones,
verify the stack end-to-end,
and make room for future routing sophistication without lying about what is already supported.

That is excellent engineering. Also, I am pleased to report, excellent Christmas engineering.

SIPOC: The Travelling Stack

	S — Suppliers	I — Inputs	P — Process	O — Outputs	C — Customers
Who/What	Developer, Claude Code, Augment MCP, RTK, LiteLLM, local services	Repository, shell commands, MCP registration, local config, verification scripts	Install prerequisites → connect MCP → trim shell output → route through gateway → verify stack	Working token-aware coding environment, lower context waste, future-ready routing setup	Solo developers, engineering teams, cost-conscious operators
Workshop	Father Christmas, travelling Elf, portable library, dispatch desk, tidy stenographer	Tool chest, route map, sleigh rules, checked inventory	Pack the case → bring the right books → shorten the chatter → dispatch the right sleigh → inspect before departure	A reliable travelling workshop that still behaves like the North Pole	Every workshop beyond the snow line

A Final Word from Father Christmas

The true sign of a good Workshop is not that it works only in its own building. It is that its principles survive the journey. Intent taught us to coordinate, retrieve wisely, verify carefully, and keep the plan honest. This external stack shows those same values travelling well: the right agent, the right context, less wasted chatter, and an honest gateway for the road ahead. If you can carry that discipline with you, then you are not merely using clever tools. You are building like the North Pole.

This concludes the Santa Augmentcode Intent series. All nine episodes are available on dev.to under the the-software-s-journey organisation.

Thank you for reading. May your specs be living, your context relevant, and your token bills modest. Ho ho ho! 🎅