@novare-technologies/nvaid 0.2.0 → 0.2.2

package/README.md

@@ -31,6 +31,27 @@ nvaid init --owning-repo frontend        # preset the config's owning_repo
 nvaid init --yes                          # non-interactive (defaults to the AGENTS.md catch-all)
 ```
 
+## Upgrading
+
+Upgrading is **two steps**, because `nvaid update` re-syncs a repo to the version of the
+tool installed on your machine — it does not upgrade the tool itself:
+
+```bash
+# 1. upgrade the tool (once per machine, when a new version ships)
+npm i -g @novare-technologies/nvaid@latest
+
+# 2. re-sync each repo to the new version (run inside each repo)
+nvaid update
+```
+
+nvaid checks npm (at most once a day, cached, non-blocking) and prints a one-line nudge
+when a newer version is available — it never upgrades itself (the package manager owns the
+tool's lifecycle). Silence the check with `NVAID_NO_UPDATE_CHECK=1`.
+
+Note: `nvaid update` never touches hand-owned files (`config.yml`, `PROJECT-RULES.md`,
+`DESIGN-CODE-DICTIONARY.md`, `intents/`). If a new version adds a config field, add it to
+your `config.yml` by hand — the changelog will call these out.
+
 ## How it works
 
 - **Full skill set, no profiles.** `init` injects every skill into each selected agent. A

package/dist/cli.js

@@ -13,6 +13,8 @@ var AGENTS = [
     id: "claude",
     label: "Claude Code",
     skillsPath: ".claude/skills",
+    commandsPath: ".claude/commands",
+    // /nvaid:install resolves from .claude/commands/nvaid/install.md
     instructionsFile: "CLAUDE.md",
     format: "markdown",
     bespoke: true
@@ -29,6 +31,8 @@ var AGENTS = [
     id: "cursor",
     label: "Cursor",
     skillsPath: ".cursor/rules",
+    commandsPath: ".cursor/commands",
+    // Cursor reads custom commands from .cursor/commands
     format: "mdc",
     bespoke: true
   },
@@ -109,8 +113,8 @@ 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"));
+  const { readFile: readFile4 } = await import("fs/promises");
+  const pkg = JSON.parse(await readFile4(resolve(TEMPLATES_DIR, "..", "package.json"), "utf8"));
   return pkg.version;
 }
 
@@ -149,7 +153,10 @@ function skillTarget(projectRoot, agent, skill) {
 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}`);
+  if (agent.commandsPath) {
+    return join(projectRoot, agent.commandsPath, "nvaid", `${base}.${ext}`);
+  }
+  return join(projectRoot, agent.skillsPath, "nvaid-commands", `nvaid-${base}.${ext}`);
 }
 async function writeFileEnsuringDir(path, body, force, result) {
   if (!force && existsSync(path)) {
@@ -186,15 +193,14 @@ async function diffAgentFiles(opts) {
   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 });
+      if (existsSync(src)) checks.push({ target: skillTarget(opts.projectRoot, agent, skill), src, agent });
     }
     for (const cmd of commands) {
-      checks.push({ target: commandTarget(opts.projectRoot, agent, cmd), src: join(COMMANDS_SRC, cmd) });
+      checks.push({ target: commandTarget(opts.projectRoot, agent, cmd), src: join(COMMANDS_SRC, cmd), agent });
     }
   }
