gsd-codex-cli 1.20.10 → 1.20.12

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

@@ -46,5 +46,5 @@ node <gsd-tools-path> commit "message" --files ....
 
 ## Completion output
 - Summarize key artifacts created/updated.
-- Next recommended command: use the next user-facing GSD command (Codex prompt name + Claude slash command).
+- Next recommended command: use the next user-facing GSD command (`/prompts:gsd-...` for Codex + `/gsd:...` for Claude).
 - Never recommend internal `node ... gsd-tools ...` commands to the user.

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

@@ -46,5 +46,5 @@ node <gsd-tools-path> commit "message" --files ....
 
 ## Completion output
 - Summarize key artifacts created/updated.
-- Next recommended command: use the next user-facing GSD command (Codex prompt name + Claude slash command).
+- Next recommended command: use the next user-facing GSD command (`/prompts:gsd-...` for Codex + `/gsd:...` for Claude).
 - Never recommend internal `node ... gsd-tools ...` commands to the user.

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

@@ -46,5 +46,5 @@ node <gsd-tools-path> commit "message" --files ....
 
 ## Completion output
 - Summarize key artifacts created/updated.
-- Next recommended command: use the next user-facing GSD command (Codex prompt name + Claude slash command).
+- Next recommended command: use the next user-facing GSD command (`/prompts:gsd-...` for Codex + `/gsd:...` for Claude).
 - Never recommend internal `node ... gsd-tools ...` commands to the user.

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

@@ -46,5 +46,5 @@ node <gsd-tools-path> commit "message" --files ....
 
 ## Completion output
 - Summarize key artifacts created/updated.
-- Next recommended command: use the next user-facing GSD command (Codex prompt name + Claude slash command).
+- Next recommended command: use the next user-facing GSD command (`/prompts:gsd-...` for Codex + `/gsd:...` for Claude).
 - Never recommend internal `node ... gsd-tools ...` commands to the user.

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

@@ -46,5 +46,5 @@ node <gsd-tools-path> commit "message" --files ....
 
 ## Completion output
 - Summarize key artifacts created/updated.
-- Next recommended command: use the next user-facing GSD command (Codex prompt name + Claude slash command).
+- Next recommended command: use the next user-facing GSD command (`/prompts:gsd-...` for Codex + `/gsd:...` for Claude).
 - Never recommend internal `node ... gsd-tools ...` commands to the user.

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

@@ -49,5 +49,5 @@ node <gsd-tools-path> commit "message" --files ....
 
 ## Completion output
 - Summarize key artifacts created/updated.
-- Next recommended command: use the next user-facing GSD command (Codex prompt name + Claude slash command).
+- Next recommended command: use the next user-facing GSD command (`/prompts:gsd-...` for Codex + `/gsd:...` for Claude).
 - Never recommend internal `node ... gsd-tools ...` commands to the user.

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

@@ -46,5 +46,5 @@ node <gsd-tools-path> commit "message" --files ....
 
 ## Completion output
 - Summarize key artifacts created/updated.
-- Next recommended command: `gsd-plan-phase [phase]` (Codex) / `/gsd:plan-phase [phase]` (Claude)
+- Next recommended command: `/prompts: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

@@ -1,12 +1,12 @@
----
-description: Diagnose Codex+Claude GSD installation (engine, prompts, versions)
-argument-hint: [none]
----
-
-$ARGUMENTS
-
-## 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.
+---
+description: Diagnose Codex+Claude GSD installation (engine, prompts, versions)
+argument-hint: [none]
+---
+
+$ARGUMENTS
+
+## 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.
@@ -28,22 +28,22 @@ Run these checks and then present a compact table: `check | status | details | f
 - `.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 check
-- Best-effort only; do not fail if offline.
-### 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:
+### Project state
+- `.planning/` exists (if missing, user hasn’t initialized a project).
+
+## Update check
+- Best-effort only; do not fail if offline.
+### 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`.
+  - Next: `/prompts: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)
+- If `.planning/` missing: run `/prompts:gsd-new-project` (Codex) / `/gsd:new-project` (Claude)
 
 ## Completion output
 - Print the table and a single “Next recommended command”:

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

@@ -59,5 +59,5 @@ node <gsd-tools-path> commit "message" --files ....
 
 ## Completion output
 - Summarize key artifacts created/updated.
-- Next recommended command: `gsd-verify-work <phase>` (Codex) / `/gsd:verify-work <phase>` (Claude)
+- Next recommended command: `/prompts: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

@@ -46,5 +46,5 @@ node <gsd-tools-path> commit "message" --files ....
 
 ## Completion output
 - Summarize key artifacts created/updated.
-- Next recommended command: use the next user-facing GSD command (Codex prompt name + Claude slash command).
+- Next recommended command: use the next user-facing GSD command (`/prompts:gsd-...` for Codex + `/gsd:...` for Claude).
 - Never recommend internal `node ... gsd-tools ...` commands to the user.

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

@@ -46,5 +46,5 @@ node <gsd-tools-path> commit "message" --files ....
 
 ## Completion output
 - Summarize key artifacts created/updated.
-- Next recommended command: use the next user-facing GSD command (Codex prompt name + Claude slash command).
+- Next recommended command: use the next user-facing GSD command (`/prompts:gsd-...` for Codex + `/gsd:...` for Claude).
 - Never recommend internal `node ... gsd-tools ...` commands to the user.

package/.codex/prompts/gsd-list-phase-assumptions.md

@@ -46,5 +46,5 @@ node <gsd-tools-path> commit "message" --files ....
 
 ## Completion output
 - Summarize key artifacts created/updated.
