Static hubs for animation & FX experiments

Explainer

Agent Engineering Map

How the pieces fit when agents write the code

One map of the main pieces of software engineering, and how they connect when AI agents do most of the building: where code lives, how agents are steered, and how work ships. No engineering background needed; every term is explained the first time it appears.

The map of maps: five pillars in three acts, plus a correction loop A top-to-bottom pipeline of five boxes. Act 1, where code lives: A, The kitchen, the codebase environment, where code lives and its hard limits. Act 2, how agents are steered: B, Hands that don't guess, scripts and CLI, one right answer means a tool checks it; C, Eyes that prove it, verification, the agent checks its work like a user; D, Teaching the cooks, harness and correction, steer with tools first and words last. Act 3, how work ships: E, Loops that ship, connectors, triggers and PRs, how work starts, ships and gets checked. Below E sits a dashed box, Same mistake twice? A dashed correction line runs from it back up to A, marked first, and to D, marked last: fix it in the kitchen first and add words like rules or skills last. ACT 1 · WHERE CODE LIVES AThe kitchenCodebase environmentwhere code lives, and its hard limits ACT 2 · HOW AGENTS ARE STEERED BHands that don’t guessScripts & CLIone right answer? a tool checks it CEyes that prove itVerificationthe agent checks its work like a user DTeaching the cooksHarness & correctionsteer with tools first, words last ACT 3 · HOW WORK SHIPS ELoops that shipConnectors, triggers, PRshow work starts, ships and gets checked Same mistake twice?Fix it in the kitchen first (A).Add words, like rules or skills, last (D). first last
The map of maps. Read top to bottom: five pillars in three acts. The dashed line is the correction loop: when a mistake repeats, fix it in the kitchen first and add words last.
  1. Act 1 Where does the code live? A The kitchen
  2. Act 2 How are agents steered? B Hands that don’t guess C Eyes that prove it D Teaching the cooks
  3. Act 3 How does work ship? E Loops that ship

How to read it: each pillar starts with two diagrams (what the parts are, then how they work together), then a short explanation. Open “Go deeper” for detail and sources.

Crank practice marks working decisions Peter and Cal have locked for Crank. Everything else is public teaching, credited at the bottom.

Three words first

Model

The AI itself: a large language model (LLM) that reads and writes text. Good at judgement. It starts every session blank unless it’s handed notes.

Agent

A model running in a loop with tools: it reads, acts, checks the result and goes again until the job is done.

Harness

Everything wrapped around the model that makes it a useful agent: tools, permissions, instructions, what it can see, and how it checks its work. Cursor and Grok Bot each provide one; your repo adds to it.

@poteto’s picture for this is a Michelin kitchen. You are the chef and agents are the cooks. A chef stops cooking every dish and runs the kitchen instead: sets it up so the cooks get things right by default, tastes a sample of plates, and fixes the kitchen when the same mistake keeps coming back. The five pillars below are the parts of that kitchen.

Architecture

Four places where work actually runs. Cal’s routing (below) picks one per task; work moves between them via git, briefs, and handoffs.

Four places work runs and how tasks move between them Four compute places in two rows. Top left: Grok Bot computer, one shared machine for all bots, eight CPU cores, fifteen gigabytes memory, no GPU, used for planning, checks, measuring and browser jobs on the Grok Bot model. Top right: Cloud agents, a fresh machine per task, run in parallel, model named per run with cost in the usage export, for heavy builds and renders. Bottom left: Mac mini, the home worker for Origin side projects and previews. Bottom right: MacBook Pro, Peter’s interactive coding with Cursor and pstack; local execution is off for the bots. Arrows: between Grok Bot and cloud agents, plan and check versus build; vertically, receipts and Origin previews on the left, long local work and branch plus plan on the right; handoff between Mac mini and MacBook Pro. WHERE WORK RUNS Grok Bot computerone shared machine8 CPU · 15 GB · no GPUplanning, checks,measuring, browser jobsGrok Bot model Cloud agentsfresh machine per taskruns in parallelmodel per runcost in usage exportheavy builds & renders build plan · check Mac minihome worker for Originside projects & previews MacBook ProPeter · Cursor · pstackinteractive codinglocal exec off for bots receipts Origin previews long local work branch · PLAN handoff
Four places work runs. Grok Bot and cloud agents trade planning and checks for builds. Cloud agents and the Mac mini share Origin previews and long work. The MacBook is for Peter to drive; bots prepare branches and plans, they don’t run locally there.

Grok Bot computer

One shared machine for all bots · 8 CPU · 15 GB · no GPU. Planning, checks, measuring and browser jobs on the Grok Bot model.

Cloud agents

Fresh machine per task, in parallel. Model per run; cost in the usage export. Heavy builds and renders.

Mac mini

Home worker for Origin side projects and previews.

MacBook Pro

Peter’s interactive coding with Cursor and pstack. Local execution is off for the bots.

12 Oct 2026. With the same model, brief and checks, quality should be similar on any of these. What differs is speed, running in parallel, choosing the model per phase, and cost tracking. This is a judgement, not a benchmark; an A/B test on one 8-second shot would settle it.

↑ Back to the map

Who does it, where it runs, which repo Crank practice

Every new task goes through one front door, the Chief of Staff bot (Cal). Before any work starts, Cal makes three decisions and records them in one or two lines in the project channel or chat. Cal tracks the work and never builds it.

