Merge pull request #1702 from bradygaster/squad/1700-auto-cast-ux-guidance

docs(gh-aw): clarify Auto-Cast first-run UX, add canonical fallback, Cast PR return guidance (#1700)

Author: bradygaster

docs/demo-agentic-sdlc-walkthrough.md

@@ -33,7 +33,7 @@ Merge the PR to activate your team. Run `/squad status` afterward to verify.
 
 **Screen shows:** The PR merges. The casting issue remains open until the user closes it.
 
-**Key point:** Casting is a one-time setup action — it gets its own issue that the user closes after merge. Your actual work intent goes in a separate issue that stays open throughout the SDLC lifecycle.
+**Key point:** This two-issue setup — a dedicated Cast issue followed by a separate work issue — is a deliberate **presenter variant** that makes each stage explicit. In everyday use you don't need to pre-cast: if you run a work command such as `/squad research` on a repo with no committed team, Squad auto-Casts on that same issue, pauses the original command, and tells you to merge the Cast PR and rerun. Either path works; the demo uses the explicit variant so each step is visible on screen.
 
 ---
 

docs/src/content/docs/guide/gh-aw.md

@@ -427,6 +427,8 @@ Squad performs a deep analysis of your repository in context of the issue, then
 posts structured findings as a comment. This is the discovery phase — no issues
 or PRs are created.
 
+> **No team yet?** If you run `/squad research` (or any other work command) on a repo with no committed team, Squad automatically opens a Cast PR on the same issue, pauses your command for that run, and posts instructions to merge the Cast PR and rerun the original command. You don't need to pre-cast on a separate issue — Squad handles it inline.
+
 The research comment includes:
 - **Current state** — architecture, patterns, dependency versions, code health
 - **Gap analysis** — what's missing or incomplete relative to the issue/goal

test/gh-aw-quality.test.ts

@@ -1107,3 +1107,26 @@ describe('gh-aw: Cast PR dedup jq filter behavioral coverage (#1689 revision)',
     expect(result).not.toContain('squad/cast-member-dev');
   });
 });
+
+// ---------------------------------------------------------------------------
+// gh-aw: Auto-Cast UX guidance — canonical fallback, paused-run wording,
+// and Cast PR body return/rerun instruction (#1700)
+//
+// Focused contract assertions for the UX guidance added in #1700.
+// Complements the broader auto-Cast coverage in the '#1689' describe blocks above.
+// ---------------------------------------------------------------------------
+describe('gh-aw: Auto-Cast UX guidance — canonical fallback and Cast PR body return instruction (#1700)', () => {
+  const squadContent = readFileSync(SQUAD_WORKFLOW, 'utf8');
+
+  it('canonical_mode definition includes safe fallback for unresolvable mode', () => {
+    expect(squadContent).toMatch(/if.*canonical_mode.*cannot be determined.*safe fallback|safe fallback.*\/squad/i);
+  });
+
+  it('first-run Auto-Cast comment tells user their command is paused this run', () => {
+    expect(squadContent).toMatch(/command.*paused this run|paused this run/i);
+  });
+
+  it('Cast PR body instructs user to return to originating issue and rerun canonical command', () => {
+    expect(squadContent).toMatch(/return to the originating issue and rerun.*\{canonical_command\}/s);
+  });
+});

workflows/squad.md

@@ -219,8 +219,8 @@ The leading `sub(/\r$/,"")` normalizes CRLF line endings so Windows-formatted te
 ### Auto-Cast Pivot
 
 **Canonical command variables** (derived from Parse Command output — never from raw input):
-- `{canonical_mode}` — the parsed mode enum (e.g., `research`, `plan`, `plan-activate`)
-- `{canonical_command}` — reconstructed user-safe command: `/squad {canonical_mode}` with optional `phase {N}` suffix
+- `{canonical_mode}` — the parsed mode enum (e.g., `research`, `plan`, `plan-activate`); if the mode cannot be determined, substitute the literal string `squad` in prose
+- `{canonical_command}` — reconstructed user-safe command: `/squad {canonical_mode}` with optional `phase {N}` suffix; if `{canonical_mode}` cannot be determined, use `/squad` as the safe fallback
 - `{phase_n}` — numeric phase if present; omit the field otherwise
 
 **Universal response invariant:** current state · result · one primary next action · recovery on ⚠️/🔴.
@@ -249,13 +249,13 @@ gh pr list --state open --json number,url,headRefName --jq '[.[] | select(.headR
 - The Cast PR body may reference the originating issue and canonical command in plain language, but MUST NOT contain `Fixes`, `Closes`, or `Resolves` closing keywords for the originating work issue.
 - Then `add-comment`:
   ```
-  🤖 Squad is assembling your team.
+  🤖 Your `{canonical_mode}` command found no team yet — Squad has automatically opened a Cast PR to assemble one.
 
   **Current state:** No team detected — Squad auto-pivoted to Cast.
-  **Result:** A Cast PR has been opened. Check the **Pull Requests** tab to find and review it.
+  **Result:** A Cast PR has been opened. Your `{canonical_mode}` command is paused this run — resume it after merging.
   **Next action:** Merge the Cast PR, then return to this issue and rerun: `{canonical_command}`
 
-  ⚠️ The PR link is not available in this comment — find it in the **Pull Requests** tab.
+  ⚠️ A direct Cast PR link is not available in this comment. Find it in the **Pull Requests** tab.
   ```
 - A closed or failed Cast PR is not durable team state. A later rerun with no committed roster and no open Cast PR MUST attempt Cast again.
 - Stop. Do not run the original command this run.
@@ -353,7 +353,7 @@ Create `meet-the-squad.md` at repo root with: title, universe name, team table (
 
 ##### Step 6: Open PR
 
-`create-pull-request`: branch `squad/cast-{repo}`, title `[squad] Cast your Squad — {description}`, body with team summary. Files: `.squad/`, `.github/agents/squad.agent.md`, `meet-the-squad.md`. Stage only these.
+`create-pull-request`: branch `squad/cast-{repo}`, title `[squad] Cast your Squad — {description}`, body with team summary. Append to the PR body: "After merging, return to the originating issue and rerun `{canonical_command}` to resume your work." Files: `.squad/`, `.github/agents/squad.agent.md`, `meet-the-squad.md`. Stage only these.
 
 ##### Step 7: Post Completion