@stella-studio/ck 1.0.0

package/install-stlck.sh

@@ -0,0 +1,163 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ============================================================
+# Stella Studio CK - Installer
+# Installs stlck wrapper and ck from mirror
+# ============================================================
+
+INSTALL_DIR="${HOME}/.local/bin"
+STLCK_URL="https://raw.githubusercontent.com/Stella-Studio/CK/main/bin/stlck"
+MIRROR_REPO="git+https://github.com/Stella-Studio/CK.git"
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+log_info() {
+    echo -e "${GREEN}[installer]${NC} $*"
+}
+
+log_error() {
+    echo -e "${RED}[installer]${NC} $*" >&2
+}
+
+log_warn() {
+    echo -e "${YELLOW}[installer]${NC} $*"
+}
+
+log_step() {
+    echo -e "${BLUE}==>${NC} $*"
+}
+
+# Check prerequisites
+check_prereqs() {
+    log_step "Checking prerequisites..."
+
+    if ! command -v npm &>/dev/null; then
+        log_error "npm not found. Please install Node.js first:"
+        log_error "  https://nodejs.org/"
+        exit 1
+    fi
+
+    if ! command -v git &>/dev/null; then
+        log_error "git not found. Please install git first:"
+        log_error "  https://git-scm.com/"
+        exit 1
+    fi
+
+    log_info "✓ npm $(npm --version)"
+    log_info "✓ git $(git --version | head -1)"
+}
+
+# Install ck from mirror
+install_ck() {
+    log_step "Installing ck from mirror..."
+    log_info "Repository: Stella-Studio/CK"
+
+    if npm install -g "$MIRROR_REPO" --force; then
+        CK_VERSION=$(ck --version 2>/dev/null | grep -oP '\d+\.\d+\.\d+' || echo "unknown")
+        log_info "✓ ck installed: v$CK_VERSION"
+    else
+        log_error "Failed to install ck from mirror"
+        exit 1
+    fi
+}
+
+# Install stlck wrapper
+install_stlck() {
+    log_step "Installing stlck wrapper..."
+
+    # Create install directory
+    mkdir -p "$INSTALL_DIR"
+
+    # Download or copy stlck script
+    STLCK_PATH="$INSTALL_DIR/stlck"
+
+    # Check if running from local repo
+    if [[ -f "$(dirname "$0")/bin/stlck" ]]; then
+        log_info "Using local stlck script"
+        cp "$(dirname "$0")/bin/stlck" "$STLCK_PATH"
+    else
+        log_info "Downloading stlck from GitHub..."
+        if ! curl -fsSL "$STLCK_URL" -o "$STLCK_PATH"; then
+            log_error "Failed to download stlck wrapper"
+            exit 1
+        fi
+    fi
+
+    chmod +x "$STLCK_PATH"
+    log_info "✓ stlck installed: $STLCK_PATH"
+}
+
+# Setup PATH
+setup_path() {
+    log_step "Setting up PATH..."
+
+    # Detect shell
+    SHELL_RC=""
+    if [[ -n "${BASH_VERSION:-}" ]]; then
+        SHELL_RC="$HOME/.bashrc"
+    elif [[ -n "${ZSH_VERSION:-}" ]]; then
+        SHELL_RC="$HOME/.zshrc"
+    else
+        SHELL_RC="$HOME/.profile"
+    fi
+
+    # Check if already in PATH
+    if [[ ":$PATH:" == *":$INSTALL_DIR:"* ]]; then
+        log_info "✓ $INSTALL_DIR already in PATH"
+        return
+    fi
+
+    # Add to PATH
+    echo "" >> "$SHELL_RC"
+    echo "# Stella Studio CK" >> "$SHELL_RC"
+    echo "export PATH=\"\$HOME/.local/bin:\$PATH\"" >> "$SHELL_RC"
+
+    log_info "✓ Added to PATH in $SHELL_RC"
+    log_warn "⚠️  Run: source $SHELL_RC"
+}
+
+# Post-install info
+post_install() {
+    log_step "Installation complete!"
+    echo ""
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo -e "${GREEN}Stella Studio CK${NC} installed successfully!"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo ""
+    echo "📦 Installation directory: $INSTALL_DIR"
+    echo "🔄 Mirror repository: Stella-Studio/CK"
+    echo "⚡ Sync frequency: Every 5 minutes"
+    echo ""
+    echo "Next steps:"
+    echo "  1. Reload shell:  source $SHELL_RC"
+    echo "  2. Verify:        stlck version"
+    echo "  3. Get started:   stlck init"
+    echo "  4. Update:        stlck update"
+    echo ""
+    echo "Documentation:"
+    echo "  https://github.com/Stella-Studio/CK"
+    echo ""
+}
+
+# Main
+main() {
+    echo ""
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo -e "   ${GREEN}Stella Studio CK${NC} Installer"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo ""
+
+    check_prereqs
+    install_ck
+    install_stlck
+    setup_path
+    post_install
+}
+
+main "$@"

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@stella-studio/ck",
+  "version": "1.0.0",
+  "description": "Stella Studio ClaudeKit - Mirror distribution CLI wrapper",
+  "bin": {
+    "stlck": "./bin/stlck"
+  },
+  "scripts": {
+    "postinstall": "echo '\n✅ stlck installed! Try: stlck init\n'"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Stella-Studio/CK.git"
+  },
+  "keywords": ["claudekit", "cli", "stella-studio", "mirror"],
+  "author": "Stella Studio",
+  "license": "MIT"
+}

