@revotools/cli 0.6.0 → 0.6.2

package/dist/revo

@@ -8,7 +8,7 @@ set -euo pipefail
 # Exit cleanly on SIGPIPE (e.g., revo clone | grep, revo status | head)
 trap 'exit 0' PIPE
 
-REVO_VERSION="0.6.0"
+REVO_VERSION="0.6.2"
 
 
 # === lib/ui.sh ===
@@ -481,6 +481,7 @@ YAML_REPO_URLS=()
 YAML_REPO_PATHS=()
 YAML_REPO_TAGS=()
 YAML_REPO_DEPS=()
+YAML_REPO_BRANCHES=()
 
 yaml_parse() {
     local file="$1"
@@ -497,6 +498,7 @@ yaml_parse() {
     YAML_REPO_PATHS=()
     YAML_REPO_TAGS=()
     YAML_REPO_DEPS=()
+    YAML_REPO_BRANCHES=()
 
     if [[ ! -f "$file" ]]; then
         return 1
@@ -550,6 +552,7 @@ yaml_parse() {
                 YAML_REPO_PATHS[$current_index]=$(yaml_path_from_url "$url")
                 YAML_REPO_TAGS[$current_index]=""
                 YAML_REPO_DEPS[$current_index]=""
+                YAML_REPO_BRANCHES[$current_index]=""
                 YAML_REPO_COUNT=$((YAML_REPO_COUNT + 1))
                 continue
             fi
@@ -573,6 +576,8 @@ yaml_parse() {
                     deps_str="${deps_str//\"/}"
                     deps_str="${deps_str//\'/}"
                     YAML_REPO_DEPS[$current_index]="$deps_str"
+                elif [[ "$trimmed" =~ ^branch:[[:space:]]*(.+)$ ]]; then
+                    YAML_REPO_BRANCHES[$current_index]="${BASH_REMATCH[1]}"
                 fi
             fi
         fi
@@ -648,6 +653,12 @@ yaml_get_deps() {
     printf '%s' "${YAML_REPO_DEPS[$idx]:-}"
 }
 
+# Get repo default branch by index (empty means use workspace default)
+yaml_get_branch() {
+    local idx="$1"
+    printf '%s' "${YAML_REPO_BRANCHES[$idx]:-}"
+}
+
 # Find repo index by name (path basename)
 # Usage: idx=$(yaml_find_by_name "backend")
 # Returns: index or -1 if not found
@@ -681,6 +692,7 @@ yaml_write() {
             local path="${YAML_REPO_PATHS[$i]}"
             local tags="${YAML_REPO_TAGS[$i]}"
             local deps="${YAML_REPO_DEPS[$i]:-}"
+            local branch="${YAML_REPO_BRANCHES[$i]:-}"
 
             printf '  - url: %s\n' "$url"
 
@@ -700,6 +712,11 @@ yaml_write() {
             if [[ -n "$deps" ]]; then
                 printf '    depends_on: [%s]\n' "$deps"
             fi
+
+            # Write branch if it differs from the workspace default
+            if [[ -n "$branch" ]] && [[ "$branch" != "$YAML_DEFAULTS_BRANCH" ]]; then
+                printf '    branch: %s\n' "$branch"
+            fi
         done
 
         printf '\ndefaults:\n'
@@ -708,12 +725,13 @@ yaml_write() {
 }
 
 # Add a repo to the config
-# Usage: yaml_add_repo "url" "path" "tags" "deps"
+# Usage: yaml_add_repo "url" "path" "tags" "deps" ["branch"]
 yaml_add_repo() {
     local url="$1"
     local path="${2:-}"
     local tags="${3:-}"
     local deps="${4:-}"
+    local branch="${5:-}"
 
     local idx=$YAML_REPO_COUNT
 
@@ -725,6 +743,7 @@ yaml_add_repo() {
     YAML_REPO_PATHS[$idx]="$path"
     YAML_REPO_TAGS[$idx]="$tags"
     YAML_REPO_DEPS[$idx]="$deps"
+    YAML_REPO_BRANCHES[$idx]="$branch"
 
     YAML_REPO_COUNT=$((YAML_REPO_COUNT + 1))
 }
@@ -826,6 +845,7 @@ config_init() {
     YAML_REPO_PATHS=()
     YAML_REPO_TAGS=()
     YAML_REPO_DEPS=()
+    YAML_REPO_BRANCHES=()
 
     # Create directory structure
     mkdir -p "$REVO_REPOS_DIR"
@@ -891,7 +911,9 @@ config_load() {
         return 1
     fi
 
-    yaml_parse "$REVO_CONFIG_FILE"
+    if ! yaml_parse "$REVO_CONFIG_FILE"; then
+        return 1
+    fi
 }
 
 # Save configuration
@@ -967,11 +989,25 @@ config_workspace_name() {
     printf '%s' "$YAML_WORKSPACE_NAME"
 }
 
-# Get default branch
+# Get workspace default branch
 config_default_branch() {
     printf '%s' "$YAML_DEFAULTS_BRANCH"
 }
 
+# Get effective default branch for a specific repo
+# Falls back to workspace default if no per-repo branch is set
+# Usage: branch=$(config_repo_default_branch "repo_index")
+config_repo_default_branch() {
+    local idx="$1"
+    local branch
+    branch=$(yaml_get_branch "$idx")
+    if [[ -n "$branch" ]]; then
+        printf '%s' "$branch"
+    else
+        printf '%s' "$YAML_DEFAULTS_BRANCH"
+    fi
+}
+
 # === lib/git.sh ===
 # Revo CLI - Git Operations
 # Wrapper functions for git commands with consistent error handling
@@ -1180,6 +1216,34 @@ git_remote_url() {
     git -C "$repo_dir" remote get-url origin 2>/dev/null
 }
 
+# Detect the default branch for a cloned repo
+# Tries symbolic-ref first, then falls back to checking main/master
+# Usage: branch=$(git_default_branch "repo_dir")
+git_default_branch() {
+    local repo_dir="$1"
+    local ref
+
+    # Best source: what the remote says HEAD points to
+    ref=$(git -C "$repo_dir" symbolic-ref refs/remotes/origin/HEAD 2>/dev/null)
+    if [[ -n "$ref" ]]; then
+        printf '%s' "${ref##*/}"
+        return 0
+    fi
+
+    # Fallback: check which of main/master exists
+    if git -C "$repo_dir" rev-parse --verify origin/main >/dev/null 2>&1; then
+        printf '%s' "main"
+        return 0
+    fi
+    if git -C "$repo_dir" rev-parse --verify origin/master >/dev/null 2>&1; then
+        printf '%s' "master"
+        return 0
+    fi
+
+    # Last resort: whatever branch we're on
+    git -C "$repo_dir" rev-parse --abbrev-ref HEAD 2>/dev/null
+}
+
 # Check if branch exists (local or remote)
 # Usage: if git_branch_exists "repo_dir" "branch_name"; then ...
 git_branch_exists() {
@@ -1299,7 +1363,7 @@ _scan_json_string() {
 _scan_pkg_has_dep() {
     local file="$1"
     local dep="$2"
-    grep -q "\"$dep\"[[:space:]]*:" "$file" 2>/dev/null
+    grep -qF "\"$dep\"" "$file" 2>/dev/null
 }
 
 # Detect framework from package.json dependencies
@@ -1733,8 +1797,10 @@ cmd_init() {
             fi
 
             tags=$(_init_auto_tags "$dir" "$name")
-            yaml_add_repo "$remote" "$path" "$tags" ""
-            ui_step_done "Detected:" "$name → $remote"
+            local branch
+            branch=$(git_default_branch "$dir")
+            yaml_add_repo "$remote" "$path" "$tags" "" "$branch"
+            ui_step_done "Detected:" "$name → $remote (branch: $branch)"
             detected_count=$((detected_count + 1))
         done <<< "$_INIT_FOUND_DIRS"
 
@@ -1839,8 +1905,10 @@ cmd_detect() {
             ln -s "../$name" "repos/$name"
         fi
 
-        yaml_add_repo "$remote" "$name" "$tags" ""
-        ui_step_done "Found:" "$name ($remote)"
+        local branch
+        branch=$(git_default_branch "$d")
+        yaml_add_repo "$remote" "$name" "$tags" "" "$branch"
+        ui_step_done "Found:" "$name ($remote, branch: $branch)"
         found=$((found + 1))
     done
 
@@ -1860,8 +1928,10 @@ cmd_detect() {
             done
             [[ $already -eq 1 ]] && continue
             remote=$(cd "$d" && git remote get-url origin 2>/dev/null || echo "local://$d")
-            yaml_add_repo "$remote" "$name" "$name" ""
-            ui_step_done "Found:" "$name ($remote)"
+            local branch
+            branch=$(git_default_branch "$d")
+            yaml_add_repo "$remote" "$name" "$name" "" "$branch"
+            ui_step_done "Found:" "$name ($remote, branch: $branch)"
             found=$((found + 1))
         done
     fi
@@ -1894,6 +1964,7 @@ cmd_clone() {
     while [[ $# -gt 0 ]]; do
         case "$1" in
             --tag)
+                [[ $# -lt 2 ]] && { ui_step_error "Option --tag requires a value"; return 1; }
                 tag="$2"
                 shift 2
                 ;;
@@ -1966,7 +2037,13 @@ cmd_clone() {
         local clone_err
         if clone_err=$(git clone --quiet "$url" "$full_path" 2>&1); then
             ui_spinner_stop
-            ui_step_done "Cloned:" "$path"
+            # Detect and store the repo's default branch
+            local detected_branch
+            detected_branch=$(git_default_branch "$full_path")
+            if [[ -n "$detected_branch" ]]; then
+                YAML_REPO_BRANCHES[$repo]="$detected_branch"
+            fi
+            ui_step_done "Cloned:" "$path (branch: ${detected_branch:-$YAML_DEFAULTS_BRANCH})"
             success_count=$((success_count + 1))
         else
             ui_spinner_error "Failed to clone: $path"
@@ -1977,9 +2054,12 @@ cmd_clone() {
         fi
     done <<< "$repos"
 
-    # Always regenerate the workspace CLAUDE.md after a clone batch so that
-    # newly cloned repos appear in the context immediately.
+    # Persist any newly detected per-repo branches and regenerate CLAUDE.md
+    # so newly cloned repos appear in the context immediately.
     if [[ $fail_count -eq 0 ]] && { [[ $success_count -gt 0 ]] || [[ $skip_count -gt 0 ]]; }; then
+        if [[ $success_count -gt 0 ]]; then
+            config_save
+        fi
         context_regenerate_silent
     fi
 
@@ -2011,6 +2091,7 @@ cmd_status() {
     while [[ $# -gt 0 ]]; do
         case "$1" in
             --tag)
+                [[ $# -lt 2 ]] && { ui_step_error "Option --tag requires a value"; return 1; }
                 tag="$2"
                 shift 2
                 ;;
@@ -2105,6 +2186,7 @@ cmd_branch() {
     while [[ $# -gt 0 ]]; do
         case "$1" in
             --tag)
+                [[ $# -lt 2 ]] && { ui_step_error "Option --tag requires a value"; return 1; }
                 tag="$2"
                 shift 2
                 ;;
@@ -2209,6 +2291,7 @@ cmd_checkout() {
     while [[ $# -gt 0 ]]; do
         case "$1" in
             --tag)
+                [[ $# -lt 2 ]] && { ui_step_error "Option --tag requires a value"; return 1; }
                 tag="$2"
                 shift 2
                 ;;
@@ -2268,6 +2351,12 @@ cmd_checkout() {
             continue
         fi
 
+        # Resolve "default" to each repo's own default branch
+        local target="$branch_name"
+        if [[ "$target" == "default" ]]; then
+            target=$(config_repo_default_branch "$repo")
+        fi
+
         # Check for uncommitted changes
         if git_is_dirty "$full_path" && [[ $force -eq 0 ]]; then
             ui_step_error "Uncommitted changes: $path"
@@ -2277,15 +2366,15 @@ cmd_checkout() {
         fi
 
         # Check if branch exists
-        if ! git_branch_exists "$full_path" "$branch_name"; then
-            ui_step_error "Branch not found: $path"
+        if ! git_branch_exists "$full_path" "$target"; then
+            ui_step_error "Branch not found: $path ($target)"
             fail_count=$((fail_count + 1))
             continue
         fi
 
         # Checkout
-        if git_checkout "$full_path" "$branch_name"; then
-            ui_step_done "Checked out:" "$path → $branch_name"
+        if git_checkout "$full_path" "$target"; then
+            ui_step_done "Checked out:" "$path → $target"
             success_count=$((success_count + 1))
         else
             ui_step_error "Failed: $path - $GIT_ERROR"
@@ -2323,6 +2412,7 @@ cmd_sync() {
     while [[ $# -gt 0 ]]; do
         case "$1" in
             --tag)
+                [[ $# -lt 2 ]] && { ui_step_error "Option --tag requires a value"; return 1; }
                 tag="$2"
                 shift 2
                 ;;
@@ -2429,6 +2519,7 @@ cmd_exec() {
     while [[ $# -gt 0 ]]; do
         case "$1" in
             --tag)
+                [[ $# -lt 2 ]] && { ui_step_error "Option --tag requires a value"; return 1; }
                 tag="$2"
                 shift 2
                 ;;
@@ -2499,7 +2590,7 @@ cmd_exec() {
         local output
         local exit_code
 
-        if output=$(cd "$full_path" && eval "$command" 2>&1); then
+        if output=$(cd "$full_path" && bash -c "$command" 2>&1); then
             exit_code=0
         else
             exit_code=$?
@@ -2549,14 +2640,17 @@ cmd_add() {
     while [[ $# -gt 0 ]]; do
         case "$1" in
             --tags)
+                [[ $# -lt 2 ]] && { ui_step_error "Option --tags requires a value"; return 1; }
                 tags="$2"
                 shift 2
                 ;;
             --path)
+                [[ $# -lt 2 ]] && { ui_step_error "Option --path requires a value"; return 1; }
                 path="$2"
                 shift 2
                 ;;
             --depends-on)
+                [[ $# -lt 2 ]] && { ui_step_error "Option --depends-on requires a value"; return 1; }
                 deps="$2"
                 shift 2
                 ;;
@@ -2643,6 +2737,7 @@ cmd_list() {
     while [[ $# -gt 0 ]]; do
         case "$1" in
             --tag)
+                [[ $# -lt 2 ]] && { ui_step_error "Option --tag requires a value"; return 1; }
                 tag="$2"
                 shift 2
                 ;;
@@ -2899,6 +2994,17 @@ _context_write_file() {
         url=$(yaml_get_url "$i")
         full_path="$REVO_REPOS_DIR/$path"
 
+        local branch
+        branch=$(yaml_get_branch "$i")
+
+        # Backfill: detect default branch for cloned repos that don't have one stored
+        if [[ -z "$branch" ]] && [[ -d "$full_path" ]]; then
+            branch=$(git_default_branch "$full_path")
+            if [[ -n "$branch" ]]; then
+                YAML_REPO_BRANCHES[$i]="$branch"
+            fi
+        fi
+
         {
             printf '### %s\n' "$path"
 
@@ -2906,6 +3012,9 @@ _context_write_file() {
                 printf -- '- **Tags:** %s\n' "$tags"
             fi
             printf -- '- **Path:** repos/%s\n' "$path"
+            if [[ -n "$branch" ]] && [[ "$branch" != "$YAML_DEFAULTS_BRANCH" ]]; then
+                printf -- '- **Default branch:** %s\n' "$branch"
+            fi
             if [[ -n "$deps" ]]; then
                 printf -- '- **Depends on:** %s\n' "$deps"
             fi
@@ -3031,38 +3140,87 @@ _context_write_file() {
         done
     fi
 
-    # Agent instructions + revo tool docs
+    # Agent instructions — directive workflows for Claude Code
     {
         printf '\n'
         printf '## Agent Instructions\n'
         printf '\n'
-        printf 'When working in this workspace:\n'
+        printf 'You are working in a multi-repo workspace managed by **revo**. Do NOT explore\n'
+        printf 'to figure out what revo is — it is a CLI tool already installed in the terminal. Use it.\n'
         printf '\n'
-        printf '1. Read this file first to understand the repo structure\n'
-        printf '2. Check `.revo/features/` for active feature contexts\n'
-        printf '3. Follow the dependency order above when making cross-repo changes\n'
-        printf '4. Each repo may have its own CLAUDE.md with repo-specific instructions\n'
-        printf '5. Use `revo status` to check state across all repos\n'
-        printf '6. Use `revo commit "msg"` to commit across all repos at once\n'
-        printf '7. Use `revo feature <name>` to start a coordinated feature workspace\n'
-        printf '8. Use `revo pr "title"` to open coordinated pull requests\n'
-        printf '9. Use `revo workspace <name>` to get a full-copy isolated workspace\n'
-        printf '   under `.revo/workspaces/<name>/` (zero bootstrap, .env included)\n'
+        printf '### Critical Rules\n'
         printf '\n'
-        printf '## Workspace Tool: revo\n'
+        printf -- '- ALWAYS read `.revo/features/<name>.md` before starting work on any feature. It contains the plan.\n'
+        printf -- '- NEVER ask "what is the scope?" for a feature that has a feature file. The file IS the scope.\n'
+        printf -- '- When uncertain about revo commands, run `revo --help` or read `.revo/COMMANDS.md`.\n'
+        printf -- '- Use `revo` commands for all cross-repo git operations. Do not manually cd into each repo and run git.\n'
+        printf -- '- Each repo may have its own CLAUDE.md with repo-specific instructions — read it when working in that repo.\n'
+        printf -- '- Follow the dependency order above when making cross-repo changes.\n'
+        printf '\n'
+        printf '### Workflows\n'
+        printf '\n'
+        printf '**"Work on feature X" or "Begin work on X":**\n'
+        printf '1. Read `.revo/features/X.md` for the plan (if it does not exist, run `revo feature X` first)\n'
+        printf '2. Run `revo status` to confirm you are on the right branches\n'
+        printf '3. Start implementing according to the plan. Follow the dependency order in this file.\n'
+        printf '\n'
+        printf '**"Work on feature X use workspaces" or "use workspace":**\n'
+        printf '1. Run `revo workspace X` to create an isolated copy at `.revo/workspaces/X/`\n'
+        printf '2. cd into `.revo/workspaces/X/` — all subsequent revo commands operate on the workspace\n'
+        printf '3. Read `.revo/features/X.md` (in the workspace root) for context\n'
+        printf '4. Implement the feature. Commit with `revo commit "msg"` when ready.\n'
+        printf '\n'
+        printf '**"Create a feature for X" or "Plan feature X":**\n'
+        printf '1. Run `revo feature X` to create branches and `.revo/features/X.md`\n'
+        printf '2. Edit `.revo/features/X.md` with the plan (scope, affected repos, approach)\n'
+        printf '\n'
+        printf '**"Commit" or "Save progress":**\n'
+        printf '1. Run `revo commit "descriptive message"` — stages and commits all dirty repos\n'
+        printf '\n'
+        printf '**"Push and PR" or "Open pull requests":**\n'
+        printf '1. Run `revo push` to push all branches\n'
+        printf '2. Run `revo pr "PR title"` to create coordinated, cross-referenced PRs\n'
+        printf '\n'
+        printf '**"Status" or "Sync":**\n'
+        printf '1. `revo status` — branch and dirty state across all repos\n'
+        printf '2. `revo sync` — pull latest across all repos\n'
+        printf '\n'
+        printf '### Quick Reference\n'
+        printf '\n'
+        printf 'Run `revo --help` for all commands. Key ones: `status`, `commit`, `push`,\n'
+        printf '`pr`, `feature`, `workspace`, `sync`, `exec`, `checkout default`, `issue list`.\n'
+        printf 'All commands accept `--tag TAG` to filter by repo tag.\n'
+        printf 'See `.revo/COMMANDS.md` for the full command reference with examples.\n'
+        printf '\n'
+        printf '%s\n' "$CONTEXT_END_MARKER"
+    } >> "$output"
+
+    # Splice the auto block into the target file, preserving any user content.
+    _context_merge_into "$output" "$target"
+    rm -f "$output"
+}
+
+# Write the .revo/COMMANDS.md reference file. Detailed command docs that
+# Claude Code can read on-demand, kept out of the main CLAUDE.md so the
+# agent sees directive workflows first, not a wall of syntax.
+_context_write_commands_file() {
+    local target="$REVO_WORKSPACE_ROOT/.revo/COMMANDS.md"
+    mkdir -p "$REVO_WORKSPACE_ROOT/.revo"
+
+    {
+        printf '# revo Command Reference\n'
         printf '\n'
-        printf 'This workspace is managed by revo.\n'
         printf 'Source: https://github.com/jippylong12/revo\n'
         printf '\n'
-        printf '### Available commands (run in terminal)\n'
+        printf '## Setup\n'
         printf '\n'
-        printf '**Setup:**\n'
         printf -- '- `revo add <git-url> --tags <tags> [--depends-on <repo>]` — add a repo\n'
         printf -- '- `revo clone` — clone all configured repos\n'
-        printf -- '- `revo context` — regenerate this file\n'
+        printf -- '- `revo context` — regenerate workspace CLAUDE.md\n'
         printf -- '- `revo detect` — bootstrap around existing repos in cwd\n'
         printf '\n'
-        printf '**Daily workflow:**\n'
+        printf '## Daily Workflow\n'
+        printf '\n'
         printf -- '- `revo status` — branch and dirty state across all repos\n'
         printf -- '- `revo sync` — pull latest across all repos\n'
         printf -- '- `revo feature <name> [--tag t]` — create feature branch across repos\n'
@@ -3071,53 +3229,64 @@ _context_write_file() {
         printf -- '- `revo pr "title" [--tag t]` — create coordinated PRs via gh CLI\n'
         printf -- '- `revo exec "cmd" [--tag t]` — run command in filtered repos\n'
         printf -- '- `revo checkout <branch> [--tag t]` — switch branch across repos\n'
+        printf -- '- `revo checkout default` — switch each repo to its own default branch (handles mixed main/master)\n'
+        printf '\n'
+        printf '## Workspaces\n'
         printf '\n'
-        printf '**Workspaces (full-copy isolated workspaces):**\n'
         printf -- '- `revo workspace <name> [--tag t]` — full copy of repos into `.revo/workspaces/<name>/` on `feature/<name>`\n'
         printf -- '- `revo workspaces` — list active workspaces with branch and dirty state\n'
         printf -- '- `revo workspace <name> --delete [--force]` — remove a workspace\n'
         printf -- '- `revo workspace --clean` — remove workspaces whose branches are merged\n'
         printf '\n'
         printf 'Workspaces hardlink-copy everything (including `.env`, `node_modules`,\n'
-        printf 'build artifacts) so Claude can start work with zero bootstrap. Run\n'
+        printf 'build artifacts) so you can start work with zero bootstrap. Run\n'
         printf '`revo` from inside `.revo/workspaces/<name>/` and it operates on the\n'
         printf 'workspace copies, not the source tree.\n'
         printf '\n'
-        printf '**Issues (cross-repo, via gh CLI):**\n'
+        printf '## Issues (cross-repo, via gh CLI)\n'
+        printf '\n'
         printf -- '- `revo issue list [--tag t] [--state open|closed|all] [--label L] [--json]` — list issues across repos\n'
         printf -- '- `revo issue create --repo <name> "title" [--body b] [--label L] [--feature F]` — create in one repo\n'
         printf -- '- `revo issue create --tag <t> "title" [--body b] [--feature F]` — create in every matching repo, cross-referenced\n'
         printf '\n'
         printf 'Use `--json` on `revo issue list` to get a flat JSON array (each entry has\n'
-        printf 'a `repo` field) — easy to filter or pipe into jq when reasoning about\n'
-        printf 'cross-repo issue state.\n'
+        printf 'a `repo` field) — easy to filter or pipe into jq.\n'
         printf '\n'
-        printf '### Tag filtering\n'
+        printf '## Tag Filtering\n'
         printf '\n'
         printf 'All commands support `--tag <tag>` to target specific repos:\n'
         printf '\n'
         printf '```\n'
         printf 'revo exec "npm test" --tag frontend\n'
         printf 'revo sync --tag backend\n'
-        printf 'revo branch hotfix --tag api\n'
+        printf 'revo commit "fix: typo" --tag api\n'
         printf '```\n'
         printf '\n'
-        printf '### Feature workflow\n'
+        printf '## Feature Workflow\n'
         printf '\n'
         printf '```\n'
-        printf 'revo feature my-feature          # branches all repos\n'
-        printf '# edit .revo/features/my-feature.md to describe scope\n'
+        printf 'revo feature my-feature          # branches all repos, writes .revo/features/my-feature.md\n'
+        printf '# edit .revo/features/my-feature.md with your plan\n'
         printf '# work across repos\n'
         printf 'revo commit "feat: my feature"   # commits all dirty repos\n'
+        printf 'revo push                        # push all branches\n'
         printf 'revo pr "My feature"             # coordinated PRs\n'
         printf '```\n'
         printf '\n'
-        printf '%s\n' "$CONTEXT_END_MARKER"
-    } >> "$output"
-
-    # Splice the auto block into the target file, preserving any user content.
-    _context_merge_into "$output" "$target"
-    rm -f "$output"
+        printf '## Workspace Workflow\n'
+        printf '\n'
+        printf '```\n'
+        printf 'revo workspace my-feature        # full copy to .revo/workspaces/my-feature/\n'
+        printf 'cd .revo/workspaces/my-feature   # enter the workspace\n'
+        printf 'revo status                      # operates on workspace repos\n'
+        printf '# work across repos\n'
+        printf 'revo commit "feat: my feature"   # commits workspace repos\n'
+        printf 'revo push                        # push workspace branches\n'
+        printf 'revo pr "My feature"             # coordinated PRs from workspace\n'
+        printf 'cd ../../..                      # back to main workspace\n'
+        printf 'revo workspace my-feature --delete  # clean up\n'
+        printf '```\n'
+    } > "$target"
 }
 
 cmd_context() {
@@ -3151,9 +3320,13 @@ cmd_context() {
 
     ui_spinner_start "Scanning $YAML_REPO_COUNT repositories..."
     _context_write_file "$output"
+    # Persist any newly detected per-repo branches back to revo.yaml
+    config_save
     ui_spinner_stop
+    _context_write_commands_file
     ui_step_done "Scanned:" "$YAML_REPO_COUNT repositories"
     ui_step_done "Wrote:" "CLAUDE.md"
+    ui_step_done "Wrote:" ".revo/COMMANDS.md"
 
     if [[ $CONTEXT_CYCLE -eq 1 ]]; then
         ui_step_error "Dependency cycle detected - see CLAUDE.md for order"
@@ -3172,6 +3345,7 @@ context_regenerate_silent() {
 
     local output="$REVO_WORKSPACE_ROOT/CLAUDE.md"
     _context_write_file "$output"
+    _context_write_commands_file
     ui_info "$(ui_dim "Regenerated CLAUDE.md for Claude Code")"
     return 0
 }
@@ -3187,6 +3361,7 @@ cmd_feature() {
     while [[ $# -gt 0 ]]; do
         case "$1" in
             --tag)
+                [[ $# -lt 2 ]] && { ui_step_error "Option --tag requires a value"; return 1; }
                 tag="$2"
                 shift 2
                 ;;
@@ -3286,10 +3461,10 @@ cmd_feature() {
             printf '# Feature: %s\n' "$name"
             printf '\n'
             printf '## Status\n'
-            printf '- Created: %s\n' "$timestamp"
-            printf '- Branch: %s\n' "$branch"
+            printf -- '- Created: %s\n' "$timestamp"
+            printf -- '- Branch: %s\n' "$branch"
             if [[ -n "$tag" ]]; then
-                printf '- Tag filter: %s\n' "$tag"
+                printf -- '- Tag filter: %s\n' "$tag"
             fi
             printf '\n'
             printf '## Repos\n'
@@ -3348,6 +3523,7 @@ cmd_commit() {
     while [[ $# -gt 0 ]]; do
         case "$1" in
             --tag)
+                [[ $# -lt 2 ]] && { ui_step_error "Option --tag requires a value"; return 1; }
                 tag="$2"
                 shift 2
                 ;;
@@ -3455,6 +3631,7 @@ cmd_push() {
     while [[ $# -gt 0 ]]; do
         case "$1" in
             --tag)
+                [[ $# -lt 2 ]] && { ui_step_error "Option --tag requires a value"; return 1; }
                 tag="$2"
                 shift 2
                 ;;
@@ -3573,10 +3750,12 @@ cmd_pr() {
     while [[ $# -gt 0 ]]; do
         case "$1" in
             --tag)
+                [[ $# -lt 2 ]] && { ui_step_error "Option --tag requires a value"; return 1; }
                 tag="$2"
                 shift 2
                 ;;
             --body)
+                [[ $# -lt 2 ]] && { ui_step_error "Option --body requires a value"; return 1; }
                 body="$2"
                 shift 2
                 ;;
@@ -3814,10 +3993,10 @@ _issue_list() {
 
     while [[ $# -gt 0 ]]; do
         case "$1" in
-            --tag) tag="$2"; shift 2 ;;
-            --state) state="$2"; shift 2 ;;
-            --label) label="$2"; shift 2 ;;
-            --limit) limit="$2"; shift 2 ;;
+            --tag) [[ $# -lt 2 ]] && { ui_step_error "Option --tag requires a value"; return 1; }; tag="$2"; shift 2 ;;
+            --state) [[ $# -lt 2 ]] && { ui_step_error "Option --state requires a value"; return 1; }; state="$2"; shift 2 ;;
+            --label) [[ $# -lt 2 ]] && { ui_step_error "Option --label requires a value"; return 1; }; label="$2"; shift 2 ;;
+            --limit) [[ $# -lt 2 ]] && { ui_step_error "Option --limit requires a value"; return 1; }; limit="$2"; shift 2 ;;
             --json) as_json=1; shift ;;
             --help|-h) _issue_help; return 0 ;;
             *) ui_step_error "Unknown option: $1"; return 1 ;;
@@ -3981,12 +4160,12 @@ _issue_create() {
 
     while [[ $# -gt 0 ]]; do
         case "$1" in
-            --repo) repo="$2"; shift 2 ;;
-            --tag) tag="$2"; shift 2 ;;
-            --body) body="$2"; shift 2 ;;
-            --label) labels="$2"; shift 2 ;;
-            --assignee) assignee="$2"; shift 2 ;;
-            --feature) feature="$2"; shift 2 ;;
+            --repo) [[ $# -lt 2 ]] && { ui_step_error "Option --repo requires a value"; return 1; }; repo="$2"; shift 2 ;;
+            --tag) [[ $# -lt 2 ]] && { ui_step_error "Option --tag requires a value"; return 1; }; tag="$2"; shift 2 ;;
+            --body) [[ $# -lt 2 ]] && { ui_step_error "Option --body requires a value"; return 1; }; body="$2"; shift 2 ;;
+            --label) [[ $# -lt 2 ]] && { ui_step_error "Option --label requires a value"; return 1; }; labels="$2"; shift 2 ;;
+            --assignee) [[ $# -lt 2 ]] && { ui_step_error "Option --assignee requires a value"; return 1; }; assignee="$2"; shift 2 ;;
+            --feature) [[ $# -lt 2 ]] && { ui_step_error "Option --feature requires a value"; return 1; }; feature="$2"; shift 2 ;;
             --help|-h) _issue_help; return 0 ;;
             -*) ui_step_error "Unknown option: $1"; return 1 ;;
             *)
@@ -4744,6 +4923,7 @@ cmd_workspace() {
     while [[ $# -gt 0 ]]; do
         case "$1" in
             --tag)
+                [[ $# -lt 2 ]] && { ui_step_error "Option --tag requires a value"; return 1; }
                 tag="$2"
                 shift 2
                 ;;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revotools/cli",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Claude-first multi-repo workspace manager (fork of Mars)",
   "bin": {
     "revo": "./dist/revo"