cp-toolkit 2.2.3 → 2.2.4

package/package.json

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

package/src/commands/add.js

@@ -13,6 +13,8 @@ const AGENT_TEMPLATES = {
   specialist: (name, description, triggers) => `---
 name: ${name}
 description: ${description}
+version: 1.0
+skills: clean-code
 ---
 
 # ${name}
@@ -39,6 +41,8 @@ ${triggers.map(t => `- ${t} related tasks`).join('\n')}
   reviewer: (name, description, triggers) => `---
 name: ${name}
 description: ${description}
+version: 1.0
+skills: clean-code, qa-automation-engineer
 ---
 
 # ${name}
@@ -76,7 +80,7 @@ description: ${description}
 
 export async function addCommand(type, name, options) {
   const targetDir = process.cwd();
-  
+
   // Validate type
   const validTypes = ['agent', 'instruction'];
   if (!validTypes.includes(type)) {
@@ -84,7 +88,7 @@ export async function addCommand(type, name, options) {
     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'))) {
@@ -92,9 +96,9 @@ export async function addCommand(type, name, options) {
     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);
@@ -107,12 +111,12 @@ export async function addCommand(type, name, options) {
 
 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',
@@ -136,30 +140,30 @@ async function addAgent(githubDir, name, options) {
       ]
     }
   ]);
-  
+
   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',
@@ -174,13 +178,16 @@ async function addInstruction(githubDir, name, options) {
       initial: `${name} coding guidelines`
     }
   ]);
-  
+
   if (!response.applyTo) {
     console.log(chalk.yellow('Aborted.'));
     return;
   }
-  
+
   const content = `---
+name: ${name}
+description: ${response.description}
+version: 1.0
 applyTo: "${response.applyTo}"
 ---
 
@@ -201,10 +208,10 @@ applyTo: "${response.applyTo}"
 ### 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}`));
 }

package/src/commands/doctor.js

@@ -61,7 +61,7 @@ const CHECKS = [
     fix: 'Run: cp-kit init (with MCP option)'
   },
   {
-    name: 'Instructions have valid applyTo',
+    name: 'Instructions have valid frontmatter (applyTo, version)',
     check: async (dir) => {
       const instrDir = path.join(dir, '.github', 'instructions');
       if (!await fs.pathExists(instrDir)) return true;
@@ -69,13 +69,15 @@ const CHECKS = [
       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;
+        if (!content.includes('version:')) return false;
+        if (!content.includes('description:')) return false;
       }
       return true;
     },
-    fix: 'Add applyTo frontmatter to instruction files'
+    fix: 'Add version and description frontmatter to instruction files'
   },
   {
-    name: 'Agents have valid frontmatter',
+    name: 'Agents have complete frontmatter (name, description, skills)',
     check: async (dir) => {
       const agentsDir = path.join(dir, '.github', 'agents');
       if (!await fs.pathExists(agentsDir)) return true;
@@ -84,30 +86,33 @@ const CHECKS = [
         const content = await fs.readFile(path.join(agentsDir, file), 'utf-8');
         if (!content.startsWith('---')) return false;
         if (!content.includes('name:')) return false;
+        if (!content.includes('description:')) return false;
+        if (!content.includes('skills:')) return false;
+        if (!content.includes('applyTo:')) return false;
       }
       return true;
     },
-    fix: 'Add frontmatter with name: to agent files'
+    fix: 'Update agent files with full frontmatter (name, description, skills, applyTo)'
   }
 ];
 
 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++;
