AGENT SKILL

sync

Move every canonical checkout in a fleet onto the remote default branch and fast-forward it. Divergent dirty work is parked in a linked worktree. Bare invocation prints a dry-run plan. Mutation requires --apply and one confirmation. Use when: 'sync the fleet', 'update all repos to main', 'fast-forward canonical checkouts', 'park my dirty branches and pull'.

License 许可
MIT
最近更新
2026-11-15
Stars
★ 30
Forks
7

01 前言 Front Matter

metadata
{ "cadence": "weekly", "summary": "Fast-forward canonical checkouts to the remote default branch", "workflow-stage": "operator" }
description
Move every canonical checkout in a fleet onto the remote default branch and fast-forward it. Divergent dirty work is parked in a linked worktree. Bare invocation prints a dry-run plan. Mutation requires --apply and one confirmation. Use when: 'sync the fleet', 'update all repos to main', 'fast-forward canonical checkouts', 'park my dirty branches and pull'.
allowed-tools
[ "Bash(${CLAUDE_SKILL_DIR}/scripts/sync-fleet.sh:*)" ]
argument-hint
[<dir>...] [--root <dir>] [--repo <dir>] [--skip <name>] [--config <file>] [--apply] [--yes]
user-invocable
true
disable-model-invocation
true

02 资源文件 3

03 SKILL.md 正文

Arguments. [<dir>...] [--root <dir>] [--repo <dir>] [--skip <name>] [--config <file>] [--apply] [--yes]. Full form: [<dir>...] [--root <dir>] [--repo <dir>] [--named <dir>] [--repos-from <file|->] [--skip <name>] [--extend-skip <name>] [--skip-from <file>] [--config <file>] [--dry-run] [--apply] [--yes]

Purpose

/repo-fleet-hygiene:audit is read-only. /repo-fleet-hygiene:apply deletes merged branches. This skill is the sync verb: each canonical checkout switches to the remote's current default branch (git ls-remote --symref origin HEAD) and pull --ff-onlys it. Dirty work on a non-default branch, and a dirty default branch, is parked in a linked worktree by the worktree-create.sh helper you name with --worktree-create.

Scope ladder

First hit wins:

  1. Explicit --repo, --root, a bare path, or --repos-from <file|-> (one checkout path per line, - reads stdin, blank lines ignored). --root, --repo, and --named repeat.
  2. Fleet config (--config, else the project file, else ~/.claude/repo-fleet-hygiene.conf).
  3. --named paths from the conversation.
  4. ghq root --all (every root), when ghq is installed.
  5. The nearest of the 4 parents above the working directory's checkout (above the working directory itself outside a checkout) that directly holds 2 or more Git repositories. A run inside one checkout therefore covers its sibling fleet.
  6. The checkout holding the working directory, when no such parent exists.
  7. Exit 3. The message names the rungs. The project directory is not an implicit repo.

/repo-fleet-hygiene:audit uses the same fallback when it has no explicit or config scope.

Claim: ghq root --all prints every configured root. Basis: the ghq README (ghq root [--all]; "Without '--all' option, the primary one is shown") and ghq help root on ghq 1.10.1 ("--all Show all roots"). As of: 2026-11-10. Recheck: the README's root entry drops or renames --all.

Every plan line and every skipped line ends with rung=<rung>, the rung that produced that repository: repo, repos-from, root (a bare path counts as --root), config, named, ghq, cwd, or ancestor. A repository found by walking a root carries that root's rung. Read the rung before applying: ghq, cwd, and ancestor mean no scope was given.

Skip flags

--skip, --extend-skip, and --skip-from <file> (one name per line, blank lines ignored, CRLF stripped, a missing file exits 2) and the config keys fleet.skip and fleet.skipAppend prune directories during discovery with the same semantics as /repo-fleet-hygiene:audit: an explicit --skip set replaces the default, --extend-skip adds to whichever set is in effect, and names are bare directory names. The skip set does not filter --repo or --repos-from paths. To leave out one repository found under a root, pass --extend-skip <its directory name>; --skip also drops the default names.

Discovery under a root is the walker /repo-fleet-hygiene:audit runs (fleet-discovery.sh, shared by both verbs): it stops at the first checkout on each path, does not follow symlinked directories, and goes 5 levels deep unless the config's fleet.maxDepth (1 through 12) says otherwise.

