cp-toolkit 2.1.2 → 2.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cp-toolkit",
-  "version": "2.1.2",
+  "version": "2.2.1",
   "description": "Copilot Toolkit - AI Agent framework for GitHub Copilot, Claude, Gemini CLI, and other AI assistants",
   "keywords": [
     "ai-agents",

package/src/commands/init.js

@@ -1,8 +1,12 @@
 /**
- * cp-kit init command
+ * cp-toolkit init command
  * 
  * Initializes Copilot Kit with GitHub Copilot 2026 standard structure.
- * Primary structure: .github/ (GitHub Copilot native)
+ * Creates:
+ *   .github/agents/       - Specialist agent definitions
+ *   .github/instructions/ - Language/context-specific instructions  
+ *   .github/copilot-instructions.md - Main Copilot config
+ *   .vscode/mcp.json      - MCP server configuration
  */
 
 import fs from 'fs-extra';
@@ -10,258 +14,16 @@ import path from 'path';
 import chalk from 'chalk';
 import ora from 'ora';
 import prompts from 'prompts';
+import { fileURLToPath } from 'url';
 
-// Template definitions - All 20 agents
-const TEMPLATE_AGENTS = [
-  {
-    name: 'orchestrator',
-    description: 'Multi-domain task coordinator',
-    skills: ['intelligent-routing', 'parallel-agents', 'plan-writing'],
-    triggers: ['complex', 'multi-file', 'architecture', 'coordinate']
-  },
-  {
-    name: 'frontend-specialist',
-    description: 'React, Next.js, CSS expert',
-    skills: ['nextjs-react', 'accessibility', 'tailwind'],
-    triggers: ['ui', 'component', 'react', 'css', 'frontend', 'styling']
-  },
-  {
-    name: 'backend-specialist',
-    description: 'Node.js, Python, APIs expert',
-    skills: ['api-patterns', 'error-handling', 'caching'],
-    triggers: ['api', 'server', 'backend', 'endpoint', 'node', 'express']
-  },
-  {
-    name: 'database-architect',
-    description: 'Schema design, SQL, Prisma expert',
-    skills: ['prisma', 'query-optimization', 'migrations'],
-    triggers: ['database', 'schema', 'sql', 'prisma', 'migration', 'query']
-  },
-  {
-    name: 'security-auditor',
-    description: 'Security analysis, OWASP expert',
-    skills: ['vulnerability-scanner', 'auth-patterns'],
-    triggers: ['security', 'auth', 'vulnerability', 'owasp', 'audit']
-  },
-  {
-    name: 'test-engineer',
-    description: 'Testing strategies, coverage expert',
-    skills: ['testing-patterns', 'e2e-testing'],
-    triggers: ['test', 'coverage', 'jest', 'playwright', 'vitest']
-  },
-  {
-    name: 'debugger',
-    description: 'Troubleshooting, root cause analysis',
-    skills: ['debugging-strategies', 'performance-profiling'],
-    triggers: ['bug', 'error', 'fix', 'debug', 'why', 'crash']
-  },
-  {
-    name: 'devops-engineer',
-    description: 'CI/CD, Docker, infrastructure expert',
-    skills: ['docker-patterns', 'ci-cd-pipelines'],
-    triggers: ['deploy', 'docker', 'ci', 'pipeline', 'kubernetes', 'infra']
-  },
-  {
-    name: 'project-planner',
-    description: 'Architecture decisions, task planning',
-    skills: ['plan-writing', 'brainstorming'],
-    triggers: ['plan', 'architecture', 'design', 'roadmap', 'breakdown']
-  },
-  {
-    name: 'performance-optimizer',
-    description: 'Web performance, Core Web Vitals expert',
-    skills: ['performance-profiling', 'bundle-optimization'],
-    triggers: ['performance', 'speed', 'optimize', 'lighthouse', 'bundle']
-  },
-  {
-    name: 'mobile-developer',
-    description: 'React Native, Flutter, iOS, Android expert',
-    skills: ['mobile-patterns', 'cross-platform'],
-    triggers: ['mobile', 'ios', 'android', 'react-native', 'flutter', 'app']
-  },
-  {
-    name: 'documentation-writer',
-    description: 'Technical docs, API documentation expert',
-    skills: ['technical-writing', 'api-docs'],
-    triggers: ['docs', 'documentation', 'readme', 'api-docs', 'jsdoc']
-  },
-  {
-    name: 'seo-specialist',
-    description: 'SEO optimization, meta tags expert',
-    skills: ['seo-patterns', 'structured-data'],
-    triggers: ['seo', 'meta', 'search', 'ranking', 'sitemap']
-  },
-  {
-    name: 'code-archaeologist',
-    description: 'Legacy code analysis, refactoring expert',
-    skills: ['refactoring', 'code-analysis'],
-    triggers: ['legacy', 'refactor', 'understand', 'cleanup', 'technical-debt']
-  },
-  {
-    name: 'explorer-agent',
-    description: 'Codebase exploration and analysis',
-    skills: ['code-navigation', 'pattern-recognition'],
-    triggers: ['explore', 'find', 'search', 'where', 'locate']
-  },
-  {
-    name: 'game-developer',
-    description: 'Game logic, mechanics, interactive experiences',
-    skills: ['game-patterns', 'physics', 'graphics'],
-    triggers: ['game', 'physics', 'animation', 'canvas', 'webgl']
-  },
-  {
-    name: 'penetration-tester',
-    description: 'Offensive security, vulnerability exploitation',
-    skills: ['pentesting', 'exploitation'],
-    triggers: ['pentest', 'exploit', 'hack', 'red-team', 'attack']
-  },
-  {
-    name: 'product-owner',
-    description: 'Product strategy, backlog management',
-    skills: ['product-management', 'prioritization'],
-    triggers: ['backlog', 'priority', 'mvp', 'feature', 'user-story']
-  },
-  {
-    name: 'product-manager',
-    description: 'Requirements gathering, user research',
-    skills: ['requirements', 'user-research'],
-    triggers: ['requirements', 'spec', 'user', 'stakeholder', 'prd']
-  },
-  {
-    name: 'qa-automation-engineer',
-    description: 'E2E testing, CI pipelines, quality automation',
-    skills: ['automation', 'ci-testing'],
-    triggers: ['qa', 'automation', 'e2e', 'regression', 'quality']
-  }
-];
-
-const TEMPLATE_INSTRUCTIONS = {
-  typescript: {
-    applyTo: '**/*.ts,**/*.tsx,**/*.mts,**/*.cts',
-    content: `## TypeScript Guidelines
-
-### Strict Mode
-- Enable \`strict: true\` in tsconfig.json
-- No \`any\` types - use \`unknown\` and narrow
-- Explicit return types for public functions
-
-### Patterns
-- Prefer \`interface\` over \`type\` for objects
-- Use \`as const\` for literal types
-- Leverage discriminated unions for state
-
-### Imports
-- Use path aliases (@/components, @/lib)
-- Barrel exports for public APIs only
-- Tree-shakeable imports
-
-### Error Handling
-- Use Result<T, E> pattern for expected errors
-- Throw only for unexpected errors
-- Custom error classes extend Error`
-  },
-  python: {
-    applyTo: '**/*.py',
-    content: `## Python Guidelines
-
-### Style
-- Black formatter, line length 88
-- Type hints for all public functions
-- PEP 8 naming conventions
-
-### Patterns
-- Pydantic for data validation
-- FastAPI for APIs
-- Async/await for I/O operations
-
-### Imports
-- isort for import ordering
-- Absolute imports preferred
-- TYPE_CHECKING for type-only imports
-
-### Error Handling
-- Custom exceptions inherit from base
-- Use \`raise from\` for chained exceptions
-- Context managers for resources`
-  },
-  react: {
-    applyTo: '**/*.jsx,**/*.tsx,**/components/**',
-    content: `## React Guidelines
-
-### Components
-- Functional components only
-- Custom hooks for shared logic
-- Props interface above component
-
-### State
-- useState for local state
-- useReducer for complex state
-- Context for global, Zustand for app state
-
-### Performance
-- React.memo for expensive renders
-- useMemo/useCallback judiciously
-- Lazy load routes and heavy components
-
-### Testing
-- React Testing Library
-- Test behavior, not implementation
-- Mock at network boundary`
-  },
-  database: {
-    applyTo: '**/prisma/**,**/*.sql,**/migrations/**,**/schema.*',
-    content: `## Database Guidelines
-
-### Schema Design
-- UUID for primary keys
-- Timestamps: createdAt, updatedAt
-- Soft delete with deletedAt
-
-### Prisma
-- Use transactions for multi-table ops
-- Select only needed fields
-- Paginate with cursor, not offset
-
-### Migrations
-- One migration per feature
-- Never modify applied migrations
-- Test migrations on copy of prod data
-
-### Security
-- Parameterized queries only
-- Row-level security where needed
-- Encrypt PII at rest`
-  },
-  security: {
-    applyTo: '**/auth/**,**/security/**,**/*auth*,**/*token*,**/*session*',
-    content: `## Security Guidelines
-
-### Authentication
-- JWT with short expiry + refresh tokens
-- HttpOnly cookies for web
-- Rate limit auth endpoints
-
-### Authorization
-- RBAC or ABAC patterns
-- Check permissions server-side
-- Deny by default
-
-### Data Protection
-- Sanitize all inputs
-- Escape outputs by context
-- Never log sensitive data
-
-### OWASP Top 10
-- Validate content types
-- CSRF tokens for state changes
-- Security headers (CSP, HSTS)`
-  }
-};
+// Get __dirname equivalent for ESM
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
 
 export async function initCommand(directory, options) {
   const targetDir = directory ? path.resolve(directory) : process.cwd();
   const dirName = path.basename(targetDir);
-  const templatesDir = path.join(path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, '$1')), '../../templates');
+  const templatesDir = path.join(__dirname, '../../templates');
 
   console.log(chalk.bold.cyan('\n🚀 cp-toolkit - GitHub Copilot Agent Toolkit\n'));
   