@@ -126,10 +131,10 @@ export async function doctorCommand() {
       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)`));

package/src/commands/init.js

@@ -26,13 +26,13 @@ export async function initCommand(directory, options) {
   const templatesDir = path.join(__dirname, '../../templates');
 
   console.log(chalk.bold.cyan('\n🚀 cp-toolkit - GitHub Copilot Agent Toolkit\n'));
-  
+
   // Create directory if needed
   if (directory && !fs.existsSync(targetDir)) {
     fs.mkdirSync(targetDir, { recursive: true });
     console.log(chalk.green(`📁 Created directory: ${dirName}`));
   }
-  
+
   // Check for existing configuration
   const githubAgentsDir = path.join(targetDir, '.github', 'agents');
   if (fs.existsSync(githubAgentsDir) && !options.force) {
@@ -42,7 +42,7 @@ export async function initCommand(directory, options) {
       message: 'Copilot Kit (.github/agents) already exists. Overwrite?',
       initial: false
     });
-    
+
     if (!overwrite) {
       console.log(chalk.yellow('⚠️  Aborted. Use --force to overwrite.'));
       return;
@@ -82,31 +82,31 @@ export async function initCommand(directory, options) {
     const agentsTargetDir = path.join(targetDir, '.github', 'agents');
     await fs.ensureDir(agentsTargetDir);
     await fs.copy(agentsSourceDir, agentsTargetDir, { overwrite: true });
-    
+
     // 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', 
+      '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)) {
@@ -115,7 +115,7 @@ export async function initCommand(directory, options) {
         await fs.copy(skillSourceDir, skillTargetDir, { overwrite: true });
       }
     }
-    
+
     // 5. Setup .github/copilot-instructions.md
     spinner.text = 'Creating copilot-instructions.md...';
     const instructionsPath = path.join(targetDir, '.github', 'copilot-instructions.md');
@@ -126,7 +126,7 @@ export async function initCommand(directory, options) {
     spinner.text = 'Configuring MCP Server...';
     const vscodeDir = path.join(targetDir, '.vscode');
     await fs.ensureDir(vscodeDir);
-    
+
     const mcpConfig = {
       "mcpServers": {
         "filesystem": {
@@ -158,9 +158,9 @@ export async function initCommand(directory, options) {
         }
       }
     };
-    
+
     await fs.writeFile(
-      path.join(vscodeDir, 'mcp.json'), 
+      path.join(vscodeDir, 'mcp.json'),
       JSON.stringify(mcpConfig, null, 2)
     );
 
@@ -201,8 +201,16 @@ export async function initCommand(directory, options) {
       await fs.copy(rulesSourceDir, rulesTargetDir, { overwrite: true });
     }
 
+    // 11. Copy AGENTS.md to root (required by doctor)
+    spinner.text = 'Copying AGENTS.md...';
+    const agentsSource = path.join(templatesDir, 'AGENTS.md');
+    const agentsTarget = path.join(targetDir, 'AGENTS.md');
+    if (fs.existsSync(agentsSource)) {
+      await fs.copy(agentsSource, agentsTarget, { overwrite: true });
+    }
+
     spinner.succeed(chalk.green('✨ Copilot Kit initialized successfully!'));
-    
+
     console.log(chalk.bold('\n📁 Created structure:'));
     console.log(chalk.dim('   .github/'));
     console.log(chalk.dim('   ├── agents/           ') + chalk.cyan('← 20 specialist agents'));
@@ -225,11 +233,12 @@ export async function initCommand(directory, options) {
     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('\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')}`);
