yuanpingsong/ultracodex/org-creation

Creating An Agent Org

An org is an attention organization: a directory tree of agents with durable memory, inboxes, and a tick scheduler. Nothing is resident. Agents are directories; ticks wake only the agents whose triggers fire.

Part 1 - The Gate

Build an org only when all four tests pass:

1. Partition key. The domain splits into entities with crisp boundaries.

Use groups/entities, not fuzzy topics that duplicate work.

1. Volume. Recurring inbound volume makes maintained memory cheaper than

rereading from scratch.

1. Compounding. Yesterday's distilled belief improves today's judgment.
2. Judgment, not action. The org produces synthesis a human reads. It does

not directly send mail, deploy, approve, trade, or operate production.

If a test fails, use a workflow, script, queue, or database instead.

Part 2 - Structure

Use two to three levels:

/                         root agent: house view and user door
  AGENTS.md BRIEF.md LOG.md inbox/ tickets/
  coverage.toml           scaffold input: groups + entities
  templates/              root.md group.md entity.md
  <GROUP>/                aggregator
    AGENTS.md BRIEF.md THESIS.md LOG.md inbox/ tickets/
    <ENTITY>/             leaf agent
      AGENTS.md BRIEF.md IDENTITY.md THESIS.md LOG.md WATCHLIST.md
      FACTS/ inbox/ tickets/
  ingest/                 ledger.jsonl cache/ unassigned/

Keep aggregator span near 5-15 children. The superior reads only child BRIEF.md files, and every BRIEF.md body is capped at 80 lines.

Templates use {{GROUP}}, {{GROUP_TITLE}}, and {{ENTITY}}. Scaffold owns AGENTS.md; edit templates and re-scaffold rather than editing instances.

Directory slugs must be filesystem-safe and stable. Avoid reserved names: ingest, templates, docs, coverage.toml, .ultracodex, .git, node_modules, ops, runtime, workflows, audit, and user. Map scoped or special external ids to safe slugs and record the mapping in IDENTITY.md.

Runtime-created files and directories such as tickets/, .thread, and QA.log.md may appear after operation. Do not make templates depend on their initial presence.

Entity counts are flexible. Cover the real population, then split or add aggregators when the span rule breaks.

Part 3 - Memory

Divide memory by update trigger, not by topic:

Every memory file needs frontmatter: updated, sources, confidence, next_review. Use fixed vocabulary: confidence speculative|possible|likely|high-confidence; severity routine|notable|material|urgent.

Calibrate severity in the templates with the deciding test: "would the owner act differently today?" Expect thresholds to be wrong at first. Replay real history and adjust.

Citation discipline:

• Fact lines cite the source that contains the fact: [source:...] or

[fact:...].

• Judgment lines lead with a confidence word and cite the facts they rest on.
• Forward-looking lines say projection: and cite their basis.
• Honest recorded ignorance beats a fabricated answer. Record missing inputs

in LOG.md or WATCHLIST.md.

Auditor test: could a reader verify this line by reading the cited source file alone?

Part 4 - Communication

Use three receiver-cost levels:

• QUERY costs the target nothing. A read-only fork answers from its files.
• NOTIFY costs one judgment. It creates an inbox item for the next wake and

expects no response.

• REQUEST costs work. Only an ancestor can request work from a descendant;

the runtime creates a ticket. The target answers with REPLY on that ticket.

Nobody writes up-tree. Agents do not page their ancestors; they write severity in memory, and the scheduler wakes the parent through content triggers.

Router violations are not silent. The runtime rejects the message, appends a routing-violation row to ingest/ledger.jsonl, and sends feedback to the sender so the next wake can correct the behavior.

Part 5 - Cycle

The scheduler evaluates four trigger classes:

• time: next_review or cadence.
• quantity: inbox depth crosses the threshold.
• content: material or urgent lines in a child wake the parent.
• dependency: enough children have completed since the parent last woke.

Wakes run from the agent directory. The wake result shape is:

{ changed, severity, logLine, outbox }

The runtime delivers outbox messages with authority checks, records state, and runs org lint. Every wake appends a LOG.md line; a quiet wake appends a null entry with severity:routine.

Part 6 - Ingestion

Build deterministic fetchers. They write one inbox item and one ledger row per delivered item:

{"type":"ingest","at":"2026-07-09T00:00:00.000Z","id":"item-1","date":"2026-07-09","to":"group/entity","item":"item-1.md","ref":"ingest/cache/item-1.txt"}

Disciplines:

• Make routing deterministic and test it with fixtures.
• Append a ledger row for every delivered item. The id is any stable

non-empty source id, not a filesystem slug; replay escapes it only when it must derive a fallback inbox filename. Router delivery and violation rows coexist in the same file.

• Use content-addressed cache entries and extract searchable plain text for

cached documents.

• Advance cursors only through fully successful days.
• Defer per item when an upstream item fails; one blocked item must not kill a

whole cycle.

• Keep unroutable inputs in ingest/unassigned/ for root review.
• Be polite: prefer per-entity APIs where they exist, avoid broad crawling,

and on blocks use silence followed by one retry.

Example domains can be dependency-watching, incident-watching, or an investment-research org watching a public filings feed. Keep the fetcher contract generic until the user supplies source-specific rules.

Part 7 - Verification

Run ultracodex org lint on demand and after ticks. Lint checks file presence, frontmatter, vocabulary, BRIEF.md length, watchlist dates, thesis provenance, LOG liveness, and single-writer boundaries.

Run ultracodex org audit after large ingests and on a schedule. A different agent samples BRIEF.md and THESIS.md claims, verifies each against its cited source file only, and returns verified|unsupported|contradicted|uncheckable. Mixed lines use weakest-link grading. Audit findings are delivered as audit notifies; owning agents fix their own memory on the next tick.

Use replay for calibration. Replay derives a corpus from ingest ledger rows, re-delivers it day by day, and can inject drop, dup, and late faults. --pristine resets memory to scaffold state and is allowed only on a replay/ branch.

Part 8 - Build Order

1. Run the gate. Pick partition key, groups, and an initial entity set.
2. Write coverage.toml and role templates. Put severity calibration and

citation rules in the templates.

1. Run ultracodex org init; ultracodex org lint must pass.
2. Write the fetcher contract before coding fetchers. Then build deterministic

fetchers with fixture tests.

1. Ingest a small sample and run ultracodex org tick. Read the root and group

briefs yourself.

1. Audit, fix templates, and re-audit.
2. Backfill through replay. Tune thresholds by replay, not by hope.
3. Schedule the daily tick only after null LOG entries, audit convergence, and

replay behavior are trustworthy.