cokit-cli 1.0.7 → 1.0.9

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

@@ -1,937 +1,374 @@
-# CoKit: Comprehensive Claude Code → GitHub Copilot Mapping Guide
-
-**Version:** 1.0.0
-**Date:** 2026-01-06
-**Purpose:** Complete reference for porting Claude Code patterns to GitHub Copilot
-
----
-
-## Table of Contents
-
-1. [Executive Summary](#1-executive-summary)
-2. [Terminology Glossary](#2-terminology-glossary)
-3. [Detailed Feature Mapping](#3-detailed-feature-mapping)
-4. [Installation Levels](#4-installation-levels)
-5. [Workflow Patterns](#5-workflow-patterns)
-6. [File Format Specifications](#6-file-format-specifications)
-7. [Migration Guide](#7-migration-guide)
-
----
-
-## 1. Executive Summary
-
-### What is Claude Code?
-
-Claude Code is Anthropic's CLI tool for AI-assisted software development. It features:
-- **Hooks system** for runtime event handling
-- **Multi-agent architecture** with specialized subagents
-- **Skills** as modular capability packages
-- **Commands** as user-invokable shortcuts
-- **Session state** tracking (todos, active plans)
-
-### What is GitHub Copilot (2025)?
-
-GitHub Copilot evolved from autocomplete to an AI agent:
-- **Agent Mode** (Feb 2025): Autonomous coding tasks
-- **Custom Instructions** (Aug 2025): Repository-level guidance
-- **AGENTS.md** (Aug 2025): Agent-specific instructions
-- **Agent Skills** (Dec 2025): Modular capability packages
-- **Prompt Files**: Reusable task templates
-
-### Key Architectural Difference
-
-| Aspect | Claude Code | GitHub Copilot |
-|--------|-------------|----------------|
-| Execution | CLI + Runtime hooks | IDE-embedded, static config |
-| Agent model | Multi-agent delegation | Single agent context |
-| State | Session state tracking | Stateless |
-| Customization | Dynamic (hooks inject context) | Static (files read at start) |
-
----
-
-## 2. Terminology Glossary
-
-### Claude Code Terms
-
-#### CLAUDE.md
-**What:** Root configuration file that Claude Code reads for project/user instructions.
-**Location:** `~/.claude/CLAUDE.md` (user) or `./CLAUDE.md` (project)
-**Purpose:** Define role, responsibilities, workflow references, documentation standards.
-**Format:** Markdown with natural language instructions.
-
-#### Skills
-**What:** Modular capability packages containing instructions + supporting resources.
-**Location:** `~/.claude/skills/{skill-name}/`
-**Structure:**
-```
-skills/debugging/
-├── SKILL.md          # Main instructions with YAML frontmatter
-├── references/       # Supporting documentation
-└── scripts/          # Helper scripts (bash, python, etc.)
-```
-**Activation:** Claude automatically loads relevant skills based on task context.
-
-#### Agents (Subagents)
-**What:** Specialized AI personas for specific tasks (planner, tester, reviewer).
-**Location:** `~/.claude/agents/{agent-name}.md`
-**Purpose:** Define behavior, tools, and constraints for delegated tasks.
-**Invocation:** Main agent delegates via `Task` tool: "Use planner agent to..."
-
-#### Commands
-**What:** User-invokable shortcuts that expand into full prompts.
-**Location:** `~/.claude/commands/{namespace}/{command}.md`
-**Invocation:** User types `/fix` → expands to full fix workflow prompt.
-**Features:** Support `$ARGUMENTS` variable, can chain to sub-commands.
-
-#### Workflows
-**What:** Process documentation defining how agents should work together.
-**Location:** `~/.claude/workflows/{workflow-name}.md`
-**Purpose:** Define step-by-step processes (implementation, testing, review).
-
-#### Hooks
-**What:** Shell commands executed at specific runtime events.
-**Location:** `~/.claude/settings.json` → `hooks` section
-**Events:**
-- `SessionStart` - When session begins
-- `UserPromptSubmit` - Before processing each user message
-- `PreToolUse` - Before executing a tool
-- `PreCompact` - Before context compaction
-- `SessionEnd` - When session ends
-
-**Example:**
-```json
-{
-  "hooks": {
-    "UserPromptSubmit": [{
-      "hooks": [{
-        "type": "command",
-        "command": "node ~/.claude/hooks/dev-rules-reminder.cjs"
-      }]
-    }]
-  }
-}
-```
-
-#### StatusLine
-**What:** Real-time status display in terminal showing session state.
-**Purpose:** Display active plan, todos, token usage, etc.
-
----
-
-### GitHub Copilot Terms
-
-#### copilot-instructions.md
-**What:** Repository-wide instructions that apply to all Copilot interactions.
-**Location:** `.github/copilot-instructions.md`
-**Purpose:** Define coding standards, project context, preferences.
-**Format:** Markdown (natural language instructions).
-**Source:** [GitHub Docs - Custom Instructions](https://docs.github.com/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot)
-
-#### Instructions Files (*.instructions.md)
-**What:** Path-specific instructions applied based on file patterns.
-**Location:** `.github/instructions/{name}.instructions.md`
-**Purpose:** Different rules for different file types (frontend vs backend).
-**Format:** Markdown with YAML frontmatter containing `applyTo` glob.
-
-**Example:**
-```yaml
----
-applyTo: "**/*.tsx,**/*.jsx"
----
-# React Component Guidelines
-- Use functional components with hooks
-- Prefer composition over inheritance
-```
-
-**Source:** [VS Code Custom Instructions](https://code.visualstudio.com/docs/copilot/customization/custom-instructions)
-
-#### AGENTS.md
-**What:** Agent-specific instructions for Copilot coding agent.
-**Location:** `./AGENTS.md` (root) or nested in subdirectories
-**Purpose:** Guide agent behavior for autonomous coding tasks.
-**Precedence:** Nearest AGENTS.md in directory tree takes precedence.
-**Source:** [GitHub Changelog - AGENTS.md](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/)
-
-#### Agent Skills
-**What:** Modular capability packages (equivalent to Claude Code skills).
-**Location:**
-- `.github/skills/{skill-name}/` (repository)
-- `~/.copilot/skills/{skill-name}/` (user-level)
-
-**Structure:**
-```
-skills/debugging/
-├── SKILL.md          # Instructions with YAML frontmatter
-├── references/       # Supporting docs
-└── scripts/          # Helper scripts
-```
-
-**Source:** [GitHub Copilot Agent Skills](https://github.blog/changelog/2025-12-18-github-copilot-now-supports-agent-skills/)
-
-#### Prompt Files (*.prompt.md)
-**What:** Reusable task-specific prompts (equivalent to Claude Code commands).
-**Location:** `.github/prompts/{name}.prompt.md`
-**Purpose:** Standardized prompts for common tasks.
-**Format:** Markdown with YAML frontmatter using `mode: agent` format.
-
-**Available Prompts (Phase 4):**
-- `fix.prompt.md` - Debug and fix code issues
-- `plan.prompt.md` - Create implementation plans
-- `code.prompt.md` - Implement from existing plans
-- `test.prompt.md` - Run tests and analyze results
-- `review.prompt.md` - Review code for quality issues
-- `docs.prompt.md` - Update project documentation
-
-**Example:**
-```yaml
----
-mode: agent
-description: Fix code issues intelligently
----
-Analyze the issue and provide a fix following project standards.
-```
-
-**Source:** [VS Code Prompt Files](https://code.visualstudio.com/docs/copilot/customization/prompt-files)
-
-#### Agent Mode
-**What:** Copilot operating autonomously on multi-step coding tasks.
-**Capabilities:** Read files, propose edits, run commands, monitor tests.
-**Trigger:** Enable in VS Code settings or use specific prompts.
-**Source:** [Introducing Copilot Agent Mode](https://code.visualstudio.com/blogs/2025/02/24/introducing-copilot-agent-mode)
-
----
-
-## 3. Detailed Feature Mapping
-
-### 3.1 CLAUDE.md → copilot-instructions.md
-
-| Aspect | Detail |
-|--------|--------|
-| **Claude Code** | `~/.claude/CLAUDE.md` or `./CLAUDE.md` |
-| **Copilot** | `.github/copilot-instructions.md` |
-| **Why this mapping** | Both serve as root configuration defining project-wide instructions. Both are Markdown files read at session start. |
-| **Evidence** | GitHub Docs: "Create a file named `.github/copilot-instructions.md`... Add natural language instructions to the file, in Markdown format." |
-| **Source** | [GitHub Docs](https://docs.github.com/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot) |
-| **Best Practices** | Keep concise (<2000 tokens). Focus on project-specific guidance. Reference other files rather than duplicating content. |
-| **Key Differences** | Claude Code supports `$HOME` variables and file references. Copilot is static - no variable expansion. |
-
-**Migration Example:**
-
-```markdown
-# Claude Code (CLAUDE.md)
-Your role is to analyze requirements...
-## Workflows
-- Primary workflow: `$HOME/.claude/workflows/primary-workflow.md`
-- Development rules: `$HOME/.claude/workflows/development-rules.md`
-
-# Copilot (copilot-instructions.md)
-Your role is to analyze requirements...
-## Workflows
-Follow these development rules:
-- YAGNI, KISS, DRY principles
-- Read ./docs/code-standards.md before implementation
-- Keep files under 200 lines
-```
-
----
-
-### 3.2 Skills → Agent Skills
-
-| Aspect | Detail |
-|--------|--------|
-| **Claude Code** | `~/.claude/skills/{name}/SKILL.md` |
-| **Copilot** | `.github/skills/{name}/SKILL.md` or `~/.copilot/skills/{name}/SKILL.md` |
-| **Why this mapping** | Identical concept - modular capability packages. Same file structure (SKILL.md + resources). Copilot explicitly adopted this pattern. |
-| **Evidence** | GitHub Changelog: "Agent Skills are folders containing instructions, scripts, and resources that Copilot automatically loads when relevant." |
-| **Source** | [GitHub Agent Skills](https://github.blog/changelog/2025-12-18-github-copilot-now-supports-agent-skills/) |
-| **Best Practices** | One skill per capability. Include concrete examples. Reference scripts with relative paths. Keep SKILL.md focused, details in references/. |
-| **Key Differences** | Claude Code: `version`, `languages` fields in frontmatter. Copilot: Only `name`, `description` required. Claude Code skills can invoke tools; Copilot skills are advisory. |
-
-**SKILL.md Format Comparison:**
-
-```yaml
-# Claude Code SKILL.md
----
-name: debugging
-description: Systematic debugging framework...
-version: 3.0.0
-languages: all
----
-
-# Copilot SKILL.md
----
-name: debugging
-description: Systematic debugging framework...
----
-```
-
----
-
-### 3.3 Agents → AGENTS.md
-
-| Aspect | Detail |
-|--------|--------|
-| **Claude Code** | `~/.claude/agents/{name}.md` (multiple files, each a specialized agent) |
-| **Copilot** | `./AGENTS.md` (single file or nested files) |
-| **Why this mapping** | Both define agent behavior and constraints. AGENTS.md is Copilot's designated file for agent instructions. |
-| **Evidence** | GitHub Changelog: "You can create a single AGENTS.md file in the root of your repository, or create nested AGENTS.md files which apply to specific parts of your project." |
-| **Source** | [AGENTS.md Support](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/) |
-| **Best Practices** | Merge agent behaviors into sections. Use headers for different task types. Keep actionable, not philosophical. |
-| **Key Differences** | **Critical:** Claude Code delegates to separate agents with isolated context. Copilot has ONE agent that follows guidelines. No delegation possible. |
-
-**Migration Strategy:**
-
-```markdown
-# Claude Code (separate files)
-# agents/planner.md
----
-name: planner
-description: Create implementation plans...
-model: opus
----
-You are an expert planner...
-
-# agents/tester.md
----
-name: tester
-description: Run and analyze tests...
----
-You are a testing expert...
-
-# Copilot (merged AGENTS.md)
-# AGENTS.md
-
-## When Planning
-- Research before proposing solutions
-- Create plans in ./plans directory
-- Use decomposition and working backwards
-
-## When Testing
-- Write comprehensive unit tests
-- Don't use mocks to fake passing tests
-- All tests must pass before completion
-
-## When Reviewing
-- Check security vulnerabilities
-- Verify error handling
-- Ensure test coverage
-```
-
----
-
-### 3.4 Commands → Prompt Files
-
-| Aspect | Detail |
-|--------|--------|
-| **Claude Code** | `~/.claude/commands/{namespace}/{name}.md` |
-| **Copilot** | `.github/prompts/{name}.prompt.md` |
-| **Why this mapping** | Both are user-invokable shortcuts expanding to full prompts. Same purpose, similar structure. |
-| **Evidence** | VS Code Docs: "Prompt files are Markdown files and use the `.prompt.md` extension... stored in the `.github/prompts` folder." |
-| **Source** | [VS Code Prompt Files](https://code.visualstudio.com/docs/copilot/customization/prompt-files) |
-| **Best Practices** | Use `mode: agent` for multi-step tasks. Keep focused on one task type. Include examples of expected input/output. |
-| **Key Differences** | Claude Code: `$ARGUMENTS` variable, sub-command routing (`/fix:types`). Copilot: No variables, flat structure. User provides context in chat. |
-
-**Migration Example:**
-
-```markdown
-# Claude Code (commands/ck/fix.md)
----
-description: Analyze and fix issues [INTELLIGENT ROUTING]
-argument-hint: [issues]
----
-Analyze issues: <issues>$ARGUMENTS</issues>
-
-## Decision Tree
-**Type Errors** → `/fix:types`
-**UI Issues** → `/fix:ui`
-
-# Copilot (prompts/fix.prompt.md)
----
-mode: agent
-description: Analyze and fix code issues
----
-Analyze the described issue and fix it.
-
-## Process
-1. Identify issue type (type errors, UI, tests, CI/CD)
-2. Search relevant files
-3. Analyze root cause
-4. Apply minimal fix
-5. Verify fix works
-```
-
----
-
-### 3.5 Workflows → Instructions Files
-
-| Aspect | Detail |
-|--------|--------|
-| **Claude Code** | `~/.claude/workflows/{name}.md` |
-| **Copilot** | `.github/instructions/{name}.instructions.md` |
-| **Why this mapping** | Both define process rules. Instructions files can be path-specific, making them suitable for workflow rules that apply to certain contexts. |
-| **Evidence** | VS Code Docs: "Create multiple .instructions.md files that apply to specific file types or tasks." |
-| **Source** | [VS Code Custom Instructions](https://code.visualstudio.com/docs/copilot/customization/custom-instructions) |
-| **Best Practices** | Use `applyTo` to scope rules. Split by concern (frontend, backend, testing). Keep actionable. |
-| **Key Differences** | Claude Code workflows are referenced dynamically. Copilot instructions are static, applied based on file pattern match. |
-
-**Migration Example:**
-
-```yaml
-# Claude Code (workflows/development-rules.md)
-# Development Rules
-- File Naming: Use kebab-case
-- File Size: Keep under 200 lines
-- Use `code-reviewer` agent after implementation
-
-# Copilot (instructions/development.instructions.md)
----
-applyTo: "**/*"
----
-# Development Rules
-- File Naming: Use kebab-case
-- File Size: Keep under 200 lines
-- Review code for security before committing
-```
-
----
-
-### 3.6 Hooks → No Equivalent
-
-| Aspect | Detail |
-|--------|--------|
-| **Claude Code** | `settings.json` → `hooks` section |
-| **Copilot** | **No equivalent** |
-| **Why no mapping** | Copilot has no runtime hook system. It reads static files, not event-driven execution. |
-| **Evidence** | Extensive search of Copilot docs reveals no hook/event system. |
-| **Source** | N/A |
-| **Best Practices** | Include all context in static files. Accept manual workflow. Consider GitHub Actions for CI-level automation. |
-| **Key Differences** | Claude Code can inject context dynamically per-prompt. Copilot cannot. This is the biggest architectural gap. |
-
-**Workaround Strategy:**
-
-| Hook Event | Copilot Alternative |
-|------------|---------------------|
-| `SessionStart` | Include all context in copilot-instructions.md |
-| `UserPromptSubmit` | Use prompt files, manually invoke |
-| `PreToolUse` | Include warnings in instructions |
-| `PreCompact` | N/A - Copilot handles context differently |
-| `SessionEnd` | GitHub Actions for cleanup |
-
----
-
-### 3.7 Multi-Agent Delegation → No Equivalent
-
-| Aspect | Detail |
-|--------|--------|
-| **Claude Code** | Main agent delegates to subagents via `Task` tool |
-| **Copilot** | **No equivalent** - single agent only |
-| **Why no mapping** | Copilot architecture is single-agent. No subagent spawning capability. |
-| **Evidence** | Copilot Agent Mode docs describe one agent doing multi-step tasks, not delegating to other agents. |
-| **Source** | [Agent Mode](https://code.visualstudio.com/blogs/2025/02/24/introducing-copilot-agent-mode) |
-| **Best Practices** | Merge agent behaviors into AGENTS.md sections. User manually switches "modes" via different prompts. |
-| **Key Differences** | Claude Code: Orchestration pattern (main → subagent → report back). Copilot: Single agent follows all guidelines. |
-
-**Workaround: Prompt Chaining**
-
-```
-# Instead of automatic delegation:
-User → "Plan this feature" → Uses /plan prompt
-User → "Now implement it" → Uses /code prompt
-User → "Now test it" → Uses /test prompt
-User → "Now review it" → Uses /review prompt
-```
-
----
-
-### 3.8 Session State → No Equivalent
-
-| Aspect | Detail |
-|--------|--------|
-| **Claude Code** | Tracks todos, active plans, session variables |
-| **Copilot** | **No equivalent** - stateless |
-| **Why no mapping** | Copilot doesn't persist state between interactions. Each request is independent. |
-| **Evidence** | No documentation of session state management in Copilot. |
-| **Best Practices** | Manual tracking in files (plan.md, TODO.md). Reference state explicitly in prompts. |
-| **Key Differences** | Claude Code maintains context across interactions. Copilot starts fresh (though has conversation history in chat). |
-
----
-
-## 4. Installation Levels
-
-CoKit supports two installation levels. Users can choose one or both.
-
-### 4.1 Repository Level (Project-Specific)
-
-**What:** Install CoKit templates into a specific project's `.github/` folder.
-
-**When to use:**
-- Project has specific requirements
-- Team collaboration (everyone gets same config)
-- Version control of AI instructions
-
-**Structure (Phase 4):**
-```
-your-project/
-├── .github/
-│   ├── copilot-instructions.md    # Project instructions
-│   ├── AGENTS.md                   # Agent guidelines
-│   ├── instructions/
-│   │   ├── frontend.instructions.md
-│   │   ├── backend.instructions.md
-│   │   └── testing.instructions.md
-│   ├── prompts/
-│   │   ├── fix.prompt.md           # Debug and fix issues
-│   │   ├── plan.prompt.md          # Create implementation plans
-│   │   ├── code.prompt.md          # Implement from plans
-│   │   ├── test.prompt.md          # Run and analyze tests
-│   │   ├── review.prompt.md        # Code review
-│   │   └── docs.prompt.md          # Update documentation
-│   └── skills/
-│       ├── debugging/
-│       ├── code-review/
-│       ├── planning/
-│       ├── docs-seeker/
-│       └── sequential-thinking/
-└── docs/
-    ├── code-standards.md
-    └── system-architecture.md
-```
-
-**Installation:**
-```bash
-# From project root
-curl -fsSL https://raw.githubusercontent.com/camping89/cokit/main/install.sh | bash -s -- --level=repo
-```
-
----
-
-### 4.2 User Level (Cross-Project)
-
-**What:** Install CoKit skills to `~/.copilot/skills/` for use across all projects.
-
-**When to use:**
-- Personal productivity skills (debugging, planning)
-- Skills not project-specific
-- Share skills across multiple projects
-
-**Phase 3 Status:** All 5 core skills now available following Copilot Agent Skills format.
-
-**Structure:**
-```
-~/.copilot/
-└── skills/
-    ├── debugging/
-    │   ├── SKILL.md
-    │   ├── references/
-    │   │   ├── systematic-debugging.md
-    │   │   ├── root-cause-tracing.md
-    │   │   └── verification.md
-    │   └── scripts/
-    ├── code-review/
-    │   ├── SKILL.md
-    │   └── references/
-    │       ├── code-review-reception.md
-    │       └── verification-before-completion.md
-    ├── planning/
-    │   ├── SKILL.md
-    │   └── references/
-    │       ├── research-phase.md
-    │       ├── solution-design.md
-    │       └── plan-organization.md
-    ├── docs-seeker/
-    │   ├── SKILL.md
-    │   └── references/
-    │       ├── search-patterns.md
-    │       └── source-evaluation.md
-    └── sequential-thinking/
-        ├── SKILL.md
-        └── references/
-            ├── core-patterns.md
-            └── advanced-techniques.md
-```
-
-**Installation:**
-```bash
-# Install to user directory
-curl -fsSL https://raw.githubusercontent.com/camping89/cokit/main/install.sh | bash -s -- --level=user
-```
-
----
-
-### 4.3 Both Levels
-
-**When to use:**
-- User skills for personal productivity
-- Repo templates for project-specific guidance
-
-**Installation:**
-```bash
-# Install both
-curl -fsSL https://raw.githubusercontent.com/camping89/cokit/main/install.sh | bash -s -- --level=all
-```
-
----
-
-### 4.4 Installation Comparison
-
-| Aspect | Repo Level | User Level |
-|--------|-----------|------------|
-| Location | `.github/` | `~/.copilot/` |
-| Scope | Single project | All projects |
-| Version controlled | Yes | No (personal) |
-| Team sharing | Yes | No |
-| Portability | With project | With user |
-| Contains | Instructions, 6 prompts (Phase 4), skills | 5 core skills (Phase 3) |
-| Prompts | fix, plan, code, test, review, docs (Phase 4) | Not included (repo-level only) |
-| Skills available | debugging, code-review, planning, docs-seeker, sequential-thinking | Same as repo level |
-| References | Each skill includes 2-3 reference docs | Each skill includes 2-3 reference docs |
-
----
-
-## 5. Workflow Patterns
-
-Since Copilot lacks hooks, workflows are more manual. This section defines patterns for daily development.
-
-### 5.1 Why No Hooks Matters
-
-**Claude Code with hooks:**
-```
-User types message
-  → UserPromptSubmit hook injects dev-rules reminder
-  → Agent processes with injected context
-  → PreToolUse hook validates tool calls
-  → Agent completes task with guardrails
-```
-
-**Copilot without hooks:**
-```
-User types message
-  → Copilot reads static instruction files
-  → Agent processes (no dynamic injection)
-  → Agent completes task
-```
-
-**Impact:** You must include ALL context in static files or prompts. No dynamic reminders.
-
----
-
-### 5.2 Daily Development Workflow
-
-#### Morning Setup
-
-```
-1. Open project in VS Code
-2. Review plan.md for today's tasks (if exists)
-3. Optionally run /plan prompt to create daily plan
-
-Example prompt: "Review the codebase and create a plan for implementing [feature]"
-```
-
-#### Feature Development
-
-```
-1. Start with /plan prompt
-   "I need to implement [feature]. Create an implementation plan."
-
-2. Work on implementation
-   - Copilot assists with code completion
-   - Reference docs/code-standards.md periodically
-
-3. When stuck, use /fix prompt
-   "I'm getting this error: [error]. Help me debug."
-
-4. Before committing, use /review prompt
-   "Review the changes in [files] for issues."
-```
-
-#### Debugging Flow
-
-```
-1. Use /debug prompt or invoke debugging skill
-   "I have a bug where [description]. Help me debug systematically."
-
-2. Copilot will (guided by debugging skill):
-   - Ask for error messages
-   - Search relevant files
-   - Trace root cause
-   - Propose fix
-
-3. Verify fix manually
-   - Run tests
-   - Check behavior
-```
-
-#### Code Review Flow
-
-```
-1. Before PR, use /review prompt
-   "Review all changes in this branch for security, performance, and best practices."
-
-2. Address feedback
-
-3. Run tests
-
-4. Create PR
-```
-
----
-
-### 5.3 Prompt Chaining (Simulating Multi-Agent)
-
-Claude Code automatically delegates. With Copilot, chain prompts manually:
-
-```
-# Planning Phase
-You: "/plan Implement user authentication"
-Copilot: Returns implementation plan
-
-# Implementation Phase
-You: "/code Implement step 1 from the plan: [paste step]"
-Copilot: Implements code
-
-# Testing Phase
-You: "/test Write tests for the authentication module"
-Copilot: Writes tests
-
-# Review Phase
-You: "/review Review the authentication implementation"
-Copilot: Reviews and suggests improvements
-```
-
----
-
-### 5.4 Context Management
-
-Without hooks, manage context manually:
-
-**Start of session:**
-```
-"I'm working on [project]. Key files are:
-- docs/code-standards.md (coding rules)
-- docs/system-architecture.md (architecture)
-- Current task: [description]"
-```
-
-**When context gets stale:**
-```
-"Let me re-establish context:
-- Project: [name]
-- Current task: [description]
-- Files changed: [list]
-- Current issue: [problem]"
-```
-
----
-
-### 5.5 Workflow Comparison
-
-| Task | Claude Code | Copilot + CoKit |
-|------|-------------|-----------------|
-| Start session | Hooks auto-inject context | User provides context or uses /plan |
-| Plan feature | `/plan` → Delegates to planner agent | `/plan` prompt → Manual follow-up |
-| Implement | Agent follows workflow, delegates testing | Implement, manually run /test |
-| Debug | `/fix` → Auto-routes to specialized handler | `/fix` or `/debug` prompt |
-| Review | Automatic after implementation | Manual `/review` prompt |
-| Commit | `/commit` → git-manager agent | Manual git operations |
-
----
-
-### 5.6 Available Prompt Files (Phase 4)
-
-6 prompt files for common workflows, all using `mode: agent` format:
-
-| Prompt | Purpose | When to Use | File |
-|--------|---------|-------------|------|
-| `/plan` | Create implementation plan | Starting new feature | plan.prompt.md |
-| `/code` | Implement from plan | During development | code.prompt.md |
-| `/fix` | Debug and fix issues | When encountering bugs | fix.prompt.md |
-| `/review` | Code review | Before committing | review.prompt.md |
-| `/test` | Write/run tests | After implementation | test.prompt.md |
-| `/docs` | Update documentation | After feature complete | docs.prompt.md |
-
----
-
-## 6. File Format Specifications
-
-### 6.1 copilot-instructions.md
-
-```markdown
-# Project Instructions
-
-Brief project description and context.
-
-## Coding Standards
-- List key standards
-- Reference ./docs/code-standards.md for details
-
-## Architecture
-- High-level architecture notes
-- Reference ./docs/system-architecture.md
-
-## Preferences
-- Preferred patterns
-- Things to avoid
-```
-
-**Max recommended size:** ~2000 tokens
-
----
-
-### 6.2 *.instructions.md
-
-```yaml
----
-applyTo: "glob-pattern"           # Required: e.g., "**/*.ts"
-excludeAgent: "coding-agent"      # Optional: exclude from specific agent
----
-
-# Instructions Title
-
-Instructions content in Markdown.
-```
-
----
-
-### 6.3 AGENTS.md
-
-```markdown
-# Agent Guidelines
-
-## General Behavior
-- Overall guidelines
-
-## When [Task Type]
-- Specific guidelines for this task type
-
-## When [Another Task Type]
-- Guidelines for another task type
-```
-
----
-
-### 6.4 *.prompt.md
-
-```yaml
----
-mode: agent                       # Optional: "agent" for multi-step tasks
-description: Brief description    # Optional: shown in prompt picker
----
-
-Prompt content in Markdown.
-
-## Context
-What context to gather.
-
-## Process
-1. Step one
-2. Step two
-
-## Output
-Expected output format.
-```
-
----
-
-### 6.5 SKILL.md
-
-```yaml
----
-name: skill-name                  # Required: lowercase, hyphens
-description: What and when        # Required: max 1024 chars
----
-
-# Skill Name
-
-## When to Use
-- Trigger conditions
-
-## Instructions
-Detailed instructions.
-
-## References
-- [Doc name](./references/doc.md)
-
-## Scripts
-- [Script name](./scripts/script.sh)
-```
-
----
-
-## 7. Migration Guide
-
-### Step 1: Inventory Current Setup
-
-List your Claude Code customizations:
-```bash
-ls ~/.claude/skills/
-ls ~/.claude/commands/
-ls ~/.claude/agents/
-ls ~/.claude/workflows/
-```
-
-### Step 2: Prioritize
-
-Decide what to migrate:
-1. **Must have:** Skills you use daily
-2. **Nice to have:** Occasionally used commands
-3. **Skip:** Claude-specific features (hooks, multi-agent)
-
-### Step 3: Convert Files
-
-For each category:
-
-| Source | Target | Conversion |
-|--------|--------|------------|
-| CLAUDE.md | copilot-instructions.md | Remove $HOME refs, inline workflow content |
-| skills/ | .github/skills/ or ~/.copilot/skills/ | Copy, remove unsupported frontmatter fields |
-| agents/ | AGENTS.md | Merge into sections |
-| commands/ | .github/prompts/ | Remove $ARGUMENTS, flatten structure |
-| workflows/ | .github/instructions/ | Add applyTo frontmatter |
-
-### Step 4: Test
-
-1. Open project in VS Code
-2. Enable Copilot
-3. Test each prompt file
-4. Verify skills are discovered
-5. Adjust based on behavior
-
-### Step 5: Iterate
-
-Copilot behavior differs from Claude Code. Expect to:
-- Reword instructions for clarity
-- Add more explicit guidance
-- Simplify complex workflows
-
----
-
-## Appendix: Quick Reference
-
-### File Locations
-
-| Purpose | Claude Code | Copilot |
-|---------|-------------|---------|
-| Global instructions | ~/.claude/CLAUDE.md | .github/copilot-instructions.md |
-| Agent guidelines | ~/.claude/agents/*.md | .github/agents.md |
-| Skills (repo) | N/A | .github/skills/ |
-| Skills (user) | ~/.claude/skills/ | ~/.copilot/skills/ |
-| Commands/Prompts | ~/.claude/commands/ | .github/prompts/ |
-| Path instructions | ~/.claude/workflows/ | .github/instructions/ |
-
-### Frontmatter Fields
-
-| Field | instructions.md | prompt.md | SKILL.md |
-|-------|-----------------|-----------|----------|
-| applyTo | Required | N/A | N/A |
-| excludeAgent | Optional | N/A | N/A |
-| mode | N/A | Optional | N/A |
-| description | N/A | Optional | Required |
-| name | N/A | N/A | Required |
-
----
-
-**Document Location:** `docs/cokit-comprehensive-mapping-guide.md`
-
-**Related Files:**
-- `plans/reports/brainstorm-260106-1029-cokit-claude-to-copilot-mapping.md` - Initial analysis
-- `https://github.com/camping89/cokit` - Project repository
+# CoKit: Comprehensive Guide
+
+Complete reference for CoKit GitHub Copilot resource toolkit.
+
+**Version:** 1.0.9
+**Date:** 2026-01-20
+
+---
+
+## 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:
+
+- **9 Specialized Agents** - Planner, code-reviewer, debugger, tester, researcher, scout, git-manager, brainstormer, docs-manager
+- **14 Prompt Templates** - Reusable workflows with `ck-` prefix (`/ck-fix`, `/ck-plan`, `/ck-cook`, etc.)
+- **7 Skill Packages** - Deep expertise in debugging, code-review, planning, problem-solving, sequential-thinking, backend, frontend
+- **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
+npx cokit-cli init -g       # Global resources only
+npx cokit-cli init -a       # Both project and global
+```
+
+---
+
+## 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 (14 total):**
+
+| Category | Prompts |
+|----------|---------|
+| Core Debugging | `/ck-fix` (debug & fix), `/ck-debug` (debug issues) |
+| Planning & Design | `/ck-plan` (create plans), `/ck-brainstorm` (ideate) |
+| Implementation | `/ck-code` (implement), `/ck-cook` (feature implementation) |
+| Project Setup | `/ck-bootstrap` (new project) |
+| Quality Assurance | `/ck-test` (write/run tests), `/ck-review-codebase` (code analysis) |
+| Utilities | `/ck-scout` (find files), `/ck-ask` (Q&A), `/ck-git` (git workflows), `/ck-docs` (docs), `/ck-ck-help` (help) |
+
+**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 (9 total):**
+
+| Agent | Specialization | Used By |
+|-------|---|---|
+| **planner** | Creates implementation plans from requirements | /ck-plan, /ck-bootstrap |
+| **code-reviewer** | Comprehensive code review and quality gates | /ck-review-codebase |
+| **debugger** | Investigates issues, diagnoses root causes | /ck-fix, /ck-debug |
+| **tester** | Writes tests, validates implementation | /ck-test |
+| **researcher** | Technology research, finds documentation | /ck-ask, /ck-scout |
+| **scout** | Locates files in codebase by purpose | /ck-scout |
+| **git-manager** | Handles commits, pushes, merges, PRs | /ck-git |
+| **brainstormer** | Solution ideation, architecture discussion | /ck-brainstorm |
+| **docs-manager** | Creates and updates documentation | /ck-docs |
+
+### 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 (7 total):**
+
+| Skill | Expertise |
+|-------|-----------|
+| **ck-debugging** | Systematic root cause analysis, not random fixes |
+| **ck-code-review** | Verification gates, technical rigor, feedback protocols |
+| **ck-planning** | Research → design → implementation workflow |
+| **ck-problem-solving** | Complexity spirals, innovation blocks, systematic solutions |
+| **ck-sequential-thinking** | Multi-step problem solving with revision capability |
+| **ck-backend-development** | Backend frameworks (Express, Django, FastAPI, etc.) |
+| **ck-frontend-development** | Frontend frameworks (React, Vue, Svelte, etc.) |
+
+### 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 -a
+```
+
+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 init -g` | Install personal skills only |
+| `npx cokit-cli init -a` | Install both project and personal |
+| `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)