cokit-cli 1.0.9 → 1.2.0

package/docs/copilot-processing-flow.md

@@ -1,212 +1,215 @@
-# Copilot Processing Flow
-
-How Copilot processes user input through CoKit resources to produce output.
-
-> **CoKit Resources:** See [README.md](../README.md) for complete resource listing.
-
----
-
-## CoKit Resource Types Overview
-
-| Resource | Trigger | Purpose | File |
-|----------|---------|---------|------|
-| **Prompt** | User calls `/ck-prompt-name` | Workflow/task template | `prompts/ck-*.prompt.md` |
-| **Agent** | Referenced by prompt | Execute specific tasks | `agents/*.agent.md` |
-| **Instruction** | Auto (by file pattern) | Coding rules/standards | `instructions/ck-*.instructions.md` |
-| **Skill** | Auto by context | Specialized knowledge | `skills/ck-*/SKILL.md` |
-| **Collection** | User selects | Bundle related resources | `collections/ck-*.collection.yml` |
-
-### CoKit Examples
-
-**Prompts:** `/ck-fix`, `/ck-plan`, `/ck-code`, `/ck-cook`, `/ck-test`, `/ck-review-codebase`, `/ck-docs`, `/ck-bootstrap`, `/ck-brainstorm`, `/ck-debug`, `/ck-scout`, `/ck-ask`, `/ck-git`, `/ck-ck-help`
-
-**Agents:** planner, code-reviewer, debugger, tester, researcher, scout, git-manager, brainstormer, docs-manager
-
-**Skills:** ck-debugging, ck-code-review, ck-planning, ck-problem-solving, ck-sequential-thinking, ck-backend-development, ck-frontend-development
-
-**Instructions:** ck-backend, ck-frontend, ck-testing, ck-development, ck-research
-
-**Collections:** ck-core, ck-development-rules, ck-documentation, ck-git-workflow, ck-orchestration
-
----
-
-## Component Details
-
-### 1. Prompt (`prompts/ck-*.prompt.md`)
-
-**Role:** Entry point - Defines workflow/task
-
-**Example: ck-fix.prompt.md**
-```yaml
----
-mode: agent
-description: 'Debug and fix issues systematically'
----
-
-# Fix Issues
-
-You are debugging an issue. Follow systematic troubleshooting...
-
-1. Read the error message
-2. Search for root cause
-3. Implement fix
-4. Test the solution
-```
-
-**CoKit Examples:**
-- `/ck-fix` - Debug and fix
-- `/ck-plan` - Create implementation plan
-- `/ck-cook` - Step-by-step feature implementation
-- `/ck-review-codebase` - Scan and analyze code
-
-**When to use:** User wants to execute a specific workflow
-
----
-
-### 2. Agent (`agents/*.agent.md`)
-
-**Role:** Executor - Specialized persona for specific tasks
-
-**Example: planner.agent.md**
-```yaml
----
-description: 'Research, analyze, and create implementation plans'
----
-
-# Planner Agent
-
-You are a research-first planner...
-- Conduct comprehensive research
-- Design system architecture
-- Create detailed implementation plans
-```
-
-**CoKit Agents:**
-- `planner` - Creates implementation plans
-- `code-reviewer` - Provides comprehensive code review
-- `debugger` - Investigates and diagnoses issues
-- `tester` - Writes and validates tests
-- `researcher` - Finds and synthesizes documentation
-- `scout` - Locates files in codebase
-- `git-manager` - Handles commits and workflows
-- `brainstormer` - Ideates solutions
-- `docs-manager` - Creates and updates documentation
-
-**When to use:** Referenced by prompts to specialize execution
-
----
-
-### 3. Instruction (`instructions/ck-*.instructions.md`)
-
-**Role:** Rules - Auto-applied coding standards
-
-**Example: ck-frontend.instructions.md**
-```yaml
----
-applyTo: '**/*.tsx, **/*.jsx, components/**'
-description: 'Frontend component guidelines'
----
-
-# Frontend Guidelines
-
-When editing React files:
-- Use functional components
-- Props interface required
-- Use hooks instead of class methods
-```
-
-**CoKit Instructions:**
-- `ck-backend` - Backend patterns (Node.js, Python, Go, Rust)
-- `ck-frontend` - Frontend patterns (React, TypeScript)
-- `ck-testing` - Testing standards and patterns
-- `ck-development` - YAGNI/KISS/DRY principles
-- `ck-research` - Research methodology guidelines
-
-**When to use:** Auto-applied based on file patterns while editing
-
----
-
-### 4. Skill (`skills/ck-*/SKILL.md`)
-
-**Role:** Knowledge - Deep specialized expertise with supporting resources
-
-**Example: ck-debugging/SKILL.md**
-```
-skills/ck-debugging/
-├── SKILL.md                  # Main methodology
-├── references/               # Case studies, patterns
-└── examples/                 # Real debugging examples
-```
-
-**CoKit Skills:**
-- `ck-debugging` - Systematic root cause analysis
-- `ck-code-review` - Comprehensive review gates
-- `ck-planning` - Research → design → implementation
-- `ck-problem-solving` - Complexity spirals, innovation blocks
-- `ck-sequential-thinking` - Multi-step problem solving
-- `ck-backend-development` - Backend framework patterns
-- `ck-frontend-development` - Frontend framework patterns
-
-**When to use:** Activated automatically based on task context
-
----
-
-### 5. Collection (`collections/ck-*.collection.yml`)
-
-**Role:** Bundle - Groups related resources by workflow
-
-**Example: ck-core.collection.yml**
-```yaml
-id: ck-core
-name: CoKit Core Workflows
-description: Essential agents, prompts, and skills
-items:
-  - path: agents/planner.agent.md
-  - path: agents/code-reviewer.agent.md
-  - path: prompts/ck-plan.prompt.md
-  - path: prompts/ck-code.prompt.md
-  - path: skills/ck-planning/
-```
-
-**CoKit Collections:**
-- `ck-core` - Core workflows for full-stack development
-- `ck-development-rules` - YAGNI/KISS/DRY principles
-- `ck-documentation` - Documentation management workflows
-- `ck-git-workflow` - Git commit, push, merge workflows
-- `ck-orchestration` - Task delegation and workflow orchestration
-
-**When to use:** Install/share resource bundles for specific workflows
-
----
-
-## Quick Reference
-
-| Resource | Trigger | Scope | Persistence | Purpose |
-|----------|---------|-------|-------------|---------|
-| Prompt | `/prompt-name` | Single task | Per invocation | Workflow |
-| Agent | Prompt refs | Task exec | Per invocation | Execution |
-| Instruction | Auto (glob) | File-based | Always active | Rules/Style |
-| Skill | On-demand | Knowledge | When activated | Expertise |
-| Collection | User install | Resource set | Permanent | Bundling |
-
----
-
-## CoKit Processing Example
-
-```
-User types: /ck-fix
-    ↓
-Prompt (ck-fix.prompt.md) activates
-    ↓
-Agent (debugger.agent.md) executes
-    ↓
-Instructions (ck-*.instructions.md) auto-apply by file pattern
-    ↓
-Skills (ck-debugging, etc.) activate by context
-    ↓
-Output: Systematic debugging solution
-```
-
-## One-liner
-
-> User calls **Prompt** (e.g., `/ck-fix`) → Prompt references **Agent** (e.g., `debugger`) → Agent auto-receives **Instructions** by file pattern → Agent activates **Skills** when needed → All can be bundled in **Collection** (e.g., `ck-core`).
+# Copilot Processing Flow
+
+How Copilot processes user input through CoKit resources to produce output.
+
+> **CoKit Resources:** See [README.md](../README.md) for complete resource listing.
+
+---
+
+## CoKit Resource Types Overview
+
+| Resource | Trigger | Purpose | File |
+|----------|---------|---------|------|
+| **Prompt** | User calls `/ck-prompt-name` | Workflow/task template | `prompts/ck-*.prompt.md` |
+| **Agent** | Referenced by prompt | Execute specific tasks | `agents/*.agent.md` |
+| **Instruction** | Auto (by file pattern) | Coding rules/standards | `instructions/ck-*.instructions.md` |
+| **Skill** | Auto by context | Specialized knowledge | `skills/ck-*/SKILL.md` |
+| **Collection** | User selects | Bundle related resources | `collections/ck-*.collection.yml` |
+
+### CoKit Examples
+
+**Prompts (28 total):** ClaudeKit (ck.*) and SpecKit (ck.spec.*) namespaces with 28 unified commands
+
+**Agents (12 total):** planner, code-reviewer, debugger, tester, researcher, scout, git-manager, brainstormer, docs-manager, code-simplifier, fullstack-developer, ui-ux-designer
+
+**Skills (27 total):** debugging, code-review, planning, problem-solving, sequential-thinking, backend-development, frontend-design, databases, devops, git, mcp-management, and more
+
+**Instructions:** ck-backend, ck-frontend, ck-testing, ck-development, ck-research
+
+**Collections:** ck-core, ck-development-rules, ck-documentation, ck-git-workflow, ck-orchestration
+
+---
+
+## Component Details
+
+### 1. Prompt (`prompts/ck-*.prompt.md`)
+
+**Role:** Entry point - Defines workflow/task
+
+**Example: ck-fix.prompt.md**
+```yaml
+---
+mode: agent
+description: 'Debug and fix issues systematically'
+---
+
+# Fix Issues
+
+You are debugging an issue. Follow systematic troubleshooting...
+
+1. Read the error message
+2. Search for root cause
+3. Implement fix
+4. Test the solution
+```
+
+**CoKit Examples:**
+- `/ck.fix` - Debug and fix
+- `/ck.plan` - Create implementation plan
+- `/ck.cook` - Step-by-step feature implementation
+- `/ck.review-codebase` - Scan and analyze code
+
+**When to use:** User wants to execute a specific workflow
+
+---
+
+### 2. Agent (`agents/*.agent.md`)
+
+**Role:** Executor - Specialized persona for specific tasks
+
+**Example: planner.agent.md**
+```yaml
+---
+description: 'Research, analyze, and create implementation plans'
+---
+
+# Planner Agent
+
+You are a research-first planner...
+- Conduct comprehensive research
+- Design system architecture
+- Create detailed implementation plans
+```
+
+**CoKit Agents (12 total):**
+- `planner` - Creates implementation plans
+- `code-reviewer` - Provides comprehensive code review
+- `debugger` - Investigates and diagnoses issues
+- `tester` - Writes and validates tests
+- `researcher` - Finds and synthesizes documentation
+- `scout` - Locates files in codebase
+- `git-manager` - Handles commits and workflows
+- `brainstormer` - Ideates solutions
+- `docs-manager` - Creates and updates documentation
+- `code-simplifier` - Refactors and simplifies code
+- `fullstack-developer` - Full-stack implementation
+- `ui-ux-designer` - UI/UX design and implementation
+
+**When to use:** Referenced by prompts to specialize execution
+
+---
+
+### 3. Instruction (`instructions/ck-*.instructions.md`)
+
+**Role:** Rules - Auto-applied coding standards
+
+**Example: ck-frontend.instructions.md**
+```yaml
+---
+applyTo: '**/*.tsx, **/*.jsx, components/**'
+description: 'Frontend component guidelines'
+---
+
+# Frontend Guidelines
+
+When editing React files:
+- Use functional components
+- Props interface required
+- Use hooks instead of class methods
+```
+
+**CoKit Instructions:**
+- `ck-backend` - Backend patterns (Node.js, Python, Go, Rust)
+- `ck-frontend` - Frontend patterns (React, TypeScript)
+- `ck-testing` - Testing standards and patterns
+- `ck-development` - YAGNI/KISS/DRY principles
+- `ck-research` - Research methodology guidelines
+
+**When to use:** Auto-applied based on file patterns while editing
+
+---
+
+### 4. Skill (`skills/ck-*/SKILL.md`)
+
+**Role:** Knowledge - Deep specialized expertise with supporting resources
+
+**Example: ck-debugging/SKILL.md**
+```
+skills/ck.debugging/
+├── SKILL.md                  # Main methodology
+├── references/               # Case studies, patterns
+└── examples/                 # Real debugging examples
+```
+
+**CoKit Skills:**
+- `ck-debugging` - Systematic root cause analysis
+- `ck-code-review` - Comprehensive review gates
+- `ck-planning` - Research → design → implementation
+- `ck-problem-solving` - Complexity spirals, innovation blocks
+- `ck-sequential-thinking` - Multi-step problem solving
+- `ck-backend-development` - Backend framework patterns
+- `ck-frontend-development` - Frontend framework patterns
+
+**When to use:** Activated automatically based on task context
+
+---
+
+### 5. Collection (`collections/ck-*.collection.yml`)
+
+**Role:** Bundle - Groups related resources by workflow
+
+**Example: ck-core.collection.yml**
+```yaml
+id: ck-core
+name: CoKit Core Workflows
+description: Essential agents, prompts, and skills
+items:
+  - path: agents/planner.agent.md
+  - path: agents/code-reviewer.agent.md
+  - path: prompts/ck.plan.prompt.md
+  - path: prompts/ck.code.prompt.md
+  - path: skills/ck.planning/
+```
+
+**CoKit Collections:**
+- `ck-core` - Core workflows for full-stack development
+- `ck-development-rules` - YAGNI/KISS/DRY principles
+- `ck-documentation` - Documentation management workflows
+- `ck-git-workflow` - Git commit, push, merge workflows
+- `ck-orchestration` - Task delegation and workflow orchestration
+
+**When to use:** Install/share resource bundles for specific workflows
+
+---
+
+## Quick Reference
+
+| Resource | Trigger | Scope | Persistence | Purpose |
+|----------|---------|-------|-------------|---------|
+| Prompt | `/prompt-name` | Single task | Per invocation | Workflow |
+| Agent | Prompt refs | Task exec | Per invocation | Execution |
+| Instruction | Auto (glob) | File-based | Always active | Rules/Style |
+| Skill | On-demand | Knowledge | When activated | Expertise |
+| Collection | User install | Resource set | Permanent | Bundling |
+
+---
+
+## CoKit Processing Example
+
+```
+User types: /ck.fix
+    ↓
+Prompt (ck-fix.prompt.md) activates
+    ↓
+Agent (debugger.agent.md) executes
+    ↓
+Instructions (ck-*.instructions.md) auto-apply by file pattern
+    ↓
+Skills (ck-debugging, etc.) activate by context
+    ↓
+Output: Systematic debugging solution
+```
+
+## One-liner
+
+> User calls **Prompt** (e.g., `/ck.fix`) → Prompt references **Agent** (e.g., `debugger`) → Agent auto-receives **Instructions** by file pattern → Agent activates **Skills** when needed → All can be bundled in **Collection** (e.g., `ck-core`).

