archgen-skill 0.0.1 → 0.0.3

package/lib/doctor.js

@@ -0,0 +1,186 @@
+// doctor.js — `archgen doctor [dir] [--check]` health-check + safe auto-repair.
+//
+// Verifies a project install: canonical store integrity, version stamp,
+// claude link resolution, managed blocks (exactly once each), and manifest
+// entry resolution. Safe issues are repaired in place unless --check is given
+// (report-only). Exit non-zero only for unrepairable failures.
+
+import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import {
+  END,
+  FEATURES_END,
+  FEATURES_START,
+  START,
+  renderBlock,
+  upsertFeaturesRegistry,
+  upsertManagedFile,
+} from './block.js';
+import { CLAUDE_LINK_REL, MANIFEST_REL, STORE_REL, VERSION_FILE, cliVersion, loadManifest, saveManifest } from './store.js';
+
+function lstatSafe(p) {
+  try { return lstatSync(p); } catch { return null; }
+}
+
+function countOccurrences(haystack, needle) {
+  let n = 0;
+  for (let i = haystack.indexOf(needle); i !== -1; i = haystack.indexOf(needle, i + needle.length)) n++;
+  return n;
+}
+
+function relJoin(rel) {
+  return join(...rel.split('/'));
+}
+
+/**
+ * @param {string} projectDir project root to inspect
+ * @param {string} packageRoot dir containing this CLI package
+ * @param {{check?: boolean}} opts check=true → report-only, no mutations
+ * @returns {{root: string, checks: {status: 'OK'|'FIXED'|'WOULD-FIX'|'WARN'|'FAIL', msg: string}[],
+ *            tally: Record<string, number>, failures: number}}
+ */
+export function doctorProject(projectDir, packageRoot, opts = {}) {
+  const root = resolve(projectDir);
+  const checkOnly = opts.check === true;
+  const version = cliVersion(packageRoot);
+  const checks = [];
+  const add = (status, msg) => checks.push({ status, msg });
+
+  const storeAbs = join(root, relJoin(STORE_REL));
+  const claudeAbs = join(root, relJoin(CLAUDE_LINK_REL));
+  const agentsAbs = join(root, 'AGENTS.md');
+  const claudeMdAbs = join(root, 'CLAUDE.md');
+
+  // 1. Canonical store validity.
+  if (existsSync(join(storeAbs, 'SKILL.md'))) {
+    add('OK', 'store .agents/skills/archgen (SKILL.md present)');
+  } else {
+    add('FAIL', 'store .agents/skills/archgen missing or incomplete - run `archgen init`');
+  }
+
+  // 2. Version stamp currency.
+  const stampAbs = join(storeAbs, VERSION_FILE);
+  let stamp = null;
+  try { stamp = readFileSync(stampAbs, 'utf8').trim(); } catch { /* absent */ }
+  if (!existsSync(storeAbs)) {
+    // already reported above; skip stamp handling without touching anything
+  } else if (stamp === version) {
+    add('OK', `version stamp ${version} (current)`);
+  } else if (checkOnly) {
+    add('WOULD-FIX', `version stamp ${stamp || 'missing'} is stale -> ${version}`);
+  } else {
+    mkdirSync(dirname(stampAbs), { recursive: true });
+    writeFileSync(stampAbs, version + '\n');
+    add('FIXED', `version stamp updated ${stamp || 'missing'} -> ${version}`);
+  }
+
+  // 3. Claude link resolution.
+  const repairLink = () => {
+    if (checkOnly) {
+      add('WOULD-FIX', 'claude link missing/dangling -> ../../.agents/skills/archgen');
+      return;
+    }
+    try {
+      try { unlinkSync(claudeAbs); } catch { /* absent */ }
+      mkdirSync(dirname(claudeAbs), { recursive: true });
+      symlinkSync('../../.agents/skills/archgen', claudeAbs);
+      add('FIXED', 'claude link recreated -> ../../.agents/skills/archgen');
+    } catch (e) {
+      add('FAIL', 'cannot recreate claude link: ' + e.message);
+    }
+  };
+  const st = lstatSafe(claudeAbs);
+  if (st && st.isSymbolicLink()) {
+    const target = resolve(dirname(claudeAbs), readlinkSync(claudeAbs));
+    if (target === storeAbs && existsSync(claudeAbs)) add('OK', 'claude link resolves to the canonical store');
+    else if (existsSync(claudeAbs)) add('WARN', 'claude link is foreign (points elsewhere) - left untouched');
+    else repairLink();
+  } else if (st && st.isDirectory()) {
+    add('WARN', '.claude/skills/archgen is a real directory (not managed) - inspect manually');
+  } else if (st) {
+    add('WARN', '.claude/skills/archgen is a regular file - left untouched');
+  } else {
+    repairLink();
+  }
+
+  // 4. AGENTS.md — managed block exactly once, features registry inside.
+  if (!existsSync(agentsAbs)) {
+    if (checkOnly) add('WOULD-FIX', 'AGENTS.md missing -> created with managed block');
+    else {
+      writeFileSync(agentsAbs, renderBlock(STORE_REL) + '\n');
+      add('FIXED', 'AGENTS.md created with managed block');
+    }
+  } else {
+    const raw = readFileSync(agentsAbs, 'utf8');
+    const starts = countOccurrences(raw, START);
+    const ends = countOccurrences(raw, END);
+    if (starts === 0) {
+      if (checkOnly) add('WOULD-FIX', 'AGENTS.md has no archgen block -> added');
+      else {
+        upsertManagedFile(agentsAbs, renderBlock(STORE_REL).split('\n'));
+        add('FIXED', 'AGENTS.md managed block added');
+      }
+    } else if (starts > 1 || ends > 1) {
+      add('FAIL', `AGENTS.md has ${starts} start / ${ends} end markers - fix manually`);
+    } else if (ends === 0 || raw.indexOf(START) > raw.indexOf(END)) {
+      add('FAIL', 'AGENTS.md has broken archgen markers - fix manually');
+    } else {
+      const fsCount = countOccurrences(raw, FEATURES_START);
+      const feCount = countOccurrences(raw, FEATURES_END);
+      if (fsCount === 1 && feCount === 1) add('OK', 'AGENTS.md block + features registry present');
+      else if (fsCount === 0 && feCount === 0) {
+        if (checkOnly) add('WOULD-FIX', 'AGENTS.md missing features registry -> inserted');
+        else {
+          upsertFeaturesRegistry(agentsAbs, []);
+          add('FIXED', 'AGENTS.md features registry inserted');
+        }
+      } else {
+        add('FAIL', 'AGENTS.md has broken archgen:features markers - fix manually');
+      }
+    }
+  }
+
+  // 5. CLAUDE.md — @AGENTS.md bridge present exactly once.
+  if (!existsSync(claudeMdAbs)) {
+    if (checkOnly) add('WOULD-FIX', 'CLAUDE.md missing -> created with @AGENTS.md bridge');
+    else {
+      upsertManagedFile(claudeMdAbs, [START, '@AGENTS.md', END]);
+      add('FIXED', 'CLAUDE.md created with @AGENTS.md bridge');
+    }
+  } else {
+    const raw = readFileSync(claudeMdAbs, 'utf8');
+    const body = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+    const imports = body.split(/\r?\n/).some((l) => l.trim() === '@AGENTS.md');
+    const starts = countOccurrences(raw, START);
+    const ends = countOccurrences(raw, END);
+    if (imports && starts <= 1 && ends <= 1) add('OK', 'CLAUDE.md bridges to AGENTS.md');
+    else if (starts > 1 || ends > 1) add('FAIL', 'CLAUDE.md has multiple archgen blocks - fix manually');
+    else if (checkOnly) add('WOULD-FIX', 'CLAUDE.md missing @AGENTS.md bridge -> written');
+    else {
+      upsertManagedFile(claudeMdAbs, [START, '@AGENTS.md', END]);
+      add('FIXED', 'CLAUDE.md @AGENTS.md bridge written');
+    }
+  }
+
+  // 6. Manifest entries resolve.
+  const manifest = loadManifest(root);
+  if (!manifest) {
+    if (existsSync(storeAbs)) add('WARN', `no install manifest at ${MANIFEST_REL} (re-run init to regenerate)`);
+    else add('OK', 'no manifest (nothing installed)');
+  } else {
+    const resolves = (e) => e && typeof e.path === 'string' && existsSync(join(root, ...e.path.split('/')));
+    const stale = manifest.entries.filter((e) => !resolves(e));
+    if (stale.length === 0) {
+      add('OK', `manifest: all ${manifest.entries.length} entr${manifest.entries.length === 1 ? 'y' : 'ies'} resolve`);
+    } else if (checkOnly) {
+      add('WOULD-FIX', `manifest: ${stale.length} stale entr${stale.length === 1 ? 'y' : 'ies'} -> pruned`);
+    } else {
+      saveManifest(root, { ...manifest, entries: manifest.entries.filter(resolves) });
+      add('FIXED', `manifest: pruned ${stale.length} stale entr${stale.length === 1 ? 'y' : 'ies'}`);
+    }
+  }
+
+  const tally = { OK: 0, FIXED: 0, 'WOULD-FIX': 0, WARN: 0, FAIL: 0 };
+  for (const c of checks) tally[c.status]++;
+  return { root, checks, tally, failures: tally.FAIL };
+}

