# Source‑of‑Truth Hierarchy for Skill Behavior in the i‑have‑adhd Plugin

> Understand the source-of-truth hierarchy for skill behavior in the i-have-adhd plugin. Learn how SKILL.md dictates changes across platforms.

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

---

**The i‑have‑adhd plugin defines a five‑level hierarchy where [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) serves as the canonical source, followed by platform mirrors, manifest files, hook declarations, and documentation.**

The `ayghri/i-have-adhd` repository implements a cross‑platform ADHD‑friendly coding assistant skill that must behave identically across Claude, Codex, Cursor, OpenCode, Qwen, Kimi, Gemini, and other runtimes. Understanding the source‑of‑truth hierarchy for skill behavior ensures consistent functionality when modifying or deploying this plugin.

## The Five‑Level Hierarchy Explained

The plugin architecture enforces a strict precedence order. Changes must propagate downward from Level 1 to guarantee platform parity.

### Level 1: Canonical Skill Definition

**[`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)** holds absolute authority.

This single file contains the 10 ADHD‑friendly response rules, tone guidelines, and behavioral prose that define how the skill operates. The [`AGENTS.md`](https://github.com/ayghri/i-have-adhd/blob/main/AGENTS.md) documentation explicitly designates it as *"The source of truth for the 10 ADHD‑friendly response rules"*【AGENTS.md†L19-L22】.

Any behavioral modification starts here.

### Level 2: Cursor‑Compatible Mirror

**[`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md)** provides IDE‑native access.

Cursor's runtime cannot reference files outside its configuration directory, so this mirror exists as a synchronized copy. The [`AGENTS.md`](https://github.com/ayghri/i-have-adhd/blob/main/AGENTS.md) guide instructs developers to *"synchronize the `.cursor` mirror"* immediately after editing the canonical file【AGENTS.md†L45-L46】.

The mirror contains identical content to Level 1 and must never be edited independently.

### Level 3: Runtime Manifest Files

Platform‑specific declarations tell each runtime which skill file to load:

- [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) — Claude Desktop / CLI
- [`.codex-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.codex-plugin/plugin.json) — Codex agent runtime
- [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) — Generic fallback
- [`qwen-extension.json`](https://github.com/ayghri/i-have-adhd/blob/main/qwen-extension.json) — Qwen platform
- [`kimi.plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/kimi.plugin.json) — Kimi assistant
- [`gemini-extension.json`](https://github.com/ayghri/i-have-adhd/blob/main/gemini-extension.json) — Gemini integrations

These are **runtime contracts** that must reference the correct skill path. They typically point to [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) by relative path, so content changes at Level 1 rarely require manifest updates. Path changes, however, demand synchronized updates across all manifest files【AGENTS.md†L45-L47】.

### Level 4: Hook Declarations

**[`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json)** and **`hooks/always-on.*`** configure invocation behavior.

These files specify when the skill activates—such as "always‑on" mode for continuous ADHD‑friendly assistance. Like the manifests, they constitute **runtime contracts** that must stay aligned across platforms【AGENTS.md†L45-L47】.

Hook configuration affects *when* the skill runs, not *how* it behaves, but divergence here would create inconsistent user experiences.

### Level 5: User‑Facing Documentation

**[`README.md`](https://github.com/ayghri/i-have-adhd/blob/main/README.md)**, **[`INSTALL.md`](https://github.com/ayghri/i-have-adhd/blob/main/INSTALL.md)**, and localized variants describe the skill to humans.

While not loaded at runtime, these files must accurately reflect the actual behavior defined in Level 1. The [`AGENTS.md`](https://github.com/ayghri/i-have-adhd/blob/main/AGENTS.md) guide specifically warns to *"keep installation and behavior claims accurate"*【AGENTS.md†L47-L48】.

Documentation drift creates support burden and user confusion even when runtime behavior remains correct.

## Propagation Workflow: Updating the Skill

Follow this exact sequence when modifying skill behavior:

1. **Edit [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)** — add, remove, or revise rules
2. **Sync [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md)** — copy the updated canonical file
3. **Verify manifest paths** — confirm all [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) files reference correct locations
4. **Validate hook alignment** — ensure [`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json) reflects intended activation logic
5. **Update documentation** — revise [`README.md`](https://github.com/ayghri/i-have-adhd/blob/main/README.md) and [`INSTALL.md`](https://github.com/ayghri/i-have-adhd/blob/main/INSTALL.md) to match new behavior
6. **Run validation scripts** — execute platform‑specific checks

```python

# Synchronize the Cursor mirror after canonical edits

import shutil
import pathlib

src = pathlib.Path("skills/i-have-adhd/SKILL.md")
dst = pathlib.Path(".cursor/skills/i-have-adhd/SKILL.md")

# Ensure parent directory exists

dst.parent.mkdir(parents=True, exist_ok=True)

# Copy canonical skill to Cursor mirror

shutil.copyfile(src, dst)

print(f"✅ Synchronized: {src} → {dst}")

```

```bash

# Validate Claude plugin manifest

claude plugin validate .

# Run platform‑agnostic test suite

python -m unittest discover -s tests -v

```

## Critical Files in the Hierarchy

| File | Level | Purpose |
|------|-------|---------|
| [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) | 1 | Canonical skill definition with 10 ADHD‑friendly rules |
| [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md) | 2 | Cursor IDE mirror requiring manual synchronization |
| [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) | 3 | Claude runtime contract |
| [`.codex-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.codex-plugin/plugin.json) | 3 | Codex runtime contract |
| [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) | 3 | Generic fallback manifest |
| [`qwen-extension.json`](https://github.com/ayghri/i-have-adhd/blob/main/qwen-extension.json), [`kimi.plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/kimi.plugin.json), [`gemini-extension.json`](https://github.com/ayghri/i-have-adhd/blob/main/gemini-extension.json) | 3 | Platform‑specific runtime contracts |
| [`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json) | 4 | Cross‑platform invocation configuration |
| `hooks/always-on.*` | 4 | Always‑on behavior hooks |
| [`README.md`](https://github.com/ayghri/i-have-adhd/blob/main/README.md), [`INSTALL.md`](https://github.com/ayghri/i-have-adhd/blob/main/INSTALL.md) | 5 | User‑facing documentation requiring consistency |

## Platform Coverage

This hierarchy supports synchronized deployment across:

- **Claude** (Desktop, CLI, API)
- **Codex** (OpenAI agent runtime)
- **Cursor** (IDE with native `.cursor` configuration)
- **Pi**, **OMP**, **OpenCode**
- **Qwen** (Alibaba models)
- **Kimi** (Moonshot AI)
- **Gemini** (Google models)

Each platform consumes the same Level 1 source through its respective Level 2–4 adapters.

## Summary

- **[`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)** is the immutable source of truth for all skill behavior
- **[`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md)** requires explicit synchronization after every canonical change
- **Manifest files** across `.claude-plugin/`, `.codex-plugin/`, and platform‑specific directories form runtime contracts that must reference correct paths
- **Hook declarations** in `hooks/` govern cross‑platform activation logic
- **Documentation** must be manually updated to prevent behavioral claims from diverging from implementation
- The AGENTS.md file at repository root documents this hierarchy and validation procedures【AGENTS.md†L19-L22】【AGENTS.md†L45-L48】

## Frequently Asked Questions

### What happens if I edit the Cursor mirror directly instead of the canonical file?

The change will be overwritten on next synchronization and will not propagate to other platforms. Claude, Codex, Qwen, Kimi, and Gemini runtimes will continue using stale behavior from [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md), creating dangerous platform inconsistency. Always edit the canonical file first, then sync downward.

### Do I need to update every manifest file when adding a new ADHD response rule?

Typically no. Manifest files reference skill files by path, not by content hash. Since [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) retains its location during rule additions, existing manifests remain valid. You must update manifests only when renaming the skill file or restructuring the repository layout.

### How does the hook system interact with the source‑of‑truth hierarchy?

Hooks operate at Level 4 and control *when* the skill activates, not *how* it responds. The [`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json) and `hooks/always-on.*` files must stay synchronized across platforms to ensure consistent activation timing, but they do not override the behavioral rules defined in [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md). Both dimensions—invocation logic and response behavior—must align for uniform cross‑platform experience.