fix(cli): default first-run handoff to plain codex

Author: BaseInfinity

README.md

@@ -14,15 +14,15 @@ codex --full-auto
 
 `codex --full-auto` is the recommended default once this wizard is installed: you keep the repo guardrails and hook enforcement, but day-to-day editing and runs stay low-friction. Use plain `codex` instead if you want more manual confirmation.
 
-Bare `npx codex-sdlc-wizard` is the adaptive interactive path. It bootstraps the repo-local guardrails first, then hands off into a live Codex setup session so the unresolved setup questions happen inside Codex instead of inside a shell checklist. `setup --yes` still exists for automation, but it is not the normal human path.
+Bare `npx codex-sdlc-wizard` is the adaptive interactive path. It bootstraps the repo-local guardrails first, then hands off into a live plain Codex setup session so the unresolved setup questions happen inside Codex instead of inside a shell checklist. At that first-run handoff prompt, press Enter for plain `codex` or type `full-auto` if you explicitly want `codex --full-auto`. `setup --yes` still exists for automation, but it is not the normal human path.
 
 Generic npm entrypoint examples: `npx codex-sdlc-wizard`, `npx codex-sdlc-wizard check`, and `npx codex-sdlc-wizard update`.
 
 Useful follow-ups after install:
 
 ```bash
-npx codex-sdlc-wizard@0.7.9 check
-npx codex-sdlc-wizard@0.7.9 update
+npx codex-sdlc-wizard@0.7.10 check
+npx codex-sdlc-wizard@0.7.10 update
 ```
 
 If you want pinned release examples instead of `@latest`, see [Releases](#releases).
@@ -83,10 +83,10 @@ How to choose:
 
 ```bash
 # recommended interactive bootstrap path
-npx codex-sdlc-wizard@0.7.9 --model-profile maximum
+npx codex-sdlc-wizard@0.7.10 --model-profile maximum
 
 # interactive bootstrap with the efficiency-first profile if you already know you want it
-npx codex-sdlc-wizard@0.7.9 --model-profile mixed
+npx codex-sdlc-wizard@0.7.10 --model-profile mixed
 
 # floating latest release with the same bootstrap recommendation
 npx codex-sdlc-wizard@latest --model-profile maximum
@@ -186,7 +186,7 @@ If you are consuming this repo in a real project, prefer a tagged release over `
 
 ```bash
 # npm / npx pinned to the current release
-npx codex-sdlc-wizard@0.7.9
+npx codex-sdlc-wizard@0.7.10
 
 # npm / npx floating on the newest published release
 npx codex-sdlc-wizard@latest
@@ -196,7 +196,7 @@ npx codex-sdlc-wizard@latest
 # so $codex-sdlc-wizard is available inside Codex
 
 # git-based install
-git clone --branch v0.7.9 --depth 1 https://github.com/BaseInfinity/codex-sdlc-wizard.git /tmp/codex-sdlc-wizard
+git clone --branch v0.7.10 --depth 1 https://github.com/BaseInfinity/codex-sdlc-wizard.git /tmp/codex-sdlc-wizard
 ```
 
 ### Maintainer Release Flow

ROADMAP.md

@@ -2,7 +2,7 @@
 
 ## Current State
 
-- `codex-sdlc-wizard@0.7.9` and `v0.7.9` are the current release target for the setup/update scope-control stabilization patch
+- `codex-sdlc-wizard@0.7.10` and `v0.7.10` are the current release target for the first-run plain-Codex handoff patch
 - npm trusted publishing is configured and the GitHub release workflow is now proven for real OIDC publish
 - the repo now ships both a Codex skill package (`SKILL.md`, `agents/openai.yaml`) and the installer/setup adapter (`install.sh`, `setup.sh`)
 - the npm CLI now defaults to adaptive interactive setup instead of requiring an explicit `setup` subcommand for the main human path
@@ -19,51 +19,52 @@
 - setup/update guidance now treats verification as diagnostic for product failures and stops before editing application code or application tests without explicit user consent
 - setup/update guidance now tells users to exit and reopen Codex after hook/skill repairs, without rerunning setup/update just for that restart
 - install/setup/update now write and repair repo-local `.codex/config.toml` model keys for the selected profile, while preserving unrelated MCP, sandbox, approval, and custom config
+- first-run live setup now defaults to plain `codex` after bootstrap and requires an explicit `full-auto` choice to start that setup handoff with `codex --full-auto`
 - the repo now ships a consumer bug-report template for install/setup/runtime failures
 - the public README now leads with the real `@latest` adaptive setup path and keeps the top section consumer-focused
 - benchmark and pilot-rollout ledgers now exist so model/default-use decisions can be measured, not guessed
 - release, packaging, npm, skill, setup, adapter, update, and E2E tests are green when the parity merge is complete
 
 ## Next Release Cycle
 
-### 0.7.10
+### 0.7.11
 
-Purpose: prove the post-`0.7.9` consumer path on real repos and stabilize any reusable wizard bugs without changing the default-use claim early.
+Purpose: prove the post-`0.7.10` consumer path on real repos and stabilize any reusable wizard bugs without changing the default-use claim early.
 
 Scope:
-- run `0.7.9` on 3-5 pilot repos and log results in `benchmarks/pilot-rollout.csv`
+- run `0.7.10` on 3-5 pilot repos and log results in `benchmarks/pilot-rollout.csv`
 - cut a stabilization patch only if pilots surface another reusable wizard bug
 - keep the default-use recommendation gated on the measurable pilot summary
-- keep the separate model experiment running, but do not let it block pilot rollout work
+- keep separate model-profile measurement running, but do not let it block pilot rollout work
 
 ## Tracker Cleanup
 
 The issue tracker is currently clear.
 
 - open a new issue only when pilot consumption exposes a proven reusable wizard bug
-- avoid speculative backlog churn while `0.7.9` is being consumed on real repos
+- avoid speculative backlog churn while `0.7.10` is being consumed on real repos
 
 ## Remaining Backlog
 
-After `0.7.9`, the main backlog is:
+After `0.7.10`, the main backlog is:
 
 - pilot rollout proof for default use on real repos
 - any reusable wizard fixes discovered during the pilot set
-- model experiment data collection for `mixed` vs `maximum`
+- model-profile measurement data collection for `mixed` vs `maximum`
 - top-level proof-run parallelization to reduce release-wall-clock time without weakening suite coverage
 - later creator-tool research after the active backlog stays under control
 
 ## Working Order
 
-1. Prove the default-use gate on 3-5 pilot repos with `0.7.9`
-2. Ship `0.7.10` only if pilot rollout surfaces another reusable wizard bug
+1. Prove the default-use gate on 3-5 pilot repos with `0.7.10`
+2. Ship `0.7.11` only if pilot rollout surfaces another reusable wizard bug
 3. Keep creator-tool investigation behind the active backlog
 
 ## Default-Use Gate
 
 Before calling this the default Codex SDLC path, prove it on real pilot repos instead of just repo-self-tests.
 
-- run `0.7.9` on 3-5 pilot repos
+- run `0.7.10` on 3-5 pilot repos
 - require pilot success >= 95% before default use
 - allow no more than 1 reusable wizard bug across the pilot set
 - track the pilot set in `benchmarks/pilot-rollout.csv`
@@ -75,7 +76,7 @@ After the current backlog is under control, investigate whether Codex's built-in
 
 - evaluate `Skill Creator` as a possible future aid for skill-structure maintenance
 - evaluate `Plugin Creator` only as later research, since plugins are not part of the current shipping path
-- experiment with `gpt-5.4-mini` for the main working pass while keeping `xhigh` for review or cross-model review, and compare that against simply running the whole slice at `xhigh`
+- measure `gpt-5.4-mini` for the main working pass while keeping `xhigh` for review or cross-model review, and compare that against simply running the whole slice at `xhigh`
 - if the mixed mode proves out, add an easy toggle between two explicit profiles:
   - `mixed`: `gpt-5.4-mini` for the main pass plus `xhigh` review
   - `maximum`: `gpt-5.4` / `xhigh` for the whole slice as the "ultimate mode"

SKILL.md

@@ -17,7 +17,7 @@ Use the bundled scripts like this:
 1. If the user wants the simplest install, run the bundled `install.sh` from this skill bundle against the current working repo.
 2. If the user wants repo-aware setup or regenerated docs, run the bundled `setup.sh --yes` from this skill bundle against the current working repo.
 3. Tell the user exactly which path you chose: `install.sh` for baseline enforcement, `setup.sh` for adaptive setup.
-4. After installation, tell the user to start a fresh Codex session so hooks and repo docs are loaded cleanly. Recommend `codex --full-auto` as the default start mode once the guardrails are installed, and mention plain `codex` as the manual fallback.
+4. After installation, tell the user to start a fresh Codex session so hooks and repo docs are loaded cleanly. Recommend plain `codex` for the first live setup handoff unless the user explicitly chooses `full-auto`; recommend `codex --full-auto` as the default start mode after setup is complete and the guardrails are loaded. Mention plain `codex` as the manual fallback for daily work.
    The fresh session should also pick up the repo-scoped `\$sdlc` skill under `.agents/skills`. Repo-scoped skill coverage is still a work in progress; `gdlc` and `rdlc` are planned next.
    For setup/update bootstrap work, recommend the `maximum` profile via `--model-profile maximum` as the safer default. For routine work after bootstrap, point users back to the `mixed` profile via `--model-profile mixed` for the better speed / lower latency / lower token path with `xhigh` review.
    This repo stays on `maximum`; when maintaining `codex-sdlc-wizard` itself, keep the wizard repo on the stability-first path because the work is unusually meta.

bin/codex-sdlc-wizard.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 
 const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
 const path = require("node:path");
+const readline = require("node:readline/promises");
 
 const scriptDir = path.resolve(__dirname, "..");
 const rawArgs = process.argv.slice(2);
@@ -22,7 +24,8 @@ Commands:
   update         Apply selective updates for missing or drifted managed files
   install        Advanced escape hatch: run install.sh without adaptive setup
 
-Default behavior: bootstrap the current repo, then hand off into a live Codex setup session.
+Default behavior: bootstrap the current repo, then hand off into a live plain Codex setup session.
+Type 'full-auto' at the handoff prompt if you want codex --full-auto for first-run setup.
 Automation/non-interactive behavior: use setup --yes to stay on the shell path.
 Bootstrap/setup recommendation: maximum.
 Routine work after bootstrap: mixed.
@@ -140,7 +143,42 @@ function runScript(scriptName, args) {
   });
 }
 
