@argenalimbaev/template-agent 1.0.0

package/scripts/recommend-template.mjs

@@ -0,0 +1,39 @@
+import { readFileSync, existsSync, realpathSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readRegistry, availableTemplates } from './registry.mjs';
+
+// The host AI extracts requirements. This helper checks constraints, not natural language.
+export function recommend(registry, requirements) {
+  const allowed = new Set(['requiredCapabilities', 'preferredCapabilities', 'excludedCapabilities', 'existingProject']);
+  if (!requirements || Object.keys(requirements).some(k => !allowed.has(k))) throw new Error('Invalid requirements fields.');
+  if (requirements.existingProject !== undefined && typeof requirements.existingProject !== 'boolean') throw new Error('existingProject must be boolean.');
+  for (const key of ['requiredCapabilities', 'preferredCapabilities', 'excludedCapabilities']) {
+    if (!Array.isArray(requirements[key]) || requirements[key].some(x => typeof x !== 'string' || !/^[a-z0-9-]+$/.test(x))) throw new Error(`Invalid ${key}.`);
+  }
+  if (requirements.existingProject) return { status: 'existing-project', candidates: [], reason: 'Inspect and modify existing code; do not scaffold over it.' };
+  const required = [...new Set(requirements.requiredCapabilities)];
+  const excluded = new Set(requirements.excludedCapabilities);
+  if (required.some(x => excluded.has(x))) return { status: 'conflicting-requirements', candidates: [] };
+  const preferred = [...new Set(requirements.preferredCapabilities)];
+  const considered = availableTemplates(registry).map(entry => ({
+    entry,
+    missing: required.filter(x => !entry.selection.capabilities.includes(x)),
+    conflicts: entry.selection.capabilities.filter(x => excluded.has(x)),
+    preferenceMatches: preferred.filter(x => entry.selection.capabilities.includes(x)).length,
+  }));
+  const candidates = considered.filter(x => !x.missing.length && !x.conflicts.length).sort((a, b) => b.preferenceMatches - a.preferenceMatches || a.entry.selection.complexity - b.entry.selection.complexity);
+  const details = candidates.map(x => ({ id: x.entry.id, preferenceMatches: x.preferenceMatches, complexity: x.entry.selection.complexity, limitations: x.entry.selection.limitations }));
+  if (!details.length) return { status: 'no-match', candidates: [], rejected: considered.map(x => ({ id: x.entry.id, missing: x.missing, conflicts: x.conflicts })) };
+  const [first, second] = details;
+  const tied = second && first.preferenceMatches === second.preferenceMatches && first.complexity === second.complexity;
+  return { status: tied ? 'ambiguous' : 'selected', ...(tied ? {} : { template: first.id }), candidates: details };
+}
+
+if (process.argv[1] && existsSync(process.argv[1]) && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    if (process.argv.length !== 3) throw new Error('Usage: node scripts/recommend-template.mjs <requirements.json>');
+    const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+    console.log(JSON.stringify(recommend(readRegistry(resolve(root, 'registry/templates.json')), JSON.parse(readFileSync(process.argv[2], 'utf8'))), null, 2));
+  } catch (error) { console.error(`ERROR: ${error.message}`); process.exitCode = 1; }
+}

package/scripts/registry.mjs

