@novare-technologies/nvaid 0.1.0 → 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/dist/cli.js

@@ -270,8 +270,14 @@ function hasConfig(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 ?? {} },
@@ -362,13 +368,14 @@ async function runInit(opts) {
   );
   p.outro(
     [
-      "Next, in your AI chat:",
+      "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",
-      "",
-      "Fill in nvaid/PROJECT-RULES.md and set owning_repo in nvaid/config.yml."
+      "  /nvaid:apply           generate per-repo unit docs + branches"
     ].join("\n")
   );
 }
@@ -455,7 +462,7 @@ async function runValidate() {
 
 // 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("0.1.0");
+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,

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@novare-technologies/nvaid",
-  "version": "0.1.0",
+  "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"
+    "nvaid": "dist/cli.js"
   },
   "files": [
     "dist",
@@ -39,10 +39,13 @@
     "yaml": "^2.4.0"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
+    "@types/node": "^22.0.0",
     "tsup": "^8.0.0",
     "tsx": "^4.7.0",
     "typescript": "^5.4.0",
-    "vitest": "^1.4.0"
+    "vitest": "^5.0.3"
+  },
+  "overrides": {
+    "esbuild": "^0.28.2"
   }
 }

package/templates/commands/apply.md

@@ -7,6 +7,14 @@ precondition: unit-breakdown approved (Decomposition-Approved gate green)
 
 # /nvaid:apply
 
+## ⛔ Precondition: nvaid install must be complete
+
+Read `nvaid/config.yml` and check the `install:` block. If `config`, `project_rules`, or
+`design_code_dictionary` is not `true` (or the file is missing), **STOP** and tell the
+user to run `/nvaid:install` first — name which flag(s) are false. Do not proceed until
+all three are true.
+
+
 Turn an **approved** unit-breakdown into construction-ready work: for each Unit, generate
 its design doc in the Owning Repo named by the breakdown, and open the construction branch
 per the `github` Skill.

package/templates/commands/breakdown.md

@@ -7,6 +7,14 @@ precondition: Contracts drafted (/nvaid:contracts has run)
 
 # /nvaid:breakdown
 
+## ⛔ Precondition: nvaid install must be complete
+
+Read `nvaid/config.yml` and check the `install:` block. If `config`, `project_rules`, or
+`design_code_dictionary` is not `true` (or the file is missing), **STOP** and tell the
+user to run `/nvaid:install` first — name which flag(s) are false. Do not proceed until
+all three are true.
+
+
 Produce `unit-breakdown.md` — the **Phase 5 output**, the decomposition of record,
 informed by the contracts from `/nvaid:contracts`. This runs **after** contracts, not
 before (the `unit-breakdown` Skill is Phase 5; the contract Skills are Phases 2–5).

package/templates/commands/contracts.md

@@ -7,6 +7,14 @@ precondition: Intent approved (Decomposition-Approved gate green)
 
 # /nvaid:contracts
 
+## ⛔ Precondition: nvaid install must be complete
+
+Read `nvaid/config.yml` and check the `install:` block. If `config`, `project_rules`, or
+`design_code_dictionary` is not `true` (or the file is missing), **STOP** and tell the
+user to run `/nvaid:install` first — name which flag(s) are false. Do not proceed until
+all three are true.
+
+
 Draft the Architecture Contracts for an **already-approved** Intent, running each role's
 contract Skill. The contracts are negotiated across Elaboration Phases 2–5 and **precede**
 the unit-breakdown (which is the Phase 5 output) — run `/nvaid:breakdown` after this.

package/templates/commands/install.md

