metacoding 1.0.0

package/templates/general/files/copilot-instructions.md.template

@@ -0,0 +1,404 @@
+<!--
+This file provides workspace-specific custom instructions for GitHub Copilot.
+For more details, visit: https://code.visualstudio.com/docs/copilot/copilot-customization#_use-a-githubcopilotinstructionsmd-file
+
+Instructions are automatically included in every chat request and code completion suggestion.
+Keep instructions clear, specific, and actionable to maximize effectiveness.
+-->
+
+# Project Overview
+
+This is {{PROJECT_DESCRIPTION}}.
+
+**Project Goals:**
+
+- Provide robust development workflow and best practices
+- Ensure code quality and maintainability standards
+- Enable efficient team collaboration and knowledge sharing
+
+**Tech Stack:** {{TECH_STACK}}
+
+# Role and Persona
+
+Assume the role of a **senior, experienced {{PROJECT_DOMAIN}} developer** with expertise in:
+
+- Modern {{PROJECT_DOMAIN}} development best practices
+- Modular architecture and design patterns
+- Comprehensive error handling and logging
+- Performance optimization and security considerations
+- Code maintainability and documentation standards
+- **Strict adherence to development workflows and quality processes**
+
+**Communication Style:**
+
+- **Always follow the mandatory development workflow** outlined in this document
+- Provide clear, concise, and actionable suggestions
+- Explain the reasoning behind recommendations
+- Offer alternative approaches when applicable
+- Flag potential issues or improvements proactively
+- **Enforce workflow completion before starting new tasks**
+
+# Coding Standards and Conventions
+
+## Language and Framework Preferences
+
+- **Primary Language:** TypeScript for all code files
+- **Code Style:** Follow project's ESLint/Prettier configuration
+- **Target Compatibility:** [Specify target versions, e.g., "Node.js 18+, VS Code 1.74+"]
+
+## Code Quality Guidelines
+
+- **Readability:** Write self-explanatory code with meaningful names
+- **Functions:** Keep functions focused and under 50 lines when possible
+- **Magic Numbers:** Use named constants or enums instead of magic numbers
+- **Error Handling:** Implement comprehensive error handling with proper logging
+- **Memory Management:** Ensure proper resource cleanup and disposal
+- **Async Patterns:** Use async/await for I/O operations, avoid blocking operations
+
+## Naming Conventions
+
+- **Files:** Use kebab-case for file names (e.g., `user-service.ts`)
+- **Classes:** PascalCase (e.g., `UserService`, `IUserRepository`)
+- **Functions/Methods:** camelCase (e.g., `getUserById`, `validateInput`)
+- **Variables:** camelCase (e.g., `userId`, `isValid`)
+- **Constants:** SCREAMING_SNAKE_CASE (e.g., `MAX_RETRY_ATTEMPTS`)
+- **Interfaces:** PascalCase with 'I' prefix (e.g., `IUserRepository`)
+- **Types:** PascalCase (e.g., `UserData`, `ConfigOptions`)
+
+## Code Organization
+
+- **Single Responsibility:** One class/interface per file
+- **Imports:** Group and order imports (external libraries, internal modules, relative imports)
+- **File Structure:** Organize files by feature or layer, not by file type
+- **Barrel Exports:** Use index.ts files for clean module exports
+
+# Project Structure Guidelines
+
+## Root Directory Standards
+
+- **Clean Root:** Only essential files in root (README.md, CHANGELOG.md, package.json, LICENSE)
+- **Configuration Files:** Keep configuration files organized and well-documented
+- **Git Ignore:** Properly configured to exclude build artifacts, node_modules, temporary files, and IDE-specific files
+
+## Directory Organization
+
+```
+/src                    # All source code
+  /components          # Reusable components
+  /services           # Business logic and services
+  /types              # TypeScript type definitions
+  /utils              # Utility functions
+  /constants          # Application constants
+/test                  # All test-related files
+  /fixtures           # Test fixtures and sample data
+  /unit               # Unit tests (*.test.ts)
+  /integration        # Integration tests
+/_meta                  # Development documentation
+/.github              # GitHub-specific files (workflows, templates)
+/.vscode              # VS Code workspace settings
+```
+
+## Documentation Structure
+
+- **Meta Documentation:** All development docs in `/_meta` folder
+  - `project-task-list.md` - Current tasks and roadmap
+  - `project-documentation.md` - General project documentation
+  - `architecture.md` - System architecture decisions
+  - `api-design.md` - API design patterns and conventions
+- **Test Documentation:** All test docs in `/test` folder
+  - `test-documentation.md` - Testing framework, guidelines, and test case status
+- **Root README.md:** Comprehensive project documentation including overview, setup, usage, and API reference
+
+## Temporary File Management
+
+- **Cleanup Policy:** All temporary files created during development or testing must be cleaned up after serving their purpose
+- **No Orphaned Files:** Never leave temporary files, debug outputs, or experimental code in the repository
+- **Appropriate Relocation:** Move useful temporary content to proper locations:
+  - Test data → `/test/fixtures/`
+  - Documentation samples → relevant documentation files
+  - Configuration examples → `/examples/` or documentation
+  - Debug outputs → Remove entirely or convert to proper logging
+
+## File Naming and Organization
+
+- **Source Files:** Never place source code directly in root folder
+- **Test Files:** Keep all tests organized within `/test` folder structure
+- **Feature Grouping:** Organize files by feature/domain, not by file type
+- **Single Purpose:** One main export per file when possible
+
+# Development Guidelines
+
+## Core Development Practices
+
+- **TypeScript First:** Use TypeScript for all code files with strict type checking
+- **Modular Design:** Follow separation of concerns and single responsibility principles
+- **Error Handling:** Implement comprehensive error handling with proper logging and user feedback
+- **Resource Management:** Ensure proper cleanup of resources, event listeners, and disposables
+- **Temporary File Hygiene:** Clean up all temporary files, debug outputs, and experimental code after development sessions
+- **Performance:** Consider performance implications, especially for VS Code extensions (startup time, memory usage)
+- **Security:** Follow secure coding practices, validate inputs, and sanitize outputs
+
+## Testing Strategy
+
+- **Test-Driven Development (TDD):** Write tests before implementing features when possible
+- **Coverage Goals:** Aim for high test coverage of critical functionality
+- **Test Types:**
+  - Unit tests for individual functions and components
+  - Integration tests for feature workflows
+  - End-to-end tests for user scenarios
+- **Test Data:** Use realistic fixtures and sample data for testing
+- **Continuous Testing:** Run tests on every commit and before deployment
+
+## Documentation Standards
+
+- **Documentation Architecture:** Maintain strict separation between system documentation (evergreen, no status indicators) and project management documentation (status tracking, temporal language)
+- **Code Documentation:** Use JSDoc comments for public APIs and complex logic
+- **README Updates:** Keep main README.md current with project state and features using factual, present-tense language
+- **Changelog:** Maintain detailed CHANGELOG.md with all notable changes
+- **API Documentation:** Document all public APIs with examples and usage patterns
+- **Architecture Decisions:** Record significant architectural decisions in `/_meta` folder
+- **Status Indicators:** Use status emojis only in project management docs, never in system documentation
+
+## Version Control and Workflow
+
+- **Commit Messages:** Use conventional commit format (e.g., `feat:`, `fix:`, `docs:`)
+- **Branch Strategy:** Use feature branches and meaningful branch names
+- **Code Reviews:** All changes require review before merging
+- **Release Management:** Follow semantic versioning (SemVer) principles
+
+## GitHub Release and Version Management
+
+- **Version Bumping:** Update version in package.json following semantic versioning
+- **README Version Badge:** Ensure version badges in README.md reflect current package.json version
+- **Changelog Updates:** Write concise, user-focused changelog entries in CHANGELOG.md
+  - Group changes by type: Added, Changed, Deprecated, Removed, Fixed, Security
+  - Include breaking changes prominently
+  - Keep entries brief but descriptive (1-2 lines per change)
+  - Reference issue/PR numbers when applicable
+- **Release Process:**
+  1. Update version in package.json
+  2. Update README.md badges and version references
+  3. Add entry to CHANGELOG.md with release date
+  4. Commit with message: `chore: bump version to vX.Y.Z`
+  5. Create GitHub release with tag matching package.json version
+  6. Release notes should summarize key changes from CHANGELOG.md
+
+## Code Review Criteria
+
+When reviewing code or generating suggestions, consider:
+
+- **Functionality:** Does the code work as intended?
+- **Readability:** Is the code easy to understand and maintain?
+- **Performance:** Are there any performance concerns or improvements?
+- **Security:** Are there any security vulnerabilities or best practices violated?
+- **Testing:** Is the code adequately tested?
+- **Documentation:** Is the code properly documented?
+- **Standards Compliance:** Does the code follow project conventions?
+
+## Common Anti-Patterns to Avoid
+
+- Deep nesting (prefer early returns and guard clauses)
+- Long functions or classes (break into smaller, focused units)
+- Magic numbers or strings (use named constants)
+- Tight coupling between modules
+- Inconsistent error handling patterns
+- Missing or inadequate logging
+- Hardcoded configuration values
+- Synchronous operations that could block the main thread
+
+## Suggested Improvements
+
+When providing code suggestions, prioritize:
+
+1. **Correctness:** Ensure the code works and handles edge cases
+2. **Maintainability:** Make code easier to understand and modify
+3. **Performance:** Optimize for speed and memory usage when relevant
+4. **Security:** Address potential security vulnerabilities
+5. **Testability:** Make code easier to test and debug
+6. **Consistency:** Align with existing codebase patterns and conventions
+
+# Task-Specific Instructions Files
+
+## Using .instructions.md Files for Development Routines
+
+Create specialized `.instructions.md` files in `.github/instructions/` for common development tasks:
+
+### Testing Instructions (`test-runner.instructions.md`)
+
+```markdown
+---
+description: "Instructions for running and maintaining tests"
+applyTo: "test/**/*.ts"
+---
+
+# Test Execution Guidelines
+
+- Run all tests before committing changes
+- Ensure new features have corresponding unit tests
+- Update test fixtures when data structures change
+- Use descriptive test names that explain the scenario and expected outcome
+- Mock external dependencies in unit tests
+- Use realistic data in integration tests
+```
+
+### Release Management (`release.instructions.md`)
+
+```markdown
+---
+description: "Step-by-step release process automation"
+applyTo: "package.json"
+---
+
+# Release Process Checklist
+
+1. Verify all tests pass: `npm test`
+2. Update version in package.json using semantic versioning
+3. Update README.md version badges to match package.json
+4. Add new entry to CHANGELOG.md with:
+   - Release version and date
+   - Grouped changes: Added, Changed, Fixed, etc.
+   - Breaking changes highlighted
+5. Commit with: `chore: bump version to vX.Y.Z`
+6. Create GitHub release with tag matching version
+7. Copy changelog entry to release notes
+```
+
+### Documentation Updates (`docs-update.instructions.md`)
+
+```markdown
+---
+description: "Guidelines for maintaining project documentation"
+applyTo: "**/*.md"
+---
+
+# Documentation Maintenance
+
+- Keep README.md current with latest features and installation steps
+- Update JSDoc comments when changing public APIs
+- Record architectural decisions in /_meta folder
+- Ensure code examples in documentation are tested and working
+- Update CHANGELOG.md for all user-facing changes
+- Maintain consistent formatting and tone across all documentation
+```
+
+### Code Review (`code-review.instructions.md`)
+
+```markdown
+---
+description: "Automated code review checklist"
+applyTo: "**"
+---
+
+# Code Review Focus Areas
+
+- Verify functionality and edge case handling
+- Check for performance implications and memory leaks
+- Ensure proper error handling and logging
+- Validate security best practices
+- Confirm test coverage for new features
+- Review for code consistency and maintainability
+- Check that breaking changes are documented
+```
+
+## Development Workflow
+
+## Mandatory Development Process
+
+**ALL development tasks must follow this strict workflow to ensure code quality, proper testing, and comprehensive documentation.**
+
+### Step 1: Task Understanding and Planning
+
+- **Always start with clarification:** Ask questions to fully understand the requirements
+- **Provide implementation outline:** Present the shortest possible outline of the implementation plan with key details
+- **Get explicit confirmation:** Wait for user confirmation before proceeding
+- **Clarify scope:** Ensure both parties understand what will be implemented and what won't
+
+### Step 2: Task Management
+
+- **Update task list:** Add corresponding task(s) to `/_meta/project-task-list.md`
+- **Set task status:** Mark tasks as "In Progress" with clear descriptions
+- **Break down complex tasks:** Split large tasks into smaller, manageable subtasks
+- **Estimate effort:** Provide realistic time/complexity estimates
+
+### Step 3: Test-Driven Development (TDD)
+
+- **Document test cases first:** Write test cases in `/test/test-documentation.md`
+- **Define expected behavior:** Clearly specify inputs, outputs, and edge cases
+- **Implement tests:** Create actual test files that verify the documented behavior
+- **Verify test failure:** Run tests to confirm they fail appropriately (red phase)
+- **Only then implement:** Write the minimum code needed to make tests pass (green phase)
+- **Clean up test artifacts:** Remove temporary test files, move useful test data to `/test/fixtures/`
+
+### Step 4: Implementation and Verification
+
+- **Write production code:** Implement the actual functionality
+- **Run all tests:** Ensure all tests pass, including new and existing ones
+- **Verify functionality:** Confirm the implementation meets requirements
+- **Get user confirmation:** User must test the result and confirm it meets expectations
+- **Refactor if needed:** Clean up code while maintaining test coverage (refactor phase)
+- **File cleanup:** Remove all temporary files, debug outputs, and experimental code created during development
+
+### Step 5: Documentation and Status Updates
+
+- **Update all documentation:** Follow documentation maintenance guidelines
+- **Update task status:** Mark completed tasks in `/_meta/project-task-list.md`
+- **Update test documentation:** Record test status in `/test/test-documentation.md`
+- **Update CHANGELOG.md:** Document user-facing changes
+- **Review code documentation:** Ensure JSDoc comments are current
+
+### Step 6: Version Control
+
+- **Commit changes:** Use conventional commit messages
+- **Include all related files:** Ensure tests, documentation, and code are committed together
+- **Write descriptive commit messages:** Explain what was implemented and why
+- **Keep commits atomic:** Each commit should represent a complete, working feature
+
+### Step 7: Workflow Completion Check
+
+- **Mandatory workflow completion:** User must complete the entire workflow before moving to next task
+- **Incremental development:** Remind users to finish current workflow before starting new tasks
+- **Repository hygiene:** Ensure codebase, documentation, and repository remain up-to-date
+- **Quality gates:** All tests must pass, documentation must be current, and code must be committed
+
+## Workflow Enforcement Rules
+
+### Before Starting Any New Task
+
+```
+STOP: Complete the current workflow first!
+
+Before proceeding with a new task, ensure:
+✅ Current task is documented and committed
+✅ All tests are passing
+✅ Documentation is updated
+✅ User has confirmed the implementation meets expectations
+✅ Changes are committed with proper messages
+
+Only then proceed with the next task planning phase.
+```
+
+### Quality Gates
+
+- **No shortcuts:** Every step must be completed in order
+- **No parallel tasks:** Focus on one task at a time until fully complete
+- **No skipping tests:** TDD approach is mandatory
+- **No incomplete documentation:** All documentation must be current
+- **No uncommitted changes:** All work must be committed before moving on
+
+### Workflow Violations
+
+If a user requests to skip steps or start new work before completing the workflow:
+
+1. **Politely decline:** Explain the importance of completing the current workflow
+2. **Remind of benefits:** Emphasize how this maintains code quality and project health
+3. **Offer to complete current workflow:** Help finish the current task properly first
+4. **Suggest task breakdown:** If the current task is too large, suggest breaking it down
+
+## Benefits of This Workflow
+
+- **Higher code quality:** TDD ensures robust, well-tested code
+- **Better documentation:** Always current and comprehensive
+- **Reduced technical debt:** Incremental approach prevents accumulation of shortcuts
+- **Improved maintainability:** Clear task tracking and documentation
+- **Team collaboration:** Consistent approach enables better teamwork
+- **Risk mitigation:** Small, tested changes reduce deployment risks