package/plans/templates/bug-fix-template.md

@@ -0,0 +1,69 @@
+# [Bug Fix] Implementation Plan
+
+**Date**: YYYY-MM-DD  
+**Type**: Bug Fix  
+**Priority**: [Critical/High/Medium/Low]  
+**Context Tokens**: <150 words
+
+## Executive Summary
+Brief description of the bug and its impact.
+
+## Issue Analysis
+### Symptoms
+- [ ] Symptom 1
+- [ ] Symptom 2
+
+### Root Cause
+Brief explanation of the underlying cause.
+
+### Evidence
+- **Logs**: Reference to log files (don't include full logs)
+- **Error Messages**: Key error patterns
+- **Affected Components**: List of impacted files/modules
+
+## Context Links
+- **Related Issues**: [GitHub issue numbers]
+- **Recent Changes**: [Relevant commits or PRs]
+- **Dependencies**: [Related systems]
+
+## Solution Design
+### Approach
+High-level fix strategy in 2-3 sentences.
+
+### Changes Required
+1. **File 1** (`path/to/file.ts`): Brief change description
+2. **File 2** (`path/to/file.ts`): Brief change description
+
+### Testing Changes
+- [ ] Update existing tests
+- [ ] Add new test cases
+- [ ] Validate fix doesn't break existing functionality
+
+## Implementation Steps
+1. [ ] Step 1 - file: `path/to/file.ts`
+2. [ ] Step 2 - file: `path/to/file.ts`
+3. [ ] Run test suite
+4. [ ] Validate fix in relevant environments
+
+## Verification Plan
+### Test Cases
+- [ ] Test case 1: Expected behavior
+- [ ] Test case 2: Edge case handling
+- [ ] Regression test: Ensure no new issues
+
+### Rollback Plan
+If the fix causes issues:
+1. Revert commit: `git revert <commit-hash>`
+2. Restore previous behavior in files X, Y, Z
+
+## Risk Assessment
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| Risk 1 | Medium | Mitigation plan |
+
+## TODO Checklist
+- [ ] Implement fix
+- [ ] Update tests
+- [ ] Run full test suite
+- [ ] Code review
+- [ ] Deploy and verify

package/plans/templates/feature-implementation-template.md

@@ -0,0 +1,84 @@
+# [Feature Name] Implementation Plan
+
+**Date**: YYYY-MM-DD  
+**Type**: Feature Implementation  
+**Status**: Planning  
+**Context Tokens**: <200 words
+
+## Executive Summary
+Brief 2-3 sentence description of the feature and its business value.
+
+## Context Links
+- **Related Plans**: [List other plan files - no full content]
+- **Dependencies**: [External systems, APIs, existing features]
+- **Reference Docs**: [Link to docs in ./docs directory]
+
+## Requirements
+### Functional Requirements
+- [ ] Requirement 1
+- [ ] Requirement 2
+
+### Non-Functional Requirements  
+- [ ] Performance target
+- [ ] Security requirement
+- [ ] Scalability requirement
+
+## Architecture Overview
+```mermaid
+[Simple component diagram]
+```
+
+### Key Components
+- **Component 1**: Brief description
+- **Component 2**: Brief description
+
+### Data Models
+- **Model 1**: Key fields
+- **Model 2**: Key fields
+
+## Implementation Phases
+
+### Phase 1: [Name] (Est: X days)
+**Scope**: Specific boundaries
+**Tasks**:
+1. [ ] Task 1 - file: `path/to/file.ts`
+2. [ ] Task 2 - file: `path/to/file.ts`
+
+**Acceptance Criteria**:
+- [ ] Criteria 1
+- [ ] Criteria 2
+
+### Phase 2: [Name] (Est: X days)
+[Repeat structure]
+
+## Testing Strategy
+- **Unit Tests**: Specific test coverage targets
+- **Integration Tests**: Key interaction points
+- **E2E Tests**: Critical user flows
+
+## Security Considerations
+- [ ] Security item 1
+- [ ] Security item 2
+
+## Risk Assessment
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| Risk 1 | High | Mitigation strategy |
+
+## Quick Reference
+### Key Commands
+```bash
+npm run command
+```
+
+### Configuration Files
+- `config/file.ts`: Purpose
+- `.env.example`: Environment variables
+
+## TODO Checklist
+- [ ] Phase 1 Task 1
+- [ ] Phase 1 Task 2
+- [ ] Phase 2 Task 1
+- [ ] Testing complete
+- [ ] Documentation updated
+- [ ] Code review passed

package/plans/templates/refactor-template.md

@@ -0,0 +1,82 @@
+# [Component/Module] Refactoring Plan
+
+**Date**: YYYY-MM-DD  
+**Type**: Refactoring  
+**Scope**: [Module/Component/System level]  
+**Context Tokens**: <200 words
+
+## Executive Summary
+Brief description of what is being refactored and why.
+
+## Current State Analysis
+### Issues with Current Implementation
+- [ ] Issue 1: Performance bottleneck
+- [ ] Issue 2: Code maintainability
+- [ ] Issue 3: Technical debt
+
+### Metrics (Before)
+- **Performance**: Current benchmarks
+- **Code Quality**: Complexity metrics
+- **Test Coverage**: Current percentage
+
+## Context Links
+- **Affected Modules**: [List without full content]
+- **Dependencies**: [Other systems impacted]
+- **Related Documentation**: [Links to docs]
+
+## Refactoring Strategy
+### Approach
+High-level strategy for the refactoring in 2-3 sentences.
+
+### Architecture Changes
+```mermaid
+[Before/After comparison diagram]
+```
+
+### Key Improvements
+- **Improvement 1**: Brief description
+- **Improvement 2**: Brief description
+
+## Implementation Plan
+
+### Phase 1: Preparation (Est: X days)
+**Scope**: Setup and preparation work
+1. [ ] Create comprehensive tests for current functionality
+2. [ ] Document current behavior
+3. [ ] Identify all dependencies
+
+### Phase 2: Core Refactoring (Est: X days)
+**Scope**: Main refactoring work
+1. [ ] Refactor component A - file: `path/to/file.ts`
+2. [ ] Refactor component B - file: `path/to/file.ts`
+3. [ ] Update integration points
+
+### Phase 3: Integration & Testing (Est: X days)
+**Scope**: Validation and cleanup
+1. [ ] Integration testing
+2. [ ] Performance validation
+3. [ ] Documentation updates
+
+## Backward Compatibility
+- **Breaking Changes**: [List any breaking changes]
+- **Migration Path**: [Steps for users/systems]
+- **Deprecation Timeline**: [If applicable]
+
+## Success Metrics (After)
+- **Performance**: Target improvements
+- **Code Quality**: Target metrics
+- **Test Coverage**: Target percentage
+
+## Risk Assessment
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| Breaking changes | High | Comprehensive testing |
+| Performance regression | Medium | Benchmarking |
+
+## TODO Checklist
+- [ ] Phase 1: Preparation complete
+- [ ] Phase 2: Core refactoring complete  
+- [ ] Phase 3: Integration complete
+- [ ] Performance benchmarks validated
+- [ ] Documentation updated
+- [ ] Code review passed

package/plans/templates/template-usage-guide.md

@@ -0,0 +1,58 @@
+# Plan Template Usage Guide
+
+## Template Selection
+
+### Feature Implementation Template
+**Use when**: Adding new functionality, endpoints, services, or modules
+**File**: `feature-implementation-template.md`
+**Size**: Medium to large scope changes
+
+### Bug Fix Template  
+**Use when**: Fixing specific issues, errors, or broken functionality
+**File**: `bug-fix-template.md`
+**Size**: Small to medium scope changes
+
+### Refactoring Template
+**Use when**: Improving code structure, performance, or maintainability without changing functionality
+**File**: `refactor-template.md` 
+**Size**: Medium to large scope changes
+
+## Context Management Best Practices
+
+### Keep Plans Focused
+- **Executive Summary**: Max 3 sentences
+- **Context Links**: Reference files, don't include full content
+- **Tasks**: Max 10 per phase
+- **Context Tokens**: Target <200 words for summaries
+
+### Template Adaptation
+1. Copy the appropriate template to `plans/YYMMDD-feature-name-plan.md`
+2. Replace bracketed placeholders with actual content
+3. Remove sections not relevant to your specific use case
+4. Keep the core structure intact for consistency
+
+### Cross-References Instead of Duplication
+- Link to existing documentation in `./docs/`
+- Reference other plans without copying content
+- Use file paths instead of code blocks where possible
+- Focus on "what" and "why", not detailed "how"
+
+## Quality Checklist
+
+Before finalizing any plan:
+- [ ] Executive summary is clear and concise
+- [ ] Tasks are specific and actionable
+- [ ] File paths are included for implementation tasks
+- [ ] Success criteria are measurable
+- [ ] Context links are used instead of full content
+- [ ] TODO checklist is complete and realistic
+
+## Context Refresh Triggers
+
+Use these templates when:
+- Starting a new development phase
+- Switching between different types of work (feature → bugfix)
+- After major context accumulation (>8000 tokens)
+- When agent handoffs occur
+
+This ensures each plan starts with fresh, focused context optimized for the specific task type.