@nurix/etna 0.1.1

package/README.md

@@ -0,0 +1,82 @@
+# @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.
+
+See [`../../harness/README.md`](../../harness/README.md) for what a harness is.
+
+## Usage
+
+From the root of the project you want to bootstrap:
+
+```sh
+GITHUB_TOKEN=ghp_... npx @nurix/etna nurix-harness
+```
+
+After this completes, the directory contains:
+
+```
+your-project/
+├── CLAUDE.md                              ← from harness/<folder>/CLAUDE.md (bundled in this package)
+└── .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
+```
+
+Open Claude Code in the project; it will pick up the plugin on next start. If Claude Code is already running, run `/reload-plugins`.
+
+## Available harnesses
+
+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`. |
+
+## 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`.
+
+Existing `CLAUDE.md` or plugin folder at the destination is renamed to `<name>.bak.<ISO-timestamp>` before install. Nothing is overwritten.
+
+## 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.
+
+## Building / contributing
+
+`data/` is generated. Don't edit by hand. To regenerate after touching anything under `etna/harness/`:
+
+```sh
+cd packages/cli
+npm run build:data
+```
+
+`prepack` runs `build:data` automatically before `npm publish`, so the bundled data always matches the published package's commit.
+
+## Publishing
+
+From `packages/cli/`:
+
+```sh
+npm publish --access restricted
+```
+
+The `publishConfig.access` is `restricted` so the scoped package is private by default.

