Architecture

This page is for engineers who need the full runtime decomposition: how workflow methodology, harness infrastructure, and your application stack relate. Read How It Works first if you need onboarding; return here for C4-level structure and a worked execution slice.

What this is

AI Native SDLC is a Procedural Cognitive Runtime Architecture — operational infrastructure for long-horizon cognitive execution in software engineering.

The central object is not the LLM. It is not the agent persona. It is the runtime harness: the layer that coordinates, governs, provisions, validates, and evolves procedural cognitive execution across sessions, agents, and environments.

LLMs provide inference. The harness provides continuity, governance, and operational integrity.

---

The organizing problem

Modern agent runtimes can reason, plan, call tools, and produce code. In isolation, that loop handles short tasks well.

It fails at long-horizon engineering because:

• context is a finite resource — context explosion is structural, not incidental
• sessions start cold — no durable operational state survives session boundaries
• “done” is a language claim — not a verified stage transition
• expertise lives in prompts — not in reusable, versionable procedural infrastructure
• observability stops at tool calls — the SDLC process itself is invisible

The architecture exists to solve long-horizon procedural cognitive execution — sustaining multi-session, multi-agent, end-to-end engineering workflows without contextual collapse.

---

Runtime harness vs agent

A common confusion: treating the agent as the architecture.

Layer	Role
LLM	Inference — reasoning, decomposition, adaptive decisions
Agent persona	Specialized cognitive role — planner, implementer, reviewer, QA
Runtime harness	Operational infrastructure — lifecycle, hooks, memory, gates, orchestration
Procedural DSL	Executable specification — what the harness must sustain
Materialization	Deterministic enforcement — doctor, gates, init, integration provisioning

The agent coordinates. It does not hold operational expertise.

Expertise is externalized procedurally through:

• skills — SDLC orchestration compositions
• playbooks — atomic domain procedural specifications
• commands — orchestration entry points
• workflows — stage contracts bound to the DSL
• memories — structured operational cognition state
• handoffs — session continuity artifacts

The agent’s job: reason, decompose, select, coordinate, provision capabilities, validate flows, manage execution. The harness’s job: make that coordination reproducible across time.

---

Two abstraction layers in the ecosystem

Two related but distinct layers appear in modern AI-assisted engineering. They are complementary — not competing.

Workflow layer (AI-DLC)

Methodologies like AIDLC formalize AI-assisted software delivery workflows:

• lifecycle phases from intent to deployment
• multi-agent collaboration patterns
• evidence gates and quality criteria
• orchestration of planning, implementation, review, QA

Core question:

How do AI systems participate in software development workflows?

Abstraction: process-centric.

Runtime substrate (AI Native SDLC)

AI Native SDLC formalizes the infrastructure underneath those workflows:

• runtime harness and lifecycle management
• procedural DSL as operational source of truth
• deterministic materialization and gate enforcement
• contextual hydration and session continuity
• cognitive trace and procedural observability
• playbook-based expertise provisioning
• SDLC baseline versioning

Core question:

How do runtime architectures sustain long-horizon procedural cognitive execution?

Abstraction: runtime-centric.

┌─────────────────────────────────────────────────────────┐
│  Workflow Layer                                         │
│  Lifecycle methodology · stages · evidence gates        │
│  (AIDLC-style delivery workflows)                       │
└──────────────────────────┬──────────────────────────────┘
                           │ runs on
┌──────────────────────────▼──────────────────────────────┐
│  Runtime Substrate (AI Native SDLC)                     │
│  Harness · DSL · materialization · hooks · trace        │
└──────────────────────────┬──────────────────────────────┘
                           │ builds
┌──────────────────────────▼──────────────────────────────┐
│  Application ({workspace.target_root}/)                 │
│  Any language · any structure · any framework           │
└─────────────────────────────────────────────────────────┘

Workflow documentation tells you what stages exist. Runtime documentation tells you how execution survives between stages and sessions.

C4 system context

flowchart TB
    subgraph external["External"]
        DEV["Engineer / Agent"]
        PLANE["Plane"]
        GH["GitHub / CI"]
        OBS["Observability"]
    end
    subgraph system["AI Native SDLC"]
        HARNESS["Runtime Harness"]
    end
    subgraph app_layer["Application"]
        APP["target_root/"]
    end
    DEV --> HARNESS
    HARNESS --> PLANE
    HARNESS --> GH
    HARNESS --> OBS
    HARNESS --> APP

C4 container view

