@levi-putna/sdlc

Installer and version manager for the Agentic SDLC development harness. Pulls the framework live off main of levi-putna/sdlc into your project and wires it up for whichever coding agents you choose.

Commands

npx @levi-putna/sdlc init [--agents claude,cursor,...] [--yes] [--cwd <path>]

Set up this project. Runs an interactive wizard to pick coding agents unless --agents is given. --yes with no --agents defaults to claude and skips everything below — no prompts at all.

In the interactive wizard, after installing the framework it also asks whether you already have requirements documented somewhere. If so, give it a path (file or folder, typed or pasted) — Claude Code is told to read directly from that location as the authoritative source for Stage 1 rather than copying it into the repo (Stage 1's gate check still needs at least one file under ./requirements/, so it's asked to leave a small pointer file there instead of duplicating the content). If the path is outside the project, the eventual claude invocation gets --add-dir <that folder> so Claude Code has read access without a permission prompt.

It then works out what's next (same logic as sdlc next, which right after a fresh install is always Stage 0) and asks how you want to trigger it: launch Claude Code now, copy the prompt to clipboard, or skip for now.

npx @levi-putna/sdlc install [--yes] [--force] [--check] [--cwd <path>]

Reports the currently installed vs. latest framework version and, once confirmed (or with --yes), applies the update. Files you've edited locally are preserved unless they also changed upstream, in which case they're left alone and reported as a conflict — pass --force to take the upstream version instead. --check only reports; it writes nothing.

npx @levi-putna/sdlc diff [--cwd <path>]

Shows exactly which files would change on the next install, bucketed as updated / added / removed / kept (local edit) / conflict, plus the changelog entries between your installed version and latest main.

npx @levi-putna/sdlc changelog [--all] [--cwd <path>]

Prints what's changed since your installed version. --all prints the full changelog.

npx @levi-putna/sdlc status [--json] [--cwd <path>]

Shows pipeline progress across all four lanes at once — Setup, Backend, Frontend, Integration — as the same tree shape agents render in their closing summaries: one stage per line (e.g. S1 - Reconcile Requirements), chained by │ connectors (● complete, ◐ active, ○ pending, ✗ blocked). Runs each of check-stage.js, check-stage-frontend.js, and check-stage-integration.js once (no --stage) and reads off the single cursor position each reports. --json prints the same data as a flat per-stage array instead of the tree.

npx @levi-putna/sdlc next [--cwd <path>]

Reads the same pipeline status as sdlc status, works out what's actually next (one option per lane that still has open work — more than one at once if the pipeline has genuinely forked, e.g. Backend and Frontend both open after S2), and lets you pick one if there's a choice. Then asks how you want to trigger it: launch Claude Code now (claude "<prompt>", in this project directory, with your terminal handed over to it) or copy the prompt to clipboard to paste yourself. Either way the prompt just points Claude Code at that stage's canonical doc under .sdlc/sdlc/stages/ and tells it to run the whole procedure — this command's only job is picking the right stage and composing that prompt; Claude Code does all the actual work (agent invocations, interview questions, the gate check) once it's running.

npx @levi-putna/sdlc explain [step] [--cwd <path>]

Explains a single pipeline step — its purpose, inputs, outputs, and gate criteria — read straight from its canonical doc under .sdlc/sdlc/stages/. Pass a step id directly (sdlc explain s1, case-insensitive), or omit it to pick one interactively from a list grouped by lane.

npx @levi-putna/sdlc docs [path] [--cwd <path>]

Browses every documentation artifact the pipeline produces — DOMAIN.md, SCOPE.md, architecture/*.md, per-stack/brick stack.md/brick.md, per-element/component Name.md, per-screen page.md, workflow flow.md, state hooks, and Change Track docs — grouped by lane, with the same Stacks→Bricks / Elements/Components / Screens / Workflows nesting the pipeline itself uses. Collection artifacts (stacks, elements, screens, ...) are discovered live off the filesystem, not a static list, so it only ever shows what's actually been generated in this project.

Pass a name or path fragment to jump straight to a document (sdlc docs scope, sdlc docs process-order) — an exact basename match wins outright, otherwise it falls back to a substring match on the relative path, prompting you to disambiguate if more than one hits. Omit the argument to browse interactively instead, picking a lane, then a category, then (for nested categories) a specific item. Backspace/Delete steps back up one level; Escape exits the browser entirely, from any depth.

Opening a document hands it to the OS's own file association — open on macOS, xdg-open on Linux, start on Windows — so it launches in whatever app you've already got set up for .md/.ts/.json files, same as double-clicking it in Finder/Explorer.

npx @levi-putna/sdlc contribute [--files <list>] [--message <text>] [--yes] [--cwd <path>]

Found or fixed a real bug in .sdlc/ locally (e.g. a coding agent patched a gate script while working)? This finds every file that differs from what's recorded in sdlc-lock.json, lets you pick which to contribute, forks and clones levi-putna/sdlc, commits your current on-disk content for those files to a new branch, pushes, and opens a PR — always pausing for confirmation first unless --yes is given. Requires the gh CLI installed and authenticated (gh auth login).

How updates are tracked

Every file under the project's .sdlc/ is SHA-256 hashed and recorded in sdlc-lock.json at the project root, alongside the installed framework version, commit, and which coding agents were selected. On install, three hashes are compared per file — the recorded hash, the freshly-fetched upstream hash, and the current on-disk hash — to tell a clean upstream update apart from a local edit apart from a genuine conflict (both changed).

Development

npm install
npm run typecheck
npm run build       # tsup -> dist/
npm test            # vitest

bin/sdlc.js is the published entrypoint; it imports the built dist/index.js.