Forem: The Software's Journey

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

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.

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.

Santa Augmentcode Intent Ep.2

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

The Master Gift List That Writes Itself 🎄

Accompanying source code repository: Santa Augmentcode Intent

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

The Problem With Static Specifications

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

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

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

The Living Spec: What Intent Does Differently

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

Here is how it works:

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

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

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

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

A Tale of Two Lists

Let me show you the difference in concrete terms.

The Old Way (Static List):

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

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

The New Way (Living Spec):

## Gift Delivery Optimisation — Living Spec

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

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

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

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

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

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

SIPOC: The Living Spec Process

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

Why This Matters for Parallel Work

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

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

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

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

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

Practical Notes: Writing a Good Spec Seed

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

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

What Is Coming Next

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

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

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

Santa Augmentcode Intent Ep.4

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

Every Elf Gets a Workbench — Isolated Workspaces 🔨

Accompanying source code repository: Santa Augmentcode Intent

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

The Problem With Sharing a Codebase

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

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

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

Intent solves this with isolated workspaces backed by Git worktrees.

What Is a Git Worktree?

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

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

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

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

The Elf Workbench in Practice

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

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

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

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

Resumable Sessions: The Workshop Is Open When You Return

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

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

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

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

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

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

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

The Unified Window: Code, Browser, Terminal, Git

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

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

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

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

SIPOC: Isolated Workspace Management

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

Practical Tip: When to Merge

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

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

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

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

What Comes Next

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

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

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

Santa Augmentcode Intent Ep.5

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

Finishing Before Christmas — Spec-Driven Development 📜

Accompanying source code repository: Santa Augmentcode Intent

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

The Old Way: Code First, Regret Later

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

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

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

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

What Is Spec-Driven Development?

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

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

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

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

The Three Pillars of SDD in Intent

Pillar 1: Write the Spec Before Any Code

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

A good pre-implementation spec answers:

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

Pillar 2: The Spec Updates as Work Progresses

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

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

Pillar 3: Review the Spec, Not Just the Code

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

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

The Christmas Deadline as a Forcing Function

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

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

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

SDD vs Traditional Approaches

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

SIPOC: Spec-Driven Development Workflow

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

A Worked Example: The Christmas Eve Delivery App

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

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

The SDD way:

## Christmas Eve Delivery Tracker — Spec

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

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

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

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

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

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

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

What Comes Next

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

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

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

Santa Augmentcode Intent Ep.1

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

SIPOC: The Workshop at a Glance

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

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

Why Should You Care?

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

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

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

Getting Started

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

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

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

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

Santa Augmentcode Intent Ep.7

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

Parallel Elves, Zero Chaos — Multi-Agent Orchestration 🎁

Accompanying source code repository: Santa Augmentcode Intent

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

From Solo Agent to Agent Orchestra

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

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

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

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

The Three-Wave Pattern

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

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

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

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

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

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

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

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

Background Agents: The Night Shift

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

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

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

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

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

Handling Handoffs Gracefully

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

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

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

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

When to Use Which Specialist

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

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

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

Bringing Your Own Elves

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

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

SIPOC: Multi-Agent Orchestration

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

The Mythical Man-Month, Solved (Partially)

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

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

Not zero. Not magic. But dramatically lower.

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

What Comes Next

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

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

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

Forem: The Software's Journey

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

Run the first server

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

The # Key: Your First Taste of Magic ✨

The Project Structure So Far 📁

The Series Map: Eight Episodes 🗺️

Magic Lamp Ep.1

🎭 The Performance

🪄 The Paul Daniels Problem

🏗️ The Stack

🎛️ OSC: The Nervous System

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

🔮 What's Coming in This Series

Air Traffic Control Scaleway Ep.1

Cleared for Approach: Identity and Access Management on Scaleway

🎯 Mission Parameters

Pre-Launch Checklist

📊 SIPOC — How IAM Moves Through the System

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

1.1 — Create Three Projects

1.2 — Generate Three SSH Keys — One Per Zone

1.3 — Register SSH Keys to Each Project

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

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

3.1 — Create the Developers Group

3.2 — Deploy Unmanned Probes: Create Applications

3.3 — Issue Flight Plans: Create Policies & Configure Rules

Policy A — Developers Group

Policy B — Individual User

Policy C — Application Principal

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

🗺️ IAM Architecture — The Clearance Map

🔑 Section 4 — The Master Override: API Keys

4.1 — Generate an API Key

4.2 — Rename a Project via the Scaleway API

🚀 Section 5 — Advanced Flight Options

Scaleway CLI

Terraform Provider

📋 Episode Debrief

📡 Further Transmissions

Game on Djangular 🎮 Ep.1

Episode 1: Welcome to the Vault

The Backlog Problem 🎯

🗂️ SIPOC — The Vault

The Gamer Metaphor: Your Stack as Your Library 🗂️

The Project Structure 🗂️

The Series Map: Nine Episodes 🗺️

Technology Stack Cheat Sheet 📋

Quick-Start: Running GameLib Locally 🚀

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

A Final Word from Father Christmas

Santa Augmentcode Intent Ep.6

The Workshop Knows Every Toy — The Context Engine 🧠

The Problem Every AI Tool Has

What the Context Engine Does

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

Install `uv` (Python package manager)

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