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

> Explore the multi-runtime adapter pattern in I-Have-ADHD. This AI architecture ensures consistent ADHD-friendly interactions across diverse platforms like Claude and Codex via lightweight translation layers.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: architecture
- Published: 2026-09-09

---

**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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/.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`](https://github.com/ayghri/i-have-adhd/blob/main/AGENTS.md), these adapters include:

- **Claude Code**: Uses [`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/.agents/plugins/marketplace.json)
- **Pi / OMP**: Expose a Node package ([`package.json`](https://github.com/ayghri/i-have-adhd/blob/main/package.json) with `pi` or `omp` scripts) and TypeScript extensions in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts)
- **OpenCode**: Relies on [`opencode.json`](https://github.com/ayghri/i-have-adhd/blob/main/opencode.json), the plugin file `.opencode/plugins/i-have-adhd.mjs`, and the command markdown [`.opencode/command/i-have-adhd.md`](https://github.com/ayghri/i-have-adhd/blob/main/.opencode/command/i-have-adhd.md)
- **Qwen / Kimi / Gemini**: Each maintains its own manifest (e.g., [`qwen-extension.json`](https://github.com/ayghri/i-have-adhd/blob/main/qwen-extension.json), [`kimi.plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/kimi.plugin.json), [`GEMINI.md`](https://github.com/ayghri/i-have-adhd/blob/main/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:

```javascript
// 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:

```javascript
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`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) uses TypeScript to handle the specific event structure:

```typescript
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`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)
2. **Synchronize the mirror copy** in [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/.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`](https://github.com/ayghri/i-have-adhd/blob/main/AGENTS.md) and include any necessary manifest files (e.g., [`new-runtime.json`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/.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.