gsd-codex-cli 1.20.3 → 1.20.5

package/.codex/prompts/gsd-add-phase.md

@@ -12,8 +12,11 @@ Add phase to end of current milestone in roadmap
 - Use .codex/skills/get-shit-done-codex semantics.
 - Treat upstream workflow as the source of truth.
 - Replace user-specific paths with workspace-relative paths (.claude/..., .planning/...).
-- Run engine commands through PowerShell: 
-node .claude/get-shit-done/bin/gsd-tools.js ...
+- Use one of these engine paths (prefer local, fallback global):
+  node .claude/get-shit-done/bin/gsd-tools.js ...
+  node ~/.claude/get-shit-done/bin/gsd-tools.js ...
+- If `.js` is unavailable, use the same path with `.cjs`.
+- Run engine commands through PowerShell.
 - Parse JSON with ConvertFrom-Json; parse key/value output when workflow uses KEY=value raw mode.
 - No jq / bash-only constructs.
 
@@ -24,16 +27,15 @@ node .claude/get-shit-done/bin/gsd-tools.js ...
 - Use `.claude/agents/gsd-*.md` as role context for each spawned agent.
 - Do not advance workflow steps until wait and close complete.
 ## Update check
-- Run:
-  $update = node .claude/get-shit-done/bin/gsd-tools.cjs update check --raw | ConvertFrom-Json
-- If $update.update_available is true, surface:
-  "Update available: $($update.installed) -> $($update.latest). Run /gsd:update or re-run npx gsd-codex-cli@latest."
-
+- Best-effort only; do not fail if offline.
+- Check installed Codex fork version from `.codex/gsd/VERSION` (or `~/.codex/gsd/VERSION`).
+- Check latest published version with `npm view gsd-codex-cli version`.
+- If versions differ, surface: "Update available: <installed> -> <latest>. Next: gsd-update (Codex) / /gsd:update (Claude) or re-run npx gsd-codex-cli@latest."
 
 ## Execution
 1. Parse <description> from the user input.
 2. Run init:
-node .claude/get-shit-done/bin/gsd-tools.js init phase-op "0" --raw
+node <gsd-tools-path> init phase-op "0" --raw
 
 3. Load .claude/get-shit-done/workflows/add-phase.md and execute it step-by-step.
 4. Translate each Task(...) in workflow into:
@@ -41,11 +43,10 @@ node .claude/get-shit-done/bin/gsd-tools.js init phase-op "0" --raw
    - wait for each spawned agent and apply returned output before moving forward.
 5. Preserve all gates and routing from upstream workflow.
 6. Preserve commit behavior using 
-node .claude/get-shit-done/bin/gsd-tools.js commit "message" --files ....
-7. If commit preflight fails (no git / no commit flag), proceed in read-only mode and report clearly.
-
-## Completion output
-- Summarize key artifacts created/updated and next recommended command.
-
-
-
+node <gsd-tools-path> commit "message" --files ....
+7. If commit preflight fails (no git / no commit flag), proceed in read-only mode and report clearly.
+
+## Completion output
+- Summarize key artifacts created/updated.
+- Next recommended command: use the next user-facing GSD command (Codex prompt name + Claude slash command).
+- Never recommend internal `node ... gsd-tools ...` commands to the user.

package/.codex/prompts/gsd-add-todo.md

@@ -12,8 +12,11 @@ Capture idea or task as todo from current conversation context
 - Use .codex/skills/get-shit-done-codex semantics.
 - Treat upstream workflow as the source of truth.
 - Replace user-specific paths with workspace-relative paths (.claude/..., .planning/...).
-- Run engine commands through PowerShell: 
-node .claude/get-shit-done/bin/gsd-tools.js ...
+- Use one of these engine paths (prefer local, fallback global):
+  node .claude/get-shit-done/bin/gsd-tools.js ...
+  node ~/.claude/get-shit-done/bin/gsd-tools.js ...
+- If `.js` is unavailable, use the same path with `.cjs`.
+- Run engine commands through PowerShell.
 - Parse JSON with ConvertFrom-Json; parse key/value output when workflow uses KEY=value raw mode.
 - No jq / bash-only constructs.
 
@@ -24,16 +27,15 @@ node .claude/get-shit-done/bin/gsd-tools.js ...
 - Use `.claude/agents/gsd-*.md` as role context for each spawned agent.
 - Do not advance workflow steps until wait and close complete.
 ## Update check
