DEV Community: Willem van Heemstra

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:

“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.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

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.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! 🎅

Santa Augmentcode Intent Ep.8

Willem van Heemstra — Sun, 19 Apr 2026 19:38:09 +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.

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

Santa Augmentcode Intent Ep.1

Willem van Heemstra — Sun, 19 Apr 2026 19:38:03 +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.

Wizard of Oz Warp 🌪️ Ep.1

Willem van Heemstra — Fri, 17 Apr 2026 13:13:15 +0000

Episode 1: Follow the Yellow Brick Road

"Toto, I've a feeling we're not in Kansas anymore."— Dorothy Gale, The Wizard of Oz (1939)

The Grey Skies of Kansas 🌩️

Kansas is a traditional terminal. It is grey, functional, unchanged since the 1970s in ways that matter. Commands vanish upward in a wall of text. You scroll to find output from thirty seconds ago. The prompt is a single blinking cursor that knows nothing about what you typed last week. An error arrives with no suggestion of how to fix it. You copy-paste from Stack Overflow into a terminal that treats you like a system administrator from 1983.

You are Dorothy. You have been working in this Kansas for years. It works. Everything works. The Ruby slippers are right there on your feet — you just do not know they are magic yet.

Then the tornado arrives. It is called Warp.

🗂️ SIPOC — The Journey Begins

Suppliers	Inputs	Process	Outputs	Customers
Warp installer (DMG)	Your Mac Mini M4 Pro, macOS Sequoia	Download → drag to Applications → launch → authenticate	A modern Agentic Development Environment running natively on Apple Silicon	You — with every future episode's workflow running here
Your project idea	An empty directory	Scaffold warp-of-oz-tasks with uv, FastAPI, Python 3.12	A running health endpoint at http://localhost:8000/health	The series codebase that grows across all 8 episodes
Warp's block system	Every command you run	Group command + output into a navigable atomic Block	A terminal session you can navigate, copy, search, and share	Your future self — no more scrolling through output walls

The Land of Oz: What Warp Actually Is 🏙️

Warp is not a terminal emulator with an AI bolt-on. It is an Agentic Development Environment — a rethinking of what the terminal can be when you assume the developer also has access to a large language model, a cloud orchestration platform, and a team knowledge base.

It has two parts:

Warp Terminal — the application you download and run on your Mac. Built in Rust for performance. It supports zsh, bash, fish, and PowerShell. It adds blocks, a code-editor-quality input experience, AI features, a file editor, code review, and the ability to run local agents interactively.

Oz — the orchestration platform that lives at oz.warp.dev. Cloud agents that run in the background, triggered by Slack messages, GitHub PRs, Linear issues, or schedules. Oz is the Emerald City — not visible from Dorothy's first view of the munchkin country, but always glowing on the horizon.

This episode is about arriving. The tornado. The yellow bricks. The first steps.

Step 1: Install Warp on the Mac Mini M4 Pro 💻

# Option 1: Direct download from warp.dev
# Download Warp.dmg → drag to /Applications → launch

# Option 2: Homebrew (recommended — keeps it updated)
brew install --cask warp

Warp runs natively on Apple Silicon — no Rosetta translation. The Mac Mini M4 Pro (24 GB unified memory, 12-core CPU) is an excellent host: Warp launches in under a second and local agent inference runs without thermal throttling.

After first launch, Warp asks you to sign in. A free account unlocks AI features with generous limits. Sign in with GitHub or email.

Verifying the install

# Warp will already be your terminal — just confirm it loaded zsh correctly
echo $SHELL
# /bin/zsh

# Confirm macOS version
sw_vers
# ProductName:    macOS
# ProductVersion: 15.x.x (Sequoia)
# BuildVersion:   ...

# Confirm architecture
uname -m
# arm64   ← Apple Silicon, not x86_64

The First Blocks: The Munchkins Welcome You 🌈

The first thing you notice in Warp is that command output is not a river — it is Blocks.

Every command and its output form a single, self-contained unit. The block has a border. You can click anywhere in it to select it. You can navigate between blocks with Ctrl-Up and Ctrl-Down. You can copy just the output, just the command, or both — with formatting preserved.

Try it:

# Run a command
ls -la ~

# Click somewhere else, then press Ctrl-Up
# You land on the ls -la ~ block, not anywhere in the sea of text

# Press Cmd-C on a block to copy just the output
# Press Shift-Cmd-C to copy "command + output" — useful for sharing

# Type: ls -la ~/Des
# Warp auto-completes the path. Press Tab. It works.

This is the yellow brick road. Every step is paved.

Setting Up the Series Project: `warp-of-oz-tasks` 🏗️

Throughout this series, we build a single Python FastAPI application — a task management API — that grows from a bare scaffold to a production-grade service with authentication, background processing, and cloud agent automation. Every feature is added in Warp, using Warp's tools, on the Mac Mini M4 Pro.

Install `uv` (Python package manager)

uv is a Rust-based Python package manager from Astral. Massively faster than pip. Perfect pairing with Warp on Apple Silicon.

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Add to PATH (uv installer does this, but verify)
source ~/.zshrc
which uv
# /Users/you/.cargo/bin/uv (or ~/.local/bin/uv)

uv --version
# uv 0.x.x

Scaffold the project

# Create the project directory
mkdir -p ~/projects/warp-of-oz-tasks
cd ~/projects/warp-of-oz-tasks

# Initialise with uv
uv init --name warp-of-oz-tasks --python 3.12

# The project structure uv creates:
# warp-of-oz-tasks/
# ├── .python-version    ← pins Python version
# ├── pyproject.toml     ← project metadata and dependencies
# ├── README.md
# └── hello.py           ← placeholder (we'll replace this)

# Add FastAPI and uvicorn
uv add fastapi "uvicorn[standard]"

# Confirm
cat pyproject.toml

Write the first source file

# Remove the placeholder
rm hello.py

# Create the application entry point
cat > src/main.py << 'PYTHON'
"""
warp-of-oz-tasks: A FastAPI task management API.
Built across 8 episodes of the Warp of Oz series on a Mac Mini M4 Pro.
"""
from fastapi import FastAPI
from datetime import datetime

app = FastAPI(
    title="Warp of Oz Tasks",
    description="Follow the yellow brick road — one endpoint at a time.",
    version="0.1.0",
)

