How Runtime Manifests Are Synchronized Across Different Plugin Configurations

The i-have-adhd repository maintains runtime manifests synchronized across different plugin configurations by establishing 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.

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 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 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.

{
  "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 for Claude Code
• .codex-plugin/plugin.json for Codex
• opencode.json for OpenCode
• qwen-extension.json for Qwen
• kimi.plugin.json for Kimi
• gemini-extension.json for Gemini

These manifests must mirror the core fields from plugin.json while allowing runtime-specific extensions. For example, the Claude Code manifest at .claude-plugin/plugin.json contains:

{
  "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 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 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 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:

# .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. For instance, .codex-plugin/plugin.json might include a custom interface field, while .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 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
• 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 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. 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 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 values.

Where is the synchronization requirement documented?

The source-of-truth rules are documented in 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.

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