oh-my-customcodex 0.1.0

package/templates/.claude/skills/fix-refs/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: omcodex:fix-refs
+description: Fix broken agent references and symlinks
+scope: harness
+argument-hint: "[agent-name] [--all] [--dry-run]"
+disable-model-invocation: true
+user-invocable: true
+---
+
+# Fix References Skill
+
+Fix broken references, missing symlinks, and other agent dependency issues.
+
+## Options
+
+```
+--all, -a        Fix all agents
+--dry-run        Show what would be fixed
+--verbose, -v    Show detailed actions
+```
+
+## Workflow
+
+```
+1. Run mgr-supplier:audit to identify issues
+
+2. Fix issues:
+   ├── Missing skill references → Add
+   ├── Missing guide references → Add
+   ├── Broken paths → Update
+   └── Invalid references → Remove
+
+3. Validate fixes
+   └── Re-run mgr-supplier:audit
+```
+
+## Fixable Issues
+
+| Issue | Action |
+|-------|--------|
+| Missing skill ref | Add to agent .md file |
+| Missing guide ref | Add to agent .md file |
+| Broken path | Update path in agent .md file |
+| Invalid reference | Remove from agent .md file |
+
+## Output Format
+
+### Dry Run
+```
+[mgr-supplier:fix lang-kotlin-expert --dry-run]
+
+Analyzing: lang-kotlin-expert
+
+Issues found:
+  1. Missing guide reference: kotlin
+
+Proposed fixes:
+  1. Add guide reference to .codex/agents/lang-kotlin-expert.md
+
+No changes made (dry-run mode).
+Run without --dry-run to apply fixes.
+```
+
+### Fix Mode
+```
+[mgr-supplier:fix lang-kotlin-expert]
+
+Fixing: lang-kotlin-expert
+
+[1/2] Adding missing reference...
+  Updating: .codex/agents/lang-kotlin-expert.md
+  ✓ Guide reference added
+
+[2/2] Validating...
+  Running mgr-supplier:audit...
+  ✓ All dependencies valid
+
+Summary:
+  Fixed: 1 issue
+  Status: HEALTHY
+
+Agent lang-kotlin-expert is now healthy.
+```
+
+### Fix All
+```
+[mgr-supplier:fix --all]
+
+Scanning all agents for issues...
+
+Found issues in 2 agents:
+  - lang-kotlin-expert: 1 issue
+  - new-agent: 2 issues
+
+Fixing lang-kotlin-expert...
+  ✓ Added guide reference: kotlin
+
+Fixing new-agent...
+  ✓ Added skill reference: skill-a
+  ✓ Added skill reference: skill-b
+
+Validating all agents...
+  ✓ mgr-supplier:audit --all passed
+
+Summary:
+  Agents fixed: 2
+  Issues resolved: 3
+  All agents healthy.
+```

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

