oh-my-customcodex 0.1.0

package/templates/.claude/skills/systematic-debugging/root-cause-tracing.md

@@ -0,0 +1,87 @@
+# Root Cause Tracing
+
+<!-- Source: https://github.com/tmdgusya/engineering-disciplines (MIT License) -->
+
+## Overview
+
+Bugs often manifest deep in the call stack (git init in wrong directory, file created in wrong location, database opened with wrong path). Your instinct is to fix where the error appears, but that's treating a symptom.
+
+**Core principle:** Trace backward through the call chain until you find the original trigger, then fix at the source.
+
+## When to Use
+
+**Use when:**
+- Error happens deep in execution (not at entry point)
+- Stack trace shows long call chain
+- Unclear where invalid data originated
+- Need to find which test/code triggers the problem
+
+## The Tracing Process
+
+### 1. Observe the Symptom
+```
+Error: git init failed in /Users/jesse/project/packages/core
+```
+
+### 2. Find Immediate Cause
+**What code directly causes this?**
+```typescript
+await execFileAsync('git', ['init'], { cwd: projectDir });
+```
+
+### 3. Ask: What Called This?
+```typescript
+WorktreeManager.createSessionWorktree(projectDir, sessionId)
+  -> called by Session.initializeWorkspace()
+  -> called by Session.create()
+  -> called by test at Project.create()
+```
+
+### 4. Keep Tracing Up
+**What value was passed?**
+- `projectDir = ''` (empty string!)
+- Empty string as `cwd` resolves to `process.cwd()`
+- That's the source code directory!
+
+### 5. Find Original Trigger
+**Where did empty string come from?**
+```typescript
+const context = setupCoreTest(); // Returns { tempDir: '' }
+Project.create('name', context.tempDir); // Accessed before beforeEach!
+```
+
+## Adding Stack Traces
+
+When you can't trace manually, add instrumentation:
+
+```typescript
+// Before the problematic operation
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  console.error('DEBUG git init:', {
+    directory,
+    cwd: process.cwd(),
+    nodeEnv: process.env.NODE_ENV,
+    stack,
+  });
+
+  await execFileAsync('git', ['init'], { cwd: directory });
+}
+```
+
+**Critical:** Use `console.error()` in tests (not logger - may not show)
+
+## Finding Which Test Causes Pollution
+
+If something appears during tests but you don't know which test, use the bisection script `find-polluter.sh` in this directory.
+
+## Key Principle
+
+**NEVER fix just where the error appears.** Trace back to find the original trigger.
+
+## Stack Trace Tips
+
+- **In tests:** Use `console.error()` not logger - logger may be suppressed
+- **Before operation:** Log before the dangerous operation, not after it fails
+- **Include context:** Directory, cwd, environment variables, timestamps
+- **Capture stack:** `new Error().stack` shows complete call chain

