# i-have-adhd Plugin Architecture: How One Skill Powers Multiple AI Coding Assistants

> Explore the i-have-adhd plugin architecture. Discover how a single ruleset powers multiple AI coding assistants like Claude Code, OpenCode, and Pi for consistent ADHD-friendly behavior.

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

---

**The i-have-adhd project uses a modular plugin architecture that separates a single ruleset ([`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md)) from lightweight runtime-specific wrappers, enabling the same ADHD-friendly behavior across Claude Code, OpenCode, Pi, OMP, and other AI assistants.**

This open-source project by `ayghri` solves a common problem for neurodivergent developers: consistent, ADHD-optimized coding assistance across multiple AI tools. Rather than maintaining separate implementations for each runtime, the architecture centralizes the ruleset and distributes thin adapter layers. This design pattern—content decoupled from transport—makes the skill portable, versionable, and easy to extend to new agents.

---

## Single Source of Truth: The SKILL.md Pattern

At the core of this plugin architecture sits [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md). This markdown file contains the complete ruleset governing how the AI assistant should behave—breaking tasks into chunks, minimizing context switches, providing explicit summaries, and other ADHD-accommodating patterns.

**Every runtime loads this identical file.** There is no duplication of logic across agents. When the ruleset updates, all runtimes receive the change immediately since they reference the same path.

```bash

# Location of the canonical ruleset

skills/i-have-adhd/SKILL.md

```

The file structure under `skills/` follows a convention that multiple agent frameworks recognize: a directory named after the skill containing a [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) file with standardized frontmatter and behavioral instructions.

---

## Runtime-Specific Wrappers: The Adapter Layer

Each AI assistant requires a small wrapper to register the skill, expose the `/i-have-adhd` command, and optionally enable always-on mode. These wrappers are **intentionally minimal**—they load [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) and delegate to the runtime's plugin API rather than reimplementing behavior.

### OpenCode: Full Plugin Implementation

The OpenCode wrapper at `.opencode/plugins/i-have-adhd.mjs` demonstrates the most complete adapter. It:

- Registers the `skills/` directory in the plugin search path
- Creates the `/i-have-adhd` slash command for on-demand activation
- Checks for `~/.config/opencode/.i-have-adhd-always` on every turn
- Injects the full ruleset into the system prompt when the flag file exists

```bash

# Install for OpenCode

git clone https://github.com/ayghri/i-have-adhd ~/.config/opencode/vendor/i-have-adhd

# Register in opencode.json

cat >> ~/.config/opencode/opencode.json <<'EOF'
{
  "plugin": ["/home/$(whoami)/.config/opencode/vendor/i-have-adhd/.opencode/plugins/i-have-adhd.mjs"]
}
EOF

# Enable always-on mode

touch ~/.config/opencode/.i-have-adhd-always

```

### Claude Code / Codex: SessionStart Hook

For Claude Code and OpenAI Codex, the project uses a **SessionStart hook** pattern. The file `hooks/always-on.mjs` runs when a new session begins, checking for the presence of `$CLAUDE_CONFIG_DIR/.i-have-adhd-always` (typically `~/.claude/.i-have-adhd-always`).

When detected, the hook prints the ruleset to stdout, effectively injecting it into the conversation context. This mimics the behavior of OpenCode's per-turn injection but operates at session initialization.

```bash

# Enable always-on for Claude Code

touch ~/.claude/.i-have-adhd-always

```

### Pi and OMP: Native Extension Format

The Pi runtime (and its marketplace variant OMP, "Oh My Pi") uses a TypeScript extension at [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts). This supplies:

- Native extension loading via Pi's plugin system
- A `/i-have-adhd` slash command registered in the Pi interface
- Direct access to Pi's context injection APIs

The same source file serves both Pi and OMP through conditional packaging—demonstrating how the architecture accommodates marketplace distribution without code forks.

### Other Runtimes: Minimal Wrappers

Qwen, Kimi, Gemini, Zed, Hermes, and additional agents supported by the project use **scan-path registration**. As documented in [`INSTALL.md`](https://github.com/ayghri/i-have-adhd/blob/main/INSTALL.md), these typically require copying or symlinking the `skills/` folder into the agent's designated plugin directory, then referencing [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) through the runtime's native skill-discovery mechanism.

---

## Activation Patterns: On-Demand vs. Always-On

The plugin architecture supports two usage modes controlled by **flag files**—empty sentinel files whose existence signals intent.

| Mode | Activation | Behavior |
|------|-----------|----------|
| **On-demand** | Run `/i-have-adhd` or `$i-have-adhd` | Loads [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) once for that command |
| **Always-on** | Create `~/.{runtime}/.i-have-adhd-always` | Injects [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) into every system prompt |

The flag file pattern is consistent across runtimes, varying only in base config directory:

- Claude Code: `~/.claude/.i-have-adhd-always`
- OpenCode: `~/.config/opencode/.i-have-adhd-always`
- Codex: follows `$CLAUDE_CONFIG_DIR` convention

To disable during a session, the skill itself recognizes:

```bash
stop adhd mode

```

This universal command works across all runtimes that parse the skill's instruction set, providing consistent user experience regardless of underlying adapter.

---

## Plugin Manifest and Marketplace Distribution

The [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) file serves as the **canonical metadata declaration** for marketplace listings:

```json
{
  "name": "i-have-adhd",
  "description": "ADHD-friendly coding assistance with chunked tasks and explicit summaries"
}

```

This manifest enables automated indexing by plugin marketplaces (OMP, Pi Store, future Claude Code marketplace). The separation of manifest from implementation allows the same repository to be packaged multiple ways without modification.

---

## Key Files in the Plugin Architecture

| File | Role |
|------|------|
| [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) | Core ruleset—behavioral instructions for ADHD-accommodating assistance |
| `.opencode/plugins/i-have-adhd.mjs` | OpenCode plugin: command registration, path setup, always-on injection |
| `hooks/always-on.mjs` | Claude Code/Codex SessionStart hook for automatic ruleset loading |
| [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) | Pi/OMP native extension with slash command integration |
| [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) | Marketplace manifest for discoverability and installation |
| [`INSTALL.md`](https://github.com/ayghri/i-have-adhd/blob/main/INSTALL.md) | Per-runtime installation commands and configuration details |
| [`AGENTS.md`](https://github.com/ayghri/i-have-adhd/blob/main/AGENTS.md) | Architecture documentation: runtime map, entry points, activation flows |

---

## Design Principles of the Architecture

The i-have-adhd plugin architecture embodies several software engineering patterns:

1. **DRY (Don't Repeat Yourself)**: One [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) serves all runtimes
2. **Open/Closed**: New agents require only new wrappers, not ruleset changes
3. **Convention over Configuration**: Standard `skills/{name}/SKILL.md` path structure
4. **Feature Flags**: File-based toggles for mode selection without config file editing
5. ** progressive Enhancement**: Core functionality works everywhere; advanced features (always-on injection) where runtimes support it

---

## Summary

- **Centralized ruleset**: [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) provides single-source behavioral definitions
- **Adapter pattern**: Runtime wrappers in `.opencode/plugins/`, `hooks/`, and `extensions/` translate the skill to local plugin APIs
- **Dual activation**: On-demand via `/i-have-adhd` command or always-on via `.i-have-adhd-always` flag files
- **Broad compatibility**: Works with Claude Code, OpenCode, Pi, OMP, Qwen, Codex, and other agents through consistent conventions
- **Minimal maintenance**: Updates to [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) propagate instantly to all supported runtimes

This architecture demonstrates how neurodivergent accessibility features can be packaged for maximum reach without compromising maintainability.

---

## Frequently Asked Questions

### How does the i-have-adhd plugin work across different AI coding assistants?

Each runtime loads the same [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) ruleset through a thin wrapper specific to that agent's plugin system. The OpenCode wrapper uses `.opencode/plugins/i-have-adhd.mjs` to register commands and inject prompts; Claude Code uses `hooks/always-on.mjs` for session-start injection; Pi uses [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) as a native extension. All reference identical content from `skills/i-have-adhd/`.

### What file enables always-on mode in Claude Code?

Create an empty file at `~/.claude/.i-have-adhd-always`. The `hooks/always-on.mjs` script detects this file at session start and prints the full ruleset into the conversation context. Delete or rename the file to disable automatic injection.

### Can I use i-have-adhd with runtimes not officially listed?

Yes. Any agent that supports skill discovery through a scan path or manual plugin registration can use the project. Copy or symlink `skills/i-have-adhd/` into the runtime's plugin directory and reference [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) through its native mechanism. The [`INSTALL.md`](https://github.com/ayghri/i-have-adhd/blob/main/INSTALL.md) file documents this pattern for emerging runtimes.

### Where is the actual behavior defined—not the wrapper code?

All behavioral instructions live in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md). This includes how to break tasks into chunks, when to provide summaries, how to handle interruptions, and the `stop adhd mode` command. The wrappers contain zero business logic; they only route this file into the runtime's prompt system.