oh-my-customcodex 0.1.0

package/templates/.claude/skills/kafka-best-practices/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: kafka-best-practices
+description: Apache Kafka best practices for event streaming, topic design, and producer-consumer patterns
+scope: core
+user-invocable: false
+---
+
+# Apache Kafka Best Practices
+
+## Producer Patterns
+
+### Idempotent Producer (CRITICAL)
+- Enable `enable.idempotence=true`
+- Prevents duplicate messages
+- Requires `acks=all`, `retries > 0`, `max.in.flight.requests.per.connection <= 5`
+
+### Exactly-Once Semantics
+- Use transactional API: `initTransactions()`, `beginTransaction()`, `commitTransaction()`
+- For exactly-once end-to-end processing
+
+### Performance
+- Batching: `linger.ms` (wait for batch to fill)
+- Compression: `compression.type=snappy` or `lz4`
+- `batch.size`: 16KB default, tune based on message size
+
+## Consumer Patterns
+
+### Offset Management
+- Auto-commit: `enable.auto.commit=true` (at-least-once)
+- Manual commit: `commitSync()` or `commitAsync()` (better control)
+
+### Rebalancing
+- Cooperative sticky assignor: minimal rebalancing disruption
+- `session.timeout.ms` and `heartbeat.interval.ms` tuning
+
+### At-Least-Once vs Exactly-Once
+- At-least-once: default, idempotent processing required
+- Exactly-once: transactional consumer + producer
+
+## Topic Design
+
+### Partitioning
+- Partition count: based on throughput (MB/s ÷ partition throughput)
+- Key-based partitioning for ordering guarantees
+- More partitions = higher throughput (but more overhead)
+
+### Retention
+- Time-based: `retention.ms`
+- Size-based: `retention.bytes`
+- Log compaction: for changelog topics (`cleanup.policy=compact`)
+
+## References
+- [Kafka Documentation](https://kafka.apache.org/documentation/)

package/templates/.claude/skills/kotlin-best-practices/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: kotlin-best-practices
+description: Idiomatic Kotlin patterns from JetBrains conventions
+scope: core
+user-invocable: false
+---
+
+## Purpose
+
+Apply idiomatic Kotlin patterns and best practices from official JetBrains documentation.
+
+## Core Principles
+
+```
+Concise yet readable
+Null safety by design
+Interoperability with Java
+Functional when appropriate
+```
+
+## Rules
+
+### 1. Naming Conventions
+
+```yaml
+packages:
+  style: lowercase, no underscores
+  example: org.example.project
+
+classes_objects:
+  style: UpperCamelCase
+  example: DeclarationProcessor
+
+functions_variables:
+  style: lowerCamelCase
+  example: processDeclarations, declarationCount
+
+constants:
+  style: SCREAMING_SNAKE_CASE
+  example: const val MAX_COUNT = 8
+
+backing_properties:
+  style: underscore prefix
+  example: private val _elementList
+
+acronyms:
+  two_letters: both uppercase (IOStream)
+  three_plus: capitalize first only (XmlFormatter)
+```
+
+### 2. Source File Organization
+
+```yaml
+file_naming:
+  single_class: name after the class (MyClass.kt)
+  multiple_classes: descriptive UpperCamelCase (ProcessDeclarations.kt)
+  platform_specific: add suffix (Platform.jvm.kt)
+
+class_layout:
+  1: Property declarations and initializer blocks
+  2: Secondary constructors
+  3: Method declarations
+  4: Companion object
+
+directory_structure:
+  - Follow package structure with common root omitted
+  - Example: org.example.kotlin.network → network/
+```
+
+### 3. Formatting
+
+```yaml
+indentation:
+  - 4 spaces (no tabs)
+  - Opening brace at end of line
+  - Closing brace on separate line
+
+horizontal_whitespace:
+  around_binary_operators: "a + b"
+  no_around_range: "0..i"
+  no_around_unary: "a++"
+  after_control_keywords: "if (condition)"
+  no_before_parentheses: "method()"
+  never_around_dot: "foo.bar()"
+
+colons:
+  type_supertype: "class Foo : Bar"
+  declaration_type: "val x: Int"
+  always_space_after: true
+
+trailing_commas:
+  recommended: true
+  reason: cleaner diffs, easier reordering
+```
+
+### 4. Functions
+
+```yaml
+expression_bodies:
+  prefer: "fun foo() = 1"
+  over: |
+    fun foo(): Int {
+        return 1
+    }
+
+default_parameters:
+  prefer: "fun foo(a: String = \"a\")"
+  over: overloaded functions
+
+single_line_signatures:
+  if_fits: "fun foo(a: Int): String = ..."
+  otherwise: |
+    fun longMethodName(
+        argument: ArgumentType = defaultValue,
+        argument2: AnotherArgumentType,
+    ): ReturnType { }
+
+unit_return:
+  avoid: "fun foo(): Unit { }"
+  prefer: "fun foo() { }"
+```
+
+### 5. Null Safety
+
+```yaml
+principles:
+  - Prefer non-null types by default
+  - Use ? only when nullability is meaningful
+  - Leverage safe calls (?.) and elvis (?:)
+
+patterns: |
+  // Safe call
+  val length = text?.length
+
+  // Elvis operator
+  val name = user?.name ?: "Anonymous"
+
+  // Let for null checks
+  user?.let {
+      println(it.name)
+  }
+
+  // Not-null assertion (use sparingly)
+  val name = user!!.name
+```
+
+### 6. Idiomatic Patterns
+
+```yaml
+immutability:
+  prefer: "val over var"
+  collections: "listOf() over arrayListOf()"
+
+conditionals:
+  binary: use if
+  multiple: use when
+
+  patterns: |
+    // if expression
+    return if (x) foo() else bar()
+
+    // when expression
+    return when(x) {
+        0 -> "zero"
+        else -> "nonzero"
+    }
+
+functional:
+  prefer: "list.filter { it > 10 }.map { it * 2 }"
+  over: manual loops (except forEach)
+
+ranges:
+  prefer: "for (i in 0..<n)"
+  avoid: "for (i in 0..n - 1)"
+
+type_aliases:
+  use_for: |
+    typealias MouseClickHandler = (Any, MouseEvent) -> Unit
+    typealias PersonIndex = Map<String, Person>
+```
+
+### 7. Lambdas
+
+```yaml
+formatting:
+  - Spaces around curly braces: "list.filter { it > 10 }"
+  - Single lambda outside parentheses
+  - it for single parameter
+
+patterns: |
+  // Outside parentheses
+  list.filter { it > 10 }
+
+  // Multiple parameters
+  list.fold(0) { acc, item -> acc + item }
+
+  // Destructuring
+  map.forEach { (key, value) -> println("$key = $value") }
+```
+
+### 8. Coroutines
+
+```yaml
+principles:
+  - Use suspend functions for async operations
+  - Structured concurrency with scopes
+  - Proper exception handling
+
+patterns: |
+  // Suspend function
+  suspend fun fetchData(): Data {
+      return withContext(Dispatchers.IO) {
+          api.getData()
+      }
+  }
+
+  // Coroutine scope
+  lifecycleScope.launch {
+      val data = fetchData()
+      updateUI(data)
+  }
+
+  // Exception handling
+  try {
+      val result = async { fetchData() }.await()
+  } catch (e: Exception) {
+      handleError(e)
+  }
+```
+
+### 9. Documentation
+
+```yaml
+format: |
+  /**
+   * Returns the absolute value of the given [number].
+   */
+  fun abs(number: Int): Int { ... }
+
+best_practices:
+  - Incorporate parameters into description
+  - Use brackets for parameter references
+  - Use @param/@return only for lengthy descriptions
+```
+
+## Application
+
+When writing or reviewing Kotlin code:
+
+1. **Always** prefer val over var
+2. **Always** use null-safe types appropriately
+3. **Prefer** expression bodies for simple functions
+4. **Prefer** functional operations over loops
+5. **Use** default parameters over overloads
+6. **Use** when for multiple conditions
+7. **Leverage** extension functions
+8. **Document** public APIs

package/templates/.claude/skills/lists/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: omcodex:lists
+description: Show all available commands
+scope: harness
+argument-hint: "[--category <category>] [--verbose]"
+user-invocable: true
+---
+
+# List Commands Skill
+
+Show all available commands with optional filtering and detailed information.
+
+## Options
+
+```
+--verbose, -v    Show detailed descriptions
+--category, -c   Filter by category (system, manager, dev)
+```
+
+## Output Format
+
+### Default
+```
+AI Agent System - Available Commands
+
+System:
+  lists              Show all available commands
+  status             Show system status
+  help               Show help information
+
+Manager:
+  /create-agent          Create a new agent
+  /update-docs           Sync documentation with project structure
+  /update-external       Update agents from external sources
+  /audit-agents          Audit agent dependencies
+  /fix-refs              Fix broken references
+
+Dev:
+  /dev-review        Review code for best practices
+  /dev-refactor      Refactor code
+
+Use "<command> --help" for detailed information.
+```
+
+### Verbose Output
+```
+lists --verbose
+
+AI Agent System - Available Commands (Detailed)
+
+System Commands:
+┌─────────┬──────────────────────────────────────────────┐
+│ Command │ Description                                  │
+├─────────┼──────────────────────────────────────────────┤
+│ lists   │ Show all available commands                  │
+│ status  │ Show system status and health checks         │
+│ help    │ Show help for commands and agents            │
+└─────────┴──────────────────────────────────────────────┘
+
+Manager Commands:
+┌──────────────────┬──────────────────────────────────────┐
+│ Command          │ Description                          │
+├──────────────────┼──────────────────────────────────────┤
+│ /create-agent    │ Create a new agent with structure    │
+│ /update-docs     │ Sync all docs with project state     │
+│ /update-external │ Update from external sources         │
+│ /audit-agents    │ Check dependencies and refs          │
+│ /fix-refs        │ Auto-fix broken references           │
+└──────────────────┴──────────────────────────────────────┘
+
+Dev Commands:
+┌──────────────┬────────────────────────────────────────┐
+│ Command      │ Description                            │
+├──────────────┼────────────────────────────────────────┤
+│ /dev-review  │ Review code against best practices     │
+│ /dev-refactor│ Suggest and apply refactoring          │
+└──────────────┴────────────────────────────────────────┘
+
+Total: 10 commands available
+```

package/templates/.claude/skills/memory-management/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: memory-management
+description: Memory persistence operations using claude-mem
+scope: core
+user-invocable: false
+---
+
+## Purpose
+
+Provide memory persistence operations using claude-mem for session context survival across compactions.
+
+## Operations
+
+### 1. Save Context
+
+```yaml
+operation: save
+description: Store session context in claude-mem
+steps:
+  1. Collect session data:
+     - Tasks completed
+     - Decisions made
+     - Open items
+     - Key code changes
+  2. Format document:
+     - Add project tag: "my-project"
+     - Add session ID: {date}-{uuid}
+     - Add relevant tags
+  3. Store in claude-mem:
+     - Use chroma_add_documents
+     - Include metadata
+```
+
+### 2. Recall Context
+
+```yaml
+operation: recall
+description: Search and retrieve relevant memories
+steps:
+  1. Build query:
+     - Always prefix with "my-project"
+     - Add user-provided search terms
+     - Include date for temporal searches
+  2. Search claude-mem:
+     - Use chroma_query_documents
+     - Request top N results
+  3. Format results:
+     - Sort by relevance
+     - Present summary
+     - Provide access to full content
+```
+
+### 3. Get Specific Memory
+
+```yaml
+operation: get
+description: Retrieve specific memory by ID
+steps:
+  1. Use chroma_get_documents with ID
+  2. Return full document content
+```
+
+## Query Patterns
+
+### Semantic Search (Primary)
+
+```python
+# Always include project name
+chroma_query_documents(["my-project {search_terms}"])
+
+# Examples:
+chroma_query_documents(["my-project authentication flow"])
+chroma_query_documents(["my-project 2025-01-24 memory system"])
+```
+
+### Get by ID
+
+```python
+# When you have a specific document ID
+chroma_get_documents(ids=["document_id"])
+```
+
+## Document Format
+
+### Save Format
+
+```yaml
+content: |
+  ## Session Summary
+  Date: {date}
+  Session: {session_id}
+
+  ### Tasks Completed
+  - Task 1: Description
+  - Task 2: Description
+
+  ### Decisions Made
+  - Decision 1: Rationale
+  - Decision 2: Rationale
+
+  ### Open Items
+  - Item 1: Status
+  - Item 2: Status
+
+  ### Notes
+  Additional context...
+
+metadata:
+  project: my-project
+  session: {date}-{uuid}
+  tags: [session, task, decision, ...]
+  created_at: {timestamp}
+```
+
+### Recall Response Format
+
+```yaml
+results:
+  - id: doc_1
+    score: 0.95
+    summary: "Authentication flow implementation"
+    date: 2025-01-20
+    tags: [authentication, oauth]
+  - id: doc_2
+    score: 0.87
+    summary: "JWT token decision"
+    date: 2025-01-18
+    tags: [authentication, decision]
+```
+
+## Best Practices
+
+### Query Tips
+
+```yaml
+do:
+  - Always include "my-project" prefix
+  - Use semantic, intent-based queries
+  - Include dates for temporal searches
+  - Use multiple queries for better coverage
+
+dont:
+  - Use complex where filters ($and, $or)
+  - Omit project name
+  - Use overly generic terms
+  - Expect exact string matching
+```
+
+### Save Tips
+
+```yaml
+do:
+  - Include meaningful tags
+  - Write clear summaries
+  - Capture decisions with rationale
+  - Note open items for future reference
+
+dont:
+  - Save trivial conversations
+  - Include sensitive data (API keys, etc.)
+  - Create duplicate entries
+```
+
+## Integration
+
+### With sys-memory-keeper Agent
+
+```
+sys-memory-keeper agent uses this skill for:
+- sys-memory-keeper:save command
+- sys-memory-keeper:recall command
+- PreCompact hook
+- SessionStart hook
+```
+
+### With Other Agents
+
+```
+Other agents can trigger memory operations via:
+- Direct sys-memory-keeper:save/recall commands
+- Delegating to sys-memory-keeper
+```
+
+## Error Handling
+
+```yaml
+save_errors:
+  - Connection failure: Retry 3 times, then log and continue
+  - Invalid format: Validate before save, report issues
+  - Storage full: Archive old memories, then retry
+
+recall_errors:
+  - No results: Suggest alternative queries
+  - Connection failure: Return empty with warning
+  - Invalid query: Help user reformulate
+```