cokit-cli 1.0.0 → 1.0.2

package/plans/260108-0924-rebuild-cokit-awesome-copilot-format/phase-04-convert-skills-to-instructions.md

@@ -0,0 +1,349 @@
+# Phase 4: Convert Skills to Instructions
+
+## Context Links
+- [Main Plan](./plan.md)
+- [Phase 3: Convert Commands](./phase-03-convert-commands-to-prompts.md)
+
+## Overview
+
+| Priority | Status | Effort |
+|----------|--------|--------|
+| P1 | pending | 4h |
+
+## Key Insights
+
+1. ClaudeKit skills co 2 loai:
+   - Simple (SKILL.md only) → convert to `.instructions.md`
+   - Complex (SKILL.md + assets) → keep as `skills/*/`
+2. Instructions can `applyTo` field de specify file patterns
+3. Skills phai co `name` va `description` trong frontmatter
+
+## Requirements
+
+### Source Skills Analysis (38 files)
+
+| Skill | Has Assets | Target Type |
+|-------|------------|-------------|
+| frontend-design-pro | No | instruction |
+| frontend-development | No | instruction |
+| sequential-thinking | No | instruction |
+| document-skills/pdf | No | instruction |
+| document-skills/pptx | No | instruction |
+| document-skills/xlsx | No | instruction |
+| document-skills/docx | No | instruction |
+| threejs | No | instruction |
+| devops | No | instruction |
+| mobile-development | No | instruction |
+| mcp-builder | No | instruction |
+| repomix | No | instruction |
+| ui-styling | No | instruction |
+| better-auth | No | instruction |
+| template-skill | No | (skip - template) |
+| debugging | No | instruction |
+| problem-solving | No | instruction |
+| media-processing | No | instruction |
+| code-review | No | instruction |
+| payment-integration | No | instruction |
+| shopify | No | instruction |
+| backend-development | No | instruction |
+| web-frameworks | No | instruction |
+| research | No | instruction |
+| ai-artist | No | instruction |
+| databases | No | instruction |
+| frontend-design | No | instruction |
+| ai-multimodal | No | instruction |
+| google-adk-python | No | instruction |
+| chrome-devtools | Yes (scripts/) | skill |
+| docs-seeker | No | instruction |
+| markdown-novel-viewer | No | instruction |
+| mcp-management | Yes (scripts/) | skill |
+| planning | No | instruction |
+| plans-kanban | No | instruction |
+| skill-creator | No | instruction |
+| ui-ux-pro-max | No | instruction |
+| dotnet-backend | No | instruction |
+
+### Skills to Keep as Skills (with assets)
+
+| Skill | Assets |
+|-------|--------|
+| chrome-devtools | scripts/, node_modules/ |
+| mcp-management | scripts/ |
+
+### Skills to Convert to Instructions (36)
+
+All other skills without bundled assets.
+
+## Frontmatter Conversion
+
+### Skill → Instruction
+
+**ClaudeKit SKILL.md:**
+```yaml
+---
+name: frontend-design-pro
+description: Creates jaw-dropping interfaces...
+---
+```
+
+**Awesome Copilot Instruction:**
+```yaml
+---
+description: 'Creates jaw-dropping interfaces...'
+applyTo: '**/*.tsx, **/*.jsx, **/*.vue, **/*.svelte'
+---
+```
+
+### Skill → Skill (keep format)
+
+**ClaudeKit SKILL.md:**
+```yaml
+---
+name: chrome-devtools
+description: Browser automation and debugging...
+---
+```
+
+**Awesome Copilot SKILL.md:**
+```yaml
+---
+name: 'ck-chrome-devtools'
+description: 'Browser automation and debugging...'
+---
+```
+
+## applyTo Mapping
+
+| Skill Category | applyTo Pattern |
+|----------------|-----------------|
+| Frontend (React, Vue) | `'**/*.tsx, **/*.jsx, **/*.vue, **/*.svelte'` |
+| Backend (Node, Python) | `'**/*.ts, **/*.js, **/*.py'` |
+| .NET | `'**/*.cs, **/*.csproj'` |
+| Mobile | `'**/*.swift, **/*.kt, **/*.dart'` |
+| Database | `'**/*.sql, **/*.prisma'` |
+| DevOps | `'**/Dockerfile, **/*.yml, **/*.yaml'` |
+| General | `'**/*'` |
+
+## Implementation Steps
+
+### Step 1: Create Classification Script
+
+Create `eng/classify-skills.mjs`:
+
+```javascript
+#!/usr/bin/env node
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+const SKILLS_DIR = path.join(os.homedir(), '.claude', 'skills');
+
+function hasAssets(skillDir) {
+  const entries = fs.readdirSync(skillDir, { withFileTypes: true });
+  return entries.some(e =>
+    e.isDirectory() && !e.name.startsWith('.') ||
+    (e.isFile() && !e.name.endsWith('.md') && e.name !== '.gitignore')
+  );
+}
+
+const skills = fs.readdirSync(SKILLS_DIR, { withFileTypes: true })
+  .filter(e => e.isDirectory() && !e.name.startsWith('.'))
+  .map(e => {
+    const skillPath = path.join(SKILLS_DIR, e.name);
+    const hasSkillMd = fs.existsSync(path.join(skillPath, 'SKILL.md'));
+    return {
+      name: e.name,
+      hasAssets: hasAssets(skillPath),
+      hasSkillMd,
+      type: hasAssets(skillPath) ? 'skill' : 'instruction'
+    };
+  });
+
+console.log('Skills Classification:');
+skills.forEach(s => {
+  console.log(`${s.name}: ${s.type} (assets: ${s.hasAssets})`);
+});
+
+// Export for conversion scripts
+export default skills;
+```
+
+### Step 2: Create Instruction Conversion Script
+
+Create `eng/convert-skills-to-instructions.mjs`:
+
+```javascript
+#!/usr/bin/env node
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+const SKILLS_DIR = path.join(os.homedir(), '.claude', 'skills');
+const INSTRUCTIONS_DIR = path.join(process.cwd(), 'instructions');
+
+const APPLY_TO_MAP = {
+  'frontend': '**/*.tsx, **/*.jsx, **/*.vue, **/*.svelte, **/*.css',
+  'backend': '**/*.ts, **/*.js, **/*.py, **/*.go',
+  'dotnet': '**/*.cs, **/*.csproj, **/*.sln',
+  'mobile': '**/*.swift, **/*.kt, **/*.dart',
+  'database': '**/*.sql, **/*.prisma',
+  'devops': '**/Dockerfile, **/*.yml, **/*.yaml',
+  'default': '**/*'
+};
+
+function getApplyTo(skillName) {
+  if (skillName.includes('frontend') || skillName.includes('ui'))
+    return APPLY_TO_MAP.frontend;
+  if (skillName.includes('backend') || skillName.includes('devops'))
+    return APPLY_TO_MAP.backend;
+  if (skillName.includes('dotnet'))
+    return APPLY_TO_MAP.dotnet;
+  if (skillName.includes('mobile'))
+    return APPLY_TO_MAP.mobile;
+  if (skillName.includes('database'))
+    return APPLY_TO_MAP.database;
+  return APPLY_TO_MAP.default;
+}
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match) return { frontmatter: {}, body: content };
+
+  const fm = {};
+  match[1].split('\n').forEach(line => {
+    const colonIdx = line.indexOf(':');
+    if (colonIdx > 0) {
+      const key = line.substring(0, colonIdx).trim();
+      const val = line.substring(colonIdx + 1).trim();
+      fm[key] = val;
+    }
+  });
+  return { frontmatter: fm, body: match[2] };
+}
+
+function convertToInstruction(skillPath, skillName) {
+  const skillMd = path.join(skillPath, 'SKILL.md');
+  if (!fs.existsSync(skillMd)) return null;
+
+  const content = fs.readFileSync(skillMd, 'utf8');
+  const { frontmatter, body } = parseFrontmatter(content);
+
+  const description = (frontmatter.description || `${skillName} guidelines`)
+    .replace(/^['"]|['"]$/g, '');
+  const applyTo = getApplyTo(skillName);
+
+  const newFm = `---
+description: '${description.replace(/'/g, "''")}'
+applyTo: '${applyTo}'
+---`;
+
+  return `${newFm}\n${body}`;
+}
+
+// Main
+const skills = fs.readdirSync(SKILLS_DIR, { withFileTypes: true })
+  .filter(e => e.isDirectory() && !e.name.startsWith('.'));
+
+skills.forEach(skill => {
+  const skillPath = path.join(SKILLS_DIR, skill.name);
+
+  // Skip skills with assets
+  const hasAssets = fs.readdirSync(skillPath, { withFileTypes: true })
+    .some(e => e.isDirectory() && !e.name.startsWith('.'));
+
+  if (hasAssets) {
+    console.log(`Skipping ${skill.name} (has assets)`);
+    return;
+  }
+
+  const converted = convertToInstruction(skillPath, skill.name);
+  if (converted) {
+    const targetName = `ck-${skill.name}.instructions.md`;
+    const targetPath = path.join(INSTRUCTIONS_DIR, targetName);
+    fs.writeFileSync(targetPath, converted);
+    console.log(`Converted: ${skill.name} -> ${targetName}`);
+  }
+});
+```
+
+### Step 3: Copy Complex Skills
+
+Create `eng/copy-complex-skills.mjs`:
+
+```javascript
+#!/usr/bin/env node
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+const SKILLS_DIR = path.join(os.homedir(), '.claude', 'skills');
+const TARGET_SKILLS_DIR = path.join(process.cwd(), 'skills');
+
+const COMPLEX_SKILLS = ['chrome-devtools', 'mcp-management'];
+
+function copyRecursive(src, dest) {
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules') continue; // Skip node_modules
+      copyRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+COMPLEX_SKILLS.forEach(skillName => {
+  const src = path.join(SKILLS_DIR, skillName);
+  const dest = path.join(TARGET_SKILLS_DIR, `ck-${skillName}`);
+
+  if (fs.existsSync(src)) {
+    copyRecursive(src, dest);
+
+    // Update SKILL.md frontmatter
+    const skillMd = path.join(dest, 'SKILL.md');
+    if (fs.existsSync(skillMd)) {
+      let content = fs.readFileSync(skillMd, 'utf8');
+      content = content.replace(
+        /name:\s*['"]?([^'"\n]+)['"]?/,
+        `name: 'ck-$1'`
+      );
+      fs.writeFileSync(skillMd, content);
+    }
+
+    console.log(`Copied: ${skillName} -> ck-${skillName}/`);
+  }
+});
+```
+
+### Step 4: Verify Skill Structure
+
+Each skill folder must have:
+- `SKILL.md` with valid frontmatter
+- `name` field (lowercase, hyphens, max 64 chars)
+- `description` field (10-1024 chars)
+
+## Success Criteria
+
+- [ ] All simple skills (36) converted to instructions
+- [ ] Complex skills (2) copied with assets
+- [ ] All instructions have `description` and `applyTo`
+- [ ] All skills have valid `name` and `description`
+- [ ] Filenames follow naming conventions
+- [ ] No node_modules copied
+
+## Risk Assessment
+
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| Wrong applyTo patterns | Medium | Low | Manual review |
+| Missing skill content | Low | High | Validate source exists |
+| Large asset files | Medium | Medium | Skip node_modules |
+| Description length | Low | Low | Truncate to 1024 chars |