@@ -0,0 +1,63 @@
+---
+command: nvaid:install
+summary: Scan the project and fill in the three required nvaid documents (config.yml, PROJECT-RULES.md, DESIGN-CODE-DICTIONARY.md). Must run before /nvaid:intent.
+stage: "nvaid onboarding — run once, first, before any workflow command"
+blocks: [nvaid:intent, nvaid:contracts, nvaid:breakdown, nvaid:apply]
+---
+
+# /nvaid:install
+
+The **first** command to run after `nvaid init`. `init` only drops empty templates; this
+skill makes nvaid actually usable by scanning the project and authoring the three required
+documents. **Every other nvaid workflow command is blocked until this completes** — running
+`/nvaid:intent` against unfilled templates would produce hollow, confidently-wrong output.
+
+## Why this is a skill, not a CLI step
+
+The CLI can detect facts (languages, frameworks from manifest files) but cannot author
+*judgment*: a project's guardrails, its design patterns, what breaks if a given module
+changes. That requires reading the actual code and reasoning about it — the agent's job,
+not a file-scan's. This skill does that reading. A human reviews before it's marked done
+(propose, don't dispose).
+
+## Steps
+
+1. **Scan the project.** Read manifest files (`package.json`, `pyproject.toml`, `go.mod`,
+   lockfiles), the directory structure, config, CI workflows, and a representative sample
+   of source to understand the stack, the architecture, and the conventions in use.
+
+2. **Fill `nvaid/config.yml`** — replace every `<placeholder>`:
+   - `project_name`, `owning_repo` (frontend | backend | platform | other — infer from the
+     code, confirm with the user if ambiguous).
+   - `tech_stack` — fill from what you actually found in the manifests, not assumptions.
+   - `architects` — these are sign-off identities you cannot infer from code. **Ask the
+     user** for the names; leave a role blank only if the user confirms it doesn't apply.
+   - `context` — the short, always-on constraints worth repeating to every agent.
+
+3. **Author `nvaid/PROJECT-RULES.md`** — replace the template skeleton with real content:
+   the approved stack and what's disallowed without an ADR, non-negotiable constraints,
+   data rules, coding standards, the quality gates CI actually runs, and known gaps.
+   Derive what you can from the code (e.g. the lint/test config that exists); for anything
+   that is a *decision* rather than a fact (what's allowed, what's off-limits), propose it
+   and flag it for the user to confirm — do not invent a guardrail the project hasn't made.
+
+4. **Author `nvaid/DESIGN-CODE-DICTIONARY.md`** — the technical README for the code:
+   the design patterns and conventions in use (with real file examples), and the component
+   map (concept → where it lives → what it depends on → what breaks if changed). This is
+   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.
+
+6. **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.
+
+## Boundaries
+
+- Facts come from the code; **decisions and sign-off identities come from the user** — ask,
+  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.

package/templates/commands/intent.md

@@ -6,6 +6,21 @@ stage: "Fig. 2 Stage 1 — Intent captured, pre-Elaboration"
 
 # /nvaid:intent
 
+## ⛔ Precondition: nvaid install must be complete
+
+Before doing anything, read `nvaid/config.yml` and check the `install:` block. If
+`config`, `project_rules`, or `design_code_dictionary` is **not** `true` — or
+`nvaid/config.yml` doesn't exist — **STOP** and tell the user:
+
+> nvaid isn't fully installed in this project yet. Run `/nvaid:install` first — it scans
+> the project and fills in config.yml, PROJECT-RULES.md, and DESIGN-CODE-DICTIONARY.md.
+> Those documents are what this command relies on; drafting an Intent without them would
+> produce hollow output.
+
+Name which flag(s) are false. Do not proceed with any step below until all three are true.
+
+---
+
 Draft a new Intent from the user's description. Produce **only** `intent.md` — the
 business need, who it's for, success criteria, and scope boundaries — then **stop**.
 
@@ -18,9 +33,8 @@ limitation — propose, don't dispose.
 
 ## Steps
 
-1. Read this repo's `nvaid/PROJECT-RULES.md` (if present) for the project's operating
-   guardrails and approved stack. If it is still the unfilled template, proceed but note
-   that the project rules are not yet defined.
+1. Read this repo's `nvaid/PROJECT-RULES.md` for the project's operating guardrails and
+   approved stack (guaranteed authored, since the install gate above has passed).
 2. Write `nvaid/intents/<INTENT-ID>-<slug>/intent.md`: business need, who it's for,
    Intent-level success criteria (observable outcomes, not implementation), scope
    boundaries (name what's out of scope, don't silently drop it), and open questions for

package/templates/nvaid/config.yml

@@ -12,6 +12,19 @@
 
 schema: nvaid/v1
 
+# Installation gate. `nvaid init` scaffolds empty templates; the /nvaid:install SKILL
+# then scans the project and fills in all three required documents. The workflow commands
+# (/nvaid:intent, :contracts, :breakdown, :apply) are BLOCKED until install is complete —
+# running them against unfilled templates would produce hollow, confidently-wrong output.
+#
+# Each flag is set to true by /nvaid:install only once that document is genuinely filled
+# (not left as <placeholder> template text) and a human has confirmed it. The install is
+# "complete" when all three are true.
+install:
+  config: false              # project_name, owning_repo, tech_stack, architects all set
+  project_rules: false       # nvaid/PROJECT-RULES.md authored (not the template skeleton)
+  design_code_dictionary: false  # nvaid/DESIGN-CODE-DICTIONARY.md authored (not the skeleton)
+
 # A short name for this project/repo, used in generated artifact headers
 # (replaces the {{PROJECT_NAME}} placeholder in PROJECT-RULES.md and the dictionary).
 project_name: "<set-me>"
@@ -71,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.1.0"
+generated_with: "0.2.0"