cokit-cli 1.0.9 → 1.2.2

package/docs/README.md

@@ -1,108 +1,75 @@
-# CoKit Documentation
-
-Complete reference for CoKit - GitHub Copilot AI resource toolkit.
-
-**Current Version:** 1.0.9
-**Last Updated:** 2026-01-20
-
-## Quick Navigation
-
-- [Team Presentation](./cokit-team-presentation.md) - Detailed overview and architecture
-- [Slides](./cokit-slides.md) - Condensed presentation format
-- [Migration Guide](./migration-guide.md) - Claude Code users
-- [Processing Flow](./copilot-processing-flow.md) - Resource interaction
-- [Project Roadmap](./project-roadmap.md) - Version history and phases
-
-## Resource Overview
-
-CoKit includes **9 agents**, **14 prompts**, **5 instructions**, **7 skills**, and **5 collections**.
-
-### Prompts (`prompts/ck-*.prompt.md`) - 14 total
-
-Entry points for Copilot workflows with `ck-` prefix:
-
-| Category | Prompts |
-|----------|---------|
-| Core | `/ck-fix`, `/ck-plan`, `/ck-code` |
-| Implementation | `/ck-cook`, `/ck-bootstrap` |
-| Quality | `/ck-test`, `/ck-review-codebase`, `/ck-debug` |
-| Analysis | `/ck-scout`, `/ck-ask` |
-| Collaboration | `/ck-brainstorm`, `/ck-docs`, `/ck-git` |
-| Help | `/ck-ck-help` |
-
-### Agents (`agents/*.agent.md`) - 9 total
-
-Specialized personas executing specific tasks:
-
-| Agent | Purpose |
-|-------|---------|
-| **planner** | Implementation planning and design |
-| **code-reviewer** | Comprehensive code review |
-| **debugger** | Issue investigation |
-| **tester** | Test writing and validation |
-| **researcher** | Technology research |
-| **scout** | Codebase navigation |
-| **git-manager** | Git workflows |
-| **brainstormer** | Solution ideation |
-| **docs-manager** | Documentation management |
-
-### Instructions (`instructions/ck-*.instructions.md`) - 5 total
-
-Coding standards auto-applied by file pattern:
-
-- **ck-backend** - Backend development (Node.js, Python, Go, Rust)
-- **ck-frontend** - Frontend development (React, TypeScript)
-- **ck-testing** - Testing standards and patterns
-- **ck-development** - YAGNI/KISS/DRY principles
-- **ck-research** - Research methodology
-
-### Skills (`skills/ck-*/`) - 7 total
-
-Deep specialized expertise packages:
-
-- **ck-debugging** - Systematic root cause analysis
-- **ck-code-review** - Verification gates and protocols
-- **ck-planning** - Research → design → implementation
-- **ck-problem-solving** - Complexity spirals and solutions
-- **ck-sequential-thinking** - Multi-step problem solving
-- **ck-backend-development** - Backend framework patterns
-- **ck-frontend-development** - Frontend framework patterns
-
-### Collections (`collections/ck-*.collection.yml`) - 5 total
-
-Curated resource bundles by workflow:
-
-- **ck-core** - Core workflows for full-stack development
-- **ck-development-rules** - YAGNI/KISS/DRY principles
-- **ck-documentation** - Documentation management
-- **ck-git-workflow** - Git workflow automation
-- **ck-orchestration** - Task delegation patterns
-
-## Installation
-
-```bash
-# Interactive setup
-npx cokit-cli init
-
-# Global resources only
-npx cokit-cli init -g
-
-# Both project and global
-npx cokit-cli init -a
-```
-
-## How It Works
-
-1. User calls prompt (e.g., `/ck-fix`)
-2. Prompt activates specified agent (e.g., `debugger`)
-3. Agent auto-receives instructions by file pattern
-4. Agent activates skills based on task context
-5. All resources can be bundled via collections
-
-See [Processing Flow](./copilot-processing-flow.md) for detailed interaction diagrams.
-
-## References
-
-- **Root README:** [CoKit Repository](../README.md)
-- **Comprehensive Guide:** [Mapping Guide](./cokit-comprehensive-mapping-guide.md)
-- **Architecture:** See `./copilot-processing-flow.md`
+# CoKit Documentation Index
+
+**Version:** 1.2.0 | **Updated:** 2026-02-10
+
+## Reading Order by Role
+
+### Users (Getting Started)
+| # | Doc | Purpose |
+|---|-----|---------|
+| 1 | [../README.md](../README.md) | Installation & sample workflows |
+| 2 | [cokit-commands-usage-guide.md](cokit-commands-usage-guide.md) | When to use `ck-*` vs `ck-spec-*` |
+
+### Team Members (Understanding CoKit)
+| # | Doc | Purpose |
+|---|-----|---------|
+| 1 | [project-overview-pdr.md](project-overview-pdr.md) | Vision, goals, success metrics |
+| 2 | [system-architecture.md](system-architecture.md) | Sync pipeline, data flow |
+| 3 | [codebase-summary.md](codebase-summary.md) | File structure overview |
+
+### Contributors (Development)
+| # | Doc | Purpose |
+|---|-----|---------|
+| 1 | [code-standards.md](code-standards.md) | Coding conventions, commit format |
+| 2 | [cokit-sync-and-maintenance-guide.md](cokit-sync-and-maintenance-guide.md) | Running sync, adding commands |
+| 3 | [project-roadmap.md](project-roadmap.md) | Future plans, phases |
+
+### Reference (As Needed)
+| Doc | Read When |
+|-----|-----------|
+| [cokit-comprehensive-mapping-guide.md](cokit-comprehensive-mapping-guide.md) | Debugging command mappings |
+| [copilot-processing-flow.md](copilot-processing-flow.md) | Understanding prompt processing |
+| [migration-guide.md](migration-guide.md) | Upgrading from older versions |
+
+### Presentations
+| Doc | Use For |
+|-----|---------|
+| [cokit-team-presentation.md](cokit-team-presentation.md) | Team onboarding |
+| [cokit-slides.md](cokit-slides.md) | Quick demos |
+
+---
+
+## Quick Reference
+
+### What's in CoKit?
+| Resource | Count | Location |
+|----------|-------|----------|
+| Prompts | 27 | `prompts/ck-*.prompt.md` |
+| Agents | 12 | `agents/*.agent.md` |
+| Skills | 27 | `skills/*/` |
+| Instructions | 5 | `instructions/ck-*.instructions.md` |
+| Collections | 5 | `collections/ck-*.collection.yml` |
+
+### Two Workflows
+| Workflow | Commands | Best For |
+|----------|----------|----------|
+| ClaudeKit | `ck-*` | Daily dev, quick fixes |
+| SpecKit | `ck-spec-*` | Complex features, formal specs |
+
+### Key Commands
+```
+/ck-fix          → Fix bugs
+/ck-plan-fast    → Quick feature
+/ck-plan-hard    → Research + plan
+/ck-spec-specify → Formal specification
+```
+
+---
+
+## TL;DR
+
+**New user?** Read README → commands-usage-guide
+
+**Joining team?** Read project-overview → system-architecture
+
+**Contributing?** Read code-standards → sync-maintenance-guide

