OAC Provider/Adapter Pattern — Final Recommendation

Document: 14-PROVIDER-PATTERN-FINAL.md Status: FINAL — authoritative before implementation starts Date: 2026-02-19 Author: Architecture Review Drives: Projects P1–P6 (all 6 projects)

This document is the final word on provider/adapter architecture. No deviation from these patterns without a formal ADR. Implementation begins with these interfaces locked.

1. The Chosen Pattern

Decision: Option C — Hybrid. Separate typed interfaces per subsystem sharing a common OACPlugin composition type.

Evaluation Matrix

Criterion	Option A (Vite Monolith)	Option B (Separate Interfaces)	Option C (Hybrid)
Simplicity for community authors	Medium — one big object, most hooks irrelevant	High — implement only your subsystem	High — each interface is small and focused
TypeScript inference	Poor — optional methods on monolith collapse to `undefined` everywhere	Excellent — each interface fully typed	Excellent — each interface fully typed
OpenCode compatibility	Neutral	Neutral	Best — `OACPlugin` maps cleanly to OpenCode's plugin type
Composability	Poor — can't mix providers	Medium — wire manually	Best — `defineConfig()` composes cleanly
Testability	Poor — mock entire monolith	Excellent — mock one interface	Excellent — mock one interface
Fit with existing BaseAdapter	Poor — BaseAdapter is a class, not a hook object	Good — direct mapping	Best — IIDEAdapter extends the same contract
Plugin author DX	Poor — "which hook do I implement?"	Good	Best — `implements IContextProvider` is unambiguous

Rationale

Option A (Vite monolith) is rejected because OAC's subsystems have fundamentally different dispatch semantics:

Context resolution is first-match-wins (one provider answers)
IDE adapters are fan-out (all adapters write in parallel)
Registry lookup is priority-ordered fallthrough

These cannot coexist correctly in a single optional-hook object without obscuring the semantics behind comments. A NotionContextProvider author does not need to know about IDE adapter hooks, and giving them an object with 25 optional methods is hostile.

Option B (pure separation) is good but loses the composition story. Users need one place to hand OAC their full configuration without assembling a ProviderRegistry manually.

Option C gives the best of both:

Each interface is small, focused, and semantically unambiguous
OACPlugin is the user-facing composition type — what goes in oac.config.ts
defineConfig() provides the helper that validates and assembles everything
The ProviderRegistry (internal to the CLI) wires dispatch semantics

The Vite-style hooks apply at the ProviderRegistry dispatch level, not at the interface level. The registry implements callFirst() and callAll() dispatch internally. Plugin authors just implement IContextProvider, not "hooks".

2. Final TypeScript Interfaces

These are authoritative. They go verbatim into packages/core/src/.

2.1 Supporting Types (`packages/core/src/types/index.ts`)

// ============================================================================
// Primitive Types
// ============================================================================

export type ComponentType = 'agent' | 'skill' | 'context' | 'plugin';
export type UpdateMode = 'manual' | 'auto-safe' | 'auto-all' | 'locked';
export type ConflictStrategy = 'ask' | 'skip' | 'overwrite' | 'backup' | 'yolo';
export type InstallLocation = 'local' | 'global';
export type ContextLayerName =
  | 'project-override'    // L1: .oac/context/
  | 'project-context'     // L2: .opencode/context/
  | 'ide-specific'        // L3: .claude/context/, .cursor/context/
  | 'project-docs'        // L4: docs/context/
  | 'user-global'         // L5: ~/.config/oac/context/
  | 'oac-bundled';        // L6: npm package (lowest priority)

// ============================================================================
// Shared Result Types
// ============================================================================

export interface ValidationResult {
  valid: boolean;
  errors: string[];
  warnings: string[];
}

export interface OACOperationResult<T = void> {
  success: boolean;
  data?: T;
  errors: string[];
  warnings: string[];
}

// ============================================================================
// Context Types
// ============================================================================

export interface ContextFile {
  /** Relative name used to resolve the file, e.g. "core/standards/code-quality.md" */
  name: string;
  content: string;
  /** Absolute path on disk */
  path: string;
  layer: ContextLayerName;
  /** True if the installed SHA256 differs from the bundled SHA256 */
  userOwned: boolean;
  sha256: string;
}

export interface ContextQuery {
  category?: string;
  layer?: ContextLayerName;
  userOwned?: boolean;
  tags?: string[];
}

// ============================================================================
// Task Management Types
// ============================================================================

export type TaskStatus = 'pending' | 'in_progress' | 'completed' | 'blocked' | 'skipped';
export type TaskPriority = 'critical' | 'high' | 'medium' | 'low';

export interface Task {
  id: string;
  title: string;
  description?: string;
  status: TaskStatus;
  priority: TaskPriority;
  dependencies: string[]; // task IDs
  assignee?: string;
  metadata?: Record<string, unknown>;
}

export interface TaskSession {
  id: string;
  feature: string;
  createdAt: string; // ISO 8601
  updatedAt: string;
  tasks: Task[];
  completedCount: number;
  totalCount: number;
}

// ============================================================================
// Registry Types
// ============================================================================

export interface RegistryFile {
  /** Path within the registry item's source */
  path: string;
  type: string; // e.g. "oac:agent-config", "oac:agent-prompt", "oac:skill"
  /** Install target relative to project root */
  target: string;
}

export interface RegistryItem {
  name: string;
  type: ComponentType;
  title: string;
  description: string;
  version: string;
  ides: string[];
  registryDependencies: string[];
  files: RegistryFile[];
  sha256?: string;
  publishedAt?: string;
  author?: string;
  tags?: string[];
}

export interface RegistrySearchOptions {
  type?: ComponentType;
  ide?: string;
  tags?: string[];
  limit?: number;
  offset?: number;
}

// ============================================================================
// IDE Adapter Types
// ============================================================================

export interface IDECapabilities {
  /** IDE identifier, e.g. "opencode", "cursor", "claude", "windsurf" */
  id: string;
  displayName: string;
  supportsMultipleAgents: boolean;
  supportsSkills: boolean;
  supportsHooks: boolean;
  supportsGranularPermissions: boolean;
  supportsContexts: boolean;
  supportsCustomModels: boolean;
  supportsTemperature: boolean;
  supportsMaxSteps: boolean;
  configFormat: 'markdown' | 'yaml' | 'json' | 'plain';
  outputStructure: 'single-file' | 'multi-file' | 'directory';
  notes?: string[];
}

