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

> Discover the i-have-adhd versioning strategy, a clear guide to Semantic Versioning (SemVer). Learn how we manage updates across multiple plugin manifests efficiently.

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

---

**i-have-adhd follows Semantic Versioning (SemVer) by defining version 0.2.0 centrally in [`package.json`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json)** – Contains `"version": "0.2.0"` at lines 3-4 for the Claude runtime
- **[`.codex-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.codex-plugin/plugin.json)** – Contains `"version": "0.2.0"` at lines 3-4 for the Codex runtime
- **[`kimi.plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/kimi.plugin.json)** – Contains `"version": "0.2.0"` at lines 3-4 for the Kimi runtime
- **[`gemini-extension.json`](https://github.com/ayghri/i-have-adhd/blob/main/gemini-extension.json)** – Contains `"version": "0.2.0"` at lines 3-4 for the Gemini runtime
- **[`qwen-extension.json`](https://github.com/ayghri/i-have-adhd/blob/main/qwen-extension.json)** – Contains `"version": "0.2.0"` at lines 3-4 for the Qwen runtime
- **[`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/package.json) and then apply identical changes to [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json), [`.codex-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.codex-plugin/plugin.json), [`kimi.plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/kimi.plugin.json), [`gemini-extension.json`](https://github.com/ayghri/i-have-adhd/blob/main/gemini-extension.json), [`qwen-extension.json`](https://github.com/ayghri/i-have-adhd/blob/main/qwen-extension.json), and [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/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:

```javascript
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:

```bash
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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/package.json)** at line 3. This value is then manually copied to six additional files: [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json), [`.codex-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.codex-plugin/plugin.json), [`kimi.plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/kimi.plugin.json), [`gemini-extension.json`](https://github.com/ayghri/i-have-adhd/blob/main/gemini-extension.json), [`qwen-extension.json`](https://github.com/ayghri/i-have-adhd/blob/main/qwen-extension.json), and [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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.