fileops: Agentic Engineering

The friction

AI coding agents change files one at a time. Rename a function across ten files and that's ten separate steps, each one a chance to fail. When step seven breaks, you're left with a half-finished change: some files updated, some not, and the cleanup is on you. There was no way to tell the agent "make all of these changes together, or don't touch anything."

agent → write auth.py       ✓
agent → write auth_test.py  ✓
agent → delete auth_old.py  ✓
agent → write routes.py     ✗  ← failure here
                                 three files changed, one didn't
                                 rollback is manual

The insight

Databases solved this problem decades ago. A transaction either commits in full or rolls back to where it started; you never see a half-written state. File changes had no equivalent for this workflow. So I built one: declare every operation up front in a single spec, and let the tool guarantee the all-or-nothing outcome

{
  "description": "refactor auth module",
  "operations": [
    { "type": "write",  "path": "src/auth.py",        "content": "..." },
    { "type": "write",  "path": "tests/auth_test.py", "content": "..." },
    { "type": "delete", "path": "src/auth_old.py" },
    { "type": "move",   "path": "src/routes.py", "destination": "src/api/routes.py" }
  ]
}

$ fileops run changes.json

✓ done  4/4 operations

  ✓  WRITE:  src/auth.py
  ✓  WRITE:  tests/auth_test.py
  ✓  DELETE: src/auth_old.py
  ✓  MOVE:   src/routes.py → src/api/routes.py

How it works

The core trick is to do all the risky work off to the side first, then swap everything into place in one fast, safe motion. New file contents are prepared as temporary copies and the originals are backed up. Only then does it commit. If anything fails partway, it undoes every step it already took and restores the originals, so you never see a broken in-between state

Proving it was real

A working prototype is not a finished tool. Most of the work happened after it ran the first time. I reviewed my own code and found six functional bugs, then wrote regression tests so they couldn't come back. I ran adversarial cases against it and fixed five more correctness and safety problems. I added handling for the ugly edge cases: preserving a file's permissions, refusing to silently clobber symlinked files, reporting honestly which operations rolled back instead of claiming success

The one I'm proudest of is smaller than all of that. I had written that the tool protected your data through a power loss. Reading my own claim closely, it didn't, not strictly: it guaranteed consistency through a crash, which is a different and weaker promise. So I narrowed the claim to match exactly what the code could back. The work was choosing accuracy over a better-sounding sentence