The rules I use to keep AI-built software safe and predictable. I decide what gets built, an AI does the building, and a second AI is brought in to poke holes in a design before any work starts. The riskier a change, the more checks it faces, and every piece of work starts and ends with a written record.
The rulebook for how AgentOS gets built. I decide what happens; a Claude Code session does the building; when the risk is significant enough, a second AI is spawned to poke holes in the design before anything is built. Every piece of work is a slice with a written kickoff and a written closeout, riskier changes face more ceremony, and the whole cycle is projected into a VS Code cockpit with one-click launches. This page is the methodology; the build log is what it produced, and the roadmap is where it is headed.
Six steps, every time. Small low-risk changes and big risky ones follow the same loop; the risky ones just face more scrutiny before any work starts.
Six steps, every time. The same loop runs whether the slice is a documentation-only design or a new write surface; only the depth of the design gate changes.
06 returns to 01: the closeout recommendation is what I select next.
Slice selection, every open design question, approval grants, review-finding dispositions, and the ship call. The AI never resolves a genuinely open fork silently, even mid-slice: it stops and asks.
Materialises kickoffs, implements, runs the validation gates, writes the records, and proposes the next step. Proposals come with a recommendation, not a menu.
There is no sprint board and no ticket system. The unit of work is the slice: small enough to commit on its own, big enough to ship something real, with a durable ID that is never reused. Kickoff and closeout share that ID, so every slice is bracketed by two written records. Each slice carries a risk class, and the ceremony scales with it.
Design memos, plans, and register changes. No code.
Deterministic code. No model call, no write surface, no UI change.
Screens and views that only display information and can never change anything.
UI changes and new read surfaces. Any new endpoint is GET-only.
Runs that cost real money. The kickoff names a spend bound before anything launches.
Anything that can change data, grant approvals, or alter how the system behaves. Design-first, independently reviewed.
Apply paths, approvals, config mutation, any new mutating seam. Design-first, externally reviewed.
Remote, multi-user, hosted. Opening that fence is its own decision, with the full R4 treatment on top.
The roadmap is a single markdown file with a hard rule: nothing multi-paragraph lands in it. It changes only by row edits and status flips; narrative lives in per-phase documents. That keeps it a steering surface, not a junk drawer.
The condensed constitution of the system: what never widens, what never grants authority, what stays read-only. Kickoffs bind these by ID, closeouts check them by ID, and the per-phase docs stay authoritative for the detail.
| ID | Invariant |
|---|---|
| G1 | No free models for reliability-critical audit, challenge, or apply runs. |
| G2 | No apply widening: structural, architectural, cross-surface, or ambiguous findings stay manual. |
| G3 | No portfolio-wide apply: every write is single-target, verifier-gated, build-gated, and ledgered. |
| G4 | No apply-write through the queue: approvals bind to an exact apply fingerprint, granted out of band. |
| G5 | The challenger stays advisory: a clear verdict never masks a failure. |
| G6 | The failure-domain enum is smoke-locked and never widened casually. |
| G7 | Restart the server after any server-side deploy, before live validation. |
| G8 | No new platform code beyond accepted slices: new gateway endpoints are GET-only. |
| G9 | Config never grants authority: JSON cannot define new executable behaviour. |
| G10 | Secrets live in env or SecretStorage only: never in config, queues, ledgers, or reports. |
| G11 | Runtime artefacts are not source: no broad deletes over tracked report folders. |
| G12 | Every slice is independently committable, compile-green, and smoke-green. |
| G13 | Proposal-first: no model output is applied without deterministic validation and human review. |
| G14 | Observe surfaces stay read-only except explicitly confirmed launches. |
| G15 | A standing fence over hosted, multi-user, write-surface, and queued-apply expansions: opening it is its own decision. |
| G16 | Every grant record carries originating-surface and grantor-auth provenance from first write. |
| G17 | Decision-quality telemetry is descriptive only and never gates. |
| G18 | A design gate that refuses a real operator need must name the lawful alternative in the same document. |
A ceremony here is a written record produced at a fixed point, in a fixed shape, and said out loud rather than left implied by file changes. AI-run work does not fail by crashing; it fails by trailing off. The ceremonies exist to make "done" an explicit, checkable claim.
Written before work starts: intent, in and out of scope, binding invariants quoted by ID, checkable acceptance criteria, the named validation gates, and the spend bound where models are involved. The kickoff is the contract; closeout validates against exactly what it named.
Capped at about 200 words: outcome (shipped, partial, or abandoned), commits, what changed, each gate with its result, and two fields that can never be omitted: Manual check (what to click or run to see the result yourself) and User docs (what changed in the user guide). A slice with nothing to show writes N/A plus why. Absence is a stated fact, never a silence.
The closeout checklist: append the record to the phase doc, move the row to the shipped register, update Now and Next, update the user guide, write memory, update the changelog, commit, restart the server if it changed. New backlog rows are minted the moment they exist, including every deferral.
How review findings are absorbed. The reviewer's verbatim verdict is pasted into the reviewed document, and every finding gets a written disposition: fold (with the edit), reject (with the reason), or defer (with the owning row). The AI proposes each disposition; I decide each one.
Before anything risky is built, a second, unrelated AI is handed the design with one instruction: break it. It shares nothing with the AI that wrote the design, so it cannot inherit the same blind spots, and an extra review round costs nothing.
Design documents get refuted before they get built. The authoring session spawns a second, unrelated AI (headless Codex CLI, running read-only) with a fixed prompt whose only instruction is to break the design. Because it runs on a subscription CLI, the marginal cost of a review round is zero.
Every review returns a verdict (GO | CONDITIONAL-GO | NO-GO), findings ranked most severe first, answers to the document's open questions, and a tried-and-failed list. The verdict never gates mechanically: a NO-GO with rejected findings and my sign-off can still ship, recorded as such. The protocol makes disagreement visible, not binding.
Not everything deserves a risk class. Work queues at the formality it needs.
The real work queue, inside the roadmap. Rowed, ID'd, risk-classed, gated. Everything that becomes a slice lives here first, and nothing gets built without a row. The roadmap page renders it in full.
The UI/UX backlog, explicitly ceremony-free: add an entry whenever something is spotted. Screenshots attach by a file-naming convention, so an entry never needs editing to gain an image. Fixes launch from the cockpit one at a time or as a batch.
Undocumented changes, collated on request by diffing the git log against the changelog, then worked as ordinary documentation updates.
The whole workflow is projected into a Development tab in the VS Code dashboard: four sub-tabs (Slice, Roadmap, Build log, UI/UX Register) rendering the live documents off disk. It is a cockpit, not a second control plane, and its interaction model is deliberately narrow.
Previous, current, and next-up slices with the full register field set rendered faithfully: empty fields render empty, never invented. A per-slice ceremony checklist tracks the ritual; a candidate table shows what could run next.
Kick off, Continue, and batch-fix buttons compose a seeded Claude Code prompt (Start 5W.2) and open the terminal. Confirmed launches only: the buttons write no files, flip no rows, and grant no authority. The session does the work; the tab just removes the friction.
The only thing the tab can write is a new UI Fix Register entry, through a validated capture form: deterministic ID allocation, an atomic single-file write, a path guard. It writes nowhere else, by design and by review.
Ceremony checkboxes persist locally and are never evidence a gate passed. At most they add an overrideable warning before a launch. A ticked box is a note to self, not proof: proof lives in the closeout record's gate results.
Docs-only work moves at conversation speed. Anything that writes, spends, or grants authority pays for design and review first. The risk classes make that a rule, not a judgement call made under momentum.
Every slice ends with an explicit outcome and a next recommendation. Every closeout must state how I can check the result myself, and 'nothing to check' must be argued, not assumed.
Every slice ends with an explicit outcome and a next recommendation. The mandatory Manual check field means I can always verify a claim myself, and N/A must be argued, not assumed.
The documents carry the whole state of play. The AI's memory points at the documents; it never replaces them. A fresh session on a fresh machine picks up from the written records alone.
The documents carry the whole state of play. Session memory indexes them; it never substitutes for them. A fresh session on a fresh machine resumes from the repo alone.
An author reviewing its own design inherits its own anchoring. A fresh-context reviewer with a fixed refutation prompt does not. Disagreement is made visible and recorded; it is never made binding.