# Architecture of the i-have-adhd Application: A Modular AI Skill Framework

> Explore the modular AI skill framework of the i-have-adhd application. Discover its platform-agnostic architecture enforcing action-first rules with markdown contracts. Learn more now.

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

---

**The i-have-adhd repository implements a declarative, platform-agnostic AI skill that enforces action-first response rules through a central markdown contract and minimal YAML/TOML adapters for Claude, Codex, and Gemini.**

The `ayghri/i-have-adhd` repository provides an open-source AI assistant skill designed to reshape LLM outputs for ADHD accessibility. Unlike monolithic applications, this project adopts a modular architecture that decouples behavioral rules from platform-specific implementations, allowing the same core logic to run across multiple code-assistant platforms.

## Core Architectural Components

The architecture of the i-have-adhd application consists of five tightly-coupled yet distinct layers:

### Skill Definition (SKILL.md)

At the heart of the system lies [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md), a declarative markdown file containing the behavioral contract that all agents must enforce. This file defines the strict "action-first" rules—including numbered steps, no tangents, and immediate executable guidance—that shape every LLM response. By centralizing logic in a single version-controlled document, the architecture eliminates code duplication across platforms.

### Plugin Manifest (plugin.json)

The [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) file at the repository root serves as the registration entry point. When users install the skill via commands like `claude plugin install`, the host platform reads this minimal JSON to discover the skill name, description, and entry points required for initialization.

### Agent Adapters (openai.yaml and gemini.toml)

Platform abstraction is handled through lightweight configuration files in `skills/i-have-adhd/agents/`. The [`openai.yaml`](https://github.com/ayghri/i-have-adhd/blob/main/openai.yaml) adapter maps the skill to Claude and Codex invocation syntax (`/i-have-adhd` and `$i-have-adhd` respectively), while [`gemini.toml`](https://github.com/ayghri/i-have-adhd/blob/main/gemini.toml) provides the equivalent mapping for Gemini CLI. These adapters contain no business logic—only interface definitions—ensuring the core skill remains independent of any particular LLM vendor.

## Runtime Execution Flow

Understanding how the components interact clarifies the application's plug-in architecture:

1. **Registration Phase**: The host platform ingests [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) to index the skill metadata and locate the appropriate adapter.
2. **Adapter Binding**: Based on the detected platform, the system loads either [`openai.yaml`](https://github.com/ayghri/i-have-adhd/blob/main/openai.yaml) or [`gemini.toml`](https://github.com/ayghri/i-have-adhd/blob/main/gemini.toml), which define the slash-command or prefix syntax users type to activate the skill.
3. **Prompt Injection**: Upon invocation, the host injects the entire contents of [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) into the LLM's system prompt context. This injection forces the model to adopt the ADHD-friendly formatting constraints for the duration of the session, persisting until the user explicitly terminates with "stop adhd mode".

## Evaluation and Testing Framework

The repository includes a self-contained validation system to ensure output consistency across model updates.

### Evaluation CLI (scripts/run_evals.py)

The [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py) module provides a Python CLI that orchestrates automated regression testing. It loads evaluation cases, executes them against configured LLM runners (Claude, Codex, or Gemini), validates outputs against predefined criteria, and aggregates weighted scores stored in the `WEIGHTS` configuration. The script reports a final `release_gate` status indicating whether the skill meets quality thresholds.

### Test Data and Scoring (cases.jsonl and rubric.md)

Concrete test scenarios reside in `evals/cases.jsonl`, a JSONL catalog containing prompts, risk levels, and expected response characteristics. The [`evals/rubric.md`](https://github.com/ayghri/i-have-adhd/blob/main/evals/rubric.md) file defines the scoring criteria and weighting scheme used by the evaluation CLI to grade each response, ensuring that "action-first" formatting remains consistent across different temperature settings and model versions.

## Platform Integration Examples

The following configurations demonstrate how the architecture maps abstract skill rules to concrete platform implementations.

**Claude/Codex Adapter Configuration:**

```yaml

# skills/i-have-adhd/agents/openai.yaml

interface:
  display_name: "I Have ADHD"
  short_description: "Action-first output for ADHD readers"
  default_prompt: "Use $i-have-adhd to make this response action-first and easy to execute."

```

**Installing and Invoking via Codex CLI:**

```bash

# Register the plugin

codex plugin marketplace add ayghri/i-have-adhd --ref main
codex plugin add i-have-adhd@i-have-adhd

# Activate the skill during a session

$i-have-adhd

```

**Running Automated Evaluations:**

```bash
python -m scripts.run_evals.py run \
  --runner-config evals/runners.example.json \
  --runner codex \
  --condition baseline \
  --condition-skill skills/i-have-adhd/SKILL.md \
  --output evals/results.jsonl

```

This command loads the skill definition from [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) and evaluates it against the baseline runner, producing a JSONL file containing scored validation results.

## Summary

- The architecture of the i-have-adhd application centers on a **declarative rule set** ([`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md)) that decouples behavioral logic from platform implementation.
- **Minimal adapter files** ([`openai.yaml`](https://github.com/ayghri/i-have-adhd/blob/main/openai.yaml), [`gemini.toml`](https://github.com/ayghri/i-have-adhd/blob/main/gemini.toml)) enable deployment across Claude, Codex, and Gemini without modifying core skill logic.
- Runtime execution relies on **system prompt injection**, persisting ADHD-friendly formatting constraints for the entire user session.
- The **evaluation framework** ([`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py)) provides automated regression testing via weighted scoring against curated prompt catalogs.
- All components reside in a **modular repository structure** that supports version control and CI/CD integration for skill updates.

## Frequently Asked Questions

### How does the i-have-adhd skill enforce its formatting rules across different LLM platforms?

The skill injects the complete contents of [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) into the LLM's system prompt at invocation time. This prompt engineering technique forces the model to adopt the action-first, numbered-step format regardless of the underlying platform, whether Claude, Codex, or Gemini.

### What is the purpose of the agent adapter files in the i-have-adhd architecture?

Agent adapters like [`openai.yaml`](https://github.com/ayghri/i-have-adhd/blob/main/openai.yaml) and [`gemini.toml`](https://github.com/ayghri/i-have-adhd/blob/main/gemini.toml) serve as platform-specific interface mappings. They declare the invocation syntax (such as `/i-have-adhd` or `$i-have-adhd`) and metadata required by each host platform, allowing the same [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) rules to execute across different LLM ecosystems without code changes.

### How is the i-have-adhd skill evaluated for consistency?

The [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py) CLI runs automated evaluations against `evals/cases.jsonl`, validating each output against criteria defined in [`evals/rubric.md`](https://github.com/ayghri/i-have-adhd/blob/main/evals/rubric.md). The framework applies weighted scoring logic and reports a `release_gate` status, ensuring that model upgrades or prompt modifications do not regress the skill's formatting guarantees.

### Can the i-have-adhd skill be extended to support additional LLM platforms?

Yes. The architecture requires only a new adapter file (YAML or TOML depending on the platform's configuration format) in `skills/i-have-adhd/agents/` and an entry in [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json). Because the core logic remains in [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md), supporting new platforms involves declaring interface metadata rather than rewriting behavioral code.