create-universal-ai-context 2.4.0 → 2.6.0-final

package/templates/base/standards/COMPATIBILITY.md

@@ -1,219 +1,219 @@
-# Compatibility Guide
-
-Version compatibility information for Claude Context Engineering.
-
-## Template Versions
-
-### Current Version: 1.0.0
-
-**Release Date:** {{DATE}}
-
-**Supported Claude Code Versions:** All versions with 200k context window
-
-**Node.js Requirement:** 18.x or higher
-
-## Version History
-
-| Version | Release | Status | Notes |
-|---------|---------|--------|-------|
-| 1.0.0 | {{DATE}} | Current | Initial release |
-
-## Semantic Versioning
-
-This project follows [Semantic Versioning](https://semver.org/):
-
-- **MAJOR** (1.x.x → 2.x.x): Breaking changes
-- **MINOR** (1.0.x → 1.1.x): New features, backward compatible
-- **PATCH** (1.0.0 → 1.0.1): Bug fixes, backward compatible
-
-## Breaking Changes
-
-### What Constitutes a Breaking Change
-
-- Schema format changes requiring migration
-- Removed or renamed configuration options
-- Changed directory structure requirements
-- Modified CLI command syntax
-- Removed agents, commands, or workflows
-
-### How Breaking Changes Are Handled
-
-1. **Announced** in CHANGELOG and release notes
-2. **Documented** with migration guide
-3. **Deprecated** features have 2 minor versions notice
-4. **Migration scripts** provided when possible
-
-## Extension Compatibility
-
-### Specifying Compatibility
-
-In your extension `manifest.json`:
-
-```json
-{
-  "claude_context_version": "^1.0.0"
-}
-```
-
-### Version Range Examples
-
-| Range | Meaning | Matches |
-|-------|---------|---------|
-| `1.0.0` | Exact version | 1.0.0 only |
-| `^1.0.0` | Compatible with 1.x.x | 1.0.0, 1.1.0, 1.2.3 |
-| `~1.0.0` | Patch updates only | 1.0.0, 1.0.1, 1.0.2 |
-| `>=1.0.0 <2.0.0` | Range | 1.x.x |
-| `*` | Any version | All (not recommended) |
-
-### Recommended Practice
-
-Use caret (`^`) for most extensions:
-```json
-{
-  "claude_context_version": "^1.0.0"
-}
-```
-
-This allows patch and minor updates while preventing breaking changes.
-
-## Schema Compatibility
-
-### Schema Versioning
-
-Schemas include version in their `$id`:
-```json
-{
-  "$id": "https://claude-context.dev/schemas/settings-v1.json"
-}
-```
-
-### Schema Changes
-
-| Change Type | Version Impact | Migration |
-|-------------|----------------|-----------|
-| Add optional field | None | Automatic |
-| Add required field | Minor bump | Defaults provided |
-| Remove field | Major bump | Migration required |
-| Change field type | Major bump | Migration required |
-| Rename field | Major bump | Migration required |
-
-## Configuration Compatibility
-
-### Adding New Settings
-
-New settings always have defaults:
-```json
-{
-  "new_feature": {
-    "enabled": false  // Default: opt-in
-  }
-}
-```
-
-### Deprecating Settings
-
-Deprecated settings:
-1. Continue to work for 2 minor versions
-2. Log deprecation warning
-3. Document replacement in CHANGELOG
-4. Remove in next major version
-
-Example deprecation notice:
-```json
-{
-  "old_setting": "DEPRECATED: Use new_setting instead"
-}
-```
-
-## CLI Compatibility
-
-### Command Stability
-
-| Stability | Description | Change Policy |
-|-----------|-------------|---------------|
-| Stable | Production ready | No breaking changes in minor versions |
-| Beta | Feature complete | May change in minor versions |
-| Alpha | Experimental | May change in any version |
-
-### Current Command Status
-
-| Command | Stability |
-|---------|-----------|
-| `init` | Stable |
-| `validate` | Stable |
-| `diagnose` | Stable |
-| `config` | Stable |
-
-## Migration Guides
-
-### Migrating Between Versions
-
-When upgrading, check:
-1. CHANGELOG for breaking changes
-2. Migration guide (if major version)
-3. Run `npx claude-context validate` after upgrade
-
-### Migration Scripts
-
-For major versions, migration scripts are provided:
-```bash
-npx claude-context migrate --from 1.x --to 2.x
-```
-
-## Testing Compatibility
-
-### Before Upgrading
-
-1. Review CHANGELOG for your current → target version
-2. Check extension compatibility
-3. Run validation on current version
-4. Backup `.ai-context/` directory
-5. Upgrade and re-validate
-
-### Extension Testing Matrix
-
-Test your extension against:
-- Current stable version
-- Latest minor version of each major
-- Next release candidate (optional)
-
-## Reporting Issues
-
-### Compatibility Issue Template
-
-When reporting compatibility issues, include:
-- Template version
-- Extension version (if applicable)
-- Node.js version
-- Operating system
-- Error message or unexpected behavior
-- Steps to reproduce
-
-### Where to Report
-
-- Template issues: [GitHub Issues]({{REPO_URL}}/issues)
-- Extension issues: Extension's repository
-- Security issues: security@claude-context.dev (example)
-
-## Support Policy
-
-### Version Support Duration
-
-| Version Type | Support Duration |
-|--------------|------------------|
-| Current major | Full support |
-| Previous major | Security fixes for 12 months |
-| Older versions | Community support only |
-
-### End of Life (EOL)
-
-EOL versions:
-- No longer receive updates
-- May have known issues
-- Should upgrade to supported version
-
-## Related
-
-- [Extension Guidelines](./EXTENSION_GUIDELINES.md)
-- [Quality Checklist](./QUALITY_CHECKLIST.md)
-- [CHANGELOG](../../CHANGELOG.md)
+# Compatibility Guide
+
+Version compatibility information for Claude Context Engineering.
+
+## Template Versions
+
+### Current Version: 1.0.0
+
+**Release Date:** {{DATE}}
+
+**Supported Claude Code Versions:** All versions with 200k context window
+
+**Node.js Requirement:** 18.x or higher
+
+## Version History
+
+| Version | Release | Status | Notes |
+|---------|---------|--------|-------|
+| 1.0.0 | {{DATE}} | Current | Initial release |
+
+## Semantic Versioning
+
+This project follows [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** (1.x.x → 2.x.x): Breaking changes
+- **MINOR** (1.0.x → 1.1.x): New features, backward compatible
+- **PATCH** (1.0.0 → 1.0.1): Bug fixes, backward compatible
+
+## Breaking Changes
+
+### What Constitutes a Breaking Change
+
+- Schema format changes requiring migration
+- Removed or renamed configuration options
+- Changed directory structure requirements
+- Modified CLI command syntax
+- Removed agents, commands, or workflows
+
+### How Breaking Changes Are Handled
+
+1. **Announced** in CHANGELOG and release notes
+2. **Documented** with migration guide
+3. **Deprecated** features have 2 minor versions notice
+4. **Migration scripts** provided when possible
+
+## Extension Compatibility
+
+### Specifying Compatibility
+
+In your extension `manifest.json`:
+
+```json
+{
+  "claude_context_version": "^1.0.0"
+}
+```
+
+### Version Range Examples
+
+| Range | Meaning | Matches |
+|-------|---------|---------|
+| `1.0.0` | Exact version | 1.0.0 only |
+| `^1.0.0` | Compatible with 1.x.x | 1.0.0, 1.1.0, 1.2.3 |
+| `~1.0.0` | Patch updates only | 1.0.0, 1.0.1, 1.0.2 |
+| `>=1.0.0 <2.0.0` | Range | 1.x.x |
+| `*` | Any version | All (not recommended) |
+
+### Recommended Practice
+
+Use caret (`^`) for most extensions:
+```json
+{
+  "claude_context_version": "^1.0.0"
+}
+```
+
+This allows patch and minor updates while preventing breaking changes.
+
+## Schema Compatibility
+
+### Schema Versioning
+
+Schemas include version in their `$id`:
+```json
+{
+  "$id": "https://claude-context.dev/schemas/settings-v1.json"
+}
+```
+
+### Schema Changes
+
+| Change Type | Version Impact | Migration |
+|-------------|----------------|-----------|
+| Add optional field | None | Automatic |
+| Add required field | Minor bump | Defaults provided |
+| Remove field | Major bump | Migration required |
+| Change field type | Major bump | Migration required |
+| Rename field | Major bump | Migration required |
+
+## Configuration Compatibility
+
+### Adding New Settings
+
+New settings always have defaults:
+```json
+{
+  "new_feature": {
+    "enabled": false  // Default: opt-in
+  }
+}
+```
+
+### Deprecating Settings
+
+Deprecated settings:
+1. Continue to work for 2 minor versions
+2. Log deprecation warning
+3. Document replacement in CHANGELOG
+4. Remove in next major version
+
+Example deprecation notice:
+```json
+{
+  "old_setting": "DEPRECATED: Use new_setting instead"
+}
+```
+
+## CLI Compatibility
+
+### Command Stability
+
+| Stability | Description | Change Policy |
+|-----------|-------------|---------------|
+| Stable | Production ready | No breaking changes in minor versions |
+| Beta | Feature complete | May change in minor versions |
+| Alpha | Experimental | May change in any version |
+
+### Current Command Status
+
+| Command | Stability |
+|---------|-----------|
+| `init` | Stable |
+| `validate` | Stable |
+| `diagnose` | Stable |
+| `config` | Stable |
+
+## Migration Guides
+
+### Migrating Between Versions
+
+When upgrading, check:
+1. CHANGELOG for breaking changes
+2. Migration guide (if major version)
+3. Run `npx claude-context validate` after upgrade
+
+### Migration Scripts
+
+For major versions, migration scripts are provided:
+```bash
+npx claude-context migrate --from 1.x --to 2.x
+```
+
+## Testing Compatibility
+
+### Before Upgrading
+
+1. Review CHANGELOG for your current → target version
+2. Check extension compatibility
+3. Run validation on current version
+4. Backup `.ai-context/` directory
+5. Upgrade and re-validate
+
+### Extension Testing Matrix
+
+Test your extension against:
+- Current stable version
+- Latest minor version of each major
+- Next release candidate (optional)
+
+## Reporting Issues
+
+### Compatibility Issue Template
+
+When reporting compatibility issues, include:
+- Template version
+- Extension version (if applicable)
+- Node.js version
+- Operating system
+- Error message or unexpected behavior
+- Steps to reproduce
+
+### Where to Report
+
+- Template issues: [GitHub Issues]({{REPO_URL}}/issues)
+- Extension issues: Extension's repository
+- Security issues: security@claude-context.dev (example)
+
+## Support Policy
+
+### Version Support Duration
+
+| Version Type | Support Duration |
+|--------------|------------------|
+| Current major | Full support |
+| Previous major | Security fixes for 12 months |
+| Older versions | Community support only |
+
+### End of Life (EOL)
+
+EOL versions:
+- No longer receive updates
+- May have known issues
+- Should upgrade to supported version
+
+## Related
+
+- [Extension Guidelines](./EXTENSION_GUIDELINES.md)
+- [Quality Checklist](./QUALITY_CHECKLIST.md)
+- [CHANGELOG](../../CHANGELOG.md)