oh-my-customcode 0.7.0 → 0.9.0

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

@@ -0,0 +1,321 @@
+---
+name: typescript-best-practices
+description: Type-safe TypeScript patterns from industry standards
+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

package/templates/.codex/skills/update-docs/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: update-docs
+description: Sync documentation with project structure
+argument-hint: "[--check] [--target <path>]"
+disable-model-invocation: true
+---
+
+# Update Documentation Skill
+
+Ensures all documentation (AGENT.md, SKILL.md, index.yaml, AGENTS.md) accurately reflects the current project state and that agents work together organically.
+
+## Options
+
+```
+--check, -c      Check only, don't modify
+--verbose, -v    Show detailed changes
+--target, -t     Specific target to update
+```
+
+## Workflow
+
+```
+1. Scan project structure
+   ├── .codex/agents/
+   ├── .codex/skills/
+   ├── guides/
+   └── commands/
+
+2. Validate consistency
+   ├── Check agent files exist
+   ├── Check skill references exist
+   ├── Check guide references exist
+   └── Check command definitions match files
+
+3. Update documentation
+   ├── Verify all .codex/agents/*.md files
+   ├── Verify all .codex/skills/*/SKILL.md files
+   ├── Update AGENTS.md summary
+   └── Update inter-agent references
+
+4. Ensure organic integration
+   ├── Verify agent → skill mappings
+   ├── Verify agent → guide mappings
+   ├── Verify command → agent mappings
+   └── Check for orphaned resources
+```
+
+## What Gets Updated
+
+### Agent Files
+- All .codex/agents/*.md files exist and are valid
+- No orphaned or missing agents
+- Metadata is consistent
+
+### Skill Files
+- All .codex/skills/*/SKILL.md files exist
+- Skill categories reflect actual structure
+- References are valid
+
+### AGENTS.md
+- Project structure diagram
+- Agent/skill/guide counts
+- Command list
+- Summary tables
+
+### Individual Agent/Skill Files
+- Skill references in agent files
+- Guide references in agent files
+- Cross-agent references
+
+## Organic Integration Checks
+
+```yaml
+agent_skill_mapping:
+  - Each agent declares valid skills
+  - Skills are in correct category
+  - No duplicate skill declarations
+
+agent_guide_mapping:
+  - Each agent declares valid guides
+  - Guides exist in guides/
+  - Paths are relative and correct
+
+command_agent_mapping:
+  - Commands reference valid agents
+  - Agent capabilities match commands
+  - Workflow is documented
+```
+
+## Output Format
+
+### Check Mode
+```
+[/update-docs --check]
+
+Scanning project structure...
+
+Agents:
+  ✓ 15 agents found in .codex/agents/
+  ✗ Missing: lang-java21-expert.md (referenced but not found)
+
+Skills:
+  ✓ 13 skills found in .codex/skills/
+  ✓ All SKILL.md files valid
+
+Guides:
+  ✓ 12 guides declared
+  ✗ Orphan: guides/old-guide/ (exists but not referenced)
+
+AGENTS.md:
+  ✗ Agent count outdated (shows 14, actual 15)
+
+Issues Found: 3
+Run "/update-docs" to fix.
+```
+
+### Update Mode
+```
+[/update-docs]
+
+Syncing documentation with project structure...
+
+[1/3] Verifying agents
+  - Removed reference: lang-java21-expert (not found)
+  ✓ 15 → 14 agents
+
+[2/3] Verifying skills
+  ✓ No changes needed
+
+[3/3] Updating AGENTS.md
+  - Updated agent count: 14 → 15
+  - Updated summary table
+  ✓ Synced
+
+Summary:
+  Modified: 1 file
+  Removed: 1 reference
+
+All documentation synced successfully.
+```