package/docs/guide-next-steps-speckit-cokit-implementation.md

@@ -0,0 +1,187 @@
+# Next Steps Guide: Spec-Kit + Cokit Implementation
+
+**Created:** Feb 3, 2026
+**Status:** COMPLETE (v1.2.0 released with SpecKit integration)
+
+---
+
+## Phase 1: Setup Spec-Kit (Week 1)
+
+### Step 1.1: Install GitHub Spec-Kit (Reference)
+```bash
+# Install spec-kit CLI for reference
+uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
+
+# Test it works
+specify --help
+```
+
+### Step 1.2: Study Spec-Kit Structure
+```bash
+# Clone for reference (don't modify)
+git clone https://github.com/github/spec-kit.git ~/reference/spec-kit
+
+# Key files to study:
+# - templates/claude/commands/*.md
+# - src/specify_cli/
+# - docs/
+```
+
+### Step 1.3: Create my-spec-kit Scaffold
+```bash
+cd /Users/admin/workspace/_me/cokit
+mkdir -p src/spec-kit/{cli,templates,validators}
+
+# Create initial files
+touch src/spec-kit/cli/init.js
+touch src/spec-kit/cli/constitution.js
+touch src/spec-kit/cli/specify.js
+touch src/spec-kit/templates/constitution.md
+touch src/spec-kit/templates/spec-feature.md
+touch src/spec-kit/templates/spec-api.md
+```
+
+### Step 1.4: Define Custom Templates
+
+**constitution.md** - Project governance:
+- Tech stack decisions
+- Code standards
+- Security requirements
+- Team conventions
+
+**spec-feature.md** - Feature specs:
+- User stories
+- Acceptance criteria
+- Technical constraints
+- Dependencies
+
+---
+
+## Phase 2: Port ClaudeKit → Cokit (Week 2-3)
+
+### Step 2.1: Research Copilot CLI
+```bash
+# Check Copilot CLI docs
+# https://docs.github.com/en/copilot/using-github-copilot/using-github-copilot-in-the-command-line
+
+# Install GitHub CLI with Copilot extension
+gh extension install github/gh-copilot
+```
+
+### Step 2.2: Map Commands
+| ClaudeKit | Cokit (Copilot) | Notes |
+|-----------|-----------------|-------|
+| `/brainstorm` | `cokit brainstorm` | Adapt prompts |
+| `/plan` | `cokit plan` | Different context model |
+| `/cook` | `cokit cook` | Simplify for Copilot |
+| `/fix` | `cokit fix` | Direct port |
+| `/worktree` | `cokit worktree` | Git-only, no AI needed |
+
+### Step 2.3: Create Cokit CLI
+```bash
+# Scaffold already exists in /src
+# Enhance with new commands:
+
+# src/commands/
+#   brainstorm.js
+#   plan.js
+#   cook.js
+#   fix.js
+#   worktree.js
+```
+
+---
+
+## Phase 3: Integrate Spec-Kit + Cokit (Week 3-4)
+
+### Step 3.1: Create Combo Workflows
+```
+cokit workflow enterprise  → speckit.constitution → speckit.specify → brainstorm → plan → cook
+cokit workflow quick       → brainstorm → plan:fast → cook
+cokit workflow fix         → fix --auto
+```
+
+### Step 3.2: Add to Instructions
+```bash
+# Update /instructions/ with combo workflows
+touch instructions/workflow-enterprise.md
+touch instructions/workflow-quick.md
+touch instructions/workflow-fix.md
+```
+
+---
+
+## Phase 4: Team Training (Week 4)
+
+### Step 4.1: Create Training Materials
+- [ ] Quick start guide (5 min read)
+- [ ] Video demo (10 min)
+- [ ] Cheat sheet (1 page)
+- [ ] FAQ document
+
+### Step 4.2: Pilot Program
+- [ ] Select 2-3 volunteer devs
+- [ ] Run 1-week pilot
+- [ ] Collect feedback
+- [ ] Iterate
+
+### Step 4.3: Full Rollout
+- [ ] Team presentation
+- [ ] Pair programming sessions
+- [ ] Office hours for questions
+
+---
+
+## Quick Reference: Commands After Setup
+
+```bash
+# Enterprise feature (with specs)
+cokit workflow enterprise "new payment system"
+
+# Quick feature (no specs)
+cokit workflow quick "add dark mode"
+
+# Bug fix
+cokit fix "error: undefined is not a function"
+
+# Parallel development
+cokit worktree "feature-x"
+```
+
+---
+
+## Checklist
+
+### Week 1
+- [ ] Install spec-kit CLI (reference)
+- [ ] Clone spec-kit repo (study)
+- [ ] Create my-spec-kit scaffold
+- [ ] Write constitution template
+- [ ] Write spec-feature template
+
+### Week 2
+- [ ] Research Copilot CLI API
+- [ ] Map ClaudeKit → Cokit commands
+- [ ] Port `/brainstorm` command
+- [ ] Port `/plan` command
+
+### Week 3
+- [ ] Port `/cook` command
+- [ ] Port `/fix` command
+- [ ] Port `/worktree` command
+- [ ] Create combo workflows
+
+### Week 4
+- [ ] Write training materials
+- [ ] Run pilot program
+- [ ] Collect feedback
+- [ ] Full team rollout
+
+---
+
+## Resources
+
+- [GitHub Spec-Kit](https://github.com/github/spec-kit)
+- [ClaudeKit Reference](https://github.com/duthaho/claudekit)
+- [Copilot CLI Docs](https://docs.github.com/en/copilot)
+- Research reports: `pocketquant/plans/reports/brainstorm-260203-*`