From d5bc28ccaf64fa45c2edabe9bb6481fad015fac4 Mon Sep 17 00:00:00 2001
From: NagyVikt <nagy.viktordp@gmail.com>
Date: Thu, 28 May 2026 22:20:57 +0200
Subject: [PATCH] fix(scripts): handle -h/--help in branch start/finish instead
 of exit 1

`--help` fell into the unknown-option catch-all and exited 1 with an
"Unknown option/argument" error. Add an explicit -h|--help case that
prints usage and exits 0 for agent-branch-start and agent-branch-finish
(branch-merge already handled it). Also patch the older frontend copy.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 frontend/scripts/agent-branch-start.sh   | 26 ++++++++++++++++++++
 templates/scripts/agent-branch-finish.sh |  4 +++
 templates/scripts/agent-branch-start.sh  | 31 ++++++++++++++++++++++++
 3 files changed, 61 insertions(+)

diff --git a/frontend/scripts/agent-branch-start.sh b/frontend/scripts/agent-branch-start.sh
index 505acb44..f84c9c24 100755
--- a/frontend/scripts/agent-branch-start.sh
+++ b/frontend/scripts/agent-branch-start.sh
@@ -15,8 +15,34 @@ OPENSPEC_MASTERPLAN_LABEL_RAW="${GUARDEX_OPENSPEC_MASTERPLAN_LABEL-masterplan}"
 PRINT_NAME_ONLY=0
 POSITIONAL_ARGS=()
 
+print_usage() {
+  cat <<'USAGE'
+Usage: agent-branch-start [task] [agent] [base] [options]
+
+Start an isolated agent/* branch + worktree for a task.
+
+Positional:
+  task                 Task name/slug (default: "task")
+  agent                Agent name (default: "agent")
+  base                 Base branch to fork from (default: repo default)
+
+Options:
+  --task <name>        Task name/slug
+  --agent <name>       Agent name
+  --base <branch>      Base branch to fork from
+  --worktree-root <p>  Worktree root dir (default: .omx/agent-worktrees)
+  --tier <T1|T2|T3>    OpenSpec tier (accepted for compatibility)
+  --print-name-only    Print the computed branch name and exit
+  -h, --help           Show this help and exit
+USAGE
+}
+
 while [[ $# -gt 0 ]]; do
   case "$1" in
+    -h|--help)
+      print_usage
+      exit 0
+      ;;
     --task)
       TASK_NAME="${2:-task}"
       shift 2
diff --git a/templates/scripts/agent-branch-finish.sh b/templates/scripts/agent-branch-finish.sh
index eca43b85..1d6e5367 100755
--- a/templates/scripts/agent-branch-finish.sh
+++ b/templates/scripts/agent-branch-finish.sh
@@ -150,6 +150,10 @@ AUTO_PROMOTE_DRAFT="$(normalize_bool "$AUTO_PROMOTE_DRAFT_RAW" "1")"
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
+    -h|--help)
+      echo "Usage: $0 [--base <branch>] [--branch <branch>] [--no-push] [--cleanup|--no-cleanup] [--wait-for-merge|--no-wait-for-merge] [--wait-timeout-seconds <n>] [--wait-poll-seconds <n>] [--parent-gitlink-commit|--no-parent-gitlink-commit] [--keep-remote-branch|--delete-remote-branch] [--mode auto|direct|pr|--via-pr|--direct-only] [--auto-resolve[=none|safe|full]|--no-auto-resolve] [--no-preflight|--preflight] [--preflight-script <path>] [--no-auto-promote|--auto-promote]"
+      exit 0
+      ;;
     --base)
       BASE_BRANCH="${2:-}"
       BASE_BRANCH_EXPLICIT=1
diff --git a/templates/scripts/agent-branch-start.sh b/templates/scripts/agent-branch-start.sh
index 0fc417a9..7a44bfb8 100755
--- a/templates/scripts/agent-branch-start.sh
+++ b/templates/scripts/agent-branch-start.sh
@@ -39,8 +39,39 @@ run_guardex_cli() {
   return 127
 }
 
+print_usage() {
+  cat <<'USAGE'
+Usage: agent-branch-start [task] [agent] [base] [options]
+
+Start an isolated agent/* branch + worktree for a task.
+
+Positional:
+  task                 Task name/slug (default: "task")
+  agent                Agent name (default: "agent")
+  base                 Base branch to fork from (default: repo default)
+
+Options:
+  --task <name>        Task name/slug
+  --agent <name>       Agent name
+  --base <branch>      Base branch to fork from
+  --worktree-root <p>  Worktree root dir (default: .omx/agent-worktrees)
+  --reuse-existing     Reuse an existing matching worktree (default)
+  --new                Force a fresh worktree instead of reusing
+  --tier <T1|T2|T3>    OpenSpec tier for scaffolding
+  --transfer           Auto-transfer uncommitted changes into the worktree (default)
+  --no-transfer        Do not auto-transfer uncommitted changes
+  --transfer-exclude <globs>  Colon-separated globs to exclude from transfer
+  --print-name-only    Print the computed branch name and exit
+  -h, --help           Show this help and exit
+USAGE
+}
+
 while [[ $# -gt 0 ]]; do
   case "$1" in
+    -h|--help)
+      print_usage
+      exit 0
+      ;;
     --task)
       TASK_NAME="${2:-task}"
       shift 2