@antomanc/aginit 0.4.1 → 0.5.1

package/src/adapters/agent-docs.ts

@@ -0,0 +1,197 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { AginitConfig } from '../config/schema.js';
+import { presetPlatform } from '../config/defaults.js';
+import { detectProject, projectCommands } from '../detect/index.js';
+import {
+  activeCapabilities,
+  CapabilityDescriptor,
+  CATALOG,
+  e2eDirFor,
+  GuideContext,
+  MicroDoc,
+  Platform,
+  Stack
+} from '../registry/index.js';
+import { readTextFile, safeWriteFile } from '../utils/fs.js';
+import { logger } from '../utils/logger.js';
+
+export interface ProjectProfile extends GuideContext {
+  active: CapabilityDescriptor[];
+}
+
+/** Platform and stack: saved in v2 configs, detected for older ones. */
+export function resolvePlatformStack(
+  config: AginitConfig,
+  targetDir?: string
+): { platform: Platform; stack: Stack } {
+  const detected = targetDir && (!config.platform || !config.stack) ? detectProject(targetDir) : null;
+  return {
+    platform:
+      config.platform ??
+      (config.preset !== 'generic' ? presetPlatform(config.preset) : (detected?.platform ?? 'cli')),
+    stack: config.stack ?? (detected && detected.stack !== 'unknown' ? detected.stack : 'node')
+  };
+}
+
+export function projectProfile(
+  config: AginitConfig,
+  options: { targetDir?: string; scripts?: Record<string, string> } = {}
+): ProjectProfile {
+  const { platform, stack } = resolvePlatformStack(config, options.targetDir);
+  const active = activeCapabilities(config);
+  const ids = new Set(active.map((c) => c.id));
+  return {
+    platform,
+    stack,
+    active,
+    has: (id) => ids.has(id),
+    commands: projectCommands(options.targetDir ?? '.', stack, {
+      packageManager: config.packageManager,
+      scripts: options.scripts
+    }),
+    e2eDir: e2eDirFor(stack)
+  };
+}
+
+export const DOCS_DIR = path.join('docs', 'agents');
+export const GENERATED_MARKER =
+  '<!-- aginit:managed — generated by npx @antomanc/aginit. Delete this line to take ownership of this file. -->';
+export const LEGACY_GENERATED_MARKER =
+  '<!-- Generated by aginit from aginit.config.json. Rerun `aginit` to refresh; delete this line to edit by hand. -->';
+
+const DOC_TITLES: Record<MicroDoc, string> = {
+  testing: 'Testing',
+  'ui-verification': 'Live UI verification',
+  workflows: 'Engineering workflows & skills'
+};
+
+const skillNames = (capability: CapabilityDescriptor) =>
+  capability.install.flatMap((step) => (step.kind === 'skills-sh' ? step.skills : []));
+
+function testingIntro(profile: ProjectProfile): string[] {
+  const { commands } = profile;
+  const rows: Array<[string, string | undefined]> = [
+    ['Build', commands.build],
+    ['Typecheck', commands.typecheck],
+    ['Lint / analyze', commands.lint],
+    ['Test', commands.test],
+    ['Unit test', commands.unitTest],
+    ['E2E', commands.e2e]
+  ];
+  const lines = rows.filter(([, cmd]) => cmd).map(([label, cmd]) => `- ${label}: \`${cmd}\``);
+  return lines.length
+    ? ['Run the full check before calling a change done:', ...lines]
+    : ['Record the project build and test commands here once they exist.'];
+}
+
+function workflowsExtras(profile: ProjectProfile): string[] {
+  // Skill capabilities without their own guide still show up, so new registry
+  // entries and custom skill repos are documented without extra code.
+  const plain = profile.active.filter(
+    (c) => !c.guide && c.install.some((step) => step.kind === 'skills-sh')
+  );
+  const bullet = (c: CapabilityDescriptor) => {
+    const skills = skillNames(c);
+    const label = skills.length ? skills.map((s) => '`' + s + '`').join(', ') : `\`${c.id}\``;
+    return `- ${label}: ${c.description}.`;
+  };
+  const discipline = plain.filter((c) => c.category === 'discipline');
+  const others = plain.filter((c) => c.category !== 'discipline');
+  return [
+    ...(discipline.length ? ['## Discipline (apply to every change)', ...discipline.map(bullet)] : []),
+    ...(others.length ? ['', '## Other skills', ...others.map(bullet)] : [])
+  ];
+}
+
+// Drivers come before the design review that uses them; unit runners before E2E.
+const SECTION_ORDER = ['methodology', 'ui-driver', 'design', 'testing-engine', 'context-guard'];
+const sectionRank = (c: CapabilityDescriptor) => {
+  const category = SECTION_ORDER.indexOf(c.category);
+  const index = CATALOG.indexOf(c);
+  return (category === -1 ? SECTION_ORDER.length : category) * 1000 + (index === -1 ? 999 : index);
+};
+
+/** Markdown for one micro-doc, or null when no active capability contributes to it. */
+export function renderMicroDoc(doc: MicroDoc, profile: ProjectProfile): string | null {
+  const sections = profile.active
+    .filter((c) => c.guide?.doc === doc)
+    .sort((a, b) => sectionRank(a) - sectionRank(b))
+    .map((c) => c.guide!.render(profile));
+  const extras = doc === 'workflows' ? workflowsExtras(profile) : [];
+  if (sections.length === 0 && extras.length === 0) return null;
+  const intro =
+    doc === 'testing'
+      ? testingIntro(profile)
+      : doc === 'workflows'
+        ? [
+            'Skills live in `.agents/skills/` (linked into `.claude/skills/` for Claude Code). Invoke one by name',
+            '(for example `/tdd`), or let the agent pick it from its description.'
+          ]
+        : ['Verify UI changes in the running app, not only in tests.'];
+  const body = [`# ${DOC_TITLES[doc]}`, '', ...intro, '', ...sections.flatMap((s) => [s, ''])];
+  if (extras.length) body.push(...extras, '');
+  return [GENERATED_MARKER, ...body].join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
+}
+
+export const MICRO_DOCS: MicroDoc[] = ['testing', 'ui-verification', 'workflows'];
+
+export function microDocPath(doc: MicroDoc): string {
+  return path.join(DOCS_DIR, `${doc}.md`).split(path.sep).join('/');
+}
+
+/** Checks if a micro-doc's content still carries an aginit managed marker. */
+export function isManagedMicroDoc(text: string | null): boolean {
+  if (text === null) return true;
+  const firstLine = text.split(/\r?\n/, 1)[0].trim();
+  return (
+    firstLine.startsWith(GENERATED_MARKER) ||
+    firstLine.startsWith(LEGACY_GENERATED_MARKER) ||
+    /^<!--\s*aginit:managed(?:\b[^>]*)?-->/.test(firstLine) ||
+    /^<!--\s*Generated by aginit\b/.test(firstLine)
+  );
+}
+
+/** Docs aginit owns: files it wrote that still carry the generated marker. */
+function ownedByAginit(file: string): boolean {
+  return isManagedMicroDoc(readTextFile(file));
+}
+
+/**
+ * Write the docs/agents/ micro-docs for the active capabilities. A doc whose
+ * marker line was removed belongs to the user and is never touched; a doc no
+ * capability contributes to any more is deleted. Returns the docs that exist.
+ */
+export function setupMicroDocs(
+  targetDir: string,
+  profile: ProjectProfile,
+  options: { dryRun?: boolean; silent?: boolean } = {}
+): MicroDoc[] {
+  const { dryRun = false, silent = false } = options;
+  const present: MicroDoc[] = [];
+  for (const doc of MICRO_DOCS) {
+    const file = path.join(targetDir, DOCS_DIR, `${doc}.md`);
+    const content = renderMicroDoc(doc, profile);
+    if (!ownedByAginit(file)) {
+      if (!silent) logger.dim(`${microDocPath(doc)} was edited by hand, preserving it.`);
+      present.push(doc);
+      continue;
+    }
+    if (content === null) {
+      if (fs.existsSync(file)) {
+        if (dryRun) logger.dim(`[dry-run] Would remove file: ${file}`);
+        else fs.rmSync(file);
+      }
+      continue;
+    }
+    present.push(doc);
+    if (readTextFile(file) !== content)
+      safeWriteFile(file, content, { overwrite: true, dryRun, silent });
+  }
+  return present;
+}
+
+/** Docs that will exist for a profile (used when rendering AGENTS.md without a target). */
+export function plannedMicroDocs(profile: ProjectProfile): MicroDoc[] {
+  return MICRO_DOCS.filter((doc) => renderMicroDoc(doc, profile) !== null);
+}

