oh-my-customcodex 0.1.0

package/templates/guides/golang/effective-go.md

@@ -0,0 +1,309 @@
+# Effective Go Reference
+
+> Source: https://go.dev/doc/effective_go
+
+## Introduction
+
+Go is a new language. Although it borrows ideas from existing languages, it has unusual properties that make effective Go programs different in character from programs written in its relatives. A straightforward translation of a C++ or Java program into Go is unlikely to produce a satisfactory result—Java programs are written in Java, not Go.
+
+## Formatting
+
+Use `gofmt` (or `goimports`) to format all Go code. This eliminates formatting debates and ensures consistency.
+
+Key points:
+- Indentation: tabs, not spaces
+- No line length limit (but break long lines sensibly)
+- Fewer parentheses than C/Java
+
+## Commentary
+
+Go provides C-style `/* */` block comments and C++-style `//` line comments.
+
+- Package comments: precede package clause, block comment for multi-line
+- Doc comments: precede declarations, complete sentences starting with name
+- `godoc` extracts documentation from comments
+
+Example:
+```go
+// Package regexp implements a simple library for regular expressions.
+package regexp
+
+// Compile parses a regular expression and returns, if successful,
+// a Regexp that can be used to match against text.
+func Compile(str string) (*Regexp, error) {
+```
+
+## Names
+
+### Package Names
+
+- Short, concise, lowercase, single-word names
+- No underscores or mixedCaps
+- Name is the base name of its source directory
+- Don't stutter: `bufio.Reader`, not `bufio.BufReader`
+
+### Getters
+
+- Don't use "Get" prefix
+- `owner := obj.Owner()` not `obj.GetOwner()`
+- Setters can use "Set": `obj.SetOwner(user)`
+
+### Interface Names
+
+- One-method interfaces: method name + "-er" suffix
+- `Reader`, `Writer`, `Formatter`, `Notifier`
+
+### MixedCaps
+
+- Use `MixedCaps` or `mixedCaps` rather than underscores
+- Exported: `MixedCaps` (capital first letter)
+- Unexported: `mixedCaps` (lowercase first letter)
+
+## Control Structures
+
+### If
+
+```go
+// With initialization statement
+if err := file.Chmod(0664); err != nil {
+    log.Print(err)
+    return err
+}
+
+// Avoid unnecessary else
+if err != nil {
+    return err
+}
+// continue normal flow
+```
+
+### For
+
+```go
+// Like C's for
+for init; condition; post { }
+
+// Like C's while
+for condition { }
+
+// Like C's for(;;)
+for { }
+
+// Range over slice
+for key, value := range oldMap {
+    newMap[key] = value
+}
+
+// Range over string (runes)
+for pos, char := range "日本語" {
+    fmt.Printf("character %c starts at byte position %d\n", char, pos)
+}
+```
+
+### Switch
+
+```go
+// No automatic fallthrough
+switch c {
+case ' ', '?', '&', '=', '#', '+', '%':
+    return true
+}
+
+// Type switch
+switch t := t.(type) {
+case bool:
+    fmt.Printf("boolean %t\n", t)
+case int:
+    fmt.Printf("integer %d\n", t)
+}
+```
+
+## Functions
+
+### Multiple Return Values
+
+```go
+func (file *File) Write(b []byte) (n int, err error)
+```
+
+### Named Result Parameters
+
+```go
+func ReadFull(r Reader, buf []byte) (n int, err error) {
+    for len(buf) > 0 && err == nil {
+        var nr int
+        nr, err = r.Read(buf)
+        n += nr
+        buf = buf[nr:]
+    }
+    return
+}
+```
+
+### Defer
+
+```go
+func Contents(filename string) (string, error) {
+    f, err := os.Open(filename)
+    if err != nil {
+        return "", err
+    }
+    defer f.Close()  // f.Close will run when we're finished.
+    // ...
+}
+```
+
+## Data
+
+### Allocation with new
+
+`new(T)` allocates zeroed storage for a new item of type `T` and returns its address, a value of type `*T`.
+
+```go
+p := new(SyncedBuffer)  // type *SyncedBuffer
+var v SyncedBuffer      // type SyncedBuffer
+```
+
+### Allocation with make
+
+`make(T, args)` creates slices, maps, and channels only. It returns an initialized (not zeroed) value of type `T` (not `*T`).
+
+```go
+make([]int, 10, 100)      // slice with len=10, cap=100
+make(map[string]int)      // map
+make(chan int, 100)       // buffered channel
+```
+
+### Arrays and Slices
+
+```go
+// Array - fixed size, value type
+var a [10]int
+
+// Slice - dynamic size, reference to array
+s := make([]int, 10)
+s = append(s, 1, 2, 3)
+```
+
+### Maps
+
+```go
+m := make(map[string]int)
+m["key"] = 42
+
+// Comma ok idiom
+if val, ok := m["key"]; ok {
+    // key exists
+}
+
+delete(m, "key")
+```
+
+## Methods
+
+### Pointer vs Value Receivers
+
+```go
+// Value receiver - operates on copy
+func (s MyStruct) ValueMethod() { }
+
+// Pointer receiver - can modify, avoids copy
+func (s *MyStruct) PointerMethod() { }
+```
+
+Rule: If any method needs a pointer receiver, all methods on that type should have pointer receivers.
+
+## Interfaces
+
+```go
+type Reader interface {
+    Read(p []byte) (n int, err error)
+}
+
+type Writer interface {
+    Write(p []byte) (n int, err error)
+}
+
+// Composition
+type ReadWriter interface {
+    Reader
+    Writer
+}
+```
+
+## Embedding
+
+```go
+type ReadWriter struct {
+    *Reader  // embedded
+    *Writer  // embedded
+}
+```
+
+## Concurrency
+
+### Goroutines
+
+```go
+go list.Sort()  // run list.Sort concurrently
+```
+
+### Channels
+
+```go
+ci := make(chan int)            // unbuffered channel of integers
+cj := make(chan int, 0)         // unbuffered channel of integers
+cs := make(chan *os.File, 100)  // buffered channel of pointers to Files
+
+c <- 1    // send
+v := <-c  // receive
+```
+
+### Select
+
+```go
+select {
+case v := <-ch1:
+    fmt.Println("received from ch1:", v)
+case ch2 <- 42:
+    fmt.Println("sent to ch2")
+default:
+    fmt.Println("no communication")
+}
+```
+
+## Errors
+
+```go
+type error interface {
+    Error() string
+}
+
+// Creating errors
+errors.New("message")
+fmt.Errorf("operation failed: %w", err)
+
+// Checking errors
+if err != nil {
+    return err
+}
+```
+
+## Panic and Recover
+
+```go
+func server(workChan <-chan *Work) {
+    for work := range workChan {
+        go safelyDo(work)
+    }
+}
+
+func safelyDo(work *Work) {
+    defer func() {
+        if err := recover(); err != nil {
+            log.Println("work failed:", err)
+        }
+    }()
+    do(work)
+}
+```

