cokit-cli 1.0.8 → 1.2.0

package/docs/cokit-slides.md

@@ -37,7 +37,7 @@
 ## Slide 4: One Command
 
 ```bash
-npx cokit init
+npx cokit-cli init
 ```
 
 That's it. No install. No config. No account.
@@ -47,11 +47,12 @@ That's it. No install. No config. No account.
 ## Slide 5: How It Works
 
 ```
-You publish once    →    npm Registry    →    User runs npx
-     ↓                                              ↓
-npm publish                               Downloads automatically
+Developer publishes    →    npm Registry    →    User runs npx
+         ↓                                            ↓
+npm publish                               Downloads cokit-cli
                                                     ↓
                                           Creates files in project
+                                          (.github/, skills)
                                                     ↓
                                           Ready to use in VS Code
 ```
@@ -60,27 +61,30 @@ npm publish                               Downloads automatically
 
 ## Slide 6: What Users Get
 
-### 6 Prompts
-| Command | Action |
-|---------|--------|
-| `/fix` | Debug issues |
-| `/plan` | Create plans |
-| `/code` | Implement |
-| `/test` | Write tests |
-| `/review` | Review code |
-| `/docs` | Update docs |
+### 28 Prompts (ClaudeKit + SpecKit)
+
+**Development workflows (ck.*):**
+- `/ck.fix`, `/ck.plan`, `/ck.cook`, `/ck.test`, `/ck.review`, `/ck.bootstrap`, `/ck.brainstorm`, etc.
+
+**Spec-driven workflows (ck.spec.*):**
+- `/ck.spec.specify`, `/ck.spec.clarify`, `/ck.spec.plan`, `/ck.spec.tasks`, `/ck.spec.implement`, etc.
+
+All unified in single namespace with cross-navigation.
 
 ---
 
 ## Slide 7: What Users Get (cont.)
 
-### 5 Skills (Auto-Activate)
+### 27 Skills + 12 Agents (Auto-Activate)
+
+**Skills (27 total):**
+- debugging, code-review, planning, problem-solving, sequential-thinking
+- backend-development, frontend-design, databases, devops, git, mcp-management
+- research, scout, and more specialized expertise
 
-- **debugging** - Root cause analysis
-- **code-review** - Security + best practices
-- **planning** - Break down features
-- **docs-seeker** - Find documentation
-- **sequential-thinking** - Step-by-step logic
+**Agents (12 total):**
+- Original 9: planner, code-reviewer, debugger, tester, researcher, scout, git-manager, brainstormer, docs-manager
+- New 3: code-simplifier, fullstack-developer, ui-ux-designer
 
 ---
 
@@ -88,19 +92,19 @@ npm publish                               Downloads automatically
 
 | Option | Command | Location |
 |--------|---------|----------|
-| **Project** | `npx cokit init` | `.github/` |
-| **Personal** | `npx cokit init --global` | `~/.copilot/` |
-| **Both** | `npx cokit init --all` | Both |
+| **Project** | `npx cokit-cli init` | `.github/` |
+| **Personal** | `npx cokit-cli init -g` | `~/.copilot/` |
+| **Both** | `npx cokit-cli init -a` | Both |
 
 ---
 
 ## Slide 9: CLI Commands
 
 ```bash
-npx cokit init      # Setup wizard
-npx cokit doctor    # Troubleshoot
-npx cokit list      # Show installed
-npx cokit update    # Get latest
+npx cokit-cli init      # Setup wizard
+npx cokit-cli doctor    # Troubleshoot
+npx cokit-cli list      # Show installed
+npx cokit-cli update    # Get latest
 ```
 
 ---
@@ -108,20 +112,22 @@ npx cokit update    # Get latest
 ## Slide 10: User Experience
 
 ```
-$ npx cokit init
+$ npx cokit-cli init
 
-🚀 CoKit Setup
+🚀 CoKit Setup (v1.0.9)
 
 ? What do you want to set up?
-  › Project templates
-    Personal skills
+  › Project templates (.github/)
+    Personal skills (~/.copilot/)
     Both
 
 ✓ Created .github/copilot-instructions.md
-✓ Created .github/prompts/fix.prompt.md
-...
+✓ Created .github/AGENTS.md
+✓ Created .github/prompts/ (14 prompts)
+✓ Created .github/instructions/ (5 files)
+✓ Created .github/collections/ (5 bundles)
 
-🎉 Done! Try /fix in Copilot Chat.
+🎉 Done! Try /ck.fix in Copilot Chat.
 ```
 
 ---
@@ -132,10 +138,11 @@ $ npx cokit init
 |-------|------|------|
 | 1 | CLI tool | 4h |
 | 2 | Project templates | 3h |
