@imdeadpool/guardex 7.0.18 → 7.0.20

package/src/toolchain/index.js

@@ -0,0 +1,223 @@
+function createToolchainApi(deps) {
+  const {
+    TOOL_NAME,
+    NPM_BIN,
+    NPX_BIN,
+    packageJson,
+    OPENSPEC_PACKAGE,
+    OPENSPEC_BIN,
+    GLOBAL_TOOLCHAIN_PACKAGES,
+    parseAutoApproval,
+    isInteractiveTerminal,
+    promptYesNoStrict,
+    run,
+    checkForGuardexUpdate,
+    printUpdateAvailableBanner,
+    readInstalledGuardexVersion,
+    restartIntoUpdatedGuardex,
+    checkForOpenSpecPackageUpdate,
+    printOpenSpecUpdateAvailableBanner,
+    resolveGlobalInstallApproval,
+    detectGlobalToolchainPackages,
+    detectOptionalLocalCompanionTools,
+    formatGlobalToolchainServiceName,
+    askGlobalInstallForMissing,
+  } = deps;
+
+  function maybeSelfUpdateBeforeStatus() {
+    const check = checkForGuardexUpdate();
+    if (!check.checked || !check.updateAvailable) {
+      return;
+    }
+
+    printUpdateAvailableBanner(check.current, check.latest);
+
+    const autoApproval = parseAutoApproval('GUARDEX_AUTO_UPDATE_APPROVAL');
+    const interactive = isInteractiveTerminal();
+
+    if (!interactive && autoApproval == null) {
+      console.log(`[${TOOL_NAME}] Non-interactive shell; skipping auto-update prompt.`);
+      return;
+    }
+
+    const shouldUpdate = interactive
+      ? promptYesNoStrict(
+        `Update now? (${NPM_BIN} i -g ${packageJson.name}@latest)`,
+      )
+      : autoApproval;
+
+    if (!shouldUpdate) {
+      console.log(`[${TOOL_NAME}] Skipped update.`);
+      return;
+    }
+
+    const installResult = run(NPM_BIN, ['i', '-g', `${packageJson.name}@latest`], { stdio: 'inherit' });
+    if (installResult.status !== 0) {
+      console.log(`[${TOOL_NAME}] ⚠️ Update failed. You can retry manually.`);
+      return;
+    }
+
+    const postInstallVersion = readInstalledGuardexVersion();
+    if (postInstallVersion != null && postInstallVersion !== check.latest) {
+      console.log(
+        `[${TOOL_NAME}] Installed version is still ${postInstallVersion} (expected ${check.latest}). ` +
+          `Retrying with pinned version ${check.latest}…`,
+      );
+      const pinnedResult = run(
+        NPM_BIN,
+        ['i', '-g', `${packageJson.name}@${check.latest}`],
+        { stdio: 'inherit' },
+      );
+      if (pinnedResult.status !== 0) {
+        console.log(
+          `[${TOOL_NAME}] ⚠️ Pinned retry failed. Run manually: ${NPM_BIN} i -g ${packageJson.name}@${check.latest}`,
+        );
+        return;
+      }
+      const pinnedVersion = readInstalledGuardexVersion();
+      if (pinnedVersion != null && pinnedVersion !== check.latest) {
+        console.log(
+          `[${TOOL_NAME}] ⚠️ On-disk version still ${pinnedVersion} after pinned retry. ` +
+            `Investigate: ${NPM_BIN} root -g && ${NPM_BIN} cache verify`,
+        );
+        return;
+      }
+    }
+
+    console.log(`[${TOOL_NAME}] ✅ Updated to latest published version.`);
+    restartIntoUpdatedGuardex(check.latest);
+  }
+
+  function maybeOpenSpecUpdateBeforeStatus() {
+    const check = checkForOpenSpecPackageUpdate();
+    if (!check.checked || !check.updateAvailable) {
+      return;
+    }
+
+    printOpenSpecUpdateAvailableBanner(check.current, check.latest);
+
+    const autoApproval = parseAutoApproval('GUARDEX_AUTO_OPENSPEC_UPDATE_APPROVAL');
+    const interactive = isInteractiveTerminal();
+
+    if (!interactive && autoApproval == null) {
+      console.log(`[${TOOL_NAME}] Non-interactive shell; skipping OpenSpec update prompt.`);
+      return;
+    }
+
+    const shouldUpdate = interactive
+      ? promptYesNoStrict(
+        `Update OpenSpec now? (${NPM_BIN} i -g ${OPENSPEC_PACKAGE}@latest && ${OPENSPEC_BIN} update)`,
+      )
+      : autoApproval;
+
+    if (!shouldUpdate) {
+      console.log(`[${TOOL_NAME}] Skipped OpenSpec update.`);
+      return;
+    }
+
+    const installResult = run(NPM_BIN, ['i', '-g', `${OPENSPEC_PACKAGE}@latest`], { stdio: 'inherit' });
+    if (installResult.status !== 0) {
+      console.log(`[${TOOL_NAME}] ⚠️ OpenSpec npm install failed. You can retry manually.`);
+      return;
+    }
+
+    const toolUpdateResult = run(OPENSPEC_BIN, ['update'], { stdio: 'inherit' });
+    if (toolUpdateResult.status !== 0) {
+      console.log(`[${TOOL_NAME}] ⚠️ OpenSpec tool update failed. Run '${OPENSPEC_BIN} update' manually.`);
+      return;
+    }
+
+    console.log(`[${TOOL_NAME}] ✅ OpenSpec updated to latest package and tool plugins refreshed.`);
+  }
+
+  function installGlobalToolchain(options) {
+    const approval = resolveGlobalInstallApproval(options);
+    if (approval.source === 'flag' && !approval.approved) {
+      return {
+        status: 'skipped',
+        reason: approval.source,
+        missingPackages: [],
+        missingLocalTools: [],
+      };
+    }
+
+    if (options.dryRun) {
+      return { status: 'dry-run-skip' };
+    }
+
+    const detection = detectGlobalToolchainPackages();
+    const localCompanionTools = detectOptionalLocalCompanionTools();
+    if (!detection.ok) {
+      console.log(`[${TOOL_NAME}] ⚠️ Could not detect global packages: ${detection.error}`);
+    } else {
+      if (detection.installed.length > 0) {
+        console.log(
+          `[${TOOL_NAME}] Already installed globally: ` +
+          `${detection.installed.map((pkg) => formatGlobalToolchainServiceName(pkg)).join(', ')}`,
+        );
+      }
+      const installedLocalTools = localCompanionTools
+        .filter((tool) => tool.status === 'active')
+        .map((tool) => tool.name);
+      if (installedLocalTools.length > 0) {
+        console.log(`[${TOOL_NAME}] Already installed locally: ${installedLocalTools.join(', ')}`);
+      }
+      if (detection.missing.length === 0 && localCompanionTools.every((tool) => tool.status === 'active')) {
+        return { status: 'already-installed' };
+      }
+    }
+
+    const missingPackages = detection.ok ? detection.missing : [...GLOBAL_TOOLCHAIN_PACKAGES];
+    const missingLocalTools = localCompanionTools.filter((tool) => tool.status !== 'active');
+    const installApproval = askGlobalInstallForMissing(options, missingPackages, missingLocalTools);
+    if (!installApproval.approved) {
+      return {
+        status: 'skipped',
+        reason: installApproval.source,
+        missingPackages,
+        missingLocalTools,
+      };
+    }
+
+    const installed = [];
+    if (missingPackages.length > 0) {
+      console.log(
+        `[${TOOL_NAME}] Installing global toolchain: npm i -g ${missingPackages.join(' ')}`,
+      );
+      const result = run(NPM_BIN, ['i', '-g', ...missingPackages], { stdio: 'inherit' });
+      if (result.status !== 0) {
+        const stderr = (result.stderr || '').trim();
+        return {
+          status: 'failed',
+          reason: stderr || 'npm global install failed',
+        };
+      }
+      installed.push(...missingPackages);
+    }
+
+    for (const tool of missingLocalTools) {
+      console.log(`[${TOOL_NAME}] Installing local companion tool: ${tool.installCommand}`);
+      const result = run(NPX_BIN, tool.installArgs, { stdio: 'inherit' });
+      if (result.status !== 0) {
+        const stderr = (result.stderr || '').trim();
+        return {
+          status: 'failed',
+          reason: stderr || `${tool.name} install failed`,
+        };
+      }
+      installed.push(tool.name);
+    }
+
+    return { status: 'installed', packages: installed };
+  }
+
+  return {
+    maybeSelfUpdateBeforeStatus,
+    maybeOpenSpecUpdateBeforeStatus,
+    installGlobalToolchain,
+  };
+}
+
+module.exports = {
+  createToolchainApi,
+};