@@ -0,0 +1,325 @@
+---
+name: flutter-best-practices
+description: Flutter/Dart development best practices for widget composition, state management, and performance
+scope: core
+user-invocable: false
+---
+
+## Purpose
+
+Apply Flutter and Dart best practices from official documentation and community standards. Covers widget patterns, state management (Riverpod/BLoC), performance optimization, testing, security, and Dart 3.x language patterns.
+
+## Core Principles
+
+```
+Widget composition over inheritance
+Unidirectional data flow
+Immutable state
+const by default
+Platform-adaptive design
+```
+
+## Rules
+
+### 1. Widget Patterns
+
+```yaml
+composition:
+  prefer: "Small, focused StatelessWidget classes"
+  avoid: "Helper functions returning Widget (no Element identity)"
+  reason: "Flutter diffing depends on widget type identity"
+
+const_constructors:
+  rule: "Mark all static widgets const"
+  pattern: "const Text('Hello'), const SizedBox(height: 8)"
+  impact: "Zero rebuild cost — compile-time constant"
+
+sizing_widgets:
+  prefer: "SizedBox for spacing/sizing"
+  avoid: "Container when only size is needed"
+  reason: "SizedBox is lighter, no decoration overhead"
+
+state_choice:
+  StatelessWidget: "No mutable state, pure rendering"
+  StatefulWidget: "Local ephemeral state (animations, form input)"
+  InheritedWidget: "Data propagation down tree (base of Provider)"
+
+build_context:
+  rule: "Never store BuildContext across async gaps"
+  pattern: "Check mounted before using context after await"
+
+keys:
+  ValueKey: "When items have unique business identity"
+  ObjectKey: "When items are objects without natural key"
+  UniqueKey: "Force rebuild on every build (rare)"
+  GlobalKey: "Cross-widget state access (use sparingly)"
+
+lists:
+  prefer: "ListView.builder for >10 items (lazy construction)"
+  avoid: "ListView(children: [...]) for large lists"
+  optimization: "Set itemExtent to skip intrinsic layout passes"
+
+layout:
+  rule: "Constraints flow down, sizes flow up"
+  common_error: "Unbounded constraints in Column/Row children"
+  fix: "Wrap with Expanded/Flexible or constrain explicitly"
+
+repaint_boundary:
+  when: "Frequently repainting subtrees (animations, video, maps)"
+  effect: "Isolates paint scope, prevents cascade repaints"
+  detect: "DevTools → highlight repaints toggle"
+
+slivers:
+  prefer: "CustomScrollView + SliverList.builder for complex scrolling"
+  use_for: "Floating headers, parallax, mixed scroll content"
+  avoid: "Nested ListView in ListView"
+```
+
+Reference: guides/flutter/fundamentals.md
+
+### 2. State Management
+
+```yaml
+default_choice:
+  new_projects: "Riverpod 3.0"
+  enterprise: "BLoC 9.0"
+  simple_prototypes: "setState or Provider"
+  avoid: "GetX (maintenance crisis, runtime crashes)"
+
+riverpod_patterns:
+  reactive_read: "ref.watch(provider) — in build methods only"
+  one_time_read: "ref.read(provider) — in callbacks, onPressed"
+  never: "ref.watch inside non-build methods"
+  async_state: "AsyncNotifier + AsyncValue (loading/data/error)"
+  family: "family modifier for parameterized providers"
+  keep_alive: "Only when justified (expensive computations)"
+  invalidate_vs_refresh: "ref.invalidate() resets to loading (lazy); ref.refresh() immediate re-fetch"
+
+bloc_patterns:
+  one_event_per_action: "One UI action = one event class"
+  cubit_vs_bloc: "Cubit for simple state changes; Bloc when audit trail needed"
+  never: "Emit state in constructor body"
+  listener_vs_consumer: "BlocListener for side effects; BlocConsumer for UI + effects; BlocBuilder for UI only"
+  stream_management: "Cancel subscriptions in close()"
+
+state_immutability:
+  rule: "All state objects must be immutable"
+  tool: "freezed package for copyWith/==/hashCode generation"
+
+result_type:
+  rule: "Return Result<T> from repositories, never throw"
+  pattern: "sealed class Result<T> with Ok<T> and Error<T> subclasses"
+```
+
+Reference: guides/flutter/state-management.md
+
+### 3. Performance
+
+```yaml
+build_optimization:
+  const_widgets: "Mark immutable widgets const — zero rebuild"
+  localize_setState: "Call setState on smallest possible subtree"
+  extract_widgets: "StatelessWidget class > helper method"
+  child_parameter: "Pass static child through AnimatedBuilder to avoid rebuild"
+
+rebuild_avoidance:
+  consumer_placement: "Place Consumer/ListenableBuilder as deep as possible"
+  read_in_callbacks: "context.read<T>() not context.watch<T>() in handlers"
+  selector: "Use BlocSelector/Selector for partial state rebuilds"
+
+rendering:
+  avoid_opacity: "Use color.withValues(alpha:) (Flutter 3.27+) or AnimatedOpacity instead; color.withOpacity() is deprecated"
+  avoid_clip: "Pre-clip static content; avoid ClipRRect in animations"
+  minimize_saveLayer: "ShaderMask, ColorFilter, Chip trigger saveLayer"
+
+compute_offloading:
+  rule: "Isolate.run() for operations >16ms (one frame budget)"
+  web_compatible: "Use compute() for web-compatible apps"
+  use_for: "JSON parsing, image processing, complex filtering"
+
+frame_budget:
+  target: "<8ms build + <8ms render = 16.67ms (60fps)"
+  profiling: "flutter run --profile, not debug mode"
+  tool: "DevTools Performance view for jank detection"
+```
+
+Reference: guides/flutter/performance.md
+
+### 4. Testing
+
+```yaml
+test_pyramid:
+  unit: "Single class/function — fast, low confidence"
+  widget: "Single widget tree — fast, medium confidence"
+  integration: "Full app on device — slow, high confidence"
+  golden: "Visual regression via matchesGoldenFile()"
+
+widget_test_pattern:
+  rule: "Use pumpWidget with ProviderScope overrides, then pump/pumpAndSettle for async"
+
+mocking:
+  prefer: "mocktail (null-safe, no codegen)"
+  avoid: "Legacy mockito with build_runner"
+  fakes: "Use Fake implementations for deterministic tests"
+
+bloc_testing:
+  rule: "Use blocTest<Bloc, State> with build/act/expect pattern"
+
+coverage_target:
+  widget_tests: "80%+ for UI logic"
+  unit_tests: "90%+ for business logic"
+  integration: "Critical user flows only"
+```
+
+Reference: guides/flutter/testing.md
+
+### 5. Security
+
+```yaml
+secrets:
+  never: "Hardcode API keys, tokens, or credentials in source"
+  best: "Backend proxy for all sensitive API calls"
+  use: "--dart-define-from-file=.env for NON-SECRET build config only (feature flags, environment URLs)"
+  warning: "dart-define values are embedded in compiled binary and extractable via static analysis"
+
+storage:
+  sensitive_data: "flutter_secure_storage v10+ (Keychain/Keystore)"
+  never: "SharedPreferences for tokens, PII, or credentials"
+  ios: "AppleOptions(useSecureEnclave: true) for high-value"
+  android: "AndroidOptions(encryptedSharedPreferences: true)"
+  web_warning: "flutter_secure_storage on Web uses localStorage by default (XSS vulnerable). Use HttpOnly cookies or in-memory-only for sensitive data."
+
+network:
+  tls: "Certificate pinning (SPKI) for financial/health apps"
+  cleartext: "cleartextTrafficPermitted=false in network_security_config"
+  ios_ats: "NSAllowsArbitraryLoads=false (default, never override)"
+
+release_builds:
+  obfuscate: "--obfuscate --split-debug-info=<path>"
+  proguard: "Configure android/app/proguard-rules.pro"
+  debug_check: "Remove all kDebugMode unguarded print() calls"
+  rule: "Never ship debug APK to production"
+
+deep_links:
+  validate: "Allow-list all URI parameters with RegExp"
+  reject: "Arbitrary schemes and unvalidated paths"
+  prefer: "Universal Links (iOS) and App Links (Android) only"
+
+logging:
+  rule: "Guard print() with kDebugMode"
+  prefer: "dart:developer log() for debug output"
+  never: "Log PII, tokens, or credentials"
+```
+
+Reference: guides/flutter/security.md
+
+### 6. Dart Language Patterns
+
+```yaml
+naming:
+  types: "UpperCamelCase for classes, enums, typedefs, extensions, mixins"
+  variables: "lowerCamelCase for variables, parameters, named constants"
+  libraries: "lowercase_with_underscores for libraries, packages, directories, source files"
+  constants: "lowerCamelCase for const (NOT SCREAMING_CAPS)"
+  private: "Prefix with underscore for library-private"
+  boolean: "Prefix with is/has/can/should"
+  avoid: "Hungarian notation, type prefixes, abbreviations unless universally known"
+
+null_safety:
+  default: "Non-nullable types — use ? only when null is meaningful"
+  avoid_bang: "Minimize ! operator — use only when null is logically impossible"
+  late: "Only when initialization is guaranteed before use"
+
+sealed_classes:
+  use_for: "Exhaustive pattern matching on state/result types"
+  pattern: "sealed class with subclass per state, exhaustive switch expression"
+
+records:
+  use_for: "Lightweight multi-value returns without class boilerplate"
+  avoid: "Records for complex data — use freezed classes instead"
+
+extension_types:
+  use_for: "Zero-cost type wrappers for primitive IDs"
+
+immutability:
+  prefer: "final variables, const constructors"
+  collections: "UnmodifiableListView for exposed lists"
+  models: "freezed package for data classes"
+
+async:
+  streams: "async* yield for reactive data pipelines"
+  futures: "async/await for sequential async operations"
+  isolates: "Isolate.run() for CPU-intensive work >16ms"
+
+dynamic:
+  avoid: "dynamic type — use generics or Object? instead"
+  reason: "No compile-time type checking, reduces IDE support"
+```
+
+Reference: guides/flutter/fundamentals.md
+
+### 7. Architecture & Project Structure
+
+```yaml
+default_structure:
+  small_app: "lib/{models,services,screens,widgets}/"
+  medium_app: "lib/{ui/{core/,<feature>/},data/{repositories/,services/},domain/}"
+  large_app: "lib/{core/,features/<feature>/{data/,domain/,presentation/}}"
+
+navigation:
+  default: "go_router (official recommendation)"
+  go_vs_push: "context.go() replaces stack; context.push() adds to stack"
+
+dependency_injection:
+  riverpod: "Built-in — providers as DI (default)"
+  getit: "GetIt + injectable — for non-Riverpod projects"
+  rule: "Dependency direction always inward (UI → ViewModel → Repository → Service)"
+
+environments:
+  pattern: "Flavors + --dart-define for multi-environment builds"
+  rule: "Separate bundle IDs, API URLs, and Firebase config per flavor"
+```
+
+Reference: guides/flutter/architecture.md
+
+## Default Stack
+
+```yaml
+state_management: Riverpod 3.0
+navigation: go_router
+models: freezed + json_serializable
+di: Riverpod (built-in)
+http: dio
+linting: very_good_analysis
+testing: flutter_test + mocktail
+structure: Official MVVM (lib/{ui,data}/)
+```
+
+## Enterprise Stack
+
+```yaml
+state_management: BLoC 9.0 + Cubit
+navigation: go_router or auto_route
+models: freezed + json_serializable
+di: GetIt + injectable (or Riverpod)
+http: dio with interceptors
+testing: flutter_test + bloc_test + mocktail (80%+ coverage)
+structure: Clean Architecture (features/{feature}/{presentation,domain,data}/)
+```
+
+## Application
+
+When writing or reviewing Flutter/Dart code:
+
+1. **Always** use const constructors for static widgets
+2. **Always** return Result<T> from repositories, never throw
+3. **Always** use flutter_secure_storage for sensitive data
+4. **Prefer** Riverpod 3.0 for new projects, BLoC for enterprise
+5. **Prefer** StatelessWidget classes over helper functions
+6. **Prefer** sealed classes for state/result types (exhaustive matching)
+7. **Use** freezed for all data model classes
+8. **Use** go_router for navigation with deep linking
+9. **Guard** all print() with kDebugMode
+10. **Never** use GetX for new projects (maintenance risk)
+11. **Never** store sensitive data in SharedPreferences
+12. **Never** hardcode API keys in source code

