feat: enhance direct push workflow with auto-detect and validation

- Updated update-registry.yml to use auto-detect-components.sh
- Added validation step for direct pushes to main
- Shows warnings (doesn't block) if validation fails on direct push
- Created comprehensive WORKFLOW_GUIDE.md documenting both workflows
- PR workflow: Auto-detect → Validate → BLOCK if invalid
- Push workflow: Auto-detect → Validate → WARN if invalid

.github/workflows/update-registry.yml

@@ -1,4 +1,4 @@
-name: Update Component Registry
+name: Update Component Registry (Direct Push)
 
 on:
   push:
@@ -11,10 +11,9 @@ on:
 
 permissions:
   contents: write
-  pull-requests: write
 
 jobs:
-  update-registry:
+  update-and-validate-registry:
     runs-on: ubuntu-latest
     
     steps:
@@ -28,37 +27,93 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y jq
       
-      - name: Run component registration
+      - name: Make scripts executable
         run: |
+          chmod +x scripts/validate-registry.sh
+          chmod +x scripts/auto-detect-components.sh
           chmod +x scripts/register-component.sh
-          ./scripts/register-component.sh
       
-      - name: Check for changes
-        id: check_changes
+      - name: Auto-detect new components
+        id: auto_detect
         run: |
-          if git diff --quiet registry.json; then
-            echo "changed=false" >> $GITHUB_OUTPUT
-            echo "No changes to registry.json"
+          echo "## 🔍 Auto-Detection Results" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          
+          # Run auto-detect in dry-run mode first
+          if ./scripts/auto-detect-components.sh --dry-run > /tmp/detect-output.txt 2>&1; then
+            cat /tmp/detect-output.txt >> $GITHUB_STEP_SUMMARY
+            
+            # Check if new components were found
+            if grep -q "Found.*new component" /tmp/detect-output.txt; then
+              echo "new_components=true" >> $GITHUB_OUTPUT
+              echo "" >> $GITHUB_STEP_SUMMARY
+              echo "⚠️ New components detected - will auto-add to registry" >> $GITHUB_STEP_SUMMARY
+            else
+              echo "new_components=false" >> $GITHUB_OUTPUT
+              echo "✅ No new components found" >> $GITHUB_STEP_SUMMARY
+            fi
           else
-            echo "changed=true" >> $GITHUB_OUTPUT
-            echo "Registry has been updated"
+            echo "new_components=false" >> $GITHUB_OUTPUT
+            echo "❌ Auto-detection failed" >> $GITHUB_STEP_SUMMARY
           fi
       
-      - name: Commit and push changes
-        if: steps.check_changes.outputs.changed == 'true'
+      - name: Add new components to registry
+        if: steps.auto_detect.outputs.new_components == 'true'
+        run: |
+          echo "## 📝 Adding New Components" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          
+          ./scripts/auto-detect-components.sh --auto-add | tee -a $GITHUB_STEP_SUMMARY
+      
+      - name: Validate registry
+        id: validate
+        run: |
+          echo "## ✅ Registry Validation" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          
+          if ./scripts/validate-registry.sh -v > /tmp/validation-output.txt 2>&1; then
+            echo "validation=passed" >> $GITHUB_OUTPUT
+            echo "✅ All registry paths are valid!" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+            tail -20 /tmp/validation-output.txt >> $GITHUB_STEP_SUMMARY
+            echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "validation=failed" >> $GITHUB_OUTPUT
+            echo "❌ Registry validation failed!" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+            cat /tmp/validation-output.txt >> $GITHUB_STEP_SUMMARY
+            echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "⚠️ WARNING: Direct push to main with invalid registry!" >> $GITHUB_STEP_SUMMARY
+            echo "Please fix registry.json and push a correction." >> $GITHUB_STEP_SUMMARY
+            # Don't exit 1 here - we already pushed to main, just warn
+          fi
+      
+      - name: Commit registry updates
+        if: steps.auto_detect.outputs.new_components == 'true'
         run: |
           git config --local user.email "github-actions[bot]@users.noreply.github.com"
           git config --local user.name "github-actions[bot]"
-          git add registry.json
-          git commit -m "chore: auto-update component registry [skip ci]"
-          git push
+          
+          if ! git diff --quiet registry.json; then
+            git add registry.json
+            git commit -m "chore: auto-update registry with new components [skip ci]"
+            git push
+            
+            echo "## 🚀 Registry Updated" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "Registry has been automatically updated with new components." >> $GITHUB_STEP_SUMMARY
+          fi
       
       - name: Summary
-        if: steps.check_changes.outputs.changed == 'true'
+        if: always()
         run: |
-          echo "✅ Registry updated successfully" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
-          echo "### Updated Components" >> $GITHUB_STEP_SUMMARY
+          echo "---" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### Registry Statistics" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
           jq -r '
             "- **Agents:** \(.components.agents | length)",
@@ -68,8 +123,3 @@ jobs:
             "- **Plugins:** \(.components.plugins | length)",
             "- **Contexts:** \(.components.contexts | length)"
           ' registry.json >> $GITHUB_STEP_SUMMARY
-      
-      - name: No changes summary
-        if: steps.check_changes.outputs.changed == 'false'
-        run: |
-          echo "ℹ️ No changes to registry" >> $GITHUB_STEP_SUMMARY

WORKFLOW_GUIDE.md

@@ -0,0 +1,327 @@
+# CI/CD Workflow Guide - Build Validation System
+
+## Overview
+
+The build validation system has **two workflows** that handle different scenarios:
+
+1. **PR Workflow** - Validates and blocks merge if registry is invalid
+2. **Direct Push Workflow** - Auto-updates registry on direct pushes to main
+
+---
+
+## Workflow 1: Pull Request Validation
+
+**File:** `.github/workflows/validate-registry.yml`
+
+**Triggers:**
+- Pull requests to `main` or `dev` branches
+- Changes to `.opencode/**`, `registry.json`, or validation scripts
+
+**What It Does:**
+
+```
+Developer creates PR
+         ↓
+GitHub Action runs automatically
+         ↓
+1. Auto-detect new components
+   - Scans .opencode/ directory
+   - Finds files not in registry
+         ↓
+2. Add to registry (if found)
+   - Extracts metadata
+   - Adds to registry.json
+   - Commits to PR branch
+         ↓
+3. Validate registry
+   - Checks all paths exist
+   - Verifies JSON is valid
+         ↓
+4. Decision
+   ├─ ✅ Valid → PR can merge
+   └─ ❌ Invalid → PR BLOCKED
+```
+
+**Key Features:**
+- ✅ **Blocks merge** if validation fails
+- ✅ **Auto-commits** registry updates to PR branch
+- ✅ **Detailed feedback** in PR checks
+- ✅ **Prevents 404 errors** before they reach main
+
+**Example Output:**
+```
+🔍 Auto-Detection Results
+⚠️ New command: my-new-command
+  Path: .opencode/command/my-new-command.md
+
+📝 Adding New Components
+✓ Added command: my-new-command
+
+✅ Registry Validation
+All registry paths are valid!
+Total paths: 51
+Valid: 51
+Missing: 0
+
+✅ Validation Passed
+This PR is ready for review!
+```
+
+---
+
+## Workflow 2: Direct Push to Main
+
+**File:** `.github/workflows/update-registry.yml`
+
+**Triggers:**
+- Direct pushes to `main` branch
+- Changes to `.opencode/**` (excluding registry.json)
+- Manual workflow dispatch
+
+**What It Does:**
+
+```
+Developer pushes directly to main
+         ↓
+GitHub Action runs automatically
+         ↓
+1. Auto-detect new components
+   - Scans .opencode/ directory
+   - Finds files not in registry
+         ↓
+2. Add to registry (if found)
+   - Extracts metadata
+   - Adds to registry.json
+   - Commits to main
+         ↓
+3. Validate registry
+   - Checks all paths exist
+   - Verifies JSON is valid
+         ↓
+4. Report results
+   ├─ ✅ Valid → Success
+   └─ ⚠️ Invalid → Warning (doesn't block)
+```
+
+**Key Differences from PR Workflow:**
+- ⚠️ **Does NOT block** - push already happened
+- ⚠️ **Shows warning** if validation fails
+- ✅ **Auto-commits** registry updates
+- ✅ **Validates** but doesn't prevent push
+
+**Why No Blocking?**
+Since the push already happened, we can't block it. Instead:
+- Shows clear warning in Actions summary
+- Alerts team to fix registry
+- Prevents future installation errors
+
+**Example Output:**
+```
+🔍 Auto-Detection Results
+✅ No new components found
+
+✅ Registry Validation
+All registry paths are valid!
+
+Registry Statistics
+- Agents: 4
+- Commands: 12
+- Contexts: 15
+```
+
+---
+
+## Comparison Table
+
+| Feature | PR Workflow | Direct Push Workflow |
+|---------|-------------|---------------------|
+| **Triggers** | Pull requests | Direct push to main |
+| **Auto-detect** | ✅ Yes | ✅ Yes |
+| **Auto-add** | ✅ Yes | ✅ Yes |
+| **Validate** | ✅ Yes | ✅ Yes |
+| **Block on failure** | ✅ Yes | ❌ No (warns only) |
+| **Auto-commit** | ✅ To PR branch | ✅ To main |
+| **Use case** | Normal development | Emergency fixes, maintainers |
+
+---
+
+## Recommended Workflow
+
+### For Contributors (Recommended)
+
+```bash
+# 1. Create feature branch
+git checkout -b feature/my-new-component
+
+# 2. Add your component
+echo "---
+description: My awesome component
+---
+# My Component" > .opencode/command/my-component.md
+
+# 3. Commit and push
+git add .opencode/command/my-component.md
+git commit -m "feat: add my-component"
+git push origin feature/my-new-component
+
+# 4. Create PR to dev
+gh pr create --base dev --title "Add my-component"
+
+# 5. GitHub Actions will:
+#    - Auto-detect your component
+#    - Add to registry.json
+#    - Validate all paths
+#    - Commit to your PR branch
+#    - Block merge if invalid
+
+# 6. Review and merge
+# Your component is now in registry!
+```
+
+### For Maintainers (Direct Push)
+
+```bash
+# 1. Add component directly to main
+git checkout main
+echo "---
+description: Urgent fix
+---
+# Fix" > .opencode/command/urgent-fix.md
+
+# 2. Commit and push
+git add .opencode/command/urgent-fix.md
+git commit -m "fix: urgent component"
+git push origin main
+
+# 3. GitHub Actions will:
+#    - Auto-detect your component
+#    - Add to registry.json
+#    - Validate all paths
+#    - Commit registry update to main
+#    - Warn if validation fails (but doesn't block)
+
+# 4. Check Actions tab for results
+# If warning, fix registry and push correction
+```
+
+---
+
+## Manual Validation (Local)
+
+Before pushing, you can validate locally:
+
+```bash
+# Check for new components
+./scripts/auto-detect-components.sh --dry-run
+
+# Add new components
+./scripts/auto-detect-components.sh --auto-add
+
+# Validate registry
+./scripts/validate-registry.sh -v
+
+# Get fix suggestions
+./scripts/validate-registry.sh --fix
+```
+
+---
+
+## Troubleshooting
+
+### PR Blocked - Validation Failed
+
+**Problem:** PR shows validation failure
+
+**Solution:**
+```bash
+# 1. Check the error in PR checks
+# 2. Run validator locally
+./scripts/validate-registry.sh --fix
+
+# 3. Fix the issues (usually path typos)
+# 4. Commit and push
+git add registry.json
+git commit -m "fix: correct registry paths"
+git push
+
+# 5. PR checks will re-run automatically
+```
+
+### Direct Push - Validation Warning
+
+**Problem:** Push succeeded but Actions shows warning
+
+**Solution:**
+```bash
+# 1. Check Actions tab for details
+# 2. Run validator locally
+./scripts/validate-registry.sh --fix
+
+# 3. Fix registry.json
+# 4. Push correction
+git add registry.json
+git commit -m "fix: correct registry after direct push"
+git push origin main
+```
+
+### Component Not Auto-Detected
+
+**Problem:** Added file but not detected
+
+**Possible causes:**
+- File in excluded directory (tests/, docs/, node_modules/)
+- File is README.md or index.md (excluded)
+- File doesn't have .md extension
+- File in wrong location (not in .opencode/)
+
+**Solution:**
+```bash
+# Check if file would be detected
+./scripts/auto-detect-components.sh --dry-run
+
+# If not detected, check file location and name
+# Move to correct location:
+# - Agents: .opencode/agent/
+# - Commands: .opencode/command/
+# - Tools: .opencode/tool/
+# - Plugins: .opencode/plugin/
+# - Contexts: .opencode/context/
+```
+
+---
+
+## Best Practices
+
+### ✅ DO
+
+- **Use PRs** for normal development (recommended)
+- **Add frontmatter** to components with description
+- **Test locally** before pushing
+- **Review auto-commits** in PR before merging
+- **Keep registry.json** in sync with files
+
+### ❌ DON'T
+
+- **Don't bypass PRs** unless emergency
+- **Don't manually edit** registry.json (let automation handle it)
+- **Don't ignore** validation warnings
+- **Don't commit** broken registry paths
+- **Don't skip** local validation
+
+---
+
+## Summary
+
+**For 99% of cases:** Use PR workflow
+- Creates PR → Auto-detect → Validate → Block if invalid → Merge
+
+**For emergencies:** Direct push works
+- Push to main → Auto-detect → Validate → Warn if invalid
+
+**Both workflows:**
+- ✅ Auto-detect new components
+- ✅ Update registry automatically
+- ✅ Validate all paths
+- ✅ Prevent installation 404 errors
+
+**The system ensures registry accuracy whether you use PRs or direct pushes!**