OpenAgentsControl/.github/WORKFLOW_AUDIT.md

Workflow & Repository Audit

Generated: 2025-12-31 Purpose: Document findings and recommendations for repository improvements

Executive Summary

This audit identifies issues in the CI/CD pipeline, versioning system, and repository structure. The goal is to prevent bugs like the install.sh non-interactive failure and make the repository easier to navigate.

---

Part 1: CI/CD & Versioning Analysis

Current Workflow Architecture

PR Creation/Update
├── pr-checks.yml (title validation, build check)
├── validate-registry.yml (component detection)
├── validate-test-suites.yml (JSON validation)
└── installer-checks.yml [NEW] (install.sh tests)

PR Merge → Main
├── post-merge-pr.yml (version bump PR creation)
├── update-registry.yml (auto-detect components)
└── sync-docs.yml (documentation updates)

Version Bump PR Merge
└── create-release.yml (tag + GitHub release)

Versioning Flow

1. PR merged with conventional commit title
2. post-merge-pr.yml detects bump type from commit message
3. Creates version bump branch + PR with version-bump label
4. On merge, create-release.yml creates tag and GitHub release
5. VERSION file and package.json stay synchronized

Issues Identified

Issue	Severity	Status
No CI for install.sh changes	High	FIXED (installer-checks.yml)
Disabled workflow file exists	Low	Needs cleanup
Complex loop prevention logic	Medium	Document better
OpenCode sync dependency	Medium	Add fallback
Multiple skip patterns scattered	Medium	Consider centralizing

Recommendations

1. Remove post-merge.yml.disabled - Causes confusion
2. Add workflow concurrency controls - Prevent race conditions
3. Document skip patterns - Create reference for maintainers
4. Add health check workflow - Weekly validation of system integrity

---

Part 2: Repository Structure Analysis

Current Structure

/
├── README.md (600+ lines)
├── QUICK_START.md
├── install.sh, update.sh
├── registry.json, package.json
├── docs/ (comprehensive)
├── scripts/ (26+ scripts in 7 subdirs)
├── evals/ (evaluation framework)
├── .opencode/ (agent components)
├── .github/ (workflows + templates)
├── dev/ (development tools)
├── src/ (minimal, possibly unused)
└── assets/ (images)

Issues Identified

Issue	Impact	Recommendation
Multiple entry points (README, QUICK_START, docs/)	High	Consolidate
Root directory clutter (20+ files)	Medium	Organize into subdirs
Overlapping documentation	Medium	Single source of truth
Orphaned src/ directory	Low	Evaluate or remove
Multiple config files without clear hierarchy	Medium	Document purposes

Recommended Structure (Non-Breaking)

/
├── README.md (streamlined ~200 lines)
├── install.sh (keep at root for curl access)
├── VERSION, LICENSE, Makefile
│
├── docs/
│   ├── README.md (comprehensive hub)
│   ├── getting-started/ (moved QUICK_START here)
│   ├── guides/
│   └── reference/
│
├── scripts/
│   ├── README.md (index of all scripts)
│   ├── install/ (installation related)
│   ├── testing/ (all tests)
│   ├── development/ (dev workflows)
│   └── maintenance/ (cleanup, validation)
│
├── config/ [NEW]
│   ├── registry.json
│   └── env.example
│
└── ... (rest unchanged)

---

Part 3: Action Items

Immediate (This PR)

• Fix install.sh non-interactive bug
• Add installer-checks.yml workflow
• Add test-non-interactive.sh
• Add test-e2e-install.sh
• Fix CHANGELOG.md duplicates
• Update registry.json metadata

Short-Term (Next Sprint)

• Streamline main README.md
• Move QUICK_START.md to docs/getting-started/
• Document all skip patterns in one place
• Remove post-merge.yml.disabled
• Add workflow concurrency controls

Medium-Term (Future)

• Create config/ directory structure
• Consolidate script organization
• Add weekly health check workflow
• Evaluate and clean up src/ directory
• Add local CI testing script

---

Part 4: Prevention Measures

For Install Script Bugs

The new installer-checks.yml workflow prevents future install.sh bugs by:

1. ShellCheck - Static analysis catches common shell issues
2. Syntax validation - Ensures scripts are parseable
3. Non-interactive tests - Validates curl | bash scenarios
4. E2E tests - Full installation workflow validation
5. Multi-platform - Tests on Ubuntu and macOS
6. Profile smoke tests - All profiles tested non-interactively

For Workflow Issues

Consider adding:

# Prevent concurrent runs on same branch
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: false

For Documentation Drift

• Use cross-references instead of duplicating content
• Add CI check for broken internal links
• Consider documentation linting

---

Appendix: Files Changed in This Audit

New Files

• .github/workflows/installer-checks.yml
• scripts/tests/test-non-interactive.sh
• scripts/tests/test-e2e-install.sh
• .github/WORKFLOW_AUDIT.md (this file)

Modified Files

• install.sh (bug fix for non-interactive collision handling)
• scripts/tests/README.md (updated test documentation)
• CHANGELOG.md (fixed duplicates, added 0.5.1)
• registry.json (updated lastUpdated metadata)