-  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]);
+  for (const { target, src, agent } of checks) {
+    const expected = await renderTemplate(src, agent);
     if (!existsSync(target)) {
       drift.push(`${relative(opts.projectRoot, target)} (missing)`);
       continue;
@@ -206,8 +212,7 @@ async function diffAgentFiles(opts) {
 }
 async function cleanAgentDirs(projectRoot, agents) {
   for (const agent of agents) {
-    const dir = join(projectRoot, agent.skillsPath);
-    const commandsDir = join(dir, "commands");
+    const commandsDir = agent.commandsPath ? join(projectRoot, agent.commandsPath, "nvaid") : join(projectRoot, agent.skillsPath, "nvaid-commands");
     if (existsSync(commandsDir)) await rm(commandsDir, { recursive: true, force: true });
   }
 }
@@ -460,6 +465,81 @@ async function runValidate() {
   return 0;
 }
 
+// src/updateNotifier.ts
+import { readFile as readFile3, writeFile as writeFile3, mkdir as mkdir3 } from "fs/promises";
+import { homedir, tmpdir } from "os";
+import { join as join4 } from "path";
+import pc4 from "picocolors";
+var PKG = "@novare-technologies/nvaid";
+var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+var FETCH_TIMEOUT_MS = 1500;
+function cacheFile() {
+  const base = process.env.XDG_CACHE_HOME || join4(homedir(), ".cache");
+  return join4(base || tmpdir(), "nvaid", "update-check.json");
+}
+async function readCache() {
+  try {
+    return JSON.parse(await readFile3(cacheFile(), "utf8"));
+  } catch {
+    return null;
+  }
+}
+async function writeCache(c) {
+  try {
+    const f = cacheFile();
+    await mkdir3(join4(f, ".."), { recursive: true });
+    await writeFile3(f, JSON.stringify(c), "utf8");
+  } catch {
+  }
+}
+async function fetchLatest() {
+  try {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
+    const res = await fetch(`https://registry.npmjs.org/${PKG}/latest`, {
+      signal: ctrl.signal
+    });
+    clearTimeout(timer);
+    if (!res.ok) return null;
+    const data = await res.json();
+    return data.version ?? null;
+  } catch {
+    return null;
+  }
+}
+function isNewer(a, b) {
+  const pa = a.split(".").map((n) => parseInt(n, 10));
+  const pb = b.split(".").map((n) => parseInt(n, 10));
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i] ?? 0;
+    const y = pb[i] ?? 0;
+    if (x > y) return true;
+    if (x < y) return false;
+  }
+  return false;
+}
+async function notifyIfOutdated() {
+  if (process.env.NVAID_NO_UPDATE_CHECK) return;
+  const current = await nvaidVersion();
+  const cache = await readCache();
+  const now = Date.now();
+  let latest = null;
+  if (cache && now - cache.lastCheck < CHECK_INTERVAL_MS) {
+    latest = cache.latest;
+  } else {
+    latest = await fetchLatest();
+    if (latest) await writeCache({ lastCheck: now, latest });
+  }
+  if (!latest || !isNewer(latest, current)) return;
+  const line = (s) => process.stderr.write(s + "\n");
+  line("");
+  line(pc4.yellow(`  \u250C\u2500 nvaid update available \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`));
+  line(pc4.yellow("  \u2502 ") + `${pc4.dim(current)} \u2192 ${pc4.green(latest)}`);
+  line(pc4.yellow("  \u2502 ") + `run: ${pc4.cyan(`npm i -g ${PKG}@latest`)}`);
+  line(pc4.yellow("  \u2502 ") + pc4.dim(`then re-sync your repo: nvaid update`));
+  line(pc4.yellow(`  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`));
+}
+
 // 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());
@@ -475,9 +555,13 @@ program.command("update").description("Re-sync agent files to the installed nvai
   await runUpdate();
 });
 program.command("validate").description("Fail if generated agent files are stale or hand-edited").action(async () => {
-  process.exit(await runValidate());
+  const code = await runValidate();
+  await notifyIfOutdated();
+  process.exit(code);
 });
