fix: resolve installed gsd-tools in workflows (#354)

* fix: resolve installed gsd-tools in workflows * chore: add changeset
2026-05-26 18:56:21 -04:00
parent 47bba87d90
commit aaa19b0609
74 changed files with 450 additions and 143 deletions
--- a/.changeset/sturdy-lynx-march.md
+++ b/.changeset/sturdy-lynx-march.md
@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 354
+---
+Allow workflow runtime resolution to fall back to the installed gsd-tools binary when a project-local runtime copy is absent.
--- a/get-shit-done/workflows/add-backlog.md
+++ b/get-shit-done/workflows/add-backlog.md
@@ -19,12 +19,15 @@ cat .planning/ROADMAP.md
 ## Step 2: Find next backlog number

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/add-phase.md
+++ b/get-shit-done/workflows/add-phase.md
@@ -29,12 +29,15 @@ Exit.
 Load phase operation context:

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/add-tests.md
+++ b/get-shit-done/workflows/add-tests.md
@@ -33,12 +33,15 @@ Exit.
 Load phase operation context:

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/add-todo.md
+++ b/get-shit-done/workflows/add-todo.md
@@ -12,12 +12,15 @@ Read all files referenced by the invoking prompt's execution_context before star
 Load todo context:

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/ai-integration-phase.md
+++ b/get-shit-done/workflows/ai-integration-phase.md
@@ -20,12 +20,15 @@ This prevents the two most common AI development failures: choosing the wrong fr
 ## 1. Initialize

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/audit-fix.md
+++ b/get-shit-done/workflows/audit-fix.md
@@ -32,12 +32,15 @@ Invoke the source audit command and capture output.

 For `audit-uat` source:
 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/audit-milestone.md
+++ b/get-shit-done/workflows/audit-milestone.md
@@ -16,12 +16,15 @@ Valid GSD subagent types (use exact names — do not fall back to 'general-purpo
 ## 0. Initialize Milestone Context

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/audit-uat.md
+++ b/get-shit-done/workflows/audit-uat.md
@@ -8,12 +8,15 @@ Cross-phase audit of all UAT and verification files. Finds every outstanding ite
 Run the CLI audit:

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/autonomous.md
+++ b/get-shit-done/workflows/autonomous.md
@@ -48,12 +48,15 @@ When `--interactive` is set, discuss runs inline with questions (not auto-answer
 Bootstrap via milestone-level init:

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/check-todos.md
+++ b/get-shit-done/workflows/check-todos.md
@@ -12,12 +12,15 @@ Read all files referenced by the invoking prompt's execution_context before star
 Load todo context:

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/cleanup.md
+++ b/get-shit-done/workflows/cleanup.md
@@ -124,12 +124,15 @@ Repeat for all milestones in the cleanup set.
 Commit the changes:

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/code-review-fix.md
+++ b/get-shit-done/workflows/code-review-fix.md
@@ -18,12 +18,15 @@ Parse arguments and load project state:

 ```bash
 PHASE_ARG="${1}"
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/code-review.md
+++ b/get-shit-done/workflows/code-review.md
@@ -18,12 +18,15 @@ Parse arguments and load project state:

 ```bash
 PHASE_ARG="${1}"
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/complete-milestone.md
+++ b/get-shit-done/workflows/complete-milestone.md
@@ -41,12 +41,15 @@ When a milestone completes:
 Before proceeding with milestone close, run the comprehensive open artifact audit.

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/debug.md
+++ b/get-shit-done/workflows/debug.md
@@ -16,12 +16,15 @@ Valid GSD subagent types (use exact names — do not fall back to 'general-purpo
 ## 0. Initialize Context

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/diagnose-issues.md
+++ b/get-shit-done/workflows/diagnose-issues.md
@@ -58,12 +58,15 @@ gaps = [
 **Read worktree config:**

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/discuss-phase-assumptions.md
+++ b/get-shit-done/workflows/discuss-phase-assumptions.md
@@ -64,12 +64,15 @@ plain-text numbered list and ask the user to type their choice number.
 Phase number from argument (required).

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/discuss-phase.md
+++ b/get-shit-done/workflows/discuss-phase.md
@@ -109,7 +109,7 @@ Phase: "API documentation"       → Structure/navigation, Code examples depth,
 Phase number from argument (required).

 ```bash
-GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"; [ -f "$GSD_TOOLS" ] && GSD_SDK="node $GSD_TOOLS" || { echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2; exit 1; }
+GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"; if [ -f "$GSD_TOOLS" ]; then GSD_SDK="node $GSD_TOOLS"; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; GSD_SDK="$GSD_TOOLS"; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2; exit 1; fi
 INIT=$($GSD_SDK query init.phase-op "${PHASE}"); [[ "$INIT" == @file:* ]] && INIT=$(cat "${INIT#@file:}")
 AGENT_SKILLS_ADVISOR=$($GSD_SDK query agent-skills gsd-advisor-researcher)
 ```
--- a/get-shit-done/workflows/do.md
+++ b/get-shit-done/workflows/do.md
@@ -26,13 +26,16 @@ Wait for response before continuing.
 **Check if project exists.**

 ```bash
-# SDK resolution: prefer local node shim, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local node shim, fall back to installed gsd-tools (#3668)
 _GSD_SHIM_NAME="gsd-tools.cjs"
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/${_GSD_SHIM_NAME}"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/docs-update.md
+++ b/get-shit-done/workflows/docs-update.md
@@ -14,12 +14,15 @@ Valid GSD subagent types (use exact names — do not fall back to 'general-purpo
 Load docs-update context:

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/edit-phase.md
+++ b/get-shit-done/workflows/edit-phase.md
@@ -34,12 +34,15 @@ Exit.
 Load phase operation context:

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/eval-review.md
+++ b/get-shit-done/workflows/eval-review.md
@@ -13,12 +13,15 @@ Use after /gsd:execute-phase to verify that the evaluation strategy from AI-SPEC
 ## 0. Initialize

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/execute-phase.md
+++ b/get-shit-done/workflows/execute-phase.md
@@ -66,12 +66,15 @@ If `--wave` is absent, preserve the current behavior of executing all incomplete
 Load all context in one call:

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/execute-plan.md
+++ b/get-shit-done/workflows/execute-plan.md
@@ -30,12 +30,15 @@ Valid GSD subagent types (use exact names — do not fall back to 'general-purpo
 Load execution context (paths only to minimize orchestrator context):

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/explore.md
+++ b/get-shit-done/workflows/explore.md
@@ -115,12 +115,15 @@ For each selected output, write the file:

 Commit if `commit_docs` is enabled:
 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/extract-learnings.md
+++ b/get-shit-done/workflows/extract-learnings.md
@@ -16,12 +16,15 @@ Analyze completed phase artifacts (PLAN.md, SUMMARY.md, VERIFICATION.md, UAT.md,
 Parse arguments and load project state:

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/forensics.md
+++ b/get-shit-done/workflows/forensics.md
@@ -272,12 +272,15 @@ gh issue create \
 ## Step 8: Update STATE.md

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/graduation.md
+++ b/get-shit-done/workflows/graduation.md
@@ -21,12 +21,15 @@ Read from project config (`config.json`):
 ## Step 1: Guard Checks

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/health.md
+++ b/get-shit-done/workflows/health.md
@@ -49,12 +49,15 @@ available — replace the prompt with a plain-text two-question sequence
 plain text from the user's response.

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/import.md
+++ b/get-shit-done/workflows/import.md
@@ -176,12 +176,15 @@ Apply GSD naming convention for the output filename:
 Determine the target directory by querying `init.phase-op` for the phase number extracted in `plan_read_input`. This ensures the `project_code` prefix from `.planning/config.json` is applied:

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/insert-phase.md
+++ b/get-shit-done/workflows/insert-phase.md
@@ -34,12 +34,15 @@ Validate first argument is an integer.
 Load phase operation context:

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/list-workspaces.md
+++ b/get-shit-done/workflows/list-workspaces.md
@@ -11,12 +11,15 @@ Read all files referenced by the invoking prompt's execution_context before star
 ## 1. Setup

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/manager.md
+++ b/get-shit-done/workflows/manager.md
@@ -19,12 +19,15 @@ Read all files referenced by the invoking prompt's execution_context before star
 Bootstrap via manager init:

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/map-codebase.md
+++ b/get-shit-done/workflows/map-codebase.md
@@ -69,12 +69,15 @@ documents refreshed.
 Load codebase mapping context:

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/milestone-summary.md
+++ b/get-shit-done/workflows/milestone-summary.md
@@ -53,12 +53,15 @@ Read all files that exist. Missing files are fine — the summary adapts to what
 Find all phase directories:

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/mvp-phase.md
+++ b/get-shit-done/workflows/mvp-phase.md
@@ -34,12 +34,15 @@ Normalize per `@~/.claude/get-shit-done/references/phase-argument-parsing.md` (z
 ## 2. Validate phase exists and check status

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/new-milestone.md
+++ b/get-shit-done/workflows/new-milestone.md
@@ -181,12 +181,15 @@ blockers, todos) is preserved across the switch — symmetric with
 `milestone.complete`.

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/new-project.md
+++ b/get-shit-done/workflows/new-project.md
@@ -57,12 +57,15 @@ The document should describe what you want to build.
 **MANDATORY FIRST STEP — Execute these checks before ANY user interaction:**

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/new-workspace.md
+++ b/get-shit-done/workflows/new-workspace.md
@@ -13,12 +13,15 @@ Read all files referenced by the invoking prompt's execution_context before star
 **MANDATORY FIRST STEP — Execute init command:**

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/next.md
+++ b/get-shit-done/workflows/next.md
@@ -14,12 +14,15 @@ Read project state to determine current position:

 ```bash
 # Get state snapshot
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/pause-work.md
+++ b/get-shit-done/workflows/pause-work.md
@@ -66,12 +66,15 @@ Report any summaries with placeholder content as incomplete items.
 **Write structured handoff to `.planning/HANDOFF.json`:**

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/plan-milestone-gaps.md
+++ b/get-shit-done/workflows/plan-milestone-gaps.md
@@ -65,12 +65,15 @@ Gap: Flow "View dashboard" broken at data fetch
 Find highest existing phase:
 ```bash
 # Get sorted phase list, extract last one
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/plan-phase.md
+++ b/get-shit-done/workflows/plan-phase.md
@@ -31,12 +31,15 @@ Valid GSD subagent types (use exact names — do not fall back to 'general-purpo
 Load all context in one call (paths only to minimize orchestrator context):

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/plan-review-convergence.md
+++ b/get-shit-done/workflows/plan-review-convergence.md
@@ -43,12 +43,15 @@ echo "$ARGUMENTS" | grep -qE '\-\-ws\s+\S+' && GSD_WS=$(echo "$ARGUMENTS" | grep
 ## 1.5. Config Gate (feature disabled by default)

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/plant-seed.md
+++ b/get-shit-done/workflows/plant-seed.md
@@ -135,12 +135,15 @@ Store relevant file paths as `$BREADCRUMBS`.

 <step name="commit-seed">
 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/profile-user.md
+++ b/get-shit-done/workflows/profile-user.md
@@ -130,12 +130,15 @@ Display: "◆ Scanning sessions..."

 Run session scan:
 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/progress.md
+++ b/get-shit-done/workflows/progress.md
@@ -12,12 +12,15 @@ Read all files referenced by the invoking prompt's execution_context before star
 **Load progress context (paths only):**

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/quick.md
+++ b/get-shit-done/workflows/quick.md
@@ -125,12 +125,15 @@ If `$VALIDATE_MODE` only:
 **Step 2: Initialize**

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/remove-phase.md
+++ b/get-shit-done/workflows/remove-phase.md
@@ -29,12 +29,15 @@ Exit.
 Load phase operation context:

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/remove-workspace.md
+++ b/get-shit-done/workflows/remove-workspace.md
@@ -13,12 +13,15 @@ Read all files referenced by the invoking prompt's execution_context before star
 Extract workspace name from $ARGUMENTS.

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/resume-project.md
+++ b/get-shit-done/workflows/resume-project.md
@@ -20,12 +20,15 @@ Instantly restore full project context so "Where were we?" has an immediate, com
 Load all context in one call:

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/review.md
+++ b/get-shit-done/workflows/review.md
@@ -24,12 +24,15 @@ command -v qwen >/dev/null 2>&1 && echo "qwen:available" || echo "qwen:missing"
 command -v cursor >/dev/null 2>&1 && echo "cursor:available" || echo "cursor:missing"

 # Check local model servers (OpenAI-compatible HTTP API — no CLI binary required)
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/scan.md
+++ b/get-shit-done/workflows/scan.md
@@ -39,12 +39,15 @@ Exit.
 ## Step 2: Check for existing documents

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/secure-phase.md
+++ b/get-shit-done/workflows/secure-phase.md
@@ -16,12 +16,15 @@ Valid GSD subagent types (use exact names — do not fall back to 'general-purpo
 ## 0. Initialize

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/settings-advanced.md
+++ b/get-shit-done/workflows/settings-advanced.md
@@ -20,12 +20,15 @@ Read all files referenced by the invoking prompt's execution_context before star
 Ensure config exists and resolve the workstream-aware config path (mirrors `settings.md`):

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/settings-integrations.md
+++ b/get-shit-done/workflows/settings-integrations.md
@@ -42,12 +42,15 @@ Read all files referenced by the invoking prompt's execution_context before star
 Ensure config exists and resolve the active config path (flat vs workstream, #2282):

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/settings.md
+++ b/get-shit-done/workflows/settings.md
@@ -12,12 +12,15 @@ Read all files referenced by the invoking prompt's execution_context before star
 Ensure config exists and load current state:

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/ship.md
+++ b/get-shit-done/workflows/ship.md
@@ -12,12 +12,15 @@ Read all files referenced by the invoking prompt's execution_context before star
 Parse arguments and load project state:

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/sketch-wrap-up.md
+++ b/get-shit-done/workflows/sketch-wrap-up.md
@@ -37,12 +37,15 @@ Exit.

 Check `commit_docs` config:
 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/sketch.md
+++ b/get-shit-done/workflows/sketch.md
@@ -99,12 +99,15 @@ ls -d .planning/sketches/[0-9][0-9][0-9]-* 2>/dev/null | sort | tail -1

 Check `commit_docs` config:
 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/spike-wrap-up.md
+++ b/get-shit-done/workflows/spike-wrap-up.md
@@ -37,12 +37,15 @@ Exit.

 Check `commit_docs` config:
 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/spike.md
+++ b/get-shit-done/workflows/spike.md
@@ -96,12 +96,15 @@ ls -d .planning/spikes/[0-9][0-9][0-9]-* 2>/dev/null | sort | tail -1

 Check `commit_docs` config:
 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/stats.md
+++ b/get-shit-done/workflows/stats.md
@@ -12,12 +12,15 @@ Read all files referenced by the invoking prompt's execution_context before star
 Gather project statistics:

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/thread.md
+++ b/get-shit-done/workflows/thread.md
@@ -28,12 +28,15 @@ ls .planning/threads/*.md 2>/dev/null
 For each thread file found:
 - Read frontmatter `status` field via:
  ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/transition.md
+++ b/get-shit-done/workflows/transition.md
@@ -163,12 +163,15 @@ If found, delete them — phase is complete, handoffs are stale.
 **Delegate ROADMAP.md and STATE.md updates to `gsd-tools.cjs query phase.complete`:**

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/ui-phase.md
+++ b/get-shit-done/workflows/ui-phase.md
@@ -19,12 +19,15 @@ Valid GSD subagent types (use exact names — do not fall back to 'general-purpo
 ## 1. Initialize

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/ui-review.md
+++ b/get-shit-done/workflows/ui-review.md
@@ -16,12 +16,15 @@ Valid GSD subagent types (use exact names — do not fall back to 'general-purpo
 ## 0. Initialize

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/ultraplan-phase.md
+++ b/get-shit-done/workflows/ultraplan-phase.md
@@ -66,12 +66,15 @@ unplanned phase from the roadmap (same logic as /gsd:plan-phase).
 Load GSD phase context:

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/validate-phase.md
+++ b/get-shit-done/workflows/validate-phase.md
@@ -16,12 +16,15 @@ Valid GSD subagent types (use exact names — do not fall back to 'general-purpo
 ## 0. Initialize

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/verify-phase.md
+++ b/get-shit-done/workflows/verify-phase.md
@@ -29,12 +29,15 @@ Then verify each level against the actual codebase.
 Load phase operation context:

 ```bash
-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/get-shit-done/workflows/verify-work.md
+++ b/get-shit-done/workflows/verify-work.md
@@ -34,12 +34,15 @@ GSD_WS=""
 echo "$ARGUMENTS" | grep -qE -- '--ws[[:space:]]+[^[:space:]]+' && GSD_WS=$(echo "$ARGUMENTS" | grep -oE -- '--ws[[:space:]]+[^[:space:]]+')
 PHASE_ARG=$(echo "$ARGUMENTS" | sed -E 's/--ws[[:space:]]+[^[:space:]]+//g' | xargs)

-# SDK resolution: prefer local gsd-tools.cjs, fail if local gsd-tools.cjs is missing (#3668)
+# SDK resolution: prefer local gsd-tools.cjs, fall back to installed gsd-tools (#3668)
 GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
 if [ -f "$GSD_TOOLS" ]; then
  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v gsd-tools)"
+  GSD_SDK="$GSD_TOOLS"
 else
-  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS." >&2
+  echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH." >&2
  echo "Run: npx -y @opengsd/get-shit-done-redux@latest --claude --local" >&2
  exit 1
 fi
--- a/tests/bug-2851-workflow-bare-gsd-tools.test.cjs
+++ b/tests/bug-2851-workflow-bare-gsd-tools.test.cjs
@@ -1,7 +1,9 @@
 /**
 * Bug #2851: plan-phase.md §13e calls bare `gsd-tools` — incomplete fix of #2245
 *
- * `gsd-tools` is NOT a published bin entry. The shipped invocation pattern is:
+ * Workflow bodies should not call `gsd-tools` as an unguarded bare command.
+ * Use the resolver snippets for SDK calls, or an explicit local CJS path when
+ * a command intentionally targets the checked-in legacy script:
 *
 *   node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" <subcommand> [args]
 *
@@ -136,7 +138,7 @@ describe('bug-2851: workflow files must not call bare `gsd-tools` (#2245 sweep r
      violations,
      [],
      'Bare `gsd-tools` invocations found in workflow shell blocks. ' +
-        'Use `node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" <subcommand>` instead.\n' +
+        'Use a resolver snippet or `node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" <subcommand>` instead.\n' +
        violations.join('\n'),
    );
  });
--- a/tests/bug-3668-workflow-runtime-resolution.test.cjs
+++ b/tests/bug-3668-workflow-runtime-resolution.test.cjs
@@ -0,0 +1,90 @@
+/**
+ * Bug #3668: workflow resolver snippets must run from installed user projects.
+ *
+ * A user project normally does not contain get-shit-done/bin/gsd-tools.cjs.
+ * The snippets should still prefer RUNTIME_DIR for local/dev installs, then
+ * fall back to the installed gsd-tools binary on PATH.
+ */
+'use strict';
+
+const { describe, test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const WORKFLOW_PATH = path.join(__dirname, '..', 'get-shit-done', 'workflows', 'next.md');
+
+function extractResolverSnippet() {
+  const content = fs.readFileSync(WORKFLOW_PATH, 'utf8');
+  const lines = content.split('\n');
+  const start = lines.findIndex((line) => line.includes('SDK resolution: prefer local gsd-tools.cjs'));
+  assert.notEqual(start, -1, 'next.md must contain the SDK resolution snippet');
+
+  const end = lines.findIndex((line, index) => index > start && line === 'fi');
+  assert.notEqual(end, -1, 'SDK resolution snippet must end with fi');
+  return lines.slice(start, end + 1).join('\n');
+}
+
+function makeTempDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-runtime-resolution-'));
+}
+
+function runResolver({ cwd, runtimeDir, pathDir }) {
+  const script = [
+    'set -e',
+    extractResolverSnippet(),
+    'printf "GSD_TOOLS=%s\\n" "$GSD_TOOLS"',
+    '$GSD_SDK query state.json',
+  ].join('\n');
+
+  return execFileSync('bash', ['-lc', script], {
+    cwd,
+    env: {
+      ...process.env,
+      PATH: `${pathDir}${path.delimiter}${process.env.PATH || ''}`,
+      RUNTIME_DIR: runtimeDir || '',
+    },
+    encoding: 'utf8',
+  });
+}
+
+function writeExecutable(file, content) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content, { mode: 0o755 });
+}
+
+describe('bug-3668: workflow SDK resolver supports installed user projects', () => {
+  test('falls back to installed gsd-tools when project-local runtime copy is absent', () => {
+    const tmp = makeTempDir();
+    const project = path.join(tmp, 'user-project');
+    const bin = path.join(tmp, 'bin');
+    fs.mkdirSync(project, { recursive: true });
+    writeExecutable(path.join(bin, 'gsd-tools'), '#!/bin/sh\nprintf "installed:%s %s\\n" "$1" "$2"\n');
+
+    const output = runResolver({ cwd: project, pathDir: bin });
+
+    assert.match(output, new RegExp(`GSD_TOOLS=${path.join(bin, 'gsd-tools').replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`));
+    assert.match(output, /installed:query state\.json/);
+  });
+
+  test('preserves RUNTIME_DIR local gsd-tools.cjs preference over PATH fallback', () => {
+    const tmp = makeTempDir();
+    const project = path.join(tmp, 'user-project');
+    const runtime = path.join(tmp, 'runtime');
+    const pathBin = path.join(tmp, 'bin');
+    fs.mkdirSync(project, { recursive: true });
+    writeExecutable(path.join(pathBin, 'gsd-tools'), '#!/bin/sh\nprintf "installed:%s %s\\n" "$1" "$2"\n');
+    writeExecutable(
+      path.join(runtime, 'get-shit-done', 'bin', 'gsd-tools.cjs'),
+      '#!/usr/bin/env node\nconsole.log(`runtime:${process.argv[2]} ${process.argv[3]}`);\n',
+    );
+
+    const output = runResolver({ cwd: project, runtimeDir: runtime, pathDir: pathBin });
+
+    assert.match(output, new RegExp(`GSD_TOOLS=${path.join(runtime, 'get-shit-done', 'bin', 'gsd-tools.cjs').replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`));
+    assert.match(output, /runtime:query state\.json/);
+    assert.doesNotMatch(output, /installed:query state\.json/);
+  });
+});