# i-have-adhd Project Structure: Modular Architecture for Cross-Platform AI Skills

> Explore the i-have-adhd project structure. Discover its modular architecture for cross-platform AI skills, featuring skill definitions, runtime adapters, and evaluation suites.

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

---

**The i-have-adhd repository organizes code into isolated skill definitions, runtime adapters, execution hooks, and evaluation suites to deliver consistent ADHD-friendly response rules across Claude, Gemini, OpenAI, and other AI platforms.**

The i-have-adhd project structure follows a strict separation of concerns that decouples canonical behavior definitions from platform-specific implementations. This architecture enables developers to maintain a single source of truth for ADHD-friendly interaction patterns while deploying to diverse AI runtimes including OpenCode, Pi, OMP, and Gemini. Each directory serves a distinct purpose in the lifecycle of the skill, from definition and adaptation to execution and validation.

## Skill Definition Layer

The core behavioral rules live in the `skills/` directory, isolated from any specific runtime implementation.

### Canonical Skill Manifest

The authoritative definition of the 10 ADHD-friendly response rules resides in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md). This file acts as the single source of truth that all runtime adapters consume. According to the ayghri/i-have-adhd source code, the skill definition includes structured guidelines for breaking down complex instructions, using clear headers, and maintaining focus-friendly formatting.

### Runtime-Specific Agents

Platform-specific prompt variations are stored in `skills/i-have-adhd/agents/`. These directories contain specialized configurations for OpenAI, Gemini, and other models that may require adjusted prompting strategies while adhering to the canonical rules in [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md).

## Runtime Adapters

The `extensions/` directory houses TypeScript adapters that translate the skill definition into platform-native implementations.

### TypeScript Adapters