package/templates/AGENTS.multiagent-safety.md

@@ -7,6 +7,9 @@
 `GUARDEX_ON=0` disables Guardex for that repo.
 `GUARDEX_ON=1` explicitly enables Guardex for that repo again.
 
+**Task-size routing.** Small tasks stay in direct caveman-only mode. For typos, single-file tweaks, one-liners, version bumps, or similarly bounded asks, solve directly and do not escalate into heavy OMX orchestration just because a keyword appears. Treat `quick:`, `simple:`, `tiny:`, `minor:`, `small:`, `just:`, and `only:` as explicit lightweight escape hatches.
+Promote to OMX orchestration only when the task is medium/large: multi-file behavior changes, API/schema work, refactors, migrations, architecture, cross-cutting scope, or long prompts. Heavy OMX modes (`ralph`, `autopilot`, `team`, `ultrawork`, `swarm`, `ralplan`) are for that larger scope. If the task grows while working, upgrade then.
+
 **Isolation.** Every task runs on a dedicated `agent/*` branch + worktree. Start with `gx branch start "<task>" "<agent-name>"`. Treat the base branch (`main`/`dev`) as read-only while an agent branch is active. Never `git checkout <branch>` on a primary working tree (including nested repos); use `git worktree add` instead. The `.githooks/post-checkout` hook auto-reverts primary-branch switches during agent sessions - bypass only with `GUARDEX_ALLOW_PRIMARY_BRANCH_SWITCH=1`.
 For every new task, including follow-up work in the same chat/session, if an assigned agent sub-branch/worktree is already open, continue in that sub-branch instead of creating a fresh lane unless the user explicitly redirects scope.
 Never implement directly on the local/base branch checkout; keep it unchanged and perform all edits in the agent sub-branch/worktree.

