aiknowsys 0.0.1

package/bin/cli.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { init } from '../lib/commands/init.js';
+import { scan } from '../lib/commands/scan.js';
+import { migrate } from '../lib/commands/migrate.js';
+import { installAgents } from '../lib/commands/install-agents.js';
+import { installSkills } from '../lib/commands/install-skills.js';
+
+// Get version from package.json
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+let packageJson;
+try {
+  packageJson = JSON.parse(
+    readFileSync(join(__dirname, '../package.json'), 'utf-8')
+  );
+} catch (error) {
+  console.error(chalk.red('Error: Could not read package.json'));
+  process.exit(1);
+}
+
+const program = new Command();
+
+program
+  .name('aiknowsys')
+  .description('AI-Powered Development Workflow for Consistent, High-Quality Code')
+  .version(packageJson.version);
+
+program
+  .command('init')
+  .description('Initialize knowledge system for a new project')
+  .option('-d, --dir <directory>', 'Target directory', '.')
+  .option('-y, --yes', 'Skip prompts and use defaults')
+  .action(init);
+
+program
+  .command('scan')
+  .description('Scan existing codebase and generate draft ESSENTIALS')
+  .option('-d, --dir <directory>', 'Project directory to scan', '.')
+  .option('-o, --output <file>', 'Output file name', 'CODEBASE_ESSENTIALS.draft.md')
+  .action(scan);
+
+program
+  .command('migrate')
+  .description('Full migration workflow for existing projects')
+  .option('-d, --dir <directory>', 'Project directory', '.')
+  .action(migrate);
+
+program
+  .command('install-agents')
+  .description('Install Developer + Architect custom agents')
+  .option('-d, --dir <directory>', 'Target directory', '.')
+  .option('-e, --essentials <file>', 'ESSENTIALS file name', 'CODEBASE_ESSENTIALS.md')
+  .action(installAgents);
+
+program
+  .command('install-skills')
+  .description('Install universal skills to .github/skills/')
+  .option('-d, --dir <directory>', 'Target directory', '.')
+  .option('-s, --skills <skills...>', 'Specific skills to install')
+  .action(installSkills);
+
+// Default command - show help with styled banner
+program
+  .action(() => {
+    console.log('');
+    console.log(chalk.cyan('  ╔════════════════════════════════════════════════════════╗'));
+    console.log(chalk.cyan('  ║') + chalk.bold.white('         🎯 Knowledge System Template                   ') + chalk.cyan('║'));
+    console.log(chalk.cyan('  ║') + chalk.gray('         AI-Powered Development Workflow                ') + chalk.cyan('║'));
+    console.log(chalk.cyan('  ╚════════════════════════════════════════════════════════╝'));
+    console.log('');
+    program.outputHelp();
+  });
+
+program.parse();

package/lib/commands/init.js

