semantu-agents 1.3.1 → 1.4.0

package/README.md

@@ -23,33 +23,45 @@ For normal users, rerun:
 npx semantu-agents global
 ```
 
-For contributors with an editable checkout at `~/.agents-src`, run this from anywhere:
+For contributors with a registered editable checkout, run this from anywhere:
 
 ```bash
 npx semantu-agents update
 ```
 
-This updates `~/.agents-src/main`, syncs it to `~/.claude/skills` and `~/.agents/skills`, then restores your previous branch when possible. If `~/.agents-src` has uncommitted changes, commit or stash them first.
+This updates the registered checkout's `main` branch, repairs its global skill links, then restores your previous branch when possible. If the checkout has uncommitted changes, commit or stash them first.
+
+`update` requires a named Git branch. It refuses dirty checkouts and detached HEAD states.
 
 ## Contributing Skill Changes
 
-Install an editable source checkout:
+Register an existing editable checkout:
 
 ```bash
+cd /path/to/semantu-agents
 npx semantu-agents dev
 ```
 
-This clones or pulls `github.com:Semantu/agents` into `~/.agents-src`, installs a post-merge hook, and syncs that checkout globally.
+You can also provide the checkout explicitly:
+
+```bash
+npx semantu-agents dev /path/to/semantu-agents
+```
+
+Without a path, `dev` uses the current directory when it is the agents checkout, then a previously registered checkout, then `~/packages/semantu-agents`. It never clones another checkout.
+
+The resolved path is stored in `~/.config/semantu-agents/config.json`. Each package-managed skill in `~/.claude/skills` and `~/.agents/skills` is linked to that checkout, so edits are available globally immediately. Unrelated installed skills are preserved.
+
+Directory junctions are used on Windows; directory symlinks are used elsewhere.
 
-Dev mode requires repo access. If cloning fails, ask for access to the Semantu agents repo.
+Dev mode requires an existing checkout. Clone the repository separately first if needed.
 
 Make changes in the source checkout only:
 
 ```bash
-cd ~/.agents-src
+cd /path/to/semantu-agents
 git checkout -b my-change
 # edit skills/public/... or skills/private/...
-npm run sync
 git add .
 git commit -m "improve workflow skill"
 git push -u origin my-change
@@ -61,9 +73,9 @@ Do not edit these generated folders directly:
 - `~/.claude/skills`
 - `~/.agents/skills`
 
-They are overwritten by `semantu-agents global`, `semantu-agents sync`, and `semantu-agents update`.
+In normal global mode, package-managed skills are copied from npm. In development mode, they are links managed by `dev`, `sync`, and `update`; edit the registered checkout instead.
 
-The dev post-merge hook runs `node cli.mjs sync` after pulls, so merged changes are synced globally automatically.
+Running `semantu-agents global` exits development mode and clears the registered checkout. Run `dev [path]` again to restore live links.
 
 ## Project Setup
 

package/cli.mjs

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 
 import {execSync} from 'node:child_process';
-import {cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync} from 'node:fs';
+import {cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync} from 'node:fs';
 import {homedir} from 'node:os';
 import path from 'node:path';
 import {fileURLToPath} from 'node:url';
+import {directoryLinkType} from './lib/link-type.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const args = process.argv.slice(2);
@@ -38,15 +39,6 @@ function cloneOrPull(dir) {
   }
 }
 