package/plans/260108-0924-rebuild-cokit-awesome-copilot-format/phase-05-create-collections.md

@@ -0,0 +1,320 @@
+# Phase 5: Create Collections
+
+## Context Links
+- [Main Plan](./plan.md)
+- [Phase 4: Convert Skills](./phase-04-convert-skills-to-instructions.md)
+
+## Overview
+
+| Priority | Status | Effort |
+|----------|--------|--------|
+| P2 | pending | 2h |
+
+## Key Insights
+
+1. ClaudeKit workflows la markdown files mo ta quy trinh
+2. Collections la YAML files group related prompts/instructions/agents
+3. Moi collection toi da 50 items
+4. Featured collections hien thi dau README
+
+## Requirements
+
+### Source Workflows (4 files)
+
+| Workflow | Description | Target Collection |
+|----------|-------------|-------------------|
+| `primary-workflow.md` | Main dev workflow | `ck-development.collection.yml` |
+| `development-rules.md` | Coding standards | `ck-code-quality.collection.yml` |
+| `documentation-management.md` | Docs workflow | `ck-documentation.collection.yml` |
+| `orchestration-protocol.md` | Agent coordination | `ck-orchestration.collection.yml` |
+
+### Additional Collections
+
+| Collection | Purpose | Items |
+|------------|---------|-------|
+| `ck-core.collection.yml` | Essential prompts | 6 core prompts |
+| `ck-fixing.collection.yml` | Bug fixing | fix variants |
+| `ck-planning.collection.yml` | Planning tools | plan variants |
+| `ck-frontend.collection.yml` | Frontend dev | frontend skills |
+| `ck-backend.collection.yml` | Backend dev | backend skills |
+
+## Collection Schema
+
+```yaml
+id: collection-name          # Required, lowercase-with-hyphens
+name: Collection Display Name # Required, max 100 chars
+description: Brief description of collection purpose # Required, max 500 chars
+tags: [tag1, tag2]           # Optional, max 10 tags
+items:                       # Required, 1-50 items
+  - path: prompts/file.prompt.md
+    kind: prompt             # prompt | instruction | agent | skill
+    usage: Optional usage notes
+display:
+  ordering: alpha            # alpha | manual
+  show_badge: true
+  featured: false            # Show in main README
+```
+
+## Implementation Steps
+
+### Step 1: Create Core Collection
+
+Create `collections/ck-core.collection.yml`:
+
+```yaml
+id: ck-core
+name: CoKit Core
+description: Essential CoKit prompts for everyday development tasks including debugging, planning, testing, and documentation.
+tags: [cokit, essential, development, productivity]
+items:
+  - path: prompts/ck-fix.prompt.md
+    kind: prompt
+    usage: Use for debugging and fixing code issues
+  - path: prompts/ck-plan.prompt.md
+    kind: prompt
+    usage: Create implementation plans before coding
+  - path: prompts/ck-code.prompt.md
+    kind: prompt
+    usage: Implement features from plans
+  - path: prompts/ck-test.prompt.md
+    kind: prompt
+    usage: Write tests for your code
+  - path: prompts/ck-review.prompt.md
+    kind: prompt
+    usage: Review code before committing
+  - path: prompts/ck-docs.prompt.md
+    kind: prompt
+    usage: Update project documentation
+display:
+  ordering: manual
+  show_badge: true
+  featured: true
+```
+
+### Step 2: Create Development Collection
+
+Create `collections/ck-development.collection.yml`:
+
+```yaml
+id: ck-development
+name: CoKit Development Workflow
+description: Complete development workflow from ClaudeKit including planning, implementation, testing, and code review practices.
+tags: [cokit, workflow, development, best-practices]
+items:
+  # Planning
+  - path: prompts/ck-plan.prompt.md
+    kind: prompt
+  - path: prompts/ck-plan-fast.prompt.md
+    kind: prompt
+  - path: prompts/ck-plan-hard.prompt.md
+    kind: prompt
+
+  # Implementation
+  - path: prompts/ck-code.prompt.md
+    kind: prompt
+  - path: prompts/ck-code-auto.prompt.md
+    kind: prompt
+
+  # Testing
+  - path: prompts/ck-test.prompt.md
+    kind: prompt
+
+  # Review
+  - path: agents/ck-code-reviewer.agent.md
+    kind: agent
+
+  # Instructions
+  - path: instructions/ck-debugging.instructions.md
+    kind: instruction
+  - path: instructions/ck-code-review.instructions.md
+    kind: instruction
+display:
+  ordering: manual
+  featured: true
+```
+
+### Step 3: Create Fixing Collection
+
+Create `collections/ck-fixing.collection.yml`:
+
+```yaml
+id: ck-fixing
+name: CoKit Bug Fixing
+description: Comprehensive bug fixing toolkit with variants for different scenarios - quick fixes, complex issues, CI failures, and more.
+tags: [cokit, debugging, bugfix, troubleshooting]
+items:
+  - path: prompts/ck-fix.prompt.md
+    kind: prompt
+    usage: Main fix command with intelligent routing
+  - path: prompts/ck-fix-fast.prompt.md
+    kind: prompt
+    usage: Quick fixes for simple issues
+  - path: prompts/ck-fix-hard.prompt.md
+    kind: prompt
+    usage: Complex issues requiring deep analysis
+  - path: prompts/ck-fix-parallel.prompt.md
+    kind: prompt
+    usage: Multiple independent issues
+  - path: prompts/ck-fix-ci.prompt.md
+    kind: prompt
+    usage: CI/CD pipeline failures
+  - path: prompts/ck-fix-types.prompt.md
+    kind: prompt
+    usage: TypeScript type errors
+  - path: prompts/ck-fix-ui.prompt.md
+    kind: prompt
+    usage: UI/UX issues
+  - path: prompts/ck-fix-logs.prompt.md
+    kind: prompt
+    usage: Log analysis and error tracing
+  - path: prompts/ck-fix-test.prompt.md
+    kind: prompt
+    usage: Test failures
+  - path: agents/ck-debugger.agent.md
+    kind: agent
+  - path: instructions/ck-debugging.instructions.md
+    kind: instruction
+display:
+  ordering: manual
+  show_badge: true
+```
+
+### Step 4: Create Planning Collection
+
+Create `collections/ck-planning.collection.yml`:
+
+```yaml
+id: ck-planning
+name: CoKit Planning
+description: Planning and research tools for creating implementation plans, conducting technical research, and managing project scope.
+tags: [cokit, planning, research, architecture]
+items:
+  - path: prompts/ck-plan.prompt.md
+    kind: prompt
+  - path: prompts/ck-plan-fast.prompt.md
+    kind: prompt
+  - path: prompts/ck-plan-hard.prompt.md
+    kind: prompt
+  - path: prompts/ck-plan-parallel.prompt.md
+    kind: prompt
+  - path: prompts/ck-plan-validate.prompt.md
+    kind: prompt
+  - path: agents/ck-planner.agent.md
+    kind: agent
+  - path: agents/ck-researcher.agent.md
+    kind: agent
+  - path: instructions/ck-planning.instructions.md
+    kind: instruction
+  - path: instructions/ck-research.instructions.md
+    kind: instruction
+display:
+  ordering: manual
+  show_badge: true
+```
+
+### Step 5: Create Frontend Collection
+
+Create `collections/ck-frontend.collection.yml`:
+
+```yaml
+id: ck-frontend
+name: CoKit Frontend Development
+description: Frontend development tools including UI/UX design, styling, and framework-specific guidelines.
+tags: [cokit, frontend, ui, react, vue, css]
+items:
+  - path: instructions/ck-frontend-design.instructions.md
+    kind: instruction
+  - path: instructions/ck-frontend-design-pro.instructions.md
+    kind: instruction
+  - path: instructions/ck-frontend-development.instructions.md
+    kind: instruction
+  - path: instructions/ck-ui-styling.instructions.md
+    kind: instruction
+  - path: instructions/ck-ui-ux-pro-max.instructions.md
+    kind: instruction
+  - path: instructions/ck-threejs.instructions.md
+    kind: instruction
+  - path: prompts/ck-design-fast.prompt.md
+    kind: prompt
+  - path: prompts/ck-design-good.prompt.md
+    kind: prompt
+  - path: agents/ck-ui-ux-designer.agent.md
+    kind: agent
+display:
+  ordering: alpha
+```
+
+### Step 6: Create Backend Collection
+
+Create `collections/ck-backend.collection.yml`:
+
+```yaml
+id: ck-backend
+name: CoKit Backend Development
+description: Backend development tools including API design, database management, and server-side best practices.
+tags: [cokit, backend, api, database, devops]
+items:
+  - path: instructions/ck-backend-development.instructions.md
+    kind: instruction
+  - path: instructions/ck-databases.instructions.md
+    kind: instruction
+  - path: instructions/ck-devops.instructions.md
+    kind: instruction
+  - path: instructions/ck-dotnet-backend.instructions.md
+    kind: instruction
+  - path: agents/ck-database-admin.agent.md
+    kind: agent
+  - path: agents/ck-fullstack-developer.agent.md
+    kind: agent
+display:
+  ordering: alpha
+```
+
+### Step 7: Create Git Collection
+
+Create `collections/ck-git.collection.yml`:
+
+```yaml
+id: ck-git
+name: CoKit Git Operations
+description: Git workflow tools for commits, pull requests, merges, and branch management.
+tags: [cokit, git, pr, commit, workflow]
+items:
+  - path: prompts/ck-git-pr.prompt.md
+    kind: prompt
+    usage: Create pull requests
+  - path: prompts/ck-git-cm.prompt.md
+    kind: prompt
+    usage: Create commits
+  - path: prompts/ck-git-cp.prompt.md
+    kind: prompt
+    usage: Cherry pick commits
+  - path: prompts/ck-git-merge.prompt.md
+    kind: prompt
+    usage: Merge branches
+  - path: agents/ck-git-manager.agent.md
+    kind: agent
+display:
+  ordering: manual
+```
+
+### Step 8: Validate Collections
+
+Create validation script or use existing `eng/validate-collections.mjs`.
+
+## Success Criteria
+
+- [ ] All 4 workflows converted to collections
+- [ ] 5+ additional curated collections created
+- [ ] All collections have valid schema
+- [ ] Featured collections marked appropriately
+- [ ] Item paths reference existing files
+- [ ] Max 50 items per collection
+
+## Risk Assessment
+
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| Invalid item paths | High | Medium | Validate after all phases |
+| Too many items | Low | Low | Split into sub-collections |
+| Missing referenced files | Medium | Medium | Create placeholder files |