recodeee · NagyVikt · Apr 22, 2026 · Apr 22, 2026
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-22
@@ -0,0 +1,11 @@
+## Why
+
+- TODO: describe the user/problem outcome this change addresses.
+
+## What Changes
+
+- TODO: summarize the intended behavior and scope.
+
+## Impact
+
+- TODO: call out risks, rollout notes, and affected surfaces.
@@ -0,0 +1,14 @@
+## ADDED Requirements
+
+### Requirement: branch-start runtime preserves template bootstrap parity
+The runtime `scripts/agent-branch-start.sh` SHALL preserve the same bootstrap behavior and user guidance as `templates/scripts/agent-branch-start.sh`.
+
+#### Scenario: OpenSpec bootstrap uses the CLI-owned path
+- **WHEN** `scripts/agent-branch-start.sh` initializes OpenSpec workspaces in a new agent worktree
+- **THEN** it invokes change and plan initialization through `gx internal run-shell ...`
+- **AND** it does not rehydrate deprecated local helper copies into the worktree.
+
+#### Scenario: printed next steps match the supported CLI surface
+- **WHEN** `scripts/agent-branch-start.sh` prints the post-start handoff instructions
+- **THEN** it points users at `gx locks claim`
+- **AND** it points users at `gx branch finish`.
@@ -0,0 +1,34 @@
+## Definition of Done
+
+This change is complete only when **all** of the following are true:
+
+- Every checkbox below is checked.
+- The agent branch reaches `MERGED` state on `origin` and the PR URL + state are recorded in the completion handoff.
+- If any step blocks (test failure, conflict, ambiguous result), append a `BLOCKED:` line under section 4 explaining the blocker and **STOP**. Do not tick remaining cleanup boxes; do not silently skip the cleanup pipeline.
+
+## Handoff
+
+- Handoff: change=`agent-codex-fix-agent-branch-start-template-parity-2026-04-22-11-18`; branch=`agent/codex/fix-agent-branch-start-template-parity-2026-04-22-11-18`; scope=`scripts/agent-branch-start.sh`; action=`restore runtime/template parity and verify existing parity coverage`.
+- Copy prompt: Continue `agent-codex-fix-agent-branch-start-template-parity-2026-04-22-11-18` on branch `agent/codex/fix-agent-branch-start-template-parity-2026-04-22-11-18`. Work inside the existing sandbox, review `openspec/changes/agent-codex-fix-agent-branch-start-template-parity-2026-04-22-11-18/tasks.md`, continue from the current state instead of creating a new sandbox, and when the work is done run `gx branch finish --branch agent/codex/fix-agent-branch-start-template-parity-2026-04-22-11-18 --base main --via-pr --wait-for-merge --cleanup`.
+
+## 1. Specification
+
+- [x] 1.1 Finalize proposal scope and acceptance criteria for `agent-codex-fix-agent-branch-start-template-parity-2026-04-22-11-18`.
+- [x] 1.2 Define normative requirements in `specs/fix-agent-branch-start-template-parity/spec.md`.
+
+## 2. Implementation
+
+- [x] 2.1 Implement scoped behavior changes.
+- [x] 2.2 Add/update focused regression coverage.
+
+## 3. Verification
+
+- [x] 3.1 Run targeted project verification commands.
+- [x] 3.2 Run `openspec validate agent-codex-fix-agent-branch-start-template-parity-2026-04-22-11-18 --type change --strict`.
+- [x] 3.3 Run `openspec validate --specs`.
+
+## 4. Cleanup (mandatory; run before claiming completion)
+
+- [ ] 4.1 Run the cleanup pipeline: `gx branch finish --branch agent/codex/fix-agent-branch-start-template-parity-2026-04-22-11-18 --base main --via-pr --wait-for-merge --cleanup`. This handles commit -> push -> PR create -> merge wait -> worktree prune in one invocation.
+- [ ] 4.2 Record the PR URL and final merge state (`MERGED`) in the completion handoff.
+- [ ] 4.3 Confirm the sandbox worktree is gone (`git worktree list` no longer shows the agent path; `git branch -a` shows no surviving local/remote refs for the branch).
@@ -7,6 +7,8 @@ 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:-}"
@@ -15,6 +17,23 @@ OPENSPEC_MASTERPLAN_LABEL_RAW="${GUARDEX_OPENSPEC_MASTERPLAN_LABEL-masterplan}"
 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)
@@ -385,26 +404,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
     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 +430,14 @@ 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
     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
+    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 +587,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"
@@ -609,6 +603,6 @@ echo "[agent-branch-start] OpenSpec change: openspec/changes/${openspec_change_s
 echo "[agent-branch-start] OpenSpec plan: openspec/plan/${openspec_plan_slug}"
 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"