@inkobytes/nexus 1.0.5 → 1.0.7

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.0.7 - 2026-06-06
+
+- Added `nexus install-skill` to install the bundled Nexus skill into `~/.agents/skills/nexus`.
+- Added `--target` and `--force` options for custom or refreshed skill installs, with a guard against broad overwrite targets.
+- Updated help, zsh completion, README docs, and regression coverage for the new skill installer command.
+
+## 1.0.6 - 2026-06-03
+
+- Extended Nexus protocol drift checks so `nexus doctor` now covers the bundled `skills/nexus/SKILL.md`.
+- Kept Nexus repo docs aligned with the agent-native release model while scoping root `README.md` doctor repair to the actual `@inkobytes/nexus` product repo.
+- Added regression coverage for Nexus-product README repair and for avoiding root README mutation in ordinary consumer repos.
+
 ## 1.0.5 - 2026-06-03
 
 - Reframed doctor-managed agent guides around agent-native, file-native release flow instead of human-oriented feature commit bundling.

package/README.md

@@ -71,6 +71,7 @@ Requires Node.js 18 or newer.
 
 - Colorized `nexus help` output for easier scanning in the terminal
 - Built-in `nexus completion zsh` support for shell completions
+- Bundled `nexus install-skill` support for installing the Nexus agent skill into `~/.agents/skills`
 
 See [CHANGELOG.md](./CHANGELOG.md) for the release summary.
 
@@ -240,6 +241,18 @@ source <(nexus completion zsh)
 
 This gives `zsh` tab-completion for commands like `claim`, `release`, `doctor`, `drill`, and common agent handles such as `@codex` and `@claude`.
 
+### `nexus install-skill [--target <path>] [--force]`
+
+Install the bundled Nexus agent skill into the shared agent skill directory.
+
+```bash
+nexus install-skill
+nexus install-skill --force
+nexus install-skill --target ~/.agents/skills/nexus
+```
+
+By default, Nexus copies `skills/nexus` from the published package into `~/.agents/skills/nexus`. Restart or refresh your agent session after installing so its skill registry can discover the new `nexus` skill.
+
 ### `nexus ledger [--json]`
 
 Show completed task entries from `_NEXUS_LEDGER.md`.
@@ -389,11 +402,13 @@ Nexus reads tasks from `_NEXUS_QUEUE.md`:
   - Affinity: cli, diagnostics
   - Cost: small
   - Auto-flow: yes
