doctor
Diagnose why squad cannot run in this repository: tools, gh login and token scopes, .squad/config.yml and its board ids, board fields and Status columns, items missing from GitHub's item listing, labels, conflicting project workflows, merge settings, branch protection, release-gate workflow, the production GitHub Environment, the Railway CLI login and project, the gh pr merge permission rule and leftover worktrees. Read-only; proposes each fix and applies it only after the stakeholder agrees. Use when a squad script fails, after a machine restart or a fresh clone, before the first run, or when the stakeholder asks whether squad is set up correctly.
- License 许可
- MIT
- 最近更新
- 2026-10-16
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- doctor
- description
- Diagnose why squad cannot run in this repository: tools, gh login and token scopes, .squad/config.yml and its board ids, board fields and Status columns, items missing from GitHub's item listing, labels, conflicting project workflows, merge settings, branch protection, release-gate workflow, the production GitHub Environment, the Railway CLI login and project, the gh pr merge permission rule and leftover worktrees. Read-only; proposes each fix and applies it only after the stakeholder agrees. Use when a squad script fails, after a machine restart or a fresh clone, before the first run, or when the stakeholder asks whether squad is set up correctly.
03 SKILL.md 正文
squad: doctor
Paths written as references/…, templates/… or scripts/… are inside ${CLAUDE_PLUGIN_ROOT} (the squad plugin folder), not the target repository.
Runs in the main session (PM). No subagent: it only reads, then asks.
Steps
-
Run
"${CLAUDE_PLUGIN_ROOT}/scripts/doctor.sh"from the repository root (--offlinewhen there is no network). It prints JSON{ok, fails, warns, checks}; each check hasstatus(ok,warn,fail),detailandfix. -
Tell the stakeholder, in their language: one line per
failandwarnwith what it breaks and the fix; then "everything else is OK" with the number of passing checks.fail: squad cannot work correctly until it is fixed (/squad:runwould stop).warn: squad runs, with a gap (e.g. no branch protection, no production secret yet).
-
Fixes, one confirmation for the whole list ("fix all?") unless a fix is destructive:
Check Fix Who configmissingthe setupskillPM ids,boardboard.sh bootstrap --project <n>(reuses the board, rewrites ids)PM labelsissue.sh labelsPM project_workflowsboard.sh workflows --fixdeletes them: explicit yes for this onePM board_itemsboard.sh relink <issues>deletes and re-adds those items (fields kept, item history lost): explicit yes for this onePM gh_auth! gh auth refresh -h github.com -s project,workflowstakeholder merge_permissionadd "Bash(gh pr merge:*)"to.claude/settings.jsonPM, after yes gitignoreappend the missing lines PM merge_settings,branch_protection,environment:*,deploy_workflowsetupskill steps 5 and 8PM railwayinstall the Railway CLI; ! railway login(OAuth); setdeploy.railway.project(setup step 8)stakeholder logs in; PM writes the config worktreesworktree.sh clean <issue> --delete-branch --pr-mergedPM commandspropose values from the stack (setup step 7), write after yes PM Changes to tracked files (
.gitignore,.claude/settings.json, workflows) go on a branchchore/squad-doctorwith a PR, never straight tomain. -
Run
doctor.shagain and report the result.
Never
- Fix anything without the stakeholder's yes, or delete project workflows or relink board items without an explicit yes for that item.
- Read, print or set secrets or tokens.
- Edit
ids:in the config by hand.
04 同仓库更多 Skills
setup
Initialize squad in the current repository (or `quick`: board, labels and commands only, no deploys, in about two minutes): create or reuse the GitHub Projects board with the squad Status columns and Priority/Size/Wave/Agent/Attempts fields, create the labels, write .squad/config.yml, and configure merges, branch protection and .gitignore. Use the first time squad is used in a repository, when .squad/config.yml is missing, or when a board script reports missing ids.
run
PM orchestrator for squad: repeatedly read the board with next.sh and dispatch the right subagent for the highest-priority action (QA, Team Lead merge, review, rebase, planning, parallel developers by wave, deploy), relay gates and questions to the stakeholder, and stop at a requirements gate, when only GATE 3 is left, after max steps, or when nothing is left (then report). Use when the stakeholder says run, continue, or keep going, or on a schedule.
review
Code review procedure for one PR in In Review: check size and scope, verify every acceptance criterion and DoD item has a test, review correctness and security against the review checklist, and post the verdict as a review comment (PASS adds review:passed for the Team Lead to merge; CHANGES sends the task back). Never approves or merges. Use when a PR is waiting for review.
report
Progress report for the stakeholder: collect delivery metrics from the board and GitHub with metrics.sh (period or milestone), have the reporter draft a report with a 5-line plain-language summary and a metrics table where every number comes from the script, then publish it as a type:report issue and summarize it in the stakeholder's language. Use when the stakeholder asks how things are going, at the end of a run, or on a schedule.
qa
QA procedure: verify a merged task, bug or story in the QA column against every acceptance criterion and DoD item by running the full test suites, e2e and the real app on the latest main; pass it to Done with a test report, or file a bug sub-issue from the bug template and keep the task out of Done. Also re-verifies a task whose bugs are fixed and closes stories whose tasks are all Done. Use when items are waiting in QA.
plan
Team Lead procedure: split approved stories (Backlog), needs-split tasks and QA bugs into small XS/S technical tasks with Files (expected), dependencies and Definition of Done, group them into parallel waves on the board and post the dispatch plan; recompute waves when developer slots are idle (rewave); put stories the stakeholder wants released into a milestone (milestone); turn one small stakeholder request into a single quick-lane task (quick); or, in merge mode, do the final check of a PR labeled review:passed and squash-merge it. Use after GATE 2 story approval, when a task is labeled needs-split, when QA files bugs, or when a reviewed PR is waiting to merge.