package/templates/.codex/skills/update-external/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: update-external
+description: Update agents from external sources (GitHub, docs, etc.)
+argument-hint: "[agent-name] [--check] [--force]"
+disable-model-invocation: true
+---
+
+# Update External Sources Skill
+
+Updates agents, skills, and guides that have external sources (GitHub, official docs, etc.) to their latest versions.
+
+## Options
+
+```
+--check, -c      Check for updates without applying
+--force, -f      Force update even if current
+--verbose, -v    Show detailed changes
+```
+
+## External Sources
+
+### Agents
+```yaml
+fe-vercel-agent:
+  source: https://github.com/vercel-labs/agent-skills
+  type: github
+```
+
+### Skills (from external agents)
+```yaml
+react-best-practices:
+  source: https://github.com/vercel-labs/agent-skills
+  type: github
+
+web-design-guidelines:
+  source: https://github.com/vercel-labs/agent-skills
+  type: github
+```
+
+### Guides (reference documentation)
+```yaml
+golang:
+  source: https://go.dev/doc/effective_go
+  type: documentation
+
+python:
+  source: https://peps.python.org/pep-0008/
+  type: documentation
+```
+
+## Workflow
+
+```
+1. Identify external resources
+   ├── Scan index.yaml files
+   ├── Find source.type = "external"
+   └── Collect URLs and versions
+
+2. Check for updates
+   ├── GitHub: Check releases/commits
+   ├── Documentation: Check last-modified
+   └── Compare with current version
+
+3. Fetch updates
+   ├── Download new content
+   ├── Parse and extract relevant parts
+   └── Validate content
+
+4. Apply updates
+   ├── Update content files
+   ├── Update version in index.yaml
+   ├── Update last_updated timestamp
+   └── Run mgr-supplier:audit to validate
+```
+
+## Version Tracking
+
+Updates are tracked in each resource's index.yaml:
+
+```yaml
+source:
+  type: external
+  origin: github
+  url: https://github.com/vercel-labs/agent-skills
+  version: "1.2.0"
+  last_updated: "2026-01-22"
+  update_history:
+    - version: "1.0.0"
+      date: "2026-01-20"
+    - version: "1.2.0"
+      date: "2026-01-22"
+```
+
+## Output Format
+
+### Check Mode
+```
+[mgr-updater:external --check]
+
+Checking for external updates...
+
+Agents:
+  fe-vercel-agent
+    Current: v1.0.0
+    Latest:  v1.2.0
+    Status:  UPDATE AVAILABLE
+
+Skills:
+  react-best-practices
+    Source: github.com/vercel-labs/agent-skills
+    Status: UPDATE AVAILABLE (linked to agent)
+
+Guides:
+  golang
+    Source: go.dev/doc/effective_go
+    Last fetched: 2026-01-22
+    Status: UP TO DATE
+
+Summary:
+  Updates available: 1 agent, 1 skill
+  Up to date: 11 guides
+
+Run "mgr-updater:external" to apply updates.
+```
+
+### Update Mode
+```
+[mgr-updater:external]
+
+Updating external resources...
+
+[1/2] Updating fe-vercel-agent
+  Fetching from github.com/vercel-labs/agent-skills...
+  ✓ Downloaded v1.2.0
+  ✓ Updated AGENT.md
+  ✓ Updated index.yaml (version: 1.0.0 → 1.2.0)
+  ✓ Updated related skills
+
+[2/2] Validating updates
+  Running mgr-supplier:audit...
+  ✓ All dependencies valid
+
+Summary:
+  Updated: 1 agent
+  Synced: 3 skills
+  Validated: ✓
+
+All external resources updated successfully.
+```

package/templates/.codex/skills/vercel-deploy/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: vercel-deploy
+description: Deploy applications to Vercel with auto-detection and preview URLs
+---
+
+## When to Use
+
+- Deploy application to Vercel
+- Create preview deployments
+- Generate shareable URLs
+
+## Features
+
+### Framework Detection
+```
+Auto-detects 40+ frameworks from package.json:
+- Next.js
+- React
+- Vue
+- Nuxt
+- Svelte
+- Astro
+- and more...
+```
+
+### Auto Exclusions
+```
+Automatically excludes:
+- node_modules/
+- .git/
+- .env files
+```
+
+### Output
+```
+On successful deployment:
+1. Preview URL (view deployment)
+2. Claim URL (transfer ownership)
+```
+
+## Execution Flow
+
+```
+1. Detect project framework
+2. Prepare deployment bundle
+3. Upload to Vercel
+4. Return URLs
+```
+
+## Output Format
+
+```
+[Deploy Success]
+Preview: https://project-xxx.vercel.app
+Claim: https://vercel.com/claim/xxx
+```
+
+## Scripts
+
+See `scripts/deploy.sh` for deployment automation.
+
+## Requirements
+
+- Valid project structure
+- package.json present
+- Vercel CLI or API token (for authenticated deploys)
+
+## Limitations
+
+- Claimable deploys are anonymous
+- Preview URLs are temporary
+- Full features require Vercel account
+```