package/templates/.claude/skills/task-decomposition/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: task-decomposition
+description: Auto-decompose large tasks into DAG-compatible parallel subtasks
+scope: core
+context: fork
+user-invocable: false
+---
+
+# Task Decomposition Skill
+
+Analyzes task complexity and decomposes large tasks into smaller, parallelizable subtasks compatible with the DAG orchestration skill. The orchestrator uses this as a planning frontend before execution.
+
+## Trigger Conditions
+
+Decomposition is **recommended** when any of these thresholds are met:
+
+| Trigger | Threshold | Rationale |
+|---------|-----------|-----------|
+| Estimated duration | > 30 minutes | Too long for single agent |
+| Files affected | > 3 files | Parallelizable across files |
+| Domains involved | > 2 domains | Requires multiple specialists |
+| Agent types needed | > 2 types | Cross-specialty coordination |
+
+### Step 0: Pattern Selection
+
+Before decomposing, select the appropriate workflow pattern:
+
+| Pattern | When to Use | Primitive |
+|---------|-------------|-----------|
+| Sequential | Steps must execute in order, each depends on previous | dag-orchestration (linear) |
+| Parallel | Independent subtasks with no shared state | Agent tool (R009) or Agent Teams (R018) |
+| Evaluator-Optimizer | Quality-critical output needing iterative refinement | worker-reviewer-pipeline |
+| Orchestrator | Complex multi-step with dynamic routing | Routing skills (secretary/dev-lead/de-lead/qa-lead) |
+
+**Decision**: If task has independent subtasks → Parallel. If quality-critical → add EO review cycle. If multi-step with dependencies → Sequential/Orchestrator.
+
+## Decomposition Process
+
+```
+1. Analyze task scope
+   ├── Estimate duration, file count, domains
+   ├── Identify required agent types
+   └── Check trigger thresholds
+
+2. If thresholds met → decompose:
+   ├── Break into atomic subtasks (single agent, single concern)
+   ├── Identify dependencies between subtasks
+   ├── Map subtasks to agents (use routing skills)
+   └── Generate DAG workflow spec
+
+3. Present plan to user (R015 transparency)
+   ├── Show decomposed subtasks with agents
+   ├── Show dependency graph
+   ├── Show estimated parallel execution time
+   └── Request confirmation before execution
+
+4. Execute via dag-orchestration skill
+```
+
+## Decomposition Heuristics
+
+### By File Independence
+```
+Task: "Update auth module across 5 files"
+  ├── auth.ts → lang-typescript-expert
+  ├── middleware.ts → lang-typescript-expert
+  ├── config.ts → lang-typescript-expert (independent)
+  ├── auth.test.ts → qa-engineer (depends: auth.ts)
+  └── README.md → arch-documenter (depends: all above)
+
+DAG: [auth.ts, middleware.ts, config.ts] → auth.test.ts → README.md
+```
+
+### By Domain Separation
+```
+Task: "Add user profile feature with API and UI"
+  ├── API endpoint → be-express-expert
+  ├── Database schema → db-postgres-expert
+  ├── Frontend component → fe-vercel-agent
+  └── Integration test → qa-engineer
+
+DAG: [API, DB] → Frontend → Integration test
+     (API and DB are independent, Frontend needs both)
+```
+
+### By Layer
+```
+Task: "Implement order processing in Spring Boot"
+  ├── Domain model → lang-kotlin-expert
+  ├── Repository → be-springboot-expert (depends: domain)
+  ├── Service → be-springboot-expert (depends: domain, repository)
+  ├── Controller → be-springboot-expert (depends: service)
+  └── Tests → qa-engineer (depends: all)
+
+DAG: domain → [repository] → service → controller → tests
+```
+
+## Output Format
+
+### Decomposition Plan
+```
+[Task Decomposition]
+├── Original: "Add user authentication with JWT"
+├── Complexity: High (4 files, 3 domains, ~45 min)
+├── Decomposed into 5 subtasks:
+│
+│   [1] analyze (Explore:haiku)
+│       Scan codebase for existing auth patterns
+│
+│   [2] implement-auth (lang-typescript-expert:sonnet)
+│       Implement JWT signing and validation
+│       Depends: [1]
+│
+│   [3] implement-middleware (lang-typescript-expert:sonnet)
+│       Create auth middleware
+│       Depends: [1]
+│
+│   [4] write-tests (qa-engineer:sonnet)
+│       Write auth tests
+│       Depends: [2, 3]
+│
+│   [5] commit (mgr-gitnerd:sonnet)
+│       Commit all changes
+│       Depends: [4]
+│
+├── Parallel layers: 3 (max 2 concurrent in layer 2)
+├── Estimated time: ~20 min (vs ~45 min sequential)
+└── Proceed? [Y/n]
+```
+
+### Generated DAG Spec
+```yaml
+workflow:
+  name: auto-decomposed-auth
+  description: "Auto-decomposed: Add user authentication with JWT"
+
+nodes:
+  - id: analyze
+    agent: Explore
+    model: haiku
+    prompt: "Scan codebase for existing auth patterns"
+  - id: implement-auth
+    agent: lang-typescript-expert
+    model: sonnet
+    prompt: "Implement JWT signing and validation"
+    depends_on: [analyze]
+  - id: implement-middleware
+    agent: lang-typescript-expert
+    model: sonnet
+    prompt: "Create auth middleware"
+    depends_on: [analyze]
+  - id: write-tests
+    agent: qa-engineer
+    model: sonnet
+    prompt: "Write auth tests"
+    depends_on: [implement-auth, implement-middleware]
+  - id: commit
+    agent: mgr-gitnerd
+    model: sonnet
+    prompt: "Commit all changes"
+    depends_on: [write-tests]
+
+config:
+  max_parallel: 4
+  failure_strategy: stop
+```
+
+## Atomic Task Criteria
+
+A subtask is **atomic** when it meets ALL of:
+- Single agent can handle it
+- Single concern (one logical change)
+- Independently testable outcome
+- < 15 minutes estimated duration
+- < 3 files affected
+
+If a subtask is not atomic → decompose further (max 2 levels deep).
+
+## Skip Decomposition When
+
+| Condition | Reason |
+|-----------|--------|
+| Single file edit | Already atomic |
+| < 10 minutes estimated | Overhead not worth it |
+| User explicitly requests "just do it" | User override |
+| Single domain, single agent | No parallelization benefit |
+
+## Integration
+
+| Component | Integration |
+|-----------|-------------|
+| dag-orchestration | Generates DAG specs consumed by dag-orchestration |
+| Routing skills | Uses dev-lead/de-lead/qa-lead routing for agent mapping |
+| R009 | Maximizes parallelization within max-4 limit |
+| R010 | Decomposition happens in orchestrator only |
+| R015 | Plan displayed before execution for user approval |
+| R018 | 3+ agents in plan → check Agent Teams eligibility |

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