-- Run:
-  $update = node .claude/get-shit-done/bin/gsd-tools.cjs update check --raw | ConvertFrom-Json
-- If $update.update_available is true, surface:
-  "Update available: $($update.installed) -> $($update.latest). Run /gsd:update or re-run npx gsd-codex-cli@latest."
-
+- Best-effort only; do not fail if offline.
+- Check installed Codex fork version from `.codex/gsd/VERSION` (or `~/.codex/gsd/VERSION`).
+- Check latest published version with `npm view gsd-codex-cli version`.
+- If versions differ, surface: "Update available: <installed> -> <latest>. Next: gsd-update (Codex) / /gsd:update (Claude) or re-run npx gsd-codex-cli@latest."
 
 ## Execution
 1. Parse [optional description] from the user input.
 2. Run init:
-node .claude/get-shit-done/bin/gsd-tools.js init todos $ARG --raw
+node <gsd-tools-path> init todos [argument] --raw
 
 3. Load .claude/get-shit-done/workflows/add-todo.md and execute it step-by-step.
 4. Translate each Task(...) in workflow into:
@@ -41,10 +43,10 @@ node .claude/get-shit-done/bin/gsd-tools.js init todos $ARG --raw
    - wait for each spawned agent and apply returned output before moving forward.
 5. Preserve all gates and routing from upstream workflow.
 6. Preserve commit behavior using 
-node .claude/get-shit-done/bin/gsd-tools.js commit "message" --files ....
-7. If commit preflight fails (no git / no commit flag), proceed in read-only mode and report clearly.
-
-## Completion output
-- Summarize key artifacts created/updated and next recommended command.
-
-
+node <gsd-tools-path> commit "message" --files ....
+7. If commit preflight fails (no git / no commit flag), proceed in read-only mode and report clearly.
+
+## Completion output
+- Summarize key artifacts created/updated.
+- Next recommended command: use the next user-facing GSD command (Codex prompt name + Claude slash command).
+- Never recommend internal `node ... gsd-tools ...` commands to the user.

package/.codex/prompts/gsd-audit-milestone.md

@@ -12,8 +12,11 @@ Audit milestone completion against original intent before archiving
 - Use .codex/skills/get-shit-done-codex semantics.
 - Treat upstream workflow as the source of truth.
 - Replace user-specific paths with workspace-relative paths (.claude/..., .planning/...).
-- Run engine commands through PowerShell: 
-node .claude/get-shit-done/bin/gsd-tools.js ...
+- Use one of these engine paths (prefer local, fallback global):
+  node .claude/get-shit-done/bin/gsd-tools.js ...
+  node ~/.claude/get-shit-done/bin/gsd-tools.js ...
+- If `.js` is unavailable, use the same path with `.cjs`.
+- Run engine commands through PowerShell.
 - Parse JSON with ConvertFrom-Json; parse key/value output when workflow uses KEY=value raw mode.
 - No jq / bash-only constructs.
 
@@ -24,16 +27,15 @@ node .claude/get-shit-done/bin/gsd-tools.js ...
 - Use `.claude/agents/gsd-*.md` as role context for each spawned agent.
 - Do not advance workflow steps until wait and close complete.
 ## Update check
-- Run:
-  $update = node .claude/get-shit-done/bin/gsd-tools.cjs update check --raw | ConvertFrom-Json
-- If $update.update_available is true, surface:
-  "Update available: $($update.installed) -> $($update.latest). Run /gsd:update or re-run npx gsd-codex-cli@latest."
-
+- Best-effort only; do not fail if offline.
+- Check installed Codex fork version from `.codex/gsd/VERSION` (or `~/.codex/gsd/VERSION`).
+- Check latest published version with `npm view gsd-codex-cli version`.
+- If versions differ, surface: "Update available: <installed> -> <latest>. Next: gsd-update (Codex) / /gsd:update (Claude) or re-run npx gsd-codex-cli@latest."
 
 ## Execution
 1. Parse "[version]" from the user input.
 2. Run init:
-node .claude/get-shit-done/bin/gsd-tools.js init milestone-op --raw
+node <gsd-tools-path> init milestone-op --raw
 
 3. Load .claude/get-shit-done/workflows/audit-milestone.md and execute it step-by-step.
 4. Translate each Task(...) in workflow into:
@@ -41,10 +43,10 @@ node .claude/get-shit-done/bin/gsd-tools.js init milestone-op --raw
    - wait for each spawned agent and apply returned output before moving forward.
 5. Preserve all gates and routing from upstream workflow.
 6. Preserve commit behavior using 
-node .claude/get-shit-done/bin/gsd-tools.js commit "message" --files ....
-7. If commit preflight fails (no git / no commit flag), proceed in read-only mode and report clearly.
-
-## Completion output
-- Summarize key artifacts created/updated and next recommended command.
-
-
+node <gsd-tools-path> commit "message" --files ....
+7. If commit preflight fails (no git / no commit flag), proceed in read-only mode and report clearly.
+
+## Completion output
+- Summarize key artifacts created/updated.
+- Next recommended command: use the next user-facing GSD command (Codex prompt name + Claude slash command).
+- Never recommend internal `node ... gsd-tools ...` commands to the user.

package/.codex/prompts/gsd-check-todos.md

@@ -12,8 +12,11 @@ List pending todos and select one to work on
 - Use .codex/skills/get-shit-done-codex semantics.
 - Treat upstream workflow as the source of truth.
 - Replace user-specific paths with workspace-relative paths (.claude/..., .planning/...).
-- Run engine commands through PowerShell: 
-node .claude/get-shit-done/bin/gsd-tools.js ...
+- Use one of these engine paths (prefer local, fallback global):
+  node .claude/get-shit-done/bin/gsd-tools.js ...
+  node ~/.claude/get-shit-done/bin/gsd-tools.js ...
+- If `.js` is unavailable, use the same path with `.cjs`.
+- Run engine commands through PowerShell.
 - Parse JSON with ConvertFrom-Json; parse key/value output when workflow uses KEY=value raw mode.
 - No jq / bash-only constructs.
 
@@ -24,16 +27,15 @@ node .claude/get-shit-done/bin/gsd-tools.js ...
 - Use `.claude/agents/gsd-*.md` as role context for each spawned agent.
 - Do not advance workflow steps until wait and close complete.
 ## Update check
-- Run:
-  $update = node .claude/get-shit-done/bin/gsd-tools.cjs update check --raw | ConvertFrom-Json
-- If $update.update_available is true, surface:
-  "Update available: $($update.installed) -> $($update.latest). Run /gsd:update or re-run npx gsd-codex-cli@latest."
-
+- Best-effort only; do not fail if offline.
+- Check installed Codex fork version from `.codex/gsd/VERSION` (or `~/.codex/gsd/VERSION`).
+- Check latest published version with `npm view gsd-codex-cli version`.
+- If versions differ, surface: "Update available: <installed> -> <latest>. Next: gsd-update (Codex) / /gsd:update (Claude) or re-run npx gsd-codex-cli@latest."
 
 ## Execution
 1. Parse [area filter] from the user input.
 2. Run init:
-node .claude/get-shit-done/bin/gsd-tools.js init todos $ARG --raw
+node <gsd-tools-path> init todos [argument] --raw
 
 3. Load .claude/get-shit-done/workflows/check-todos.md and execute it step-by-step.
 4. Translate each Task(...) in workflow into:
@@ -41,10 +43,10 @@ node .claude/get-shit-done/bin/gsd-tools.js init todos $ARG --raw
    - wait for each spawned agent and apply returned output before moving forward.
 5. Preserve all gates and routing from upstream workflow.
 6. Preserve commit behavior using 
-node .claude/get-shit-done/bin/gsd-tools.js commit "message" --files ....
-7. If commit preflight fails (no git / no commit flag), proceed in read-only mode and report clearly.
-
-## Completion output
-- Summarize key artifacts created/updated and next recommended command.
-
-
+node <gsd-tools-path> commit "message" --files ....
+7. If commit preflight fails (no git / no commit flag), proceed in read-only mode and report clearly.
+
+## Completion output
+- Summarize key artifacts created/updated.
+- Next recommended command: use the next user-facing GSD command (Codex prompt name + Claude slash command).
+- Never recommend internal `node ... gsd-tools ...` commands to the user.

package/.codex/prompts/gsd-complete-milestone.md

