@antomanc/aginit 0.3.0 → 0.4.1

package/src/adapters/tool-ignores.ts

@@ -0,0 +1,158 @@
+import path from 'node:path';
+import { fileExists, readTextFile, safeWriteFile } from '../utils/fs.js';
+import { readPackageManifest } from '../config/validation.js';
+
+// Vendored skill sources ship third-party JS and Markdown that the project's own
+// linters and formatters must not check. No ignore convention is shared across tools,
+// so each tool below says where its ignores live and how to add to them.
+const VENDORED_DIRS = ['.agents', '.claude'];
+
+interface Project {
+  manifest: Record<string, any> | null;
+  has(dependency: string): boolean;
+  exists(file: string): boolean;
+}
+
+interface ToolIgnore {
+  /** The file holding this tool's ignores, when the project uses the tool. */
+  file(project: Project): string | undefined;
+  /** Vendored directories the file does not ignore yet. */
+  missing(text: string): string[];
+  /** The file with those directories ignored, or null when it cannot be edited safely. */
+  patch(text: string, dirs: string[]): string | null;
+  advice(file: string, dirs: string[]): string;
+}
+
+const configs = (base: string, extensions: string[]) => extensions.map((ext) => `${base}${ext}`);
+
+/** Gitignore-syntax files: append the directories. */
+function ignoreFile(name: string, used: (project: Project) => boolean): ToolIgnore {
+  return {
+    file: (project) => (used(project) ? name : undefined),
+    missing: (text) => {
+      const lines = text.split(/\r?\n/).map((line) => line.trim().replace(/^\/|\/(\*\*)?$/g, ''));
+      return VENDORED_DIRS.filter((dir) => !lines.includes(dir));
+    },
+    patch: (text, dirs) => {
+      const block = `# Vendored agent skills (aginit)\n${dirs.map((dir) => `${dir}/`).join('\n')}\n`;
+      return text.trim() ? `${text.trimEnd()}\n\n${block}` : block;
+    },
+    advice: (file, dirs) => `add ${dirs.map((dir) => `${dir}/`).join(' and ')} to ${file}`
+  };
+}
+
+const prettier = ignoreFile(
+  '.prettierignore',
+  (project) =>
+    project.has('prettier') ||
+    Boolean(project.manifest?.prettier) ||
+    [
+      ...configs('.prettierrc', ['', '.json', '.json5', '.yaml', '.yml', '.toml']),
+      ...configs('.prettierrc', ['.js', '.cjs', '.mjs', '.ts', '.cts', '.mts']),
+      ...configs('prettier.config', ['.js', '.cjs', '.mjs', '.ts', '.cts', '.mts'])
+    ].some(project.exists)
+);
+
+// Legacy ESLint and oxlint read .eslintignore; flat-config ESLint does not.
+const eslintIgnore = ignoreFile(
+  '.eslintignore',
+  (project) =>
+    project.has('oxlint') ||
+    Boolean(project.manifest?.eslintConfig) ||
+    configs('.eslintrc', ['', '.js', '.cjs', '.json', '.yaml', '.yml']).some(project.exists)
+);
+
+/** Flat ESLint config: extend a global ignores array if there is an unambiguous one,
+ * `globalIgnores([...])` or an object holding only `ignores`. */
+const eslintFlat: ToolIgnore = {
+  file: (project) =>
+    configs('eslint.config', ['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts']).find(project.exists),
+  missing: (text) => VENDORED_DIRS.filter((dir) => !text.includes(`${dir}/`)),
+  patch: (text, dirs) => {
+    const match =
+      /globalIgnores\(\s*\[/.exec(text) ??
+      /\{\s*ignores\s*:\s*\[(?=[^[\]]*\]\s*,?\s*\})/.exec(text);
+    if (!match) return null;
+    const at = match.index + match[0].length;
+    const rest = text.slice(at);
+    const quote =
+      /^\s*(['"`])/.exec(rest)?.[1] ??
+      ((text.match(/"/g)?.length ?? 0) > (text.match(/'/g)?.length ?? 0) ? '"' : "'");
+    const entries = dirs.map((dir) => `${quote}${dir}/**${quote}`);
+    const indent = /^(\s*\n[ \t]*)/.exec(rest)?.[1];
+    const insertion = indent
+      ? entries.map((entry) => `${indent}${entry},`).join('')
+      : entries.join(', ') + (/^\s*\]/.test(rest) ? '' : ', ');
+    return text.slice(0, at) + insertion + rest;
+  },
+  advice: (file, dirs) =>
+    `add { ignores: [${dirs.map((dir) => `'${dir}/**'`).join(', ')}] } to the exported array in ${file}`
+};
+
+/** Biome 2.2+: force-ignore the folders through files.includes. */
+const biome: ToolIgnore = {
+  file: (project) => ['biome.json', 'biome.jsonc'].find(project.exists),
+  missing: (text) => VENDORED_DIRS.filter((dir) => !text.includes(`**/${dir}`)),
+  patch: (text, dirs) => {
+    let config: Record<string, any>;
+    try {
+      config = JSON.parse(text); // a biome.jsonc with comments gets advice instead
+    } catch {
+      return null;
+    }
+    const includes = config.files?.includes ?? ['**'];
+    if (!Array.isArray(includes)) return null;
+    config.files = {
+      ...config.files,
+      includes: [...includes, ...dirs.map((dir) => `!!**/${dir}`)]
+    };
+    const json = JSON.stringify(config, null, /\n([ \t]+)"/.exec(text)?.[1] ?? 2) + '\n';
+    // Like Biome's formatter, keep the array on one line when it fits in 80 columns.
+    return json.replace(/^([ \t]*"includes": )\[[^\]]*\]/m, (block, key: string) => {
+      const inline = `${key}[${config.files.includes.map((p: string) => JSON.stringify(p)).join(', ')}]`;
+      return inline.replace(/\t/g, '  ').length <= 80 ? inline : block;
+    });
+  },
+  advice: (file, dirs) =>
+    `add ${dirs.map((dir) => `"!!**/${dir}"`).join(', ')} to files.includes in ${file}`
+};
+
+const TOOLS = [prettier, eslintIgnore, eslintFlat, biome];
+
+function pendingIgnores(targetDir: string) {
+  const manifest = readPackageManifest(targetDir);
+  const project: Project = {
+    manifest,
+    has: (name) => Boolean(manifest?.dependencies?.[name] || manifest?.devDependencies?.[name]),
+    exists: (file) => fileExists(path.join(targetDir, file))
+  };
+  return TOOLS.flatMap((tool) => {
+    const file = tool.file(project);
+    if (!file) return [];
+    const text = readTextFile(path.join(targetDir, file)) ?? '';
+    const missing = tool.missing(text);
+    return missing.length > 0 ? [{ tool, file, text, missing }] : [];
+  });
+}
+
+/** Keeps the project's linters and formatters off vendored skills. Returns the
+ * advice for configs that could not be edited safely. */
+export function ignoreVendoredSkills(
+  targetDir: string,
+  options: { dryRun?: boolean; silent?: boolean } = {}
+): string[] {
+  const { dryRun = false, silent = false } = options;
+  const advice: string[] = [];
+  for (const { tool, file, text, missing } of pendingIgnores(targetDir)) {
+    const patched = tool.patch(text, missing);
+    if (patched === null)
+      advice.push(`Linters check vendored skills: ${tool.advice(file, missing)}`);
+    else safeWriteFile(path.join(targetDir, file), patched, { overwrite: true, dryRun, silent });
+  }
+  return advice;
+}
+
+/** Doctor view: every config that still lets a linter or formatter see vendored skills. */
+export function vendoredSkillsExposure(targetDir: string): string[] {
+  return pendingIgnores(targetDir).map(({ tool, file, missing }) => tool.advice(file, missing));
+}

package/src/cli/doctor.ts

@@ -9,7 +9,13 @@ import {
   PackageManager
 } from '../config/schema.js';
 import { detectPackageManager } from '../adapters/package-manager.js';
-import { getInstalledSkills } from '../adapters/skills.js';
+import fs from 'node:fs';
+import {
+  claudeCodeEnabled,
+  getInstalledSkills,
+  getSkillsMissingForClaude
+} from '../adapters/skills.js';
+import { claudeMarkdownImportsAgents } from '../adapters/agents-md.js';
 import {
   agentBrowserConfigured,
   agentBrowserStubInstalled,
@@ -17,6 +23,7 @@ import {
   runAgentBrowserDiagnostics
 } from '../adapters/agent-browser.js';
 import { readProjectConfig } from '../config/validation.js';
+import { vendoredSkillsExposure } from '../adapters/tool-ignores.js';
 import { logger } from '../utils/logger.js';
 
 interface CheckItem {
@@ -169,7 +176,7 @@ export async function runDoctor(targetDir: string = process.cwd()): Promise<void
     category: 'Project Config',
     ok: !!projectConfig,
     detail: projectConfig
-      ? `Preset: "${projectConfig.preset}" (v${projectConfig.schemaVersion || '1.0.0'}), pm: ${activePm}, agents: ${projectConfig.agents.primary}/${projectConfig.agents.secondary}`
+      ? `Preset: "${projectConfig.preset}" (v${projectConfig.schemaVersion || '1.0.0'}), pm: ${activePm}, agents: ${projectConfig.agents.primary}/${projectConfig.agents.secondary}${claudeCodeEnabled(projectConfig) ? '/claude-code' : ''}`
       : configError
         ? `Invalid configuration: ${configError}`
         : 'No aginit.config.json found in current directory',
@@ -220,6 +227,69 @@ export async function runDoctor(targetDir: string = process.cwd()): Promise<void
         : 'Run `aginit init` or `npx skills add ...` to install skills'
   });
 
+  // 9a. Vendored skills must stay out of the project's linters and formatters
+  if (installedSkills.length > 0) {
+    const exposure = vendoredSkillsExposure(targetDir);
+    checks.push({
+      name: 'Lint/format ignores for vendored skills',
+      category: 'Project Config',
+      ok: exposure.length === 0,
+      detail:
+        exposure.length === 0
+          ? 'Detected linters and formatters skip .agents/ and .claude/'
+          : 'Project linters or formatters will check vendored skill files',
+      suggestion:
+        exposure.length === 0 ? undefined : `Run \`aginit update\`, or ${exposure.join('; ')}`
+    });
+  }
+
+  // 9b. Claude Code: skills linked into .claude/skills/ and AGENTS.md reachable
+  if (projectConfig !== null && claudeCodeEnabled(projectConfig)) {
+    if (!skillsDisabled && installedSkills.length > 0) {
+      const missing = getSkillsMissingForClaude(targetDir);
+      checks.push({
+        name: 'Claude Code Skills (.claude/skills/)',
+        category: 'Project Config',
+        ok: missing.length === 0,
+        detail:
+          missing.length === 0
+            ? `All ${installedSkills.length} skills visible to Claude Code`
+            : `${missing.length} skills not linked for Claude Code: ${missing.join(', ')}`,
+        suggestion:
+          missing.length === 0
+            ? undefined
+            : 'Run `aginit update` or `aginit init` to link skills into .claude/skills/ (or set agents.claudeCode: false)'
+      });
+    }
+
+    const claudePath = path.join(targetDir, 'CLAUDE.md');
+    const claudeExists = fileExists(claudePath);
+    // A CLAUDE.md symlinked to AGENTS.md is as good as the import.
+    const claudeIsAgentsLink =
+      claudeExists &&
+      agentsExists &&
+      fs.realpathSync(claudePath) === fs.realpathSync(agentsPath);
+    const claudeOk =
+      !claudeExists ||
+      claudeIsAgentsLink ||
+      claudeMarkdownImportsAgents(readTextFile(claudePath) || '');
+    checks.push({
+      name: 'CLAUDE.md → AGENTS.md',
+      category: 'Project Config',
+      ok: claudeExists && claudeOk,
+      detail: !claudeExists
+        ? 'No CLAUDE.md; only Claude Code v2.1.277+ reads AGENTS.md on its own'
+        : claudeOk
+          ? 'CLAUDE.md imports AGENTS.md'
+          : 'CLAUDE.md exists without `@AGENTS.md`, so Claude Code ignores AGENTS.md',
+      suggestion: !claudeExists
+        ? 'Run `aginit update` or `aginit init` to add a CLAUDE.md that imports AGENTS.md'
+        : claudeOk
+          ? undefined
+          : 'Add a line `@AGENTS.md` to CLAUDE.md'
+    });
+  }
+
   // 10. agent-browser runtime (only when the project ships the skill)
   const agentBrowserWanted =
     projectConfig !== null &&

package/src/cli/main.ts

@@ -3,7 +3,9 @@ import { readFileSync } from 'node:fs';
 import { createProject } from './new.js';
 import { initCurrentDirectory } from './init.js';
 import { runDoctor } from './doctor.js';
-import { updateSkills } from '../adapters/skills.js';
+import { claudeCodeEnabled, ensureClaudeSkillLinks, updateSkills } from '../adapters/skills.js';
+import { ignoreVendoredSkills } from '../adapters/tool-ignores.js';
+import { setupClaudeMarkdown } from '../adapters/agents-md.js';
 import { buildGraft } from '../adapters/graft.js';
 import { readProjectConfig } from '../config/validation.js';
 import { logger } from '../utils/logger.js';
@@ -161,9 +163,16 @@ export function createCliProgram(): Command {
       const targetDir = process.cwd();
       const config = readProjectConfig(targetDir);
       const skillsOk =
-        config?.skills.sources.length === 0
+        (config?.skills.sources.length === 0
           ? true
-          : await updateSkills(targetDir, { dryRun: options.dryRun });
+          : await updateSkills(targetDir, { dryRun: options.dryRun })) &&
+        (config ? await ensureClaudeSkillLinks(targetDir, config, { dryRun: options.dryRun }) : true);
+      if (config && claudeCodeEnabled(config))
+        setupClaudeMarkdown(targetDir, { dryRun: options.dryRun });
+      if (config?.skills.sources.length !== 0) {
+        const advice = ignoreVendoredSkills(targetDir, { dryRun: options.dryRun, silent: true });
+        for (const line of advice) logger.warn(line);
+      }
       const graftOk =
         config?.codebase.graft === false
           ? true

package/src/cli/new.ts

@@ -9,9 +9,10 @@ import {
 } from '../config/schema.js';
 import { getPreset } from '../presets/registry.js';
 import { setupGit } from '../adapters/git.js';
-import { setupAgentsMarkdown } from '../adapters/agents-md.js';
-import { installAllSkills } from '../adapters/skills.js';
+import { setupAgentsMarkdown, setupClaudeMarkdown } from '../adapters/agents-md.js';
+import { claudeCodeEnabled, installAllSkills, skillAgents } from '../adapters/skills.js';
 import { initGraft } from '../adapters/graft.js';
+import { ignoreVendoredSkills } from '../adapters/tool-ignores.js';
 import {
   agentBrowserConfigured,
   agentBrowserStubInstalled,
@@ -137,13 +138,14 @@ export async function createProject(
   // Step 4: Write or update AGENTS.md intake contract
   if (!silent) logger.step(currentStep++, totalSteps, 'Generating AGENTS.md intake guidance');
   setupAgentsMarkdown(targetDir, config, { dryRun, silent });
+  if (claudeCodeEnabled(config)) setupClaudeMarkdown(targetDir, { dryRun, silent });
   if (!silent) logger.success('Configured AGENTS.md');
 
   // Step 5: Install skills via skills.sh engine
   if (!silent) logger.step(currentStep++, totalSteps, 'Installing upstream skills via skills.sh');
   if (options.skills !== false && config.skills.sources.length > 0) {
     const { installed, failed } = await installAllSkills(targetDir, config.skills.sources, {
-      agents: [config.agents.primary, config.agents.secondary],
+      agents: skillAgents(config),
       dryRun,
       silent
     });
@@ -159,6 +161,10 @@ export async function createProject(
   } else if (!silent) {
     logger.dim('Skills installation skipped (--no-skills or empty configuration)');
   }
+  if ((options.skills !== false && config.skills.sources.length > 0) || agentBrowserWanted) {
+    const advice = ignoreVendoredSkills(targetDir, { dryRun, silent: true });
+    if (!silent) for (const line of advice) logger.warn(line);
+  }
 
   // Provision the agent-browser runtime the skill stub drives
   if (agentBrowserWanted) {
@@ -171,7 +177,11 @@ export async function createProject(
   // Codebase intelligence (Graft)
   if (!silent) logger.step(currentStep++, totalSteps, 'Configuring codebase intelligence');
   if (config.codebase.graft && options.graft !== false) {
-    const graftOk = await initGraft(targetDir, { dryRun, silent });
+    const graftOk = await initGraft(targetDir, {
+      dryRun,
+      silent,
+      claude: claudeCodeEnabled(config)
+    });
     complete &&= graftOk;
     if (graftOk && !silent) {
       logger.success('Graft context graph initialized');

package/src/config/defaults.ts

@@ -70,7 +70,8 @@ export function getDefaultConfig(
         packageManager,
         agents: {
           primary: 'antigravity',
-          secondary: 'codex'
+          secondary: 'codex',
+          claudeCode: true
         },
         skills: {
           sources: [
@@ -120,7 +121,8 @@ export function getDefaultConfig(
         packageManager,
         agents: {
           primary: 'antigravity',
-          secondary: 'codex'
+          secondary: 'codex',
+          claudeCode: true
         },
         skills: {
           sources: [
@@ -162,7 +164,8 @@ export function getDefaultConfig(
         packageManager,
         agents: {
           primary: 'antigravity',
-          secondary: 'codex'
+          secondary: 'codex',
+          claudeCode: true
         },
         skills: {
           sources: [

package/src/config/schema.ts

@@ -16,6 +16,11 @@ export interface AginitConfig {
   agents: {
     primary: string;
     secondary: string;
+    /**
+     * Also install skills, Graft wiring and a CLAUDE.md import for Claude Code.
+     * Missing in configs written before 0.4.0; treated as enabled.
+     */
+    claudeCode?: boolean;
   };
   skills: {
     /**

package/src/config/validation.ts

@@ -45,6 +45,8 @@ export function validateConfig(value: unknown): AginitConfig {
   if (!isRecord(value.agents)) fail('agents');
   for (const key of ['primary', 'secondary'])
     validateUpstreamArgument(value.agents[key], `agent ${key}`);
+  if (value.agents.claudeCode !== undefined && typeof value.agents.claudeCode !== 'boolean')
+    fail('agents.claudeCode');
   if (!isRecord(value.skills) || !Array.isArray(value.skills.sources)) fail('skills.sources');
   if (value.skills.workflow !== undefined && !['minimal', 'spec'].includes(value.skills.workflow))
     fail('skills.workflow');

package/src/presets/web.ts

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { fileExists, safeWriteFile, writeJsonFile } from '../utils/fs.js';
+import { fileExists, readTextFile, safeWriteFile, writeJsonFile } from '../utils/fs.js';
 import { readPackageManifest } from '../config/validation.js';
 import { runExecutable } from '../utils/shell.js';
 import { PresetContext, PresetHandler } from './types.js';
@@ -8,6 +8,34 @@ import { setupAdr } from './adr.js';
 import { scaffoldCommand } from '../adapters/package-manager.js';
 import { addTestingDependencies, setupTesting } from './testing.js';
 
+/** Plain tsc cannot resolve framework virtual modules or single-file components,
+ * so those frameworks get their own checker (and the package that provides it). */
+function typecheckFor(
+  pkg: Record<string, any>,
+  targetDir: string,
+  freshNext: boolean
+): { script: string; checker?: [string, string] } {
+  const has = (name: string) => Boolean(pkg.dependencies?.[name] || pkg.devDependencies?.[name]);
+  if (freshNext) return { script: 'next typegen && tsc --noEmit' };
+  if (has('astro')) return { script: 'astro check', checker: ['@astrojs/check', '^0.9.10'] };
+  if (has('nuxt')) return { script: 'nuxi typecheck', checker: ['vue-tsc', '^3.3.13'] };
+  if (has('@sveltejs/kit'))
+    return {
+      script: 'svelte-kit sync && svelte-check --tsconfig ./tsconfig.json',
+      checker: ['svelte-check', '^4.7.6']
+    };
+  if (has('svelte')) return { script: 'svelte-check', checker: ['svelte-check', '^4.7.6'] };
+  // A solution-style tsconfig (Vite templates) has no files of its own: only build mode checks
+  // the referenced projects.
+  const build = /"references"\s*:/.test(readTextFile(path.join(targetDir, 'tsconfig.json')) || '');
+  if (has('vue'))
+    return {
+      script: build ? 'vue-tsc -b --noEmit' : 'vue-tsc --noEmit',
+      checker: ['vue-tsc', '^3.3.13']
+    };
+  return { script: build ? 'tsc -b --noEmit' : 'tsc --noEmit' };
+}
+
 export const webPreset: PresetHandler = {
   name: 'web',
   description:
@@ -55,8 +83,12 @@ export const webPreset: PresetHandler = {
     );
     addTestingDependencies(pkg, config.browser.playwright);
     if (fileExists(path.join(targetDir, 'tsconfig.json'))) {
-      pkg.scripts.typecheck ??=
-        fresh && framework === 'next' ? 'next typegen && tsc --noEmit' : 'tsc --noEmit';
+      if (pkg.scripts.typecheck === undefined) {
+        const { script, checker } = typecheckFor(pkg, targetDir, fresh && framework === 'next');
+        pkg.scripts.typecheck = script;
+        if (checker && !pkg.dependencies?.[checker[0]] && !pkg.devDependencies[checker[0]])
+          pkg.devDependencies[checker[0]] = checker[1];
+      }
       if (!pkg.dependencies?.typescript && !pkg.devDependencies.typescript)
         pkg.devDependencies.typescript = '^5.6.3';
     }