Who does it

Work Owner
Production, wearecrank-ltd repos, Railway/Cloudflare prod Forge
Ideas, Origin repos, Mac mini work, previews miniForge
Triage, tracking, decisions, To-Do, reporting Cal
Ads, inbox, client context, writing Watcher, Context, Writer (existing remits)

Load cap: a lead (Forge or miniForge) carries at most about 3 active projects. When a new one would go over the cap:

  1. The lead asks for a project bot. dr eggbot designs it from a template, using CreateAgent.
  2. Create a project channel with Cal, the lead and the project bot.
  3. The project bot builds, and the lead reviews.
  4. Retire the project bot (hide or delete it, with Peter’s yes) when the project ships or is abandoned. No idle bots.

Where it runs

Situation Run it on
Small, well-defined change (a fix, or one PR) Cursor cloud agent on Composer (the default; name the model explicitly)
Long, iterative or heavy build (motion films, previews, local tools) Private worker mac-mini (CloudAgent environment machine)
Peter wants to drive interactively Cursor desktop on his MacBook. Prepare a branch and a PLAN.md for him; the bots can’t push into his IDE session
Scripts, data, browser jobs, checks The Grok Bot box, not repo builds

Token rules:

  • Cloud agents always run Max Mode, so keep briefs tight.
  • Prefer steering an existing agent over launching a new one.
  • Run one agent per stage when token reporting is needed.
  • Use Opus only when Peter asks for it.

Which repo stage

  1. Idea or test: peterjabraham GitHub or Origin.
  2. Proven: transfer (not mirror) to wearecrank-ltd for production. aivw is Peter’s only, so bots never touch it.

Maintenance lane

One owner per side.

  • Forge owns production maintenance: grouped Dependabot, PR CI, Bugbot, and a security audit before go-live.
  • miniForge owns maintenance for Origin and the mini.
  • Run scheduled checks only on repos that are actually active.

Always

  • Merges, deploys, spend, sends and deletions need Peter’s explicit yes.
  • On repos with deploy or setup scripts, every cloud-agent prompt forbids running those scripts and making credentialed external calls.
  • Record the decision (owner, where it runs, repo) in the project channel so anyone can see who has it.

↑ Back to the map

Pillar A · Act 1: where code lives

The kitchen · codebase environment

Where good default behaviour lives, so agents bump into the right shape.

A1. What's in the kitchen: nine parts in three groups inside the codebase A dashed outline labelled Codebase, every file in the project, also called the repo, holds three columns. Shape: Architecture, the big shape; Abstractions, fewer choices; Patterns, one house way. Inventory: Features, what users do; Directories, a folder each; Registry, the app's list of features. Hard limits: Lint rules and types, bad shapes fail; Manifests, declare the app; Dependencies, outside code it needs. A tag under the inventory column says Feature Map, see Pillar C. CODEBASE every file in the project (the repo) SHAPE Architecturethe big shape Abstractionsfewer choices Patternsone house way INVENTORY Featureswhat users do Directoriesa folder each Registrythe app’s list HARD LIMITS Lint & typesbad shape fails Manifestsdeclares the app Dependenciesoutside code Feature Map → see C
A1 · What’s in the kitchen. Nine parts in three groups, all inside the codebase.
A2. How the kitchen steers a change A flow from top to bottom. An agent proposes a change, such as a new feature or a fix. First the registry and feature directory answer where does it go. Then abstractions and patterns answer how is it done here. Then lint rules and types check whether the shape is allowed. If not, a clear error says what to fix and the agent fixes it and tries again. If yes, the change fits the kitchen and the next step is proving it works, in Pillar C. A note says agents copy what the code already does, so the kitchen teaches by example. AGENTProposes a changea new feature or a fix Registry + directorywhere does it go? Abstractions + patternshow is it done here? Lint rules + typesis the shape allowed? Clear errorsays what to fix Fits the kitchennext: prove it works (C) yes no fix it, try again Agents copy what the code already does, so the kitchen teaches by example.
A2 · How the kitchen steers a change. The change is pointed to the right place, shaped by the house patterns, then checked by lint and types before anyone tests it.

The codebase (or repo) is every file in the project. Every agent works inside it, so it’s the best place to keep good habits. Architecture is the big shape: which parts exist and how they connect. Abstractions wrap messy detail in a simple handle, and patterns make the house way the obvious way. Each feature (something a user can do) gets its own directory (folder), listed in a registry (the app’s list of them), so “where does this go?” has one answer. Lint rules and types let a program reject bad shapes before the code runs. Manifests declare what the project is and which dependencies (outside code) it needs. Matt Pocock’s phrase for the goal: make bad code unrepresentable.

Teachers: Matt Pocock, @mattpocockuk (more abstractions, plus harsh lint rules); @poteto (a directory per feature, a registry and strict lint, from the harness conversation).