-- Next recommended command: use the next user-facing GSD command (Codex prompt name + Claude slash command).
+- Next recommended command: use the next user-facing GSD command (`/prompts:gsd-...` for Codex + `/gsd:...` for Claude).
 - Never recommend internal `node ... gsd-tools ...` commands to the user.

package/.codex/prompts/gsd-map-codebase.md

@@ -46,5 +46,5 @@ node <gsd-tools-path> commit "message" --files ....
 
 ## Completion output
 - Summarize key artifacts created/updated.
-- Next recommended command: use the next user-facing GSD command (Codex prompt name + Claude slash command).
+- Next recommended command: use the next user-facing GSD command (`/prompts:gsd-...` for Codex + `/gsd:...` for Claude).
 - Never recommend internal `node ... gsd-tools ...` commands to the user.

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

@@ -1,12 +1,12 @@
 ---
-description: Start a new milestone cycle — update PROJECT.md and route to requirements
+description: Start a new milestone cycle end-to-end (questioning -> requirements -> roadmap)
 argument-hint: "[milestone name, for example v1.1 Notifications]"
 ---
 
 $ARGUMENTS
 
 ## Objective
-Start a new milestone cycle — update PROJECT.md and route to requirements
+Start a new milestone cycle end-to-end (questioning -> requirements -> roadmap)
 
 ## Compatibility
 - Use .codex/skills/get-shit-done-codex semantics.
@@ -22,6 +22,8 @@ Start a new milestone cycle — update PROJECT.md and route to requirements
 - No jq / bash-only constructs.
 - Accept natural-language command input; do not require an exact literal argument template.
 - If a required argument is still missing after extraction, ask one concise clarification question.
+- If `.planning/MILESTONE-CONTEXT.md` is missing, ask options before drafting goals; do not assume milestone scope.
+- Do not complete successfully unless `.planning/ROADMAP.md` exists (or explicit `ROADMAP BLOCKED` is surfaced).
 
 ## Subagent lifecycle (required)
 
@@ -36,15 +38,22 @@ Start a new milestone cycle — update PROJECT.md and route to requirements
 node <gsd-tools-path> init new-milestone --raw
 
 3. Load .claude/get-shit-done/workflows/new-milestone.md and execute it step-by-step.
-4. Translate each Task(...) in workflow into:
+4. If `.planning/MILESTONE-CONTEXT.md` is absent, run an explicit options question before requirements:
+   - "Ship features (Recommended)"
+   - "Stabilize quality"
+   - "Platform + ops"
+   - "Custom scope"
+   Then summarize the chosen direction and ask for confirmation.
+5. Translate each Task(...) in workflow into:
    - spawn_agent with the matching role file context from .claude/agents/.
    - 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 
+6. Preserve all gates and routing from upstream workflow.
+7. Before reporting success, verify `.planning/ROADMAP.md` exists. If missing, treat as blocked and continue workflow remediation.
+8. Preserve commit behavior using 
 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.
+9. 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).
+- Next recommended command: use the next user-facing GSD command (`/prompts:gsd-...` for Codex + `/gsd:...` for Claude).
 - Never recommend internal `node ... gsd-tools ...` commands to the user.

package/.codex/prompts/gsd-new-project.md

@@ -46,5 +46,5 @@ node <gsd-tools-path> commit "message" --files ....
 
 ## Completion output
 - Summarize key artifacts created/updated.
-- Next recommended command: `gsd-discuss-phase 1` (Codex) / `/gsd:discuss-phase 1` (Claude)
+- Next recommended command: `/prompts:gsd-discuss-phase 1` (Codex) / `/gsd:discuss-phase 1` (Claude)
 - Never recommend internal `node ... gsd-tools ...` commands to the user.

package/.codex/prompts/gsd-pause-work.md

@@ -46,5 +46,5 @@ node <gsd-tools-path> commit "message" --files ....
 
 ## Completion output
 - Summarize key artifacts created/updated.
-- Next recommended command: use the next user-facing GSD command (Codex prompt name + Claude slash command).
+- Next recommended command: use the next user-facing GSD command (`/prompts:gsd-...` for Codex + `/gsd:...` for Claude).
 - Never recommend internal `node ... gsd-tools ...` commands to the user.

package/.codex/prompts/gsd-plan-milestone-gaps.md

@@ -46,5 +46,5 @@ node <gsd-tools-path> commit "message" --files ....
 
 ## Completion output
 - Summarize key artifacts created/updated.
-- Next recommended command: use the next user-facing GSD command (Codex prompt name + Claude slash command).
+- Next recommended command: use the next user-facing GSD command (`/prompts:gsd-...` for Codex + `/gsd:...` for Claude).
 - Never recommend internal `node ... gsd-tools ...` commands to the user.

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

@@ -46,5 +46,5 @@ node <gsd-tools-path> commit "message" --files ....
 
 ## Completion output
 - Summarize key artifacts created/updated.
-- Next recommended command: `gsd-execute-phase [phase]` (Codex) / `/gsd:execute-phase [phase]` (Claude)
+- Next recommended command: `/prompts:gsd-execute-phase [phase]` (Codex) / `/gsd:execute-phase [phase]` (Claude)
 - Never recommend internal `node ... gsd-tools ...` commands to the user.

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

@@ -46,5 +46,5 @@ node <gsd-tools-path> commit "message" --files ....
 
 ## Completion output
 - Summarize key artifacts created/updated.
