oh-my-customcodex 0.1.0

package/templates/guides/kotlin/coding-conventions.md

@@ -0,0 +1,247 @@
+# Kotlin Coding Conventions
+
+> Source: https://kotlinlang.org/docs/coding-conventions.html
+
+## Source Code Organization
+
+### Directory Structure
+
+Follow package structure with common root omitted:
+- `org.example.kotlin.network.socket` → `network/socket` subdirectory
+
+### Source File Names
+
+| Content | File Name |
+|---------|-----------|
+| Single class | `MyClass.kt` |
+| Multiple declarations | `ProcessDeclarations.kt` |
+| Platform-specific | `Platform.jvm.kt` |
+
+### Class Layout
+
+1. Property declarations and initializer blocks
+2. Secondary constructors
+3. Method declarations
+4. Companion object
+
+```kotlin
+class MyClass(val name: String) {
+    // 1. Properties
+    private val items = mutableListOf<Item>()
+
+    init {
+        // initializer block
+    }
+
+    // 2. Secondary constructors
+    constructor() : this("default")
+
+    // 3. Methods
+    fun doSomething() { }
+
+    // 4. Companion object
+    companion object {
+        const val TAG = "MyClass"
+    }
+}
+```
+
+## Naming Conventions
+
+| Element | Style | Example |
+|---------|-------|---------|
+| Packages | lowercase | `org.example.project` |
+| Classes | UpperCamelCase | `DeclarationProcessor` |
+| Functions | lowerCamelCase | `processDeclarations()` |
+| Properties | lowerCamelCase | `declarationCount` |
+| Constants | UPPER_SNAKE_CASE | `MAX_COUNT` |
+| Backing properties | underscore prefix | `_elementList` |
+
+### Acronyms
+
+- 2 letters: both uppercase (`IOStream`)
+- 3+ letters: capitalize first only (`XmlFormatter`)
+
+## Formatting
+
+### Indentation
+
+```kotlin
+if (elements != null) {
+    for (element in elements) {
+        // 4 spaces indentation
+    }
+}
+```
+
+### Horizontal Whitespace
+
+```kotlin
+// Binary operators with spaces
+val sum = a + b
+
+// No space around range
+for (i in 0..n) { }
+
+// No space around dot
+foo.bar().filter { it > 2 }
+
+// Space after control keywords
+if (condition) { }
+```
+
+### Colons
+
+```kotlin
+// Type and supertype: space before
+abstract class Foo<out T : Any> : IFoo {
+    // Declaration and type: no space before
+    abstract fun foo(a: Int): T
+}
+```
+
+### Function Signatures
+
+```kotlin
+// Short: single line
+fun foo(a: Int): String = a.toString()
+
+// Long: break parameters
+fun longMethodName(
+    argument: ArgumentType = defaultValue,
+    argument2: AnotherArgumentType,
+): ReturnType {
+    // body
+}
+```
+
+### Trailing Commas
+
+```kotlin
+class Person(
+    val firstName: String,
+    val lastName: String,
+    val age: Int, // trailing comma
+)
+```
+
+## Idiomatic Patterns
+
+### Immutability
+
+```kotlin
+// Prefer val
+val name = "Kotlin"
+
+// Prefer immutable collections
+val items = listOf(1, 2, 3)
+```
+
+### Default Parameters
+
+```kotlin
+// Prefer over overloads
+fun read(
+    b: ByteArray,
+    off: Int = 0,
+    len: Int = b.size,
+) { }
+```
+
+### Expression Bodies
+
+```kotlin
+// Prefer for simple functions
+fun square(x: Int) = x * x
+```
+
+### Conditionals
+
+```kotlin
+// Use if for binary
+return if (x) foo() else bar()
+
+// Use when for multiple
+return when (x) {
+    0 -> "zero"
+    1 -> "one"
+    else -> "many"
+}
+```
+
+### Functional Operations
+
+```kotlin
+// Prefer
+list.filter { it > 10 }
+    .map { it * 2 }
+    .take(5)
+
+// Over manual loops
+```
+
+### Ranges
+
+```kotlin
+// Good: open-ended range
+for (i in 0..<n) { }
+
+// Avoid
+for (i in 0..n - 1) { }
+```
+
+## Null Safety
+
+```kotlin
+// Safe call
+val length = text?.length
+
+// Elvis operator
+val name = user?.name ?: "Unknown"
+
+// Let for non-null
+user?.let {
+    println("Hello, ${it.name}")
+}
+
+// Not-null assertion (use sparingly)
+val name = user!!.name
+```
+
+## Documentation
+
+```kotlin
+/**
+ * Returns the absolute value of the given [number].
+ */
+fun abs(number: Int): Int = if (number < 0) -number else number
+
+/**
+ * A group of *members*.
+ *
+ * This class has no useful logic; it's just a documentation example.
+ *
+ * @property name the name of this group.
+ * @constructor Creates an empty group.
+ */
+class Group(val name: String) {
+    /**
+     * Adds a [member] to this group.
+     * @return the new size of the group.
+     */
+    fun add(member: Member): Int { ... }
+}
+```
+
+## Avoid Redundant Constructs
+
+```kotlin
+// Avoid explicit Unit return
+fun foo() { } // not: fun foo(): Unit { }
+
+// Avoid semicolons
+val x = 1 // not: val x = 1;
+
+// Use simple string templates
+"$name" // not: "${name}"
+```

