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

The i‑have‑adhd plugin defines a five‑level hierarchy where 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 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 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 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 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 — Claude Desktop / CLI
• .codex-plugin/plugin.json — Codex agent runtime
• plugin.json — Generic fallback
• qwen-extension.json — Qwen platform
• kimi.plugin.json — Kimi assistant
• 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 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 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, 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 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 — add, remove, or revise rules
2. Sync .cursor/skills/i-have-adhd/SKILL.md — copy the updated canonical file
3. Verify manifest paths — confirm all plugin.json files reference correct locations
4. Validate hook alignment — ensure hooks/hooks.json reflects intended activation logic
5. Update documentation — revise README.md and INSTALL.md to match new behavior
6. Run validation scripts — execute platform‑specific checks

# 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}")

# 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	1	Canonical skill definition with 10 ADHD‑friendly rules
.cursor/skills/i-have-adhd/SKILL.md	2	Cursor IDE mirror requiring manual synchronization
.claude-plugin/plugin.json	3	Claude runtime contract
.codex-plugin/plugin.json	3	Codex runtime contract
plugin.json	3	Generic fallback manifest
qwen-extension.json, kimi.plugin.json, gemini-extension.json	3	Platform‑specific runtime contracts
hooks/hooks.json	4	Cross‑platform invocation configuration
hooks/always-on.*	4	Always‑on behavior hooks
README.md, 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 is the immutable source of truth for all skill behavior
• .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, 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 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 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. Both dimensions—invocation logic and response behavior—must align for uniform cross‑platform experience.

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