package/templates/codex/skills/gitguardex/SKILL.md

@@ -8,4 +8,4 @@ Use when repo safety may be broken.
 `gx status` -> `gx doctor` -> `gx status --strict`
 
 Bootstrap: `gx setup`
-Ops: `bash scripts/codex-agent.sh "<task>" "<agent>"`, `gx finish --all`, `gx cleanup`
+Ops: `gx branch start "<task>" "<agent>"`, `gx locks claim --branch "<agent-branch>" <file...>`, `gx branch finish --branch "<agent-branch>" --base <base> --via-pr --wait-for-merge --cleanup`, `gx finish --all`, `gx cleanup`

package/templates/codex/skills/guardex-merge-skills-to-dev/SKILL.md

@@ -24,7 +24,7 @@ echo "$BASE_BRANCH"
 2. Start a dedicated integration sandbox from base:
 
 ```sh
-bash scripts/agent-branch-start.sh "merge-skill-files-to-${BASE_BRANCH}" "skill-merge" "$BASE_BRANCH"
+gx branch start "merge-skill-files-to-${BASE_BRANCH}" "skill-merge" "$BASE_BRANCH"
 ```
 
 3. Enter the sandbox worktree printed by the command above.
@@ -48,11 +48,11 @@ git diff --name-only
 ```sh
 git add .codex/skills templates/codex/skills
 git commit -m "Merge skill file updates into ${BASE_BRANCH}"
-bash scripts/agent-branch-finish.sh --branch "$(git rev-parse --abbrev-ref HEAD)" --base "$BASE_BRANCH" --via-pr --wait-for-merge --cleanup
+gx branch finish --branch "$(git rev-parse --abbrev-ref HEAD)" --base "$BASE_BRANCH" --via-pr --wait-for-merge --cleanup
 ```
 
 ## Notes
 
 - If a source branch has non-skill changes, this runbook keeps them out of the merge.
-- If merge conflicts occur, resolve only within the skill files, then rerun `agent-branch-finish.sh`.
+- If merge conflicts occur, resolve only within the skill files, then rerun `gx branch finish`.
 - Do not commit directly on `dev`/`main`; always merge through an agent branch/worktree.