package/docs/code-standards.md

@@ -0,0 +1,68 @@
+# CoKit Code Standards
+
+## Principles
+- **YAGNI**: Don't build what you don't need
+- **KISS**: Keep solutions simple
+- **DRY**: Don't repeat yourself
+
+## File Naming
+- kebab-case for all files: `transform-claudekit.mjs`
+- Descriptive names that self-document purpose
+- Extensions: `.mjs` for ES modules, `.js` for CommonJS
+
+## Project Structure
+```
+cokit/
+├── bin/cokit.js          # CLI entry point
+├── src/index.js          # Main CLI logic
+├── eng/                  # Build/sync scripts
+│   ├── sync.mjs          # Sync orchestrator
+│   ├── transform-*.mjs   # Transform scripts
+│   ├── patch-navigation.mjs
+│   └── resource-origins.yml
+├── prompts/              # Generated prompts
+├── agents/               # Agent definitions
+├── skills/               # Skill definitions
+├── instructions/         # Instruction files
+├── collections/          # Bundled collections
+├── upstream/speckit/     # Git subtree (read-only)
+└── docs/                 # Documentation
+```
+
+## Code Style
+
+### JavaScript/Node.js
+- ES Modules with top-level await
+- Async/await over callbacks
+- Destructuring for imports
+- Template literals for strings
+
+### Example
+```javascript
+import { globby } from 'globby';
+import fs from 'fs/promises';
+
+export async function transform(config) {
+  const files = await globby('*.md', { cwd: config.path });
+  // ...
+}
+```
+
+## Commit Messages
+Conventional commits: `type(scope): description`
+
+| Type | Use For |
+|------|---------|
+| feat | New features |
+| fix | Bug fixes |
+| docs | Documentation |
+| chore | Maintenance |
+
+## Testing
+- `npm test` runs Node.js test runner
+- Test files: `*.test.js`
+
+## Documentation
+- Max 800 LOC per doc file
+- Use tables for structured data
+- Include code examples