package/lib/init.js

@@ -1,13 +1,27 @@
-// init.js — project-local skill install + AGENTS.md/CLAUDE.md context files.
+// init.js — single-store project installer + AGENTS.md/CLAUDE.md context files.
 //
-// `archgen init` makes a repository SELF-CONTAINED: the skill is copied into
-// .agents/skills/archgen (committed to git, team-shared) and mirrored at
-// .claude/skills/archgen for Claude Code; AGENTS.md + CLAUDE.md carry a
-// managed pointer block so every agent harness auto-discovers the workflow.
+// `archgen init` makes a repository SELF-CONTAINED with ONE real copy of the
+// skill: the canonical store at .agents/skills/archgen (committed to git,
+// team-shared). .claude/skills/archgen becomes a RELATIVE symlink to the
+// store — skipped gracefully where symlinks are unavailable, never a second
+// copy. AGENTS.md carries a managed pointer block with an embedded features
+// registry; CLAUDE.md carries a one-line `@AGENTS.md` bridge. Every created
+// artifact is recorded in .archgen/.install-manifest.json.
+//
+// Verified-surgical safety semantics:
+// - existing paths are fingerprinted (stable-order sha256 over relpaths +
+//   contents) BEFORE any mutation;
+// - an identical store is refreshed in place; a divergent one is moved to
+//   .archgen/.backup/<timestamp>/ FIRST, then reinstalled fresh;
+// - a real-directory claude copy identical to the vendor skill is migrated
+//   to a symlink; a customized one is left untouched with a warning;
+// - installs are atomic: built in a temp sibling dir, then renamed.
 
