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

The i-have-adhd project uses a modular plugin architecture that separates a single ruleset (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. 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.

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

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

# 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. 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, these typically require copying or symlinking the skills/ folder into the agent's designated plugin directory, then referencing 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 once for that command
Always-on	Create ~/.{runtime}/.i-have-adhd-always	Injects 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:

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 file serves as the canonical metadata declaration for marketplace listings:

{
  "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	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	Pi/OMP native extension with slash command integration
plugin.json	Marketplace manifest for discoverability and installation
INSTALL.md	Per-runtime installation commands and configuration details
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 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 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 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 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 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 through its native mechanism. The 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. 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.

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