@@ -0,0 +1,52 @@
+import { readFileSync } from 'node:fs';
+
+const token = value => typeof value === 'string' && /^[a-z0-9-]+$/.test(value);
+const strings = value => Array.isArray(value) && value.every(x => typeof x === 'string' && x.trim());
+const tokens = value => strings(value) && value.every(token) && new Set(value).size === value.length;
+export const safePath = value => typeof value === 'string' && value.length > 0 && !value.includes('\\') && !value.startsWith('/') && !value.includes(':') && value.split('/').every(p => p && !['.', '..', '.git'].includes(p));
+
+function validRepository(value) {
+  if (/^\.\.?\/[^\s]+$/.test(value)) return true; // Explicit local test/development source.
+  if (/^git@[a-zA-Z0-9.-]+:[\w./-]+$/.test(value)) return !value.includes('/../');
+  try {
+    const url = new URL(value);
+    return url.protocol === 'https:' && !!url.hostname && !url.username && !url.password && !url.search && !url.hash && url.pathname !== '/' && !/\s/.test(value);
+  } catch { return false; }
+}
+
+export function validateRegistry(registry) {
+  if (![2, 3].includes(registry?.version) || !Array.isArray(registry.templates)) throw new Error('Registry requires version 2 or 3 and templates array.');
+  const allowedRegistryFields = new Set(registry.version === 3 ? ['version', 'minCliVersion', 'templates'] : ['version', 'templates']);
+  if (Object.keys(registry).some(key => !allowedRegistryFields.has(key))) throw new Error('Unknown registry field; executable hooks are forbidden.');
+  if (registry.version === 3 && (typeof registry.minCliVersion !== 'string' || !/^\d+\.\d+\.\d+$/.test(registry.minCliVersion))) {
+    throw new Error('Registry version 3 requires minCliVersion.');
+  }
+  const ids = new Set();
+  const allowed = new Set(['id', 'name', 'description', 'profile', 'repository', 'ref', 'commit', 'stack', 'skills', 'enabled', 'selection', 'project']);
+  for (const entry of registry.templates) {
+    if (!entry || typeof entry !== 'object' || !token(entry.id) || ids.has(entry.id)) throw new Error('Invalid/duplicate template ID.');
+    ids.add(entry.id);
+    if (Object.keys(entry).some(key => !allowed.has(key))) throw new Error('Unknown registry field; executable hooks are forbidden.');
+    for (const key of ['name', 'description', 'profile', 'repository', 'ref']) {
+      if (typeof entry[key] !== 'string' || !entry[key].trim()) throw new Error(`Missing ${key}: ${entry.id}`);
+    }
+    if (typeof entry.enabled !== 'boolean') throw new Error('enabled must be boolean.');
+    if (!/^v\d+\.\d+\.\d+$/.test(entry.ref)) throw new Error('Use a versioned release tag.');
+    if (entry.commit !== undefined && !/^[a-f0-9]{40}$/.test(entry.commit)) throw new Error('Invalid commit pin.');
+    if (!entry.repository.startsWith('.') && !entry.commit) throw new Error('Remote releases require a commit pin.');
+    if (!tokens(entry.stack) || !entry.stack.length || !tokens(entry.skills) || !entry.skills.length || !token(entry.profile)) throw new Error('Invalid stack, skills or profile.');
+    if (!validRepository(entry.repository)) throw new Error('Use HTTPS, Git SSH or an explicit relative development source; never embedded credentials.');
+    const s = entry.selection;
+    if (!s || Object.keys(s).some(k => !['capabilities', 'useWhen', 'avoidWhen', 'limitations', 'complexity'].includes(k)) || !tokens(s.capabilities) || !s.capabilities.length || !strings(s.useWhen) || !s.useWhen.length || !strings(s.avoidWhen) || !strings(s.limitations) || !Number.isInteger(s.complexity) || s.complexity < 1) throw new Error('Invalid selection metadata.');
+    const p = entry.project;
+    if (!p || Object.keys(p).some(k => !['renamePackage', 'requiredFiles'].includes(k)) || typeof p.renamePackage !== 'boolean' || !Array.isArray(p.requiredFiles) || !p.requiredFiles.every(safePath)) throw new Error('Invalid project contract.');
+    if (p.renamePackage && !p.requiredFiles.includes('package.json')) throw new Error('Renaming requires root package.json in requiredFiles.');
+  }
+  return registry;
+}
+
+export function readRegistry(file) {
+  return validateRegistry(JSON.parse(readFileSync(file, 'utf8')));
+}
+
+export const availableTemplates = registry => registry.templates.filter(entry => entry.enabled);

package/scripts/skill-adapters.mjs

