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:

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.

Manifest and dependency discipline

Schema discipline

Documentation discipline

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.