oh-my-customcode 0.1.1 → 0.1.3

package/templates/agents/sw-engineer/language/golang-expert/refs/golang/error-handling.md

@@ -0,0 +1,250 @@
+# Go Error Handling
+
+> Reference for error handling patterns in Go
+
+## Error Interface
+
+```go
+type error interface {
+    Error() string
+}
+```
+
+Errors are values. They can be stored, passed, and compared.
+
+## Creating Errors
+
+### Simple Errors
+
+```go
+import "errors"
+
+err := errors.New("something went wrong")
+```
+
+### Formatted Errors
+
+```go
+import "fmt"
+
+err := fmt.Errorf("failed to process %s: %v", filename, err)
+```
+
+### Custom Error Types
+
+```go
+type MyError struct {
+    Code    int
+    Message string
+}
+
+func (e *MyError) Error() string {
+    return fmt.Sprintf("error %d: %s", e.Code, e.Message)
+}
+```
+
+## Handling Errors
+
+### Basic Pattern
+
+```go
+result, err := doSomething()
+if err != nil {
+    return err
+}
+// use result
+```
+
+### Adding Context
+
+```go
+result, err := doSomething()
+if err != nil {
+    return fmt.Errorf("doSomething failed: %w", err)
+}
+```
+
+### Multiple Returns
+
+```go
+func divide(a, b float64) (float64, error) {
+    if b == 0 {
+        return 0, errors.New("division by zero")
+    }
+    return a / b, nil
+}
+```
+
+## Error Wrapping (Go 1.13+)
+
+### Wrapping Errors
+
+```go
+// Use %w verb to wrap
+if err != nil {
+    return fmt.Errorf("operation failed: %w", err)
+}
+```
+
+### Unwrapping Errors
+
+```go
+// errors.Unwrap returns the wrapped error
+inner := errors.Unwrap(err)
+
+// errors.Is checks if any error in chain matches
+if errors.Is(err, os.ErrNotExist) {
+    // handle file not found
+}
+
+// errors.As finds first error matching type
+var pathErr *os.PathError
+if errors.As(err, &pathErr) {
+    fmt.Println("failed path:", pathErr.Path)
+}
+```
+
+## Sentinel Errors
+
+```go
+var (
+    ErrNotFound     = errors.New("not found")
+    ErrUnauthorized = errors.New("unauthorized")
+    ErrInvalid      = errors.New("invalid input")
+)
+
+func fetch(id string) (*Item, error) {
+    item, ok := store[id]
+    if !ok {
+        return nil, ErrNotFound
+    }
+    return item, nil
+}
+
+// Usage
+item, err := fetch("123")
+if errors.Is(err, ErrNotFound) {
+    // handle not found
+}
+```
+
+## Error Handling Strategies
+
+### Fail Fast
+
+```go
+func process() error {
+    if err := step1(); err != nil {
+        return err
+    }
+    if err := step2(); err != nil {
+        return err
+    }
+    return step3()
+}
+```
+
+### Deferred Cleanup
+
+```go
+func processFile(path string) (err error) {
+    f, err := os.Open(path)
+    if err != nil {
+        return err
+    }
+    defer func() {
+        if cerr := f.Close(); cerr != nil && err == nil {
+            err = cerr
+        }
+    }()
+    // process file
+    return nil
+}
+```
+
+### Error Aggregation
+
+```go
+type MultiError []error
+
+func (m MultiError) Error() string {
+    var msgs []string
+    for _, err := range m {
+        msgs = append(msgs, err.Error())
+    }
+    return strings.Join(msgs, "; ")
+}
+
+func validateAll(items []Item) error {
+    var errs MultiError
+    for _, item := range items {
+        if err := validate(item); err != nil {
+            errs = append(errs, err)
+        }
+    }
+    if len(errs) > 0 {
+        return errs
+    }
+    return nil
+}
+```
+
+## Panic and Recover
+
+### When to Panic
+
+- Unrecoverable errors during initialization
+- Programming errors (nil pointer, out of bounds)
+- Violation of invariants
+
+```go
+func MustCompile(pattern string) *Regexp {
+    re, err := Compile(pattern)
+    if err != nil {
+        panic(err)
+    }
+    return re
+}
+```
+
+### Recovering from Panic
+
+```go
+func safeCall(fn func()) (err error) {
+    defer func() {
+        if r := recover(); r != nil {
+            err = fmt.Errorf("panic recovered: %v", r)
+        }
+    }()
+    fn()
+    return nil
+}
+```
+
+### Package Boundary Rule
+
+- Convert panics to errors at package boundaries
+- Don't let panics escape your API
+
+```go
+func (s *Server) handleRequest(w http.ResponseWriter, r *http.Request) {
+    defer func() {
+        if err := recover(); err != nil {
+            log.Printf("panic: %v\n%s", err, debug.Stack())
+            http.Error(w, "Internal Server Error", 500)
+        }
+    }()
+    // handle request
+}
+```
+
+## Best Practices
+
+1. **Handle errors immediately** after the call
+2. **Add context** when propagating errors
+3. **Use error wrapping** with `%w` for error chains
+4. **Define sentinel errors** for known conditions
+5. **Don't ignore errors** (at minimum, log them)
+6. **Prefer errors over panics** in library code
+7. **Document error returns** in function comments
+8. **Test error paths** as thoroughly as success paths

package/templates/agents/sw-engineer/language/golang-expert/refs/golang/index.yaml

@@ -0,0 +1,27 @@
+# Golang Guide
+
+metadata:
+  name: golang
+  description: Go language reference documentation
+
+source:
+  type: external
+  origin: go.dev
+  url: https://go.dev/doc/effective_go
+  last_fetched: "2026-01-22"
+
+documents:
+  - name: effective-go
+    path: ./effective-go.md
+    description: Effective Go - official best practices guide
+
+  - name: concurrency
+    path: ./concurrency.md
+    description: Concurrency patterns and practices
+
+  - name: error-handling
+    path: ./error-handling.md
+    description: Error handling patterns
+
+used_by:
+  - golang-expert

package/templates/agents/sw-engineer/language/kotlin-expert/refs/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}"
+```