-program.parseAsync().catch((err) => {
+program.parseAsync().then(async () => {
+  await notifyIfOutdated();
+}).catch((err) => {
   console.error(err instanceof Error ? err.message : err);
   process.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@novare-technologies/nvaid",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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": {
@@ -16,7 +16,7 @@
   "scripts": {
     "build": "tsup src/cli.ts --format esm --clean",
     "dev": "tsx src/cli.ts",
-    "test": "vitest run --passWithNoTests",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run build"
   },

package/templates/commands/install.md

@@ -47,13 +47,48 @@ not a file-scan's. This skill does that reading. A human reviews before it's mar
    narrative derived from reading the code; §1 references `config.yml`'s `tech_stack`
    rather than repeating it. Be honest in the "not yet mapped" section about coverage.
 
-5. **Human review.** Present all three for review. Per propose-don't-dispose, you draft;
-   a human confirms. Do not self-approve.
+5. **Set up ADRs (Architecture Decision Records) — the project's decision anchors.**
+   ADRs are where a significant decision is justified and preserved, so the project (and
+   any future agent) can trace *why* a choice was made and revisit it later. Create them
+   on demand, not as empty ceremony:
+   - If authoring PROJECT-RULES (step 3) surfaced genuine, non-obvious decisions — an
+     approved-stack choice, a deliberate constraint, something a reviewer might otherwise
+     question — **create `nvaid/adr/`** and seed one ADR per such decision, numbered
+     `ADR-001`, `ADR-002`, … using the template below. These are the decisions the project
+     has already made, now anchored.
+   - If the project is simple enough that no decision needs anchoring yet, **do not create
+     an empty `adr/` folder** — just tell the user ADRs will be added when the first real
+     decision arises (e.g. via the `solutions` skill flagging "needs a new ADR"). The
+     folder appears when there's a decision to put in it.
+   - Each ADR follows this shape:
+     ```markdown
+     ---
+     adr: ADR-NNN
+     title: "<the decision, stated as a choice>"
+     status: accepted            # proposed | accepted | superseded by ADR-XXX
+     date: "<YYYY-MM-DD>"
+     ---
+     # ADR-NNN — <title>
+     ## Context
+     <the forces at play: what problem/constraint prompted this decision>
+     ## Decision
+     <what was decided, stated plainly>
+     ## Consequences
+     <what this makes easier, what it makes harder, what it rules out>
+     ## Alternatives considered
+     <options weighed and why they lost — so the decision can be revisited with the same context>
+     ```
+   - A decision anchored in an ADR must not contradict `PROJECT-RULES.md`; if it does,
+     reconcile them (an ADR can *drive* a rules change, recorded in the rules change log).
 
-6. **Flip the gate.** Only after the user confirms each document is genuinely filled (not
+6. **Human review.** Present all documents (config, PROJECT-RULES, dictionary, any ADRs)
+   for review. Per propose-don't-dispose, you draft; a human confirms. Do not self-approve.
+
+7. **Flip the gate.** Only after the user confirms each document is genuinely filled (not
    placeholder text), set the matching flag in `config.yml`'s `install:` block to `true`:
    `config`, `project_rules`, `design_code_dictionary`. When all three are true, the
-   workflow commands unblock.
+   workflow commands unblock. (ADRs are not a gate flag — they are created as decisions
+   warrant, not required for the install to be complete.)
 
 ## Boundaries
 
@@ -61,3 +96,5 @@ not a file-scan's. This skill does that reading. A human reviews before it's mar
   don't fabricate.
 - Never set an `install:` flag to `true` on a document that still contains template
   `<placeholder>` text or that the user hasn't confirmed.
+- **Create `nvaid/adr/` only when there is a real decision to anchor** — never an empty
+  folder for its own sake.

package/templates/nvaid/config.yml

@@ -84,4 +84,4 @@ context: ""
 
 # nvaid version this repo was last generated against. `nvaid validate` compares the
 # installed CLI version to this and flags drift.
-generated_with: "0.2.0"
+generated_with: "0.2.2"

package/templates/skills/customer-experience/SKILL.md

@@ -2,13 +2,13 @@
 name: customer-experience
 description: Drafts the Customer Experience Contract for an Intent, per customer-experience-contract-generation-rules.md. Use when asked to run the Customer Experience Skill or draft a Customer Experience contract during Mob Elaboration.
 invoked_by: Mob Elaboration (Ceremony 1), Phases 2–5
-output: file — intents/<INTENT-ID>/contracts/customer-experience-contract.md
+output: file — nvaid/intents/<INTENT-ID>/contracts/customer-experience-contract.md
 ---
 
 # Customer Experience Skill
 
 Drafts the Customer Experience Contract for an Intent, per
-`docs/templates/customer-experience-contract-generation-rules.md` — reconciling what the
+`{{AIDLC_ROOT}}/customer-experience-contract-generation-rules.md` — reconciling what the
 room actually committed to against what `intent.md` originally asked for.
 
 ## Steps
@@ -18,7 +18,7 @@ room actually committed to against what `intent.md` originally asked for.
 2. Write the Final Acceptance Criteria: the Intent's Success Criteria, incorporating
    what the other contracts actually committed to, not a verbatim restatement.
 3. Tie "done" to a concrete validation scenario, never just "the code merged."
-4. Write `intents/<INTENT-ID>/contracts/customer-experience-contract.md`.
+4. Write `nvaid/intents/<INTENT-ID>/contracts/customer-experience-contract.md`.
 
 ## Boundaries
 

package/templates/skills/frontend/SKILL.md

@@ -2,13 +2,13 @@
 name: frontend
 description: Drafts the Frontend Architecture Contract for an Intent, per frontend-architecture-contract-generation-rules.md. Use when asked to run the Frontend Skill or draft a Frontend contract during Mob Elaboration.
 invoked_by: Mob Elaboration (Ceremony 1), Phases 2–5
-output: file — intents/<INTENT-ID>/contracts/frontend-architecture-contract.md
+output: file — nvaid/intents/<INTENT-ID>/contracts/frontend-architecture-contract.md
 ---
 
 # Frontend Skill
 
 Drafts the Frontend Architecture Contract for an Intent, per
-`docs/templates/frontend-architecture-contract-generation-rules.md` — consuming the
+`{{AIDLC_ROOT}}/frontend-architecture-contract-generation-rules.md` — consuming the
 Backend contract's shapes verbatim rather than reinterpreting them.
 
 ## Steps
@@ -22,7 +22,7 @@ Backend contract's shapes verbatim rather than reinterpreting them.
 4. State Identity/Access implications explicitly, even when "none for this Intent" —
    never left implicit.
 5. List components touched (Design-Code Dictionary impact).
-6. Write `intents/<INTENT-ID>/contracts/frontend-architecture-contract.md`.
+6. Write `nvaid/intents/<INTENT-ID>/contracts/frontend-architecture-contract.md`.
 
 ## Boundaries
 

package/templates/skills/project-ticketing/SKILL.md

@@ -7,13 +7,13 @@ output: link — a Jira or GitHub Projects ticket
 
 # Project Ticketing Skill
 
-Creates and updates Epics, Stories, and Bugs per `docs/templates/ISSUE-TRACKER-TEMPLATE.md`
+Creates and updates Epics, Stories, and Bugs per `{{AIDLC_ROOT}}/ISSUE-TRACKER-TEMPLATE.md`
 — so ticket shape never drifts from one Intent to the next.
 
 ## Steps
 
 1. On Unit Breakdown (Mob Elaboration Phase 5), create one Story or Bug per Unit,
-   classified per `docs/templates/unit-breakdown-rules.md` §3.
+   classified per `{{AIDLC_ROOT}}/unit-breakdown-rules.md` §3.
 2. Attach each ticket's Acceptance Criteria verbatim from the Unit's own design doc —
    never re-worded independently.
 3. As Mob Construction moves a Unit through Design → Building → Gates → Merged, update

package/templates/skills/quality/SKILL.md

@@ -2,13 +2,13 @@
 name: quality
 description: Drafts the Quality Architecture Contract for an Intent, per quality-architecture-contract-generation-rules.md. Use when asked to run the Quality Skill or draft a Quality contract during Mob Elaboration.
 invoked_by: Mob Elaboration (Ceremony 1), Phases 2–5
-output: file — intents/<INTENT-ID>/contracts/quality-architecture-contract.md
+output: file — nvaid/intents/<INTENT-ID>/contracts/quality-architecture-contract.md
 ---
 
 # Quality Skill
 
 Drafts the Quality Architecture Contract for an Intent, per
-`docs/templates/quality-architecture-contract-generation-rules.md` — the Required Test
+`{{AIDLC_ROOT}}/quality-architecture-contract-generation-rules.md` — the Required Test
 Coverage table the Unit Test and Integration Test gates run against.
 
 ## Steps
@@ -20,12 +20,12 @@ Coverage table the Unit Test and Integration Test gates run against.
 3. State which existing SRS NFRs this Intent's Units are held to, beyond the standing
    baseline; say "none beyond baseline" explicitly when true.
 4. Log any Known Gap the room consciously accepted, flagged rather than dropped.
-5. Write `intents/<INTENT-ID>/contracts/quality-architecture-contract.md`.
+5. Write `nvaid/intents/<INTENT-ID>/contracts/quality-architecture-contract.md`.
 
 ## Boundaries
 
 - Never define Solution-Specific gates (Build, Code Coverage, Code Quality,
-  Reusability, Regression Test, SAST) — those are fixed in `docs/templates/PROJECT-RULES.md`
+  Reusability, Regression Test, SAST) — those are fixed in `nvaid/PROJECT-RULES.md`
   §5.2, not something any Intent's contract opts into or out of.
 - A draft, not a verdict — flag it awaiting the Quality Architect's Sign-Off; never
   present it as final.

package/templates/skills/solutions/SKILL.md

@@ -2,26 +2,28 @@
 name: solutions
 description: Drafts the Solutions Architecture Contract for an Intent, per solutions-architecture-contract-generation-rules.md. Use when asked to run the Solutions Skill or draft a Solutions contract during Mob Elaboration.
 invoked_by: Mob Elaboration (Ceremony 1), Phases 2–5
-output: file — intents/<INTENT-ID>/contracts/solutions-architecture-contract.md
+output: file — nvaid/intents/<INTENT-ID>/contracts/solutions-architecture-contract.md
 ---
 
 # Solutions Skill
 
 Drafts the Solutions Architecture Contract for an Intent, per
-`docs/templates/solutions-architecture-contract-generation-rules.md` — the cross-role
+`{{AIDLC_ROOT}}/solutions-architecture-contract-generation-rules.md` — the cross-role
 boundary and consistency check every other contract this session has to fit inside.
 
 ## Steps
 
-1. Assess whether this Intent introduces a new system container, crosses an SRS System
-   Container boundary, or needs a new ADR — state the answer even when it's "no" on
-   every count.
+1. Assess whether this Intent introduces a new system container, crosses an architectural
+   boundary, or **needs a new ADR** — state the answer even when it's "no" on every count.
+   If a new ADR is warranted, record it as `nvaid/adr/ADR-NNN-<slug>.md` (next free number)
+   using the ADR shape from the `/nvaid:install` skill: Context, Decision, Consequences,
+   Alternatives considered. An ADR is a decision anchor — it must not contradict
+   `nvaid/PROJECT-RULES.md`; if it would, reconcile them.
 2. State explicitly what this Intent is and isn't allowed to touch.
-3. Flag any unsupervised-action surface `docs/templates/PROJECT-RULES.md` §7 doesn't
-   already cover.
+3. Flag any unsupervised-action surface `nvaid/PROJECT-RULES.md` §7 doesn't already cover.
 4. Cross-check the other contracts drafted this session for contradictions — the
    Consistency Gate, recorded in writing.
-5. Write `intents/<INTENT-ID>/contracts/solutions-architecture-contract.md`.
+5. Write `nvaid/intents/<INTENT-ID>/contracts/solutions-architecture-contract.md`.
 
 ## Boundaries
 

package/templates/skills/unit-breakdown/SKILL.md

@@ -2,7 +2,7 @@
 name: unit-breakdown
 description: Cuts an Intent into Units of Work, each with its own Acceptance Criteria, per unit-breakdown-rules.md. Use when asked to run the Unit Breakdown Skill, break down an Intent into Units, or produce a Unit Breakdown during Mob Elaboration Phase 5.
 invoked_by: Mob Elaboration (Ceremony 1), Phase 5
-output: file — intents/<INTENT-ID>/unit-breakdown.md
+output: file — nvaid/intents/<INTENT-ID>/unit-breakdown.md
 ---
 
 # Unit Breakdown Skill
@@ -12,14 +12,14 @@ a first-cut proposal the room then critiques, not the decomposition of record.
 
 ## Steps
 
-1. Read the Intent file (`intents/<INTENT-ID>/intent.md`) and its stated success
+1. Read the Intent file (`nvaid/intents/<INTENT-ID>/intent.md`) and its stated success
    criteria.
 2. Propose a decomposition into Units, each with its own Acceptance Criteria narrowed
-   from the Intent's success criteria, per `docs/templates/unit-breakdown-rules.md` §2.
+   from the Intent's success criteria, per `{{AIDLC_ROOT}}/unit-breakdown-rules.md` §2.
 3. Classify each Unit as a Story or Bug (§3), and size it per the file's decomposition
    heuristics (§4).
 4. Number Units per §5.
-5. Write `intents/<INTENT-ID>/unit-breakdown.md` — the contract index every
+5. Write `nvaid/intents/<INTENT-ID>/unit-breakdown.md` — the contract index every
    Architecture Contract Skill downstream reads from.
 
 ## Boundaries
@@ -27,5 +27,5 @@ a first-cut proposal the room then critiques, not the decomposition of record.
 - This is a proposal, not the decomposition of record. Mob Elaboration Phase 3
   ("Mark it up alone") and Phase 4 ("Negotiate live") are where the room actually owns
   the cut — flag this file as a draft awaiting that review, never as final.
-- Read `docs/templates/unit-breakdown-rules.md` in full before drafting; don't rely on
+- Read `{{AIDLC_ROOT}}/unit-breakdown-rules.md` in full before drafting; don't rely on
   this summary alone for the numbering and classification rules.