Initial commit of WordPress Plugin Starter Template for AI Coding

.ai-workflows/multi-repo-workspace.md

@@ -0,0 +1,122 @@
+# Working in Multi-Repository Workspaces
+
+This document provides guidelines for AI assistants working in VSCode/VSCodium workspaces that contain multiple repository folders.
+
+## Understanding Multi-Repository Workspaces
+
+In VSCode/VSCodium, developers often create workspaces that include multiple repository folders. This allows them to work on related projects simultaneously or reference code from one project while working on another.
+
+### Common Workspace Configurations
+
+1. **Multiple WordPress Plugins**: A workspace containing several WordPress plugin repositories
+2. **Plugin and Theme Combinations**: Repositories for both plugins and themes that work together
+3. **Reference Repositories**: Including repositories purely for reference or inspiration
+4. **Shared Libraries**: Repositories containing shared code used across multiple projects
+
+## Potential Issues in Multi-Repository Workspaces
+
+### 1. Feature Hallucination
+
+The most common issue is "feature hallucination" - assuming that features present in one repository should be implemented in another, or documenting non-existent features based on code seen in other repositories.
+
+### 2. Cross-Repository Code References
+
+Referencing or suggesting code patterns from one repository when working on another can lead to inconsistent coding styles and approaches.
+
+### 3. Documentation Confusion
+
+Creating documentation that includes features or functionality from other repositories in the workspace.
+
+### 4. Scope Creep
+
+Suggesting changes or improvements based on other repositories, leading to scope creep and feature bloat.
+
+## Best Practices for AI Assistants
+
+### 1. Repository Verification
+
+**ALWAYS** verify which repository you're currently working in before:
+- Making code suggestions
+- Creating or updating documentation
+- Discussing features or functionality
+- Implementing new features
+
+### 2. Explicit Code Search Scoping
+
+When searching for code or functionality:
+- Explicitly limit searches to the current repository
+- Use repository-specific paths in search queries
+- Verify search results are from the current repository before using them
+
+### 3. Feature Verification Process
+
+Before documenting or implementing a feature:
+
+1. **Check the codebase**: Use the codebase-retrieval tool to search for relevant code in the current repository
+2. **Verify functionality**: Look for actual implementation, not just references or comments
+3. **Check documentation**: Review existing documentation to understand intended functionality
+4. **Ask for clarification**: If uncertain, ask the developer to confirm the feature's existence or scope
+
+### 4. Documentation Guidelines
+
+When creating or updating documentation:
+
+1. **Repository-specific content**: Only document features and functionality that exist in the current repository
+2. **Verify before documenting**: Check the codebase to confirm features actually exist
+3. **Clear boundaries**: Make it clear which repository the documentation applies to
+4. **Accurate feature descriptions**: Describe features as they are implemented, not as they might be in other repositories
+
+### 5. Cross-Repository Inspiration
+
+When implementing features inspired by other repositories:
+
+1. **Explicit attribution**: Clearly state that the feature is inspired by another repository
+2. **New implementation**: Treat it as a new feature being added, not an existing one
+3. **Repository-appropriate adaptation**: Adapt the feature to fit the current repository's architecture and style
+4. **Developer confirmation**: Confirm with the developer that adding the feature is appropriate
+
+## Repository Context Verification Checklist
+
+Before making significant changes or recommendations, run through this checklist:
+
+- [ ] Verified current working directory/repository
+- [ ] Confirmed repository name and purpose
+- [ ] Checked that code searches are limited to current repository
+- [ ] Verified features exist in current repository before documenting them
+- [ ] Ensured documentation reflects only the current repository's functionality
+- [ ] Confirmed that any cross-repository inspiration is clearly marked as new functionality
+
+## Example Verification Workflow
+
+1. **Check current repository**:
+   ```
+   pwd
+   git remote -v
+   ```
+
+2. **Verify feature existence**:
+   ```
+   # Use codebase-retrieval to search for the feature
+   # Look for actual implementation, not just references
+   ```
+
+3. **Document with clear repository context**:
+   ```
+   # Always include repository name in documentation
+   # Be specific about which features are included
+   ```
+
+4. **When suggesting new features**:
+   ```
+   # Clearly state if inspired by another repository
+   # Explain why it's appropriate for the current repository
+   ```
+
+## Handling Repository Switching
+
+When the developer switches between repositories in the workspace:
+
+1. **Acknowledge the switch**: Confirm the new repository context
+2. **Reset context**: Don't carry over assumptions from the previous repository
+3. **Verify new environment**: Check the structure and features of the new repository
+4. **Update documentation references**: Ensure you're referencing documentation specific to the new repository