package/templates/githooks/pre-commit

@@ -13,6 +13,8 @@ repo_root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
 if [[ -z "$repo_root" ]]; then
   exit 0
 fi
+NODE_BIN="${GUARDEX_NODE_BIN:-node}"
+CLI_ENTRY="${GUARDEX_CLI_ENTRY:-}"
 guardex_env_helper="${repo_root}/scripts/guardex-env.sh"
 if [[ -f "$guardex_env_helper" ]]; then
   # shellcheck source=/dev/null
@@ -22,6 +24,23 @@ if declare -F guardex_repo_is_enabled >/dev/null 2>&1 && ! guardex_repo_is_enabl
   exit 0
 fi
 
+run_guardex_cli() {
+  if [[ -n "$CLI_ENTRY" ]]; then
+    "$NODE_BIN" "$CLI_ENTRY" "$@"
+    return $?
+  fi
+  if command -v gx >/dev/null 2>&1; then
+    gx "$@"
+    return $?
+  fi
+  if command -v gitguardex >/dev/null 2>&1; then
+    gitguardex "$@"
+    return $?
+  fi
+  echo "[agent-branch-guard] Guardex CLI entrypoint unavailable; rerun via gx." >&2
+  return 127
+}
+
 if [[ "${ALLOW_COMMIT_ON_PROTECTED_BRANCH:-0}" == "1" ]]; then
   exit 0
 fi
