Shipping Reliable Products

The ten tenets of a product engineer

The core ideology. None of these are about tools; every one of them changes what the agent gets handed.

1. 01
   Understand the problem spaceThe agent only knows the problem you managed to describe. Time spent here is the planning third of Brooks's schedule.
2. 02
   User, machine and fellow-dev empathyAdd a fourth: agent empathy. The next reader of your code is as likely to be a model as a colleague.
3. 03
   Think in outcomes, not outputOutput is now nearly free. If you measure yourself by it, the agent will happily bury you in it.
4. 04
   Be comfortable with ambiguityAgents are not. Resolving ambiguity before you hand work over is the highest-leverage thing you do all day.
5. 05
   Ship fast, think and act slowlySlow is smooth, smooth is fast. The agent supplies the fast; you supply the slow.
6. 06
   Talk to users who use your productOr to your ideal customers. How well do you interview your users? No agent can do this for you, and everything downstream depends on it.
7. 07
   Always use your productDogfood. The agent can run the tests; it cannot feel the friction. That is the review only you can give.
8. 08
   Connect the dotsAcross the codebase, the user's day and the business. Agents see one context window; you see the whole board.
9. 09
   Use LLMs to augment your learningAsk the agent to explain why it did the thing. The point is that you understand more at the end of the session, not less.
10. 10
    Develop taste in code, design and UXTaste is what you review with. Without it, every agent suggestion looks equally fine.

Estimation and optimism

Brooks's claim in chapter two: the two things that sink software are optimism and bad estimation, and they are the same thing. Software engineering is optimistic by nature. We rarely thought through the outcome before; agents give us even less reason to pause.

The surgical team, remapped

Chapter three describes Harlan Mills's proposal: one surgeon who owns the design, surrounded by specialists who keep the surgeon's hands free. It is the first description of a person working with a staff of helpers who do not share authorship. Note what the team is not: it is not ten surgeons operating at once. Here is the roster with today's cast.

Brooks's "promising attacks", thirty years on

Keeping up without the FOMO

One check-in said it plainly: watching the timeline, it feels like everyone else is doing unbelievable things, and the question is what it takes to catch up. No Silver Bullet is the answer, and it is a kind one. Every tool on the timeline is an attack on accidental difficulty, and a good one, but the gain any single tool can give you is bounded by how much accident is left in your work. The essence (knowing what to build, the shape of the data, what correct means) is where the compounding happens, and none of it expires when the next tool ships.

Why this and not a CRUD app

Chopin names three gaps in how we plan with agents: plans are not interactive, decisions have no owner, and agents explain in text when a picture would do. A tool that fixes those is also, conveniently, the perfect specimen for this workshop. Decisions are events, so event sourcing is the obvious model rather than a flourish. A plan room with people and an agent in it is the multiplayer harness, so the harness demo and the product are the same code. The agent-built artifacts from the planning skills below have a home to live in. And you dogfood it on stage: the ticket for Greenhouse gets planned inside Greenhouse.

Scope, honestly. Chopin is months of work by two people and includes a real-time collaborative MDX editor, research blocks, and GitHub-repo organisation. Greenhouse is the smallest cut that still proves the point: block-level plans (no character-level co-editing; each edit is an event, last writer wins per block), comment threads, a decision log, an agent that participates through the same commands as a person, embedded artifacts rendered from Markdown, and an MCP server so any coding agent can read the plan and write decisions back. Deferred: CRDT text editing, presence cursors, research blocks, multi-repo. Chopin itself is open source (githubnext/chopin); the point here is not to clone it but to build the thin version on the stack below so every practice is visible.

The domain: a plan room

A plan belongs to a repo. It is made of blocks. Anyone in the room, human or agent, can edit a block, open a comment thread on it, or ask for an exploration. Threads end in decisions. Decisions stay attached to blocks. That is the whole model, and it needs a real vocabulary, an event log, auth, a file store for artifacts, and an agent in the loop.