-| 3 | Skills (5) | 4h |
-| 4 | Prompts (6) | 2h |
+| 3 | Skills (7), Agents (9), Instructions (5), Collections (5) | 6h |
+| 4 | Prompts (14) | 3h |
 | 5 | Documentation | 3h |
-| **Total** | | **16h** |
+| 6 | Cleanup phase | 2h |
+| **Total** | | **21h** |
 
 ---
 
@@ -156,10 +163,10 @@ Node.js CLI
 
 ```bash
 # We do once:
-npm publish
+npm publish (publishes cokit-cli to npmjs.com)
 
 # Users do:
-npx cokit init    # Always gets latest
+npx cokit-cli init    # Always gets latest version
 ```
 
 ---
@@ -189,9 +196,9 @@ npx cokit init    # Always gets latest
 ## Slide 16: Summary
 
 1. **Problem:** Copilot is inconsistent
-2. **Solution:** CoKit adds structure
-3. **Install:** `npx cokit init`
-4. **Timeline:** 16 hours
+2. **Solution:** CoKit adds structure (v1.0.9)
+3. **Install:** `npx cokit-cli init`
+4. **Resources:** 9 agents, 14 prompts, 7 skills, 5 instructions, 5 collections
 5. **Repo:** github.com/camping89/cokit
 
 ---
@@ -202,4 +209,4 @@ npx cokit init    # Always gets latest
 
 **Full docs:** `docs/cokit-team-presentation.md`
 
-**Plan:** `plans/260106-1102-cokit-implementation/`
+**Quick start:** `npx cokit-cli init -g`

package/docs/cokit-sync-and-maintenance-guide.md