.ai-workflows/readme.md

@@ -0,0 +1,19 @@
+# AI Workflows
+
+This directory contains workflow documentation for AI assistants working with this repository.
+
+## Contents
+
+- **bug-fixing.md**: Guidelines for identifying and fixing bugs in the codebase
+- **code-review.md**: Standards and procedures for reviewing code changes
+- **dev-prefs-memory.md**: Persistent memory of developer preferences
+- **feature-development.md**: Process for developing new features
+- **folder-structure.md**: Documentation of the plugin's folder structure and naming conventions
+- **git-workflow.md**: Detailed git workflow and branch management guidelines
+- **incremental-development.md**: Time-efficient approach for incremental development and testing
+- **local-env-vars.md**: Local development environment paths and URLs
+- **multi-repo-workspace.md**: Guidelines for working in workspaces with multiple repositories
+- **release-process.md**: Steps for preparing and publishing new releases
+- **wiki-documentation.md**: Guidelines for maintaining wiki documentation
+
+These documents help ensure consistent quality and approach when using AI tools to assist with development tasks.

.ai-workflows/release-process.md

@@ -0,0 +1,156 @@
+# Release Process Guide for AI Assistants
+
+This document outlines the process for preparing and publishing new releases of the WordPress Plugin Starter Template.
+
+## Release Workflow Overview
+
+1. Create a version branch
+2. Update version numbers in all required files
+3. Build and test the plugin
+4. Commit version changes
+5. Create version tags
+6. Push to remote repositories
+7. Merge into main branch
+
+## Detailed Steps
+
+### 1. Create a Version Branch
+
+Always start by creating a version branch from the latest main branch:
+
+```bash
+git checkout main
+git pull origin main  # Critical step - never skip this
+git checkout -b v{MAJOR}.{MINOR}.{PATCH}
+```
+
+Example: `git checkout -b v1.0.0`
+
+### 2. Update Version Numbers
+
+Update version numbers in all required files:
+
+1. **Main plugin file** (wp-plugin-starter-template.php):
+   - Update the `Version:` header
+   - Update the version parameter in the Plugin class instantiation
+
+2. **readme.txt**:
+   - Update the `Stable tag:` value
+   - Add a new section to the changelog
+
+3. **README.md**:
+   - Update version references
+   - Add new section to the changelog
+
+4. **CHANGELOG.md**:
+   - Add a new version section at the top
+
+5. **languages/wp-plugin-starter-template.pot**:
+   - Update the `Project-Id-Version` header
+
+### 3. Build and Test the Plugin
+
+Build the plugin with the new version:
+
+```bash
+./build.sh {MAJOR}.{MINOR}.{PATCH}
+```
+
+This will:
+- Create a clean build in the `build/` directory
+- Generate a ZIP file for distribution
+- Deploy to a local WordPress installation if configured
+
+Test the plugin thoroughly:
+- Test with the latest WordPress version
+- Test with the minimum supported WordPress version (5.0)
+- Test with PHP 7.0+ (minimum supported version)
+- Test all features and functionality
+
+### 4. Commit Version Changes
+
+Commit all version changes:
+
+```bash
+git add wp-plugin-starter-template.php readme.txt README.md CHANGELOG.md languages/wp-plugin-starter-template.pot
+git commit -m "Version {MAJOR}.{MINOR}.{PATCH} - [brief description]"
+```
+
+### 5. Create Version Tags
+
+Create version tags:
+
+```bash
+git tag -a v{MAJOR}.{MINOR}.{PATCH} -m "Version {MAJOR}.{MINOR}.{PATCH}"
+git tag -a v{MAJOR}.{MINOR}.{PATCH}-stable -m "Stable version {MAJOR}.{MINOR}.{PATCH}"
+```
+
+The `-stable` tag is used by Git Updater to identify the stable version.
+
+### 6. Push to Remote Repositories
+
+Push the version branch and tags to remote repositories:
+
+```bash
+# Push to GitHub
+git push github refs/heads/v{MAJOR}.{MINOR}.{PATCH}:refs/heads/v{MAJOR}.{MINOR}.{PATCH}
+git push github refs/tags/v{MAJOR}.{MINOR}.{PATCH}:refs/tags/v{MAJOR}.{MINOR}.{PATCH}
+git push github refs/tags/v{MAJOR}.{MINOR}.{PATCH}-stable:refs/tags/v{MAJOR}.{MINOR}.{PATCH}-stable
+
+# Push to Gitea
+git push gitea refs/heads/v{MAJOR}.{MINOR}.{PATCH}:refs/heads/v{MAJOR}.{MINOR}.{PATCH}
+git push gitea refs/tags/v{MAJOR}.{MINOR}.{PATCH}:refs/tags/v{MAJOR}.{MINOR}.{PATCH}
+git push gitea refs/tags/v{MAJOR}.{MINOR}.{PATCH}-stable:refs/tags/v{MAJOR}.{MINOR}.{PATCH}-stable
+```
+
+### 7. Merge into Main Branch
+
+Merge the version branch into the main branch:
+
+```bash
+git checkout main
+git merge v{MAJOR}.{MINOR}.{PATCH} --no-ff -m "Merge v{MAJOR}.{MINOR}.{PATCH} into main"
+git push github main
+git push gitea main
+```
+
+## Version Numbering Guidelines
+
+Follow semantic versioning (MAJOR.MINOR.PATCH):
+
+- **MAJOR**: Incompatible API changes
+- **MINOR**: Add functionality in a backward-compatible manner
+- **PATCH**: Backward-compatible bug fixes
+
+Examples:
+- Bug fix: 1.0.0 → 1.0.1
+- New feature: 1.0.0 → 1.1.0
+- Breaking change: 1.0.0 → 2.0.0
+
+## GitHub Actions Workflow
+
+When you push a tag, the GitHub Actions workflow will:
+
+1. Build the plugin
+2. Create a ZIP file
+3. Create a GitHub release
+4. Attach the ZIP file to the release
+
+You can monitor the workflow in the "Actions" tab of the GitHub repository.
+
+## WordPress.org Deployment (If Applicable)
+
+If the plugin is hosted on WordPress.org:
+
+1. Ensure the `readme.txt` file is properly formatted
+2. Ensure the stable tag matches the new version
+3. Use the WordPress.org SVN repository to deploy the new version
+
+## Post-Release Tasks
+
+After releasing a new version:
+
+1. Update the wiki documentation if needed
+2. Announce the release in relevant channels
+3. Monitor for any issues or feedback
+4. Start planning the next release