@@ -12,8 +12,11 @@ Archive completed milestone and prepare for next version
 - Use .codex/skills/get-shit-done-codex semantics.
 - Treat upstream workflow as the source of truth.
 - Replace user-specific paths with workspace-relative paths (.claude/..., .planning/...).
-- Run engine commands through PowerShell: 
-node .claude/get-shit-done/bin/gsd-tools.js ...
+- Use one of these engine paths (prefer local, fallback global):
+  node .claude/get-shit-done/bin/gsd-tools.js ...
+  node ~/.claude/get-shit-done/bin/gsd-tools.js ...
+- If `.js` is unavailable, use the same path with `.cjs`.
+- Run engine commands through PowerShell.
 - Parse JSON with ConvertFrom-Json; parse key/value output when workflow uses KEY=value raw mode.
 - No jq / bash-only constructs.
 
@@ -24,16 +27,15 @@ node .claude/get-shit-done/bin/gsd-tools.js ...
 - Use `.claude/agents/gsd-*.md` as role context for each spawned agent.
 - Do not advance workflow steps until wait and close complete.
 ## Update check
-- Run:
-  $update = node .claude/get-shit-done/bin/gsd-tools.cjs update check --raw | ConvertFrom-Json
-- If $update.update_available is true, surface:
-  "Update available: $($update.installed) -> $($update.latest). Run /gsd:update or re-run npx gsd-codex-cli@latest."
-
+- Best-effort only; do not fail if offline.
+- Check installed Codex fork version from `.codex/gsd/VERSION` (or `~/.codex/gsd/VERSION`).
+- Check latest published version with `npm view gsd-codex-cli version`.
+- If versions differ, surface: "Update available: <installed> -> <latest>. Next: gsd-update (Codex) / /gsd:update (Claude) or re-run npx gsd-codex-cli@latest."
 
 ## Execution
 1. Parse <version> from the user input.
 2. Run init:
-node .claude/get-shit-done/bin/gsd-tools.js init execute-phase "1" --raw
+node <gsd-tools-path> init execute-phase "1" --raw
 
 3. Load .claude/get-shit-done/workflows/complete-milestone.md and execute it step-by-step.
 4. Translate each Task(...) in workflow into:
@@ -41,10 +43,10 @@ node .claude/get-shit-done/bin/gsd-tools.js init execute-phase "1" --raw
    - wait for each spawned agent and apply returned output before moving forward.
 5. Preserve all gates and routing from upstream workflow.
 6. Preserve commit behavior using 
-node .claude/get-shit-done/bin/gsd-tools.js commit "message" --files ....
-7. If commit preflight fails (no git / no commit flag), proceed in read-only mode and report clearly.
-
-## Completion output
-- Summarize key artifacts created/updated and next recommended command.
-
-
+node <gsd-tools-path> commit "message" --files ....
+7. If commit preflight fails (no git / no commit flag), proceed in read-only mode and report clearly.
+
+## Completion output
+- Summarize key artifacts created/updated.
+- Next recommended command: use the next user-facing GSD command (Codex prompt name + Claude slash command).
+- Never recommend internal `node ... gsd-tools ...` commands to the user.

package/.codex/prompts/gsd-debug.md

@@ -12,8 +12,11 @@ Systematic debugging with persistent state across context resets
 - Use .codex/skills/get-shit-done-codex semantics.
 - Treat upstream workflow as the source of truth.
 - Replace user-specific paths with workspace-relative paths (.claude/..., .planning/...).
-- Run engine commands through PowerShell: 
-node .claude/get-shit-done/bin/gsd-tools.js ...
+- Use one of these engine paths (prefer local, fallback global):
+  node .claude/get-shit-done/bin/gsd-tools.js ...
+  node ~/.claude/get-shit-done/bin/gsd-tools.js ...
+- If `.js` is unavailable, use the same path with `.cjs`.
+- Run engine commands through PowerShell.
 - Parse JSON with ConvertFrom-Json; parse key/value output when workflow uses KEY=value raw mode.
 - No jq / bash-only constructs.
 
@@ -24,16 +27,15 @@ node .claude/get-shit-done/bin/gsd-tools.js ...
 - Use `.claude/agents/gsd-*.md` as role context for each spawned agent.
 - Do not advance workflow steps until wait and close complete.
 ## Update check
