cokit-cli 1.2.7 → 1.4.0

package/docs/claudekit-porting-rules.md

@@ -1,182 +0,0 @@
-# ClaudeKit → CoKit Porting Rules
-
-**Purpose:** Definitive reference for porting ClaudeKit (Claude Code) content to CoKit (GitHub Copilot).
-**Audience:** AI agents and developers performing sync/port operations.
-**Last Updated:** 2026-02-25
-
----
-
-## 0. Porting Workflow
-
-**IMPORTANT:** Always follow this order when porting from ClaudeKit.
-
-### Step 1: Inventory CoKit
-Map what CoKit already has — prompts, agents, skills, instructions. This is the source of truth.
-
-### Step 2: Diff against ClaudeKit
-Compare ClaudeKit's commands/agents/skills with CoKit inventory. Identify:
-- **Updates** — existing CoKit files that need content sync
-- **New variants** — ClaudeKit has a new sub-command (e.g., `/plan:red-team`) → create as `/ck-plan-red-team` variant
-- **New top-level** — entirely new prompt/agent/skill → create in CoKit
-
-### Step 3: Verify Copilot compatibility
-Before porting, **websearch** to check if Copilot now supports features that were previously unavailable. Copilot evolves fast — what didn't work last month may work now.
-
-Key things to re-check periodically:
-- Subagent spawning & orchestration (`code.visualstudio.com/docs/copilot/agents/subagents`)
-- Agent-to-agent communication (currently NOT supported — may change)
-- Persistent memory API (currently NOT supported — may change)
-- Plan mode / approval flows (currently NOT supported — may change)
-- File ownership / task management APIs (currently NOT supported — may change)
-- New frontmatter fields (check `code.visualstudio.com/docs/copilot/customization/custom-agents`)
-
-### Step 4: Apply conversion rules (sections below)
-
-### Step 5: Validate with grep patterns (section 9)
-
-### Step 6: Update version & docs (section 8)
-
----
-
-## 1. Syntax Conversions
-
-| ClaudeKit | CoKit | Notes |
-|-----------|-------|-------|
-| `$ARGUMENTS` | `${input}` | Copilot prompt variable |
-| `@agent-name` | `` `agent-name` agent `` | No `@` prefix in Copilot |
-| `.claude/` paths | `$HOME/.copilot/` | Global config directory |
-| `~/.claude/` | `$HOME/.copilot/` | Same as above |
-| `subagent` | `agent` | Copilot terminology |
-
-## 2. Command References
-
-| ClaudeKit | CoKit | Notes |
-|-----------|-------|-------|
-| `/fix:types` | `/ck-fix-types` | Colon → hyphen |
-| `/fix:tests` | `/ck-fix-test` | Colon → hyphen |
-| `/scout:ext` | `/ck-scout ext` | Colon → space (argument) |
-| `/plan --hard` | `/ck-plan-hard` | Flag → separate command |
-| `/plan --fast` | `/ck-plan-fast` | Flag → separate command |
-| `SlashCommand(/scout)` | `/ck-scout` | Remove `SlashCommand()` wrapper |
-
-**New variant?** If ClaudeKit adds a new sub-command (e.g., `/plan:red-team`), create it as a variant prompt file in CoKit (`ck-plan-red-team.prompt.md`). Variants don't count toward prompt total.
-
-## 3. Tool/API Conversions
-
-| ClaudeKit | CoKit | Notes |
-|-----------|-------|-------|
-| `AskUserQuestion` | Natural conversation | Just ask the user directly |
-| `Task(subagent_type="X")` | Natural language delegation | Describe what agent should do |
-| `TaskCreate/TaskUpdate/TaskList` | Checklist/todo tracking | No task management API |
-| `SendMessage` | Direct communication | No message passing API |
-| `EnterPlanMode/ExitPlanMode` | N/A | Copilot doesn't have plan mode |
-
-**NOTE:** Websearch these before each port session — Copilot may add equivalents.
-
-## 4. Frontmatter Fields
-
-### Remove (unsupported by Copilot)
-- `name:` — Copilot infers from filename
-- `model:` — Copilot handles model selection
-- `memory:` — No persistent memory API
-- `version:` — Not a valid field
-- `license:` — Not a valid field
-- `scripts:` — Not valid in prompts
-- `handoffs:` — Not valid in prompts
-- `agent_scripts:` — Not valid
-
-### Keep/Modify
-- `description:` — Keep, but single line only (no examples)
-- `agent: 'agent'` — Required for agent-mode prompts
-- `tools:` — Keep valid tool references
-- `argument-hint:` — Keep for user guidance
-
-## 5. Agent-Specific Rules
-
-### CoKit agents (12)
-`brainstormer`, `code-reviewer`, `code-simplifier`, `debugger`, `docs-manager`, `fullstack-developer`, `git-manager`, `planner`, `researcher`, `scout`, `tester`, `ui-ux-designer`
-
-### ClaudeKit agents that DON'T exist in CoKit
-| ClaudeKit Agent | CoKit Replacement |
-|-----------------|-------------------|
-| `project-manager` | Direct action (describe what to do) |
-| `journal-writer` | Remove or convert to manual journaling |
-| `mcp-manager` | Remove or use `mcp-management` skill |
-
-### Agent file conventions
-- Remove `## Team Mode` sections — Copilot subagents don't support task claiming, peer communication, or file ownership
-- Add skills activation directive referencing `$HOME/.copilot/skills/*`
-
-## 6. External Tool Qualifiers
-
-If a skill/tool exists in CoKit's `skills/*/SKILL.md` → it's available, no qualifier needed.
-If NOT → add `(if available)`:
-
-| Tool | Action | Reason |
-|------|--------|--------|
-| `repomix` | Add "(if available)" | External npm package, needs CLI install |
-| `ai-multimodal` | Add "(if available)" | External Gemini skill, not in CoKit |
-| `ui-ux-pro-max` | Add "(if available)" | Not in CoKit skills |
-| `media-processing` | Add "(if available)" | Not in CoKit skills |
-| `chrome-devtools` | Use `agent-browser` | Renamed in CoKit |
-| `document-skills` | Use `docs-seeker` | Different name in CoKit |
-
-**Single flag:** Always use `(if available)` — never `(if installed)`.
-
-**Before porting:** Check if any missing skill has been added to CoKit since last port. If so, remove the qualifier.
-
-## 7. Prompt Classification
-
-- **Prompts** = top-level commands counted in "25 prompts" (e.g., `/ck-plan`, `/ck-fix`, `/ck-cook`)
-- **Variant commands** = sub-routes, NOT counted (e.g., `/ck-plan-fast`, `/ck-plan-hard`, `/ck-plan-validate`, `/ck-plan-red-team`)
-
-New variant → update flowchart + Deep Dive in `index.html`, do NOT bump prompt count.
-
-## 8. Version & Docs Update Checklist
-
-### Always update
-- [ ] `package.json` + `package-lock.json` (`npm install --package-lock-only`)
-- [ ] `CHANGELOG.md` — new entry
-- [ ] `index.html` — hero badge + footer version
-- [ ] `README.md` — "What's New" section
-- [ ] `docs/project-roadmap.md` — version + last updated
-
-### Sync if outdated (check version string)
-- [ ] `docs/README.md`
-- [ ] `docs/codebase-summary.md`
-- [ ] `docs/cokit-comprehensive-mapping-guide.md`
-- [ ] `docs/cokit-team-presentation.md`
-- [ ] `docs/cokit-sync-and-maintenance-guide.md`
-- [ ] `docs/guide-next-steps-speckit-cokit-implementation.md`
-- [ ] `docs/project-overview-pdr.md`
-
-### If new commands added
-- [ ] Flowchart nodes/edges in `index.html`
-- [ ] Deep Dive section in `index.html`
-- [ ] Prompts table in `index.html` (if variant of existing command)
-
-## 9. Validation Grep Patterns
-
-After porting, run these — must return 0 matches (except historical/changelog):
-
-```bash
-grep -r "@\w+-\w+" agents/ skills/ prompts/          # @agent-name syntax
-grep -r "project-manager" agents/ skills/ prompts/    # Non-existent agent
-grep -r "subagent" agents/                            # Wrong terminology
-grep -r "\.claude/" agents/ skills/ prompts/          # Wrong path
-grep -r "AskUserQuestion\|SlashCommand" agents/ skills/ prompts/  # Claude Code APIs
-grep -r "chrome-devtools" agents/                     # Renamed tool
-grep -r "\$ARGUMENTS" agents/ prompts/                # Wrong variable
-grep -r "^name:\|^model:\|^memory:" agents/ prompts/  # Invalid frontmatter
-```
-
-## 10. Common Mistakes
-
-1. **`@agent-name`** → Use `` `agent-name` agent `` (no `@` prefix)
-2. **`project-manager` agent** → Doesn't exist, replace with direct instructions
-3. **Team Mode sections** → Don't port, Copilot subagents are isolated
-4. **Missing "(if available)"** → External tools need `(if available)` qualifier. Use this single flag only — never "(if installed)"
-5. **Counting variants as prompts** → Variants don't bump prompt count
-6. **`SlashCommand()` wrappers** → Convert to plain `/ck-*`
-7. **`document-skills`** → Use `docs-seeker`
-8. **`chrome-devtools`** → Use `agent-browser`

