@undeemed/get-shit-done-codex 1.22.0 → 1.23.0

package/.codex/config.toml

@@ -1,4 +1,4 @@
-:schema https://developers.openai.com/codex/config-schema.json
+#:schema https://developers.openai.com/codex/config-schema.json
 
 # Project-scoped Codex config for get-shit-done-codex.
 # Loaded only when this project is trusted.

package/README.md

@@ -5,8 +5,9 @@ A meta-prompting, context engineering and spec-driven development system for [Op
 Fork of [get-shit-done](https://github.com/taches/get-shit-done) by TÂCHES, adapted for Codex CLI by [undeemed](https://github.com/undeemed).
 
 > [!CAUTION]
-> As of February 25, 2026, Codex is supported upstream. This fork remains focused on Codex-specific UX and compatibility with extra goodies.
+> Codex is now supported upstream. This fork remains focused on Codex-specific UX, compatibility, and cutting-edge experimental features.
 
+[![CI](https://github.com/undeemed/get-shit-done-codex/actions/workflows/ci.yml/badge.svg)](https://github.com/undeemed/get-shit-done-codex/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/%40undeemed%2Fget-shit-done-codex?style=flat-square)](https://www.npmjs.com/package/@undeemed/get-shit-done-codex)
 [![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)
 ![npm Downloads](https://img.shields.io/npm/dt/@undeemed/get-shit-done-codex?style=flat-square)
@@ -46,6 +47,7 @@ npx @undeemed/get-shit-done-codex --global
 ```bash
 npx @undeemed/get-shit-done-codex --global   # Install to ~/.codex/
 npx @undeemed/get-shit-done-codex --local    # Install to current directory
+npx @undeemed/get-shit-done-codex --path .   # Install to a specific directory
 npx @undeemed/get-shit-done-codex --global --migrate             # Clean up legacy prompts/
 npx @undeemed/get-shit-done-codex --verify --global              # Check install integrity
 npx @undeemed/get-shit-done-codex --verify --repair --global     # Auto-repair

package/agents/gsd-debugger.md

@@ -812,7 +812,7 @@ gathering -> investigating -> fixing -> verifying -> awaiting_human_verify -> re
 
 ## Resume Behavior
 
-When reading debug file after /clear:
+When reading debug file after session reset:
 1. Parse frontmatter -> know status
 2. Read Current Focus -> know exactly what was happening
 3. Read Eliminated -> know what NOT to retry
@@ -897,7 +897,7 @@ Gather symptoms through questioning. Update file after EACH answer.
   - Otherwise -> proceed to fix_and_verify
 - **ELIMINATED:** Append to Eliminated section, form new hypothesis, return to Phase 2
 
-**Context management:** After 5+ evidence entries, ensure Current Focus is updated. Suggest "/clear - run $gsd-debug to resume" if context filling up.
+**Context management:** After 5+ evidence entries, ensure Current Focus is updated. Suggest "start a new session — run $gsd-debug to resume" if context filling up.
 </step>
 
 <step name="resume_from_file">
@@ -1239,7 +1239,7 @@ Check for mode flags in prompt context:
 - [ ] Current Focus always reflects NOW
 - [ ] Evidence appended for every finding
 - [ ] Eliminated prevents re-investigation
-- [ ] Can resume perfectly from any /clear
+- [ ] Can resume perfectly from any session reset
 - [ ] Root cause confirmed with evidence before fixing
 - [ ] Fix verified against original symptoms
 - [ ] Appropriate return format based on mode

package/agents/gsd-planner.md

@@ -1211,7 +1211,7 @@ Return structured planning outcome to orchestrator.
 
 Execute: `$gsd-execute-phase {phase}`
 
-<sub>`/clear` first - fresh context window</sub>
+<sub>start a new session first — fresh context window</sub>
 ```
 
 ## Gap Closure Plans Created

package/bin/install.js

@@ -41,6 +41,8 @@ const hasRepair = args.includes('--repair');
 const hasNoVersionCheck = args.includes('--no-version-check') || process.env.GSD_SKIP_VERSION_CHECK === '1';
 const hasMigrate = args.includes('--migrate');
 const hasSkipMigrate = args.includes('--skip-migrate') || args.includes('--no-migrate');
+const pathIdx = args.indexOf('--path');
+const customPath = pathIdx !== -1 && args[pathIdx + 1] ? args[pathIdx + 1] : null;
 const isInteractiveTerminal = Boolean(process.stdin.isTTY && process.stdout.isTTY);
 const codexMode = 'skills';
 
@@ -52,6 +54,7 @@ if (hasHelp) {
   ${yellow}Options:${reset}
     ${cyan}-g, --global${reset}              Install globally (to ~/.codex/)
     ${cyan}-l, --local${reset}               Install locally (to current directory)
+    ${cyan}--path <dir>${reset}              Install into a specific directory
     ${cyan}--migrate${reset}                 Apply detected legacy surface cleanup without prompting
     ${cyan}--skip-migrate${reset}            Keep legacy surface files when migration is detected
     ${cyan}--verify${reset}                  Verify current install integrity
@@ -66,6 +69,9 @@ if (hasHelp) {
     ${dim}# Install to current project only${reset}
     npx ${NPM_PACKAGE} --local
 
+    ${dim}# Install to a specific directory${reset}
+    npx ${NPM_PACKAGE} --path /path/to/project
+
     ${dim}# Verify global installation${reset}
     npx ${NPM_PACKAGE} --verify --global
 
@@ -357,13 +363,24 @@ function showCachedVersionWarning() {
   }
 }
 
-function getInstallContext(isGlobal) {
-  const codexDir = isGlobal ? path.join(os.homedir(), '.codex') : process.cwd();
-  return {
-    codexDir,
-    locationLabel: isGlobal ? '~/.codex' : '.',
-    pathPrefix: isGlobal ? '~/.codex/' : './',
-  };
+function getInstallContext(isGlobal, targetPath) {
+  let codexDir;
+  let locationLabel;
+  let pathPrefix;
+  if (targetPath) {
+    codexDir = path.resolve(targetPath);
+    locationLabel = targetPath;
+    pathPrefix = codexDir.endsWith(path.sep) ? codexDir : `${codexDir}${path.sep}`;
+  } else if (isGlobal) {
+    codexDir = path.join(os.homedir(), '.codex');
+    locationLabel = '~/.codex';
+    pathPrefix = '~/.codex/';
+  } else {
+    codexDir = process.cwd();
+    locationLabel = '.';
+    pathPrefix = './';
+  }
+  return { codexDir, locationLabel, pathPrefix };
 }
 
 function listPromptCommandFiles(promptsDir) {
@@ -388,9 +405,9 @@ function detectInstalledMode(promptCount, skillCount) {
   return 'none';
 }
 
-function verifyInstall(isGlobal) {
+function verifyInstall(isGlobal, targetPath) {
   const src = path.join(__dirname, '..');
-  const { codexDir, locationLabel } = getInstallContext(isGlobal);
+  const { codexDir, locationLabel } = getInstallContext(isGlobal, targetPath);
   const promptsDir = path.join(codexDir, 'prompts');
   const skillsDir = path.join(codexDir, 'skills');
   const workflowRoot = path.join(codexDir, 'get-shit-done');
@@ -447,9 +464,9 @@ function verifyInstall(isGlobal) {
   return { ok, detectedMode };
 }
 
-function installCore(isGlobal, migrationPlan, applyMigration, done = () => {}) {
+function installCore(isGlobal, migrationPlan, applyMigration, done = () => {}, targetPath) {
   const src = path.join(__dirname, '..');
-  const { codexDir, locationLabel, pathPrefix } = getInstallContext(isGlobal);
+  const { codexDir, locationLabel, pathPrefix } = getInstallContext(isGlobal, targetPath);
 
   console.log(`  Installing to ${cyan}${locationLabel}${reset}\n`);
   fs.mkdirSync(codexDir, { recursive: true });
@@ -546,12 +563,12 @@ function installCore(isGlobal, migrationPlan, applyMigration, done = () => {}) {
   }
 }
 
-function install(isGlobal, done = () => {}) {
-  const { codexDir } = getInstallContext(isGlobal);
+function install(isGlobal, done = () => {}, targetPath) {
+  const { codexDir } = getInstallContext(isGlobal, targetPath);
   const migrationPlan = detectMigrationPlan(codexDir);
 
   if (!migrationPlan.hasChanges) {
-    installCore(isGlobal, migrationPlan, false, done);
+    installCore(isGlobal, migrationPlan, false, done, targetPath);
     return;
   }
 
@@ -560,13 +577,13 @@ function install(isGlobal, done = () => {}) {
 
   if (hasMigrate) {
     console.log(`  ${green}✓${reset} Migration approved by --migrate`);
-    installCore(isGlobal, migrationPlan, true, done);
+    installCore(isGlobal, migrationPlan, true, done, targetPath);
     return;
   }
 
   if (hasSkipMigrate) {
     console.log(`  ${yellow}Skipping migration due to --skip-migrate.${reset}`);
-    installCore(isGlobal, migrationPlan, false, done);
+    installCore(isGlobal, migrationPlan, false, done, targetPath);
     return;
   }
 
@@ -589,7 +606,7 @@ function install(isGlobal, done = () => {}) {
     if (!applyMigration) {
       console.log(`  ${yellow}Keeping legacy files.${reset}`);
     }
-    installCore(isGlobal, migrationPlan, applyMigration, done);
+    installCore(isGlobal, migrationPlan, applyMigration, done, targetPath);
   });
 }
 
@@ -614,8 +631,14 @@ function promptLocation(done) {
   });
 }
 
-if (hasGlobal && hasLocal) {
-  console.error(`  ${yellow}Cannot specify both --global and --local${reset}`);
+const locationFlagCount = [hasGlobal, hasLocal, !!customPath].filter(Boolean).length;
+if (locationFlagCount > 1) {
+  console.error(`  ${yellow}Cannot specify more than one of --global, --local, and --path${reset}`);
+  process.exit(1);
+}
+
+if (pathIdx !== -1 && !customPath) {
+  console.error(`  ${yellow}--path requires a directory argument${reset}`);
   process.exit(1);
 }
 
@@ -634,21 +657,23 @@ if (!hasNoVersionCheck && !hasVerify) {
 }
 
 if (hasVerify) {
-  const isGlobal = hasLocal ? false : true;
-  let result = verifyInstall(isGlobal);
+  const isGlobal = customPath ? false : (hasLocal ? false : true);
+  let result = verifyInstall(isGlobal, customPath);
 
   if (!result.ok && hasRepair) {
     console.log(`\n  ${yellow}Repairing install...${reset}\n`);
     install(isGlobal, () => {
       console.log('');
-      const repaired = verifyInstall(isGlobal);
+      const repaired = verifyInstall(isGlobal, customPath);
       process.exit(repaired.ok ? 0 : 1);
-    });
+    }, customPath);
   } else {
     process.exit(result.ok ? 0 : 1);
   }
 } else {
-  if (hasGlobal) {
+  if (customPath) {
+    install(false, () => {}, customPath);
+  } else if (hasGlobal) {
     install(true);
   } else if (hasLocal) {
     install(false);

package/get-shit-done/references/continuation-format.md

@@ -13,7 +13,7 @@ Standard format for presenting next steps after completing a command or workflow
 
 `{command to copy-paste}`
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 ---
 
@@ -29,7 +29,7 @@ Standard format for presenting next steps after completing a command or workflow
 1. **Always show what it is** — name + description, never just a command path
 2. **Pull context from source** — ROADMAP.md for phases, PLAN.md `<objective>` for plans
 3. **Command in inline code** — backticks, easy to copy-paste, renders as clickable link
-4. **`/clear` explanation** — always include, keeps it concise but explains why
+4. **New session reminder** — always include, keeps it concise but explains why
 5. **"Also available" not "Other options"** — sounds more app-like
 6. **Visual separators** — `---` above and below to make it stand out
 
@@ -46,7 +46,7 @@ Standard format for presenting next steps after completing a command or workflow
 
 `$gsd-execute-phase 2`
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 ---
 
@@ -71,7 +71,7 @@ Add note that this is the last plan and what comes after:
 
 `$gsd-execute-phase 2`
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 ---
 
@@ -93,7 +93,7 @@ Add note that this is the last plan and what comes after:
 
 `$gsd-plan-phase 2`
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 ---
 
@@ -122,7 +122,7 @@ Show completion status before next action:
 
 `$gsd-plan-phase 3`
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 ---
 
@@ -151,7 +151,7 @@ When there's no clear primary action:
 
 **To research unknowns:** `$gsd-research-phase 3`
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 ---
 ```
@@ -171,7 +171,7 @@ All 4 phases shipped
 
 `$gsd-new-milestone`
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 ---
 ```
@@ -182,6 +182,7 @@ All 4 phases shipped
 
 ```markdown
 ### Phase 2: Authentication
+
 **Goal**: JWT login flow with refresh tokens
 ```
 
@@ -191,6 +192,7 @@ Extract: `**Phase 2: Authentication** — JWT login flow with refresh tokens`
 
 ```markdown
 Plans:
+
 - [ ] 02-03: Add refresh token rotation
 ```
 
@@ -213,18 +215,18 @@ Extract: `**02-03: Refresh Token Rotation** — Add /api/auth/refresh with slidi
 ```
 ## To Continue
 
-Run `/clear`, then paste:
+Start a new session, then paste:
 $gsd-execute-phase 2
 ```
 
 User has no idea what 02-03 is about.
 
-### Don't: Missing /clear explanation
+### Don't: Missing session reset explanation
 
 ```
 `$gsd-plan-phase 3`
 
-Run /clear first.
+Start a new session first.
 ```
 
 Doesn't explain why. User might skip it.
@@ -241,9 +243,13 @@ Sounds like an afterthought. Use "Also available:" instead.
 ### Don't: Fenced code blocks for commands
 
 ```
+
 ```
+
 $gsd-plan-phase 3
+
 ```
+
 ```
 
 Fenced blocks inside templates create nesting ambiguity. Use inline backticks instead.

package/get-shit-done/references/ui-brand.md

@@ -110,7 +110,7 @@ Always at end of major completions.
 
 `{copy-paste command}`
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 ───────────────────────────────────────────────────────────────
 

package/get-shit-done/templates/DEBUG.md

@@ -32,7 +32,7 @@ reproduction: [how to trigger]
 started: [when it broke / always broken]
 
 ## Eliminated
-<!-- APPEND only - prevents re-investigating after /clear -->
+<!-- APPEND only - prevents re-investigating after a session reset -->
 
 - hypothesis: [theory that was wrong]
   evidence: [what disproved it]
@@ -68,7 +68,7 @@ files_changed: []
 **Current Focus:**
 - OVERWRITE entirely on each update
 - Always reflects what Codex is doing RIGHT NOW
-- If Codex reads this after /clear, it knows exactly where to resume
+- If Codex reads this after a session reset, it knows exactly where to resume
 - Fields: hypothesis, test, expecting, next_action
 
 **Symptoms:**
@@ -81,7 +81,7 @@ files_changed: []
 - APPEND only - never remove entries
 - Prevents re-investigating dead ends after context reset
 - Each entry: hypothesis, evidence that disproved it, timestamp
-- Critical for efficiency across /clear boundaries
+- Critical for efficiency across session boundaries
 
 **Evidence:**
 - APPEND only - never remove entries
@@ -140,7 +140,7 @@ files_changed: []
 
 <resume_behavior>
 
-When Codex reads this file after /clear:
+When Codex reads this file after a session reset:
 
 1. Parse frontmatter → know status
 2. Read Current Focus → know exactly what was happening

package/get-shit-done/templates/UAT.md

@@ -156,7 +156,7 @@ skipped: [N]
 - Commit file
 - Present summary with next steps
 
-**Resume after /clear:**
+**Resume after session reset:**
 1. Read frontmatter → know phase and status
 2. Read Current Test → know where we are
 3. Find first [pending] result → continue from there

package/get-shit-done/workflows/add-phase.md

@@ -88,7 +88,7 @@ Roadmap updated: .planning/ROADMAP.md
 
 `$gsd-plan-phase {N}`
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 ---
 

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

@@ -198,7 +198,7 @@ All requirements covered. Cross-phase integration verified. E2E flows complete.
 
 $gsd-complete-milestone {version}
 
-<sub>/clear first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 ───────────────────────────────────────────────────────────────
 
@@ -235,7 +235,7 @@ $gsd-complete-milestone {version}
 
 $gsd-plan-milestone-gaps
 
-<sub>/clear first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 ───────────────────────────────────────────────────────────────
 
@@ -277,7 +277,7 @@ $gsd-complete-milestone {version}
 
 $gsd-plan-milestone-gaps
 
-<sub>/clear first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 ───────────────────────────────────────────────────────────────
 </offer_next>

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

@@ -731,7 +731,7 @@ Tag: v[X.Y]
 
 `$gsd-new-milestone`
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 ---
 

package/get-shit-done/workflows/discuss-phase.md

@@ -399,7 +399,7 @@ Created: .planning/phases/${PADDED_PHASE}-${SLUG}/${PADDED_PHASE}-CONTEXT.md
 
 `$gsd-plan-phase ${PHASE}`
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 ---
 
@@ -505,7 +505,7 @@ Task(
   Auto-advance pipeline finished: discuss → plan → execute
 
   Next: $gsd-discuss-phase ${NEXT_PHASE} --auto
-  <sub>/clear first → fresh context window</sub>
+  <sub>start a new session first → fresh context window</sub>
   ```
 - **PLANNING COMPLETE** → Planning done, execution didn't complete:
   ```

package/get-shit-done/workflows/execute-phase.md

@@ -349,7 +349,7 @@ All automated checks passed. {N} items need human testing:
 
 `$gsd-plan-phase {X} --gaps`
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 Also: `cat {phase_dir}/{phase_num}-VERIFICATION.md` — full report
 Also: `$gsd-verify-work {X}` — manual testing first

package/get-shit-done/workflows/execute-plan.md

@@ -427,7 +427,7 @@ ls -1 .planning/phases/[current-phase-dir]/*-SUMMARY.md 2>/dev/null | wc -l
 | summaries = plans, current < highest phase | **B: Phase done** | Show completion, suggest `$gsd-plan-phase {Z+1}` + `$gsd-verify-work {Z}` + `$gsd-discuss-phase {Z+1}` |
 | summaries = plans, current = highest phase | **C: Milestone done** | Show banner, suggest `$gsd-complete-milestone` + `$gsd-verify-work` + `$gsd-add-phase` |
 
-All routes: `/clear` first for fresh context.
+All routes: start a new session first for fresh context.
 </step>
 
 </process>

package/get-shit-done/workflows/help.md

@@ -33,12 +33,14 @@ $gsd-new-project → $gsd-plan-phase → $gsd-execute-phase → repeat
 Initialize new project through unified flow.
 
 One command takes you from idea to ready-for-planning:
+
 - Deep questioning to understand what you're building
 - Optional domain research (spawns 4 parallel researcher agents)
 - Requirements definition with v1/v2/out-of-scope scoping
 - Roadmap creation with phase breakdown and success criteria
 
 Creates all `.planning/` artifacts:
+
 - `PROJECT.md` — vision and requirements
 - `config.json` — workflow mode (interactive/yolo)
 - `research/` — domain research (if selected)
@@ -119,6 +121,7 @@ Usage: `$gsd-execute-phase 5`
 Execute small, ad-hoc tasks with GSD guarantees but skip optional agents.
 
 Quick mode uses the same system with a shorter path:
+
 - Spawns planner + executor (skips researcher, checker, verifier)
 - Quick tasks live in `.planning/quick/` separate from planned phases
 - Updates STATE.md tracking (not ROADMAP.md)
@@ -226,7 +229,7 @@ Systematic debugging with persistent state across context resets.
 - Gathers symptoms through adaptive questioning
 - Creates `.planning/debug/[slug].md` to track investigation
 - Investigates using scientific method (evidence → hypothesis → test)
-- Survives `/clear` — run `$gsd-debug` with no args to resume
+- Survives session resets — run `$gsd-debug` with no args to resume
 - Archives resolved issues to `.planning/debug/resolved/`
 
 Usage: `$gsd-debug "login button doesn't work"`
@@ -406,19 +409,23 @@ Change anytime by editing `.planning/config.json`
 Configure how planning artifacts are managed in `.planning/config.json`:
 
 **`planning.commit_docs`** (default: `true`)
+
 - `true`: Planning artifacts committed to git (standard workflow)
 - `false`: Planning artifacts kept local-only, not committed
 
 When `commit_docs: false`:
+
 - Add `.planning/` to your `.gitignore`
 - Useful for OSS contributions, client projects, or keeping planning private
 - All planning files still work normally, just not tracked in git
 
 **`planning.search_gitignored`** (default: `false`)
+
 - `true`: Add `--no-ignore` to broad ripgrep searches
 - Only needed when `.planning/` is gitignored and you want project-wide searches to include it
 
 Example config:
+
 ```json
 {
   "planning": {
@@ -434,9 +441,9 @@ Example config:
 
 ```
 $gsd-new-project        # Unified flow: questioning → research → requirements → roadmap
-/clear
+# start a new session
 $gsd-plan-phase 1       # Create plans for first phase
-/clear
+# start a new session
 $gsd-execute-phase 1    # Execute all plans in phase
 ```
 
@@ -458,7 +465,7 @@ $gsd-execute-phase 5.1
 
 ```
 $gsd-complete-milestone 1.0.0
-/clear
+# start a new session
 $gsd-new-milestone  # Start next milestone (questioning → research → requirements → roadmap)
 ```
 
@@ -476,7 +483,7 @@ $gsd-check-todos api             # Filter by area
 ```
 $gsd-debug "form submission fails silently"  # Start debug session
 # ... investigation happens, context fills up ...
-/clear
+# start a new session
 $gsd-debug                                    # Resume from where you left off
 ```
 
@@ -486,4 +493,4 @@ $gsd-debug                                    # Resume from where you left off
 - Read `.planning/STATE.md` for current context
 - Check `.planning/ROADMAP.md` for phase status
 - Run `$gsd-progress` to check where you're up to
-</reference>
+  </reference>

package/get-shit-done/workflows/insert-phase.md

@@ -94,7 +94,7 @@ Project state updated: .planning/STATE.md
 
 `$gsd-plan-phase {decimal_phase}`
 
-<sub>`/clear` first -> fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 ---
 

package/get-shit-done/workflows/map-codebase.md

@@ -287,7 +287,7 @@ Created .planning/codebase/:
 
 `$gsd-new-project`
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 ---
 

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

@@ -357,7 +357,7 @@ node ~/.codex/get-shit-done/bin/gsd-tools.cjs commit "docs: create milestone v[X
 
 `$gsd-discuss-phase [N]` — gather context and clarify approach
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 Also: `$gsd-plan-phase [N]` — skip discussion, plan directly
 ```

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

@@ -1063,7 +1063,7 @@ Exit skill and invoke SlashCommand("$gsd-discuss-phase 1 --auto")
 
 $gsd-discuss-phase 1 — gather context and clarify approach
 
-<sub>/clear first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 ---
 

package/get-shit-done/workflows/plan-milestone-gaps.md

@@ -166,7 +166,7 @@ node ~/.codex/get-shit-done/bin/gsd-tools.cjs commit "docs(roadmap): add gap clo
 
 `$gsd-plan-phase {N}`
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 ---
 

package/get-shit-done/workflows/plan-phase.md

@@ -450,7 +450,7 @@ Verification: {Passed | Passed with override | Skipped}
 
 $gsd-execute-phase {X}
 
-<sub>/clear first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 ───────────────────────────────────────────────────────────────
 

package/get-shit-done/workflows/progress.md

@@ -181,7 +181,7 @@ Read its `<objective>` section.
 
 `$gsd-execute-phase {phase}`
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 ---
 ```
@@ -204,7 +204,7 @@ Check if `{phase_num}-CONTEXT.md` exists in phase directory.
 
 `$gsd-plan-phase {phase-number}`
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 ---
 ```
@@ -220,7 +220,7 @@ Check if `{phase_num}-CONTEXT.md` exists in phase directory.
 
 `$gsd-discuss-phase {phase}` — gather context and clarify approach
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 ---
 
@@ -246,7 +246,7 @@ UAT.md exists with gaps (diagnosed issues). User needs to plan fixes.
 
 `$gsd-plan-phase {phase} --gaps`
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 ---
 
@@ -293,7 +293,7 @@ Read ROADMAP.md to get the next phase's name and goal.
 
 `$gsd-discuss-phase {Z+1}` — gather context and clarify approach
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 ---
 
@@ -321,7 +321,7 @@ All {N} phases finished!
 
 `$gsd-complete-milestone`
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 ---
 
@@ -352,7 +352,7 @@ Ready to plan the next milestone.
 
 `$gsd-new-milestone`
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 ---
 ```

package/get-shit-done/workflows/resume-project.md

@@ -217,7 +217,7 @@ Based on user selection, route to appropriate workflow:
 
   `$gsd-execute-phase {phase}`
 
-  <sub>`/clear` first → fresh context window</sub>
+  <sub>start a new session first → fresh context window</sub>
 
   ---
   ```
@@ -231,7 +231,7 @@ Based on user selection, route to appropriate workflow:
 
   `$gsd-plan-phase [phase-number]`
 
-  <sub>`/clear` first → fresh context window</sub>
+  <sub>start a new session first → fresh context window</sub>
 
   ---
 

package/get-shit-done/workflows/settings.md

@@ -80,7 +80,7 @@ AskUserQuestion([
     header: "Auto",
     multiSelect: false,
     options: [
-      { label: "No (Recommended)", description: "Manual /clear + paste between stages" },
+      { label: "No (Recommended)", description: "Manual new session + paste between stages" },
       { label: "Yes", description: "Chain stages via Task() subagents (same isolation)" }
     ]
   },

package/get-shit-done/workflows/transition.md

@@ -409,7 +409,7 @@ Exit skill and invoke SlashCommand("$gsd-discuss-phase [X+1] --auto")
 
 `$gsd-discuss-phase [X+1]` — gather context and clarify approach
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 ---
 
@@ -434,7 +434,7 @@ Exit skill and invoke SlashCommand("$gsd-discuss-phase [X+1] --auto")
 
 `$gsd-plan-phase [X+1]`
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 ---
 
@@ -485,7 +485,7 @@ Exit skill and invoke SlashCommand("$gsd-complete-milestone {version}")
 
 `$gsd-complete-milestone {version}`
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>start a new session first → fresh context window</sub>
 
 ---
 

package/get-shit-done/workflows/verify-work.md

@@ -1,5 +1,5 @@
 <purpose>
-Validate built features through conversational testing with persistent state. Creates UAT.md that tracks test progress, survives /clear, and feeds gaps into $gsd-plan-phase --gaps.
+Validate built features through conversational testing with persistent state. Creates UAT.md that tracks test progress, survives session resets, and feeds gaps into $gsd-plan-phase --gaps.
 
 User tests, Codex records. One test at a time. Plain text responses.
 </purpose>
@@ -511,7 +511,7 @@ Plans verified and ready for execution.
 
 **Execute fixes** — run fix plans
 
-`/clear` then `$gsd-execute-phase {phase} --gaps-only`
+start a new session, then `$gsd-execute-phase {phase} --gaps-only`
 
 ───────────────────────────────────────────────────────────────
 ```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@undeemed/get-shit-done-codex",
-  "version": "1.22.0",
-  "description": "A meta-prompting, context engineering and spec-driven development system for OpenAI Codex (CLI and Desktop). Fork of get-shit-done by TÂCHES, adapted for Codex by undeemed.",
+  "version": "1.23.0",
+  "description": "A meta-prompting, context engineering and spec-driven development system for OpenAI Codex (CLI and Desktop). Fork of get-shit-done by TÂCHES, adapted for Codex.",
   "bin": {
     "get-shit-done-codex": "bin/install.js"
   },