-import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-import { renderBlock, upsertBlock } from './block.js';
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, renameSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { dirname, join, resolve } from 'node:path';
+import { importsAgents, renderBlock, START, END, upsertManagedFile } from './block.js';
+import { CLAUDE_LINK_REL, STORE_REL, VERSION_FILE, appendEntry, cliVersion, hashDir, moveToBackup } from './store.js';
 
 const CONTEXT_FILES = ['AGENTS.md', 'CLAUDE.md'];
 
@@ -21,36 +35,124 @@ export function resolveSkillSource(packageRoot) {
   throw new Error('bundled archgen skill not found (expected vendor/skills/archgen)');
 }
 
+function lstatSafe(p) {
+  try { return lstatSync(p); } catch { return null; }
+}
+
+function relJoin(rel) {
+  return join(...rel.split('/'));
+}
+
+/**
+ * Create the claude adapter: `<project>/.claude/skills/archgen` as a RELATIVE
+ * symlink into the canonical store. Never copies. Migration/keep semantics:
+ * - ours already -> 'existing'
+ * - real dir identical to vendor -> replaced with symlink ('migrated')
+ * - real dir modified / foreign live symlink / stray file -> hands off + warn
+ * - dangling symlink -> recreated
+ * - symlink creation fails (privileges/FS) -> skipped + warning
+ */
+function installClaudeAdapter(root, source, warnings) {
+  const claudeAbs = join(root, relJoin(CLAUDE_LINK_REL));
+  const storeAbs = join(root, relJoin(STORE_REL));
+  const st = lstatSafe(claudeAbs);
+  let migrating = false;
+
+  if (st && st.isSymbolicLink()) {
+    const resolvedTarget = resolve(dirname(claudeAbs), readlinkSync(claudeAbs));
+    if (resolvedTarget === storeAbs && existsSync(claudeAbs)) return 'existing';
+    if (existsSync(claudeAbs)) {
+      warnings.push('.claude/skills/archgen is a foreign symlink - left untouched');
+      return 'kept-divergent';
+    }
+    unlinkSync(claudeAbs); // dangling: recreate ours below
+  } else if (st && st.isDirectory()) {
+    if (hashDir(claudeAbs) === hashDir(source)) {
+      rmSync(claudeAbs, { recursive: true }); // legacy dual copy -> migrate
+      migrating = true;
+    } else {
+      warnings.push('user-customized claude copy kept at .claude/skills/archgen (not managed)');
+      return 'kept-divergent';
+    }
+  } else if (st) {
+    warnings.push('.claude/skills/archgen exists and is not a directory - left untouched');
+    return 'kept-divergent';
+  }
+
+  try {
+    mkdirSync(dirname(claudeAbs), { recursive: true });
+    symlinkSync('../../.agents/skills/archgen', claudeAbs);
+    appendEntry(root, 'link', CLAUDE_LINK_REL);
+    return migrating ? 'migrated' : 'created';
+  } catch (e) {
+    warnings.push('claude adapter skipped: symlink unavailable (' + e.message + ')');
+    return 'skipped';
+  }
+}
+
 /**
- * Initialize a project: copy the skill locally + write context pointers.
+ * Initialize a project: install the single canonical skill store, wire the
+ * claude adapter, and write context pointers.
  * @param {string} projectDir target repo root
  * @param {string} packageRoot dir containing this CLI package
- * @returns {{skillCopies: string[], contextFiles: string[], createdContextFiles: string[]}}
+ * @param {{force?: boolean}} opts --force proceeds automatically; divergent
+ *   copies are always auto-backed-up (never refused, never destroyed)
+ * @returns {{storePath: string, claudeLink: 'created'|'existing'|'migrated'|'skipped'|'kept-divergent',
+ *            backups: string[], contextFiles: string[], createdContextFiles: string[], warnings: string[]}}
  */