Go deeper: the kitchen
  • Matt Pocock’s hot take after talking to @poteto: we should use MORE abstractions in the AI age, combined with harsh lint rules, to reduce the design space available to the agent and constrain them only to good decisions. Good abstractions also mean less code, so fewer tokens. Shorter: Don’t make it improbable with prompts, make it impossible with lint rules.
  • In the harness conversation, @poteto describes Dune, her team’s in-house framework for desktop apps: very restrictive lint rules, a directory for every feature, and a registry that finds features, so there’s really only one way to do something. Matt Pocock’s summary: the agent isn’t loaded up with rules to remember, because it stumbles into the rules in the environment at the right moment. His notes on the talk: Abstractions are designed so they can’t screw up, and lint rules enforce it.
  • On architecture, from pstack Pt. 2: it’s more important to spend my time on architecture, choosing the right data structures, and thinking about how the systems I build will work together. My agents fill in the implementation details.
  • This repo is a small example. package.json is its manifest: it names the project, says npm run build runs scripts/build.mjs, and asks for Node 18 or newer. wrangler.toml tells Cloudflare Pages to publish the dist folder. scripts/build.mjs keeps the list of experiments the hub page reads (a tiny registry), and each experiment gets its own directory under /e/.

↑ Back to the map

Pillar B · Act 2: how agents are steered

Hands that don’t guess · scripts & CLI

Mechanical work belongs in code that returns a clear pass or fail.

B1. Who does what: skill, CLI command, result, model On the left, a chain of four boxes. A thin skill, which is words: a short recipe. It names a CLI command, which is deterministic, for example crank film check. The command returns a result with one right answer: pass or fail, as JSON. The result is read by the model, which uses judgement to decide what it means. On the right, a panel marked Crank practice shows where tools live: crank-tools, shared and used by every agent, holding crank film check and crank recon match; and a product repo, which keeps its own verify CLI for that one product. A dashed line links the CLI command to this panel. WORDSSkill (thin)a short recipe DETERMINISTICCLI commandcrank film check ONE RIGHT ANSWERResultpass or fail, as JSON JUDGEMENTModeldecides what it means names returns read by WHERE TOOLS LIVE CRANK PRACTICE SHAREDcrank-toolsused by every agent crank film check crank recon match ONE PRODUCTProduct repoits own verify CLI
B1 · Who does what. The skill names the command, the command gives one right answer, and the model judges what it means.
B2. When to build a tool A decision flow. Agents repeat a chore, slightly differently each time. Question: is there one right answer? If no, it is judgement: the model judges, guided by a skill. If yes, it is deterministic: write a CLI command that gives the same answer every time. Then, as Crank practice, put it where it belongs: shared tools go in crank-tools; a tool for one product goes in that product's repo. Finally the skill shrinks to: run X, then interpret Y. A side note asks why bother, and answers: every agent gets the same answer, for fewer tokens. Agents repeat a choreslightly differently each time One right answer? JUDGEMENTModel judgesa skill guides it DETERMINISTICWrite a CLI commandsame answer every time CRANK PRACTICEPut it where it belongsshared → crank-toolsone product → that product’s repo The skill shrinks to“run X, then interpret Y” yes no Why bother?every agent getsthe same answer,for fewer tokens
B2 · When to build a tool. A chore with one right answer becomes a CLI command, and the skill shrinks to “run X, then interpret Y”.

Crank practice Crank sorts work into two kinds. Deterministic work has one right answer: does this file exist, did the build pass? A program can check it: pass or fail. Judgement work means weighing options: which design, what wording, what to test first. That’s what the model is for. A script is code that does one job. A CLI (command-line interface) is a script grown into a tool, with named commands, help text and output other programs can read. When agents keep redoing the same mechanical steps, each a bit differently, make them a CLI command. Every agent then gets the same answer, using fewer tokens (the chunks of text a model reads). pstack calls this Build the Lever.

Crank practice Shared tools live in one repo, crank-tools, so agents on Crank’s own machines (“box agents”) and cloud agents run exactly the same commands. The first two are crank film check and crank recon match. A product verify CLI, one that only makes sense for one product, lives in that product’s repo.

Teachers: @poteto (Build the Lever; what makes a CLI agent-friendly; pulling the deterministic parts out of skills). The deterministic/judgement split and where tools live are Crank practice.

Go deeper: building good tools
  • @poteto’s checklist for an agent-friendly CLI, from pstack Pt. 1: easy to compose; a --dry-run option on anything with destructive side effects; subcommands that reveal features gradually instead of all at once; error messages that tell the agent what to do instead; rich --help text; output in a machine-readable form such as JSON.
  • Why a CLI beats a throwaway script: agents consume fewer tokens trying to do a task (run a CLI command instead of writing a throwaway script to click on something), and the work becomes more reproducible and testable.
  • In the harness conversation, @poteto describes taking the deterministic parts of a skill and encoding them in a script or CLI, leaving the agent only the parts that need judgement. Before her verification CLI existed, the agent would basically rebuild the world each time and then every agent did it differently. A good question to ask: how much of your skills and rules could actually be deterministic?
  • The words “Deterministic” and “Judgement” are Crank’s labels. The idea lines up with @poteto’s aim to make very efficient use of determinism and non-determinism and let agents shine at the non-deterministic parts.

↑ Back to the map

Pillar C · Act 2: how agents are steered

Eyes that prove it · verification

Without proof, loops just make more mess.

