Principles

Principles, projected from principle entities. Edit a principle entity and regenerate.

Emerging / retired:

Id	Title	Summary	State
Avoid deferring small or trivial work items	Avoid deferring small or trivial work items	- Self-referencing improvements ship with their migrations: when a new standard, principle, format, or convention is defined, the corpus is brought into compliance in the same parent unit of work.	open/draft
Disclose a CLI’s surface progressively	Disclose a CLI’s surface progressively	- A command-line tool reveals itself in tiers: the first screen is the smallest set that gets someone working, and everything else is one explicit question away.	open/draft
Serve humans, agents, and scripts from one command	Serve humans, agents, and scripts from one command	- Every command has three readers, a person at a terminal, an agent reading the output as context, and a script parsing it, and one implementation serves all three by varying the output, not by growing a second tool.	open/draft

Id	Title	Summary
Business logic lives in the backend	Business logic lives in the backend	- Business logic and process state live in a backend. A frontend renders, holds view state and caches backend reads.
Capture execution data; aggregate, surface, and act on signals	Capture execution data; aggregate, surface, and act on signals	- Every workflow captures structured execution data: what happened, what surprised, what failed, what took too long.
Develop SDLC in a self-hosting way wherever possible	Develop SDLC in a self-hosting way wherever possible	- SDLC is built using SDLC: its planning artifacts describe its own work, its lifecycle drives that work, and its validators check what it produces.
Favor long-lived data formats (markdown + frontmatter)	Favor long-lived data formats (markdown + frontmatter)	- The substrate is plain text under git: markdown with YAML frontmatter.
Harness-agnostic substrate	Harness-agnostic substrate	- SDLC’s artifacts (markdown, schemas, validators, scripts) work without Claude Code.
Leverage the best available tool; don’t reinvent substrate	Leverage the best available tool; don’t reinvent substrate	- Leverage external tools and agents built by parties with more resources; do not build parallel implementations.
Mutations are fully addressed	Mutations are fully addressed	- A mutation API names its target in full, in its type: not by convention, and not by a leading positional argument reassembled downstream.
Operationalize Recurrent Activities Through Processes	Operationalize Recurrent Activities Through Processes	- Any [[TM-0013-reoccurring-workflow\|reoccurring workflow]] becomes a defined process: captured, executable, repeatable. This principle owns the capture decision; maturation of the captured process is [[P-0001-prefer-deterministic-over-llm]].
Pragmatic, target-driven evolutionary architecture	Pragmatic, target-driven evolutionary architecture	- Architecture evolves pragmatically, but every decision targets a known end state.
Prefer deterministic action over indeterminate LLM action when possible	Prefer deterministic action over indeterminate LLM action when possible	- A captured workflow matures toward deterministic form (script, code) as its shape settles. LLM orchestration is the bootstrap form, not the destination. Whether a [[TM-0013-reoccurring-workflow\|reoccurring workflow]] earns capture at all is [[P-0002-operationalize-activity]]‘s call; this principle governs maturation from there.
Rust core, adapters as needed	Rust core, adapters as needed	- Build the core in Rust; add a language adapter when a consumer needs one, never in anticipation.
Schema over prose; model everything that can be modeled	Schema over prose; model everything that can be modeled	- Every entity is a schema-validated artifact, not prose alone; the frontmatter contract is parsed once and consumed by tooling.
Surface system shape; don’t hide it	Surface system shape; don’t hide it	- Every system SDLC defines publishes its own structure in `docs/`: the entity roster, the work queue, and where decisions live, derivable without reading code or asking a maintainer.
Tests and agents run apps against a scratch root, never a person’s real data	Tests and agents run apps against a scratch root, never a person’s real data	- Tests and agents run apps against a scratch root and never touch a person’s real data.
Understandability by humans is a critical aspect of development	Understandability by humans is a critical aspect of development	- As agents write more of the code, a human’s ability to understand what changed and why is the constraint that keeps the system steerable.