package/templates/.claude/skills/gemini-exec/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: gemini-exec
+description: Execute Gemini CLI prompts and return results
+scope: core
+argument-hint: "<prompt> [--json] [--stream-json] [--output <path>] [--model <name>] [--timeout <ms>] [--sandbox] [--plan]"
+user-invocable: true
+---
+
+# Gemini Exec Skill
+
+Execute Google Gemini CLI prompts in non-interactive mode and return structured results. Enables Claude + Gemini hybrid workflows.
+
+## Options
+
+```
+<prompt>          Required. The prompt to send to Gemini CLI
+--json            Return structured JSON output (-o json)
+--stream-json     Return streaming JSON events (-o stream-json)
+--output <path>   Save response to file
+--model <name>    Model override (default: Gemini CLI default)
+--timeout <ms>    Execution timeout (default: 120000, max: 600000)
+--yolo            Enable auto-approval mode (gemini -y)
+--sandbox         Run in sandbox mode (gemini -s)
+--plan            Use plan approval mode (--approval-mode plan)
+--working-dir     Working directory for Gemini execution
+```
+
+## Workflow
+
+```
+1. Pre-checks
+   - Verify `gemini` binary is installed (which gemini)
+   - Verify authentication (GOOGLE_API_KEY, GEMINI_API_KEY, or gcloud auth)
+2. Build command
+   - Base: gemini -p "<prompt>"
+   - Apply options: -o json, -m <model>, -y, -s, --approval-mode plan
+3. Execute
+   - Run via Bash tool with timeout (default 2min, max 10min)
+   - Or use helper script: node .codex/skills/gemini-exec/scripts/gemini-wrapper.cjs
+4. Parse output
+   - Text mode: return raw stdout
+   - JSON mode: parse single JSON object, extract response field
+   - Stream-JSON mode: parse event stream, extract final assistant message
+5. Report results
+   - Format output with execution metadata
+```
+
+## Safety Defaults
+
+- `-p` flag: Non-interactive prompt mode (no session persistence)
+- Default mode: Normal approval (Gemini prompts for confirmation)
+- Override with `--yolo` only when explicitly requested
+- Sandbox mode (`-s`) available for isolated execution
+
+## Output Format
+
+### Success (Text Mode)
+```
+[Gemini Exec] Completed
+
+Model: (default)
+Duration: 23.4s
+Working Dir: /path/to/project
+
+--- Output ---
+{gemini response text}
+```
+
+### Success (JSON Mode)
+```
+[Gemini Exec] Completed (JSON)
+
+Model: (default)
+Duration: 23.4s
+
+--- Response ---
+{extracted response from JSON}
+
+--- Stats ---
+{token usage and other stats}
+```
+
+### Success (Stream-JSON Mode)
+```
+[Gemini Exec] Completed (Stream-JSON)
+
+Model: (default)
+Duration: 23.4s
+Events: 12
+
+--- Final Message ---
+{extracted final assistant message}
+```
+
+### Failure
+```
+[Gemini Exec] Failed
+
+Error: {error_message}
+Exit Code: {code}
+Suggested Fix: {suggestion}
+```
+
+## Helper Script
+
+For complex executions, use the wrapper script:
+```bash
+node .codex/skills/gemini-exec/scripts/gemini-wrapper.cjs --prompt "your prompt" [options]
+```
+
+The wrapper provides:
+- Environment validation (binary + auth checks)
+- Safe command construction
+- JSON and stream-JSON parsing with response extraction
+- Structured JSON output
+- Timeout handling with graceful termination
+
+## Examples
+
+```bash
+# Simple text prompt
+gemini-exec "explain what this project does"
+
+# JSON output with model override
+gemini-exec "list all TODO items" --json --model gemini-2.5-pro
+
+# Stream-JSON for detailed event tracking
+gemini-exec "analyze the codebase" --stream-json
+
+# Save output to file
+gemini-exec "generate a README" --output ./README.md
+
+# Sandbox mode with auto-approval
+gemini-exec "fix the failing tests" --yolo --sandbox
+
+# Plan mode for careful execution
+gemini-exec "refactor the auth module" --plan
+
+# Specify working directory
+gemini-exec "analyze the codebase" --working-dir /path/to/project
+```
+
+## Integration
+
+Works with the orchestrator pattern:
+- Main conversation delegates Gemini execution via this skill
+- Results are returned to the main conversation for further processing
+- Can be chained with other skills (e.g., dev-review after Gemini generates code)
+
+## Availability Check
+
+gemini-exec requires the Gemini CLI binary to be installed and authenticated. The skill is only usable when:
+
+1. `gemini` binary is found in PATH (`which gemini` succeeds)
+2. Authentication is valid (GOOGLE_API_KEY, GEMINI_API_KEY set, or gcloud auth active)
+
+If either check fails, this skill cannot be used. Fall back to Claude agents for the task.
+
+> **Note**: This skill is invoked via `/gemini-exec` command, delegated by the orchestrator, or suggested by routing skills when gemini is available. The intent-detection system can trigger it for research and code generation hybrid workflows.
+
+## Agent Teams Integration
+
+When used within Agent Teams (requires explicit invocation):
+
+1. **As delegated task**: orchestrator explicitly delegates gemini-exec for code generation
+2. **Hybrid workflow**: Claude team member analyzes → orchestrator invokes gemini-exec → Claude reviews
+3. **Iteration**: Team messaging enables review-fix cycles between Claude and Gemini outputs
+
+```
+Orchestrator delegates generation task
+  → /gemini-exec invoked explicitly
+  → Output returned to orchestrator
+  → Reviewer validates quality
+  → Iterate if needed
+```
+
+## Research Workflow
+
+When the orchestrator or intent-detection detects a research request:
+
+1. **Check Gemini availability**: Verify `gemini` binary and auth
+2. **If available**: Execute prompt for research
+3. **If unavailable**: Fall back to Claude's WebFetch/WebSearch
+
+### Research Command Pattern
+```
+/gemini-exec "Research and analyze: {topic}. Provide structured findings with sources." --json
+```
+
+## Code Generation Workflow
+
+When routing skills detect a code generation task and gemini is available:
+
+1. **Check availability**: Verify gemini CLI via `/tmp/.codex-env-status-*`
+2. **If available + new file creation**: Suggest hybrid workflow
+3. **Hybrid pattern**:
+   - gemini-exec generates initial code (fast, broad generation)
+   - Claude expert reviews for quality, patterns, best practices
+   - Iterate if needed
+
+### Suitable Tasks
+- New file scaffolding
+- Boilerplate generation
+- Test stub creation
+- Documentation generation
+
+### Unsuitable Tasks
+- Modifying existing code (Claude expert better at understanding context)
+- Architecture decisions (requires reasoning, not generation)
+- Bug fixes (requires deep code understanding)
+
+### Code Generation Command Pattern
+```
+/gemini-exec "Generate {description} following {framework} best practices" --yolo
+```