archgen-skill 0.0.2 → 0.0.3

package/README.md

@@ -21,13 +21,27 @@ Antigravity** — and any [agentskills.io](https://agentskills.io)-compatible ha
 
 ## Install
 
-**Prepare a project** (recommended) — copies the skill locally + writes
-`AGENTS.md` / `CLAUDE.md` pointer blocks so every harness auto-discovers it:
+**Prepare a project** (recommended) — installs ONE canonical skill copy plus
+harness bridges so every agent auto-discovers it:
 
 ```bash
 npx archgen-skill init
 ```
 
+What `init` writes (nothing is ever duplicated):
+
+| Path | What |
+| --- | --- |
+| `.agents/skills/archgen/` | **The only real copy** — the agentskills.io standard location read natively by OpenCode, Cursor, Codex, Gemini CLI, Copilot and Antigravity |
+| `.claude/skills/archgen → ../../.agents/skills/archgen` | Relative symlink for Claude Code (the one harness needing it). Skipped gracefully where symlinks need privileges — Claude still works via the bridge below |
+| `AGENTS.md` | Managed hub block: skill pointer + quick triggers + a features registry that stays current as you add features |
+| `CLAUDE.md` | One-line bridge: `@AGENTS.md` (existing files keep all their content; if it already imports AGENTS.md we write nothing) |
+
+Existing projects with user content are safe: managed blocks upsert between
+markers, modified skill copies are backed up to `.archgen/.backup/<timestamp>/`
+before refresh, and legacy dual-copy layouts are migrated to symlinks
+automatically. Verify anytime with `archgen-skill doctor`.
+
 **Or install globally** into every detected harness:
 
 ```bash
@@ -56,9 +70,11 @@ architecture contract, docs, ADRs, plans, and a `tasks.yaml` task graph — vers
 
 | Command | What it does |
 | --- | --- |
-| `npx archgen-skill init [dir]` | Copy the skill into `.agents/skills/archgen` + `.claude/skills/archgen` and write AGENTS.md / CLAUDE.md pointer blocks |
+| `npx archgen-skill init [dir]` | Install the single canonical skill store at `.agents/skills/archgen`, add the Claude symlink adapter, write the AGENTS.md hub + CLAUDE.md `@AGENTS.md` bridge |
 | `npx archgen-skill install [--copy]` | Install into global harness skill dirs (symlinks by default, real copies with `--copy`) |
 | `npx archgen-skill uninstall` | Remove globally-installed copies (manifest-recorded, safe removal) |
+| `npx archgen-skill uninstall --project [dir]` | Remove project install: strips managed blocks, our symlink and the store **only if unmodified** — feature folders in `.archgen/` and all user content are preserved |
+| `npx archgen-skill doctor [dir] [--check]` | Verify + auto-repair an installation: store integrity, version stamp, Claude link, blocks present exactly once, manifest resolution (`--check` reports without fixing) |
 | `npx archgen-skill --help` | Help |
 
 ## Why archgen

package/bin/archgen.mjs

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 // archgen — npm CLI for the archgen skill.
 //
-//   npx archgen-skill init            Install skill into THIS project + write
-//                               AGENTS.md / CLAUDE.md context pointers
+//   npx archgen-skill init [dir]      ONE canonical skill store + claude symlink
+//                               adapter + AGENTS.md / CLAUDE.md context pointers
+//   npx archgen-skill doctor [dir]    Verify/repair a project install (--check = report only)
 //   npx archgen-skill install         Install skill into global harness dirs
 //                               (Claude Code, OpenCode, Cursor, agentskills)
 //   npx archgen-skill uninstall       Remove globally-installed copies (manifest-based)
+//     --project [dir]           Remove archgen from a specific project instead
 //
 // Zero dependencies. Cross-platform (Windows included — no bash required).
 
@@ -13,20 +15,50 @@ import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { installGlobal, uninstallGlobal } from '../lib/install.js';
 import { initProject } from '../lib/init.js';
+import { doctorProject } from '../lib/doctor.js';
+import { uninstallProject } from '../lib/uninstall-project.js';
+import { compareSemver, fetchLatestVersion } from '../lib/version.js';
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
+function cliVersion() {
+  return JSON.parse(readFileSync(resolve(PACKAGE_ROOT, 'package.json'), 'utf8')).version;
+}
+
+function runInitAndDoctor(dir) {
+  const r = initProject(dir, PACKAGE_ROOT);
+  console.log('  = store refreshed at ' + r.storePath);
+  doctorProject(dir, PACKAGE_ROOT, {});
+}
+
 const HELP = `archgen — architecture generation & autonomous task execution for coding agents
 
 Usage:
-  npx archgen-skill init [dir]        Prepare a project: copy the skill into
-                                .agents/skills/archgen + .claude/skills/archgen
-                                and generate AGENTS.md / CLAUDE.md pointer blocks
-                                so every agent harness auto-discovers it.
+  npx archgen-skill init [dir]        Prepare a project: create the canonical skill
+                                store at .agents/skills/archgen, symlink
+                                .claude/skills/archgen -> ../../.agents/skills/archgen,
+                                and generate AGENTS.md / CLAUDE.md pointer blocks.
+    [--force]                     proceed automatically; divergent copies are
+                                  backed up to .archgen/.backup/ (never destroyed)
+  npx archgen-skill doctor [dir]      Health-check a project install: store integrity,
+                                version stamp, claude link, managed blocks,
+                                manifest. Repairs safe issues in place.
+    [--check]                     report only - change nothing
   npx archgen-skill install           Install into global harness skill dirs
     [--copy]                      real copies instead of symlinks
     [--uninstall]                 remove manifest-recorded entries
-  npx archgen-skill uninstall         Alias for install --uninstall
+  npx archgen-skill uninstall         Remove globally-installed copies (manifest-based)
+    --project [dir]               remove archgen from a project: claude link,
+                                  managed blocks, canonical store (kept when
+                                  customized) and manifest; .archgen feature
+                                  folders and backups are preserved
+  npx archgen-skill update [dir]      Check npm for a newer archgen-skill, upgrade
+                                  the global install when outdated, then
+                                  re-init this project + doctor against the
+                                  new version. No-op when already latest.
+  npx archgen-skill --version         Print the running CLI version
   npx archgen-skill --help            This help
 
 Docs: https://github.com/akashmaurya99/archgen`;
@@ -40,19 +72,40 @@ function flag(name) {
   return true;
 }
 
+function positionalDir() {
+  return rest[0] ? resolve(rest[0]) : process.cwd();
+}
+
 try {
   switch (cmd) {
     case 'init': {
-      const dir = rest[0] ? resolve(rest[0]) : process.cwd();
-      const r = initProject(dir, PACKAGE_ROOT);
-      console.log('archgen: skill installed into project');
-      for (const p of r.skillCopies) console.log('  + ' + p);
+      flag('--force');
+      const r = initProject(positionalDir(), PACKAGE_ROOT);
+      console.log('archgen: project ready (single-store layout)');
+      console.log('  + store ' + r.storePath);
+      if (r.claudeLink === 'created') console.log('  + link  .claude/skills/archgen -> ../../.agents/skills/archgen');
+      else if (r.claudeLink === 'existing') console.log('  = link  .claude/skills/archgen (already points at the store)');
+      else if (r.claudeLink === 'migrated') console.log('  ~ link  .claude/skills/archgen migrated from copy to symlink');
+      else if (r.claudeLink === 'kept-divergent') console.log('  ! kept  .claude/skills/archgen (divergent - left untouched)');
+      else console.log('  ! skip  .claude/skills/archgen (symlink unavailable)');
+      for (const b of r.backups) console.log('  ~ backup ' + b + ' (previous store moved aside)');
       for (const f of r.contextFiles) {
         console.log(`  ${r.createdContextFiles.includes(f) ? 'created' : 'updated'} ${f} (archgen pointer block)`);
       }
+      for (const w of r.warnings) console.log('  note: ' + w);
       console.log('\nNext: open this project in your agent and say "generate architecture" or "add feature X".');
       break;
     }
+    case 'doctor': {
+      const check = flag('--check');
+      const r = doctorProject(positionalDir(), PACKAGE_ROOT, { check });
+      console.log('archgen doctor — ' + r.root + (check ? '  (check mode: no changes made)' : ''));
+      for (const c of r.checks) console.log(`  [${c.status.toLowerCase().padEnd(9)}] ${c.msg}`);
+      const t = r.tally;
+      console.log(`Summary: ${t.OK} ok, ${t.FIXED} fixed, ${t['WOULD-FIX']} would-fix, ${t.WARN} warning(s), ${t.FAIL} failure(s)`);
+      if (r.failures > 0) process.exitCode = 1;
+      break;
+    }
     case 'install': {
       const copy = flag('--copy');
       if (flag('--uninstall')) { uninstall(); break; }
@@ -64,7 +117,65 @@ try {
       break;
     }
     case 'uninstall': {
-      uninstall();
+      if (flag('--project')) {
+        const r = uninstallProject(positionalDir(), PACKAGE_ROOT);
+        console.log('archgen: project uninstall — ' + r.root);
+        if (r.linkRemoved) console.log('  - .claude/skills/archgen (link)');
+        if (r.strippedBlocks.length) console.log('  - managed blocks stripped from ' + r.strippedBlocks.join(', '));
+        if (r.storeRemoved) console.log('  - .agents/skills/archgen (unmodified store)');
+        if (r.storeKept) console.log('  = .agents/skills/archgen KEPT (customized)');
+        if (r.manifestRemoved) console.log('  - .archgen/.install-manifest.json');
+        for (const w of r.warnings) console.log('  note: ' + w);
+        console.log('  .archgen feature folders and backups are preserved.');
+      } else {
+        uninstall();
+      }
+      break;
+    }
+    case 'update': {
+      const dir = positionalDir();
+      const current = cliVersion();
+      console.log('archgen update — running v' + current + ', checking npm registry…');
+      const latest = fetchLatestVersion('archgen-skill');
+      if (!latest) {
+        console.log('  ! could not reach the npm registry (offline?). Nothing changed.');
+        break;
+      }
+      const cmp = compareSemver(latest, current);
+      if (cmp === 0) {
+        console.log('  = already on the latest published version (' + latest + ').');
+        console.log('  Refreshing this project against it anyway…');
+        runInitAndDoctor(dir);
+        break;
+      }
+      if (cmp < 0) {
+        console.log('  ↑ running v' + current + ' is newer than npm (' + latest + ') — not published yet.');
+        console.log('  Refreshing this project against the running version…');
+        runInitAndDoctor(dir);
+        break;
+      }
+      console.log('  ↑ newer version available: ' + latest);
+      console.log('  upgrading global install: npm install -g archgen-skill@' + latest);
+      const up = spawnSync('npm', ['install', '-g', 'archgen-skill@' + latest], { stdio: 'inherit' });
+      if (up.status !== 0) {
+        console.error('  ! global upgrade failed — run it manually, then re-run: archgen-skill update');
+        process.exitCode = 1;
+        break;
+      }
+      // The running process is the OLD code; re-exec the freshly installed binary.
+      const bin = spawnSync('command', ['-v', 'archgen-skill'], { encoding: 'utf8', shell: true });
+      const freshBin = (bin.stdout || '').trim();
+      if (!freshBin) {
+        console.log('\nUpgraded to v' + latest + '. Now finish per project with:\n  npx archgen-skill@latest init');
+        break;
+      }
+      console.log('\nre-running init + doctor with the new binary (' + latest + ')…');
+      spawnSync(freshBin, ['init', dir], { stdio: 'inherit' });
+      spawnSync(freshBin, ['doctor', dir], { stdio: 'inherit' });
+      break;
+    }
+    case '--version': case '-v': {
+      console.log(cliVersion());
       break;
     }
     case '--help': case '-h': case undefined: {

package/lib/block.js

@@ -4,15 +4,24 @@
 // archgen writes lives between START/END markers; re-runs replace the block
 // in place, uninstalls strip it, and anything the user wrote outside the
 // markers is untouched.
+//
+// AGENTS.md carries the full pointer block with an embedded features registry
+// (between FEATURES_START/FEATURES_END). CLAUDE.md carries a one-line
+// `@AGENTS.md` bridge inside the same managed markers.
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 
 export const START = '<!-- archgen:start (managed block - do not edit between markers) -->';
 export const END = '<!-- archgen:end -->';
+export const FEATURES_START = '<!-- archgen:features:start -->';
+export const FEATURES_END = '<!-- archgen:features:end -->';
 
 /**
  * Render the archgen pointer block for a project.
  * @param {string} skillRelPath relative path to the skill dir from project root
+ * @param {string} eol line ending used to join the block lines
  */
-export function renderBlock(skillRelPath = '.agents/skills/archgen') {
+export function renderBlock(skillRelPath = '.agents/skills/archgen', eol = '\n') {
   return [
     START,
     '# ArchGen - Architecture Generation & Autonomous Task Execution',
@@ -32,16 +41,24 @@ export function renderBlock(skillRelPath = '.agents/skills/archgen') {
     '- Generated artifacts live ONLY under `.archgen/<slug>/`',
     '- Never hand-edit task statuses - use `scripts/set-status.mjs` (comment-safe)',
     '- Two gates before any execution: verifier approval, then human approval',
+    '',
+    '## Features registry',
+    '',
+    FEATURES_START,
+    '| Feature | Status | Updated |',
+    '| --- | --- | --- |',
+    FEATURES_END,
     END,
-  ].join('\n');
+  ].join(eol);
 }
 
 /**
  * Insert or replace the managed block inside existing file content.
  * @param {string} existing file contents ('' when creating new)
  * @param {string} block rendered block
+ * @param {string} eol line ending used when appending to empty/missing files
  */
-export function upsertBlock(existing, block) {
+export function upsertBlock(existing, block, eol = '\n') {
   const trimmed = existing ?? '';
   const startIdx = trimmed.indexOf(START);
   const endIdx = trimmed.indexOf(END);
@@ -51,8 +68,9 @@ export function upsertBlock(existing, block) {
   if (startIdx !== -1 || endIdx !== -1) {
     throw new Error('found only one archgen marker - fix or remove it manually');
   }
-  if (trimmed.trim() === '') return block + '\n';
-  return trimmed.replace(/\n*$/, '\n\n') + block + '\n';
+  if (trimmed.trim() === '') return block + eol;
+  const core = trimmed.replace(/(?:\r?\n)+$/, '');
+  return core + eol + eol + block + eol;
 }
 
 /**
@@ -69,3 +87,89 @@ export function stripBlock(existing) {
   out = out.replace(/^\n+/, '').replace(/\n{3,}/g, '\n\n');
   return { content: out, hadBlock: true };
 }
+
+function splitBom(raw) {
+  const bom = raw.charCodeAt(0) === 0xfeff;
+  return { bom, body: bom ? raw.slice(1) : raw };
+}
+
+/**
+ * BOM/EOL-aware upsert of a managed block directly into a file.
+ * Preserves a leading UTF-8 BOM and the file's CRLF/LF convention.
+ * @param {string} absPath target file (created when missing)
+ * @param {string[]} blockLines lines between the managed markers
+ * @returns {boolean} whether the file existed before the call
+ */
+export function upsertManagedFile(absPath, blockLines) {
+  const existed = existsSync(absPath);
+  const raw = existed ? readFileSync(absPath, 'utf8') : '';
+  const { bom, body } = splitBom(raw);
+  const eol = body.includes('\r\n') ? '\r\n' : '\n';
+  const next = upsertBlock(body, blockLines.join(eol), eol);
+  writeFileSync(absPath, (bom ? '\uFEFF' : '') + next);
+  return existed;
+}
+
+/**
+ * True when the file already contains a trimmed `@AGENTS.md` line anywhere
+ * (BOM- and CRLF-tolerant).
+ */
+export function importsAgents(absPath) {
+  let raw = '';
+  try { raw = readFileSync(absPath, 'utf8'); } catch { return false; }
+  const { body } = splitBom(raw);
+  return body.split(/\r?\n/).some((l) => l.trim() === '@AGENTS.md');
+}
+
+/** Strip the managed block from a file on disk, preserving BOM. */
+export function stripManagedFile(absPath) {
+  let raw = '';
+  try { raw = readFileSync(absPath, 'utf8'); } catch { return { hadBlock: false }; }
+  const { bom, body } = splitBom(raw);
+  const { content, hadBlock } = stripBlock(body);
+  if (hadBlock) writeFileSync(absPath, (bom ? '\uFEFF' : '') + content);
+  return { hadBlock };
+}
+
+function renderRow(row) {
+  const cells = Array.isArray(row)
+    ? row.map(String)
+    : [row.feature ?? row.name ?? '', row.status ?? '', row.updated ?? ''].map(String);
+  return '| ' + cells.join(' | ') + ' |';
+}
+
+/**
+ * Replace the content between the archgen:features markers in a file with the
+ * registry table (header rows plus `rows`). When the markers are missing but
+ * the managed block exists, the registry section is inserted before its END
+ * marker. Never touches anything outside the markers.
+ * @param {string} fileAbsPath absolute path to AGENTS.md-style file
+ * @param {Array<string[]|{feature:string,status:string,updated:string}>} rows
+ * @returns {string} the new file content
+ */
+export function upsertFeaturesRegistry(fileAbsPath, rows = []) {
+  const raw = readFileSync(fileAbsPath, 'utf8');
+  const table = [
+    '| Feature | Status | Updated |',
+    '| --- | --- | --- |',
+    ...rows.map(renderRow),
+  ].join('\n');
+  const s = raw.indexOf(FEATURES_START);
+  const e = raw.indexOf(FEATURES_END);
+  let next;
+  if (s !== -1 && e !== -1 && e > s) {
+    next = raw.slice(0, s + FEATURES_START.length) + '\n' + table + '\n' + raw.slice(e);
+  } else if (s === -1 && e === -1) {
+    const bStart = raw.indexOf(START);
+    const bEnd = raw.indexOf(END);
+    if (bStart === -1 || bEnd === -1 || bEnd < bStart) {
+      throw new Error('no archgen managed block - cannot place features registry');
+    }
+    const section = '\n## Features registry\n\n' + FEATURES_START + '\n' + table + '\n' + FEATURES_END + '\n';
+    next = raw.slice(0, bEnd) + section + raw.slice(bEnd);
+  } else {
+    throw new Error('found only one archgen:features marker - fix or remove it manually');
+  }
+  if (next !== raw) writeFileSync(fileAbsPath, next);
+  return next;
+}

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,6 +1,6 @@
 {
   "name": "archgen-skill",
-  "version": "0.0.2",
+  "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",

package/vendor/skills/archgen/SKILL.md

@@ -34,7 +34,8 @@ Do NOT load for plain bug fixes or one-line edits that need no planning.
 1. **Everything you generate goes inside `.archgen/<project-slug>/`** at the
    target repo root. NEVER write generated artifacts anywhere else. The only
    files you may touch outside `.archgen/` are source-code edits performed by
-   worker sub-agents for approved tasks.
+   worker sub-agents for approved tasks and the `AGENTS.md` features registry,
+   maintained exclusively via `scripts/update-agents.mjs`.
 2. **Two gates before execution**: (a) the VERIFIER sub-agent must return
    APPROVE on plan+tasks, then (b) the USER must approve. Never skip either.
 3. **Right-size every generation.** Classify scope BEFORE creating files:
@@ -98,9 +99,13 @@ Pick ONE mode from the user's intent and follow its section below:
    Use templates from references/artifact-templates.md. Every task needs:
    id, title, depends_on (prerequisite ids), file_ownership (disjoint globs!),
    acceptance criteria, and status left unset (resolver derives readiness).
-4. **Self-check:** run
+   If `<slug>` already exists under `.archgen/`, pick `<slug>-2`, `<slug>-3`, …
+   — NEVER overwrite or merge into an existing feature folder.
+4. **Self-check + registry:** run
    `node <skill>/scripts/validate.mjs .archgen/<slug>/tasks.yaml`
-   Fix until exit 0.
+   Fix until exit 0. Then refresh the AGENTS.md features registry:
+   `node <skill>/scripts/update-agents.mjs <repo-root> --slug <slug> --status planned`.
+   Re-run it after ANY later artifact update so AGENTS.md never goes stale.
 5. **VERIFIER GATE.** Dispatch a verifier sub-agent (brief in
    references/orchestration.md §verifier). It must also run
    `node <skill>/scripts/verify-plan.mjs .archgen/<slug>/tasks.yaml --plan .archgen/<slug>/plans`
@@ -145,6 +150,8 @@ Run from the target repo root where `.archgen/<slug>/` exists.
      `set-status.mjs <id> done` on success (or `failed` on failure) and commit.
 4. After the wave settles: re-run next-tasks. Failed tasks are NOT retried
    automatically — surface them, propose a fix task, [wait for user].
+   Refresh the registry so AGENTS.md tracks the new statuses:
+   `node <skill>/scripts/update-agents.mjs <repo-root>`.
 5. Repeat until no actionable tasks remain.
 6. Final report: tasks done/failed/blocked, commits produced, suggested
    follow-ups. Update `.archgen/<slug>/plans/*.md` checkboxes if present.
@@ -197,6 +204,8 @@ When a task domain matches an entry in `assets/skill-registry.json`
 ## Things you must NOT do
 
 - Do NOT write artifacts outside `.archgen/<slug>/`.
+- Do NOT reuse or overwrite an existing `.archgen/<slug>/` folder — suffix
+  `-2`, `-3`, … instead (multi-feature repos must stay isolated).
 - Do NOT skip the verifier gate or the user gate — ever, even for SMALL scopes.
 - Do NOT implement features yourself; dispatch workers.
 - Do NOT put two same-wave tasks on overlapping file_ownership globs.
@@ -225,6 +234,8 @@ When a task domain matches an entry in `assets/skill-registry.json`
 scripts/next-tasks.mjs  <tasks.yaml>                       # waves JSON
 scripts/validate.mjs    <tasks.yaml> [--plan <dir>]        # exit 0/1
 scripts/set-status.mjs  <tasks.yaml> <id> <status> [--force]
+scripts/update-agents.mjs <projectRoot> [--slug <s>] [--status <s>] [--prune]
+                        # AGENTS.md features registry
 scripts/impact.mjs      <tasks.yaml> <id-or-artifactPath>  # ripple JSON
 scripts/verify-plan.mjs <tasks.yaml> --plan <dir>          # APPROVE|ISSUES
 ```

package/vendor/skills/archgen/references/platforms.md

@@ -23,6 +23,23 @@ confirmed. The orchestrator loads ONLY the row matching Step-0 detection.
 Universal fallback: `.agents/skills/` project + `~/.agents/skills/` user works
 across most harnesses. Primary distribution: `npx skills add <repo>` (75+ agents).
 
+## archgen installed layout
+
+`install.sh` / `npx archgen-skill install` maintain ONE canonical store plus
+thin bridges — the skill is never copied twice:
+
+| Path | Role |
+|---|---|
+| `.agents/skills/archgen/` | Canonical store — `SKILL.md`, `scripts/`, `references/`, `assets/` |
+| `.claude/skills/archgen` | Optional symlink → canonical store, for Claude Code discovery |
+| `CLAUDE.md` | One-line `@AGENTS.md` bridge only — no content of its own |
+| `AGENTS.md` | The hub every harness reads; hosts the features registry between `<!-- archgen:features:start -->` and `<!-- archgen:features:end -->` |
+
+The registry table (`| Feature | Status | Updated |`, one row per
+`.archgen/<slug>/`) is machine-maintained by `scripts/update-agents.mjs` after
+every generate/plan/wave run — never hand-edit it; edit `.archgen/` state and
+re-run the script instead.
+
 ## MCP configuration
 
 Four different top-level keys exist — NEVER assume `mcpServers`:

package/vendor/skills/archgen/scripts/update-agents.mjs

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+// update-agents.mjs — keeps the AGENTS.md features registry in sync with .archgen/.
+// Usage: node update-agents.mjs <projectRoot> [--slug <s>] [--status <s>] [--prune]
+// Scans .archgen/*/tasks.yaml and rewrites the table between the
+// <!-- archgen:features:start --> / <!-- archgen:features:end --> markers in
+// <projectRoot>/AGENTS.md, preserving every byte outside the block (BOM and
+// CRLF line endings included). A missing AGENTS.md gets a minimal scaffold; an
+// existing file without markers gets them appended. Rows whose feature folder
+// disappeared are pruned by default (--prune is accepted as the explicit
+// no-op spelling of the same behavior). Writes atomically via temp + rename.
+// Exit codes: 0 ok · 2 no .archgen/ dir · 4 usage/IO/marker errors.
+import { existsSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseYaml } from './lib/yaml.mjs';
+
+const START_MARKER = '<!-- archgen:features:start -->';
+const END_MARKER = '<!-- archgen:features:end -->';
+const HEADER = '| Feature | Status | Updated |';
+const SEPARATOR = '| --- | --- | --- |';
+const DISPLAY_STATUSES = ['planned', 'in progress', 'done', 'blocked', 'unknown'];
+// Task-level statuses set-status.mjs may write; anything else in tasks.yaml
+// means the file is not a contract we can read -> row falls back to unknown.
+const TASK_STATUSES = new Set(['pending', 'ready', 'running', 'blocked', 'done', 'failed']);
+
+// ---- arguments ------------------------------------------------------------
+const [projectRoot, ...flags] = process.argv.slice(2);
+let slug = null;
+let status = null;
+let pruneFlag = false; // pruning is always on; the flag just makes it explicit
+for (let i = 0; i < flags.length; i++) {
+  const arg = flags[i];
+  if (arg === '--slug' || arg === '--status') {
+    const value = flags[++i];
+    if (value === undefined) { console.error(`${arg} requires a value`); process.exit(4); }
+    if (arg === '--slug') slug = value;
+    else status = value;
+  } else if (arg === '--prune') {
+    pruneFlag = true;
+  } else {
+    console.error(`unknown argument '${arg}'`);
+    process.exit(4);
+  }
+}
+if (!projectRoot) {
+  console.error('usage: update-agents.mjs <projectRoot> [--slug <s>] [--status <s>] [--prune]');
+  process.exit(4);
+}
+if ((slug === null) !== (status === null)) {
+  console.error('--slug and --status must be passed together');
+  process.exit(4);
+}
+if (status !== null && !DISPLAY_STATUSES.includes(status)) {
+  console.error(`invalid status '${status}' (allowed: ${DISPLAY_STATUSES.join('|')})`);
+  process.exit(4);
+}
+if (slug !== null && !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(slug)) {
+  console.error(`invalid slug '${slug}' (start alphanumeric; then letters, digits, '.', '_', '-')`);
+  process.exit(4);
+}
+
+// ---- scan .archgen/*/tasks.yaml -------------------------------------------
+const archgenDir = join(projectRoot, '.archgen');
+if (!existsSync(archgenDir)) {
+  console.error(`no .archgen/ directory under ${projectRoot} — nothing to register (generate a plan first)`);
+  process.exit(2);
+}
+
+/** Date -> YYYY-MM-DD (local time, zero-padded). */
+function fmtDate(d) {
+  const mm = String(d.getMonth() + 1).padStart(2, '0');
+  const dd = String(d.getDate()).padStart(2, '0');
+  return `${d.getFullYear()}-${mm}-${dd}`;
+}
+
+/**
+ * Derive the one-word registry status from a parsed tasks.yaml `tasks`
+ * sequence. Precedence: unreadable -> unknown; any blocked -> blocked; all
+ * done -> done; all pending/ready -> planned; everything else (any running,
+ * or a done/pending/failed mix) -> in progress.
+ */
+function deriveStatus(tasks) {
+  if (!Array.isArray(tasks)) return 'unknown';
+  const statuses = [];
+  for (const t of tasks) {
+    if (t === null || typeof t !== 'object' || Array.isArray(t)) return 'unknown';
+    const s = String(t.status ?? 'pending').trim().toLowerCase(); // SKILL.md leaves status unset until wave resolution
+    if (!TASK_STATUSES.has(s)) return 'unknown';
+    statuses.push(s);
+  }
+  if (statuses.length === 0) return 'planned'; // scaffolded folder, no entries yet
+  if (statuses.includes('blocked')) return 'blocked';
+  if (statuses.every((s) => s === 'done')) return 'done';
+  if (statuses.every((s) => s === 'pending' || s === 'ready')) return 'planned';
+  return 'in progress';
+}
+
+/** @type {Map<string, {feature: string, status: string, updated: string}>} */
+const rows = new Map();
+for (const ent of readdirSync(archgenDir, { withFileTypes: true })) {
+  if (!ent.isDirectory()) continue;
+  const tasksPath = join(archgenDir, ent.name, 'tasks.yaml');
+  if (!existsSync(tasksPath)) continue; // the scan target is exactly */tasks.yaml
+  let derived = 'unknown';
+  try {
+    const { data } = parseYaml(readFileSync(tasksPath, 'utf8'), { filename: tasksPath });
+    derived = deriveStatus(data?.tasks);
+  } catch {
+    derived = 'unknown'; // unparseable YAML is data about the feature, not a crash
+  }
+  rows.set(ent.name, { feature: ent.name, status: derived, updated: fmtDate(statSync(tasksPath).mtime) });
+}
+
+// ---- upsert override (--slug/--status, run right after generating) --------
+if (slug !== null) {
+  const existing = rows.get(slug);
+  if (existing) existing.status = status;
+  else rows.set(slug, { feature: slug, status, updated: fmtDate(new Date()) });
+}
+
+const ordered = [...rows.values()].sort((a, b) => (a.feature < b.feature ? -1 : a.feature > b.feature ? 1 : 0));
+
+// ---- render -----------------------------------------------------------------
+function renderTable(eol) {
+  const lines = [HEADER, SEPARATOR, ...ordered.map((r) => `| ${r.feature} | ${r.status} | ${r.updated} |`)];
+  return lines.join(eol) + eol;
+}
+
+/** Parse the CURRENT registry rows out of an existing AGENTS.md (or null). */
+function oldRowsFrom(raw) {
+  const si = raw.indexOf(START_MARKER);
+  if (si === -1) return null;
+  const ei = raw.indexOf(END_MARKER, si + START_MARKER.length);
+  if (ei === -1) return null;
+  const old = new Map();
+  for (const line of raw.slice(si + START_MARKER.length, ei).split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t.startsWith('|') || t === HEADER || t === SEPARATOR) continue;
+    const cells = t.split('|').slice(1, -1).map((c) => c.trim());
+    if (!cells[0]) continue;
+    old.set(cells[0], { status: cells[1] ?? '', updated: cells[2] ?? '' });
+  }
+  return old;
+}
+
+const agentsPath = join(projectRoot, 'AGENTS.md');
+let raw = null;
+try { raw = readFileSync(agentsPath, 'utf8'); } catch { /* missing -> scaffold below */ }
+const oldRows = raw === null ? new Map() : (oldRowsFrom(raw) ?? new Map());
+
+let out;
+let banner;
+if (raw === null) {
+  // Missing AGENTS.md: minimal scaffold — H1, pointer paragraph, markers+table.
+  banner = `created ${agentsPath}`;
+  out = '# Agent Guide\n'
+    + '\n'
+    + 'This project uses the archgen skill at `.agents/skills/archgen/SKILL.md` for architecture generation and autonomous task execution.\n'
+    + '\n'
+    + START_MARKER + '\n'
+    + renderTable('\n')
+    + END_MARKER + '\n';
+} else if (!raw.includes(START_MARKER)) {
+  // Existing user file: append newline + markers + table; prior bytes untouched.
+  banner = `appended features registry to ${agentsPath}`;
+  const eol = raw.includes('\r\n') ? '\r\n' : '\n';
+  out = raw + eol + START_MARKER + eol + renderTable(eol) + END_MARKER + '\n';
+} else {
+  // Markers present: replace ONLY the span between them; every outside byte
+  // (BOM, prose, trailing sections, CRLF endings) survives verbatim.
+  const si = raw.indexOf(START_MARKER);
+  const ei = raw.indexOf(END_MARKER, si + START_MARKER.length);
+  if (ei === -1) {
+    console.error(`${agentsPath}: found ${START_MARKER} but no ${END_MARKER} — repair the markers by hand`);
+    process.exit(4);
+  }
+  banner = `updated features registry in ${agentsPath}`;
+  const eol = raw.includes('\r\n') ? '\r\n' : '\n';
+  out = raw.slice(0, si + START_MARKER.length) + eol + renderTable(eol) + raw.slice(ei);
+}
+
+// ---- human summary ----------------------------------------------------------
+const notes = [];
+for (const feature of oldRows.keys()) {
+  if (!rows.has(feature)) notes.push(`pruned: ${feature} (missing .archgen/${feature}/tasks.yaml)`);
+}
+let unchanged = 0;
+for (const r of ordered) {
+  const prev = oldRows.get(r.feature);
+  if (!prev) notes.push(`added: ${r.feature} (${r.status})`);
+  else if (prev.status !== r.status) notes.push(`updated: ${r.feature} (${prev.status || '?'} -> ${r.status})`);
+  else if (prev.updated !== r.updated) notes.push(`updated: ${r.feature} (${r.updated})`);
+  else unchanged++;
+}
+
+const tmp = `${agentsPath}.tmp-${process.pid}-${Date.now()}`;
+writeFileSync(tmp, out);
+renameSync(tmp, agentsPath); // atomic on POSIX: readers observe old-or-new, never partial
+
+console.log(banner);
+for (const n of notes) console.log(n);
+if (unchanged) console.log(`unchanged: ${unchanged}`);
+console.log(`registry: ${ordered.length} feature${ordered.length === 1 ? '' : 's'}`);