export interface IDEOutputFile {
  /** Absolute path to write */
  path: string;
  content: string;
  encoding?: 'utf-8' | 'base64';
}

export interface IDEAdapterResult {
  success: boolean;
  files: IDEOutputFile[];
  warnings: string[];
  errors: string[];
}

// ============================================================================
// Agent Profile Types
// ============================================================================

export interface AgentProfile {
  name: string;
  displayName: string;
  description: string;
  /** Agent IDs included in this profile */
  agents: string[];
  /** Skill IDs included in this profile */
  skills: string[];
  /** Context profile name (from manifest.json profiles) */
  contextProfile?: string;
}

// ============================================================================
// OAC Agent (canonical internal representation)
// ============================================================================

/**
 * OACAgent is the canonical internal representation of an agent.
 * It is the type that flows between subsystems. Adapters convert
 * to/from this type. It is NOT the same as OpenAgent (the legacy
 * compatibility-layer type).
 */
export interface OACAgent {
  /** From agent.json */
  config: import('../schemas/agent.js').AgentConfig;
  /** From prompt.md — the prose content */
  promptMd: string;
  /** From system.md — optional system prompt override */
  systemMd?: string;
  /** Resolved source path */
  sourcePath: string;
}

// ============================================================================
// OAC Context (resolved context file for IDE adapter consumption)
// ============================================================================

export type OACContext = ContextFile;

2.2 Provider Interfaces (`packages/core/src/providers/`)

`context.ts`

import type { ContextFile, ContextQuery, ValidationResult } from '../types/index.js';

/**
 * Provides context files to OAC's resolution pipeline.
 *
 * The default implementation is the 6-layer filesystem resolver.
 * Replace with a Notion/Confluence/custom implementation by pointing
 * config.providers.context at your package.
 *
 * Dispatch: callFirst() — first provider that returns non-null wins.
 */
export interface IContextProvider {
  /** Unique stable identifier, e.g. "oac-default", "notion", "confluence" */
  readonly id: string;
  readonly displayName: string;

  /**
   * Resolve a single context file by name.
   * Return null if this provider does not have the file.
   */
  resolve(name: string): Promise<ContextFile | null>;

  /** List all context files this provider can serve. */
  list(query?: ContextQuery): Promise<ContextFile[]>;

  /**
   * Install a context file.
   * Called by `oac context install`.
   */
  install(name: string, source: string | Buffer): Promise<void>;

  /**
   * Update an existing context file if the installed version matches
   * expectedSha256. Returns 'skipped' if user-modified, 'conflict' if
   * the new content differs from expected.
   */
  update(
    name: string,
    newContent: string,
    expectedSha256: string
  ): Promise<'updated' | 'skipped' | 'conflict'>;

  /**
   * Return true if the installed file at `name` has been modified
   * relative to `installedSha256`.
   */
  isModified(name: string, installedSha256: string): Promise<boolean>;

  /** Full validation of a named context file. */
  validate(name: string): Promise<ValidationResult>;
}

`task-management.ts`

import type { Task, TaskSession } from '../types/index.js';

/**
 * Manages task sessions for OAC's agent workflow system.
 *
 * The default implementation stores sessions as JSON in .tmp/tasks/.
 * Replace with a Linear/Jira/GitHub Issues implementation.
 *
 * Dispatch: single provider — no fan-out.
 */
export interface ITaskManagementProvider {
  readonly id: string;
  readonly displayName: string;

  /** Create a new task session with the given tasks. */
  createSession(tasks: Omit<Task, 'id'>[], feature: string): Promise<TaskSession>;

  /** Get the current active session, or null if none. */
  getCurrentSession(): Promise<TaskSession | null>;

  /**
   * Get the next eligible task (no unmet dependencies, status=pending).
   * Returns null when all tasks are complete.
   */
  getNextTask(sessionId: string): Promise<Task | null>;

  /** Mark a task as completed. */
  completeTask(sessionId: string, taskId: string): Promise<void>;

  /** List all sessions (active and archived). */
  listSessions(): Promise<TaskSession[]>;

  /** Delete sessions older than the given number of days. Returns count deleted. */
  cleanSessions(olderThanDays: number): Promise<number>;
}

`registry.ts`

import type { RegistryItem, RegistryFile, RegistrySearchOptions, ComponentType } from '../types/index.js';

/**
 * Provides access to a component registry.
 *
 * The default implementation talks to registry.nextsystems.dev.
 * Replace with a private enterprise registry.
 *
 * Dispatch: callFirst() in priority order — highest-priority registry that
 * has the component wins. All registries participate in search (merged).
 */
export interface IRegistryProvider {
  readonly id: string;
  readonly displayName: string;
  /** Base URL of this registry, used for display and auth. */
  readonly baseUrl: string;
  /** Higher number = higher priority in multi-registry resolution. */
  readonly priority: number;

  /** Fetch metadata for a specific component. Throws if not found. */
  fetch(name: string, type: ComponentType): Promise<RegistryItem>;

  /** Search the registry. Returns empty array (not throws) if no results. */
  search(query: string, options?: RegistrySearchOptions): Promise<RegistryItem[]>;

  /**
   * Download all files for a registry item.
   * Returns array of { file, content } pairs ready to write to disk.
   */
  download(item: RegistryItem): Promise<Array<{ file: RegistryFile; content: string }>>;

  /** Health check. Returns true if registry is reachable. */
  ping(): Promise<boolean>;

  /** Get the latest published version string for a component. */
  getLatestVersion(name: string, type: ComponentType): Promise<string>;
}

`ide-adapter.ts`

import type { OACAgent, OACContext, IDEAdapterResult, IDECapabilities, ValidationResult } from '../types/index.js';

/**
 * Converts OAC agents to IDE-specific configuration formats.
 *
 * Built-in implementations: OpenCode, Claude Code, Cursor, Windsurf.
 * Community extensions: JetBrains, Zed, etc.
 *
 * Dispatch: callAll() — ALL registered IDE adapters run in parallel.
 * Each adapter writes its own output files.
 */