@@ -0,0 +1,30 @@
+import { readFileSync, writeFileSync, mkdirSync, rmSync, lstatSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const adapters = ['.agents/skills', '.claude/skills', '.codex/skills'];
+
+export function writeSkillAdapters(directory, skills) {
+  for (const adapter of adapters) {
+    // Remove the checkout's legacy link (or Git's text representation on Windows), not its destination.
+    rmSync(join(directory, adapter), { recursive: true, force: true });
+    for (const name of skills) {
+      const canonical = `.ai/skills/${name}/SKILL.md`;
+      const text = readFileSync(join(directory, canonical), 'utf8');
+      const frontmatter = text.match(/^---\r?\n[\s\S]*?\r?\n---/)?.[0];
+      if (!frontmatter) throw new Error(`Skill needs YAML frontmatter: ${name}`);
+      const folder = join(directory, adapter, name);
+      mkdirSync(folder, { recursive: true });
+      writeFileSync(join(folder, 'SKILL.md'), `${frontmatter}\n\nRead the canonical skill at project root: \`${canonical}\`.\nResolve its references and scripts relative to the canonical skill directory, not this forwarding file.\nProject AGENTS.md and actual source override generic skill examples.\n`);
+    }
+  }
+}
+
+export function validateSkillAdapters(directory, skills) {
+  for (const adapter of adapters) {
+    if (!lstatSync(join(directory, adapter)).isDirectory() || lstatSync(join(directory, adapter)).isSymbolicLink()) throw new Error('Expected portable adapter directory.');
+    for (const name of skills) {
+      const file = join(directory, adapter, name, 'SKILL.md');
+      if (!readFileSync(file, 'utf8').includes(`.ai/skills/${name}/SKILL.md`)) throw new Error(`Invalid forwarding skill: ${file}`);
+    }
+  }
+}

package/scripts/template-ai-contract.mjs

@@ -0,0 +1,56 @@
+import { lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { isAbsolute, join, relative, sep } from 'node:path';
+
+const adapters = ['.agents/skills', '.claude/skills', '.codex/skills'];
+const key = value => typeof value === 'string' && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value);
+const object = value => !!value && typeof value === 'object' && !Array.isArray(value);
+const list = value => Array.isArray(value) && value.every(key) && new Set(value).size === value.length;
+const exact = (value, keys) => object(value) && Object.keys(value).every(key => keys.includes(key)) && keys.every(key => Object.hasOwn(value, key));
+
+function local(root, path, directory = false) {
+  const resolved = realpathSync(join(root, path));
+  const rel = relative(realpathSync(root), resolved);
+  if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) throw new Error(`Unsafe path: ${path}`);
+  const stat = lstatSync(resolved);
+  if (directory ? !stat.isDirectory() : !stat.isFile()) throw new Error(`Invalid path type: ${path}`);
+  return resolved;
+}
+
+const read = (root, path) => readFileSync(local(root, path), 'utf8');
+
+export function readManifest(root) {
+  const manifest = JSON.parse(read(root, '.ai/workflows.json'));
+  if (!exact(manifest, ['version', 'skills', 'tasks', 'risks']) || manifest.version !== 1 || !list(manifest.skills) || !manifest.skills.length || !object(manifest.tasks) || !Object.keys(manifest.tasks).length || !object(manifest.risks)) {
+    throw new Error('Invalid workflow manifest.');
+  }
+  for (const [name, task] of Object.entries(manifest.tasks)) {
+    if (!key(name) || !exact(task, ['mode', 'skills']) || !['read', 'change'].includes(task.mode) || !list(task.skills) || task.skills.some(skill => !manifest.skills.includes(skill))) throw new Error(`Invalid task: ${name}`);
+  }
+  for (const [name, risk] of Object.entries(manifest.risks)) {
+    if (!key(name) || !exact(risk, ['skills', 'checks']) || !list(risk.skills) || risk.skills.some(skill => !manifest.skills.includes(skill)) || !Array.isArray(risk.checks) || !risk.checks.length || risk.checks.some(check => typeof check !== 'string' || !check.trim())) throw new Error(`Invalid risk: ${name}`);
+  }
+  return manifest;
+}
+
+export function validateTemplateAiContract(root) {
+  const manifest = readManifest(root);
+  for (const name of ['project-documentation-wiki', 'graphify']) {
+    if (!manifest.skills.includes(name)) throw new Error(`Required knowledge skill missing: ${name}`);
+  }
+  for (const path of ['AGENTS.md', '.ai/context.mjs', '.ai/WORKFLOW.md', '.codex-harness/AGENT_GRAPH.md', '.codex-harness/VERIFICATION.md', '.wiki/index.md']) local(root, path);
+  const inventory = readdirSync(local(root, '.ai/skills', true)).sort();
+  if (JSON.stringify(inventory) !== JSON.stringify([...manifest.skills].sort())) throw new Error('Skill inventory differs from manifest.');
+  for (const name of manifest.skills) {
+    const text = read(root, `.ai/skills/${name}/SKILL.md`);
+    const frontmatter = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!frontmatter || !frontmatter[1].split(/\r?\n/).includes(`name: ${name}`) || !/^description:\s*\S/m.test(frontmatter[1])) throw new Error(`Invalid skill metadata: ${name}`);
+    for (const adapter of adapters) {
+      const adapterPath = join(root, adapter);
+      if (lstatSync(adapterPath).isSymbolicLink()) throw new Error(`Unsafe adapter link: ${adapter}`);
+      local(root, adapter, true);
+      const forward = read(root, `${adapter}/${name}/SKILL.md`);
+      if (!forward.includes(`.ai/skills/${name}/SKILL.md`) || !forward.startsWith(frontmatter[0])) throw new Error(`Invalid adapter: ${adapter}/${name}`);
+    }
+  }
+  return { status: 'valid', skills: manifest.skills.length };
+}

