aidevops 2.52.1 → 2.53.2

package/.agent/workflows/branch.md

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

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