@inkobytes/nexus 1.0.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@inkobytes/nexus",
+  "version": "1.0.0",
+  "description": "Multi-agent coordination CLI for coding agents sharing a local repository",
+  "type": "module",
+  "bin": {
+    "nexus": "bin/nexus.js"
+  },
+  "scripts": {
+    "test": "node --test test/**/*.test.js"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "multi-agent",
+    "coordination",
+    "swarm",
+    "cli",
+    "claude",
+    "codex",
+    "gemini",
+    "git"
+  ],
+  "author": "Carmelyne Thompson <carmelyne@inkobytes.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/carmelyne/inkobytes-nexus.git"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "drills/",
+    "skills/",
+    "nexus-dashboard/",
+    "LICENSE",
+    "README.md"
+  ]
+}

package/skills/nexus/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: nexus
+description: Use in repos coordinated by the Nexus CLI, especially when _NEXUS_CONSTITUTION.md, _NEXUS_QUEUE.md, _NEXUS_STANDUP.md, or .nexus/ exists, or when the user asks about Nexus start/claim/release/doctor/status/next.
+---
+
+# Nexus
+
+Nexus CLI is the coordination engine. This skill is only the agent playbook.
+
+## Loop
+
+1. Run `nexus start`; set `NEXUS_AGENT` for your CLI, or pass `--agent @agy|@claude|@codex|@gemini`. Start is orientation only, not permission to edit.
+2. Read `USER.md` if present for local user preferences.
+3. Read continuity and latest memory when present.
+4. Read `_NEXUS_QUEUE.md` and `_NEXUS_STANDUP.md`.
+5. Choose user-assigned work or `nexus next @Agent`; do not free-roam into `Auto-flow: no`.
+6. Claim exact shared files before reading/editing:
+
+   ```bash
+   nexus claim <path> @Agent "intent"
+   ```
+
+7. Treat claim output as current file state. Ignore cached file memory when contents matter.
+8. Work only inside the claimed surface and run focused validation.
+9. If the user wants a commit, release through Nexus:
+
+   ```bash
+   nexus release <path> "short commit message"
+   ```
+
+## Queue Items
+
+When adding work to `_NEXUS_QUEUE.md`, keep tasks dashboard-parseable and immediately actionable. Use this shape:
+
+```md
+- [ ] TASK/@agent: Short task title
+  - Id: stable-kebab-id
+  - Epic: Product area or safety theme
+  - Status: Ready
+  - Depends on: none
+  - Files: path/one.js, path/two.md
+  - Affinity: cli, docs, dashboard
+  - Cost: small
+  - Auto-flow: yes
+  - Notes: One practical paragraph with scope, constraints, and definition of done.
+```
+
+- `Files` should name the likely edit surface so other agents can spot conflicts before claiming.
+- `Depends on` should list hard blockers by `Id`; use `none` when the task is independent.
+- `Auto-flow: yes` means an agent can grab it after `nexus next`; use `no` when planning or human approval is needed.
+- `Notes` should carry dashboard-useful context, not a whole design doc.
+
+## Guardrails
+
+- Ask before `nexus doctor --fix` unless scaffold repair is already approved.
+- Use `nexus doctor` for audit/repair, not as the normal startup command.
+- Use CLI/model names as lock handles: `@agy`, `@claude`, `@codex`, `@gemini`.
+- Agent-local continuity and memory files are claim-exempt unless the user says otherwise.
+- When using subagents or parallel workers, the lead agent owns the repo effects: claim the full path scope, pass boundaries down, re-read affected files, and mention delegated work in release or standup notes.
+- Avoid parallel `nexus release`.
+- Do not install packages younger than 14 days; if age is unknown, ask.
+- Use `nexus status`, `nexus clean --stale`, or surgical `nexus clean <path>` for lock recovery. Never nuke all locks without explicit approval.

package/src/commands/checkin.js