package/bin/etna.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+// packages/cli/bin/etna.js
+// `npx @nurix/etna <plugin-name>` — install a Nurix harness into the current directory.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, copyFileSync, lstatSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+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();
+    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(`\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();
+}
+
+function loadHarnessIndex() {
+    const path = join(dataDir, 'harness-index.json');
+    if (!existsSync(path)) {
+        die(`harness-index.json missing — run \`npm run build:data\` from the package root.`);
+    }
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+function die(msg, code = 1) {
+    console.error(`error: ${msg}`);
+    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;
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const backup = `${path}.bak.${ts}`;
+    renameSync(path, backup);
+    return backup;
+}
+
+function isSymlink(path) {
+    try {
+        return lstatSync(path).isSymbolicLink();
+    } catch {
+        return false;
+    }
+}
+
+// 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}`);
+        }
+    }
+
+    settings.enabledPlugins = settings.enabledPlugins || {};
+    const key = `${pluginName}@nurixlabs`;
+    settings.enabledPlugins[key] = true;
+
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 4) + '\n');
+    return { settingsPath, key };
+}
+
+async function main(args) {
+    if (args.includes('-h') || args.includes('--help') || args.length === 0) {
+        usage();
+        process.exit(args.length === 0 ? 1 : 0);
+    }
+
+    const pluginName = args[0];
+    const idx = loadHarnessIndex();
+    const harnessFolder = idx.plugins[pluginName];
+    if (!harnessFolder) {
+        die(
+            `Unknown harness '${pluginName}'. Available: ${Object.keys(idx.plugins).join(', ') || '(none)'}`,
+        );
+    }
+
+    const bundledClaude = join(dataDir, 'harnesses', harnessFolder, 'CLAUDE.md');
+    if (!existsSync(bundledClaude)) {
+        die(`Bundled CLAUDE.md missing for harness '${harnessFolder}'. Rebuild package data.`);
+    }
+
+    const targetDir = process.cwd();
+    const pluginDir = join(targetDir, '.claude', 'plugins', pluginName);
+    const claudeMdDest = join(targetDir, 'CLAUDE.md');
+
+    console.log(`\nInstalling ${pluginName} (from harness/${harnessFolder}) 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}`);
+
+    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`);
+}
+
+main(process.argv.slice(2)).catch((e) => {
+    console.error(e?.stack || e);
+    process.exit(1);
+});

package/data/harness-index.json

@@ -0,0 +1,5 @@
+{
+    "plugins": {
+        "nurix-harness": "code"
+    }
+}

package/data/harnesses/code/CLAUDE.md

@@ -0,0 +1,181 @@
+# Agent Instructions
+
+This file defines how AI agents (Claude, GPT, etc.) should work on this project.
+
+---
+
+## Getting Started
+
+- Read **[`docs/README.md`](docs/README.md)** for documentation root (architecture, features, operations, history)
+- Read **[`docs/memory/`](docs/memory/)** for agent memory files (one per agent + `main.md` for shared project memory)
+- Ignore **[`README.md`](README.md)** — it's for human reference only
+- Check **[`package.json`](package.json)** for available scripts. **Detect the package manager from the lockfile** (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `package-lock.json` → npm) and use the matching command. Don't hardcode a specific manager.
+- Look at similar modules/files and follow existing patterns
+
+> **If you are a Claude agent** (for example, `claude-4.5-sonnet`) — other agents ignore:
+> Check **[`.claude/rules/`](.claude/rules/)** for specialized instructions (automatically loaded into memory)
+
+---
+
+## Workflows
+
+For new features or new systems, enter **Spec Mode** before Plan Mode.
+
+### Spec Mode → Plan Mode → Completion
+
+1. **Spec Mode**: Create or update a feature spec in `docs/features/{feature}.md` using the **Feature Documentation template** (Status: Draft) — see the documentation skill (`.claude/skills/documentation/references/templates.md`). Use the **`spec-mode`** agent (`.claude/agents/spec-mode.md`) for codebase research; its findings drop directly into the template's research-derived sections (Affected Modules, Conventions to Follow, Current Behavior, Ownership Conflicts). Interview the user for the design-intent sections (Goal, Goals & Non-Goals, Background, Approach). Present the spec for approval before proceeding.
+
+2. **Plan Mode**: Once the spec is approved, create a plan in `docs/history/plans/YYYY-MM-DD-feature-name.md` using the **Plan template**. Link back to the feature spec in the **Spec** field. The template's **Proposed Changes** subsections are load-bearing — the `introspect` skill parses them to check guardrail impact.
+
+3. **Completion**: When a plan is fully implemented:
+    - Mark the plan `Status: Complete` and fill the **Completed:** date. The plan is now frozen.
+    - **Flip the feature spec** to `Status: Active` and extend it in place with the implementation sections (Architecture, Key Functions, State, Redux, Files). Same file. Confirm `owns`/`touches` frontmatter against actual code; resolve any unresolved Open Questions by folding them into Background.
+    - If `docs/routing.md` exists, use it to find other docs affected by the changes; otherwise glob `docs/features/**/*.md` and check `owns`/`touches` frontmatter. Update affected docs — or create new ones if a touched area has no doc yet.
+    - Create a changelog entry in `docs/history/changelog/YYYY-MM-DD-feature-name.md`.
+
+`docs/features/` is _what_ we're building (lives on as documentation). `docs/history/plans/` is _how_ we built it (historical record).
+
+### Context Routing
+
+Before modifying code in an unfamiliar area:
+
+1. If **[`docs/routing.md`](docs/routing.md)** exists, read it for file-pattern → doc/agent mapping. If it doesn't exist yet, skip — the codebase may not have owned features.
+2. If **[`docs/OWNERSHIP_INDEX.md`](docs/OWNERSHIP_INDEX.md)** exists, check it for the owning feature doc and read that doc before making changes. If it doesn't exist, glob `docs/features/**/*.md` and check `owns` frontmatter directly.
+3. If a `docs/memory/` file exists for the domain you're working in, read it for domain knowledge and failure modes
+
+For the protocol on *writing* to memory, see **Project Memory** below.
+
+### Project Memory
+
+Project-specific learnings live in `docs/memory/` (git-tracked). Cross-project user preferences live in `~/.claude/` (untracked).
+
+| File | Owner | Contents |
+|------|-------|----------|
+| `docs/memory/main.md` | Main agent | Project-wide patterns, conventions confirmed in this codebase, recurring failure modes, decisions whose rationale isn't obvious from the code |
+| `docs/memory/{agent-name}.md` | The named sub-agent | Strategy memory for that agent — how to be more effective on this project. Never user-centric. |
+| `~/.claude/projects/...` | Auto-memory system | User preferences, role, communication style, cross-project habits |
+
+**Override the default auto-memory location for project-relevant facts.** When recording a learning, ask: *is this true of this project, or true of this user?* Project facts → `docs/memory/`. User facts → `~/.claude/`.
+
+`docs/memory/main.md` is scaffolded during baseline. Append entries dated `## YYYY-MM-DD — {topic}`; oldest at bottom is fine.
+
+### Out-of-Scope Discovery
+
+When implementing a plan, if you discover work that is important but outside the current plan's scope:
+
+- Append it to `docs/history/backlog.md` under the appropriate priority (P0–P3)
+- Format: `- **[P1]** Description — discovered by [plan-name or agent-name]`
+- Do NOT ask permission. Just append and mention it in your response.
+
+### Doc Ownership
+
+Feature docs in `docs/features/` must include YAML frontmatter with `owns`, `touches`, and `depends_on` fields. Architecture docs describe cross-cutting patterns and don't own specific files; operations docs describe procedures. Only feature docs need frontmatter.
+
+The spec-mode agent checks for ownership conflicts during research. If conflicts are found, address them in the spec before proceeding.
+
+---
+
+## Agents
+
+Seven sub-agents and three skills are defined under `.claude/`. Reach for them by name or by trigger phrase:
+
+| Component | Type | Use for | Trigger phrases |
+|-----------|------|---------|-----------------|
+| `spec-mode` | Agent | Codebase research before writing a feature spec | Invoked during Spec Mode |
+| `maintenance` | Agent | Periodic audit — fix docs drifting from code | "run maintenance", "audit docs", "check drift" |
+| `contract-monitor` | Agent | Post-implementation contract audit — scan code against guardrails | "check contracts", "audit guardrails", "code drift" |
+| `review` | Agent | Code health — bundle, performance, anti-patterns | "weekly review", "review code health", "check bundle" |
+| `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" |
+| `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" |
+
+### Guardrails
+
+`docs/operations/guardrails.md` documents **cascading failure boundaries** — places where editing one module silently breaks another (shared state shapes, entity registration checklists, cross-module string coupling, persistence rehydration, etc.). Two components depend on it:
+
+- **`contract-monitor`** (post-implementation) — scans code for violations of documented guardrails
+- **`introspect`** (pre-implementation) — checks a proposed plan against guardrails to surface cascading risk before coding
+
+To create or extend guardrails, invoke the `documentation` skill with "create guardrails" / "add guardrail". Without guardrails populated, `contract-monitor` and `introspect` are not useful.
+
+---
+
+## Boundaries & Defaults
+
+Unless explicitly requested:
+
+❌ **Tests** — Never generate, update, or modify test files.
+❌ **Dependencies** — Never upgrade frameworks, libraries, or dependencies.
+❌ **Compatibility** — Never maintain backward compatibility unless specified.
+❌ **Browser Automation** — Never use "Claude in Chrome" (CDP/MCP browser tools) unless the user explicitly requests it.
+❌ **Protected Files** — Never modify these read-only files:
+`AGENTS.md`, `docs/operations/protected-files.md`
+✅ **Documentation** — Keep `docs/` updated when code changes affect documented behavior.
+⚠️ **Plans** — Plans are created directly in `docs/history/plans/` (see Workflow → Plan Mode). Once `Status: Complete` or `Status: Abandoned`, the file is frozen — never edited. If scope changes after completion, write a new dated plan that links back to the old one.
+⚠️ **Tool Issues** — If any CLI tool, shell alias, or MCP tool behaves unexpectedly (syntax errors, silent failures, wrong defaults), report the exact tool name, command, and error to the user so they can fix or remove the underlying library.
+
+---
+
+## File Structure
+
+- Add file path at top of each file:
+  `// src/modules/example.js - Module for handling user authentication`
+- Add a 1-line function description as a comment above each function:
+  `// Extract JWT token from request based on endpoint type`
+- Keep related code together in a logical hierarchy.
+- No inline comments that restate obvious code. No commented-out code. If a block of code needs a comment to be understandable, refactor for clarity instead.
+
+---
+
+## Documentation
+
+- **[`docs/README.md`](docs/README.md)** — Documentation root (start here for all docs)
+- Only `CLAUDE.md`, `AGENTS.md`, and `README.md` are allowed in the repository root
+- One canonical source per topic — link, don't copy
+
+### Folder Structure
+
+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                |
+
+### 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
+- Memory: `{agent-name}.md` — agent-maintained
+
+### Documentation Maintenance
+
+- **Prerequisite**: Before creating changelogs, feature docs, or plans, check that `docs/memory/index.md` exists and records a baseline. If not, prompt the user to baseline docs first.
+- After plan completion: create a `docs/history/changelog/YYYY-MM-DD-feature-name.md` entry + update the index in `docs/history/CHANGELOG.md` (no confirmation needed).
+- Update related docs affected by the changes (use `docs/routing.md` to find the right files)
+- Non-plan changes (refactors, bug fixes, API changes): prompt user first
+- Multi-commit changes: include `Commits: abc1234, def5678`
+- Missing `docs/README.md`: create a documentation index
+
+### Keeping the Loop Tight
+
+When you create, move, or delete a doc:
+- If **[`docs/routing.md`](docs/routing.md)** exists, update it — file-pattern routes and keyword routes
+- Update **[`docs/README.md`](docs/README.md)** — add/remove the doc's entry
+- If creating a new top-level domain folder and routing.md exists: add the folder to routing.md's **Top-Level Folders** table
+
+When you move or rename source files:
+- Check `owns`/`touches` frontmatter in the owning doc. Find the owning doc via `docs/routing.md` or `docs/OWNERSHIP_INDEX.md` if either is present; otherwise glob `docs/features/**/*.md` and match against `owns` patterns. Update paths to match the new locations.
+
+When you create a new doc that owns code:
+- Add `owns`, `touches`, `depends_on` YAML frontmatter
+- Verify `owns` globs don't conflict with existing docs (check `docs/OWNERSHIP_INDEX.md` if present, otherwise compare against `owns` frontmatter across `docs/features/`)
+

package/package.json

@@ -0,0 +1,39 @@
+{
+    "name": "@nurix/etna",
+    "version": "0.1.1",
+    "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": {
+        "etna": "bin/etna.js"
+    },
+    "files": [
+        "bin/",
+        "data/",
+        "README.md"
+    ],
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "scripts": {
+        "build:data": "node scripts/build-data.js",
+        "prepack": "node scripts/build-data.js"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/nurixlabs/etna.git",
+        "directory": "packages/cli"
+    },
+    "homepage": "https://github.com/nurixlabs/etna/tree/dev/packages/cli",
+    "license": "UNLICENSED",
+    "publishConfig": {
+        "access": "restricted"
+    },
+    "keywords": [
+        "claude",
+        "claude-code",
+        "harness",
+        "nurix",
+        "agent",
+        "plugin"
+    ]
+}