package/skills/arg3n41ck-frontend-project/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: arg3n41ck-frontend-project
+description: Select and create a new frontend project from the Template Agent catalog. Use when the user explicitly asks to start, scaffold, generate, or create a new React, Next.js, CRM dashboard, fullstack project, or new layout from scratch. Do not use for architecture discussion or changes inside an existing project.
+---
+
+Use this flow only when the user wants a new project and a terminal is available.
+
+1. Confirm the target does not already contain a project. Never scaffold over existing code.
+2. Run `npx --yes @argenalimbaev/template-agent@1 list --json` and read the current catalog.
+3. Translate the request into factual capabilities. Do not infer a backend merely from CRM, SaaS, auth, API, or login. Use `recommend --requirements <file> --json` to check the decision.
+4. If one template is compatible, briefly state its ID, reason, and important limitation. If candidates are tied, no match exists, or a requested constraint conflicts with the catalog, ask one consequential question. Do not silently substitute a stack or merge templates.
+5. Create the project with `npx --yes @argenalimbaev/template-agent@1 create <new-directory> --template <id> --brief-file <accepted-brief-file>`. Do not install dependencies, run hooks, publish, or expose secrets.
+6. Read the generated project's `AGENTS.md`, its project brief, and verification guide. Continue implementation only when the user asked for work beyond starter creation.
+
+If the environment has no shell or filesystem access, explain that it cannot materialize a project and provide the manual CLI command. For manual creation, `npx --yes @argenalimbaev/template-agent@1 create` asks only for a template and project name.

package/src/catalog.mjs