+    console.log(chalk.green('\n✅ Smart Context patterns applied to agents.'));
 
   } catch (error) {
     spinner.fail(chalk.red('❌ Failed to initialize Copilot Kit'));
@@ -243,6 +252,9 @@ export async function initCommand(directory, options) {
 async function createInstructionFiles(instructionsDir) {
   const instructions = {
     'typescript-development.instructions.md': `---
+name: typescript-development
+description: Strict guidelines for TypeScript development including type safety, modules, and error handling.
+version: 1.0
 applyTo: "**/*.ts,**/*.tsx,**/*.mts,**/*.cts"
 ---
 
@@ -273,6 +285,9 @@ applyTo: "**/*.ts,**/*.tsx,**/*.mts,**/*.cts"
 `,
 
     'javascript-development.instructions.md': `---
+name: javascript-development
+description: Best practices for modern JavaScript development including ES6+ features and functional patterns.
+version: 1.0
 applyTo: "**/*.js,**/*.mjs,**/*.cjs"
 ---
 
@@ -306,6 +321,9 @@ applyTo: "**/*.js,**/*.mjs,**/*.cjs"
 `,
 
     'react-development.instructions.md': `---
+name: react-development
+description: Component patterns, state management, and accessibility standards for React development.
+version: 1.0
 applyTo: "**/*.jsx,**/*.tsx,**/*react*"
 ---
 
@@ -344,7 +362,10 @@ applyTo: "**/*.jsx,**/*.tsx,**/*react*"
 `,
 
     'nextjs-development.instructions.md': `---
-applyTo: "**/pages/**,**/app/**,**/components/**,**/lib/**,**/utils/**"
+name: nextjs-development
+description: Guidelines for Next.js development including App Router, Server Components, and SEO optimization.
+version: 1.0
+applyTo: "**/app/**,**/components/**,**/lib/**,**/utils/**"
 ---
 
 # Next.js Development Guidelines
@@ -383,6 +404,9 @@ applyTo: "**/pages/**,**/app/**,**/components/**,**/lib/**,**/utils/**"
 `,
 
     'python-development.instructions.md': `---
+name: python-development
+description: Best practices for Python development including type hints, async/await, and testing.
+version: 1.0
 applyTo: "**/*.py"
 ---
 
@@ -422,6 +446,9 @@ applyTo: "**/*.py"
 `,
 
     'security-development.instructions.md': `---
+name: security-development
+description: Comprehensive security guidelines including auth, data protection, and web security.
+version: 1.0
 applyTo: "**/auth/**,**/security/**,**/*auth*,**/*token*,**/*session*,**/middleware/**"
 ---
 
@@ -464,6 +491,9 @@ applyTo: "**/auth/**,**/security/**,**/*auth*,**/*token*,**/*session*,**/middlew
 `,
 
     'database-development.instructions.md': `---
+name: database-development
+description: Standards for schema design, query optimization, and database migrations.
+version: 1.0
 applyTo: "**/prisma/**,**/*.sql,**/migrations/**,**/schema.*,**/db/**,**/models/**"
 ---
 
@@ -506,6 +536,9 @@ applyTo: "**/prisma/**,**/*.sql,**/migrations/**,**/schema.*,**/db/**,**/models/
 `,
 
     'testing-development.instructions.md': `---
+name: testing-development
+description: Guidelines for test structure, frameworks, and code coverage best practices.
+version: 1.0
 applyTo: "**/*.test.*,**/*.spec.*,**/tests/**,**/__tests__/**"
 ---
 
@@ -547,6 +580,9 @@ applyTo: "**/*.test.*,**/*.spec.*,**/tests/**,**/__tests__/**"
 `,
 
     'api-development.instructions.md': `---
+name: api-development
+description: RESTful API design standards including versioning, error handling, and documentation.
+version: 1.0
 applyTo: "**/api/**,**/routes/**,**/controllers/**,**/services/**,**/*api*,**/*endpoint*"
 ---
 
@@ -589,6 +625,9 @@ applyTo: "**/api/**,**/routes/**,**/controllers/**,**/services/**,**/*api*,**/*e
 `,
 
     'github-actions.instructions.md': `---
+name: github-actions
+description: Standards for GitHub Actions workflows including security, performance, and best practices.
+version: 1.0
 applyTo: ".github/workflows/**/*.yml,.github/workflows/**/*.yaml"
 ---
 

package/templates/AGENTS.md

@@ -0,0 +1,47 @@
+# Available Agents
+
+This project is equipped with specialized AI agents to assist with development. Invoke them using `@workspace` in Copilot Chat or by their specific names.
+
+## Core Agents
+
+| Agent | Description | Triggers |
+|-------|-------------|----------|
+| **orchestrator** | Multi-agent coordination and task decomposition. | `plan`, `organize`, `coordinate` |
+| **project-planner** | Task breakdown and roadmap planning. | `plan`, `roadmap`, `tasks` |
+| **explorer-agent** | Codebase mapping and architectural analysis. | `analyze`, `map`, `audit` |
+
+## Development Agents
+
+| Agent | Description | Triggers |
+|-------|-------------|----------|
+| **frontend-specialist** | React/Next.js UI implementation. | `component`, `css`, `ui` |
+| **backend-specialist** | Node.js/Python API and server logic. | `api`, `server`, `endpoint` |
+| **mobile-developer** | React Native/Flutter app development. | `ios`, `android`, `mobile` |
+| **database-architect** | Schema design and migrations. | `schema`, `sql`, `migration` |
+| **game-developer** | Game mechanics and engine logic. | `unity`, `godot`, `game` |
+
+## Specialized Agents
+
+| Agent | Description | Triggers |
+|-------|-------------|----------|
+| **test-engineer** | Unit and integration testing strategies. | `test`, `spec`, `coverage` |
+| **qa-automation-engineer** | E2E and browser automation. | `e2e`, `cypress`, `playwright` |
+| **security-auditor** | Vulnerability scanning and auth review. | `security`, `audit`, `auth` |
+| **penetration-tester** | Offensive security testing. | `pentest`, `exploit` |
+| **performance-optimizer** | Web vitals and bundle optimization. | `performance`, `slow`, `optimize` |
+| **seo-specialist** | SEO and GEO (Generative Engine Optimization). | `seo`, `meta`, `robots` |
+| **debugger** | Root cause analysis for complex bugs. | `debug`, `crash`, `error` |
+
+## Product Agents
+
+| Agent | Description | Triggers |
+|-------|-------------|----------|
+| **product-manager** | Requirements gathering and PRDs. | `requirements`, `user story` |
+| **product-owner** | Backlog prioritization and strategy. | `backlog`, `roadmap` |
+| **code-archaeologist** | Understanding legacy systems. | `legacy`, `refactor` |
+| **devops-engineer** | CI/CD, Docker, and infrastructure. | `deploy`, `docker`, `ci` |
+| **documentation-writer** | Technical documentation. | `docs`, `readme` |
+
+---
+
+> **Tip:** Use `cp-toolkit list agents` to see this list in your CLI.

package/templates/ARCHITECTURE.md

@@ -17,6 +17,48 @@ Antigravity Kit is a modular system consisting of:
 
 ---
 
+## 📝 Template Standards
+
+All toolkit files MUST follow the strict metadata standard (YAML Frontmatter) to ensure proper indexing by GitHub Copilot and the CP-Toolkit CLI.
+
+### AGENTS (`/agents/*.md`)
+```yaml
+---
+name: agent-name        # lowercase-slug
+description: "..."     # Concise mandatory description
+version: 1.0           # Current version
+skills: skill-a, skill-b # Comma-separated list of primary skills
+---
+```
+
+### SKILLS (`/skills/**/SKILL.md`)
+```yaml
+---
+name: skill-name        # lowercase-slug
+description: "..."     # Detailed capability description
+version: 1.0           # Mandatory version tracking
+---
+```
+
+### INSTRUCTIONS (`/instructions/*.instructions.md`)
+```yaml
+---
+name: instruction-name
+description: "..."
+version: 1.0
+applyTo: "**/*.ext"    # Glob pattern for Copilot context
+---
+```
+
+### RULES (`/rules/GEMINI.md`)
+```yaml
+---
+trigger: always_on     # Activation trigger
+---
+```
+
+---
+
 ## 🏗️ Directory Structure
 
 ```plaintext

package/templates/agents/backend-specialist.md

@@ -4,6 +4,7 @@ description: Expert backend architect for Node.js, Python, and modern serverless
 tools: Read, Grep, Glob, Bash, Edit, Write
 model: inherit
 skills: clean-code, nodejs-best-practices, python-patterns, api-patterns, database-design, mcp-builder, lint-and-validate, powershell-windows, bash-linux
+applyTo: ["**/api/**", "**/*.server.*", "**/controllers/**", "**/*.service.ts"]
 ---
 
 # Backend Development Architect