package/docs/cokit-comprehensive-mapping-guide.md

@@ -1,357 +0,0 @@
-# CoKit: Comprehensive Guide
-
-Complete reference for CoKit GitHub Copilot resource toolkit.
-
-**Version:** 1.2.6
-**Date:** 2026-02-25
-
----
-
-## Table of Contents
-
-1. [Quick Overview](#quick-overview)
-2. [Resource Architecture](#resource-architecture)
-3. [Installation Guide](#installation-guide)
-4. [Feature Mapping](#feature-mapping)
-5. [Integration Patterns](#integration-patterns)
-6. [Best Practices](#best-practices)
-
----
-
-## Quick Overview
-
-CoKit transforms GitHub Copilot from basic autocomplete to a structured AI development assistant with:
-
-- **12 Specialized Agents** - Planner, code-reviewer, debugger, tester, researcher, code-simplifier, fullstack-developer, ui-ux-designer, etc.
-- **25 Prompt Templates** - Reusable workflows with `ck-*` and `ck-spec-*` prefixes
-- **27 Skill Packages** - Deep expertise in debugging, code-review, planning, frontend-design, databases, devops, etc.
-- **5 Instructions** - Coding standards auto-applied by file pattern (backend, frontend, testing, development, research)
-- **5 Collections** - Bundled resource sets for specific workflows (core, development-rules, documentation, git-workflow, orchestration)
-
-### Installation
-
-```bash
-npx cokit-cli init          # Interactive setup
-```
-
----
-
-## Resource Architecture
-
-### Prompts (`prompts/ck-*.prompt.md`)
-
-**Purpose:** Entry points defining workflows and tasks.
-
-**Format:**
-```yaml
----
-mode: agent
-description: 'Clear task description'
----
-
-# Workflow Title
-
-Step-by-step instructions...
-```
-
-**CoKit Prompts (27 total):**
-
-**ClaudeKit (ck-* namespace):** Development workflows - fix, plan, cook, test, review, debug, ask, etc.
-
-**SpecKit (ck-spec-* namespace):** Spec-driven workflows - specify, clarify, constitution, plan, tasks, implement, analyze, checklist, etc.
-
-All 25 prompts are unified in a single namespace for seamless workflow navigation.
-
-**Usage Example:**
-```
-User: /ck-fix The login endpoint returns 500 error
-
-Copilot uses: ck-fix.prompt.md → debugger.agent.md → ck-debugging skill
-Result: Systematic debugging plan and fix
-```
-
-### Agents (`agents/*.agent.md`)
-
-**Purpose:** Specialized personas executing specific tasks referenced by prompts.
-
-**CoKit Agents (12 total):**
-
-Core agents (9): planner, code-reviewer, debugger, tester, researcher, scout, git-manager, brainstormer, docs-manager
-
-New agents (3): code-simplifier, fullstack-developer, ui-ux-designer
-
-Each agent provides specialized expertise and is invoked by relevant prompts and commands.
-
-### Instructions (`instructions/ck-*.instructions.md`)
-
-**Purpose:** Coding standards auto-applied based on file patterns.
-
-**Format:**
-```yaml
----
-applyTo: '**/*.tsx, components/**'
-description: 'Frontend guidelines'
----
-
-# Rules
-
-When editing matching files:
-- Use functional components
-- Props interface required
-```
-
-**CoKit Instructions (5 total):**
-
-- `ck-backend` - Node.js, Python, Go, Rust patterns
-- `ck-frontend` - React, TypeScript, component patterns
-- `ck-testing` - Test writing standards
-- `ck-development` - YAGNI, KISS, DRY principles
-- `ck-research` - Research methodology
-
-### Skills (`skills/ck-*/SKILL.md`)
-
-**Purpose:** Deep specialized expertise packages with supporting resources.
-
-**Structure:**
-```
-skills/ck-skill-name/
-├── SKILL.md                # Main instructions
-├── references/             # Supporting documentation
-└── examples/               # Concrete examples
-```
-
-**CoKit Skills (27 total):**
-
-Core: debugging, code-review, planning, problem-solving, sequential-thinking, backend-development, frontend-design
-
-Extended: databases, devops, git, markdown-novel-viewer, mcp-management, context-engineering, cook, debug, fix, frontend-design, research, scout, ui-styling, web-testing, and more
-
-Skills are organized by domain expertise with specialized tools and reference materials for each.
-
-### Collections (`collections/ck-*.collection.yml`)
-
-**Purpose:** Curated bundles of related resources for specific workflows.
-
-**Format:**
-```yaml
-id: ck-collection-id
-name: Collection Name
-description: What this collection enables
-items:
-  - path: agents/agent.agent.md
-  - path: prompts/prompt.prompt.md
-  - path: skills/skill/
-```
-
-**CoKit Collections (5 total):**
-
-| Collection | Contents | Use Case |
-|---|---|---|
-| **ck-core** | Essential agents, prompts, skills | Full-stack development |
-| **ck-development-rules** | Development instructions and guidelines | Team consistency |
-| **ck-documentation** | Docs-manager, ck-docs prompt, skills | Documentation workflows |
-| **ck-git-workflow** | git-manager agent, ck-git prompt | Git automation |
-| **ck-orchestration** | Planner, researcher, orchestration guidance | Complex task delegation |
-
----
-
-## Installation Guide
-
-### Quick Start (30 seconds)
-
-```bash
-cd your-project
-npx cokit-cli init
-```
-
-You'll be prompted to choose:
-- **Project only** (`.github/`)
-- **Personal only** (`~/.copilot/`)
-- **Both** (recommended)
-
-### What Gets Installed
-
-**If Project Selected:**
-```
-.github/
-├── copilot-instructions.md    # Project AI guidelines
-├── AGENTS.md                   # Agent behavior rules
-├── prompts/ck-*.prompt.md      # 14 workflow templates
-├── instructions/ck-*.instructions.md  # 5 coding standards
-├── collections/ck-*.collection.yml    # 5 resource bundles
-└── skills/ck-*/                # Optional project skills
-```
-
-**If Personal Selected:**
-```
-~/.copilot/skills/
-├── ck-debugging/
-├── ck-code-review/
-├── ck-planning/
-├── ck-problem-solving/
-├── ck-sequential-thinking/
-├── ck-backend-development/
-└── ck-frontend-development/
-```
-
-### CLI Commands
-
-| Command | Description |
-|---------|-------------|
-| `npx cokit-cli init` | Interactive setup wizard |
-| `npx cokit-cli list` | Show installed components |
-| `npx cokit-cli doctor` | Diagnose setup issues |
-| `npx cokit-cli update` | Update to latest version |
-
----
-
-## Feature Mapping
-
-### Claude Code → CoKit (Reference)
-
-| Feature | Claude Code | CoKit/Copilot | Notes |
-|---------|-------------|---|---|
-| **Commands** | `/fix:types`, `/plan:auto` | `/ck-fix`, `/ck-plan`, `/ck-cook`, etc. | 14 prompts vs sub-commands |
-| **Skills** | `~/.claude/skills/` | `~/.copilot/skills/ck-*/` | Identical structure |
-| **Instructions** | `.claude/instructions/` | `.github/instructions/ck-*.md` | Auto-applied by pattern |
-| **Agents** | Task delegation | Agent references in prompts | Different invocation model |
-| **Collections** | Not available | `.github/collections/` | NEW: Bundle resources |
-| **Variables** | `$ARGUMENTS`, `$HOME` | User provides context in chat | Manual parameter passing |
-| **Hooks** | SessionStart, UserPrompt, etc. | Not supported | Workaround: embed in prompts |
-| **State** | Session state tracking | Stateless (per-message) | Manual workflow chaining |
-
----
-
-## Integration Patterns
-
-### Pattern 1: Fix & Debug Workflow
-
-```
-User: /ck-fix The API timeout is too short
-  ↓
-Prompt (ck-fix.prompt.md)
-  ↓
-Agent (debugger.agent.md)
-  ↓
-Skills Activated: ck-debugging, ck-sequential-thinking
-  ↓
-Output: Root cause analysis + fix
-```
-
-### Pattern 2: Feature Implementation
-
-```
-User: /ck-plan Build user authentication
-  ↓
-Prompt (ck-plan.prompt.md) + Agent (planner.agent.md)
-  ↓
-Skills: ck-planning, ck-sequential-thinking
-  ↓
-Output: Implementation plan
-
-User: /ck-code Implement step 1
-  ↓
-Prompt (ck-code.prompt.md) + Agent (code-reviewer monitors)
-  ↓
-Skills: ck-backend-development or ck-frontend-development
-  ↓
-Output: Implemented code
-
-User: /ck-test Write tests
-  ↓
-Prompt (ck-test.prompt.md) + Agent (tester.agent.md)
-  ↓
-Output: Test coverage
-```
-
-### Pattern 3: Code Review
-
-```
-User: /ck-review-codebase My auth changes
-  ↓
-Prompt (ck-review-codebase.prompt.md)
-  ↓
-Agent (code-reviewer.agent.md)
-  ↓
-Skills: ck-code-review, ck-development
-  ↓
-Output: Quality gates, security issues, improvements
-```
-
----
-
-## Best Practices
-
-### 1. Workflow Chaining
-
-CoKit supports manual chaining (Copilot is stateless):
-
-```
-/ck-plan feature  →  /ck-code step1  →  /ck-test  →  /ck-review-codebase
-```
-
-### 2. Context Management
-
-Without `$ARGUMENTS`, provide context in chat:
-
-```
-DON'T:
-/ck-fix $ARGUMENTS
-
-DO:
-/ck-fix The login endpoint returns 401 for valid credentials in auth.ts
-```
-
-### 3. Instructions Auto-Apply
-
-Add `.github/instructions/` files to auto-guide specific file types:
-
-```yaml
-# .github/instructions/ck-custom-backend.instructions.md
----
-applyTo: '**/*.service.ts'
----
-
-When editing service files:
-- Implement dependency injection
-- Use async/await patterns
-```
-
-### 4. Collections for Teams
-
-Use collections to bundle workflows for team consistency:
-
-```bash
-# Install specific collection
-# Users select ck-core for full-stack development
-# Automatic setup of related prompts, agents, skills
-```
-
-### 5. Skill Activation
-
-Skills auto-activate based on task context:
-
-- Editing `.tsx` files → `ck-frontend-development` activates
-- Running tests → `ck-testing` instruction applies
-- Debugging → `ck-debugging` skill loads
-
----
-
-## Troubleshooting
-
-| Issue | Solution |
-|-------|----------|
-| Prompts not appearing | Run `npx cokit-cli list` to verify installation |
-| Instructions not applying | Check `applyTo` glob pattern matches your files |
-| Skills not activating | Verify skill SKILL.md frontmatter is correct |
-| Commands show help instead of running | Use `/ck-prompt-name` (with `ck-` prefix) |
-
----
-
-## Resources
-
-- **Root README:** [CoKit Repository](../README.md)
-- **Team Presentation:** [cokit-team-presentation.md](./cokit-team-presentation.md)
-- **Processing Flow:** [copilot-processing-flow.md](./copilot-processing-flow.md)
-- **Migration Guide:** [migration-guide.md](./migration-guide.md)
-- **Roadmap:** [project-roadmap.md](./project-roadmap.md)