Repository navigation
docs(gh-aw): comprehensive guide update — slash commands, fast-path risks, implement vs @copilot, review gap - #1722
Merged
Conversation
…ement vs copilot agent, review lifecycle gap
- Replace single flat command table with grouped tables (team management,
research/planning, acceptance/activation, implementation) covering all
supported variants including /squad plan program revise and /squad research <focus>
- Expand fast-paths section: explicit table of skipped stages and per-path
risk callouts for /squad plan and /squad plan accept
- Expand implementing issues: full worker step sequence (dep check, dup check,
routing, build/test/lint, self-review, PR), epic slot calculation detail
- Add '/squad implement vs. GitHub Copilot coding agent' comparison table
and clarification that /squad implement does not enlist copilot-swe-agent[bot]
- Add 'Review lifecycle and current gaps' section documenting worker self-review
steps, no /squad review command exists, and the open lifecycle gap
- Fix troubleshooting: create-issue max corrected from 30 to 75; remediation
updated to re-run (idempotent) rather than split cycles
Pre-existing dirty files NOT staged: samples/storage-provider-azure/scripts/{create,delete}-storage.sh
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…/ glob Listing individual workflow files in the commit step drifts whenever Squad ships new or renamed shared imports. Replace both occurrences (Quick start and Setup sections) with: git add -- .gitattributes .github/aw/ .github/workflows/ This captures all workflow sources, lock files, and shared imports regardless of how the shipped file set evolves. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Contributor
🟢 Impact Analysis — PR #1722Risk tier: 🟢 LOW 📊 Summary
🎯 Risk Factors
📦 Modules Affecteddocs (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 | 2 commits — consider squashing before review |
| ✅ | 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 | No Copilot review threads |
| ❌ | CI passing | 1 check(s) still running |
Files Changed (1 file, +184 −83)
| File | +/− |
|---|---|
docs/src/content/docs/guide/gh-aw.md |
+184 −83 |
Total: +184 −83
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
Updates the GitHub Agentic Workflows (gh-aw) guide to better document Squad slash commands, fast-path tradeoffs, implementation-worker behavior, and the gap in automated review after implementation—aimed at improving accuracy and maintainability of the docs.
Changes:
- Reworked
/squadslash-command reference into grouped tables and expanded variants/notes. - Added guidance on fast-path risks (
/squad plan,/squad plan accept) and clarified implementation-worker + epic slot behavior. - Added
/squad implementvs@copilotcomparison and documented the lack of a dedicated/squad reviewworkflow/command.
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/guide/gh-aw.md | Expanded and reorganized gh-aw/Squad guide content (commands, risks, worker behavior, troubleshooting) |
Review details
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Suppressed comments (1)
docs/src/content/docs/guide/gh-aw.md:117
- This
git addsnippet stages all of.github/aw/, which can include downloaded workflow logs under.github/aw/logs/. Since the log ignore file is discussed immediately after, it’s safer to call out (in the snippet) that.github/aw/logs/.gitignoreshould exist before staging to avoid accidentally committing logs.
git add -- .gitattributes .github/aw/ .github/workflows/
git commit -m "ci: add Squad agentic workflow"
git push
- Files reviewed: 1/1 changed files
- Comments generated: 4
- Review effort level: Lite
Comment on lines
+38
to
40
| git add -- .gitattributes .github/aw/ .github/workflows/ | ||
| git commit -m "ci: add Squad agentic workflow" | ||
| git push |
| | Universe is full on cast-member | All character names in the universe are allocated | Retire an unused member first, or re-cast with `/squad cast` | | ||
| | "No plan found" on plan accept | No `/squad plan` comment exists yet | Run `/squad plan` first to generate a plan for review | | ||
| | Plan accept creates fewer issues than expected | `create-issue` safe-output has a max of 30 | Split into multiple plan/accept cycles for very large decompositions | | ||
| | Plan accept creates fewer issues than expected | `create-issue` safe-output has a max of 75 | Re-run the identical activation command — it is idempotent and picks up where it left off | |
Comment on lines
+183
to
+184
| | `/squad cast` | Analyze your repo and generate a tailored team of AI agents | Replaces existing team | | ||
| | `/squad cast [brief]` | Cast with an inline brief | Include your team spec in the same comment | |
| | `/squad connect <owner/repo>` | Link to an external squad source | Remote-managed; syncs at activation | | ||
| | `/squad adopt <owner/repo>` | Copy a squad from another repo | One-time copy; you own it after | | ||
| | `/squad cast-member <description>` | Add a single specialist to an existing team | Allocates a name from the existing universe | | ||
| | `/squad cast-member rename <name> to <new-focus>` | Change an existing member's specialty | Keeps identity; regenerates charter | |
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.
Summary
Comprehensive update to the GitHub Agentic Workflows guide addressing accuracy, completeness, and long-term maintainability.
Changes
Slash command reference — flat list replaced with four grouped tables (team management, research/planning, acceptance/activation, implementation) covering every supported variant, sourced from \workflows/squad.md.
Fast-path risks — per-path table of skipped stages; /squad plan\ skips triage + scope review; /squad plan accept\ creates GitHub issues immediately with no undo.
Implementation worker steps — full sequence documented (dep check → dup check → routing → implement → build/test/lint → self-review → one PR). Epic slot calculation and merge-relay auto-refill documented from workflow source.
/squad implement\ vs. GitHub Copilot coding agent — new comparison table; explicit statement that the worker does NOT enlist \copilot-swe-agent[bot].
Review lifecycle gap — new section: worker self-review steps, no /squad review\ command exists, open lifecycle gap named.
Troubleshooting fix — \create-issue\ max corrected 30 → 75 (verified in workflow frontmatter); remediation updated to idempotent re-run.
*Drift-proof \git add* — both explicit file lists replaced with \git add -- .gitattributes .github/aw/ .github/workflows/\ so the commit step stays correct as Squad ships new workflow files.
Validation
\
PASS: 84 fences balanced, 7 bash blocks, 40393 chars
\\
Docs-only change. No runtime code modified.