.ai-workflows/wiki-documentation.md

@@ -0,0 +1,181 @@
+# Wiki Documentation Guide for AI Assistants
+
+This document provides guidelines for maintaining and updating the wiki documentation for the WordPress Plugin Starter Template.
+
+## Wiki Structure
+
+The wiki documentation is organized into the following sections:
+
+1. **User Documentation**:
+   - Home
+   - Installation Guide
+   - Usage Instructions
+   - Frequently Asked Questions
+   - Troubleshooting
+
+2. **Developer Documentation**:
+   - Architecture Overview
+   - Customization Guide
+   - Extending the Plugin
+   - Coding Standards
+   - Release Process
+
+3. **AI Documentation**:
+   - AI Workflow Documentation
+
+4. **Additional Resources**:
+   - Changelog
+   - Contributing
+
+## Wiki Files Location
+
+The wiki documentation is stored in the `.wiki/` directory in the repository. This allows:
+
+1. Version control of wiki content alongside the code
+2. Automated synchronization with the GitHub wiki using GitHub Actions
+3. Easy contribution to documentation through pull requests
+
+## Synchronization Process
+
+When changes are pushed to the `.wiki/` directory in the `main` branch, the GitHub Actions workflow `.github/workflows/sync-wiki.yml` automatically synchronizes these changes with the GitHub wiki.
+
+## Documentation Standards
+
+### General Guidelines
+
+- Use clear, concise language
+- Follow Markdown formatting conventions
+- Include code examples where appropriate
+- Use screenshots or diagrams for complex concepts
+- Keep documentation up-to-date with code changes
+
+### Markdown Formatting
+
+- Use `#` for main headings
+- Use `##` for section headings
+- Use `###` for subsection headings
+- Use backticks for inline code: `code`
+- Use triple backticks for code blocks:
+  ```php
+  // Code example
+  function example() {
+      return true;
+  }
+  ```
+- Use bullet points for lists
+- Use numbered lists for sequential steps
+- Use blockquotes for important notes: > Note
+
+### Code Examples
+
+- Include complete, working code examples
+- Use proper syntax highlighting
+- Include comments to explain complex parts
+- Follow WordPress coding standards in examples
+
+## Updating Documentation
+
+### When to Update
+
+Documentation should be updated:
+
+1. When adding new features
+2. When changing existing functionality
+3. When fixing bugs that affect user experience
+4. When improving or clarifying existing documentation
+
+### How to Update
+
+1. Identify the relevant wiki file(s) in the `.wiki/` directory
+2. Make the necessary changes
+3. Commit and push the changes to the `main` branch
+4. The GitHub Actions workflow will automatically sync the changes with the GitHub wiki
+
+### Creating New Pages
+
+To create a new wiki page:
+
+1. Create a new Markdown file in the `.wiki/` directory
+2. Name the file according to the page title (e.g., `New-Feature.md`)
+3. Add a link to the new page in the appropriate section of `Home.md`
+4. Add a link to the new page in `_Sidebar.md`
+
+## Repository-Specific Documentation
+
+When working in a multi-repository workspace, it's critical to ensure that wiki documentation accurately reflects the features and functionality of the **current repository only**.
+
+### Avoiding Cross-Repository Confusion
+
+1. **Verify Features Before Documenting**:
+   - Always verify that a feature exists in the current repository before documenting it
+   - Use `codebase-retrieval` to search for feature implementations
+   - Check the actual code, not just comments or references
+
+2. **Repository-Specific Content**:
+   - Document only features that exist in the current repository
+   - Don't assume features from other repositories are present in this one
+   - Be explicit about which repository the documentation applies to
+
+3. **Feature Inspiration vs. Existing Features**:
+   - If documenting a feature inspired by another repository but not yet implemented, clearly mark it as a proposed feature
+   - Don't document features as if they exist when they're only planned or inspired by other repositories
+
+4. **Cross-Repository References**:
+   - If referencing functionality from another repository, clearly indicate that it's external
+   - Use phrases like "unlike Repository X, this plugin does not include..."
+
+For detailed guidelines on working in multi-repository workspaces, see **@.ai-workflows/multi-repo-workspace.md**.
+
+## Best Practices
+
+### Content Guidelines
+
+- Use clear, concise language
+- Include step-by-step instructions for complex tasks
+- Use screenshots or diagrams to illustrate concepts
+- Provide code examples for developers
+- Keep the documentation organized and easy to navigate
+
+### Formatting Guidelines
+
+- Use consistent Markdown formatting
+- Use headings to create a clear hierarchy
+- Use lists for steps or related items
+- Use tables for structured data
+- Use code blocks for code examples
+
+### Maintenance Guidelines
+
+- Review documentation regularly for accuracy
+- Update documentation when code changes
+- Remove outdated information
+- Add new documentation for new features
+- Respond to user feedback about documentation
+
+## User-Focused Documentation
+
+When writing documentation for users:
+
+1. Assume minimal technical knowledge
+2. Provide clear, step-by-step instructions
+3. Include screenshots for visual guidance
+4. Explain technical terms when necessary
+5. Focus on what users want to accomplish
+
+## Developer-Focused Documentation
+
+When writing documentation for developers:
+
+1. Assume familiarity with WordPress development
+2. Provide technical details and explanations
+3. Include code examples and API references
+4. Explain architectural decisions
+5. Focus on how to extend or customize the plugin
+
+## Responding to User Feedback
+
+Improve documentation based on user feedback:
+
+1. Monitor GitHub issues and WordPress.org support forums for common questions
+2. Update the FAQ and troubleshooting sections based on user feedback
+3. Add new examples or clarifications based on user questions