-- Run:
-  $update = node .claude/get-shit-done/bin/gsd-tools.cjs update check --raw | ConvertFrom-Json
-- If $update.update_available is true, surface:
-  "Update available: $($update.installed) -> $($update.latest). Run /gsd:update or re-run npx gsd-codex-cli@latest."
-
+- Best-effort only; do not fail if offline.
+- Check installed Codex fork version from `.codex/gsd/VERSION` (or `~/.codex/gsd/VERSION`).
+- Check latest published version with `npm view gsd-codex-cli version`.
+- If versions differ, surface: "Update available: <installed> -> <latest>. Next: gsd-update (Codex) / /gsd:update (Claude) or re-run npx gsd-codex-cli@latest."
 
 ## Execution
 1. Parse [issue description] from the user input.
 2. Run init:
-node .claude/get-shit-done/bin/gsd-tools.js state load --raw
+node <gsd-tools-path> state load --raw
 
 3. Execute the debug flow defined in this command (no separate workflow file exists in the gsd commands set).
 4. Translate each Task(...) in the debug flow into:
@@ -41,13 +43,13 @@ node .claude/get-shit-done/bin/gsd-tools.js state load --raw
    - wait for each spawned agent and apply returned output before moving forward.
 5. Preserve all gates and routing from upstream workflow.
 6. Preserve commit behavior using 
-node .claude/get-shit-done/bin/gsd-tools.js commit "message" --files ....
+node <gsd-tools-path> commit "message" --files ....
 7. Checkpoint handling:
    - If an active debug session exists and no new issue was provided, list open sessions and ask the user which to resume.
    - If a checkpoint is returned by the debugger, summarize the checkpoint and continue only after user confirmation.
-8. If commit preflight fails (no git / no commit flag), proceed in read-only mode and report clearly.
-
-## Completion output
-- Summarize key artifacts created/updated and next recommended command.
-
-
+8. If commit preflight fails (no git / no commit flag), proceed in read-only mode and report clearly.
+
+## Completion output
+- Summarize key artifacts created/updated.
+- Next recommended command: use the next user-facing GSD command (Codex prompt name + Claude slash command).
+- Never recommend internal `node ... gsd-tools ...` commands to the user.

package/.codex/prompts/gsd-discuss-phase.md

@@ -12,8 +12,11 @@ Gather phase context through adaptive questioning before planning
 - Use .codex/skills/get-shit-done-codex semantics.
 - Treat upstream workflow as the source of truth.
 - Replace user-specific paths with workspace-relative paths (.claude/..., .planning/...).
-- Run engine commands through PowerShell: 
-node .claude/get-shit-done/bin/gsd-tools.js ...
+- Use one of these engine paths (prefer local, fallback global):
+  node .claude/get-shit-done/bin/gsd-tools.js ...
+  node ~/.claude/get-shit-done/bin/gsd-tools.js ...
+- If `.js` is unavailable, use the same path with `.cjs`.
+- Run engine commands through PowerShell.
 - Parse JSON with ConvertFrom-Json; parse key/value output when workflow uses KEY=value raw mode.
 - No jq / bash-only constructs.
 
@@ -24,16 +27,15 @@ node .claude/get-shit-done/bin/gsd-tools.js ...
 - Use `.claude/agents/gsd-*.md` as role context for each spawned agent.
 - Do not advance workflow steps until wait and close complete.
 ## Update check
-- Run:
-  $update = node .claude/get-shit-done/bin/gsd-tools.cjs update check --raw | ConvertFrom-Json
-- If $update.update_available is true, surface:
-  "Update available: $($update.installed) -> $($update.latest). Run /gsd:update or re-run npx gsd-codex-cli@latest."
-
+- Best-effort only; do not fail if offline.
+- Check installed Codex fork version from `.codex/gsd/VERSION` (or `~/.codex/gsd/VERSION`).
+- Check latest published version with `npm view gsd-codex-cli version`.
+- If versions differ, surface: "Update available: <installed> -> <latest>. Next: gsd-update (Codex) / /gsd:update (Claude) or re-run npx gsd-codex-cli@latest."
 
 ## Execution
 1. Parse "<phase>" from the user input.
 2. Run init:
