Skip to content
← Back to writing

May 18, 2026

How I actually build software in 2026

Human-led construction, agent-led maintenance. The honest middle between AI hype and AI denial.

How I actually build software in 2026: human-led construction, agent-led maintenance.

The real PR #65 the post cites: git show on 97a88670 in eightly-os, <button type="button" class="ticket-ref" data-ticket="EP-11">EP-11</button> through <button type="button" class="ticket-ref" data-ticket="EP-15">EP-15</button>, splitting five monolith handler files into 28 focused modules — pkg/api/health/alerts.go landing at exactly the 246 lines this post quotes.

This is a living document. It keeps me honest about my real workflow, so every public repository I ship can point back to one consistent source of truth instead of marketing-flavored hand-waving.


The short version

Agents are not yet ready to build production software from scratch. They can maintain production software that has already been built well. Most people telling you otherwise in 2026 have either not tried to ship a real product end-to-end, or are selling you the framework.

My workflow today:

  1. A human (me) owns the architecture, scope, sequencing, and acceptance criteria.
  2. Claude Code does the implementation, inside a written architectural contract codified in CLAUDE.md (Go files max 1,000 lines, frontend max 500 lines, shadcn-only UI, atomic writes, no raw exec.Command).
  3. I review the work in my browser, against the live dev URL, with a second AI assistant in a Chrome extension that reads the DOM, writes verification scripts, and produces auditor-style review specs that go back to Claude Code as the next ticket.
  4. A multi-model adversarial pass (Grok, ChatGPT) gets used for architectural decisions, security-sensitive code, and tricky edge cases.
  5. Changes ride a real dev to staging to prod pipeline with feature branches, CI-built images, and tight blast-radius rules per environment.
  6. I accept the final diff at the prod boundary, or send it back through the loop.

This is a deliberately supervised loop with a senior operator routing decisions. Most "agentic" pitches skip that part, and it is what makes the work actually ship.

Once a codebase reaches a stable, well-tested, well-documented foundation, agents earn a seat: socials, marketing, updates, dependency PRs, documentation upkeep, customer-facing automation. This is boring, well-bounded work, where a wrong answer is cheap to throw away and a right one keeps paying off.

The real line is who owns the decisions with compounding blast radius. Construction is where the expensive, hard-to-reverse calls get made: architecture, data models, the foundations everything else sits on. A wrong call there costs weeks to unwind, so a human makes it. Implementation inside that decided shape is bounded and reversible; the worst case is that I reject the diff and the blast radius is one ticket. That is also why I can stack five AI reviewers without contradicting myself. Review is purely additive: a reviewer can only suggest, never decide, so a wrong comment costs nothing. The agent implements what I have already scoped and reviews what I have already built; it does not get to decide what gets built.

That is the thesis, and the rest of this document explains why I hold it, how I arrived at it, and what it means for every repo I ship.


What I actually believe about agents

The original auto-router from the homelabarr-cli days: one /auto-route command parsed the task and chained the right specialists in sequence, docker to network to security to monitoring to tests to docs, while enforcing the validation pipeline and the SDLC. It is the ancestor of the later dispatch model, not today's workflow.

I do not believe agents are hype, and I am not a recent convert to AI-assisted development; I have been using Claude Code since it shipped.

My first real agentic workflow lived inside smashingtags/homelabarr-cli (now archived) under .claude/agents/ and .claude/commands/. Sixteen Claude Code subagents, each with a defined role: Docker, network, security, and monitoring specialists, a test automator, a debugger, a deployment engineer, a documentation specialist, a project manager, a code reviewer, and the rest of a small org chart.

The piece that made it work was the auto-router. One slash command, /auto-route, lived at .claude/commands/auto-route.md. I typed it followed by a plain-English task description, and the router parsed keywords and context, picked the right specialist (or chained several in sequence for multi-domain work), ran the validation pipeline (YAML, JSON, lint, prettier), and enforced the SDLC: sprint validation, story point estimation by the matching domain specialist, branch naming convention feature/{ticket}-{description}, breaking change detection, QA pathway routing, and a standardized completion comment back to Jira.

