cokit-cli 1.0.1 → 1.0.2

package/plans/260108-0924-rebuild-cokit-awesome-copilot-format/phase-01-restructure-folders.md

@@ -0,0 +1,183 @@
+# Phase 1: Restructure Folders
+
+## Context Links
+- [Main Plan](./plan.md)
+- Reference: `C:\w\_demo\awesome-copilot-main\` (Awesome Copilot structure)
+
+## Overview
+
+| Priority | Status | Effort |
+|----------|--------|--------|
+| P1 | pending | 1h |
+
+## Key Insights
+
+1. Awesome Copilot dung cau truc flat voi 5 directories chinh
+2. Moi category co README rieng trong `docs/`
+3. Build scripts nam trong `eng/` folder
+4. Schema validation cho collections
+
+## Requirements
+
+### Target Directory Structure
+
+```
+C:\w\_me\cokit\
+├── agents/                  # *.agent.md files
+├── prompts/                 # *.prompt.md files
+├── instructions/            # *.instructions.md files
+├── skills/                  # */SKILL.md folders
+├── collections/             # *.collection.yml files
+├── docs/                    # Category READMEs
+│   ├── README.agents.md
+│   ├── README.prompts.md
+│   ├── README.instructions.md
+│   ├── README.skills.md
+│   └── README.collections.md
+├── eng/                     # Build scripts
+│   ├── constants.mjs
+│   ├── update-readme.mjs
+│   ├── validate-collections.mjs
+│   ├── validate-skills.mjs
+│   ├── create-collection.mjs
+│   ├── create-skill.mjs
+│   └── yaml-parser.mjs
+├── .schemas/                # JSON schemas
+│   └── collection.schema.json
+├── templates/               # Keep for init command (repo templates)
+│   └── repo/
+│       ├── .github/
+│       └── .vscode/
+├── src/                     # CLI source (keep existing)
+├── bin/                     # CLI entrypoint (keep existing)
+├── AGENTS.md                # Project instructions for AI
+├── README.md                # Main readme
+└── package.json
+```
+
+## Related Code Files
+
+| File | Purpose | Action |
+|------|---------|--------|
+| `package.json` | Dependencies | Add js-yaml, vfile-matter |
+| `.gitignore` | Git ignore | Update for new structure |
+
+## Implementation Steps
+
+### Step 1: Create Core Directories
+
+```bash
+# From C:\w\_me\cokit\
+mkdir agents
+mkdir prompts
+mkdir instructions
+mkdir collections
+mkdir eng
+mkdir .schemas
+```
+
+### Step 2: Create Collection Schema
+
+Create `.schemas/collection.schema.json`:
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Collection Manifest",
+  "type": "object",
+  "required": ["id", "name", "description", "items"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]+$",
+      "maxLength": 50
+    },
+    "name": {
+      "type": "string",
+      "maxLength": 100
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 500
+    },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^[a-z0-9-]+$" },
+      "maxItems": 10
+    },
+    "items": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 50,
+      "items": {
+        "type": "object",
+        "required": ["path", "kind"],
+        "properties": {
+          "path": { "type": "string" },
+          "kind": { "enum": ["prompt", "instruction", "agent", "skill"] }
+        }
+      }
+    }
+  }
+}
+```
+
+### Step 3: Update package.json
+
+Add dependencies:
+
+```json
+{
+  "dependencies": {
+    "commander": "^12.0.0",
+    "prompts": "^2.4.2",
+    "chalk": "^5.3.0",
+    "js-yaml": "^4.1.0",
+    "vfile-matter": "^5.0.0"
+  },
+  "scripts": {
+    "build": "node eng/update-readme.mjs",
+    "collection:validate": "node eng/validate-collections.mjs",
+    "collection:create": "node eng/create-collection.mjs",
+    "skill:validate": "node eng/validate-skills.mjs",
+    "skill:create": "node eng/create-skill.mjs"
+  }
+}
+```
+
+### Step 4: Update .gitignore
+
+```gitignore
+node_modules/
+*.log
+.DS_Store
+# Keep templates and build output
+!templates/
+!docs/README.*.md
+```
+
+### Step 5: Create Placeholder Files
+
+Create empty placeholder files de Git track directories:
+
+```bash
+touch agents/.gitkeep
+touch prompts/.gitkeep
+touch instructions/.gitkeep
+touch collections/.gitkeep
+```
+
+## Success Criteria
+
+- [ ] All 6 directories created
+- [ ] `.schemas/collection.schema.json` valid JSON
+- [ ] `package.json` updated with new deps and scripts
+- [ ] `.gitignore` updated
+- [ ] Directory structure matches Awesome Copilot format
+
+## Risk Assessment
+
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| Git conflicts | Low | Low | Create fresh directories |
+| Missing dependencies | Low | Medium | Test npm install |

