aidevops 2.52.1

package/.agent/workflows/branch/experiment.md

@@ -0,0 +1,115 @@
+---
+description: Experiment branch - spike, POC, may not merge
+mode: subagent
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  glob: true
+  grep: true
+---
+
+# Experiment Branch
+
+<!-- AI-CONTEXT-START -->
+
+| Aspect | Value |
+|--------|-------|
+| **Prefix** | `experiment/` |
+| **Commit** | `experiment:` or `spike:` |
+| **Version** | None (experiments don't get released) |
+| **Create from** | `main` |
+| **Key rule** | May never merge - that's okay |
+
+```bash
+git checkout main && git pull origin main
+git checkout -b experiment/{description}
+```
+
+<!-- AI-CONTEXT-END -->
+
+## When to Use
+
+- Proof of concept (POC)
+- Technical spikes
+- Exploring new approaches
+- Testing third-party integrations
+- Performance experiments
+- Architecture exploration
+- "What if we tried..." investigations
+
+**Key difference**: Experiments may never merge, and that's a valid outcome.
+
+## The Experiment Mindset
+
+Experiments are about **learning**, not shipping:
+
+- **Success** = You learned something valuable
+- **Failure** = You learned what doesn't work (also valuable)
+- **Abandoned** = Priorities changed (document why)
+
+## Unique Guidance
+
+### Document the Hypothesis
+
+Before starting, document what you're testing:
+
+```bash
+experiment: test GraphQL for API layer
+
+Hypothesis: GraphQL could reduce API calls by 60%
+
+Testing:
+- Set up Apollo Server
+- Migrate 3 endpoints
+- Measure performance
+```
+
+### Document Results (Even If Not Merging)
+
+When experiment concludes, document in PR:
+
+```markdown
+## Experiment: GraphQL Migration
+
+### Hypothesis
+GraphQL could reduce API calls by 60%
+
+### What We Tried
+- Migrated user, posts, and comments endpoints
+- Implemented DataLoader for batching
+
+### Results
+- API calls reduced by 45% (not 60%)
+- Complexity increased significantly
+- Team learning curve is steep
+
+### Conclusion
+**Not proceeding** - benefits don't outweigh costs.
+
+### Learnings
+- GraphQL works well for complex nested data
+- Our API is mostly flat, so benefit is limited
+- Consider for future mobile app API
+```
+
+### Transitioning to Feature
+
+If experiment succeeds and should be productionized:
+
+1. **Don't merge experiment directly**
+2. Create new `feature/` branch from `main`
+3. Cherry-pick or reimplement cleanly
+4. Follow normal feature workflow
+5. Reference experiment branch in PR for context
+
+## Examples
+
+```bash
+experiment/graphql-migration
+experiment/redis-caching
+experiment/serverless-functions
+experiment/lazy-loading-images
+experiment/microservices-split
+```

package/.agent/workflows/branch/feature.md

@@ -0,0 +1,59 @@
+---
+description: Feature branch - new functionality
+mode: subagent
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  glob: true
+  grep: true
+---
+
+# Feature Branch
+
+<!-- AI-CONTEXT-START -->
+
+| Aspect | Value |
+|--------|-------|
+| **Prefix** | `feature/` |
+| **Commit** | `feat: description` |
+| **Version** | Minor bump (1.0.0 → 1.1.0) |
+| **Create from** | `main` |
+
+```bash
+git checkout main && git pull origin main
+git checkout -b feature/{description}
+```
+
+<!-- AI-CONTEXT-END -->
+
+## When to Use
+
+- New functionality or capabilities
+- New integrations
+- Significant enhancements
+
+## Unique Guidance
+
+For detailed feature implementation patterns, see `workflows/feature-development.md`.
+
+## Examples
+
+```bash
+feature/user-dashboard
+feature/123-api-rate-limiting
+feature/export-to-csv
+```
+
+## Commit Example
+
+```bash
+feat: add user authentication
+
+- Implement OAuth2 flow
+- Add session management
+- Create login/logout endpoints
+
+Closes #123
+```

package/.agent/workflows/branch/hotfix.md

@@ -0,0 +1,98 @@
+---
+description: Hotfix branch - urgent production fixes
+mode: subagent
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  glob: true
+  grep: true
+---
+
+# Hotfix Branch
+
+<!-- AI-CONTEXT-START -->
+
+| Aspect | Value |
+|--------|-------|
+| **Prefix** | `hotfix/` |
+| **Commit** | `fix: [HOTFIX] description` |
+| **Version** | Patch bump (1.0.0 → 1.0.1) |
+| **Create from** | **Latest tag** (not main) |
+| **Urgency** | Immediate - bypasses normal review if needed |
+
+```bash
+git fetch --tags
+git checkout $(git describe --tags --abbrev=0)
+git checkout -b hotfix/{description}
+```
+
+<!-- AI-CONTEXT-END -->
+
+## When to Use
+
+- Critical production bugs
+- Security vulnerabilities
+- Data corruption issues
+- Service outages
+
+**If it can wait for normal release cycle**, use `bugfix/` instead.
+
+## Unique Guidance
+
+### Create from Latest Tag (Not Main)
+
+This ensures the hotfix applies to what's actually in production:
+
+```bash
+git fetch --tags
+git checkout $(git describe --tags --abbrev=0)
+git checkout -b hotfix/critical-issue
+```
+
+### Expedited Process
+
+1. Apply **minimal fix** - only what's needed
+2. Test immediately
+3. Fast-track review (or deploy directly if authorized)
+4. **Merge back to main** after deployment
+
+### Post-Hotfix Checklist
+
+After deploying:
+- [ ] Ensure fix is merged to `main`
+- [ ] Create proper regression tests
+- [ ] Document incident
+- [ ] Review how issue was missed
+
+## Examples
+
+```bash
+hotfix/critical-auth-bypass
+hotfix/production-database-lock
+hotfix/payment-processing-failure
+```
+
+## Commit Example
+
+```bash
+fix: [HOTFIX] prevent authentication bypass
+
+CRITICAL SECURITY FIX
+- Add missing permission check
+- Validate session token
+
+Deploy immediately. Full audit to follow.
+```
+
+## Merge Back to Main
+
+After deployment:
+
+```bash
+git checkout main
+git pull origin main
+git merge hotfix/critical-issue
+git push origin main
+```

package/.agent/workflows/branch/refactor.md

@@ -0,0 +1,92 @@
+---
+description: Refactor branch - code restructure, same behavior
+mode: subagent
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  glob: true
+  grep: true
+---
+
+# Refactor Branch
+
+<!-- AI-CONTEXT-START -->
+
+| Aspect | Value |
+|--------|-------|
+| **Prefix** | `refactor/` |
+| **Commit** | `refactor: description` |
+| **Version** | Usually none (no behavior change) |
+| **Create from** | `main` |
+
+```bash
+git checkout main && git pull origin main
+git checkout -b refactor/{description}
+```
+
+<!-- AI-CONTEXT-END -->
+
+## When to Use
+
+- Code restructuring without behavior change
+- Extracting reusable components
+- Improving code organization
+- Reducing technical debt
+- Performance improvements (same behavior, faster)
+
+**Not for**: Bug fixes (use `bugfix/`) or new features (use `feature/`).
+
+## The Golden Rule
+
+> **Same inputs → Same outputs**
+
+If behavior changes, it's not a refactor. Either:
+- Split into separate `bugfix/` or `feature/` branch
+- Document the intentional behavior change
+
+## Unique Guidance
+
+### Extra Testing Scrutiny
+
+Refactors require **extra testing scrutiny**:
+
+- [ ] All existing tests pass (mandatory)
+- [ ] No new test failures
+- [ ] Manual verification of key flows
+- [ ] Performance not degraded (if applicable)
+
+### Ensure Tests Pass Before Starting
+
+```bash
+npm test  # or project-specific test command
+```
+
+### PR Review Focus
+
+Reviewers should verify:
+1. No behavior changes (unless documented)
+2. Tests still pass
+3. Code is actually cleaner/better
+4. No hidden bugs introduced
+
+## Examples
+
+```bash
+refactor/extract-auth-service
+refactor/simplify-database-layer
+refactor/consolidate-api-handlers
+```
+
+## Commit Example
+
+```bash
+refactor: extract authentication into dedicated service
+
+- Move auth logic from UserController to AuthService
+- No behavior changes
+- All existing tests pass
+
+This improves testability and separation of concerns.
+```

package/.agent/workflows/branch/release.md

@@ -0,0 +1,96 @@
+---
+description: Release branch - version preparation
+mode: subagent
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  glob: true
+  grep: true
+---
+
+# Release Branch
+
+<!-- AI-CONTEXT-START -->
+
+| Aspect | Value |
+|--------|-------|
+| **Prefix** | `release/` |
+| **Naming** | `release/{MAJOR}.{MINOR}.{PATCH}` |
+| **Commit** | `chore(release): v{version}` |
+| **Create from** | `main` (or latest stable) |
+| **Merge to** | `main` via PR, then tag |
+
+```bash
+git checkout main && git pull origin main
+git checkout -b release/1.2.0
+```
+
+<!-- AI-CONTEXT-END -->
+
+## When to Create
+
+| Scenario | Action |
+|----------|--------|
+| Features ready for release | Create `release/X.Y.0` |
+| Bug fixes accumulated | Create `release/X.Y.Z` (patch) |
+| Breaking changes ready | Create `release/X+1.0.0` |
+| Hotfix needed | Use `hotfix/` branch instead |
+
+## Unique Guidance
+
+### Version Selection
+
+| Change Type | Version Bump | Example |
+|-------------|--------------|---------|
+| Bug fixes only | Patch | 1.2.3 → 1.2.4 |
+| New features (backward compatible) | Minor | 1.2.3 → 1.3.0 |
+| Breaking changes | Major | 1.2.3 → 2.0.0 |
+
+### Release Lifecycle
+
+1. **Create release branch**
+2. **Update version files**: `.agent/scripts/version-manager.sh bump {type}`
+3. **Update CHANGELOG.md**
+4. **Final testing**: `.agent/scripts/linters-local.sh`
+5. **Create PR to main**
+6. **Merge and tag**
+7. **Create GitHub release**
+8. **Run postflight**
+
+### Cherry-Picking (If Needed)
+
+```bash
+# List unmerged feature branches
+git branch --no-merged main | grep -E "^  (feature|bugfix)/"
+
+# Cherry-pick specific commits
+git cherry-pick {commit-hash}
+```
+
+### Tag and Release
+
+```bash
+# After PR merged
+git checkout main && git pull
+git tag -a v{VERSION} -m "Release v{VERSION}"
+git push origin v{VERSION}
+gh release create v{VERSION} --generate-notes
+```
+
+## Difference from Hotfix
+
+| Aspect | Release Branch | Hotfix Branch |
+|--------|----------------|---------------|
+| Urgency | Planned | Urgent |
+| Source | `main` | Latest tag |
+| Content | Multiple features/fixes | Single critical fix |
+| Testing | Full test cycle | Minimal, focused |
+
+## Related
+
+- `workflows/version-bump.md` - Version file management
+- `workflows/release.md` - Full release process
+- `workflows/changelog.md` - Changelog format
+- `workflows/postflight.md` - Post-release verification