--- roadcrew_template_name: "update-roadcrew.md" roadcrew_template_type: "command" execution_mode: "auto-execute" roadcrew_template_version: "v1.0" roadcrew_last_updated: "2025-10-25" roadcrew_min_version: "1.5.0" roadcrew_license: "See LICENSE file in .roadcrew folder" roadcrew_copyright: "Copyright (c) 2025 North Star Holdings, LLC" spdx_license_identifier: "LicenseRef-RoadcrewLicense-1.0" --- # Update Roadcrew Update your instance repository with latest changes from upstream roadcrew, then optionally upgrade your documents to use new template structures. ## Installation Types This command works with two types of roadcrew installations: ### Submodule Installation - Roadcrew installed at `.roadcrew/` as a git submodule - Updates by moving the submodule pointer to latest commit - No merge conflicts possible - Commands accessed via `.roadcrew/.cursor/commands/` - Most common for downstream projects ### Instance Installation - Roadcrew forked/cloned as your own repository - Updates by merging from `roadcrew-upstream` remote - May have merge conflicts if you customized roadcrew files - Commands at `.cursor/commands/` - Used when you need to customize roadcrew itself The script automatically detects which type you have and uses the appropriate update strategy. ## What This Command Does **Phase 0: Detection & Validation** 1. Verifies `.cursor/rules` directory exists 2. Ensures Git authentication is configured 3. Pulls latest Roadcrew distribution from upstream 4. Detects if roadcrew is installed as a submodule or instance 5. Detects if you have the old `.roadmapper` submodule name 6. Offers to automatically rename to `.roadcrew` (one-time migration) **Phase 1: Upstream Sync** 7. Explains what will change (templates, commands, utilities) 8. Lists all files that will be updated 9. Asks for confirmation before proceeding 10. Updates roadcrew (submodule update OR merge depending on installation type) **Phase 2: Document Upgrade (Optional)** 10. Asks if you want to upgrade your existing documents to new templates 11. Backs up your documents before changes 12. Runs `/update-my-documents` for each document ## Usage Run this command when: - You want to get latest roadcrew updates - New releases or important fixes are available - Before starting new work to ensure you have latest features - Regularly (weekly/monthly) to stay current ```bash /update-roadcrew ``` Or directly via script: - **Instance installation:** `./scripts/update-roadcrew.sh` - **Submodule installation:** `./.roadcrew/scripts/update-roadcrew.sh` or `./roadcrew/scripts/update-roadcrew.sh` ## How It Works ### Phase 0: Migration Check **Step 0: Verify .cursor/rules** The script verifies that a `.cursor/rules` directory exists before proceeding: Example successful output: ``` [✓] .cursor/rules directory found ``` Example error output: ``` [✗] .cursor/rules directory not found ``` This command requires a `.cursor/rules` directory to be present. ### .cursor/rules Directory A `.cursor/rules` directory must exist in your repository root: ```bash # Check if .cursor/rules exists ls -la .cursor/rules # If not present, verify Roadcrew is properly installed # The directory should contain 14 .mdc rule files ``` This ensures your instance has proper Cursor AI configuration before updating. **Step 0.4: Detect Installation Type** The script automatically detects if roadcrew is installed as a submodule: ``` [INFO] Detected roadcrew as submodule at .roadcrew ``` This determines which update strategy to use: - **Submodule:** Updates the submodule pointer to latest upstream commit - **Instance:** Merges changes from `roadcrew-upstream` remote **Step 0.5: Detect Old Submodule Name (Automatic)** If your instance has roadcrew installed as a submodule at the old `.roadmapper` path, the script will automatically include the rename in the update process. You'll see it listed in the "READY TO UPDATE" section. **Step 0.6: Detect Duplicate Files (Automatic)** If you're using roadcrew as a submodule (`.roadcrew/`) but have duplicate roadcrew files at root, the script will detect and clean them up automatically: ``` ═══════════════════════════════════════════════════════════ DUPLICATE FILES DETECTED ═══════════════════════════════════════════════════════════ You're using roadcrew as a submodule, but have duplicate files at root: - .cursor/commands - scripts (roadcrew) - templates - docs (roadcrew) These will be removed and backed up during the update. Commands will be accessed from .roadcrew/.cursor/commands/ ═══════════════════════════════════════════════════════════ READY TO UPDATE ═══════════════════════════════════════════════════════════ This update will: - Update roadcrew submodule to latest version - Commit submodule pointer update - Rename .roadmapper submodule to .roadcrew - Clean up duplicate roadcrew files at root - Backup instance documents Proceeding with upgrade in 10 seconds... Type 'STOP' and press Enter to halt the upgrade. ``` **What happens during the rename:** - Script safely removes `.roadmapper` submodule - Preserves the current commit hash - Adds new `.roadcrew` submodule - Checks out the same commit you were on - Commits the rename automatically - Continues to upstream sync **What happens during the cleanup:** - Script creates backup directory: `backups/roadcrew-cleanup-YYYY-MM-DD-HHMMSS/` - Backs up all duplicate files - Removes duplicate directories from root: - `.cursor/commands/` - `scripts/` (roadcrew scripts only) - `templates/` - `docs/` (roadcrew docs only) - `dist/` - Commits the cleanup automatically - All roadcrew files now accessed from `.roadcrew/` **To prevent the update:** - Type `STOP` during the 30-second countdown - The entire update will be cancelled (including cleanup) - You can clean up manually using `scripts/cleanup-duplicate-commands.sh` **Note:** These are **one-time migrations** - once completed, they won't run again. ### Phase 1: Upstream Sync **Step 1: Explain What Will Change** Script analyzes upstream and shows: ``` 🔄 ROADMAPPER UPDATE AVAILABLE This will update your instance with latest upstream changes: Categories: - Templates: 3 files (vision, spec, epic) - Commands: 2 files (scope-release, analyze-epic) - Utilities: 1 file (issue-classification.ts) - Documentation: 2 files (README, instance-guide) Total: 8 files will be updated ``` **Step 2: Show Commit History** Lists recent commits: ``` Recent upstream commits: a1b2c3d - 2 hours ago - feat: Add dependency validation d4e5f6g - 1 day ago - fix: Bug in template parsing h7i8j9k - 2 days ago - docs: Update documentation ⚠️ WARNING: 1 breaking change detected! - a1b2c3d BREAKING: Rename vision.md to vision.md ``` **Step 3: List All File Changes** Shows what will change: ``` Files that will be updated: M templates/vision.template.md M .cursor/commands/scope-release.md A scripts/utils/issue-classification.ts D .cursor/commands/deprecated-command.md ``` **Step 4: Ask for Confirmation** ``` Do you want to proceed with these updates? [y/N]: ``` - Type `y` to continue - Type `n` or Enter to cancel **Step 5: Apply Changes** If confirmed, the script applies changes based on installation type: **For Submodule Installations:** 1. Commits the submodule pointer update 2. Shows before/after commit hashes 3. Reports success ``` ✓ Successfully updated roadcrew submodule! Updated from: abc123def456 Updated to: xyz789abc012 ``` **For Instance Installations:** 1. Runs `git merge roadcrew-upstream/main` 2. Removes roadcrew-only commands (like `/update-ci-cd`) 3. Reports success or conflicts 4. If conflicts: Provides resolution guidance ### Phase 2: Document Upgrade (Optional) **After successful sync, script asks:** ``` ✓ Upstream updates merged successfully! Your instance documents may be using older template structures. Would you like to upgrade your documents to the latest templates? This will: - Backup your existing documents - Add new template sections while preserving your content - Update template version metadata Documents that can be upgraded: - memory-bank/activeContext.md - context/specs/*.md - memory-bank/releases/current-release.md - memory-bank/releases/future-releases.md Upgrade documents now? [y/N]: ``` **If yes:** 1. **Backup Documents** ```bash mkdir -p backups/documents-2025-10-17/ cp memory-bank/activeContext.md backups/documents-2025-10-17/ cp context/specs/*.md backups/documents-2025-10-17/ # ... backup all eligible documents ``` 2. **Run /update-my-documents for each** ```bash /update-my-documents vision /update-my-documents context/specs/feature-spec.md # ... for each document ``` 3. **Show Summary** ``` ✓ Document upgrades complete! Upgraded: - memory-bank/activeContext.md (v1.0 → v2.0) - context/specs/auth-spec.md (v1.1 → v2.0) Backups saved to: backups/documents-2025-10-17/ ``` ## Prerequisites ### .cursor/rules Directory A `.cursor/rules` directory must exist in your repository root: ```bash # Check if .cursor/rules exists ls -la .cursor/rules # If not present, verify Roadcrew is properly installed # The directory should contain 14 .mdc rule files ``` This file configures how Cursor AI assists with your instance. ### Upstream Remote Configuration (Instance Installations Only) **For instance installations**, the `roadcrew-upstream` remote must be configured: ```bash # Check if configured git remote -v | grep roadcrew-upstream # If not configured, add it (SSH recommended) git remote add roadcrew-upstream git@github.com:tailwind-ai/roadcrew.git git fetch roadcrew-upstream ``` **For submodule installations**, no upstream remote is needed - the script automatically updates the submodule. ### Clean Working Directory You must have no uncommitted changes: ```bash # Check status git status # If you have changes, commit or stash them git stash # or git commit -am "WIP: description" ``` ## Handling Conflicts If merge conflicts occur: ``` [✗] Merge conflicts detected in 3 files! Conflicting files: - .cursor/commands/scope-release.md - templates/epic.template.md - README.md To resolve: 1. Open each file and fix conflict markers 2. Keep your customizations + adopt upstream improvements 3. git add 4. git commit 5. git push origin main To abort: git merge --abort ``` **Resolution strategy:** - **Templates:** Usually safe to take upstream (you customize copies) - **Commands:** Review both versions, merge manually - **Your content:** (vision.md, specs/) Keep your content, adopt structure changes - **Config:** Keep your settings, note new options ## What Gets Updated **Upstream sync brings:** - **Templates** - New sections, improved structure - **Commands** - Bug fixes, new features - **Utilities** - Detection improvements, new functions - **Documentation** - Updated guides - **Dependencies** - Package updates **Your documents (after upgrade):** - **Structure** - New template sections added - **Content** - Your existing content preserved - **Metadata** - Template version tracking added - **Completeness** - Missing sections filled with placeholders ## Safety Features ✅ **Automatic migration detection** - Detects old `.roadmapper` and offers rename ✅ **Explains before acting** - Shows what will change ✅ **Confirmation required** - Won't proceed without approval ✅ **Backup system** - Documents backed up before upgrade ✅ **Non-destructive** - Can review changes before committing ✅ **Abort option** - Can cancel at any time ✅ **Conflict guidance** - Clear instructions for resolution ✅ **Commit preservation** - Maintains your submodule commit hash during rename ## Related Commands - **`/update-my-documents`** - Upgrade individual documents to new templates - **`scripts/sync-upstream.sh`** - Low-level sync script (called by this command) - **`docs/instance-repository-guide.md`** - Complete instance management guide ## Tips - **Say yes to rename** - If prompted about `.roadmapper` → `.roadcrew`, accept the rename (one-time migration) - **Run regularly** - Weekly checks keep you current - **Read changes** - Understand what's being updated - **Test after sync** - Verify commands still work - **Review document upgrades** - Check that content preserved correctly - **Keep backups** - Backups folder contains all pre-upgrade versions --- **Behavior:** - Safe, interactive, user-controlled - Explains, lists, confirms before any changes - Offers document upgrade after upstream sync - Creates backups before modifications