C1. The drive loop: a verify CLI runs five steps against the real app On the left, a dashed outline labelled Verify CLI, which drives the app over CDP, holds five numbered steps: 1 Launch, start the app. 2 Doctor, check it is healthy and up to date. 3 Drive, click, type and read. 4 Evidence, save the proof. 5 Cleanup, stop what it started. On the right, a two-way arrow links the CLI to the real app, a web or Electron app with test data and test logins. A Feature Map box, one note per feature saying how a user gets there, how to drive it and known gotchas, points into the Drive step. The Evidence step points to an evidence pack: tests going from red to green, screenshots, video, traces and heap profiles. VERIFY CLI drives the app over CDP 1Launchstart the app 2Doctorhealthy, up to date? 3Driveclick, type, read 4Evidencesave the proof 5Cleanupstop what it started The real appweb or Electrontest data, test logins Feature Mapone note per feature:how a user gets therehow to drive itknown gotchas Evidence packtests: red → greenscreenshots, videotraces, heap profiles
C1 · The drive loop. A verify CLI launches the real app, checks it’s healthy, drives it like a user, saves evidence and cleans up.
C2. Proving a UI change A flow from top to bottom. The agent changes the UI, for example by adding an Export button. It opens the Feature Map entry that says how a user reaches Export. It drives that path with the verify CLI, like a user would, and captures proof: a screenshot, a video, a test result. Question: did it work? If no, fix it and drive the path again. If yes, it is done and the proof goes in the pull request. AGENTChanges the UIe.g. adds an Export button Opens the Feature Map entryhow a user reaches Export Drives that pathwith the verify CLI, like a user Captures proofscreenshot, video, test result Did it work? Donethe proof goes in the PR Fix itdrive again yes no
C2 · Proving a UI change. The Feature Map tells the agent which path to drive, and the proof goes in the PR.

Verification means the agent checks its own work on the real thing, the way a user would. Not “it compiles”, but “I clicked Export and the file downloaded.” Without it, you are the agent’s eyes and every loop waits for you. With it, the agent can try, look, fix and try again on its own. That’s why @poteto thinks of a good verification skill as critical infrastructure. For web apps, a small CLI drives the app through CDP (Chrome DevTools Protocol), Chrome’s built-in remote control. Desktop apps built on Chrome’s engine (Electron) work the same way. A Feature Map lists every feature and how a user reaches it, so the agent drives the right path instead of guessing.

Crank practice Prove UI changes with a Feature Map plus a CDP CLI, once a UI product repo exists. Generate that repo’s own verification skill and Feature Map with pstack’s official /create-verification-skill, and keep them up to date with /maintain-verification-skill. Until that repo, its preview environment (a private test copy of the app) and its test accounts are named, don’t build a full “Control-Glass-style” control stack.

Teachers: @poteto (verification as the limiting step; Feature Maps; CDP CLIs; pstack’s /create-verification-skill and /maintain-verification-skill); Lingxi Li (give agents a complete feedback loop). Generating the verification skill with pstack is Crank practice.

Go deeper: what counts as proof
  • The five steps in C1 match the sections pstack’s /create-verification-skill writes into a project’s verification skill: Launch, Doctor, Drive, Evidence and Cleanup, plus Helpers for any scripts the skill ships. “Doctor” means checking the app is healthy and running the latest build before driving it. The generator works out how to drive the app (an existing harness first, otherwise the browser over CDP, a terminal or plain web requests) and proves the new skill once, end to end, before handing it over.
  • What a Feature Map looks like: the generator writes a features/ folder with a README.md index, then one short file per feature with the same four headings: Sub-features, How to get to it (user POV), Driving it with … (named after the project’s drive tool) and Gotchas. @poteto’s fictional example skill, verification-skill-example, sums up each file as what exists, how a user reaches it, how to drive it with the harness, what usually lies.
  • Upkeep: apps change and Feature Maps go stale. pstack’s /maintain-verification-skill checks the skill against the app: one reader per feature goes through the source code, then one live session drives every mapped feature. It ends with nothing to fix, one PR of proven corrections to the skill, or a named blocker. It never edits the product’s code.
  • @poteto calls the Feature Map materialized memory. In her view your codebase is the ultimate form of memory, and a Feature Map is a compact, agent-facing copy of it that saves tokens.
  • The proof bar: pstack’s generator writes proof standards into each skill’s Evidence section. Among them: capture the action and the resulting state, not just the final screen, and check side effects too, such as files written or messages sent. The example skill puts it more bluntly: Do not submit look, it opens captures. A video against a stale bundle is not evidence (a stale bundle is an out-of-date build).
  • pstack’s planning playbook tells agents that tests alone are not sufficient verification. Work counts as verified only once the agent has actually run the code and seen it work.
  • The real app needs a good dev setup (pstack Pt. 1): seeded test data, test users and logins, a test or staging environment, and a consistent way to start it all.
  • Lingxi Li’s first tip for running engineer bots: give cloud agents a complete feedback loop, so they can launch a dev copy and drive the whole stack end to end, for example through Chrome DevTools, a CLI or Apple Accessibility.

↑ Back to the map

Pillar D · Act 2: how agents are steered

Teaching the cooks · harness & correction

How you steer agents without micromanaging every keystroke.