-function cloneIfMissing(dir) {
-  if (existsSync(path.join(dir, '.git'))) {
-    console.log('Using existing editable agents repo at ~/.agents-src');
-  } else {
-    console.log('Cloning agents repo...');
-    run(`git clone ${skillsRepo} ${dir}`);
-  }
-}
-
 function globalTargets() {
   const home = homedir();
   return [
@@ -55,93 +47,155 @@ function globalTargets() {
   ];
 }
 
-function syncSkillsInto(skillsSource, targets) {
-  if (!existsSync(skillsSource)) return;
+function skillSources(sourceDir, includePrivate) {
+  const sources = new Map();
+  const roots = [path.join(sourceDir, 'skills', 'public')];
+  if (includePrivate) roots.push(path.join(sourceDir, 'skills', 'private'));
 
-  for (const dest of targets) {
-    mkdirSync(dest, {recursive: true});
-    cpSync(skillsSource, dest, {recursive: true});
+  for (const root of roots) {
+    if (!existsSync(root)) continue;
+    for (const name of readdirSync(root)) {
+      const source = path.join(root, name);
+      if (statSync(source).isDirectory()) sources.set(name, source);
+    }
   }
+
+  return sources;
 }
 
-function syncFromSource(sourceDir, label = 'source checkout', options = {}) {
+function installSkillsFromSource(sourceDir, label, options = {}) {
   const includePrivate = options.includePrivate ?? true;
+  const mode = options.mode ?? 'copy';
   const targets = globalTargets();
-  const publicSkills = path.join(sourceDir, 'skills', 'public');
-  const privateSkills = path.join(sourceDir, 'skills', 'private');
+  const sources = skillSources(sourceDir, includePrivate);
 
   for (const dest of targets) {
-    rmSync(dest, {recursive: true, force: true});
+    mkdirSync(dest, {recursive: true});
+    for (const [name, source] of sources) {
+      // Replace only skills managed by this package; preserve every other entry in the global directory.
+      const target = path.join(dest, name);
+      rmSync(target, {recursive: true, force: true});
+      if (mode === 'link') {
+        symlinkSync(source, target, directoryLinkType(process.platform));
+      } else {
+        cpSync(source, target, {recursive: true});
+      }
+    }
   }
 
-  syncSkillsInto(publicSkills, targets);
-  if (includePrivate) {
-    syncSkillsInto(privateSkills, targets);
+  console.log(`${mode === 'link' ? 'Linked' : 'Synced'} skills from ${label} -> ~/.claude/skills/ and ~/.agents/skills/`);
+}
+
+function devConfigPath() {
+  return path.join(homedir(), '.config', 'semantu-agents', 'config.json');
+}
+
+function readDevConfig() {
+  const configPath = devConfigPath();
+  if (!existsSync(configPath)) return null;
+  try {
+    return JSON.parse(readFileSync(configPath, 'utf8'));
+  } catch {
+    console.error(`Invalid development configuration: ${configPath}`);
+    console.error('Rerun `npx semantu-agents dev [path]` after removing or repairing this file.');
+    process.exit(1);
   }
+}
 
-  console.log(`Synced skills from ${label} -> ~/.claude/skills/ and ~/.agents/skills/`);
+function writeDevConfig(source) {
+  const configPath = devConfigPath();
+  mkdirSync(path.dirname(configPath), {recursive: true});
+  writeFileSync(configPath, `${JSON.stringify({source}, null, 2)}\n`);
 }
 
-function setupGlobal() {
-  syncFromSource(__dirname, 'npm package', {includePrivate: false});
-  console.log('\nDone. Public skills synced globally. Run `npx semantu-agents dev` to install an editable source checkout.');
+function clearDevConfig() {
+  rmSync(devConfigPath(), {force: true});
 }
 
-function installPostMergeHook(repoDir) {
-  const hooksDir = path.join(repoDir, '.git', 'hooks');
-  const hookPath = path.join(hooksDir, 'post-merge');
-  const hook = `#!/bin/sh
-[ "$SEMANTU_AGENTS_SKIP_HOOK_SYNC" = "1" ] && exit 0
-cd "$(git rev-parse --show-toplevel)" && node cli.mjs sync
-`;
-
-  mkdirSync(hooksDir, {recursive: true});
-  writeFileSync(hookPath, hook, {mode: 0o755});
-  console.log('Installed post-merge hook to sync global skills after pulls');
+function isAgentsCheckout(candidate) {
+  try {
+    const packageJson = JSON.parse(readFileSync(path.join(candidate, 'package.json'), 'utf8'));
+    return packageJson.name === 'semantu-agents' &&
+      existsSync(path.join(candidate, '.git')) &&
+      existsSync(path.join(candidate, 'skills', 'public'));
+  } catch {
+    return false;
+  }
 }
 
-function setupDev() {
-  const srcDir = path.join(homedir(), '.agents-src');
+function resolveDevSource(inputPath) {
+  if (inputPath) {
+    const resolved = path.resolve(inputPath);
+    if (isAgentsCheckout(resolved)) return realpathSync(resolved);
+    console.error(`Not an editable semantu-agents checkout: ${resolved}`);
+    process.exit(1);
+  }
+
+  const configured = readDevConfig()?.source;
+  const candidates = [
+    process.cwd(),
+    configured,
+    path.join(homedir(), 'packages', 'semantu-agents'),
+  ].filter(Boolean);
+
+  for (const candidate of candidates) {
+    const resolved = path.resolve(candidate);
+    if (isAgentsCheckout(resolved)) return realpathSync(resolved);
+  }
+
+  console.error('No editable semantu-agents checkout found.');
+  console.error('Run `npx semantu-agents dev /path/to/checkout` from an existing checkout.');
+  process.exit(1);
+}
 
-  cloneIfMissing(srcDir);
-  installPostMergeHook(srcDir);
-  syncFromSource(srcDir, '~/.agents-src');
+function setupGlobal() {
+  installSkillsFromSource(__dirname, 'npm package', {includePrivate: false});
+  clearDevConfig();
+  console.log('\nDone. Public skills synced globally. Run `npx semantu-agents dev [path]` to link an editable checkout.');
+}
 
-  console.log('\nDone. Edit skills in ~/.agents-src, run `node cli.mjs sync`, then commit and open a PR.');
+function setupDev(inputPath) {
+  const source = resolveDevSource(inputPath);
+  writeDevConfig(source);
+  installSkillsFromSource(source, source, {mode: 'link'});
+  console.log(`\nDone. Edit skills in ${source}; changes are available globally immediately.`);
 }
 
 function syncGlobalFromCurrentCheckout() {
-  syncFromSource(__dirname, 'current checkout');
+  setupDev(__dirname);
 }
 
 function updateDevCheckout() {
-  const srcDir = path.join(homedir(), '.agents-src');
-
-  if (!existsSync(path.join(srcDir, '.git'))) {
-    console.log('No editable checkout found at ~/.agents-src.');
-    console.log('Run `npx semantu-agents dev` if you have access to github.com:Semantu/agents.');
+  const source = readDevConfig()?.source;
+  if (!source || !isAgentsCheckout(source)) {
+    console.log('No registered editable checkout found.');
+    console.log('Run `npx semantu-agents dev [path]` from an existing checkout.');
     process.exit(1);
   }
 
-  const currentBranch = output('git branch --show-current', {cwd: srcDir});
-  const dirty = output('git status --porcelain', {cwd: srcDir});
+  const currentBranch = output('git branch --show-current', {cwd: source});
+  if (!currentBranch) {
+    console.log(`Cannot update ${source} from a detached HEAD.`);
+    console.log('Switch to a named branch, then rerun `npx semantu-agents update`.');
+    process.exit(1);
+  }
+  const dirty = output('git status --porcelain', {cwd: source});
 
   if (dirty) {
-    console.log('Cannot update ~/.agents-src because it has uncommitted changes.');
+    console.log(`Cannot update ${source} because it has uncommitted changes.`);
     console.log('Commit, stash, or discard them, then rerun `npx semantu-agents update`.');
     process.exit(1);
   }
 
-  run('git fetch origin main', {cwd: srcDir});
-  run('git switch main', {cwd: srcDir});
-  run('git pull --ff-only origin main', {
-    cwd: srcDir,
-    env: {...process.env, SEMANTU_AGENTS_SKIP_HOOK_SYNC: '1'},
-  });
-  syncFromSource(srcDir, '~/.agents-src');
-
-  if (currentBranch && currentBranch !== 'main') {
-    run(`git switch ${currentBranch}`, {cwd: srcDir});
+  run('git fetch origin main', {cwd: source});
+  try {
+    if (currentBranch !== 'main') run('git switch main', {cwd: source});
+    run('git pull --ff-only origin main', {cwd: source});
+    installSkillsFromSource(source, source, {mode: 'link'});
+  } finally {
+    if (currentBranch && currentBranch !== 'main') {
+      run(`git switch ${currentBranch}`, {cwd: source});
+    }
   }
 }
 
@@ -403,7 +457,7 @@ if (command === 'docs') {
 } else if (command === 'global' || isGlobal) {
   setupGlobal();
 } else if (command === 'dev') {
-  setupDev();
+  setupDev(args[1]);
 } else if (command === 'sync') {
   syncGlobalFromCurrentCheckout();
 } else if (command === 'update') {

package/lib/link-type.mjs

@@ -0,0 +1,3 @@
+export function directoryLinkType(platform) {
+  return platform === 'win32' ? 'junction' : 'dir';
+}

package/package.json

@@ -1,22 +1,25 @@
 {
   "name": "semantu-agents",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Reusable Claude Code skills and hooks for Semantu projects",
   "type": "module",
   "bin": "cli.mjs",
   "files": [
     "cli.mjs",
+    "lib",
     "skills/public"
   ],
   "scripts": {
-    "sync": "node cli.mjs sync"
+    "sync": "node cli.mjs sync",
+    "test": "node --test test/*.test.mjs"
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.5.2",
-    "@changesets/cli": "^2.29.8"
+    "@changesets/cli": "^2.29.8",
+    "js-yaml": "^4.3.2"
   },
   "dependencies": {
     "gray-matter": "^4.0.3"

package/skills/public/explore/SKILL.md

@@ -19,8 +19,8 @@ Run this skill when the user explicitly says `explore <topic>`, clearly asks to
 2. Decompose the topic into decision candidates and unknowns.
 3. Prioritize planning blockers first when called from ideation or review iteration.
 4. Before presenting options, explain the affected area, current behavior, wider context, and why the decision matters. Assume the user may not know the implementation. Include code, before/after, or concrete examples when useful.
-5. Present exactly 3 viable approaches (A–C), each with pros, cons, and risks.
-6. After all options, add a separate **Recommendation** section naming the suggested option and why it is the best fit.
+5. Present exactly 3 viable approaches (A–C), each with pros, cons, and risks. Mark the suggested option in its heading with **(Recommended)**.
+6. Immediately after that decision's options, add a separate **Recommendation** section naming the suggested option and why it is the best fit. Do this before presenting the next decision; never collect recommendations at the end of a batch.
 7. If there are multiple decisions, present them in batches of 3 by default (use fewer only when fewer remain or when the user asks for a different batch size). Start with `Decision x-y of N`, and end with `Recap: 1A 2C 3B`; ask for agreement or edits in normal chat.
 8. Iterate until consent; no feedback on a decision counts as acceptance after an explicit agreement prompt.
 9. Recurse only for nested decisions that block planning. Default max depth is 2 unless the user asks for deeper drilldown.