H Rig Patterns 🚀

Target: @h-rig/core Context: Config and plugin composition library for Rig’s OMP extension ecosystem. Pure task-graph and engine logic. No app-shell assumptions.

🚀 Quick Start

• Purpose: Orchestrates Rig configuration, plugin metadata, task graphs, and runtime dependency injection using effect Schemas.
• Initialization: Wrap configuration in defineConfig() and plugins in definePlugin() to separate serializable schema metadata from executable runtime components.
• Host Generation: Pass validated plugins to createPluginHost() to build the globally deduplicated registry for hooks, skills, validators, and tasks.

🔧 Configuration & Composition Patterns

• Split Architecture (meta vs __runtime): Plugins strictly separate string-serializable metadata (skills, hooks, task sources) from executable implementations (functions).
• Config Decoding Injection: defineConfig() intercepts __runtime properties, passes the serializable metadata through strict Schema.decodeUnknownSync(RigConfig), and safely reattaches the executable __runtime objects to prevent validation from stripping them.
• Workspace Normalization: If missing, workspace defaults to checkout: "worktree", isolation: "worktree", sandbox: "enforce".

💡 Best Practices

• Use projectRoot for FS Paths: Inside TaskSourceFactoryContext, ALWAYS resolve relative config/asset paths against context.projectRoot. NEVER use process.cwd(), as servers/extensions might spawn outside the project root.
• App-Agnostic Selectors: Keep reducers and task-graph logic app-agnostic (reusable by web, TUI, server, tests). Push shared logic to @h-rig/core before duplicating in UI.
• Strict Runtime Matching: When providing runtime.validators or runtime.taskSources, ensure their IDs, category, and kind properties exactly match the metadata declared in contributes.
• Exclusive Hook Implementations: Choose exactly ONE implementation strategy per hook: a typed function inside runtime.hooks OR a string command in metadata.

🚨 Gotchas / Anti-patterns

• Anti-pattern: Leaking functions into metadata: Attempting to put functions, promises, or classes directly into RigPlugin metadata results in them being stripped or throwing errors during Schema.decodeUnknownSync().
• Anti-pattern: Partial Implementations: Registering a validator/task-source in metadata without a corresponding __runtime implementation (or vice-versa) immediately throws a fatal initialization error.
• Anti-pattern: Dual Hook Implementation: Defining a hook with both a CLI command string in metadata AND a typed implementation in __runtime.hooks throws a fatal error.
• Anti-pattern: Namespace Collisions: Reusing plugin names, validator IDs, skill IDs, or task source kinds across plugins hard-crashes createPluginHost() at boot.
• Gotcha: Mismatched Categories/Kinds: The category for validators and kind for task sources in the runtime objects must strictly equal the values declared in metadata. Any divergence causes a throw in definePlugin().
• Gotcha: Path Inconsistency: Assuming process.cwd() is the workspace root inside task-source factories breaks workspace-spawned server operations.