@cregis-dev/cckit 0.2.0

package/templates/ecc/skills/springboot-tdd/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: springboot-tdd
+description: Test-driven development for Spring Boot using JUnit 5, Mockito, MockMvc, Testcontainers, and JaCoCo. Use when adding features, fixing bugs, or refactoring.
+---
+
+# Spring Boot TDD Workflow
+
+TDD guidance for Spring Boot services with 80%+ coverage (unit + integration).
+
+## When to Use
+
+- New features or endpoints
+- Bug fixes or refactors
+- Adding data access logic or security rules
+
+## Workflow
+
+1) Write tests first (they should fail)
+2) Implement minimal code to pass
+3) Refactor with tests green
+4) Enforce coverage (JaCoCo)
+
+## Unit Tests (JUnit 5 + Mockito)
+
+```java
+@ExtendWith(MockitoExtension.class)
+class MarketServiceTest {
+  @Mock MarketRepository repo;
+  @InjectMocks MarketService service;
+
+  @Test
+  void createsMarket() {
+    CreateMarketRequest req = new CreateMarketRequest("name", "desc", Instant.now(), List.of("cat"));
+    when(repo.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+    Market result = service.create(req);
+
+    assertThat(result.name()).isEqualTo("name");
+    verify(repo).save(any());
+  }
+}
+```
+
+Patterns:
+- Arrange-Act-Assert
+- Avoid partial mocks; prefer explicit stubbing
+- Use `@ParameterizedTest` for variants
+
+## Web Layer Tests (MockMvc)
+
+```java
+@WebMvcTest(MarketController.class)
+class MarketControllerTest {
+  @Autowired MockMvc mockMvc;
+  @MockBean MarketService marketService;
+
+  @Test
+  void returnsMarkets() throws Exception {
+    when(marketService.list(any())).thenReturn(Page.empty());
+
+    mockMvc.perform(get("/api/markets"))
+        .andExpect(status().isOk())
+        .andExpect(jsonPath("$.content").isArray());
+  }
+}
+```
+
+## Integration Tests (SpringBootTest)
+
+```java
+@SpringBootTest
+@AutoConfigureMockMvc
+@ActiveProfiles("test")
+class MarketIntegrationTest {
+  @Autowired MockMvc mockMvc;
+
+  @Test
+  void createsMarket() throws Exception {
+    mockMvc.perform(post("/api/markets")
+        .contentType(MediaType.APPLICATION_JSON)
+        .content("""
+          {"name":"Test","description":"Desc","endDate":"2030-01-01T00:00:00Z","categories":["general"]}
+        """))
+      .andExpect(status().isCreated());
+  }
+}
+```
+
+## Persistence Tests (DataJpaTest)
+
+```java
+@DataJpaTest
+@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
+@Import(TestContainersConfig.class)
+class MarketRepositoryTest {
+  @Autowired MarketRepository repo;
+
+  @Test
+  void savesAndFinds() {
+    MarketEntity entity = new MarketEntity();
+    entity.setName("Test");
+    repo.save(entity);
+
+    Optional<MarketEntity> found = repo.findByName("Test");
+    assertThat(found).isPresent();
+  }
+}
+```
+
+## Testcontainers
+
+- Use reusable containers for Postgres/Redis to mirror production
+- Wire via `@DynamicPropertySource` to inject JDBC URLs into Spring context
+
+## Coverage (JaCoCo)
+
+Maven snippet:
+```xml
+<plugin>
+  <groupId>org.jacoco</groupId>
+  <artifactId>jacoco-maven-plugin</artifactId>
+  <version>0.8.14</version>
+  <executions>
+    <execution>
+      <goals><goal>prepare-agent</goal></goals>
+    </execution>
+    <execution>
+      <id>report</id>
+      <phase>verify</phase>
+      <goals><goal>report</goal></goals>
+    </execution>
+  </executions>
+</plugin>
+```
+
+## Assertions
+
+- Prefer AssertJ (`assertThat`) for readability
+- For JSON responses, use `jsonPath`
+- For exceptions: `assertThatThrownBy(...)`
+
+## Test Data Builders
+
+```java
+class MarketBuilder {
+  private String name = "Test";
+  MarketBuilder withName(String name) { this.name = name; return this; }
+  Market build() { return new Market(null, name, MarketStatus.ACTIVE); }
+}
+```
+
+## CI Commands
+
+- Maven: `mvn -T 4 test` or `mvn verify`
+- Gradle: `./gradlew test jacocoTestReport`
+
+**Remember**: Keep tests fast, isolated, and deterministic. Test behavior, not implementation details.