@@ -0,0 +1,227 @@
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import ora from 'ora';
+import { getPackageDir, copyTemplate, hasExistingProject } from '../utils.js';
+
+export async function init(options) {
+  const targetDir = path.resolve(options.dir);
+  
+  console.log('');
+  console.log(chalk.cyan.bold('🎯 Knowledge System Setup'));
+  console.log('');
+  
+  // Check for existing project
+  if (hasExistingProject(targetDir)) {
+    console.log(chalk.yellow('🔍 Existing project detected!'));
+    console.log('');
+    
+    if (!options.yes) {
+      const { mode } = await inquirer.prompt([{
+        type: 'list',
+        name: 'mode',
+        message: 'Choose setup mode:',
+        choices: [
+          { name: 'Scan existing codebase (recommended)', value: 'scan' },
+          { name: 'Manual setup (blank templates)', value: 'manual' }
+        ]
+      }]);
+      
+      if (mode === 'scan') {
+        const { migrate } = await import('./migrate.js');
+        return migrate({ dir: targetDir });
+      }
+    }
+  }
+  
+  console.log(chalk.blue('📝 Starting fresh project setup...'));
+  console.log('');
+  
+  // Step 1: Technology Stack
+  const answers = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'language',
+      message: 'What\'s your primary language?',
+      choices: [
+        { name: 'TypeScript/JavaScript', value: 'typescript' },
+        { name: 'Python', value: 'python' },
+        { name: 'Rust', value: 'rust' },
+        { name: 'Go', value: 'go' },
+        { name: 'Other', value: 'other' }
+      ]
+    },
+    {
+      type: 'input',
+      name: 'customLanguage',
+      message: 'Enter language name:',
+      when: (ans) => ans.language === 'other'
+    },
+    {
+      type: 'list',
+      name: 'framework',
+      message: 'Frontend framework?',
+      when: (ans) => ans.language === 'typescript',
+      choices: [
+        { name: 'Vue', value: 'vue' },
+        { name: 'React', value: 'react' },
+        { name: 'Svelte', value: 'svelte' },
+        { name: 'Angular', value: 'angular' },
+        { name: 'Next.js', value: 'nextjs' },
+        { name: 'Vanilla/Other', value: 'vanilla' }
+      ]
+    },
+    {
+      type: 'list',
+      name: 'framework',
+      message: 'Backend framework?',
+      when: (ans) => ans.language === 'python',
+      choices: [
+        { name: 'Django', value: 'django' },
+        { name: 'FastAPI', value: 'fastapi' },
+        { name: 'Flask', value: 'flask' },
+        { name: 'Other', value: 'other' }
+      ]
+    },
+    {
+      type: 'input',
+      name: 'projectName',
+      message: 'Project name:',
+      default: path.basename(targetDir)
+    },
+    {
+      type: 'confirm',
+      name: 'useOpenSpec',
+      message: 'Use OpenSpec for spec-driven development? (recommended for teams)',
+      default: false
+    }
+  ]);
+  
+  const spinner = ora('Creating knowledge system files...').start();
+  
+  try {
+    const packageDir = getPackageDir();
+    
+    // Ensure target directory exists
+    if (!fs.existsSync(targetDir)) {
+      fs.mkdirSync(targetDir, { recursive: true });
+    }
+    
+    // Copy template files
+    copyTemplate(
+      path.join(packageDir, 'CODEBASE_ESSENTIALS.template.md'),
+      path.join(targetDir, 'CODEBASE_ESSENTIALS.md'),
+      {
+        '{{PROJECT_NAME}}': answers.projectName,
+        '{{LANGUAGE}}': answers.customLanguage || getLanguageName(answers.language),
+        '{{FRAMEWORK}}': getFrameworkName(answers.framework),
+        '{{DATE}}': new Date().toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' })
+      }
+    );
+    
+    copyTemplate(
+      path.join(packageDir, 'AGENTS.template.md'),
+      path.join(targetDir, 'AGENTS.md')
+    );
+    
+    copyTemplate(
+      path.join(packageDir, 'CODEBASE_CHANGELOG.template.md'),
+      path.join(targetDir, 'CODEBASE_CHANGELOG.md'),
+      {
+        '{{PROJECT_NAME}}': answers.projectName,
+        '{{DATE}}': new Date().toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' })
+      }
+    );
+    
+    spinner.succeed('Core files created');
+    
+    // Install agents
+    const agentSpinner = ora('Installing custom agents...').start();
+    const { installAgents } = await import('./install-agents.js');
+    await installAgents({ dir: targetDir, essentials: 'CODEBASE_ESSENTIALS.md', _silent: true });
+    agentSpinner.succeed('Custom agents installed');
+    
+    // Install skills
+    const skillsSpinner = ora('Installing universal skills...').start();
+    const { installSkills } = await import('./install-skills.js');
+    await installSkills({ dir: targetDir, _silent: true });
+    skillsSpinner.succeed('Universal skills installed');
+    
+    console.log('');
+    console.log(chalk.green.bold('✅ Knowledge system initialized!'));
+    console.log('');
+    console.log(chalk.white('📁 Created files:'));
+    console.log(chalk.gray('   • CODEBASE_ESSENTIALS.md'));
+    console.log(chalk.gray('   • AGENTS.md'));
+    console.log(chalk.gray('   • CODEBASE_CHANGELOG.md'));
+    console.log(chalk.gray('   • .github/agents/developer.agent.md'));
+    console.log(chalk.gray('   • .github/agents/architect.agent.md'));
+    console.log(chalk.gray('   • .github/skills/'));
+    console.log('');
+    console.log(chalk.cyan('📖 Next steps:'));
+    console.log(chalk.white('   1. Complete TODO sections in CODEBASE_ESSENTIALS.md'));
+    console.log(chalk.white('   2. Customize validation matrix in AGENTS.md'));
+    console.log(chalk.white('   3. Start using: @Developer <your request>'));
+    
+    // OpenSpec installation
+    if (answers.useOpenSpec) {
+      console.log('');
+      const openSpecSpinner = ora('Installing OpenSpec...').start();
+      try {
+        // Check if openspec is already installed globally
+        try {
+          execSync('openspec --version', { stdio: 'pipe' });
+          openSpecSpinner.text = 'OpenSpec already installed, initializing...';
+        } catch {
+          // Not installed, install it
+          execSync('npm install -g openspec', { stdio: 'pipe', cwd: targetDir });
+        }
+        
+        // Initialize openspec in the project
+        execSync('openspec init', { stdio: 'pipe', cwd: targetDir });
+        openSpecSpinner.succeed('OpenSpec installed and initialized');
+        
+        console.log(chalk.gray('   • openspec/project.md'));
+        console.log(chalk.gray('   • openspec/AGENTS.md'));
+      } catch (error) {
+        openSpecSpinner.warn('OpenSpec installation failed (you can install manually)');
+        if (error.message) {
+          console.log(chalk.gray(`   Reason: ${error.message.split('\n')[0]}`));
+        }
+        console.log(chalk.gray('   Run: npm install -g openspec && openspec init'));
+      }
+    }
+    console.log('');
+    
+  } catch (error) {
+    spinner.fail('Failed to initialize');
+    console.error(chalk.red(error.message));
+    process.exit(1);
+  }
+}
+
+function getLanguageName(key) {
+  const names = {
+    typescript: 'TypeScript',
+    python: 'Python',
+    rust: 'Rust',
+    go: 'Go'
+  };
+  return names[key] || key;
+}
+
+function getFrameworkName(key) {
+  const names = {
+    vue: 'Vue 3',
+    react: 'React',
+    svelte: 'Svelte',
+    angular: 'Angular',
+    nextjs: 'Next.js',
+    django: 'Django',
+    fastapi: 'FastAPI',
+    flask: 'Flask'
+  };
+  return names[key] || key || 'None specified';
+}