export interface IIDEAdapter {
  /** Unique stable identifier, e.g. "opencode", "cursor", "claude", "windsurf" */
  readonly id: string;
  readonly displayName: string;

  /**
   * Convert OAC agents + context to this IDE's format.
   * Returns file paths and content to write, plus warnings.
   * MUST NOT write to disk — the caller writes the files.
   */
  fromOAC(agents: OACAgent[], context: OACContext[]): Promise<IDEAdapterResult>;

  /**
   * Parse this IDE's config format back to OAC agents.
   * Used by `oac compat import`.
   * `source` is the raw file content.
   */
  toOAC(source: string): Promise<OACAgent[]>;

  /**
   * Return the output directory/file path for this IDE.
   * Relative to project root, e.g. ".opencode", ".cursorrules".
   */
  getOutputPath(): string;

  /** Describe what this IDE supports. */
  getCapabilities(): IDECapabilities;

  /**
   * Validate the result before writing. Called after fromOAC().
   * Returns warnings about feature loss, size limits, etc.
   */
  validate(result: IDEAdapterResult): ValidationResult;
}

`agent-profile.ts`

import type { AgentProfile } from '../types/index.js';

/**
 * Provides agent profiles (developer, minimal, enterprise, etc.).
 *
 * The default implementation reads from the OAC npm package manifest.
 * Enterprise users can point this at an internal profile registry.
 *
 * Dispatch: callFirst() — first provider that has the profile wins.
 */
export interface IAgentProfileProvider {
  readonly id: string;
  readonly displayName: string;

  /** List all available profiles. */
  list(): Promise<AgentProfile[]>;

  /** Get a profile by name. Returns null if not found. */
  get(name: string): Promise<AgentProfile | null>;

  /** Check if a profile exists. */
  has(name: string): Promise<boolean>;
}

2.3 `OACPlugin` — User-Facing Composition Type (`packages/core/src/plugin.ts`)

import type { IContextProvider } from './providers/context.js';
import type { ITaskManagementProvider } from './providers/task-management.js';
import type { IRegistryProvider } from './providers/registry.js';
import type { IIDEAdapter } from './providers/ide-adapter.js';
import type { IAgentProfileProvider } from './providers/agent-profile.js';

/**
 * OACPlugin is what a user (or enterprise author) exports from oac.config.ts.
 *
 * All fields are optional. OAC uses defaults for any field not provided.
 *
 * @example
 * ```ts
 * // oac.config.ts
 * import { defineConfig } from '@nextsystems/oac-core';
 * import { NotionContextProvider } from '@my-company/oac-notion-context';
 * import { LinearTaskProvider } from '@my-company/oac-linear';
 *
 * export default defineConfig({
 *   context: new NotionContextProvider({ token: process.env.NOTION_TOKEN! }),
 *   taskManagement: new LinearTaskProvider({ apiKey: process.env.LINEAR_KEY! }),
 *   ideAdapters: [process.env.CI && new CIOnlyAdapter()].filter(Boolean),
 * });
 * ```
 */
export interface OACPlugin {
  /**
   * Replace the default 6-layer filesystem context resolver.
   * Provide ONE context provider. If multiple are needed, compose them
   * inside a wrapper that implements IContextProvider.
   */
  context?: IContextProvider;

  /**
   * Replace the default JSON-file task management system.
   */
  taskManagement?: ITaskManagementProvider;

  /**
   * Additional registry providers, prepended before the official registry.
   * The first registry in this array that finds a component wins.
   * The official registry is always appended as the final fallback.
   */
  registries?: IRegistryProvider[];

  /**
   * Additional IDE adapters. These are run IN ADDITION TO built-in adapters
   * unless you also set `replaceBuiltInAdapters: true`.
   *
   * Falsy values are filtered (enables: `process.env.CI && new CIAdapter()`).
   */
  ideAdapters?: Array<IIDEAdapter | false | null | undefined>;

  /**
   * If true, built-in IDE adapters (OpenCode, Claude, Cursor, Windsurf) are
   * NOT registered. Your `ideAdapters` array is the complete set.
   * Default: false.
   */
  replaceBuiltInAdapters?: boolean;

  /**
   * Additional agent profile providers, tried before the built-in manifest profiles.
   */
  profileProviders?: IAgentProfileProvider[];
}

2.4 `defineConfig()` Helper (`packages/core/src/define-config.ts`)

import type { OACPlugin } from './plugin.js';

/**
 * Type-safe configuration helper. Validates the shape of your plugin
 * configuration at TypeScript compile time and provides IDE autocomplete.
 *
 * This is a pure identity function at runtime — it exists solely for
 * TypeScript's benefit and to signal intent to readers.
 *
 * @example
 * ```ts
 * // oac.config.ts
 * import { defineConfig } from '@nextsystems/oac-core';
 *
 * export default defineConfig({
 *   context: new NotionContextProvider(),
 * });
 * ```
 */
export function defineConfig(plugin: OACPlugin): OACPlugin {
  return plugin;
}

2.5 `ProviderRegistry` — Internal Wiring (`packages/core/src/provider-registry.ts`)

import type { IContextProvider } from './providers/context.js';
import type { ITaskManagementProvider } from './providers/task-management.js';
import type { IRegistryProvider } from './providers/registry.js';
import type { IIDEAdapter } from './providers/ide-adapter.js';
import type { IAgentProfileProvider } from './providers/agent-profile.js';
import type { OACPlugin } from './plugin.js';

export class ProviderRegistryError extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'ProviderRegistryError';
  }
}

/**
 * ProviderRegistry is the internal wiring layer used by the CLI.
 * It is NOT a singleton. Each CLI invocation creates one via
 * `createProviderRegistry(config, plugin)`.
 *
 * Dispatch semantics:
 * - Context: callFirst() — first provider returning non-null wins
 * - Task management: single provider
 * - Registry: callFirst() in priority order, all participate in search
 * - IDE adapters: callAll() — all run in parallel
 * - Profile providers: callFirst() — first provider returning non-null wins
 */
