RFC: OSuite — Principles for Splitting Order Apart

Status: early, exploratory. This is meant as a living document, not a locked spec. It's closer to an RFC than a final design. It'll change as the thinking sharpens.

Motivation

Every creative project seems to move through an initial phase of divergence: exploring options, trying shapes, figuring out what actually works before anything converges into something stable. Tiago Forte's Building a Second Brain is a useful reference point here: the same divergence/convergence rhythm he describes for personal knowledge work applies just as well to building the tool itself.

A lot of what currently lives inside Order -- the single, unified app trying to hold notes, chat/voice, calendar, finance, reading, sheets, drawings, publishing, all in one shell etc. -- is really just the upshot of that divergence phase. Features got added where they were needed, tried out, kept if they worked. That's healthy for exploration, but it isn't necessarily the right shape to converge into permanently. At some point divergence needs to give way to convergence, and convergence might not mean "keep adding to the one app forever”. It might mean pulling the distinct, proven ideas out into their own focused tools.

The core idea

Instead of Order being one monolithic app trying to do everything, split its key functions apart into a suite of separate, focused apps, each one really good at exactly one job. Notes, calendar, chat, sheets, drawings etc. I’m calling it the Order Suite or ‘OSuite’ for short.

What ties them together isn't a shared codebase or a unified UI. It's the filesystem itself, plus the conventions layered on top of it: the Johnny Decimal numbering, plain-text markdown, the vault structure, the Notable Folder model. The filesystem is the durable, portable substrate. The individual apps are replaceable tools that sit on top of it and read/write into that same shared structure.

The tension with spacetime.md and its resolution

There's a real conceptual friction here worth naming directly, because it isn't small. The whole spacetime.md article argues for one unified way of reading space and time together a single home, not a set of separate rooms with separate front doors. OSuite starts from close to the opposite instinct: cutting that home apart into a suite of focused apps. That's the first concern.

The second concern is more practical: sometimes it's just easier to edit the plain text file directly, or visualize it directly, than to go through any app at all. Part of spacetime.md's appeal is that for a lot of events, you never have to create a new file or a new folder. It’s just another line appended into existing text. This is a different mode from a notable-folder-with-its-own-directory model, and different again from a suite of separate apps, each of which might expect its own structured place to write into. More apps risks more ceremony per event, which cuts against the "just a line, no new file" simplicity that makes the format work in the first place.

The resolution: flip spacetime.md from something hand-authored into something derived. Rather than being the thing you type into directly, it becomes a compiled index generated from whatever structure the various apps or CLI tools actually create on disk. That preserves the low-ceremony ease for the cases where a quick tool handles it, while spacetime.md becomes a unifying view of the truth rather than a thing every app has to remember to maintain by hand. It also fits OSuite naturally: separate apps can each write their own files in their own way, and spacetime.md is rebuilt from what's actually there, rather than requiring every app to coordinate on writing to one shared file directly.

Landing this further: the file system itself -- its actual directory listing and lexicographic ordering -- is the index and source of truth, full stop. That's what makes the old spacetime.md "brood" rule (never list a partial set of children, since a list only means something when it's complete) still hold true, just relocated -- it's no longer a rule about hand-editing one ledger honestly, it's a property the file system already gives you for free when folders are named with sortable, complete prefixes. This is also exactly why Johnny Decimal numbering and file-system-as-truth pair so naturally: decimal prefixes are what make that lexicographic ordering meaningful and stable rather than accidental. spacetime.md becomes an optional export -- a derived YAML or Markwhen-style rollup you can generate on demand if you want one file to scan top to bottom -- never a thing any app or tool needs to read from to know the truth.

The three layers: format, convention, tooling

Sorting out what OSuite actually requires versus what's left to personal taste comes down to three distinct layers, each with a different bar for being "required":

1. File format (integral, non-negotiable). This is the one layer every OSuite app must read and write identically, or interoperability breaks silently. It covers: the Notable Folder shape (a real filesystem folder with a main document marked by a leading ! -- Notable Folder/! Notable Folder.md as a recommended habit, though the marker alone, not the name, is what identifies it -- and a stream of dated notes around it); the small set of YAML frontmatter fields a note may carry (public, slug, and the optional folded) -- notably no folder field, since folder membership is defined purely by physical location, and no date/title either, since an event's schedule and a note's title both live in its filename (see the grammar below); and ISO 8601 as the one date format used everywhere, in dated filenames. None of this is up for per-app interpretation -- it's the substrate.

Because folder membership is purely physical, moving a note between folders is a real file-system move -- a plain relocation of the file, nothing else touched. This is a different operation from rescheduling a note, which changes when it happens rather than where it lives: rescheduling means renaming the file's date prefix, a pure rename, since the date lives only in the name with no second field to keep in step. Move and reschedule aren't the same primitive underneath -- one is a pure physical move, the other a rename of the date prefix -- but both should exist as clean, single-purpose operations any OSuite tool (CLI or UI) can expose.