// the ubiquitous language, as types the user would recognise
Plan         — a document tied to a repo; a stream of events
Block        — a unit of the plan: prose, artifact, or research
Thread       — a comment thread anchored to one block
Decision     — how a thread ended: who, when, what, which block
Exploration  — an agent thread implementing one option, reporting back
Artifact     — an agent-built interactive thing embedded in a block
Participant  — a person or an agent; same commands, same rights

// commands anyone issues      // events that get recorded
EditBlock       ───────────▶  BlockEdited
OpenThread      ───────────▶  ThreadOpened
Reply           ───────────▶  ReplyPosted
ResolveThread   ───────────▶  ThreadResolved ──▶ DecisionRecorded
RequestExploration ────────▶  ExplorationStarted … ExplorationReported
AttachArtifact  ───────────▶  ArtifactAttached
ForkPlan        ───────────▶  PlanForked        // a branching entry point, not a dead end

Three speakers, one vocabulary: the person says "resolve this thread", the code says ResolveThread, and the agent, reading the repo, says the same thing back. The agent is a Participant, nothing more: it holds no command a person cannot issue, which is also how you keep it honest.

The stack: good enough, boring on purpose

Deploy footnote. Cloudflare is the easy path here: Alchemy's TanStack Start adapter is first-class on Workers, R2 speaks S3 so the MinIO code path is unchanged, and Durable Objects give pi-durable a per-session home for free. The one thing Cloudflare does not have natively is Postgres. Two honest options: keep Postgres (local from Nix, hosted Neon in prod, Hyperdrive in between) for full local/prod parity, or move to D1 and SQLite everywhere. The page assumes Postgres; D1 is a smaller, cheaper demo if the audience will not care about parity. Agent sandboxes run as Cloudflare Containers through the Sandbox SDK.

Repo layout

greenhouse/
├── flake.nix              # postgres, minio, mailpit, bun — one env everywhere
├── process-compose.yaml   # what `just up` starts
├── justfile               # the only commands anyone (or any agent) needs
├── alchemy.run.ts         # workers, r2, hyperdrive, durable objects, secrets
├── packages/
│   ├── domain/            # Plan, Block, Thread, Decision: commands, events, projections
│   │   └── __expect__/    # expect tests: command in, event stream out
│   ├── api/               # Effect HTTP, Better Auth, plan-room Durable Object
│   ├── agent/             # the room's pi-durable harness and its tools
│   ├── mcp/               # MCP server: read plan, list decisions, record decision
│   └── web/               # TanStack Start + shadcn/ui; block editor, threads, log
├── e2e/                   # event-replay e2e, and a few Stagehand flows
├── scripts/               # scaffolding: new-command, new-event, new-projection, new-route
├── skills/                # the collection below, loaded by pi and Claude Code
├── docs/
│   ├── GLOSSARY.md        # the ubiquitous language, kept next to the code
│   └── decisions/         # living wiki: why, not what
├── AGENTS.md              # shared agent instructions
└── CLAUDE.md              # → AGENTS.md

Scripts the demos run

A justfile is the contract between you, the agent and the sandbox. If a thing is not a recipe here, the agent will invent its own way to do it.

just up                 # nix develop + process-compose: db, minio, mail, api, web
just test               # expect tests (ms) then event-replay e2e (s)
just test:ui            # Stagehand flows against the local app (min)
just new command Name   # scaffold command + schema + expect test stub
just new event Name     # scaffold event + append to the registry
just new projection Name
just new route /path    # TanStack route + loader wired to the api
just plan GH-12        # open a plan room for the ticket; agent drafts blocks
just explore GH-12     # one exploration per approach, reported back into the plan
just trace session-id  # animated walk through what the agent touched
just replay stream-id  # rebuild a projection from the log, print the story
just review             # model-inversion review of the current branch
just deploy             # bun alchemy.run.ts

How a coding harness works

Before the multiplayer version, the single-player loop, because most of what feels like magic is six lines of plumbing. A harness is a program that assembles context, asks a model, executes whatever tool call comes back, and feeds the result in again until the model stops asking.

// the whole loop, honestly
context  = system prompt + AGENTS.md + skills + conversation + tool results
loop:
  reply  = model(context, tools)
  if reply has no tool call: break
  result = execute(reply.tool_call)         // shell, read, write, browser…
  context += reply + result                  // this is where context grows