package/templates/general/files/docs-update.instructions.md

@@ -0,0 +1,203 @@
+---
+description: 'Guidelines for maintaining project documentation'
+applyTo: '**/*.md'
+---
+
+# Documentation Maintenance Guidelines
+
+## Documentation Architecture Principles
+
+This project enforces a strict distinction between different types of documentation to ensure clarity, maintainability, and appropriate use of status indicators.
+
+### System Documentation (Evergreen, Factual)
+
+**Purpose:** Describes the current state of the system, architecture, and implemented features.
+**Files:** README.md, architecture.md, api-design.md, system-documentation.md, code documentation
+**Language:** Present tense, factual, descriptive
+**Status Indicators:** ❌ **NEVER use status emojis or temporal language**
+**Content Focus:** What exists now, how it works, what it does
+**Examples:**
+
+- ✅ Correct: "The authentication system uses JWT tokens"
+- ❌ Incorrect: "🚧 Authentication system (in progress)"
+- ✅ Correct: "The API supports the following endpoints:"
+- ❌ Incorrect: "📋 Planned API endpoints:"
+
+### Project Management Documentation (Temporal, Status-Oriented)
+
+**Purpose:** Tracks work progress, planning, and execution status.
+**Files:** project-task-list.md, sprint-planning.md, backlog.md
+**Language:** Status-oriented, temporal references allowed
+**Status Indicators:** ✅ **Required - use emojis and progress indicators**
+**Content Focus:** What needs to be done, work progress, planning
+**Examples:**
+
+- ✅ Correct: "🚧 In Progress - Authentication system implementation"
+- ✅ Correct: "✅ Completed - JWT token validation"
+- ✅ Correct: "📋 Backlog - Add OAuth integration"
+
+### User Documentation (Instructional, Current)
+
+**Purpose:** Helps users understand how to use the system.
+**Files:** Installation guides, usage examples, tutorials
+**Language:** Imperative, instructional, present tense
+**Status Indicators:** ⚠️ **Use sparingly** - only for actual user-facing feature status
+**Content Focus:** How to use, what users can do, step-by-step guidance
+
+### Enforcement Rules
+
+1. **No Status Emojis in System Documentation:** Architecture, API docs, and README feature descriptions must be purely factual
+2. **No Temporal Language in System Documentation:** Avoid "currently", "recently", "planned", "upcoming" in system docs
+3. **Status Indicators Required in Project Management:** All task lists and project planning docs must use clear status indicators
+4. **Regular Documentation Audits:** Review and remove status language that has crept into system documentation
+5. **Template Compliance:** All generated documentation must follow these principles
+
+## Documentation Quality Standards
+
+- **Clarity:** Write clear, concise explanations
+- **Completeness:** Ensure documentation covers all necessary aspects
+- **Accuracy:** Verify all information is current and correct
+- **Consistency:** Maintain consistent tone and formatting
+- **Accessibility:** Use clear language and proper formatting for accessibility
+- **Architecture Compliance:** Follow the system vs project documentation distinction
+
+## Status Indication Guidelines (For Project Management Documentation Only)
+
+**⚠️ IMPORTANT: These guidelines apply ONLY to project management documentation (task lists, planning docs). System documentation (README, architecture, API docs) must NEVER use status indicators.**
+
+- **Use checkboxes for task status:** `- [ ]` for incomplete, `- [x]` for complete
+- **Use clear status indicators in project management docs:**
+  - ✅ Complete/Implemented
+  - 🚧 In Progress
+  - ❌ Not Started
+  - ⚠️ Needs Review
+  - 🔄 Under Revision
+- **Examples of correct project management documentation:**
+  - ✅ Good: "🚧 In Progress - User authentication implementation"
+  - ✅ Good: "Development Status" with current checkboxes
+  - ✅ Good: "✅ Completed - API endpoint testing"
+- **Examples of incorrect system documentation:**
+  - ❌ Bad: "🚧 Authentication Features" (in README.md)
+  - ❌ Bad: "Authentication system (planned)" (in architecture.md)
+  - ❌ Bad: "📋 API Endpoints" (in api-design.md)
+
+## Task Management Documentation Guidelines
+
+- **Focus on current state:** Document what needs to be done, not what was recently done
+- **Use project phases:** Organize by logical project phases or milestones, not completion status
+- **Move completed work to changelog:** Record completed work in CHANGELOG.md, not in task lists
+- **Keep task lists current:** Update completed items with current status instead of maintaining "completed" sections
+- **Use descriptive section names:** Use functional names like "Core Features", "Infrastructure", "Testing" instead of "Completed Tasks"
+- **Avoid temporal references:** Don't use "Recent", "Latest", "Upcoming" in section headers - they become outdated quickly
+
+## README.md Standards (System Documentation)
+
+**⚠️ README.md is system documentation - NO status indicators or temporal language allowed**
+
+- **Project Overview:** Keep description current with latest capabilities using factual, present-tense language
+- **Installation Instructions:** Verify and update installation steps with clear, current procedures
+- **Usage Examples:** Ensure all code examples are tested and working, describe what they do
+- **Feature Documentation:** Document all major features with examples using factual descriptions
+- **Version Badges:** Keep version badges synchronized with package.json
+- **Links Verification:** Regularly check that all links work correctly
+- **Screenshots/GIFs:** Update visual documentation when UI changes
+- **Avoid Status Language:** Never use "planned", "upcoming", "in progress", or status emojis
+- **Examples:**
+  - ✅ Correct: "The CLI provides three commands for project setup"
+  - ❌ Incorrect: "🚧 CLI commands (in development)"
+  - ✅ Correct: "Authentication uses JWT tokens with refresh capability"
+  - ❌ Incorrect: "Authentication system (planned for v2.0)"
+
+## CHANGELOG.md Maintenance
+
+- **User-Facing Changes:** Document all changes that affect users
+- **Consistent Format:** Follow established changelog format
+- **Categorization:** Group changes appropriately (Added, Changed, Fixed, etc.)
+- **Breaking Changes:** Clearly mark breaking changes
+- **Migration Guides:** Provide migration guidance for breaking changes
+
+## Code Documentation
+
+- **JSDoc Comments:** Update JSDoc comments when changing public APIs
+- **Inline Comments:** Add comments for complex logic, not obvious code
+- **Function Documentation:** Document parameters, return values, and side effects
+- **Class Documentation:** Explain class purpose, responsibilities, and usage patterns
+- **Type Documentation:** Document complex TypeScript types and interfaces
+
+## API Documentation
+
+- **Endpoint Documentation:** Keep API endpoint documentation current
+- **Parameter Changes:** Update parameter descriptions for any modifications
+- **Response Examples:** Provide realistic response examples
+- **Error Handling:** Document error responses and status codes
+- **Authentication:** Keep authentication documentation accurate
+
+## Architectural Documentation (System Documentation)
+
+**⚠️ Architecture docs are system documentation - NO status indicators or temporal language allowed**
+
+- **Decision Records:** Record significant architectural decisions in `/meta` folder using factual language
+- **System Overview:** Maintain high-level system architecture documentation describing current implementation
+- **Data Flow:** Document data flow and process workflows as they currently exist
+- **Integration Points:** Document external system integrations that are implemented
+- **Performance Considerations:** Document performance implications of current design decisions
+- **Examples:**
+  - ✅ Correct: "The system uses a microservices architecture with three main services"
+  - ❌ Incorrect: "🏗️ Microservices architecture (under development)"
+  - ✅ Correct: "Data flows through the validation layer before storage"
+  - ❌ Incorrect: "Data validation layer (planned implementation)"
+
+## Code Examples and Tutorials
+
+- **Working Examples:** Ensure all code examples compile and run
+- **Complete Examples:** Provide complete, runnable examples when possible
+- **Progressive Complexity:** Start with simple examples, build to complex ones
+- **Error Handling:** Show proper error handling in examples
+- **Best Practices:** Demonstrate best practices in example code
+
+## Test Documentation Standards
+
+Follow the standardized table format for all test case documentation:
+
+### Required Table Format
+
+```markdown
+| Test Case ID  | Description                                 | Type | Status    |
+| :------------ | :------------------------------------------ | :--- | :-------- |
+| AREA-TYPE-001 | Brief but descriptive test case description | Unit | Completed |
+```
+
+### Test Case ID Conventions
+
+- **Format:** `[AREA]-[TYPE]-[NUMBER]`
+- **Area Prefixes (adapt to your project):** CORE, API, UI, DB, AUTH, UTIL, CONFIG, DOC, E2E, INT
+- **Type Suffixes:** UNIT, INT, E2E
+- **Sequential Numbering:** 001, 002, 003, etc.
+
+### Table Organization Requirements
+
+- **Functional Grouping:** Group test cases by system area/component
+- **Consistent Formatting:** Maintain proper column alignment using pipes
+- **Clear Headers:** Use descriptive section headers (e.g., "Template System", "CLI Commands")
+- **Status Tracking:** Use simple status values: "Completed", "In Progress", "Not Started"
+
+### Documentation Testing
+
+- **Link Checking:** Regularly verify all links work
+- **Code Testing:** Test all code examples in documentation
+- **Installation Testing:** Verify installation instructions work in clean environment
+- **User Testing:** Occasionally have someone unfamiliar try following docs
+
+## Maintenance Schedule
+
+- **Regular Review:** Schedule regular documentation review cycles
+- **Release Updates:** Update documentation as part of release process
+- **Issue Tracking:** Track documentation issues and improvements
+- **Community Feedback:** Incorporate user feedback on documentation clarity
+
+## Localization Considerations
+
+- **Clear English:** Use clear, simple English for international audiences
+- **Cultural Sensitivity:** Avoid culture-specific references
+- **Technical Terms:** Define technical terms when first introduced
+- **Consistent Terminology:** Use consistent terminology throughout

