cp-toolkit 2.0.0

package/README.md

@@ -0,0 +1,130 @@
+# cp-toolkit
+
+> GitHub Copilot Agent Toolkit - Initialize and manage AI agents for your project
+
+## Installation
+
+```bash
+# Global install
+npm install -g cp-toolkit
+
+# Or use with npx
+npx cp-toolkit init
+```
+
+## Quick Start
+
+```bash
+# Initialize in current directory
+cp-kit init
+
+# Initialize in new directory
+cp-kit init my-project
+
+# Skip prompts (use defaults)
+cp-kit init -y
+```
+
+## Commands
+
+### `cp-kit init [directory]`
+
+Initialize cp-kit with GitHub Copilot 2026 structure:
+
+```
+.github/
+├── copilot-instructions.md    # Global instructions (always active)
+├── agents/                    # Agent definitions
+│   ├── orchestrator.md
+│   ├── frontend-specialist.md
+│   └── backend-specialist.md
+└── instructions/              # Path-specific rules
+    ├── typescript.instructions.md
+    ├── python.instructions.md
+    └── security.instructions.md
+
+AGENTS.md                      # Universal AI instructions
+.vscode/mcp.json              # MCP server configuration
+```
+
+Options:
+- `-y, --yes` - Skip prompts, use defaults
+- `-f, --force` - Overwrite existing configuration
+
+### `cp-kit add <type> <name>`
+
+Add new components:
+
+```bash
+# Add a new agent
+cp-kit add agent my-specialist
+
+# Add a new instruction
+cp-kit add instruction golang
+```
+
+### `cp-kit list [type]`
+
+List available components:
+
+```bash
+cp-kit list agents       # List all agents
+cp-kit list instructions # List all instructions
+cp-kit list all          # List everything
+```
+
+### `cp-kit doctor`
+
+Check configuration and diagnose issues:
+
+```bash
+cp-kit doctor
+```
+
+## GitHub Copilot Integration
+
+After initialization, GitHub Copilot automatically loads:
+
+1. **copilot-instructions.md** - Always active, global rules
+2. **agents/*.md** - Invokable with `@agent-name`
+3. **instructions/*.instructions.md** - Applied based on `applyTo` patterns
+
+### Using Agents
+
+In GitHub Copilot Chat:
+
+```
+@frontend-specialist Create a responsive navbar component
+@security-auditor Review this authentication flow
+@orchestrator Implement user dashboard with API
+```
+
+### Path-Specific Instructions
+
+Instructions are applied automatically based on file patterns:
+
+```yaml
+# typescript.instructions.md
+---
+applyTo: "**/*.ts,**/*.tsx"
+---
+
+## TypeScript Guidelines
+- Enable strict mode
+- No any types
+...
+```
+
+## Structure
+
+| File | Purpose |
+|------|---------|
+| `.github/copilot-instructions.md` | Global instructions (always active) |
+| `.github/agents/*.md` | Agent definitions |
+| `.github/instructions/*.instructions.md` | Path-specific rules |
+| `AGENTS.md` | Universal AI instructions |
+| `.vscode/mcp.json` | MCP server configuration |
+
+## License
+
+MIT

package/bin/cp-kit.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+/**
+ * cp-kit - GitHub Copilot Agent Toolkit
+ * 
+ * Initialize and manage AI agents for GitHub Copilot.
+ * 
+ * Usage:
+ *   npx cp-kit init              # Initialize in current directory
+ *   npx cp-kit init my-project   # Initialize in new directory
+ *   cp-kit add agent <name>      # Add a new agent
+ *   cp-kit add instruction <name># Add a new instruction
+ *   cp-kit list agents           # List available agents
+ *   cp-kit list instructions     # List available instructions
+ *   cp-kit doctor                # Check configuration
+ * 
+ * @version 1.0.0
+ * @license MIT
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { initCommand } from '../src/commands/init.js';
+import { addCommand } from '../src/commands/add.js';
+import { listCommand } from '../src/commands/list.js';
+import { doctorCommand } from '../src/commands/doctor.js';
+
+const program = new Command();
+
+program
+  .name('cp-kit')
+  .description('GitHub Copilot Agent Toolkit - Initialize AI agents for your project')
+  .version('1.0.0');
+
+// cp-kit init [directory]
+program
+  .command('init [directory]')
+  .description('Initialize cp-kit in a directory (creates .github/ structure)')
+  .option('-y, --yes', 'Skip prompts and use defaults')
+  .option('-f, --force', 'Overwrite existing configuration')
+  .action(initCommand);
+
+// cp-kit add <type> <name>
+program
+  .command('add <type> <name>')
+  .description('Add a new agent or instruction')
+  .option('-t, --template <template>', 'Use a specific template')
+  .action(addCommand);
+
+// cp-kit list [type]
+program
+  .command('list [type]')
+  .description('List available agents or instructions')
+  .action((type = 'all') => listCommand(type));
+
+// cp-kit doctor
+program
+  .command('doctor')
+  .description('Check cp-kit configuration and diagnose issues')
+  .action(doctorCommand);
+
+// Show help if no command provided
+if (process.argv.length === 2) {
+  console.log('');
+  console.log(chalk.bold.cyan('  🤖 cp-kit - GitHub Copilot Agent Toolkit'));
+  console.log('');
+  console.log(chalk.gray('  Initialize AI agents and instructions for GitHub Copilot'));
+  console.log('');
+  program.outputHelp();
+}
+
+program.parse();

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "cp-toolkit",
+  "version": "2.0.0",
+  "description": "Copilot Toolkit - AI Agent framework for GitHub Copilot, Claude, Gemini CLI, and other AI assistants",
+  "keywords": [
+    "ai-agents",
+    "github-copilot",
+    "copilot",
+    "gemini-cli",
+    "claude",
+    "mcp",
+    "model-context-protocol",
+    "agent-toolkit"
+  ],
+  "author": "NuvemTalk",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gensart-projs/cp-kit"
+  },
+  "type": "module",
+  "bin": {
+    "cp-kit": "./bin/cp-kit.js"
+  },
+  "main": "./src/index.js",
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test src/**/*.test.js",
+    "start": "node bin/cp-kit.js"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "chalk": "^5.3.0",
+    "ora": "^8.0.0",
+    "prompts": "^2.4.2",
+    "fs-extra": "^11.2.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/src/commands/add.js