Concretely: /auto-route "Add Jellyfin media server with Traefik routing, Authelia protection, and monitoring dashboards" would route to docker-infrastructure-specialist for container setup, then network-architecture-specialist for Traefik, then security-authentication-specialist for Authelia, then monitoring-alerting-specialist for dashboards, then test-automator for validation, then documentation-specialist to update the wiki. All from one command, the multi-agent dispatch wired into a real SDLC rather than a demo.

That was my workflow through most of the August 2025 build sprint and into early 2026. The auto-router pattern is the direct ancestor of the dispatch model that later showed up in Imogen.

When OpenClaw shipped, I tried it for about a month, stood up a hosting site and a media site next to it, and then took both down because I did not believe in the business and did not want the support load; I iterate fast and rip down fast.

I built Imogen as an OpenClaw operator. The scaffold is public at smashingtags/operator-kit, on npm as @imogenlabs/operator-kit: SOUL.md, IDENTITY.md, USER.md, AGENTS.md, TOOLS.md, HEARTBEAT.md, three-layer memory (daily logs, evergreen references, instinct YAML files), cron jobs, and optional multi-agent roles (orchestrator, coder, security, researcher). The IPAC methodology that backs it is at smashingtags/ipac. That stack is real, it works, and the methodology is public.

Right now, in May 2026, Imogen is not running my operations. She is built and idle. Back in March I let her dispatch a site update and she handed it to Claude Code, which rewrote the whole thing straight to production in about thirty seconds; that incident is part of why. I went back to driving Claude Code directly because at this stage of the products I am shipping, I do not want an autonomous agent making operational decisions on a codebase that is still being shaped. Once the software stabilizes, Imogen comes back online to handle the work she is good at: managing my socials, managing my LinkedIn, dependency updates, marketing posts, narrow well-bounded jobs where a bad call is low-cost and a good call compounds. That is Phase 3 work, and the products are not in Phase 3 yet.

Paperclip was a separate one-day experiment in March 2026. Four roleplay agents (CEO, marketing, content, engineer) orchestrated through Paperclip on top of the OpenClaw gateway. It was an interesting demo, but it is not what I use to ship Eight.ly OS, HomelabARR, or anything else with a customer attached to it.

So the truthful picture in May 2026:

  • Builder: Claude Code, driven by me.
  • Reviewer: me in the browser, with a Chrome extension AI assistant that audits live DOM, writes verification scripts, and drafts the next ticket.
  • Adversarial pass: Grok and ChatGPT on the work that warrants it.
  • Pipeline: dev to staging to prod, one VM per environment per product, CI-built images, Watchtower-driven prod promotion.
  • Operator (Imogen, on OpenClaw): built, idle, waiting for the software to stabilize before she gets the keys back.

Agents have a real job in 2026: narrow, well-bounded operational work on a stable system that a human designed. They are not ready to build your product without supervision, and I am not handing it to them.


The dev to staging to prod pipeline

How a change promotes: a feature branch off dev, local validation, a PR that CI builds multi-arch, the browser review on the dev URL, then dev to staging to main, gated by twelve required status checks that fail closed before anything reaches prod, where Watchtower auto-pulls the signed image.

Every product I ship rides the same three-environment flow that every real engineering org uses, just sized for one operator.

The branch model

  • Feature branches cut off dev for every change. Naming convention: feature/{ticket-id}-{short-description}, bugfix/{ticket-id}-{...}, or hotfix/{ticket-id}-{...}. Enforced by the auto-router pattern; PRs that do not match get rejected.
  • dev branch is the integration target. Feature branches merge here once the work passes local validation and the browser review loop.
  • staging branch is the pre-production candidate. Merged from dev once a slice of work is ready to be customer-facing. Mostly idle for products that have no public customer surface yet; comes online when a product earns one.
  • main branch is prod. Merged from staging (or directly from dev for products without an active staging gate). Tagged for releases. The only branch Watchtower watches for auto-promotion.

The environment topology

Each product gets its own isolated VM per environment so a bad deploy in one product cannot blast another. The pattern I run today, generalized:

  • <product>-dev: every dev branch lands here. URL: dev.<product-domain>. Fast iteration, broken state tolerated, used by me and the browser review loop.
  • <product>-staging: staging branch lands here when active. URL: staging.<product-domain>. Customer-facing-shaped traffic, but no real customers yet. Pre-prod smoke tests.
  • <product>-prod: main branch lands here, via auto-pull from the container registry. URL: <product-domain>. Real customers. Highest blast-radius rules.

