agentos

README

agentOS

A computer for delegated work. Frontier AI you already pay for does the reasoning; a box you set up once does the executing, remembering, and improving, under your sole control. You direct it by text or phone call.

Status: pre-alpha, not yet usable by an owner. What is being built now, and what is done, is on BOARD.md.

Documents

Each fact has one home; other files point to it rather than restate it (docs/OPERATING.md, "Where facts live"). tools/doclint.py checks that this table lists every top-level document.

File	Kind	What it is	Changed by
SPEC.md	what to build	The system specification. v1.0: keys, clerks and one log. Requirement IDs like KEY-1 are normative; Appendix A maps every retired v0.12 ID.	L1 spec-diff PR
PLAN.md	how it is built	Premises, the nested build loops (L0–L4), migration steps 0–5, routing and tiers.	L1
CLAUDE.md	rules	The working contract for builder and reviewer agents, one line per rule.	L4 proposes, L1 adopts
AGENTS.md	rules	Entry point for agents other than Claude Code; points to CLAUDE.md.	L1
docs/OPERATING.md	procedures	The reasons and procedures behind the rules: triage, risk tiers, review pipeline, sessions and migration rules, parallel teams.	L1, Mark decides
BOARD.md	generated	Index of live work packages, rendered from the work-item issues by tools/board.py; change an issue, not a row.	board.yml
briefs/<ID>.md	state	One package's brief: goal, IDs, scope, dependencies, estimate.	L1
docs/LANES.md	state	Which subscription owns which directories during the migration, and any other team's lane.	either peer subscription
docs/conv-3-triage.md	record	Frozen record of the pre-MIG-1 convergence push: the open-PR classes and close list (D-090). Removed in PLAN step 5.	nobody
docs/conv-2-reaudit.md	record	Frozen record of the pre-MIG-1 convergence push: the re-audit of queued and building rows. Removed in PLAN step 5.	nobody
docs/conv-5-uncovered.md	record	Frozen record of the pre-MIG-1 convergence push: what blocked each then-uncovered v0.12 ID. Removed in PLAN step 5.	nobody
DECISIONS.md	record	Decisions as D-NNN rows with date, status and source; long reasoning in decisions/D-NNN.md.	L1, Mark
docs/BOARD-HISTORY.md	record	BOARD.md's merged and dropped rows up to the 2026-10-10 cutover to issues; frozen.	nobody
docs/LATER-HISTORY.md	record	LATER.md's release path and backlog at the 2026-10-10 cutover; frozen. Classes now live on issue labels.	nobody
reviews/<lens>/	record	Lens methods (README) and lens verdicts per PR.	lens screen
<package>/ASSUMPTIONS.md	record	What each package's code rests on.	its builder
LEDGER.md	input	Manual usage readings from Mark's usage screen; METRICS reads them.	L1
METRICS.md	generated	Weekly L4 inputs: first-pass accept, review rounds and causes, usage, defects.	metrics workflow
TRACE.md	generated	Which tests cover which requirement IDs, and the count of old-core markers (tests citing retired IDs). Never edited by hand.	trace workflow
docs/owners-guide.md	product	The guide for the box's owner.	builders, with the features it describes

Reading order by role

Read in this order and stop when you have what you need. Token counts are approximate.

Role	Read	About
Builder (L2)	CLAUDE.md; your briefs/<ID>.md; the SPEC.md sections for the IDs it cites (python3 tools/specslice.py --ids KEY-1,CLK-2); the touched package's ASSUMPTIONS.md	3k + brief + cited sections
Reviewer (L3)	CLAUDE.md; OPERATING §2–4; the diff, the cited SPEC IDs and the brief (an optional aid: python3 tools/reviewpacket.py <PR> bundles them with the tier, and its claims are checked against the source)	5k + diff
Lens screen	OPERATING §4 checklist; active DECISIONS rows; the lens READMEs; the bundle's diffs	10k + diffs
Coordinator (L1)	CLAUDE.md; OPERATING; BOARD.md; class:release (not frozen) and decision issues; recent DECISIONS rows	15k
Another team	AGENTS.md; CLAUDE.md; docs/LANES.md (your lane); OPERATING §7; then the builder row above	6k + builder

Licensed under the Apache License 2.0 (see LICENSE and NOTICE; D-041, spec OSS-12).