@@ -0,0 +1,212 @@
+/**
+ * cp-kit add command
+ * 
+ * Add new agents or instructions to a cp-kit project.
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+import chalk from 'chalk';
+import prompts from 'prompts';
+
+const AGENT_TEMPLATES = {
+  specialist: (name, description, triggers) => `---
+name: ${name}
+description: ${description}
+---
+
+# ${name}
+
+> ${description}
+
+## When to Use
+
+Invoke this agent for:
+${triggers.map(t => `- ${t} related tasks`).join('\n')}
+
+## Trigger Keywords
+
+\`${triggers.join('`, `')}\`
+
+## Response Format
+
+\`\`\`
+🤖 **Applying @${name}...**
+
+[specialized response]
+\`\`\`
+`,
+  reviewer: (name, description, triggers) => `---
+name: ${name}
+description: ${description}
+---
+
+# ${name}
+
+> ${description}
+
+## Review Checklist
+
+- [ ] Code follows project conventions
+- [ ] No security vulnerabilities
+- [ ] Adequate test coverage
+- [ ] Performance considerations
+- [ ] Documentation updated
+
+## Trigger Keywords
+
+\`${triggers.join('`, `')}\`
+
+## Response Format
+
+\`\`\`
+🔍 **Review by @${name}**
+
+### Summary
+[brief overview]
+
+### Issues Found
+[list with severity]
+
+### Recommendations
+[suggested improvements]
+\`\`\`
+`
+};
+
+export async function addCommand(type, name, options) {
+  const targetDir = process.cwd();
+  
+  // Validate type
+  const validTypes = ['agent', 'instruction'];
+  if (!validTypes.includes(type)) {
+    console.log(chalk.red(`❌ Unknown type: ${type}`));
+    console.log(chalk.dim(`   Valid types: ${validTypes.join(', ')}`));
+    return;
+  }
+  
+  // Check if cp-kit is initialized
+  const githubDir = path.join(targetDir, '.github');
+  if (!fs.existsSync(path.join(githubDir, 'copilot-instructions.md'))) {
+    console.log(chalk.red('❌ cp-kit not initialized.'));
+    console.log(chalk.dim('   Run: cp-kit init'));
+    return;
+  }
+  
+  console.log(chalk.bold.cyan(`\n➕ Adding ${type}: ${name}\n`));
+  
+  switch (type) {
+    case 'agent':
+      await addAgent(githubDir, name, options);
+      break;
+    case 'instruction':
+      await addInstruction(githubDir, name, options);
+      break;
+  }
+}
+
+async function addAgent(githubDir, name, options) {
+  const agentFile = path.join(githubDir, 'agents', `${name}.md`);
+  
+  if (fs.existsSync(agentFile)) {
+    console.log(chalk.yellow(`⚠️  Agent "${name}" already exists.`));
+    return;
+  }
+  
+  const response = await prompts([
+    {
+      type: 'text',
+      name: 'description',
+      message: 'Agent description:',
+      initial: `${name} specialist agent`
+    },
+    {
+      type: 'text',
+      name: 'triggers',
+      message: 'Trigger keywords (comma-separated):',
+      initial: name.replace(/-/g, ', ')
+    },
+    {
+      type: 'select',
+      name: 'template',
+      message: 'Template:',
+      choices: [
+        { title: 'Specialist - General purpose', value: 'specialist' },
+        { title: 'Reviewer - Code review focus', value: 'reviewer' }
+      ]
+    }
+  ]);
+  
+  if (!response.description) {
+    console.log(chalk.yellow('Aborted.'));
+    return;
+  }
+  
+  const triggers = response.triggers.split(',').map(t => t.trim());
+  const content = AGENT_TEMPLATES[response.template](name, response.description, triggers);
+  
+  await fs.ensureDir(path.dirname(agentFile));
+  await fs.writeFile(agentFile, content);
+  
+  console.log(chalk.green(`✅ Created agent: .github/agents/${name}.md`));
+  console.log(chalk.dim(`   Invoke with @${name} in Copilot Chat`));
+}
+
+async function addInstruction(githubDir, name, options) {
+  const instrFile = path.join(githubDir, 'instructions', `${name}.instructions.md`);
+  
+  if (fs.existsSync(instrFile)) {
+    console.log(chalk.yellow(`⚠️  Instruction "${name}" already exists.`));
+    return;
+  }
+  
+  const response = await prompts([
+    {
+      type: 'text',
+      name: 'applyTo',
+      message: 'Apply to files (glob pattern):',
+      initial: `**/*.${name},**/${name}/**`
+    },
+    {
+      type: 'text',
+      name: 'description',
+      message: 'Brief description:',
+      initial: `${name} coding guidelines`
+    }
+  ]);
+  
+  if (!response.applyTo) {
+    console.log(chalk.yellow('Aborted.'));
+    return;
+  }
+  
+  const content = `---
+applyTo: "${response.applyTo}"
+---
+
+## ${name.charAt(0).toUpperCase() + name.slice(1)} Guidelines
+
+> ${response.description}
+
+### Style
+- Follow project conventions
+- Consistent formatting
+- Document public APIs
+
+### Patterns
+- Use established patterns
+- Avoid anti-patterns
+- Consider maintainability
+
+### Best Practices
+- [Add specific guidelines here]
+`;
+  
+  await fs.ensureDir(path.dirname(instrFile));
+  await fs.writeFile(instrFile, content);
+  
+  console.log(chalk.green(`✅ Created instruction: .github/instructions/${name}.instructions.md`));
+  console.log(chalk.dim(`   Will apply to: ${response.applyTo}`));
+}
+
+export default addCommand;

package/src/commands/doctor.js

@@ -0,0 +1,149 @@
+/**
+ * cp-kit doctor command
+ * 
+ * Diagnose cp-kit configuration and suggest fixes.
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+import chalk from 'chalk';
+
+const CHECKS = [
+  {
+    name: '.github/ directory exists',
+    check: async (dir) => fs.pathExists(path.join(dir, '.github')),
+    fix: 'Run: cp-kit init'
+  },
+  {
+    name: 'copilot-instructions.md exists',
+    check: async (dir) => fs.pathExists(path.join(dir, '.github', 'copilot-instructions.md')),
+    fix: 'Run: cp-kit init'
+  },
+  {
+    name: 'agents/ directory exists',
+    check: async (dir) => fs.pathExists(path.join(dir, '.github', 'agents')),
+    fix: 'Run: cp-kit init'
+  },
+  {
+    name: 'At least one agent defined',
+    check: async (dir) => {
+      const agentsDir = path.join(dir, '.github', 'agents');
+      if (!await fs.pathExists(agentsDir)) return false;
+      const files = await fs.readdir(agentsDir);
+      return files.some(f => f.endsWith('.md'));
+    },
+    fix: 'Run: cp-kit add agent <name>'
+  },
+  {
+    name: 'instructions/ directory exists',
+    check: async (dir) => fs.pathExists(path.join(dir, '.github', 'instructions')),
+    fix: 'Run: cp-kit init'
+  },
+  {
+    name: 'At least one instruction defined',
+    check: async (dir) => {
+      const instrDir = path.join(dir, '.github', 'instructions');
+      if (!await fs.pathExists(instrDir)) return false;
+      const files = await fs.readdir(instrDir);
+      return files.some(f => f.endsWith('.instructions.md'));
+    },
+    fix: 'Run: cp-kit add instruction <name>'
+  },
+  {
+    name: 'AGENTS.md exists at root',
+    check: async (dir) => fs.pathExists(path.join(dir, 'AGENTS.md')),
+    fix: 'Run: cp-kit init'
+  },
+  {
+    name: '.vscode/mcp.json exists',
+    check: async (dir) => fs.pathExists(path.join(dir, '.vscode', 'mcp.json')),
+    optional: true,
+    fix: 'Run: cp-kit init (with MCP option)'
+  },
+  {
+    name: 'Instructions have valid applyTo',
+    check: async (dir) => {
+      const instrDir = path.join(dir, '.github', 'instructions');
+      if (!await fs.pathExists(instrDir)) return true;
+      const files = await fs.readdir(instrDir);
+      for (const file of files.filter(f => f.endsWith('.instructions.md'))) {
+        const content = await fs.readFile(path.join(instrDir, file), 'utf-8');
+        if (!content.includes('applyTo:')) return false;
+      }
+      return true;
+    },
+    fix: 'Add applyTo frontmatter to instruction files'
+  },
+  {
+    name: 'Agents have valid frontmatter',
+    check: async (dir) => {
+      const agentsDir = path.join(dir, '.github', 'agents');
+      if (!await fs.pathExists(agentsDir)) return true;
+      const files = await fs.readdir(agentsDir);
+      for (const file of files.filter(f => f.endsWith('.md'))) {
+        const content = await fs.readFile(path.join(agentsDir, file), 'utf-8');
+        if (!content.startsWith('---')) return false;
+        if (!content.includes('name:')) return false;
+      }
+      return true;
+    },
+    fix: 'Add frontmatter with name: to agent files'
+  }
+];
+
+export async function doctorCommand() {
+  const targetDir = process.cwd();
+  
+  console.log('');
+  console.log(chalk.bold.cyan('🩺 cp-kit Doctor'));
+  console.log(chalk.gray('─'.repeat(50)));
+  console.log(chalk.gray(`Checking: ${targetDir}`));
+  console.log('');
+  
+  let passed = 0;
+  let failed = 0;
+  let warnings = 0;
+  
+  for (const check of CHECKS) {
+    try {
+      const result = await check.check(targetDir);
+      
+      if (result) {
+        console.log(chalk.green('  ✓ ') + check.name);
+        passed++;
+      } else if (check.optional) {
+        console.log(chalk.yellow('  ⚠ ') + check.name + chalk.gray(' (optional)'));
+        warnings++;
+      } else {
+        console.log(chalk.red('  ✗ ') + check.name);
+        if (check.fix) {
+          console.log(chalk.gray('    ' + check.fix));
+        }
+        failed++;
+      }
+    } catch (error) {
+      console.log(chalk.red('  ✗ ') + check.name + chalk.gray(` (${error.message})`));
+      failed++;
+    }
+  }
+  
+  console.log('');
+  console.log(chalk.gray('─'.repeat(50)));
+  
+  if (failed === 0) {
+    if (warnings > 0) {
+      console.log(chalk.green.bold(`✓ All checks passed!`) + chalk.gray(` (${passed} passed, ${warnings} optional)`));
+    } else {
+      console.log(chalk.green.bold(`✓ All checks passed! (${passed}/${passed})`));
+    }
+    console.log('');
+    console.log(chalk.green('✨ cp-kit is healthy!'));
+  } else {
+    console.log(chalk.red.bold(`✗ ${failed} checks failed`) + chalk.gray(` (${passed} passed, ${warnings} optional)`));
+    console.log('');
+    console.log(chalk.yellow('Run suggested fixes above.'));
+  }
+  console.log('');
+}
+
+export default doctorCommand;