aidevops 2.52.1

package/.agent/workflows/branch.md

@@ -0,0 +1,347 @@
+---
+description: Git branch creation and management workflow
+mode: subagent
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: true
+  glob: true
+  grep: true
+  webfetch: false
+  task: true
+---
+
+# Branch Workflow
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **Before building**: Check for existing WIP branch
+- **Continue WIP**: `git checkout <branch>` and resume
+- **New work**: Create branch using type below, always from updated `main`
+
+| Task Type | Branch Prefix | Subagent |
+|-----------|---------------|----------|
+| New functionality | `feature/` | `branch/feature.md` |
+| Bug fix | `bugfix/` | `branch/bugfix.md` |
+| Urgent production fix | `hotfix/` | `branch/hotfix.md` |
+| Code restructure | `refactor/` | `branch/refactor.md` |
+| Docs, deps, config | `chore/` | `branch/chore.md` |
+| Spike, POC | `experiment/` | `branch/experiment.md` |
+| Version release | `release/` | `branch/release.md` |
+
+**Branch naming**: `{type}/{short-description}` (e.g., `feature/user-dashboard`)
+
+**Mandatory start**:
+
+```bash
+git checkout main && git pull origin main && git checkout -b {type}/{description}
+```
+
+**Task status**: Move task to `## In Progress` and add `started:` timestamp when branch is created.
+
+**Lifecycle**: Create → Develop → Preflight → Version → Push → PR → Review → Merge → Release → Postflight → Cleanup
+
+**Task lifecycle**:
+
+```text
+Ready/Backlog → In Progress → In Review → Done
+   (branch)       (develop)      (PR)     (merge/release)
+```
+
+<!-- AI-CONTEXT-END -->
+
+## Purpose
+
+This workflow ensures all build agents use consistent branching practices. Every code change should go through a branch, PR, and merge process.
+
+**Important**: Before creating branches, read `workflows/git-workflow.md` for the complete git workflow including issue URL handling, fork detection, and new repo initialization.
+
+## Checking for Existing Work
+
+Before starting new work, check for WIP branches:
+
+```bash
+# List all branches with WIP or your current work
+git branch -a | grep -E "(feature|bugfix|hotfix|refactor|chore|experiment)/"
+
+# Check current branch
+git branch --show-current
+```text
+
+If a relevant branch exists, continue on it rather than creating a new one.
+
+## Creating a New Branch
+
+**Always start from updated main:**
+
+```bash
+git checkout main
+git pull origin main
+git checkout -b {type}/{description}
+```text
+
+### Branch Type Selection
+
+| If the task is... | Use branch type |
+|-------------------|-----------------|
+| Adding new capability | `feature/` |
+| Fixing a bug (non-urgent) | `bugfix/` |
+| Fixing production issue (urgent) | `hotfix/` |
+| Restructuring code, same behavior | `refactor/` |
+| Updating docs, deps, CI, config | `chore/` |
+| Exploring, prototyping, POC | `experiment/` |
+| Preparing a version release | `release/` |
+
+### Naming Conventions
+
+- Use lowercase with hyphens: `feature/user-authentication`
+- Be descriptive but concise: `bugfix/login-timeout` not `bugfix/fix`
+- Start with an action verb for clarity:
+  - New functionality: `feature/add-user-dashboard`
+  - Enhancing existing: `feature/improve-search-filters`
+  - Fixing: `bugfix/fix-login-timeout`
+  - Removing: `feature/remove-legacy-api`
+- Include issue number if applicable: `bugfix/123-login-timeout`
+- Release branches use version: `release/1.2.0` (semver format)
+
+### Branch Names from Planning Files
+
+When TODO.md or PLANS.md tasks exist, derive branch names from them:
+
+| Source | Example Task | Branch Name |
+|--------|--------------|-------------|
+| TODO.md | `- [ ] Add Ahrefs MCP server #seo` | `feature/add-ahrefs-mcp-server` |
+| TODO.md | `- [ ] Fix login timeout #auth` | `bugfix/fix-login-timeout` |
+| PLANS.md | `### User Auth Overhaul` | `feature/user-auth-overhaul` |
+| PRD file | `prd-export-csv.md` | `feature/export-csv` |
+
+**Slugification**: lowercase, spaces→hyphens, remove special chars, max ~50 chars.
+
+See `git-workflow.md` for full branch naming from planning files.
+
+## Branch Lifecycle
+
+```text
+main ─────────────────────────────────────────────────────────────► main
+       \                                                          /
+        └─► feature/xyz ─► preflight ─► PR ─► review ─► merge ─► release
+```text
+
+### 1. Create Branch
+
+Start from updated `main`. Reference domain agents for implementation guidance.
+
+```bash
+git checkout main && git pull origin main
+git checkout -b {type}/{description}
+```
+
+**Task status update**: After creating the branch, update the corresponding task in TODO.md:
+
+1. Move task from `## Ready` or `## Backlog` to `## In Progress`
+2. Add `started:` timestamp
+3. Sync with Beads
+
+```markdown
+# Before (in ## Ready or ## Backlog)
+- [ ] t001 Add user dashboard #feature ~4h
+
+# After (move to ## In Progress)
+- [ ] t001 Add user dashboard #feature ~4h started:2025-01-15T10:30Z
+```
+
+```bash
+# Sync with Beads after updating TODO.md
+~/.aidevops/agents/scripts/beads-sync-helper.sh push
+```
+
+**Agents**: Domain agents (`seo.md`, `tools/wordpress/`, etc.) for implementation patterns
+
+### 2. Develop
+
+Regular commits following conventional format (`feat:`, `fix:`, `refactor:`, etc.).
+
+**Agents**: `branch/{type}.md` for branch-specific guidance
+
+### 3. Preflight (Local Quality)
+
+Run quality checks before pushing. Catches issues early.
+
+```bash
+.agent/scripts/linters-local.sh --fast
+```text
+
+**Agents**: `workflows/preflight.md`
+
+### 4. Version (If Applicable)
+
+Bump version for releases. Skip for WIP or intermediate commits.
+
+```bash
+.agent/scripts/version-manager.sh bump [major|minor|patch]
+```text
+
+**Agents**: `workflows/version-bump.md`, `workflows/changelog.md`
+
+### 5. Push
+
+Push to remote for backup and collaboration.
+
+```bash
+git push -u origin HEAD
+```text
+
+### 6. Pull Request
+
+Create PR/MR. CI/CD runs automatically.
+
+```bash
+gh pr create --fill        # GitHub
+glab mr create --fill      # GitLab
+```text
+
+**Agents**: `workflows/pr.md`
+
+### 7. Review Feedback
+
+Address reviewer comments. Re-request review when ready.
+
+```bash
+git add . && git commit -m "fix: address review feedback"
+git push
+```text
+
+**Agents**: `workflows/code-audit-remote.md`
+
+### 8. Merge
+
+Final CI/CD verification, then merge via PR.
+
+```bash
+gh pr merge --squash --delete-branch
+```text
+
+### 9. Release (If Applicable)
+
+Tag and publish for version releases.
+
+```bash
+.agent/scripts/version-manager.sh release [major|minor|patch]
+```text
+
+**Agents**: `workflows/release.md`
+
+### 10. Postflight
+
+Verify CI/CD and quality tools after release.
+
+```bash
+gh run watch $(gh run list --limit=1 --json databaseId -q '.[0].databaseId') --exit-status
+```text
+
+**Agents**: `workflows/postflight.md`
+
+### 11. Cleanup
+
+Delete branch after merge (usually automatic).
+
+```bash
+git branch -d {branch-name}           # Local
+git push origin --delete {branch-name} # Remote (if not auto-deleted)
+```text
+
+## Commit Message Standards
+
+Use conventional commit format:
+
+```text
+type: brief description
+
+Detailed explanation if needed.
+Fixes #123
+```text
+
+| Type | Usage |
+|------|-------|
+| `feat:` | New feature |
+| `fix:` | Bug fix |
+| `refactor:` | Code restructure |
+| `docs:` | Documentation |
+| `chore:` | Maintenance |
+| `test:` | Tests |
+
+## Keeping Branch Updated
+
+If `main` has been updated while you're working:
+
+```bash
+git checkout main
+git pull origin main
+git checkout your-branch
+git merge main
+# Resolve conflicts if any
+```text
+
+## Safety: Protecting Uncommitted Work
+
+**Before destructive operations** (reset, clean, rebase, checkout with changes):
+
+```bash
+# Protect ALL work including untracked files
+git stash --include-untracked -m "safety: before [operation]"
+
+# After operation, restore if needed
+git stash pop
+```text
+
+**Why this matters**: `git restore` only recovers tracked files. Untracked new files are permanently lost without stash.
+
+**Safe workflow**:
+1. `git stash --include-untracked` before risky operations
+2. Perform operation
+3. `git stash pop` to restore work
+4. If stash conflicts, `git stash show -p` to review
+
+## Full Workflow Chain
+
+```text
+┌─────────────────────────────────────────────────────────────────────────┐
+│  1. Create    2. Develop    3. Preflight    4. Version    5. Push      │
+│  branch.md    branch/*.md   preflight.md    version-bump  (git push)   │
+│                                             changelog.md               │
+├─────────────────────────────────────────────────────────────────────────┤
+│  6. PR           7. Review      8. Merge       9. Release   10. Post   │
+│  pull-request    code-review    (gh pr merge)  release.md   postflight │
+├─────────────────────────────────────────────────────────────────────────┤
+│  11. Cleanup - Delete branch after merge                               │
+└─────────────────────────────────────────────────────────────────────────┘
+```text
+
+### Lifecycle Summary
+
+| Stage | Action | Agent/Command | Required |
+|-------|--------|---------------|----------|
+| 1 | Create branch | `branch.md`, `branch/{type}.md` | Yes |
+| 2 | Develop | Domain agents, conventional commits | Yes |
+| 3 | Preflight | `preflight.md`, `linters-local.sh` | Yes |
+| 4 | Version | `version-bump.md`, `changelog.md` | For releases |
+| 5 | Push | `git push -u origin HEAD` | Yes |
+| 6 | PR | `pull-request.md` | Yes |
+| 7 | Review | `code-review.md` | Yes |
+| 8 | Merge | `gh pr merge --squash` | Yes |
+| 9 | Release | `release.md` | For releases |
+| 10 | Postflight | `postflight.md` | For releases |
+| 11 | Cleanup | Delete branch | Yes |
+
+## Related Workflows
+
+- **Pull requests**: `workflows/pr.md` (review before merge)
+- **Preflight**: `workflows/preflight.md` (quality checks before release)
+- **Version bumping**: `workflows/version-bump.md`
+- **Changelog**: `workflows/changelog.md`
+- **Creating releases**: `workflows/release.md`
+- **Postflight**: `workflows/postflight.md` (verify after release)
+- **Code review**: `workflows/code-audit-remote.md`