D1. The harness around the model A dashed outline labelled Harness, everything around the model that makes it a useful agent. In the centre is the model, the LLM. Six boxes surround it, each linked to it: Context, what it sees now; Memory, kept between runs; Rules, always-on notes; Skills, recipes on demand; the proof loop, which checks its work, from Pillar C; and tools and permissions, from Pillar B. HARNESS everything around the model that makes it a useful agent Contextwhat it sees now Memorykept between runs Rulesalways-on notes Skillsrecipes on demand Proof loopchecks its work (C) Toolsand permissions (B) Modelthe LLM
D1 · The harness around the model. Words (context, memory, rules, skills), plus tools from B and proof from C, turn a model into a useful agent.
D2. Climb the ladder: the correction hierarchy Marked Crank practice. The same mistake shows up again, spotted in review, in proof, or by a user. Try the top rung first. A ladder of five rungs, strongest at the top: 1 Codebase, the mistake can't even be written; 2 Lint, a program says no; 3 Rules, the agent must read it; 4 Skills, a procedure it follows; 5 Style, wording, the weakest. An upward arrow says move fixes up. Then encode the fix once, at the strongest rung that works, and every later agent inherits it, with no reminders in chat needed. CRANK PRACTICE Same mistake, againspotted in review, in proof, or by a user 1Codebasecan’t even be written 2Linta program says no 3Rulesthe agent must read it 4Skillsa procedure it follows 5Stylewording; weakest try the top rung first strongest weakest move fixes up Encode the fix onceat the strongest rung that works Every later agent inherits itno reminders in chat needed
D2 · Climb the ladder. When a mistake repeats, fix it at the strongest rung that works, so every later agent inherits the fix.

Part of the harness steers with words. Context is what the model can see right now (its context window). Memory is what carries over between sessions: notes, past transcripts, the codebase itself. Rules are short instructions the agent always sees. Skills are step-by-step procedures in plain text that it loads when a task needs them. Style notes shape its wording. Words are the weakest way to steer: the agent must notice, remember and obey them. So when the same mistake comes back, move the fix up the correction hierarchy: make it impossible in the codebase, or catch it with lint, before adding another rule, skill or style note. As proof piles up, agents earn more freedom: @poteto’s trust ladder.

Crank practice Keep skills small and make them name a CLI: “run crank film check, then judge what the result means.” The CLI does the deterministic part; the skill holds the judgement. Fix repeats at the strongest rung: codebase > lint > rules > skills > style.

Teachers: @poteto (harness, trust ladder, pstack’s Encode Lessons in Structure, /recall); Matt Pocock (Some of your Cursor rules should be custom lint rules). The five named rungs are Crank practice built on pstack’s principle.

Go deeper: words, memory and the ladder
  • Rules, skills and playbooks differ mainly in when they load. Rules are usually always on. Skills load when a task calls for them. pstack also has playbooks: reference files inside its /poteto-mode skill that load only for the matching kind of task, to save tokens. Under the hood, @poteto points out, a skill is just markdown: words, not magic.
  • Memory: @poteto finds that your past transcripts are often a gold mine for rich context, so pstack’s /recall skill pulls recent chat history back in and a fresh agent starts informed. Lingxi Li’s engineer bots each keep their own memory, and an operations bot repeats key points to them daily because the context limit can’t hold everything.
  • Supervising someone smarter than you: @poteto often asks the agent to restate the problem in its own words before it starts, and uses pstack’s /teach, /how and /why skills to have it explain its work.
  • The trust ladder: in the harness conversation, @poteto describes earning agents more freedom as trust builds, from micromanaging every step up to letting agents merge their own work, once verification and the environment are strong. Lingxi Li puts it this way: working with bots is a trust-building process. Crank stops short of that top step: agents earn more freedom, but a person still does every merge (see Pillar E).
  • Where the ladder comes from: pstack’s Encode Lessons in Structure principle says written instructions are easy to miss, so a correction you’ve given twice should become a lint rule, a check or a script, using the strongest mechanism available, because agents copy what the code around them already does. @poteto’s version in the conversation: how do I turn this into a lint rule? How do I make it so that the code base makes this impossible?

↑ Back to the map

Pillar E · Act 3: how work ships

Loops that ship · connectors, triggers, PRs

How work starts, how it leaves the kitchen, and who watches.

E1. Two loops: outer loop brings work in, inner loop builds it, a human merges At the top, outside the repo: Slack, email, issues, docs and X. Connectors, often using MCP, feed a coordinator bot in the outer loop, which gathers context and writes a clean task. A trigger or routine starts it. The clean task goes into the inner loop, inside the repo: coding agents build, verify and open a PR, producing a pull request with proof, a small change with evidence attached. Below, a human merges every PR and samples some closely. A dashed line from the human to the codebase, the kitchen from Pillar A, says: if a problem repeats, fix the kitchen. OUTSIDE THE REPO Slack Email Issues Docs X OUTER LOOPCoordinator botgathers context, writes a clean task Triggeror routinestarts it connectors (MCP) clean task INNER LOOP INSIDE THE REPO Coding agentsbuild · verify · open a PR Pull request + proofa small change, evidence attached HUMANMerges every PRand samples some closely Codebasethe kitchen (A) repeats? fix the kitchen
E1 · Two loops. The outer loop brings work in from the world, the inner loop builds it inside the repo, and a human merges every PR.
E2. A bug report, end to end A flow from top to bottom. Trigger: a bug report lands in Slack. A connector fetches the whole thread. The coordinator restates it and writes a clean task. A worker reproduces it with the verify CLI, then fixes it and opens a PR with proof. Question: strong proof and small blast radius? If yes, a human checks the proof and merges. If no, or if the change is hard to undo, a human digs in and reads the code as well. Either way a human does the merge, and if the same kind of bug comes again, fix the kitchen, Pillar A, so it can't come back. TRIGGERA bug report lands in Slack CONNECTORFetches the whole thread COORDINATORRestates it, writes a clean task WORKERReproduces it with the verify CLI WORKERFixes it, opens a PR with proof Strong proof andsmall blast radius? YESA human mergesafter checking the proof NO, OR HARD TO UNDOA human digs inreads the code as well Same kind of bug again?fix the kitchen (A) so it can’t come back
E2 · A bug report, end to end. Proof and blast radius decide how closely a person checks the PR. Either way, a person merges it.