you decide: which tools exist, what needs approval, what gets compacted,
            what persists between sessions, who else can see the thread

Context economics: tokens, caching, compaction

The model remembers nothing between requests, so every turn re-sends the whole conversation. Cost grows with the square of session length unless the harness is careful. Three mechanisms keep it survivable, and all three are decided by the harness, not the model.

// one request, in the order Claude Code sends it (stable first, volatile last)
[ system prompt + tool definitions ]  changes when: the tool set changes, upgrade
[ CLAUDE.md · auto memory · rules   ]  changes when: session start, /clear, /compact
[ conversation · tool results        ]  changes when: every turn (appended at the end)

// the cache matches the PREFIX, exactly. change byte 1 and everything after it is recomputed.
turn n:    [sys][ctx][msg1 … msg n-1] ← read from cache [msg n] ← processed
/model:    [sys][ctx][msg1 … msg n  ] ← all recomputed: each model has its own cache

Two kinds of durability

Vanilla pi and Claude Code both write the conversation to disk as it happens and can reopen it. Neither resumes a tool call that was running when the process died. pi-durable is built for exactly that gap: it checkpoints the loop itself, so a killed process picks up from the last committed step. The table is the slide.

The honest line for the talk: Claude Code gives you a resumable conversation; pi-durable gives you a resumable run. For a coding session on your laptop the first is usually enough. For an agent that runs unattended in the cloud, triggered by a webhook, the second is the whole point.

pi-durable, picked apart

Three packages, two files, one store. The example below is the shape of the Flavio Copes walkthrough, trimmed to the parts that matter for the demo.

// tools.ts — a tool that takes 10s and declares it is safe to replay
import { defineTool } from "@earendil-works/pi-ai";

export const serviceStatus = defineTool({
  name: "service_status",
  replay: "safe",                       // rerun after a crash; no side effects
  async execute(input, context) {
    await delay(10_000, undefined, { signal: context.abortSignal });
    return { checkout: "degraded" };
  },
});

// agent.ts — open a store, get the root conversation, submit work
import { openNodeSqliteStorage } from "@earendil-works/pi-durable";
const storage = openNodeSqliteStorage("./agent.sqlite");   // one process owns this file
const harness = createHarness({ storage, tools: [serviceStatus], model });

const root = await harness.root(context, { conversationId: ROOT_CONVERSATION_ID });
harness.resume();                                        // pick up anything left mid-flight

await root.submit(context, {
  requestId: "incident-106",              // same id twice = same answer, no rerun
  text: "What is the checkout status?",
  whenBusy: "steer",                      // or default: queue as a follow-up
});

// ui.ts — any client, reconnecting at any time
for await (const view of root.viewState(context)) {
  render(view.entries, view.runningTools, view.queuedInputs);
}

Building the cloud multiplayer harness on pi-durable

The walkthrough: take the single-player loop above and make it survive and share. pi stays small and vanilla; pi-durable gives it a persistent, resumable session. In Greenhouse this is not a side demo: a plan room is a durable session with people in it, so the harness you build here is the product's agent layer.