package/lib/commands/install-agents.js

@@ -0,0 +1,100 @@
+import fs from 'fs';
+import path from 'path';
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import ora from 'ora';
+import { getPackageDir, copyTemplate } from '../utils.js';
+
+export async function installAgents(options) {
+  const targetDir = path.resolve(options.dir);
+  const essentialsFile = options.essentials || 'CODEBASE_ESSENTIALS.md';
+  const silent = options._silent || false;
+  
+  if (!silent) {
+    console.log('');
+    console.log(chalk.cyan.bold('🤖 Installing Custom Agents (Developer + Architect Workflow)'));
+    console.log('');
+  }
+  
+  const packageDir = getPackageDir();
+  const agentsDir = path.join(targetDir, '.github', 'agents');
+  
+  // Create agents directory
+  if (!fs.existsSync(agentsDir)) {
+    fs.mkdirSync(agentsDir, { recursive: true });
+  }
+  
+  const spinner = silent ? null : ora('Copying agent templates...').start();
+  
+  try {
+    // Copy agent templates
+    copyTemplate(
+      path.join(packageDir, 'templates', 'agents', 'developer.agent.template.md'),
+      path.join(agentsDir, 'developer.agent.md'),
+      {
+        '{{ESSENTIALS_FILE}}': essentialsFile,
+        '{{PROJECT_GUIDELINES}}': 'None specified'
+      }
+    );
+    
+    copyTemplate(
+      path.join(packageDir, 'templates', 'agents', 'architect.agent.template.md'),
+      path.join(agentsDir, 'architect.agent.md'),
+      {
+        '{{ESSENTIALS_FILE}}': essentialsFile
+      }
+    );
+    
+    // Copy README
+    copyTemplate(
+      path.join(packageDir, 'templates', 'agents', 'README.md'),
+      path.join(agentsDir, 'README.md')
+    );
+    
+    if (spinner) spinner.succeed('Agent templates installed');
+    
+    // Ask for project-specific guidelines (only in interactive mode)
+    if (!silent) {
+      const { addGuidelines } = await inquirer.prompt([{
+        type: 'confirm',
+        name: 'addGuidelines',
+        message: 'Do you want to add project-specific guidelines for the Developer agent?',
+        default: false
+      }]);
+      
+      if (addGuidelines) {
+        const { guidelines } = await inquirer.prompt([{
+          type: 'input',
+          name: 'guidelines',
+          message: 'Enter guidelines:'
+        }]);
+        
+        if (guidelines) {
+          const devAgentPath = path.join(agentsDir, 'developer.agent.md');
+          let content = fs.readFileSync(devAgentPath, 'utf-8');
+          content = content.replace('None specified', guidelines);
+          fs.writeFileSync(devAgentPath, content);
+        }
+      }
+      
+      console.log('');
+      console.log(chalk.green.bold('✅ Custom agents installed successfully!'));
+      console.log('');
+      console.log(chalk.white('📍 Location: .github/agents/'));
+      console.log(chalk.gray('   • developer.agent.md    (Primary implementer)'));
+      console.log(chalk.gray('   • architect.agent.md    (Code reviewer)'));
+      console.log(chalk.gray('   • README.md             (Usage guide)'));
+      console.log('');
+      console.log(chalk.cyan.bold('🚀 Usage in VS Code:'));
+      console.log(chalk.white('   @Developer <your request>     → Implements and auto-reviews'));
+      console.log(chalk.white('   @SeniorArchitect <file>       → Direct review request'));
+      console.log('');
+    }
+    
+  } catch (error) {
+    if (spinner) spinner.fail('Failed to install agents');
+    console.error(chalk.red(error.message));
+    if (!silent) process.exit(1);
+    throw error;
+  }
+}