@@ -0,0 +1,106 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { dirname, join } from 'node:path';
+import { validateRegistry } from '../scripts/registry.mjs';
+import { compareSemver } from './semver.mjs';
+
+export const CLI_VERSION = '1.0.0';
+export const CATALOG_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+export const MAX_CATALOG_BYTES = 1024 * 1024;
+export const DEFAULT_RELEASE_API_URL = 'https://api.github.com/repos/arg3n41ck/frontend-template-hub/releases?per_page=100';
+
+export function defaultCacheDirectory({ home = homedir(), env = process.env, os = platform() } = {}) {
+  if (os === 'darwin') return join(home, 'Library', 'Caches', 'template-agent');
+  if (os === 'win32') return join(env.LOCALAPPDATA || join(home, 'AppData', 'Local'), 'template-agent', 'Cache');
+  return join(env.XDG_CACHE_HOME || join(home, '.cache'), 'template-agent');
+}
+
+function catalogFile(cacheDirectory) {
+  return join(cacheDirectory, 'catalog.json');
+}
+
+function readCatalogFile(file) {
+  return validateRegistry(JSON.parse(readFileSync(file, 'utf8')));
+}
+
+function ensureCompatible(registry, cliVersion) {
+  if (registry.minCliVersion && compareSemver(cliVersion, registry.minCliVersion) < 0) {
+    throw new Error(`Catalog requires CLI ${registry.minCliVersion} or newer; run npx @argenalimbaev/template-agent@1 update.`);
+  }
+  return registry;
+}
+
+function saveCatalog(cacheDirectory, registry) {
+  mkdirSync(cacheDirectory, { recursive: true });
+  const file = catalogFile(cacheDirectory);
+  const temporary = `${file}.${process.pid}.tmp`;
+  writeFileSync(temporary, JSON.stringify(registry, null, 2) + '\n', { mode: 0o600 });
+  renameSync(temporary, file);
+}
+
+async function readResponseJson(response, label) {
+  if (!response.ok) throw new Error(`${label} returned HTTP ${response.status}.`);
+  const length = Number(response.headers.get('content-length') || '0');
+  if (length > MAX_CATALOG_BYTES) throw new Error(`${label} is too large.`);
+  const text = await response.text();
+  if (Buffer.byteLength(text) > MAX_CATALOG_BYTES) throw new Error(`${label} is too large.`);
+  return JSON.parse(text);
+}
+
+async function fetchRemoteCatalog({ fetchImpl, releaseApiUrl, timeoutMs }) {
+  const signal = AbortSignal.timeout(timeoutMs);
+  const releasesResponse = await fetchImpl(releaseApiUrl, {
+    headers: { accept: 'application/vnd.github+json', 'user-agent': 'template-agent' },
+    signal,
+  });
+  const releases = await readResponseJson(releasesResponse, 'Catalog release endpoint');
+  if (!Array.isArray(releases)) throw new Error('Catalog release endpoint returned an invalid payload.');
+  const release = releases.find(item => !item.draft && !item.prerelease && /^catalog-v\d+\.\d+\.\d+$/.test(item.tag_name));
+  const asset = release?.assets?.find(item => item.name === 'templates.json' && typeof item.browser_download_url === 'string');
+  if (!asset) throw new Error('No published catalog-v release with templates.json was found.');
+  const assetUrl = new URL(asset.browser_download_url);
+  if (assetUrl.protocol !== 'https:') throw new Error('Catalog asset must use HTTPS.');
+  const catalogResponse = await fetchImpl(assetUrl.href, {
+    headers: { accept: 'application/json', 'user-agent': 'template-agent' },
+    signal,
+  });
+  return validateRegistry(await readResponseJson(catalogResponse, 'Catalog asset'));
+}
+
+export async function resolveCatalog({
+  bundledRegistry,
+  cacheDirectory = defaultCacheDirectory(),
+  releaseApiUrl = DEFAULT_RELEASE_API_URL,
+  fetchImpl = globalThis.fetch,
+  cliVersion = CLI_VERSION,
+  forceRefresh = false,
+  timeoutMs = 10_000,
+  now = Date.now(),
+} = {}) {
+  if (!bundledRegistry) throw new Error('Bundled catalog is required.');
+  const cached = catalogFile(cacheDirectory);
+  if (!forceRefresh && existsSync(cached) && now - statSync(cached).mtimeMs < CATALOG_CACHE_TTL_MS) {
+    try {
+      return { registry: ensureCompatible(readCatalogFile(cached), cliVersion), source: 'cache', stale: false };
+    } catch (error) {
+      if (/requires CLI/.test(error.message)) throw error;
+      // A damaged cache is never trusted.
+    }
+  }
+  try {
+    const registry = ensureCompatible(await fetchRemoteCatalog({ fetchImpl, releaseApiUrl, timeoutMs }), cliVersion);
+    saveCatalog(cacheDirectory, registry);
+    return { registry, source: 'remote', stale: false };
+  } catch (error) {
+    if (/requires CLI/.test(error.message)) throw error;
+    if (existsSync(cached)) {
+      try {
+        return { registry: ensureCompatible(readCatalogFile(cached), cliVersion), source: 'cache', stale: true, warning: error.message };
+      } catch (cacheError) {
+        if (/requires CLI/.test(cacheError.message)) throw cacheError;
+        // Fall through to the bundled release.
+      }
+    }
+    return { registry: ensureCompatible(validateRegistry(bundledRegistry), cliVersion), source: 'bundled', stale: true, warning: error.message };
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,228 @@
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { createInterface } from 'node:readline/promises';
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createProject } from '../scripts/create-project.mjs';
+import { availableTemplates, readRegistry } from '../scripts/registry.mjs';
+import { recommend } from '../scripts/recommend-template.mjs';
+import { CLI_VERSION, defaultCacheDirectory, resolveCatalog } from './catalog.mjs';
+import { compareSemver } from './semver.mjs';
+import { detectClients, findDuplicateSkillNames, installSkill, skillTargets, uninstallSkill } from './skill-manager.mjs';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const skillSource = join(root, 'skills', 'arg3n41ck-frontend-project', 'SKILL.md');
+const bundledCatalog = () => readRegistry(join(root, 'registry', 'templates.json'));
+const valueOptions = new Set(['template', 'brief-file', 'requirements', 'client']);
+const booleanOptions = new Set(['json', 'dry-run', 'allow-third-party', 'keep-template-history', 'purge-cache', 'help']);
+const commands = new Set(['create', 'list', 'recommend', 'setup', 'doctor', 'update', 'check', 'uninstall', 'help']);
+const windowsReserved = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..*)?$/i;
+const optionKey = name => name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+
+export function parseArguments(argv) {
+  const [first = 'help', ...rest] = argv;
+  if (!commands.has(first)) throw new Error(`Unknown command: ${first}`);
+  const options = {};
+  let target;
+  for (let index = 0; index < rest.length; index += 1) {
+    const argument = rest[index];
+    if (argument === '--help' || argument === '-h') {
+      options.help = true;
+      continue;
+    }
+    if (argument.startsWith('--')) {
+      const name = argument.slice(2);
+      if (booleanOptions.has(name)) {
+        options[optionKey(name)] = true;
+        continue;
+      }
+      if (!valueOptions.has(name)) throw new Error(`Unknown option: ${argument}`);
+      const value = rest[++index];
+      if (!value || value.startsWith('--')) throw new Error(`${argument} needs a value.`);
+      options[optionKey(name)] = value;
+      continue;
+    }
+    if (target !== undefined) throw new Error('Only one target directory is allowed.');
+    target = argument;
+  }
+  return { command: first, ...(target === undefined ? {} : { target }), options };
+}
+
+export function validateInteractiveProjectName(value) {
+  const name = typeof value === 'string' ? value.trim() : '';
+  if (!name || name.length > 100 || name === '.' || name === '..' || windowsReserved.test(name)) throw new Error('Project name is invalid.');
+  if (name.includes('/') || name.includes('\\') || /[<>:"|?*\u0000-\u001f]/.test(name) || name.endsWith('.') || name.endsWith(' ')) throw new Error('Project name is invalid.');
+  return name;
+}
+
+function print(value, { json, output }) {
+  output(json ? JSON.stringify(value, null, 2) : value);
+}
+
+function isFirstParty(entry) {
+  try {
+    const source = new URL(entry.repository);
+    return source.protocol === 'https:' && source.hostname === 'github.com' && source.pathname.startsWith('/arg3n41ck/');
+  } catch {
+    return false;
+  }
+}
+
+function assertSourcePolicy(entry, allowThirdParty) {
+  if (!isFirstParty(entry) && !allowThirdParty) {
+    throw new Error(`Template ${entry.id} is not a first-party source. Re-run with --allow-third-party only after reviewing its repository.`);
+  }
+}
+
+function formatTemplates(templates) {
+  return templates.map((entry, index) => `${index + 1}. ${entry.name} (${entry.id}) — ${entry.description}`).join('\n');
+}
+
+async function interactivePrompt() {
+  const readline = createInterface({ input: process.stdin, output: process.stdout });
+  return {
+    ask: question => readline.question(question),
+    close: () => readline.close(),
+  };
+}
+
+async function chooseCreateArguments({ templates, target, template, prompt }) {
+  let selectedId = template;
+  if (!selectedId) {
+    const answer = await prompt.ask(`Choose a template:\n${formatTemplates(templates)}\n> `);
+    const selected = templates[Number(answer) - 1];
+    if (!selected) throw new Error('Choose a template number from the list.');
+    selectedId = selected.id;
+  }
+  let selectedTarget = target;
+  if (!selectedTarget) selectedTarget = validateInteractiveProjectName(await prompt.ask('Project name: '));
+  return { template: selectedId, target: selectedTarget };
+}
+
+function selectedClients(option, environment) {
+  if (option === 'all') return ['codex', 'claude'];
+  if (option) return [option];
+  const detected = detectClients(environment);
+  if (!detected.length) throw new Error('No supported client was detected. Use setup --client codex or setup --client claude.');
+  return detected;
+}
+
+function usage() {
+  return `Template Agent ${CLI_VERSION}\n\n` +
+    `npx --yes @argenalimbaev/template-agent@1 setup [--client codex|claude|all]\n` +
+    `npx --yes @argenalimbaev/template-agent@1 create [project-name] [--template id]\n` +
+    `template-agent list [--json]\n` +
+    `template-agent doctor | update | check [project-path] | uninstall`;
+}
+
+async function catalogForCommand(options, dependencies) {
+  return resolveCatalog({ bundledRegistry: bundledCatalog(), forceRefresh: !!options.forceRefresh, ...dependencies.catalog });
+}
+
+export async function runCli(argv, dependencies = {}) {
+  const parsed = parseArguments(argv);
+  const output = dependencies.output || (value => console.log(value));
+  const cwd = dependencies.cwd || process.cwd();
+  const environment = dependencies.environment || {};
+  if (parsed.options.help || parsed.command === 'help') {
+    output(usage());
+    return { status: 'help' };
+  }
+  if (parsed.command === 'setup' || parsed.command === 'uninstall') {
+    const clients = parsed.command === 'uninstall' && !parsed.options.client
+      ? ['codex', 'claude']
+      : selectedClients(parsed.options.client, environment);
+    const targets = skillTargets({ clients, ...environment });
+    const result = parsed.command === 'setup'
+      ? installSkill({ targets, source: skillSource, dryRun: !!parsed.options.dryRun })
+      : uninstallSkill({ targets, dryRun: !!parsed.options.dryRun });
+    const response = { skills: result };
+    if (parsed.command === 'uninstall' && parsed.options.purgeCache) {
+      const cache = dependencies.cacheDirectory || defaultCacheDirectory(environment);
+      if (!parsed.options.dryRun) rmSync(cache, { recursive: true, force: true });
+      response.cache = parsed.options.dryRun ? 'would-remove' : 'removed';
+    }
+    print(response, { json: !!parsed.options.json, output });
+    return response;
+  }
+  if (parsed.command === 'doctor') {
+    const nodeOk = compareSemver(process.versions.node, '22.14.0') >= 0;
+    let gitOk = true;
+    try { execFileSync('git', ['--version'], { stdio: 'ignore' }); } catch { gitOk = false; }
+    const catalog = await catalogForCommand({}, dependencies);
+    const clients = detectClients(environment);
+    const result = {
+      node: { version: process.versions.node, supported: nodeOk },
+      git: { supported: gitOk },
+      catalog: { source: catalog.source, stale: catalog.stale, warning: catalog.warning || null },
+      clients,
+      duplicateSkillFiles: findDuplicateSkillNames(environment),
+      ok: nodeOk && gitOk,
+    };
+    print(result, { json: !!parsed.options.json, output });
+    return result;
+  }
+  if (parsed.command === 'update') {
+    const catalog = await catalogForCommand({ forceRefresh: true }, dependencies);
+    const clients = detectClients(environment);
+    const skills = clients.length ? installSkill({ targets: skillTargets({ clients, ...environment }), source: skillSource, dryRun: !!parsed.options.dryRun }) : [];
+    const result = { catalog: { source: catalog.source, stale: catalog.stale, warning: catalog.warning || null }, skills };
+    print(result, { json: !!parsed.options.json, output });
+    return result;
+  }
+  const catalog = await catalogForCommand({}, dependencies);
+  const templates = availableTemplates(catalog.registry);
+  if (parsed.command === 'list') {
+    const result = { source: catalog.source, templates };
+    print(parsed.options.json ? result : formatTemplates(templates), { json: !!parsed.options.json, output });
+    return result;
+  }
+  if (parsed.command === 'recommend') {
+    if (!parsed.options.requirements) throw new Error('recommend needs --requirements <file>.');
+    const requirements = JSON.parse(readFileSync(resolve(cwd, parsed.options.requirements), 'utf8'));
+    const result = recommend(catalog.registry, requirements);
+    print(result, { json: true, output });
+    return result;
+  }
+  if (parsed.command === 'check') {
+    const project = resolve(cwd, parsed.target || '.');
+    const provenancePath = join(project, '.template-provenance.json');
+    if (!existsSync(provenancePath)) throw new Error(`No .template-provenance.json found in ${project}.`);
+    const provenance = JSON.parse(readFileSync(provenancePath, 'utf8'));
+    const current = templates.find(entry => entry.id === provenance.template);
+    const result = {
+      project,
+      template: provenance.template,
+      current: current ? { ref: current.ref, commit: current.commit } : null,
+      generated: { ref: provenance.ref, commit: provenance.commit },
+      updateAvailable: !!current && (current.ref !== provenance.ref || current.commit !== provenance.commit),
+    };
+    print(result, { json: !!parsed.options.json, output });
+    return result;
+  }
+  if (parsed.command !== 'create') throw new Error(`Unsupported command: ${parsed.command}`);
+  let prompt;
+  try {
+    if ((!parsed.options.template || !parsed.target) && !dependencies.prompt && !process.stdin.isTTY) {
+      throw new Error('create needs a project name and --template outside an interactive terminal.');
+    }
+    if (!parsed.options.template || !parsed.target) prompt = dependencies.prompt || await interactivePrompt();
+    const selected = await chooseCreateArguments({ templates, target: parsed.target, template: parsed.options.template, prompt });
+    const entry = templates.find(item => item.id === selected.template);
+    if (!entry) throw new Error('Unknown template ID. Run template-agent list.');
+    assertSourcePolicy(entry, !!parsed.options.allowThirdParty);
+    const target = isAbsolute(selected.target) ? selected.target : resolve(cwd, selected.target);
+    if (parsed.options.dryRun) {
+      const result = { target, template: entry.id, source: catalog.source, dryRun: true };
+      print(result, { json: true, output });
+      return result;
+    }
+    const brief = parsed.options.briefFile ? readFileSync(resolve(cwd, parsed.options.briefFile), 'utf8') : undefined;
+    const metadata = createProject({ entry, target, brief, keepHistory: !!parsed.options.keepTemplateHistory });
+    const result = { target, source: catalog.source, metadata };
+    print(result, { json: true, output });
+    return result;
+  } finally {
+    prompt?.close?.();
+  }
+}

package/src/semver.mjs

@@ -0,0 +1,16 @@
+const pattern = /^(\d+)\.(\d+)\.(\d+)$/;
+
+export function parseSemver(value) {
+  const match = typeof value === 'string' && value.match(pattern);
+  if (!match) throw new Error(`Invalid semantic version: ${value}`);
+  return match.slice(1).map(Number);
+}
+
+export function compareSemver(left, right) {
+  const a = parseSemver(left);
+  const b = parseSemver(right);
+  for (let index = 0; index < a.length; index += 1) {
+    if (a[index] !== b[index]) return a[index] > b[index] ? 1 : -1;
+  }
+  return 0;
+}

package/src/skill-manager.mjs

@@ -0,0 +1,85 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, rmdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+export const SKILL_NAME = 'arg3n41ck-frontend-project';
+const managedMarker = '<!-- template-agent:managed -->';
+
+export function skillTargets({ home = homedir(), env = process.env, clients = ['codex', 'claude'] } = {}) {
+  return clients.map(client => {
+    if (client === 'codex') {
+      const directory = join(home, '.agents', 'skills', SKILL_NAME);
+      return { client, directory, file: join(directory, 'SKILL.md') };
+    }
+    if (client === 'claude') {
+      const directory = join(env.CLAUDE_CONFIG_DIR || join(home, '.claude'), 'skills', SKILL_NAME);
+      return { client, directory, file: join(directory, 'SKILL.md') };
+    }
+    throw new Error(`Unsupported client: ${client}`);
+  });
+}
+
+export function detectClients({ home = homedir(), env = process.env } = {}) {
+  const clients = [];
+  if (existsSync(join(home, '.agents')) || existsSync(join(home, '.codex'))) clients.push('codex');
+  if (existsSync(env.CLAUDE_CONFIG_DIR || join(home, '.claude'))) clients.push('claude');
+  return clients;
+}
+
+function managed(text) {
+  return text.includes(managedMarker);
+}
+
+function managedSkillContent(source) {
+  const text = readFileSync(source, 'utf8');
+  return `${managedMarker}\n${text}`;
+}
+
+function writeAtomic(file, content) {
+  mkdirSync(dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.tmp`;
+  writeFileSync(temporary, content, { mode: 0o600 });
+  renameSync(temporary, file);
+}
+
+export function installSkill({ targets, source, dryRun = false }) {
+  const content = managedSkillContent(source);
+  return targets.map(target => {
+    const alreadyExists = existsSync(target.file);
+    if (alreadyExists) {
+      const current = readFileSync(target.file, 'utf8');
+      if (!managed(current)) throw new Error(`Refusing to overwrite unmanaged skill: ${target.file}`);
+      if (current === content) return { client: target.client, status: 'unchanged', file: target.file };
+      if (!dryRun) writeAtomic(`${target.file}.template-agent.bak`, current);
+    }
+    if (!dryRun) writeAtomic(target.file, content);
+    return { client: target.client, status: alreadyExists ? 'updated' : 'installed', file: target.file };
+  });
+}
+
+export function uninstallSkill({ targets, dryRun = false }) {
+  return targets.map(target => {
+    if (!existsSync(target.file)) return { client: target.client, status: 'absent', file: target.file };
+    if (!managed(readFileSync(target.file, 'utf8'))) throw new Error(`Refusing to remove unmanaged skill: ${target.file}`);
+    if (!dryRun) {
+      rmSync(target.file);
+      rmSync(`${target.file}.template-agent.bak`, { force: true });
+      if (existsSync(target.directory) && readdirSync(target.directory).length === 0) rmdirSync(target.directory);
+    }
+    return { client: target.client, status: 'removed', file: target.file };
+  });
+}
+
+export function findDuplicateSkillNames({ home = homedir(), env = process.env } = {}) {
+  const roots = [join(home, '.agents', 'skills'), join(env.CLAUDE_CONFIG_DIR || join(home, '.claude'), 'skills')];
+  const duplicates = [];
+  for (const root of roots) {
+    if (!existsSync(root)) continue;
+    for (const folder of readdirSync(root)) {
+      const file = join(root, folder, 'SKILL.md');
+      if (folder === SKILL_NAME || !existsSync(file)) continue;
+      if (readFileSync(file, 'utf8').match(new RegExp(`^name:\\s*${SKILL_NAME}\\s*$`, 'm'))) duplicates.push(file);
+    }
+  }
+  return duplicates;
+}