1. Single-player, localVanilla pi against Greenhouse. Show the loop in the logs: context in, tool call out, result back in.trust ladder · rung 1
2. Add skills and the justfile as toolsWatch behaviour change with nothing but files added to context. This is the whole skills story in one diff.rung 2
3. Make it durableSwap the loop for pi-durable with a SQLite store. kill -9 mid tool call, rerun the same requestId, watch it resume from the checkpoint. Then a second client on viewState: a terminal and a browser showing the same run.durability
4. Put the sandbox in the cloudA Durable Object per session is the store (DO SQLite behind pi-durable's storage interface, one owner per object); a Cloudflare Container per session runs the repo and just. The loop runs there; viewState streams back to everyone watching over a WebSocket from the same object.rung 4
5. Trigger it from a webhookA PR opened starts a review session. Sandbox, agent, webhook: the simple code-review agent from the notebook, now legible end to end.review for understanding

The skills collection

All loaded from skills/ by both pi and Claude Code. Third-party ones are pinned by commit; project ones are ours. Each row says when it fires, because a skill nobody triggers is a document nobody reads.

Planning as a boundary object

Maggie Appleton's "Planning with Agents" names the problem with how we plan today: the agent writes about 4,500 words a minute, you read about 240, so the plan arrives as a wall of Markdown you skim and approve. Her remedy is two ideas from Suchman and Star: plans are "a weak resource for ad hoc activity", not a contract, and the plan should be a boundary object, something that serves the human's way of seeing as well as the agent's. Her line for builders: "the agent can and should do 1000x more work to make the human more effective." Greenhouse takes that literally. The speaker has been doing this by hand in a product; the skills and scripts below are that practice, written down so the agent builds the interface instead of you.

The social half of Appleton's argument (colleagues and agents debating a decision together) is what Chopin is for, and Greenhouse keeps the mechanism (a shared room, threads, an agent as participant) while leaving team process out of the talk: one person planning with an agent is the case shown; a second person joining the room is one click more, and that is the only team-level thing said all evening.

Connectors and tools the agent reaches for

Skills tell the agent how to think; these give it somewhere to look. All four are used in the runs.

The testing skill, spelled out

The rule the agent follows: if a test's expected output is not something you could show a user and get a nod, it is the wrong test.

Demo script: each practice, shown live

1. Fresh clone to green tests, with nobody at the keyboardHand the agent a bare checkout. just up, just test. If it needs you, that is a DX bug, and we fix it on stage.run anywhere
2. Plan the ticket in the tooljust plan GH-12 opens a room. The agent drafts blocks, runs two explorations, embeds a decision report. You resolve the thread by clicking. The plan is now a boundary object with one owned decision in it.planning · boundary objects
3. Add a field, follow the trellisAdd rationale to Decision in the shared schema. Watch the compiler walk the agent through api, UI, MCP server and tests.types as design language
4. A new feature as command, event, projectionjust new command ResolveThread. The scaffold writes the expect stub; the agent fills it; the snapshot is reviewed as prose.event sourcing · expect tests
5. End to end without a browserReplay a full plan (edit, thread, replies, resolve, fork) through the API and assert on the decision log. Then the one Stagehand flow, to show what it costs by comparison.testing skill
6. Taste under supervisionAsk for the resolve action "to feel better". impeccable and the animation skills turn that into specific edits; you judge the result by using it.taste · dogfood
7. Correct code that is wrongHave one tool author a change that passes every test but breaks a glossary rule. Have a different model review it with just review.model inversion · review for understanding
8. Explain it backjust trace renders the event flow of a real session with viz-explainer and attaches it to the plan as an artifact block. The agent's account of its own work, as a picture, where the decision lives.augment your learning
9. Implement from the plan, anywhereOpen Claude Code with the Greenhouse MCP server. It reads the plan, sees the one decision, implements against it, and writes "implemented in PR #n" back as a decision. Plan here, build there, review against the plan.one vocabulary · legibility
10. Ship itjust deploy from the agent's sandbox, after it has read the Cloudflare docs via the deploy skill. Same repo, same vocabulary, now on Workers.read the docs · trust ladder

The workflow, one task end to end

Release checklist

Lives in the repo as docs/RELEASE.md; the PR template links it. Short on purpose: a checklist nobody finishes protects nobody.

1 · Changing events people already recorded

The log is a record of facts, and you do not change the past. So an event-sourced product evolves by changing how events are read, not what was written. There is a ladder, least invasive first, and the agent should be told to climb it from the bottom.

Why this matters for the agent: an agent asked to "add a rationale to decisions" will happily edit the event schema in place and break every replay of every existing plan. The event-sourcing skill makes the ladder explicit and makes the expect tests the gate.

2 · Feature flags: behaviour, not code

3 · Rollouts: a sequence you can watch

4 · Letting users send you bugs the agent can reproduce

A bug report is a repro you did not have to write. Design the report so it carries enough for the agent to reproduce it without a call. In an event-sourced app most of that is already there.