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

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. 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.

Runtime Adapters

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

TypeScript Adapters

• 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: 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: Configuration for Pi/OMP plugin loaders
• opencode.json: OpenCode-specific manifest
• qwen-extension.json: Qwen runtime configuration
• kimi.plugin.json: Kimi plugin metadata
• 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 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:

# 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:

// .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, providing usage examples and parameter descriptions.

Package Configuration

Node.js metadata files (.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: Validates the OpenCode plugin's initialization and execution behavior
• 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: Scoring criteria for evaluating ADHD-friendly formatting
• evals/README.md: Methodology documentation for the evaluation framework

Evaluation Runner

The scripts/run_evals.py utility executes the full evaluation suite:

# 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: Validates that the plugin loads correctly across Pi, OMP, and OpenCode environments
• .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: Validates TypeScript compilation for Pi adapters
• 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: Primary project overview and installation instructions
• INSTALL.md: Step-by-step setup guide for developers
• 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 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 and kimi.plugin.json) consume the platform-agnostic skill definition in 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. 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, while behavioral evaluations in evals/ assess adherence to ADHD-friendly formatting rules using cases.jsonl and rubric.md. The scripts/run_evals.py orchestrates these tests, and .github/workflows/plugin-load-check.yml ensures continuous validation across all supported runtimes during CI/CD pipelines.

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