Filename date/time grammar

The dated-filename convention is itself part of this integral layer, and it's designed to compactly express everything Markwhen-style scheduling syntax covers, without relying on characters the filesystem can't safely hold (no /, no :). It escalates in specificity, each shape adding exactly one more token to the last:

A timed multi-day range (a specific start time on one day through a specific end time on another) is deliberately out of core scope -- rare enough in practice that it isn't worth the added complexity. If it's ever needed, it falls back to being just a multi-day date-range filename with the specific times, if any, living in frontmatter instead.

Main document and pinned-note markers (! / $)

Two more prefix symbols, both genuinely part of layer one because they're JD-independent -- they work identically whether the folder above them is JD-numbered or not, and they solve a real problem the four date/time shapes alone can't: raw lexicographic order can't guarantee any particular note appears first, since a JD-numbered folder's own leading digits can sort anywhere relative to a 20YY-MM-DD date. The fix isn't a rendering-layer rule, it's a character below the digit range (ASCII), so the ordering holds in a completely raw, tool-less ls -- not just in a smart app's interpretation of one.

A validity rule falls directly out of what each symbol means, rather than needing to be stated as an arbitrary restriction: a filename may carry at most one of ! or $, never both. The main document was never competing in the ordinary note sort to begin with -- it isn't "a pinned note," it's the folder's own defining document -- so "sort it near the top among notes" is a category error applied to it.

Sort-modifier suffixes (~ / +) -- Johnny Decimal's own, not layer one

Johnny Decimal's symbols RFC (W0192) defines two further symbols, ~ and +, but on closer reading of his own spec, these are suffixes on a full AC.ID (e.g. 11.11~ Notes from applying for UK copy, 11.11+ Belinda) -- they're conventions of his numbering scheme specifically, not general-purpose filename grammar that exists independent of it. Given that OSuite's own JD usage (below) keeps ID numbers purely at the directory level and doesn't repeat them in filenames inside a Notable Folder, adopting ~/+ verbatim would mean reintroducing exactly the kind of ID-repetition this spec otherwise avoids. So they're deliberately not part of OSuite's core layer-one grammar -- they stay documented as part of Johnny Decimal's own convention (layer two, below), for anyone applying JD literally at the directory level (e.g. naming a category folder 11.11+ to group it above unstructured folders), rather than something every OSuite app needs to parse on ordinary notes.

For reference, what they mean in JD's own system: ~ (tilde) marks an arbitrary, one-off sub-note whose title won't repeat anywhere else (his example: notes from a specific phone call) -- its sinking to the bottom of a listing is a side effect of where ~ falls in most filesystems' sort order, not the point. + (plus) marks a systematic, repeating pattern -- the same named sub-thing recurring identically across many different IDs (his example: a + Belinda suffix appearing under birth certificate, vaccination record, and savings account, each a different category, so searching + Belinda surfaces everything related to her regardless of which ID it lives under) -- and Johnny Decimal confirms this also has a real sorting benefit: folders named with + group together above unstructured folders. A third symbol, @, links a "work package" back to its parent ID -- narrower still, and unrelated to sort order.

Seasons as an ordinary date-range file

Seasons -- a named, user-defined date range used to roll up notable activity across areas -- don't need to be a special construct at all. A season is just an ordinary file living in its own folder (e.g. Seasons/), named using the same date-range shape already defined above: YYYY-MM-DD - YYYY-MM-DD Season Name.md. It's genuinely a multi-day all-day event like any other; it just happens to represent a long span rather than one note's specific occurrence. This is a good proof that the four-shape grammar is general enough to cover a concept that originally looked structurally different -- no special-cased aggregation file format needed, just the same primitive applied at a longer timescale. Anything that wants to compute "what happened during this season" does so by querying the vault for that date range, composing on top of the canonical parser rather than needing Seasons to be hardcoded as its own layer-one concept.

2. Recommended conventions (suggested, swappable). This is where Johnny Decimal numbering lives, and it's also where Markwhen-style shorthand belongs -- a plain-text, human-friendly way to quickly express a dated event or range from a CLI, a quick-capture surface, or elsewhere, without needing to hand-author YAML. Both are genuinely recommended, documented as the OSuite-preferred way to do these things, but neither is required for the vault to function. A different numbering scheme or a different quick-capture syntax would still interoperate fine, as long as what ultimately lands on disk matches the file format layer above. Any app is free to translate Markwhen-style input into a real dated filename, or skip it entirely and build its own capture flow.

