Agentic engineering, from the model to the organisation.
Interactive explainers, published at https://camunda.github.io/agentic-engineering-explainers/. Chapters, in reading order:
Why (00–04): The model, where humans fit in it, and the risks it balances.
- 00 From Dark Factory to Software Garden (
src/pages/dark-factory.html) - 01 It was never the typing (
src/pages/grief.html) - 02 The role of humans (
src/pages/humans.html) - 03 The organisation of agents (
src/pages/garden.html) - 04 Engineering Risk (
src/pages/risk.html)
Quality (05–09): How you know it's any good, at agentic speed.
- 05 Agentic Loop Engineering (
src/pages/loops.html) - 06 There are no flaky tests (
src/pages/no-flaky.html) - 07 All software fails somewhere (
src/pages/fails-somewhere.html) - 08 Point them at a number (
src/pages/telemetry.html) - 09 Zero-eyes PR approval (
src/pages/zero-eyes.html)
Structure (10–12): Know where the model is reliable, and harden the edges at compiler speed.
- 10 Every model has an envelope (
src/pages/envelope.html) - 11 Rules that enforce themselves (
src/pages/enforce.html) - 12 Derivation over duplication (
src/pages/derive.html)
System (13–15): The tools agents use, and the gates they pass through.
- 13 Designing for agent users (
src/pages/agent-users.html) - 14 Get to the eleventh (
src/pages/eleventh.html) - 15 The merge button is part of the system (
src/pages/merge-gate.html)
Organisation (16–20): Rolling it out: people, teams, tools and bottlenecks.
- 16 The bottleneck moved (
src/pages/constraints.html) - 17 The constraint is mindset, not the model (
src/pages/mindset.html) - 18 You are the skill (
src/pages/skill.html) - 19 Conway's Law still holds (
src/pages/conway.html) - 20 Start with one garden (
src/pages/start.html)
Case studies (21–23): What happened when we did it: the numbers, from the git history.
- 21 The Cambrian explosion (
src/pages/case-study.html) - 22 Three shapes (
src/pages/three-shapes.html) - 23 c8ctl (
src/pages/c8ctl.html)
Conclusion (24): What it comes down to.
- 24 Agency, not AGENTS.md (
src/pages/agency.html)
The case study's numbers are snapshots from October and November 2026; the data scripts that produced them are not in this repo.
The site is generated. Don't edit HTML in _site/: it's build output and isn't committed.
| What | Where |
|---|---|
| Chapter order, groups, titles, card text, descriptions | chapters.json (the single source of truth) |
| A page's styles and body | src/pages/<id>.html, after a front-matter block (---, layout: chapter, ---) |
| The shared page shell (head, sharing tags, header bar, section dots, brand.css, hints.js) | src/layouts/chapter.html |
| Images, scripts, fonts, brand files | src/assets/, copied to the site root unchanged |
node scripts/build.mjs # build into _site/ (also refreshes the chapter list above)
node scripts/build.mjs --serve # build, serve http://localhost:8931, rebuild on save
node scripts/build.mjs --check # what CI runs: build, check links, check this README is current
Pages get chapter metadata through placeholders, so nothing about order or numbering is hand-written:
{{kicker}}: "The Software Garden · Group · NN", for the intro{{nav}}: the end-of-chapter Next / Previous / Contents links{{num:<id>}}: a chapter's number, e.g.{{num:zero-eyes}};{{range:<Group>}}: a group's span, e.g.{{range:Structure}}{{chapter_map}},{{toc}}: the chapter map (dark-factory) and the contents cards (index){{prev_href}},{{prev_title}},{{next_href}},{{next_title}}: for pages with their own navigation (garden)
To add or move a chapter: add src/pages/<id>.html and src/assets/thumbs/<id>.jpg (1200×750), add or move its entry in chapters.json, and run the build. Numbers, cards, maps, links and this README follow. An unknown placeholder, a chapter without a page, or a broken link fails the build.
Branding and interactivity hints: src/layouts/chapter.html loads brand/brand.css after the page styles and brand/hints.js before </body>. Mark every interactive control (button, slider, toggle) with data-hint="…", e.g. data-hint="drag the slider". It gets a "Try it: …" label and pulses until the reader first uses it, so interactive diagrams don't read as static pictures.
cd ~/workspace/agentic-engineering-explainers && node scripts/build.mjs --serve
open http://localhost:8931 # contents
open http://localhost:8931/garden.html
Fully offline (three.js vendored). Drag pan · right-drag rotate/tilt · scroll zoom-to-cursor · double-click fly in · 1–6 codebases (press twice to enter the garden) · 0 overview · space auto-orbit · g toggles structured / unstructured garden · p partial garden (⚙ in the mode pill: human/agentic speed, agents wait/carry on) · m toggles stable / evolving (structured) · ←/→ (or PageUp/PageDown) step through the guide sidebar · t hides it.
Live: https://camunda.github.io/agentic-engineering-explainers/