@cregis-dev/cckit 0.4.0 → 0.5.0

package/templates/ecc/skills/strategic-compact/SKILL.md

@@ -1,103 +0,0 @@
----
-name: strategic-compact
-description: Suggests manual context compaction at logical intervals to preserve context through task phases rather than arbitrary auto-compaction.
-origin: ECC
----
-
-# Strategic Compact Skill
-
-Suggests manual `/compact` at strategic points in your workflow rather than relying on arbitrary auto-compaction.
-
-## When to Activate
-
-- Running long sessions that approach context limits (200K+ tokens)
-- Working on multi-phase tasks (research → plan → implement → test)
-- Switching between unrelated tasks within the same session
-- After completing a major milestone and starting new work
-- When responses slow down or become less coherent (context pressure)
-
-## Why Strategic Compaction?
-
-Auto-compaction triggers at arbitrary points:
-- Often mid-task, losing important context
-- No awareness of logical task boundaries
-- Can interrupt complex multi-step operations
-
-Strategic compaction at logical boundaries:
-- **After exploration, before execution** — Compact research context, keep implementation plan
-- **After completing a milestone** — Fresh start for next phase
-- **Before major context shifts** — Clear exploration context before different task
-
-## How It Works
-
-The `suggest-compact.js` script runs on PreToolUse (Edit/Write) and:
-
-1. **Tracks tool calls** — Counts tool invocations in session
-2. **Threshold detection** — Suggests at configurable threshold (default: 50 calls)
-3. **Periodic reminders** — Reminds every 25 calls after threshold
-
-## Hook Setup
-
-Add to your `~/.claude/settings.json`:
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Edit",
-        "hooks": [{ "type": "command", "command": "node ~/.claude/skills/strategic-compact/suggest-compact.js" }]
-      },
-      {
-        "matcher": "Write",
-        "hooks": [{ "type": "command", "command": "node ~/.claude/skills/strategic-compact/suggest-compact.js" }]
-      }
-    ]
-  }
-}
-```
-
-## Configuration
-
-Environment variables:
-- `COMPACT_THRESHOLD` — Tool calls before first suggestion (default: 50)
-
-## Compaction Decision Guide
-
-Use this table to decide when to compact:
-
-| Phase Transition | Compact? | Why |
-|-----------------|----------|-----|
-| Research → Planning | Yes | Research context is bulky; plan is the distilled output |
-| Planning → Implementation | Yes | Plan is in TodoWrite or a file; free up context for code |
-| Implementation → Testing | Maybe | Keep if tests reference recent code; compact if switching focus |
-| Debugging → Next feature | Yes | Debug traces pollute context for unrelated work |
-| Mid-implementation | No | Losing variable names, file paths, and partial state is costly |
-| After a failed approach | Yes | Clear the dead-end reasoning before trying a new approach |
-
-## What Survives Compaction
-
-Understanding what persists helps you compact with confidence:
-
-| Persists | Lost |
-|----------|------|
-| CLAUDE.md instructions | Intermediate reasoning and analysis |
-| TodoWrite task list | File contents you previously read |
-| Memory files (`~/.claude/memory/`) | Multi-step conversation context |
-| Git state (commits, branches) | Tool call history and counts |
-| Files on disk | Nuanced user preferences stated verbally |
-
-## Best Practices
-
-1. **Compact after planning** — Once plan is finalized in TodoWrite, compact to start fresh
-2. **Compact after debugging** — Clear error-resolution context before continuing
-3. **Don't compact mid-implementation** — Preserve context for related changes
-4. **Read the suggestion** — The hook tells you *when*, you decide *if*
-5. **Write before compacting** — Save important context to files or memory before compacting
-6. **Use `/compact` with a summary** — Add a custom message: `/compact Focus on implementing auth middleware next`
-
-## Related
-
-- [The Longform Guide](https://x.com/affaanmustafa/status/2014040193557471352) — Token optimization section
-- Memory persistence hooks — For state that survives compaction
-- `continuous-learning` skill — Extracts patterns before session ends

package/templates/ecc/skills/strategic-compact/suggest-compact.sh

@@ -1,54 +0,0 @@
-#!/bin/bash
-# Strategic Compact Suggester
-# Runs on PreToolUse or periodically to suggest manual compaction at logical intervals
-#
-# Why manual over auto-compact:
-# - Auto-compact happens at arbitrary points, often mid-task
-# - Strategic compacting preserves context through logical phases
-# - Compact after exploration, before execution
-# - Compact after completing a milestone, before starting next
-#
-# Hook config (in ~/.claude/settings.json):
-# {
-#   "hooks": {
-#     "PreToolUse": [{
-#       "matcher": "Edit|Write",
-#       "hooks": [{
-#         "type": "command",
-#         "command": "~/.claude/skills/strategic-compact/suggest-compact.sh"
-#       }]
-#     }]
-#   }
-# }
-#
-# Criteria for suggesting compact:
-# - Session has been running for extended period
-# - Large number of tool calls made
-# - Transitioning from research/exploration to implementation
-# - Plan has been finalized
-
-# Track tool call count (increment in a temp file)
-# Use CLAUDE_SESSION_ID for session-specific counter (not $$ which changes per invocation)
-SESSION_ID="${CLAUDE_SESSION_ID:-${PPID:-default}}"
-COUNTER_FILE="/tmp/claude-tool-count-${SESSION_ID}"
-THRESHOLD=${COMPACT_THRESHOLD:-50}
-
-# Initialize or increment counter
-if [ -f "$COUNTER_FILE" ]; then
-  count=$(cat "$COUNTER_FILE")
-  count=$((count + 1))
-  echo "$count" > "$COUNTER_FILE"
-else
-  echo "1" > "$COUNTER_FILE"
-  count=1
-fi
-
-# Suggest compact after threshold tool calls
-if [ "$count" -eq "$THRESHOLD" ]; then
-  echo "[StrategicCompact] $THRESHOLD tool calls reached - consider /compact if transitioning phases" >&2
-fi
-
-# Suggest at regular intervals after threshold
-if [ "$count" -gt "$THRESHOLD" ] && [ $((count % 25)) -eq 0 ]; then
-  echo "[StrategicCompact] $count tool calls - good checkpoint for /compact if context is stale" >&2
-fi

package/templates/ecc/skills/swift-actor-persistence/SKILL.md

@@ -1,143 +0,0 @@
----
-name: swift-actor-persistence
-description: Thread-safe data persistence in Swift using actors — in-memory cache with file-backed storage, eliminating data races by design.
-origin: ECC
----
-
-# Swift Actors for Thread-Safe Persistence
-
-Patterns for building thread-safe data persistence layers using Swift actors. Combines in-memory caching with file-backed storage, leveraging the actor model to eliminate data races at compile time.
-
-## When to Activate
-
-- Building a data persistence layer in Swift 5.5+
-- Need thread-safe access to shared mutable state
-- Want to eliminate manual synchronization (locks, DispatchQueues)
-- Building offline-first apps with local storage
-
-## Core Pattern
-
-### Actor-Based Repository
-
-The actor model guarantees serialized access — no data races, enforced by the compiler.
-
-```swift
-public actor LocalRepository<T: Codable & Identifiable> where T.ID == String {
-    private var cache: [String: T] = [:]
-    private let fileURL: URL
-
-    public init(directory: URL = .documentsDirectory, filename: String = "data.json") {
-        self.fileURL = directory.appendingPathComponent(filename)
-        // Synchronous load during init (actor isolation not yet active)
-        self.cache = Self.loadSynchronously(from: fileURL)
-    }
-
-    // MARK: - Public API
-
-    public func save(_ item: T) throws {
-        cache[item.id] = item
-        try persistToFile()
-    }
-
-    public func delete(_ id: String) throws {
-        cache[id] = nil
-        try persistToFile()
-    }
-
-    public func find(by id: String) -> T? {
-        cache[id]
-    }
-
-    public func loadAll() -> [T] {
-        Array(cache.values)
-    }
-
-    // MARK: - Private
-
-    private func persistToFile() throws {
-        let data = try JSONEncoder().encode(Array(cache.values))
-        try data.write(to: fileURL, options: .atomic)
-    }
-
-    private static func loadSynchronously(from url: URL) -> [String: T] {
-        guard let data = try? Data(contentsOf: url),
-              let items = try? JSONDecoder().decode([T].self, from: data) else {
-            return [:]
-        }
-        return Dictionary(uniqueKeysWithValues: items.map { ($0.id, $0) })
-    }
-}
-```
-
-### Usage
-
-All calls are automatically async due to actor isolation:
-
-```swift
-let repository = LocalRepository<Question>()
-
-// Read — fast O(1) lookup from in-memory cache
-let question = await repository.find(by: "q-001")
-let allQuestions = await repository.loadAll()
-
-// Write — updates cache and persists to file atomically
-try await repository.save(newQuestion)
-try await repository.delete("q-001")
-```
-
-### Combining with @Observable ViewModel
-
-```swift
-@Observable
-final class QuestionListViewModel {
-    private(set) var questions: [Question] = []
-    private let repository: LocalRepository<Question>
-
-    init(repository: LocalRepository<Question> = LocalRepository()) {
-        self.repository = repository
-    }
-
-    func load() async {
-        questions = await repository.loadAll()
-    }
-
-    func add(_ question: Question) async throws {
-        try await repository.save(question)
-        questions = await repository.loadAll()
-    }
-}
-```
-
-## Key Design Decisions
-
-| Decision | Rationale |
-|----------|-----------|
-| Actor (not class + lock) | Compiler-enforced thread safety, no manual synchronization |
-| In-memory cache + file persistence | Fast reads from cache, durable writes to disk |
-| Synchronous init loading | Avoids async initialization complexity |
-| Dictionary keyed by ID | O(1) lookups by identifier |
-| Generic over `Codable & Identifiable` | Reusable across any model type |
-| Atomic file writes (`.atomic`) | Prevents partial writes on crash |
-
-## Best Practices
-
-- **Use `Sendable` types** for all data crossing actor boundaries
-- **Keep the actor's public API minimal** — only expose domain operations, not persistence details
-- **Use `.atomic` writes** to prevent data corruption if the app crashes mid-write
-- **Load synchronously in `init`** — async initializers add complexity with minimal benefit for local files
-- **Combine with `@Observable`** ViewModels for reactive UI updates
-
-## Anti-Patterns to Avoid
-
-- Using `DispatchQueue` or `NSLock` instead of actors for new Swift concurrency code
-- Exposing the internal cache dictionary to external callers
-- Making the file URL configurable without validation
-- Forgetting that all actor method calls are `await` — callers must handle async context
-- Using `nonisolated` to bypass actor isolation (defeats the purpose)
-
-## When to Use
-
-- Local data storage in iOS/macOS apps (user data, settings, cached content)
-- Offline-first architectures that sync to a server later
-- Any shared mutable state that multiple parts of the app access concurrently
-- Replacing legacy `DispatchQueue`-based thread safety with modern Swift concurrency

package/templates/ecc/skills/swift-concurrency-6-2/SKILL.md

@@ -1,216 +0,0 @@
----
-name: swift-concurrency-6-2
-description: Swift 6.2 Approachable Concurrency — single-threaded by default, @concurrent for explicit background offloading, isolated conformances for main actor types.
----
-
-# Swift 6.2 Approachable Concurrency
-
-Patterns for adopting Swift 6.2's concurrency model where code runs single-threaded by default and concurrency is introduced explicitly. Eliminates common data-race errors without sacrificing performance.
-
-## When to Activate
-
-- Migrating Swift 5.x or 6.0/6.1 projects to Swift 6.2
-- Resolving data-race safety compiler errors
-- Designing MainActor-based app architecture
-- Offloading CPU-intensive work to background threads
-- Implementing protocol conformances on MainActor-isolated types
-- Enabling Approachable Concurrency build settings in Xcode 26
-
-## Core Problem: Implicit Background Offloading
-
-In Swift 6.1 and earlier, async functions could be implicitly offloaded to background threads, causing data-race errors even in seemingly safe code:
-
-```swift
-// Swift 6.1: ERROR
-@MainActor
-final class StickerModel {
-    let photoProcessor = PhotoProcessor()
-
-    func extractSticker(_ item: PhotosPickerItem) async throws -> Sticker? {
-        guard let data = try await item.loadTransferable(type: Data.self) else { return nil }
-
-        // Error: Sending 'self.photoProcessor' risks causing data races
-        return await photoProcessor.extractSticker(data: data, with: item.itemIdentifier)
-    }
-}
-```
-
-Swift 6.2 fixes this: async functions stay on the calling actor by default.
-
-```swift
-// Swift 6.2: OK — async stays on MainActor, no data race
-@MainActor
-final class StickerModel {
-    let photoProcessor = PhotoProcessor()
-
-    func extractSticker(_ item: PhotosPickerItem) async throws -> Sticker? {
-        guard let data = try await item.loadTransferable(type: Data.self) else { return nil }
-        return await photoProcessor.extractSticker(data: data, with: item.itemIdentifier)
-    }
-}
-```
-
-## Core Pattern — Isolated Conformances
-
-MainActor types can now conform to non-isolated protocols safely:
-
-```swift
-protocol Exportable {
-    func export()
-}
-
-// Swift 6.1: ERROR — crosses into main actor-isolated code
-// Swift 6.2: OK with isolated conformance
-extension StickerModel: @MainActor Exportable {
-    func export() {
-        photoProcessor.exportAsPNG()
-    }
-}
-```
-
-The compiler ensures the conformance is only used on the main actor:
-
-```swift
-// OK — ImageExporter is also @MainActor
-@MainActor
-struct ImageExporter {
-    var items: [any Exportable]
-
-    mutating func add(_ item: StickerModel) {
-        items.append(item)  // Safe: same actor isolation
-    }
-}
-
-// ERROR — nonisolated context can't use MainActor conformance
-nonisolated struct ImageExporter {
-    var items: [any Exportable]
-
-    mutating func add(_ item: StickerModel) {
-        items.append(item)  // Error: Main actor-isolated conformance cannot be used here
-    }
-}
-```
-
-## Core Pattern — Global and Static Variables
-
-Protect global/static state with MainActor:
-
-```swift
-// Swift 6.1: ERROR — non-Sendable type may have shared mutable state
-final class StickerLibrary {
-    static let shared: StickerLibrary = .init()  // Error
-}
-
-// Fix: Annotate with @MainActor
-@MainActor
-final class StickerLibrary {
-    static let shared: StickerLibrary = .init()  // OK
-}
-```
-
-### MainActor Default Inference Mode
-
-Swift 6.2 introduces a mode where MainActor is inferred by default — no manual annotations needed:
-
-```swift
-// With MainActor default inference enabled:
-final class StickerLibrary {
-    static let shared: StickerLibrary = .init()  // Implicitly @MainActor
-}
-
-final class StickerModel {
-    let photoProcessor: PhotoProcessor
-    var selection: [PhotosPickerItem]  // Implicitly @MainActor
-}
-
-extension StickerModel: Exportable {  // Implicitly @MainActor conformance
-    func export() {
-        photoProcessor.exportAsPNG()
-    }
-}
-```
-
-This mode is opt-in and recommended for apps, scripts, and other executable targets.
-
-## Core Pattern — @concurrent for Background Work
-
-When you need actual parallelism, explicitly offload with `@concurrent`:
-
-> **Important:** This example requires Approachable Concurrency build settings — SE-0466 (MainActor default isolation) and SE-0461 (NonisolatedNonsendingByDefault). With these enabled, `extractSticker` stays on the caller's actor, making mutable state access safe. **Without these settings, this code has a data race** — the compiler will flag it.
-
-```swift
-nonisolated final class PhotoProcessor {
-    private var cachedStickers: [String: Sticker] = [:]
-
-    func extractSticker(data: Data, with id: String) async -> Sticker {
-        if let sticker = cachedStickers[id] {
-            return sticker
-        }
-
-        let sticker = await Self.extractSubject(from: data)
-        cachedStickers[id] = sticker
-        return sticker
-    }
-
-    // Offload expensive work to concurrent thread pool
-    @concurrent
-    static func extractSubject(from data: Data) async -> Sticker { /* ... */ }
-}
-
-// Callers must await
-let processor = PhotoProcessor()
-processedPhotos[item.id] = await processor.extractSticker(data: data, with: item.id)
-```
-
-To use `@concurrent`:
-1. Mark the containing type as `nonisolated`
-2. Add `@concurrent` to the function
-3. Add `async` if not already asynchronous
-4. Add `await` at call sites
-
-## Key Design Decisions
-
-| Decision | Rationale |
-|----------|-----------|
-| Single-threaded by default | Most natural code is data-race free; concurrency is opt-in |
-| Async stays on calling actor | Eliminates implicit offloading that caused data-race errors |
-| Isolated conformances | MainActor types can conform to protocols without unsafe workarounds |
-| `@concurrent` explicit opt-in | Background execution is a deliberate performance choice, not accidental |
-| MainActor default inference | Reduces boilerplate `@MainActor` annotations for app targets |
-| Opt-in adoption | Non-breaking migration path — enable features incrementally |
-
-## Migration Steps
-
-1. **Enable in Xcode**: Swift Compiler > Concurrency section in Build Settings
-2. **Enable in SPM**: Use `SwiftSettings` API in package manifest
-3. **Use migration tooling**: Automatic code changes via swift.org/migration
-4. **Start with MainActor defaults**: Enable inference mode for app targets
-5. **Add `@concurrent` where needed**: Profile first, then offload hot paths
-6. **Test thoroughly**: Data-race issues become compile-time errors
-
-## Best Practices
-
-- **Start on MainActor** — write single-threaded code first, optimize later
-- **Use `@concurrent` only for CPU-intensive work** — image processing, compression, complex computation
-- **Enable MainActor inference mode** for app targets that are mostly single-threaded
-- **Profile before offloading** — use Instruments to find actual bottlenecks
-- **Protect globals with MainActor** — global/static mutable state needs actor isolation
-- **Use isolated conformances** instead of `nonisolated` workarounds or `@Sendable` wrappers
-- **Migrate incrementally** — enable features one at a time in build settings
-
-## Anti-Patterns to Avoid
-
-- Applying `@concurrent` to every async function (most don't need background execution)
-- Using `nonisolated` to suppress compiler errors without understanding isolation
-- Keeping legacy `DispatchQueue` patterns when actors provide the same safety
-- Skipping `model.availability` checks in concurrency-related Foundation Models code
-- Fighting the compiler — if it reports a data race, the code has a real concurrency issue
-- Assuming all async code runs in the background (Swift 6.2 default: stays on calling actor)
-
-## When to Use
-
-- All new Swift 6.2+ projects (Approachable Concurrency is the recommended default)
-- Migrating existing apps from Swift 5.x or 6.0/6.1 concurrency
-- Resolving data-race safety compiler errors during Xcode 26 adoption
-- Building MainActor-centric app architectures (most UI apps)
-- Performance optimization — offloading specific heavy computations to background