Philosophy
General working discipline for any Solid Plans Software project (the cli/command application pattern, manifest-driven modules, schema-generated types, repo adapters). These instructions are repo-agnostic: each consuming repository’s main context file supplies its concrete commands and project-specific notes, and opens with a table of contents into these documents.
They are language-agnostic too, and that is a claim with a seam behind it rather than a hope. The framework owns structure and contracts; a repo adapter owns the language it adapts. So a rule here is stated so that any adapter’s author can act on it, and how one language satisfies it is written where that language’s behaviour already lives: the obligations every adapter must meet are in the adapter contract’s README, and the mechanisms one language uses are in that adapter’s own INSTRUCTIONS.md. Python appears here as illustration and is welcome — a concrete example is easier to implement against than an abstraction, and a second language’s author reads it and does the same thing their own way. What does not appear here is a sentence that would simply be false for that second language.
One thing the seam does not divide. Commands and adapters are themselves Python, in every repository and for every language adapted, because the framework loads them in process. The target language is what an adapter abstracts, not what it is written in — a TypeScript repository is adapted by a Python adapter that shells out to tsc. So the command discipline below is host-language discipline and stays here whole; only discipline about the language being adapted crosses the seam.
This document is the why. Beside it: workflow.md for how work is done, tools.md for what to invoke, and conventions.md for the shape a finished thing has to have.
Design philosophy in practice
The framework’s premise is that a repository is data: structure, contracts, and rules are declared, validated, and generated — so tools and agents can operate on verified understanding instead of convention. When producing code, apply the premise:
-
Code is cheap; maintenance is not. Writing something is the small cost and carrying it is the large one, so decide by what a choice leaves behind rather than by what it costs today. Delete in preference to keeping: a mechanism whose upkeep exceeds its value goes, and sunk cost is not an argument for its survival — a feature that took a month to build and costs a day of every month after to keep working is deleted when that sum is noticed, and is not brought back because it once worked. Two rules further down are this one applied: unproven generality is not kept, and there are no compatibility shims.
-
Avoid third-party code. Every dependency is a security surface you do not control, a failure point you did not design, and a maintenance obligation you did not choose the timing of. The cost is not paid at adoption; it is paid years later, when an entire team is pulled off productive work to upgrade something somebody added a decade earlier — which is not an acceptable outcome for a functioning engineering team, and is a foreseeable one. The bar for taking a dependency is therefore not “would this save time this week” but “would I accept being conscripted to maintain this in five years.” Build the fundamental thing instead; it is usually smaller than it looks and it is always ours.
-
Depend on technologies, not vendors. A technology is standardised, has several implementations, and has no owner who can withdraw it — git, HTTP, POSIX, containers, SQL. Depend on those directly and concretely: wrapping git in a version-control interface of our own buys nothing, because there is no supplier there to swap. A vendor is a product somebody sells, changes, or discontinues — GitHub, a particular agent, a particular model host — and a vendor belongs behind a seam another could take over. The shape is an executor that contains no branch on which model host serves it: each host is a class behind one interface, so a third is a new class rather than another arm. Where this is not yet true it is known debt, not an exception, and it is recorded as debt, with the trigger that ends the deferral. The mistake in this direction is leaving a vendor unwrapped because there is only one of them today.
-
Stay as low-level as the problem allows. An abstraction earns its place two ways and no others: a supplier sits behind it, or it expresses a genuine domain concept that already has more than one member — target language, executor kind. It does not earn its place by taste, novelty, symmetry, or an individual’s preference for a pattern. Speculative layering — an interface because there might be a second implementation one day — is the same error as unproven generality, and is not kept for the same reason. Stay close to the vanilla language and build our own super-fundamental concepts rather than adopting somebody else’s framework for them. The mistake in this direction is a layer whose only justification is that it looks tidy.
The two together. Abstract outward, stay concrete inward — and the test is what sits on the other side of the seam. Somebody else’s product earns an abstraction. A plurality that already exists earns one. Our own code does not. Both mistakes are common and neither is cheap: an unwrapped vendor eventually forces a rewrite, and a speculative layer is maintenance nobody asked for.
-
A package is a unit of responsibility, not a wrapper for a file. A directory earns its place by being a cohesive subsystem — one concern, with its schema, generated types, validator and tests co-located — and the test is what else moves in with the file: if a file’s schema, tests and closest collaborators come along and the directory has a one-line answer to “what is this subsystem for”, it is a package; if the file arrives alone and the directory name is the file name, it is a wrapper. This is the principle behind the structure rules in
conventions.md, and it is the half those rules cannot check: a tree of one-file directories satisfies every check and is exactly as disorganized as the loose files it replaced. The mistake in this direction is treating a structural rule as a placement problem rather than as a question about what the code is for. -
Declare before you code. Before writing code by hand, ask whether the thing can be a declaration instead — a schema definition, a rule from the DSL, a command config, a manifest field. If the schema system cannot express it, prefer extending the system (a new built-in rule, a shorthand, a meta-schema field) over one-off code below it. Hand-written code is for genuine behavior only.
-
A failing validation is information about structure, never an obstacle. Fix the structure: move the code, extend the facade, vendor the contract, reclassify the edge. Weakening a check to make something pass is a design smell — if the rule itself is wrong, change the rule deliberately and document why.
-
Merge conflicts are data errors. The system detects dependencies and orders execution from them. If executing in that order produces a merge conflict, the conflict is not an event to resolve — it is evidence that the dependency calculation was wrong: an edge that was missed, mistyped, or scoped too loosely. Fix the dependency data, then re-derive the order. This is the rule above applied to ordering rather than to structure, and it asks for the same reflex: a conflict resolved by hand loses the information, so the wrong edge stays wrong and the next pair of items conflicts again for the same reason. The limit, stated so the principle is not overstated. Not every conflict is a missed dependency. Two changes can legitimately touch the same lines without either depending on the other, and adjacency in a file is not a dependency — a principle that denies this blames the graph for ordinary co-location. The claim worth making is directional: a conflict is always evidence to examine the dependency data, and usually a defect in it; a conflict that survives that examination is co-location, which is a finding rather than an evasion. One question it leaves open is the reason to settle it: dependencies are modelled between modules and conflicts happen between changes, and whether a change-level edge is derived from the module graph, declared per work item, or detected from the diff is undecided.
-
Rename the moment a name drifts. When a name stops matching what a thing does — a module, a field, a command flag, a coordinate — correct it immediately and update every reference. There are no compatibility shims to preserve; a wrong name left standing propagates wrong design.
-
Prefer the weakest honest coupling. Reference by versioned id, not path. Vendor when the reference is the only reason for a runtime edge; type-only for pure annotations; import only when the producer is a runtime dependency anyway; process invocation across executable boundaries. Never reach across a boundary because it happens to be importable.
-
A framework edge arrives by coordinate, never from a path. This is the rule above applied to delivery. An edge onto a module of the framework is obtained by coordinate: vendored from a build catalog, or vendored as a schema. An edge onto a third-party package (
pydantic,PyYAML,tzdata) is installed by the language’s package manager. The kind of an edge (runtime, build, dev, test) says when the code needs it, and its delivery says how it arrives. The two are independent, so an edge’s kind never moves because of how it is delivered. A vendored import is still a runtime edge. A path is the wrong delivery because it is found only where one machine’s layout happens to put the other checkout, and a repository cloned anywhere else cannot resolve it.module dependency detect --validatederives every edge’s delivery (vendored,vendored-schema,path,undelivered) from the repository’s own declarations and refusesundeliveredeverywhere. It refusespatheverywhere but one case, and nothing else is exempt: the repo adapter. An adapter is never installed, because several versions provide one package name. The resolver puts the resolved version’s source tree, vendored or taken from its catalog, on the import path for the length of one import. That is resolution of a dynamically chosen dependency, and it never points at a sibling checkout. -
A module has a public boundary, and consumers cross only there. An owned module (
schema,manifest,type,repo_adapter_api,repo_adapter) is reached through its package root or through a facade the module itself declares public; an internal path that merely happens to resolve is not a door. When a consumer needs a symbol the boundary does not expose, widen the boundary — do not deepen the import. In Python the declaration is__public_submodules__in the root__init__.py(schema declaresparserandgenerator), the paths it refuses areschema.src.*,manifest.__types__.*and their like, and lint rule ROI001 reads the declaration and holds every consumer to it. Another language declares its boundary differently and is held to the same rule: that a module has a resolvable public boundary is an obligation of the adapter contract, and the spelling is the adapter’s. -
One owner, one writer. Every artifact — a store ledger, a generated file, a schema — has exactly one owner. Other parties read through vendored contracts and write through the owner’s commands. If two modules share logic without a shared domain identity, dissolve toward the owner rather than extracting a shared library.
-
One declaration, not a table per fact. When several things are true of the same named thing — how it renders, what it is called elsewhere, which rules it carries, whether it belongs to a set — they belong in one entry keyed by that name, not in a separate map per fact keyed by the same names. A second map keyed by names declared elsewhere is a second declaration of the same thing, and it drifts from the first the moment either changes; the drift is silent, because each map stays internally consistent and nothing compares them. The test is what adding a member costs: one entry, or a sweep for every map that lists the existing ones. A set of built-in types described by a runtime-model map, a membership set, an annotation table and a rules map is four declarations of one list; as one entry apiece in a single map, with membership in that map serving as the membership test, a new type is one entry. This is
declare before you codeapplied to configuration: reach for the existing declaration and widen it, and extend the record it lives in when it has no room for the new fact. The mistake in this direction is adding a one-off map because the existing entry has the wrong shape for what you want to say, rather than changing its shape. -
Semantics on the type, rendering at the use site. Meaning that is the same everywhere (parsing, expansion, validation) belongs on the type; anything context-dependent (display shape, key format, path segments) is declared at the point of use. Do not bake one context’s choice into a shared type.
-
Keep interfaces domain-general. A command or module serving a general concept must not leak one consumer’s vocabulary into its interface (a package store registers packages, not schemas).
-
Every mechanism ships with a proving consumer. New capability is adopted in the repository in the same change that introduces it, and unproven generality is not kept.
-
The record keeps pace with the work. Architecture decisions land as queue notes; finished items are retired; documentation changes ride in the same change as the design they describe.
Working discipline
How work is done — the gate, which tests a change owes, how it is shipped — is workflow.md. What to invoke is tools.md. What a finished thing has to look like is conventions.md. This document is the why those three cite.
Generated artifacts
Generated files are never edited by hand. Edit the source of truth and regenerate:
| Generated | Source of truth | Regenerate with |
|---|---|---|
| a module’s generated type modules | schema.yml / *.schema.yml |
schema gen |
| a command’s generated inputs model | <command>.config.yml |
command gen |
| the app’s generated API client | registries + command configs | api gen |
The first row crosses the seam and the other two do not. What a module’s generated types are called and what shape they take is a fact about the language being adapted, rendered by the adapter’s generate_types — Python’s are the __types__/ packages. A command’s inputs model and an app’s API client are host-language artifacts and are Python in every repository: __types__/inputs.py beside the command config, and the app’s api.py.
Regeneration is deterministic, which is what makes a --validate run mean anything: a generator whose output varies between runs reports drift that is not there. That obligation is the adapter’s, and is stated in the adapter contract rather than here.
Generated values are immutable: never assign a field after construction — derive a new value carrying the change and reinsert it into the owning container. A derived value a helper makes and does not return is discarded, so a helper that reports through a value it was handed cannot be fixed by copying inside it. Pass an unchanged CommandContext through directly; construct a new one only when a field genuinely changes. How deriving one is spelled belongs to the language — model.copy(field=value) on Python’s frozen pydantic models.
If a generated file must change to unblock a bootstrap (the CLI itself cannot boot on stale generated code), hand-patch it minimally, then regenerate and confirm --validate parity.
Command development
Commands are host-language code — Python, in every repository and whatever language that repository is otherwise written in — so none of this crosses the language seam.
- Commands follow one contract:
validate(context, global_args, args)→execute(...)→format_human_output(data, global_args), exportingcommandfrom the package. - To add a command: write
<command>.config.yml, runcommand gen(generates theInputsmodel and scaffolds the implementation for new packages), implement, and register it in the group’s*.registry.yml. - Commands that delegate to the repo adapter validate with
validate_adapter_command()(checkingrequired_kind) and return the unifiedAdapterOutput. - List-type CLI inputs are nargs-style: pass
--flag a b c, not repeated flags. - A boolean input has no unset state:
optional: truewith no default still generatesbool = False, so a flag can only force a setting on (args.flag or config.key), with the config carrying the standing setting. Name the flag for the direction it forces —--skip-<behaviour>against a config key that stands on — and reach for a nullable input type when a flag genuinely needs three states. - Human output honors
--verboseviaglobal_args; payloads never carry presentation flags.
Manifest and dependency discipline
- The manifest is authoritative for project identity, modules, and the supported command surface.
- Modules declare four dependency lists —
dependencies(runtime),buildDependencies(schema generation ordering),devDependencies(needed to resolve annotations and never imported at run time;if TYPE_CHECKING:blocks in Python),testDependencies(test-time) — and detection enforces all four: after any dependency-affecting change, run bothmodule dependency list --validateandmodule dependency detect --validate; both must PASS. - A submodule reaches another module its own manifest declares, outside its top-level module, only through the boundary facade that top-level module keeps — never by importing it directly from submodule code. Fix such a violation by extending the facade, not by loosening validation. Python’s facade is
submodule_api.py. - A submodule reaches another repository’s package by declaring its coordinate and importing it itself. A dependency is declared by the module that calls it: a package declared on the top-level module and handed down through the facade is a dependency of everything nested there, so a change in it reaches every one of them, while one declared by its caller reaches the caller and what depends on it. The facade keeps what a generated type binds through it and what the nest as a whole is built on; a package one or two submodules call does not belong there.
- Modules must not depend on
kind: executablemodules. The one exception is the application’s generated API: alibrarywhoseapiOfnames the executable.api genwrites that API as a package of its own,<app>_api, so a consumer depends on a library and never on the application. Vendoring the API brings the application’s source along, which is why naming an executable inapiOfalso publishes it. Across any other boundary, integration is by process invocation. - Cycle detection runs per layer: runtime and build edges are checked separately (they execute at different times); dev and test edges are exempt.
Schema discipline
x-normalize/x-validatefield rules come from the closed, schema-transported DSL vocabulary (built-ins plus parameterized forms). A new structural rule belongs in the type runtime, not a package-local handler; uselocal:<rule>only for behavior a schema genuinely cannot carry — it breaks portability for consumers.- Cross-module schema references are id-based (
id: namespace:name@version), resolved from the seeded store;module dependency detect --validaterejects cross-module path references. Choose the consumption mode deliberately:vendor: truewhen the reference is the only reason for a runtime dependency (dissolves to a build edge), plaintargetwhen the producer is a runtime dependency anyway or class identity must be shared,typeOnlyfor annotation-only references in generic definitions. - A schema becomes id-resolvable when it declares
export: trueplusname/namespace/versionmetadata and has been registered in the store (schema genregisters exportables via the store owner). - Version-valued fields reference the canonical
versiontype and declare their rendering with a field-levelformat; when keying dicts or building store paths, render explicitly for the store’s version shape.
Documentation discipline
- Which documents a module carries, and what each one is for, is
conventions.md’s “The documentation set”. The discipline here is about keeping them true. When a change alters something a README documents — public API, command surface, config or schema shapes, adapter contract, workflow — update the affected README(s) in the same change. Check the root README and the repository’s main context file when the change is repo-wide. Don’t let docs describe the previous design.
Adoption
A consuming repository’s main context file states its concrete gate and test commands, its project-specific gotchas and procedures, and opens with the table of contents into these documents that makes them reachable.
It cites the language half from the same list, and which document that is follows from declarations the repository has already made rather than from a path somebody wires by hand: the manifest names the adapter by coordinate (repoAdapter: language:python), .dev-tool/config.yml names the repoAdapterCatalog that turns a coordinate into a package, and the language discipline is INSTRUCTIONS.md inside that package, beside the adapter’s README. A repository that has declared those two has already said where its language half is. An adapter that publishes no such document leaves nothing to cite, which is a fact about that adapter rather than a gap here.
That the document is versioned with the adapter is deliberate rather than incidental. Discipline that changes when the adapter’s behaviour changes belongs to the version that behaves that way, so a 0.1 adapter carries its own copy and the two are allowed to differ; the cost is that a correction true of both is made twice, which is what the version being meaningful costs.