What Is the Hierarchy for Metadata Updates Across Plugin Manifests in i-have-adhd?

The repository enforces a strict five-tier hierarchy where skills/i-have-adhd/SKILL.md serves as the single source of truth, followed by a Cursor-compatible mirror, then runtime-specific manifests, hook declarations, and finally CI validation to guarantee consistency.

The ayghri/i-have-adhd project maintains multiple plugin manifests to support diverse AI runtimes including Claude, Codex, OpenCode, Qwen, Kimi, and Gemini. Understanding the hierarchy for metadata updates across different plugin manifests ensures that version numbers, entry points, and capability flags remain synchronized across all runtime contracts.

The Canonical Source of Truth

Every metadata change originates in skills/i-have-adhd/SKILL.md. This file contains the authoritative definition of skill behavior, version metadata, and capability descriptions. According to the source-of-truth rules documented in the repository, you must modify this file first before touching any downstream manifests.

The repository explicitly treats this path as the runtime contract baseline. Changes to functionality, descriptions, or supported operations must be committed here to maintain the integrity of the plugin's public interface.

Mirror Synchronization Layer

After updating the canonical skill definition, the hierarchy mandates synchronization with the Cursor-compatible mirror at .cursor/skills/i-have-adhd/SKILL.md. This duplication ensures that Cursor IDE users receive identical behavior definitions without parsing the primary skill file directly.

The mirror acts as a read-only reflection of the canonical source. Updates flow unidirectionally from skills/i-have-adhd/SKILL.md to the .cursor directory, never the reverse.

Runtime Manifest Propagation

Once the skill definition stabilizes, metadata propagates to each runtime-specific manifest. These JSON files declare versions, entry points, and platform compatibility settings.

Core and Claude/Codex Manifests

The primary runtime manifests reside at:

• plugin.json – The core manifest used by generic plugin loaders
• .claude-plugin/plugin.json – Claude-specific configuration
• .codex-plugin/plugin.json – Codex-specific configuration

These files must align their "version" fields with the semantic version declared in the canonical skill documentation.

Extended Runtime Support

Additional runtimes require their own dedicated manifest files:

• opencode.json – OpenCode IDE integration
• qwen-extension.json – Qwen runtime extension metadata
• kimi.plugin.json – Kimi plugin definition
• gemini-extension.json – Gemini extension configuration
• package.json – Pi and OMP compatibility entries

Each manifest must reflect the same version identifier and capability flags defined in the source skill to prevent runtime drift.

Hook Configuration Alignment

The hooks/hooks.json file represents the fourth tier in the hierarchy. This configuration references plugin versions and metadata to coordinate always-on scripts and lifecycle hooks. When updating manifests, you must ensure that any version strings stored in hooks/hooks.json match the values in the runtime-specific JSON files.

Treating manifests and hook declarations as runtime contracts means that shared metadata, including versions, must remain aligned across these configuration boundaries.

Automated Validation via CI

The final tier involves .github/workflows/plugin-load-check.yml and related workflows. These CI pipelines automatically validate that all manifest files maintain consistency with the canonical source. If version mismatches or metadata drift occur between SKILL.md, the runtime manifests, and hook configurations, the build fails immediately.

This enforcement mechanism guarantees that the hierarchy remains intact throughout the development lifecycle.

Practical Update Workflow

The following bash snippet demonstrates the complete metadata update sequence as implemented in the repository's CI utilities:

#!/usr/bin/env bash
NEW_VER="1.3.0"

# Tier 1: Sync the Cursor mirror from canonical source

cp skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md

# Tier 2: Update all runtime manifests

sed -i "s/\"version\": \".*\"/\"version\": \"${NEW_VER}\"/" plugin.json
sed -i "s/\"version\": \".*\"/\"version\": \"${NEW_VER}\"/" .claude-plugin/plugin.json
sed -i "s/\"version\": \".*\"/\"version\": \"${NEW_VER}\"/" .codex-plugin/plugin.json
sed -i "s/\"version\": \".*\"/\"version\": \"${NEW_VER}\"/" opencode.json
sed -i "s/\"version\": \".*\"/\"version\": \"${NEW_VER}\"/" qwen-extension.json
sed -i "s/\"version\": \".*\"/\"version\": \"${NEW_VER}\"/" kimi.plugin.json
sed -i "s/\"version\": \".*\"/\"version\": \"${NEW_VER}\"/" gemini-extension.json

# Tier 3: Align hook configuration

sed -i "s/\"pluginVersion\": \".*\"/\"pluginVersion\": \"${NEW_VER}\"/" hooks/hooks.json

# Tier 4: Validation occurs automatically via CI workflows

For Node.js-based runtimes, you can verify local manifest alignment programmatically:

import fs from "fs";
import path from "path";

const manifestPath = path.resolve(import.meta.dirname, "..", "opencode.json");
const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
console.log(`Running ${manifest.name} v${manifest.version}`);

Summary

• skills/i-have-adhd/SKILL.md functions as the single source of truth for all plugin metadata and behavior definitions.
• .cursor/skills/i-have-adhd/SKILL.md receives unidirectional synchronization from the canonical skill file.
• Runtime manifests (plugin.json, .claude-plugin/plugin.json, .codex-plugin/plugin.json, opencode.json, qwen-extension.json, kimi.plugin.json, gemini-extension.json) must reflect identical version and capability metadata.
• hooks/hooks.json maintains aligned version references for lifecycle hook execution.
• CI workflows enforce the hierarchy by failing builds when metadata inconsistencies are detected between tiers.

Frequently Asked Questions

Which file should I edit first when updating plugin capabilities?

You must edit skills/i-have-adhd/SKILL.md first. The repository's source-of-truth rules explicitly require changing the canonical skill definition before synchronizing any other manifests. This ensures that all downstream files inherit consistent behavioral descriptions and version metadata.

How do I ensure version numbers stay consistent across all runtimes?

Use the CI validation scripts or manually update all JSON manifests simultaneously. The hierarchy requires that plugin.json, .claude-plugin/plugin.json, .codex-plugin/plugin.json, opencode.json, qwen-extension.json, kimi.plugin.json, and gemini-extension.json share identical "version" strings. The hooks/hooks.json file must also reflect this version if it tracks plugin metadata.

What happens if I update a runtime manifest without updating SKILL.md?

The .github/workflows/plugin-load-check.yml CI pipeline will detect the inconsistency and fail the build. The repository treats manifests as runtime contracts that must align with the canonical skill definition. This enforcement prevents version drift and ensures that all AI runtimes consume identical capability descriptions.

Does the Cursor mirror affect the actual plugin functionality?

No, the .cursor/skills/i-have-adhd/SKILL.md mirror serves only IDE compatibility purposes. It reflects the canonical skill file but does not drive runtime behavior. Functionality remains determined by the primary SKILL.md and the JSON manifests consumed by each specific runtime loader.

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