export class ProviderRegistry {
  private _context: IContextProvider;
  private _taskManagement: ITaskManagementProvider;
  private _registries: IRegistryProvider[];
  private _ideAdapters: Map<string, IIDEAdapter>;
  private _profileProviders: IAgentProfileProvider[];

  // Use createProviderRegistry() — not this constructor directly
  constructor(
    context: IContextProvider,
    taskManagement: ITaskManagementProvider,
    registries: IRegistryProvider[],
    ideAdapters: IIDEAdapter[],
    profileProviders: IAgentProfileProvider[]
  ) {
    this._context = context;
    this._taskManagement = taskManagement;
    // Sort registries by priority descending
    this._registries = [...registries].sort((a, b) => b.priority - a.priority);
    this._ideAdapters = new Map(ideAdapters.map(a => [a.id, a]));
    this._profileProviders = profileProviders;
  }

  // ── Context ──────────────────────────────────────────────────────────────

  get context(): IContextProvider {
    return this._context;
  }

  // ── Task Management ──────────────────────────────────────────────────────

  get taskManagement(): ITaskManagementProvider {
    return this._taskManagement;
  }

  // ── Registry ─────────────────────────────────────────────────────────────

  get registries(): IRegistryProvider[] {
    return this._registries;
  }

  getRegistry(id: string): IRegistryProvider | undefined {
    return this._registries.find(r => r.id === id);
  }

  /**
   * callFirst() for registry fetch/version lookup.
   * Tries each registry in priority order, returns first success.
   */
  async resolveFromRegistry<T>(
    fn: (registry: IRegistryProvider) => Promise<T>
  ): Promise<T> {
    const errors: Error[] = [];
    for (const registry of this._registries) {
      try {
        return await fn(registry);
      } catch (err) {
        errors.push(err instanceof Error ? err : new Error(String(err)));
      }
    }
    throw new ProviderRegistryError(
      `No registry satisfied the request. Errors:\n${errors.map(e => `  - ${e.message}`).join('\n')}`
    );
  }

  // ── IDE Adapters ─────────────────────────────────────────────────────────

  getIDEAdapter(id: string): IIDEAdapter | undefined {
    return this._ideAdapters.get(id);
  }

  get ideAdapters(): IIDEAdapter[] {
    return Array.from(this._ideAdapters.values());
  }

  /**
   * callAll() for IDE adapter output generation.
   * Runs all adapters in parallel. Partial failures are collected,
   * not thrown — the caller decides what to do with failed adapters.
   */
  async runAllAdapters(
    fn: (adapter: IIDEAdapter) => Promise<void>
  ): Promise<Map<string, Error | null>> {
    const results = new Map<string, Error | null>();
    await Promise.all(
      Array.from(this._ideAdapters.entries()).map(async ([id, adapter]) => {
        try {
          await fn(adapter);
          results.set(id, null);
        } catch (err) {
          results.set(id, err instanceof Error ? err : new Error(String(err)));
        }
      })
    );
    return results;
  }

  // ── Profile Providers ────────────────────────────────────────────────────

  get profileProviders(): IAgentProfileProvider[] {
    return this._profileProviders;
  }

  /**
   * callFirst() for profile resolution.
   */
  async resolveProfile(name: string): Promise<import('./types/index.js').AgentProfile | null> {
    for (const provider of this._profileProviders) {
      const profile = await provider.get(name);
      if (profile !== null) return profile;
    }
    return null;
  }
}

/**
 * Factory function — the ONLY way to create a ProviderRegistry.
 * Never export `new ProviderRegistry()` or a module-level instance.
 *
 * The CLI calls this once per invocation after loading oac.config.ts.
 * Tests call this with mock providers for isolation.
 */
export async function createProviderRegistry(
  plugin: OACPlugin,
  defaults: {
    context: IContextProvider;
    taskManagement: ITaskManagementProvider;
    officialRegistry: IRegistryProvider;
    builtInAdapters: IIDEAdapter[];
    builtInProfileProvider: IAgentProfileProvider;
  }
): Promise<ProviderRegistry> {
  const context = plugin.context ?? defaults.context;
  const taskManagement = plugin.taskManagement ?? defaults.taskManagement;

  const registries: IRegistryProvider[] = [
    ...(plugin.registries ?? []),
    defaults.officialRegistry,
  ];

  const ideAdapters: IIDEAdapter[] = plugin.replaceBuiltInAdapters
    ? (plugin.ideAdapters?.filter(Boolean) as IIDEAdapter[] ?? [])
    : [
        ...defaults.builtInAdapters,
        ...(plugin.ideAdapters?.filter(Boolean) as IIDEAdapter[] ?? []),
      ];

  const profileProviders: IAgentProfileProvider[] = [
    ...(plugin.profileProviders ?? []),
    defaults.builtInProfileProvider,
  ];

  return new ProviderRegistry(
    context,
    taskManagement,
    registries,
    ideAdapters,
    profileProviders
  );
}

3. How Existing Code Maps In

3.1 AdapterRegistry → ProviderRegistry

AdapterRegistry is kept in packages/compatibility-layer/ for backward compatibility with the 236 existing tests. It is not moved — its role is narrower (IDE adapter storage). ProviderRegistry is the new top-level wiring for all subsystems.

AdapterRegistry (existing)         ProviderRegistry (new)
──────────────────────────         ───────────────────────
register(adapter, aliases)    →    constructor(ideAdapters: IIDEAdapter[])
get(nameOrAlias)              →    getIDEAdapter(id)
getAll()                      →    ideAdapters getter
findByFeature(feature)        →    (move to IDE-specific query utilities)
registerBuiltInAdapters()     →    defaults.builtInAdapters in createProviderRegistry()
export const registry = ...   →    DELETED (see §3.3)

AdapterRegistry.registerBuiltInAdapters() becomes a function in packages/cli/src/defaults.ts:

// packages/cli/src/defaults.ts
export async function loadBuiltInAdapters(): Promise<IIDEAdapter[]> {
  const adapters: IIDEAdapter[] = [];
  const modules = [
    ['opencode', () => import('./adapters/opencode.js')],
    ['claude',   () => import('./adapters/claude.js')],
    ['cursor',   () => import('./adapters/cursor.js')],
    ['windsurf', () => import('./adapters/windsurf.js')],
  ] as const;

  for (const [id, loader] of modules) {
    try {
      const mod = await loader();
      adapters.push(mod.default);
    } catch {
      // Adapter not available in this build — skip silently
    }
  }
  return adapters;
}