package/docs/codebase-summary.md

@@ -0,0 +1,263 @@
+# CoKit Codebase Summary
+
+## Overview
+
+CoKit is a CLI tool that enhances GitHub Copilot with 27 prompts, 12 agents, 5 instructions, 27 skills, and 5 collections. The tool unifies two upstream sources (ClaudeKit and SpecKit) into a single ck-* namespace.
+
+**Repository:** https://github.com/camping89/cokit.git
+**Version:** 1.2.0
+**License:** CC BY-NC 4.0
+**Node Requirements:** >= 18.0.0
+**Last Updated:** 2026-02-10
+
+## Architecture
+
+CoKit uses a **sync pipeline architecture** that transforms and merges upstream resources:
+
+```
+Upstream Sources (ClaudeKit + SpecKit)
+    ↓
+Transform Modules (Transform ClaudeKit & SpecKit)
+    ↓
+Merge Results
+    ↓
+Patch Navigation (Inject workflow footers)
+    ↓
+Output: Unified ck-* Prompts
+```
+
+### Sync Pipeline (eng/sync.mjs)
+- **Flow:** Load config → Transform sources → Merge → Patch navigation → Write output
+- **Configuration:** resource-origins.yml (mappings, navigation, ignore list)
+- **Parallel Processing:** ClaudeKit and SpecKit transformations run concurrently
+- **Dry-run Support:** Preview changes without writing files
+
+## Source Code Structure
+
+### Core Files (600 LOC total)
+
+| File | Size | Purpose |
+|------|------|---------|
+| `src/index.js` | 35 LOC | CLI entry point; registers commands (init, add, list, doctor, update) |
+| `bin/cokit.js` | 4 LOC | Binary wrapper; delegates to src/index.js |
+| `eng/sync.mjs` | 97 LOC | Main sync orchestrator; orchestrates transformation and merging |
+| `eng/transform-claudekit.mjs` | 220 LOC | ClaudeKit transformer; resolves files, applies transformations |
+| `eng/transform-speckit.mjs` | 175 LOC | SpecKit transformer; processes upstream/speckit/templates/commands |
+| `eng/patch-navigation.mjs` | 69 LOC | Navigation patcher; injects "Suggested Next Steps" footers |
+
+### Directory Structure
+
+```
+cokit/
+├── bin/
+│   └── cokit.js                    # Binary entry point
+├── src/
+│   ├── index.js                    # CLI program setup
+│   ├── commands/                   # Command implementations
+│   │   ├── init.js                 # Installation logic
+│   │   ├── add.js                  # Add resources
+│   │   ├── list.js                 # List resources
+│   │   ├── doctor.js               # System diagnostics
+│   │   └── update.js               # Update check
+│   └── utils/
+│       └── update-checker.js        # Version checking
+├── eng/
+│   ├── sync.mjs                    # Sync orchestrator
+│   ├── transform-claudekit.mjs      # ClaudeKit transformer
+│   ├── transform-speckit.mjs        # SpecKit transformer
+│   ├── patch-navigation.mjs         # Navigation footer injection
+│   └── resource-origins.yml         # Configuration (mappings, navigation)
+├── prompts/                        # Output: Transformed prompts (28 files)
+├── agents/                         # Agent definitions (12 files)
+├── instructions/                   # Instruction sets (5 files)
+├── skills/                         # Skill packs (27 directories)
+├── collections/                    # Collection definitions (5 files)
+├── docs/                           # Documentation
+└── package.json                    # Dependencies & scripts
+
+```
+
+## Key Components
+
+### 1. CLI Entry (src/index.js)
+Registers 5 commands using Commander.js:
+- **init** - Install CoKit resources globally or to project
+- **add** - Add specific resources
+- **list** - List installed resources
+- **doctor** - Diagnose setup issues
+- **update** - Check for new versions
+
+### 2. Sync Pipeline (eng/sync.mjs)
+**Flow:**
+1. Load resource-origins.yml configuration
+2. Transform ClaudeKit and SpecKit sources in parallel
+3. Merge results (total: 27 prompts)
+4. Apply navigation patches to all prompts
+5. Write output files or show dry-run preview
+6. Update sync timestamps
+
+**Config Structure:**
+```yaml
+version: '2.0'
+sources:
+  speckit: {repo, ref, path, last_sync}
+  claudekit: {path, last_sync}
+ignore: []            # Commands to skip
+mappings: {}          # Command mappings (21 entries)
+unknown_commands: []  # Tracking unknown sources
+navigation: {}        # Workflow navigation rules
+```
+
+### 3. Transform Modules
+
+#### ClaudeKit Transformer (transform-claudekit.mjs)
+**Input:** ~/.claude/commands/ (user's local ClaudeKit)
+**Transformations:**
+- Rename: `/*` → `ck-*` namespace
+- Replace: `$ARGUMENTS` → `${input}`
+- Remove `model` field from frontmatter
+- Update handoff references to ck-* commands
+- Transform command references in content
+
+**Functions:**
+- `resolveClaudekitPath()` - Expand ~ paths
+- `findCommandFile()` - Locate command files (handles variations)
+- `transformFile()` - Apply all transformations
+- `transformCommandReference()` - Update handoff commands
+- `transformContentReferences()` - Replace content references
+
+#### SpecKit Transformer (transform-speckit.mjs)
+**Input:** upstream/speckit/templates/commands/
+**Transformations:**
+- Rename: `/speckit-*` → `/ck-*`
+- Replace: `$ARGUMENTS` → `${input}`
+- Remove `model` field from frontmatter
+- Update handoff references to ck-* commands
+
+**Functions:**
+- `transformFile()` - Apply transformations
+- `transformCommandReference()` - Update handoffs (speckit-* → ck-*)
+- `transformContentReferences()` - Replace content references
+
+### 4. Navigation Patcher (patch-navigation.mjs)
+Injects workflow navigation footers into transformed prompts.
+
+**Features:**
+- Custom navigation rules from config
+- Default suggestions based on command type
+- Table format: `| /command | Description |`
+- All commands listed at footer
+
+**Default Patterns:**
+- `brainstorm` → suggest: specify, plan.fast
+- `specify/clarify` → suggest: plan, brainstorm
+- `plan` → suggest: cook, tasks
+- `cook/implement` → suggest: test, fix
+- `test` → suggest: fix, review
+
+### 5. Configuration (eng/resource-origins.yml)
+Maintains mappings and sync metadata.
+
+**Key Sections:**
+- `version` - Config format version
+- `synced_at` - Last sync timestamp
+- `sources.speckit` - SpecKit repo location
+- `sources.claudekit` - ClaudeKit local path (~/.claude/commands)
+- `ignore` - Commands to skip
+- `mappings` - 28 command mappings with origins and descriptions
+- `navigation` - Workflow navigation rules
+- `unknown_commands` - Tracking array for unmapped sources
+
+## Prompt Inventory
+
+### ClaudeKit Commands (12)
+12 prompts from ~/.claude/commands/ (plan, fix, test, ask, bootstrap, review, watzup, journal, preview, help, plan.hard, plan.fast)
+
+### SpecKit Commands (8)
+8 prompts from upstream/speckit (specify, clarify, constitution, plan, tasks, implement, analyze, checklist)
+
+## Dependencies
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| chalk | ^5.3.0 | Terminal color output |
+| commander | ^12.0.0 | CLI framework |
+| prompts | ^2.4.2 | Interactive prompts |
+| globby | ^16.1.0 | File globbing (dev) |
+| gray-matter | ^4.0.3 | YAML frontmatter parsing (dev) |
+| js-yaml | ^4.1.1 | YAML parsing (dev) |
+
+## Scripts
+
+```bash
+npm run sync              # Pull upstream + transform
+npm run sync:pull        # git subtree pull SpecKit
+npm run sync:transform   # Run transformations only
+npm run sync:dry-run     # Preview changes without writing
+npm run test             # Run tests
+npm run build            # Update README
+```
+
+## Data Flow
+
+### Sync Operation
+1. **Config Load** - Read resource-origins.yml
+2. **Parallel Transform:**
+   - ClaudeKit: Glob ~/.claude/commands → Transform → Output ck-* prompts
+   - SpecKit: Glob upstream/speckit/templates/commands → Transform → Output ck-* prompts
+3. **Merge** - Combine results (21 total)
+4. **Patch Navigation** - Inject workflow footers
+5. **Write Output** - Create prompt files (prompts/ directory)
+6. **Update Config** - Record sync timestamps
+
+### File Transformation
+```
+Input (ClaudeKit)
+├── Frontmatter: {name: "plan", ...}
+├── Content: "Run $ARGUMENTS using /fix command"
+↓
+Transform
+├── Rename: ck-plan
+├── Replace: $ARGUMENTS → ${input}
+├── Update: /fix → /ck-fix
+├── Remove: model field
+↓
+Output (ck-*)
+├── Frontmatter: {name: "ck-plan", ...}
+├── Content: "Run ${input} using /ck-fix command"
+├── Navigation Footer: "Suggested Next Steps"
+```
+
+## Error Handling
+
+- **Missing ClaudeKit:** Warns if ~/.claude/commands not found, continues gracefully
+- **Missing SpecKit:** Warns if upstream/speckit not found, continues gracefully
+- **File Not Found:** Logs warning per missing file, adds to skipped array
+- **Transform Errors:** Logs errors per command, collects in results.errors
+- **Unknown Commands:** Tracks in config.unknown_commands for manual mapping
+
+## Notable Features
+
+1. **Flexible Source Resolution:** Handles file path variations (index.md, nested dirs)
+2. **Ignore List:** Skip commands via resource-origins.yml
+3. **Dry-run Mode:** Preview all changes before writing
+4. **Navigation Workflow:** Suggested next steps guide users through prompts
+5. **Parallel Processing:** Concurrent ClaudeKit + SpecKit transforms
+6. **Graceful Degradation:** Continues if sources unavailable
+7. **Frontmatter Management:** Preserves metadata, removes model field
+8. **Content Reference Updates:** Transforms all command references to ck-* namespace
+
+## Version History
+
+- **v1.2.0** (Current) - 27 prompts, 12 agents, 27 skills
+- **v1.1.0** - 21 prompts (12 ClaudeKit + 9 SpecKit), SpecKit sync pipeline
+- **v1.0.9** - Comprehensive documentation update
+- **v1.0.8** - Initial release
+
+## Future Considerations
+
+- Integration with GitHub Copilot API
+- Resource validation and linting
+- Custom instruction support
+- Skill marketplace integration
+- Cloud sync capabilities

package/docs/cokit-commands-usage-guide.md

@@ -0,0 +1,138 @@
+# CoKit Commands Usage Guide
+
+When to use which command workflow.
+
+## Quick Reference
+
+| Need | Command | Workflow |
+|------|---------|----------|
+| **Quick implementation** | `ck-plan-fast` | ClaudeKit |
+| **Deep research + plan** | `ck-plan-hard` | ClaudeKit |
+| **Formal spec from idea** | `ck-spec-specify` | SpecKit |
+| **Fix a bug** | `ck-fix` | ClaudeKit |
+| **Run tests** | `ck-test` | ClaudeKit |
+
+---
+
+## Two Workflows
+
+### ClaudeKit (`ck-*`) - Flexible, Fast
+
+Best for: **Day-to-day development**, quick fixes, exploration.
+
+```
+ck-plan-fast → ck-test → ck-fix
+```
+
+**When to use:**
+- Fixing bugs
+- Small features (< 1 day)
+- Prototyping
+- Exploratory coding
+- You know what to build
+
+**Commands:**
+| Command | Description |
+|---------|-------------|
+| `ck-plan` | Create implementation plan |
+| `ck-plan-fast` | Quick plan, no research |
+| `ck-plan-hard` | Deep research + plan |
+| `ck-fix` | Fix issues |
+| `ck-test` | Run tests |
+| `ck-ask` | Answer questions |
+| `ck-review` | Review codebase |
+| `ck-bootstrap` | Start new project |
+
+---
+
+### SpecKit (`ck-spec-*`) - Structured, Rigorous
+
+Best for: **Complex features**, team collaboration, formal requirements.
+
+```
+ck-spec-specify → ck-spec-clarify → ck-spec-plan → ck-spec-tasks → ck-spec-implement
+```
+
+**When to use:**
+- Multi-day features
+- Requirements need formal spec
+- Multiple stakeholders
+- Need traceability
+- Compliance/audit needs
+
+**Commands:**
+| Command | Description |
+|---------|-------------|
+| `ck-spec-specify` | Create formal spec from idea |
+| `ck-spec-clarify` | Ask clarification questions |
+| `ck-spec-plan` | Generate plan from spec |
+| `ck-spec-tasks` | Break plan into tasks |
+| `ck-spec-implement` | Execute tasks |
+| `ck-spec-analyze` | Check consistency |
+| `ck-spec-checklist` | Validate requirements |
+
+---
+
+## Decision Flowchart
+
+```
+Is this a bug fix?
+  └─ Yes → ck-fix
+
+Is this < 4 hours work?
+  └─ Yes → ck-plan-fast
+
+Do you need formal requirements?
+  └─ Yes → ck-spec-specify → ck-spec-* flow
+  └─ No  → ck-plan-hard → ck-* flow
+
+Are you exploring/prototyping?
+  └─ Yes → ck-plan-fast (skip spec)
+```
+
+---
+
+## Example Scenarios
+
+### Scenario 1: Fix a Login Bug
+```
+/ck-fix "Users can't login with email containing +"
+```
+Single command. Done.
+
+### Scenario 2: Add Dark Mode (Small Feature)
+```
+/ck-plan-fast "Add dark mode toggle"
+/ck-test
+/ck-fix  (if tests fail)
+```
+
+### Scenario 3: Payment Integration (Complex Feature)
+```
+/ck-spec-specify "Integrate Stripe payments for subscriptions"
+/ck-spec-clarify  (answer questions about tiers, regions, etc.)
+/ck-spec-plan
+/ck-spec-tasks
+/ck-spec-implement
+/ck-test
+```
+
+---
+
+## Mixing Workflows
+
+You can mix them:
+- Start with `ck-spec-specify` for formal spec
+- Use `ck-fix` when bugs arise during implementation
+- Use `ck-test` regardless of workflow
+
+---
+
+## Summary
+
+| Workflow | Best For | Time | Rigor |
+|----------|----------|------|-------|
+| **ClaudeKit** | Daily dev, fixes | Minutes-Hours | Low-Medium |
+| **SpecKit** | Big features, teams | Days-Weeks | High |
+
+**Rule of thumb:** If you can explain it in one sentence, use ClaudeKit. If you need a doc, use SpecKit.