flowchart TB
    subgraph adapter["Runtime Adapter"]
        HOOKS["Hooks"]
        SKILLS["Skills & Commands"]
    end
    subgraph harness["Harness (.sdlc/)"]
        DSL["sdlc.yaml"]
        WF["Workflows"]
        PB["Playbooks"]
        GATES["Gates"]
        TRACE["Trace"]
    end
    HOOKS --> TRACE
    SKILLS --> PB
    SKILLS --> WF
    DSL --> GATES
    WF --> GATES
    GATES --> APP["Application"]

For the canonical workflow-vs-runtime comparison, see Workflow vs Runtime — this page focuses on harness decomposition.

---

Repository structure

Three cooperating regions in every AI Native SDLC project:

┌─────────────────────────────────────────────────────────┐
│  Runtime Adapter ({specialization_layer}/)              │
│  Reference implementation of harness binding            │
│  cursor | claude | openclaw | hermes-agent              │
└──────────────────────────┬──────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────┐
│  Harness (.sdlc/)                                       │
│  DSL · workflows · gates · bin/ · INDEX · trace         │
└──────────────────────────┬──────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────┐
│  Application ({workspace.target_root}/)                 │
│  Your project — unchanged by install                    │
└─────────────────────────────────────────────────────────┘

workspace.target_root binds harness to application. It can point to ., packages/api/, backend/, or any path. The authoring repository uses app/ for dogfooding — not as a structural invariant.

Feature code never lives in .sdlc/ or the adapter directory. SDLC infrastructure survives project resets. Application code is ephemeral work isolated in git worktrees.

---

The procedural DSL

.sdlc/sdlc.yaml is the operational source of truth. Not documentation — executable operational specification.

It defines:

Section	Specifies
workspace	Application root and stack profile
runtime	Active adapter and hook bindings
gates	Deterministic stage-transition contracts
workflows	Command → YAML stage graph bindings
integrations	Materialized plug-in manifests (empty until init)
constraints	Worktrees, handoffs, ticket requirements
qa	Evidence policy

Everything the harness must sustain operationally is declared here. Runtime adapters, integration manifests, CI templates, and gate scripts are projections of the DSL — not independent sources of truth.

See Operational Layer and Workflows.

---

Materialization layer

Declarative DSL without deterministic enforcement produces operational drift.

The materialization layer interprets the DSL and builds verifiable runtime state:

Mechanism	Role
/sdlc:init	Discovers repository, binds workspace, generates integration manifests
/sdlc:config	Adds, removes, or swaps integration plug-ins post-init
/sdlc:doctor	Validates DSL ↔ code ↔ credentials ↔ directory indices alignment
sdlc_gate_check.py	Blocks stage transitions without artifact proof
sdlc_workspace_rebind.py	Retargets target_root across CI and integration bindings
Integration mutator	Generates {provider}.yaml manifests from catalog templates

If the DSL declares a Jira integration, materialization verifies API credentials exist. If a gate declares feature_flow_complete, materialization checks manifest fields — not agent assertions.

Runtime state cannot depend only on probabilistic inference.

See Materialization.

---

Inference vs governed execution

The architecture enforces an explicit separation:

Inference — what the LLM decides adaptively within a stage (implementation approach, error recovery, decomposition choices).

Governed execution — what the harness permits deterministically (stage transitions, gate passage, handoff recording, integration availability, worktree isolation).

Playbooks sit between the two: they formalize domain procedure (what, how, validate, measure, constraints, fallbacks) while leaving adaptive execution to the agent within those bounds.

This separation is what allows long workflows without the harness trusting every natural-language completion claim.

---

Long-horizon continuity mechanisms

Hooks

Hooks transform the runtime into an interceptable operational structure. They observe, enrich, validate, and persist at every lifecycle point.

sessionStart: inject memory, handoffs, constraints, active run state, baseline procedural context. The runtime never starts empty.

stop: consolidate memory, generate handoff, prompt session closure artifacts.

See Runtime Layer.

Handoffs

When a session ends, the harness generates a handoff containing operational state, architectural decisions, pending work, artifacts produced, gate status, and expected next steps.

Handoffs bridge sessions, agents, and environments. A stub handoff fails the mark-done gate — incomplete work, not a documentation gap.

Memory

Memory is structured operational cognition — not chat history. Event-driven updates to architecture invariants, sprint state, business rules, and incident records.

SDLC baselines

The harness version-controls its own evolution separately from application code:

Baseline	Scope
app_baseline_tag	Application restore point
sdlc_baseline_tag	Harness + adapter infrastructure version

Baselines enable procedural versioning, organizational sync, runtime reproducibility, and rollback of orchestration structures — not feature code.

---

Observability: two layers