3.2 BaseAdapter → IIDEAdapter

BaseAdapter maps to IIDEAdapter as follows:

BaseAdapter	IIDEAdapter	Notes
`abstract name: string`	`readonly id: string`	Renamed for clarity
`abstract displayName: string`	`readonly displayName: string`	Same
`abstract toOAC(source: string): Promise<OpenAgent>`	`toOAC(source: string): Promise<OACAgent[]>`	Now returns array (multi-agent IDEs)
`abstract fromOAC(agent: OpenAgent): Promise<ConversionResult>`	`fromOAC(agents: OACAgent[], context: OACContext[]): Promise<IDEAdapterResult>`	Takes all agents + context
`abstract getConfigPath(agent?)`	`getOutputPath(): string`	Simplified — path is static per IDE
`abstract getCapabilities(): ToolCapabilities`	`getCapabilities(): IDECapabilities`	`ToolCapabilities` renamed `IDECapabilities`
`abstract validateConversion(agent)`	`validate(result: IDEAdapterResult): ValidationResult`	Validates output, not input

Migration approach: existing ClaudeAdapter, CursorAdapter, WindsurfAdapter stay in packages/compatibility-layer/ and continue extending BaseAdapter. In Project 5, new adapter implementations in packages/cli/src/adapters/ implement IIDEAdapter directly. Both patterns coexist during the transition.

3.3 Singleton Fix (Critical — Blocks Test Isolation)

Before (packages/compatibility-layer/src/core/AdapterRegistry.ts:358):

// BUG: Module-level singleton — shared state bleeds between tests
export const registry = new AdapterRegistry();

After:

// DELETED — do not export a module-level instance

// Keep the class and export it:
export { AdapterRegistry } from './AdapterRegistry.js';

// The CLI creates its own instance:
// const reg = new AdapterRegistry();
// await reg.registerBuiltInAdapters();

For the CLI (packages/cli/src/index.ts):

// One instance per CLI invocation — created in the command handler, not at module load
async function runCommand(args: string[]): Promise<void> {
  const config = await loadOACConfig();
  const plugin = await loadUserPlugin(config);
  const registry = await createProviderRegistry(plugin, await loadDefaults(config));
  // pass `registry` into command handlers
}

For the compatibility-layer tests (backward-compatible fix, no test changes):

In test setup files, replace:

import { registry } from '../core/AdapterRegistry.js';
// registry is the same singleton for all tests — BAD

with:

import { AdapterRegistry } from '../core/AdapterRegistry.js';
const registry = new AdapterRegistry(); // fresh instance per test

If the tests import from the old path, add a beforeEach reset:

import { registry } from '../core/AdapterRegistry.js';
beforeEach(() => registry.clear()); // temporary mitigation

This is the minimal fix that doesn't break the 236 tests while the full migration proceeds.

3.4 AgentLoader Module Globals Fix

Before (packages/compatibility-layer/src/core/AgentLoader.ts:169):

// BUG: Module globals — bleed between tests, never invalidated
let cachedMetadata: Record<string, Partial<OpenAgent["metadata"]>> = {};
let metadataLoaded = false;

After — move cache into the class instance:

export class AgentLoader {
  private projectRoot?: string;
  // Cache lives on the instance, not the module
  private cachedMetadata: Record<string, Partial<OpenAgent["metadata"]>> | null = null;

  constructor(projectRoot?: string) {
    this.projectRoot = projectRoot;
  }

  private loadMetadataFile(): Record<string, Partial<OpenAgent["metadata"]>> {
    if (this.cachedMetadata !== null) {
      return this.cachedMetadata;
    }
    // ... same file loading logic ...
    this.cachedMetadata = parsed.agents || {};
    return this.cachedMetadata;
  }
}

Tests that need a fresh metadata load: new AgentLoader(testRoot) — the fresh instance has no cache. No test changes required.

3.5 Types From `types.ts`: Keep / Fix / Replace

Type	Action	Reason
`ToolAccessSchema`	Keep — move to core	Still valid
`PermissionRuleSchema`	Keep — move to core	Still valid
`GranularPermissionSchema`	Keep — move to core	Still valid
`ContextPrioritySchema`	Keep — move to core	Still valid
`ModelIdentifierSchema`	Fix — `z.union([z.string(), z.string()])` → `z.string()`	Union of identical types is a bug
`TemperatureSchema`	Fix — add `.min(0).max(2)`	Unconstrained allows nonsense values
`AgentMetadataSchema`	Fix — make consistent with `OpenAgentSchema.metadata` (all optional or all required — pick one)	Strict vs loose mismatch causes validation failures
`OpenAgentSchema.metadata`	Fix — align with `AgentMetadataSchema`	One or the other must be the canonical shape
`ToolCapabilities`	Rename → `IDECapabilities` in core	More precise name, same fields
`ConversionResult`	Replace → `IDEAdapterResult` in core	Richer type (files vs configs, better error model)
`ToolConfig`	Keep in compat-layer — used by existing adapters	Not needed in core
`AgentFrontmatterSchema`	Keep — move to core	Canonical schema
`OpenAgentSchema`	Keep — move to core, fix metadata inconsistency	Canonical

Schema fix — ModelIdentifierSchema:

// Before (bug):
export const ModelIdentifierSchema = z.union([z.string(), z.string()]);

// After:
export const ModelIdentifierSchema = z.string()
  .min(1)
  .describe('Model identifier, e.g. "claude-opus-4-5", "gpt-4o", "gemini-2.0-flash"');

Schema fix — TemperatureSchema:

// Before (unconstrained):
export const TemperatureSchema = z.number();

// After:
export const TemperatureSchema = z.number()
  .min(0)
  .max(2)
  .describe('Model temperature (0.0–2.0). Most IDEs cap at 1.0.');

Schema fix — AgentMetadata strict/OpenAgent metadata loose:

// Root cause: AgentMetadataSchema requires category/type/author
// but OpenAgentSchema.metadata makes them all optional.
// Decision: OpenAgentSchema.metadata IS AgentMetadataSchema (all required except tags/deps)

export const OpenAgentSchema = z.object({
  frontmatter: AgentFrontmatterSchema,
  metadata: AgentMetadataSchema,   // Use the strict schema — it's the canonical shape
  systemPrompt: z.string(),
  contexts: z.array(ContextReferenceSchema).default([]),
  sections: z.object({ ... }).optional(),
});

4. Configuration Design

4.1 Format Decision: `oac.config.ts` (TypeScript)

Decision: oac.config.ts, not oac.config.json.

Rationale:

Providers are class instances — they cannot be expressed in JSON
Environment variable interpolation is native in TypeScript (process.env.NOTION_TOKEN!)
Conditional providers work naturally: process.env.CI && ciAdapter()
TypeScript gives compile-time validation of the config shape
defineConfig() provides full IDE autocomplete

JSON config is used for data (preferences, registries list, IDE paths). TypeScript is used for behavior (provider wiring).

The two files coexist:

.oac/config.json — committed to git, data-only, no secrets
oac.config.ts — committed to git, provider wiring, imports from npm packages
~/.config/oac/config.json — user-global preferences (not committed)

4.2 Config Loading Pipeline

// packages/cli/src/config/loader.ts

export async function loadFullConfig(cwd: string): Promise<{
  data: OACConfig;
  plugin: OACPlugin;
}> {
  // Step 1: Load data config (JSON, three-way merge)
  const defaults = getConfigDefaults();
  const globalData = await loadConfigJson('~/.config/oac/config.json');
  const projectData = await loadConfigJson(join(cwd, '.oac/config.json'));
  const envOverrides = readEnvOverrides();

  const data = OACConfigSchema.parse(
    deepMerge(defaults, globalData, projectData, envOverrides)
  );

  // Step 2: Load TypeScript plugin (optional)
  const pluginPath = join(cwd, 'oac.config.ts');
  let plugin: OACPlugin = {};

  if (await pathExists(pluginPath)) {
    // Use jiti for zero-config TS execution (no ts-node required)
    const { createJiti } = await import('jiti');
    const jiti = createJiti(import.meta.url);
    const mod = await jiti.import(pluginPath);
    plugin = mod.default ?? mod;
  }

  return { data, plugin };
}

4.3 Environment Variable Mapping

Env Var	Maps To	Type
`OAC_YOLO=true`	`data.preferences.yoloMode`	boolean
`OAC_REGISTRY_URL=https://...`	Prepends to `data.registries` with priority 0	string
`OAC_BRANCH=main`	`data.preferences.branch`	string
`OAC_INSTALL_LOCATION=global`	`data.preferences.installLocation`	`'local' \\| 'global'`
`OAC_CONFLICT_STRATEGY=yolo`	`data.preferences.conflictStrategy`	ConflictStrategy
`OAC_PRIVATE_TOKEN=...`	Used by registry providers that opt in	string
`OAC_VERBOSE=true`	CLI verbosity	boolean
`OAC_QUIET=true`	CLI quiet mode	boolean

Environment variables override JSON config but cannot wire providers (use oac.config.ts for that).

4.4 `defineConfig()` Signature (Final)

// packages/core/src/define-config.ts

/**
 * @param plugin - Your OAC provider configuration
 * @returns The same object, typed as OACPlugin
 *
 * @example Minimal — override context only
 * ```ts
 * export default defineConfig({
 *   context: new NotionContextProvider({ token: process.env.NOTION_TOKEN! }),
 * });
 * ```
 *
 * @example Enterprise — full stack replacement
 * ```ts
 * export default defineConfig({
 *   context: new ConfluenceContextProvider({ baseUrl: '...', token: '...' }),
 *   taskManagement: new JiraTaskProvider({ projectKey: 'ENG', token: '...' }),
 *   registries: [new PrivateRegistryProvider({ url: '...', token: '...' })],
 *   ideAdapters: [new JetBrainsAdapter()],
 * });
 * ```
 *
 * @example Conditional — CI-only adapter
 * ```ts
 * export default defineConfig({
 *   ideAdapters: [
 *     process.env.CI && new CIMetricsAdapter(),
 *   ],
 * });
 * ```
 */
export function defineConfig(plugin: OACPlugin): OACPlugin {
  return plugin;
}

4.5 OACConfig Schema (Data Shape)

// packages/core/src/schemas/config.ts

export const OACConfigSchema = z.object({
  version: z.string().default('1.0.0'),
  preferences: z.object({
    defaultIDE: z.string().default('opencode'),
    installLocation: z.enum(['local', 'global']).default('local'),
    yoloMode: z.boolean().default(false),
    conflictStrategy: z.enum(['ask', 'skip', 'overwrite', 'backup', 'yolo']).default('ask'),
    autoBackup: z.boolean().default(true),
    updateMode: z.enum(['manual', 'auto-safe', 'auto-all', 'locked']).default('manual'),
    branch: z.string().default('main'),
  }).default({}),
  registries: z.array(z.object({
    name: z.string(),
    url: z.string().url(),
    priority: z.number().int().min(0).default(1),
    authTokenEnvVar: z.string().optional(), // e.g. "OAC_PRIVATE_TOKEN"
  })).default([{ name: 'official', url: 'https://registry.nextsystems.dev/oac', priority: 1 }]),
  ides: z.record(z.string(), z.object({
    enabled: z.boolean().default(false),
    path: z.string().optional(),
    profile: z.string().default('developer'),
  })).default({
    opencode: { enabled: true, path: '.opencode', profile: 'developer' },
  }),
});

export type OACConfig = z.infer<typeof OACConfigSchema>;

5. `packages/core` Final Structure