-- Next recommended command: use the next user-facing GSD command (Codex prompt name + Claude slash command).
+- Next recommended command: use the next user-facing GSD command (`/prompts:gsd-...` for Codex + `/gsd:...` for Claude).
 - Never recommend internal `node ... gsd-tools ...` commands to the user.

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

@@ -46,5 +46,5 @@ node <gsd-tools-path> commit "message" --files ....
 
 ## Completion output
 - Summarize key artifacts created/updated.
-- Next recommended command: use the next user-facing GSD command (Codex prompt name + Claude slash command).
+- Next recommended command: use the next user-facing GSD command (`/prompts:gsd-...` for Codex + `/gsd:...` for Claude).
 - Never recommend internal `node ... gsd-tools ...` commands to the user.

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

@@ -46,5 +46,5 @@ node <gsd-tools-path> commit "message" --files ....
 
 ## Completion output
 - Summarize key artifacts created/updated.
-- Next recommended command: use the next user-facing GSD command (Codex prompt name + Claude slash command).
+- Next recommended command: use the next user-facing GSD command (`/prompts:gsd-...` for Codex + `/gsd:...` for Claude).
 - Never recommend internal `node ... gsd-tools ...` commands to the user.

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

@@ -46,5 +46,5 @@ node <gsd-tools-path> commit "message" --files ....
 
 ## Completion output
 - Summarize key artifacts created/updated.
-- Next recommended command: use the next user-facing GSD command (Codex prompt name + Claude slash command).
+- Next recommended command: use the next user-facing GSD command (`/prompts:gsd-...` for Codex + `/gsd:...` for Claude).
 - Never recommend internal `node ... gsd-tools ...` commands to the user.

package/.codex/prompts/gsd-resume-work.md

@@ -46,5 +46,5 @@ node <gsd-tools-path> commit "message" --files ....
 
 ## Completion output
 - Summarize key artifacts created/updated.
-- Next recommended command: use the next user-facing GSD command (Codex prompt name + Claude slash command).
+- Next recommended command: use the next user-facing GSD command (`/prompts:gsd-...` for Codex + `/gsd:...` for Claude).
 - Never recommend internal `node ... gsd-tools ...` commands to the user.

package/.codex/prompts/gsd-set-profile.md

@@ -46,5 +46,5 @@ node <gsd-tools-path> commit "message" --files ....
 
 ## Completion output
 - Summarize key artifacts created/updated.
-- Next recommended command: use the next user-facing GSD command (Codex prompt name + Claude slash command).
+- Next recommended command: use the next user-facing GSD command (`/prompts:gsd-...` for Codex + `/gsd:...` for Claude).
 - Never recommend internal `node ... gsd-tools ...` commands to the user.

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

@@ -46,5 +46,5 @@ node <gsd-tools-path> commit "message" --files ....
 
 ## Completion output
 - Summarize key artifacts created/updated.
-- Next recommended command: use the next user-facing GSD command (Codex prompt name + Claude slash command).
+- Next recommended command: use the next user-facing GSD command (`/prompts:gsd-...` for Codex + `/gsd:...` for Claude).
 - Never recommend internal `node ... gsd-tools ...` commands to the user.

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

@@ -34,7 +34,7 @@ Update GSD to latest version with changelog display
 - 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."
+- If versions differ, surface: "Update available: <installed> -> <latest>. Next: /prompts:gsd-update (Codex) / /gsd:update (Claude) or re-run npx gsd-codex-cli@latest."
 
 ## Execution
 1. No positional argument is required. Read flags from command text if present.
@@ -52,5 +52,5 @@ node <gsd-tools-path> commit "message" --files ....
 
 ## Completion output
 - Summarize key artifacts created/updated.
-- Next recommended command: use the next user-facing GSD command (Codex prompt name + Claude slash command).
+- Next recommended command: use the next user-facing GSD command (`/prompts:gsd-...` for Codex + `/gsd:...` for Claude).
 - Never recommend internal `node ... gsd-tools ...` commands to the user.

package/.codex/prompts/gsd-verify-work.md

@@ -46,5 +46,5 @@ node <gsd-tools-path> commit "message" --files ....
 
 ## Completion output
 - Summarize key artifacts created/updated.
-- Next recommended command: use the next user-facing GSD command (Codex prompt name + Claude slash command).
+- Next recommended command: use the next user-facing GSD command (`/prompts:gsd-...` for Codex + `/gsd:...` for Claude).
 - Never recommend internal `node ... gsd-tools ...` commands to the user.

package/.codex/skills/get-shit-done-codex/SKILL.md

@@ -14,27 +14,31 @@ Use this skill to run `gsd-*` prompts under `Codex` while preserving upstream GS
 - Keep `.claude/agents/gsd-*.md` as role contracts for subagents.
 - Keep `.codex/prompts/gsd-*.md` as Codex-native orchestrators.
 
-## Core rules
-1. Do not change command semantics.
-2. Do not change source workflow logic unless necessary for Codex command compatibility.
-3. Use workspace-relative paths.
-4. Preserve step ordering and gate behavior from workflow files.
-5. User-facing guidance should recommend `gsd-*` prompts (Codex) and `/gsd:*` commands (Claude), not internal `node ... gsd-tools ...` plumbing.
+## Core rules
+1. Do not change command semantics.
+2. Do not change source workflow logic unless necessary for Codex command compatibility.
+3. Use workspace-relative paths.
+4. Preserve step ordering and gate behavior from workflow files.
+5. User-facing guidance should recommend `/prompts:gsd-*` prompts (Codex) and `/gsd:*` commands (Claude), not internal `node ... gsd-tools ...` plumbing.
 
