ci(workflows): add automatic release creation and smart commit analysis (#61)

Why: Version bumps were happening but tags/releases weren't being created Impact: - After version bump PRs merge, tags and releases will be created automatically - commit-openagents command now analyzes repo health before commits - Detects missing releases, stale branches, and workflow issues Changes: - New workflow: create-release.yml (auto-creates tags & releases) - Workflow audit: WORKFLOW_AUDIT.md (complete documentation) - Enhanced: commit-openagents command with smart repo analysis Testing: Will manually trigger workflow to create v0.5.0 release
2025-12-18 14:08:09 +00:00 · 2025-12-18 14:08:09 +00:00 · 87b980fb6a
commit 87b980fb6a
parent 25041f77fb
3 changed files with 630 additions and 17 deletions
--- a/.github/workflows/WORKFLOW_AUDIT.md
+++ b/.github/workflows/WORKFLOW_AUDIT.md
@ -0,0 +1,156 @@
+# Workflow Audit Report
+
+**Date:** 2025-12-18  
+**Status:** ✅ Completed
+
+## Summary
+
+Comprehensive audit of GitHub Actions workflows to identify issues and streamline automation.
+
+## Key Findings
+
+### 🔴 Critical Issue: Missing Tags & Releases
+
+**Problem:** Version bumps were happening (VERSION file at 0.5.0) but no git tags or GitHub releases were being created.
+
+**Root Cause:** The `post-merge-pr.yml` workflow creates PRs for version bumps but doesn't create tags/releases. The disabled `post-merge.yml.disabled` had this functionality but was disabled to avoid direct pushes to main.
+
+**Solution:** Created new `create-release.yml` workflow that:
+- Detects when version bump PRs are merged (by checking for `version-bump` label)
+- Creates git tags automatically
+- Creates GitHub releases with CHANGELOG notes
+- Supports manual triggering for backfilling missing releases
+
+### ✅ Working Well
+
+1. **PR Checks** (`pr-checks.yml`)
+   - Validates conventional commit format
+   - Runs build & validation
+   - Clear feedback to contributors
+   - **No changes needed**
+
+2. **Registry Workflows**
+   - `validate-registry.yml` - Validates on PRs, handles forks gracefully
+   - `update-registry.yml` - Auto-updates registry on main
+   - **Both working great, no changes needed**
+
+3. **Version Bump Workflow** (`post-merge-pr.yml`)
+   - Creates PRs for version bumps
+   - Updates VERSION, package.json, CHANGELOG.md
+   - Good loop prevention
+   - **Working well, just needed tag/release creation added**
+
+### ⚠️ Potentially Overkill
+
+**Docs Sync** (`sync-docs.yml`)
+- Creates GitHub issues for OpenCode to process
+- Creates branches and waits for manual PR creation
+- May be more complex than needed
+- **Recommendation:** Consider simplifying or making optional
+
+## Changes Made
+
+### 1. New Workflow: `create-release.yml`
+
+**Purpose:** Automatically create git tags and GitHub releases after version bump PRs are merged.
+
+**Features:**
+- Detects version bump PR merges by checking for `version-bump` label
+- Reads version from VERSION file
+- Creates git tag (e.g., `v0.5.0`)
+- Extracts release notes from CHANGELOG.md
+- Creates GitHub release with notes
+- Idempotent - checks if tag/release already exists
+- Manual trigger support for backfilling
+
+**Workflow:**
+```
+Version Bump PR Merged → Detect Label → Read VERSION → Create Tag → Create Release
+```
+
+### 2. Documentation
+
+Created this audit report documenting:
+- Current workflow state
+- Issues found
+- Solutions implemented
+- Recommendations for future improvements
+
+## Workflow Inventory
+
+| Workflow | Status | Purpose | Changes |
+|----------|--------|---------|---------|
+| `create-release.yml` | ✅ NEW | Create tags & releases | New workflow |
+| `post-merge-pr.yml` | ✅ Active | Version bump PRs | No changes |
+| `post-merge.yml.disabled` | ❌ Disabled | Old direct push approach | Can be deleted |
+| `pr-checks.yml` | ✅ Active | PR validation | No changes |
+| `validate-registry.yml` | ✅ Active | Registry validation on PRs | No changes |
+| `update-registry.yml` | ✅ Active | Auto-update registry | No changes |
+| `sync-docs.yml` | ✅ Active | Sync docs via OpenCode | No changes |
+| `validate-test-suites.yml` | ✅ Active | Validate test YAML | No changes |
+
+## Next Steps
+
+### Immediate
+
+1. ✅ Create `create-release.yml` workflow
+2. ⏳ Commit and push to trigger workflow
+3. ⏳ Manually trigger workflow to create missing releases:
+   - v0.4.0 (if needed)
+   - v0.5.0
+
+### Future Improvements (Optional)
+
+1. **Simplify Docs Sync**
+   - Consider direct updates instead of issue-based approach
+   - Or make it manual-trigger only
+
+2. **Cleanup**
+   - Delete `post-merge.yml.disabled`
+   - Clean up stale automation branches
+   - Archive old workflow documentation
+
+3. **Documentation**
+   - Add workflow documentation to README
+   - Create troubleshooting guide
+   - Document manual release process
+
+## Testing Plan
+
+1. **Test New Workflow:**
+   - Manually trigger `create-release.yml` with version 0.5.0
+   - Verify tag creation
+   - Verify release creation
+   - Check release notes formatting
+
+2. **Test Automatic Trigger:**
+   - Wait for next version bump PR to merge
+   - Verify workflow triggers automatically
+   - Verify tag and release created
+
+## Recommendations
+
+### Keep Simple
+
+The current PR-based approach is working well. The new `create-release.yml` workflow completes the automation without adding complexity.
+
+### Avoid Over-Engineering
+
+- Don't add more automation unless there's a clear pain point
+- Keep workflows focused and single-purpose
+- Prefer manual triggers for infrequent operations
+
+### Monitor & Iterate
+
+- Watch for workflow failures
+- Gather feedback from contributors
+- Adjust based on actual usage patterns
+
+## Conclusion
+
+✅ **Critical issue fixed:** Tags and releases will now be created automatically  
+✅ **Minimal changes:** Only added one new workflow  
+✅ **Existing workflows:** All working well, no changes needed  
+✅ **Simple & maintainable:** Easy to understand and debug  
+
+The workflow system is now complete and should handle version management automatically while keeping the PR-based approval process you prefer.
--- a/.github/workflows/create-release.yml
+++ b/.github/workflows/create-release.yml
@ -0,0 +1,209 @@
+name: Create Release
+
+# This workflow creates git tags and GitHub releases after version bump PRs are merged.
+# It detects when a version bump PR (with 'version-bump' label) is merged and creates
+# the corresponding tag and release automatically.
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to release (e.g., 0.5.0)'
+        required: false
+        type: string
+
+permissions:
+  contents: write
+
+jobs:
+  check-if-version-bump:
+    name: Check if Version Bump PR Merged
+    runs-on: ubuntu-latest
+    outputs:
+      should_release: ${{ steps.check.outputs.should_release }}
+      version: ${{ steps.check.outputs.version }}
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+      
+      - name: Check if this was a version bump PR merge
+        id: check
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            
+            // Manual trigger - use provided version
+            if (context.eventName === 'workflow_dispatch' && context.payload.inputs.version) {
+              core.setOutput('should_release', 'true');
+              core.setOutput('version', context.payload.inputs.version);
+              console.log(`Manual release triggered for version: ${context.payload.inputs.version}`);
+              return;
+            }
+            
+            // Get the commit that triggered this workflow
+            const commit = context.sha;
+            
+            // Find PRs that were merged with this commit
+            const { data: prs } = await github.rest.repos.listPullRequestsAssociatedWithCommit({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              commit_sha: commit
+            });
+            
+            // Check if any of these PRs had the version-bump label
+            const versionBumpPR = prs.find(pr => 
+              pr.labels.some(label => label.name === 'version-bump')
+            );
+            
+            if (versionBumpPR) {
+              console.log(`Version bump PR detected: #${versionBumpPR.number}`);
+              
+              // Read VERSION file to get the new version
+              const version = fs.readFileSync('VERSION', 'utf8').trim();
+              
+              core.setOutput('should_release', 'true');
+              core.setOutput('version', version);
+              console.log(`Will create release for version: ${version}`);
+            } else {
+              console.log('Not a version bump PR - skipping release creation');
+              core.setOutput('should_release', 'false');
+            }
+
+  create-tag-and-release:
+    name: Create Git Tag and GitHub Release
+    runs-on: ubuntu-latest
+    needs: check-if-version-bump
+    if: needs.check-if-version-bump.outputs.should_release == 'true'
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+      
+      - name: Check if tag already exists
+        id: check_tag
+        run: |
+          VERSION="${{ needs.check-if-version-bump.outputs.version }}"
+          
+          if git rev-parse "v$VERSION" >/dev/null 2>&1; then
+            echo "tag_exists=true" >> $GITHUB_OUTPUT
+            echo "⚠️ Tag v$VERSION already exists"
+          else
+            echo "tag_exists=false" >> $GITHUB_OUTPUT
+            echo "✅ Tag v$VERSION does not exist - will create"
+          fi
+      
+      - name: Create git tag
+        if: steps.check_tag.outputs.tag_exists == 'false'
+        run: |
+          VERSION="${{ needs.check-if-version-bump.outputs.version }}"
+          
+          echo "Creating tag: v$VERSION"
+          git tag "v$VERSION"
+          git push origin "v$VERSION"
+          
+          echo "## ✅ Git Tag Created" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "- **Tag:** v$VERSION" >> $GITHUB_STEP_SUMMARY
+          echo "- **Commit:** ${{ github.sha }}" >> $GITHUB_STEP_SUMMARY
+      
+      - name: Extract release notes from CHANGELOG
+        id: release_notes
+        run: |
+          VERSION="${{ needs.check-if-version-bump.outputs.version }}"
+          
+          if [ -f CHANGELOG.md ]; then
+            RELEASE_NOTES=$(awk '/^## \['"$VERSION"'\]/{flag=1; next} /^## \[/{flag=0} flag' CHANGELOG.md)
+            
+            if [ -z "$RELEASE_NOTES" ]; then
+              RELEASE_NOTES="Release v$VERSION
+
+          See [CHANGELOG.md](CHANGELOG.md) for details."
+            fi
+          else
+            RELEASE_NOTES="Release v$VERSION"
+          fi
+          
+          echo "$RELEASE_NOTES" > /tmp/release_notes.md
+          
+          echo "## 📝 Release Notes Preview" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+          cat /tmp/release_notes.md >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+      
+      - name: Check if release already exists
+        id: check_release
+        run: |
+          VERSION="${{ needs.check-if-version-bump.outputs.version }}"
+          
+          if gh release view "v$VERSION" >/dev/null 2>&1; then
+            echo "release_exists=true" >> $GITHUB_OUTPUT
+            echo "⚠️ Release v$VERSION already exists"
+          else
+            echo "release_exists=false" >> $GITHUB_OUTPUT
+            echo "✅ Release v$VERSION does not exist - will create"
+          fi
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      
+      - name: Create GitHub release
+        if: steps.check_release.outputs.release_exists == 'false'
+        run: |
+          VERSION="${{ needs.check-if-version-bump.outputs.version }}"
+          
+          echo "Creating GitHub release: v$VERSION"
+          
+          gh release create "v$VERSION" \
+            --title "v$VERSION" \
+            --notes-file /tmp/release_notes.md \
+            --latest
+          
+          echo "## 🚀 GitHub Release Created" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "- **Release:** v$VERSION" >> $GITHUB_STEP_SUMMARY
+          echo "- **URL:** https://github.com/${{ github.repository }}/releases/tag/v$VERSION" >> $GITHUB_STEP_SUMMARY
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      
+      - name: Summary
+        if: always()
+        run: |
+          VERSION="${{ needs.check-if-version-bump.outputs.version }}"
+          TAG_EXISTS="${{ steps.check_tag.outputs.tag_exists }}"
+          RELEASE_EXISTS="${{ steps.check_release.outputs.release_exists }}"
+          
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "---" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### 📊 Release Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Version:** v$VERSION" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          
+          if [ "$TAG_EXISTS" = "true" ]; then
+            echo "- ⏭️ Git tag already existed (skipped)" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "- ✅ Git tag created" >> $GITHUB_STEP_SUMMARY
+          fi
+          
+          if [ "$RELEASE_EXISTS" = "true" ]; then
+            echo "- ⏭️ GitHub release already existed (skipped)" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "- ✅ GitHub release created" >> $GITHUB_STEP_SUMMARY
+          fi
+          
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "🎉 **Release v$VERSION is now available!**" >> $GITHUB_STEP_SUMMARY
--- a/.opencode/command/commit-openagents.md
+++ b/.opencode/command/commit-openagents.md
@ -10,9 +10,67 @@ You are an AI agent that helps create well-formatted git commits specifically fo

 When the user runs this command, execute the following workflow:

-### 1. **Pre-Commit Validation (Optional)**
+### 1. **Smart Repo Analysis (Automatic)**

-**Ask user first:**
+**Before doing anything, analyze the repo state:**
+
+```bash
+# Check current branch and status
+git status
+git branch --show-current
+
+# Check for workflow issues
+git tag --sort=-v:refname | head -5  # Check recent tags
+cat VERSION  # Check current version
+git log --oneline -5  # Check recent commits
+
+# Check for stale automation branches
+git branch -a | grep -E "chore/version-bump|docs/auto-sync" | wc -l
+```
+
+**Intelligent Analysis:**
+- 🔍 **Version Sync Check**: Compare VERSION file with latest git tag
+  - If VERSION > latest tag → Suggest creating missing release
+  - If tags are missing → Offer to trigger release workflow
+- 🧹 **Branch Cleanup**: Detect stale automation branches
+  - Count `chore/version-bump-*` branches
+  - Count `docs/auto-sync-*` branches
+  - If > 3 stale branches → Suggest cleanup
+- 🔄 **Workflow Health**: Check if workflows are working
+  - Look for recent workflow runs
+  - Check for disabled workflows that might be needed
+- 📊 **Repo State**: Summarize current state
+  - Current branch
+  - Uncommitted changes
+  - Recent activity
+
+**Present Analysis:**
+```
+📊 Repo Health Check:
+- Current branch: <branch>
+- Version: <VERSION> | Latest tag: <tag>
+- Stale branches: <count> automation branches
+- Uncommitted changes: <count> files
+
+[If issues detected:]
+⚠️ Issues Found:
+- Missing release for v<VERSION> (tag not created)
+- <count> stale automation branches need cleanup
+
+Would you like to:
+1. Fix issues first (recommended)
+2. Continue with commit
+3. View detailed analysis
+```
+
+**If user chooses "Fix issues":**
+- Offer to trigger `create-release.yml` workflow for missing tags
+- Offer to clean up stale branches
+- Offer to audit workflows if problems detected
+
+### 2. **Pre-Commit Validation (Optional)**
+
+**Ask user:**
 ```
 Would you like to run smoke tests before committing? (y/n)
 - y: Run validation tests
@ -29,13 +87,17 @@ cd evals/framework && npm run eval:sdk -- --agent=core/opencoder --pattern="**/s
 - ⚠️ If tests fail, ask user if they want to proceed or fix issues first
 - ✅ Tests are optional - user can skip and commit directly

-### 2. **Analyze Changes**
+### 3. **Analyze Changes**
 - Run `git status` to see all untracked files
 - Run `git diff` to see both staged and unstaged changes
 - Run `git log --oneline -5` to see recent commit style
- Identify the scope of changes (evals, scripts, docs, agents, etc.)
+- Identify the scope of changes (evals, scripts, docs, agents, workflows, etc.)
+- **Special Detection**: Check if changes are workflow-related
+  - If `.github/workflows/` modified → Suggest workflow validation
+  - If new workflow added → Offer to document it
+  - If workflow disabled/deleted → Ask for confirmation

-### 3. **Stage Files Intelligently**
+### 4. **Stage Files Intelligently**
 **Auto-stage based on change type:**
 - If modifying evals framework → stage `evals/framework/`
 - If modifying core agents → stage `.opencode/agent/core/`
@ -59,7 +121,7 @@ cd evals/framework && npm run eval:sdk -- --agent=core/opencoder --pattern="**/s
 - `test_tmp/` or temporary directories
 - `evals/results/` (test results)

-### 4. **Generate Commit Message**
+### 5. **Generate Commit Message**

 **Follow Conventional Commits (NO EMOJIS):**
 ```
@ -115,7 +177,7 @@ feat(registry): add new agent categories
 ci: add automatic version bumping workflow
 ```

-### 5. **Commit Analysis**
+### 6. **Commit Analysis**

 <commit_analysis>
 - List all files that have been changed or added
@ -129,14 +191,14 @@ ci: add automatic version bumping workflow
 - Verify message is specific and not generic
 </commit_analysis>

-### 6. **Execute Commit**
+### 7. **Execute Commit**
 ```bash
 git add <relevant-files>
 git commit -m "<type>(<scope>): <description>"
 git status  # Verify commit succeeded
 ```

-### 7. **Post-Commit Actions**
+### 8. **Post-Commit Actions**

 **Ask user:**
 ```
@ -144,25 +206,155 @@ git status  # Verify commit succeeded
 📝 Message: <commit-message>

 Would you like to:
-1. Push to remote (git push origin main)
+1. Push to remote (git push origin <branch>)
 2. Create another commit
 3. Done
 ```

 **If user chooses push:**
 ```bash
-git push origin main
+git push origin <current-branch>
 ```

-**Then inform:**
+**Then inform based on commit type:**
+
+**For workflow changes (`.github/workflows/`):**
+```
+🚀 Pushed workflow changes!
+
+This will trigger:
+- Workflow validation on PR
+- Registry validation
+- PR checks
+
+⚠️ Important:
+- New workflows won't run until merged to main
+- Test workflows using workflow_dispatch if available
+- Check GitHub Actions tab for workflow syntax errors
+```
+
+**For feature/fix commits to main:**
+```
+🚀 Pushed to main!
+
+This will trigger:
+- Post-merge version bump workflow
+- Create version bump PR automatically
+- Update VERSION, package.json, CHANGELOG.md
+- After version bump PR merges → Create git tag & release
+
+Expected flow:
+1. Your commit merged ✅
+2. Version bump PR created (automated)
+3. Review & merge version bump PR
+4. Git tag & GitHub release created automatically
+```
+
+**For other commits:**
 ```
 🚀 Pushed to remote!

 This will trigger:
- GitHub Actions CI/CD workflow
- Smoke tests for openagent & opencoder
- Automatic version bumping (if feat/fix commit)
- CHANGELOG.md update
+- PR checks (if on feature branch)
+- Registry validation
+- Build & test validation
+```
+
+## Workflow Management (Smart Automation)
+
+### Automatic Workflow Analysis
+
+When committing workflow changes or when issues are detected, provide intelligent guidance:
+
+**1. Version & Release Sync**
+```bash
+# Check if version and tags are in sync
+VERSION=$(cat VERSION)
+LATEST_TAG=$(git tag --sort=-v:refname | head -1)
+
+if [ "v$VERSION" != "$LATEST_TAG" ]; then
+  echo "⚠️ Version mismatch detected!"
+  echo "VERSION file: $VERSION"
+  echo "Latest tag: $LATEST_TAG"
+  echo ""
+  echo "Would you like to:"
+  echo "1. Trigger create-release workflow to create v$VERSION tag/release"
+  echo "2. Manually create tag: git tag v$VERSION && git push origin v$VERSION"
+  echo "3. Ignore (version bump PR may be pending)"
+fi
+```
+
+**2. Stale Branch Cleanup**
+```bash
+# Detect stale automation branches
+STALE_BRANCHES=$(git branch -a | grep -E "chore/version-bump|docs/auto-sync" | wc -l)
+
+if [ "$STALE_BRANCHES" -gt 3 ]; then
+  echo "🧹 Found $STALE_BRANCHES stale automation branches"
+  echo ""
+  echo "Would you like to clean them up?"
+  echo "1. Yes - delete merged automation branches"
+  echo "2. No - keep them"
+  echo "3. Show me the branches first"
+fi
+```
+
+**3. Workflow Health Check**
+```bash
+# Check for common workflow issues
+if [ -f .github/workflows/post-merge.yml.disabled ]; then
+  echo "ℹ️ Found disabled workflow: post-merge.yml.disabled"
+  echo "This workflow has been replaced by post-merge-pr.yml + create-release.yml"
+  echo ""
+  echo "Would you like to delete it? (cleanup)"
+fi
+
+# Check if create-release.yml exists
+if [ ! -f .github/workflows/create-release.yml ]; then
+  echo "⚠️ Missing create-release.yml workflow"
+  echo "Tags and releases won't be created automatically!"
+  echo ""
+  echo "Would you like to create it?"
+fi
+```
+
+**4. Workflow Documentation**
+
+When new workflows are added, offer to update documentation:
+```
+✅ New workflow detected: <workflow-name>.yml
+
+Would you like to:
+1. Add entry to .github/workflows/WORKFLOW_AUDIT.md
+2. Update README.md with workflow info
+3. Skip documentation (do it later)
+```
+
+### Workflow Commit Best Practices
+
+**For workflow changes, always:**
+- Test workflow syntax before committing
+- Document what the workflow does
+- Explain why changes were made
+- Note any breaking changes
+- Update workflow audit documentation
+
+**Commit message format for workflows:**
+```
+ci(workflows): <what changed>
+
+Why: <reason for change>
+Impact: <what this affects>
+Testing: <how to test>
+```
+
+**Example:**
+```
+ci(workflows): add automatic release creation workflow
+
+Why: Version bumps were happening but tags/releases weren't being created
+Impact: After version bump PRs merge, tags and releases will be created automatically
+Testing: Manually trigger workflow with: gh workflow run create-release.yml
 ```

 ## Repository-Specific Rules
@ -232,18 +424,74 @@ Conflicted files:
 Run: git status
 ```

+## Active Workflows in This Repo
+
+**Understanding the automation:**
+
+1. **create-release.yml** ✅ NEW
+   - Triggers: After version bump PRs merge (detects `version-bump` label)
+   - Creates: Git tags and GitHub releases
+   - Manual: Can trigger via `gh workflow run create-release.yml`
+
+2. **post-merge-pr.yml** ✅ Active
+   - Triggers: Push to main
+   - Creates: Version bump PR (updates VERSION, package.json, CHANGELOG.md)
+   - Skips: If commit has `version-bump` or `automated` label
+
+3. **pr-checks.yml** ✅ Active
+   - Triggers: Pull requests
+   - Validates: PR title format, builds framework, runs tests
+   - Required: Must pass before merge
+
+4. **validate-registry.yml** ✅ Active
+   - Triggers: Pull requests
+   - Validates: Registry.json, prompt library structure
+   - Auto-fixes: Adds new components to registry
+
+5. **update-registry.yml** ✅ Active
+   - Triggers: Push to main (when .opencode/ changes)
+   - Updates: Registry.json automatically
+   - Direct push: No PR needed
+
+6. **sync-docs.yml** ✅ Active
+   - Triggers: Push to main (when registry/components change)
+   - Creates: GitHub issue for OpenCode to sync docs
+   - Optional: Can be simplified if too complex
+
+7. **validate-test-suites.yml** ✅ Active
+   - Triggers: Pull requests (when evals/ changes)
+   - Validates: YAML test files
+   - Required: Must pass before merge
+
+**Workflow Flow for Version Bumps:**
+```
+1. Merge feat/fix PR to main
+   ↓
+2. post-merge-pr.yml creates version bump PR
+   ↓
+3. Review & merge version bump PR
+   ↓
+4. create-release.yml creates tag & release
+   ↓
+5. Done! 🎉
+```
+
 ## Agent Behavior Notes

+- **Repo health first** - Always run smart analysis before committing
+- **Workflow awareness** - Understand which workflows will trigger
 - **Optional validation** - Ask user if they want to run smoke tests (not mandatory)
 - **Smart staging** - Only stage relevant files based on change scope and category structure
 - **Conventional commits** - Strictly follow conventional commit format (NO EMOJIS)
 - **Scope awareness** - Use appropriate scope for this repository (include category paths)
- **Version awareness** - Inform user about automatic version bumping
+- **Version awareness** - Inform user about automatic version bumping and release creation
 - **CI/CD awareness** - Remind user that push triggers automated workflows
 - **Security** - Never commit sensitive information (API keys, tokens, .env files)
 - **Atomic commits** - Each commit should have a single, clear purpose
 - **Push guidance** - Always ask before pushing to remote
 - **Category-aware** - Recognize new agent organization (core, development, content, data, meta, learning, product)
+- **Cleanup suggestions** - Offer to clean up stale branches and disabled workflows
+- **Documentation** - Suggest updating workflow docs when workflows change

 ## Quick Reference