package/plans/260108-0924-rebuild-cokit-awesome-copilot-format/phase-02-convert-agents.md

@@ -0,0 +1,206 @@
+# Phase 2: Convert Agents
+
+## Context Links
+- [Main Plan](./plan.md)
+- [Phase 1: Restructure Folders](./phase-01-restructure-folders.md)
+
+## Overview
+
+| Priority | Status | Effort |
+|----------|--------|--------|
+| P1 | pending | 2h |
+
+## Key Insights
+
+1. ClaudeKit agents co frontmatter: `name`, `description`, `model`
+2. Awesome Copilot agents can: `description`, `model`, `tools`, `allowed-tools`
+3. Model mapping: opus → GPT-4.1, sonnet → GPT-4.0
+4. Filename format: `kebab-case.agent.md`
+
+## Requirements
+
+### Source Agents (17 files)
+
+| ClaudeKit Agent | Target File |
+|-----------------|-------------|
+| `copywriter.md` | `ck-copywriter.agent.md` |
+| `docs-manager.md` | `ck-docs-manager.agent.md` |
+| `tester.md` | `ck-tester.agent.md` |
+| `scout.md` | `ck-scout.agent.md` |
+| `debugger.md` | `ck-debugger.agent.md` |
+| `project-manager.md` | `ck-project-manager.agent.md` |
+| `scout-external.md` | `ck-scout-external.agent.md` |
+| `brainstormer.md` | `ck-brainstormer.agent.md` |
+| `journal-writer.md` | `ck-journal-writer.agent.md` |
+| `database-admin.md` | `ck-database-admin.agent.md` |
+| `code-reviewer.md` | `ck-code-reviewer.agent.md` |
+| `fullstack-developer.md` | `ck-fullstack-developer.agent.md` |
+| `git-manager.md` | `ck-git-manager.agent.md` |
+| `mcp-manager.md` | `ck-mcp-manager.agent.md` |
+| `planner.md` | `ck-planner.agent.md` |
+| `researcher.md` | `ck-researcher.agent.md` |
+| `ui-ux-designer.md` | `ck-ui-ux-designer.agent.md` |
+
+### Frontmatter Conversion
+
+**ClaudeKit Format:**
+```yaml
+---
+name: planner
+description: Use this agent when...
+model: opus
+---
+```
+
+**Awesome Copilot Format:**
+```yaml
+---
+description: 'Use this agent when...'
+model: 'GPT-4.1'
+tools: ['search', 'read', 'edit/editFiles']
+---
+```
+
+### Model Mapping
+
+| ClaudeKit | Copilot |
+|-----------|---------|
+| opus | GPT-4.1 |
+| sonnet | GPT-4.0 |
+| (default) | GPT-4.0 |
+
+## Related Code Files
+
+| File | Purpose |
+|------|---------|
+| `~/.claude/agents/*.md` | Source agents |
+| `agents/*.agent.md` | Target location |
+
+## Implementation Steps
+
+### Step 1: Create Conversion Script
+
+Create `eng/convert-agents.mjs`:
+
+```javascript
+#!/usr/bin/env node
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+const CLAUDE_AGENTS_DIR = path.join(os.homedir(), '.claude', 'agents');
+const TARGET_DIR = path.join(process.cwd(), 'agents');
+
+const MODEL_MAP = {
+  'opus': 'GPT-4.1',
+  'sonnet': 'GPT-4.0'
+};
+
+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 [key, ...val] = line.split(':');
+    if (key && val.length) {
+      fm[key.trim()] = val.join(':').trim();
+    }
+  });
+  return { frontmatter: fm, body: match[2] };
+}
+
+function convertAgent(sourceFile) {
+  const content = fs.readFileSync(sourceFile, 'utf8');
+  const { frontmatter, body } = parseFrontmatter(content);
+
+  const model = MODEL_MAP[frontmatter.model] || 'GPT-4.0';
+  const description = frontmatter.description || 'Agent description';
+
+  const newFm = `---
+description: '${description.replace(/'/g, "''")}'
+model: '${model}'
+---`;
+
+  return `${newFm}\n${body}`;
+}
+
+// Main
+const files = fs.readdirSync(CLAUDE_AGENTS_DIR)
+  .filter(f => f.endsWith('.md'));
+
+files.forEach(file => {
+  const source = path.join(CLAUDE_AGENTS_DIR, file);
+  const targetName = `ck-${file.replace('.md', '.agent.md')}`;
+  const target = path.join(TARGET_DIR, targetName);
+
+  const converted = convertAgent(source);
+  fs.writeFileSync(target, converted);
+  console.log(`Converted: ${file} -> ${targetName}`);
+});
+```
+
+### Step 2: Manual Review Checklist
+
+For each converted agent, verify:
+
+1. [ ] Description wrapped in single quotes
+2. [ ] Model field present and valid
+3. [ ] No broken markdown formatting
+4. [ ] Remove Claude-specific references (e.g., "delegate to agent")
+
+### Step 3: Update Agent Content
+
+Replace Claude-specific patterns:
+
+| Find | Replace |
+|------|---------|
+| `delegate to \`agent\` agent` | `use specialized approach for` |
+| `%USERPROFILE%/.claude/` | `project's .github/` |
+| `Task tool` | `available tools` |
+
+### Step 4: Add Tools Field (Optional)
+
+Common tools for Copilot agents:
+
+```yaml
+tools: ['search', 'read', 'edit/editFiles', 'execute/runInTerminal']
+```
+
+## Agent Template
+
+```markdown
+---
+description: 'Brief description of agent purpose'
+model: 'GPT-4.1'
+tools: ['search', 'read', 'edit/editFiles']
+---
+
+# Agent Name
+
+## Purpose
+What this agent does.
+
+## Capabilities
+- Capability 1
+- Capability 2
+
+## Usage
+How to use this agent.
+```
+
+## Success Criteria
+
+- [ ] All 17 agents converted
+- [ ] Filenames follow `ck-*.agent.md` pattern
+- [ ] All have valid frontmatter with `description`
+- [ ] Model values are valid Copilot models
+- [ ] No Claude-specific references remain
+
+## Risk Assessment
+
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| Description too long | Medium | Low | Truncate to 500 chars |
+| Special chars in description | Medium | Low | Escape single quotes |
+| Claude-specific features | High | Medium | Manual review |

