@nusoft/nuos-build-catalogue 0.10.2 → 0.12.0

package/dist/commands/init.d.ts

@@ -5,8 +5,15 @@
  *   1. mkdir docs/build/ + copy starter-kit content
  *   2. Substitute {{PROJECT_NAME}} / {{PROJECT_TAGLINE}} / {{TODAY}} in
  *      STATE.md and methodfile.json
- *   3. Copy the four protocols into .claude/commands/ (preserving
- *      existing files)
+ *   3. Fan the four protocols out to ALL THREE supported AI coding tools:
+ *      Claude Code (.claude/commands/<n>.md), OpenCode
+ *      (.opencode/commands/<n>.md), and Codex CLI
+ *      (.agents/skills/<n>/SKILL.md). Each tool reads commands from a
+ *      different path with slightly different frontmatter; the body is
+ *      identical across all three. We write to all three by default — the
+ *      files are tiny and harmless if a tool is unused. A consumer of
+ *      this catalogue on any of the three tools gets working slash
+ *      commands without extra configuration.
  *   4. Append a "Build catalogue (NuOS Build Method)" section to
  *      CLAUDE.md (creating it if missing; preserving existing content)
  *   5. Update .gitignore: !docs/build/ override (if `build/` is present
@@ -16,7 +23,8 @@
  *   6. Run a first migrate to verify
  *
  * Companion command: `install-protocols` refreshes just step 3 from the
- * canonical bodies bundled in this CLI package.
+ * canonical bodies bundled in this CLI package, also fanning out to all
+ * three tool paths.
  */
 import type { Prompt } from './prompt.js';
 export interface InitOptions {

package/dist/commands/init.js

@@ -5,8 +5,15 @@
  *   1. mkdir docs/build/ + copy starter-kit content
  *   2. Substitute {{PROJECT_NAME}} / {{PROJECT_TAGLINE}} / {{TODAY}} in
  *      STATE.md and methodfile.json
- *   3. Copy the four protocols into .claude/commands/ (preserving
- *      existing files)
+ *   3. Fan the four protocols out to ALL THREE supported AI coding tools:
+ *      Claude Code (.claude/commands/<n>.md), OpenCode
+ *      (.opencode/commands/<n>.md), and Codex CLI
+ *      (.agents/skills/<n>/SKILL.md). Each tool reads commands from a
+ *      different path with slightly different frontmatter; the body is
+ *      identical across all three. We write to all three by default — the
+ *      files are tiny and harmless if a tool is unused. A consumer of
+ *      this catalogue on any of the three tools gets working slash
+ *      commands without extra configuration.
  *   4. Append a "Build catalogue (NuOS Build Method)" section to
  *      CLAUDE.md (creating it if missing; preserving existing content)
  *   5. Update .gitignore: !docs/build/ override (if `build/` is present
@@ -16,9 +23,10 @@
  *   6. Run a first migrate to verify
  *
  * Companion command: `install-protocols` refreshes just step 3 from the
- * canonical bodies bundled in this CLI package.
+ * canonical bodies bundled in this CLI package, also fanning out to all
+ * three tool paths.
  */
-import { mkdir, readFile, writeFile, copyFile, readdir, access } from 'node:fs/promises';
+import { mkdir, readFile, writeFile, readdir, access } from 'node:fs/promises';
 import { existsSync, constants } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -32,6 +40,41 @@ const PROTOCOL_FILES = [
     'wu-new.md',
     'persona-new.md',
 ];
+/**
+ * One-line descriptions used in the frontmatter of installed protocol
+ * files. Tools surface this text in their command list, so it should
+ * read as an imperative summary.
+ */
+const PROTOCOL_DESCRIPTIONS = {
+    'start-of-session': 'Read STATE, last session log, active WU; surface next action',
+    'end-of-session': 'Write session log, update STATE + indices, move ✅ WUs to done/, commit',
+    'wu-new': 'Create a new work unit with the six-field outcome shape (per D046)',
+    'persona-new': 'Create a new P-NNN persona with the seven dimensions and acid-test (per D046)',
+};
+const TOOLS = {
+    claude: {
+        label: 'Claude Code',
+        destPath: (slug) => path.join('.claude', 'commands', `${slug}.md`),
+        render: (slug, body) => withFrontmatter({ description: PROTOCOL_DESCRIPTIONS[slug] ?? '' }, body),
+    },
+    opencode: {
+        label: 'OpenCode',
+        destPath: (slug) => path.join('.opencode', 'commands', `${slug}.md`),
+        render: (slug, body) => withFrontmatter({ description: PROTOCOL_DESCRIPTIONS[slug] ?? '' }, body),
+    },
+    codex: {
+        label: 'Codex CLI',
+        destPath: (slug) => path.join('.agents', 'skills', slug, 'SKILL.md'),
+        render: (slug, body) => withFrontmatter({ name: slug, description: PROTOCOL_DESCRIPTIONS[slug] ?? '' }, body),
+    },
+};
+function withFrontmatter(fields, body) {
+    const lines = ['---'];
+    for (const [k, v] of Object.entries(fields))
+        lines.push(`${k}: ${v}`);
+    lines.push('---', '', '');
+    return lines.join('\n') + body;
+}
 export async function cmdInit(prompt, options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const today = new Date().toISOString().slice(0, 10);
@@ -107,14 +150,20 @@ export async function cmdInit(prompt, options = {}) {
     log_line('  · writing methodfile.json at repo root');
     const methodfileSrc = await readFile(path.join(TEMPLATES_ROOT, 'starter-kit', 'methodfile.json'), 'utf8');
     await writeFile(path.join(cwd, 'methodfile.json'), substitute(methodfileSrc, subs), 'utf8');
-    // Step 3: copy protocols into .claude/commands/
-    const claudeCommandsDir = path.join(cwd, '.claude', 'commands');
-    await mkdir(claudeCommandsDir, { recursive: true });
-    for (const protocol of PROTOCOL_FILES) {
-        const dest = path.join(claudeCommandsDir, protocol);
-        const existed = existsSync(dest);
-        await copyFile(path.join(TEMPLATES_ROOT, 'protocols', protocol), dest);
-        log_line(`  · ${existed ? 'overwrote' : 'installed'} .claude/commands/${protocol}`);
+    // Step 3: fan protocols out to all three supported AI coding tools.
+    // Each tool reads project-level commands from its own path; we install
+    // to all three by default so users on any of Claude Code / OpenCode /
+    // Codex CLI get working slash commands without extra configuration.
+    for (const protocolFile of PROTOCOL_FILES) {
+        const slug = path.basename(protocolFile, '.md');
+        const body = await readFile(path.join(TEMPLATES_ROOT, 'protocols', protocolFile), 'utf8');
+        for (const tool of Object.values(TOOLS)) {
+            const dest = path.join(cwd, tool.destPath(slug));
+            const existed = existsSync(dest);
+            await mkdir(path.dirname(dest), { recursive: true });
+            await writeFile(dest, tool.render(slug, body), 'utf8');
+            log_line(`  · ${existed ? 'overwrote' : 'installed'} ${tool.destPath(slug)} (${tool.label})`);
+        }
     }
     // Step 4: CLAUDE.md
     const claudeMdPath = path.join(cwd, 'CLAUDE.md');
@@ -159,26 +208,26 @@ export async function cmdInstallProtocols(prompt, options = {}) {
             exitCode: 1,
         };
     }
-    const claudeCommandsDir = path.join(cwd, '.claude', 'commands');
-    await mkdir(claudeCommandsDir, { recursive: true });
     const lines = [];
-    for (const protocol of PROTOCOL_FILES) {
-        const src = path.join(TEMPLATES_ROOT, 'protocols', protocol);
-        const dest = path.join(claudeCommandsDir, protocol);
-        let action = 'created';
-        if (existsSync(dest)) {
-            const [srcContent, destContent] = await Promise.all([
-                readFile(src, 'utf8'),
-                readFile(dest, 'utf8'),
-            ]);
-            action = srcContent === destContent ? 'unchanged' : 'updated';
-        }
-        if (action !== 'unchanged') {
-            await copyFile(src, dest);
+    for (const protocolFile of PROTOCOL_FILES) {
+        const slug = path.basename(protocolFile, '.md');
+        const body = await readFile(path.join(TEMPLATES_ROOT, 'protocols', protocolFile), 'utf8');
+        for (const tool of Object.values(TOOLS)) {
+            const dest = path.join(cwd, tool.destPath(slug));
+            const rendered = tool.render(slug, body);
+            let action = 'created';
+            if (existsSync(dest)) {
+                const destContent = await readFile(dest, 'utf8');
+                action = destContent === rendered ? 'unchanged' : 'updated';
+            }
+            if (action !== 'unchanged') {
+                await mkdir(path.dirname(dest), { recursive: true });
+                await writeFile(dest, rendered, 'utf8');
+            }
+            lines.push(`  ${action.padEnd(10)} ${tool.destPath(slug)}`);
         }
-        lines.push(`  ${action.padEnd(10)} .claude/commands/${protocol}`);
     }
-    prompt.print(`Refreshing protocols at ${claudeCommandsDir}:`);
+    prompt.print(`Refreshing protocols (Claude Code / OpenCode / Codex CLI):`);
     for (const l of lines)
         prompt.print(l);
     return { output: '', exitCode: 0 };

package/dist/embedder/ollama.d.ts

@@ -1,10 +1,16 @@
 /**
  * Ollama embedder — local inference, no network egress.
  *
- * Default model: qwen3-embedding:8b (4096 dims, 32k context). Config via
- * NUOS_CATALOGUE_OLLAMA_MODEL. Smaller variants (qwen3-embedding:4b,
- * qwen3-embedding:0.6b) work the same way; switching variants requires
- * a full reindex if the dimension changes.
+ * Default model: qwen3-embedding:0.6b (1024 dims). Picked as default
+ * because it runs on the broad majority of developer machines without
+ * meaningful CPU strain — the prior 8b default produced noticeable load
+ * on Apple Silicon during a catalogue reindex, and the build harness
+ * ships to projects whose maintainers won't necessarily have an
+ * M-series Mac. Higher-fidelity variants (qwen3-embedding:4b at 2560
+ * dims, qwen3-embedding:8b at 4096 dims) are available via
+ * NUOS_CATALOGUE_OLLAMA_MODEL when the user wants better recall and
+ * has the headroom. Switching variants requires a full reindex because
+ * dimensions change.
  *
  * Why local: keeps the catalogue's content (and any future workload that
  * uses the same Embedder interface) inside whatever boundary Ollama is
@@ -26,10 +32,10 @@
  * idle-timeout (the keep_alive: "1m" we sent) cleans up within a
  * minute.
  *
- * Sizing note — the 8b model at Q4_K_M is ~4.7GB on disk and benefits
- * from ~16GB of RAM. Apple Silicon Metal acceleration helps a lot. On
- * smaller boxes drop to qwen3-embedding:4b (better accuracy/RAM ratio)
- * or qwen3-embedding:0.6b (CPU-only friendly).
+ * Sizing note — the new 0.6b default is ~600MB on disk and runs
+ * comfortably on any modern laptop, including CPU-only. The 4b variant
+ * (~2.5GB) and 8b variant (~4.7GB, benefits from ~16GB RAM + Metal)
+ * are upgrades for users who want better recall and have the headroom.
  */
 import type { Embedder } from './types.js';
 export declare class OllamaEmbedder implements Embedder {

package/dist/embedder/ollama.js

@@ -1,10 +1,16 @@
 /**
  * Ollama embedder — local inference, no network egress.
  *
- * Default model: qwen3-embedding:8b (4096 dims, 32k context). Config via
- * NUOS_CATALOGUE_OLLAMA_MODEL. Smaller variants (qwen3-embedding:4b,
- * qwen3-embedding:0.6b) work the same way; switching variants requires
- * a full reindex if the dimension changes.
+ * Default model: qwen3-embedding:0.6b (1024 dims). Picked as default
+ * because it runs on the broad majority of developer machines without
+ * meaningful CPU strain — the prior 8b default produced noticeable load
+ * on Apple Silicon during a catalogue reindex, and the build harness
+ * ships to projects whose maintainers won't necessarily have an
+ * M-series Mac. Higher-fidelity variants (qwen3-embedding:4b at 2560
+ * dims, qwen3-embedding:8b at 4096 dims) are available via
+ * NUOS_CATALOGUE_OLLAMA_MODEL when the user wants better recall and
+ * has the headroom. Switching variants requires a full reindex because
+ * dimensions change.
  *
  * Why local: keeps the catalogue's content (and any future workload that
  * uses the same Embedder interface) inside whatever boundary Ollama is
@@ -26,12 +32,12 @@
  * idle-timeout (the keep_alive: "1m" we sent) cleans up within a
  * minute.
  *
- * Sizing note — the 8b model at Q4_K_M is ~4.7GB on disk and benefits
- * from ~16GB of RAM. Apple Silicon Metal acceleration helps a lot. On
- * smaller boxes drop to qwen3-embedding:4b (better accuracy/RAM ratio)
- * or qwen3-embedding:0.6b (CPU-only friendly).
+ * Sizing note — the new 0.6b default is ~600MB on disk and runs
+ * comfortably on any modern laptop, including CPU-only. The 4b variant
+ * (~2.5GB) and 8b variant (~4.7GB, benefits from ~16GB RAM + Metal)
+ * are upgrades for users who want better recall and have the headroom.
  */
-const DEFAULT_MODEL = 'qwen3-embedding:8b';
+const DEFAULT_MODEL = 'qwen3-embedding:0.6b';
 const DEFAULT_HOST = 'http://localhost:11434';
 // Qwen3-Embedding produces Matryoshka representations 32–4096 dims.
 // We use the model default. A future tweak could truncate to e.g. 1024

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nusoft/nuos-build-catalogue",
-  "version": "0.10.2",
+  "version": "0.12.0",
   "description": "NuOS build-catalogue tooling: semantic search (WU 110) + migration runner that lifts markdown artefacts into JSON-backed workflow records (WU 111, Phase G).",
   "type": "module",
   "bin": {