@@ -272,12 +34,12 @@ export async function initCommand(directory, options) {
   }
   
   // Check for existing configuration
-  const agentDir = path.join(targetDir, '.agent');
-  if (fs.existsSync(agentDir) && !options.force) {
+  const githubAgentsDir = path.join(targetDir, '.github', 'agents');
+  if (fs.existsSync(githubAgentsDir) && !options.force) {
     const { overwrite } = await prompts({
       type: 'confirm',
       name: 'overwrite',
-      message: 'cp-toolkit (.agent) already initialized. Overwrite?',
+      message: 'Copilot Kit (.github/agents) already exists. Overwrite?',
       initial: false
     });
     
@@ -304,51 +66,69 @@ export async function initCommand(directory, options) {
       {
         type: 'confirm',
         name: 'installEverything',
-        message: 'Install full Copilot Kit (Agents, Skills, Workflows)?',
+        message: 'Install full Copilot Kit (Agents, Instructions, Workflows)?',
         initial: true
       }
     ]);
-     config = { ...config, ...response };
+    config = { ...config, ...response };
   }
 
   const spinner = ora('Installing Copilot Kit...').start();
 
   try {
-    // 1. Copy Templates to .agent folder
-    await fs.ensureDir(agentDir);
-    await fs.copy(templatesDir, agentDir, {
-      overwrite: true,
-      filter: (src) => !src.includes('node_modules') && !src.includes('.git')
-    });
+    // 1. Setup .github/agents/
+    spinner.text = 'Copying agents...';
+    const agentsSourceDir = path.join(templatesDir, 'agents');
+    const agentsTargetDir = path.join(targetDir, '.github', 'agents');
+    await fs.ensureDir(agentsTargetDir);
+    await fs.copy(agentsSourceDir, agentsTargetDir, { overwrite: true });
     
-    spinner.text = 'Configuring GitHub Copilot...';
-
-    // 2. Setup .github/copilot-instructions.md
-    const githubDir = path.join(targetDir, '.github');
-    await fs.ensureDir(githubDir);
+    // 2. Setup .github/instructions/ (from skills that have instruction content)
+    spinner.text = 'Copying instructions...';
+    const instructionsTargetDir = path.join(targetDir, '.github', 'instructions');
+    await fs.ensureDir(instructionsTargetDir);
+    
+    // Create standard instruction files
+    await createInstructionFiles(instructionsTargetDir);
+    
+    // 4. Setup .github/skills/ (essential skills referenced by agents)
+    spinner.text = 'Copying essential skills...';
+    const skillsTargetDir = path.join(targetDir, '.github', 'skills');
+    await fs.ensureDir(skillsTargetDir);
+    
+    // Copy essential skills that agents reference
+    const essentialSkills = [
+      'mobile-design',
+      'frontend-design', 
+      'api-patterns',
+      'database-design',
+      'testing-patterns',
+      'deployment-procedures',
+      'architecture'
+    ];
+    
+    for (const skill of essentialSkills) {
+      const skillSourceDir = path.join(templatesDir, 'skills', 'optional', skill);
+      if (fs.existsSync(skillSourceDir)) {
+        const skillTargetDir = path.join(skillsTargetDir, skill);
+        await fs.ensureDir(skillTargetDir);
+        await fs.copy(skillSourceDir, skillTargetDir, { overwrite: true });
+      }
+    }
     
-    const instructionsPath = path.join(githubDir, 'copilot-instructions.md');
+    // 5. Setup .github/copilot-instructions.md
+    spinner.text = 'Creating copilot-instructions.md...';
+    const instructionsPath = path.join(targetDir, '.github', 'copilot-instructions.md');
     const instructionsContent = generateCopilotInstructions(config);
     await fs.writeFile(instructionsPath, instructionsContent);
 
-    // 3. Setup .vscode/mcp.json
+    // 6. Setup .vscode/mcp.json
     spinner.text = 'Configuring MCP Server...';
     const vscodeDir = path.join(targetDir, '.vscode');
     await fs.ensureDir(vscodeDir);
     
     const mcpConfig = {
       "mcpServers": {
-        "antigravity-toolkit": {
-          "command": "node",
-          "args": [
-            "${workspaceFolder}/.agent/scripts/mcp-server.js"
-          ],
-          "env": {
-            "AGENT_ROOT": "${workspaceFolder}/.agent"
-          },
-          "disabled": false,
-          "autoApprove": []
-        },
         "filesystem": {
           "command": "npx",
           "args": [
@@ -376,65 +156,207 @@ export async function initCommand(directory, options) {
       JSON.stringify(mcpConfig, null, 2)
     );
 
-    // 4. Create root integration files if needed
-    // Copy AGENTS.md if it exists in templates root (which is now in .agent)
-    const agentsMdSrc = path.join(agentDir, 'AGENTS.md'); // Might not exist in root of reference
-    // If reference had AGENTS.md in root, it should be in agentDir now if we copied everything.
-    // Based on list_dir earlier, it wasn't there. It was likely outside. 
-    // We will generate a basic one if missing.
+    // 7. Copy workflows to .github/workflows-copilot/ (optional reference)
+    if (config.installEverything) {
+      spinner.text = 'Copying workflows...';
+      const workflowsSourceDir = path.join(templatesDir, 'workflows');
+      const workflowsTargetDir = path.join(targetDir, '.github', 'copilot-workflows');
+      if (fs.existsSync(workflowsSourceDir)) {
+        await fs.ensureDir(workflowsTargetDir);
+        await fs.copy(workflowsSourceDir, workflowsTargetDir, { overwrite: true });
+      }
+    }
+
+    spinner.succeed(chalk.green('✨ Copilot Kit initialized successfully!'));
     
-    spinner.succeed(chalk.green('Copilot Kit installed successfully!'));
+    console.log(chalk.bold('\n📁 Created structure:'));
+    console.log(chalk.dim('   .github/'));
+    console.log(chalk.dim('   ├── agents/           ') + chalk.cyan('← 20 specialist agents'));
+    console.log(chalk.dim('   ├── skills/           ') + chalk.cyan('← Essential skills library'));
+    console.log(chalk.dim('   ├── instructions/     ') + chalk.cyan('← Language-specific rules'));
+    console.log(chalk.dim('   ├── copilot-workflows/') + chalk.cyan('← Workflow templates'));
+    console.log(chalk.dim('   └── copilot-instructions.md'));
+    console.log(chalk.dim('   .vscode/'));
+    console.log(chalk.dim('   └── mcp.json          ') + chalk.cyan('← MCP server config'));
     
-    console.log(chalk.bold('\nNext Steps:'));
-    console.log(`1. Open ${chalk.cyan('.github/copilot-instructions.md')} to see the setup.`);
-    console.log(`2. Reload Window to activate MCP server.`);
-    console.log(`3. Try typing ${chalk.yellow('/create')} or ${chalk.yellow('Is the agent active?')} in Copilot Chat.`);
+    console.log(chalk.bold('\n🚀 Next Steps:'));
+    console.log(`   1. ${chalk.cyan('Reload VS Code window')} to activate MCP servers`);
+    console.log(`   2. Open Copilot Chat and try: ${chalk.yellow('@workspace use the orchestrator agent')}`);
+    console.log(`   3. Or try a workflow: ${chalk.yellow('/create a React component')}`);
 
   } catch (error) {
-    spinner.fail('Installation failed.');
-    console.error(error);
+    spinner.fail(chalk.red('❌ Failed to initialize Copilot Kit'));
+    console.error(chalk.dim(error.message));
+    if (options.verbose) {
+      console.error(error);
+    }
   }
 }
 
-function generateAgentFile(agent) {
-  // Deprecated generally, using static files now, but keeping for fallback
-  return `---
-name: ${agent.name}
-description: ${agent.description}
-skills: [${agent.skills.join(', ')}]
+async function createInstructionFiles(instructionsDir) {
+  const instructions = {
+    'typescript.instructions.md': `---
+applyTo: "**/*.ts,**/*.tsx,**/*.mts,**/*.cts"
 ---
 
-# ${agent.name}
+# TypeScript Guidelines
 
-${agent.description}
-`;
+## Strict Mode
+- Enable \`strict: true\` in tsconfig.json
+- No \`any\` types - use \`unknown\` and narrow with type guards
+- Explicit return types for public functions
+
+## Patterns
+- Prefer \`interface\` over \`type\` for object shapes
+- Use \`as const\` for literal types
+- Leverage discriminated unions for state
+
+## Imports
+- Use type-only imports: \`import type { X } from 'y'\`
+- Barrel exports for public APIs only
+`,
+
+    'python.instructions.md': `---
+applyTo: "**/*.py"
+---
+
+# Python Guidelines
+
+## Type Hints
+- Use type hints for all function signatures
+- Use \`from __future__ import annotations\` for forward refs
+- Prefer \`typing.Optional\` over \`X | None\` for Python 3.9 compat
+
+## Patterns
+- Use dataclasses or Pydantic for data structures
+- Async/await for I/O bound operations
+- Context managers for resource management
+
+## Style
+- Follow PEP 8
+- Use Black for formatting
+- Docstrings in Google style
+`,
+
+    'security.instructions.md': `---
+applyTo: "**/auth/**,**/security/**,**/*auth*,**/*token*,**/*session*"
+---
+
+# Security Guidelines
+
+## Authentication
+- JWT with short expiry + refresh tokens
+- HttpOnly cookies for web sessions
+- Rate limit authentication endpoints
+
+## Authorization
+- RBAC or ABAC patterns
+- Check permissions server-side always
+- Deny by default, allow explicitly
+
+## Data Protection
+- Sanitize all user inputs
+- Escape outputs by context (HTML, SQL, etc.)
+- Never log sensitive data (passwords, tokens, PII)
+
+## OWASP Top 10
+- Validate content types
+- CSRF tokens for state-changing operations
+- Security headers (CSP, HSTS, X-Frame-Options)
+`,
+
+    'database.instructions.md': `---
+applyTo: "**/prisma/**,**/*.sql,**/migrations/**,**/schema.*,**/db/**"
+---
+
+# Database Guidelines
+
+## Schema Design
+- UUID or ULID for primary keys
+- Timestamps: createdAt, updatedAt on all tables
+- Soft delete with deletedAt when needed
+
+## Queries
+- Use parameterized queries only (never string concat)
+- Select only needed fields
+- Use cursor-based pagination for large datasets
+
+## Prisma
+- Use transactions for multi-table operations
+- Define indexes for frequently queried fields
+- Use \`@map\` and \`@@map\` for legacy schemas
+
+## Migrations
+- One migration per feature
+- Never modify already-applied migrations
+- Test migrations on copy of production data
+`
+  };
+
+  for (const [filename, content] of Object.entries(instructions)) {
+    await fs.writeFile(path.join(instructionsDir, filename), content);
+  }
 }
 
 function generateCopilotInstructions(config) {
   return `# GitHub Copilot Instructions
 
-> **Copilot Kit Active**
-> Profile: ${config.projectName}
+> **Copilot Kit v2** - Project: ${config.projectName}
+
+## 🤖 Agent System
+
+This project uses specialized AI agents located in \`.github/agents/\`.
+
+### Available Agents
+
+| Agent | Specialty |
+|-------|-----------|
+| orchestrator | Multi-agent coordination, complex tasks |
+| frontend-specialist | React, Next.js, CSS, accessibility |
+| backend-specialist | Node.js, Python, APIs, microservices |
+| database-architect | Schema design, SQL, Prisma, migrations |
+| security-auditor | OWASP, auth, vulnerability analysis |
+| test-engineer | Testing strategies, coverage, TDD |
+| debugger | Troubleshooting, root cause analysis |
+| devops-engineer | CI/CD, Docker, Kubernetes, infrastructure |
+| performance-optimizer | Web vitals, profiling, optimization |
+| documentation-writer | Technical docs, API documentation |
+
+### How to Use Agents
+
+To invoke an agent, reference it in your prompt:
+- "Use the **orchestrator** to plan this feature"
+- "Ask the **security-auditor** to review this code"
+- "Have the **debugger** analyze this error"
+
+## 📋 Language Instructions
+
+Context-specific rules are in \`.github/instructions/\`:
+- \`typescript.instructions.md\` - TS/TSX files
+- \`python.instructions.md\` - Python files
+- \`security.instructions.md\` - Auth/security code
+- \`database.instructions.md\` - Database/Prisma code
 
-## 🧠 Core Protocols
+## 🔧 MCP Servers
 
-The user has installed the **Copilot Kit** in \`.agent/\`.
-You must follow the rules defined in \`.agent/rules/GEMINI.md\`.
+Configured in \`.vscode/mcp.json\`:
+- **filesystem** - File system access
+- **memory** - Persistent memory across sessions
 
-### Structure
-- **Agents:** \`.agent/agents/\` (Specialist personas)
-- **Skills:** \`.agent/skills/\` (Capabilities)
-- **Workflows:** \`.agent/workflows/\` (Procedures)
-- **Scripts:** \`.agent/scripts/\` (Tools)
+## 🚀 Workflows
 
-## 🚀 Activation
+Workflow templates in \`.github/copilot-workflows/\`:
+- \`/create\` - Scaffold new features
+- \`/debug\` - Systematic debugging
+- \`/test\` - Generate test suites
+- \`/plan\` - Architecture planning
 
-When the user asks for a specific role or task, look up the corresponding agent in \`.agent/agents/\`.
-Always read \`.agent/rules/GEMINI.md\` first.
+## 📝 General Guidelines
 
-## 🛠️ MCP Tools
-An MCP server is configured at \`.agent/scripts/mcp-server.js\`.
-Use it to list available tools, resources, and prompts.
+1. **Read before writing** - Understand existing patterns
+2. **Small, focused changes** - One concern per commit
+3. **Test coverage** - Write tests for new features
+4. **Security first** - Validate inputs, sanitize outputs
 `;
 }