package/templates/guides/kotlin/idioms.md

@@ -0,0 +1,234 @@
+# Kotlin Idioms
+
+> Source: https://kotlinlang.org/docs/idioms.html
+
+## Data Classes
+
+```kotlin
+data class Customer(val name: String, val email: String)
+```
+
+Provides:
+- `equals()` / `hashCode()`
+- `toString()`: `"Customer(name=John, email=john@example.com)"`
+- `copy()` function
+- `componentN()` functions
+
+## Default Parameter Values
+
+```kotlin
+fun foo(a: Int = 0, b: String = "") { }
+```
+
+## Filtering Collections
+
+```kotlin
+val positives = list.filter { it > 0 }
+
+// or with explicit type
+val positives = list.filter { x -> x > 0 }
+```
+
+## Checking Element Presence
+
+```kotlin
+if ("john@example.com" in emailsList) { }
+if ("jane@example.com" !in emailsList) { }
+```
+
+## String Interpolation
+
+```kotlin
+println("Name: $name")
+println("Age: ${person.age}")
+```
+
+## Instance Checks
+
+```kotlin
+when (x) {
+    is Foo -> ...
+    is Bar -> ...
+    else -> ...
+}
+```
+
+## Read-only Collections
+
+```kotlin
+val list = listOf("a", "b", "c")
+val map = mapOf("a" to 1, "b" to 2, "c" to 3)
+```
+
+## Accessing Maps
+
+```kotlin
+val map = mapOf("a" to 1)
+println(map["a"]) // prints 1
+```
+
+## Traversing Maps
+
+```kotlin
+for ((k, v) in map) {
+    println("$k -> $v")
+}
+```
+
+## Ranges
+
+```kotlin
+for (i in 1..100) { }      // closed range: 1 to 100
+for (i in 1..<100) { }     // half-open: 1 to 99
+for (i in 2..10 step 2) { }
+for (i in 10 downTo 1) { }
+```
+
+## Lazy Property
+
+```kotlin
+val p: String by lazy {
+    // compute the string
+}
+```
+
+## Extension Functions
+
+```kotlin
+fun String.spaceToCamelCase() { }
+"Convert this to camelcase".spaceToCamelCase()
+```
+
+## Singleton
+
+```kotlin
+object Resource {
+    val name = "Name"
+}
+```
+
+## Instantiate Abstract Class
+
+```kotlin
+abstract class MyAbstractClass {
+    abstract fun doSomething()
+}
+
+val myObject = object : MyAbstractClass() {
+    override fun doSomething() { }
+}
+```
+
+## if-not-null Shorthand
+
+```kotlin
+// Simple
+val length = files?.size
+
+// With else
+val length = files?.size ?: 0
+
+// With let
+files?.let {
+    println(it.size)
+}
+```
+
+## Return on when
+
+```kotlin
+fun transform(color: String): Int {
+    return when (color) {
+        "Red" -> 0
+        "Green" -> 1
+        "Blue" -> 2
+        else -> throw IllegalArgumentException("Invalid color")
+    }
+}
+```
+
+## try-catch Expression
+
+```kotlin
+val result = try {
+    count()
+} catch (e: ArithmeticException) {
+    throw IllegalStateException(e)
+}
+```
+
+## if Expression
+
+```kotlin
+val y = if (x == 1) {
+    "one"
+} else if (x == 2) {
+    "two"
+} else {
+    "other"
+}
+```
+
+## Builder-style Usage
+
+```kotlin
+fun arrayOfMinusOnes(size: Int): IntArray {
+    return IntArray(size).apply { fill(-1) }
+}
+```
+
+## Single-expression Functions
+
+```kotlin
+fun theAnswer() = 42
+
+// equivalent to
+fun theAnswer(): Int {
+    return 42
+}
+```
+
+## Call Multiple Methods (with)
+
+```kotlin
+class Turtle {
+    fun penDown()
+    fun penUp()
+    fun turn(degrees: Double)
+    fun forward(pixels: Double)
+}
+
+val myTurtle = Turtle()
+with(myTurtle) {
+    penDown()
+    for (i in 1..4) {
+        forward(100.0)
+        turn(90.0)
+    }
+    penUp()
+}
+```
+
+## Configure Object (apply)
+
+```kotlin
+val myRectangle = Rectangle().apply {
+    length = 4
+    breadth = 5
+    color = 0xFAFAFA
+}
+```
+
+## Swap Variables
+
+```kotlin
+var a = 1
+var b = 2
+a = b.also { b = a }
+```
+
+## TODO: Marking Incomplete
+
+```kotlin
+fun calcTaxes(): BigDecimal = TODO("Waiting for feedback from accounting")
+```

