Pragmatic, target-driven evolutionary architecture
Status: open/published
Summary
Section titled “Summary”- Architecture evolves pragmatically, but every decision targets a known end state.
- Pragmatic without target is drift; target without pragmatism is paralysis.
- Target: deterministic workflow engine with LLMs as injected tools, provider-agnostic. Today’s Claude-Code-hosted shape is the practical starting point, not the destination.
- Lateral moves are allowed; regressions need explicit justification.
Statement
Section titled “Statement”The system’s architecture evolves pragmatically, feature by feature and milestone by milestone, but decisions are driven by a known target end state. The current shape is not necessarily where the system is going; it’s the practical starting point. Pragmatic without a target is drift; target without pragmatism is paralysis.
Building the ideal system on day one is impossible: there isn’t enough information, time, or working evidence to justify the cost. But building “just what’s needed today” with no North Star produces a series of locally-rational decisions whose sum is incoherent, and the resulting mound of accidents has to be re-architected before further progress can land.
The pragmatic-target combination resolves both failure modes. Each decision is small (pragmatic), but every decision is evaluated against the known target (target-driven). When the two pull apart, the target wins on direction and the pragmatic side wins on sequencing.
How it applies
Section titled “How it applies”The known target end state for SDLC today:
- A peer-to-peer distributed work runner supporting 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 LLM models.
The current practical starting point:
- Using Claude Code as orchestrator, workflow executor, and sole coding agent. Past the engine cutover it is the agent-driver implementation only; the engine is the orchestrator and workflow executor.
Every architecture decision asks: does this move toward the target or away from it? Lateral moves are allowed (often necessary to consolidate before the next forward step); regressions need explicit justification.
In practice:
- The plugin architecture (skills under
plugin/skills/, validators inplugin/validators/, scripts inplugin/scripts/) is shaped to be harness-agnostic: the data model and validators don’t depend on Claude Code, so the same artifacts can be operated by a future CLI, web UI, or alternate harness. A target-driven choice expressed in today’s pragmatic packaging. - The CLI surface ([S0004]) is structured as deterministic tails with LLM heads, so the tails are reusable from any harness. Target-driven.
- ADRs and Standards distinguish between the discussion that shapes a decision (ADR) and the rule that hardens out of it (Standard); the rule outlives the discussion. Target-driven: the rules accumulate even as the discussion form changes.
Examples
Section titled “Examples”- Plugin architecture shaped harness-agnostic today even though Claude Code is the only consumer: a target-driven choice (P-0008-harness-agnostic-substrate) expressed in current pragmatic packaging.
- S0004 sdlc-cli ADR: today’s mixed LLM-head + deterministic-tail surface is the pragmatic step; the target is for the tail to absorb more of what the head does.
- ADR vs Standard separation: ADRs capture the discussion that may evolve; Standards capture the rule that outlives it. Target-driven: rules accumulate even as discussion form changes.
- Roadmap manifest as canonical milestone order, with frontmatter
order:deferred until reshape pressure justifies it.
Implications
Section titled “Implications”- P-0001-prefer-deterministic-over-llm is the most concrete application of this principle: deterministic is closer to the target than LLM-orchestrated.
- P-0004-leverage-best-tool is the corollary that says: when someone else is building the deterministic substrate, use theirs; don’t reinvent the path to the target.
- Premature commitment to ideal shape is the failure mode. A feature used twice doesn’t need to be the target-shaped feature yet; it needs to be the next-step-shaped feature.
- The natural-progression model in P-0001-prefer-deterministic-over-llm is the operationalization of “pragmatic toward target”: each stage is a known, named step on the path.
- The known target state is current as of 2026-05-29 and is expected to evolve as the system learns. This principle is the canonical source; updating the target is a deliberate act here, and downstream documentation (the README’s architectural philosophy in particular) should be updated to match in the same change.