Each VM has its own Docker socket. Customer app deploys never share a Docker socket across products. Dev and staging may share a VM within a single product if the surface area is small; prod is always isolated.

How a change promotes

The promotion path for any change, end-to-end:

  1. Cut a feature branch from dev. feature/HL-123-add-jellyfin.
  2. Build locally, test locally, run the local validation pipeline. YAML, JSON, lint, prettier, Playwright for UI work.
  3. Open a PR into dev. CI builds the multi-arch Docker image (linux/amd64 + linux/arm64) and pushes to GHCR with a branch-tagged image.
  4. Browser-based review loop on dev.<product-domain>. I open the dev URL, run an audit session, get a markdown spec back with root cause, fix, verification script, and PR draft. Spec gets committed alongside the work.
  5. Merge the PR into dev. dev VM auto-pulls the new image and redeploys. Smoke verification on dev URL.
  6. (When staging is active) Merge dev into staging. Same CI, same image format, lands on the staging VM. Final pre-prod checks here.
  7. Merge staging into main (or dev into main for staging-less products). CI builds and pushes the :latest tag to GHCR. Watchtower on the prod VM auto-pulls within the configured interval and redeploys with zero downtime if the image health-checks pass.
  8. Post-prod verification. Browser review loop runs one more pass against the prod URL with cache busting. Any regression is a P0 and gets handled before anything else.

Why three environments matter even solo

A common shortcut for one-person shops is "I just push to prod." I do not do that, and the reason is blast radius. Three environments mean:

  • dev absorbs the cost of iteration. Broken builds, half-finished features, in-progress refactors all live here. I can break dev twenty times in a morning and no customer notices.
  • staging absorbs the cost of integration surprises. Things that work in isolation on dev can fail when promoted because of environment differences (TLS, auth, real DNS, real cache headers). Staging catches those before they touch a paying user.
  • prod only sees code that has already survived two stricter environments. That is what lets a one-person shop deploy with the same confidence as a team.

It is the cheapest insurance policy I run, and it costs me a few VMs on my Proxmox cluster.

Promotion guardrails

These are written into the rules:

  • No raw exec.Command in production code. All shell calls go through helper wrappers with logging and timeouts.
  • All JSON state writes atomic. AtomicWriteJSON with fsync, .bak backup, RecoverJSON on startup. No partial writes survive a crash.
  • One SSH/scp at a time. Never parallel remote ops.
  • Agents deploy to dev only. Staging and prod require human approval. AI never pushes to main.
  • Never push to remote without asking. AI works on feature branches; humans merge.
  • Playwright before every UI commit.
  • shadcn/Radix-only UI primitives. A Playwright test fails the build if Bootstrap classes appear. No hand-rolled modals, no hand-rolled tabs.

The branches and the VMs are only the frame; what runs inside them still has to honor a contract.


How the review loop actually runs

The supervised loop as a sequence: I hand Claude Code a scoped ticket, it implements and deploys to dev, I run a browser audit against the live DOM, the audit spec becomes the next ticket, and it repeats until I accept the diff at the prod boundary. The human routes every step; the AI never pushes to main.

The receipts for the review loop are public. smashingtags/imogenlabs-site/reviews/ has dated folders full of audit specs from real review sessions. Each spec contains:

  • A root-cause analysis written against the live DOM.
  • A specific fix with file paths and exact diffs.
  • A DevTools verification script with pass criteria.
  • A commit/PR title and body draft ready to drop into Claude Code as the next ticket.

The round-trip works like this. Claude Code builds, I open the dev URL in the browser and run a review session, and that session produces a markdown spec that goes back into Claude Code as the next ticket. Claude Code ships the fix and I re-verify against the live DOM with cache busting. The spec gets committed alongside the code, so the history is auditable.

That is what human-led construction with AI implementation looks like when you write it down: a written contract per project (CLAUDE.md), a cross-project SDLC, a real dev/staging/prod pipeline, and a paper trail of review specs that any future contributor (or future me) can read to understand why a given decision was made.


How I actually keep AI output reviewable