-node .claude/get-shit-done/bin/gsd-tools.js init phase-op $ARG --raw
+node <gsd-tools-path> init phase-op [argument] --raw
 
 3. Load .claude/get-shit-done/workflows/discuss-phase.md and execute it step-by-step.
 4. Translate each Task(...) in workflow into:
@@ -41,10 +43,10 @@ node .claude/get-shit-done/bin/gsd-tools.js init phase-op $ARG --raw
    - wait for each spawned agent and apply returned output before moving forward.
 5. Preserve all gates and routing from upstream workflow.
 6. Preserve commit behavior using 
-node .claude/get-shit-done/bin/gsd-tools.js commit "message" --files ....
-7. If commit preflight fails (no git / no commit flag), proceed in read-only mode and report clearly.
-
-## Completion output
-- Summarize key artifacts created/updated and next recommended command.
-
-
+node <gsd-tools-path> commit "message" --files ....
+7. If commit preflight fails (no git / no commit flag), proceed in read-only mode and report clearly.
+
+## Completion output
+- Summarize key artifacts created/updated.
+- Next recommended command: `gsd-plan-phase [phase]` (Codex) / `/gsd:plan-phase [phase]` (Claude)
+- Never recommend internal `node ... gsd-tools ...` commands to the user.

package/.codex/prompts/gsd-doctor.md

@@ -0,0 +1,51 @@
+---
+description: Diagnose Codex+Claude GSD installation (engine, prompts, versions)
+argument-hint: [none]
+---
+
+
+
+## Objective
+Diagnose whether this project is set up to run GSD prompts in Codex while remaining compatible with Claude workflows on the same `.planning/` milestone/phases.
+
+## Compatibility
+- Use .codex/skills/get-shit-done-codex semantics.
+- Do not modify files (read-only diagnostics).
+- Prefer PowerShell commands; no jq.
+
+## Checks to run
+Run these checks and then present a compact table: `check | status | details | fix`.
+
+### Versions
+- Codex fork installed version (first match wins):
+  - `.codex/gsd/VERSION`
+  - `~/.codex/gsd/VERSION`
+- Claude engine installed version (first match wins):
+  - `.claude/get-shit-done/VERSION`
+  - `~/.claude/get-shit-done/VERSION`
+
+### Engine presence (required for Codex prompts)
+- `.claude/get-shit-done/bin/gsd-tools.cjs` OR `.claude/get-shit-done/bin/gsd-tools.js`
+- If only `gsd-tools.test.js` exists, treat engine as missing/incomplete.
+
+### Project state
+- `.planning/` exists (if missing, user hasn’t initialized a project).
+
+### Update availability (best-effort)
+- Latest Codex fork version (do not fail if offline):
+  - `npm view gsd-codex-cli version`
+- If installed Codex fork version is known and differs from latest, surface:
+  - `Update available: {installed} -> {latest}`
+  - Next: `gsd-update` (Codex) / `/gsd:update` (Claude) or re-run `npx gsd-codex-cli@latest`.
+
+## Recommended fixes (use the minimum)
+- If engine missing: `npx gsd-codex-cli@latest --path .` (or `--global`)
+- If only Claude engine exists and Codex prompts are desired in-project: `npx gsd-codex-cli@latest --path .`
+- If `.planning/` missing: run `gsd-new-project` (Codex) / `/gsd:new-project` (Claude)
+
+## Completion output
+- Print the table and a single “Next recommended command”:
+  - If engine missing: `npx gsd-codex-cli@latest --path .`
+  - Else if `.planning/` missing: `gsd-new-project` / `/gsd:new-project`
+  - Else: `gsd-progress` / `/gsd:progress`
+

package/.codex/prompts/gsd-execute-phase.md

@@ -12,8 +12,11 @@ Execute all plans in a phase with wave-based parallelization
 - Use .codex/skills/get-shit-done-codex semantics.
 - Treat upstream workflow as the source of truth.
 - Replace user-specific paths with workspace-relative paths (.claude/..., .planning/...).
-- Run engine commands through PowerShell: 
-node .claude/get-shit-done/bin/gsd-tools.js ...
+- Use one of these engine paths (prefer local, fallback global):
+  node .claude/get-shit-done/bin/gsd-tools.js ...
+  node ~/.claude/get-shit-done/bin/gsd-tools.js ...
+- If `.js` is unavailable, use the same path with `.cjs`.
+- Run engine commands through PowerShell.
 - Parse JSON with ConvertFrom-Json; parse key/value output when workflow uses KEY=value raw mode.
 - No jq / bash-only constructs.
 