package/src/adapters/agents-md.ts

@@ -3,97 +3,151 @@ import { fileExists, readTextFile, safeWriteFile } from '../utils/fs.js';
 import { AginitConfig } from '../config/schema.js';
 import { readPackageManifest } from '../config/validation.js';
 import { logger } from '../utils/logger.js';
-import { getPackageManagerAdapter } from './package-manager.js';
+import { CapabilityDescriptor, isNodeStack, MicroDoc } from '../registry/index.js';
+import {
+  microDocPath,
+  plannedMicroDocs,
+  projectProfile,
+  ProjectProfile,
+  resolvePlatformStack
+} from './agent-docs.js';
+
+const PLATFORM_LABELS: Record<string, string> = {
+  web: 'Web',
+  'mobile-native': 'Native mobile',
+  'mobile-rn': 'React Native',
+  backend: 'Backend',
+  cli: 'CLI'
+};
+
+export const AGINIT_BLOCK_START =
+  '<!-- aginit:start — managed by npx @antomanc/aginit (re-run to refresh) -->';
+export const AGINIT_BLOCK_END = '<!-- aginit:end -->';
+
+export const AGINIT_START_PATTERN = /<!--\s*aginit:start(?:\b[^>]*)?-->/;
+export const AGINIT_END_PATTERN = /<!--\s*aginit:end(?:\b[^>]*)?-->/;
+
+const BOOTSTRAP_SECTION = [
+  '## Bootstrap & First Session',
+  'When the user asks to "bootstrap this project" or kicks off a new initiative:',
+  '1. Understand product intent and ask 2-3 essential questions to resolve ambiguity.',
+  '2. Draft or refine canonical context in `PRODUCT.md` and `DESIGN.md` (or `docs/adr/`).',
+  '3. Plan in small verifiable increments and implement test-first using installed skills.'
+];
+
+/** Placeholder scripts used when AGENTS.md is rendered without a package.json to read. */
+function presetScripts(config: AginitConfig): Record<string, string> {
+  return config.preset === 'generic'
+    ? { test: 'vitest run' }
+    : { build: '', typecheck: '', test: '', dev: '', 'test:e2e': '' };
+}
 
