title: Version Policy last_updated: 2026-03-21

Version Policy

How this repository handles tool version changes for Claude Code, Codex CLI, and other covered tools.

Principles

1. Concepts are stable; implementations change. Tool-agnostic concepts in concepts.md should rarely need updating. Tool-specific files absorb the churn.
2. Version-pin everything. Every tool-specific example includes the version it was tested with.
3. Stale is worse than missing. Outdated examples that silently fail erode trust faster than gaps in coverage.
4. Update the layer, not the whole module. When Claude Code ships a new feature, update claude-code.md — don't rewrite concepts.md.

Version Tracking

Frontmatter

Every tool-specific file includes:

tested_with:
  claude-code: "1.0.x"
  codex-cli: "0.2.x"

Use semver ranges:

• "1.0.x" — tested with any 1.0.x patch release
• "1.0.3" — tested with exactly this version (use when a specific version matters)

Staleness Threshold

Content is flagged when tested_with is 2+ minor versions behind the current release.

Example: If Claude Code is at 1.3.0 and a file says tested_with: "1.0.x", it gets flagged.

When a New Version Ships

Minor Releases (e.g., 1.1.0 to 1.2.0)

1. File a tool-update issue listing affected modules
2. Triage: which files need changes vs. which are unaffected?
3. Update affected tool-specific files
4. Bump tested_with and last_updated
5. If a pattern changes: document in CHANGELOG.md under "Pattern Evolution"

Major Releases (e.g., 1.x to 2.x)

1. Create a tracking issue for the full migration
2. Audit all tool-specific files for breaking changes
3. Update files in priority order: Foundation modules first, then Intermediate, then Advanced
4. If concepts change (rare): update concepts.md with clear before/after explanation
5. Add migration notes to the relevant module

New Tool Added

1. RFC discussion in GitHub Discussions
2. Create {tool}.md files in each relevant module
3. Add to cheatsheets
4. Add to GLOSSARY.md
5. Update README.md curriculum tables

Supported Tools

End-of-Support

If a covered tool is deprecated or discontinued:

1. Add a notice to the top of each affected file
2. Keep content for 6 months for historical reference
3. Archive (move to an archive/ directory) after 6 months