AGENT SKILL

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

  1. Run "${CLAUDE_PLUGIN_ROOT}/scripts/doctor.sh" from the repository root (--offline when there is no network). It prints JSON {ok, fails, warns, checks}; each check has status (ok, warn, fail), detail and fix.

  2. Tell the stakeholder, in their language: one line per fail and warn with 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:run would stop).
    • warn: squad runs, with a gap (e.g. no branch protection, no production secret yet).
  3. Fixes, one confirmation for the whole list ("fix all?") unless a fix is destructive:

    Check Fix Who
    config missing the setup skill PM
    ids, board board.sh bootstrap --project <n> (reuses the board, rewrites ids) PM
    labels issue.sh labels PM
    project_workflows board.sh workflows --fix deletes them: explicit yes for this one PM
    board_items board.sh relink <issues> deletes and re-adds those items (fields kept, item history lost): explicit yes for this one PM
    gh_auth ! gh auth refresh -h github.com -s project,workflow stakeholder
    merge_permission add "Bash(gh pr merge:*)" to .claude/settings.json PM, after yes
    gitignore append the missing lines PM
    merge_settings, branch_protection, environment:*, deploy_workflow setup skill steps 5 and 8 PM
    railway install the Railway CLI; ! railway login (OAuth); set deploy.railway.project (setup step 8) stakeholder logs in; PM writes the config
    worktrees worktree.sh clean <issue> --delete-branch --pr-merged PM
    commands propose values from the stack (setup step 7), write after yes PM

    Changes to tracked files (.gitignore, .claude/settings.json, workflows) go on a branch chore/squad-doctor with a PR, never straight to main.

  4. Run doctor.sh again 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

congdang-agilityio
congdang-agilityio/agile-squad

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.

★ 2
congdang-agilityio
congdang-agilityio/agile-squad

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.

★ 2
congdang-agilityio
congdang-agilityio/agile-squad

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.

★ 2
congdang-agilityio
congdang-agilityio/agile-squad

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.

★ 2
congdang-agilityio
congdang-agilityio/agile-squad

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.

★ 2
congdang-agilityio
congdang-agilityio/agile-squad

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.

★ 2