How It Works

If you are new to AI Native SDLC, start with Show Me (what gets produced) and Introduction (when to adopt). This page is the install and layer map — read it before the full Architecture thesis.

Start here

1. Show Me — one intent through tickets, worktrees, evidence, deploy
2. This page — install and three-layer map
3. Architecture — internal PCRA decomposition (C4, harness names)

---

One sentence

AI Native SDLC is runtime infrastructure for long-horizon procedural cognitive execution in software engineering — not a chatbot, not a single agent, not a fixed tool stack.

The runtime harness (.sdlc/ + runtime adapter) coordinates governed execution. The LLM provides inference inside it.

---

Install

# Preferred — no global install
npx @jambu/ai-native-sdlc@latest install

# Global CLI
npm install -g @jambu/ai-native-sdlc
ai-native-sdlc install --runtime cursor    # or claude | openclaw | hermes-agent

Then in your agent runtime:

/sdlc:init

Init discovers your repository, binds workspace.target_root (any path, any language), materializes integration plug-ins, and sets the harness operational. See Materialization.

---

Three things to understand

1. The harness is the architecture — not the agent

Agents coordinate: reason, decompose, select, provision capabilities. Operational expertise lives in skills, playbooks, workflows, gates, and memory — externalized from any single persona.

2. The DSL is operational source of truth

.sdlc/sdlc.yaml specifies workspace, runtime, gates, workflows, constraints. Everything else — adapter rules, integration manifests, CI paths — is a projection materialized from it. See Operational Layer.

3. Workflow layer vs runtime substrate

Methodologies like AIDLC define delivery workflows (intent → deploy, evidence gates, lifecycle stages). AI Native SDLC defines the runtime substrate underneath (continuity, materialization, procedural observability, deterministic enforcement). They stack; they do not compete.

Workflow layer     →  what stages exist
Runtime substrate  →  how execution survives them
Application        →  what you build ({workspace.target_root}/)

---

Repository layout

{specialization_layer}/   ← runtime adapter (reference implementation)
.sdlc/                    ← harness: DSL, workflows, gates, trace
{target_root}/            ← your application (any stack)

The authoring repo uses app/ for dogfooding. Your project uses whatever path init binds.

---

Composition at a glance

/sdlc:goal  (macro orchestrator — composes, never reimplements; `/sdlc:e2e` deprecated ADR-020)
    → /implement-feature  (per ticket, isolated worktree, subagent)
        → feature-flow.yaml
            → planner → implementer → reviewer → qa
                → skills (worktree, handoff, ticket sync, qa-recording)
                    → playbooks (lazy, on provision)

One ticket → one worktree → one PR. Gates verify completion — agents do not self-certify.

---

Session continuity

sessionStart hook hydrates: handoff, memories, DSL status, active run. stop hook enforces: memory consolidation + /handoff. Stub handoff fails mark-done gate.

The harness never starts empty. Long-horizon execution requires this.

---

What closes the SDLC loop

Integrations are plug-ins materialized at init — not bundled product. They close cycles:

Slot	Closes
work_items	Ticket → spec → PR → Done
source_control + ci	Branch → PR → merge gate
observability	Production errors → incident flow
deploy	Build → staging → production

Plane, Jira, Notion, GitHub Issues are interchangeable work_items providers. Same workflows regardless.

MCPs are user-configured — the harness declares requirements; you supply setup.

---

Documentation map

Read	For
Architecture	Full runtime harness thesis
Materialization	Init, doctor, gates, manifest generation
Runtime Layer	Adapter contract, hooks, reference implementations
Workflows	DSL stage contracts
Composition Stack	Playbooks → skills → commands → agents
Integrations	Lifecycle slot plug-ins
Playbooks	Domain procedural specifications
Observability	Runtime trace + cognitive trace
Lifecycle	End-to-end execution path
Gates	Deterministic enforcement
Context Economics	Token budget as engineering constraint
Distribution	Install, init, baselines