package/templates/guides/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/guides/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:
+  - lang-golang-expert

package/templates/guides/hook-data-flow/README.md

@@ -0,0 +1,135 @@
+# Hook Data Flow: Stall Detection Pipeline
+
+Added in v0.78.0. Documents the three-script pipeline that detects stalled parallel agents and emits R009 Adaptive Parallel Splitting advisories.
+
+Related rule: `.claude/rules/MUST-parallel-execution.md` (R009 Adaptive Parallel Splitting section)
+
+---
+
+## Overview
+
+When multiple agents run in parallel, one agent may take significantly longer than its peers. The stall detection pipeline identifies this condition at the moment any agent completes and advises the orchestrator to spawn independent pending tasks immediately — without cancelling the stalled agent.
+
+The pipeline spans two hook events and three scripts:
+
+| Event | Script | Role |
+|-------|--------|------|
+| SubagentStart | `agent-start-recorder.sh` | Record spawn timestamp |
+| SubagentStop (1st) | `task-outcome-recorder.sh` | Read start time, record outcome with duration |
+| SubagentStop (2nd) | `stall-detection-advisor.sh` | Read start times, compare durations, emit advisory, consume start entry |
+
+---
+
+## Data Flow
+
+```
+SubagentStart event
+  └─ agent-start-recorder.sh
+       reads:  stdin JSON (agent_type, model, description)
+       writes: /tmp/.claude-agent-starts-$PPID  (appends 1 JSON line)
+
+SubagentStop event  [hooks execute in array order — ordering is critical]
+  │
+  ├─ [1] task-outcome-recorder.sh
+  │       reads:  stdin JSON (agent_type, model, outcome)
+  │       reads:  /tmp/.claude-agent-starts-$PPID  (duration calc — entry still present)
+  │       writes: /tmp/.claude-task-outcomes-$PPID  (appends 1 JSON line with duration_seconds)
+  │       writes: stderr  (on failure only)
+  │
+  └─ [2] stall-detection-advisor.sh
+          reads:  stdin JSON (agent_type, model, description)
+          reads:  /tmp/.claude-agent-starts-$PPID  (finds matching start entry for duration)
+          reads:  /tmp/.claude-agent-durations-$PPID  (peer durations for average calculation)
+          writes: /tmp/.claude-agent-durations-$PPID  (appends completed agent's duration)
+          writes: /tmp/.claude-agent-starts-$PPID  (removes consumed start entry)
+          writes: stderr  (advisory block if stall detected — R021 advisory-only)
+```
+
+### Stall Detection Logic
+
+At SubagentStop, after at least one peer has already completed:
+
+1. Calculate `avg_duration` from all entries in `.claude-agent-durations-$PPID`
+2. Set `stall_threshold = avg_duration * 2`
+3. Scan `.claude-agent-starts-$PPID` for agents not yet in the duration file (still running)
+4. For each still-running agent where `elapsed > stall_threshold`, emit advisory to stderr
+
+The current agent's duration is recorded *after* stall detection so it does not inflate the average for its own check.
+
+### Advisory Output Format
+
+```
+─── [Stall Detection Advisory] ───────────────────────────
+  Stalled: {agent_type}:{model} ({elapsed}s elapsed, 2x avg {avg_duration}s)
+  Description: {description}
+  ⚡ Consider spawning independent pending tasks immediately
+  R009 Adaptive Parallel Splitting applies
+──────────────────────────────────────────────────────────
+```
+
+---
+
+## Shared Files
+
+| File | Writer | Readers | Lifecycle |
+|------|--------|---------|-----------|
+| `/tmp/.claude-agent-starts-$PPID` | `agent-start-recorder.sh` (append) | `task-outcome-recorder.sh` (read), `stall-detection-advisor.sh` (read + remove entry) | Session-scoped via PPID; ring buffer 50 entries; entry removed after `stall-detection-advisor` consumes it |
+| `/tmp/.claude-task-outcomes-$PPID` | `task-outcome-recorder.sh` (append) | `feedback-collector.sh`, `eval-core-batch-save.sh` (at Stop) | Session-scoped via PPID; ring buffer 50 entries |
+| `/tmp/.claude-agent-durations-$PPID` | `stall-detection-advisor.sh` (append) | `stall-detection-advisor.sh` (read for average calculation) | Session-scoped via PPID; ring buffer 50 entries |
+
+---
+
+## Execution Order Requirements
+
+The SubagentStop hook array in `hooks.json` defines a strict ordering:
+
+```json
+"SubagentStop": [
+  { "command": "bash .claude/hooks/scripts/task-outcome-recorder.sh" },
+  { "command": "bash .claude/hooks/scripts/stall-detection-advisor.sh" },
+  ...
+]
+```
+
+**task-outcome-recorder MUST run before stall-detection-advisor.**
+
+Reason: `stall-detection-advisor.sh` removes the matching start entry from `.claude-agent-starts-$PPID` after reading it (to prevent re-matching on the next SubagentStop). If the order were reversed, `task-outcome-recorder.sh` would find no start entry for the agent and would always record `duration_seconds=0`.
+
+If the order is swapped:
+- `task-outcome-recorder` records `duration_seconds=0` for all agents
+- Model escalation decisions based on duration become unreliable
+- No other visible error — silent data corruption
+
+---
+
+## Temp File Lifecycle
+
+```
+Session start (PPID assigned)
+  │
+  ├─ First SubagentStart  →  .claude-agent-starts-$PPID  created
+  │
+  ├─ First SubagentStop   →  .claude-task-outcomes-$PPID  created
+  │                          .claude-agent-durations-$PPID  created
+  │
+  ├─ Each SubagentStop    →  start entry consumed (removed by stall-detection-advisor)
+  │                          duration entry appended
+  │                          outcome entry appended
+  │
+  └─ Session end (PPID released)
+       Files remain in /tmp — OS cleans up on reboot
+       Ring buffers cap each file at 50 lines to bound growth
+```
+
+PPID (parent process ID) is used rather than PID (`$$`) to scope files to the current GPT Codex + OMX session rather than to individual script invocations. All three scripts use `${PPID}` consistently.
+
+---
+
+## Design Principles
+
+- **Advisory-only (R021):** All three scripts exit 0 unconditionally. A missing `jq` binary causes silent pass-through, not a blocked hook.
+- **PPID scoping:** Isolates temp files per GPT Codex + OMX session. Multiple concurrent sessions do not interfere.
+- **Ring buffers:** Each temp file is capped at 50 lines via `tail -50` after each append. Prevents unbounded growth in long sessions with many agents.
+- **grep -F for pattern matching:** Fixed-string matching in `agent-start-recorder` and `task-outcome-recorder` avoids regex injection from agent type names.
+- **Self-exclusion from average:** `stall-detection-advisor` reads the duration file *before* appending its own entry, so the completing agent is never compared against itself.
+- **Sibling preservation:** When removing a start entry, `awk` removes only the first matching line — preserving sibling entries when multiple agents of the same type run in parallel.