@@ -0,0 +1,322 @@
+---
+name: typescript-best-practices
+description: Type-safe TypeScript patterns from industry standards
+scope: core
+user-invocable: false
+---
+
+## Purpose
+
+Apply type-safe TypeScript patterns and best practices from industry standards.
+
+## Core Principles
+
+```
+Type safety over convenience
+Explicit over implicit
+Prefer strict mode
+Use inference wisely
+```
+
+## Rules
+
+### 1. Type System
+
+```yaml
+type_inference:
+  rely_on: trivially inferred types (primitives, literals)
+  annotate: complex expressions, return types, public APIs
+
+any_vs_unknown:
+  prefer: unknown (requires type narrowing)
+  avoid: any (disables type checking)
+  if_any_needed: add suppressing comment
+
+nullable:
+  prefer: "field?: Type"
+  avoid: "field: Type | undefined"
+  compare_enums: explicitly, not boolean coercion
+
+patterns: |
+  // Good: unknown with narrowing
+  function process(data: unknown): void {
+    if (typeof data === 'string') {
+      console.log(data.toUpperCase());
+    }
+  }
+
+  // Avoid: any
+  function process(data: any): void {
+    console.log(data.toUpperCase()); // No type checking!
+  }
+```
+
+### 2. Interfaces vs Types
+
+```yaml
+prefer_interfaces:
+  - Object type definitions
+  - Public API contracts
+  - Extendable types
+
+use_types_for:
+  - Union types
+  - Intersection types
+  - Mapped types
+  - Utility types
+
+patterns: |
+  // Interface for objects
+  interface User {
+    id: string;
+    name: string;
+    email: string;
+  }
+
+  // Type for unions/utilities
+  type Status = 'pending' | 'active' | 'completed';
+  type ReadonlyUser = Readonly<User>;
+```
+
+### 3. Arrays and Generics
+
+```yaml
+array_syntax:
+  simple_types: "T[]"
+  complex_types: "Array<T>"
+
+generics:
+  naming: single uppercase (T, K, V) or descriptive (TItem, TResult)
+  constraints: use extends for type bounds
+  defaults: provide when appropriate
+
+patterns: |
+  // Array syntax
+  const numbers: number[] = [1, 2, 3];
+  const items: Array<{ id: string; value: number }> = [];
+
+  // Generic constraints
+  function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
+    return obj[key];
+  }
+```
+
+### 4. Variables and Constants
+
+```yaml
+declarations:
+  prefer: const
+  when_needed: let
+  never: var
+
+one_per_statement: true
+
+patterns: |
+  // Good
+  const name = 'TypeScript';
+  const version = 5.0;
+
+  // Avoid
+  var name = 'TypeScript', version = 5.0;
+```
+
+### 5. Functions
+
+```yaml
+function_declarations:
+  named_functions: function declaration
+  callbacks: arrow functions
+  methods: shorthand syntax
+
+parameters:
+  prefer_rest: "...args: T[]"
+  avoid: arguments object
+
+this_handling:
+  prefer: arrow functions or explicit parameter
+  avoid: rebinding with bind/call/apply
+
+patterns: |
+  // Function declaration
+  function processData(data: Data): Result {
+    return transform(data);
+  }
+
+  // Arrow function for callbacks
+  items.map((item) => item.value);
+
+  // Rest parameters
+  function concat(...strings: string[]): string {
+    return strings.join('');
+  }
+```
+
+### 6. Classes
+
+```yaml
+visibility:
+  prefer: explicit modifiers (public, private, protected)
+  avoid: private fields (#)
+
+initialization:
+  prefer: at declaration site
+  use: parameter properties in constructors
+
+readonly:
+  apply_to: non-reassigned properties
+
+patterns: |
+  class User {
+    readonly id: string;
+    private email: string;
+
+    constructor(
+      public name: string,
+      email: string,
+    ) {
+      this.id = generateId();
+      this.email = email;
+    }
+  }
+```
+
+### 7. Naming Conventions
+
+```yaml
+UpperCamelCase:
+  - Classes
+  - Interfaces
+  - Type aliases
+  - Enums
+  - Type parameters
+
+lowerCamelCase:
+  - Variables
+  - Parameters
+  - Functions
+  - Methods
+  - Properties
+
+CONSTANT_CASE:
+  - Global constants
+  - Enum values
+  - Static readonly fields
+
+rules:
+  - No leading/trailing underscores
+  - No abbreviations (except universal: URL, ID, DNS)
+  - Acronyms as whole words: loadHttpUrl, not loadHTTPURL
+  - Single-letter names only in 10-line scopes
+```
+
+### 8. Control Flow
+
+```yaml
+braces:
+  always: use braces for all control statements
+
+equality:
+  always: "=== and !=="
+  never: "== and !="
+
+loops:
+  arrays: for...of
+  objects: for...in with hasOwnProperty check
+
+patterns: |
+  // Always braced
+  if (condition) {
+    doSomething();
+  }
+
+  // for...of for arrays
+  for (const item of items) {
+    process(item);
+  }
+
+  // for...in with check
+  for (const key in obj) {
+    if (Object.prototype.hasOwnProperty.call(obj, key)) {
+      process(obj[key]);
+    }
+  }
+```
+
+### 9. Error Handling
+
+```yaml
+throwing:
+  only: Error instances
+  with_message: descriptive error messages
+
+catching:
+  type: unknown
+  validate: before use
+
+empty_catch:
+  require: rationale comment
+
+patterns: |
+  // Throw Error instances
+  throw new Error('Invalid input');
+
+  // Catch with unknown
+  try {
+    riskyOperation();
+  } catch (error: unknown) {
+    if (error instanceof Error) {
+      console.error(error.message);
+    }
+    throw error;
+  }
+```
+
+### 10. Imports and Exports
+
+```yaml
+imports:
+  prefer: named imports
+  use_namespace: for large APIs
+  prefer_relative: within project
+
+exports:
+  prefer: named exports
+  avoid: default exports
+
+patterns: |
+  // Named imports
+  import { User, UserService } from './user';
+
+  // Namespace import for large APIs
+  import * as fs from 'fs';
+
+  // Named exports
+  export interface User { }
+  export function createUser() { }
+```
+
+### 11. Disallowed Features
+
+```yaml
+never_use:
+  - eval() or dynamic code evaluation
+  - with statements
+  - const enum (use plain enum)
+  - debugger statements in production
+  - Modifying built-in prototypes
+  - Wrapper objects (new String(), new Boolean())
+  - Automatic semicolon insertion reliance
+```
+
+## Application
+
+When writing or reviewing TypeScript code:
+
+1. **Always** enable strict mode
+2. **Always** use explicit return types for public APIs
+3. **Prefer** unknown over any
+4. **Prefer** interfaces for object types
+5. **Use** const by default
+6. **Use** triple equals exclusively
+7. **Handle** errors with typed catch blocks
+8. **Avoid** default exports