create-universal-ai-context 2.0.0

package/templates/base/standards/COMPATIBILITY.md

@@ -0,0 +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)

package/templates/base/standards/EXTENSION_GUIDELINES.md

@@ -0,0 +1,280 @@
+# Extension Publishing Guidelines
+
+Standards and requirements for publishing Claude Context Engineering extensions.
+
+## Overview
+
+Extensions enhance the Context Engineering template with additional agents, commands, workflows, and integrations. This guide covers requirements for publishing extensions to the community registry.
+
+## Extension Types
+
+| Type | Description | Directory |
+|------|-------------|-----------|
+| **Agent** | Specialized AI assistant | `.ai-context/extensions/[name]/agents/` |
+| **Command** | Custom slash command | `.ai-context/extensions/[name]/commands/` |
+| **Workflow** | Domain workflow documentation | `.ai-context/extensions/[name]/workflows/` |
+| **Adapter** | Framework-specific configuration | `.ai-context/extensions/[name]/adapters/` |
+| **Integration** | Third-party service integration | `.ai-context/extensions/[name]/integrations/` |
+
+## Extension Structure
+
+```
+my-extension/
+├── manifest.json        # Required: Extension metadata
+├── README.md            # Required: Documentation
+├── LICENSE              # Required: License file
+├── CHANGELOG.md         # Recommended: Version history
+├── agents/              # Agent definitions
+│   └── my-agent.md
+├── commands/            # Command definitions
+│   └── my-command.md
+├── workflows/           # Workflow documentation
+│   └── my-workflow.md
+├── schemas/             # Custom schemas
+│   └── my-schema.json
+└── tests/               # Extension tests
+    └── validate.js
+```
+
+## Manifest Requirements
+
+Every extension must include a `manifest.json`:
+
+```json
+{
+  "$schema": "https://claude-context.dev/schemas/extension-manifest-v1.json",
+  "name": "my-extension",
+  "version": "1.0.0",
+  "displayName": "My Extension",
+  "description": "Brief description of what this extension provides",
+  "author": {
+    "name": "Author Name",
+    "email": "author@example.com",
+    "url": "https://github.com/author"
+  },
+  "license": "MIT",
+  "repository": "https://github.com/author/my-extension",
+  "keywords": ["keyword1", "keyword2"],
+  "claude_context_version": "^1.0.0",
+  "contents": {
+    "agents": ["my-agent"],
+    "commands": ["my-command"],
+    "workflows": ["my-workflow"]
+  },
+  "dependencies": {},
+  "peerDependencies": {}
+}
+```
+
+### Required Fields
+
+| Field | Description |
+|-------|-------------|
+| `name` | Unique identifier (lowercase, hyphens only) |
+| `version` | Semantic version (MAJOR.MINOR.PATCH) |
+| `displayName` | Human-readable name |
+| `description` | Brief description (max 200 chars) |
+| `author` | Author information |
+| `license` | SPDX license identifier |
+| `claude_context_version` | Compatible template version |
+| `contents` | What the extension provides |
+
+## Documentation Requirements
+
+### README.md Must Include
+
+1. **Title and Description** - What the extension does
+2. **Installation** - How to install
+3. **Usage** - How to use each component
+4. **Configuration** - Any required configuration
+5. **Examples** - Working examples
+6. **Troubleshooting** - Common issues
+7. **License** - License information
+
+### Minimum README Template
+
+```markdown
+# Extension Name
+
+Brief description.
+
+## Installation
+
+\`\`\`bash
+npx claude-context extension install extension-name
+\`\`\`
+
+## Usage
+
+### Agent: @agent-name
+
+Description and usage.
+
+### Command: /command-name
+
+Description and usage.
+
+## Configuration
+
+Required configuration steps.
+
+## Examples
+
+Working examples.
+
+## License
+
+MIT License
+```
+
+## Code Standards
+
+### Agents
+
+- Follow frontmatter schema
+- Include all required metadata
+- Document capabilities clearly
+- Provide usage examples
+- Specify context budget
+
+### Commands
+
+- Follow frontmatter schema
+- Document all subcommands
+- Include input/output examples
+- Specify prerequisites
+- Document error handling
+
+### Workflows
+
+- Follow workflow schema
+- Include file:line references
+- Document integration points
+- Keep under 5000 tokens
+
+## Quality Requirements
+
+Before submitting, ensure:
+
+- [ ] All files pass schema validation
+- [ ] README is complete and accurate
+- [ ] All examples work correctly
+- [ ] No placeholder text remains
+- [ ] License file included
+- [ ] CHANGELOG documents changes
+- [ ] Tests pass (if included)
+- [ ] Context budget is documented
+- [ ] No sensitive data included
+
+## Versioning
+
+Follow Semantic Versioning (SemVer):
+
+- **MAJOR**: Breaking changes
+- **MINOR**: New features, backward compatible
+- **PATCH**: Bug fixes, backward compatible
+
+### Version Compatibility
+
+Specify `claude_context_version` using semver ranges:
+
+```json
+{
+  "claude_context_version": "^1.0.0"  // 1.x.x
+}
+```
+
+## Submission Process
+
+### 1. Prepare Extension
+
+- Complete all required files
+- Run quality checklist
+- Test with target template version
+
+### 2. Create Repository
+
+- Host on GitHub (public)
+- Include all required files
+- Tag release with version
+
+### 3. Submit for Review
+
+Open an issue using the Extension Submission template:
+- Provide repository URL
+- Describe the extension
+- List tested versions
+
+### 4. Review Process
+
+Maintainers will:
+1. Validate manifest and structure
+2. Review documentation quality
+3. Test installation and functionality
+4. Check for security issues
+5. Verify license compatibility
+
+### 5. Publication
+
+Once approved:
+- Added to community registry
+- Listed in extension search
+- Announced in release notes
+
+## Maintenance
+
+### Ongoing Requirements
+
+- Respond to issues within 14 days
+- Update for breaking template changes
+- Maintain documentation accuracy
+- Follow security advisories
+
+### Deprecation
+
+To deprecate an extension:
+1. Add `"deprecated": true` to manifest
+2. Document migration path in README
+3. Keep available for 6 months minimum
+
+## Security Guidelines
+
+### Do NOT Include
+
+- API keys or secrets
+- Personal data
+- Executable binaries
+- Minified/obfuscated code
+- External network calls without disclosure
+
+### Security Review
+
+Extensions with these features require extra review:
+- External API integrations
+- File system operations
+- Code execution
+- Configuration of sensitive settings
+
+## License Requirements
+
+Acceptable licenses (SPDX identifiers):
+- MIT
+- Apache-2.0
+- BSD-2-Clause
+- BSD-3-Clause
+- ISC
+- MPL-2.0
+
+Other licenses reviewed case-by-case.
+
+## Support
+
+- GitHub Issues for bug reports
+- Discussions for questions
+- Security issues: security@claude-context.dev (example)
+
+## Related
+
+- [Quality Checklist](./QUALITY_CHECKLIST.md)
+- [Compatibility Guide](./COMPATIBILITY.md)
+- [Extension Manifest Schema](../schemas/manifest.schema.json)