-## Mandatory codex translations
-- Replace each `Task(...)` with: `spawn_agent` + `wait`.
-- Replace Bash/JQ patterns with PowerShell and `ConvertFrom-Json`.
-- Replace AskUserQuestion interactions with direct user prompts in chat.
+## Mandatory codex translations
+- Replace each `Task(...)` with: `spawn_agent` + `wait`.
+- Replace Bash/JQ patterns with PowerShell and `ConvertFrom-Json`.
+- Replace AskUserQuestion interactions with direct user prompts in chat.
+- Translate resolved model aliases before Codex subagent spawn:
+  - `inherit` (opus tier) -> `gpt-5.3-codex` (`xhigh`)
+  - `sonnet` -> `gpt-5.3-spark` (`xhigh`)
+  - `haiku` -> `gpt-5.1-codex-mini` (`high`)
 
-## Subagent lifecycle (required)
-- Spawn only when the upstream workflow explicitly defines a `Task(...)` role.
-- For each spawned subagent:
-  - Start with `spawn_agent` and provide the role source from `.claude/agents/gsd-*.md`.
-  - Do not set `agent_type` to a GSD role. Codex only accepts `default`, `explorer`, or `worker` (or omit `agent_type`).
-  - Wait for completion before proceeding: `wait`.
-  - Explicitly close the agent after it finishes (`close_agent`) to release resources.
-- Keep prompt-level sequencing intact; do not continue to subsequent steps until waiting + closure are complete.
-- If an agent fails or exceeds retry policy, stop that phase of workflow and surface a clear remediation step.
+## Subagent lifecycle (required)
+- Spawn only when the upstream workflow explicitly defines a `Task(...)` role.
+- For each spawned subagent:
+  - Start with `spawn_agent` and provide the role source from `.claude/agents/gsd-*.md`.
+  - Do not set `agent_type` to a GSD role. Codex only accepts `default`, `explorer`, or `worker` (or omit `agent_type`).
+  - Wait for completion before proceeding: `wait`.
+  - Explicitly close the agent after it finishes (`close_agent`) to release resources.
+- Keep prompt-level sequencing intact; do not continue to subsequent steps until waiting + closure are complete.
+- If an agent fails or exceeds retry policy, stop that phase of workflow and surface a clear remediation step.
 
 ## Required GSD roles (must map by name)
 - `gsd-project-researcher`

package/.codex/skills/get-shit-done-codex/references/compat.md

@@ -20,6 +20,10 @@
 - `subagent_type=gsd-*` maps to equivalent role contract in `.claude/agents/gsd-*.md`.
 - Unspecified `subagent_type` values default to command-context Codex agent behavior.
 - Do not pass `agent_type=gsd-*` to `spawn_agent`. Codex only accepts `default`, `explorer`, or `worker` (or omit `agent_type`).
+- Translate GSD model aliases to Codex models when spawning:
+  - `inherit` (opus tier) -> `gpt-5.3-codex` with `xhigh` reasoning effort
+  - `sonnet` -> `gpt-5.3-spark` with `xhigh` reasoning effort
+  - `haiku` -> `gpt-5.1-codex-mini` with `high` reasoning effort
 
 ## Required GSD subagents
 - `gsd-project-researcher`

package/README.md

@@ -4,11 +4,11 @@ This repository packages the get-shit-done (GSD) workflow for Codex. It installs
 
 Use this fork if you want the GSD workflow inside Codex with a simple installer that works for a single project or your home directory.
 
-## Quick Install
-
-```bash
-npx gsd-codex-cli@latest --path .
-```
+## Quick Install
+
+```bash
+npx gsd-codex-cli@latest --path .
+```
 
 Install globally (prompts available from any project):
 
@@ -34,11 +34,11 @@ This fork is Codex-first, but the Claude assets are kept alongside for compatibi
 
 ## Using the Prompts
 
-Open your project in Codex and run these prompts from the prompt list:
+Open your project in Codex and run these prompt commands:
 
-- `gsd-new-project`
-- `gsd-plan-phase`
-- `gsd-execute-phase`
+- `/prompts:gsd-new-project`
+- `/prompts:gsd-plan-phase`
+- `/prompts:gsd-execute-phase`
 
 All Codex prompts live in `.codex/prompts`.
 
@@ -50,13 +50,21 @@ Re-run the installer to update your local or global install. It overwrites the e
 npx gsd-codex-cli@latest --path . --global
 ```
 
-## CLI Options
-
-```
---path <dir>   Install into a specific directory (defaults to current directory)
---global       Also install to your home directory (~/.codex and ~/.claude)
---help         Show help
-```
+## CLI Options
+
+```
+--path <target-dir>   Install into this directory (defaults to current directory)
+--global              Also install to your home directory
+--help                Show help
+```
+
+## Examples
+
+```bash
+npx gsd-codex-cli@latest --path .
+npx gsd-codex-cli@latest --global
+npx gsd-codex-cli@latest --path . --global
+```
 
 ## Development
 

package/bin/install-codex.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
 
 const args = process.argv.slice(2);
 const pkg = require('../package.json');
@@ -12,17 +12,17 @@ const helpText = `
 ${pkg.name} v${pkg.version}
 
 Usage:
-  ${pkg.name} [--path <target-dir>] [--help]
-
-Options:
-  --path <target-dir>   Install into this directory (defaults to current directory)
-  --global              Also install .claude to your home directory (for manual sharing)
-  --help, -h            Show this help message
+  ${pkg.name} [--path <target-dir>] [--global] [--help]
+
+Options:
+  --path <target-dir>   Install into this directory (defaults to current directory)
+  --global              Also install .claude to your home directory (for manual sharing)
+  --help, -h            Show this help message
 
-Examples:
-  npx gsd-codex-cli@latest --path .
-  npx gsd-codex-cli@latest --path ./my-project
-`;
+Examples:
+  npx gsd-codex-cli@latest --path .
+  npx gsd-codex-cli@latest --path ./my-project
+`;
 
 if (args.includes('--help') || args.includes('-h')) {
   console.log(helpText);
@@ -43,16 +43,16 @@ if (pathArgIndex !== -1) {
   targetDir = path.resolve(process.cwd(), userPath);
 }
 
-const installGlobal = args.includes('--global');
+const installGlobal = args.includes('--global');
 
 function copyRecursive(source, destination) {
   if (!fs.existsSync(source)) return;
   fs.cpSync(source, destination, { recursive: true, force: true });
 }
 
-function ensureDir(dirPath) {
-  fs.mkdirSync(dirPath, { recursive: true });
-}
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
 
 function resolveSourceDir(repoRelative, fallbackRelative) {
   const primary = path.join(repoRoot, repoRelative);
@@ -65,43 +65,50 @@ function resolveSourceDir(repoRelative, fallbackRelative) {
   throw new Error(`Missing source directory "${repoRelative}"${fallbackMessage} in repository root ${repoRoot}`);
 }
 
-function copyCodexToDirectory(baseDir) {
-  const targetCodex = path.join(baseDir, '.codex');
-  const targetClaude = path.join(baseDir, '.claude');
-  const sourceCodex = path.join(repoRoot, '.codex');
-  const sourceGetShitDone = resolveSourceDir('get-shit-done', '.claude/get-shit-done');
-  const sourceAgents = resolveSourceDir('agents', '.claude/agents');
-  const versionDest = path.join(targetClaude, 'get-shit-done', 'VERSION');
-  const codexVersionDest = path.join(targetCodex, 'gsd', 'VERSION');
+function copyCodexToDirectory(baseDir) {
+  const targetCodex = path.join(baseDir, '.codex');
+  const targetClaude = path.join(baseDir, '.claude');
+  const sourceCodex = path.join(repoRoot, '.codex');
+  const sourceGetShitDone = resolveSourceDir('get-shit-done', '.claude/get-shit-done');
+  const sourceAgents = resolveSourceDir('agents', '.claude/agents');
+  const versionDest = path.join(targetClaude, 'get-shit-done', 'VERSION');
+  const codexVersionDest = path.join(targetCodex, 'gsd', 'VERSION');
+
+  ensureDir(baseDir);
+  ensureDir(targetCodex);
+  ensureDir(targetClaude);
+
+  copyRecursive(sourceCodex, targetCodex);
+  copyRecursive(sourceGetShitDone, path.join(targetClaude, 'get-shit-done'));
+  copyRecursive(sourceAgents, path.join(targetClaude, 'agents'));
+  ensureDir(path.dirname(versionDest));
+  fs.writeFileSync(versionDest, `${pkg.version}\n`);
+  ensureDir(path.dirname(codexVersionDest));
+  fs.writeFileSync(codexVersionDest, `${pkg.version}\n`);
+}
+
+async function main() {
+  copyCodexToDirectory(targetDir);
 
-  ensureDir(baseDir);
-  ensureDir(targetCodex);
-  ensureDir(targetClaude);
+  if (installGlobal) {
+    // Global installs should place prompts at ~/.codex/prompts (not ~/.codex/.codex/prompts).
+    const globalBase = os.homedir();
+    copyCodexToDirectory(globalBase);
+  }
 
-  copyRecursive(sourceCodex, targetCodex);
-  copyRecursive(sourceGetShitDone, path.join(targetClaude, 'get-shit-done'));
-  copyRecursive(sourceAgents, path.join(targetClaude, 'agents'));
-  ensureDir(path.dirname(versionDest));
-  fs.writeFileSync(versionDest, `${pkg.version}\n`);
-  ensureDir(path.dirname(codexVersionDest));
-  fs.writeFileSync(codexVersionDest, `${pkg.version}\n`);
+  console.log(`\n${pkg.name}@${pkg.version} installed to:`);
+  console.log(`  local: ${targetDir}`);
+  if (installGlobal) {
+    console.log('  global: ~/.codex');
+  }
+  console.log('\nNext steps:');
+  console.log('  1) Open your project in Codex');
+  console.log('  2) Run /prompts:gsd-new-project, then /prompts:gsd-discuss-phase, /prompts:gsd-plan-phase, /prompts:gsd-execute-phase');
+  console.log('  3) If something looks off, run /prompts:gsd-doctor');
+  console.log('  4) Use .codex/prompts/* for all GSD commands in this fork');
 }
-
-copyCodexToDirectory(targetDir);
-
-if (installGlobal) {
-  // Global installs should place prompts at ~/.codex/prompts (not ~/.codex/.codex/prompts).
-  const globalBase = os.homedir();
-  copyCodexToDirectory(globalBase);
-}
-
-console.log(`\n${pkg.name}@${pkg.version} installed to:`);
-console.log(`  local: ${targetDir}`);
-if (installGlobal) {
-  console.log('  global: ~/.codex');
-}
-console.log('\nNext steps:');
-console.log('  1) Open your project in Codex');
-console.log('  2) Run prompt gsd-new-project, then gsd-discuss-phase, gsd-plan-phase, gsd-execute-phase');
-console.log('  3) If something looks off, run prompt gsd-doctor');
-console.log('  4) Use .codex/prompts/* for all GSD commands in this fork');
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+});

package/commands/gsd/new-milestone.md

@@ -1,6 +1,6 @@
 ---
 name: gsd:new-milestone
-description: Start a new milestone cycle — update PROJECT.md and route to requirements
+description: Start a new milestone cycle end-to-end (questioning -> requirements -> roadmap)
 argument-hint: "[milestone name, e.g., 'v1.1 Notifications']"
 allowed-tools:
   - Read
@@ -48,4 +48,7 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
 <process>
 Execute the new-milestone workflow from @~/.claude/get-shit-done/workflows/new-milestone.md end-to-end.
 Preserve all workflow gates (validation, questioning, research, requirements, roadmap approval, commits).
+Hard gates:
+- If `.planning/MILESTONE-CONTEXT.md` is missing, present milestone direction options and capture user confirmation before defining requirements.
+- Do not finish successfully unless `.planning/ROADMAP.md` exists (or explicit blocked reason is reported).
 </process>

package/get-shit-done/bin/gsd-tools.cjs

@@ -129,29 +129,55 @@ const { execSync } = require('child_process');
 
 // ─── Model Profile Table ─────────────────────────────────────────────────────
 
-const MODEL_PROFILES = {
-  'gsd-planner':              { quality: 'opus', balanced: 'opus',   budget: 'sonnet' },
-  'gsd-roadmapper':           { quality: 'opus', balanced: 'sonnet', budget: 'sonnet' },
-  'gsd-executor':             { quality: 'opus', balanced: 'sonnet', budget: 'sonnet' },
+const MODEL_PROFILES = {
+  'gsd-planner':              { quality: 'opus', balanced: 'opus',   budget: 'sonnet' },
+  'gsd-roadmapper':           { quality: 'opus', balanced: 'sonnet', budget: 'sonnet' },
+  'gsd-executor':             { quality: 'opus', balanced: 'sonnet', budget: 'sonnet' },
   'gsd-phase-researcher':     { quality: 'opus', balanced: 'sonnet', budget: 'haiku' },
   'gsd-project-researcher':   { quality: 'opus', balanced: 'sonnet', budget: 'haiku' },
   'gsd-research-synthesizer': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
   'gsd-debugger':             { quality: 'opus', balanced: 'sonnet', budget: 'sonnet' },
   'gsd-codebase-mapper':      { quality: 'sonnet', balanced: 'haiku', budget: 'haiku' },
   'gsd-verifier':             { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
-  'gsd-plan-checker':         { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
-  'gsd-integration-checker':  { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
-};
+  'gsd-plan-checker':         { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+  'gsd-integration-checker':  { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+};
+
+const CODEX_MODEL_MAP = {
+  // Opus-tier aliases resolve to `inherit` in GSD, then map to Codex 5.3 at xhigh effort.
+  inherit: { model: 'gpt-5.3-codex', reasoning_effort: 'xhigh' },
+  // Sonnet-tier aliases map to Spark 5.3 at xhigh effort.
+  sonnet: { model: 'gpt-5.3-spark', reasoning_effort: 'xhigh' },
+  // Haiku-tier aliases map to codex-mini at high effort.
+  haiku: { model: 'gpt-5.1-codex-mini', reasoning_effort: 'high' },
+};
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
-function parseIncludeFlag(args) {
+function parseIncludeFlag(args) {
   const includeIndex = args.indexOf('--include');
   if (includeIndex === -1) return new Set();
   const includeValue = args[includeIndex + 1];
   if (!includeValue) return new Set();
   return new Set(includeValue.split(',').map(s => s.trim()));
-}
+}
+
+function codexModelSpecFromAlias(alias) {
+  if (!alias) return null;
+  const normalized = String(alias).toLowerCase() === 'opus' ? 'inherit' : String(alias).toLowerCase();
+  return CODEX_MODEL_MAP[normalized] || null;
+}
+
+function withCodexModelHints(result) {
+  for (const [key, value] of Object.entries(result)) {
+    if (!key.endsWith('_model') || typeof value !== 'string') continue;
+    const spec = codexModelSpecFromAlias(value);
+    if (!spec) continue;
+    result[`${key}_codex`] = spec.model;
+    result[`${key}_reasoning_effort`] = spec.reasoning_effort;
+  }
+  return result;
+}
 
 function safeReadFile(filePath) {
   try {
@@ -1472,7 +1498,7 @@ function cmdStateRecordSession(cwd, options, raw) {
   }
 }
 
-function cmdResolveModel(cwd, agentType, raw) {
+function cmdResolveModel(cwd, agentType, raw) {
   if (!agentType) {
     error('agent-type required');
   }
@@ -1480,18 +1506,31 @@ function cmdResolveModel(cwd, agentType, raw) {
   const config = loadConfig(cwd);
   const profile = config.model_profile || 'balanced';
 
-  const agentModels = MODEL_PROFILES[agentType];
-  if (!agentModels) {
-    const result = { model: 'sonnet', profile, unknown_agent: true };
-    output(result, raw, 'sonnet');
-    return;
-  }
-
-  const resolved = agentModels[profile] || agentModels['balanced'] || 'sonnet';
-  const model = resolved === 'opus' ? 'inherit' : resolved;
-  const result = { model, profile };
-  output(result, raw, model);
-}
+  const agentModels = MODEL_PROFILES[agentType];
+  if (!agentModels) {
+    const codexSpec = codexModelSpecFromAlias('sonnet');
+    const result = {
+      model: 'sonnet',
+      profile,
+      unknown_agent: true,
+      codex_model: codexSpec?.model || null,
+      codex_reasoning_effort: codexSpec?.reasoning_effort || null,
+    };
+    output(result, raw, 'sonnet');
+    return;
+  }
+
+  const resolved = agentModels[profile] || agentModels['balanced'] || 'sonnet';
+  const model = resolved === 'opus' ? 'inherit' : resolved;
+  const codexSpec = codexModelSpecFromAlias(model);
+  const result = {
+    model,
+    profile,
+    codex_model: codexSpec?.model || null,
+    codex_reasoning_effort: codexSpec?.reasoning_effort || null,
+  };
+  output(result, raw, model);
+}
 
 function cmdFindPhase(cwd, phase, raw) {
   if (!phase) {
@@ -1998,8 +2037,9 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
     has_checkpoints: hasCheckpoints,
   };
 
-  output(result, raw);
-}
+  withCodexModelHints(result);
+  output(result, raw);
+}
 
 function cmdStateSnapshot(cwd, raw) {
   const statePath = path.join(cwd, '.planning', 'STATE.md');
@@ -2099,8 +2139,9 @@ function cmdStateSnapshot(cwd, raw) {
     session,
   };
 
-  output(result, raw);
-}
+  withCodexModelHints(result);
+  output(result, raw);
+}
 
 function cmdSummaryExtract(cwd, summaryPath, fields, raw) {
   if (!summaryPath) {
@@ -2703,8 +2744,9 @@ function cmdRoadmapAnalyze(cwd, raw) {
     missing_phase_details: missingDetails.length > 0 ? missingDetails : null,
   };
 
-  output(result, raw);
-}
+  withCodexModelHints(result);
+  output(result, raw);
+}
 
 // ─── Phase Add ────────────────────────────────────────────────────────────────
 
@@ -3118,8 +3160,9 @@ function cmdPhaseRemove(cwd, targetPhase, options, raw) {
     state_updated: fs.existsSync(statePath),
   };
 
-  output(result, raw);
-}
+  withCodexModelHints(result);
+  output(result, raw);
+}
 
 // ─── Roadmap Update Plan Progress ────────────────────────────────────────────
 
@@ -3365,8 +3408,9 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
     state_updated: fs.existsSync(statePath),
   };
 
-  output(result, raw);
-}
+  withCodexModelHints(result);
+  output(result, raw);
+}
 
 // ─── Milestone Complete ───────────────────────────────────────────────────────
 
@@ -3502,8 +3546,9 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     state_updated: fs.existsSync(statePath),
   };
 