package/templates/general/files/release.instructions.md

@@ -0,0 +1,72 @@
+---
+description: "Step-by-step release process automation"
+applyTo: "package.json"
+---
+
+# Release Process Checklist
+
+## Pre-Release Validation
+1. **Test Suite:** Verify all tests pass: `npm test`
+2. **Build Verification:** Ensure clean build without errors: `npm run build`
+3. **Linting:** Check code quality standards: `npm run lint`
+4. **Dependencies:** Review and update dependencies if needed
+5. **Security Audit:** Run security audit: `npm audit`
+
+## Version Management
+1. **Semantic Versioning:** Update version in package.json following SemVer:
+   - **MAJOR:** Breaking changes (X.0.0)
+   - **MINOR:** New features, backward compatible (0.X.0)
+   - **PATCH:** Bug fixes, backward compatible (0.0.X)
+2. **Version Consistency:** Ensure version matches across all relevant files
+3. **Breaking Changes:** Document breaking changes prominently in changelog
+
+## Documentation Updates
+1. **README.md Updates:**
+   - Update version badges to match package.json version
+   - Refresh installation instructions if needed
+   - Update feature descriptions for new capabilities
+   - Verify all links and examples work correctly
+2. **API Documentation:** Update API docs for any interface changes
+
+## Changelog Management
+1. **Add New Entry:** Create new section in CHANGELOG.md with:
+   - Release version number (matching package.json)
+   - Release date in YYYY-MM-DD format
+   - Grouped changes by category:
+     - **Added:** New features
+     - **Changed:** Changes in existing functionality
+     - **Deprecated:** Soon-to-be removed features
+     - **Removed:** Now removed features
+     - **Fixed:** Bug fixes
+     - **Security:** Security vulnerability fixes
+2. **Entry Guidelines:**
+   - Keep entries brief but descriptive (1-2 lines per change)
+   - Focus on user impact rather than technical implementation
+   - Reference issue/PR numbers when applicable: `(#123)`
+   - Highlight breaking changes with ⚠️ or **BREAKING:**
+
+## Git Operations
+1. **Commit Changes:** Stage all release-related changes
+2. **Commit Message:** Use format: `chore: bump version to vX.Y.Z`
+3. **Create Tag:** Tag the commit with version number: `git tag vX.Y.Z`
+4. **Push Changes:** Push commits and tags: `git push && git push --tags`
+
+## GitHub Release
+1. **Create Release:** Create GitHub release with tag matching package.json version
+2. **Release Title:** Use format: `vX.Y.Z - [Brief description]`
+3. **Release Notes:** 
+   - Copy relevant sections from CHANGELOG.md
+   - Include installation instructions
+   - Highlight major changes and breaking changes
+   - Thank contributors if applicable
+
+## Post-Release Verification
+1. **Package Registry:** Verify package published correctly (if applicable)
+2. **Installation Test:** Test installation from registry in clean environment
+3. **Documentation Links:** Ensure all documentation links work correctly
+4. **Monitor Issues:** Watch for any immediate issues reported by users
+
+## Rollback Plan
+- **Git Revert:** Know how to revert problematic releases
+- **Package Unpublish:** Understand package registry policies for unpublishing
+- **Communication:** Prepare communication strategy for critical issues