package/templates/guides/kotlin/index.yaml

@@ -0,0 +1,26 @@
+# Kotlin Guide
+
+metadata:
+  name: kotlin
+  description: Kotlin language reference documentation
+
+source:
+  type: external
+  origin: kotlinlang.org
+  urls:
+    - https://kotlinlang.org/docs/coding-conventions.html
+    - https://kotlinlang.org/docs/idioms.html
+    - https://developer.android.com/kotlin/style-guide
+  last_fetched: "2026-01-22"
+
+documents:
+  - name: coding-conventions
+    path: ./coding-conventions.md
+    description: Official Kotlin coding conventions
+
+  - name: idioms
+    path: ./idioms.md
+    description: Idiomatic Kotlin patterns
+
+used_by:
+  - lang-kotlin-expert

package/templates/guides/multi-model-routing/README.md

@@ -0,0 +1,101 @@
+# Multi-Model Routing
+
+## Overview
+
+Role-based model selection strategy for AI agent workflows. Consolidates model routing conventions from R006 (agent design), R008 (tool identification), and agent frontmatter into a single reference.
+
+## Model Aliases
+
+| Alias | Full ID | Cost | Speed | Use Case |
+|-------|---------|------|-------|----------|
+| `haiku` | claude-haiku-4-5 | $ | Fast | Search, simple edits, file discovery |
+| `sonnet` | claude-sonnet-4-6 | $$ | Moderate | Code generation, general tasks (default) |
+| `opus` | claude-opus-4-6 | $$$ | Slower | Complex reasoning, architecture, planning |
+| `opusplan` | claude-opus-4-6 + plan mode | $$$ | Slower | Architecture with approval gates |
+
+Extended context: `[1m]` suffix enables 1M token context (e.g., `claude-opus-4-6[1m]`).
+
+## Role-Based Routing Table
+
+| Role | Recommended Model | Rationale |
+|------|------------------|-----------|
+| Code search / file discovery | haiku | Fast, cheap, sufficient for retrieval |
+| Code review | sonnet | Needs understanding, not deep reasoning |
+| Code generation | sonnet | Good balance of quality and speed |
+| Bug fix (simple) | sonnet | Pattern recognition sufficient |
+| Bug fix (complex) | opus | Needs deep reasoning across modules |
+| Architecture design | opus / opusplan | Requires holistic thinking |
+| Test generation | sonnet | Template-driven, moderate complexity |
+| Documentation | sonnet | Straightforward generation |
+| Release verification | opus | Cross-cutting validation |
+| Orchestration | opus | Routing decisions need broad context |
+
+## Cost-Quality Tradeoff Matrix
+
+```
+Quality ▲
+        │  ┌─────────┐
+        │  │  opus    │ Complex reasoning
+        │  └────┬────┘
+        │       │
+        │  ┌────┴────┐
+        │  │ sonnet   │ General purpose (default)
+        │  └────┬────┘
+        │       │
+        │  ┌────┴────┐
+        │  │  haiku   │ Retrieval, simple tasks
+        │  └─────────┘
+        └──────────────────────► Cost
+```
+
+## MODEL_ROUTING.md Convention
+
+Projects can declare a `MODEL_ROUTING.md` file to override default routing:
+
+```markdown
+# Model Routing
+
+| Agent Pattern | Model | Override Reason |
+|---------------|-------|-----------------|
+| lang-*-expert | sonnet | Default sufficient for code generation |
+| mgr-sauron | opus | Verification requires deep analysis |
+| Explore | haiku | Search-only, no generation needed |
+```
+
+Place in project root or `.claude/` directory.
+
+## Agent Frontmatter Integration
+
+```yaml
+# .claude/agents/example.md
+name: example-agent
+model: sonnet  # Use alias from table above
+```
+
+The `model` field in agent frontmatter sets the default. The Agent tool's `model` parameter overrides at spawn time.
+
+## Escalation Pattern
+
+When a task fails at a lower model tier, escalate:
+
+```
+haiku → sonnet → opus
+```
+
+Configuration in agent frontmatter:
+```yaml
+escalation:
+  enabled: true
+  path: haiku → sonnet → opus
+  threshold: 2  # failures before escalation advisory
+```
+
+## Fast Mode Interaction
+
+Fast Mode (`/fast` toggle) uses the same model with faster output (~2.5x). It does NOT change the model — it reduces reasoning depth while maintaining the configured model tier.
+
+## Related
+
+- R006 — Agent design rules (model aliases, frontmatter format)
+- R008 — Tool identification (model in agent:model format)
+- `guides/skill-bundle-design/` — Skill architecture patterns