@@ -0,0 +1,19 @@
+/**
+ * nexus checkin @agent — signal agent presence
+ */
+
+import { writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { env, cwd } from 'process';
+
+export default function checkin(args = []) {
+  const root = cwd();
+  const agent = args[0] || env.NEXUS_AGENT || '@unknown';
+  const presenceDir = join(root, '.nexus', 'presence');
+  const presenceFile = join(presenceDir, agent.replace(/^@/, ''));
+
+  mkdirSync(presenceDir, { recursive: true });
+  writeFileSync(presenceFile, String(Math.floor(Date.now() / 1000)), 'utf-8');
+
+  console.log(`[CHECKIN] ${agent} is active.`);
+}

package/src/commands/checkout.js

@@ -0,0 +1,33 @@
+/**
+ * nexus checkout @agent — signal agent session end
+ */
+
+import { unlinkSync, existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { env, cwd } from 'process';
+
+export default function checkout(args = []) {
+  const root = cwd();
+  const presenceDir = join(root, '.nexus', 'presence');
+  const all = args.includes('--all');
+
+  if (all) {
+    if (existsSync(presenceDir)) {
+      for (const file of readdirSync(presenceDir)) {
+        unlinkSync(join(presenceDir, file));
+      }
+      console.log(`[CHECKOUT] All agent presence cleared.`);
+    }
+    return;
+  }
+
+  const agent = args[0] || env.NEXUS_AGENT || '@unknown';
+  const presenceFile = join(presenceDir, agent.replace(/^@/, ''));
+
+  if (existsSync(presenceFile)) {
+    unlinkSync(presenceFile);
+    console.log(`[CHECKOUT] ${agent} is offline.`);
+  } else {
+    console.log(`[CHECKOUT] No presence record for ${agent}.`);
+  }
+}

package/src/commands/chmod.js

@@ -0,0 +1,93 @@
+/**
+ * nexus chmod — manage the promptCHMOD permission matrix.
+ * Human-controlled only: blocks unverified sessions from editing.
+ *
+ * r = read for reference
+ * w = modify (claim/release already enforces this)
+ * x = treat as authoritative instructions (the injection surface)
+ */
+
+import { DEFAULT_MATRIX, loadPermissions, getChmodPath } from '../lib/permissions.js';
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+
+const VALID_PERMS = /^[r-][w-][x-]$/;
+
+export default function chmod(args) {
+  const chmodPath = getChmodPath();
+
+  if (args.includes('--init')) {
+    if (existsSync(chmodPath)) {
+      console.log('[INFO] _NEXUS_CHMOD.md already exists. Use --list to inspect or edit directly.');
+      return;
+    }
+    writeFileSync(chmodPath, DEFAULT_MATRIX, 'utf-8');
+    console.log('[OK] Created _NEXUS_CHMOD.md with default permission matrix.');
+    return;
+  }
+
+  if (args.length === 0 || args.includes('--list')) {
+    if (!existsSync(chmodPath)) {
+      console.log('[WARN] No _NEXUS_CHMOD.md found. Run `nexus chmod --init` to create defaults.');
+      return;
+    }
+    const entries = loadPermissions();
+    if (!entries.length) {
+      console.log('No permissions defined.');
+      return;
+    }
+    console.log('\npromptCHMOD — permission matrix\n');
+    console.log('  ' + 'PATH'.padEnd(36) + 'PERMS  AGENT         NOTE');
+    console.log('  ' + '─'.repeat(72));
+    for (const e of entries) {
+      const note = e.perms[2] === 'x' ? 'authoritative' : 'reference only';
+      console.log('  ' + e.path.padEnd(36) + e.perms + '   ' + e.agent.padEnd(14) + note);
+    }
+    console.log('');
+    return;
+  }
+
+  // nexus chmod <path> <perms> [agent]
+  const positional = args.filter(a => !a.startsWith('--'));
+  const [target, perms, agent = 'all'] = positional;
+
+  if (!target || !perms) {
+    console.error('Usage: nexus chmod <path> <perms> [agent]\n  e.g. nexus chmod USER.md r-x all\nFlags: --list, --init');
+    process.exit(1);
+  }
+  if (!VALID_PERMS.test(perms)) {
+    console.error('[ERROR] perms must be 3 chars: [r-][w-][x-]  e.g. r--, rw-, r-x, rwx');
+    process.exit(1);
+  }
+
+  // Human-only gate — ties into agent-identity trust detection
+  const trustSource = process.env.CLAUDECODE === '1' ? 'harness'
+    : process.env.NEXUS_AGENT ? 'operator'
+    : 'unverified';
+  if (trustSource === 'unverified') {
+    console.error('[ERROR] nexus chmod requires a verified session (CLAUDECODE=1 or NEXUS_AGENT set).\nThe permission matrix is human-controlled — agents cannot self-elevate.');
+    process.exit(1);
+  }
+
+  const content = existsSync(chmodPath) ? readFileSync(chmodPath, 'utf-8') : DEFAULT_MATRIX;
+  const lines = content.split('\n');
+  const agentNorm  = agent.toLowerCase();
+  const targetNorm = target.replace(/^\.\//, '');
+
+  let found = false;
+  const newLines = lines.map(line => {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) return line;
+    const parts = trimmed.split(/\s+/);
+    if (parts[0] === targetNorm && (parts[2] || 'all').toLowerCase() === agentNorm) {
+      found = true;
+      return targetNorm.padEnd(36) + perms + '   ' + agentNorm;
+    }
+    return line;
+  });
+
+  if (!found) newLines.push(targetNorm.padEnd(36) + perms + '   ' + agentNorm);
+  writeFileSync(chmodPath, newLines.join('\n'), 'utf-8');
+
+  const note = perms[2] === 'x' ? 'authoritative (x-on)' : 'reference only (x-off)';
+  console.log(`[OK] ${targetNorm} → ${perms} for ${agentNorm} — ${note}`);
+}

package/src/commands/claim.js

@@ -0,0 +1,122 @@
+/**
+ * nexus claim <path> <agent> "<intent>"
+ * Lock a file or directory, update blackboard, dump fresh state.
+ */
+
+import { appendEntry } from '../lib/blackboard.js';
+import { acquireLock } from '../lib/lockManager.js';
+import { dumpState } from '../lib/dump.js';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { cwd } from 'process';
+import { normalizeTarget } from '../lib/pathSafety.js';
+import { CANONICAL_MODEL_HANDLE_SET, CANONICAL_MODEL_HANDLES_TEXT, hasAgentAlias } from '../lib/agentScopes.js';
+
+const CORE_FILES = [
+  '_NEXUS_CONSTITUTION.md',
+  '_NEXUS_QUEUE.md',
+  '_NEXUS_STANDUP.md',
+];
+const THINKING_LEVELS = new Set(['low', 'medium', 'high']);
+
+function missingCoreFiles() {
+  const root = cwd();
+  return CORE_FILES.filter((file) => !existsSync(join(root, file)));
+}
+
+function shouldWarnAgentHandle(agent) {
+  const normalized = agent.toLowerCase();
+  return normalized === '@agent'
+    || normalized === 'unknownagent'
+    || (normalized.startsWith('@') && !CANONICAL_MODEL_HANDLE_SET.has(normalized) && hasAgentAlias(normalized));
+}
+
+function isAgentHandle(agent) {
+  return typeof agent === 'string' && /^@[a-z0-9][a-z0-9_-]*$/i.test(agent);
+}
+
+function readFlag(args, name) {
+  const index = args.indexOf(name);
+  if (index === -1) return '';
+
+  const value = args[index + 1];
+  const hasValue = value && !String(value).startsWith('--');
+  args.splice(index, hasValue ? 2 : 1);
+  return hasValue ? value : '';
+}
+
+export default function claim(args) {
+  const positional = [...args];
+
+  const agentFlag = readFlag(positional, '--agent').trim();
+  const intentFlag = readFlag(positional, '--intent').trim();
+  const subagents = parseInt(readFlag(positional, '--subagents'), 10) || 0;
+  const model = readFlag(positional, '--model').trim();
+  const thinking = readFlag(positional, '--thinking').trim().toLowerCase();
+
+  let target = positional[0];
+  const agent = agentFlag || positional[1] || '';
+  const intent = intentFlag || positional[2] || '';
+  const hasAgent = Boolean(agentFlag || positional[1]);
+  const hasIntent = Boolean(intentFlag || positional[2]);
+
+  if (!target) {
+    console.error('Usage: nexus claim <filepath_or_dir> <agent> "<intent>" [--agent <agent>] [--intent <intent>] [--subagents <n>] [--model <name>] [--thinking <low|medium|high>]');
+    process.exit(1);
+  }
+
+  if (!hasAgent || !isAgentHandle(agent)) {
+    console.error('[ERROR] Missing or invalid claim agent.');
+    console.error('Use: nexus claim <path> @codex "intent"');
+    console.error('Or:  nexus claim <path> --agent @codex --intent "intent"');
+    process.exit(1);
+  }
+
+  if (!hasIntent) {
+    console.error('[ERROR] Missing claim intent.');
+    console.error('Use: nexus claim <path> @codex "intent"');
+    console.error('Or:  nexus claim <path> --agent @codex --intent "intent"');
+    process.exit(1);
+  }
+
+  if (thinking && !THINKING_LEVELS.has(thinking)) {
+    console.error('[ERROR] --thinking must be one of: low, medium, high');
+    process.exit(1);
+  }
+
+  try {
+    target = normalizeTarget(target);
+  } catch (err) {
+    console.error(`[ERROR] ${err.message}`);
+    process.exit(1);
+  }
+
+  const result = acquireLock(target, agent, intent, subagents, { model, thinking });
+
+  if (!result.success) {
+    console.error(`[ERROR] ${result.message}`);
+    process.exit(1);
+  }
+
+  const missing = missingCoreFiles();
+  if (missing.length) {
+    console.warn(`[WARN] Missing Nexus protocol files: ${missing.join(', ')}. Run \`nexus doctor\`.`);
+  }
+
+  if (!CANONICAL_MODEL_HANDLE_SET.has(agent.toLowerCase()) && shouldWarnAgentHandle(agent)) {
+    console.warn(`[WARN] Use CLI/model names as lock handles: ${CANONICAL_MODEL_HANDLES_TEXT}.`);
+  }
+
+  if (!model) {
+    console.warn('[WARN] Claim has no model metadata. Add `--model <name>` when available.');
+  }
+
+  // Update blackboard
+  appendEntry(`- 🔒 **${target}** - Locked by **${agent}**: ${intent}`);
+
+  console.log(result.message);
+
+  // Dump fresh file state
+  const state = dumpState(target);
+  console.log(state);
+}

package/src/commands/clean.js

@@ -0,0 +1,76 @@
+/**
+ * nexus clean [--stale | <path>]
+ * Surgical, stale, or nuke lock cleanup.
+ */
+
+import { removeEntry, clearBoard } from '../lib/blackboard.js';
+import { releaseLock, breakStaleLocks, nukeAllLocks, getLockPath } from '../lib/lockManager.js';
+import { existsSync } from 'fs';
+import { createInterface } from 'readline';
+import { normalizeTarget } from '../lib/pathSafety.js';
+
+export default async function clean(args) {
+  const mode = args[0];
+
+  // Mode: stale — prune expired locks
+  if (mode === '--stale') {
+    const broken = breakStaleLocks();
+
+    if (broken.length === 0) {
+      console.log('No stale locks found.');
+      return;
+    }
+
+    for (const { target, age } of broken) {
+      removeEntry(`🔒 **${target}**`);
+      console.log(`🩺 [STALE CLEAN] Unlocked: ${target} (${age}s old)`);
+    }
+    return;
+  }
+
+  // Mode: surgical — clean specific file/dir
+  if (mode && mode !== '--nuke') {
+    let target;
+    try {
+      target = normalizeTarget(mode);
+    } catch (err) {
+      console.error(`[ERROR] ${err.message}`);
+      process.exit(1);
+    }
+
+    const lockPath = getLockPath(target);
+
+    if (existsSync(lockPath)) {
+      releaseLock(target);
+      removeEntry(`🔒 **${target}**`);
+      console.log(`🩺 [SURGICAL CLEAN] Unlocked: ${target}`);
+    } else {
+      console.log(`No lock found for: ${target}`);
+    }
+    return;
+  }
+
+  // Mode: nuke — clear everything (with confirmation)
+  const confirmed = await confirm('⚠️  NUKE ALL LOCKS? (y/N): ');
+
+  if (confirmed) {
+    nukeAllLocks();
+    clearBoard();
+    console.log('[SYSTEM] Cleared all locks.');
+  } else {
+    console.log('Cancelled.');
+  }
+}
+
+function confirm(prompt) {
+  return new Promise((resolve) => {
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    rl.question(prompt, (answer) => {
+      rl.close();
+      resolve(answer.toLowerCase() === 'y');
+    });
+  });
+}