Work has to start somewhere and leave somewhere. The inner loop is coding agents inside the repo: build, verify, then open a PR (pull request), a proposed change waiting to be accepted. The outer loop is bots watching the world outside the repo. They gather context through connectors: plugs into Slack, email or issue trackers. Many connectors use a standard called MCP (Model Context Protocol). They then hand a clean task inward, so the coder doesn’t carry the messy discussion. Triggers start work when something happens; routines run it on a schedule. People stop tasting every plate: they sample PRs, fix the kitchen when a problem repeats, and keep a human gate before anything merges.

Crank practice Draft, not merge. Agents open every PR as a draft (marked “not ready yet”), and a person does the merge. Strong proof helps that person decide; it never merges a PR on its own. There’s no timed auto-merge either: no PR merges itself after an hour, or after any other wait.

Crank practice Optional post-fix swarm. After a fix PR, two or three outer-loop agents can probe the fixed app, one of them clicking around at random. They gather evidence, then ping a person with it. They never merge. This step is optional and isn’t always on.

Teachers: Matt Palmer, @mattyp (outer vs inner loop, routines and triggers, specialist bots, reviewers and human gates); Lingxi Li (proof on PRs, review confidence and blast radius); @poteto (inner and outer loops, coordinators, sampling). Draft-not-merge and the post-fix swarm are Crank practice.

Go deeper: loops, proof and merging
  • Matt Palmer on why the loops are separate: If you ask one agent to read files, debate what to build, then immediately delegate the fix, that agent carries a bunch of dirty context. His outer-loop bot gathers context from Slack, Notion, GitHub and docs, then hands a clean prompt to a coding agent for the inner loop.
  • He treats bots as specialists that can ask each other for help, and keeps them in check with permissions, a reviewer and allow/block lists: A separate review agent checks proposed actions and can allow, block, or escalate to you.
  • @poteto thinks of her bots more as coordinators who manage and supervise cloud agents. In the harness conversation she describes bots with routines that watch Slack, X, email and issue trackers, so bug reports become tasks without her carrying them across by hand.
  • Lingxi Li’s merge rule: If the review is highly confident and the blast radius is low, the PR is merged automatically. Otherwise she reviews the code and the proof herself. Her bots also run routines: a check on every open PR each half hour (automated review comments, failing CI, merge conflicts) and nightly clean-up audits. Crank doesn’t copy the automatic merge: at Crank, a person does every merge.
  • One-way doors: in the conversation, Matt Pocock asks about PRs that can’t easily be walked back, such as ones that could lose data. @poteto’s answer comes back to verification: where the work can be checked strongly, one-way doors start to behave like two-way doors. Put together: strong proof and a small blast radius make a PR quick to check, and anything hard to undo gets a close human look. At Crank, a person merges either way.
  • pstack draws the same line. Its PR babysitter stops at merge-ready. It never merges, even with everything green, because merging is a different decision.
  • Reviewing at scale: you can’t taste every dish, so it becomes more about sampling, like a quality supervisor in a factory. When several agents make the same mistake, @poteto fixes the kitchen (skills, constraints, lint rules, types), not that one agent.
  • Small PRs: in pstack’s planning playbook, Each PR is small, self-contained, and easily reviewed.

↑ Back to the map

The whole map on one screen

Every idea on this page, sorted into its pillar and cluster. A diamond marks Crank practice.