-  output(result, raw);
-}
+  withCodexModelHints(result);
+  output(result, raw);
+}
 
 // ─── Validate Consistency ─────────────────────────────────────────────────────
 
@@ -4299,8 +4344,9 @@ function cmdInitExecutePhase(cwd, phase, includes, raw) {
     result.roadmap_content = safeReadFile(path.join(cwd, '.planning', 'ROADMAP.md'));
   }
 
-  output(result, raw);
-}
+  withCodexModelHints(result);
+  output(result, raw);
+}
 
 function cmdInitPlanPhase(cwd, phase, includes, raw) {
   if (!phase) {
@@ -4395,10 +4441,11 @@ function cmdInitPlanPhase(cwd, phase, includes, raw) {
     } catch {}
   }
 
-  output(result, raw);
-}
+  withCodexModelHints(result);
+  output(result, raw);
+}
 
-function cmdInitNewProject(cwd, raw) {
+function cmdInitNewProject(cwd, raw) {
   const config = loadConfig(cwd);
 
   // Detect Brave Search API key availability
@@ -4451,10 +4498,11 @@ function cmdInitNewProject(cwd, raw) {
     brave_search_available: hasBraveSearch,
   };
 
-  output(result, raw);
-}
+  withCodexModelHints(result);
+  output(result, raw);
+}
 