Layer	Observes
Runtime trace	Tool calls, token usage, hook execution, agent lifecycle, file edits
Cognitive trace	SDLC stages, run manifests, decomposition, tickets, workflow transitions, artifacts

Runtime trace answers: what did the agent do?

Cognitive trace answers: where is the engineering process?

Together they produce procedural observability — workflows that are auditable, navigable, and replayable.

See Observability.

---

Context as operational resource

Context is finite. The harness treats token budget as an engineering constraint:

• scoped hydration at session start — not full repository load
• lazy playbook provision — domain expertise on demand
• bracket-notation INDEX — compact navigational structure
• /sdlc:token-health — continuous audit and compression
• handoffs as lossy compression of session state

Goal: preserve operational coherence, retrieval efficiency, and stability across long executions — not merely reduce API cost.

See Context Economics.

---

SDLC Learn — procedural capability acquisition

New domain expertise enters the harness through /sdlc:learn:

research → critical synthesis → playbook materialization → delivery manifest → optional wire into workflows

Learned capabilities integrate procedurally — as .pb.yaml playbooks registered in the catalog — not as prompt dumps or chat context.

Examples from production use: pixel-perfect visual validation, DOCX generation, cognitive trace instrumentation, HTML deck scaffolding.

See Playbooks.

---

End-to-end execution

The harness coordinates the full engineering cycle from a single high-level intent:

intent → discovery → decomposition → ticket hierarchy → architecture
    → wave execution (per-ticket feature-flow in isolated worktrees)
    → integration → deploy → post-deploy validation → reflect → handoff

The operator provides intent. The harness:

• decomposes and creates tickets
• provisions playbooks and capabilities
• executes implementation through isolated subagent contexts
• validates with deterministic gates
• produces evidence and trace artifacts
• closes operational cycles through materialized integrations

Macro orchestrator (/sdlc:e2e) composes workflows — it does not reimplement them.

See Lifecycle.

---

Integrations close cycles — they are not the product

Integrations connect the harness to external systems: ticket trackers, source control, CI, observability, deploy targets.

They close operational cycles — without them, the harness produces code locally but cannot complete the SDLC loop.

They are plug-ins materialized at init — manifests generated by commands and skills, not shipped pre-filled. Plane, Jira, Notion, GitHub Issues are interchangeable occupants of the work_items slot.

MCPs are user-configured runtime tools — separate from integration manifests. The harness declares requirements; the user supplies configuration.

See Integrations.

---

Reference implementation

AI Native SDLC is specification-first, runtime-agnostic, implementation-agnostic.

Runtime adapters (cursor, claude, openclaw, hermes-agent) are reference implementations of the harness binding contract. The procedural DSL, workflows, gate scripts, and materialization layer are constant.

Cursor (.cursor/) is the primary reference implementation today. Other adapters follow the same contract shape.

---

Structural indexing

Every navigable domain has an index entry point:

Artifact	Index
Project navigation	.sdlc/INDEX.md
Workflow composition	.sdlc/workflows/README.md
Runtime scripts	.sdlc/bin/README.md
Adapter subsystems	{specialization_layer}/*/README.md
Playbook catalog	.sdlc/playbooks/PLAYBOOKS.md (lazy)

Predictable entry points reduce retrieval entropy — the harness always knows where official state lives.

---

Worked vertical slice: /sdlc:e2e

One complete chain from trigger to observability — the docs-artistry elevation run:

Step	Artifact / component
Trigger	/sdlc:e2e intent → sdlc_e2e_manifest.py init
Data	.sdlc/runs/docs-artistry-20260530/manifest.yaml, architecture-review-plan
Transform	Waves JAMBU-102..105 → worktree → gpt-image-2 assets → Starlight content
Output	app/public/images/docs/*.png, updated engineering pages
Observability	.sdlc/evidence/architecture-artistry-20260530/, trace events, e2e smoke

Every stage transition is gated — agents do not self-certify completion.

---

What this is not

AI Native SDLC is not:

• a replacement for deterministic software infrastructure — it builds on top of it
• a fully probabilistic architecture — gates, doctor, and materialization are deterministic
• a single agent product — agents are coordinators within the harness
• a fixed integration stack — integrations are materialized plug-ins
• a framework for one language or stack — target_root accepts any project

The result is operational infrastructure for governed, observable, evolvable procedural cognitive execution — not an “intelligent agent.”

---

Engineering shift being formalized

The transition is not:

chatbot → autonomous AI

The transition is:

workflow-centric AI systems
        →
runtime-centric procedural cognitive systems

Workflow methodologies define what stages exist. Runtime harnesses define how execution survives them.

That is the architectural layer AI Native SDLC formalizes.