Version Management

Version Management

How ai-coding-ok manages versions, how version markers work, and the complete upgrade path history.

---

Versioning scheme

ai-coding-ok follows Semantic Versioning:

vMAJOR.MINOR.PATCH

v3  .  1  .  0
│    │     │
│    │     └── PATCH: backward-compatible bug fixes
│    └──────── MINOR: backward-compatible new features
└───────────── MAJOR: incompatible structural changes

What triggers each level

Level	Examples
MAJOR	Plugin packaging (v3.0.0), template language split, new file structure
MINOR	New platform support (v2.1.0 Cursor), new defense layer (v3.1.0 hooks), new auto-load mechanism (v2.2.0 CLAUDE.md)
PATCH	Bug fixes in template content, wording improvements (v3.0.1 Act enforcement)

---

Version markers

Every installed file carries a version marker on line 1:

Markdown files

<!-- ai-coding-ok: v3.1.0 -->

YAML files

# ai-coding-ok: v3.1.0

JSON files

// ai-coding-ok: v3.1.0

Files with markers

File	Marker format
AGENTS.md	<!-- ai-coding-ok: vX.Y.Z -->
CLAUDE.md	<!-- ai-coding-ok: vX.Y.Z -->
.github/copilot-instructions.md	<!-- ai-coding-ok: vX.Y.Z -->
.github/agent/system-prompt.md	<!-- ai-coding-ok: vX.Y.Z -->
.github/agent/coding-standards.md	<!-- ai-coding-ok: vX.Y.Z -->
.github/agent/workflows.md	<!-- ai-coding-ok: vX.Y.Z -->
.github/agent/prompt-templates.md	<!-- ai-coding-ok: vX.Y.Z -->
.github/agent/memory/project-memory.md	<!-- ai-coding-ok: vX.Y.Z -->
.github/agent/memory/decisions-log.md	<!-- ai-coding-ok: vX.Y.Z -->
.github/agent/memory/task-history.md	<!-- ai-coding-ok: vX.Y.Z -->
.github/project-metadata.yml	# ai-coding-ok: vX.Y.Z
.claude/settings.local.json	// ai-coding-ok: v3.1.0

---

How markers are used

During install (Mode A)

All markers are set to the latest version:

<!-- ai-coding-ok: v3.1.0 -->

During upgrade (Mode D)

1. Claude reads the marker from each file to detect the installed version
2. Compares against the latest template version
3. Determines the upgrade path (v2.2.0 → v3.0.0 → v3.0.1 → v3.1.0)
4. After applying changes, bumps all markers to the latest version

During verification

verify.sh checks that all markers are consistent (same version across all files).

---

Complete upgrade path history

graph LR
    v1.0[v1.0<br/>Initial release<br/>2025] --> v2.0[v2.0<br/>PDCA mandate<br/>Mode A/B/C/D<br/>Version markers]
    v2.0 --> v2.1[v2.1.0<br/>Cursor + OpenCode<br/>support]
    v2.1 --> v2.2[v2.2.0<br/>CLAUDE.md shim<br/>Skill desc rewrite]
    v2.2 --> v3.0[v3.0.0<br/>Plugin packaging<br/>Bilingual templates]
    v3.0 --> v3.0.1[v3.0.1<br/>Act enforcement<br/>in output format]
    v3.0.1 --> v3.1[v3.1.0<br/>Five-layer defense<br/>Claude Code hooks]

Loading

v1.0 → v2.0

Change	Type
AGENTS.md gains PDCA mandatory instruction block	Added
copilot-instructions.md gains PDCA enforcement block	Added
All template files get version markers	Added
SKILL.md gains Mode A/B/C/D and Upgrade Playbook	Added
workflows.md Step 5 annotated "⚠️ Do not skip"	Modified
copilot-instructions.md footer section removed	Removed

v2.0 → v2.1.0

Change	Type
Cursor support (.cursor/rules/ai-coding-ok.mdc)	Added
OpenCode support (--opencode install mode)	Added
install.sh/interactive menu expanded to 5 options	Modified
SKILL.md compatibility frontmatter updated	Modified

v2.1.0 → v2.2.0

Change	Type
CLAUDE.md auto-load shim (@AGENTS.md import)	Added
SKILL.md description rewritten (command-first)	Modified
install.sh conflict check adds CLAUDE.md	Modified

v2.2.0 → v3.0.0

Change	Type
Plugin packaging (.claude-plugin/plugin.json)	Added
Bilingual templates (templates/en/, templates/zh/)	Added
English README split from Chinese	Modified
install.sh --lang en|zh flag	Added
Canonical SKILL.md in skills/ai-coding-ok/	Added

v3.0.0 → v3.0.1

Change	Type
copilot-instructions.md mandatory Memory Updates section	Modified
system-prompt.md Act phase annotated "⚠️ must not skip"	Modified
Output format enforcement (cannot omit sections)	Modified

v3.0.1 → v3.1.0

Change	Type
Five-layer defense system	Added
Claude Code hooks (SessionStart/UserPromptSubmit/PreToolUse/Stop)	Added
CLAUDE.md STOP instruction	Modified
AGENTS.md Plan phase 3→7 steps	Modified
Install-time auto-configuration (Step 5.5 + 5.6)	Added
{{SOURCE_DIR_PATTERN}} placeholder	Added

---

How upgrades preserve project customizations

During an upgrade, Claude:

1. Reads the current file from the user's project
2. Reads the template for the target version
3. Diffs at section level (by ## / ### headings)
4. Identifies three change types:
   • Added sections: Insert into the project file (fill placeholders from project context)
   • Removed sections: Ask user before deleting
   • Modified sections: Replace the old section with the new one
5. Preserves project-specific content (project name, tech stack, architecture, custom ADRs, custom constraints)
6. Bumps the version marker

---

Checking your version

# Check the version of your installation
head -1 AGENTS.md
# → <!-- ai-coding-ok: v3.1.0 -->

# Check all file versions for consistency
grep -r "ai-coding-ok: v" AGENTS.md CLAUDE.md .github/

---

Next steps

• Upgrade ai-coding-ok — how to perform an upgrade
• Changelog — full version history with details
• File Structure — which files have version markers