@nurix/etna 0.1.1 → 0.1.3

package/README.md

@@ -1,35 +1,36 @@
 # @nurix/etna
 
-CLI to bootstrap a project with a Nurix harness. Installs a Claude Code plugin from the `nurixlabs/skills` marketplace and drops the harness's `CLAUDE.md` at the project root.
+CLI to bootstrap a project with a Nurix harness. Produces the same on-disk state as running
 
-See [`../../harness/README.md`](../../harness/README.md) for what a harness is.
+```
+/plugin marketplace add nurixlabs/skills
+/plugin install nurix-harness@nurixlabs
+```
+
+inside Claude Code, plus drops the harness's `CLAUDE.md` at the project root. See [`../../harness/README.md`](../../harness/README.md) for what a harness is and why the install model is designed this way.
 
 ## Usage
 
 From the root of the project you want to bootstrap:
 
 ```sh
-GITHUB_TOKEN=ghp_... npx @nurix/etna nurix-harness
+npx @nurix/etna nurix-harness
 ```
 
-After this completes, the directory contains:
+After this completes, three things have changed on disk:
 
 ```
 your-project/
-├── CLAUDE.md                              ← from harness/<folder>/CLAUDE.md (bundled in this package)
+├── CLAUDE.md                          ← bundled in this package; the harness's policy
 └── .claude/
-    ├── settings.json                      ← enabledPlugins updated
-    └── plugins/
-        └── nurix-harness/                 ← fetched from nurixlabs/skills/plugins/nurix-harness/
-            ├── .claude-plugin/plugin.json
-            ├── skills/{documentation, workflow-mapper, introspect}/
-            ├── agents/{change-review, contract-monitor, dep-health, git-history, maintenance, review, spec-mode}.md
-            ├── scripts/{build-ownership-index, check-doc-drift}.sh
-            ├── rules/{general, nomenclature}.md
-            └── README.md
+    └── settings.json                  ← enabledPlugins["nurix-harness@nurixlabs"] = true
+
+~/.claude/settings.json                ← extraKnownMarketplaces["nurixlabs"] registered
 ```
 