package/templates/base/standards/QUALITY_CHECKLIST.md

@@ -0,0 +1,211 @@
+# Quality Checklist
+
+Use this checklist to ensure your Claude Context Engineering implementation meets quality standards.
+
+## For Projects Using the Template
+
+### Initial Setup
+
+- [ ] All `{{PLACEHOLDER}}` values replaced with project-specific content
+- [ ] AI_CONTEXT.md customized for your codebase
+- [ ] Tech stack correctly identified
+- [ ] File paths in documentation are accurate
+- [ ] Line numbers in code references are current
+
+### Documentation Quality
+
+- [ ] INDEX files reflect actual directory structure
+- [ ] Workflow documents describe real system behavior
+- [ ] Architecture snapshot matches current architecture
+- [ ] Known gotchas are documented and current
+- [ ] Code-to-workflow map is accurate
+
+### Context Budget
+
+- [ ] Total documentation under 40% of context budget (~80K tokens)
+- [ ] No single file exceeds 10K tokens
+- [ ] Indexes are concise pointers, not content dumps
+- [ ] Rarely-used content in separate files
+
+### Validation
+
+- [ ] `npx claude-context validate --all` passes
+- [ ] All internal links resolve
+- [ ] JSON files pass schema validation
+- [ ] No broken file references
+
+---
+
+## For Extension Authors
+
+### Structure
+
+- [ ] `manifest.json` present and valid
+- [ ] `README.md` complete with all sections
+- [ ] `LICENSE` file included
+- [ ] `CHANGELOG.md` documents version history
+- [ ] Directory structure follows convention
+
+### Manifest
+
+- [ ] `name` is lowercase with hyphens only
+- [ ] `version` follows semver (MAJOR.MINOR.PATCH)
+- [ ] `description` is under 200 characters
+- [ ] `author` information complete
+- [ ] `license` is valid SPDX identifier
+- [ ] `claude_context_version` specifies compatibility
+- [ ] `contents` lists all provided components
+
+### Documentation
+
+- [ ] Installation instructions clear and tested
+- [ ] All components documented with examples
+- [ ] Configuration requirements specified
+- [ ] Troubleshooting section included
+- [ ] No placeholder text remains
+
+### Code Quality
+
+- [ ] Agents follow frontmatter schema
+- [ ] Commands follow frontmatter schema
+- [ ] Workflows follow workflow schema
+- [ ] All required metadata present
+- [ ] Context budgets documented
+
+### Testing
+
+- [ ] Installs without errors
+- [ ] All examples work as documented
+- [ ] No conflicts with base template
+- [ ] Tested with specified template version
+
+### Security
+
+- [ ] No hardcoded secrets or API keys
+- [ ] No personal data included
+- [ ] External calls documented
+- [ ] File operations are safe
+- [ ] License is compatible
+
+---
+
+## For Template Contributors
+
+### Code Changes
+
+- [ ] Follows existing code style
+- [ ] Includes appropriate tests
+- [ ] Documentation updated
+- [ ] CHANGELOG entry added
+- [ ] Breaking changes documented
+
+### Schema Changes
+
+- [ ] Schema version incremented
+- [ ] Migration path documented
+- [ ] Backward compatibility considered
+- [ ] Examples updated
+
+### Documentation Changes
+
+- [ ] Links verified
+- [ ] Line numbers updated
+- [ ] Consistent formatting
+- [ ] Grammar and spelling checked
+
+### Pull Request
+
+- [ ] Clear description of changes
+- [ ] Issue reference (if applicable)
+- [ ] Tests passing
+- [ ] Documentation updated
+- [ ] CHANGELOG updated
+
+---
+
+## Validation Commands
+
+Run these commands to validate your implementation:
+
+```bash
+# Full validation suite
+npx claude-context validate --all
+
+# Specific validations
+npx claude-context validate --schema      # JSON schemas
+npx claude-context validate --links       # Internal links
+npx claude-context validate --placeholders # Unreplaced placeholders
+npx claude-context validate --structure   # Directory structure
+npx claude-context validate --lines       # Line number accuracy
+
+# Diagnostics
+npx claude-context diagnose               # System health check
+npx claude-context diagnose --fix         # Auto-fix issues
+```
+
+## Quality Levels
+
+### Level 1: Minimal (Required)
+
+- All placeholders replaced
+- Basic documentation present
+- Validation passes
+- No broken links
+
+### Level 2: Standard (Recommended)
+
+- Complete documentation
+- Accurate line numbers (>60%)
+- Context budget under 40%
+- Regular validation in CI
+
+### Level 3: Exemplary (Best Practice)
+
+- Comprehensive documentation
+- Line accuracy >80%
+- Context budget under 30%
+- Automated documentation updates
+- Full CI/CD integration
+
+## Common Issues
+
+### Placeholder Not Replaced
+
+**Symptom:** `{{PLACEHOLDER}}` appears in output
+
+**Fix:** Search for all `{{` patterns and replace:
+```bash
+grep -r "{{" .ai-context/
+```
+
+### Broken Internal Link
+
+**Symptom:** Link validation fails
+
+**Fix:** Update link path or create missing file:
+```bash
+npx claude-context validate --links --verbose
+```
+
+### Context Budget Exceeded
+
+**Symptom:** Documentation >40% of budget
+
+**Fix:**
+1. Split large files
+2. Move details to separate files
+3. Compact verbose sections
+
+### Line Number Drift
+
+**Symptom:** Code references point to wrong lines
+
+**Fix:**
+```bash
+npx claude-context diagnose --fix
+```
+
+## Related
+
+- [Extension Guidelines](./EXTENSION_GUIDELINES.md)
+- [Compatibility Guide](./COMPATIBILITY.md)