packages/core/
├── src/
│   ├── providers/
│   │   ├── context.ts             # IContextProvider interface
│   │   ├── task-management.ts     # ITaskManagementProvider interface
│   │   ├── registry.ts            # IRegistryProvider interface
│   │   ├── ide-adapter.ts         # IIDEAdapter interface
│   │   └── agent-profile.ts       # IAgentProfileProvider interface
│   ├── schemas/
│   │   ├── agent.ts               # AgentConfigSchema + AgentFrontmatterSchema (canonical)
│   │   ├── config.ts              # OACConfigSchema
│   │   ├── lockfile.ts            # OACLockSchema + InstalledComponentSchema
│   │   ├── registry.ts            # RegistryItemSchema + RegistrySchema
│   │   ├── skill.ts               # SkillFrontmatterSchema
│   │   ├── context.ts             # ContextFrontmatterSchema + ContextFileSchema
│   │   └── manifest.ts            # BundledManifestSchema + InstalledManifestSchema
│   ├── types/
│   │   └── index.ts               # All shared TypeScript types (§2.1 above)
│   ├── plugin.ts                  # OACPlugin interface
│   ├── define-config.ts           # defineConfig() helper
│   ├── provider-registry.ts       # ProviderRegistry class + createProviderRegistry()
│   └── index.ts                   # Re-exports everything (single import surface)
├── package.json
└── tsconfig.json

src/index.ts (complete barrel — everything available from '@nextsystems/oac-core'):

// Providers
export type { IContextProvider } from './providers/context.js';
export type { ITaskManagementProvider } from './providers/task-management.js';
export type { IRegistryProvider } from './providers/registry.js';
export type { IIDEAdapter } from './providers/ide-adapter.js';
export type { IAgentProfileProvider } from './providers/agent-profile.js';

// Schemas (Zod objects, for runtime validation)
export { AgentFrontmatterSchema, AgentConfigSchema } from './schemas/agent.js';
export { OACConfigSchema } from './schemas/config.js';
export { OACLockSchema } from './schemas/lockfile.js';
export { RegistryItemSchema, RegistrySchema } from './schemas/registry.js';
export { SkillFrontmatterSchema } from './schemas/skill.js';
export { ContextFrontmatterSchema } from './schemas/context.js';
export { BundledManifestSchema, InstalledManifestSchema } from './schemas/manifest.js';

// Types (TypeScript-only)
export type {
  ComponentType, UpdateMode, ConflictStrategy, InstallLocation,
  ContextLayerName, ContextFile, ContextQuery,
  Task, TaskStatus, TaskPriority, TaskSession,
  RegistryFile, RegistryItem, RegistrySearchOptions,
  IDECapabilities, IDEOutputFile, IDEAdapterResult,
  AgentProfile, OACAgent, OACContext,
  ValidationResult, OACOperationResult,
  // Inferred from schemas
  AgentFrontmatter, AgentConfig, OACConfig, OACLock,
} from './types/index.js';

// Plugin system
export type { OACPlugin } from './plugin.js';
export { defineConfig } from './define-config.js';

// Provider registry (internal wiring — CLI uses this, not plugin authors)
export { ProviderRegistry, createProviderRegistry, ProviderRegistryError } from './provider-registry.js';

package.json:

{
  "name": "@nextsystems/oac-core",
  "version": "1.0.0",
  "description": "Shared interfaces, schemas, and provider contracts for OAC",
  "type": "module",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  },
  "files": ["dist"],
  "scripts": {
    "build": "tsc --project tsconfig.json",
    "typecheck": "tsc --noEmit",
    "test": "vitest run"
  },
  "peerDependencies": {
    "zod": "^3.22.0"
  },
  "devDependencies": {
    "typescript": "^5.4.0",
    "vitest": "^1.5.0",
    "zod": "^3.22.0"
  }
}

Zero runtime dependencies. zod is a peer dependency — the CLI and plugin authors both have it. This means @nextsystems/oac-core ships ~0 bytes of dependencies.

6. Migration Path (No Breaking Changes to 236 Tests)

The migration is designed so that every step leaves the test suite green. Each step is a separate PR.

Step 1: Fix Module-Level Bugs (No New Code)

PR: "fix: eliminate module-level singletons that break test isolation"

In AdapterRegistry.ts:358: Remove export const registry = new AdapterRegistry(). Add export function createAdapterRegistry(): AdapterRegistry { return new AdapterRegistry(); }.
In test files that import registry: Add beforeEach(() => registry.clear()) as a bridge (or switch to createAdapterRegistry()).
In AgentLoader.ts:169: Move cachedMetadata and metadataLoaded to instance fields.
In plugin.ts: Remove const pluginInstance = new AbilitiesPlugin(). Make AbilitiesPlugin instantiated in the consumer.

Test impact: Tests that relied on shared singleton state may need beforeEach(() => registry.clear()). All 236 tests must pass after this step.

Step 2: Fix Schema Bugs

PR: "fix: correct schema bugs in types.ts"

Fix ModelIdentifierSchema: z.union([z.string(), z.string()]) → z.string()
Fix TemperatureSchema: add .min(0).max(2)
Fix AgentMetadataSchema vs OpenAgentSchema.metadata inconsistency: use AgentMetadataSchema inside OpenAgentSchema

Test impact: Tests that previously passed invalid temperature/model values will now fail Zod validation — fix the test data, not the schema.

Step 3: Create `packages/core` Package

PR: "feat(core): create @nextsystems/oac-core with provider interfaces"

Create packages/core/ with the directory structure from §5
Copy types from compatibility-layer/src/types.ts into core/src/schemas/ (with schema fixes applied)
Write the 5 provider interfaces, OACPlugin, defineConfig(), ProviderRegistry
Add "@nextsystems/oac-core": "workspace:*" to root package.json
Fix root package.json workspaces: ["packages/*", "evals/framework"]

Test impact: Zero — no existing code changed, only new files added.

Step 4: Wire Compatibility-Layer to Core Types

PR: "refactor(compat): import shared types from @nextsystems/oac-core"

In compatibility-layer/src/types.ts: Change schema definitions to re-export from @nextsystems/oac-core (keep backward-compatible exports)
In compatibility-layer/src/adapters/BaseAdapter.ts: Import OACAgent, IDEAdapterResult from @nextsystems/oac-core

Test impact: Zero if re-exports are clean. Run tsc --noEmit to confirm.

Step 5: Migrate Adapters to IIDEAdapter

PR: "refactor(compat): ClaudeAdapter, CursorAdapter, WindsurfAdapter implement IIDEAdapter"