-function cmdInitNewMilestone(cwd, raw) {
+function cmdInitNewMilestone(cwd, raw) {
   const config = loadConfig(cwd);
   const milestone = getMilestoneInfo(cwd);
 
@@ -4478,10 +4526,11 @@ function cmdInitNewMilestone(cwd, raw) {
     state_exists: pathExistsInternal(cwd, '.planning/STATE.md'),
   };
 
-  output(result, raw);
-}
+  withCodexModelHints(result);
+  output(result, raw);
+}
 
-function cmdInitQuick(cwd, description, raw) {
+function cmdInitQuick(cwd, description, raw) {
   const config = loadConfig(cwd);
   const now = new Date();
   const slug = description ? generateSlugInternal(description)?.substring(0, 40) : null;
@@ -4527,8 +4576,9 @@ function cmdInitQuick(cwd, description, raw) {
     planning_exists: pathExistsInternal(cwd, '.planning'),
   };
 
-  output(result, raw);
-}
+  withCodexModelHints(result);
+  output(result, raw);
+}
 
 function cmdInitResume(cwd, raw) {
   const config = loadConfig(cwd);
@@ -4557,7 +4607,7 @@ function cmdInitResume(cwd, raw) {
   output(result, raw);
 }
 
-function cmdInitVerifyWork(cwd, phase, raw) {
+function cmdInitVerifyWork(cwd, phase, raw) {
   if (!phase) {
     error('phase required for init verify-work');
   }
@@ -4583,8 +4633,9 @@ function cmdInitVerifyWork(cwd, phase, raw) {
     has_verification: phaseInfo?.has_verification || false,
   };
 
-  output(result, raw);
-}
+  withCodexModelHints(result);
+  output(result, raw);
+}
 
 function cmdInitPhaseOp(cwd, phase, raw) {
   const config = loadConfig(cwd);
@@ -4759,7 +4810,7 @@ function cmdInitMilestoneOp(cwd, raw) {
   output(result, raw);
 }
 
-function cmdInitMapCodebase(cwd, raw) {
+function cmdInitMapCodebase(cwd, raw) {
   const config = loadConfig(cwd);
 
   // Check for existing codebase maps
@@ -4790,10 +4841,11 @@ function cmdInitMapCodebase(cwd, raw) {
     codebase_dir_exists: pathExistsInternal(cwd, '.planning/codebase'),
   };
 
-  output(result, raw);
-}
+  withCodexModelHints(result);
+  output(result, raw);
+}
 
-function cmdInitProgress(cwd, includes, raw) {
+function cmdInitProgress(cwd, includes, raw) {
   const config = loadConfig(cwd);
   const milestone = getMilestoneInfo(cwd);
 
@@ -4897,8 +4949,9 @@ function cmdInitProgress(cwd, includes, raw) {
     result.config_content = safeReadFile(path.join(cwd, '.planning', 'config.json'));
   }
 
-  output(result, raw);
-}
+  withCodexModelHints(result);
+  output(result, raw);
+}
 
 // ─── CLI Router ───────────────────────────────────────────────────────────────
 

package/get-shit-done/references/model-profile-resolution.md

@@ -24,11 +24,22 @@ Task(
 )
 ```
 
-**Note:** Opus-tier agents resolve to `"inherit"` (not `"opus"`). This causes the agent to use the parent session's model, avoiding conflicts with organization policies that may block specific opus versions.
+**Note:** Opus-tier agents resolve to `"inherit"` (not `"opus"`). This causes the agent to use the parent session's model, avoiding conflicts with organization policies that may block specific opus versions.
+
+## Codex alias mapping
+
+When running under Codex, map the resolved aliases to concrete Codex models:
+
+| Alias | Codex model | Reasoning effort |
+|-------|-------------|------------------|
+| `inherit` (`opus` tier) | `gpt-5.3-codex` | `xhigh` |
+| `sonnet` | `gpt-5.3-spark` | `xhigh` |
+| `haiku` | `gpt-5.1-codex-mini` | `high` |
 
 ## Usage
 
 1. Resolve once at orchestration start
 2. Store the profile value
 3. Look up each agent's model from the table when spawning
-4. Pass model parameter to each Task call (values: `"inherit"`, `"sonnet"`, `"haiku"`)
+4. Pass model parameter to each Task call (values: `"inherit"`, `"sonnet"`, `"haiku"`)
+5. In Codex mode, translate those aliases with the table above before spawning subagents

package/get-shit-done/workflows/new-milestone.md

@@ -26,9 +26,15 @@ Read all files referenced by the invoking prompt's execution_context before star
 - Present summary for confirmation
 
 **If no context file:**
-- Present what shipped in last milestone
-- Ask: "What do you want to build next?"
-- Use AskUserQuestion to explore features, priorities, constraints, scope
+- Present what shipped in last milestone plus pending todos/blockers.
+- Run an explicit AskUserQuestion with milestone direction options before drafting scope:
+  - "Ship features (Recommended)" — Build the next user-facing capability set
+  - "Stabilize quality" — Focus on bug fixes, reliability, and hardening
+  - "Platform + ops" — Improve architecture, performance, tooling, and observability
+  - "Custom scope" — User provides bespoke milestone goals
+- If "Custom scope", ask one focused follow-up question and capture the goals verbatim.
+- Summarize the selected direction as draft milestone goals and ask for confirm/adjust.
+- Hard gate: do not continue to Step 3 until user confirms goals.
 
 ## 3. Determine Milestone Version
 
@@ -319,6 +325,9 @@ Success criteria:
 **If "Adjust":** Get notes, re-spawn roadmapper with revision context, loop until approved.
 **If "Review":** Display raw ROADMAP.md, re-ask.
 
+**Hard gate before completion:** verify `.planning/ROADMAP.md` exists on disk.
+- If missing, treat as `## ROADMAP BLOCKED` (agent returned success without writing file), explain the issue, and re-spawn roadmapper with explicit instruction to write `.planning/ROADMAP.md`, `.planning/STATE.md`, and REQUIREMENTS traceability updates before returning.
+
 **Commit roadmap** (after approval):
 ```bash
 node ~/.claude/get-shit-done/bin/gsd-tools.cjs commit "docs: create milestone v[X.Y] roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
@@ -364,6 +373,7 @@ Also: `/gsd:plan-phase [N]` — skip discussion, plan directly
 - [ ] REQUIREMENTS.md created with REQ-IDs
 - [ ] gsd-roadmapper spawned with phase numbering context
 - [ ] Roadmap files written immediately (not draft)
+- [ ] `.planning/ROADMAP.md` exists on disk before Done
 - [ ] User feedback incorporated (if any)
 - [ ] ROADMAP.md phases continue from previous milestone
 - [ ] All commits made (if planning docs committed)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd-codex-cli",
-  "version": "1.20.10",
+  "version": "1.20.12",
   "description": "Codex-native package for the get-shit-done workflow with native subagent orchestration.",
   "bin": {
     "gsd-codex-cli": "bin/install-codex.js",