cokit-cli 1.0.9 → 1.2.0

package/docs/system-architecture.md

@@ -0,0 +1,81 @@
+# CoKit System Architecture
+
+## Overview
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        SOURCES                               │
+├─────────────────────────────────────────────────────────────┤
+│  ClaudeKit (~/.claude/)      SpecKit (upstream/speckit/)    │
+│  ├── commands/               ├── templates/commands/         │
+│  ├── skills/                 └── (git subtree)               │
+│  └── (local install)                                         │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    SYNC PIPELINE (npm run sync)              │
+├─────────────────────────────────────────────────────────────┤
+│  eng/sync.mjs                                                │
+│  ├── Load resource-origins.yml (mappings + ignore list)     │
+│  ├── transform-claudekit.mjs → ck.* namespace               │
+│  ├── transform-speckit.mjs → ck.spec.* namespace            │
+│  ├── patch-navigation.mjs → Add "Suggested Next Steps"      │
+│  └── Write to prompts/                                       │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                       OUTPUT                                 │
+├─────────────────────────────────────────────────────────────┤
+│  prompts/                                                    │
+│  ├── ck-*.prompt.md (28 total commands)                     │
+│  └── agents/, skills/, instructions/, collections/         │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    CLI (npx cokit-cli)                       │
+├─────────────────────────────────────────────────────────────┤
+│  bin/cokit.js → src/index.js                                │
+│  ├── init -g    → Install to ~/.copilot/                    │
+│  ├── init -a    → Install global + project                  │
+│  └── init       → Interactive setup                         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Data Flow
+
+### Sync Pipeline
+```
+1. git subtree pull (SpecKit)
+2. Read ~/.claude/commands/ (ClaudeKit)
+3. Transform: rename, replace $ARGUMENTS, remove model field
+4. Patch: inject navigation footer
+5. Write: prompts/*.prompt.md
+6. Update: resource-origins.yml (timestamps)
+```
+
+### CLI Install
+```
+1. User runs: npx cokit-cli init -g
+2. CLI copies: prompts/, agents/, skills/, instructions/, collections/
+3. Target: ~/.copilot/
+4. User gets: All ck.* commands in Copilot
+```
+
+## Key Components
+
+| Component | File | Purpose |
+|-----------|------|---------|
+| Orchestrator | eng/sync.mjs | Runs full sync pipeline |
+| ClaudeKit Transform | eng/transform-claudekit.mjs | Transform ~/.claude/ commands |
+| SpecKit Transform | eng/transform-speckit.mjs | Transform upstream/speckit/ |
+| Navigation Patch | eng/patch-navigation.mjs | Add cross-command navigation |
+| Config | eng/resource-origins.yml | Mappings, ignore list, navigation |
+
+## Namespace Convention
+
+| Prefix | Source | Example |
+|--------|--------|---------|
+| `ck.*` | ClaudeKit | ck.plan, ck.fix, ck.test |
+| `ck.spec.*` | SpecKit | ck.spec.specify, ck.spec.plan |

package/instructions/ck-backend.instructions.md

@@ -1,48 +1,48 @@
----
-applyTo: "**/*.py,**/*.go,**/*.rs,**/*.java,**/*.cs,**/api/**,**/services/**,**/controllers/**"
-description: "Backend development rules for Python, Go, Rust, Java, C# and API files"
----
-
-# Backend Guidelines
-
-## Input Validation
-
-- Validate all external inputs at boundaries
-- Sanitize before processing
-- Return clear, actionable error messages
-- Never trust client-side validation alone
-
-## Error Handling
-
-- Handle errors explicitly, no silent failures
-- Log at appropriate levels (debug/info/warn/error)
-- Don't expose internal errors or stack traces to clients
-- Use structured error responses with error codes
-
-## Data Integrity
-
-- Use transactions for multi-step operations
-- Validate data consistency at write time
-- Handle concurrent access with proper locking
-- Implement idempotency for critical operations
-
-## External Services
-
-- Rate limit outbound API calls
-- Implement circuit breakers for resilience
-- Handle timeouts gracefully with retries
-- Cache responses when appropriate
-
-## Security
-
-- Parameterize all database queries (no SQL injection)
-- Escape output to prevent XSS
-- Validate file uploads (type, size, content)
-- Use least-privilege for service accounts
-
-## Performance
-
-- Profile before optimizing
-- Use connection pooling for databases
-- Batch operations when possible
-- Index frequently queried fields
+---
+description: 'Backend development rules for Python, Go, Rust, Java, C# and API files'
+applyTo: '**/*.py,**/*.go,**/*.rs,**/*.java,**/*.cs,**/api/**,**/services/**,**/controllers/**'
+---
+
+# Backend Guidelines
+
+## Input Validation
+
+- Validate all external inputs at boundaries
+- Sanitize before processing
+- Return clear, actionable error messages
+- Never trust client-side validation alone
+
+## Error Handling
+
+- Handle errors explicitly, no silent failures
+- Log at appropriate levels (debug/info/warn/error)
+- Don't expose internal errors or stack traces to clients
+- Use structured error responses with error codes
+
+## Data Integrity
+
+- Use transactions for multi-step operations
+- Validate data consistency at write time
+- Handle concurrent access with proper locking
+- Implement idempotency for critical operations
+
+## External Services
+
+- Rate limit outbound API calls
+- Implement circuit breakers for resilience
+- Handle timeouts gracefully with retries
+- Cache responses when appropriate
+
+## Security
+
+- Parameterize all database queries (no SQL injection)
+- Escape output to prevent XSS
+- Validate file uploads (type, size, content)
+- Use least-privilege for service accounts
+
+## Performance
+
+- Profile before optimizing
+- Use connection pooling for databases
+- Batch operations when possible
+- Index frequently queried fields

