Lumos OS
A Claude Code operating system I designed and run: eleven skills, four subagents, and four scripts that take a business website from prospect to delivered redesign — with every finding backed by an automated scan, and every outward-facing send gated behind me.
Personal system · In daily use since late June 2026 · Repo private
Two audiences, one website
Websites are now read by two audiences: people, and the AI agents that increasingly browse and transact on their behalf. Most small-business sites are invisible to the second one — no structured data, no machine-readable map, forms an agent cannot fill. That gap is diagnosable, and diagnosing it by hand is slow and inconsistent.
Lumos OS is my attempt to make that diagnosis repeatable: a single loop that finds candidate businesses, scores them against a fixed rubric, turns the evidence into an outreach case, and — when one converts — carries the same evidence forward into a redesign.
One lap, six stages
- Prospect — research businesses in an industry and city, write them into a structured pipeline file.
- Scan — batch-score every prospect against the readiness rubric, rank hot-first.
- Pitch — turn scan evidence into outreach copy. I send it. Nothing auto-sends.
- Discover → Audit → Strategy → Design research — the diagnostic half of a converted engagement.
- Build → Deliver — the rebuild, judged against the same rubric it was sold on.
- Case study — the delivered work becomes the evidence for the next lap.
Six choices that define the system
State lives in files, not in conversation.
Every stage reads structured state and writes structured state. A fresh session can pick up any engagement from its folder alone, with no memory of what came before. This was the decision that made the system survivable — conversation-held context evaporates, and a system that forgets mid-engagement is not a system.
Evidence before opinion.
No claim about a website gets made until a script has actually looked at it. The rubric is weighted and fixed — structured data, discoverability, semantic structure, form readability, no-JS content, metadata, link clarity, agent-actionability — so two sites scored a week apart are scored the same way.
Every design choice is a logged decision — including the rejections.
No entry in the decision log, no build. Recording what I chose not to do turned out to matter more than recording what I chose, because the rejected option is the one a reviewer asks about three weeks later.
A motion ladder, not motion taste.
Animation climbs a fixed ladder from CSS upward, and every rung above the bottom requires a written justification. It is a small rule that removes a large category of argument with myself.
Nothing reaches a human without passing through me.
Drafts, pitches, proposals, reports — the system produces them, I send them. The generation is automated; the judgment is not.
Gaps are a first-class artifact.
When the tooling cannot produce evidence, the run does not halt and it does not guess — it writes the gap to a file. That file is the product backlog for the system itself.
The one number
Scoring twenty prospects against the readiness rubric took roughly a full day by hand. Through the loop it takes about forty minutes, including my review.
Self-measured on my own workflow — one person, one process. Treat it as an honest estimate, not a benchmark.
The rule the system is built on, and where it fails
The system's first rule is evidence before opinion — nothing gets claimed about a site until a script has looked at it. The tooling cannot always hold up its end of that. On some sites the automated capture came back with screenshots that were not a faithful picture of the live page, and the scanner could not reconstruct the site's real information architecture from markup alone. Structure that is obvious to a person looking at a page — what is primary navigation, what is actually a section, what the hierarchy is meant to be — is not reliably recoverable from the HTML.
That is a real limit, and it sits directly against the rule the whole system is built on. A diagnostic tool that quietly produces a thin evidence base is worse than one that fails loudly, because the output looks identical either way.
What I changed in response was the handling, not the capability: a run that cannot gather evidence logs the gap rather than filling it in. The underlying problem is still open.
Three open problems
- Make missing evidence a visible state in the output itself, not just a line in a backlog file — a finding built on partial evidence should be marked as such wherever it is read.
- Treat IA reconstruction as its own problem rather than a side effect of scanning: a human-in-the-loop confirmation step before any structural recommendation.
- The rubric is version one. It needs to be re-weighted as agent browsing standards actually settle, and I have not yet built the mechanism for re-scoring old audits when the rubric changes.