@@ -0,0 +1,414 @@
+# CoKit Sync & Maintenance Guide
+
+> **IMPORTANT**: This is the official guide for maintaining CoKit's integration with upstream sources (ClaudeKit + SpecKit). Read this before making any changes to the sync pipeline.
+
+---
+
+## Architecture Overview
+
+CoKit merges two upstream sources into a unified `ck.*` command namespace:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        SOURCES                                   │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  ClaudeKit (pre-installed)        SpecKit (git subtree)         │
+│  ~/.claude/                       upstream/speckit/             │
+│  ├── commands/                    └── templates/commands/       │
+│  ├── agents/                                                    │
+│  └── skills/                                                    │
+│                                                                 │
+└───────────────────────┬─────────────────────────────────────────┘
+                        │
+                        ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    SYNC PIPELINE                                 │
+│                    npm run sync                                  │
+├─────────────────────────────────────────────────────────────────┤
+│  1. PULL      → git subtree pull speckit                        │
+│  2. TRANSFORM → Rename commands, fix placeholders               │
+│  3. PATCH     → Inject unified navigation                       │
+│  4. GENERATE  → Write to prompts/, agents/, skills/             │
+└───────────────────────┬─────────────────────────────────────────┘
+                        │
+                        ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      OUTPUT                                      │
+├─────────────────────────────────────────────────────────────────┤
+│  prompts/           agents/           skills/                   │
+│  ├── ck.brainstorm  ├── planner       ├── ck-planning/          │
+│  ├── ck.specify     ├── debugger      ├── ck-databases/         │
+│  ├── ck.plan        └── ...           └── ...                   │
+│  └── ...                                                        │
+│                                                                 │
+│  All use unified ck.* namespace                                 │
+│  All have cross-navigation to other ck.* commands               │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `eng/sync.mjs` | Main sync orchestrator |
+| `eng/transform-claudekit.mjs` | ClaudeKit → CoKit transform rules |
+| `eng/transform-speckit.mjs` | SpecKit → CoKit transform rules |
+| `eng/patch-navigation.mjs` | Injects unified navigation footer |
+| `eng/resource-origins.yml` | **CRITICAL** - Maps ck.* commands to upstream sources |
+
+---
+
+## The Resource Origins File
+
+**Location:** `eng/resource-origins.yml`
+
+This is the **source of truth** for all command mappings. When upstream adds/removes commands, update this file.
+
+```yaml
+version: "2.0"
+synced_at: "2026-02-03"
+
+sources:
+  speckit:
+    repo: github/spec-kit
+    ref: main
+    last_sync: "2026-02-03"
+  claudekit:
+    path: ~/.claude
+    last_sync: "2026-02-03"
+
+# COMMAND MAPPINGS
+# Format: ck.{name} → source info
+mappings:
+  # ═══════════════════════════════════════════════════════════════
+  # FROM SPECKIT
+  # ═══════════════════════════════════════════════════════════════
+  ck.specify:
+    origin: speckit
+    original: speckit.specify
+    upstream_file: templates/commands/specify.md
+    description: Create feature specification from description
+
+  ck.clarify:
+    origin: speckit
+    original: speckit.clarify
+    upstream_file: templates/commands/clarify.md
+    description: Resolve specification ambiguities
+
+  ck.constitution:
+    origin: speckit
+    original: speckit.constitution
+    upstream_file: templates/commands/constitution.md
+    description: Create/update project constitution
+
+  ck.tasks:
+    origin: speckit
+    original: speckit.tasks
+    upstream_file: templates/commands/tasks.md
+    description: Generate task list from plan
+
+  ck.analyze:
+    origin: speckit
+    original: speckit.analyze
+    upstream_file: templates/commands/analyze.md
+    description: Analyze spec consistency
+
+  ck.checklist:
+    origin: speckit
+    original: speckit.checklist
+    upstream_file: templates/commands/checklist.md
+    description: Quality validation checklist
+
+  # ═══════════════════════════════════════════════════════════════
+  # FROM CLAUDEKIT
+  # ═══════════════════════════════════════════════════════════════
+  ck.brainstorm:
+    origin: claudekit
+    original: brainstorm
+    upstream_file: skills/brainstorm/SKILL.md
+    description: Explore solutions with trade-off analysis
+
+  ck.plan:
+    origin: claudekit
+    original: plan
+    upstream_file: commands/plan.md
+    description: Intelligent plan creation
+
+  ck.plan.hard:
+    origin: claudekit
+    original: plan/hard
+    upstream_file: commands/plan/hard.md
+    description: Deep research + comprehensive plan
+
+  ck.plan.fast:
+    origin: claudekit
+    original: plan/fast
+    upstream_file: commands/plan/fast.md
+    description: Quick plan without research
+
+  ck.cook:
+    origin: claudekit
+    original: cook
+    upstream_file: skills/cook/SKILL.md
+    description: Implement feature step by step
+
+  ck.fix:
+    origin: claudekit
+    original: fix
+    upstream_file: skills/fix/SKILL.md
+    description: Analyze and fix issues
+
+  ck.test:
+    origin: claudekit
+    original: test
+    upstream_file: commands/test.md
+    description: Run tests and analyze results
+
+# New commands discovered during sync (review and add to mappings)
+unknown_commands: []
+```
+
+---
+
+## Sync Workflow
+
+### Regular Sync (Weekly/Monthly)
+
+```bash
+# 1. Pull latest from SpecKit
+npm run sync:pull
+
+# 2. Transform and generate
+npm run sync:transform
+
+# 3. Review changes
+git diff
+
+# 4. Check for unknown commands
+cat eng/resource-origins.yml | grep -A5 "unknown_commands"
+
+# 5. If unknown commands found, add them to mappings
+# Edit eng/resource-origins.yml, then re-run:
+npm run sync:transform
+
+# 6. Commit
+git add .
+git commit -m "sync: update from claudekit + speckit $(date +%Y-%m-%d)"
+```
+
+### When Upstream Adds New Commands
+
+1. **Sync detects unknown command** → logged to `unknown_commands` in resource-origins.yml
+2. **Review the new command** → check upstream docs
+3. **Add to mappings** with appropriate `ck.*` name
+4. **Re-run transform**
+5. **Test the new command**
+
+### When Upstream Removes/Renames Commands
+
+1. **Sync will fail** to find upstream file
+2. **Check if renamed** → update `upstream_file` path
+3. **If removed** → decide: keep as cokit-native or deprecate
+4. **Update resource-origins.yml** accordingly
+
+---
+
+## Transform Rules
+
+### Command Renaming
+
+| Original | Transformed |
+|----------|-------------|
+| `/speckit.specify` | `/ck.specify` |
+| `/speckit.plan` | `/ck.plan` (conflicts with claudekit, see below) |
+| `/plan` (claudekit) | `/ck.plan` |
+| `/plan:hard` | `/ck.plan.hard` |
+| `/brainstorm` | `/ck.brainstorm` |
+
+### Conflict Resolution
+
+When both sources have same command name (e.g., `plan`):
+- **Default**: ClaudeKit version wins (more mature)
+- **SpecKit version**: Available as `ck.plan.spec` if needed
+- **Document in resource-origins.yml**
+
+### Placeholder Substitution
+
+| Original | Transformed |
+|----------|-------------|
+| `$ARGUMENTS` | `${input}` |
+| `{ARGS}` | `${input}` |
+
+### Model Field
+
+- **Remove entirely** - Let Copilot use its default
+- ClaudeKit's `model: opus/sonnet/haiku` → removed
+
+### Handoffs (SpecKit-specific)
+
+SpecKit commands have `handoffs` in frontmatter:
+```yaml
+handoffs:
+  - label: Build Technical Plan
+    agent: speckit.plan
+```
+
+Transform to:
+```yaml
+handoffs:
+  - label: Build Technical Plan
+    agent: ck.plan
+```
+
+---
+
+## Patch: Unified Navigation
+
+Every prompt gets a navigation footer injected:
+
+```markdown
+---
+
+## Suggested Next Steps
+
+| Current | Next Options |
+|---------|--------------|
+| After `ck.brainstorm` | `/ck.specify`, `/ck.plan.fast` |
+| After `ck.specify` | `/ck.clarify`, `/ck.brainstorm`, `/ck.plan` |
+| After `ck.clarify` | `/ck.specify` (update), `/ck.plan` |
+| After `ck.plan` | `/ck.cook`, `/ck.brainstorm` (rethink) |
+| After `ck.cook` | `/ck.test`, `/ck.fix` |
+
+**All commands:** `ck.brainstorm`, `ck.specify`, `ck.clarify`, `ck.constitution`, `ck.plan`, `ck.plan.hard`, `ck.plan.fast`, `ck.tasks`, `ck.cook`, `ck.fix`, `ck.test`
+```
+
+---
+
+## Default Workflow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    RECOMMENDED FLOW                              │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  User has idea                                                  │
+│       │                                                         │
+│       ▼                                                         │
+│  ┌─────────────┐                                                │
+│  │ck.brainstorm│ ← Always start here (question everything)     │
+│  └──────┬──────┘                                                │
+│         │                                                       │
+│         ▼                                                       │
+│  ┌─────────────┐                                                │
+│  │ ck.specify  │ ← Formalize into spec                         │
+│  └──────┬──────┘                                                │
+│         │ Has ambiguities?                                      │
+│         ▼                                                       │
+│  ┌─────────────┐                                                │
+│  │ ck.clarify  │ ← Resolve (optional)                          │
+│  └──────┬──────┘                                                │
+│         │◄────────────────────────┐                             │
+│         ▼                         │                             │
+│  ┌─────────────┐                  │                             │
+│  │ ck.plan     │    Loop back if  │                             │
+│  └──────┬──────┘    approach needs│                             │
+│         │           rethinking    │                             │
+│         ▼                         │                             │
+│  ┌─────────────┐                  │                             │
+│  │ ck.cook     │──────────────────┘                             │
+│  └──────┬──────┘    (via ck.brainstorm)                         │
+│         │                                                       │
+│         ▼                                                       │
+│  ┌─────────────┐                                                │
+│  │ ck.test     │                                                │
+│  └─────────────┘                                                │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Troubleshooting
+
+### Sync fails with "file not found"
+
+1. Check if upstream renamed/moved the file
+2. Update `upstream_file` in resource-origins.yml
+3. Re-run sync
+
+### New command not appearing
+
+1. Check if it's in `unknown_commands` list
+2. Add to `mappings` section with `ck.*` name
+3. Re-run sync
+
+### Merge conflicts in generated files
+
+**Never manually edit files in `prompts/`, `agents/`, `skills/`**
+
+These are generated. Fix the source:
+1. Check transform scripts for bugs
+2. Check resource-origins.yml for correct mappings
+3. Re-run sync
+
+### ClaudeKit not found
+
+Ensure ClaudeKit is installed at `~/.claude/`:
+```bash
+ls ~/.claude/commands/
+ls ~/.claude/agents/
+ls ~/.claude/skills/
+```
+
+---
+
+## Adding Cokit-Native Commands
+
+For commands that don't come from upstream:
+
+1. Create directly in `prompts/` with `ck.` prefix
+2. Add to resource-origins.yml with `origin: cokit-native`:
+
+```yaml
+ck.workflow.enterprise:
+  origin: cokit-native
+  description: Full enterprise flow (brainstorm → specify → plan → cook)
+```
+
+3. These won't be overwritten by sync
+
+---
+
+## Version Pinning (Production)
+
+For stability, pin SpecKit to a specific tag:
+
+```yaml
+# eng/resource-origins.yml
+sources:
+  speckit:
+    repo: github/spec-kit
+    ref: v1.2.0  # Pin to tag instead of main
+```
+
+Update `sync:pull` script to use the ref:
+```bash
+git subtree pull --prefix=upstream/speckit https://github.com/github/spec-kit.git v1.2.0 --squash
+```
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| 2026-02-03 | Initial architecture design |
+
+---
+
+## Questions?
+
+Check the brainstorm report: `plans/reports/brainstorm-260203-1630-cokit-v2-architecture-refresh.md`