@@ -24,16 +27,15 @@ node .claude/get-shit-done/bin/gsd-tools.js ...
 - Use `.claude/agents/gsd-*.md` as role context for each spawned agent.
 - Do not advance workflow steps until wait and close complete.
 ## Update check
-- Run:
-  $update = node .claude/get-shit-done/bin/gsd-tools.cjs update check --raw | ConvertFrom-Json
-- If $update.update_available is true, surface:
-  "Update available: $($update.installed) -> $($update.latest). Run /gsd:update or re-run npx gsd-codex-cli@latest."
-
+- Best-effort only; do not fail if offline.
+- Check installed Codex fork version from `.codex/gsd/VERSION` (or `~/.codex/gsd/VERSION`).
+- Check latest published version with `npm view gsd-codex-cli version`.
+- If versions differ, surface: "Update available: <installed> -> <latest>. Next: gsd-update (Codex) / /gsd:update (Claude) or re-run npx gsd-codex-cli@latest."
 
 ## Execution
 1. Parse "<phase-number> [--gaps-only]" from the user input.
 2. Run init:
-node .claude/get-shit-done/bin/gsd-tools.js init execute-phase $PHASE --raw
+node <gsd-tools-path> init execute-phase [phase] --raw
 
 3. Load .claude/get-shit-done/workflows/execute-phase.md and execute it step-by-step.
 4. Translate each Task(...) in workflow into:
@@ -41,10 +43,10 @@ node .claude/get-shit-done/bin/gsd-tools.js init execute-phase $PHASE --raw
    - wait for each spawned agent and apply returned output before moving forward.
 5. Preserve all gates and routing from upstream workflow.
 6. Preserve commit behavior using 
-node .claude/get-shit-done/bin/gsd-tools.js commit "message" --files ....
-7. If commit preflight fails (no git / no commit flag), proceed in read-only mode and report clearly.
-
-## Completion output
-- Summarize key artifacts created/updated and next recommended command.
-
-
+node <gsd-tools-path> commit "message" --files ....
+7. If commit preflight fails (no git / no commit flag), proceed in read-only mode and report clearly.
+
+## Completion output
+- Summarize key artifacts created/updated.
+- Next recommended command: `gsd-verify-work [phase]` (Codex) / `/gsd:verify-work [phase]` (Claude)
+- Never recommend internal `node ... gsd-tools ...` commands to the user.

package/.codex/prompts/gsd-help.md

@@ -12,8 +12,11 @@ Show available GSD commands and usage guide
 - Use .codex/skills/get-shit-done-codex semantics.
 - Treat upstream workflow as the source of truth.
 - Replace user-specific paths with workspace-relative paths (.claude/..., .planning/...).
-- Run engine commands through PowerShell: 
-node .claude/get-shit-done/bin/gsd-tools.js ...
+- Use one of these engine paths (prefer local, fallback global):
+  node .claude/get-shit-done/bin/gsd-tools.js ...
+  node ~/.claude/get-shit-done/bin/gsd-tools.js ...
+- If `.js` is unavailable, use the same path with `.cjs`.
+- Run engine commands through PowerShell.
 - Parse JSON with ConvertFrom-Json; parse key/value output when workflow uses KEY=value raw mode.
 - No jq / bash-only constructs.
 
@@ -24,11 +27,10 @@ node .claude/get-shit-done/bin/gsd-tools.js ...
 - Use `.claude/agents/gsd-*.md` as role context for each spawned agent.
 - Do not advance workflow steps until wait and close complete.
 ## Update check
-- Run:
-  $update = node .claude/get-shit-done/bin/gsd-tools.cjs update check --raw | ConvertFrom-Json
-- If $update.update_available is true, surface:
-  "Update available: $($update.installed) -> $($update.latest). Run /gsd:update or re-run npx gsd-codex-cli@latest."
-
+- Best-effort only; do not fail if offline.
+- Check installed Codex fork version from `.codex/gsd/VERSION` (or `~/.codex/gsd/VERSION`).
+- Check latest published version with `npm view gsd-codex-cli version`.
+- If versions differ, surface: "Update available: <installed> -> <latest>. Next: gsd-update (Codex) / /gsd:update (Claude) or re-run npx gsd-codex-cli@latest."
 
 ## Execution
 1. Parse [none] from the user input.