Pillar A, The kitchen: Codebase environment Pillar A, The kitchen, Codebase environment. container: Codebase (repo); shape: Architecture, Abstractions, Patterns; inventory: Features, Directories, Registries, Feature Maps (see Pillar C); hard limits: Lint rules & types, Manifests, Dependencies. A The kitchen Codebase environment CONTAINER Codebase (repo) SHAPE Architecture Abstractions Patterns INVENTORY Features Directories Registries Feature Maps → C HARD LIMITS Lint rules & types Manifests Dependencies
Pillar B, Hands that don't guess: Scripts & CLI Pillar B, Hands that don't guess, Scripts & CLI. tools: Scripts, CLI, Agent-friendly CLIs; split the work: Deterministic (Crank practice), Judgement (Crank practice); where tools live: crank-tools (Crank practice), crank film check (Crank practice), crank recon match (Crank practice), Product verify CLIs (Crank practice). B Hands Scripts & CLI TOOLS Scripts CLI Agent-friendly CLIs SPLIT THE WORK Deterministic Judgement WHERE TOOLS LIVE crank-tools crank film check crank recon match Product verify CLIs
Pillar C, Eyes that prove it: Verification Pillar C, Eyes that prove it, Verification. proof: Verification, Evidence pack; drive loop: CDP; launch, then doctor, drive, evidence, cleanup; navigation: Feature Maps; ui proof: Feature Map + CDP CLI, a verify skill made and kept current with pstack, and holding off on the full control stack (all Crank practice). C Eyes that prove it Verification PROOF Verification Evidence pack DRIVE LOOP CDP Launch → Doctor → Drive → Evidence → Cleanup NAVIGATION Feature Maps UI PROOF Feature Map + CDP CLI pstack verify skill Hold the full stack
Pillar D, Teaching the cooks: Harness & correction Pillar D, Teaching the cooks, Harness & correction. harness: Harness, Trust ladder; words: Context, Memory, Rules, Skills, Style; correction: Correction hierarchy (Crank practice), strongest first: codebase, lint, rules, skills, style. D Teaching the cooks Harness & correction HARNESS Harness Trust ladder WORDS Context Memory Rules Skills Style CORRECTION Correction hierarchy: codebase › lint › rules › skills › style
Pillar E, Loops that ship: Connectors, triggers, PRs Pillar E, Loops that ship, Connectors, triggers, PRs. loops: Inner loop, Outer loop, optional Post-fix swarm (Crank practice); inputs: MCP / connectors, Triggers, Routines, Coordinators; outputs: PRs + proof, Sampling review, Merge policy, Draft PRs that a human merges (Crank practice), Human gates. E Loops that ship Connectors, triggers, PRs LOOPS Inner loop Outer loop Post-fix swarm INPUTS MCP / connectors Triggers Routines Coordinators OUTPUTS PRs + proof Sampling review Merge policy Draft; a human merges Human gates
The taxonomy: five pillars, each split into clusters. ◆ = Crank practice. A text version follows.
Text version of the whole map
  • A · The kitchen (codebase environment)
    • Container: codebase (repo)
    • Shape: architecture, abstractions, patterns
    • Inventory: features, directories, registries, Feature Maps (explained in C)
    • Hard limits: lint rules and types, manifests, dependencies
  • B · Hands that don’t guess (scripts & CLI)
    • Tools: scripts, CLIs, agent-friendly CLIs
    • Split the work (Crank practice): deterministic, judgement
    • Where tools live (Crank practice): crank-tools with crank film check and crank recon match; product verify CLIs in product repos
  • C · Eyes that prove it (verification)
    • Proof: verification, evidence pack
    • Drive loop: CDP; launch, doctor, drive, evidence, cleanup
    • Navigation: Feature Maps
    • UI proof (Crank practice): Feature Map + CDP CLI; a verification skill generated with /create-verification-skill and kept current with /maintain-verification-skill; hold the full control stack until the UI repo, preview and test accounts are named
  • D · Teaching the cooks (harness & correction)
    • Harness: harness, trust ladder
    • Words: context, memory, rules, skills, style
    • Correction (Crank practice): the correction hierarchy, codebase > lint > rules > skills > style
  • E · Loops that ship (connectors, triggers, PRs)
    • Loops: inner loop, outer loop; an optional post-fix swarm (Crank practice)
    • Inputs: MCP and connectors, triggers, routines, coordinators
    • Outputs: PRs with proof, sampling review, merge policy, human gates; draft PRs that a person merges, with no timed auto-merge (Crank practice)

Glossary

Every term on the page, A to Z. The tag shows which pillar it belongs to.