In this system, Johnny Decimal is deliberately scoped to directory naming only -- AC.ID Category Name/ as a folder, full stop. Once you're inside a Notable Folder, JD hands off entirely to the layer-one filename grammar above; the ID is never repeated inside filenames there. This is a real, honest departure from Johnny Decimal's own literal spec, where an ID is defined as a file (AC.ID Title) and folder nesting is just an optional convenience around it -- here the relationship is inverted, and it's worth being explicit about the tradeoff rather than presenting it as a straight adoption of JD's convention. The main disadvantage: a tool that searches or greps by filename alone won't find a note's JD ID, since it lives only in the parent folder's name, not repeated in the file. The upside, and the reason this is the preferred tradeoff here, is the same one threaded through this whole document -- nothing needs to be kept in sync. A note's folder membership is already fully defined by physical location (see layer one above); repeating the ID in every filename inside that folder would just be a second, redundant place for the same fact to live, and a second place for it to go stale. JD and the OSuite Notable Folder grammar are meant to be complementary and separable this way: JD owns the directory tree, this spec owns what happens once you're standing inside one of its folders.

3. Tooling (CLI and UI contracts -- the actual value proposition). This is the layer that's still open and worth designing deliberately, because it's where Order (or any OSuite app) actually earns its keep versus the alternatives: hand-editing files directly with no tool at all, using bare conventions like Johnny Decimal without any app enforcing them, or just having an AI agent read and write files ad hoc with no stable contract at all. A well-defined CLI command and UI behavior for "create a note," "promote a list item to an event," "renumber a category" -- each with a predictable interface -- is what makes an OSuite app worth using over those alternatives. This is also where the UNIX-philosophy value of the suite actually shows up: small tools with well-defined contracts that compose, rather than one AI improvising file changes each time with no guaranteed shape.

The ripgrep test: what's actually worth building

Once folder/note mutation collapses down to plain filesystem primitives (create, physical move, delete, rename-for-reschedule), those operations stop being much of a contribution in themselves -- they're trivial precisely because the filesystem already fully defines what a correct outcome looks like, with no ambiguity left to resolve. That raises the real question: what, specifically, is worth building as a tool rather than just letting an AI or a script improvise it fresh each time?

The useful test here is the same one that explains why a tool like ripgrep earns a permanent place in a toolchain even in a world full of capable coding agents: it isn't valuable because searching text is conceptually hard, it's valuable because doing it correctly and fast, across encodings, huge trees, edge cases, is fiddly enough that even a capable AI would rather shell out to a well-tested implementation than re-derive those edge cases from scratch on every call. Nobody gains anything by reimplementing grep slightly differently each session.

Applied to OSuite, the equivalent narrow, fiddly-but-worth-solving-once problem isn't search or calendar rendering -- it's the filename-and-frontmatter grammar itself. Turning a filename into a structured record (date, optional time, optional time-range or date-range, title) and back again, correctly, every time, respecting every edge case just settled above (no colons, dash meaning either a time-range or a date-range depending on token shape, titles that themselves contain a dash, date-boundary handling) -- that's a small, canonical parser/validator/serializer, ripgrep-tier in spirit: narrow, correct, fast, and not worth any tool (human, script, or AI) re-implementing per call.

That reframes everything else discussed above -- range queries, gap-checks, season rollups, calendar day/week/year views, the spacetime.md export -- as composition on top of that one canonical primitive, the same way rg composes with sort and uniq in a shell pipeline, rather than being separate core contributions competing for design attention. Order/OSuite's actual value proposition is being the one correct, shared implementation of the grammar -- so nobody, human or AI, has to get its edge cases right themselves ever again.

CLI-first as a design rule

Every app in OSuite should ideally expose a CLI component, and the underlying code should be architected to support that from the start rather than bolted on afterward for one app in particular. In practice, this means core logic gets written as callable functions or standalone commands first, with any GUI or voice-agent interaction sitting on top as a thin layer that calls into that same shared code, rather than a GUI holding logic a script can't reach.

This matters beyond convenience. For me, it means that each tool in the Order Suite has not only a well defined interface (API, CLI, UX behavior), but that itself acts as a value proposition when you tie the tools together in the spirit of the UNIX philosophy.

OTerm — a terminal app

One candidate OSuite app worth naming even at this early stage: a terminal app, OTerm. A CLI-first design already implies the core logic is callable from a shell; OTerm would be the dedicated terminal interface built on top of that shared code, rather than a demo of what the CLI can do. Not yet scoped beyond the name and the fact that it belongs on the eventual list of split-off apps. Think of it like Claude Code but for Order.

Where this stands

Not yet scoped: which functions would actually split off first, how they'd share state or sync, and what the CLI/UI contracts in layer three should actually look like per app. This note exists to capture the principles before the scoping work starts. The filesystem's own structure and ordering as source of truth, apps as replaceable tools on top of it, spacetime.md as an optional derived export rather than something anything reads from, Johnny Decimal / Markwhen-style syntax as recommended conventions rather than requirements, and the filename date/time grammar plus the no-folder-field, physical-move-vs-reschedule distinction as now-settled parts of layer one.