fix: prevent agent from suggesting non-existent /gsd:transition command (#1081) (#1129)

The agent was telling users to run '/gsd:transition' after phase completion,
but this command does not exist. transition.md is an internal workflow invoked
by execute-phase during auto-advance.

Changes:
- Add <internal_workflow> banner to transition.md declaring it is NOT a user command
- Add explicit warning in execute-phase completion section that /gsd:transition
  does not exist
- Add 'only suggest commands listed above' guard to prevent hallucination
- Update resume-project.md to avoid ambiguous 'Transition' label
- Replace 'ready for transition' with 'ready for next step' in execute-plan.md

Fixes #1081

.release-monitor.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Release monitor for gsd-build/get-shit-done
+# Checks every 15 minutes, writes new release info to a signal file
+
+REPO="gsd-build/get-shit-done"
+SIGNAL_FILE="/tmp/gsd-new-release.json"
+STATE_FILE="/tmp/gsd-monitor-last-tag"
+LOG_FILE="/tmp/gsd-monitor.log"
+
+# Initialize with current latest
+echo "v1.25.1" > "$STATE_FILE"
+rm -f "$SIGNAL_FILE"
+
+log() {
+  echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" >> "$LOG_FILE"
+  echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1"
+}
+
+log "Monitor started. Watching $REPO for releases newer than v1.25.1"
+log "Checking every 15 minutes..."
+
+while true; do
+  sleep 900  # 15 minutes
+
+  LAST_KNOWN=$(cat "$STATE_FILE" 2>/dev/null)
+  
+  # Get latest release tag
+  LATEST=$(gh release list -R "$REPO" --limit 1 2>/dev/null | awk '{print $1}')
+  
+  if [ -z "$LATEST" ]; then
+    log "WARNING: Failed to fetch releases (network issue?)"
+    continue
+  fi
+
+  if [ "$LATEST" != "$LAST_KNOWN" ]; then
+    log "NEW RELEASE DETECTED: $LATEST (was: $LAST_KNOWN)"
+    
+    # Fetch release notes
+    RELEASE_BODY=$(gh release view "$LATEST" -R "$REPO" --json tagName,name,body 2>/dev/null)
+    
+    # Write signal file for the agent to pick up
+    echo "$RELEASE_BODY" > "$SIGNAL_FILE"
+    echo "$LATEST" > "$STATE_FILE"
+    
+    log "Signal file written to $SIGNAL_FILE"
+    # Exit so the agent can process it, then restart
+    exit 0
+  else
+    log "No new release. Latest is still $LATEST"
+  fi
+done

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

@@ -574,6 +574,8 @@ Read and follow `~/.claude/get-shit-done/workflows/transition.md`, passing throu
 
 **STOP. Do not auto-advance. Do not execute transition. Do not plan next phase. Present options to the user and wait.**
 
+**IMPORTANT: There is NO `/gsd:transition` command. Never suggest it. The transition workflow is internal only.**
+
 ```
 ## ✓ Phase {X}: {Name} Complete
 
@@ -582,6 +584,8 @@ Read and follow `~/.claude/get-shit-done/workflows/transition.md`, passing throu
 /gsd:plan-phase {next} — plan next phase
 /gsd:execute-phase {next} — execute next phase
 ```
+
+Only suggest the commands listed above. Do not invent or hallucinate command names.
 </step>
 
 </process>

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

@@ -371,7 +371,7 @@ One-liner SUBSTANTIVE: "JWT auth with refresh rotation using jose library" not "
 
 Include: duration, start/end times, task count, file count.
 
-Next: more plans → "Ready for {next-plan}" | last → "Phase complete, ready for transition".
+Next: more plans → "Ready for {next-plan}" | last → "Phase complete, ready for next step".
 </step>
 
 <step name="update_current_position">

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

@@ -154,7 +154,7 @@ Based on project state, determine the most logical next action:
 → Option: Abandon and move on
 
 **If phase in progress, all plans complete:**
-→ Primary: Transition to next phase
+→ Primary: Advance to next phase (via internal transition workflow)
 → Option: Review completed work
 
 **If phase ready to plan:**
@@ -242,7 +242,7 @@ Based on user selection, route to appropriate workflow:
 
   ---
   ```
-- **Transition** → ./transition.md
+- **Advance to next phase** → ./transition.md (internal workflow, invoked inline — NOT a user command)
 - **Check todos** → Read .planning/todos/pending/, present summary
 - **Review alignment** → Read PROJECT.md, compare to current state
 - **Something else** → Ask what they need

get-shit-done/workflows/transition.md

@@ -1,3 +1,19 @@
+<internal_workflow>
+
+**This is an INTERNAL workflow — NOT a user-facing command.**
+
+There is no `/gsd:transition` command. This workflow is invoked automatically by
+`execute-phase` during auto-advance, or inline by the orchestrator after phase
+verification. Users should never be told to run `/gsd:transition`.
+
+**Valid user commands for phase progression:**
+- `/gsd:discuss-phase {N}` — discuss a phase before planning
+- `/gsd:plan-phase {N}` — plan a phase
+- `/gsd:execute-phase {N}` — execute a phase
+- `/gsd:progress` — see roadmap progress
+
+</internal_workflow>
+
 <required_reading>
 
 **Read these files NOW:**