@@ -41,10 +43,10 @@ node .claude/get-shit-done/bin/gsd-tools.js ...
    - wait for each spawned agent and apply returned output before moving forward.
 5. Preserve all gates and routing from upstream workflow.
 6. Preserve commit behavior using 
-node .claude/get-shit-done/bin/gsd-tools.js commit "message" --files ....
-7. If commit preflight fails (no git / no commit flag), proceed in read-only mode and report clearly.
-
-## Completion output
-- Summarize key artifacts created/updated and next recommended command.
-
-
+node <gsd-tools-path> commit "message" --files ....
+7. If commit preflight fails (no git / no commit flag), proceed in read-only mode and report clearly.
+
+## Completion output
+- Summarize key artifacts created/updated.
+- Next recommended command: use the next user-facing GSD command (Codex prompt name + Claude slash command).
+- Never recommend internal `node ... gsd-tools ...` commands to the user.

package/.codex/prompts/gsd-insert-phase.md

@@ -12,8 +12,11 @@ Insert urgent work as decimal phase (for example 72.1) between existing phases
 - Use .codex/skills/get-shit-done-codex semantics.
 - Treat upstream workflow as the source of truth.
 - Replace user-specific paths with workspace-relative paths (.claude/..., .planning/...).
-- Run engine commands through PowerShell: 
-node .claude/get-shit-done/bin/gsd-tools.js ...
+- Use one of these engine paths (prefer local, fallback global):
+  node .claude/get-shit-done/bin/gsd-tools.js ...
+  node ~/.claude/get-shit-done/bin/gsd-tools.js ...
+- If `.js` is unavailable, use the same path with `.cjs`.
+- Run engine commands through PowerShell.
 - Parse JSON with ConvertFrom-Json; parse key/value output when workflow uses KEY=value raw mode.
 - No jq / bash-only constructs.
 
@@ -24,16 +27,15 @@ node .claude/get-shit-done/bin/gsd-tools.js ...
 - Use `.claude/agents/gsd-*.md` as role context for each spawned agent.
 - Do not advance workflow steps until wait and close complete.
 ## Update check
-- Run:
-  $update = node .claude/get-shit-done/bin/gsd-tools.cjs update check --raw | ConvertFrom-Json
-- If $update.update_available is true, surface:
-  "Update available: $($update.installed) -> $($update.latest). Run /gsd:update or re-run npx gsd-codex-cli@latest."
-
+- Best-effort only; do not fail if offline.
+- Check installed Codex fork version from `.codex/gsd/VERSION` (or `~/.codex/gsd/VERSION`).
+- Check latest published version with `npm view gsd-codex-cli version`.
+- If versions differ, surface: "Update available: <installed> -> <latest>. Next: gsd-update (Codex) / /gsd:update (Claude) or re-run npx gsd-codex-cli@latest."
 
 ## Execution
 1. Parse <after> <description> from the user input.
 2. Run init:
-node .claude/get-shit-done/bin/gsd-tools.js init phase-op $AFTER --raw
+node <gsd-tools-path> init phase-op [after-phase] --raw
 
 3. Load .claude/get-shit-done/workflows/insert-phase.md and execute it step-by-step.
 4. Translate each Task(...) in workflow into:
@@ -41,10 +43,10 @@ node .claude/get-shit-done/bin/gsd-tools.js init phase-op $AFTER --raw
    - wait for each spawned agent and apply returned output before moving forward.
 5. Preserve all gates and routing from upstream workflow.
 6. Preserve commit behavior using 
-node .claude/get-shit-done/bin/gsd-tools.js commit "message" --files ....
-7. If commit preflight fails (no git / no commit flag), proceed in read-only mode and report clearly.
-
-## Completion output
-- Summarize key artifacts created/updated and next recommended command.
-
-
+node <gsd-tools-path> commit "message" --files ....
+7. If commit preflight fails (no git / no commit flag), proceed in read-only mode and report clearly.
+
+## Completion output
+- Summarize key artifacts created/updated.
+- Next recommended command: use the next user-facing GSD command (Codex prompt name + Claude slash command).
+- Never recommend internal `node ... gsd-tools ...` commands to the user.