-function handoffToCodex(modelProfile) {
+async function askHandoffMode() {
+  if (process.env.CODEX_SDLC_HANDOFF_MODE === "full-auto") {
+    return "full-auto";
+  }
+
+  if (process.env.CODEX_SDLC_HANDOFF_MODE === "plain") {
+    return "plain";
+  }
+
+  const prompt = [
+    "",
+    "First-run Codex handoff defaults to plain codex.",
+    "Type 'full-auto' to use codex --full-auto instead, or press Enter for plain codex: "
+  ].join("\n");
+
+  if (!process.stdin.isTTY) {
+    process.stdout.write(prompt);
+    const answer = fs.readFileSync(0, "utf8").split(/\r?\n/, 1)[0].trim().toLowerCase();
+    process.stdout.write("\n");
+    return answer === "full-auto" ? "full-auto" : "plain";
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  try {
+    const answer = (await rl.question(prompt)).trim().toLowerCase();
+    return answer === "full-auto" ? "full-auto" : "plain";
+  } finally {
+    rl.close();
+  }
+}
+
+async function handoffToCodex(modelProfile) {
   const installArgs = ["--model-profile", modelProfile];
   const installResult = runScript("install.sh", installArgs);
 
@@ -153,10 +191,11 @@ function handoffToCodex(modelProfile) {
     process.exit(installResult.status === null ? 1 : installResult.status);
   }
 
-  process.stdout.write("\nHanding off into Codex for live setup...\n");
+  const handoffMode = await askHandoffMode();
+  const modeLabel = handoffMode === "full-auto" ? "codex --full-auto" : "plain codex";
+  process.stdout.write(`\nHanding off into Codex for live setup using ${modeLabel}...\n`);
 
   const codexArgs = [
-    "--full-auto",
     "-C",
     process.cwd(),
     "-m",
@@ -166,33 +205,43 @@ function handoffToCodex(modelProfile) {
     interactiveSessionPrompt
   ];
 
+  if (handoffMode === "full-auto") {
+    codexArgs.unshift("--full-auto");
+  }
+
   const codexResult = spawnCodex(codexArgs, "inherit");
 
   if (codexResult.error) {
     process.stderr.write(`${codexResult.error.message}\n`);
     process.exit(1);
   }
 
-  process.exit(codexResult.status === null ? 1 : codexResult.status);
+  return codexResult.status === null ? 1 : codexResult.status;
 }
 
-if (shouldHandoffToCodex()) {
-  handoffToCodex(getSetupModelProfile(scriptArgs));
-}
+async function main() {
+  if (shouldHandoffToCodex()) {
+    process.exit(await handoffToCodex(getSetupModelProfile(scriptArgs)));
+  }
 
-const scriptName = command === "setup"
-  ? "setup.sh"
-  : command === "check"
-    ? "check.sh"
-    : command === "update"
-      ? "update.sh"
-      : "install.sh";
-const scriptPath = path.join(scriptDir, scriptName);
-const result = runScript(scriptName, scriptArgs);
-
-if (result.error) {
-  process.stderr.write(`${result.error.message}\n`);
-  process.exit(1);
+  const scriptName = command === "setup"
+    ? "setup.sh"
+    : command === "check"
+      ? "check.sh"
+      : command === "update"
+        ? "update.sh"
+        : "install.sh";
+  const result = runScript(scriptName, scriptArgs);
+
+  if (result.error) {
+    process.stderr.write(`${result.error.message}\n`);
+    process.exit(1);
+  }
+
+  process.exit(result.status === null ? 1 : result.status);
 }
 
-process.exit(result.status === null ? 1 : result.status);
+main().catch((error) => {
+  process.stderr.write(`${error.message}\n`);
+  process.exit(1);
+});

package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-sdlc-wizard",
-  "version": "0.7.9",
+  "version": "0.7.10",
   "description": "Codex SDLC adaptive setup wizard and maintenance CLI for npx distribution",
   "license": "MIT",
   "repository": {

tests/test-npm.sh

@@ -279,15 +279,17 @@ test_packed_tarball_scratch_smoke() {
 }
 
 test_default_interactive_hands_off_to_codex() {
-    local ws fakebin fakebin_win codex_home args_file output
+    local ws fakebin fakebin_win codex_home args_file input_file output
     ws=$(mktemp -d "$MKTEMP_DIR/sdlc-npx-target.XXXXXX")
     fakebin=$(mktemp -d "$MKTEMP_DIR/sdlc-npx-bin.XXXXXX")
     codex_home=$(mktemp -d "$MKTEMP_DIR/sdlc-npx-home.XXXXXX")
     args_file="$ws/codex-args.txt"
+    input_file="$ws/handoff-input.txt"
 
     printf '%s' '{"name":"handoff-smoke","scripts":{"test":"npm test"}}' > "$ws/package.json"
     mkdir -p "$ws/tests"
     touch "$ws/tests/app.e2e.ts" "$ws/playwright.config.js"
+    printf '\n' > "$input_file"
 
     cat > "$fakebin/codex.cmd" <<'EOF'
 @echo off
@@ -306,29 +308,78 @@ EOF
         CODEX_SDLC_DISABLE_REASONING=1 \
         FAKE_CODEX_ARGS_FILE="$args_file" \
         PATH="$fakebin_win;$PATH" \
-        node "$REPO_DIR/bin/codex-sdlc-wizard.js" 2>&1
+        node "$REPO_DIR/bin/codex-sdlc-wizard.js" < "$input_file" 2>&1
     ) || true
 
     local valid=true
     [ -f "$ws/.codex/config.toml" ] || valid=false
     [ -f "$ws/.codex/hooks.json" ] || valid=false
     [ -f "$ws/.codex-sdlc/model-profile.json" ] || valid=false
     [ ! -f "$ws/.codex-sdlc/manifest.json" ] || valid=false
-    grep -Fq -- '--full-auto' "$args_file" 2>/dev/null || valid=false
+    grep -Fq -- '--full-auto' "$args_file" 2>/dev/null && valid=false
     grep -Fq -- '-C' "$args_file" 2>/dev/null || valid=false
     grep -Fq -- '-m' "$args_file" 2>/dev/null || valid=false
     grep -Fq 'gpt-5.4' "$args_file" 2>/dev/null || valid=false
     grep -Fq 'model_reasoning_effort="xhigh"' "$args_file" 2>/dev/null || valid=false
     grep -Fq '$setup-wizard' "$args_file" 2>/dev/null || valid=false
-    echo "$output" | grep -Fq 'Handing off into Codex for live setup' || valid=false
+    echo "$output" | grep -Fq 'First-run Codex handoff defaults to plain codex' || valid=false
+    echo "$output" | grep -Fq 'Handing off into Codex for live setup using plain codex' || valid=false
+    ! echo "$output" | grep -Fq 'Scanning project...' || valid=false
+
+    rm -rf "$ws" "$fakebin" "$codex_home"
+
+    if [ "$valid" = "true" ]; then
+        pass "default interactive CLI bootstraps then hands off into plain Codex"
+    else
+        fail "default interactive CLI did not hand off into plain Codex correctly"
+    fi
+}
+
+test_full_auto_handoff_choice_is_explicit() {
+    local ws fakebin fakebin_win codex_home args_file input_file output
+    ws=$(mktemp -d "$MKTEMP_DIR/sdlc-npx-target.XXXXXX")
+    fakebin=$(mktemp -d "$MKTEMP_DIR/sdlc-npx-bin.XXXXXX")
+    codex_home=$(mktemp -d "$MKTEMP_DIR/sdlc-npx-home.XXXXXX")
+    args_file="$ws/codex-args.txt"
+    input_file="$ws/handoff-input.txt"
+
+    printf '%s' '{"name":"handoff-smoke","scripts":{"test":"npm test"}}' > "$ws/package.json"
+    mkdir -p "$ws/tests"
+    touch "$ws/tests/app.e2e.ts" "$ws/playwright.config.js"
+    printf 'full-auto\n' > "$input_file"
+
+    cat > "$fakebin/codex.cmd" <<'EOF'
+@echo off
+if not "%FAKE_CODEX_ARGS_FILE%"=="" (
+  >>"%FAKE_CODEX_ARGS_FILE%" echo %*
+)
+exit /b 0
+EOF
+
+    fakebin_win=$(cd "$fakebin" && pwd -W 2>/dev/null || printf '%s' "$fakebin")
+
+    output=$(
+        cd "$ws" && \
+        CODEX_HOME="$codex_home" \
+        CODEX_SDLC_CODEX_BIN="$fakebin_win\\codex.cmd" \
+        CODEX_SDLC_DISABLE_REASONING=1 \
+        FAKE_CODEX_ARGS_FILE="$args_file" \
+        PATH="$fakebin_win;$PATH" \
+        node "$REPO_DIR/bin/codex-sdlc-wizard.js" < "$input_file" 2>&1
+    ) || true
+
+    local valid=true
+    grep -Fq -- '--full-auto' "$args_file" 2>/dev/null || valid=false
+    grep -Fq '$setup-wizard' "$args_file" 2>/dev/null || valid=false
+    echo "$output" | grep -Fq 'Handing off into Codex for live setup using codex --full-auto' || valid=false
     ! echo "$output" | grep -Fq 'Scanning project...' || valid=false
 
     rm -rf "$ws" "$fakebin" "$codex_home"
 
     if [ "$valid" = "true" ]; then
-        pass "default interactive CLI bootstraps then hands off into Codex"
+        pass "full-auto first-run handoff requires an explicit choice"
     else
-        fail "default interactive CLI did not hand off into Codex correctly"
+        fail "full-auto first-run handoff was not controlled by the explicit choice"
     fi
 }
 
@@ -420,6 +471,7 @@ test_local_npx_installs_into_clean_repo
 test_local_npx_setup_honors_model_profile_flag
 test_packed_tarball_scratch_smoke
 test_default_interactive_hands_off_to_codex
+test_full_auto_handoff_choice_is_explicit
 test_ci_mode_keeps_shell_setup_path
 test_cli_help_documents_bootstrap_profile_policy