Confirmation

Flags Behavior
(default), or --dry-run Dry-run plan. Nothing changes. --dry-run with --apply exits 2.
--apply on a terminal One prompt for the whole plan. Decline changes nothing.
--apply without a terminal Exit 3. Nothing changes.
--apply --yes Apply.

--yes skips the script's prompt, not the user. Pass it only after you have shown the user the dry-run plan (its repos: count and each repo's action row) and the user has explicitly said to go ahead. This holds in non-terminal runs too: no terminal is never consent.

Non-fast-forward, dubious ownership, and a partial stash apply are skipped and reported. The script does not reset a branch.

Parking flags, not in argument-hint:

  • --worktree-create <path>: the helper, which this skill never looks for. Give the path of the source-control plugin's worktree-create.sh. The file must exist and be named worktree-create.sh, or the run exits 2. The helper is called with --existing-branch, which checks out the branch that already holds the work.
  • --worktree-root <dir>: optional. Without it the helper resolves the root from each repository's worktreeroot.path (includeIf applies). A repository with none makes the helper exit 3; that repo is put back as it was, skipped, and the remedy quotes the helper's first message line.

Without --worktree-create, a dirty repo is planned skip ... worktree-create-missing and nothing is stashed. Park it by hand with /source-control:worktree create --existing-branch, or commit or stash the work.

Run:

${CLAUDE_SKILL_DIR}/scripts/sync-fleet.sh --project-dir "${CLAUDE_PROJECT_DIR}" [--worktree-create <path>] [--worktree-root <dir>] <quoted-arguments>

Next

/repo-fleet-hygiene:audit after canonical checkouts are on their default branches.

Gotchas

  • A clean non-default branch is checked out away from, not deleted. The branch remains.
  • pull --ff-only refuses a history that diverged. That repo is skipped.
  • Do not point this at repo-hygiene:clean tree-batch. That verb is destructive and is not this skill.

04 同仓库更多 Skills

melodic-software
melodic-software/claude-code-plugins

track

Backlog reads through the bound tracker: search open and closed items, view one item with its comments and state history. Use when another skill searches or reads tracker items.

★ 30
melodic-software
melodic-software/claude-code-plugins

reviewer-media

Reviewer media for one pull request: decides whether it needs a narrated walkthrough, builds the storyboard from /review:explain-change's digest, has /explainer-video:produce render it and hands the manifest to /source-control:pull-request media. Use when asked for 'reviewer media', 'a walkthrough video for this PR', 'a produced video of this change', or when pull-request ready or monitor hands a PR over.

★ 30
melodic-software
melodic-software/claude-code-plugins

route

Model and effort per agent role (orchestrator, worker, verifier, retrieval) for a multi-agent run, resolved through the bundled defaults and the user, team and personal override config layers into fenced JSON with single-agent and fan-out variants and the layer behind each value. Use when asked 'which model for the subagents', 'route the roles' or 'model routing', or before a skill passes a role's model on a spawn.

★ 30
melodic-software
melodic-software/claude-code-plugins

route

Model and effort per agent role (orchestrator, worker, verifier, retrieval) for a multi-agent run, resolved through the bundled defaults and the user, team and personal override config layers into fenced JSON with single-agent and fan-out variants and the layer behind each value. Use when asked 'which model for the subagents', 'route the roles' or 'model routing', or before a skill passes a role's model on a spawn.

★ 30
melodic-software
melodic-software/claude-code-plugins

principles

Module-design vocabulary for architecture findings, and the checks built on it. Use when: 'what is a deep module', 'what is a seam', 'deep vs shallow module', 'what is the deletion test', 'leverage and locality', 'module design vocabulary', 'which word do we use for X in architecture findings'. Scanning a codebase for friction is /architecture:improve.

★ 30
melodic-software
melodic-software/claude-code-plugins

write

Structured five-field bug report (title, steps to reproduce, expected vs actual, justified severity, suggested fix location) from an informal description, read-only. Use when the user names a defect they observed, or asks for one written up ('report a bug', 'file a bug', 'write this up as a bug').

★ 30