package/.agent/workflows/bug-fixing.md

@@ -0,0 +1,267 @@
+---
+description: Guidance for AI assistants to help with bug fixing workflows
+mode: subagent
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  glob: true
+  grep: true
+  webfetch: false
+  task: true
+---
+
+# Bug Fixing Guide for AI Assistants
+
+This document provides guidance for AI assistants to help with bug fixing workflows.
+
+## Bug Fixing Workflow
+
+### 1. Create a Bug Fix Branch
+
+Always start from the latest main branch (mandatory):
+
+```bash
+git checkout main
+git pull origin main
+git checkout -b fix/bug-description
+```
+
+Use descriptive names that indicate what bug is being fixed. Include issue numbers when available:
+
+```bash
+git checkout -b fix/123-plugin-activation-error
+git checkout -b fix/api-timeout-handling
+git checkout -b fix/null-pointer-exception
+```
+
+### 2. Understand the Bug
+
+Before fixing, understand:
+
+| Question | Why It Matters |
+|----------|----------------|
+| What is the expected behavior? | Defines the goal |
+| What is the actual behavior? | Clarifies the problem |
+| Steps to reproduce? | Enables testing |
+| What is the impact? | Prioritizes the fix |
+| What is the root cause? | Prevents symptom-only fixes |
+
+### 3. Fix the Bug
+
+When implementing the fix:
+
+- Make **minimal changes** necessary to fix the bug
+- **Avoid introducing new features** while fixing bugs
+- **Maintain backward compatibility**
+- Add appropriate **comments explaining the fix**
+- Consider adding **tests to prevent regression**
+
+### 4. Update Documentation
+
+Update relevant documentation:
+
+```markdown
+# CHANGELOG.md - Add under "Unreleased" section
+## [Unreleased]
+### Fixed
+- Fixed issue where X caused Y (#123)
+```
+
+Update readme/docs if the bug fix affects user-facing functionality.
+
+### 5. Testing
+
+Test the fix thoroughly:
+
+- [ ] Verify the bug is fixed
+- [ ] Ensure no regression in related functionality
+- [ ] Test with latest supported versions
+- [ ] Test with minimum supported versions
+- [ ] Run automated test suite
+- [ ] Run quality checks
+
+```bash
+# Run tests
+npm test
+composer test
+
+# Run quality checks
+bash ~/Git/aidevops/.agent/scripts/linters-local.sh
+```
+
+### 6. Commit Changes
+
+Make atomic commits with clear messages:
+
+```bash
+git add .
+git commit -m "Fix #123: Brief description of the bug fix
+
+- Detailed explanation of what was wrong
+- How this commit fixes it
+- Any side effects or considerations"
+```
+
+### 7. Version Determination
+
+After fixing and confirming the fix works, determine version increment:
+
+| Increment | When to Use | Example |
+|-----------|-------------|---------|
+| **PATCH** | Most bug fixes (no functionality change) | 1.6.0 -> 1.6.1 |
+| **MINOR** | Bug fixes with new features or significant changes | 1.6.0 -> 1.7.0 |
+| **MAJOR** | Bug fixes with breaking changes | 1.6.0 -> 2.0.0 |
+
+**Important:** Don't update version numbers during development. Only create version branches when the fix is confirmed working.
+
+### 8. Prepare for Release
+
+When ready for release:
+
+```bash
+# Create version branch
+git checkout -b v{MAJOR}.{MINOR}.{PATCH}
+
+# Merge fix branch
+git merge fix/bug-description --no-ff
+
+# Update version numbers in all required files
+# Commit version updates
+git add .
+git commit -m "Version {VERSION} - Bug fix release"
+```
+
+## Hotfix Process
+
+For critical bugs requiring immediate release:
+
+### 1. Create Hotfix Branch from Tag
+
+```bash
+# Find the current release tag
+git tag -l "v*" --sort=-v:refname | head -5
+
+# Create hotfix branch from that tag
+git checkout v{MAJOR}.{MINOR}.{PATCH}
+git checkout -b hotfix/v{MAJOR}.{MINOR}.{PATCH+1}
+```
+
+### 2. Apply Minimal Fix
+
+Apply only the essential fix for the critical issue.
+
+### 3. Update Version Numbers
+
+Increment PATCH version in all files:
+
+- Main application file (version constant/header)
+- CHANGELOG.md
+- README.md / readme.txt
+- Package files (package.json, composer.json)
+- Language/localization files if applicable
+
+### 4. Commit and Tag
+
+```bash
+git add .
+git commit -m "Hotfix: Critical bug description"
+git tag -a v{MAJOR}.{MINOR}.{PATCH+1} -m "Hotfix release"
+```
+
+### 5. Push Hotfix
+
+```bash
+git push origin hotfix/v{MAJOR}.{MINOR}.{PATCH+1}
+git push origin v{MAJOR}.{MINOR}.{PATCH+1}
+```
+
+### 6. Merge to Main
+
+```bash
+git checkout main
+git merge hotfix/v{MAJOR}.{MINOR}.{PATCH+1} --no-ff
+git push origin main
+```
+
+## Common Bug Types and Strategies
+
+### Null/Undefined Errors
+
+```javascript
+// Before: Crashes if user is null
+const name = user.name;
+
+// After: Safe access with fallback
+const name = user?.name ?? 'Unknown';
+```
+
+### Race Conditions
+
+- Add proper async/await handling
+- Use locks or semaphores where needed
+- Ensure proper initialization order
+
+### Memory Leaks
+
+- Clean up event listeners
+- Clear timers and intervals
+- Release references when done
+
+### API/Network Errors
+
+- Add proper error handling
+- Implement retries with backoff
+- Add timeout handling
+- Validate responses before use
+
+### Security Issues
+
+- Validate and sanitize all inputs
+- Escape all outputs
+- Use parameterized queries
+- Check permissions/capabilities
+
+## Testing Previous Versions
+
+To test against a previous version:
+
+```bash
+# Checkout specific tag
+git checkout v{MAJOR}.{MINOR}.{PATCH}
+
+# Or create test branch from tag
+git checkout v{MAJOR}.{MINOR}.{PATCH} -b test/some-issue
+```
+
+## Rollback Procedure
+
+If a fix causes issues after release:
+
+```bash
+# Find last stable version
+git tag -l "*-stable" --sort=-v:refname | head -5
+
+# Create fix branch from stable
+git checkout v{VERSION}-stable
+git checkout -b fix/rollback-based-fix
+
+# Apply corrected fix
+# Test thoroughly
+# Create new version when confirmed
+```
+
+## Bug Fix Checklist
+
+Before marking a bug fix as complete:
+
+- [ ] Root cause identified and documented
+- [ ] Fix is minimal and focused
+- [ ] No new features introduced
+- [ ] Tests added to prevent regression
+- [ ] All existing tests pass
+- [ ] Quality checks pass
+- [ ] Documentation updated
+- [ ] Changelog updated
+- [ ] Ready for code review