@novare-technologies/nvaid 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Novare SQE Armory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,138 @@
-# Temporary Holding Version
+# nvaid
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+One CLI that installs an **AI-DLC** (AI Development Lifecycle) skills-and-workflow toolkit
+into **any** coding agent, and houses a repo's intents, config, and design-code dictionary
+in a single owned `nvaid/` folder.
+
+Edit a skill once here, publish, and every consuming repo re-syncs with `nvaid update` —
+no more hand-copying skills between repositories, or between one agent's config and
+another's (`.claude/`, `.kiro/`, `.cursor/`, …).
+
+## Install & use
+
+```bash
+npm i -g @novare-technologies/nvaid     # or on demand: npx @novare-technologies/nvaid <command>
+
+cd your-repo
+nvaid init               # pick coding agents, inject skills + slash commands, drop nvaid/
+nvaid update             # re-sync every configured agent to the installed nvaid version
+nvaid validate           # CI gate: fail if generated files are stale or hand-edited
+```
+
+> Published under the `@novare-technologies` org scope as a **public** package, so anyone
+> can install it. The typed command stays `nvaid` (that's the `bin`, independent of the
+> package name).
+
+`init` flags:
+
+```bash
+nvaid init --agents claude,kiro,cursor   # skip the prompt, name agents directly
+nvaid init --owning-repo frontend        # preset the config's owning_repo
+nvaid init --yes                          # non-interactive (defaults to the AGENTS.md catch-all)
+```
+
+## How it works
+
+- **Full skill set, no profiles.** `init` injects every skill into each selected agent. A
+  repo declares what it *is* in `nvaid/config.yml` (`owning_repo`), rather than receiving a
+  trimmed-down skill set.
+- **Any coding agent.** `init` shows a multi-select. Each agent is a *path + format adapter*
+  (`src/agents.ts`) over one neutral source — adding a new agent is a new registry entry,
+  not new content. An `AGENTS.md` catch-all covers any tool that reads the cross-agent
+  standard but has no bespoke adapter.
+- **The `nvaid/` folder is hand-owned, content only** — `config.yml`, `PROJECT-RULES.md`,
+  `DESIGN-CODE-DICTIONARY.md`, and `intents/`. `update` never touches these. The *generated*
+  skill/command files live in each agent's own directory and carry a "do not edit" header.
+- **`PROJECT-RULES.md` and `DESIGN-CODE-DICTIONARY.md` are per-project templates**, not
+  shipped content: `init` drops fill-in skeletons for a developer to own. nvaid ships only
+  the universal skills and the contract/unit-decomposition rules.
+- **Drift is caught, not just avoided.** `validate` fails (exit 1) if a repo's generated
+  files are stale (behind the installed version), missing, or hand-edited — turning silent
+  divergence into a failing CI check.
+
+## The workflow (slash commands)
+
+`init` installs four gated commands. They run in order, with a human gate after the intent:
+
+```
+/nvaid:intent      draft the intent — business need + success criteria only, then STOP
+   ⏸  stakeholder approval
+/nvaid:contracts   draft the per-role architecture contracts
+/nvaid:breakdown   cut into units (each tagged with its owning repo) — the final cut
+/nvaid:apply       generate per-repo unit docs + open construction branches
+```
+
+Contracts precede the breakdown deliberately (the contract skills run across the
+elaboration phases; the unit-breakdown is their final output).
+
+## Repository layout
+
+```
+nvaid/
+  package.json              # bin: nvaid; ships dist/ + templates/
+  tsconfig.json
+  src/
+    cli.ts                  # command wiring (commander)
+    agents.ts               # the agent registry — 9 bespoke + an AGENTS.md catch-all
+    paths.ts                # resolves the bundled templates/
+    config.ts               # read/patch a repo's nvaid/config.yml
+    scaffold.ts             # drop the nvaid/ folder + sync nvaid/rules
+    generate.ts             # neutral source -> per-agent files (+ drift diff)
+    commands/
+      init.ts               # agent multi-select + inject + scaffold nvaid/
+      update.ts             # re-sync configured agents
+      validate.ts           # drift gate
+  templates/                # the payload shipped in the package
+    skills/                 # 12 skills (6 ceremony + frontend + backend + 4 tool)
+    rules/                  # 7 flow/rule files (contract-gen, unit-breakdown, tracker)
+    commands/               # the 4 slash-command defs
+    nvaid/                  # the folder init drops into a repo (all hand-owned)
+      config.yml
+      PROJECT-RULES.md      # fill-in template
+      DESIGN-CODE-DICTIONARY.md  # fill-in template (a technical README for the code)
+      intents/
+```
+
+### Skills included (`templates/skills/`)
+
+- **Ceremony:** `customer-experience`, `solutions`, `quality`, `unit-breakdown`,
+  `r3-analytics`, `release-plan`
+- **Tier:** `frontend`, `backend`
+- **Tool:** `github`, `project-ticketing`, `pr-review`, `daily-construction-update`
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm run dev -- init --agents claude   # run the CLI from source (tsx)
+npm run build                          # bundle src/ -> dist/cli.js (tsup)
+npm test                               # vitest
+```
+
+## Status & next steps
+
+The CLI (`init` / `update` / `validate`) is implemented and runs end-to-end. Still open:
+
+- Tests (`vitest`) for the generator and the agent adapters.
+- Confirm each agent's target path against its current docs before relying on its adapter
+  (agent conventions change often; `AGENTS.md` is the safe default).
+### Non-JS repos (Python, Go, etc.)
+
+No special delivery path needed. nvaid only *writes files* — skills, the guardrail
+templates, and the `nvaid/` folder — and exits; the output has no runtime dependency on
+Node. A Python repo just runs the command once:
+
+```bash
+npx @novare-technologies/nvaid init
+```
+
+Nothing is added to the target project itself (no `devDependency`, no Node toolchain in
+the repo). The only requirement is that Node is available on the developer's machine or CI
+to invoke the CLI — a one-time "have Node installed to run a scaffolding tool" ask, not an
+ongoing footprint. (A prebuilt binary or pipx wrapper was considered and dropped as
+unnecessary.)
+
+---
+
+Authored and maintained by **Novare SQE Armory**.

package/dist/cli.js

@@ -0,0 +1,483 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from "commander";
+
+// src/commands/init.ts
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+
+// src/agents.ts
+var AGENTS = [
+  {
+    id: "claude",
+    label: "Claude Code",
+    skillsPath: ".claude/skills",
+    instructionsFile: "CLAUDE.md",
+    format: "markdown",
+    bespoke: true
+  },
+  {
+    id: "kiro",
+    label: "Kiro",
+    skillsPath: ".kiro/skills",
+    instructionsFile: ".kiro/steering/nvaid.md",
+    format: "markdown",
+    bespoke: true
+  },
+  {
+    id: "cursor",
+    label: "Cursor",
+    skillsPath: ".cursor/rules",
+    format: "mdc",
+    bespoke: true
+  },
+  {
+    id: "copilot",
+    label: "GitHub Copilot",
+    skillsPath: ".github",
+    instructionsFile: ".github/copilot-instructions.md",
+    format: "markdown",
+    bespoke: true
+  },
+  {
+    id: "windsurf",
+    label: "Windsurf",
+    skillsPath: ".windsurf/rules",
+    format: "markdown",
+    bespoke: true
+  },
+  {
+    id: "amazonq",
+    label: "Amazon Q",
+    skillsPath: ".amazonq/rules",
+    format: "markdown",
+    bespoke: true
+  },
+  {
+    id: "cline",
+    label: "Cline",
+    skillsPath: ".cline/rules",
+    instructionsFile: ".clinerules",
+    format: "markdown",
+    bespoke: true
+  },
+  {
+    id: "gemini",
+    label: "Gemini Code Assist",
+    skillsPath: ".gemini",
+    instructionsFile: ".gemini/styleguide.md",
+    format: "markdown",
+    bespoke: true
+  },
+  {
+    id: "aider",
+    label: "Aider",
+    skillsPath: ".nvaid/skills",
+    instructionsFile: "AGENTS.md",
+    format: "markdown",
+    bespoke: true
+  },
+  {
+    id: "agents-md",
+    label: "Any AGENTS.md-compatible tool (catch-all)",
+    skillsPath: ".nvaid/skills",
+    instructionsFile: "AGENTS.md",
+    format: "markdown",
+    bespoke: false
+  }
+];
+function getAgent(id) {
+  return AGENTS.find((a) => a.id === id);
+}
+
+// src/generate.ts
+import { readFile, writeFile, mkdir, readdir, rm } from "fs/promises";
+import { existsSync } from "fs";
+import { join, relative } from "path";
+
+// src/paths.ts
+import { fileURLToPath } from "url";
+import { dirname, resolve } from "path";
+var here = dirname(fileURLToPath(import.meta.url));
+var TEMPLATES_DIR = resolve(here, "..", "templates");
+var SKILLS_SRC = resolve(TEMPLATES_DIR, "skills");
+var RULES_SRC = resolve(TEMPLATES_DIR, "rules");
+var COMMANDS_SRC = resolve(TEMPLATES_DIR, "commands");
+var NVAID_FOLDER_SRC = resolve(TEMPLATES_DIR, "nvaid");
+var NVAID_DIR_NAME = "nvaid";
+var CONFIG_FILE = "config.yml";
+var AIDLC_ROOT_TOKEN = "{{AIDLC_ROOT}}";
+async function nvaidVersion() {
+  const { readFile: readFile3 } = await import("fs/promises");
+  const pkg = JSON.parse(await readFile3(resolve(TEMPLATES_DIR, "..", "package.json"), "utf8"));
+  return pkg.version;
+}
+
+// src/generate.ts
+var DO_NOT_EDIT = "<!-- generated by nvaid \u2014 do not edit. Run `nvaid update` to regenerate. -->";
+function aidlcRootFor(agent) {
+  void agent;
+  return "nvaid/rules";
+}
+function withHeader(body, format) {
+  if (format === "mdc") {
+    return `${DO_NOT_EDIT}
+${body}`;
+  }
+  return `${DO_NOT_EDIT}
+
+${body}`;
+}
+async function listSkillDirs() {
+  const entries = await readdir(SKILLS_SRC, { withFileTypes: true });
+  return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+}
+async function listCommandFiles() {
+  const entries = await readdir(COMMANDS_SRC, { withFileTypes: true });
+  return entries.filter((e) => e.isFile() && e.name.endsWith(".md")).map((e) => e.name);
+}
+async function renderTemplate(srcFile, agent) {
+  const raw = await readFile(srcFile, "utf8");
+  const substituted = raw.split(AIDLC_ROOT_TOKEN).join(aidlcRootFor(agent));
+  return withHeader(substituted, agent.format);
+}
+function skillTarget(projectRoot, agent, skill) {
+  const ext = agent.format === "mdc" ? "mdc" : "md";
+  return join(projectRoot, agent.skillsPath, `${skill}.${ext}`);
+}
+function commandTarget(projectRoot, agent, cmdFile) {
+  const base = cmdFile.replace(/\.md$/, "");
+  const ext = agent.format === "mdc" ? "mdc" : "md";
+  return join(projectRoot, agent.skillsPath, `commands`, `nvaid-${base}.${ext}`);
+}
+async function writeFileEnsuringDir(path, body, force, result) {
+  if (!force && existsSync(path)) {
+    result.skipped.push(path);
+    return;
+  }
+  await mkdir(join(path, ".."), { recursive: true });
+  await writeFile(path, body, "utf8");
+  result.written.push(path);
+}
+async function generateAgentFiles(opts) {
+  const result = { written: [], skipped: [] };
+  const skills = await listSkillDirs();
+  const commands = await listCommandFiles();
+  for (const agent of opts.agents) {
+    for (const skill of skills) {
+      const src = join(SKILLS_SRC, skill, "SKILL.md");
+      if (!existsSync(src)) continue;
+      const body = await renderTemplate(src, agent);
+      await writeFileEnsuringDir(skillTarget(opts.projectRoot, agent, skill), body, opts.force, result);
+    }
+    for (const cmd of commands) {
+      const body = await renderTemplate(join(COMMANDS_SRC, cmd), agent);
+      await writeFileEnsuringDir(commandTarget(opts.projectRoot, agent, cmd), body, opts.force, result);
+    }
+  }
+  return result;
+}
+async function diffAgentFiles(opts) {
+  const drift = [];
+  const skills = await listSkillDirs();
+  const commands = await listCommandFiles();
+  const checks = [];
+  for (const agent of opts.agents) {
+    for (const skill of skills) {
+      const src = join(SKILLS_SRC, skill, "SKILL.md");
+      if (existsSync(src)) checks.push({ target: skillTarget(opts.projectRoot, agent, skill), src });
+    }
+    for (const cmd of commands) {
+      checks.push({ target: commandTarget(opts.projectRoot, agent, cmd), src: join(COMMANDS_SRC, cmd) });
+    }
+  }
+  for (const { target, src } of checks) {
+    const agent = opts.agents.find((a) => target.includes(a.skillsPath.replace(/^\.\//, "")));
+    const expected = await renderTemplate(src, agent ?? opts.agents[0]);
+    if (!existsSync(target)) {
+      drift.push(`${relative(opts.projectRoot, target)} (missing)`);
+      continue;
+    }
+    const actual = await readFile(target, "utf8");
+    if (actual !== expected) drift.push(relative(opts.projectRoot, target));
+  }
+  return drift;
+}
+async function cleanAgentDirs(projectRoot, agents) {
+  for (const agent of agents) {
+    const dir = join(projectRoot, agent.skillsPath);
+    const commandsDir = join(dir, "commands");
+    if (existsSync(commandsDir)) await rm(commandsDir, { recursive: true, force: true });
+  }
+}
+
+// src/scaffold.ts
+import { cp, mkdir as mkdir2, readdir as readdir2 } from "fs/promises";
+import { existsSync as existsSync2 } from "fs";
+import { join as join2 } from "path";
+async function scaffoldNvaidFolder(projectRoot) {
+  const dest = join2(projectRoot, NVAID_DIR_NAME);
+  await mkdir2(dest, { recursive: true });
+  const written = [];
+  await copyTreeSkipExisting(NVAID_FOLDER_SRC, dest, written);
+  return written;
+}
+async function syncRules(projectRoot) {
+  const dest = join2(projectRoot, NVAID_DIR_NAME, "rules");
+  await mkdir2(dest, { recursive: true });
+  await cp(RULES_SRC, dest, { recursive: true, force: true });
+}
+async function copyTreeSkipExisting(src, dest, written) {
+  const entries = await readdir2(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const s = join2(src, entry.name);
+    const d = join2(dest, entry.name);
+    if (entry.isDirectory()) {
+      await mkdir2(d, { recursive: true });
+      await copyTreeSkipExisting(s, d, written);
+    } else {
+      if (existsSync2(d)) continue;
+      await cp(s, d);
+      written.push(d);
+    }
+  }
+}
+
+// src/config.ts
+import { readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
+import { existsSync as existsSync3 } from "fs";
+import { join as join3 } from "path";
+import { parse } from "yaml";
+var EMPTY_STACK = {
+  languages: [],
+  runtime: "",
+  frameworks: [],
+  package_manager: "",
+  build: "",
+  test: "",
+  lint_format: "",
+  database: "",
+  deploy: "",
+  additional: {}
+};
+function configPath(projectRoot) {
+  return join3(projectRoot, NVAID_DIR_NAME, CONFIG_FILE);
+}
+function hasConfig(projectRoot) {
+  return existsSync3(configPath(projectRoot));
+}
+async function readConfig(projectRoot) {
+  const raw = await readFile2(configPath(projectRoot), "utf8");
+  const parsed = parse(raw) ?? {};
+  const install = parsed.install ?? {};
+  return {
+    schema: parsed.schema ?? "nvaid/v1",
+    install: {
+      config: install.config === true,
+      project_rules: install.project_rules === true,
+      design_code_dictionary: install.design_code_dictionary === true
+    },
+    project_name: parsed.project_name ?? "",
+    owning_repo: parsed.owning_repo ?? "",
+    tech_stack: { ...EMPTY_STACK, ...parsed.tech_stack ?? {} },
+    agents: Array.isArray(parsed.agents) ? parsed.agents : [],
+    context: parsed.context ?? "",
+    generated_with: parsed.generated_with ?? ""
+  };
+}
+async function setConfigFields(projectRoot, fields) {
+  const path = configPath(projectRoot);
+  let text = await readFile2(path, "utf8");
+  if (fields.project_name !== void 0) {
+    text = replaceScalar(text, "project_name", `"${fields.project_name}"`);
+  }
+  if (fields.owning_repo !== void 0) {
+    text = replaceScalar(text, "owning_repo", `"${fields.owning_repo}"`);
+  }
+  if (fields.generated_with !== void 0) {
+    text = replaceScalar(text, "generated_with", `"${fields.generated_with}"`);
+  }
+  if (fields.agents !== void 0) {
+    text = replaceAgents(text, fields.agents);
+  }
+  await writeFile2(path, text, "utf8");
+}
+function replaceScalar(text, key, value) {
+  const re = new RegExp(`^(${key}:).*$`, "m");
+  return re.test(text) ? text.replace(re, `$1 ${value}`) : `${text}
+${key}: ${value}
+`;
+}
+function replaceAgents(text, agents) {
+  const flow = agents.length ? `[${agents.map((a) => `"${a}"`).join(", ")}]` : "[]";
+  const re = /^agents:.*(?:\n[ \t]*-.*)*$/m;
+  const line = `agents: ${flow}`;
+  return re.test(text) ? text.replace(re, line) : `${text}
+${line}
+`;
+}
+
+// src/commands/init.ts
+async function runInit(opts) {
+  const projectRoot = process.cwd();
+  if (hasConfig(projectRoot) && !opts.yes) {
+    const proceed = await p.confirm({
+      message: "This repo already has nvaid/config.yml. Re-run init anyway (update is usually what you want)?",
+      initialValue: false
+    });
+    if (p.isCancel(proceed) || !proceed) {
+      p.cancel("Nothing changed. Run `nvaid update` to re-sync agents.");
+      return;
+    }
+  }
+  let selected;
+  if (opts.agents?.length) {
+    selected = opts.agents.map(resolveAgentOrThrow);
+  } else if (opts.yes) {
+    selected = [getAgent("agents-md")];
+  } else {
+    p.intro(pc.bold("nvaid init"));
+    const choice = await p.multiselect({
+      message: "Select the coding agents to set up (space to toggle, enter to confirm):",
+      options: AGENTS.map((a) => ({ value: a.id, label: a.label, hint: a.skillsPath })),
+      required: true
+    });
+    if (p.isCancel(choice)) {
+      p.cancel("Cancelled.");
+      return;
+    }
+    selected = choice.map(resolveAgentOrThrow);
+  }
+  const gen = await generateAgentFiles({ projectRoot, agents: selected, force: false });
+  const scaffolded = await scaffoldNvaidFolder(projectRoot);
+  await syncRules(projectRoot);
+  await setConfigFields(projectRoot, {
+    agents: selected.map((a) => a.id),
+    owning_repo: opts.owningRepo ?? "<set-me>",
+    ...opts.projectName ? { project_name: opts.projectName } : {},
+    generated_with: await nvaidVersion()
+  });
+  p.note(
+    [
+      `agents:   ${selected.map((a) => a.label).join(", ")}`,
+      `written:  ${gen.written.length} agent files` + (gen.skipped.length ? `, ${gen.skipped.length} skipped (existing)` : ""),
+      `nvaid/:   ${scaffolded.length ? scaffolded.length + " files created" : "already present"}`
+    ].join("\n"),
+    "Done"
+  );
+  p.outro(
+    [
+      "Next, in your AI chat \u2014 run this FIRST:",
+      "  /nvaid:install         scan the project, fill config.yml + PROJECT-RULES + dictionary",
+      "",
+      "The workflow commands are blocked until /nvaid:install completes:",
+      '  /nvaid:intent "..."   draft the intent, then STOP for stakeholder approval',
+      "  /nvaid:contracts       after approval \u2014 draft the per-role contracts",
+      "  /nvaid:breakdown       cut into units (tagged by owning repo)",
+      "  /nvaid:apply           generate per-repo unit docs + branches"
+    ].join("\n")
+  );
+}
+function resolveAgentOrThrow(id) {
+  const a = getAgent(id);
+  if (!a) throw new Error(`Unknown agent id: "${id}". Known: ${AGENTS.map((x) => x.id).join(", ")}`);
+  return a;
+}
+
+// src/commands/update.ts
+import * as p2 from "@clack/prompts";
+import pc2 from "picocolors";
+async function runUpdate() {
+  const projectRoot = process.cwd();
+  if (!hasConfig(projectRoot)) {
+    throw new Error("No nvaid/config.yml here. Run `nvaid init` first.");
+  }
+  const cfg = await readConfig(projectRoot);
+  if (!cfg.agents.length) {
+    throw new Error("config.yml lists no agents. Run `nvaid init` to select some.");
+  }
+  const agents = cfg.agents.map((id) => {
+    const a = getAgent(id);
+    if (!a) throw new Error(`config.yml references unknown agent "${id}".`);
+    return a;
+  });
+  const version = await nvaidVersion();
+  p2.intro(pc2.bold(`nvaid update \u2192 ${version}`));
+  await cleanAgentDirs(projectRoot, agents);
+  const gen = await generateAgentFiles({ projectRoot, agents, force: true });
+  await syncRules(projectRoot);
+  await setConfigFields(projectRoot, { generated_with: version });
+  p2.note(
+    [
+      `agents:   ${agents.map((a) => a.label).join(", ")}`,
+      `rewrote:  ${gen.written.length} agent files`,
+      `rules:    refreshed nvaid/rules/`,
+      `was:      ${cfg.generated_with || "unknown"}  \u2192  now: ${version}`
+    ].join("\n"),
+    "Updated"
+  );
+  p2.outro("Hand-owned files (config.yml, PROJECT-RULES.md, DESIGN-CODE-DICTIONARY.md, intents/) untouched.");
+}
+
+// src/commands/validate.ts
+import pc3 from "picocolors";
+async function runValidate() {
+  const projectRoot = process.cwd();
+  if (!hasConfig(projectRoot)) {
+    console.error(pc3.red("\u2717 No nvaid/config.yml here. Run `nvaid init` first."));
+    return 1;
+  }
+  const cfg = await readConfig(projectRoot);
+  const agents = [];
+  for (const id of cfg.agents) {
+    const a = getAgent(id);
+    if (!a) {
+      console.error(pc3.red(`\u2717 config.yml references unknown agent "${id}".`));
+      return 1;
+    }
+    agents.push(a);
+  }
+  const version = await nvaidVersion();
+  let failed = false;
+  if (cfg.generated_with && cfg.generated_with !== version) {
+    console.error(
+      pc3.yellow(
+        `\u26A0 generated with nvaid ${cfg.generated_with}, installed is ${version}. Run \`nvaid update\`.`
+      )
+    );
+    failed = true;
+  }
+  const drift = await diffAgentFiles({ projectRoot, agents, force: true });
+  if (drift.length) {
+    console.error(pc3.red(`\u2717 ${drift.length} generated file(s) stale or hand-edited:`));
+    for (const f of drift) console.error(pc3.red(`    ${f}`));
+    console.error(pc3.dim("  Run `nvaid update` to regenerate (hand edits belong in the nvaid source, not here)."));
+    failed = true;
+  }
+  if (failed) return 1;
+  console.log(pc3.green(`\u2713 nvaid ${version}: ${agents.length} agent(s) in sync, no drift.`));
+  return 0;
+}
+
+// src/cli.ts
+var program = new Command();
+program.name("nvaid").description("nvaid \u2014 install an AI-DLC skills + workflow toolkit into any coding agent").version(await nvaidVersion());
+program.command("init").description("Onboard this repo: select coding agents, inject skills, create the nvaid/ folder").option("--agents <ids>", "comma-separated agent ids (skips the prompt)", (v) => v.split(",")).option("--owning-repo <tier>", "owning_repo value written to config.yml").option("--project-name <name>", "project_name value written to config.yml").option("-y, --yes", "accept defaults, no prompts (CI)").action(async (opts) => {
+  await runInit({
+    agents: opts.agents,
+    owningRepo: opts.owningRepo,
+    projectName: opts.projectName,
+    yes: opts.yes
+  });
+});
+program.command("update").description("Re-sync agent files to the installed nvaid version").action(async () => {
+  await runUpdate();
+});
+program.command("validate").description("Fail if generated agent files are stale or hand-edited").action(async () => {
+  process.exit(await runValidate());
+});
+program.parseAsync().catch((err) => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@novare-technologies/nvaid",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "nvaid — one CLI that installs an AI-DLC skills-and-workflow toolkit into any coding agent, and houses intents, config, and the design-code dictionary in a single nvaid/ folder.",
+  "type": "module",
+  "bin": {
+    "nvaid": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup src/cli.ts --format esm --clean",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai-dlc",
+    "coding-agent",
+    "skills",
+    "scaffold",
+    "cli"
+  ],
+  "author": "Novare SQE Armory",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "commander": "^12.0.0",
+    "picocolors": "^1.0.0",
+    "yaml": "^2.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0",
+    "vitest": "^5.0.3"
+  },
+  "overrides": {
+    "esbuild": "^0.28.2"
+  }
+}