Pragmatic, target-driven evolutionary architecture

State: open/published

Summary

Architecture evolves pragmatically, but every decision targets a known end state.
Pragmatic without a target is drift; target without pragmatism is paralysis.
Target: a deterministic workflow engine with LLMs as injected tools, provider-agnostic. Today’s Claude-Code-hosted shape is the starting point, not the destination.
Lateral moves are allowed. A regression is justified in a Decision linked from the PR.

Statement

The architecture evolves pragmatically, feature by feature and milestone by milestone, and every decision is driven by a known target end state. The current shape is the practical starting point, not necessarily where the system is going.

Why

Building the ideal system on day one is impossible: there is not enough information, time, or evidence to justify the cost. But building only what is needed today, with no target, produces a series of locally rational decisions whose sum is incoherent and has to be re-architected before progress can continue.

Combining the two resolves both failures. Each decision is small (pragmatic), and each is evaluated against the target (target-driven). When they pull apart, the target wins on direction and the pragmatic side wins on sequencing.

How it applies

The target end state for SDLC today:

A peer-to-peer distributed work runner for secure, autonomous software development: a self-contained binary on each user’s machine, coordinating over one shared ref authority. Several machines, no control plane; an always-on host is one more peer, never a requirement (D-VSLI-distributed-work-runner-architecture).
A completely deterministic workflow engine.
LLMs injected as tools within particular workflow steps.
LLM-provider-agnostic, ideally using open-source or local models.

The current starting point: Claude Code as orchestrator and workflow executor, with several engines (Claude Code, Codex, and others) as coding agents behind one agent-driver seam. Past the engine cutover, the engine is the orchestrator and workflow executor and the harness is an agent driver only.

Every architecture decision asks: does this move toward the target or away from it? Lateral moves are allowed and often needed to consolidate before the next step. A regression, a change that moves the system away from the target above, is justified in a Decision under docs/planning/decisions/ linked from the PR that lands it; a PR that regresses without that link is not ready to merge.

In practice:

The op and entity substrate (solutions/ontological/) is harness-agnostic (P-0008-harness-agnostic-substrate owns that posture): a target-driven choice in today’s pragmatic packaging.
The CLI surface (S-0004-sdlc-cli-llm-head-deterministic-tail) is deterministic tails with LLM heads, so the tails are reusable from any harness.
Decisions capture the discussion that shapes a rule; Standards capture the rule that outlives it. The rules accumulate even as the discussion form changes.

Examples

S-0004-sdlc-cli-llm-head-deterministic-tail: today’s mixed head-plus-tail surface is the pragmatic step; the target is for the tail to absorb more of what the head does.
Milestone order: a roadmap manifest was the pragmatic step, a frontmatter version field the target. The manifest retired once the field landed (D-ORMG-data-model).

Implications

P-0001-prefer-deterministic-over-llm is the most concrete application: deterministic is closer to the target than LLM-orchestrated.
P-0004-leverage-best-tool is the corollary: when someone else builds the deterministic substrate, use theirs.
Premature commitment to the ideal shape is the failure mode. A feature used twice needs the next-step shape, not the target shape.

Notes

The target above is current as of 2026-05-29 and will evolve. This principle is the canonical source for it; updating the target is a deliberate act here, and downstream documentation is updated in the same change.

← Back to Principles