One capability, one home

On 30 August I wrote a document that answers one question. When I want to do something the matrix doesn't do yet, which repository should it grow in?

By then the matrix had more than a dozen projects. Every new thing meant deciding again where it went, and the trouble was that the same question, asked a few days apart, got different answers. The same capability ended up half-built in two repositories, complete in neither.

The document opens with "one capability, one home". There is no repository for odds and ends, and no capability is allowed to be split across two. If something has no home, either its place hasn't been thought through yet or it really needs a new repository. "Put it here for now" is the one answer that isn't allowed.

Placement comes down to four questions, asked in order; the first yes is the answer. Is it part of what an existing project already does? Then it goes there. Is it about the matrix itself, like monitoring, ledgers or distribution? Then it belongs to yPulse. Should every project inherit it, like analytics or SEO defaults? Then it goes into the template repositories. Only if all three fail, and it has its own output and its own users, does it get a new repository.

I wrote down what a new repository costs too. It needs its own feature ledger and release process, a webhook, and an instructions file for the AI to read. The matrix table grows a row, and every project's colour shifts one place along. Putting something in an existing repository is far cheaper.

The document has turned a project away. On 4 September I removed yGraphify from the matrix. It had two parts, a showcase of a design system and a replica of a landing page. The first is what yBlocks, my component library, exists to do; the second is what yLookbook, my design lab, exists to do. yGraphify had been a second half-finished version of the same capability from the start; nobody had checked it against the table. It had fourteen commits, and its README was still the one create-next-app generates.

It has let a new repository in, too. yListen, set up on 18 September, is a live interpreting tool for macOS. It has to capture system audio, show a floating window that doesn't steal focus and run a model locally. The one desktop project in the matrix, yTools, is built on Tauri, and eighty per cent of this app's difficulty sits on Apple's side of the APIs, so it is native Swift in its own repository. A different runtime is a reason the matrix accepts for splitting. In the same entry I wrote that it would not get a Swift template of its own: the matrix extracts a template when a second instance appears, and there is only one.

A rule about graduation came later, taken from how yLookbook already worked. Things are born in a lab and compared side by side; when they are ready they graduate into a product repository, and the lab keeps only a pointer to where they went. After graduation the product repository is the source of truth and the lab's entry is just a link.

There are several examples now. At the end of September the mathematical films left yLookbook and became yAtlas, with a site of their own. On 1 October a page in yLookbook that measures disk usage graduated into a desktop app, yIsobath, which scans real disks and ships installers. On 3 October the drawing code that the Drafting Sheets series kept reusing was split out as yPlotter. Since then yLookbook uses its packaged releases and no longer edits it.

Engines have a higher bar. I only consider pulling one out after more than five works of the same kind, and each engine gets one home: its repository holds the engine and nothing else, and the works stay where they were made. Tools every engine needs, like exporting video and writing export manifests, live once in yReel instead of being rebuilt inside each engine. On 10 October, when I needed a new kind of video version, I changed the one copy in yReel, and yLookbook and yAtlas each picked it up by updating a package.

Rules get broken sometimes. On 9 October the code in yLookbook that builds miniature city models was split out early as yDiorama. By the rule it wasn't ready: only one work used it, the model cabinet, and the first guide film would be the second. I decided to split it anyway, and the exception went into the document along with the reason.

Whether something joins or leaves, the reason stays on record. yGraphify still has its row in the "removed" table at the end of the document, with a long paragraph explaining why, so that when the same idea comes back in six months under another name, there is somewhere to look it up.