docs(gh-aw): clarify Auto-Cast first-run UX, add canonical fallback, Cast PR return guidance (#1700) - #1702
Merged
Merged
Conversation
…Cast PR return guidance - workflows/squad.md: add safe fallback clauses to canonical_mode/canonical_command definitions; update first-run Auto-Cast Pivot comment to be warmer, explain paused-run state, and give explicit merge/rerun instruction; append return-to- originating-issue rerun instruction to Cast Step 6 PR body - test/gh-aw-quality.test.ts: add focused non-duplicative #1700 describe with 3 assertions: canonical fallback wording, paused-run wording, Cast PR body return/rerun instruction - docs/demo-agentic-sdlc-walkthrough.md: label two-issue explicit Cast as deliberate presenter variant and note inline auto-Cast path - docs/src/content/docs/guide/gh-aw.md: add concise no-team auto-Cast callout in Research section Closes #1700 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: fcedf035-540a-4d9d-8dc5-df265d91fe34
Contributor
🟡 Impact Analysis — PR #1702Risk tier: 🟡 MEDIUM 📊 Summary
🎯 Risk Factors
📦 Modules Affecteddocs (2 files)
root (1 file)
tests (1 file)
This report is generated automatically for every PR. See #733 for details. |
Contributor
🛫 PR Readiness Check
PR Scope: 🔧 Infrastructure
|
| Status | Check | Details |
|---|---|---|
| ✅ | Single commit | 1 commit — clean history |
| ✅ | Not in draft | Ready for review |
| ✅ | Branch up to date | Up to date with dev |
| ❌ | Copilot review | No Copilot review yet — it may still be processing |
| ✅ | Changeset present | No source files changed — changeset not required |
| ✅ | Scope clean | No .squad/ or docs/proposals/ files |
| ✅ | No merge conflicts | No merge conflicts |
| ❌ | Copilot threads resolved | 2 unresolved Copilot thread(s) — fix and resolve before merging |
| ✅ | CI passing | All checks passing |
Files Changed (4 files, +32 −7)
| File | +/− |
|---|---|
docs/demo-agentic-sdlc-walkthrough.md |
+1 −1 |
docs/src/content/docs/guide/gh-aw.md |
+2 −0 |
test/gh-aw-quality.test.ts |
+23 −0 |
workflows/squad.md |
+6 −6 |
Total: +32 −7
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR refines the gh-aw Squad documentation and contract tests to clarify the Auto-Cast first-run experience (including safe canonical fallbacks, “paused this run” wording), and to guide users to merge the Cast PR and rerun the originating command.
Changes:
- Update
workflows/squad.mdAuto-Cast Pivot guidance with canonical fallbacks, warmer first-run messaging, and Cast PR return/rerun instructions. - Add focused #1700 contract coverage in
test/gh-aw-quality.test.tsfor the new UX text. - Clarify explicit-vs-auto Cast guidance in the demo walkthrough and gh-aw docs guide.
Show a summary per file
| File | Description |
|---|---|
| workflows/squad.md | Clarifies canonical fallback prose, first-run Auto-Cast comment wording, and Cast PR body guidance. |
| test/gh-aw-quality.test.ts | Adds #1700-focused assertions for canonical fallback, paused-run wording, and PR body return/rerun guidance. |
| docs/src/content/docs/guide/gh-aw.md | Adds a concise “no team yet?” Auto-Cast callout in the Research section. |
| docs/demo-agentic-sdlc-walkthrough.md | Reframes the two-issue Cast flow as a deliberate presenter variant and points to inline auto-Cast. |
Review details
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
- Files reviewed: 4/4 changed files
- Comments generated: 2
- Review effort level: Lite
| ##### 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. |
Comment on lines
+1121
to
+1123
| 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); | ||
| }); |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #1700
Summary
Ports and refines the UX guidance changes validated in E2E runs against issue #1 of bradygaster/squad. Targets
devonly — no merge requested.Changes
workflows/squad.md— adds safe fallback prose to{canonical_mode}/{canonical_command}variable definitions; updates first-run Auto-Cast Pivot comment to be warmer and explicitly say the original command is paused this run; appends return-to-originating-issue + rerun instruction to Cast Step 6 PR bodytest/gh-aw-quality.test.ts— focused non-duplicative#1700describe block with 3 assertions: canonical fallback, paused-run wording, Cast PR body return/rerun. 82/82 tests passdocs/demo-agentic-sdlc-walkthrough.md— labels two-issue explicit Cast as deliberate presenter variant; notes inline auto-Cast pathdocs/src/content/docs/guide/gh-aw.md— concise no-team auto-Cast callout in Research sectionValidation
gh aw compile workflows/squad.md --strict --no-emitpasses at repo root; pre-existing dispatch-workflow strict-check failure fromgh aw compilein worktree subpath not introduced herenpx vitest run test/gh-aw-quality.test.ts— 82/82 pass in isolated worktreenpm run build— passes (SDK + CLI)docs/demo-agentic-sdlc-walkthrough.md:312(MD018) is pre-existing, not in a changed linegit diff --cached --diff-filter=D— 0 deletions; exactly 4 filesLive E2E Evidence
Threat Detector Note
Any threat-detector warnings on this PR are upstream
parse_errorfindings from the agentic workflow engine, not security findings from these content changes.