package/lib/commands/install-skills.js

@@ -0,0 +1,92 @@
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import ora from 'ora';
+import { getPackageDir, copyDirectory } from '../utils.js';
+
+const AVAILABLE_SKILLS = [
+  'code-refactoring',
+  'dependency-updates',
+  'documentation-management',
+  'skill-creator'
+];
+
+export async function installSkills(options) {
+  const targetDir = path.resolve(options.dir);
+  const selectedSkills = options.skills || AVAILABLE_SKILLS;
+  const silent = options._silent || false;
+  
+  if (!silent) {
+    console.log('');
+    console.log(chalk.cyan.bold('📚 Installing Universal Skills'));
+    console.log('');
+  }
+  
+  const packageDir = getPackageDir();
+  const skillsDir = path.join(targetDir, '.github', 'skills');
+  
+  // Create skills directory
+  if (!fs.existsSync(skillsDir)) {
+    fs.mkdirSync(skillsDir, { recursive: true });
+  }
+  
+  const spinner = silent ? null : ora('Installing skills...').start();
+  
+  let installed = 0;
+  let skipped = 0;
+  
+  try {
+    for (const skill of selectedSkills) {
+      const sourcePath = path.join(packageDir, 'templates', 'skills', skill);
+      const destPath = path.join(skillsDir, skill);
+      
+      if (!fs.existsSync(sourcePath)) {
+        if (!silent) {
+          console.log(chalk.yellow(`   ⚠️  Skill not found: ${skill}`));
+        }
+        continue;
+      }
+      
+      if (fs.existsSync(destPath)) {
+        skipped++;
+        continue;
+      }
+      
+      copyDirectory(sourcePath, destPath);
+      installed++;
+    }
+    
+    if (spinner) {
+      if (installed > 0) {
+        spinner.succeed(`Installed ${installed} skill${installed > 1 ? 's' : ''}`);
+      } else if (skipped > 0) {
+        spinner.succeed('All skills already installed');
+      } else {
+        spinner.warn('No skills found to install');
+      }
+    }
+    
+    if (!silent) {
+      console.log('');
+      console.log(chalk.white('📍 Location: .github/skills/'));
+      
+      for (const skill of AVAILABLE_SKILLS) {
+        const destPath = path.join(skillsDir, skill);
+        if (fs.existsSync(destPath)) {
+          console.log(chalk.gray(`   ✅ ${skill}`));
+        }
+      }
+      
+      console.log('');
+      console.log(chalk.cyan('💡 Skills provide domain-specific guidance for AI assistants'));
+      console.log(chalk.gray('   Use by asking about the topic, e.g., "How do I update dependencies?"'));
+      console.log('');
+    }
+    
+  } catch (error) {
+    if (spinner) spinner.fail('Failed to install skills');
+    console.error(chalk.red(error.message));
+    if (!silent) process.exit(1);
+    throw error;
+  }
+}