package/templates/guides/multi-provider-exec/README.md

@@ -0,0 +1,83 @@
+# Multi-Provider Exec
+
+## Overview
+
+Unified reference for executing prompts through external LLM providers via exec skills. Complements the [Multi-Model Routing](../multi-model-routing/README.md) guide (Claude model selection) with cross-provider execution capabilities.
+
+Inspired by OpenHarness's provider profile switching pattern, adapted for oh-my-customcodex's skill-based architecture.
+
+## Provider Matrix
+
+| Provider | Skill | CLI Dependency | Model | Strengths |
+|----------|-------|---------------|-------|-----------|
+| OpenAI (Codex) | `codex-exec` | `codex` CLI | GPT-5.4 | Code generation, broad knowledge |
+| Google (Gemini) | `gemini-exec` | `gemini` CLI | Gemini 2.5 Pro | Long context, multimodal |
+| RTK (proxy) | `rtk-exec` | `rtk` CLI | Configurable | Token-optimized output, cost reduction |
+
+## Availability Detection
+
+The `session-env-check.sh` hook (SessionStart) auto-detects available providers:
+
+```
+[SessionStart] Checking external CLI availability...
+  codex: ✓ available
+  gemini: ✗ not found
+  rtk: ✓ available
+```
+
+Providers are opt-in — missing CLIs are silently skipped.
+
+## Usage Patterns
+
+### Direct Invocation
+
+```
+/codex-exec "Review this function for security issues"
+/gemini-exec "Analyze this architecture diagram"
+/rtk-exec "List files matching pattern X"
+```
+
+### Provider Selection Guide
+
+| Task | Recommended Provider | Rationale |
+|------|---------------------|-----------|
+| Second opinion on code review | codex-exec | Independent model reduces confirmation bias |
+| Long document analysis | gemini-exec | 1M+ context window |
+| Token-heavy batch operations | rtk-exec | Compressed output reduces context cost |
+| Security audit cross-check | codex-exec | Different training data catches different patterns |
+| Multi-model verification | All three | `/multi-model-verification` skill orchestrates this |
+
+### Integration with Existing Skills
+
+| Skill | Uses Provider | How |
+|-------|--------------|-----|
+| `multi-model-verification` | codex-exec + gemini-exec | Parallel verification with severity classification |
+| `reasoning-sandwich` | Any exec skill | Pre/post reasoning with different models |
+| `model-escalation` | Claude models only | Internal escalation (haiku→sonnet→opus), not cross-provider |
+
+## Relationship to Multi-Model Routing
+
+| Aspect | Multi-Model Routing | Multi-Provider Exec |
+|--------|--------------------|--------------------|
+| Scope | Claude model selection | Cross-provider execution |
+| Models | haiku / sonnet / opus | GPT-5.4 / Gemini 2.5 / RTK proxy |
+| Mechanism | `model` frontmatter field | Exec skill invocation |
+| Use case | Cost/quality optimization within Claude | Independent verification, specialized tasks |
+| Guide | `guides/multi-model-routing/` | `guides/multi-provider-exec/` |
+
+## Configuration
+
+No global configuration required. Each exec skill reads its own CLI configuration:
+
+| Skill | Config Source |
+|-------|-------------|
+| codex-exec | `~/.codex/config` or CODEX_API_KEY env |
+| gemini-exec | `~/.gemini/config` or GEMINI_API_KEY env |
+| rtk-exec | RTK proxy running on localhost |
+
+## Limitations
+
+- Provider availability depends on user's CLI installations
+- Cross-provider results are advisory — Claude remains the primary execution engine
+- No automatic fallback between providers (by design — explicit selection preferred)
+- Rate limits and costs are provider-specific and not tracked by oh-my-customcodex