-export function initProject(projectDir, packageRoot) {
+export function initProject(projectDir, packageRoot, opts = {}) {
+  // --force is accepted for explicitness: this installer never refuses and
+  // never destroys data — divergent copies are backed up automatically, so
+  // both plain and --force runs take the same safe path.
+  const force = opts.force === true;
+  void force;
+
   const root = resolve(projectDir);
   const source = resolveSkillSource(packageRoot);
+  const version = cliVersion(packageRoot);
+  const warnings = [];
+  const backups = [];
+
+  const storeAbs = join(root, relJoin(STORE_REL));
+
+  // 1. Canonical store — fingerprint before mutating (ownership check).
+  const prev = lstatSafe(storeAbs);
+  if (prev) {
+    const identical = prev.isDirectory() && !prev.isSymbolicLink()
+      && hashDir(storeAbs, { ignore: [VERSION_FILE] }) === hashDir(source);
+    if (!identical) backups.push(moveToBackup(root, STORE_REL));
+  }
+
+  // Atomic install: build in a temp sibling dir, then rename into place.
+  const skillsParent = dirname(storeAbs);
+  mkdirSync(skillsParent, { recursive: true });
+  const tmp = join(skillsParent, '.archgen-tmp-' + randomBytes(6).toString('hex'));
+  cpSync(source, tmp, { recursive: true });
+  writeFileSync(join(tmp, VERSION_FILE), version + '\n');
+  rmSync(storeAbs, { recursive: true, force: true });
+  renameSync(tmp, storeAbs);
+  appendEntry(root, 'dir', STORE_REL);
 
-  // 1. Skill copies — real files (not symlinks) so git carries them for the team.
-  const agentsSkills = join(root, '.agents', 'skills', 'archgen');
-  const claudeSkills = join(root, '.claude', 'skills', 'archgen');
-  mkdirSync(agentsSkills, { recursive: true });
-  cpSync(source, agentsSkills, { recursive: true });
-  mkdirSync(join(root, '.claude', 'skills'), { recursive: true });
-  cpSync(agentsSkills, claudeSkills, { recursive: true });
+  // 2. Claude adapter — relative symlink, never a second copy.
+  const claudeLink = installClaudeAdapter(root, source, warnings);
 
-  // 2. Context pointer files — managed blocks, user content preserved.
-  const block = renderBlock('.agents/skills/archgen');
+  // 3. Context files — managed blocks, user content preserved.
   const contextFiles = [];
-  const created = [];
+  const createdContextFiles = [];
   for (const name of CONTEXT_FILES) {
-    const p = join(root, name);
-    const existed = existsSync(p);
-    const next = upsertBlock(existed ? readFileSync(p, 'utf8') : '', block);
-    writeFileSync(p, next);
+    const abs = join(root, name);
+    if (name === 'CLAUDE.md' && importsAgents(abs)) {
+      warnings.push('CLAUDE.md already imports @AGENTS.md - skipped (already-imports)');
+      continue;
+    }
+    const existed = upsertManagedFile(
+      abs,
+      name === 'AGENTS.md' ? renderBlock(STORE_REL).split('\n') : [START, '@AGENTS.md', END],
+    );
     contextFiles.push(name);
-    if (!existed) created.push(name);
+    if (!existed) createdContextFiles.push(name);
+    appendEntry(root, 'block', name);
   }
 
-  return { skillCopies: [agentsSkills, claudeSkills], contextFiles, createdContextFiles: created };
+  return { storePath: storeAbs, claudeLink, backups, contextFiles, createdContextFiles, warnings };
 }

package/lib/store.js

@@ -0,0 +1,146 @@
+// store.js — shared primitives for the single-store project layout.
+//
+// Layout (all paths relative to the project root):
+//   .agents/skills/archgen            canonical store (the ONLY real copy)
+//   .agents/skills/archgen/.archgen-version  CLI version stamp (rewritten every init)
+//   .claude/skills/archgen            RELATIVE symlink -> ../../.agents/skills/archgen
+//   .archgen/.install-manifest.json   manifest of everything archgen created
+//   .archgen/.backup/<timestamp>/     divergent copies moved aside before replace
+//
+// Safety rails:
+// - hashDir() fingerprints a tree (stable-order walk of relpaths + contents,
+//   sha256) so mutations only ever happen after verifying ownership/divergence;
+// - GUARDED_RELPATHS (.claude, .agents, .claude/skills, .agents/skills) are
+//   never deleted: parent pruning stops before touching those levels.
+
+import { createHash } from 'node:crypto';
+import {
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  readlinkSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export const STORE_REL = '.agents/skills/archgen';
+export const CLAUDE_LINK_REL = '.claude/skills/archgen';
+export const MANIFEST_REL = '.archgen/.install-manifest.json';
+export const BACKUP_ROOT_REL = '.archgen/.backup';
+export const VERSION_FILE = '.archgen-version';
+
+const GUARDED_RELPATHS = new Set(['.claude', '.agents', '.claude/skills', '.agents/skills']);
+
+/** Version string of this CLI package (used for the in-store stamp). */
+export function cliVersion(packageRoot) {
+  return JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8')).version;
+}
+
+function byName(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * Stable-order directory fingerprint: sha256 over sorted relpaths plus file
+ * contents (symlinks hashed via their targets). Deterministic across machines.
+ * @param {string} dir absolute directory to hash
+ * @param {{ignore?: string[]}} opts relpaths to skip (e.g. our version stamp)
+ */
+export function hashDir(dir, opts = {}) {
+  const ignore = opts.ignore ?? [];
+  const hash = createHash('sha256');
+  (function walk(abs, rel) {
+    const entries = readdirSync(abs, { withFileTypes: true }).sort((a, b) => byName(a.name, b.name));
+    for (const ent of entries) {
+      const r = rel ? rel + '/' + ent.name : ent.name;
+      if (ignore.includes(r)) continue;
+      const p = join(abs, ent.name);
+      if (ent.isSymbolicLink()) hash.update('l ' + r + ' -> ' + readlinkSync(p) + '\n');
+      else if (ent.isDirectory()) { hash.update('d ' + r + '\n'); walk(p, r); }
+      else { hash.update('f ' + r + '\0'); hash.update(readFileSync(p)); hash.update('\n'); }
+    }
+  })(dir, '');
+  return hash.digest('hex');
+}
+
+/** Load `.archgen/.install-manifest.json`; null when absent/corrupt. */
+export function loadManifest(root) {
+  const p = join(root, ...MANIFEST_REL.split('/'));
+  if (!existsSync(p)) return null;
+  try {
+    const m = JSON.parse(readFileSync(p, 'utf8'));
+    return m && typeof m === 'object' ? m : null;
+  } catch {
+    return null;
+  }
+}
+
+export function saveManifest(root, manifest) {
+  const p = join(root, ...MANIFEST_REL.split('/'));
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, JSON.stringify(manifest, null, 2) + '\n');
+}
+
+/** Record a created dir/link/block; dedupes on kind+path. */
+export function appendEntry(root, kind, relPath) {
+  const now = new Date().toISOString();
+  const m = loadManifest(root) ?? { version: 1, createdAt: now, entries: [] };
+  if (!Array.isArray(m.entries)) m.entries = [];
+  if (m.entries.some((e) => e && e.kind === kind && e.path === relPath)) return;
+  m.version = m.version ?? 1;
+  m.createdAt = m.createdAt ?? now;
+  m.entries.push({ kind, path: relPath, createdAt: now });
+  saveManifest(root, m);
+}
+
+/**
+ * Move an existing project-relative path into `.archgen/.backup/<ts>/<rel>`.
+ * Preserves the relative layout so backups restore unambiguously.
+ * @returns {string} backup location relative to the project root
+ */
+export function moveToBackup(root, relPath) {
+  const ts = new Date().toISOString().replace(/:/g, '-');
+  const destRel = BACKUP_ROOT_REL + '/' + ts + '/' + relPath;
+  const destAbs = join(root, ...destRel.split('/'));
+  mkdirSync(dirname(destAbs), { recursive: true });
+  const srcAbs = join(root, ...relPath.split('/'));
+  try {
+    renameSync(srcAbs, destAbs);
+  } catch {
+    cpSync(srcAbs, destAbs, { recursive: true });
+    rmSync(srcAbs, { recursive: true, force: true });
+  }
+  return destRel;
+}
+
+export function rmIfExists(absPath) {
+  let st = null;
+  try { st = lstatSync(absPath); } catch { /* absent */ }
+  if (!st) return false;
+  rmSync(absPath, { force: true, recursive: st.isDirectory() && !st.isSymbolicLink() });
+  return true;
+}
+
+/**
+ * Walk UPWARD from relPath removing directories only while they are left
+ * completely empty by our removals. Stops at guarded levels and the root —
+ * `.claude`, `.agents`, `.claude/skills`, `.agents/skills` are never deleted.
+ */
+export function pruneEmptyParents(root, relPath) {
+  let cur = relPath;
+  while (cur && cur !== '.') {
+    if (GUARDED_RELPATHS.has(cur)) break;
+    const abs = join(root, ...cur.split('/'));
+    let empty = false;
+    try { empty = readdirSync(abs).length === 0; } catch { break; }
+    if (!empty) break;
+    rmSync(abs, { recursive: true, force: true });
+    const parent = dirname(cur);
+    cur = parent === '.' ? '' : parent;
+  }
+}

package/lib/uninstall-project.js

@@ -0,0 +1,92 @@
+// uninstall-project.js — `archgen uninstall --project [dir]` removal with rails.
+//
+// Removes exactly what archgen owns in a project: the claude symlink, the
+// managed blocks, the canonical store (ONLY when unmodified vs the vendor
+// skill — a customized store is kept with a warning), and the install
+// manifest. `.archgen/<slug>` feature folders and `.archgen/.backup/` are
+// always preserved. Parents are pruned only when left completely empty, and
+// never past the guarded .claude/.agents levels.
+
+import { existsSync, lstatSync, readlinkSync, rmSync, unlinkSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { stripManagedFile } from './block.js';
+import {
+  CLAUDE_LINK_REL,
+  MANIFEST_REL,
+  STORE_REL,
+  VERSION_FILE,
+  hashDir,
+  pruneEmptyParents,
+  rmIfExists,
+} from './store.js';
+import { resolveSkillSource } from './init.js';
+
+function lstatSafe(p) {
+  try { return lstatSync(p); } catch { return null; }
+}
+
+function relJoin(rel) {
+  return join(...rel.split('/'));
+}
+
+/**
+ * @param {string} projectDir project root to clean
+ * @param {string} packageRoot dir containing this CLI package (vendor source)
+ * @returns {{root: string, linkRemoved: boolean, strippedBlocks: string[],
+ *            storeRemoved: boolean, storeKept: boolean, manifestRemoved: boolean, warnings: string[]}}
+ */
+export function uninstallProject(projectDir, packageRoot) {
+  const root = resolve(projectDir);
+  const warnings = [];
+  const strippedBlocks = [];
+
+  const storeAbs = join(root, relJoin(STORE_REL));
+  const claudeAbs = join(root, relJoin(CLAUDE_LINK_REL));
+
+  // 1. Claude adapter — remove only our own symlink (dangling included).
+  let linkRemoved = false;
+  const lst = lstatSafe(claudeAbs);
+  if (lst && lst.isSymbolicLink()) {
+    const target = resolve(dirname(claudeAbs), readlinkSync(claudeAbs));
+    if (target === storeAbs || !existsSync(claudeAbs)) {
+      unlinkSync(claudeAbs); // removes the link itself, never its target
+      linkRemoved = true;
+    } else {
+      warnings.push('foreign symlink at .claude/skills/archgen - left untouched');
+    }
+  } else if (lst && lst.isDirectory()) {
+    warnings.push('.claude/skills/archgen is a real directory - left untouched (remove manually if unwanted)');
+  }
+
+  // 2. Managed blocks — strip markers, keep all user content.
+  for (const name of ['AGENTS.md', 'CLAUDE.md']) {
+    if (stripManagedFile(join(root, name)).hadBlock) strippedBlocks.push(name);
+  }
+
+  // 3. Canonical store — remove ONLY if unmodified vs vendor.
+  //    The version stamp is our metadata, so it is ignored when comparing.
+  let storeRemoved = false;
+  let storeKept = false;
+  if (lstatSafe(storeAbs)) {
+    const st = lstatSafe(storeAbs);
+    const mine = st.isDirectory() && !st.isSymbolicLink()
+      ? hashDir(storeAbs, { ignore: [VERSION_FILE] })
+      : null;
+    let vendor = null;
+    try { vendor = hashDir(resolveSkillSource(packageRoot)); } catch { vendor = null; }
+    if (vendor !== null && mine === vendor) {
+      rmSync(storeAbs, { recursive: true, force: true });
+      storeRemoved = true;
+    } else {
+      storeKept = true;
+      warnings.push('canonical store kept at .agents/skills/archgen: modified vs vendor (or unverifiable) - review manually');
+    }
+  }
+
+  // 4. Manifest file — then prune .archgen only if nothing else remains
+  //    (feature folders / backups keep it alive).
+  const manifestRemoved = rmIfExists(join(root, relJoin(MANIFEST_REL)));
+  if (manifestRemoved) pruneEmptyParents(root, dirname(MANIFEST_REL));
+
+  return { root, linkRemoved, strippedBlocks, storeRemoved, storeKept, manifestRemoved, warnings };
+}

package/lib/version.js

@@ -0,0 +1,23 @@
+// version.js — semver compare + npm registry lookup (zero deps).
+import { spawnSync } from 'node:child_process';
+
+export function parseSemver(v) {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(String(v ?? '').trim());
+  return m ? { major: +m[1], minor: +m[2], patch: +m[3] } : null;
+}
+
+export function compareSemver(a, b) {
+  const x = parseSemver(a);
+  const y = parseSemver(b);
+  if (!x || !y) return 0;
+  for (const k of ['major', 'minor', 'patch']) {
+    if (x[k] !== y[k]) return x[k] < y[k] ? -1 : 1;
+  }
+  return 0;
+}
+
+export function fetchLatestVersion(pkg) {
+  const r = spawnSync('npm', ['view', pkg, 'version'], { encoding: 'utf8', timeout: 15000 });
+  if (r.status !== 0 || !r.stdout) return null;
+  return r.stdout.trim().split(/\r?\n/).pop() || null;
+}

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "archgen-skill",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Architecture generation & autonomous task execution for coding agents - conversational requirements in, dependency-ordered tasks out, executed wave-by-wave with verifier gates. Works with Claude Code, OpenCode, Cursor, Codex, Gemini CLI and any agentskills.io harness.",
   "license": "MIT",
   "type": "module",
-  "bin": { "archgen": "bin/archgen.mjs" },
+  "bin": { "archgen-skill": "bin/archgen.mjs" },
   "files": ["bin/", "lib/", "vendor/", "README.md"],
   "engines": { "node": ">=18" },
-  "keywords": ["ai", "agents", "architecture", "claude", "cursor", "opencode", "codex", "skills", "tasks", "orchestration"],
+  "keywords": ["ai", "agents", "claude", "codex", "cursor", "opencode", "gemini", "architecture", "skills", "orchestration", "task-graph", "planning"],
   "repository": { "type": "git", "url": "git+https://github.com/akashmaurya99/archgen.git" },
+  "homepage": "https://github.com/akashmaurya99/archgen#readme",
+  "bugs": { "url": "https://github.com/akashmaurya99/archgen/issues" },
   "//": "vendor/skills/archgen is synced from ../skills/archgen by scripts/sync-vendor.mjs (run automatically via prepublishOnly). The extension ships separately as a VS Code vsix.",
   "scripts": {
     "sync": "node scripts/sync-vendor.mjs",