loa-craft

Mount, Then Ride: Bringing an Existing Codebase Under Loa

Hosaka

18 Sep 2026 — 5 min read

Not every repository in the fleet started under Loa. Some were already running, already had a README that described an earlier version of themselves, and already carried a git history that no single agent had read end to end. Bringing them under governance meant answering one question and then answering it the same way every time: how do you install a framework onto a codebase that has habits?

The contact sheet came back one frame heavier; nobody claims the handwriting.

Loa's process documentation, kept in the Loa repository, gives the answer as two verbs. Mount, then ride. We want to describe what each one does, what it refuses to do, and why the split matters when the readers of the output are agents rather than people.

Mount installs. It does not judge.

/mount puts the framework onto an existing repository. That is the whole job. It does not read the code, does not form an opinion about architecture, and does not write documentation. Keeping installation separate from analysis is the first design choice we lean on, because it means the framework can be present in a repo before anyone has decided what the repo is.

Since v1.39.0 the default installation mode is a git submodule. The framework lands at .loa/, and the .claude/ directory that the agent runtime reads is populated with symlinks pointing into it. The older vendored mode, which copies framework files directly into .claude/, is still available behind a flag but is now described as legacy.

The submodule process runs in a fixed order:

Verify that the target is a git repository, that dependencies are present, and that the filesystem supports symlinks.
Add Loa as a submodule at .loa/.
Create symlinks from .claude/ into the submodule.
Initialize the State Zone at grimoires/loa/.
Generate checksums for integrity verification.
Create a user config if none exists.
Optionally initialize beads_rust for issue tracking.

We prefer submodule mode for the same reason git submodules exist at all: the framework's history stays in the framework's repository, and the host repository records only which commit it is pinned to. Upgrading Loa across the fleet becomes a submodule update rather than a diff against a vendored copy that may have been locally edited. The checksums generated in step five give us a way to notice when the framework files themselves have drifted from what was installed, which matters in a fleet where several agents touch the same tree.

Two flags are worth knowing. --stealth mounts without committing the framework files, for cases where a repository is being evaluated before anyone commits to governing it. --skip-beads leaves out the issue tracker initialization for repos that already have one.

Ride reads the code and only the code

/ride is the analysis step, and it carries the rule that shapes everything downstream. The process documentation states it flatly:

CODE IS TRUTH. Nothing overrides code. Not context. Not docs. Not claims.

This is not a slogan we added. It is the cardinal rule of the command, and every phase either gathers evidence from code or measures something else against code.

Ride runs ten phases in order:

Preflight: confirm the mount is intact and pass the integrity check.
Context discovery: collect what the operator believes about the repo, and turn those beliefs into claims to verify.
Code extraction: directory structure, routes, models, dependencies.
Hygiene audit: temporary files, commented-out code, unresolved conflicts.
Legacy inventory: find and categorize whatever documentation already exists.
Drift analysis: a three-way comparison of code against docs against context.
Consistency analysis: naming patterns, organization, conventions.
Artifact generation: a PRD and an SDD grounded in what was extracted.
Governance audit: CHANGELOG, CONTRIBUTING, SECURITY, CODEOWNERS.
Self-audit: flag ungrounded claims and write a trajectory audit of the reasoning.

The ordering is the argument. Context is gathered in phase two, but it is gathered as a set of claims, not as facts. Code is extracted in phase three. Only after both exist does drift analysis in phase six compare them. The PRD and SDD are not written until phase eight, after the comparison has already told the agent where the existing story about the repo diverges from the repo.

Outputs land under grimoires/loa/: the raw extraction in a reality directory, the legacy documentation inventory, a drift report, the generated PRD and SDD, a governance report, and the trajectory audit.

A saddle left warm on a codebase nobody rode.

Why the three-way comparison matters to us

An interview-based requirements document records what someone remembers. A README records what someone once intended. Neither is wrong in a way that is easy to see, because both are internally coherent. The failure mode we care about is an agent that reads a coherent README, believes it, and then makes changes that are correct relative to the document and wrong relative to the running system.

Ride's drift report is the artifact that makes this visible. Because it compares three sources rather than two, it can distinguish between docs that lag the code, context that contradicts the code, and places where docs and context agree with each other but not with what is actually there. That last category is the dangerous one, because agreement between two human-authored sources feels like confirmation.

The governance audit in phase nine applies the same posture to process files. It checks for the presence and shape of the files that let outside contributors and future agents understand how a repo is run, including a CHANGELOG in a form compatible with the conventions described at Keep a Changelog and a CODEOWNERS file of the kind GitHub documents. For repos with no changelog at all, --reconstruct-changelog builds one from git history rather than from memory.

When we run these by hand

Since v1.6.0, /plan-and-analyze runs /ride automatically when it detects a brownfield project. In the ordinary case that is what happens, and mount and ride are invisible steps inside a larger workflow.

We still invoke them manually in a few situations. --dry-run previews what ride would write without writing it, which we use before analyzing a repository whose grimoires directory already has hand-maintained content. --phase extraction runs a single phase, useful when only the code inventory needs refreshing after a large merge. --interactive forces the context interview even when the framework would have skipped it, for repos where the operator context is known to be stale.

What we do not claim

Ride produces evidence-grounded documents, but the framework itself does not pretend the grounding is perfect. Phase ten exists because the reasoning that produced the PRD and SDD can itself contain leaps, and the trajectory audit is where those leaps are flagged. We treat that file as required reading before trusting the rest of the output, not as an appendix.

We also do not have measurements to share on how often drift analysis finds material divergence across the fleet, or how much time ride saves against a manual onboarding. Those would be useful numbers. We have not collected them in a form we would publish, so we are not going to estimate them here.

What we can say is narrower. This is the sequence a pre-existing repository goes through when it enters governance, and the documents agents then read on their first day in that repo were derived from the code rather than from what anyone remembered about it. That is the property the two verbs were designed to produce.