@meraki-digital/agent-init 1.0.0

package/README.md

@@ -0,0 +1,79 @@
+# agent-init
+
+Bootstrap repositories with Meraki agent infrastructure.
+
+## Installation
+
+```bash
+npm install -g @meraki-digital/agent-init
+```
+
+Or use directly without installing:
+
+```bash
+npx @meraki-digital/agent-init
+```
+
+## Usage
+
+Run in any repository you want to bootstrap:
+
+```bash
+cd your-project
+agent-init
+```
+
+The tool will:
+
+1. Check for `meraki-standards` as a sibling directory
+2. Clone it if missing (with your permission)
+3. Ask a few questions about your setup preferences
+4. Create the agent infrastructure:
+   - `AGENTS.md` (symlinked from meraki-standards)
+   - `PROJECT.md` (project-specific, you fill this in)
+   - `.amp/skills/` or `.claude/skills/` (symlinked)
+   - `agentic/prd/` structure (optional)
+
+## Options
+
+```
+--copy    Copy files instead of symlinking (Windows fallback)
+--update  Pull latest meraki-standards and verify symlinks
+--help    Show help message
+```
+
+## Updating
+
+After initial setup, run `--update` to pull the latest standards:
+
+```bash
+agent-init --update
+```
+
+This will:
+1. Pull latest changes to meraki-standards
+2. Verify all symlinks are intact
+3. Report any issues
+
+## Windows
+
+On Windows, symlinks require Developer Mode enabled. The tool will detect this and provide instructions, or you can use `--copy` to copy files instead.
+
+## Project Structure After Init
+
+```
+your-project/
+  AGENTS.md              # Symlink → ../meraki-standards/AGENTS.md
+  PROJECT.md             # Project-specific (edit this!)
+  .amp/skills/           # Symlink → ../meraki-standards/skills/
+  agentic/
+    prd/
+      proposed/{name}/   # PRDs in development
+      working/           # PRDs being implemented
+      completed/         # Archived PRDs
+```
+
+## Requirements
+
+- Node.js 18+
+- Git (for cloning meraki-standards)

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@meraki-digital/agent-init",
+  "version": "1.0.0",
+  "description": "Bootstrap repositories with Meraki agent infrastructure",
+  "type": "module",
+  "bin": {
+    "agent-init": "./src/cli.js"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "bootstrap",
+    "cli"
+  ],
+  "author": "Meraki Digital",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/meraki-digital/agent-init.git"
+  }
+}

package/src/cli.js