-Open Claude Code in the project; it will pick up the plugin on next start. If Claude Code is already running, run `/reload-plugins`.
+That's the entire footprint. Open Claude Code in the project; on next session start it resolves `nurix-harness@nurixlabs`, clones `nurixlabs/skills` into `~/.claude/plugins/marketplaces/`, fills the plugin cache at `~/.claude/plugins/cache/nurixlabs/nurix-harness/<version>/`, and loads the plugin. The CLI does not touch any of those Claude Code internals itself — that's deliberate (see [Installation goals](../../harness/README.md#installation-goals)).
+
+If Claude Code is already running, run `/reload-plugins`.
 
 ## Available harnesses
 
@@ -37,28 +38,21 @@ Listed by `npx @nurix/etna` (no args) using the bundled `data/harness-index.json
 
 | Plugin name | Harness folder in etna | What it ships |
 |---|---|---|
-| `nurix-harness` | [`harness/code/`](../../harness/code/) | The canonical v7 harness — 7 audit agents, 3 workflow skills, 2 rules, 2 scripts |
-
-## Environment
-
-| Variable | Required | Purpose |
-|---|---|---|
-| `GITHUB_TOKEN` | Yes (while `nurixlabs/skills` is private) | Personal access token with `repo:read` scope. Access to `nurixlabs/skills` is the access control for the harness. |
-| `NURIX_SKILLS_REF` | No | Git ref to fetch from in `nurixlabs/skills`. Default `dev`. |
+| `nurix-harness` | [`harness/code/`](../../harness/code/) | The canonical v7 harness — governance agents, baseline workflow skills, ownership/drift scripts |
 
 ## How it works
 
-1. Looks up `<plugin-name>` in the bundled `data/harness-index.json` to find the matching harness folder.
-2. Walks `nurixlabs/skills/plugins/<plugin-name>/` via the GitHub Contents API and downloads each file into `./.claude/plugins/<plugin-name>/`.
-3. Copies the bundled `data/harnesses/<harness-folder>/CLAUDE.md` to `./CLAUDE.md`.
-4. Adds `<plugin-name>@nurixlabs: true` to `./.claude/settings.json` under `enabledPlugins`.
+1. Looks up `<plugin-name>` in the bundled `data/harness-index.json` to find the matching harness folder and the marketplace metadata.
+2. Copies the bundled `data/harnesses/<harness-folder>/CLAUDE.md` to `./CLAUDE.md` (backing up any existing one to `CLAUDE.md.bak.<ISO-timestamp>`).
+3. Adds the marketplace entry to `~/.claude/settings.json` under `extraKnownMarketplaces`.
+4. Adds `<plugin-name>@<marketplace>: true` to `./.claude/settings.json` under `enabledPlugins`.
 
-Existing `CLAUDE.md` or plugin folder at the destination is renamed to `<name>.bak.<ISO-timestamp>` before install. Nothing is overwritten.
+No GitHub fetch. No `.claude/plugins/<name>/` folder. Claude Code's plugin resolver handles all of that on next launch.
 
 ## Why two sources
 
-- **Plugin content** comes from the marketplace (`nurixlabs/skills`) so it's always the latest CI-published version.
-- **`CLAUDE.md`** is bundled in this npm package, versioned with the package. Harness policy changes warrant a package version bump.
+- **Plugin content** lives in the marketplace (`nurixlabs/skills`) and is fetched by Claude Code at session start — always the latest CI-published version.
+- **`CLAUDE.md`** is bundled in this npm package, versioned with the package. A plugin cannot ship a project-root `CLAUDE.md` (Claude Code's plugin spec doesn't support it), so the CLI ships that half itself. Harness policy changes warrant a package version bump.
 
 ## Building / contributing
 
@@ -73,10 +67,4 @@ npm run build:data
 
 ## Publishing
 
-From `packages/cli/`:
-
-```sh
-npm publish --access restricted
-```
-
-The `publishConfig.access` is `restricted` so the scoped package is private by default.
+CI auto-publishes on push to `dev` when `packages/cli/**` or `harness/**` change — see [`.github/workflows/publish-etna-to-npm.yml`](../../.github/workflows/publish-etna-to-npm.yml). The `publishConfig.access` is `restricted` so the scoped package is private by default.

package/bin/etna.js

@@ -1,8 +1,12 @@
 #!/usr/bin/env node
 // packages/cli/bin/etna.js
-// `npx @nurix/etna <plugin-name>` — install a Nurix harness into the current directory.
+// `npx @nurix/etna <plugin-name>` — bootstrap a Nurix harness in the current directory.
+// Produces the same on-disk state as running `/plugin marketplace add <repo>` followed by
+// `/plugin install <plugin>@<marketplace>` inside Claude Code, plus drops the harness's
+// CLAUDE.md at the project root. Claude Code's plugin resolver fills the cache on next launch.
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, copyFileSync, lstatSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -10,20 +14,17 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkgRoot = resolve(__dirname, '..');
 const dataDir = join(pkgRoot, 'data');
 
-const SKILLS_REPO = 'nurixlabs/skills';
-const SKILLS_REF = process.env.NURIX_SKILLS_REF || 'dev';
-
 function usage() {
-    console.log(`\nUsage: npx @nurix/etna <plugin-name>\n`);
     const idx = loadHarnessIndex();
+    console.log(`\nUsage: npx @nurix/etna <plugin-name>\n`);
     const names = Object.keys(idx.plugins);
     if (names.length) {
-        console.log(`Available harnesses (plugin → harness folder):`);
-        for (const name of names) console.log(`  ${name.padEnd(20)} → harness/${idx.plugins[name]}`);
+        console.log(`Available harnesses (plugin → marketplace):`);
+        for (const name of names) {
+            console.log(`  ${name.padEnd(20)} → ${idx.marketplace.name}`);
+        }
     }
-    console.log(`\nEnvironment:`);
-    console.log(`  GITHUB_TOKEN          Required if ${SKILLS_REPO} is private (token with repo:read scope)`);
-    console.log(`  NURIX_SKILLS_REF      Git ref to fetch from (default: dev)`);
+    console.log(`\nMarketplace: ${idx.marketplace.source.repo} (github)`);
     console.log();
 }
 
@@ -40,54 +41,6 @@ function die(msg, code = 1) {
     process.exit(code);
 }
 
-function ghHeaders() {
-    const h = {
-        Accept: 'application/vnd.github+json',
-        'User-Agent': '@nurix/etna',
-        'X-GitHub-Api-Version': '2022-11-28',
-    };
-    if (process.env.GITHUB_TOKEN) h.Authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
-    return h;
-}
-
-// Recursively download a GitHub repo subdirectory into a local destination.
-async function fetchPluginFolder(pluginName, destDir) {
-    const apiUrl = `https://api.github.com/repos/${SKILLS_REPO}/contents/plugins/${pluginName}?ref=${SKILLS_REF}`;
-    await fetchDir(apiUrl, destDir);
-}
-
-async function fetchDir(apiUrl, destDir) {
-    const res = await fetch(apiUrl, { headers: ghHeaders() });
-    if (res.status === 401 || res.status === 403) {
-        die(
-            `GitHub returned ${res.status} for ${apiUrl}.\n` +
-                `${SKILLS_REPO} is private — set GITHUB_TOKEN (a personal access token with repo:read scope).\n` +
-                `  export GITHUB_TOKEN=ghp_...`,
-        );
-    }
-    if (res.status === 404) {
-        die(`Plugin not found in ${SKILLS_REPO}@${SKILLS_REF}. Has the marketplace publish pipeline run yet?`);
-    }
-    if (!res.ok) die(`GitHub API ${res.status}: ${await res.text()}`);
-
-    const items = await res.json();
-    mkdirSync(destDir, { recursive: true });
-
-    for (const item of items) {
-        const localPath = join(destDir, item.name);
-        if (item.type === 'dir') {
-            await fetchDir(item.url, localPath);
-        } else if (item.type === 'file') {
-            const dl = item.download_url;
-            if (!dl) die(`File ${item.path} has no download_url`);
-            const fileRes = await fetch(dl, { headers: ghHeaders() });
-            if (!fileRes.ok) die(`Failed to download ${item.path}: ${fileRes.status}`);
-            const buf = Buffer.from(await fileRes.arrayBuffer());
-            writeFileSync(localPath, buf);
-        }
-    }
-}
-
 // Move <path> to <path>.bak.<timestamp> if it exists. Returns the backup path, or null.
 function backupIfExists(path) {
     if (!existsSync(path) && !isSymlink(path)) return null;
@@ -105,28 +58,46 @@ function isSymlink(path) {
     }
 }
 
-// Add pluginName to enabledPlugins in .claude/settings.json (creating the file if needed).
-// Uses the conventional shape `"plugin-name@marketplace": true`.
-function enablePlugin(targetDir, pluginName) {
-    const claudeDir = join(targetDir, '.claude');
-    mkdirSync(claudeDir, { recursive: true });
-    const settingsPath = join(claudeDir, 'settings.json');
-
-    let settings = {};
-    if (existsSync(settingsPath)) {
-        try {
-            settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
-        } catch (e) {
-            die(`Failed to parse existing ${settingsPath}: ${e.message}`);
-        }
+function readJson(path) {
+    if (!existsSync(path)) return {};
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    } catch (e) {
+        die(`failed to parse ${path}: ${e.message}`);
     }
+}
+
+// 2-space indent matches Claude Code's own writes to settings.json.
+function writeJson(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value, null, 2) + '\n');
+}
+
+// Register the marketplace in ~/.claude/settings.json (extraKnownMarketplaces).
+// Mirrors what `/plugin marketplace add <owner>/<repo>` writes, plus opts the
+// marketplace into auto-updates (off by default for non-Anthropic marketplaces).
+function registerMarketplace(marketplace) {
+    const path = join(homedir(), '.claude', 'settings.json');
+    const settings = readJson(path);
+    settings.extraKnownMarketplaces = settings.extraKnownMarketplaces || {};
+    settings.extraKnownMarketplaces[marketplace.name] = {
+        source: marketplace.source,
+        autoUpdate: true,
+    };
+    writeJson(path, settings);
+    return path;
+}
 
+// Add `<plugin>@<marketplace>: true` to <target>/.claude/settings.json under enabledPlugins.
+// Mirrors what `/plugin install <plugin>@<marketplace>` writes at project scope.
+function enablePlugin(targetDir, pluginName, marketplaceName) {
+    const path = join(targetDir, '.claude', 'settings.json');
+    const settings = readJson(path);
     settings.enabledPlugins = settings.enabledPlugins || {};
-    const key = `${pluginName}@nurixlabs`;
+    const key = `${pluginName}@${marketplaceName}`;
     settings.enabledPlugins[key] = true;
-
-    writeFileSync(settingsPath, JSON.stringify(settings, null, 4) + '\n');
-    return { settingsPath, key };
+    writeJson(path, settings);
+    return { path, key };
 }
 
 async function main(args) {
@@ -150,32 +121,28 @@ async function main(args) {
     }
 
     const targetDir = process.cwd();
-    const pluginDir = join(targetDir, '.claude', 'plugins', pluginName);
     const claudeMdDest = join(targetDir, 'CLAUDE.md');
+    const marketplace = idx.marketplace;
+    const fqKey = `${pluginName}@${marketplace.name}`;
 
-    console.log(`\nInstalling ${pluginName} (from harness/${harnessFolder}) into ${targetDir}`);
+    console.log(`\nInstalling ${fqKey} into ${targetDir}`);
 
-    // 1. Backup conflicts
-    const pluginBackup = backupIfExists(pluginDir);
-    if (pluginBackup) console.log(`  backed up existing plugin folder → ${pluginBackup}`);
     const claudeBackup = backupIfExists(claudeMdDest);
     if (claudeBackup) console.log(`  backed up existing CLAUDE.md → ${claudeBackup}`);
 
-    // 2. Fetch plugin from nurixlabs/skills marketplace
-    console.log(`  fetching plugin from ${SKILLS_REPO}@${SKILLS_REF}…`);
-    await fetchPluginFolder(pluginName, pluginDir);
-    console.log(`  installed plugin → ${pluginDir}`);
-
-    // 3. Copy bundled CLAUDE.md to project root
     copyFileSync(bundledClaude, claudeMdDest);
     console.log(`  installed CLAUDE.md → ${claudeMdDest}`);
 
-    // 4. Enable plugin in .claude/settings.json
-    const { settingsPath, key } = enablePlugin(targetDir, pluginName);
-    console.log(`  enabled '${key}' in ${settingsPath}`);
+    const marketplacePath = registerMarketplace(marketplace);
+    console.log(`  registered marketplace '${marketplace.name}' → ${marketplacePath}`);
+
+    const { path: enablePath } = enablePlugin(targetDir, pluginName, marketplace.name);
+    console.log(`  enabled '${fqKey}' → ${enablePath}`);
 
-    console.log(`\nDone. Open Claude Code in this directory; it will load the plugin on next start.`);
-    console.log(`Run /plugin to verify, or /reload-plugins if it's already running.\n`);
+    console.log(`\nDone. Open Claude Code in ${targetDir}.`);
+    console.log(
+        `It will fetch ${marketplace.source.repo}, install ${pluginName}, and load it on next session start.\n`,
+    );
 }
 
 main(process.argv.slice(2)).catch((e) => {

package/data/harness-index.json

@@ -1,5 +1,13 @@
 {
+    "marketplace": {
+        "name": "nurixlabs",
+        "source": {
+            "source": "github",
+            "repo": "nurixlabs/skills"
+        }
+    },
     "plugins": {
-        "nurix-harness": "code"
+        "nurix-harness": "code",
+        "kb-agi": "kb-agi"
     }
 }

package/data/harnesses/code/CLAUDE.md

@@ -73,6 +73,13 @@ Feature docs in `docs/features/` must include YAML frontmatter with `owns`, `tou
 
 The spec-mode agent checks for ownership conflicts during research. If conflicts are found, address them in the spec before proceeding.
 
+### Architecture Decisions (ADRs)
+
+Record an ADR when a decision (a) changes how state, dependencies, or boundaries are organized, (b) has a rejected alternative worth remembering, and (c) could plausibly be re-litigated. Default: don't write one. Style preferences, local refactors, and obvious-from-code choices don't qualify.
+
+- File: `docs/architecture/adr/NNNN-kebab-case.md` (4-digit sequential number). Frozen once written — supersede via a new ADR, never edit.
+- Invoke the `documentation` skill with "record an ADR" or "architecture decision".
+
 ---
 
 ## Agents
@@ -88,7 +95,7 @@ Seven sub-agents and three skills are defined under `.claude/`. Reach for them b
 | `dep-health` | Agent | Dependency supply-chain audit | "audit dependencies", "check CVEs", "dep health" |
 | `git-history` | Agent | Classify recent commits into a velocity/severity CSV | "classify commits", "commit history report" |
 | `change-review` | Agent | Velocity heatmap, risk zones (high churn + low coverage) | "where is risk accumulating", "velocity report" |
-| `documentation` | Skill | Baseline audit, scaffolding, templates | "baseline docs", "create docs", "audit docs" |
+| `documentation` | Skill | Baseline audit, scaffolding, templates, ADRs, guardrails | "baseline docs", "create docs", "audit docs", "record an ADR", "architecture decision", "create guardrails" |
 | `workflow-mapper` | Skill | Discover and diagram codebase workflows | "map workflows", "trace flows" |
 | `introspect` | Skill | Pre-implementation impact analysis against guardrails | "introspect this plan", "impact analysis" |
 
@@ -140,20 +147,22 @@ Unless explicitly requested:
 
 The six procedural folders below are fixed. Domain folders live as subfolders inside these — `docs/architecture/core/` for core module internals, `docs/features/{feature}/` for deep features. Discovery flows through **[`docs/routing.md`](docs/routing.md)** when present.
 
-| Folder               | Purpose                                                | Mutability            |
-| -------------------- | ------------------------------------------------------ | --------------------- |
-| `docs/architecture/` | System-wide patterns, technical decisions, API specs   | Living                |
-| `docs/features/`     | How implemented features work today                    | Living                |
-| `docs/operations/`   | Setup, development, deployment                         | Living                |
-| `docs/history/`      | Plans, changelogs, backlog                             | Frozen or append-only |
-| `docs/memory/`       | Project knowledge + agent state                        | Living                |
-| `docs/tests/`        | Test plans and automation                              | Living                |
+| Folder                   | Purpose                                                  | Mutability            |
+| ------------------------ | -------------------------------------------------------- | --------------------- |
+| `docs/architecture/`     | System-wide patterns, technical decisions, API specs     | Living                |
+| `docs/architecture/adr/` | Architecture Decision Records — numbered, one per file   | Frozen (supersede)    |
+| `docs/features/`         | How implemented features work today                      | Living                |
+| `docs/operations/`       | Setup, development, deployment                           | Living                |
+| `docs/history/`          | Plans, changelogs, backlog                               | Frozen or append-only |
+| `docs/memory/`           | Project knowledge + agent state                          | Living                |
+| `docs/tests/`            | Test plans and automation                                | Living                |
 
 ### Naming & Lifecycle
 
 - Features: `kebab-case.md` — living reference, status `Active`
 - Plans: `YYYY-MM-DD-kebab-case.md` — frozen after `Complete` or `Abandoned`
 - Changelogs: `YYYY-MM-DD-kebab-case.md` — append-only
+- ADRs: `NNNN-kebab-case.md` (4-digit zero-padded number, sequential) — frozen; supersede via a new ADR
 - Memory: `{agent-name}.md` — agent-maintained
 
 ### Documentation Maintenance

package/data/harnesses/kb-agi/CLAUDE.md

@@ -0,0 +1,57 @@
+# nupilot Knowledge Hub — router
+
+This repo is a flat Obsidian vault that you read on the user's behalf. It's the bridge from the front (positioning, claims) to the back (product and service specs); detailed execution lives downstream in the service repos.
+
+You are the **router**. Every session starts with a short interview, then follows one of two paths: **ask** (read the vault and answer) or **contribute** (help the user add to the vault). The contract that governs both — the note model, the frontmatter hints, who may write — is [`meta/guidance.md`](meta/guidance.md). Read it before you write anything.
+
+---
+
+## Step 0 — first run
+
+If `meta/guidance.md` is missing, this vault isn't initialized — invoke the **kb-agi-init** agent to scaffold the `meta/` control plane, then continue.
+
+---
+
+## Step 1 — the opening interview
+
+Before answering anything, run a short interview with the `AskUserQuestion` tool to establish two things:
+
+1. **What brings you?** → *ask* (you have a question) or *contribute* (you have something to add).
+2. **Your user-type (genre):** → *Sales*, *PM*, or *Contributor*. This sets the default depth and framing of answers, nothing else. (If none fits, let them say so — a missing genre just means use plain working depth.)
+
+Then load the matching template from [`meta/genre/`](meta/genre/) — `sales.md`, `pm.md`, or `contributor.md` — and follow the path below.
+
+Keep the interview to those two questions. Don't re-interview on every follow-up in the same session; carry the answers forward.
+
+---
+
+## The ask path — read-only
+
+You are **read-only** on this path. You never edit a note. Your only write is appending a query log to `meta/sessions/` (see below).
+
+1. **Find the entry note(s)** for the question. Start from [`meta/intent-index.md`](meta/intent-index.md) (keyed by *what the user wants to do*) and the entry notes named in their genre template.
+2. **Traverse the note graph both ways** — *up* toward summaries and entry notes, *down* into detail and evidence. The `[[wikilinks]]` are the structure. Lead with `canonical` notes; treat `canonical: false` ones as background.
+3. **Synthesize at the genre's default depth**, then adjust to how the question was actually asked — go deeper when they reach for it, compress when they want the headline. Depth shapes the answer; it never hides notes.
+4. **Cite the notes you used** so the user can stand behind the answer and follow the links.
+5. **Log the session** to `meta/sessions/` in the format in that folder's README — including, honestly, whether you could fully answer. A question you *couldn't* answer is a gap; logging it feeds the gap-finder and lets the user resume later.
+
+If the vault can't answer, say so plainly and log it as a gap. Don't invent an answer the notes don't support.
+
+## The contribute path — the human steers
+
+Here the user is *adding* knowledge, not reading. This path is deliberately thin and grows with use. There are **no sub-agents** — it's you and the user in a normal session.
+
+1. **Orient them** with [`meta/guidance.md`](meta/guidance.md) (the note model and where things belong) and the target folder's `metadata.md` (what belongs there, what's already nearby).
+2. **What does the hub want next?** Run the `kb-find-gaps` agent (it reads `meta/sessions/` gaps + folder `metadata.md`) — that's the live content roadmap.
+3. **Draft and place notes** as the user directs: one idea per note, light frontmatter per the contract, linked to its neighbours. Links form naturally as you write.
+4. Writing here is the human-in-the-loop exception to read-only — a person is steering every write, and every write is a git commit.
+
+---
+
+## What you do *not* do
+
+- **You don't run upkeep.** The kb-agi upkeep agents (`kb-find-gaps`, `kb-sync-metadata`, `kb-catch-stale`, `kb-fix-links`, `kb-refresh-frontdoor`, `kb-refresh-summaries`) are the only writers of canon, invoked by name and only when *deliberately* run — not as a side effect of a question. Don't trigger them from the ask path.
+- **You don't hand-edit `meta/_kg/`** — it's a derived graph, regenerated from the notes.
+- **You don't mutate notes on the ask path.** Read-only means read-only.
+
+Everything is git-checked-in, so any write is reviewable and reversible (doctrine P3).

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nurix/etna",
-    "version": "0.1.1",
+    "version": "0.1.3",
     "description": "Bootstrap a project with a Nurix harness — installs a Claude Code plugin from the nurixlabs/skills marketplace and drops the harness's CLAUDE.md at the project root.",
     "type": "module",
     "bin": {