Multi-Runtime Adapter Pattern in I-Have-ADHD: Cross-Platform AI Architecture

The multi-runtime adapter pattern in I-Have-ADHD decouples core conversational logic from platform-specific implementations, enabling consistent ADHD-friendly behavior across Claude, Codex, OpenCode, and other AI runtimes through lightweight translation layers.

The I-Have-ADHD project implements a sophisticated multi-runtime adapter pattern to ensure identical behavior across diverse AI platforms. This architecture centralizes the ten ADHD-friendly response rules in a single canonical file while delegating platform integration to thin, runtime-specific adapters. By separating what the assistant says from how each platform delivers it, the repository maintains consistency without code duplication.

Core Architecture of the Multi-Runtime Adapter Pattern

Canonical Skill as the Single Source of Truth

At the heart of the pattern lies one canonical markdown file that serves as the single source of truth. Located at skills/i-have-adhd/SKILL.md, this file defines the ten ADHD-friendly response rules that every runtime must obey.

A mirror copy exists at .cursor/skills/i-have-adhd/SKILL.md to maintain compatibility with Cursor's specific skill-loading mechanism. When the canonical skill updates, this mirror receives a simple copy-over synchronization, ensuring all runtimes access identical behavior definitions without configuration drift.

Runtime-Specific Adapter Layers

Each supported AI platform receives its own lightweight adapter that translates the runtime’s hook, plugin, or extension API into calls that execute the canonical skill. According to the repository’s AGENTS.md, these adapters include:

• Claude Code: Uses hooks/hooks.json and hooks/always-on.mjs as entry points
• Codex: Reads \.codex-plugin/plugin.json and the marketplace manifest in .agents/plugins/marketplace.json
• Pi / OMP: Expose a Node package (package.json with pi or omp scripts) and TypeScript extensions in extensions/i-have-adhd.ts
• OpenCode: Relies on opencode.json, the plugin file .opencode/plugins/i-have-adhd.mjs, and the command markdown .opencode/command/i-have-adhd.md
• Qwen / Kimi / Gemini: Each maintains its own manifest (e.g., qwen-extension.json, kimi.plugin.json, GEMINI.md) plus shared runtime contracts

These adapters function as thin shims: they import the skill, format request/response objects according to the runtime’s expectations, and forward results back to the model.

How the Adapters Work

Every adapter follows a consistent four-step execution pattern defined in the hook contracts. The adapters load the skill, convert incoming requests to the skill’s input shape, execute the logic, and return formatted results.

Generic Adapter Structure

The following pseudo-code illustrates the universal adapter pattern implemented across all runtimes:

// Load the skill (Markdown file)
import { loadSkill } from "./skillLoader.js";
const skill = loadSkill("./skills/i-have-adhd/SKILL.md");

// Runtime-specific entry point
export async function handleMessage(request) {
  // Transform model-specific request into the skill's format
  const input = {
    userMessage: request.content,
    context: request.context,
  };

  // Execute the skill logic (e.g., match a rule)
  const response = await skill.run(input);

  // Convert the skill's response back to the runtime's reply shape
  return {
    answer: response.text,
    metadata: response.meta,
  };
}

OpenCode Adapter Implementation

The concrete implementation for OpenCode at .opencode/plugins/i-have-adhd.mjs demonstrates runtime-specific request transformation:

import { loadSkill } from "../../skillLoader.js";
const skill = loadSkill("../skills/i-have-adhd/SKILL.md");

export async function invoke({ messages, user }) {
  const result = await skill.run({ userMessage: messages.at(-1).content });
  return { content: result.text };
}

Pi Runtime Adapter

The Pi platform adapter in extensions/i-have-adhd.ts uses TypeScript to handle the specific event structure:

import { loadSkill } from "./skillLoader";
const skill = loadSkill("../skills/i-have-adhd/SKILL.md");

export async function piHandler(event: PiEvent) {
  const answer = await skill.run({ userMessage: event.input });
  return { reply: answer.text };
}

In each implementation, the adapter never duplicates business logic. It only handles translation between the runtime’s native format and the skill’s expected interface.

Synchronization and Maintenance Workflow

The multi-runtime adapter pattern enables zero-downtime updates through a disciplined synchronization workflow:

1. Update the canonical skill at skills/i-have-adhd/SKILL.md
2. Synchronize the mirror copy in .cursor/skills/i-have-adhd/SKILL.md
3. Automatic propagation: Because adapters only call into the skill, no further code changes are required; runtimes automatically pick up updated behavior

This workflow relies on shared contracts defined in hooks/hooks.json and various *.json manifest files. These contracts guarantee that every runtime follows the same interface expectations—including input shape, output format, and error handling—while allowing each platform to implement its peculiar bootstrap logic.

Summary

The multi-runtime adapter pattern in I-Have-ADHD delivers three key architectural benefits:

• Consistency: All runtimes obey the same ADHD-friendly rules defined in the canonical skill file
• Extensibility: Adding a new runtime requires only a tiny adapter that forwards to the existing skill
• Maintainability: Core logic lives in one place, reducing duplication and eliminating version drift across platforms

Frequently Asked Questions

What is the multi-runtime adapter pattern in I-Have-ADHD?

The multi-runtime adapter pattern is an architectural design that separates the core conversational skill (what the assistant should say) from platform-specific delivery mechanisms (how each AI runtime executes that behavior). It consists of a single canonical skill file at skills/i-have-adhd/SKILL.md and lightweight runtime adapters that translate platform-specific APIs into calls to that skill.

Where is the canonical skill file located in the repository?

The canonical skill file is located at skills/i-have-adhd/SKILL.md. This file serves as the single source of truth for all ADHD-friendly response rules. A synchronized mirror copy exists at .cursor/skills/i-have-adhd/SKILL.md to support Cursor's specific loading mechanism.

How do I add support for a new AI runtime to the I-Have-ADHD project?

To add a new runtime, create a lightweight adapter that imports the skill using loadSkill("./skills/i-have-adhd/SKILL.md"), transforms the runtime's native request format into the skill's expected input shape, executes skill.run(), and returns the result in the runtime's required format. Document the new adapter in AGENTS.md and include any necessary manifest files (e.g., new-runtime.json).

Why does the project maintain a mirror copy of the skill in the .cursor directory?

The mirror copy at .cursor/skills/i-have-adhd/SKILL.md provides compatibility with Cursor's specific skill-loading mechanism while maintaining the single source of truth pattern. When the canonical skill updates, this file receives a simple copy-over synchronization, ensuring Cursor users access identical behavior without requiring Cursor-specific adapters to reference files outside their expected directory structure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}