DEV Community: The Software's Journey

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.

Santa Augmentcode Intent Ep.3

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

Santa Plans, Elves Build — Coordinator & Specialist Agents 🧝

Accompanying source code repository: Santa Augmentcode Intent

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

The Fundamental Division of Labour

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

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

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

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

What the Coordinator Does

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

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

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

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

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

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

What the Specialists Do

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

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

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

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

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

The Conversation Pattern

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

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

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

[20 minutes pass]

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

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

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

[Test Suite Elf runs]

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

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

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

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

Choosing the Right Model for Each Role

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

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

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

SIPOC: Coordinator → Specialists → Verifier

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

What Can Go Wrong (And How Intent Handles It)

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

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

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

What Comes Next

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

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

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

Charlie's Chocolate Factory Paperclip — Ep.1

Willem van Heemstra — Mon, 06 Apr 2026 08:48:12 +0000

🎫 The Golden Ticket

"Oh! I've got a Golden Ticket!"
— Charlie Bucket, Roald Dahl's Charlie and the Chocolate Factory.
"Oh! I've got a zero-human company!"
— You, after npx paperclipai onboard.

🍫 A Factory That Runs Itself

Willy Wonka's chocolate factory was the great mystery of its age. Products came out. Deliveries went out. Lights were on. Machines were running. And for years, not a single human worker was seen entering or leaving.

The world assumed it was impossible. The world was wrong. Wonka had figured out something everyone else had missed: you do not need human workers if you have the right workers. Organised. Purposeful. Tireless. Aligned to a single mission.

Paperclip is the same idea, applied to your business.

Paperclip is an open-source orchestration platform that lets you build and run a company where the workers are AI agents. Not one agent. Not a chatbot. A company — with an org chart, a CEO, department heads, engineers, marketers, analysts, and support staff. All of them AI. All of them working from goals you set. All of them running 24 hours a day, seven days a week, without a lunch break, a sick day, or a performance review.

The factory runs itself. You are Wonka. You own the ticket.

📋 SIPOC — The Factory Floor

Suppliers	Inputs	Process	Outputs	Customers
Paperclip (open-source, MIT)	Your business goal	Onboard → Create company → Hire agents → Set goals	Business output — code, content, analysis, customer responses	Your users, clients, and customers
AI providers (Anthropic, OpenAI, Google)	Agent adapters (Claude Code, Codex, Cursor, OpenClaw)	Heartbeat scheduling → Task checkout → Execution	Completed tasks, audit trails, cost reports	You, the board — reviewing and approving
PostgreSQL (embedded in dev)	A mission statement	Governance gates → Budget enforcement → Rollback	A running zero-human company	The wider world, which receives your factory's output
Node.js + React	Your API keys	Clipmart (coming soon) → One-click company templates	Portable, importable company configurations	Future Paperclip users

🏭 Why This Is Different from Everything Else

The AI space is full of tools that give you one clever worker. A coding assistant. A writing helper. A research tool. These are useful. They are also lonely — a single Oompa Loompa, standing in a field, doing their best.

Paperclip is not a tool. It is a factory.

What Paperclip is NOT	What Paperclip IS
A chatbot	An org chart with agents in every role
A single-agent framework	An orchestration layer for teams of agents
A prompt manager	A goal-alignment and delegation system
A drag-and-drop workflow builder	A company modelled with hierarchy, budgets, and governance
A code review tool	A work orchestration system (bring your own review process)

The mental shift is important. You are not prompting agents. You are managing a company of them. You set the mission. You hire the CEO. The CEO decomposes the goal and hires department heads. The department heads spawn workers. The workers do the work and report upward. You, as the board, review strategy, approve hiring, set budgets, and intervene when needed.

That is a company. And you are running it.

🎫 The Golden Ticket — What Makes Paperclip Special

Five things that set Paperclip apart from the pile of agent tools launched in the last two years:

1. Atomic execution. Task checkout and budget enforcement happen atomically — no two agents accidentally work on the same task, and no agent accidentally exceeds its budget. The factory floor does not have collisions.

2. Persistent agent state. Agents remember their context across heartbeats. They do not restart from scratch every time they wake up. The worker who left a task half-done yesterday picks it up where they left it.

3. Runtime skill injection. Agents learn Paperclip workflows, project context, and company standards at runtime — without retraining. Slip a SKILL.md into the right directory and the agent reads it on the next heartbeat. The Oompa Loompas learn new recipes without going back to school.

4. Governance with rollback. Approval gates are enforced. Configuration changes are versioned. Bad changes can be rolled back. You can pause any agent, terminate any run, override any budget. You are always the board. The factory never locks you out.

5. True multi-company isolation. One Paperclip deployment can run dozens of companies with complete data separation. Your software agency and your content studio run in the same instance, invisible to each other. Wonka's factory, but with multiple production lines.

🗺️ What This Series Covers

Eight episodes. One complete journey from "what is this?" to "my company is running":

#	Episode	Factory Metaphor
1	This one — what Paperclip is	The Golden Ticket
2	Installation and onboarding	Finding the Factory
3	The dashboard, companies, and org charts	The Tour Begins
4	Agents, adapters, and heartbeats	Meet the Oompa Loompas
5	Projects, goals, and tasks	The Chocolate Rooms
6	Skills and runtime injection	The Secret Recipe Book
7	Clipmart and company templates	The Great Glass Elevator
8	Running a real zero-human company	You've Won the Factory

By the end of Episode 8, your factory will be running. The agents will be working. The output will be flowing. You will be the board — reviewing strategy, not executing tasks.

🍫 A Note on the Name

The name Paperclip is a deliberate reference to the paperclip maximiser — a classic thought experiment in AI safety. In the original scenario, a hypothetical AI converts all available resources into paperclips because that is all it has been told to do. Everything. All of it. Paperclips.

Paperclip the software takes that premise and gives it a more useful direction: what happens when you point an AI agent at a real business goal and let it organise itself to pursue it? Not paperclips. Revenue. Code. Content. Customer satisfaction.

The thought experiment ends badly. The framework, used with care, does not have to.

The board (you) is always in charge. The budget always has a ceiling. The governance gates always require approval. The factory never runs without a Wonka.

"The suspense is terrible. I hope it will last."
— Willy Wonka.
"The autonomy is impressive. I hope it stays governed."
— Paperclip, with appropriate restraint.

🚀 What's Next

In Episode 2, we find the factory. We install Paperclip, run the onboarding wizard, and walk through your first company setup — from npm install to a live dashboard with a running CEO agent.

The ticket is in your hand. The gates are opening.

🍫 Charlie's Chocolate Factory is a series about building zero-human companies with Paperclip — the open-source AI agent orchestration platform.

Santa Augmentcode Intent Ep.1

Willem van Heemstra — Mon, 06 Apr 2026 08:44:00 +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.

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

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?”

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

Getting Started

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

Willem van Heemstra — Mon, 06 Apr 2026 08:43:54 +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.

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.

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

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

Pillar 3: Review the Spec, Not Just the Code

The Christmas Deadline as a Forcing Function

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 is SDD. This is how Christmas gets delivered on time.

What Comes Next

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.