Overhaul Installation System to Best-in-Class Standards

[carmandale]

Overview

Transform Agent OS installation from functional to exemplary by implementing industry best practices, fixing critical gaps, and creating a gold-standard user experience.

Problem Statement

Critical Issues Identified

1. ❌ Missing scripts: workflow-status.sh, workflow-complete.sh not installed → commands fail
2. ❌ Inconsistent frontmatter: Older commands lack security controls (allowed-tools)
3. ❌ Path resolution bugs: Example files show ~ paths that don't work in settings.json
4. ❌ No idempotency: Scripts not safely re-runnable
5. ❌ Limited error context: Generic failures without actionable guidance
6. ❌ Update mechanism: Hook updates don't work (Issue Fix installer to properly update Claude hooks when needed #65)
7. ❌ Verification gaps: No comprehensive health check (Issues Create missing verify-installation.sh script #92, Address Repository Technical Debt and Infrastructure Gaps #93)

Evidence:

• Research: docs/INSTALLATION-BEST-PRACTICES.md (created)
• Research: docs/INSTALLATION-RESEARCH-SUMMARY.md (created)
• Repository analysis: setup.sh:1-466, setup-claude-code.sh:1-263
• Real user impact: Commands showing 'no such file or directory' errors

Proposed Solution

Three-phase transformation to world-class installation:

Phase 1: Critical Fixes (Week 1) ✅ IN PROGRESS

• ✅ Fix missing script installations (uncommitted work)
• Add frontmatter to all commands
• Implement comprehensive verification
• Fix path resolution issues

Phase 2: Reliability & Security (Week 2)

• Make scripts idempotent
• Add robust error handling
• Implement security best practices
• Add cross-platform support

Phase 3: Polish & Documentation (Week 3)

• Create interactive installation experience
• Add self-update mechanism
• Write comprehensive troubleshooting guide
• Document all conventions

Acceptance Criteria

Phase 1 (Critical Fixes)

• workflow-status.sh installed and executable
• workflow-complete.sh installed and executable
• All 8 commands have proper frontmatter
• verify-installation.sh created and tested
• Hook examples use absolute paths
• hygiene-check.md instruction installed

Phase 2 (Reliability & Security)

• setup.sh wrapped in main() function
• Idempotency checks for all operations
• Centralized abort() error function
• Cross-platform detection (macOS/Linux)
• Secure file permissions (600/700)

Phase 3 (Polish & Documentation)

• Progress indicators (step X/Y)
• Color-coded output
• self-update.sh script
• docs/TROUBLESHOOTING.md
• Installation completes <60s

Success Metrics

Installation Reliability:

• ✅ 100% of repo scripts installed (currently ~80%)
• ✅ 0 'command not found' errors
• ✅ <1% installation failure rate

User Experience:

• ⏱️ <60s installation time
• 📊 User satisfaction >4.5/5
• 🐛 <5 bugs/month

Related Issues

• Fixes Fix installer to properly update Claude hooks when needed #65 (Hook update mechanism)
• Fixes Create missing verify-installation.sh script #92 (verify-installation.sh)
• Fixes Address Repository Technical Debt and Infrastructure Gaps #93 (Technical debt)

Current Status

Uncommitted work already addresses Phase 1:

• ✅ setup.sh: Adds workflow-status.sh installation (fixes /workflow-status command)
• ✅ setup.sh: Adds workflow-complete.sh installation (fixes /workflow-complete command)
• ✅ setup.sh: Adds hygiene-check.md instruction installation
• ✅ setup.sh: Adds Codex CLI support with --skip-codex-commands flag
• ✅ setup-claude-code-local.sh: Updates command list for parity
• ✅ setup-cursor.sh: Maintains cross-platform command parity
• ✅ Removes obsolete work-session.md command

Next Steps:

1. Commit current fixes as Phase 1 initial implementation
2. Add frontmatter to remaining 5 commands
3. Create verify-installation.sh script
4. Fix path examples in hooks/examples/

References

Research Documents

• docs/INSTALLATION-BEST-PRACTICES.md (35KB comprehensive guide)
• docs/INSTALLATION-RESEARCH-SUMMARY.md (14KB quick reference)

External Best Practices

• Homebrew, Rustup, NVM installation patterns
• Claude Code integration requirements
• Security best practices for shell installations

Implementation Patterns

See full technical specification with code examples:

• Script installation automation
• Frontmatter templates for all commands
• verify-installation.sh implementation
• Idempotency patterns
• Error handling with abort() function
• Cross-platform detection
• Self-update mechanism
• Troubleshooting guide template

---

Phase 1 Critical Fixes Ready for Implementation

[carmandale]

Phase 1 Critical Fixes - ✅ COMPLETED

Three commits pushed to main branch implementing Phase 1 critical fixes:

1. Fix Missing Script Installations (b311349)

Fixes the core issue that caused this investigation:

• ✅ Installs workflow-status.sh script
• ✅ Installs workflow-complete.sh script
• ✅ Installs hygiene-check.md instruction
• ✅ Adds Codex CLI support with --skip-codex-commands flag
• ✅ Maintains command parity across all 4 platforms
• ✅ Removes obsolete work-session.md command

Impact:

• /workflow-status command now works (was failing with "no such file or directory")
• /workflow-complete command now works (was failing with "no such file or directory")

2. Documentation Updates (3fe55f0)

Updated documentation for consistency:

• ✅ AGENTS.md - Documents Codex CLI installation
• ✅ CLAUDE.md - Adds Codex CLI note
• ✅ README.md - Updates usage examples for all platforms
• ✅ docs/ARCHITECTURE.md - Architectural updates

3. Research Documentation (e5258c5)

Added comprehensive installation research:

• ✅ docs/INSTALLATION-BEST-PRACTICES.md (35KB)
• ✅ docs/INSTALLATION-RESEARCH-SUMMARY.md (14KB)

These documents provide the foundation for Phases 2 and 3.

---

Testing Verification

✅ Commands that were failing now work:

/workflow-status    # Now finds ~/.agent-os/scripts/workflow-status.sh
/workflow-complete  # Now finds ~/.agent-os/scripts/workflow-complete.sh

✅ Platform parity maintained:

• Claude Code (8 commands)
• Cursor (8 commands)
• Factory CLI (8 commands)
• Codex CLI (8 commands)

---

Next Steps

Phase 1 Remaining Work:

• Add frontmatter to 5 commands (plan-product, create-spec, execute-tasks, analyze-product, hygiene-check)
• Create verify-installation.sh script
• Fix path examples in hooks/examples/agent-os-bash-hooks.json
• Test on clean macOS and Linux systems

Phase 2 Ready to Start:
See issue description for Phase 2 (Reliability & Security) implementation details.

---

Commits:

• b311349: fix: install missing workflow scripts and add Codex CLI support (Overhaul Installation System to Best-in-Class Standards #95)
• 3fe55f0: docs: update documentation for Codex CLI support and new commands
• e5258c5: docs: add comprehensive installation research and best practices

[carmandale]

Phase 1 Completion Update

All Phase 1 tasks have been successfully completed:

✅ Completed Tasks

1. Command Frontmatter Security - Added allowed-tools YAML frontmatter to all 5 core commands:

   • plan-product.md - Git, GitHub, file operations
   • create-spec.md - Git, GitHub CLI, date utilities
   • execute-tasks.md - Full development toolchain
   • analyze-product.md - Git, file discovery, aos status
   • hygiene-check.md - Git, GitHub, file search tools

2. Verification Script - The comprehensive verify-installation.sh script already existed (from Issue Create missing verify-installation.sh script #92) and includes:

   • Multiple verification modes (quick, full, hooks-only, alias-only)
   • Directory structure validation
   • File integrity checks
   • Claude hooks validation
   • CLI commands verification
   • Git integration checks
   • Proper exit codes and color-coded output

3. Absolute Path Examples - Updated hooks/examples/agent-os-bash-hooks.json:

   • Changed from ~/ to /Users/USERNAME/ placeholder format
   • Added clear documentation comments
   • Explained that setup script handles path expansion automatically

4. Testing - Verified installation script works correctly:

   • Ran in quick and full modes
   • Identified and fixed test file permission issues
   • Confirmed all checks pass with only non-critical warnings

📦 Deliverables

• Commit: 8c0e0e9
• All changes pushed to main branch
• Installation script tested and verified working

🔜 Next Steps

Phase 2 and 3 remain as outlined in the original issue. These phases will focus on:

• Enhanced error handling and recovery
• Performance optimizations
• Cross-platform testing
• Additional documentation

The Phase 1 improvements provide a solid foundation for users to:

• Understand command security boundaries
• Verify their installation health
• See clear examples of proper hook configuration