Pillar AAbstraction
A simple handle over messy detail, like one save() command that hides every step of saving. Good ones leave agents fewer ways to go wrong.
BasicsAgent
A model running in a loop with tools: it reads, acts, checks the result and goes again until the job is done.
Pillar AArchitecture
The big shape of a system: which parts exist, what each one owns, and how they connect.
Pillar EBlast radius
How much could break if a change is wrong. Small: one button looks odd. Large: everyone loses data.
Pillar BBox agent Crank practice
An agent running on one of Crank’s own machines, rather than in the cloud.
Pillar CCDP
Chrome DevTools Protocol: Chrome’s built-in remote control. A program can use it to click, type, read the page and record what happens.
Pillar BCLI
Command-line interface: a tool you run by typing a command, like crank film check. Agent-friendly CLIs have clear help text and output other programs can read.
Pillar ECloud agent
A coding agent running on its own computer in the cloud rather than on your laptop, so many can work at once.
Pillar ACodebase (repo)
Every file in a project, kept in version control so every change is tracked. “Repo” is short for repository.
Pillar EConnector
A plug that lets an agent read from, or act in, another app such as Slack, email or GitHub.
Pillar DContext
Everything the model can see right now: your message, the files it opened, the notes it was given. The limit is called the context window.
Pillar ECoordinator
An agent that splits a job into tasks, hands them to worker agents and checks the results, without doing the work itself.
Pillar DCorrection hierarchy Crank practice
Where to fix a repeated mistake, strongest first: codebase > lint > rules > skills > style.
Pillar ADependency
Code someone else wrote that your project needs to build or run. The manifest lists them.
Pillar BDeterministic Crank practice
Work with one right answer, so a program can check it and say pass or fail.
Pillar ADirectory
A folder. A feature directory keeps everything for one feature in one place.
Pillar EDraft PR Crank practice
A PR marked “not ready yet”. At Crank, agents’ PRs stay drafts until a person merges them. Nothing merges itself, however strong the proof or long the wait.
Pillar CEvidence
What proves a change works: tests going from red (failing) to green (passing), screenshots, video, traces of what the app did.
Pillar AFeature
Something a user can do in the app, like exporting a file.
Pillar CFeature Map
Short notes, one per feature: what it does, how a user reaches it, how to drive it and what usually goes wrong.
BasicsHarness
Everything around the model that makes it a useful agent: tools, permissions, instructions, context and proof loops.
Pillar EHuman gate
A step where a person must approve before something risky or hard to undo happens.
Pillar EInner loop
Coding agents working inside the repo: build, verify, open a PR.
Pillar BJudgement Crank practice
Work that means weighing options, like choosing a design or the wording. That’s the model’s job.
Pillar ALint rule
An automatic check that reads code and rejects patterns you’ve banned, before the code runs.
Pillar AManifest
A file that declares what a project is, what it needs and how to run it, such as package.json.
Pillar EMCP
Model Context Protocol: a shared standard for connectors, so one plug can work with many AI tools.
Pillar DMemory
What carries over between sessions: saved notes, past transcripts and, most of all, the codebase itself.
Pillar EMerge
Accepting a PR, so its change becomes part of the main code.
Pillar EMerge policy
The rule for when a PR is ready to merge and who merges it. Crank’s rule: a person merges every PR.
BasicsModel (LLM)
The AI itself: a large language model that reads and writes text.
Pillar EOne-way door
A change that can’t easily be undone, like deleting data. A two-way door can simply be reverted.
Pillar EOuter loop
Bots outside the repo that watch Slack, email and issue trackers, gather context and hand clean tasks to the inner loop.
Pillar APattern
The house way of doing a common thing, used everywhere so there’s one obvious way to do it.
Pillar EPost-fix swarm Crank practice
An optional outer-loop step: after a fix PR, two or three agents probe the app, one clicking at random, then ping a person with the evidence. They never merge.
Pillar EPR (pull request)
A proposed change with a description (and, here, proof) that waits to be reviewed and merged.
Pillar Dpstack
@poteto’s public set of skills for rigorous agent work, with named principles such as Build the Lever.
Pillar ARegistry
The app’s list of its parts, such as all its features, which the app reads to find them.
Pillar ERoutine
Work that runs on a schedule, like a nightly clean-up.
Pillar DRules
Short instructions an agent always sees, like “always use the shared date helper”. Some belong in lint instead.
Pillar ESampling review
Checking a sample of finished work closely instead of every piece, then fixing the kitchen when problems repeat.
Pillar BScript
A small program that does one job, often written once and thrown away.
Pillar DSkill
A step-by-step procedure written in plain text (markdown) that an agent loads when a task needs it.
Pillar DStyle
Notes about wording and tone. The weakest way to steer an agent.
Pillar BToken
A small chunk of text, often part of a word. Models read and write in tokens, and their use is measured and paid for in tokens.
Pillar ETrigger
An event that starts work automatically, like a new message in a bug-report channel.
Pillar DTrust ladder
@poteto’s idea that agents earn more freedom as trust in their work builds: from close supervision up to merging their own changes. Crank stops short of that last step.
Pillar ATypes
Labels that say what kind of data goes where. A type checker rejects code that mixes them up.
Pillar CVerification
The agent checking its own work on the real app, the way a user would, and keeping the proof.

Crank practice

Working decisions Peter and Cal have locked for Crank. These are Crank’s choices, not public teaching.

  1. Deterministic vs Judgement. If a job has one right answer, code checks it and says pass or fail. If it means weighing options, the model decides.
  2. Small skills that name a CLI. A skill says which command to run and how to read the result: “run crank film check, then judge what it means.” The command does the mechanical part.
  3. One shared toolbox. Tools every agent needs live in crank-tools, so box agents and cloud agents run the same commands. The first two are crank film check and crank recon match. A verify CLI for one product lives in that product’s repo.
  4. UI proof = Feature Map + CDP CLI. Once a UI product repo exists, prove UI changes by driving the real app and saving the evidence. Generate the repo’s verification skill and Feature Map with pstack’s /create-verification-skill, and keep them current with /maintain-verification-skill. Hold off on a full Control-Glass-style stack until that repo, its preview environment and its test accounts are named.
  5. Fix repeats at the strongest rung. Codebase > lint > rules > skills > style. Don’t add another reminder in chat if a lint rule would do.
  6. Draft, not merge. Agents open PRs as drafts and a person does every merge. Strong proof never merges a PR on its own, and there’s no timed auto-merge, after an hour or any other wait.
  7. Optional post-fix swarm. After a fix PR, two or three agents can probe the fixed app, one clicking around at random. They gather evidence and ping a person. They never merge, and the step isn’t always on.

Sources and credits

Ideas are credited as themes. Quotes are copied from the linked sources. Numbers that appear in titles are the authors’ own claims, not Crank figures.

How this page was made

Model: Composer 2.5 (composer-2.5, from this run’s metadata), with Grok as fallback, in one Cursor cloud agent run with no subagents.

Token total: missing. The run metadata available to the agent doesn’t report a token count or cost, so no total is shown and none was estimated.

Built 5 October 2026 from Cal’s brief; wording refreshed 7 October 2026; Architecture section added 12 October 2026. Build note: src/e/agent-engineering-map/BUILD-NOTE.md.