Source-of-Truth Rules for Maintaining Skill Mirrors Across Platforms

The i-have-adhd repository enforces strict source-of-truth rules requiring all skill modifications to originate in skills/i-have-adhd/SKILL.md before propagating to platform-specific mirrors like the Cursor copy at .cursor/skills/i-have-adhd/SKILL.md, ensuring byte-for-byte consistency across Claude, Codex, and other AI runtimes.

The ayghri/i-have-adhd project implements a rigorous protocol for maintaining skill mirrors across platforms, treating the canonical skill definition as the single authoritative version. According to the repository's AGENTS.md documentation, any deviation between the source file and its mirrors creates behavioral drift across AI assistants, making strict synchronization essential for reliable multi-platform execution.

The Canonical File Architecture

The repository designates skills/i-have-adhd/SKILL.md as the immutable source of truth. This file contains the definitive skill definition, including behavior specifications, metadata, and runtime instructions. All other copies—referred to as skill mirrors—are derivative artifacts that must maintain exact parity with this canonical location.

The primary mirror resides at .cursor/skills/i-have-adhd/SKILL.md, specifically serving the Cursor IDE. While multiple runtimes (Claude, Codex, Pi, OMP, OpenCode) consume this skill data, the synchronization rules apply universally: the canonical file changes first, and mirrors follow without transformation.

The Five Source-of-Truth Rules for Skill Mirroring

Documented in AGENTS.md, these five rules govern how contributors maintain consistency between the canonical definition and all platform-specific copies.

1. Edit the Canonical File First

Any change to skill behavior, configuration, or metadata must originate in skills/i-have-adhd/SKILL.md. This rule ensures that version control history accurately reflects the evolution of the authoritative definition, preventing orphaned changes in mirror files that lack upstream representation.

2. Synchronize the Mirror Immediately

After updating the canonical file, the platform-specific mirror at .cursor/skills/i-have-adhd/SKILL.md must be brought into exact alignment. The mirror is a plain copy; no transformation is applied, so a simple file copy operation is sufficient to guarantee byte-for-byte equality.

3. Treat Manifests and Hooks as Contracts

Files such as hooks/hooks.json, hooks/always-on.*, and runtime manifests (.claude-plugin/, .codex-plugin/, opencode.json) define contract-level behavior. Their versions and metadata must stay consistent across all platforms, just like the skill files, because they govern runtime execution hooks that assistants depend on.

4. Keep Documentation Accurate

Public-facing documentation—including README.md, INSTALL.md, and localized variants—must reflect the current state of the skill and its mirrors. When the canonical skill changes, contributors must update corresponding documentation to prevent user confusion about available capabilities or installation procedures.

5. Do Not Edit Generated Artifacts

Auto-generated files such as compiled bundles, lockfiles, or cache directories should never be edited manually. This rule prevents drift between the source-of-truth and derived artifacts, ensuring that build processes remain reproducible and that manual changes do not get overwritten by automated tooling.

Synchronization Workflows: Manual and Automated

The repository supports multiple workflows for maintaining mirror consistency, ranging from manual command-line operations to fully automated CI/CD pipelines.

Manual Synchronization with Bash

For immediate local updates, use a simple copy operation followed by verification:

# 1. Edit the canonical skill file

vim skills/i-have-adhd/SKILL.md   # make your changes, then save

# 2. Sync the Cursor mirror

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

# 3. Verify that both files are identical

diff -u skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md

The cp command guarantees byte-for-byte equality, while the optional diff step provides a safety net for CI pipelines or pre-commit hooks.

Automated CI/CD with GitHub Actions

To prevent human error, automate synchronization using a workflow triggered by changes to the canonical file:

# .github/workflows/sync-skill.yml

name: Sync Skill Mirror
on:
  push:
    paths:
      - 'skills/i-have-adhd/SKILL.md'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Sync mirror
        run: cp skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md
      - name: Commit sync
        run: |
          git config --global user.name "github-actions[bot]"
          git config --global user.email "github-actions[bot]@users.noreply.github.com"
          git add .cursor/skills/i-have-adhd/SKILL.md
          git commit -m "🔄 Sync skill mirror after canonical change"
          git push

This workflow triggers only when skills/i-have-adhd/SKILL.md changes, automatically propagating updates to the mirror and committing the change to keep the repository consistently synchronized.

Programmatic Synchronization in Node.js

For JavaScript-based tooling chains, use the filesystem API to perform the synchronization:

// scripts/syncSkillMirror.js
import { readFileSync, writeFileSync } from 'fs';
import { resolve } from 'path';

const canonical = resolve('skills/i-have-adhd/SKILL.md');
const mirror   = resolve('.cursor/skills/i-have-adhd/SKILL.md');

const content = readFileSync(canonical, 'utf8');
writeFileSync(mirror, content);
console.log('✅ Mirror synced to canonical skill.');

Execute the script with node scripts/syncSkillMirror.js after editing the canonical file. This approach integrates easily with npm-based build processes or custom developer tooling.

Enforcing Compliance via Pull Request Templates

The repository reinforces these rules through the pull request template located at .github/pull_request_template.md. Contributors must verify that "Canonical and mirrored skill files are synchronized when applicable" before submitting changes. This checklist requirement creates a manual gate that catches desynchronization before it reaches the main branch, ensuring that all runtimes (Claude, Codex, Pi, OMP, OpenCode) operate on identical skill definitions.

Summary

• The file skills/i-have-adhd/SKILL.md serves as the single source of truth for the i-have-adhd skill definition.
• Platform mirrors—specifically .cursor/skills/i-have-adhd/SKILL.md—must remain byte-for-byte identical to the canonical file.
• Always edit the canonical file first, then synchronize mirrors using simple copy operations.
• Runtime contracts including hooks/hooks.json and platform manifests must stay consistent across all targets.
• Never manually edit auto-generated artifacts to prevent drift from the source-of-truth.
• Automate synchronization via GitHub Actions or Node.js scripts to eliminate human error.

Frequently Asked Questions

What is the canonical source-of-truth file in the i-have-adhd repository?

The canonical source-of-truth is skills/i-have-adhd/SKILL.md. This file contains the definitive skill definition, and all platform-specific mirrors must derive from it without modification.

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

Editing a mirror directly violates the source-of-truth protocol and creates behavioral drift across platforms. Changes made to .cursor/skills/i-have-adhd/SKILL.md without updating the canonical version will be overwritten during the next synchronization and will not be tracked in version control history.

Which files act as runtime contracts that must stay synchronized?

Beyond the main skill file, hooks/hooks.json, hooks/always-on.*, and platform-specific manifests (.claude-plugin/, .codex-plugin/, opencode.json) define contract-level behavior. These files must maintain version and metadata consistency across all platforms to ensure compatible runtime execution.

How does the repository prevent skill desynchronization?

The repository uses a pull request checklist in .github/pull_request_template.md that requires contributors to confirm synchronization between canonical and mirrored files. Additionally, automated CI workflows can enforce this by triggering synchronization jobs whenever the canonical skill file changes.

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