@app.get("/health")
async def health_check():
    """The Munchkins confirm you have arrived safely."""
    return {
        "status": "alive",
        "message": "Toto, I've a feeling we're not in Kansas anymore.",
        "timestamp": datetime.utcnow().isoformat(),
    }
PYTHON

# uv expects src layout — create the package
mkdir -p src
touch src/__init__.py

Wait — let's check the pyproject.toml and fix the source layout:

# Update pyproject.toml to reflect src layout
cat > pyproject.toml << 'TOML'
[project]
name = "warp-of-oz-tasks"
version = "0.1.0"
description = "A FastAPI task API — built with Warp, episode by episode."
requires-python = ">=3.12"
dependencies = [
    "fastapi>=0.115.0",
    "uvicorn[standard]>=0.30.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["src"]
TOML

Run the first server

# Run with uv run (handles the venv automatically)
uv run uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

Open another Warp tab (Cmd-T) and test:

curl http://localhost:8000/health | python3 -m json.tool
# {
#     "status": "alive",
#     "message": "Toto, I've a feeling we're not in Kansas anymore.",
#     "timestamp": "2026-04-17T..."
# }

The yellow brick road is paved. The first block sparkles.

The Warp Input Editor: Cursor Movement in the Terminal 🖊️

Traditional terminals treat the input line like a 1970s text field. Warp treats it like a code editor:

# Multi-line input — press Shift-Enter for new lines
# The entire block becomes a multi-line script
python3 -c "
import sys
print(f'Python {sys.version}')
print('Running on Apple Silicon' if 'arm64' in sys.platform else 'Not ARM')
"

# Alt-click to place the cursor exactly where you want
# Cmd-Z to undo a character you deleted in the input
# Select text with Shift-Arrow and delete it

# This works like VS Code. Because Warp is built to.

The `#` Key: Your First Taste of Magic ✨

Type # in Warp's input and start describing what you want in plain English:

# show me all python processes running on this machine

Warp converts this to:

ps aux | grep python

This is not AI autocomplete. This is natural language to shell command translation. Try more:

# find all files larger than 100MB in my home directory
# show disk usage for the current directory sorted by size
# what port is uvicorn running on

The Scarecrow is acquiring a brain. But that is Episode 2.

The Project Structure So Far 📁

~/projects/warp-of-oz-tasks/
├── .python-version         ← Python 3.12
├── pyproject.toml          ← dependencies and metadata
├── README.md
└── src/
    ├── __init__.py
    └── main.py             ← health endpoint ✓

Commit this starting point:

cd ~/projects/warp-of-oz-tasks
git init
git add .
git commit -m "feat: scaffold warp-of-oz-tasks — the tornado has landed"

The Series Map: Eight Episodes 🗺️

#	Episode	Oz parallel	Warp feature	Codebase milestone
1	This one — Yellow Brick Road	Dorothy arrives	Blocks, input editor, # key	Health endpoint
2	The Scarecrow Gets a Brain	Scarecrow + brain	AI completions, Active AI, agent chat	CRUD endpoints for tasks
3	The Tin Man Gets a Heart	Tin Man + heart	WARP.md, Rules, Skills	Auth middleware
4	The Lion Gets Courage	Cowardly Lion	Agent pair mode, code review panel	Debug a planted error
5	Flying Monkeys: Dispatch	Flying monkeys	Autonomous dispatch mode	Background task processor
6	The Emerald City: Oz	Emerald City	Cloud agents, Oz CLI, schedules	Scheduled cleanup agent
7	The Ruby Slippers: Augment	Ruby slippers	Augment Code Intent + Warp	Spec-driven feature
8	There's No Place Like Home	Going home	MCP, Warp Drive, full workflow	Production-ready service

In Episode 2, the Scarecrow joins the road. He needs a brain. Warp's AI features are exactly that.

🔗 Resources

Warp download: warp.dev
Warp documentation: docs.warp.dev
Oz platform: oz.warp.dev
uv (Python package manager): docs.astral.sh/uv
FastAPI: fastapi.tiangolo.com

🌪️ Warp of Oz Series follows the Yellow Brick Road through Warp's Agentic Development Environment — from the first install on a Mac Mini M4 Pro to cloud agent orchestration with Oz, with Augment Code Intent as the ruby slippers that were powerful all along.

Magic Lamp Ep.1

Willem van Heemstra — Fri, 17 Apr 2026 12:33:42 +0000

"You'll like it — not a lot, but you'll like it."
— Paul Daniels

Paul Daniels never actually made things appear from nowhere. The secret to his act was subtler: he made you see life in the lifeless. A silk handkerchief folded just so. A coin that hesitated before vanishing. The magic wasn't in the props — it was in the relationship between performer and object. The audience believed because the performer believed first.

This is a project that works the same way.

🎭 The Performance

PIXSTARS is a 20-minute silent theatrical piece for a live event. The setup is deliberately sparse:

One performer on stage
One animatronic desk lamp named Pinokio
A live piano
A deconstructed rendering of Guns N' Roses' November Rain
No dialogue. Not a single word.

The lamp is not a prop. It is a co-performer. It has 14 distinct personality states — from INERT to ARROGANT to DYING to REBORN — and moves through them on choreographed cues as the music plays. The performer holds three simultaneous character identities (Rockstar, Creator, Witness). The lamp holds the mirror.

Think Kim Ki-duk, not Cirque du Soleil. Sparse. Patient. Emotionally loaded.

🪄 The Paul Daniels Problem

When Paul Daniels placed a lifeless prop on his table, it was just an object. The moment he began working with it — tilting, pausing, reacting — it became a character. The prop hadn't changed. The frame around it had.

Building Pinokio means solving the same problem in code: how do you cross the line from object that moves to character that lives?

The answer, it turns out, is architecture.

A lamp that moves on command is a prop. A lamp that has emotional states, reacts to music, speaks with its body, and wakes up on cue — that's a character. The difference is not hardware. It's the layer of abstraction between the mechanical and the theatrical.

This series documents exactly how that abstraction is built.

🏗️ The Stack

Before we get into code, here is the complete hardware and software picture.

Hardware:

Component	Role
Mac Mini M4 Pro	Show control host, runs everything
Pololu Mini Maestro 24-ch USB servo controller	Lamp motion brain
4x MG996R servos	Large articulation: base, shoulder, elbow, head tilt
2x MG90S servos	Fine motion
MEAN WELL LRS-50-5 PSU	5V servo rail, isolated from logic
Arduino Nano	NeoPixel serial bridge (the Maestro doesn't speak NeoPixel)
NeoPixel RGBW ring	Lamp head LED indicator
Logitech C920 webcam	Mounted near lamp — gaze source or projection input
Raspberry Pi Zero 2 WH	Satellite node: mic, speaker, LED — no soldering required
Enttec DMX USB Pro	Stage lighting control

Software subsystems (all on the Mac Mini):

┌─────────────────────────────────────────────────────┐
│                   SHOW CONDUCTOR                    │
│           conductor/main.py  (YAML timeline)        │
└────────┬──────────┬──────────┬──────────┬───────────┘
         │ OSC      │ OSC      │ OSC      │ OSC
         ▼          ▼          ▼          ▼
    Port 3819   Port 9001   Port 9002   Port 9003
    ┌───────┐  ┌────────┐  ┌──────────┐  ┌─────────┐
    │Ardour │  │  Lamp  │  │Projection│  │Lighting │
    │  DAW  │  │adapter │  │(pygame)  │  │  (DMX)  │
    └───────┘  └────────┘  └──────────┘  └─────────┘
                                  all mirrored to
                              Port 9004 / WS 8765
                         ┌──────────────────────┐
                         │    Digital Twin      │
                         │  (BabylonJS + Deno)  │
                         └──────────────────────┘

Every subsystem speaks OSC (Open Sound Control) over UDP on localhost. The conductor doesn't know or care whether the lamp adapter talks to real servos or a simulator — it just sends /lamp/state CURIOUS and moves on.

That decoupling is the key architectural decision. More on that in episode 2.

🎛️ OSC: The Nervous System

OSC is the protocol that holds the show together. It's a UDP-based message format originally designed for musical instruments and live sound, which makes it a natural fit for real-time stage control. Messages look like:

/lamp/state        CURIOUS
/projection/scene  DISNEY_CASTLE
/lighting/state    DISNEY_SOFT
/toggle_roll       (Ardour play/stop)

Each subsystem listens on its own port. The conductor dispatches all messages for a single cue within the same 50ms polling tick. The result is near-simultaneous state transitions across audio, video, light, and motion.

The complete port map:

# conductor/config.py
ARDOUR_OSC_PORT     = 3819   # Ardour 9 control surface
LAMP_OSC_PORT       = 9001   # Lamp personality adapter
PROJECTION_OSC_PORT = 9002   # Pygame display
LIGHTING_OSC_PORT   = 9003   # Enttec DMX USB Pro
TWIN_OSC_PORT       = 9004   # Digital Twin OSC bridge
TWIN_WS_PORT        = 8765   # Digital Twin WebSocket (browser)

⏱️ The Timeline: 15 Cues, 9 Minutes 15 Seconds

The entire show lives in a single YAML file. Here's a slice:

# conductor/timeline.yaml (excerpt)
cues:
  - time: 0.0
    name: SHOW_START
    lamp: INERT
    projection: BLACKOUT
    lighting: BLACKOUT
    ardour: {command: transport_play}

  - time: 60.0
    name: DRUMS_BEGIN
    lamp: CURIOUS

  - time: 340.0
    name: OVERHEATING
    lamp: OVERHEATING
    lighting: OVERHEAT

  - time: 380.0
    name: LAMP_DEATH
    lamp: DYING
    lighting: DEATH

  - time: 460.0
    name: REVEAL_AI
    lamp: WEAK
    projection: AI_SIGNATURE
    lighting: REBIRTH

At second 0, the lamp is INERT and Ardour begins playing. By second 60, the drums enter and the lamp becomes CURIOUS. By second 380, it is DYING. The arc from object to character to death to rebirth — all scripted, all precise, all driven by this YAML.

Paul Daniels rehearsed his timing with a stopwatch. So does Pinokio.

🔮 What's Coming in This Series

Episode	Topic
1 (this one)	Architecture overview — the magic prop metaphor
2	The Show Conductor — OSC dispatching and timeline execution
3	14 Personalities in a Lampshade — servo states and motion vocabulary
4	Light the Stage — DMX control, pygame projection, and the digital twin
5	Finding Its Voice — HiveMind, Coqui XTTS, and the Raspberry Pi satellite

By the end of episode 5, Pinokio will have gone from a desk lamp on a table to a character capable of reacting to music, shifting emotional states on cue, speaking in a synthesised voice, and lighting up its own head in synchrony with its mood — all orchestrated from a single Python process on a Mac Mini.

Not a lot. But you'll like it.

Next: Episode 2 — The Show Conductor: how 15 YAML cues orchestrate five subsystems in real time.

Air Traffic Control Scaleway Ep.1

Willem van Heemstra — Fri, 17 Apr 2026 10:09:31 +0000

Cleared for Approach: Identity and Access Management on Scaleway

“F-A-B, Mr. Tracy. All runways are cleared. But before any aircraft lifts off, we must know exactly who is behind the controls — and precisely what they are cleared to do.”— International Rescue, Thunderbird 5 Orbital Station

Welcome to the Scaleway Air Traffic Control Centre — your operations hub in the French cloud.

In this series, we run our infrastructure the way International Rescue manages its missions: with discipline, precision, and absolute clarity about who is authorised to do what. In a busy airport, you do not simply wave aircraft onto the runway. Every pilot has a licence. Every aircraft has a flight plan. Every gate has a crew with specific clearances.

Identity and Access Management (IAM) on Scaleway works on precisely this principle.

Think of your Scaleway Organisation as Thunderbird Island itself — the central command. Your Projects are the individual Thunderbird vehicles: Dev is Thunderbird 1 (fast, agile, first on the scene), Production is Thunderbird 2 (heavy lifting, critical cargo), and Test is Thunderbird 3 (probing unmapped territory). Each requires its own flight crew, its own access codes, and its own launch protocols.

By the end of this episode, you will have configured the entire clearance architecture: SSH keys, collaborators, groups, applications, policies, and an API key — all locked down in a manner that would satisfy even the most zealous International Rescue security review.

🎯 Mission Parameters

In this hands-on episode, you will learn how to:

Set up multiple Projects within a Scaleway Organisation
Access the IAM section of the Scaleway Console
Create member accounts and invite collaborators to your Organisation
Navigate between Organisations as a guest member
Create a Group and assign members to it
Create Applications for non-human (programmatic) principals
Define Policies with scoped permission sets for different principals
Attach an existing Policy to an Application
Generate an API key with a controlled expiry window
Authenticate a live Scaleway API request using a secret key

Pre-Launch Checklist

Before Scott Tracy can take Thunderbird 1 to maximum velocity, ground crew run their checks. Do the same:

✅ You hold an active Scaleway account and own an Organisation
✅ Two teammates are available — they will serve as co-pilots, each assigned a different clearance level

📊 SIPOC — How IAM Moves Through the System

Before we touch the Console, let us map the process. IAM is not a single action — it is a pipeline. The SIPOC model (Supplier → Input → Process → Output → Consumer) reveals exactly how identity and access flow through your Scaleway Organisation.

Stage	SIPOC Element	IAM Equivalent	Example
S	Supplier	Scaleway IAM engine + your Organisation Owner account	The platform and the human who configures it
I	Input	Member definitions, Group memberships, Application names, Policy rules	“User: teammate-1, Group: Developers, Scope: Dev project, Permission: FullAccess”
P	Process	Creating Projects → Onboarding members → Defining Groups → Writing Policies → Issuing API keys	All the hands-on steps in this episode
O	Output	A working IAM architecture: scoped permissions enforced across all projects	Teammate 1 can create Instances in Dev. Teammate 2 can create Instances in Production. Applications hold API keys.
C	Consumer	Developers, CI/CD pipelines, automation scripts, and applications that interact with Scaleway resources	Your team, app-1, app-2, and your own curl commands

Supplier              Input                Process               Output               Consumer
─────────             ─────────            ─────────             ─────────            ─────────
Scaleway IAM   ──▶   Members         ──▶  Create Projects  ──▶  Scoped        ──▶   Developers
engine               Groups               Onboard users         policies              CI/CD
                     Applications         Define groups         enforced              pipelines
Organisation         Policy rules         Write policies        across all            Applications
Owner account        SSH keys             Issue API keys        projects              (app-1, app-2)

Tower to crew: The SIPOC view tells us something important — IAM is only as good as the inputs you provide. Vague policy rules produce vague clearances. Garbage in, unrestricted access out. Thunderbird Island does not operate on vague.

🛫 Section 1 — Establishing the Flight Zones: Set Up Projects

Every International Rescue operation begins with a clear separation of zones. We mirror this discipline with three Scaleway Projects.

1.1 — Create Three Projects

In the Organisation Dashboard menu, select the Projects tab.
Click Create Project and enter Dev as the Project Name.
Repeat to create a project named Production.
Repeat once more for a project named Test.

1.2 — Generate Three SSH Keys — One Per Zone

An SSH key is your pilot’s licence. Each zone gets its own key; cross-zone entry is not permitted. Open your terminal:

# Generate Ed25519 keys, AES-256-GCM encrypted, no passphrase
ssh-keygen -t ed25519 -C "login" -Z aes256-gcm@openssh.com \
           -f handson-iam-dev.pub -N ""

ssh-keygen -t ed25519 -C "login" -Z aes256-gcm@openssh.com \
           -f handson-iam-production.pub -N ""

ssh-keygen -t ed25519 -C "login" -Z aes256-gcm@openssh.com \
           -f handson-iam-test.pub -N ""

Why Ed25519? It is modern, compact, and resistant to the brute-force attacks that might trouble a less security-conscious organisation. The -Z aes256-gcm@openssh.com flag encrypts the private key file at rest. International Rescue keeps its launch codes safe.

1.3 — Register SSH Keys to Each Project

Repeat this procedure for Dev, Test, and Production — using the corresponding key file each time.

Run cat handson-iam-dev.pub in your terminal to display the public key.
Copy the key. It begins with ssh-ed25519.
In the Organisation Dashboard, click the Dev project, then select the SSH keys tab.
Click Add SSH key. Enter a name such as Hands on IAM dev and paste the public key.
Click Add SSH key to confirm.
Repeat for Test and Production using their respective key files.

🧑‍✈️ Section 2 — Crew Manifest: Adding Collaborators

No mission launches with anonymous personnel aboard. We now bring our two teammates into the Organisation — each with their own identity and password, ready to receive specific clearances.

In the Management & Governance drop-down, select IAM.
Select the Users tab, then click Create member.
For each teammate: enter their username, select Send password by email, then add their email and personal information. Leave Assign member to group empty for now. Click Create member.
Ask each teammate to check their inbox and log in to your Organisation.
Repeat for the second teammate.

Note: Once logged in, teammates can reach your Organisation via the Organisation drop-down → + Add Organisation. They will see the projects you created — but, with no policy assigned yet, they cannot touch anything. Clearance is coming. Patience, as Brains would say.

🏗️ Section 3 — Clearance Architecture: Groups, Applications & Policies

With the crew aboard, we build the clearance architecture — the system that determines who may access which runway, and with what authority.

Think of it this way:

A Group is a flight crew qualification — all pilots in the group share the same category of clearance.
A Policy is the air traffic control instruction that says precisely which zones that clearance covers.
An Application is an unmanned probe — a programmatic identity with its own flight plan.

3.1 — Create the Developers Group

In IAM, select the Groups tab. Click Create group.
Enter Developers as the Name. Leave Tags empty.
Click Add a member and add your first teammate.
Confirm with Create group.

3.2 — Deploy Unmanned Probes: Create Applications

Thunderbird 3 can fly to Space Station Alpha without a human crew. Our Applications are the cloud equivalent — automated systems that need identities and permissions, but no login.

In IAM, select the Applications tab. Click Create application.
Name it app-1. Leave Tags and Policy empty. Confirm.
Repeat to create a second application named app-2.

3.3 — Issue Flight Plans: Create Policies & Configure Rules

Three principals. Three policies. Each one a precisely scoped flight authorisation.

Navigate to IAM → Policies → Create policy for each of the following.

Policy A — Developers Group

Field	Value
Name	Hands on IAM developers
Principal	Group → Developers
Rule 1 — Scope	Access to resources → Dev project
Rule 1 — Permissions	AllProducts → AllProductsFullAccess
Rule 2 — Scope	Access to resources → All current and future projects
Rule 2 — Permissions	AllProducts → AllProductsReadOnly

Work through the policy wizard in order: set ① Scope and validate; set ② Permission sets and validate; leave ③ CEL conditions empty; add a second rule via Add rule and repeat. Finalise with Create policy.

Tower confirms: Teammate 1 now has full command over the Dev zone and read-only visibility everywhere else. Ask them to attempt launching an Instance in both Dev and Production. Dev succeeds; Production refuses. Exactly as the clearance system intends.

Policy B — Individual User

Field	Value
Name	Hands on IAM User
Principal	User → Teammate 2
Rule 1 — Scope	Access to resources → Production project
Rule 1 — Permissions	Compute → InstancesFullAccess

Tower confirms: Teammate 2 has been given the Production runway — specifically for compute resources. They can create and manage Instances there, and nowhere else.

Policy C — Application Principal

Field	Value
Name	app-policy
Principal	Application → app-1
Rule 1 — Scope	Access to resources → Test project
Rule 1 — Permissions	AllProducts → AllProductsFullAccess

3.4 — Transfer Flight Plan: Attach Policy to app-2

app-2 currently has no clearance — it sits idle on the apron. Rather than writing a new policy, we duplicate the existing app-policy.

In IAM → Applications, click app-2, then open the Groups & Policies tab.
In the Policies section, click Attach a policy.
Select Duplicate an existing policy, then choose app-policy. Confirm.

🗺️ IAM Architecture — The Clearance Map

Your Organisation’s IAM implementation should now match the following layout:

┌────────────────────────────────────────────────────────────────┐
│                     ORGANISATION                               │
│                                                                │
│  PRINCIPALS             POLICIES              PROJECTS         │
│  ──────────────         ─────────────         ───────────      │
│                                                                │
│  Developers  ──────▶  IAM developers ──▶  Dev (Full)          │
│  Group                                ──▶  All (Read-Only)    │
│  (Teammate 1)                                                  │
│                                                                │
│  Teammate 2  ──────▶  IAM User       ──▶  Production          │
│  (IAM user)                               (InstancesFullAccess)│
│                                                                │
│  app-1       ──────▶  app-policy     ──▶  Test (Full)         │
│                                                                │
│  app-2       ──────▶  app-policy     ──▶  Test (Full)         │
│               (duplicated)                                     │
└────────────────────────────────────────────────────────────────┘

🔑 Section 4 — The Master Override: API Keys

Every control tower has a master key — used sparingly, stored securely, and never left on the desk. In Scaleway, the API key is that master key. It allows you to issue commands to the platform programmatically, bypassing the Console entirely.

4.1 — Generate an API Key

In IAM, select the API keys tab. Click Generate API key.
Select Myself (IAM user) as the bearer.
Leave Description empty. Set Expiration to 1 hour.
Select No for Object Storage usage.
Copy and securely store the Secret Key displayed. It will not be shown again.

⚠️ Security Protocol — Restricted: A Secret Key is sensitive data of the highest classification. Never commit it to a repository, paste it into a chat message, or leave it in a shell history file. The Organisation Owner’s API key inherits full permissions — treat it accordingly. International Rescue does not negotiate with those who mishandle launch codes.

Note: When an Organisation Owner generates an API key for themselves, the key carries all permissions, since the Owner holds all permissions.

4.2 — Rename a Project via the Scaleway API

We will demonstrate the API key by renaming the Test project to updated_test — without touching the Console. A single curl command, precisely aimed.

In the Project header drop-down, select Test, then click Copy ID next to the project name to copy its UUID.
Open a terminal and run the following command, substituting your actual secret key and project ID:

curl -X PATCH \
  -H "X-Auth-Token: <your_secret_key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "updated_test"}' \
  "https://api.scaleway.com/account/v3/projects/<test_project_id>"

Refresh your browser. The Test project is now named updated_test.

Note: Take care with invisible whitespace when copying keys and IDs from the Console — a single hidden character produces a 401 Unauthorised response, and even the most experienced tower controller will spend a frustrating few minutes debugging. You have been warned by someone who has been there.

🚀 Section 5 — Advanced Flight Options

You have now proven your ability at the controls. But International Rescue never stops improving its equipment. The API key you generated can power far more than a single curl call. Two recommended flight paths once you have your bearings:

Scaleway CLI

The Scaleway CLI gives you full IAM control from the terminal. Install it and try:

# List all IAM policies in your organisation
scw iam policy list

# Describe a specific policy by ID
scw iam policy get policy-id=<your-policy-id>

# List all IAM users
scw iam user list

Terraform Provider

The Scaleway Terraform provider lets you manage IAM as infrastructure-as-code. A minimal API key resource looks like this:

resource "scaleway_iam_application" "app_ci" {
  name        = "app-ci-pipeline"
  description = "Programmatic identity for CI/CD pipeline"
}

resource "scaleway_iam_api_key" "app_ci_key" {
  application_id = scaleway_iam_application.app_ci.id
  description    = "CI pipeline key — rotated monthly"
  expires_at     = "2026-04-01T00:00:00Z"
}

The Terraform approach is strongly recommended for any IAM configuration that will persist beyond a lab environment. Infrastructure-as-code means your clearance architecture is version-controlled, peer-reviewed, and reproducible — three qualities that Jeff Tracy demands of every Thunderbird system.

📋 Episode Debrief

“All systems nominal. Clearances verified. The runway is yours — and only yours. Thunderbirds are GO.”— Jeff Tracy, Thunderbird Island Operations Centre

In this episode, you have:

✅ Created three Projects — Dev, Production, Test — each with its own SSH key
✅ Onboarded two collaborators as Organisation members
✅ Established a Developers Group for shared clearance management
✅ Registered two Applications as non-human principals (app-1, app-2)
✅ Defined three Policies with scoped permission sets across group, user, and application principals
✅ Duplicated an existing Policy and attached it to app-2
✅ Generated an API key with a one-hour expiry window
✅ Executed a live Scaleway API call via curl to rename a project
✅ Mapped the full process through the SIPOC model

The clearance architecture is in place. In the next episode, we will spin up our first compute resources inside these carefully guarded zones — and the IAM rules we built today will be the first thing that greets them.

📡 Further Transmissions

Scaleway IAM documentation
Scaleway CLI — IAM command reference
Terraform Provider — scaleway_iam_api_key
Scaleway API — Update Project endpoint

Estimated reading time: 12 minutes. Estimated hands-on time: 45–60 minutes with teammates.

This series is part of the *the-software-s-journey** publication on DEV.to — cloud infrastructure explained through the metaphors that make it stick.*

Game on Djangular 🎮 Ep.1

Willem van Heemstra — Thu, 16 Apr 2026 13:33:21 +0000

Episode 1: Welcome to the Vault

“Every gamer has a backlog. The good ones have a system.”

The Backlog Problem 🎯

Every gamer knows the feeling. Forty-three games in your library. You can only name eight of them from memory. Three are half-finished from two years ago. You started one last week but cannot remember whether the save file is on the laptop or the desktop. Someone on Reddit just posted that a game you bought on sale is “not worth it past hour 12” and you are on hour 11.

You need a Vault.

GameLib is that vault: a full-stack web application where gamers manage their personal libraries, track progress, discover new titles, and share reviews. Built for a Web Development course at KBTU, it is a working example of the Djangular stack — Django REST Framework on the backend, Angular on the frontend, PostgreSQL as the game database, and JWT tokens as the keys to your personal collection.

This series builds GameLib from the ground up and extends it into enterprise territory: XML file exchange with external Linux servers, TLS and mutual TLS certificate management, SailPoint IAM for identity verification, and a full PKI infrastructure managed by django-ca.

🗂️ SIPOC — The Vault

Suppliers	Inputs	Process	Outputs	Customers
Gamers (registered users)	Game titles, play status, ratings, reviews	Angular frontend → DRF API → PostgreSQL	A personal vault: tracked games, statuses, scores, reviews	The gamer — with a searchable, filterable record of their entire library
The global game catalogue	Game metadata: title, genre, description, cover image	Django admin / seed scripts → Game model	A browsable catalogue of all games the system knows about	All users — browsing before adding to their vault
External Linux server (Episodes 5–8)	XML files containing game catalogue updates or vault exports	Django backend ↔ Linux server via HTTP/HTTPS/mTLS	Synchronised data; audit trail; identity-verified exchange	Enterprise operators, partner systems, compliance teams

The Gamer Metaphor: Your Stack as Your Library 🗂️

The metaphor is exact, not decorative.

Game library world	Djangular stack
Your game Vault (personal collection)	PostgreSQL + Django `UserGame` model
The global catalogue you browse	DRF read-only `Game` and `Genre` endpoints
Adding a game to your Vault	Authenticated POST to `UserGame` API
Your status badge (Playing/Finished/Planned)	`status` field — string enum on `UserGame`
Your review and score out of ten	`Review` model — one per user per game
Genre filter on the shelf	`django-filter` + DRF `FilterBackend`
Your login / session token	JWT via `djangorestframework-simplejwt`
Angular loading your shelf on login	`HttpClient` → DRF API → component binding
Exporting saves to a remote server	Django `requests.post()` with XML payload
Encrypting the connection to the server	TLS — self-signed cert, `verify=ca.crt`
Both sides proving who they are	mTLS — mutual certificate handshake
The key factory that issues all certs	PKI — Root CA + Intermediate CA
The guild’s member identity check	SailPoint IAM — verifying server requester
A banned player’s membership card	Revoked certificate — CRL or OCSP

The Project Structure 🗂️

Based on the GameLib repository at github.com/software-journey/djangular:

djangular/
├── backend/                    ← Django project
│   ├── manage.py
│   ├── gamelib/                ← Django settings/urls/wsgi
│   │   ├── settings.py
│   │   ├── urls.py
│   │   └── wsgi.py
│   ├── games/                  ← Django app: catalogue
│   │   ├── models.py           ← Game, Genre
│   │   ├── serializers.py
│   │   ├── views.py
│   │   └── urls.py
│   ├── vault/                  ← Django app: personal library
│   │   ├── models.py           ← UserGame, Review
│   │   ├── serializers.py
│   │   ├── views.py
│   │   └── urls.py
│   ├── users/                  ← Django app: auth
│   │   ├── models.py           ← Custom User
│   │   ├── serializers.py
│   │   └── views.py
│   ├── xml_bridge/             ← Django app: XML exchange (Ep.5–7)
│   │   ├── client.py           ← HTTP/HTTPS/mTLS requests
│   │   ├── serializers.py      ← lxml XML serialisation
│   │   └── views.py
│   └── requirements.txt
│
└── frontend/gamelib/           ← Angular project
    ├── src/
    │   ├── app/
    │   │   ├── core/           ← AuthService, JwtInterceptor, Guards
    │   │   ├── features/
    │   │   │   ├── catalogue/  ← Browse games, genre filter
    │   │   │   ├── vault/      ← Your library, status, reviews
    │   │   │   └── auth/       ← Login, register
    │   │   └── shared/         ← Components, pipes, models
    │   └── environments/
    └── angular.json

The Series Map: Nine Episodes 🗺️

#	Episode	Gamer concept	Technical concept
1	This one — Welcome to the Vault	The backlog problem	Architecture overview
2	Building the Game Catalogue	Designing the Vault	Django models, DRF serializers, viewsets
3	Your Login Token	The guild membership card	JWT auth, simplejwt, Angular interceptor
4	Loading Your Shelf	The front of the Vault	Angular components, services, routing
5	Save Data Over the Wire	Syncing to a remote server	XML POST/GET to Linux server, HTTP toggle
6	Encrypting the Channel	Locking the save file	TLS, self-signed certs, `requests` verify
7	Both Sides of the Lock	Proving who you are	mTLS, client cert generation, full handshake
8	The Guild Registry	The guildmaster’s identity check	SailPoint IAM, SCIM 2.0, access verification
9	The Key Factory	Where all locks are made	PKI management, `django-ca`, CRL, OCSP, rotation

Technology Stack Cheat Sheet 📋

Backend:

Python 3.12+
Django 5.x + Django REST Framework 3.15+
djangorestframework-simplejwt — JWT auth
django-filter — queryset filtering
django-cors-headers — CORS for Angular dev server
psycopg2-binary — PostgreSQL adapter
requests — HTTP client for XML exchange
lxml — XML serialisation / deserialisation
cryptography / OpenSSL — TLS / mTLS cert handling
django-ca — PKI certificate authority management

Frontend:

Angular 17+ with standalone components
TypeScript 5+
Angular HttpClient + HttpInterceptor
Angular Router with route guards
RxJS for reactive state
Angular Material (optional) or TailwindCSS

Database: PostgreSQL 16+

External Linux server: Nginx (TLS termination) + custom XML endpoint

IAM: SailPoint IdentityIQ or IdentityNow (SCIM 2.0 API)

Quick-Start: Running GameLib Locally 🚀

# Clone the repo
git clone https://github.com/Elsa-Yanke/web-dev-project-2026.git
cd web-dev-project-2026

# Backend setup
cd backend
python -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\activate
pip install -r requirements.txt

# Create PostgreSQL database
createdb gamelib_db               # or use pgAdmin

# Configure environment
cp .env.example .env              # fill in DB credentials, SECRET_KEY
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver

# Frontend setup (new terminal)
cd ../frontend/gamelib
npm install
ng serve                          # http://localhost:4200

In Episode 2, we open the database and build the models: Game, Genre, UserGame, Review. The Vault takes shape.

🔗 Resources

GameLib repository: github.com/software-journey/djangular
Django REST Framework: django-rest-framework.org
Angular: angular.dev
djangorestframework-simplejwt: django-rest-framework-simplejwt.readthedocs.io

🎮 Game on Djangular Series is a series about building GameLib — a full-stack game library tracker — with Django REST Framework and Angular, extended with XML exchange, TLS/mTLS, SailPoint IAM, and PKI management.

Santa Augmentcode Intent Ep.8

Willem van Heemstra — Mon, 13 Apr 2026 20:40:38 +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.

A Final Word from Father Christmas

I have been doing this for over a thousand years. Every century, the tools improve. The quill gave way to the telegraph, the telegraph to the computer, and now the computer gives way to the agent. But the fundamental challenge has never changed: how do you coordinate complex, parallel work towards a shared goal, on an unmovable deadline, without chaos?The answer, in 1025 and in 2025, is the same: a clear plan, a good team, and the discipline to keep the plan honest.Augment Intent is the first software I have encountered that truly understands this. It puts the plan first. It keeps the plan honest. It coordinates the team without the Elves colliding. And it finishes on time.I am proud of everything we have built in this Workshop. I hope you will build something wonderful in yours.Merry Christmas, and Happy Coding.Ho ho ho! 🎅

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

Thank you for reading. May your specs be living and your merges be clean.

Santa Augmentcode Intent Ep.6

Willem van Heemstra — Mon, 13 Apr 2026 20:40:32 +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.

Luxo Jr. ThingsBoard 🎬 Ep.1

Willem van Heemstra — Mon, 13 Apr 2026 20:40:13 +0000

Episode 1: The Prop That Came Alive

“The question is not whether a lamp can have a personality. The question is whether you are willing to do the work to give it one.”
— paraphrasing John Lasseter, very liberally

A Desk Lamp That Changed Everything 💡

In 1986, John Lasseter had a real Luxo brand desk lamp on his drawing table. He had been using it as a rendering model — studying how light fell on its surfaces, how its joints articulated. It was a prop. An inert object. A piece of hardware.

Then he gave it joints. He gave it movement. He gave it reaction — a curious tilt of the head when the ball rolled by, a deflated slump when the ball burst, an instant excited pivot when something bigger and bouncier appeared. He gave it a story.

Within two minutes of film, the audience at SIGGRAPH 1986 was on its feet screaming. Not because the lamp was technically impressive — though it was. Because they had forgotten it was a lamp. It had become, impossibly, something alive.

This is the precise ambition of the IoT platform ThingsBoard: to take your physical hardware — sensors, actuators, meters, controllers — and give them the equivalent of Lasseter’s joints. Telemetry. Attributes. Dashboards. Rules. Relationships. Commands. To animate the inert thing and turn it into something you can watch, understand, and direct.

In this series, we build stage props. We give them personality. By Episode 8, they will perform.

🗂️ SIPOC — The Stage

Suppliers	Inputs	Process	Outputs	Customers
Physical devices (sensors, actuators, meters)	Raw telemetry data: temperature, humidity, power, position	ThingsBoard: ingest, store, visualise, process, alert	Live dashboards, alarm notifications, RPC commands, analytics	Operators, homeowners, engineers, stakeholders — anyone who needs to see and act on what devices are doing
Home Assistant (Ep.7)	Entity states and sensor readings via MQTT	MQTT bridge: HA → ThingsBoard for enterprise-scale visualisation	Enterprise dashboard showing all HA devices alongside industrial sensors	IT/OT teams bridging consumer smart home with professional IoT
ThingsBoard AI Solution Creator (Ep.6)	A plain-language description of your use case	AI agent: generates entity profiles, dashboards, alarm rules, roles	A working prototype of your IoT solution in under 10 minutes	System integrators, explorers, business stakeholders doing PoC

The Stage Props Metaphor 🎭

Every stage production has props — the physical objects on stage that the cast interacts with: lamps, chairs, telephones, clocks. A prop sitting in the prop house is inert. It has physical properties (weight, colour, shape) but no story, no behaviour, no relationship to anything else.

Bring the prop onto the stage and give it context:

A position (where on the stage it sits)
A character (what role it plays in the story)
Joints (how it can move and change)
Cues (when it does something — the lamp flickers when the villain enters)
A place on the prompt book (the director’s master view of the whole production)

This is exactly what ThingsBoard does to a physical sensor or actuator:

Stage props world	ThingsBoard world
An inert prop in the prop house	A sensor with no platform — just hardware
Giving the prop joints & articulation	Registering a Device with a Device Profile
The prop’s observable state	Telemetry — timestamped key-value data the device sends
The prop’s fixed characteristics	Attributes — static properties (location, model number, threshold)
Grouping props on the same set	Assets — logical containers (rooms, floors, buildings)
The director’s prompt book	The Dashboard — master view of the whole production
A lighting cue (“if lamp > 50°C → warn director”)	An Alarm Rule — automated trigger on telemetry threshold
The director calling “Action!”	An RPC command — instructing a device to do something
The Pixar logo animation	Your finished, running, production-grade IoT solution

Luxo Jr. had one prop — a desk lamp — and gave it so much personality that it became a mascot seen before every Pixar film for forty years. You have sensors, meters, and controllers. ThingsBoard gives them the same treatment.

What ThingsBoard Actually Is 🏗️

ThingsBoard is an open-source IoT platform for data collection, processing, visualisation, and device management. It is production-grade: companies use it to manage tens of thousands of devices across smart energy, fleet tracking, agriculture, smart buildings, and industrial automation.

The key capabilities

Device connectivity — ThingsBoard speaks MQTT, HTTP, CoAP, LwM2M, and more. Any device that can transmit data via one of these protocols can connect. If it cannot, the ThingsBoard IoT Gateway (Python, open-source) acts as a translator.

Telemetry and attributes — Every data point a device sends is stored as a timestamped key-value pair. Device metadata (location, firmware version, thresholds) is stored as attributes — permanent properties rather than time-series values.

Dashboards and widgets — A rich, configurable UI for visualising your data: time-series charts, gauges, maps, alarm tables, entity lists, and custom widgets. Dashboards are built by wiring widgets to device telemetry and attributes.

Rule Engine — A visual, flow-based processing system. Incoming messages pass through chains of nodes that filter, transform, and react. An alarm fires. An email sends. A command goes back to the device. A Kafka message is published.

Entity model — Devices, Assets, Customers, Users, and more — all connected via typed relations. A building contains floors, which contain rooms, which contain devices. The hierarchy is modelled explicitly.

Alarms — When telemetry crosses a threshold, ThingsBoard creates an alarm, propagates it up the entity hierarchy, and notifies the appropriate users via the Notification Centre.

Which edition?

Edition	Best for	Cost
Community Edition (CE)	Self-hosted, learning, open-source projects	Free (Apache 2.0)
Professional Edition (PE)	Enterprise features: platform integrations, entity groups, white-labelling	Commercial licence
Cloud	Zero-setup SaaS — US or EU regions	Free tier + paid plans

For this series, everything works on Community Edition and Cloud. Where PE-specific features appear, they are labelled.

ThingsBoard and Home Assistant: Two Stages, One Show 🏠

Home Assistant (HA) is your personal stage — the smart home controller that knows Rianne’s heating schedule, whether Beau and Elvis are in the garden, and which lights to turn off at bedtime.

ThingsBoard is the enterprise stage — built for industrial-scale telemetry, multi-tenant isolation, hierarchical entity models, and professional dashboards.

They are not competitors. They are collaborators. In Episode 7, we bridge them via MQTT — HA publishes its entity states to ThingsBoard’s MQTT broker. ThingsBoard ingests them as device telemetry, displays them on dashboards alongside other sensors, and applies alarm rules that HA has no native concept of.

The result: your home’s Luxo Jr. lamp plays alongside industrial-scale equipment on the same stage. The prompt book covers both.

The Series Map: Eight Episodes 🎬

#	Episode	Stage props concept
1	This one — What ThingsBoard is	The prop house and the stage
2	Devices, Assets, Profiles, Relations	Building the set
3	MQTT, HTTP, telemetry, attributes	The prop speaks
4	Dashboards and widgets	The prompt book
5	Rule Engine, alarms, notifications	The director’s cue sheet
6	AI Solution Creator	Animating the lamp in 10 minutes
7	Home Assistant ↔ ThingsBoard via MQTT	Two stages, one show
8	Production deployment, ThingsBoard Edge, scaling	The Pixar logo — going live

The prop house is open. The stage is set. In Episode 2, we build the first set and register our first device.

🔗 Resources

ThingsBoard website: thingsboard.io
ThingsBoard Cloud (free tier): thingsboard.io/installations
ThingsBoard docs: thingsboard.io/docs
AI Solution Creator blog post: thingsboard.io/blog/ai-solution-creator
Luxo Jr. (Wikipedia): en.wikipedia.org/wiki/Luxo_Jr.

🎬 Stage Props! is a series about ThingsBoard — the IoT platform that gives your devices joints, personality, and behaviour, the way John Lasseter gave Luxo Jr. a soul.

DEV Community: Willem van Heemstra

Santa Augmentcode Intent Ep.9

Beyond the Workshop — Intent Meets an External Agent Stack 🎅

When the Workshop Must Travel

The Travelling Kit: Four Tools in One Case

Why Context Quality Beats Context Quantity

The Hidden Token Tax: Shell Output

The Gateway Question: Why LiteLLM Belongs in the Story

What the Finished Setup Looks Like

The Architecture, as Father Christmas Would Draw It

The Recommended Order Matters

Fast Path for the Impatient Elf

Why This Is a Perfect Episode 9

SIPOC: The Travelling Stack

A Final Word from Father Christmas

Santa Augmentcode Intent Ep.8

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

The Complete Picture

The Scenario

Step 1: Open Intent and Set the Goal

Step 2: The Coordinator Drafts the Living Spec

Step 3: Intent Creates Isolated Workspaces

Step 4: Wave 1 Runs

Step 5: Handoffs and Wave 2

Step 6: The Verifier Checks Everything

Step 7: The Pull Request

What We Built Together

SIPOC: The Complete Intent Workflow

Getting Started

One More Sleigh Stop

Santa Augmentcode Intent Ep.9

Beyond the Workshop — Intent Meets an External Agent Stack 🎅

When the Workshop Must Travel

The Travelling Kit: Four Tools in One Case

Why Context Quality Beats Context Quantity

The Hidden Token Tax: Shell Output

The Gateway Question: Why LiteLLM Belongs in the Story

What the Finished Setup Looks Like

The Architecture, as Father Christmas Would Draw It

The Recommended Order Matters

Fast Path for the Impatient Elf

Why This Is a Perfect Episode 9

SIPOC: The Travelling Stack

A Final Word from Father Christmas

Santa Augmentcode Intent Ep.8

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

The Complete Picture

The Scenario

Step 1: Open Intent and Set the Goal

Step 2: The Coordinator Drafts the Living Spec

Step 3: Intent Creates Isolated Workspaces

Step 4: Wave 1 Runs

Step 5: Handoffs and Wave 2

Step 6: The Verifier Checks Everything

Step 7: The Pull Request

What We Built Together

SIPOC: The Complete Intent Workflow

Getting Started

One More Sleigh Stop

Santa Augmentcode Intent Ep.1

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

The Problem With Being Father Christmas

What Is Augment Intent?

The North Pole Analogy, Explained

What This Series Covers

SIPOC: The Workshop at a Glance

Why Should You Care?

Getting Started

Wizard of Oz Warp 🌪️ Ep.1

Episode 1: Follow the Yellow Brick Road

The Grey Skies of Kansas 🌩️

🗂️ SIPOC — The Journey Begins

The Land of Oz: What Warp Actually Is 🏙️

Step 1: Install Warp on the Mac Mini M4 Pro 💻

Verifying the install

The First Blocks: The Munchkins Welcome You 🌈

Setting Up the Series Project: warp-of-oz-tasks 🏗️

Install uv (Python package manager)

Scaffold the project

Write the first source file

Setting Up the Series Project: `warp-of-oz-tasks` 🏗️

Install `uv` (Python package manager)

The `#` Key: Your First Taste of Magic ✨