package/instructions/ck-development.instructions.md

@@ -1,54 +1,54 @@
----
-applyTo: "**/*"
-description: "General development rules applied to all files"
----
-
-# Development Rules
-
-## Principles
-
-- **YAGNI**: Don't add features until needed
-- **KISS**: Prefer simple solutions over complex ones
-- **DRY**: Extract repeated code into reusable functions
-
-## Code Standards
-
-- File size: Keep under 200 lines when practical
-- Naming: kebab-case for files, camelCase for variables
-- No hardcoded secrets or credentials
-- Verify before claiming complete
-
-## Quality Gates
-
-- Run linter before committing
-- All tests must pass
-- No TODO/FIXME without tracking issues
-- Handle errors explicitly
-
-## Security
-
-- Never commit secrets, keys, or credentials
-- Use environment variables for configuration
-- Validate all user inputs
-- Escape outputs to prevent injection
-
-## Git Hygiene
-
-- Atomic commits (one logical change per commit)
-- Conventional commit messages
-- No large binary files in repo
-- Keep branches short-lived
-
-## Permission Check (MUST DO FIRST)
-
-Before creating/editing files, check if you have permission:
-1. **If permission denied:** Ask user to enable:
-   ```
-   ⚠️ I need Write/Edit permission to modify files.
-
-   Please enable it:
-   - VS Code: Click "Allow" when Copilot asks to create/edit files
-   - Ensure workspace is trusted: File → Trust Workspace
-   - Check Copilot Chat settings: Enable file creation/editing
-   ```
-2. **If permission granted:** Proceed with file operations
+---
+description: 'General development rules applied to all files'
+applyTo: '**/*'
+---
+
+# Development Rules
+
+## Principles
+
+- **YAGNI**: Don't add features until needed
+- **KISS**: Prefer simple solutions over complex ones
+- **DRY**: Extract repeated code into reusable functions
+
+## Code Standards
+
+- File size: Keep under 200 lines when practical
+- Naming: kebab-case for files, camelCase for variables
+- No hardcoded secrets or credentials
+- Verify before claiming complete
+
+## Quality Gates
+
+- Run linter before committing
+- All tests must pass
+- No TODO/FIXME without tracking issues
+- Handle errors explicitly
+
+## Security
+
+- Never commit secrets, keys, or credentials
+- Use environment variables for configuration
+- Validate all user inputs
+- Escape outputs to prevent injection
+
+## Git Hygiene
+
+- Atomic commits (one logical change per commit)
+- Conventional commit messages
+- No large binary files in repo
+- Keep branches short-lived
+
+## Permission Check (MUST DO FIRST)
+
+Before creating/editing files, check if you have permission:
+1. **If permission denied:** Ask user to enable:
+   ```
+   ⚠️ I need Write/Edit permission to modify files.
+
+   Please enable it:
+   - VS Code: Click "Allow" when Copilot asks to create/edit files
+   - Ensure workspace is trusted: File → Trust Workspace
+   - Check Copilot Chat settings: Enable file creation/editing
+   ```
+2. **If permission granted:** Proceed with file operations

package/instructions/ck-frontend.instructions.md

@@ -1,44 +1,44 @@
----
-applyTo: "**/*.tsx,**/*.jsx,**/*.vue,**/*.svelte,**/components/**"
-description: "Frontend component guidelines for React, Vue, Svelte"
----
-
-# Frontend Guidelines
-
-## Component Design
-
-- Use functional components with hooks
-- Prefer composition over inheritance
-- Extract reusable components early
-- Keep components focused (single responsibility)
-- Props interface required for TypeScript
-
-## State Management
-
-- Lift state only when necessary
-- Use context for truly global state (auth, theme)
-- Prefer local state when possible
-- Avoid prop drilling beyond 2 levels
-
-## User Experience
-
-- Handle loading states explicitly (skeleton, spinner)
-- Show meaningful error messages to users
-- Use semantic HTML for accessibility
-- Design mobile-first, then scale up
-- Support keyboard navigation
-
-## Performance
-
-- Lazy load large components and routes
-- Memoize expensive calculations (useMemo)
-- Avoid unnecessary re-renders (React.memo)
-- Use virtualization for long lists
-- Optimize images (srcset, lazy loading)
-
-## Accessibility
-
-- All interactive elements keyboard accessible
-- Proper ARIA labels where needed
-- Color contrast meets WCAG AA
-- Focus management for modals/dialogs
+---
+description: 'Frontend component guidelines for React, Vue, Svelte'
+applyTo: '**/*.tsx,**/*.jsx,**/*.vue,**/*.svelte,**/components/**'
+---
+
+# Frontend Guidelines
+
+## Component Design
+
+- Use functional components with hooks
+- Prefer composition over inheritance
+- Extract reusable components early
+- Keep components focused (single responsibility)
+- Props interface required for TypeScript
+
+## State Management
+
+- Lift state only when necessary
+- Use context for truly global state (auth, theme)
+- Prefer local state when possible
+- Avoid prop drilling beyond 2 levels
+
+## User Experience
+
+- Handle loading states explicitly (skeleton, spinner)
+- Show meaningful error messages to users
+- Use semantic HTML for accessibility
+- Design mobile-first, then scale up
+- Support keyboard navigation
+
+## Performance
+
+- Lazy load large components and routes
+- Memoize expensive calculations (useMemo)
+- Avoid unnecessary re-renders (React.memo)
+- Use virtualization for long lists
+- Optimize images (srcset, lazy loading)
+
+## Accessibility
+
+- All interactive elements keyboard accessible
+- Proper ARIA labels where needed
+- Color contrast meets WCAG AA
+- Focus management for modals/dialogs