Add implements IIDEAdapter to each adapter class
Rename name → id on each adapter
Update fromOAC signature to accept agents[] + context[]
Add validate() method to each adapter

Test impact: Adapter tests that call adapter.name need updating to adapter.id. This is the one place where test changes are expected — they are mechanical renames.

Step 6: CLI Wiring

PR: "feat(cli): wire ProviderRegistry into CLI commands"

Create packages/cli/ with createProviderRegistry() call in CLI entry point
Load oac.config.ts via jiti if present
Pass ProviderRegistry into command handlers

Test impact: CLI tests get fresh registry per test via createProviderRegistry() with mock providers.

7. Impact on Each of the 6 Projects

P1: `@nextsystems/oac-core`

This document is the specification for P1. The team builds exactly the interfaces, types, schemas, OACPlugin, defineConfig(), and ProviderRegistry defined in §2. The package has zero runtime dependencies (zod is peer). The 5 provider interfaces are the extensibility contract that must remain stable — no breaking changes without a major version bump. Primary deliverable: a clean index.ts barrel from which every other package imports. Time estimate: 1–2 weeks. The schema fixes in §3.5 are part of P1, not P4.

P2: `@nextsystems/oac-cli`

P2 depends on P1 and builds around createProviderRegistry(). Every CLI command receives a ProviderRegistry instance, never a singleton. The ConfigManager loads .oac/config.json (data) and oac.config.ts (plugin wiring) separately via the pipeline in §4.2. The jiti dependency handles TypeScript config execution without requiring ts-node. CLI commands must never import providers directly — they receive them through the registry. The YOLO flag maps to OACConfig.preferences.conflictStrategy = 'yolo', not a separate code path.

P3: Context System

P3 implements IContextProvider twice: DefaultContextProvider (6-layer filesystem resolver) and tests can mock it. The DefaultContextProvider is the only built-in implementation; it is passed as defaults.context to createProviderRegistry(). The 6-layer resolution logic lives entirely inside this class — nothing else in the codebase does path resolution. oac context install calls provider.install(), oac context update calls provider.update(). The dispatch semantics (callFirst) mean that if an enterprise user provides a NotionContextProvider, the 6-layer resolver is completely bypassed — no partial execution, no fallthrough.

P4: Agent & Skill Management

P4 introduces the agent.json + prompt.md split. The OACAgent type defined in §2.1 is exactly what flows between P4's loader and the IDE adapters. P4 implements IAgentProfileProvider (built-in, reading from manifest.json profiles). The AgentLoader refactor (instance-scoped cache, §3.4) is a P4 prerequisite and should be done in P1's bug-fix step. The task-cli.ts → task-cli.js compilation happens in P4's build pipeline; the resulting .js file implements the default ITaskManagementProvider behavior for local JSON sessions.

P5: Plugin System

P5 implements the IDE adapters as IIDEAdapter (not extending BaseAdapter). The OpenCode TS plugin is an OpenCode plugin (a different abstraction — Plugin from @opencode-ai/plugin) that internally calls createProviderRegistry() to get the configured context and task providers. The Claude Code adapter implements IIDEAdapter.fromOAC() to generate session-start.js. Cursor and Windsurf adapters are straightforward IIDEAdapter implementations. The callAll() dispatch in ProviderRegistry.runAllAdapters() is what P5 calls when oac install --all runs — all IDE adapters execute in parallel.

P6: Registry & Community

P6 implements IRegistryProvider as OfficialRegistryProvider (nextsystems.dev) and provides the wiring for user-configured private registries. The RegistryClient in §P6 of the breakdown maps to ProviderRegistry.resolveFromRegistry() — the priority-ordered callFirst dispatch. Multi-registry search is implemented by calling search() on all registries, deduplicating by name+type, and returning sorted results. Auth tokens for private registries are read from config.registries[n].authTokenEnvVar — the env var name is stored in config, the value is never stored.

8. Red Lines

The following are explicitly forbidden. Each has a one-line rationale.

Do Not	Why
Export a module-level singleton (`export const registry = new X()`)	Singletons bleed state between tests and make isolation impossible
Add runtime dependencies to `packages/core`	Zero-dep is a load-time guarantee; adding deps violates the contract with plugin authors
Use `ts-node` at runtime	Eliminates a fragile dev dependency from production paths; use jiti or pre-compile
Merge `IContextProvider` and `ITaskManagementProvider` into one interface	Different dispatch semantics (callFirst vs single) cannot be unified without obscuring behavior
Make `OACPlugin` fields required	Plugin authors implement one subsystem; required fields force them to stub everything else
Use TSyringe, Inversify, or any DI container	Decorator-based DI requires `emitDecoratorMetadata`, is incompatible with ESM tree-shaking, and creates plugin author friction
Use Effect-TS	Its error model and type complexity is appropriate for library authors, not community plugin authors writing `implements IContextProvider`
Store auth tokens in `.oac/config.json`	Secrets in config files get committed to git; use env vars and store only the env var name
Implement `callAll()` dispatch outside `ProviderRegistry`	Dispatch semantics must be centralized; scattered fan-out logic produces inconsistent error handling
Give IDE adapters filesystem write access directly	Adapters return file content; the CLI writes files; this enables dry-run support and prevents adapters from bypassing conflict resolution
Use `z.union([z.string(), z.string()])` anywhere	Duplicate union members collapse to the first — this is always a bug
Share `AgentLoader` instance between parallel requests	`AgentLoader` has instance-scoped cache; a shared instance across concurrent loads will return stale data
Make `BaseAdapter` implement `IIDEAdapter` via inheritance	Inheritance creates a coupling between the compatibility-layer and core; the adapters in P5 implement `IIDEAdapter` directly
Hand-maintain SHA256 hashes in manifest.json	Manual SHA256s drift; `scripts/generate-manifest.ts` must be the only source
Put business logic in `defineConfig()`	It is an identity function for type safety; logic in it is invisible to callers
Make `ProviderRegistry` accept partial providers without defaults	A registry with no context provider crashes at runtime; defaults must be passed to `createProviderRegistry()`

This document supersedes all prior provider/adapter discussions. Implementation of P1 begins with the interfaces in §2 locked.

14-PROVIDER-PATTERN-FINAL.md 52 KB History Raw