-export function generateAgentsMarkdown(
+const table = (head: [string, string], rows: Array<[string, string]>) => [
+  `| ${head[0]} | ${head[1]} |`,
+  '| --- | --- |',
+  ...rows.map(([a, b]) => `| ${a} | ${b} |`)
+];
+
+/**
+ * The part of AGENTS.md aginit keeps in sync with the active capabilities:
+ * guardrails, the Task Routing table and the Anti-Rationalization table.
+ */
+export function renderAgentsBlock(
   config: AginitConfig,
-  scripts?: Record<string, string>
+  profile: ProjectProfile,
+  docs: MicroDoc[] = plannedMicroDocs(profile)
 ): string {
-  const commands =
-    scripts ??
-    (config.preset === 'generic'
-      ? { test: 'vitest run' }
-      : { build: '', typecheck: '', test: '', dev: '', 'test:e2e': '' });
-  const hasCommand = (name: string) => Object.hasOwn(commands, name);
-  const isWeb = config.preset === 'web';
-  const hasBrowser = isWeb && config.browser.playwright;
-  const hasVisualAgent = isWeb && config.browser.visualAgent;
-  const pm = config.packageManager || 'pnpm';
-  const pmAdapter = getPackageManagerAdapter(pm);
-
-  let devCommand = '';
-  if (hasCommand('dev') && isWeb && config.framework && config.framework !== 'none') {
-    devCommand = `- Dev Server: \`${pmAdapter.runCmd('dev')}\``;
-  }
-
-  let testE2E = '';
-  if (hasBrowser && hasCommand('test:e2e')) {
-    testE2E = `- Test (E2E / Browser): \`${pmAdapter.runCmd('test:e2e')}\``;
-  }
-
-  // A source with an empty skill list (or `*`) installs every skill it ships.
-  const skillInstalled = (skill: string) =>
-    config.skills.sources.some(
-      (source) =>
-        source.skills.length === 0 || source.skills.includes('*') || source.skills.includes(skill)
-    );
-  const mattSkills = (() => {
-    const source = config.skills.sources.find((s) => s.package === 'mattpocock/skills');
-    if (!source) return [];
-    return source.skills.length ? source.skills : ['*'];
-  })();
   const hasSkills = config.skills.sources.length > 0;
+  const routing: Array<[string, string]> = [
+    ['Product intent, scope, target users', '`PRODUCT.md`']
+  ];
+  const order = ['design', 'codebase-graph'];
+  const rank = (c: CapabilityDescriptor) => (order.indexOf(c.category) + order.length + 1) % (order.length + 1);
+  const direct = profile.active.filter((c) => c.routing).sort((a, b) => rank(a) - rank(b));
+  const routeOf = (c: CapabilityDescriptor): [string, string] => [c.routing!.task, c.routing!.read];
+  // Design and codebase rows lead, discipline rows follow the micro-docs.
+  routing.push(...direct.filter((c) => c.category !== 'discipline').map(routeOf));
+  if (docs.includes('testing'))
+    routing.push(['Automated unit & E2E testing', '`' + microDocPath('testing') + '`']);
+  if (docs.includes('ui-verification'))
+    routing.push(['Live UI verification (Web / Mobile)', '`' + microDocPath('ui-verification') + '`']);
+  if (docs.includes('workflows'))
+    routing.push(['Engineering workflow & skills', '`' + microDocPath('workflows') + '`']);
+  routing.push(...direct.filter((c) => c.category === 'discipline').map(routeOf));
+
+  const rebuttals = new Map<string, string>();
+  for (const capability of profile.active)
+    for (const { excuse, rule } of capability.rebuttals ?? [])
+      if (!rebuttals.has(excuse)) rebuttals.set(excuse, rule);
+  const unitExcuse = 'Unit tests pass, so the feature works.';
+  if (!rebuttals.has(unitExcuse) && profile.active.some((c) => c.category === 'testing-engine'))
+    rebuttals.set(
+      unitExcuse,
+      'Insufficient. Unit tests do not verify wiring or rendering. Exercise the feature end to end ' +
+        `(${profile.commands.e2e && profile.has('playwright') ? '`' + profile.commands.e2e + '`' : 'integration or smoke run'}) before marking complete.`
+    );
 
-  const specSkillNames = ['to-spec', 'to-tickets', 'implement-spec'];
-  let engineeringCapability = '';
-  if (mattSkills.includes('*')) {
-    engineeringCapability =
-      '- **Engineering**: the full Matt Pocock skill set installed in `.agents/skills/` — start with `ask-matt` to route to the right one.';
-  } else if (mattSkills.length) {
-    const engineering = mattSkills.filter((skill) => !specSkillNames.includes(skill));
-    if (engineering.length) {
-      engineeringCapability = `- **Engineering**: ${engineering.map((skill) => '`' + skill + '`').join(', ')}`;
-    }
-  }
-
-  let proseCapability = '';
-  if (skillInstalled('humanizer')) {
-    proseCapability =
-      '- **Prose & Copy**: Use `humanizer` skill to eliminate AI writing tells and refine documentation.';
-  }
-
-  let simplicityCapability = '';
-  if (skillInstalled('ponytail')) {
-    simplicityCapability =
-      '- **Simplicity**: Use `ponytail` skill for the smallest complete change and to cut over-engineering.';
-  }
-
-  let uiCapability = '';
-  if (isWeb && skillInstalled('impeccable')) {
-    uiCapability =
-      '- **UI & Design**: Use `impeccable` skill for frontend polish, design critique, and token craft.';
-  }
-
-  let browserCapability = '';
-  if (hasVisualAgent && skillInstalled('agent-browser')) {
-    browserCapability =
-      '- **Browser Verification**: Use `agent-browser` skill for interactive inspection and visual QA.';
-  }
-
-  let graftCapability = '';
-  if (config.codebase.graft) {
-    graftCapability =
-      '- **Codebase Graph**: Use `graft ask "<query>" --source` or `graft map` for orientation before raw grep.';
-  }
-
-  const specCapability = skillInstalled('to-spec')
-    ? '- **Spec & Tickets Workflow**: `to-spec`, `to-tickets`, `implement-spec`'
-    : '';
+  const lines = [
+    AGINIT_BLOCK_START,
+    ...(profile.has('karpathy-guidelines')
+      ? [
+          '## Guardrails (karpathy-guidelines)',
+          '- **Think before coding**: state assumptions and trade-offs; ask instead of guessing.',
+          '- **Simplicity first**: minimum code that solves the problem; no speculative features or abstractions.',
+          '- **Surgical changes**: touch only what the task needs; no silent scope creep or drive-by refactors.',
+          '- **Goal-driven execution**: define a verifiable success check first, then loop until it passes.',
+          ''
+        ]
+      : []),
+    '## Task Routing',
+    hasSkills
+      ? config.agents.claudeCode === false
+        ? 'Load only what the task needs. Skills live in `.agents/skills/`.'
+        : 'Load only what the task needs. Skills live in `.agents/skills/` (linked into `.claude/skills/` for Claude Code).'
+      : 'Load only what the task needs. Skills installation is disabled in this configuration.',
+    '',
+    ...table(['Task', 'Read / Use'], routing),
+    ...(rebuttals.size
+      ? ['', '## Anti-Rationalization', ...table(['Excuse', 'Rule'], [...rebuttals].map(([e, r]) => [`"${e}"`, r]))]
+      : []),
+    AGINIT_BLOCK_END
+  ];
+  return lines.join('\n');
+}
 
-  const sections: Array<string | undefined> = [
+export function generateAgentsMarkdown(
+  config: AginitConfig,
+  scripts?: Record<string, string>,
+  targetDir?: string
+): string {
+  const resolved = resolvePlatformStack(config, targetDir);
+  const node = isNodeStack(resolved.stack);
+  const profile = projectProfile(config, {
+    targetDir,
+    scripts: node ? (scripts ?? presetScripts(config)) : undefined
+  });
+  const { commands } = profile;
+  const pm = config.packageManager || 'pnpm';
+  const isWeb = profile.platform === 'web';
+  const commandLines = [
+    node ? `- Package Manager: \`${pm}\`` : undefined,
+    commands.dev && isWeb && config.framework && config.framework !== 'none'
+      ? `- Dev Server: \`${commands.dev}\``
+      : undefined,
+    commands.build ? `- Build: \`${commands.build}\`` : undefined,
+    commands.typecheck ? `- Typecheck: \`${commands.typecheck}\`` : undefined,
+    commands.lint ? `- Lint: \`${commands.lint}\`` : undefined,
+    commands.test ? `- Test: \`${commands.test}\`` : undefined,
+    commands.unitTest ? `- Unit Test: \`${commands.unitTest}\`` : undefined,
+    commands.e2e && profile.has('playwright')
+      ? `- Test (E2E / Browser): \`${commands.e2e}\``
+      : undefined
+  ].filter((line): line is string => line !== undefined);
+
+  const sections: string[] = [
     `# ${config.name}`,
     '',
-    `AI-first ${config.preset} project configured with \`aginit\`.`,
+    `AI-first ${config.preset} project configured with \`aginit\` (${PLATFORM_LABELS[profile.platform]}, ${profile.stack}).`,
     '',
     '## Core Invariants',
     '- Keep changes small, focused, and test-verified.',
@@ -101,80 +155,60 @@ export function generateAgentsMarkdown(
     '- Never commit broken builds, failed typechecks, or unverified changes.',
     '',
     '## Essential Commands',
-    `- Package Manager: \`${pm}\``,
-    devCommand || undefined,
-    hasCommand('build') ? `- Build: \`${pmAdapter.runCmd('build')}\`` : undefined,
-    hasCommand('typecheck') ? `- Typecheck: \`${pmAdapter.runCmd('typecheck')}\`` : undefined,
-    hasCommand('test') ? `- Test: \`${pmAdapter.runCmd('test')}\`` : undefined,
-    hasCommand('test:unit') ? `- Unit Test: \`${pmAdapter.runCmd('test:unit')}\`` : undefined,
-    testE2E || undefined,
+    ...(commandLines.length ? commandLines : ['- Add the build and test commands here once they exist.']),
     '',
-    '## AI Capabilities & Skills',
-    hasSkills
-      ? config.agents.claudeCode === false
-        ? 'Configured skills install into `.agents/skills/` (shared by Antigravity and Codex):'
-        : 'Configured skills install into `.agents/skills/` (shared by Antigravity and Codex, linked into `.claude/skills/` for Claude Code):'
-      : 'Skills installation is disabled in this configuration.',
-    engineeringCapability || undefined,
-    proseCapability || undefined,
-    simplicityCapability || undefined,
-    specCapability || undefined,
-    uiCapability || undefined,
-    browserCapability || undefined,
-    graftCapability || undefined,
+    renderAgentsBlock(config, profile),
     '',
-    '## Bootstrap & First Session',
-    'When the user asks to "bootstrap this project" or kicks off a new initiative:',
-    '1. Understand product intent and ask 2-3 essential questions to resolve ambiguity.',
-    '2. Draft or refine canonical context in `PRODUCT.md` and `DESIGN.md` (or `docs/adr/`).',
-    '3. Plan in small verifiable increments and implement test-first using installed skills.',
+    ...BOOTSTRAP_SECTION,
     ''
   ];
+  return sections.join('\n').replace(/\n{3,}/g, '\n\n').trim() + '\n';
+}
 
-  // Conditional lines are `undefined` and dropped; `''` entries are the blank
-  // separators between sections and must survive.
-  return (
-    sections
-      .filter((s): s is string => s !== undefined)
-      .join('\n')
-      .trim() + '\n'
-  );
+/** Insert or refresh the aginit block in an existing AGENTS.md, leaving everything else as written. */
+export function mergeAgentsBlock(existing: string, block: string): string {
+  const startMatch = existing.match(AGINIT_START_PATTERN);
+  if (startMatch && startMatch.index !== undefined) {
+    const afterStart = existing.slice(startMatch.index + startMatch[0].length);
+    const endMatch = afterStart.match(AGINIT_END_PATTERN);
+    if (endMatch && endMatch.index !== undefined) {
+      const endOffset = startMatch.index + startMatch[0].length + endMatch.index + endMatch[0].length;
+      return existing.slice(0, startMatch.index) + block + existing.slice(endOffset);
+    }
+  }
+  // Above Graft's block when there is one, so Graft keeps owning the end of the file.
+  const graftMatch = existing.match(/<!--\s*graft:start(?:\b[^>]*)?-->/);
+  if (graftMatch && graftMatch.index !== undefined) {
+    const graft = graftMatch.index;
+    return existing.slice(0, graft).trimEnd() + '\n\n' + block + '\n\n' + existing.slice(graft);
+  }
+  return existing.trimEnd() + '\n\n' + block + '\n';
 }
 
 export function setupAgentsMarkdown(
   targetDir: string,
   config: AginitConfig,
-  options: { overwrite?: boolean; dryRun?: boolean; silent?: boolean } = {}
+  options: { overwrite?: boolean; dryRun?: boolean; silent?: boolean; docs?: MicroDoc[] } = {}
 ): boolean {
   const { overwrite = false, dryRun = false, silent = false } = options;
   const filePath = path.join(targetDir, 'AGENTS.md');
 
   if (fileExists(filePath) && !overwrite) {
-    // File exists; check if it has the bootstrap guidance. If not, append it conservatively.
     const existing = readTextFile(filePath) || '';
-    if (!existing.includes('## Bootstrap & First Session')) {
-      const addition = [
-        '',
-        '## Bootstrap & First Session',
-        'When the user asks to "bootstrap this project" or kicks off a new initiative:',
-        '1. Understand product intent and ask 2-3 essential questions to resolve ambiguity.',
-        '2. Draft or refine canonical context in `PRODUCT.md` and `DESIGN.md` (or `docs/adr/`).',
-        '3. Plan in small verifiable increments and implement test-first using installed skills.',
-        ''
-      ].join('\n');
-      safeWriteFile(filePath, existing.trimEnd() + '\n' + addition, {
-        overwrite: true,
-        dryRun,
-        silent
-      });
-      if (!silent) logger.dim('Appended Bootstrap section to existing AGENTS.md');
+    const scripts = readPackageManifest(targetDir)?.scripts;
+    const profile = projectProfile(config, { targetDir, scripts });
+    let updated = mergeAgentsBlock(existing, renderAgentsBlock(config, profile, options.docs));
+    if (!updated.includes('## Bootstrap & First Session'))
+      updated = updated.trimEnd() + '\n\n' + BOOTSTRAP_SECTION.join('\n') + '\n';
+    if (updated === existing) {
+      if (!silent) logger.dim('AGENTS.md is up to date, preserving content.');
       return true;
     }
-    if (!silent) logger.dim('AGENTS.md already exists, preserving content.');
-    return true;
+    if (!silent) logger.dim('Refreshed the aginit section of the existing AGENTS.md');
+    return safeWriteFile(filePath, updated, { overwrite: true, dryRun, silent });
   }
 
-  const content = generateAgentsMarkdown(config, readPackageManifest(targetDir)?.scripts);
+  const content = generateAgentsMarkdown(config, readPackageManifest(targetDir)?.scripts, targetDir);
   return safeWriteFile(filePath, content, { overwrite: true, dryRun, silent });
 }
 

package/src/adapters/e2e.ts

@@ -0,0 +1,58 @@
+import path from 'node:path';
+import { fileExists } from '../utils/fs.js';
+import { runExecutable } from '../utils/shell.js';
+import { logger } from '../utils/logger.js';
+import { e2eDirFor, Platform, Stack } from '../registry/index.js';
+
+const E2E_CONFIGS = ['e2e.config.ts', 'e2e.config.mts', 'e2e.config.js', 'e2e.config.mjs'];
+
+export function e2eConfigured(targetDir: string, stack: Stack): boolean {
+  const dir = path.join(targetDir, e2eDirFor(stack));
+  return E2E_CONFIGS.some((name) => fileExists(path.join(dir, name)));
+}
+
+/**
+ * Scaffold tester-army/e2e with its own `e2e init`: at the project root for
+ * Node projects, in an isolated `.agents/e2e/` workspace otherwise so the root
+ * never gets a package.json. The e2e skill comes from the Skills CLI, so init
+ * installs no skill or MCP entry; dependencies are installed by the user.
+ */
+export async function setupE2e(
+  targetDir: string,
+  options: { stack: Stack; platform: Platform; dryRun?: boolean; silent?: boolean }
+): Promise<boolean> {
+  const { stack, platform, dryRun = false, silent = false } = options;
+  if (e2eConfigured(targetDir, stack)) {
+    if (!silent) logger.dim('e2e is already configured, preserving it.');
+    return true;
+  }
+  const dir = e2eDirFor(stack);
+  const engine = platform === 'mobile-native' || platform === 'mobile-rn' ? 'mobile' : 'web';
+  const args = [
+    '-y',
+    'e2e@latest',
+    'init',
+    ...(dir ? [dir] : []),
+    '--yes',
+    '--engine',
+    engine,
+    '--skills',
+    'none',
+    '--mcp',
+    'none',
+    '--no-install'
+  ];
+  if (!silent) logger.dim(`Scaffolding e2e (${engine} engine) in ${dir || 'the project root'}...`);
+  const res = await runExecutable('npx', args, {
+    cwd: targetDir,
+    dryRun,
+    silent: true,
+    timeout: 600_000
+  });
+  if (!res.ok) {
+    logger.warn(`e2e init failed: ${res.stderr || res.stdout}`);
+    logger.dim(`  Retry manually: npx e2e init ${dir} --engine ${engine}`.replace(/\s+/g, ' '));
+    return false;
+  }
+  return true;
+}

package/src/adapters/skills.ts

@@ -162,3 +162,21 @@ export async function updateSkills(
   });
   return res.ok;
 }
+
+/** Remove skills from every agent through the Skills CLI (`npx skills remove`). */
+export async function removeSkills(
+  targetDir: string,
+  skills: string[],
+  options: { dryRun?: boolean; silent?: boolean } = {}
+): Promise<boolean> {
+  if (skills.length === 0) return true;
+  for (const skill of skills) validateUpstreamArgument(skill, 'skill name');
+  if (!options.silent) logger.dim(`Removing skills: ${skills.join(', ')}...`);
+  const res = await runExecutable('npx', ['-y', 'skills', 'remove', ...skills, '-y'], {
+    cwd: targetDir,
+    dryRun: options.dryRun,
+    silent: true
+  });
+  if (!res.ok) logger.warn(`Failed removing skills: ${res.stderr || res.stdout}`);
+  return res.ok;
+}