The working method
How I built it
Every change starts as a proposal, every part follows one constitution, and nothing counts as done until the checks pass.
AlanOS spans many repositories, a runtime, a console and the models that route questions and compile knowledge. Keeping that consistent takes a method more than a framework: the same loop for every change, one set of rules, and checks that do not care who wrote the code.
This page is about that method, the rules it relies on, and the tools it runs on.
How a change happens
The same loop runs for a new domain, a console screen or a one-line rule change.
- 01
An idea, written as a proposal
Every non-trivial change starts as a short written proposal: what it is for, the options, a recommendation, and the questions only I can answer.
- 02
I decide
I approve, change or reject the proposal. Some ideas are parked on purpose, with the reasoning kept so they can come back later.
- 03
I build it
The work happens inside the repository the change belongs to, against that repository's own rules and the constitution.
- 04
Checks decide whether it is done
Tests, type checks, manifest checks and the constitution's conformance checks run. A change that fails them is not finished, whatever anyone reports.
- 05
A gap becomes a rule
When a real run exposes a gap, the fix goes into the contract or the constitution, so every domain gets it at once.
Rules live in a constitution
The rules live in one register of numbered clauses. Every repository checks itself against it, and each change is an amendment with a recorded reason.
The core holds only the clauses whose breach would be a failure of trust or of a boundary. Everything else lives in schedules and in each domain's own constitution, so the core stays small and changes rarely.
The engine
The runtime reads each domain's manifest, the file where a domain declares what it can do, and routes a question to the domains that can answer it. A small, cheap model does the routing. It never searches a domain's files itself; it can only call the capabilities a domain exposes.
For work on code, the runtime starts an agent harness, Claude Code or Codex, inside a sandbox, and the repository's own checks decide whether the result is merged. The orchestrator framework, Mastra, is kept replaceable on purpose: removing it should lose only runtime code, and no domain is allowed to depend on it.
A model never decides privacy
Every record is public, personal or confidential. Every interface declares the most sensitive level it may serve, and deterministic code removes anything above it. A missing or invalid level falls back to private.
Automated work runs inside an operating-system sandbox that keeps it out of private folders. That is why Career can answer questions on this site while Health only runs on my own machine.
Measured before trusted
Routing has an eval suite, so I can compare models and prompts on the same questions instead of by impression. Every domain checks that its manifest matches its code. A daily audit compares what the documentation says with what the code does and reports the drift without editing anything.
Every repository runs its own tests, type checks and conformance checks before a change can land.
Rules that came from use
Some rules exist because a real run showed they were needed. Each one now applies to every domain.
- 01
A capability with no arguments takes none
Every domain's status capability must be callable with no arguments at all, and every domain is checked for it.
- 02
Citations come from the domain
A domain hands back the exact citation string for every answer, and the orchestrator records a citation only if a domain returned it.
- 03
Observe at the boundary
The orchestrator checks what actually happened at each boundary and logs what it did, never only what it was told.
- 04
The runtime commits, the harness writes
An agent harness writes inside its sandbox; the runtime commits what it wrote. The repository's internals stay closed to the harness.
Domains propose their own improvements
Every domain answers three standard questions: what it is waiting on me for, what has changed underneath it, and how it could be better. A scheduled run reads each domain and writes scored proposals. I accept or reject them in the console, and an accepted dependency fix can be handed straight to an executor, one repository at a time.
Tools
- Language and runtime
- TypeScript, Node.js, pnpm, Vitest
- Models
- Claude Code and Codex as agent harnesses, a small OpenAI model for routing, Mastra as a replaceable orchestrator
- Interfaces
- Model Context Protocol servers, JSON Schema manifests, a command-line router
- Console
- Vite, React, Tailwind CSS, shadcn/ui, installed on my phone as a web app
- Collectors
- Swift and HealthKit on the iPhone, a scale reader in TypeScript
- Documentation
- Markdown, architecture decision records, Astro Starlight
Models and tools will keep changing. The method stays the same: write the idea down, decide, build it, and let the checks say when it is done.