https://joshuaayson.com/explore/essays/ Essays from Joshua Ayson's blog en-us Mon, 10 Aug 2026 02:57:53 GMT Astro Copyright 2026 Joshua Ayson https://joshuaayson.com/2026/07/25/hello-again/ Three weeks ago I wrote about a script called hello, the one warm door into my system. I kept pulling the thread and the door turned out to be the outermost loop, the one that asks whether the whole thing can still become useful. This is what I found standing behind a greeting: cybernetics, nested watchers, and the rule that intelligence never gets its own hands. Sun, 26 Jul 2026 04:00:00 GMT https://joshuaayson.com/2026/07/25/hello-again/ essays Joshua Ayson https://joshuaayson.com/2026/07/19/same-score-half-the-time/ I failed another practice exam today. Same score as my best one, and my best is still a fail. But I finished in half the time and it felt easy in a way it never has, and I think the number is the last thing that moves, not the first. Mon, 20 Jul 2026 01:00:00 GMT https://joshuaayson.com/2026/07/19/same-score-half-the-time/ essays Joshua Ayson https://joshuaayson.com/2026/07/17/knowing-isnt-a-system/ I bought the IPO everyone wanted, and a quiet part of me narrated the mistake while I made it. The post-mortem found the real bug: a category I had built so I could skip my own system. Knowing isn't a system. Fri, 17 Jul 2026 20:00:00 GMT https://joshuaayson.com/2026/07/17/knowing-isnt-a-system/ essays Joshua Ayson https://joshuaayson.com/2026/07/15/the-loop-was-the-top-of-a-stack/ I typed my thirty-two loops, then drew them as a graph, and thought the loop was the top of the system. It turned out to be the roof of a stack eight floors deep, and the floor holding all the weight is the smallest one: the edge. Wed, 15 Jul 2026 16:00:00 GMT https://joshuaayson.com/2026/07/15/the-loop-was-the-top-of-a-stack/ essays Joshua Ayson https://joshuaayson.com/2026/07/14/one-writer-per-artifact/ Typing my automation handed me most of its rules for free; the type carries the contract. One rule came free with nothing, and it was the one my system was breaking: every file gets exactly one job that writes it. On the difference between rules you remember and rules the structure carries. Tue, 14 Jul 2026 22:00:00 GMT https://joshuaayson.com/2026/07/14/one-writer-per-artifact/ essays Joshua Ayson https://joshuaayson.com/2026/07/14/the-view-youre-missing-is-the-graph/ I gave every job in my automation a receipt, a health check, and a green light, and the system still would not fit in my head. A dashboard shows the state of the parts. The question I actually had was about the shape of the whole, and no amount of state answers a question about shape. Tue, 14 Jul 2026 20:00:00 GMT https://joshuaayson.com/2026/07/14/the-view-youre-missing-is-the-graph/ essays Joshua Ayson https://joshuaayson.com/2026/07/14/you-reinvented-data-engineering/ The best thing anyone told me about my own system this year was that I had not invented it. The scripts I grew by hand are a data pipeline, the shape is a DAG, and the discipline is solved. What the tools actually sell, why I am not buying yet, and the difference between wanting an engine and wanting a map. Tue, 14 Jul 2026 18:00:00 GMT https://joshuaayson.com/2026/07/14/you-reinvented-data-engineering/ essays Joshua Ayson https://joshuaayson.com/2026/07/14/a-loop-is-seven-things/ Thirty-two automated jobs run underneath my days, I wrote every one of them, and I could not hold the system in my head. The problem was never my memory. It was a word. "Loop" was one word doing the work of seven. Tue, 14 Jul 2026 16:00:00 GMT https://joshuaayson.com/2026/07/14/a-loop-is-seven-things/ essays Joshua Ayson https://joshuaayson.com/2026/07/12/finding-edgar-morin/ Edgar Morin died in May at 104, and I met him through his obituary. He spent eighty years on the question I have been building around: how to think inside the weave without cutting it apart. Two book reviews are coming. This is the marker I am leaving at the trailhead first. Sun, 12 Jul 2026 19:00:00 GMT https://joshuaayson.com/2026/07/12/finding-edgar-morin/ essays Joshua Ayson https://joshuaayson.com/2026/07/08/engineering-orientation/ Making complexity visible is the method. Orientation is the objective function. The research program now has an installable runtime, laboratories that keep their data, and its first pre-registered experiment, running on my own life. Does this thing improve a person's orientation while reducing their cognitive effort? You can ask that of a trading dashboard, a release pipeline, a journaling practice, a codebase map, and a language-learning routine, and it is the same question every time. That is what makes it an objective function instead of a slogan. Complexity becomes visible so that orientation improves. Visibility that does not buy orientation is decoration. The reframe also forced an admission. The mission statement has a measurable core, and measurable things can fail. Which is the point. A research program that cannot fail is a brand. ## The operating system move The correction exposed a structural problem. Complexence, as shipped, was something you read and then applied by hand. Every place I actually use it, my repositories, my daily practice, my projects, was generating observations and small results, and none of that could flow back into the science without dragging private life into a public repo. The fix is the oldest pattern in systems design. Linux never contains your documents. Git never contains your business. Terraform does not know your architecture. Each provides a language, your world runs on top of it, and the language never learns what your world is. Complexence is now that shape. The [public repository](https://github.com/OrganicArtsLLC/complexence) holds grammar, never knowledge: definitions, operators, role contracts, schemas, install tooling. Any project can install a thin scaffold and become a **laboratory**: it runs the roles, tracks its own experiments, logs its own measurements, and keeps every bit of its data. The only thing that ever travels back to the public repo is an abstraction, a pattern stripped of every domain noun, and it moves only after it has shown up in at least three different contexts. The discipline compresses to one line, and it is the load-bearing line of the architecture: labs are consumers of Complexence. They are not Complexence. I will not tell you what my labs are. That is the point of the design. What I can tell you is that the public repo now opens with a research index, every open question carrying an ID you can cite, so an experiment in a private lab can say precisely which public claim it feeds without saying anything else at all. ## The measure, and what it is not An objective function needs an instrument. This is where the most caution is required, because the failure mode of frameworks like this one is a formula that describes everything and predicts nothing. The candidate measure is called legibility, written Λ. The shape of it: a map of a system is worth what it provides in compression, prediction, and actionability, divided by what it introduces in distortion and costs in cognitive load. A system becomes legible when the ratio clears one, when the map gives more usable orientation than it costs or distorts. A bad map makes complexity simpler but false. A good map makes it simpler and more actionable. The mission restated with a threshold in it: making complexity visible means increasing Λ. As written, Λ is a picture of a trade-off, not a computation. The five factors live on no common scale, and they are not independent, compress harder and you distort more. What survives scrutiny today is smaller: hold the system fixed, compare two maps, and ask which one raises the ratio. That is an ordinal judgment. The cardinal number does not exist yet. Two of the five factors, how well the map predicts the system and what the map costs to use, can be grounded now, and their ratio is the defensible core. So Λ ships in the spec labeled as what it is: a candidate, a comparison scaffold, with its debts listed beside it. It becomes a real measure when a laboratory shows a Λ proxy tracking a real outcome. The theory already predicted this would be the hard part. Measurability is the whole bet. ## The first laboratory is my life The pilot lab is the one where I am both operator and subject, and its first experiment points at the instrument itself. Before any claim about measuring orientation, there is a prior question. Will the measurement happen at all? So experiment one is fourteen days of a single evening habit: one table row per day, did orientation go up or down, roughly why, on a scale that fits in a glance. The prediction is pre-registered, written down before a single row exists. If I fill the log at least ten days out of fourteen, and the scores agree with a blind re-reading of my own journal at least four times out of five, the instrument survives. If not, the instrument is too heavy, and that is the finding. It generalizes: a measurement scaffold that a motivated person will not fill in on his own life will not be filled in anywhere. Either way there is a result. The first one closes around July 21 and will be written up here whichever direction it points. The prior two experiments in this program came back null and invalid, and both write-ups are public, sitting in the repo next to the hope. The next one gets the same treatment, whatever it says. ## Out loud includes the mistakes One more thing happened on day one, and it belongs in the report. Within an hour of shipping the privacy boundary, I violated it by accident. A push carried old local history that still held a few private breadcrumbs, names of things I work on that have no business in a public repo. The guardrails written that same week contained their own remedy, and it ran: the history was rewritten clean within minutes, and the checker that guards every future commit now knows those words and refuses them. The boundary held because the rule existed before it was needed, and the rule did not care how I felt about force-pushing. That is the thesis in miniature. Systems outside your head, carrying the discipline your head will drop under load. ## Lab notes Every experiment that closes gets written up here, in a running series I am calling lab notes. Null results, invalid runs, instruments too heavy to use, and the occasional thing that works. Each note names the public research question it feeds, so the essays and the repository stay projections of one idea instead of drifting apart. The theory has a law about that drift, and I no longer get to ignore it. A theory that never touches an instrument stays a philosophy. The first instrument is already running. ## More on the idea underneath - [Complexence](/complexence/), the capability all of this serves. - [Complexence OS](/2026/06/25/complexence-os/), the daily method the labs install. - [The Science of Complexence](/2026/06/28/science-of-complexence/), the formal program these measurements feed. - [The open repository](https://github.com/OrganicArtsLLC/complexence), where the runtime, the research index, and the results live, including the failed ones.]]> Wed, 08 Jul 2026 16:00:00 GMT https://joshuaayson.com/2026/07/08/engineering-orientation/ essays Joshua Ayson https://joshuaayson.com/2026/07/03/hello/ The first program you write used to be the machine greeting the world. Hello, world. I built a different first program: my own system greeting me. One warm door instead of four scattered starters, and the greeting sits inside the loop it opens, so it can reach in and improve itself. Fri, 03 Jul 2026 18:00:00 GMT https://joshuaayson.com/2026/07/03/hello/ essays Joshua Ayson https://joshuaayson.com/2026/07/02/the-little-black-book-of-hansuru/ A book I wrote about selling options for income, built on one law: survive first. It shows a record most books would hide, and that is the reason it exists. Out now in Kindle and paperback. Thu, 02 Jul 2026 16:00:00 GMT https://joshuaayson.com/2026/07/02/the-little-black-book-of-hansuru/ essays Joshua Ayson https://joshuaayson.com/2026/06/28/science-of-complexence/ I built a method, pointed it at my own thirty-four repositories, and watched the sprawl become a page I could read. Then I tried to prove its deeper claim and the first experiment came back null. Under the practice is a field: the science of complexence, the loop as a recursive equation, meaning velocity, and the cognitive form, an idea held apart from how you say it. A research program, published openly, nulls and all. Sun, 28 Jun 2026 18:00:00 GMT https://joshuaayson.com/2026/06/28/science-of-complexence/ essays Joshua Ayson https://joshuaayson.com/2026/06/25/complexence-os/ Complexence is the capability of staying oriented inside complexity. Complexence OS is the rough machine I built today to run it: you talk into a file, one Chief of Staff agent sorts what you said and hands the rest to a few specialist roles, and you review only the exceptions. Day one of going from AI assisted to agent director. The method is open source; your data stays yours. one router -> specialist roles -> durable artifacts -> weekly review ``` You capture by speaking into a dated inbox file. You route the whole inbox through one prompt, a Chief of Staff. It does not try to be clever. It cleans each spoken entry into readable prose without changing your words, classifies every item, scores how sure it is, and either handles the item or hands it to a specialist. Then it writes one daily brief with five sections: your top three, what it processed, what is waiting on you, what is blocked, and one forward action. You read the top three and the blockers. You ignore the rest, because the rest is done. Behind the router is a capped set of specialist roles, six to start. One maps the terrain of my repositories so I can see what changed. One drafts and stages writing. One keeps a census of the system. One plays critic. None of them act on the world without me. The cap matters as much as the roles. The temptation with agents is to keep adding them until you have a committee you now have to manage, and a committee is just complexity wearing a helpful face. Six roles I can name and trust beats twenty I have to supervise. A few of them are barely past a prompt and a hope right now. On day one that is fine. The shape is the point, and the shape held. The reviewing is the discipline, and it is deliberately tiny. A five section brief, mostly blockers. If I am tired, capture is enough, and the system tolerates a day or two of lag without breaking. The point of the whole design is that on my worst day the obligation is still just: talk into the file, save. A system is for the version of you that won't listen; [I learned that one the expensive way](/2026/07/17/knowing-isnt-a-system/). ## The rule that makes it safe to hand over The reason I will let an agent run unattended is that it physically cannot do the dangerous things. When the Chief of Staff runs on its own, it has file tools and nothing else. No posting, no pushing, no deploying. If I ask it to publish something, it does not publish. It stages the thing privately and leaves me a single yes or no decision. Going public is always me, by hand, on purpose. That is the line the whole system is built around, and it is the same instinct as the [antifragile](/2026/05/30/living-with-antifragility/) one. Let the machine take the volatility you do not want, the drudgery and the filing and the first draft, and keep for yourself the few moves that are irreversible. Automate the recoverable. Gate the permanent. An assistant you have to watch every second is not saving you anything. One that is structurally incapable of the catastrophic case is a different kind of tool. ## Why I made the method public I open sourced the method, not my life. The public repository, [the Complexence repo on GitHub](https://github.com/OrganicArtsLLC/complexence), holds the specification, the role prompts, and blank templates. It does not hold a single one of my captures or outputs. Those live in a private instance the repository is built to keep out, with a guard that refuses to commit your real data. The method is the part that generalizes. The data is the part that never should. The prose is licensed CC BY 4.0 and the scripts are MIT, so you can take it, adapt it, run it at work or for a project, and change only the nouns: your own categories, your own arenas, what a finished artifact means to you. I did not want to ship an app. Apps decide for you. This is a method you instantiate, which means you stay in charge of the shape of it. The reason it is public is that complexence is [trained, not issued](/2026/06/17/complexence/), and the training goes faster when the scaffolding is already standing. I spent a long time building the trellis. There is no reason you should have to build the same one from scratch before you get to the part that actually grows you. ## What it is really for I did not build this to be productive in the magazine sense. I built it because the world keeps getting more complex and I refuse to answer that by making myself smaller. The machine is not the point. The capability is the point. The machine just clears the desk so the capability has room. You talk. One agent sorts it. You review only what truly needs you. Everything else becomes a durable artifact you can find later, and when the loop holds, it closes on its own. That is the externalized half of standing inside complexity without coming apart. I keep the judgment. The system keeps the structure. This is day one. For a couple of years my work has been AI assisted, me at the keyboard with a fast helper at my elbow. Tonight it crossed into something else: me directing a small set of agents and reviewing what they hand back. From AI assisted to agent director, in one tired evening, with a setup that half works and a year-old Slack app holding part of it together. It will grow and get less brittle over the coming days, and I will post a followup when it has earned one. The direction is what I wanted to mark. It starts, still, with me talking into a file and saving. ## How I am actually doing it None of this is fancy, and that is the point. The whole thing runs on one Mac at home. Capture is dumb and local. I hit an iOS Shortcut on my phone, talk, and it drops the recording into a Shortcuts folder in iCloud. A small loop on the Mac watches that folder, and when a new memo arrives a local Whisper model (faster-whisper, the small English model, on the CPU, no cloud and no API) turns it into text and writes it into the day's note. The thing that hears me never leaves the machine. That voice path is one of the two ways in. The other is typing to Marcus in Slack, for the times I would rather not talk. Two different doors, the same route, the same place it ends up. The piece I did not expect to need was Slack. Partway through I realized a capture-only loop is half a loop. If the system can take what I say but cannot say anything back, I am still tied to a terminal to find out what it did. So I wired in a Slack app I built last year and never finished, two-way, over Socket Mode. Now the loop talks back. It DMs me the brief and the blockers, and I can DM it a new thought from my phone without opening a terminal or even speaking. That one change is what turned it from a script I run into a thing I have a conversation with. The rest, for now, is held together with tape, and I am fine saying so. I reach the Mac from my phone over Tailscale, a small private network, with Termius as the terminal. The session drops on me constantly, which is half the reason the Slack back channel matters as much as it does. I keep meaning to live inside tmux so the work survives a disconnect, but its scrolling fights me, so for now I just reopen Termius and resume the agent session where it died, and I have learned to tell the agent to run anything long as its own detached process so a dropped phone connection cannot kill it halfway. It is day one, and it looks like day one. This very post got staged that way, by an agent that finished the job after my session had already fallen over. So there are two ways in, voice and Slack, and they both lead to the same place: one dated markdown file that gets written once and is never edited after. Everything downstream, the briefs, the artifacts, the dashboards, is derived from that one file. Two inputs, one source of truth, written once. That rule is boring, and it is the whole reason I trust the thing not to quietly rewrite its own memory. I know there are a dozen better ways to build this, and people who would do it cleaner in an afternoon. That is fine. This is iteration one, my first rough pass at it, and I like the spirit of the thing more than I am bothered by the seams. Mostly I am just excited about what comes next. ## More on the idea underneath - [Complexence](/2026/06/17/complexence/), the capability this whole system exists to grow, and [The Science of Complexence](/2026/06/28/science-of-complexence/), the formal floor under it, where the cognitive form this machine passes around is the kernel object. - [Making complexity visible](/2026/06/02/making-complexity-visible/), the mission, and [coherent complexity](/2026/06/02/coherent-complexity/), the framework under it. - [Living with antifragility](/2026/05/30/living-with-antifragility/), the instinct behind gating the irreversible. - [Finding Edgar Morin](/2026/07/12/finding-edgar-morin/), the man who worked this same mountain for eighty years as epistemology while I work it as operations.]]> Thu, 25 Jun 2026 22:00:00 GMT https://joshuaayson.com/2026/06/25/complexence-os/ essays Joshua Ayson https://joshuaayson.com/2026/06/24/germane-friction/ The fight over whether AI is good or bad is the wrong fight. AI is a friction-removal engine, and there are two kinds of friction: the kind that is building you, and the kind that is only taxing you. Telling them apart, in the moment, is the whole skill. Wed, 24 Jun 2026 23:00:00 GMT https://joshuaayson.com/2026/06/24/germane-friction/ essays Joshua Ayson https://joshuaayson.com/2026/06/24/the-case-for-ai/ Most defenses of AI are about productivity, and they are weak. The strong case is older and bigger: this is the next rung on a seventy-year ladder of removing effort that was never building anyone. Here it is, made at full strength. Wed, 24 Jun 2026 22:00:00 GMT https://joshuaayson.com/2026/06/24/the-case-for-ai/ essays Joshua Ayson https://joshuaayson.com/2026/06/24/the-case-against-ai/ AI does not destroy your work in front of you. It moves the cost somewhere you cannot see: to later, to the invisible, to the version of you that stops getting built. The strongest case against leaning on it, made in full. Wed, 24 Jun 2026 21:00:00 GMT https://joshuaayson.com/2026/06/24/the-case-against-ai/ essays Joshua Ayson https://joshuaayson.com/2026/06/23/why-my-repos-needed-a-census/ I had thirty-three git repositories and treated all thirty-three as if they were on fire. The fix was not more discipline or a better tool. It was a census: an inventory, an edge, and a rule for what counts as alive. Domain cartography applied to my own sprawl. Tue, 23 Jun 2026 23:30:00 GMT https://joshuaayson.com/2026/06/23/why-my-repos-needed-a-census/ essays Joshua Ayson https://joshuaayson.com/2026/06/23/how-to-map-a-domain/ The hardest part of mapping a complex domain is the blank page. Here are the six layers I run every domain through, from primitives to levels, with the question each one answers, how to actually do it, and the failure mode that shows up when you skip it. Tue, 23 Jun 2026 22:30:00 GMT https://joshuaayson.com/2026/06/23/how-to-map-a-domain/ essays Joshua Ayson https://joshuaayson.com/2026/06/23/domain-cartography/ Domain cartography is the practice of charting a complex domain you have to live and act inside, until it is legible enough to navigate. Not making it simple. Making it readable. Here is the field, the method, and the six layers every map needs. Tue, 23 Jun 2026 21:00:00 GMT https://joshuaayson.com/2026/06/23/domain-cartography/ essays Joshua Ayson https://joshuaayson.com/2026/06/17/complexence/ Complexity is the condition of the world. Complexence is the quality you bring to it: the capability of standing inside a system larger than yourself, seeing it whole, and still choosing. A word for the thing all my work has been about. Wed, 17 Jun 2026 21:00:00 GMT https://joshuaayson.com/2026/06/17/complexence/ essays Joshua Ayson https://joshuaayson.com/2026/06/17/compressed-or-destroyed/ The same tool that can fold a beginner's learning curve shorter can also erase it. AI compresses apprenticeship when it transfers expertise and destroys it when it lets people skip the repetitions that were quietly teaching them. Wed, 17 Jun 2026 19:00:00 GMT https://joshuaayson.com/2026/06/17/compressed-or-destroyed/ essays Joshua Ayson https://joshuaayson.com/2026/06/17/botsitting/ The subscription is the small line. The real meter is the time you spend feeding context, checking output, catching the confident mistake, and cleaning up the work that looked finished. That hidden labor has a name now: botsitting. Wed, 17 Jun 2026 18:00:00 GMT https://joshuaayson.com/2026/06/17/botsitting/ essays Joshua Ayson https://joshuaayson.com/2026/06/17/rhetoric-is-the-physics-of-other-minds/ If AWS is math and Kubernetes is physics, then discourse is the physics of other minds, the same live, empirical, pushes-back system, except the matter is a person and the latency is a blank stare. Why the studio and the arena are two different rooms, why the second one floods you, and how to build the faculty that levels the field. Wed, 17 Jun 2026 17:00:00 GMT https://joshuaayson.com/2026/06/17/rhetoric-is-the-physics-of-other-minds/ essays Joshua Ayson https://joshuaayson.com/2026/06/17/the-jagged-frontier/ AI is strong in one place and confidently wrong half a step over, and from the inside the two feel identical. The real skill is not prompting. It is knowing when to delegate, when to steer, when to verify, and when to think alone. Wed, 17 Jun 2026 17:00:00 GMT https://joshuaayson.com/2026/06/17/the-jagged-frontier/ essays Joshua Ayson https://joshuaayson.com/2026/06/17/the-real-bill-for-ai-at-work/ The invoice for AI is the cheap part: a seat and some tokens. The real bill arrives in four ledgers: financial, attention, coordination, and development. Why AI makes the individual feel fast while the organization barely moves. Wed, 17 Jun 2026 16:00:00 GMT https://joshuaayson.com/2026/06/17/the-real-bill-for-ai-at-work/ essays Joshua Ayson https://joshuaayson.com/2026/06/16/the-patient-part/ My head does not run in a line, it runs in branches. A tool arrived that does the exact part I cannot do and amplifies the exact part I already do too much. On building with an agent when your attention has its own ideas. Tue, 16 Jun 2026 16:00:00 GMT https://joshuaayson.com/2026/06/16/the-patient-part/ essays Joshua Ayson https://joshuaayson.com/2026/06/15/aws-is-smaller-than-it-looks/ AWS is taught as two hundred services. Underneath it is a handful of primitives, and every service is a frozen answer to a distributed-systems trade-off. The map I built studying for the SAA-C03, and the two questions that decode any new AWS service. Mon, 15 Jun 2026 17:00:00 GMT https://joshuaayson.com/2026/06/15/aws-is-smaller-than-it-looks/ essays Joshua Ayson https://joshuaayson.com/2026/06/14/the-language-of-sound/ I could already make sound. I could not name it, and you cannot ask for a thing you cannot name. So I asked my music engine for a map. This is that map: sound built in altitudes, and the words that let you climb it. Sun, 14 Jun 2026 16:00:00 GMT https://joshuaayson.com/2026/06/14/the-language-of-sound/ essays Joshua Ayson https://joshuaayson.com/2026/06/13/ai-agents-across-many-repositories/ There are thirty-three repositories in my workspace, and I cannot hold more than two of them in my head at once. They sit side by side in one folder, but it is not a monorepo. Each is its own indepen... Sun, 14 Jun 2026 05:00:00 GMT https://joshuaayson.com/2026/06/13/ai-agents-across-many-repositories/ essays Joshua Ayson https://joshuaayson.com/2026/06/13/password-protect-cloudfront-static-site/ A static site has no server to check a password, which is fine right up until the day you need one. My staging site is the problem in miniature. It is a full mirror of production, except it also carr... Sun, 14 Jun 2026 03:00:00 GMT https://joshuaayson.com/2026/06/13/password-protect-cloudfront-static-site/ essays Joshua Ayson https://joshuaayson.com/2026/06/13/handwriting-ocr-with-ai-vision/ Tesseract could not read a word of it. I have years of handwritten journals, the actual paper kind, and I wanted them on this site. The obvious first move is optical character recognition, and the ob... Sun, 14 Jun 2026 01:00:00 GMT https://joshuaayson.com/2026/06/13/handwriting-ocr-with-ai-vision/ essays Joshua Ayson https://joshuaayson.com/2026/06/13/compiling-a-blog-into-one-build-cache/ There is a 4.8 megabyte TypeScript file in my repository that I did not write. A script writes it, on every build, and I commit the result into git like it was mine. Most build advice would tell me th... Sat, 13 Jun 2026 23:00:00 GMT https://joshuaayson.com/2026/06/13/compiling-a-blog-into-one-build-cache/ essays Joshua Ayson https://joshuaayson.com/2026/06/13/how-to-detect-ai-writing-tells/ The em dash is the easy one. I can catch every em dash I will ever type with about nine lines of shell, and I do, on every commit. The script walks my published posts and the book chapters and fails ... Sat, 13 Jun 2026 21:00:00 GMT https://joshuaayson.com/2026/06/13/how-to-detect-ai-writing-tells/ essays Joshua Ayson https://joshuaayson.com/2026/06/13/content-security-policy-static-site/ A strict Content-Security-Policy on a static site allowlists inline scripts by hash. Change one script, forget to update the hash, and every page renders blank. The incident that taught me, and the deploy guard that ends it. ` block is by its hash. You take the exact bytes between the tags, run them through sha256, base64 the result, and put `'sha256-...'` in the policy. The browser hashes every inline script it finds and runs only the ones whose hash is on the list. One character different, different hash, blocked. That is the trap, and I walked straight into it. ## Why it broke I had edited one inline script. It is the small block in my base layout that sets the theme before the page paints, so dark-mode users do not get a white flash on every navigation. To do that without a flash, the script starts the page at `visibility: hidden` and then clears it once the theme is applied. Hide first, decide, reveal. I changed one line in that block. Reformatted it, really. The behavior was identical. But the bytes were not, so the hash was not, and the CloudFront policy still listed the old hash. The browser found the script, hashed it, did not find a match, and refused to run it. The script that never ran was the one whose entire job was to undo `visibility: hidden`. So every page loaded its full HTML, sat there correctly structured and completely invisible, and waited for a reveal that the browser had just blocked. View-source showed all the content. The console showed the CSP violation. The page showed nothing. ## The fix, and then the real fix The immediate fix is mechanical. I have a script, `hash_inline_scripts.py`, that walks `dist/`, pulls every inline script that is not a JSON-LD data block, computes the sha256, and prints the allowlist. You run it after a build, take the new hashes, and update two places: the live CloudFront Response Headers Policy, and a `response-headers-policy.json` checked into the infrastructure repo so the policy is version-controlled instead of living only in the AWS console. Mirror them or they drift, and a drifted security policy is a bug you cannot see in the diff. That fixes the symptom. It does not fix the part where the whole thing depended on me remembering to do it at the exact moment I was thinking about something else. So the real fix is a guard. `pre-deploy-csp-check.py` runs before anything uploads. It scans the build for inline scripts that appear on a lot of pages, the common ones like the theme block and the navigation, because those are the scripts that take the entire site down rather than one page. For each common script it checks whether its hash is present in the live policy. If a hash is missing, the deploy fails. Loudly. Before a single file moves. The deploy now refuses to ship a site that would render blank. That is the sentence I actually wanted. Not "be more careful." The careful version had already failed once and it will fail again, because careful is a feeling and a build step is a fact. ## What I would tell you If you put a strict CSP on a static site, and you should, understand that inline scripts plus hash allowlisting is a sharp edge and plan for it on day one. You have two clean ways out. Move every script into an external bundled file so there is nothing inline to hash, which is the simplest if you can pay the small no-flash-theme cost. Or keep the few inline blocks you actually need, automate the hashing, and put a guard in front of the deploy so a stale hash can never reach production. I kept two inline blocks for the theme load and bought the safety with the guard. The general lesson is older than CSP. The most dangerous failures are the ones where the system is working perfectly and the configuration is wrong, because nothing throws, nothing logs an error, and the tool you would reach for to debug it is reporting success. A blank page with a 200 status and all its HTML intact is that failure wearing a costume. When something is impossible, check the thing that is succeeding. This is the same loop I run on everything now: when a failure teaches you something, you do not just fix it, you build the system that makes that failure impossible to ship again. I wrote about that habit in [Recursive DevOps](/2026/06/05/recursive-devops/), and about rebuilding this whole site under that discipline in [Rebuilt My Site in Agent Mode](/2026/06/03/rebuilt-my-site-in-agent-mode/). If you are choosing tools for this kind of work, my comparison of the two I lived in is [Claude vs Copilot for DevOps](/2026/06/02/claude-vs-copilot-for-devops/). The rest of the field notes live at [AI-assisted engineering](/ai-development/). The smallest place to start, though, is to go read your own deploy script and ask it one question: what is the worst thing it will let you ship without complaining? ## Update, June 2026: I took the simpler way out, and the guard earned its keep I am leaving the original below rather than quietly editing it, because the change of mind is the useful part. When I wrote this, I kept two inline blocks for the theme load and bought safety with the deploy guard, and I called moving everything to external files the simpler way out that I had chosen not to take. Then I went to upgrade the framework, and the guard caught exactly what it was built to catch: the new version re-minified one of those inline scripts on its own, the hash changed, and the deploy stopped itself before it could blank the site. The cost I had dodged by keeping the scripts inline came due, on a change I did not control. It was a strange thing to be happy about a failed deploy, but that is the whole point of the guard, and here it was doing the job in the wild. So I took the way out. The interactive scripts now live in their own files, served from the site itself, with nothing inline left to hash. The one piece I cared about most, the small block that reveals the page once the theme is set, got its own tiny file on purpose, so a bug anywhere else can no longer leave the page hidden. The no-flash cost I had braced for never really showed up, because that reveal was already waiting for the page to parse before it ran. I had been carrying the fragility without getting much for it. That groundwork paid off sooner than I expected. The larger upgrade I had been circling finally landed, the kind that rewrites a lot of generated code in one pass. Because the scripts were already external, there was almost nothing to re-bless by hand, just one small file the framework generates for an interactive page, where before it would have been a scramble across the whole site. A second check earned its keep the same day: the one that pings a short list of must-work pages after every deploy caught a page that had quietly changed address during the upgrade, and stopped the deploy before anyone could land on the empty spot. Fix, rebuild, confirm. The lesson did not change, it just got tested at a bigger size. The job was never to be more careful. It was to build the thing that is careful for me, and then to actually listen when it complains. What is left inline now is one stable block that the framework copies through untouched, so a version bump can no longer change a hash out from under me. The guard stays, but it has almost nothing left to guard. The setup in the original post was not wrong. It was the right call for the moment and the wrong call for the next one, which is most engineering decisions if you keep them long enough. Then I took the last step, and it is the part I am happiest with. A guard can only ever tell you a hash is missing; you still have to go fix the list. So I stopped keeping the list by hand at all. The deploy now reads the finished site, works out the exact set of scripts it actually contains, and writes that into the policy itself, every time, before anything goes live. A changed script, a new one, even a generated one I did not write by hand gets blessed on the way out the door. The list cannot fall behind the site, because the site is now what produces the list. That is the whole arc of this post in one move: I started by being careful, got burned, built a thing to catch me when I was not, and finally handed the care to the build entirely. The thing I wanted all along was not a safer habit. It was a system that stays correct without me remembering to keep it that way.]]> Sat, 13 Jun 2026 17:00:00 GMT https://joshuaayson.com/2026/06/13/content-security-policy-static-site/ essays Joshua Ayson https://joshuaayson.com/2026/06/12/agent-mode-vs-autonomous-mode/ Agent mode and autonomous mode get used interchangeably and they are not the same thing. The difference is who closes the loop: you, after every task, or the system, on a schedule. A working engineer's disambiguation. Fri, 12 Jun 2026 18:00:00 GMT https://joshuaayson.com/2026/06/12/agent-mode-vs-autonomous-mode/ essays Joshua Ayson https://joshuaayson.com/2026/06/12/how-i-use-ai-as-a-senior-engineer/ Not a tools list. The tools changed three times this year; what changed underneath is where the hours go: specs in the morning, batch review in the afternoon, and the judgment work that never left. Fri, 12 Jun 2026 16:00:00 GMT https://joshuaayson.com/2026/06/12/how-i-use-ai-as-a-senior-engineer/ essays Joshua Ayson https://joshuaayson.com/2026/06/11/ai-code-review-workflow/ The code got cheap. The review did not. Here is the review workflow I actually use when AI agents write most of the diff: three passes, an adversarial second agent, and the discipline of reading what ships. Thu, 11 Jun 2026 16:00:00 GMT https://joshuaayson.com/2026/06/11/ai-code-review-workflow/ essays Joshua Ayson https://joshuaayson.com/2026/06/08/working-at-the-frontier/ A field report from inside sustained agent-mode work: the heat behind the eyes, the way speed bends your sense of time, what it costs the body, and the practice that lets you build at the frontier anyway. I have started calling this the age of agents, and I draw the same small figure in the margin every time. Plan. Observe. Act. It is not only the speed. The results that come out of scaling cognition under the right direction are astounding, given the calibre of the output. What changes underneath is the shape of the work itself. The way you think about the job moves from implementation to design, to orchestration, to efficiency, to anything and everything in between. It is devops applied to the whole of it. That shift drives a real need, for technical ability and for familiarity, leaning harder than ever into architecture, into quality, into security, and into cost, all of it broken down continuously and accurately and kept attached to what it actually costs. Here is what I could not have written down eighteen months ago. This lets you leap-frog across domains. Once you have a general grasp of a new territory, its codex and its language, once the vocabulary is understood, there is great power waiting on the other side of it. With the right context and the right systems you get to a high standard in a field in far less time than it used to take, and you start to find what I call the edges. The places where, with proper tools and the meta-capability of these models to abstract models and patterns, you can take some of the most sophisticated machinery there is and model the domains, the systems, the cognition itself, and bring coherence to complexity. The overwhelming becomes navigable. The illegible becomes legible. You draw the maps that let you work near the furnace, close to the source of the heat and the energy, and still keep enough of yourself in reserve to make sense of it all, or to hold what has to be held, and carry it. Don't panic.]]> Mon, 08 Jun 2026 08:00:00 GMT https://joshuaayson.com/2026/06/08/working-at-the-frontier/ essays Joshua Ayson https://joshuaayson.com/2026/06/06/ai-assisted-engineering-howto/ A practical, plain-spoken manual for building software with an AI agent: the setup, the loop, context management, and verified Claude Code and Copilot commands. Written like the old Linux HOWTOs, by someone who runs it daily. invoked as /ship # put your standard pre-deploy steps in that file in plain language ``` After that, `/ship` runs your checklist the same way every time. This is the lock-it-down move from the next section, made concrete. ## 9. Lock it down, or leave it open There are two modes of working this way and you need both. Sometimes I want the creativity of not locking things down. I give the agent room, leave the constraints loose, and let it surprise me. I try to encourage artistry in the outcome and in the system itself, not just correctness. This is the same instinct I bring to freewriting, the practice I call consciousness mining: keep the prompt loose, stay honest, get the ego out of the way, so something I did not plan has room to surface. You are fishing, and you want a wide net. A tight spec here kills the thing you were reaching for. Other times I build for repetition and lock it down hard. A clear ADR. A strict memory file. Fences around the dangerous code. A custom slash command so the steps never drift. A task specified so tightly there is one reasonable result. That is the mode for work that has to be right and has to be the same every time. The skill is knowing which one you are in. Leave a production change loose and you ship a subtle bug. Lock down an exploration and you kill the surprise you were after. Decide on purpose, at the start, which mode the task is, and do not drift between them by accident. ## 10. Common failure modes and how to fix them Symptom, then cause, then fix. **The output looks right and is subtly wrong.** Cause: you verified the build, not the behavior. Fix: exercise the actual feature. I once moved a site to a private origin; the change was correct except the new origin did not serve directory index files, so every subpage would have broken. The build was green. I caught it by loading a real page, not by trusting the log. **It keeps reintroducing a mistake you fixed.** Cause: the correction lives in your memory, not the project's. Fix: write the rule into the memory file so it survives the session. **Its answers start drifting and getting vague.** Cause: the context window is full of stale history. Fix: `/clear` for a new task, or `/compact` to keep the thread but drop the noise. Check `/context` when in doubt. **It changed something you did not ask it to.** Cause: the task was broader than you thought, or the danger zone was not fenced. Fix: narrow the task, mark the protected areas in writing, reset to your last commit. **It is slow and you want to just write it yourself.** Cause: the task is small enough that specifying it costs more than doing it. Fix: do the small ones yourself. The loop earns its keep on tasks big enough that direction beats typing. Not everything should be delegated. **You shipped fast and now you do not understand your own system.** Cause: you skipped the record step, and speed without memory is debt. Fix: slow down on the decisions, write them down, read the diffs you waved through. The cognitive bill is real and it comes due. ## 11. Frequently asked questions **Claude Code or Copilot agent mode?** I use both. Terminal for parallel and large work, the editor for small visual changes. They run the same loop. My longer comparison for engineering work is in [Claude vs Copilot for DevOps](/2026/06/02/claude-vs-copilot-for-devops/). **Sonnet or Opus?** Sonnet for almost everything; it is fast and it is enough. Opus for the hard reasoning: thorny architecture, a bug that survived two attempts, a plan with many parts. Switch with `/model`, then switch back. **CLAUDE.md or copilot-instructions.md?** Both, if you use both tools. Claude Code reads `CLAUDE.md`; Copilot agent mode reads `.github/copilot-instructions.md`. Keep both, keep them in sync. They are additional, not a choice. **Is this just vibe coding with extra steps?** No, and the difference is the whole thing. Vibe coding skips specify and verify. This method is built on them. See [AI-Assisted Development Is Not Vibe Coding](/2026/05/07/ai-assisted-development-is-not-vibe-coding/). **Can I let it run on its own?** Sometimes, with care. Autonomous mode runs the loop without you in it. When to trust it is its own question, covered in [What Is Autonomous Mode?](/2026/06/02/what-is-autonomous-mode/). **Does this replace software engineers?** No. It moves the work. The cost of writing code fell; the cost of deciding what to build did not. [How AI Is Changing Software Engineering](/2026/05/27/how-ai-is-changing-software-engineering/) is the long answer. **Does this apply to infrastructure?** Yes, and the payoff compounds there. The same loop runs on Dockerfiles, CI pipelines, and infrastructure code. [Recursive DevOps](/2026/06/05/recursive-devops/) is where I take that to its end. ## 12. Where to go next This document is the entry point. The cluster behind it goes deeper: - [AI-Assisted Engineering](/ai-development/), the hub that collects every essay and field note in one place. Start there if you want the map. - [How AI Is Changing Software Engineering](/2026/05/27/how-ai-is-changing-software-engineering/), the field report on where the bottleneck moved. - [An AI Agent Workflow for Software Engineers](/2026/06/02/ai-agent-workflow-for-software-engineers/), the core loop in full. - [Agentic AI Development: How to Build Software with AI Agent Workflows](/2026/05/30/agentic-ai-development-workflows/), the cornerstone on giving an agent real repository access and directing it. - [DevOps Beyond Automation](/2026/05/27/devops-beyond-automation/), what compounds across a long engineering career. - [AgentSpek](/books/agentspek/), my book on building this way, free to start reading here. All of this is the practical application of one larger idea I keep coming back to, [making complexity visible](/making-complexity-visible/): keeping a system understandable enough to navigate without pretending it is small. AI-assisted engineering is where I apply it every day. ## 13. A note on the meta I built this manual the way it tells you to build software. I specified it, delegated the draft to an agent in the exact agent mode described above, verified every command against the live tools, and recorded the decisions as I went. The document is an instance of its own method. That is the meta. The meta of the meta is the memory file. The `CLAUDE.md` and the voice rules that governed how this got written are the same kind of standing intent section 4 tells you to keep, pointed at prose instead of code. The thing that shaped the writing is itself a project memory file. And the Übermeta, with the umlaut it has earned: the method applies to itself, all the way up. Building the thing, writing about building the thing, and setting the rules for how that writing is done are one loop running at three heights. This is [Recursive DevOps](/2026/06/05/recursive-devops/) pointed at language. The system that makes the work and the system that improves the system are the same system. Once you see it you do not unsee it. Good. Now go build something. ## Appendix A: A starter memory file Drop this at the repo root as `CLAUDE.md` for Claude Code, and as `.github/copilot-instructions.md` for Copilot agent mode. Same content, both files. Fill in the brackets. Keep it short and true; a file that lies to the agent is worse than no file. ```markdown # Project Memory ## What this is [One or two sentences. What the project does, who uses it.] ## How it is built and run - Install: [command] - Dev: [command] - Test: [command] - Build: [command] ## Conventions that matter - [The naming, structure, or style rules you actually enforce.] - [How errors are handled here.] - [Anything a newcomer always gets wrong.] ## Do not touch without care - [Files or systems that are load-bearing and easy to break.] - [The rule for changing them.] ## Lessons (append as you go) - [Mistakes the agent made, so it stops repeating them.] ``` ## Appendix B: Spec and ADR templates Two more good ideas worth keeping as templates. The first is for the Specify step: write the intent before you prompt. The second is the ADR I keep one of per real decision. A spec you hand the agent: ```markdown # Intent: [one-line outcome] ## Outcome [What is true when this is done.] ## Constraints - [What it must not break.] - [What it must stay compatible with.] ## Non-negotiable - [The parts there is no flexibility on.] ## Done when - [The check that proves it works: behavior, not exit code.] ``` An ADR you write when you decide something real: ```markdown # ADR-[NNN]: [the decision in a few words] **Status:** [Proposed | Accepted | Superseded] **Date:** [YYYY-MM-DD] ## Context [The situation that forced a choice.] ## Decision [What we are doing, in plain language.] ## Consequences [What this makes easy, what it makes hard, what we gave up.] ``` ## Appendix C: Command cheat-sheet The commands from this manual in one place. Terminal commands are for Claude Code; the slash commands run inside a session. ```bash # Start and choose a model claude # interactive session in the current repo claude --model sonnet # start on Sonnet (default for daily work) claude --model opus # start on Opus (hard reasoning) # Pick up past work claude --continue # resume the most recent session here claude --resume # choose from past sessions # Headless, for scripts and pipes claude -p "one-shot prompt" # run once and exit cat file.log | claude -p "..." # pipe input in # Parallel agents via git worktrees git worktree add ../proj-x -b feature-x git worktree list git worktree remove ../proj-x ``` ```text # Inside a session /model opus | /model sonnet # switch model mid-task /context # what is filling the context window /clear # wipe conversation, keep the memory file /compact # summarize and continue /init # generate a starter CLAUDE.md /memory # show loaded memory files /agents # configure subagents Shift+Tab # cycle permission modes (ask / auto-edit / plan) Esc # interrupt a run that is going wrong ``` ## About this document Written by Joshua Ayson, a DevOps engineering leader who builds this way every day. Corrections and better tips are welcome; like the HOWTOs I learned from, this one gets revised. - *Revision 1.0, June 2026.* First cut: setup, the loop, tips, failure modes. - *Revision 1.1, June 2026.* Added the tools I actually use (Claude Code and Copilot agent mode), the memory-file split, context and token management, verified commands, and a cheat-sheet. If it saved you an afternoon, it did its job.]]> Sat, 06 Jun 2026 17:00:00 GMT https://joshuaayson.com/2026/06/06/ai-assisted-engineering-howto/ essays Joshua Ayson https://joshuaayson.com/2026/06/05/the-cognitive-cost-of-modern-software-engineering/ AI took the typing, and the cost of software engineering did not go away. It moved from the hands to the head and got heavier. The new scarce resource is your attention, and the new discipline is managing it. Fri, 05 Jun 2026 22:00:00 GMT https://joshuaayson.com/2026/06/05/the-cognitive-cost-of-modern-software-engineering/ essays Joshua Ayson https://joshuaayson.com/2026/06/05/recursive-devops/ DevOps was always a feedback loop. The first one ran between people. The one worth building now runs the system back on itself, so every failure and every change makes the next one cheaper and safer. The recursion is the compounding. Fri, 05 Jun 2026 21:00:00 GMT https://joshuaayson.com/2026/06/05/recursive-devops/ essays Joshua Ayson https://joshuaayson.com/2026/06/05/agent-mode-changes-the-shape-of-thought/ Agent mode is not a faster way to type. It moves the unit of thought up from syntax to intent, turns you into a conductor of parallel work, and makes the real bottleneck the clarity you can hold in your head at once. Fri, 05 Jun 2026 20:00:00 GMT https://joshuaayson.com/2026/06/05/agent-mode-changes-the-shape-of-thought/ essays Joshua Ayson https://joshuaayson.com/2026/06/03/microservices-agents-what-im-building-next/ Microservices used to be a tax a solo builder could not afford. AI agents change that math. Here is why I am drawn to the architecture for what I build next, and the discipline that keeps it from becoming a mess. Wed, 03 Jun 2026 19:00:00 GMT https://joshuaayson.com/2026/06/03/microservices-agents-what-im-building-next/ essays Joshua Ayson https://joshuaayson.com/2026/06/03/agent-mode-iron-man-suit/ The suit never replaced Tony Stark. It amplified him. That is the closest thing I have to a description of what it feels like to build software in agent mode, directing one or many agents and scaling your own thought and output. Wed, 03 Jun 2026 18:00:00 GMT https://joshuaayson.com/2026/06/03/agent-mode-iron-man-suit/ essays Joshua Ayson https://joshuaayson.com/2026/06/03/rebuilt-my-site-in-agent-mode/ This site was rebuilt from scratch by directing an AI agent, then migrated off cPanel onto AWS S3 and CloudFront. Here is what that actually looked like, the parts that worked, and the day a deploy script quietly deleted production. Wed, 03 Jun 2026 17:00:00 GMT https://joshuaayson.com/2026/06/03/rebuilt-my-site-in-agent-mode/ essays Joshua Ayson https://joshuaayson.com/2026/06/02/what-is-autonomous-mode/ Autonomous mode is when the agent runs the whole loop without you in it: plan, act, check, repeat, until the task is done or it gets stuck. Here is what that means, how it differs from agent mode, and where the real risk lives. Tue, 02 Jun 2026 17:30:00 GMT https://joshuaayson.com/2026/06/02/what-is-autonomous-mode/ essays Joshua Ayson https://joshuaayson.com/2026/06/02/ai-agent-workflow-for-software-engineers/ A practical, repeatable workflow for building software with an AI agent: specify, delegate, verify, record. The loop I actually run every day, with the parts that keep it from turning into slop. Tue, 02 Jun 2026 17:00:00 GMT https://joshuaayson.com/2026/06/02/ai-agent-workflow-for-software-engineers/ essays Joshua Ayson https://joshuaayson.com/2026/06/02/making-complexity-visible/ When a system gets too big to hold, almost everyone reaches for the same move: make it simpler. It is the wrong move. You cannot simplify the ocean. You can only chart it. This is about the difference between simplicity and legibility, why decisions quietly migrate to whoever holds the context, and how to make a complex system visible enough to navigate without pretending it is small. Tue, 02 Jun 2026 17:00:00 GMT https://joshuaayson.com/2026/06/02/making-complexity-visible/ essays Joshua Ayson https://joshuaayson.com/2026/06/02/claude-vs-copilot-for-devops/ I use GitHub Copilot at work and the Claude Code CLI at home, every day. Here is the firsthand comparison for DevOps and infrastructure work, from someone who ships with both, in the context each one actually lives in. Tue, 02 Jun 2026 16:30:00 GMT https://joshuaayson.com/2026/06/02/claude-vs-copilot-for-devops/ essays Joshua Ayson