semantu-agents 1.0.0

package/README.md

@@ -0,0 +1,62 @@
+# semantu-agents
+
+Reusable Claude Code skills and hooks for Semantu projects.
+
+The npm package is a thin CLI that clones this private repo — no skill files are shipped on npm.
+
+## Project setup
+
+```bash
+npx semantu-agents
+```
+
+Clones the agents repo into `packages/skills/`, patches `package.json` and `.gitignore`, then syncs skills to `.claude/skills/` and `.agents/skills/`. Skips gracefully without repo access.
+
+Add to `package.json` so it runs on setup:
+
+```json
+{
+  "scripts": {
+    "setup": "npx semantu-agents"
+  }
+}
+```
+
+## Global setup
+
+```bash
+npx semantu-agents --global
+```
+
+Clones the repo into `~/.agents-src/` and syncs skills to `~/.claude/skills/` and `~/.agents/skills/`. This makes skills available to Claude Code and Codex across all projects without per-repo setup.
+
+## Editing skills
+
+Edit directly in `packages/skills/skills/`, then commit and push:
+
+```bash
+cd packages/skills
+git checkout -b my-change
+# edit skills...
+git add -A && git commit -m "improve workflow skill"
+git push -u origin my-change
+```
+
+To re-sync after editing:
+
+```bash
+npm run sync:agents
+```
+
+## Skills
+
+| Skill | Purpose |
+|---|---|
+| `workflow` | Enforces the mode cadence: ideation → plan → tasks → implementation → review → wrapup |
+| `ideation` | Explore and compare implementation options |
+| `plan` | Convert decisions into a concrete architecture plan |
+| `tasks` | Break a plan into phased tasks with validation criteria |
+| `implementation` | Execute tasks phase-by-phase with commits and validation |
+| `review` | Review work against intent, readiness, and gaps |
+| `wrapup` | Cleanup, changesets, and PR preparation |
+| `automatic` | Run the full workflow without manual mode transitions |

package/cli.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+
+/**
+ * semantu-agents — thin CLI that clones the private agents repo and syncs skills.
+ *
+ * Usage:
+ *   npx semantu-agents           — clone repo into packages/skills/, sync to project
+ *   npx semantu-agents --global  — clone repo into ~/.agents-src/, sync to ~/.claude/ and ~/.agents/
+ *
+ * Skips gracefully if the user lacks repo access.
+ */
+
+import {cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync} from 'node:fs';
+import {homedir} from 'node:os';
+import path from 'node:path';
+import {execSync} from 'node:child_process';
+
+const skillsRepo = 'git@github.com:Semantu/agents.git';
+
+function run(cmd, opts) {
+  return execSync(cmd, {stdio: 'inherit', ...opts});
+}
+
+function cloneOrPull(dir) {
+  if (existsSync(path.join(dir, '.git'))) {
+    console.log('Updating skills repo...');
+    run('git pull --ff-only', {cwd: dir});
+  } else {
+    console.log('Cloning skills repo...');
+    run(`git clone ${skillsRepo} ${dir}`);
+  }
+}
+
+function syncSkills(skillsSource, targets) {
+  for (const dest of targets) {
+    rmSync(dest, {recursive: true, force: true});
+    mkdirSync(path.dirname(dest), {recursive: true});
+    cpSync(skillsSource, dest, {recursive: true});
+    console.log(`Synced skills -> ${dest}`);
+  }
+}
+
+function setupGlobal() {
+  const home = homedir();
+  const srcDir = path.join(home, '.agents-src');
+
+  cloneOrPull(srcDir);
+
+  const skillsSource = path.join(srcDir, 'skills');
+  syncSkills(skillsSource, [
+    path.join(home, '.claude', 'skills'),
+    path.join(home, '.agents', 'skills'),
+  ]);
+
+  console.log('\nDone. Skills synced globally to ~/.claude/skills/ and ~/.agents/skills/');
+}
+
+function setupProject() {
+  const projectRoot = process.cwd();
+  const skillsDir = path.join(projectRoot, 'packages', 'skills');
+
+  cloneOrPull(skillsDir);
+
+  // Patch package.json scripts
+  const pkgPath = path.join(projectRoot, 'package.json');
+  if (existsSync(pkgPath)) {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    const scripts = pkg.scripts || {};
+    let changed = false;
+
+    if (!scripts['sync:agents']) {
+      scripts['sync:agents'] = 'node packages/skills/sync.mjs';
+      changed = true;
+    }
+    if (!scripts['setup'] || scripts['setup'] === 'npx semantu-agents') {
+      scripts['setup'] = 'npx semantu-agents';
+      changed = true;
+    }
+
+    if (changed) {
+      pkg.scripts = scripts;
+      writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+      console.log('Updated package.json scripts');
+    }
+  }
+
+  // Patch .gitignore
+  const ignorePath = path.join(projectRoot, '.gitignore');
+  const ignoreEntries = ['packages/', '.claude/', '.agents/'];
+  let ignoreContent = existsSync(ignorePath) ? readFileSync(ignorePath, 'utf8') : '';
+  let ignoreChanged = false;
+
+  for (const entry of ignoreEntries) {
+    if (!ignoreContent.split('\n').some(line => line.trim() === entry)) {
+      ignoreContent = ignoreContent.trimEnd() + '\n' + entry + '\n';
+      ignoreChanged = true;
+    }
+  }
+
+  if (ignoreChanged) {
+    writeFileSync(ignorePath, ignoreContent);
+    console.log('Updated .gitignore');
+  }
+
+  // Sync from the cloned repo
+  run('node sync.mjs', {cwd: skillsDir});
+}
+
+// --- Main ---
+
+const isGlobal = process.argv.includes('--global') || process.argv.includes('-g');
+
+try {
+  if (isGlobal) {
+    setupGlobal();
+  } else {
+    setupProject();
+  }
+} catch {
+  console.log('\nSkipping skills setup — could not access the skills repo.');
+  console.log("This is fine if you don't have access to github.com:Semantu/agents.");
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "semantu-agents",
+  "version": "1.0.0",
+  "description": "Reusable Claude Code skills and hooks for Semantu projects",
+  "type": "module",
+  "bin": {
+    "semantu-agents": "cli.mjs"
+  },
+  "files": [
+    "cli.mjs"
+  ],
+  "scripts": {
+    "sync": "node sync.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "^0.5.2",
+    "@changesets/cli": "^2.29.8"
+  }
+}