Understanding the Versioning Strategy for i-have-adhd: A Complete Guide

i-have-adhd follows Semantic Versioning (SemVer) by defining version 0.2.0 centrally in package.json and manually propagating that string to seven runtime-specific plugin manifests including Claude, Codex, Gemini, Kimi, Qwen, and OpenCode.

The ayghri/i-have-adhd repository employs a straightforward versioning strategy designed to maintain strict synchronization across multiple AI runtime environments. By treating the root package.json as the single source of truth and explicitly updating individual plugin configuration files, the project ensures that every supported platform reports identical version numbers for runtime compatibility checks and change tracking.

Semantic Versioning Foundation

The project adheres strictly to Semantic Versioning (SemVer) using the format MAJOR.MINOR.PATCH. The current release is 0.2.0, reflecting the project's pre-1.0 development status.

Each version component signals specific change types:

• MAJOR – Incremented for breaking changes to skill definitions or runtime contracts that would require consumer updates
• MINOR – Incremented for backward-compatible feature additions, such as new skill rules or capabilities
• PATCH – Incremented for bug fixes, documentation updates, or internal refactors that preserve the public contract

Centralized Version Management in package.json

The root package.json serves as the canonical definition of the current version. According to the source code, line 3 contains "version": "0.2.0", making this file the authoritative source for release numbering.

Because the repository specifies "private": true in its package.json, the package is not published to npm. Consequently, the version string functions primarily for internal runtime compatibility checks and change tracking rather than public package distribution. Tools and dependent systems read this version to verify they are interfacing with a compatible iteration of the skills framework.

Manual Propagation to Runtime Manifests

The versioning strategy for i-have-adhd requires manual duplication of the version string from package.json into every supported runtime manifest. This explicit propagation ensures that Claude, Codex, Gemini, Kimi, Qwen, and OpenCode environments all report identical version metadata.

Supported Runtime Manifests

The version 0.2.0 appears in the following files:

• .claude-plugin/plugin.json – Contains "version": "0.2.0" at lines 3-4 for the Claude runtime
• .codex-plugin/plugin.json – Contains "version": "0.2.0" at lines 3-4 for the Codex runtime
• kimi.plugin.json – Contains "version": "0.2.0" at lines 3-4 for the Kimi runtime
• gemini-extension.json – Contains "version": "0.2.0" at lines 3-4 for the Gemini runtime
• qwen-extension.json – Contains "version": "0.2.0" at lines 3-4 for the Qwen runtime
• plugin.json (OpenCode) – Contains "version": "0.2.0" at lines 3-4 for the OpenCode runtime

This manual approach guarantees that each AI runtime receives the exact version intended for its manifest format without automated transformations that might introduce drift.

Version Bump Workflows

When preparing a release, maintainers update the version in package.json first, then replicate that exact string across all six manifest files. This two-step process prevents partial updates and ensures atomic version changes across the entire repository.

For a typical patch release (0.2.0 → 0.2.1), the maintainer would modify the version field in package.json and then apply identical changes to .claude-plugin/plugin.json, .codex-plugin/plugin.json, kimi.plugin.json, gemini-extension.json, qwen-extension.json, and plugin.json.

Automating Version Updates

While the strategy relies on manual propagation, you can automate the synchronization using shell scripts or Node.js utilities.

To read the current version programmatically:

import { readFileSync } from 'fs';
const pkg = JSON.parse(readFileSync('package.json', 'utf8'));
console.log(`i-have-adhd version: ${pkg.version}`);

To update all manifests simultaneously:

NEW_VER="0.3.0"

# Update central package.json

jq ".version = \"$NEW_VER\"" package.json >tmp && mv tmp package.json

# Propagate to all runtime manifests

for f in .claude-plugin/plugin.json .codex-plugin/plugin.json \
         kimi.plugin.json gemini-extension.json qwen-extension.json plugin.json; do
  jq ".version = \"$NEW_VER\"" "$f" >tmp && mv tmp "$f"
done

Summary

• i-have-adhd uses SemVer (MAJOR.MINOR.PATCH) with the current version at 0.2.0
• The root package.json serves as the single source of truth for version numbering
• Version strings are manually propagated to seven runtime manifests including Claude, Codex, Gemini, Kimi, Qwen, and OpenCode
• The repository is marked private, meaning versions track internal compatibility rather than npm releases
• MAJOR bumps indicate breaking changes, MINOR adds features, and PATCH fixes bugs

Frequently Asked Questions

What versioning scheme does i-have-adhd use?

i-have-adhd uses Semantic Versioning (SemVer) following the MAJOR.MINOR.PATCH format. The current version is 0.2.0, indicating pre-1.0 development status where minor version increments may include breaking changes.

Where is the version number defined in i-have-adhd?

The version is defined in the root package.json at line 3. This value is then manually copied to six additional files: .claude-plugin/plugin.json, .codex-plugin/plugin.json, kimi.plugin.json, gemini-extension.json, qwen-extension.json, and plugin.json (OpenCode).

Why does i-have-adhd use manual propagation instead of automated scripts?

The project uses manual propagation to ensure explicit control over version consistency across diverse runtime formats. This approach prevents automated build processes from introducing unintended version drift between the core package and specific AI runtime manifests.

Is i-have-adhd published to the npm registry?

No. The package.json contains "private": true, which prevents accidental publication. The versioning strategy supports internal runtime compatibility checks and change tracking rather than public package distribution.

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