Distribution

npm package distribution and two-phase init protocol.

What gets installed

The npm package @jambu/ai-native-sdlc distributes:

SDLC framework — .sdlc/ templates: DSL, workflows, gate scripts, playbook schema, doctor
Runtime adapter — one of cursor, claude, openclaw, hermes-agent

It does not distribute application code, pre-filled integration manifests, or MCP configuration. Those are generated or configured during init and by the user.

Installation

# Option A: zero global install (preferred)
npx @jambu/ai-native-sdlc@latest install

# Option B: global CLI
npm install -g @jambu/ai-native-sdlc
ai-native-sdlc install --runtime cursor
ai-native-sdlc install --runtime claude
ai-native-sdlc install --runtime openclaw
ai-native-sdlc install --runtime hermes-agent

Additional CLI commands:

npx @jambu/ai-native-sdlc doctor [--fix]
npx @jambu/ai-native-sdlc trace          # cognitive trace server

Two-phase model

Phase	Actor	Command	Output
Install	CLI (deterministic)	`npx @jambu/ai-native-sdlc@latest install [--runtime {name}]`	`.sdlc/` + adapter; `status: uninitialized`; empty integrations
Specialize	Agent via runtime	`/sdlc:init [intent]`	Repository-bound DSL; stack profile; generated integration manifests; `status: operational`
Mutate	Agent via runtime	`/sdlc:config <directive>`	Post-init integration add/remove/swap

Phase 1 constraints

CLI install MUST NOT:

Modify application code
Install app dependencies
Prompt for secrets
Pre-materialize integration configs

Phase 2 — init learns the repository

/sdlc:init runs bootstrap-flow.yaml v2 (ADR-029). The runtime:

Discovers structure (/sdlc:discovery or inline scan)
Confirms workspace.target_root — any path, any language
Detects or declares stack profile
Walks the init questionnaire (.sdlc/templates/init-questionnaire.yaml) — lifecycle slots with explicit opt-in; skip = none or framework default
Writes .sdlc/pipeline/.init-selections.json with confirmed_at; validates via python3 .sdlc/bin/sdlc_init_validate.py
Materializes integrations via integration mutator + slot-aware catalog-patch.ts (GitHub incident fragments only when user opts in)
Collects credentials from the union manifest — never before slot confirmation
Sets status: operational

Incident agent runtime (Cursor SDK vs Claude vs human-in-loop) is a separate decision from IDE runtime (install --runtime). No demo secrets (e.g. CURSOR_API_KEY) materialize unless the incident slot is explicitly selected.

After init, the project is integrated end-to-end: workflows bound, gates active, doctor validates alignment. No manual wiring of individual workflow stages.

Workspace decoupling

workspace:
  target_root: .              # or app/, packages/web/, backend/, …
  profile: python-fastapi     # detected or declared
status: operational

target_root is a pointer, not a convention. The authoring repo uses app/ for dogfooding. Your repo might use . for a single-package Python service or packages/frontend/ in a monorepo.

All SDLC scripts, CI templates, and doctor checks resolve application paths through workspace.target_root via sdlc_dsl_bindings.py.

What appears after install vs after init

After install only:

your-repo/
├── .sdlc/
│   ├── sdlc.yaml          # status: uninitialized
│   ├── workflows/       # generic stage contracts
│   ├── bin/               # gate scripts, playbook CLI
│   └── integrations/    # empty
├── .cursor/               # or .claude/, .openclaw/, .hermes/
└── {your existing code}   # untouched

After init:

your-repo/
├── .sdlc/
│   ├── sdlc.yaml          # status: operational, workspace bound
│   └── integrations/
│       └── {chosen providers}/   # manifests generated
├── .cursor/               # stack-specific rules added
└── {target_root}/         # profile detected, paths wired in CI

Runtime adapter selection

ai-native-sdlc install --runtime cursor      # → .cursor/
ai-native-sdlc install --runtime claude      # → .claude/
ai-native-sdlc install --runtime openclaw    # → .openclaw/
ai-native-sdlc install --runtime hermes-agent # → .hermes/

Declared in DSL after install:

runtime:
  engine: cursor
  specialization_layer: .cursor/

Swap runtime: reinstall adapter, update runtime.engine and specialization_layer. Workflows and gates unchanged.

See Runtime Layer.

Integration materialization

Integrations are not bundled. Init generates them from the catalog when slots are selected; catalog-patch.ts merges provider-specific fragments (e.g. GitHub incident) only for opted-in slots. See Integrations and ADR-029.

Baseline versioning (ADR-014)

All projects — npm consumers and the authoring monorepo — share the same baseline: block in sdlc.yaml. Three layers, two git tag dimensions:

Layer	Key	Mechanism
Upstream	`baseline.sdlc_package_version`	npm semver written at CLI `install`
Downstream	`baseline.sdlc_baseline_tag`	Local git tag; mandatory after init
App (optional)	`baseline.app_baseline_tag`	Local git tag; app tree restore on reset

Consumer projects

After ai-native-sdlc install + /sdlc:init:

baseline:
  sdlc_package_version: "0.1.0"   # from @jambu/ai-native-sdlc package.json
  sdlc_baseline_tag: my-app-sdlc-v1.0.0
  app_baseline_tag: null            # optional
  last_sdlc_baseline_date: "2026-05-27"

Action	Command	Tag pattern
First tag	`/sdlc:baseline` → `sdlc_baseline.py init` (after init — not during `/sdlc:init`, ADR-029)
Advance	`/sdlc:baseline` → `sdlc_baseline.py advance`	`{slug}-sdlc-v1.{N+1}.0`
Verify	`python3 .sdlc/bin/sdlc_baseline.py verify`	`git rev-parse $TAG`
Reset	`scripts/reset.sh`	Restores app from `app_baseline_tag`; clears session state

Consumer baseline advance does not require packages/ sync or authoring-monorepo tag names. Authoring v0.N.0-sdlc tags are local to the authoring repo and never distributed.

Authoring monorepo

This repository uses the same schema. Its downstream tags follow v0.{N}.0-sdlc (e.g. v0.19.0-sdlc). Advancing baseline additionally requires sync-templates.sh + npm run build so packages/ai-native-sdlc/ matches the cognitive layer being tagged.

Doctor Group 5 validates that sdlc_baseline_tag resolves in git when status: operational, and warns on structural drift. See /sdlc:doctor and ADR-014.

Workspace rebind

When target_root changes after init:

python3 .sdlc/bin/sdlc_workspace_rebind.py --target packages/api --profile python-fastapi

Patches DSL, CI working-directory paths, deploy integration bindings, architecture memory. Blocked until doctor gate workspace:ci-target-aligned passes.

Operational consequences

Install is deterministic; init is conversational. CLI stops at template copy. Stack and slot selection require agent guidance because intent varies.

Empty integrations after install is correct. Not an error state.

Doctor is the operational gate. Check Groups 1–6: DSL sync, integration credentials, hooks, baseline, gates, directory indices.

Any project, any stack. Init binds the generic workflow library to a specific repository. The DSL specializes; the workflows do not multiply.