archgen-skill 0.0.1 → 0.0.3

package/README.md

@@ -0,0 +1,156 @@
+<div align="center">
+
+# archgen-skill
+
+**Conversational architecture generation & autonomous task execution for coding agents.**
+
+[![CI](https://github.com/akashmaurya99/archgen/actions/workflows/ci.yml/badge.svg)](https://github.com/akashmaurya99/archgen/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/akashmaurya99/archgen/blob/main/LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+
+Describe what you want to build. archgen interviews you (or surveys your existing
+codebase), produces an architecture contract plus a dependency-ordered task graph,
+verifies the plan, then executes it wave-by-wave through sub-agents.
+
+Works as an agent skill for **Claude Code · OpenCode · Cursor · Codex · Gemini CLI ·
+Antigravity** — and any [agentskills.io](https://agentskills.io)-compatible harness.
+
+</div>
+
+---
+
+## Install
+
+**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
+npx archgen-skill install          # symlinks; --copy for real copies
+```
+
+Prefer shell? Clone the repo and run `./install.sh` (same behavior, plus
+`--init`, `--project`, `--uninstall`). Requires Node.js ≥ 18.
+The skill itself has zero npm dependencies.
+
+## Quick start
+
+After `npx archgen-skill init`, open your project in any supported agent and talk naturally:
+
+| You say | What runs |
+| --- | --- |
+| *"generate architecture for a booking platform"* | Interview → artifacts → both gates |
+| *"add rate-limiting to my API server"* | Survey existing code first, then plan + gates |
+| *"start work"* | Autonomous wave execution until done or blocked |
+| *"roll back the auth changes"* | Impact analysis → reverse-order revert plan → approval |
+
+Everything archgen produces lives in one reviewable `.archgen/<slug>/` folder —
+architecture contract, docs, ADRs, plans, and a `tasks.yaml` task graph — versioned by git.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `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
+
+AI coding agents fail at scale for predictable reasons: plans with hidden cycles,
+workers editing the same files, tasks without objective acceptance criteria, and no
+human checkpoint before execution. archgen makes each of these a *structural*
+guarantee rather than a hope:
+
+| Guarantee | Mechanism |
+| --- | --- |
+| Plans are valid before work starts | Verifier gate — catches cycles, dangling refs, ownership overlaps, plan↔task coverage gaps |
+| You approve before code is written | Explicit user gate after verifier approval |
+| Parallel workers never collide | Disjoint `file_ownership` globs enforced per wave |
+| Task order is always correct | Topological waves from `depends_on`; chains stay sequential |
+| Failures never cascade silently | Failed tasks exclude downstream into `blockedByFailure`, surfaced to you |
+| Every artifact is reviewable | Everything in one `.archgen/<slug>/` folder, versioned by git |
+
+```text
+ interview (greenfield)  ·  survey (brownfield)
+              │
+              ▼
+   .archgen/<slug>/  ── architecture.yaml · docs · ADRs · plans · tasks.yaml
+              │
+              ▼
+   VERIFIER GATE ──issues──► fix & re-verify
+              │ APPROVE
+              ▼
+   USER GATE ────reject───► revise
+              │ approve
+              ▼
+   WAVES ── topological order · one sub-agent per task · disjoint ownership
+              │
+              ▼
+   final report: done / failed / blocked · commits · follow-ups
+```
+
+## Supported harnesses
+
+| Harness | Global install | Project-local (`init`) |
+| --- | --- | --- |
+| Claude Code | ✅ | ✅ |
+| OpenCode | ✅ | ✅ |
+| Cursor | ✅ | ✅ |
+| Codex | ✅ | ✅ |
+| Gemini CLI | ✅ | ✅ |
+| Antigravity | ✅ | ✅ |
+| Any agentskills.io harness | ✅ | ✅ |
+
+## VS Code extension (optional)
+
+A read-only visual layer that renders `.archgen/` as a live task DAG (running tasks
+pulse, edges animate), your code-dependency graph, and rendered docs — with a ▶
+button that launches your agent on any task. Install the `.vsix` from
+[GitHub Releases](https://github.com/akashmaurya99/archgen/releases). It is strictly
+a viewer: uninstalling it loses nothing.
+
+## Documentation
+
+| Doc | Contents |
+| --- | --- |
+| [Architecture walkthrough](https://github.com/akashmaurya99/archgen/blob/main/docs/architecture.md) | Dual-mode design, gates, wave mechanics, platform detection |
+| [The skill contract](https://github.com/akashmaurya99/archgen/blob/main/skill/SKILL.md) | The full skill specification agents execute |
+| [Changelog](https://github.com/akashmaurya99/archgen/blob/main/CHANGELOG.md) | Release history |
+| [Contributing](https://github.com/akashmaurya99/archgen/blob/main/CONTRIBUTING.md) | Development setup and PR guide |
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/akashmaurya99/archgen/blob/main/CONTRIBUTING.md).
+Skill suite and CLI tests run with zero dependencies:
+
+```sh
+node --test skill/scripts/test/*.test.mjs   # skill suite
+cd packages/cli && npm test                 # CLI suite
+```
+
+## License
+
+[MIT](https://github.com/akashmaurya99/archgen/blob/main/LICENSE) © ArchGen contributors

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,23 +15,53 @@ 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/akash/archgen`;
+Docs: https://github.com/akashmaurya99/archgen`;
 
 const [, , cmd, ...rest] = process.argv;
 
@@ -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;
+}