@@ -0,0 +1,372 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, symlinkSync, copyFileSync, cpSync, writeFileSync, lstatSync, readlinkSync } from 'fs';
+import { join, dirname } from 'path';
+import { execSync } from 'child_process';
+import * as readline from 'readline';
+
+const STANDARDS_REPO = 'https://github.com/meraki-digital/meraki-standards.git';
+const STANDARDS_DIR = '../meraki-standards';
+
+// Colors
+const colors = {
+  red: (s) => `\x1b[31m${s}\x1b[0m`,
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+  bold: (s) => `\x1b[1m${s}\x1b[0m`,
+};
+
+// Readline interface
+function createPrompt() {
+  return readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+}
+
+async function ask(rl, question) {
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      resolve(answer.trim());
+    });
+  });
+}
+
+// Check if symlinks work
+function canSymlink() {
+  const testTarget = join(process.env.TMPDIR || '/tmp', `agent-init-target-${process.pid}`);
+  const testLink = join(process.env.TMPDIR || '/tmp', `agent-init-link-${process.pid}`);
+  
+  try {
+    writeFileSync(testTarget, '');
+    symlinkSync(testTarget, testLink);
+    execSync(`rm -f "${testLink}" "${testTarget}"`, { stdio: 'ignore' });
+    return true;
+  } catch {
+    try {
+      execSync(`rm -f "${testTarget}"`, { stdio: 'ignore' });
+    } catch {}
+    return false;
+  }
+}
+
+// Check if Windows
+function isWindows() {
+  return process.platform === 'win32';
+}
+
+// Check if path is a symlink pointing to expected target
+function isValidSymlink(path, expectedTarget) {
+  try {
+    const stat = lstatSync(path);
+    if (!stat.isSymbolicLink()) return false;
+    const target = readlinkSync(path);
+    return target === expectedTarget;
+  } catch {
+    return false;
+  }
+}
+
+// Update mode
+async function runUpdate() {
+  console.log('');
+  console.log(colors.bold('agent-init --update'));
+  console.log('===================');
+  console.log('');
+
+  // Check meraki-standards exists
+  if (!existsSync(STANDARDS_DIR)) {
+    console.log(`${colors.red('✗')} meraki-standards not found at ${STANDARDS_DIR}/`);
+    console.log('  Run agent-init first to set up this repo.');
+    process.exit(1);
+  }
+
+  // Pull latest
+  console.log('Updating meraki-standards...');
+  try {
+    const result = execSync('git pull', { 
+      cwd: STANDARDS_DIR, 
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+    if (result.includes('Already up to date')) {
+      console.log(`  ${colors.green('✓')} Already up to date`);
+    } else {
+      const commits = result.match(/(\d+) files? changed/);
+      console.log(`  ${colors.green('✓')} Pulled latest${commits ? ` (${commits[0]})` : ''}`);
+    }
+  } catch (err) {
+    console.log(`  ${colors.yellow('!')} Could not pull: ${err.message}`);
+  }
+
+  // Check symlinks
+  console.log('');
+  console.log('Checking symlinks...');
+
+  const expectedLinks = [
+    { path: 'AGENTS.md', target: `${STANDARDS_DIR}/AGENTS.md` },
+    { path: 'instructions', target: `${STANDARDS_DIR}/instructions` },
+  ];
+
+  // Detect skills folder
+  if (existsSync('.amp/skills')) {
+    expectedLinks.push({ path: '.amp/skills', target: `${STANDARDS_DIR}/skills` });
+  } else if (existsSync('.claude/skills')) {
+    expectedLinks.push({ path: '.claude/skills', target: `${STANDARDS_DIR}/skills` });
+  }
+
+  let allGood = true;
+
+  for (const { path, target } of expectedLinks) {
+    if (!existsSync(path)) {
+      console.log(`  ${colors.red('✗')} ${path} (missing)`);
+      allGood = false;
+    } else if (isValidSymlink(path, target)) {
+      console.log(`  ${colors.green('✓')} ${path}`);
+    } else {
+      console.log(`  ${colors.yellow('!')} ${path} (not a symlink or wrong target)`);
+      allGood = false;
+    }
+  }
+
+  // Check PROJECT.md exists
+  if (existsSync('PROJECT.md')) {
+    console.log(`  · PROJECT.md (local file)`);
+  } else {
+    console.log(`  ${colors.yellow('!')} PROJECT.md (missing - run agent-init to create)`);
+  }
+
+  console.log('');
+  if (allGood) {
+    console.log(colors.green('All up to date.'));
+  } else {
+    console.log(colors.yellow('Some issues found. Run agent-init to fix.'));
+  }
+  console.log('');
+}
+
+// Clone meraki-standards
+function cloneStandards(targetDir) {
+  console.log('\nCloning meraki-standards...');
+  try {
+    execSync(`git clone ${STANDARDS_REPO} "${targetDir}"`, { stdio: 'inherit' });
+    console.log(`  ${colors.green('✓')} Cloned to ${targetDir}/`);
+    return true;
+  } catch (err) {
+    console.log(`  ${colors.red('✗')} Failed to clone: ${err.message}`);
+    return false;
+  }
+}
+
+// Create symlink or copy
+function linkOrCopy(src, dest, name, useCopy) {
+  if (existsSync(dest)) {
+    console.log(`  · ${name} (exists, skipped)`);
+    return;
+  }
+
+  try {
+    if (useCopy) {
+      try {
+        // Try directory copy first
+        cpSync(src, dest, { recursive: true });
+      } catch {
+        // Fall back to file copy
+        copyFileSync(src, dest);
+      }
+      console.log(`  ${colors.green('✓')} ${name} (copied)`);
+    } else {
+      symlinkSync(src, dest);
+      console.log(`  ${colors.green('✓')} ${name} (symlinked)`);
+    }
+  } catch (err) {
+    console.log(`  ${colors.red('✗')} ${name} failed: ${err.message}`);
+  }
+}
+
+// Create PROJECT.md
+function createProjectMd() {
+  if (existsSync('PROJECT.md')) {
+    console.log('  · PROJECT.md (exists, skipped)');
+    return;
+  }
+
+  const content = `# PROJECT.md
+
+<!--
+Project-specific instructions for AI agents.
+AGENTS.md (symlinked from meraki-standards) provides the generic foundation.
+This file adds context unique to this repository.
+
+Suggested sections:
+- Overview: What does this project do?
+- Tech Stack: Languages, frameworks, key dependencies
+- Commands: Build, test, lint, deploy
+- Structure: Key directories and their purpose
+- Conventions: Project-specific patterns
+-->
+
+## Overview
+
+## Tech Stack
+
+## Commands
+
+## Structure
+
+## Conventions
+`;
+
+  writeFileSync('PROJECT.md', content);
+  console.log(`  ${colors.green('✓')} PROJECT.md (created)`);
+}
+
+// Create directory if it doesn't exist
+function createDir(dir) {
+  if (existsSync(dir)) {
+    console.log(`  · ${dir}/ (exists, skipped)`);
+    return;
+  }
+  mkdirSync(dir, { recursive: true });
+  console.log(`  ${colors.green('✓')} ${dir}/`);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  let useCopy = args.includes('--copy');
+  const showHelp = args.includes('--help') || args.includes('-h');
+  const runUpdateMode = args.includes('--update');
+
+  if (showHelp) {
+    console.log('Usage: agent-init [--copy] [--update] [--help]');
+    console.log('');
+    console.log('Bootstrap a repository with Meraki agent infrastructure.');
+    console.log('');
+    console.log('Options:');
+    console.log('  --copy    Copy files instead of symlinking (Windows fallback)');
+    console.log('  --update  Pull latest meraki-standards and check symlinks');
+    console.log('  --help    Show this help message');
+    process.exit(0);
+  }
+
+  if (runUpdateMode) {
+    await runUpdate();
+    process.exit(0);
+  }
+
+  console.log('');
+  console.log(colors.bold('agent-init - Meraki Standards Bootstrap'));
+  console.log('========================================');
+  console.log('');
+
+  // Check for meraki-standards
+  console.log('Checking for meraki-standards repo...');
+  
+  if (!existsSync(STANDARDS_DIR)) {
+    console.log(`  ${colors.yellow('!')} Not found at ${STANDARDS_DIR}/`);
+    
+    const rl = createPrompt();
+    const answer = await ask(rl, '\nClone meraki-standards now? [Y/n]: ');
+    
+    if (answer.toLowerCase() === 'n') {
+      console.log('\nmeraki-standards is required. Clone it manually:');
+      console.log(`  cd ${dirname(process.cwd())}`);
+      console.log(`  git clone ${STANDARDS_REPO}`);
+      console.log('');
+      rl.close();
+      process.exit(1);
+    }
+    
+    rl.close();
+    
+    if (!cloneStandards(STANDARDS_DIR)) {
+      process.exit(1);
+    }
+  } else {
+    console.log(`  ${colors.green('✓')} Found at ${STANDARDS_DIR}/`);
+  }
+
+  // Windows symlink check
+  if (isWindows() && !useCopy) {
+    if (!canSymlink()) {
+      console.log('');
+      console.log(colors.yellow('Windows detected. Symlinks not enabled.'));
+      console.log('');
+      console.log('To enable symlinks (recommended):');
+      console.log('  1. Enable Developer Mode: Settings > System > For Developers');
+      console.log('  2. Run: git config --global core.symlinks true');
+      console.log('  3. Re-run this script');
+      console.log('');
+      console.log('Or run with --copy to copy files instead of symlinking:');
+      console.log('  agent-init --copy');
+      console.log('');
+      process.exit(1);
+    }
+  }
+
+  const rl = createPrompt();
+
+  // Interview
+  console.log('');
+  console.log('Skills folder');
+  console.log('  1) .amp/skills (default)');
+  console.log('  2) .claude/skills');
+  const skillsChoice = await ask(rl, 'Choice [1]: ');
+  const skillsFolder = skillsChoice === '2' ? '.claude/skills' : '.amp/skills';
+
+  console.log('');
+  const projectInput = await ask(rl, 'Project name for initial PRD folder [initial]: ');
+  const projectName = projectInput || 'initial';
+
+  console.log('');
+  const prdInput = await ask(rl, 'Create agentic/prd structure? [Y/n]: ');
+  const createPrd = prdInput.toLowerCase() !== 'n';
+
+  rl.close();
+
+  console.log('');
+  console.log('Creating structure...');
+
+  // AGENTS.md
+  linkOrCopy(`${STANDARDS_DIR}/AGENTS.md`, 'AGENTS.md', 'AGENTS.md', useCopy);
+
+  // PROJECT.md
+  createProjectMd();
+
+  // Skills folder
+  const skillsParent = dirname(skillsFolder);
+  if (skillsParent !== '.') {
+    mkdirSync(skillsParent, { recursive: true });
+  }
+  // Extra ../ because we're inside .amp/ or .claude/
+  linkOrCopy(`../${STANDARDS_DIR}/skills`, skillsFolder, `${skillsFolder}/`, useCopy);
+
+  // Instructions folder
+  linkOrCopy(`${STANDARDS_DIR}/instructions`, 'instructions', 'instructions/', useCopy);
+
+  // PRD structure
+  if (createPrd) {
+    createDir(`agentic/prd/proposed/${projectName}`);
+    createDir('agentic/prd/working');
+    createDir('agentic/prd/completed');
+  }
+
+  console.log('');
+  console.log('Done. Next steps:');
+  console.log('  - Edit PROJECT.md with project-specific details');
+  if (createPrd) {
+    console.log(`  - Add seed.md to agentic/prd/proposed/${projectName}/`);
+  }
+
+  if (useCopy) {
+    console.log('');
+    console.log(colors.yellow('Note: Files were copied, not symlinked. They may drift from meraki-standards.'));
+  }
+
+  console.log('');
+}
+
+main().catch((err) => {
+  console.error(colors.red(`Error: ${err.message}`));
+  process.exit(1);
+});