I do not pretend to read every line Claude writes. Nobody can keep up with a coding assistant at full output, and anyone claiming they do is either lying or shipping at human-eyeball speeds, which defeats the point of the assistant. The discipline that keeps the loop honest is architectural. I cap file size, hard, so the codebase stays decomposed into pieces a senior engineer can hold in their head one at a time.

The file-size rule

Codified in CLAUDE.md and the all-projects SDLC.md. Verbatim:

Go files max 1,000 lines, frontend max 500 lines.

No file in production crosses those ceilings. When a file approaches the cap, it must be split by domain before anything else gets added to it. I learned this rule from a real refactor. Five Jira tickets ( through ) had sat open for months pointing at five bloated Go files totaling 6,463 lines: apps/handlers.go at 1,429 lines, the health package at 2,524 lines across three files, samba_handlers.go at 853 lines, storage/handlers.go at 975 lines, container/handlers.go at 682 lines. The tickets were older than some of the code in them. was written when apps/handlers.go was 1,062 lines; by the time I got to it, it had grown to 1,429.

I split all five in a single PR (#65, eightly-os repo) into 28 focused modules, none over 636 lines, zero behavior changes. Every integration test passed because no test cared where a function lived, only what it returned. From the outside, the refactor was invisible. From the inside, everything got easier: finding the alert lifecycle went from scrolling 988 lines of monitoring.go to opening alerts.go at 246 lines. Big files cost attention, and the cost compounds silently every time you ship a feature on top of an already-bloated one.

That refactor is where the file-size rule actually comes from. I wrote it up in detail at mjashley.com/writing/monolith-split-eight-go-files on April 16, 2026.

The asymmetric numbers (1,000 for Go, 500 for frontend) have a reason. Go's package-per-directory model, verbose error handling, and explicit type declarations make a 1,000-line domain-scoped file legible. React and TypeScript files start to collapse in legibility much faster: JSX nesting, prop drilling, hooks, and inline styles compound non-linearly with line count. A 500-line frontend file is roughly the legibility-equivalent of a 1,000-line Go file, and the rule reflects that reality.

Why this works as a review discipline

The size cap is the lever that makes everything else possible:

  • Files stay reviewable. A 500-line React component or a 1,000-line Go domain file can be read top to bottom, understood, and signed off on. A 4,000-line file cannot, regardless of how good the reviewer is.
  • Refactors get forced early. When a file approaches the cap, the decomposition conversation happens before the code rots, not after.
  • AI output gets scoped to a target. When I ask Claude Code to implement a feature, the target file already has a size budget. If the new work would blow the budget, the conversation becomes "split this first," not "merge a monster."
  • Bug surface shrinks per file. Small files have small blast radii. A bug in a 500-line component touches less of the world than a bug in a 5,000-line component.
  • The review-to-output ratio stays sane. Claude Code produces faster than I read, but it has to produce within the size cap, which means the work arrives pre-decomposed into reviewable chunks. The cap does the triage that I would otherwise have to do manually.

What it does NOT do

The cap does not mean I read every line. It means the code is structured so that when I do need to read a piece, I can. The browser-based review loop covers the runtime surface. The multi-model adversarial pass (Grok and ChatGPT) covers architectural and security-sensitive code. Between three different model perspectives plus a human who can spot-check any 500-line slice on demand, the actual review coverage stays high without requiring me to keep up with the output volume in real time.

There is a real difference between "the AI wrote it and I approved it" and "I directed the work, the AI implemented it within architectural constraints I set, three review surfaces examined the output, and the file structure means I can audit any piece on demand." Those are two different jobs, and the file-size cap is what makes the second one possible.


The construction-then-custodianship lifecycle

The lifecycle: construction and stabilization are human-led with Claude Code, and the operator agent stays out until the software is stable, then takes over custodianship, the socials, dependency PRs, and routine maintenance, with a human reviewing on a schedule.

Every product I ship moves through three phases, construction to stabilization to custodianship.

Phase 1: Construction (human-led, AI-assisted)

  • Architecture, scope, and sequencing decisions made by a human operator.
  • Implementation done by Claude Code inside a written contract (CLAUDE.md per project, SDLC.md across projects) that caps file size, forces decomposition before bloat, and bans the AI from pushing to main.
  • Feature branches cut off dev. Browser-based review loop on the dev URL produces audit specs that go back to Claude Code as the next ticket.
  • Adversarial review by Grok and ChatGPT on architectural decisions, security surface, and edge cases.
  • Decisions documented in ADRs and runbooks as they are made, not retroactively.
  • Tests written alongside the code, not after.

Imogen is not invited to this phase, because letting an operator agent make foundational decisions on still-shaping software is too noisy and unwinding bad foundations is too expensive.

Phase 2: Stabilization (human-led, AI-assisted, monitoring-instrumented)

  • Bug fixes, performance work, security hardening, observability rollout.
  • staging becomes active for any product that is preparing to take real customer traffic.
  • Same human plus Claude Code plus browser review loop plus multi-model adversarial pass.
  • Monitoring, alerting, and runbook coverage rolled out to the point where on-call is uneventful.
  • Documentation reaches "a competent stranger could operate this" quality.

Imogen is still idle in this phase. She may be allowed to draft documentation or propose dependency updates for human review, but she does not merge to main.

Phase 3: Custodianship (agent-led, human-supervised)

  • The product is stable. The human has moved on to the next thing.
  • Imogen comes back online to handle the work she is good at: socials, LinkedIn, marketing posts, scheduled maintenance, dependency PRs, security patches, log rotation, certificate renewals, routine customer-facing automation, documentation upkeep.
  • A human reviews agent work on a schedule (daily, weekly, monthly depending on the system), not on every action.

This is the phase where agents earn their keep, extending one engineer's reach across more systems than they could babysit alone. The products are not there yet, but when they are, Imogen gets the keys.


Why this thesis matters for the repos I ship

Most of my public repositories currently describe themselves with language that implies more agentic autonomy than the system actually has, which was a mistake I am now correcting.

From now on:

  • A repo that was built with Claude Code and human review will say so plainly.
  • A repo that is planned for future Imogen-led maintenance once stable will say "planned for agent-led maintenance once stable" and not pretend the agents are there yet.
  • A repo that is plain human-and-Claude-Code work will not use the word "agentic" at all.
  • The operator-kit and ipac repos are about the methodology and the scaffold, not a claim that the operator is currently running my company.

The goal is that someone reading any of my READMEs gets the same honest answer to the question, "is this really agent-built software, or is this a human shipping fast with good tools?" The answer, in almost every case, is the latter. I read that as the current state of the art for shipping real software in 2026, not a weakness in the work.


My actual tooling stack

The real version, not the marketing one. The build-and-review stack is what this document already laid out: Claude Code as the builder, me plus a Chrome-extension reviewer auditing the live DOM (receipts in imogenlabs-site/reviews/), Grok and ChatGPT as the adversarial pass, the archived /auto-route dispatch pattern as the ancestor, and the dev/staging/prod pipeline with Watchtower-driven prod promotion. The part I have not described yet is the iron underneath it.

Local inference: a homelab with dual Intel Arc Pro B50 16GB cards (32GB combined ECC VRAM), Xe2 "Battlemage" workstation GPUs at 170 TOPS Int8 each, 70W, no power connectors, PCIe 5.0 x8. Offline testing, fine-tuning, and running the eightly-agent model. ECC and OpenVINO/IPEX support matter more here than raw FP32; the box is built for inference, not gaming.

Operations: a Proxmox cluster, multi-node Docker hosts, a NAS on SnapRAID + MergerFS, Traefik v3, Cloudflare zero-trust tunnels, a Mac Mini M4 for CI, Proxmox Backup Server for snapshots. Project tooling is Jira with story points and sprints, and Confluence for ADRs and runbooks, which is where the 7 years of Scrum actually show up. The operator (Imogen) is built and idle, waiting for Phase 3 as covered above.


Security hardening (the basics, codified)

Agentic software does not get a pass on basic security hygiene. If anything it gets less of a pass, because the same assistant that ships features fast can also ship a credential leak, a privileged container, or a curl http://... into a bootstrap script just as fast. The discipline that keeps the construction phase honest is the same discipline a competent engineering org would run without any AI in the loop. I just enforce it through CI rather than through code-review headcount.

The actual stack, condensed. GitHub-native controls on every repo that supports them: Dependabot, code scanning, secret scanning, private vulnerability reporting, and a real SECURITY.md that states the auth model in plain terms (HMAC-SHA256 signed cookies, not JWT; PBKDF2 at 600K iterations; 32-byte crypto/rand session secrets; SHA256-hashed API keys; TLS TOFU cert pinning; single-use agent enrollment tokens). CodeQL runs on push, PR, and a weekly cron across Go and JS/TS, failing the build whether or not the findings dashboard is available. HomelabARR CE adds a security-audit.yml that fires ShellCheck, Semgrep, Bandit, and Trivy only on the files that changed and fails on any critical. Snyk rides alongside Dependabot for the transitive paths and IaC misconfigurations Dependabot misses.

The one I am proudest of is the adversarial audit I ran to exhaustion against HomelabARR CE: an AI reviewer kept producing findings and I kept fixing them, twenty-two rounds, a hundred and seventy-five issues, from a default-credential chain and an auth bypass down to a passwordless sudo in a Dockerfile. It also produced the artifacts that turn a bug list into a program: a STRIDE threat model, an incident-response runbook, a compliance posture mapped to CIS, OWASP ASVS, and NIST CSF, ZAP DAST in CI, an Atomic Red Team pentest pass, read-only-rootfs container hardening, a Docker socket proxy, and a login rate limiter that worked well enough to lock me out of my own demo. I run to exhaustion because I do not get to decide the audit is finished. The reviewer does, when it stops finding things.

The cross-host agent gets the strictest model in the product line, because it runs on machines I do not control. No hardcoded fallback secret: each agent generates a 32-byte crypto/rand secret on first boot. Registration is gated behind a single-use, time-limited enrollment token, not a master credential. Tokens are SHA256-hashed at rest. The transport pins the server's TLS cert on first use and refuses a changed fingerprint, closing the man-in-the-middle gap a bearer token leaves open. A version handshake stops a stale agent from talking to a server that has moved past it. That all came out of a cross-service audit that found ten issues and fixed every one before shipping, and releases are signed with SLSA provenance.

Builds are signed end to end. docker/build-push-action emits SLSA provenance and an SBOM; PRs build but do not push, and a health-check smoke test gates the merge; Watchtower on prod only pulls signed images from the tracked path. Several AI reviewers (Sourcery, CodeRabbit, the Codex connector, Copilot) plus a Claude Code self-review each add a perspective on every PR, and none of them can merge. Twelve required status checks have to be green before main accepts anything, bot PRs included. Secrets are generated at deploy time and live in the prod VM's environment, never the repo; Cloudflare tunnels keep customer-facing services off a raw public IP.

This is the part the "agentic engineering" pitch glosses over. A model that writes code fast does not absolve you of CodeQL, Trivy, signed images, SBOMs, secret scanning, branch protection, or a real SECURITY.md. If anything, the velocity makes that floor more important, because you still cannot skip the basics.

What this thesis is not

None of this is anti-AI. I would not be shipping at this velocity without Claude Code, and the browser review loop catches things I would miss alone. The pace and the output are both real, and the AI is doing real work.

It is not anti-agent either. Narrow, well-bounded agents doing maintenance work on stable systems are useful and getting more useful. I built Imogen for exactly that, and I will bring her back online when the software is ready for her.

What it is against is hype. I am arguing with the version of "agentic engineering" that pretends a swarm of agents can replace a senior engineer at the construction phase. That claim has not survived contact with production reality in 2026, and I am not putting it in my README.

I am not going to underclaim either. A human plus Claude Code plus a browser review loop plus a multi-model adversarial pass, riding a real dev to staging to prod pipeline, operated by someone with 7 years of Scrum experience and 12 years in technical program management, is a serious shipping engine. The proof is the shipped products, not a contribution graph: a NAS operating system, an iOS app in review, a container app store with real installs, a managed hosting business that takes real money.

This thesis is the honest middle, and that is the position I will defend.


How this document evolves

This document is intended to go public eventually. It deliberately leaves out internal hostnames, IP addresses, secrets, tunnel UUIDs, and anything else that should not live in a public README. The patterns are what I am sharing here; the actual topology stays in private infrastructure docs.

When the thesis is stable enough that I am willing to defend every sentence in public, it moves to mjashley.com/writing as a blog post, and every public repository's README links here as the canonical source of truth.


Last updated: 2026-05-18 Author: Michael Ashley Status: Living document, published at mjashley.com/writing.