Runtime Layer

Harness binding — not the harness itself

The runtime adapter directory ({specialization_layer}/) is the binding between a specific agent environment and the harness (.sdlc/).

Distinction:

Concept	What it is
Agent runtime	The underlying environment — Cursor IDE, Claude Code, OpenClaw, Hermes. Provides the LLM loop.
Runtime harness	.sdlc/ + materialization + gate scripts. Operational infrastructure. Runtime-neutral.
Runtime adapter	{specialization_layer}/. Reference implementation of how one agent runtime connects to the harness.

The harness is the architecture. The adapter is how one environment implements the binding. Cursor is the primary reference implementation — not the product definition.

runtime:
  engine: cursor
  specialization_layer: .cursor/
  hooks: .cursor/hooks.json
  context_injection: sessionStart

---

Supported adapters (reference implementations)

Runtime	Directory	Status
cursor	.cursor/	Primary reference implementation
claude	.claude/	Adapter contract defined
openclaw	.openclaw/	Adapter contract defined
hermes-agent	.hermes/	Adapter contract defined

Install selects the adapter:

npx @jambu/ai-native-sdlc@latest install --runtime cursor
ai-native-sdlc install --runtime claude

Each adapter implements the same binding contract:

Subsystem	Binds
rules/	Always-applied harness constraints into runtime injection
commands/	Orchestration entry points → .sdlc/workflows/
agents/	Cognitive role personas for workflow stages
skills/	Callable SDLC procedures
memories/	Structured operational cognition state
hooks.json + hooks/	Lifecycle interception — hydration, trace, handoff

The AIDLC Tracks model separates lifecycle methodology from tool-specific implementation. Runtime adapters are Tracks: same harness, different binding mechanism.

Swap adapter: reinstall + update runtime.engine and specialization_layer in DSL. Harness unchanged.

---

The agent is a coordinator

Agents are isolated cognitive execution contexts — not monolithic executors.

Each agent owns one workflow stage: planner decomposes, implementer writes code, reviewer gates, QA validates in browser. Subagents dispatch in isolated threads/worktrees to reduce context contamination and cognitive drift.

The agent’s responsibilities:

• reason and decompose
• select and coordinate capabilities
• provision playbooks when stages require domain expertise
• validate flows within stage bounds

The agent does not hold:

• operational expertise (→ playbooks)
• SDLC orchestration patterns (→ skills)
• stage transition authority (→ gate scripts)
• session continuity (→ hooks + handoffs)

---

Hooks — lifecycle interception infrastructure

Hooks transform the agent runtime into an interceptable operational structure.

Event	Harness action
sessionStart	Hydrate: handoff, memories, DSL status, active run, trace URL
beforeSubmitPrompt	Runtime trace collection
afterAgentResponse	Trace + telemetry
afterFileEdit	Trace file mutations
stop	Memory consolidation prompt + mandatory /handoff
subagentStart/Stop	Dispatch tracking for gate verification

sessionStart output: the runtime never begins empty. Procedural continuity is injected before the first prompt.

Other adapters implement equivalent hook points via their native extension mechanisms. Trace store (.sdlc/trace/) and DSL are shared.

See Observability.

---

Commands — orchestration entry points

Commands are not executors. They are high-level intent interfaces that trigger the full orchestration chain:

/sdlc:e2e
    → load run manifest
    → dispatch subagents per ticket
    → enforce gates at each stage transition
    → provision playbooks when stages require domain expertise

Examples:

Command	Orchestrates
/sdlc:init	bootstrap-flow — repository discovery + materialization
/sdlc:doctor	alignment validation across DSL, code, credentials
/sdlc:e2e	full macro orchestration
/implement-feature	feature-flow per ticket
/sdlc:learn	playbook acquisition pipeline

Each command references a workflow YAML binding in the DSL.

---

Memories — structured operational cognition

{specialization_layer}/memories/*.md — not chat history, not documentation dumps.

File	Holds
architecture.md	Stack invariants, structural constraints
operational-context.md	Sprint state, active work, phase
business-rules.md	Domain constraints
incidents.md	Open/closed incident records

Event-driven updates. Stale memory → incorrect agent behavior on next session. Stop hook prompts consolidation; doctor validates baseline alignment.

---

MCPs — user-supplied runtime tools

MCP servers are configured by the user in their runtime environment. The harness declares requirements in sdlc.yaml:

runtime:
  mcps:
    - name: playwright
      required: true
      purpose: Browser automation for QA

Doctor verifies declared MCPs are reachable. The harness defines when browser automation is needed in QA workflow stages. The user supplies how via MCP setup.

Integrations (ticket API, deploy API) and MCPs (agent tool servers) are different layers. See Integrations.

---

Operational consequences

Adapter ≠ harness. Replacing Cursor with Claude changes the binding, not the procedural DSL or gate scripts.

Hooks are continuity infrastructure. Without sessionStart hydration, every session reconstructs state from scratch — defeating long-horizon execution.

Agents in isolation are insufficient. A planner without harness context, gates, and handoffs is a chat session — not an SDLC runtime.

Reference implementation honesty. Only Cursor adapter is fully implemented in the npm package today. Other adapters follow the same contract; implementation status varies.