package/plans/260108-0924-rebuild-cokit-awesome-copilot-format/phase-03-convert-commands-to-prompts.md

@@ -0,0 +1,284 @@
+# Phase 3: Convert Commands to Prompts
+
+## Context Links
+- [Main Plan](./plan.md)
+- [Phase 2: Convert Agents](./phase-02-convert-agents.md)
+
+## Overview
+
+| Priority | Status | Effort |
+|----------|--------|--------|
+| P1 | pending | 4h |
+
+## Key Insights
+
+1. ClaudeKit commands dung nested folder structure (e.g., `ck/fix/hard.md`)
+2. Awesome Copilot prompts la flat files (e.g., `ck-fix-hard.prompt.md`)
+3. ClaudeKit dung `$ARGUMENTS` variable - Copilot khong co equivalent
+4. Prompts phai co `agent` field (value = `'agent'` for reusable prompts)
+
+## Requirements
+
+### Source Commands Structure
+
+```
+~/.claude/commands/ck/
+├── fix.md                    → ck-fix.prompt.md
+├── fix/
+│   ├── fast.md               → ck-fix-fast.prompt.md
+│   ├── hard.md               → ck-fix-hard.prompt.md
+│   ├── parallel.md           → ck-fix-parallel.prompt.md
+│   ├── logs.md               → ck-fix-logs.prompt.md
+│   ├── test.md               → ck-fix-test.prompt.md
+│   ├── ci.md                 → ck-fix-ci.prompt.md
+│   ├── types.md              → ck-fix-types.prompt.md
+│   └── ui.md                 → ck-fix-ui.prompt.md
+├── code.md                   → ck-code.prompt.md
+├── code/
+│   ├── auto.md               → ck-code-auto.prompt.md
+│   ├── no-test.md            → ck-code-no-test.prompt.md
+│   └── parallel.md           → ck-code-parallel.prompt.md
+├── plan.md                   → ck-plan.prompt.md
+├── plan/
+│   ├── fast.md               → ck-plan-fast.prompt.md
+│   ├── hard.md               → ck-plan-hard.prompt.md
+│   ├── parallel.md           → ck-plan-parallel.prompt.md
+│   ├── validate.md           → ck-plan-validate.prompt.md
+│   ├── archive.md            → ck-plan-archive.prompt.md
+│   └── ...
+├── test.md                   → ck-test.prompt.md
+├── debug.md                  → ck-debug.prompt.md
+├── cook.md                   → ck-cook.prompt.md
+├── cook/
+│   ├── auto.md               → ck-cook-auto.prompt.md
+│   └── auto/
+│       ├── fast.md           → ck-cook-auto-fast.prompt.md
+│       └── parallel.md       → ck-cook-auto-parallel.prompt.md
+├── docs/
+│   ├── init.md               → ck-docs-init.prompt.md
+│   ├── update.md             → ck-docs-update.prompt.md
+│   └── summarize.md          → ck-docs-summarize.prompt.md
+├── git/
+│   ├── pr.md                 → ck-git-pr.prompt.md
+│   ├── cm.md                 → ck-git-cm.prompt.md
+│   ├── cp.md                 → ck-git-cp.prompt.md
+│   └── merge.md              → ck-git-merge.prompt.md
+└── ... (71 total)
+```
+
+### Complete Command List (71 files)
+
+| Category | Commands |
+|----------|----------|
+| Core | fix, code, plan, test, debug, cook |
+| Fix variants | fast, hard, parallel, logs, test, ci, types, ui |
+| Code variants | auto, no-test, parallel |
+| Plan variants | fast, hard, parallel, validate, archive, two, ci, cro |
+| Cook variants | auto, auto/fast, auto/parallel |
+| Bootstrap | bootstrap, auto, auto/parallel, auto/fast |
+| Docs | init, update, summarize |
+| Git | pr, cm, cp, merge |
+| Design | video, screenshot, describe, 3d, fast, good |
+| Content | enhance, fast, cro, good |
+| Review | codebase |
+| Skill | fix-logs, add, create, optimize, optimize/auto, plan |
+| Integrate | polar, sepay |
+| Utility | ask, watzup, scout, scout/ext, journal, brainstorm, preview, kanban, worktree, coding-level, ck-help, use-mcp, test/ui |
+
+### Frontmatter Conversion
+
+**ClaudeKit Format:**
+```yaml
+---
+description: Fix issues
+argument-hint: [issues]
+---
+```
+
+**Awesome Copilot Format:**
+```yaml
+---
+agent: 'agent'
+description: 'Fix issues - provide issues in chat'
+model: 'GPT-4.0'
+---
+```
+
+## Implementation Steps
+
+### Step 1: Create Flattening Script
+
+Create `eng/convert-commands.mjs`:
+
+```javascript
+#!/usr/bin/env node
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+const COMMANDS_DIR = path.join(os.homedir(), '.claude', 'commands', 'ck');
+const TARGET_DIR = path.join(process.cwd(), 'prompts');
+
+function flattenPath(relativePath) {
+  // ck/fix/hard.md -> ck-fix-hard.prompt.md
+  return 'ck-' + relativePath
+    .replace(/\//g, '-')
+    .replace('.md', '.prompt.md');
+}
+
+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 [key, ...val] = line.split(':');
+    if (key && val.length) {
+      fm[key.trim()] = val.join(':').trim();
+    }
+  });
+  return { frontmatter: fm, body: match[2] };
+}
+
+function convertPrompt(content, filename) {
+  const { frontmatter, body } = parseFrontmatter(content);
+
+  let description = frontmatter.description || `Prompt: ${filename}`;
+
+  // Handle $ARGUMENTS
+  let newBody = body.replace(/\$ARGUMENTS/g, '[user input from chat]');
+
+  // Add note about arguments if present
+  if (body.includes('$ARGUMENTS') || frontmatter['argument-hint']) {
+    const hint = frontmatter['argument-hint'] || 'input';
+    description += ` - Provide ${hint} in chat`;
+  }
+
+  // Clean description
+  description = description
+    .replace(/'/g, "''")
+    .substring(0, 500);
+
+  const newFm = `---
+agent: 'agent'
+description: '${description}'
+---`;
+
+  return `${newFm}\n${newBody}`;
+}
+
+function walkDir(dir, base = '') {
+  const files = [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    const relativePath = base ? `${base}/${entry.name}` : entry.name;
+
+    if (entry.isDirectory()) {
+      files.push(...walkDir(fullPath, relativePath));
+    } else if (entry.name.endsWith('.md')) {
+      files.push({ fullPath, relativePath });
+    }
+  }
+  return files;
+}
+
+// Main
+const files = walkDir(COMMANDS_DIR);
+console.log(`Found ${files.length} command files`);
+
+files.forEach(({ fullPath, relativePath }) => {
+  const content = fs.readFileSync(fullPath, 'utf8');
+  const targetName = flattenPath(relativePath);
+  const target = path.join(TARGET_DIR, targetName);
+
+  const converted = convertPrompt(content, targetName);
+  fs.writeFileSync(target, converted);
+  console.log(`Converted: ${relativePath} -> ${targetName}`);
+});
+```
+
+### Step 2: Handle $ARGUMENTS Replacement
+
+ClaudeKit `$ARGUMENTS` patterns:
+
+| Pattern | Replacement |
+|---------|-------------|
+| `<issues>$ARGUMENTS</issues>` | `<issues>[Describe issues in chat]</issues>` |
+| `$ARGUMENTS` in body | `[user input from chat]` |
+| `argument-hint: [issues]` | Add to description |
+
+### Step 3: Remove Claude-Specific References
+
+| Find | Replace/Remove |
+|------|----------------|
+| `/code <path-to-plan>` | `follow the plan at [path]` |
+| `/fix:types` | `use type-fixing approach` |
+| `delegate to \`agent\`` | Remove or generalize |
+| `Task tool` | `available tools` |
+
+### Step 4: Organize by Category
+
+After conversion, verify prompts by category:
+
+```
+prompts/
+├── ck-fix.prompt.md          # Core
+├── ck-fix-*.prompt.md        # Fix variants (8 files)
+├── ck-code.prompt.md         # Core
+├── ck-code-*.prompt.md       # Code variants (3 files)
+├── ck-plan.prompt.md         # Core
+├── ck-plan-*.prompt.md       # Plan variants (8 files)
+├── ck-test.prompt.md         # Core
+├── ck-cook.prompt.md         # Core
+├── ck-cook-*.prompt.md       # Cook variants (3 files)
+├── ck-docs-*.prompt.md       # Docs (3 files)
+├── ck-git-*.prompt.md        # Git (4 files)
+├── ck-design-*.prompt.md     # Design (6 files)
+└── ...
+```
+
+## Prompt Template
+
+```markdown
+---
+agent: 'agent'
+description: 'Brief description of what this prompt does'
+model: 'GPT-4.0'
+---
+
+# Prompt Title
+
+## Purpose
+What this prompt accomplishes.
+
+## Instructions
+1. Step one
+2. Step two
+3. Step three
+
+## Expected Input
+- Input type 1
+- Input type 2
+
+## Output Format
+Description of expected output.
+```
+
+## Success Criteria
+
+- [ ] All 71 commands converted to prompts
+- [ ] Filenames follow `ck-*.prompt.md` pattern (lowercase, hyphens)
+- [ ] All have `agent` field with value `'agent'`
+- [ ] All have non-empty `description` field
+- [ ] No `$ARGUMENTS` variables remain
+- [ ] No broken slash command references
+
+## Risk Assessment
+
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| Complex nested routing lost | High | Medium | Document original behavior |
+| $ARGUMENTS functionality lost | High | Medium | Add instructions to provide input |
+| Inter-command references broken | High | Medium | Update to use generic text |