package/templates/ecc/skills/springboot-verification/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: springboot-verification
+description: "Verification loop for Spring Boot projects: build, static analysis, tests with coverage, security scans, and diff review before release or PR."
+---
+
+# Spring Boot Verification Loop
+
+Run before PRs, after major changes, and pre-deploy.
+
+## When to Activate
+
+- Before opening a pull request for a Spring Boot service
+- After major refactoring or dependency upgrades
+- Pre-deployment verification for staging or production
+- Running full build → lint → test → security scan pipeline
+- Validating test coverage meets thresholds
+
+## Phase 1: Build
+
+```bash
+mvn -T 4 clean verify -DskipTests
+# or
+./gradlew clean assemble -x test
+```
+
+If build fails, stop and fix.
+
+## Phase 2: Static Analysis
+
+Maven (common plugins):
+```bash
+mvn -T 4 spotbugs:check pmd:check checkstyle:check
+```
+
+Gradle (if configured):
+```bash
+./gradlew checkstyleMain pmdMain spotbugsMain
+```
+
+## Phase 3: Tests + Coverage
+
+```bash
+mvn -T 4 test
+mvn jacoco:report   # verify 80%+ coverage
+# or
+./gradlew test jacocoTestReport
+```
+
+Report:
+- Total tests, passed/failed
+- Coverage % (lines/branches)
+
+### Unit Tests
+
+Test service logic in isolation with mocked dependencies:
+
+```java
+@ExtendWith(MockitoExtension.class)
+class UserServiceTest {
+
+  @Mock private UserRepository userRepository;
+  @InjectMocks private UserService userService;
+
+  @Test
+  void createUser_validInput_returnsUser() {
+    var dto = new CreateUserDto("Alice", "alice@example.com");
+    var expected = new User(1L, "Alice", "alice@example.com");
+    when(userRepository.save(any(User.class))).thenReturn(expected);
+
+    var result = userService.create(dto);
+
+    assertThat(result.name()).isEqualTo("Alice");
+    verify(userRepository).save(any(User.class));
+  }
+
+  @Test
+  void createUser_duplicateEmail_throwsException() {
+    var dto = new CreateUserDto("Alice", "existing@example.com");
+    when(userRepository.existsByEmail(dto.email())).thenReturn(true);
+
+    assertThatThrownBy(() -> userService.create(dto))
+        .isInstanceOf(DuplicateEmailException.class);
+  }
+}
+```
+
+### Integration Tests with Testcontainers
+
+Test against a real database instead of H2:
+
+```java
+@SpringBootTest
+@Testcontainers
+class UserRepositoryIntegrationTest {
+
+  @Container
+  static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine")
+      .withDatabaseName("testdb");
+
+  @DynamicPropertySource
+  static void configureProperties(DynamicPropertyRegistry registry) {
+    registry.add("spring.datasource.url", postgres::getJdbcUrl);
+    registry.add("spring.datasource.username", postgres::getUsername);
+    registry.add("spring.datasource.password", postgres::getPassword);
+  }
+
+  @Autowired private UserRepository userRepository;
+
+  @Test
+  void findByEmail_existingUser_returnsUser() {
+    userRepository.save(new User("Alice", "alice@example.com"));
+
+    var found = userRepository.findByEmail("alice@example.com");
+
+    assertThat(found).isPresent();
+    assertThat(found.get().getName()).isEqualTo("Alice");
+  }
+}
+```
+
+### API Tests with MockMvc
+
+Test controller layer with full Spring context:
+
+```java
+@WebMvcTest(UserController.class)
+class UserControllerTest {
+
+  @Autowired private MockMvc mockMvc;
+  @MockBean private UserService userService;
+
+  @Test
+  void createUser_validInput_returns201() throws Exception {
+    var user = new UserDto(1L, "Alice", "alice@example.com");
+    when(userService.create(any())).thenReturn(user);
+
+    mockMvc.perform(post("/api/users")
+            .contentType(MediaType.APPLICATION_JSON)
+            .content("""
+                {"name": "Alice", "email": "alice@example.com"}
+                """))
+        .andExpect(status().isCreated())
+        .andExpect(jsonPath("$.name").value("Alice"));
+  }
+
+  @Test
+  void createUser_invalidEmail_returns400() throws Exception {
+    mockMvc.perform(post("/api/users")
+            .contentType(MediaType.APPLICATION_JSON)
+            .content("""
+                {"name": "Alice", "email": "not-an-email"}
+                """))
+        .andExpect(status().isBadRequest());
+  }
+}
+```
+
+## Phase 4: Security Scan
+
+```bash
+# Dependency CVEs
+mvn org.owasp:dependency-check-maven:check
+# or
+./gradlew dependencyCheckAnalyze
+
+# Secrets in source
+grep -rn "password\s*=\s*\"" src/ --include="*.java" --include="*.yml" --include="*.properties"
+grep -rn "sk-\|api_key\|secret" src/ --include="*.java" --include="*.yml"
+
+# Secrets (git history)
+git secrets --scan  # if configured
+```
+
+### Common Security Findings
+
+```
+# Check for System.out.println (use logger instead)
+grep -rn "System\.out\.print" src/main/ --include="*.java"
+
+# Check for raw exception messages in responses
+grep -rn "e\.getMessage()" src/main/ --include="*.java"
+
+# Check for wildcard CORS
+grep -rn "allowedOrigins.*\*" src/main/ --include="*.java"
+```
+
+## Phase 5: Lint/Format (optional gate)
+
+```bash
+mvn spotless:apply   # if using Spotless plugin
+./gradlew spotlessApply
+```
+
+## Phase 6: Diff Review
+
+```bash
+git diff --stat
+git diff
+```
+
+Checklist:
+- No debugging logs left (`System.out`, `log.debug` without guards)
+- Meaningful errors and HTTP statuses
+- Transactions and validation present where needed
+- Config changes documented
+
+## Output Template
+
+```
+VERIFICATION REPORT
+===================
+Build:     [PASS/FAIL]
+Static:    [PASS/FAIL] (spotbugs/pmd/checkstyle)
+Tests:     [PASS/FAIL] (X/Y passed, Z% coverage)
+Security:  [PASS/FAIL] (CVE findings: N)
+Diff:      [X files changed]
+
+Overall:   [READY / NOT READY]
+
+Issues to Fix:
+1. ...
+2. ...
+```
+
+## Continuous Mode
+
+- Re-run phases on significant changes or every 30–60 minutes in long sessions
+- Keep a short loop: `mvn -T 4 test` + spotbugs for quick feedback
+
+**Remember**: Fast feedback beats late surprises. Keep the gate strict—treat warnings as defects in production systems.

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

@@ -0,0 +1,102 @@
+---
+name: strategic-compact
+description: Suggests manual context compaction at logical intervals to preserve context through task phases rather than arbitrary auto-compaction.
+---
+
+# 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

@@ -0,0 +1,54 @@
+#!/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

@@ -0,0 +1,142 @@
+---
+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.
+---
+
+# 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