How i-have-adhd Enforces ADHD-Friendly Response Formatting: A Technical Deep Dive

The i-have-adhd skill enforces ADHD-friendly response formatting through a three-component pipeline: a canonical rule set in SKILL.md, a SessionStart hook that injects rules at the start of every chat, and a plugin entry point that intercepts and rewrites all model outputs before they reach the user.

The i-have-adhd skill is an OpenCode plugin that reshapes AI assistant responses for readers with ADHD. According to the ayghri/i-have-adhd source code, the enforcement mechanism operates at the runtime level—guaranteeing compliance regardless of which underlying model generates the raw answer.

Core Components of the Enforcement System

SKILL.md: The Canonical Rule Set

The file skills/i-have-adhd/SKILL.md defines ten concrete formatting rules that constitute the ADHD-friendly style. These include leading with the next actionable step, numbering multi-step tasks, suppressing tangents, and providing concrete time estimates.

The skill's runtime loads this file as its authoritative source. Each rule is programmed into the response-filter pipeline, making SKILL.md the single source of truth for all formatting decisions.

SessionStart Hook: Universal Rule Injection

The hook declaration in hooks/hooks.json registers a SessionStart hook that activates the skill at the beginning of every chat session. The companion file hooks/always-on.mjs implements persistent activation logic.

When the skill is active—either via the /i-have-adhd command or an always-on flag—the hook instructs the runtime to wrap all model outputs with the rule-enforcement filter before delivery to the user.

Plugin Entry Point: Command Handler and Formatter

The file .opencode/plugins/i-have-adhd.mjs provides:

• The /i-have-adhd command interface
• Logic to read SKILL.md and activate the SessionStart hook
• Support for a persistent flag file at ~/.claude/.i-have-adhd-always
• The actual formatter implementation that rewrites each response

How the Formatting Pipeline Works

The enforcement flow proceeds in five stages:

1. Activation — User types /i-have-adhd or enables the always-on flag; the plugin registers the session hook
2. Rule Loading — The plugin reads skills/i-have-adhd/SKILL.md
3. Response Interception — The hook invokes the formatter on every model output
4. Formatting Pass — The formatter executes four specific transformations:
   • Moves the first actionable command or code snippet to the top
   • Converts multi-step instructions to a compact numbered list (maximum 5 items)
   • Strips prohibited preambles, tangents, and closing pleasantries
   • Appends a concrete next-action line (≤ 2 minutes effort) with time estimate and visible "win" statement
5. Delivery — The transformed text reaches the user

Because this hook runs after model generation but before user delivery, the skill guarantees compliance across all supported runtimes: Claude Code, Codex, OpenCode, Pi, OMP, Qwen, Gemini, and others.

Activation Methods

Temporary Activation

/i-have-adhd

After this command, every subsequent reply follows the ADHD-friendly format until you type stop adhd mode or normal mode.

Persistent Activation

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

This flag file makes the SessionStart hook load the rules automatically for every new session.

Example Transformation

Raw model output (hypothetical):

"I think the best approach here would be to consider the authentication flow. There are several schools of thought on this, but let me walk you through what I'd recommend. First, you'll want to look at the token verification logic..."

After i-have-adhd formatting:

1. Open `src/auth.ts`
2. Replace `verifyToken` (lines 42-58) with the snippet below
3. Run `npm test -- auth.spec.ts`

Time estimate: About 12 minutes.
Next: run `npm test` and paste the first failing line.

The filter extracts actionable content, discards tangential prose, and structures the remainder into the enforced format.

Key Source Files

File	Purpose
skills/i-have-adhd/SKILL.md	Canonical rule set defining the ten formatting requirements
hooks/hooks.json	Declares the SessionStart hook for rule injection
hooks/always-on.mjs	Implements always-on flag logic for persistent activation
.opencode/plugins/i-have-adhd.mjs	Plugin entry point with command handler and formatter implementation
.opencode/command/i-have-adhd.md	Command documentation for OpenCode interface

Summary

• SKILL.md provides the rule set that defines ADHD-friendly formatting
• SessionStart hooks inject these rules at the start of every chat session
• The plugin formatter intercepts and rewrites all model outputs before user delivery
• Two activation modes exist: temporary (/i-have-adhd command) and persistent (flag file)
• Universal compatibility applies across Claude Code, OpenCode, and other supported runtimes

Frequently Asked Questions

What makes a response "ADHD-friendly" in this skill?

ADHD-friendly responses follow ten concrete rules from SKILL.md: lead with the next action, number multi-step tasks (max 5), suppress tangents, give concrete time estimates, append a single next-action line (≤ 2 min effort), and include a visible "win" statement. The skill enforces these through automated rewriting of every model output.

Can I use i-have-adhd with models other than Claude?

Yes. The enforcement mechanism operates at the runtime level through SessionStart hooks, not the model itself. The skill works with Claude Code, Codex, OpenCode, Pi, OMP, Qwen, Gemini, and any other runtime that supports the OpenCode hook system.

Where does the skill store my always-on preference?

The skill checks for a flag file at ~/.claude/.i-have-adhd-always. If this file exists, hooks/always-on.mjs activates the SessionStart hook automatically for every new session. Delete or rename this file to disable persistent mode.

How does the formatter handle responses that don't contain clear actions?

The formatter in .opencode/plugins/i-have-adhd.mjs attempts to extract any actionable content—even if it's just a single next step. Failing that, it may transform informational responses into a "Next: [specific action to continue]" format to maintain the required structure. The ten rules in SKILL.md guide these edge-case decisions.

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