# How Runtime Manifests Are Synchronized Across Different Plugin Configurations

> Learn how i-have-adhd syncs runtime manifests across plugin configurations using plugin.json as the source of truth, enforced by CI validation for consistent name, version, and description.

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

---

**The i-have-adhd repository maintains runtime manifests synchronized across different plugin configurations by establishing [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) as the canonical source of truth and enforcing identical **name**, **version**, and **description** fields through both manual editing protocols and automated CI validation in [`.github/workflows/cursor-skill-sync.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/cursor-skill-sync.yml).**

The open-source **i-have-adhd** project provides ADHD-friendly output shaping for multiple AI coding assistants, including Claude Code, Codex, OpenCode, Qwen, Kimi, and Gemini. Keeping **runtime manifests synchronized across different plugin configurations** ensures that every AI runtime presents an identical plugin identity to users while still permitting runtime-specific extensions. The repository achieves this consistency through a dual-layer synchronization strategy documented in [`AGENTS.md`](https://github.com/ayghri/i-have-adhd/blob/main/AGENTS.md) and enforced via GitHub Actions.

## The Runtime Manifest Architecture

The project implements a **hub-and-spoke model** where one canonical manifest feeds multiple runtime-specific configurations.

### Canonical Source of Truth

The [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) file at the repository root serves as the **single source of truth** for shared metadata. This file defines the immutable core identity fields that must propagate to all runtime manifests. According to the source code structure, this JSON object contains the baseline `name`, `version`, and `description` values that represent the plugin's public identity.

```json
{
  "name": "i-have-adhd",
  "description": "Shape Antigravity output for an ADHD reader: lead with the next action, number steps, suppress tangents, restate state, make wins visible."
}

```

### Runtime-Specific Manifests

Each supported runtime maintains its own manifest file, allowing the plugin to integrate with different AI coding environments while preserving the canonical identity:

- [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) for Claude Code
- [`.codex-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.codex-plugin/plugin.json) for Codex  
- [`opencode.json`](https://github.com/ayghri/i-have-adhd/blob/main/opencode.json) for OpenCode
- [`qwen-extension.json`](https://github.com/ayghri/i-have-adhd/blob/main/qwen-extension.json) for Qwen
- [`kimi.plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/kimi.plugin.json) for Kimi
- [`gemini-extension.json`](https://github.com/ayghri/i-have-adhd/blob/main/gemini-extension.json) for Gemini

These manifests must mirror the core fields from [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) while allowing runtime-specific extensions. For example, the Claude Code manifest at [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) contains:

```json
{
  "name": "i-have-adhd",
  "version": "0.2.0",
  "description": "Shape Claude Code output for an ADHD reader: lead with the next action, number steps, suppress tangents, restate state, make wins visible."
}

```

## Synchronization Mechanisms

Consistency is enforced through two complementary mechanisms that prevent configuration drift.

### Manual Single-Source-of-Truth Updates

Developers must manually propagate changes from the canonical [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) to all runtime-specific manifests before committing. When updating the **name**, **version**, or **description** fields, contributors copy these exact values into each runtime manifest. The [`AGENTS.md`](https://github.com/ayghri/i-have-adhd/blob/main/AGENTS.md) file explicitly mandates this protocol, stating that shared metadata must be kept identical across every manifest to guarantee consistent behavior.

### Automated CI Validation

The [`.github/workflows/cursor-skill-sync.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/cursor-skill-sync.yml) workflow runs on every push to validate synchronization. This GitHub Actions job parses each manifest and asserts that the `name`, `version`, and `description` values match the canonical file. If any discrepancy is detected, the workflow fails and blocks the merge, preventing out-of-sync configurations from reaching the main branch.

Because the manifests are compact JSON objects, the CI check uses `jq` to parse and compare the relevant keys directly. The validation script reads the canonical manifest and compares normalized JSON structures against each runtime-specific file.

## Implementation Details

### The Validation Logic

The CI workflow implements a straightforward comparison strategy using shell commands and `jq`. The pipeline iterates through all runtime manifests and verifies they match the canonical source for the core identity fields:

```yaml

# .github/workflows/cursor-skill-sync.yml (excerpt)

- name: Verify runtime manifests are in sync
  run: |
    canonical=$(jq -S . /path/to/plugin.json)
    for manifest in .claude-plugin/plugin.json .codex-plugin/plugin.json opencode.json qwen-extension.json kimi.plugin.json gemini-extension.json; do
      if [[ "$(jq -S . "$manifest")" != "$canonical"* ]]; then
        echo "❌ $manifest out of sync"
        exit 1
      fi
    done
    echo "✅ All manifests are synchronized"

```

### Runtime-Specific Extensions

While the core fields must remain synchronized, each runtime manifest may contain unique extensions that do not exist in the canonical [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json). For instance, [`.codex-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.codex-plugin/plugin.json) might include a custom `interface` field, while [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) could specify a unique `brandColor` property. These additions do not violate synchronization rules because they fall outside the scope of the shared metadata contract. The CI validation specifically checks only the `name`, `version`, and `description` keys, ignoring runtime-specific capabilities.

## Summary

- Treat **[`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json)** as the immutable source of truth for plugin identity metadata
- Maintain identical **`name`**, **`version`**, and **`description`** values across all runtime manifests
- Run **`jq`-based CI validation** on every push via [`.github/workflows/cursor-skill-sync.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/cursor-skill-sync.yml)
- Permit **runtime-specific extensions** outside the core identity fields
- Block merges automatically when manifests fall out of synchronization

## Frequently Asked Questions

### What specific fields must remain synchronized across all manifests?

The **`name`**, **`version`**, and **`description`** fields must remain identical across all runtime manifests according to the [`AGENTS.md`](https://github.com/ayghri/i-have-adhd/blob/main/AGENTS.md) specification. These three fields constitute the plugin's public identity contract, ensuring users see consistent metadata regardless of which AI runtime they use.

### Can runtime manifests contain unique fields not present in the canonical file?

Yes. Each runtime manifest can contain unique fields such as `interface` or `brandColor` that are not present in the canonical [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json). The synchronization rules apply only to the core identity fields, allowing runtimes to expose additional capabilities without breaking the consistency contract.

### What happens if a manifest falls out of sync with the canonical source?

The GitHub Actions workflow in [`.github/workflows/cursor-skill-sync.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/cursor-skill-sync.yml) will detect the discrepancy during the validation phase and fail the build. This failure prevents the pull request from merging until the developer updates the runtime manifests to match the canonical [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) values.

### Where is the synchronization requirement documented?

The source-of-truth rules are documented in **[`AGENTS.md`](https://github.com/ayghri/i-have-adhd/blob/main/AGENTS.md)** at the repository root. This file specifies that shared metadata must be kept identical across every manifest and establishes the protocol for maintaining **runtime manifests synchronized across different plugin configurations**.