@@ -191,11 +210,11 @@ if [[ "$branch" == agent/* ]]; then
     while IFS= read -r staged_file; do
       [[ -z "$staged_file" ]] && continue
       [[ "$staged_file" == ".omx/state/agent-file-locks.json" ]] && continue
-      python3 scripts/agent-file-locks.py claim --branch "$branch" "$staged_file" >/dev/null 2>&1 || true
+      run_guardex_cli locks claim --branch "$branch" "$staged_file" >/dev/null 2>&1 || true
     done < <(git diff --cached --name-only --diff-filter=ACMRDTUXB)
   fi
 
-  if ! python3 scripts/agent-file-locks.py validate --branch "$branch" --staged; then
+  if ! run_guardex_cli locks validate --branch "$branch" --staged; then
     cat >&2 <<'MSG'
 [agent-branch-guard] Agent branch commits require file ownership locks.
 Claim files first:

package/templates/scripts/agent-branch-finish.sh

@@ -9,11 +9,30 @@ DELETE_REMOTE_BRANCH=0
 DELETE_REMOTE_BRANCH_EXPLICIT=0
 MERGE_MODE="auto"
 GH_BIN="${GUARDEX_GH_BIN:-gh}"
+NODE_BIN="${GUARDEX_NODE_BIN:-node}"
+CLI_ENTRY="${GUARDEX_CLI_ENTRY:-}"
 CLEANUP_AFTER_MERGE_RAW="${GUARDEX_FINISH_CLEANUP:-false}"
 WAIT_FOR_MERGE_RAW="${GUARDEX_FINISH_WAIT_FOR_MERGE:-false}"
 WAIT_TIMEOUT_SECONDS_RAW="${GUARDEX_FINISH_WAIT_TIMEOUT_SECONDS:-1800}"
 WAIT_POLL_SECONDS_RAW="${GUARDEX_FINISH_WAIT_POLL_SECONDS:-10}"
 
+run_guardex_cli() {
+  if [[ -n "$CLI_ENTRY" ]]; then
+    "$NODE_BIN" "$CLI_ENTRY" "$@"
+    return $?
+  fi
+  if command -v gx >/dev/null 2>&1; then
+    gx "$@"
+    return $?
+  fi
+  if command -v gitguardex >/dev/null 2>&1; then
+    gitguardex "$@"
+    return $?
+  fi
+  echo "[agent-branch-finish] Guardex CLI entrypoint unavailable; rerun via gx." >&2
+  return 127
+}
+
 normalize_bool() {
   local raw="${1:-}"
   local fallback="${2:-0}"
@@ -431,7 +450,7 @@ run_pr_flow() {
   if [[ -z "$pr_title" ]]; then
     pr_title="Merge ${SOURCE_BRANCH} into ${BASE_BRANCH}"
   fi
-  pr_body="Automated by scripts/agent-branch-finish.sh (PR flow)."
+  pr_body="Automated by gx branch finish (PR flow)."
 
   "$GH_BIN" pr create \
     --base "$BASE_BRANCH" \
@@ -517,9 +536,7 @@ if [[ "$PUSH_ENABLED" -eq 1 ]]; then
   fi
 fi
 
-if [[ -x "${repo_root}/scripts/agent-file-locks.py" ]]; then
-  python3 "${repo_root}/scripts/agent-file-locks.py" release --branch "$SOURCE_BRANCH" >/dev/null 2>&1 || true
-fi
+run_guardex_cli locks release --branch "$SOURCE_BRANCH" >/dev/null 2>&1 || true
 
 base_worktree="$(get_worktree_for_branch "$BASE_BRANCH")"
 if [[ -n "$base_worktree" ]] && is_clean_worktree "$base_worktree" && [[ "$PUSH_ENABLED" -eq 1 ]]; then
@@ -555,29 +572,25 @@ if [[ "$CLEANUP_AFTER_MERGE" -eq 1 ]]; then
     fi
   fi
 
-  if [[ -x "${repo_root}/scripts/agent-worktree-prune.sh" ]]; then
-    prune_args=(--base "$BASE_BRANCH" --only-dirty-worktrees --delete-branches)
-    if [[ "$DELETE_REMOTE_BRANCH" -eq 1 ]]; then
-      prune_args+=(--delete-remote-branches)
-    fi
-    if ! bash "${repo_root}/scripts/agent-worktree-prune.sh" "${prune_args[@]}"; then
-      echo "[agent-branch-finish] Warning: automatic worktree prune failed." >&2
-      echo "[agent-branch-finish] You can run manual cleanup: bash scripts/agent-worktree-prune.sh --base ${BASE_BRANCH} --delete-branches" >&2
-    fi
+  prune_args=(--base "$BASE_BRANCH" --only-dirty-worktrees --delete-branches)
+  if [[ "$DELETE_REMOTE_BRANCH" -eq 1 ]]; then
+    prune_args+=(--delete-remote-branches)
+  fi
+  if ! run_guardex_cli worktree prune "${prune_args[@]}"; then
+    echo "[agent-branch-finish] Warning: automatic worktree prune failed." >&2
+    echo "[agent-branch-finish] You can run manual cleanup: gx cleanup --base ${BASE_BRANCH}" >&2
   fi
 
   echo "[agent-branch-finish] Merged '${SOURCE_BRANCH}' into '${BASE_BRANCH}' via ${merge_status} flow and cleaned source branch/worktree."
   if [[ "$source_worktree" == "$current_worktree" && "$source_worktree" == "${agent_worktree_root}"/* ]]; then
     echo "[agent-branch-finish] Current worktree '${source_worktree}' still exists because it is the active shell cwd." >&2
-    echo "[agent-branch-finish] Leave this directory, then run: bash scripts/agent-worktree-prune.sh --base ${BASE_BRANCH} --delete-branches" >&2
+    echo "[agent-branch-finish] Leave this directory, then run: gx cleanup --base ${BASE_BRANCH}" >&2
   fi
 else
-  if [[ -x "${repo_root}/scripts/agent-worktree-prune.sh" ]]; then
-    if ! bash "${repo_root}/scripts/agent-worktree-prune.sh" --base "$BASE_BRANCH"; then
-      echo "[agent-branch-finish] Warning: temporary worktree prune failed." >&2
-    fi
+  if ! run_guardex_cli worktree prune --base "$BASE_BRANCH"; then
+    echo "[agent-branch-finish] Warning: temporary worktree prune failed." >&2
   fi
 
   echo "[agent-branch-finish] Merged '${SOURCE_BRANCH}' into '${BASE_BRANCH}' via ${merge_status} flow and kept source branch/worktree."
-  echo "[agent-branch-finish] Cleanup later with: bash scripts/agent-worktree-prune.sh --base ${BASE_BRANCH} --delete-branches --delete-remote-branches"
+  echo "[agent-branch-finish] Cleanup later with: gx cleanup --base ${BASE_BRANCH}"
 fi

package/templates/scripts/agent-branch-merge.sh

@@ -6,18 +6,37 @@ BASE_BRANCH_EXPLICIT=0
 TARGET_BRANCH=""
 TASK_NAME=""
 AGENT_NAME="${GUARDEX_MERGE_AGENT_NAME:-codex}"
+NODE_BIN="${GUARDEX_NODE_BIN:-node}"
+CLI_ENTRY="${GUARDEX_CLI_ENTRY:-}"
 declare -a SOURCE_BRANCHES=()
 
 usage() {
   cat <<'EOF'
-Usage: scripts/agent-branch-merge.sh --branch <agent/...> [--branch <agent/...> ...] [--into <agent/...>] [--task <task>] [--agent <agent>] [--base <branch>]
+Usage: gx branch merge --branch <agent/...> [--branch <agent/...> ...] [--into <agent/...>] [--task <task>] [--agent <agent>] [--base <branch>]
 
 Examples:
-  bash scripts/agent-branch-merge.sh --branch agent/codex/ui-a --branch agent/codex/ui-b
-  bash scripts/agent-branch-merge.sh --into agent/codex/owner-lane --branch agent/codex/helper-a --branch agent/codex/helper-b
+  gx branch merge --branch agent/codex/ui-a --branch agent/codex/ui-b
+  gx branch merge --into agent/codex/owner-lane --branch agent/codex/helper-a --branch agent/codex/helper-b
 EOF
 }
 
+run_guardex_cli() {
+  if [[ -n "$CLI_ENTRY" ]]; then
+    "$NODE_BIN" "$CLI_ENTRY" "$@"
+    return $?
+  fi
+  if command -v gx >/dev/null 2>&1; then
+    gx "$@"
+    return $?
+  fi
+  if command -v gitguardex >/dev/null 2>&1; then
+    gitguardex "$@"
+    return $?
+  fi
+  echo "[agent-branch-merge] Guardex CLI entrypoint unavailable; rerun via gx." >&2
+  return 127
+}
+
 sanitize_slug() {
   local raw="$1"
   local fallback="${2:-merge-agent-branches}"
@@ -262,7 +281,7 @@ if [[ -z "$TARGET_BRANCH" ]]; then
   start_output=""
   if ! start_output="$(
     cd "$repo_root"
-    env GUARDEX_OPENSPEC_AUTO_INIT=1 bash "scripts/agent-branch-start.sh" "$TASK_NAME" "$AGENT_NAME" "$BASE_BRANCH" 2>&1
+    GUARDEX_OPENSPEC_AUTO_INIT=1 run_guardex_cli branch start "$TASK_NAME" "$AGENT_NAME" "$BASE_BRANCH" 2>&1
   )"; then
     printf '%s\n' "$start_output" >&2
     exit 1
@@ -418,4 +437,4 @@ echo "[agent-branch-merge] Merge sequence complete for '${TARGET_BRANCH}'."
 if [[ "$target_created" -eq 1 ]]; then
   echo "[agent-branch-merge] Review and verify in '${target_worktree}', then finish the integration branch when ready."
 fi
-echo "[agent-branch-merge] Next step: bash scripts/agent-branch-finish.sh --branch \"${TARGET_BRANCH}\" --base \"${BASE_BRANCH}\" --via-pr --wait-for-merge --cleanup"
+echo "[agent-branch-merge] Next step: gx branch finish --branch \"${TARGET_BRANCH}\" --base \"${BASE_BRANCH}\" --via-pr --wait-for-merge --cleanup"

package/templates/scripts/agent-branch-start.sh

@@ -7,14 +7,34 @@ BASE_BRANCH=""
 BASE_BRANCH_EXPLICIT=0
 WORKTREE_ROOT_REL=""
 WORKTREE_ROOT_EXPLICIT=0
+NODE_BIN="${GUARDEX_NODE_BIN:-node}"
+CLI_ENTRY="${GUARDEX_CLI_ENTRY:-}"
 OPENSPEC_AUTO_INIT_RAW="${GUARDEX_OPENSPEC_AUTO_INIT:-false}"
 OPENSPEC_PLAN_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_PLAN_SLUG:-}"
 OPENSPEC_CHANGE_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_CHANGE_SLUG:-}"
 OPENSPEC_CAPABILITY_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_CAPABILITY_SLUG:-}"
 OPENSPEC_MASTERPLAN_LABEL_RAW="${GUARDEX_OPENSPEC_MASTERPLAN_LABEL-masterplan}"
+OPENSPEC_TIER_RAW="${GUARDEX_OPENSPEC_TIER:-T3}"
 PRINT_NAME_ONLY=0
 POSITIONAL_ARGS=()
 
+run_guardex_cli() {
+  if [[ -n "$CLI_ENTRY" ]]; then
+    "$NODE_BIN" "$CLI_ENTRY" "$@"
+    return $?
+  fi
+  if command -v gx >/dev/null 2>&1; then
+    gx "$@"
+    return $?
+  fi
+  if command -v gitguardex >/dev/null 2>&1; then
+    gitguardex "$@"
+    return $?
+  fi
+  echo "[agent-branch-start] Guardex CLI entrypoint unavailable; rerun via gx." >&2
+  return 127
+}
+
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --task)
@@ -35,8 +55,7 @@ while [[ $# -gt 0 ]]; do
       shift
       ;;
     --tier)
-      # Accepted for CLAUDE.md compatibility; scaffold size is not yet wired
-      # through this script. Consume the value so callers can pass it.
+      OPENSPEC_TIER_RAW="${2:-$OPENSPEC_TIER_RAW}"
       shift 2
       ;;
     --in-place|--allow-in-place)
@@ -227,11 +246,45 @@ normalize_bool() {
 
 OPENSPEC_AUTO_INIT="$(normalize_bool "$OPENSPEC_AUTO_INIT_RAW" "1")"
 
+normalize_tier() {
+  local raw="${1:-}"
+  local fallback="${2:-T3}"
+  local upper
+  upper="$(printf '%s' "$raw" | tr '[:lower:]' '[:upper:]')"
+  case "$upper" in
+    T0|T1|T2|T3) printf '%s' "$upper" ;;
+    '') printf '%s' "$fallback" ;;
+    *) return 1 ;;
+  esac
+}
+
+if ! OPENSPEC_TIER="$(normalize_tier "$OPENSPEC_TIER_RAW" "T3")"; then
+  echo "[agent-branch-start] Unsupported OpenSpec tier: ${OPENSPEC_TIER_RAW}" >&2
+  exit 1
+fi
+
+OPENSPEC_SKIP_CHANGE=0
+OPENSPEC_SKIP_PLAN=0
+OPENSPEC_MINIMAL=0
+case "$OPENSPEC_TIER" in
+  T0)
+    OPENSPEC_SKIP_CHANGE=1
+    OPENSPEC_SKIP_PLAN=1
+    ;;
+  T1)
+    OPENSPEC_SKIP_PLAN=1
+    OPENSPEC_MINIMAL=1
+    ;;
+  T2)
+    OPENSPEC_SKIP_PLAN=1
+    ;;
+esac
+
 resolve_openspec_masterplan_label() {
   local raw="${OPENSPEC_MASTERPLAN_LABEL_RAW:-}"
   local label
 
-  if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]] || [[ -z "$raw" ]]; then
+  if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]] || [[ "$OPENSPEC_SKIP_PLAN" -eq 1 ]] || [[ -z "$raw" ]]; then
     printf ''
     return 0
   fi
@@ -385,26 +438,14 @@ initialize_openspec_plan_workspace() {
   local worktree="$2"
   local plan_slug="$3"
 
-  hydrate_local_helper_in_worktree "$repo" "$worktree" "scripts/openspec/init-plan-workspace.sh"
-
-  if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]]; then
+  if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]] || [[ "$OPENSPEC_SKIP_PLAN" -eq 1 ]]; then
     return 0
   fi
 
-  local openspec_script="${worktree}/scripts/openspec/init-plan-workspace.sh"
-  if [[ ! -f "$openspec_script" ]]; then
-    echo "[agent-branch-start] OpenSpec init script is missing in sandbox worktree." >&2
-    echo "[agent-branch-start] Run 'gx setup --target \"$repo\"' to repair templates, then retry." >&2
-    return 1
-  fi
-  if [[ ! -x "$openspec_script" ]]; then
-    chmod +x "$openspec_script" 2>/dev/null || true
-  fi
-
   local init_output=""
   if ! init_output="$(
     cd "$worktree"
-    bash "scripts/openspec/init-plan-workspace.sh" "$plan_slug" 2>&1
+    run_guardex_cli internal run-shell planInit "$plan_slug" 2>&1
   )"; then
     printf '%s\n' "$init_output" >&2
     echo "[agent-branch-start] OpenSpec workspace initialization failed for plan '${plan_slug}'." >&2
@@ -423,26 +464,15 @@ initialize_openspec_change_workspace() {
   local change_slug="$3"
   local capability_slug="$4"
 
-  hydrate_local_helper_in_worktree "$repo" "$worktree" "scripts/openspec/init-change-workspace.sh"
-
-  if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]]; then
+  if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]] || [[ "$OPENSPEC_SKIP_CHANGE" -eq 1 ]]; then
     return 0
   fi
 
-  local openspec_script="${worktree}/scripts/openspec/init-change-workspace.sh"
-  if [[ ! -f "$openspec_script" ]]; then
-    echo "[agent-branch-start] OpenSpec change init script is missing in sandbox worktree." >&2
-    echo "[agent-branch-start] Run 'gx setup --target \"$repo\"' to repair templates, then retry." >&2
-    return 1
-  fi
-  if [[ ! -x "$openspec_script" ]]; then
-    chmod +x "$openspec_script" 2>/dev/null || true
-  fi
-
   local init_output=""
   if ! init_output="$(
     cd "$worktree"
-    bash "scripts/openspec/init-change-workspace.sh" "$change_slug" "$capability_slug" 2>&1
+    GUARDEX_OPENSPEC_MINIMAL="$OPENSPEC_MINIMAL" \
+      run_guardex_cli internal run-shell changeInit "$change_slug" "$capability_slug" 2>&1
   )"; then
     printf '%s\n' "$init_output" >&2
     echo "[agent-branch-start] OpenSpec workspace initialization failed for change '${change_slug}'." >&2
@@ -592,7 +622,6 @@ if [[ -n "$auto_transfer_stash_ref" ]]; then
   fi
 fi
 
-hydrate_local_helper_in_worktree "$repo_root" "$worktree_path" "scripts/codex-agent.sh"
 hydrate_dependency_dir_symlink_in_worktree "$repo_root" "$worktree_path" "node_modules"
 hydrate_dependency_dir_symlink_in_worktree "$repo_root" "$worktree_path" "apps/frontend/node_modules"
 hydrate_dependency_dir_symlink_in_worktree "$repo_root" "$worktree_path" "apps/backend/node_modules"
@@ -605,10 +634,19 @@ fi
 
 echo "[agent-branch-start] Created branch: ${branch_name}"
 echo "[agent-branch-start] Worktree: ${worktree_path}"
-echo "[agent-branch-start] OpenSpec change: openspec/changes/${openspec_change_slug}"
-echo "[agent-branch-start] OpenSpec plan: openspec/plan/${openspec_plan_slug}"
+echo "[agent-branch-start] OpenSpec tier: ${OPENSPEC_TIER}"
+if [[ "$OPENSPEC_SKIP_CHANGE" -eq 1 ]]; then
+  echo "[agent-branch-start] OpenSpec change: skipped by tier ${OPENSPEC_TIER}"
+else
+  echo "[agent-branch-start] OpenSpec change: openspec/changes/${openspec_change_slug}"
+fi
+if [[ "$OPENSPEC_SKIP_PLAN" -eq 1 ]]; then
+  echo "[agent-branch-start] OpenSpec plan: skipped by tier ${OPENSPEC_TIER}"
+else
+  echo "[agent-branch-start] OpenSpec plan: openspec/plan/${openspec_plan_slug}"
+fi
 echo "[agent-branch-start] Next steps:"
 echo "  cd \"${worktree_path}\""
-echo "  python3 scripts/agent-file-locks.py claim --branch \"${branch_name}\" <file...>"
+echo "  gx locks claim --branch \"${branch_name}\" <file...>"
 echo "  # implement + commit"
-echo "  bash scripts/agent-branch-finish.sh --branch \"${branch_name}\" --base ${BASE_BRANCH} --via-pr --wait-for-merge"
+echo "  gx branch finish --branch \"${branch_name}\" --base ${BASE_BRANCH} --via-pr --wait-for-merge"