Harness-agnostic substrate
Status: open/published
Summary
Section titled “Summary”- sdlc’s artifacts (markdown, schemas, validators, scripts) work without Claude Code.
- Claude is the harness today because it’s the best available; the substrate must remain operable by any future CLI, web UI, or alternate agent.
- Deliberate complement to P0004: leverage liberally, but build abstraction proportional to swap risk. Heaviest abstraction in the LLM-tool dimension (rapid provider churn); lightest for standardized deterministic tools (git, GitHub).
- Two LLM-space pressures drive the principle: supplier risk (early-stage providers, uncertain pricing) and rapid-development advantage (capture best-of-breed model performance as the landscape shifts).
Statement
Section titled “Statement”The SDLC system as a whole is being built under the evolutionary architecture principle: pragmatic current construction directionally pointed toward an ideal end state of being LLM-provider-agnostic.
Components that touch LLM-driven agentic coding are guided to a thin, swappable LLM surface. sdlc’s artifacts (markdown files, schemas, validators, scripts) are designed to work without Claude Code. Claude is the harness today because it’s the best available; the substrate must remain operable by any future CLI, web UI, or alternate agent that reads the same files and respects the same schemas.
Supplier risk. LLM providers are in a very early business phase; end-state pricing and value propositions are unknown. Maintaining the ability to change provider, or to fall back on OSS models, reduces both risk and long-term cost.
Rapid development. Agent harness and model progress is rapid, and providers generally share similar API surfaces. Keeping flexibility makes it possible to capture best-of-breed performance as the landscape shifts.
These two pressures are LLM-space-specific. For traditional deterministic tools (git, GitHub, the TypeScript validators), the swap risk is low and the abstractions are standardized; off-the-shelf is the default per P-0004-leverage-best-tool without additional defensive layering. The harness-agnostic posture concentrates effort where the swap risk concentrates: at the LLM surface.
How it applies
Section titled “How it applies”Initial scope:
- Aligning with other principles, as much of the system as possible is or will be defined through traditional programmatic means.
- Skills (the LLM-orchestrated layer) are kept as thin as possible. Prose instruction is minimized in favor of the deterministic tails the skill calls; in some cases a skill is little more than a natural-language head over a deterministic tail ([S0004]). The tails themselves are harness-agnostic.
- New design decisions ask: “would this still work if Claude Code vanished tomorrow?” If the answer is “the deterministic substrate yes, the LLM orchestration no”, that’s the right shape.
Examples
Section titled “Examples”- Entity validation (
sdlc entities validate, underapps/sdlc/): pure TypeScript with no Claude dependencies. Runs in CI, on a contributor’s laptop, or under any future CLI. - Entity schemas as Zod TypeScript under
apps/sdlc/lib/model/entities/<type>/schema.ts, projected to plain JSON Schema: readable by any JSON-schema-aware tool. - Scaffolding as sdlc CLI verbs (e.g.
sdlc task create), standalone TypeScript: invokable without an LLM session. - The Obsidian Bases dashboard (
docs/dashboard.base) works in any Obsidian vault that opens this repo; no plugin chain required.
Implications
Section titled “Implications”- This principle is the canonical source for the harness-agnostic posture. Downstream documentation reflects it; the project’s README carries the user-facing one-liner (“harness-agnostic, eventually self-hosting”) as the short reflection of what is captured here.
- Connects to P-0001-prefer-deterministic-over-llm: the deterministic substrate is what carries forward across harnesses.
- Connects to P-0006-self-hosting-development: sdlc-on-sdlc implicitly tests that the substrate works without Claude (when the deterministic parts run in scripts and CI).
- The terms substrate, harness, and adapter (protocol adapter)
used throughout this principle are defined in
glossary.
Deliberate complement to P-0004-leverage-best-tool, not a contradiction. P0004 says lean toward off-the-shelf so we don’t reinvent substrate; this principle says keep the substrate shaped so LLM suppliers and harnesses can be swapped when the landscape shifts. Both are pragmatic from opposite directions, and together they produce the working rule: leverage liberally, abstract proportional to swap risk. The abstraction layer is heaviest in the LLM-tool dimension (rapid provider churn, supplier risk) and lightest for standardized deterministic tools (git, GitHub) where swap is cheap.