- [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts): The primary adapter for Pi and OMP runtimes, exporting the skill logic as a reusable module.
- [`extensions/context-compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/context-compat.ts): Compatibility layer ensuring consistent context handling across different JavaScript environments.

### Manifest Files

Each supported runtime requires a manifest declaring entry points and metadata:

- [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json): Configuration for Pi/OMP plugin loaders
- [`opencode.json`](https://github.com/ayghri/i-have-adhd/blob/main/opencode.json): OpenCode-specific manifest
- [`qwen-extension.json`](https://github.com/ayghri/i-have-adhd/blob/main/qwen-extension.json): Qwen runtime configuration
- [`kimi.plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/kimi.plugin.json): Kimi plugin metadata
- [`gemini-extension.json`](https://github.com/ayghri/i-have-adhd/blob/main/gemini-extension.json): Google Gemini integration settings

## Execution Hooks

The `hooks/` directory enables always-on functionality, ensuring the skill activates automatically in supported environments.

### Hook Declarations

The [`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json) file declares entry points for automatic skill activation. This JSON configuration maps trigger events to specific hook implementations.

### Platform-Specific Scripts

Execution scripts support multiple operating systems and shells:

```bash

# hooks/always-on.sh

#!/usr/bin/env bash

# Activate the i-have-adhd skill on every new session

opencode run i-have-adhd "$@"

```

PowerShell and Node.js variants (`hooks/always-on.ps1`, `hooks/always-on.mjs`) provide equivalent functionality for Windows and cross-platform JavaScript environments.

## OpenCode Integration

The `.opencode/` directory contains the primary entry point for the OpenCode runtime, which serves as the main deployment target for this skill.

### Plugin Implementation

The file `.opencode/plugins/i-have-adhd.mjs` implements the OpenCode plugin interface:

```javascript
// .opencode/plugins/i-have-adhd.mjs
import { definePlugin } from '@opencode/core';
import skill from '../skills/i-have-adhd/SKILL.md';

export default definePlugin({
  name: 'i-have-adhd',
  description: 'ADHD-friendly response rules',
  execute: async (input) => {
    // The plugin returns the skill text for embedding into prompts
    return skill;
  },
});

```

### Command Documentation

User-facing documentation for the OpenCode CLI appears in [`.opencode/command/i-have-adhd.md`](https://github.com/ayghri/i-have-adhd/blob/main/.opencode/command/i-have-adhd.md), providing usage examples and parameter descriptions.

### Package Configuration

Node.js metadata files ([`.opencode/package.json`](https://github.com/ayghri/i-have-adhd/blob/main/.opencode/package.json), `.opencode/bun.lock`) manage dependencies specific to the OpenCode runtime environment.

## Testing and Evaluation Framework

Quality assurance is organized into unit tests and behavioral evaluations.

### Unit Tests

The `tests/` directory contains platform-specific validation suites:

- [`tests/test_opencode_plugin.py`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_opencode_plugin.py): Validates the OpenCode plugin's initialization and execution behavior
- [`tests/test_run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_run_evals.py): Integration tests for the evaluation runner

### Behavioral Evaluations

The `evals/` directory defines comprehensive test cases:

- `evals/cases.jsonl`: Line-delimited JSON containing input/output test pairs
- [`evals/rubric.md`](https://github.com/ayghri/i-have-adhd/blob/main/evals/rubric.md): Scoring criteria for evaluating ADHD-friendly formatting
- [`evals/README.md`](https://github.com/ayghri/i-have-adhd/blob/main/evals/README.md): Methodology documentation for the evaluation framework

### Evaluation Runner

The [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py) utility executes the full evaluation suite:

```python

# scripts/run_evals.py

import json
import subprocess
import pathlib

def run_case(case_path):
    case = json.loads(pathlib.Path(case_path).read_text())
    result = subprocess.check_output([
        'opencode', 'run', 'i-have-adhd', 
        '--input', case['input']
    ])
    return result.decode('utf-8')

```

## Automation and Workflows

The `.github/workflows/` directory automates validation across all supported runtimes.

### Continuous Integration

- [`.github/workflows/plugin-load-check.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/plugin-load-check.yml): Validates that the plugin loads correctly across Pi, OMP, and OpenCode environments
- [`.github/workflows/pi-load-check.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/pi-load-check.yml): Specific validation for the Pi runtime adapter

### Development Utilities

Helper scripts in `scripts/` facilitate local development and CI tasks:

- [`scripts/check_pi_extension.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/check_pi_extension.py): Validates TypeScript compilation for Pi adapters
- [`scripts/check_context_compat.ts`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/check_context_compat.ts): Type-checks the context compatibility layer

## Documentation and Localization

High-level project documentation resides in the repository root, with localized variants in `.github/readme/`.

- [`README.md`](https://github.com/ayghri/i-have-adhd/blob/main/README.md): Primary project overview and installation instructions
- [`INSTALL.md`](https://github.com/ayghri/i-have-adhd/blob/main/INSTALL.md): Step-by-step setup guide for developers
- [`GEMINI.md`](https://github.com/ayghri/i-have-adhd/blob/main/GEMINI.md): Google Gemini-specific integration instructions
- `.github/readme/`: Translated README files for international contributors

## Summary

The i-have-adhd project structure enforces a clean separation between behavior definition and runtime implementation:

- **Skill definitions** in `skills/i-have-adhd/` provide the canonical source of truth for ADHD-friendly rules
- **Runtime adapters** in `extensions/` and manifest files enable deployment across Claude, Gemini, OpenAI, and other platforms
- **Execution hooks** in `hooks/` support always-on activation in compatible environments
- **OpenCode integration** in `.opencode/` serves as the primary entry point and reference implementation
- **Testing frameworks** in `tests/` and `evals/` ensure behavioral consistency across all adapters
- **CI workflows** in `.github/workflows/` automate validation across the full matrix of supported runtimes

## Frequently Asked Questions

### What is the main entry point for the i-have-adhd skill?

The primary entry point is `.opencode/plugins/i-have-adhd.mjs`, which implements the OpenCode plugin interface. This module imports the canonical skill definition from [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) and exposes it through the `execute` function, making it available to the OpenCode runtime and serving as the reference implementation for other adapters.

### How does the project support multiple AI runtimes simultaneously?

The repository uses adapter pattern architecture where platform-specific code in `extensions/` and manifest files (such as [`gemini-extension.json`](https://github.com/ayghri/i-have-adhd/blob/main/gemini-extension.json) and [`kimi.plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/kimi.plugin.json)) consume the platform-agnostic skill definition in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md). Each adapter translates the canonical rules into runtime-specific implementations while maintaining consistent behavioral semantics across Claude, Pi, OMP, Gemini, and Qwen environments.

### Where are the behavioral rules for ADHD-friendly responses defined?

The authoritative behavioral rules reside in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md). This file contains the structured guidelines that all runtime adapters must follow, including rules for breaking complex instructions into steps, using clear visual headers, and maintaining concise paragraph lengths. Runtime-specific variations in `skills/i-have-adhd/agents/` adapt these rules for particular model capabilities without altering the core semantics.

### How is the skill tested across different platforms?

The project employs a two-tier testing strategy: unit tests in `tests/` validate adapter functionality using frameworks like [`test_opencode_plugin.py`](https://github.com/ayghri/i-have-adhd/blob/main/test_opencode_plugin.py), while behavioral evaluations in `evals/` assess adherence to ADHD-friendly formatting rules using `cases.jsonl` and [`rubric.md`](https://github.com/ayghri/i-have-adhd/blob/main/rubric.md). The [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py) orchestrates these tests, and [`.github/workflows/plugin-load-check.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/plugin-load-check.yml) ensures continuous validation across all supported runtimes during CI/CD pipelines.