@novare-technologies/nvaid 0.2.1 → 0.2.3

package/dist/cli.js

@@ -13,8 +13,9 @@ 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
   },
   {
@@ -22,68 +23,65 @@ var AGENTS = [
     label: "Kiro",
     skillsPath: ".kiro/skills",
     instructionsFile: ".kiro/steering/nvaid.md",
-    format: "markdown",
     bespoke: true
   },
   {
     id: "cursor",
     label: "Cursor",
-    skillsPath: ".cursor/rules",
-    format: "mdc",
+    skillsPath: ".cursor/skills",
+    // cursor.com/docs/skills
     bespoke: true
   },
   {
     id: "copilot",
     label: "GitHub Copilot",
-    skillsPath: ".github",
+    skillsPath: ".github/skills",
+    // docs.github.com — project skills in .github/skills
     instructionsFile: ".github/copilot-instructions.md",
-    format: "markdown",
     bespoke: true
   },
   {
     id: "windsurf",
     label: "Windsurf",
-    skillsPath: ".windsurf/rules",
-    format: "markdown",
+    skillsPath: ".windsurf/skills",
+    // docs.windsurf.com/windsurf/cascade/skills
     bespoke: true
   },
   {
     id: "amazonq",
     label: "Amazon Q",
-    skillsPath: ".amazonq/rules",
-    format: "markdown",
+    skillsPath: ".amazonq/skills",
     bespoke: true
   },
   {
     id: "cline",
     label: "Cline",
-    skillsPath: ".cline/rules",
+    skillsPath: ".cline/skills",
+    // docs.cline.bot/customization/skills
     instructionsFile: ".clinerules",
-    format: "markdown",
     bespoke: true
   },
   {
     id: "gemini",
     label: "Gemini Code Assist",
-    skillsPath: ".gemini",
-    instructionsFile: ".gemini/styleguide.md",
-    format: "markdown",
+    skillsPath: ".gemini/skills",
+    // geminicli.com/docs/cli/skills
     bespoke: true
   },
   {
     id: "aider",
     label: "Aider",
-    skillsPath: ".nvaid/skills",
+    skillsPath: ".agents/skills",
+    // neutral cross-tool skills location
     instructionsFile: "AGENTS.md",
-    format: "markdown",
     bespoke: true
   },
   {
     id: "agents-md",
-    label: "Any AGENTS.md-compatible tool (catch-all)",
-    skillsPath: ".nvaid/skills",
+    label: "Any Agent-Skills / AGENTS.md tool (catch-all)",
+    skillsPath: ".agents/skills",
+    // the emerging neutral standard (per GitHub Copilot docs)
     instructionsFile: "AGENTS.md",
-    format: "markdown",
     bespoke: false
   }
 ];
@@ -120,11 +118,7 @@ function aidlcRootFor(agent) {
   void agent;
   return "nvaid/rules";
 }
-function withHeader(body, format) {
-  if (format === "mdc") {
-    return `${DO_NOT_EDIT}
-${body}`;
-  }
+function withHeader(body) {
   return `${DO_NOT_EDIT}
 
 ${body}`;
@@ -140,16 +134,17 @@ async function listCommandFiles() {
 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);
+  return withHeader(substituted);
 }
 function skillTarget(projectRoot, agent, skill) {
-  const ext = agent.format === "mdc" ? "mdc" : "md";
-  return join(projectRoot, agent.skillsPath, `${skill}.${ext}`);
+  return join(projectRoot, agent.skillsPath, skill, "SKILL.md");
 }
 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}.md`);
+  }
+  return join(projectRoot, agent.skillsPath, `nvaid-${base}`, "SKILL.md");
 }
 async function writeFileEnsuringDir(path, body, force, result) {
   if (!force && existsSync(path)) {
@@ -186,15 +181,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;
@@ -205,12 +199,22 @@ async function diffAgentFiles(opts) {
   return drift;
 }
 async function cleanAgentDirs(projectRoot, agents) {
+  const skills = await listSkillDirs().catch(() => []);
   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 });
+    if (agent.commandsPath) {
+      await rmIfExists(join(projectRoot, agent.commandsPath, "nvaid"));
+    }
+    await rmIfExists(join(projectRoot, agent.skillsPath, "commands"));
+    await rmIfExists(join(projectRoot, agent.skillsPath, "nvaid-commands"));
+    for (const skill of skills) {
+      await rmIfExists(join(projectRoot, agent.skillsPath, `${skill}.md`));
+      await rmIfExists(join(projectRoot, agent.skillsPath, `${skill}.mdc`));
+    }
   }
 }
+async function rmIfExists(path) {
+  if (existsSync(path)) await rm(path, { recursive: true, force: true });
+}
 
 // src/scaffold.ts
 import { cp, mkdir as mkdir2, readdir as readdir2 } from "fs/promises";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@novare-technologies/nvaid",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "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.1"
+generated_with: "0.2.3"

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.