package/lib/commands/migrate.js

@@ -0,0 +1,161 @@
+import fs from 'fs';
+import path from 'path';
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import ora from 'ora';
+import { scan } from './scan.js';
+import { installAgents } from './install-agents.js';
+import { installSkills } from './install-skills.js';
+import { getPackageDir, copyTemplate } from '../utils.js';
+
+export async function migrate(options) {
+  const targetDir = path.resolve(options.dir);
+  
+  console.log('');
+  console.log(chalk.cyan.bold('🚀 Knowledge System Migration (Existing Project)'));
+  console.log('');
+  console.log(chalk.white('This will:'));
+  console.log(chalk.gray('  1. Scan your codebase'));
+  console.log(chalk.gray('  2. Generate draft documentation'));
+  console.log(chalk.gray('  3. Install custom agents'));
+  console.log(chalk.gray('  4. Set up skills'));
+  console.log(chalk.gray('  5. Initialize changelog'));
+  console.log('');
+  
+  const { proceed } = await inquirer.prompt([{
+    type: 'confirm',
+    name: 'proceed',
+    message: 'Continue?',
+    default: true
+  }]);
+  
+  if (!proceed) {
+    console.log(chalk.yellow('Migration cancelled.'));
+    return;
+  }
+  
+  // Step 1: Scan codebase
+  console.log('');
+  console.log(chalk.cyan('══════════════════════════════════════════'));
+  console.log(chalk.cyan.bold('Step 1/5: Scanning codebase...'));
+  console.log(chalk.cyan('══════════════════════════════════════════'));
+  
+  const findings = await scan({ dir: targetDir, output: 'CODEBASE_ESSENTIALS.draft.md' });
+  
+  // Step 2: Review draft
+  console.log('');
+  console.log(chalk.cyan('══════════════════════════════════════════'));
+  console.log(chalk.cyan.bold('Step 2/5: Review generated draft'));
+  console.log(chalk.cyan('══════════════════════════════════════════'));
+  console.log('');
+  console.log(chalk.yellow.bold('📝 CODEBASE_ESSENTIALS.draft.md has been created'));
+  console.log('');
+  console.log(chalk.white('IMPORTANT: You must complete the TODO sections!'));
+  console.log('');
+  console.log(chalk.gray('Required sections to fill in:'));
+  console.log(chalk.gray('  - Core Patterns (how you structure code, handle auth, make API calls)'));
+  console.log(chalk.gray('  - Critical Invariants (rules that must never be violated)'));
+  console.log(chalk.gray('  - Common Gotchas (issues new contributors encounter)'));
+  console.log(chalk.gray('  - Architecture Decisions (why you chose this approach)'));
+  console.log('');
+  
+  const { reviewed } = await inquirer.prompt([{
+    type: 'confirm',
+    name: 'reviewed',
+    message: 'Have you completed and renamed the file to CODEBASE_ESSENTIALS.md?',
+    default: false
+  }]);
+  
+  const essentialsPath = path.join(targetDir, 'CODEBASE_ESSENTIALS.md');
+  const draftPath = path.join(targetDir, 'CODEBASE_ESSENTIALS.draft.md');
+  
+  if (!reviewed && !fs.existsSync(essentialsPath)) {
+    const { action } = await inquirer.prompt([{
+      type: 'list',
+      name: 'action',
+      message: 'CODEBASE_ESSENTIALS.md not found. What would you like to do?',
+      choices: [
+        { name: 'Rename draft file now and continue', value: 'rename' },
+        { name: 'Continue anyway (not recommended)', value: 'continue' },
+        { name: 'Exit and complete the file first', value: 'exit' }
+      ]
+    }]);
+    
+    if (action === 'exit') {
+      console.log(chalk.yellow('Complete CODEBASE_ESSENTIALS.md and run: npx aiknowsys migrate'));
+      return;
+    }
+    
+    if (action === 'rename' && fs.existsSync(draftPath)) {
+      fs.renameSync(draftPath, essentialsPath);
+      console.log(chalk.green('✅ Renamed to CODEBASE_ESSENTIALS.md'));
+    }
+  }
+  
+  // Step 3: Generate AGENTS.md
+  console.log('');
+  console.log(chalk.cyan('══════════════════════════════════════════'));
+  console.log(chalk.cyan.bold('Step 3/5: Creating AGENTS.md'));
+  console.log(chalk.cyan('══════════════════════════════════════════'));
+  
+  const agentsPath = path.join(targetDir, 'AGENTS.md');
+  if (!fs.existsSync(agentsPath)) {
+    const packageDir = getPackageDir();
+    copyTemplate(
+      path.join(packageDir, 'AGENTS.template.md'),
+      agentsPath
+    );
+    console.log(chalk.green('✅ AGENTS.md created (customize validation matrix as needed)'));
+  } else {
+    console.log(chalk.gray('⏭️  AGENTS.md already exists, skipping'));
+  }
+  
+  // Step 4: Install custom agents
+  console.log('');
+  console.log(chalk.cyan('══════════════════════════════════════════'));
+  console.log(chalk.cyan.bold('Step 4/5: Installing custom agents...'));
+  console.log(chalk.cyan('══════════════════════════════════════════'));
+  
+  await installAgents({ dir: targetDir, essentials: 'CODEBASE_ESSENTIALS.md' });
+  
+  // Step 5: Install skills
+  console.log('');
+  console.log(chalk.cyan('══════════════════════════════════════════'));
+  console.log(chalk.cyan.bold('Step 5/5: Installing universal skills...'));
+  console.log(chalk.cyan('══════════════════════════════════════════'));
+  
+  await installSkills({ dir: targetDir });
+  
+  // Initialize changelog
+  const changelogPath = path.join(targetDir, 'CODEBASE_CHANGELOG.md');
+  if (!fs.existsSync(changelogPath)) {
+    const packageDir = getPackageDir();
+    const projectName = path.basename(targetDir);
+    copyTemplate(
+      path.join(packageDir, 'CODEBASE_CHANGELOG.template.md'),
+      changelogPath,
+      {
+        '{{PROJECT_NAME}}': projectName,
+        '{{DATE}}': new Date().toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' })
+      }
+    );
+    console.log(chalk.green('✅ CODEBASE_CHANGELOG.md initialized'));
+  }
+  
+  // Final summary
+  console.log('');
+  console.log(chalk.green.bold('═══════════════════════════════════════════'));
+  console.log(chalk.green.bold('  ✅ Migration Complete!'));
+  console.log(chalk.green.bold('═══════════════════════════════════════════'));
+  console.log('');
+  console.log(chalk.white('📁 Created files:'));
+  console.log(chalk.gray('   • CODEBASE_ESSENTIALS.md'));
+  console.log(chalk.gray('   • AGENTS.md'));
+  console.log(chalk.gray('   • CODEBASE_CHANGELOG.md'));
+  console.log(chalk.gray('   • .github/agents/'));
+  console.log(chalk.gray('   • .github/skills/'));
+  console.log('');
+  console.log(chalk.cyan.bold('🚀 Start using:'));
+  console.log(chalk.white('   @Developer <your request>'));
+  console.log('');
+}