+  - Review: approved
+  - Approved by: human
   - Notes: Add a doctor section for stale locks with tests and clear fix guidance.
 ```
 
 The queue is the executable priority surface. Standup is for comms and human context.
-Keep items dashboard-friendly: include `Id`, `Epic`, `Status`, `Depends on`, `Files`, `Affinity`, `Cost`, `Auto-flow`, and `Notes`. Use `Files` to expose conflict surfaces, `Depends on` for hard blockers, and `Auto-flow: no` when a task needs planning or human approval before an agent grabs it.
+Keep items dashboard-friendly: include `Id`, `Epic`, `Status`, `Depends on`, `Files`, `Affinity`, `Cost`, `Auto-flow`, and `Notes`. Use `Files` to expose conflict surfaces, `Depends on` for hard blockers, and `Auto-flow: no` when a task needs planning or human approval before an agent grabs it. Auto-flow work in `Ready Queue` should also include `Review: approved` and `Approved by: human`, or `doctor` will flag it and `nexus next` may skip it.
 
 Add `Drills` when a task has known failure-mode guidance:
 
@@ -408,12 +423,13 @@ When `Drills` is absent, `nexus next` may surface obvious related drills from ta
 The agent rule of thumb:
 
 1. Run `nexus start` when entering an existing repo; it does not replace claim/release.
-2. Read `USER.md` when present.
-3. Read continuity and latest memory when present.
-4. Read `_NEXUS_QUEUE.md` before taking follow-on work.
-5. Claim before touching shared project files.
-6. Release when finished.
-7. Use `nexus next @Agent` instead of free-roaming.
+2. Read `_NEXUS_CONSTITUTION.md`.
+3. Read `USER.md` when present.
+4. Read continuity and latest memory when present.
+5. Read `_NEXUS_QUEUE.md` before taking follow-on work.
+6. Claim before touching shared project files.
+7. Release each claimed tracked file as soon as it reaches a coherent checkpoint.
+8. Use `nexus next @Agent` instead of free-roaming.
 
 Use model names as lock handles so ownership stays clear:
 
@@ -424,6 +440,8 @@ Use model names as lock handles so ownership stays clear:
 
 Agent-local continuity and memory files are exempt from claim/release unless the human says otherwise.
 
+Nexus is agent-native and file-native, not human-native: optimize for concurrency and rollback, not feature-commit aesthetics. Do not hold claims to bundle related work into prettier feature commits; that blocks other agents waiting on files.
+
 When a lead agent uses subagents, tools, or parallel workers, the lead still owns the repo effects. Claim the full path scope before delegating shared-file work, give subagents the claimed path and boundaries, re-read affected files before release, and mention delegated work when it changed files, tests, or risk.
 
 Supply-chain rule: agents should not install third-party packages that have existed for less than 14 days. If package age cannot be verified, stop and ask the human. `nexus doctor` also flags install hooks and package scripts that look like they could exfiltrate data.
@@ -445,7 +463,7 @@ Avoid introducing extra startup names in scripts or narration.
 
 Nexus ships an agent skill at `skills/nexus/SKILL.md`.
 
-The CLI is the coordination engine. The skill is the lean playbook for this flow: `start -> claim -> release`.
+The CLI is the coordination engine. The skill is the lean playbook for this flow: `start -> claim -> work -> release -> next`.
 
 ## Legacy Helper Transition
 

package/bin/nexus.js

@@ -20,12 +20,13 @@ const COMMANDS = {
   ledger: () => import('../src/commands/ledger.js'),
   drill: () => import('../src/commands/drill.js'),
   soul: () => import('../src/commands/soul.js'),
+  'install-skill': () => import('../src/commands/install-skill.js'),
   chmod: () => import('../src/commands/chmod.js'),
   db: () => import('../src/commands/db.js'),
   help: () => import('../src/commands/help.js'),
 };
 
-const VERSION = '1.0.1';
+const VERSION = '1.0.7';
 const COLORS = createColors();
 
 const args = argv.slice(2);
@@ -76,6 +77,7 @@ function printHelp() {
     ['db <backup|list|restore|schedule>', 'Database backup and recovery'],
     ['drill <list|show|run|report>', 'Inspect or run protocol drills'],
     ['soul [--file <path>] [--status | --remove]', 'Manage local soul overlay in agent files'],
+    ['install-skill [--target <path>] [--force]', 'Install bundled Nexus skill into ~/.agents/skills'],
     ['help', 'Show this help'],
   ];
 
@@ -89,6 +91,7 @@ function printHelp() {
     'nexus metrics --json',
     'nexus ledger backfill',
     'nexus drill show wrong-repo-push',
+    'nexus install-skill',
     'nexus claim src/lib/components/login/ @claude "Building login UI"',
     'nexus release src/lib/components/login/ "feat: login form component"',
     'nexus standup "2026-06-01 08:38 AM @codex [DONE]: Updated tests"',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inkobytes/nexus",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Multi-agent coordination CLI for coding agents sharing a local repository",
   "type": "module",
   "bin": {

package/skills/nexus/SKILL.md

@@ -10,24 +10,27 @@ 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:
+2. Read `_NEXUS_CONSTITUTION.md`.
+3. Read `USER.md` if present for local user preferences.
+4. Read continuity and latest memory when present.
+5. Read `_NEXUS_QUEUE.md` and `_NEXUS_STANDUP.md`.
+6. Choose user-assigned work or `nexus next @Agent`; do not free-roam into `Auto-flow: no`.
+7. 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:
+8. Treat claim output as current file state. Ignore cached file memory when contents matter.
+9. Work only inside the claimed surface and run focused validation.
+10. Release each claimed tracked file through Nexus as soon as it reaches a coherent checkpoint:
 
    ```bash
    nexus release <path> "short commit message"
    ```
 
+11. Do not hold claims to bundle related work into a prettier feature commit. Nexus is agent-native and file-native: optimize for file availability, rollback safety, and agent throughput.
+
 ## Queue Items
 
 When adding work to `_NEXUS_QUEUE.md`, keep tasks dashboard-parseable and immediately actionable. Use this shape:
@@ -42,12 +45,15 @@ When adding work to `_NEXUS_QUEUE.md`, keep tasks dashboard-parseable and immedi
   - Affinity: cli, docs, dashboard
   - Cost: small
   - Auto-flow: yes
+  - Review: approved
+  - Approved by: human
   - 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.
+- Auto-flow work in `Ready Queue` should include `Review: approved` and `Approved by: human`, or `doctor` will flag it and `nexus next` may skip it.
 - `Notes` should carry dashboard-useful context, not a whole design doc.
 
 ## Guardrails

package/src/commands/completion.js

@@ -54,6 +54,7 @@ commands=(
   'db:Database backup and recovery'
   'drill:Inspect or run protocol drills'
   'soul:Manage local soul overlay in agent files'
+  'install-skill:Install bundled Nexus skill into ~/.agents/skills'
   'help:Show command help'
 )
 
@@ -116,6 +117,9 @@ case $words[2] in
   soul)
     _arguments '--file[Overlay file path]:path:_files' '--status[Show status]' '--remove[Remove overlay]'
     ;;
+  install-skill)
+    _arguments '--target[Install target]:path:_files' '--force[Refresh existing installation]'
+    ;;
   start)
     _arguments '--agent[Agent handle]:agent:(@agy @claude @codex @gemini)'
     ;;

package/src/commands/doctor.js

@@ -352,6 +352,7 @@ export default function doctor(args) {
   const sections = {
     'Nexus Files': [],
     'Agent Instructions': [],
+    'Docs & Skills': [],
     Security: [],
     'Package Privacy': [],
     'Git Privacy': [],
@@ -513,6 +514,37 @@ export default function doctor(args) {
     }
   }
 
+  const protocolDocs = [];
+  if (isNexusProductRepo(root)) {
+    protocolDocs.push({
+      path: 'README.md',
+      label: 'README.md',
+      repair: repairReadmeProtocolDoc,
+    });
+  }
+  protocolDocs.push({
+    path: 'skills/nexus/SKILL.md',
+    label: 'skills/nexus/SKILL.md',
+    repair: repairNexusSkillDoc,
+  });
+
+  for (const doc of protocolDocs) {
+    const path = join(root, doc.path);
+    if (!existsSync(path)) continue;
+    const existing = readFileSync(path, 'utf-8');
+    const next = doc.repair(existing);
+    if (next === existing) continue;
+    if (fix) {
+      writeFileSync(path, next, 'utf-8');
+      changes.push(`updated ${doc.label}`);
+    } else {
+      sections['Docs & Skills'].push({
+        issue: `${doc.label} is out of sync with current Nexus protocol wording`,
+        fix: 'Run `nexus doctor --fix`.',
+      });
+    }
+  }
+
   const locks = listLocks();
   const staleLocks = locks.filter((lock) => lock.age !== null && lock.age >= config.staleThreshold);
   const freshLocks = locks.filter((lock) => lock.age === null || lock.age < config.staleThreshold);
@@ -947,6 +979,140 @@ function replaceLegacyHelperCommands(content) {
     .join('\n');
 }
 
+function isNexusProductRepo(root) {
+  const packagePath = join(root, 'package.json');
+  if (!existsSync(packagePath)) return false;
+
+  try {
+    const pkg = JSON.parse(readFileSync(packagePath, 'utf-8'));
+    return pkg?.name === '@inkobytes/nexus';
+  } catch {
+    return false;
+  }
+}
+
+function repairReadmeProtocolDoc(content) {
+  return content
+    .replace(
+      [
+        '- [ ] TASK/Codex: Add doctor stale-lock category',
+        '  - Id: doctor-stale-locks',
+        '  - Epic: Release hygiene',
+        '  - Status: Ready',
+        '  - Depends on: none',
+        '  - Files: src/commands/doctor.js',
+        '  - Affinity: cli, diagnostics',
+        '  - Cost: small',
+        '  - Auto-flow: yes',
+        '  - Notes: Add a doctor section for stale locks with tests and clear fix guidance.',
+      ].join('\n'),
+      [
+        '- [ ] TASK/Codex: Add doctor stale-lock category',
+        '  - Id: doctor-stale-locks',
+        '  - Epic: Release hygiene',
+        '  - Status: Ready',
+        '  - Depends on: none',
+        '  - Files: src/commands/doctor.js',
+        '  - Affinity: cli, diagnostics',
+        '  - Cost: small',
+        '  - Auto-flow: yes',
+        '  - Review: approved',
+        '  - Approved by: human',
+        '  - Notes: Add a doctor section for stale locks with tests and clear fix guidance.',
+      ].join('\n'),
+    )
+    .replace(
+      'Keep items dashboard-friendly: include `Id`, `Epic`, `Status`, `Depends on`, `Files`, `Affinity`, `Cost`, `Auto-flow`, and `Notes`. Use `Files` to expose conflict surfaces, `Depends on` for hard blockers, and `Auto-flow: no` when a task needs planning or human approval before an agent grabs it.',
+      'Keep items dashboard-friendly: include `Id`, `Epic`, `Status`, `Depends on`, `Files`, `Affinity`, `Cost`, `Auto-flow`, and `Notes`. Use `Files` to expose conflict surfaces, `Depends on` for hard blockers, and `Auto-flow: no` when a task needs planning or human approval before an agent grabs it. Auto-flow work in `Ready Queue` should also include `Review: approved` and `Approved by: human`, or `doctor` will flag it and `nexus next` may skip it.',
+    )
+    .replace(
+      [
+        '1. Run `nexus start` when entering an existing repo; it does not replace claim/release.',
+        '2. Read `USER.md` when present.',
+        '3. Read continuity and latest memory when present.',
+        '4. Read `_NEXUS_QUEUE.md` before taking follow-on work.',
+        '5. Claim before touching shared project files.',
+        '6. Release when finished.',
+        '7. Use `nexus next @Agent` instead of free-roaming.',
+      ].join('\n'),
+      [
+        '1. Run `nexus start` when entering an existing repo; it does not replace claim/release.',
+        '2. Read `_NEXUS_CONSTITUTION.md`.',
+        '3. Read `USER.md` when present.',
+        '4. Read continuity and latest memory when present.',
+        '5. Read `_NEXUS_QUEUE.md` before taking follow-on work.',
+        '6. Claim before touching shared project files.',
+        '7. Release each claimed tracked file as soon as it reaches a coherent checkpoint.',
+        '8. Use `nexus next @Agent` instead of free-roaming.',
+      ].join('\n'),
+    )
+    .replace(
+      'Agent-local continuity and memory files are exempt from claim/release unless the human says otherwise.',
+      'Agent-local continuity and memory files are exempt from claim/release unless the human says otherwise.\n\nNexus is agent-native and file-native, not human-native: optimize for concurrency and rollback, not feature-commit aesthetics. Do not hold claims to bundle related work into prettier feature commits; that blocks other agents waiting on files.',
+    )
+    .replace(
+      'The CLI is the coordination engine. The skill is the lean playbook for this flow: `start -> claim -> release`.',
+      'The CLI is the coordination engine. The skill is the lean playbook for this flow: `start -> claim -> work -> release -> next`.',
+    );
+}
+
+function repairNexusSkillDoc(content) {
+  return content
+    .replace(
+      [
+        '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:',
+      ].join('\n'),
+      [
+        '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 `_NEXUS_CONSTITUTION.md`.',
+        '3. Read `USER.md` if present for local user preferences.',
+        '4. Read continuity and latest memory when present.',
+        '5. Read `_NEXUS_QUEUE.md` and `_NEXUS_STANDUP.md`.',
+        '6. Choose user-assigned work or `nexus next @Agent`; do not free-roam into `Auto-flow: no`.',
+        '7. Claim exact shared files before reading/editing:',
+      ].join('\n'),
+    )
+    .replace(
+      [
+        '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:',
+      ].join('\n'),
+      [
+        '8. Treat claim output as current file state. Ignore cached file memory when contents matter.',
+        '9. Work only inside the claimed surface and run focused validation.',
+        '10. Release each claimed tracked file through Nexus as soon as it reaches a coherent checkpoint:',
+      ].join('\n'),
+    )
+    .replace(
+      '```\\n\\n## Queue Items',
+      '```\\n\\n11. Do not hold claims to bundle related work into a prettier feature commit. Nexus is agent-native and file-native: optimize for file availability, rollback safety, and agent throughput.\\n\\n## Queue Items',
+    )
+    .replace(
+      [
+        '  - Cost: small',
+        '  - Auto-flow: yes',
+        '  - Notes: One practical paragraph with scope, constraints, and definition of done.',
+      ].join('\n'),
+      [
+        '  - Cost: small',
+        '  - Auto-flow: yes',
+        '  - Review: approved',
+        '  - Approved by: human',
+        '  - Notes: One practical paragraph with scope, constraints, and definition of done.',
+      ].join('\n'),
+    )
+    .replace(
+      '- `Auto-flow: yes` means an agent can grab it after `nexus next`; use `no` when planning or human approval is needed.\n- `Notes` should carry dashboard-useful context, not a whole design doc.',
+      '- `Auto-flow: yes` means an agent can grab it after `nexus next`; use `no` when planning or human approval is needed.\n- Auto-flow work in `Ready Queue` should include `Review: approved` and `Approved by: human`, or `doctor` will flag it and `nexus next` may skip it.\n- `Notes` should carry dashboard-useful context, not a whole design doc.',
+    );
+}
+
 const SUSPICIOUS_SCRIPT_PATTERNS = [
   { pattern: /\b(curl|wget)\b/i, label: 'network download command' },
   { pattern: /\b(nc|netcat|ncat|socat)\b/i, label: 'raw network transfer command' },

package/src/commands/install-skill.js

@@ -0,0 +1,83 @@
+/**
+ * nexus install-skill - install the bundled Nexus agent skill
+ */
+
+import { cpSync, existsSync, mkdirSync, rmSync } from 'fs';
+import { basename, dirname, parse, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { homedir } from 'os';
+
+const COMMAND_USAGE = 'Usage: nexus install-skill [--target <path>] [--force]';
+const DEFAULT_TARGET = '~/.agents/skills/nexus';
+
+function parseArgs(args) {
+  let target = DEFAULT_TARGET;
+  let force = false;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--force') {
+      force = true;
+      continue;
+    }
+
+    if (arg === '--target') {
+      const value = args[index + 1];
+      if (!value || value.startsWith('--')) throw new Error(COMMAND_USAGE);
+      target = value;
+      index += 1;
+      continue;
+    }
+
+    throw new Error(COMMAND_USAGE);
+  }
+
+  return { target, force };
+}
+
+function expandHome(path) {
+  if (path === '~') return homedir();
+  if (path.startsWith('~/')) return resolve(homedir(), path.slice(2));
+  return resolve(path);
+}
+
+function packageRoot() {
+  return resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+}
+
+function assertSafeSkillTarget(destination) {
+  if (basename(destination) !== 'nexus') {
+    throw new Error('Install target must be the Nexus skill directory, for example ~/.agents/skills/nexus.');
+  }
+
+  if (destination === parse(destination).root || destination === homedir()) {
+    throw new Error('Install target is too broad.');
+  }
+}
+
+export default function installSkill(args) {
+  const { target, force } = parseArgs(args);
+  const source = resolve(packageRoot(), 'skills', 'nexus');
+  const destination = expandHome(target);
+
+  if (!existsSync(source)) {
+    throw new Error(`Bundled Nexus skill not found: ${source}`);
+  }
+
+  assertSafeSkillTarget(destination);
+
+  if (existsSync(destination)) {
+    if (!force) {
+      console.log(`Nexus skill already installed at ${destination}`);
+      console.log('Run `nexus install-skill --force` to refresh it.');
+      return;
+    }
+    rmSync(destination, { recursive: true, force: true });
+  }
+
+  mkdirSync(dirname(destination), { recursive: true });
+  cpSync(source, destination, { recursive: true });
+
+  console.log(`Installed Nexus skill to ${destination}`);
+  console.log('Restart or refresh your agent session so the skill registry can pick it up.');
+}