Multi-Agent Git Orchestrator

Coordinate parallel development without corrupting workspaces, rewriting shared history, or integrating stale/unverified agent output. When advice depends on the current repository, inspect the repository first and base recommendations on observed Git state rather than assumptions.

Activation Scope

Activate automatically for either mode below.

A. Orchestration Mode

Use when multiple development actors share one Git repository and work involves any of:

• parallel coding agents or developers;
• one task/agent per branch or worktree;
• task-lane or dependency-DAG planning;
• worktree isolation or branch ownership;
• merge queues or protected integration branches;
• deciding between merge, squash merge, cherry-pick, rebase, reset, or revert;
• selective acceptance of agent commits;
• cross-agent conflicts, branch divergence, stale approvals, or shared rollback;
• branch strategy: choosing or auditing the branching model (integration/lane/long-lived branch roles, lane naming and lifetime, release/hotfix flow, branch protection).

B. Reconnaissance / Advice Mode

Use proactively when the user asks what should be done with the current repository, including:

• inspect/list/analyze worktrees or branches;
• recommend which branch/worktree should receive a task;
• decide what can be merged, rebased, cherry-picked, archived, or deleted;
• explain divergence, stale branches, detached worktrees, dirty lanes, or overlapping work;
• advise how to simplify or reorganize current multi-branch/worktree topology;
• assess whether it is safe to start another agent/lane;
• assess, design, or change the branching model/strategy of the current repository (which model it actually follows, whether it suits parallel agents, what the smallest fix is).

For repository-specific advice, inspect before recommending when repository shell/tool access is available. Do not ask the user to manually paste branch/worktree state that can be observed directly.

Do not activate merely because Git is mentioned. Pure conceptual questions such as “what does commit mean?” or “explain gitflow vs trunk-based”, and ordinary single-branch operations, do not require this skill unless repository-specific topology or shared-history safety matters. A request to choose, audit, or change the branching model of a specific repository does, above all one that agents, worktrees, or several developers share.

Explicit Command Interface

Treat the following names as explicit invocation intents. The canonical command names are /Git...; host-native skill adapters may map them to another selector. Explicit invocation selects the command mode but does not bypass safety gates.

Host Invocation Names

All three hosts can install the package as the plugin magos from this repository's marketplace: Claude Code through .claude-plugin/marketplace.json and .claude-plugin/plugin.json (commands /magos:GitRecon and so on), Codex through the same marketplace file and the root plugin.json ($magos:git-recon; the root mcp.json adds the local MCP server magos for the one-click approval), and Hermes through plugin.yaml (/magos:git-recon; the plugin's __init__.py also runs the lane guard on the terminal tool). Plugin hosts never load this root file as a skill, so the plugin carries skills/git-orchestrator, an entry skill with this description that reads this file. Claude Code also loads a clone in ~/.claude/skills/magos as that plugin; otherwise it registers /GitRecon and the rest only from copies of the commands/ files in ~/.claude/commands/ (or a project's .claude/commands/), which do not update when the package does (references/installation.md covers every way). Codex and Hermes discover the nine Agent Skills in skills/ (nested under this package) in addition to this root skill: Codex exposes them as $git-* skills (or browse with /skills) and does not register arbitrary custom /Git... slash commands; Hermes registers each as a /git-* slash command. The skills/ adapters are host-neutral: they read this file and references/ directly and never route through commands/, whose loading steps are Claude-specific. Codex adapters disable implicit selection in agents/openai.yaml; Hermes has no per-skill switch, so the write adapters (git-integrate, git-cleanup, git-converge, git-sweep, git-plan, git-protect) enforce explicit invocation by instruction. Agent Plugins clients (the root plugin.json, specification 1.0.0) discover only these nine adapters and the entry skill git-orchestrator in skills/; for them this root skill is shared package content that the entry skill and the adapters read, not a plugin skill. Only that discovery is verified: Hermes plugin skills get no /git-* commands, so the write adapters (which act only on an explicit invocation) are for the skills-directory installs there. See references/commands.md Host Adapter Contract for argument passing and file resolution per host.

Command Semantics

• Explicit command wins over automatic mode selection. /GitRecon//GitAnalyze//GitRecommend do not mutate repository topology by default.
• --remote authorizes a remote-ref refresh when needed (for example git fetch --prune); it does not authorize branch/history mutation.
• /GitRecommend MUST run or reuse a fresh reconnaissance snapshot. A snapshot is stale if relevant HEADs, refs, worktree cleanliness, or integration target changed after observation.
• /GitIntegrate is authorization to attempt a safe integration, not permission to bypass review, freshness, dependency, protected-branch, or repository-policy gates. If gates fail, stop and report the blocker rather than forcing integration.
• --strategy auto is the default. Choose the repository-consistent strategy from observed evidence. A requested explicit strategy is still rejected if unsafe or incompatible with repository policy.
• /GitCleanup without --apply MUST NOT delete, prune, reset, force-delete, or rewrite anything.
• /GitCleanup --apply may remove only candidates that are clean (as references/commands.md section 6 defines it), not in progress, free of ignored files, fully integrated or otherwise explicitly disposable, have no active owner/dependent lane (a linked worktree whose owner is not recorded stays UNKNOWN), and contain no unique unpreserved work. It never touches main, the integration target, or the invoking worktree, and never runs a repository-wide git worktree prune. Never use forced deletion merely to make cleanup succeed.
• /GitConverge without --apply MUST NOT merge, switch, delete, prune, or fetch anything.
• /GitConverge <branch> --apply is the user's explicit acceptance of the source tips in the plan that run records and reports (or in an earlier GitConverge preview in the same conversation). That acceptance stands in for per-lane review of exactly those tips; it is not permission to write any branch other than <branch>, to move, reset, or delete main, to push or delete remote branches, to touch a worktree with an active owner (references/commands.md section 6), or to bypass the gates in references/commands.md section 6. If a gate fails, stop and report; never force.
• /GitSweep without --apply MUST NOT merge, switch, delete, prune, fetch, or contact the network. /GitSweep <branch> --apply is /GitConverge <branch> --apply (same acceptance, gates, and local deletion rules) followed by deletion of remote branches already merged into a branch the remote keeps; for GitSweep, that acceptance also covers the remote deletions in its recorded plan, which the GitConverge rule above excludes, and, with --push, the publish of <branch>. It is the only command allowed to delete remote branches, one named branch at a time with git push --recurse-submodules=no --force-with-lease=<ref>:<sha> <remote> :<ref>. It is also the only command that pushes commits, and only with --push: one fast-forward git push --recurse-submodules=no --no-follow-tags <remote> refs/heads/<branch>:refs/heads/<branch> after the converge phase, never forced, never --no-verify, and refused when the live remote branch is not an ancestor of the local one, when <branch> is main or the remote default, when the converge phase stopped or its validation failed, or when the remote sweep is UNKNOWN; without --apply the preview only predicts it. It never pushes other commits or tags, never force-pushes, never lets a push reach a repository other than <remote> or recurse into submodules, runs every git command as an argument list and never as a shell string, never deletes the remote default, main, the target's remote branch, or a branch with a long-lived role, and deletes nothing remote when the converge phase stopped. Its preview ends with a readiness verdict (ONE_SHOT, PARTIAL or BLOCKED), a recommended command that carries exactly the flags that lift something, and the remaining items with their remedies; its apply report ends with the run state COMPLETE or PARTIAL and, for PARTIAL, a Next preview: line and a Next command: line. See references/commands.md section 7.
• /GitPlan without --apply (and without --release) MUST NOT register, create, merge, switch, fetch, or contact the network: it reads the repository, runs only the guard's read-only calls (version, list, set-show, set-plan --dry-run), and writes only a scratch spec file outside every worktree. /GitPlan <set> --into <branch> --apply registers exactly the plan that a preview of the same set earlier in the conversation showed (its spec, byte for byte), writing the lane claims and the set record only through magos_guard.py set-plan; --create also creates the registered lane branches and worktrees from the recorded base SHA and nothing else. set-plan also registers a claim for the integration branch agent/<set>/integration, which is why a plain git switch -c may create that branch in a guarded repository; while the set exists, a plain plan that would write the claim of one of its lanes or of its integration branch (an amend, the re-plan after an override, and also where that claim is missing or carries no set=; of a record the guard cannot read or that a newer MAGOS wrote only the integration branch agent/<set>/integration is known, so a lane counts only through the set= line of its claim) or a plain release of one of its claims is refused (exit 14, exit 16), so the set changes only through this command. /GitPlan <set> --converge --apply is the user's acceptance of the recorded lane heads: it merges them in dependency order into agent/<set>/integration only (created with git switch -c from the current target tip; a denial of that creation is quoted and stops the run), records each with set-update, stops on a conflict, runs the repository's normal checks, and with --land makes one --ff-only merge of that branch into <branch> while <branch> still sits at the integration start; --release removes the claims and the record through set-release. It never pushes, force-pushes, deletes a branch or worktree, touches main, uses override, rebases, squashes, or resolves a conflict by ours/theirs, and runs every git and guard command as an argument list. See references/commands.md section 8.
• /GitPlan lists the plan in two tables that are rendered from the spec the guard proved and its set-plan --dry-run result (a preview), or from the set record (afterwards), never from memory: the requirements of the task (requirements: id, text, with the lanes that serve each one and the outcome they deliver) and the lanes (branch, worktree, owned files, dependencies, acceptance; --status and --converge add State and Head columns). Every requirement is served by a lane and every lane serves a requirement (exit 24 otherwise). A lane id is a topic slug that names the subject of the change in 1 to 3 words (claim-store, sweep-readiness; [a-z0-9][a-z0-9-]{0,23}), never an ordinal, generic or reserved name (l1, lane-2, task3, integration); the lane branch is exactly agent/<set>/<id> and its worktree directory name ends with -<set>-<id>, and the guard refuses any other spelling with exit 24. When a lane is recorded integrated the guard stores a summary of what it changed (changes: commits, subjects, more, files, insertions, deletions, paths, paths_more), and the converge apply report, --release and, once a lane is integrated, --status and --converge print the original two tables again supplemented with it: a Changes column, a Result column, a Changes summary list with one bullet per lane, and a total line.
• /GitProtect writes no branch and no repository content: it sets or lifts the protection of one branch in the guard's state through the user-only guard subcommand protect, which runs only with the user's approval (the host's own approval prompt or the user's own terminal, at every approval level, --release included); --status only reads, through protect-show. While a branch is protected, the guard's hook refuses every write to it that an agent makes through a hooked tool (commit, merge, pull, cherry-pick, revert, rebase, reset, am, update-ref, branch -f/-m/-M/-d/-D, checkout -B, switch -C, worktree add of it, a fetch or local push into it, and a write whose target cannot be read); reads, checking it out and creating other branches from it stay allowed. A refusal is final for the agent: report it, work on another branch, and leave the merge into the protected branch to the user; never lift the protection, retry in another form, or edit .git/magos to make a write pass. See references/commands.md section 9 and references/lane-split.md section 15.
• All nine commands accept --lang <language>: it sets the language of every reply (Chinese when absent) and never translates command names, options, branch or worktree names, paths, SHAs, or status codes. See references/commands.md.
• When a target name is ambiguous between a branch and worktree, resolve it from observed repository state; if ambiguity materially changes the action and cannot be resolved safely, report the ambiguity instead of guessing.

Load references/commands.md when command-specific arguments, output contracts, or safety behavior are needed.

Operating Invariants

1. One active lane = one writable workspace. Never run parallel writers in the same checkout.
2. The integration branch is not a worker workspace. Workers change only their assigned lane.
3. One lane has one write owner at a time. Transfer ownership explicitly.
4. Every managed lane records: task, owner, base branch, base SHA, dependencies, acceptance criteria.
5. Evidence beats claims. Repository state and executed checks determine readiness.
6. Rewrite only rewrite-safe history. Published/shared/dependency-source history is not rewritten by default.
7. Integration is serialized. Only one actor writes the protected integration branch at a time.
8. Reconnaissance is non-destructive by default. Investigate before mutating.
9. Unknown is not safe. Do not infer ownership, remote freshness, semantic dependencies, or merge safety without evidence.
10. A lane's files are planned before the lane exists. Where the lane guard is installed, creating a branch or worktree needs a registered file manifest; overlap with another branch or worktree is denied at creation and every conflicting branch is named (references/lane-split.md). Existing lanes are never stopped. The guard needs Git 2.36+ (the commands need 2.30+).

Branch Strategy

This skill does not impose one branching model. The repository's existing model and policy are authoritative; the skill makes that model explicit, checks that it is safe for parallel writers, and proposes the smallest change when it is not.

1. Observe first. Classify the model the repository actually follows from refs, tags, merge history, and policy files. A branch name alone proves no role, owner, or status.
2. Keep roles distinct. A branch is an integration branch, a lane (one task, one writable worktree), a long-lived staging/release branch, an archive, or unknown when the evidence does not decide. A branch playing two roles (a worker writing to the integration branch) is a finding.
3. Default when no model exists: a protected integration branch plus short-lived lanes cut from its current tip, integrated through the gates below, then retired. Add a long-lived branch only for a stated need, with one owner and a hub-and-spoke flow (it merges into the integration branch and syncs from it, never peer to peer).
4. Lifetime is a cost. The longer a lane lives, the further it drifts. Prefer integrate-or-retire; sync by rewrite safety (this file's section 6, Sync Safely).
5. Names are an interface; a name alone is not evidence. Follow the repository's convention; otherwise agent/<task-id>-<short-name>. Avoid names that collide by case, shadow a tag, or clash as a ref prefix.
6. Strategy advice is advisory. Never rename, move, delete, or reconfigure branches, local or remote, as part of giving it. Deleting and merging go through the explicit commands and their gates; no command renames a branch, so a rename is a manual step after dependents are coordinated.

Load references/branch-strategy.md for model classification, the fit checklist, release/hotfix flow, protection, naming, and the report format.

1. Repository Reconnaissance

When advice depends on current Git state, perform a read-only survey before proposing changes.

Quick Scan

Collect at minimum:

• repository root and current HEAD/branch;
• all linked worktrees, paths, branches, HEADs, detached/locked/prunable state;
• local branches, commit IDs, upstreams, tracking status, and recent activity;
• dirty/untracked/unmerged state for relevant worktrees;
• likely integration target and whether that target is confidently known.

Prefer stable machine-readable Git output such as:

git rev-parse --show-toplevel
git status --porcelain=v1 --branch --untracked-files=normal
git worktree list --porcelain
git for-each-ref --sort=-committerdate --format="%(refname:short)%09%(objectname:short)%09%(upstream:short)%09%(upstream:track)%09%(committerdate:iso8601)" refs/heads
git remote -v
git symbolic-ref --quiet --short refs/remotes/origin/HEAD

For each relevant linked worktree, inspect its local state with git -C <path> status --porcelain=v1 --branch --untracked-files=normal (without the flag, status.showUntrackedFiles=no hides untracked files).

Do not assume main is the integration target. Infer it from repository policy/configuration or clearly report uncertainty.

Deep Scan

Only when needed for a decision, compare candidate branches with the integration target using:

git rev-list --left-right --count <target>...<branch>
git merge-base <target> <branch>
git merge-base --is-ancestor <branch> <target>
git diff --name-only <target>...<branch>
git log --oneline --decorate <target>..<branch>

Use these to determine ahead/behind state, whether a branch is already integrated, likely changed-file overlap, and the commits unique to a lane.

Git topology can prove commit ancestry; it cannot by itself prove business/semantic dependency. Label inferred dependencies separately from recorded dependencies.

Remote Freshness

Local reconnaissance does not prove remote freshness. Do not silently hide a network mutation inside a “read-only” survey.

• If local state is sufficient, advise from local facts and mark remote freshness as unknown where relevant.
• If the user asks for current remote truth, or an integration decision requires it, refresh remotes with the environment's authorized Git workflow (for example git fetch --prune) before final advice.
• If network access is unavailable, say the recommendation is based on local remote-tracking refs.

Reconnaissance Output

Before recommendations, summarize the observed state compactly:

Integration target: <branch@sha | uncertain>
Worktrees: <count>; dirty: <count>; detached: <count>; prunable: <count>
Active branches: <count>; diverged: <count>; merged candidates: <count>
Remote freshness: current | local-only | unknown
High-risk findings: <items>

Then provide prioritized recommendations with the evidence behind each recommendation. Load references/reconnaissance.md for the full classification and advice matrix.

2. Preflight for New Work

Before creating anything:

• detect whether the harness already provided an isolated workspace; prefer harness-native isolation;
• inspect current branch/worktree state and existing lane ownership;
• require a clean or explicitly understood baseline;
• run the repository's normal baseline checks and record pre-existing failures;
• capture <base-branch> and <base-SHA>;
• plan the new lane's files first: check, then plan (references/lane-split.md): always for a worktree, and for a branch once other lanes exist; a denial names the conflicting lanes.

Do not create a nested/redundant worktree when already isolated.

3. Plan Lanes as a Dependency DAG

Parallelize only independently reviewable work.

A ──┐
B ──┼─> integration
C ──┘

A -> B    means B depends on A

If B is based on A, record that edge. Once another active lane depends on A's commit IDs, treat A as rewrite-frozen unless all dependents are explicitly retargeted.

When recommending a new lane, first inspect existing worktrees/branches and reuse an appropriate clean idle lane only if ownership, base, and scope are compatible. Otherwise create a new isolated lane.

4. Create the Lane

Use one branch/worktree per lane, for example:

agent/<task-id>-<short-name>

Fallback when no native isolation exists:

git worktree add <path> -b agent/<task-id>-<short-name> <base-branch>

Register the lane's manifest first (magos_guard.py plan --branch agent/<task-id>-<short-name> --paths <files>) as its own step, then create exactly that branch; release the claim when the lane is integrated or abandoned. When the guard denies the creation, report the denial and ask the user first: an override needs the user's approval, given as a click in the host's own approval prompt (Claude Code's permission dialog, Codex's magos_approve dialog, Hermes' approval prompt) or in the user's own terminal (references/lane-split.md sections 6 and 10).

Keep unrelated refactors outside the lane unless approved as separate scope.

5. Implement with Integratable Commits

Checkpoint commits are allowed. Prefer logical commits that are understandable, reversible, and dependency-clear.

Do not combine unrelated changes when selective integration may be needed later.

Before handoff, identify which commits depend on earlier lane commits.

6. Sync Safely

Fetch/refresh the integration target as required by repository policy before final review.

Choose synchronization by rewrite safety:

• Private lane, no downstream consumer: rebase onto the integration branch.
• Published lane or dependency source: do not casually rebase; merge the integration branch into the lane, or coordinate/retarget every dependent lane.
• Architectural incompatibility: stop and return the lane to planning rather than forcing conflict resolution.

Resolve conflicts in the lane, then re-run validation.

7. Validation and Independent Review

A lane is not READY until required build/test/lint/type/security checks pass and the diff contains no accidental scope, secrets, generated junk, or environment artifacts.

For non-trivial work, separate:

• Worker: implementation;
• Reviewer: requirement/scope/design/code review;
• Verifier: executes checks independently when practical;
• Orchestrator: dependency and integration decisions.

A worker's statement that tests passed is not evidence by itself.

8. Approval and Freshness Gate

Use states:

PLANNED -> ACTIVE -> READY -> APPROVED -> INTEGRATING -> INTEGRATED
                      \-> BLOCKED / REJECTED

Before writing the integration branch:

1. acquire exclusive integration ownership / merge-queue position;
2. refresh required refs;
3. confirm the reviewed lane HEAD is unchanged;
4. confirm the integration target is unchanged since approval;
5. if either changed, sync and re-run affected validation/review before integration.

Never integrate a stale approval.

9. Choose the Integration Operation

Before cherry-picking, verify selected commits do not depend on rejected commits. When uncertain, apply the candidate set to a temporary integration candidate and validate it there.

Do not invent a per-agent merge policy; follow repository policy.

10. Conflict Policy

Never resolve by blindly choosing ours or theirs.

Preserve current integration behavior unless requirements intentionally replace it, then reapply the lane's intended semantics and test the result.

If integration itself produces a non-trivial semantic conflict, return it to the responsible lane or designated integrator rather than improvising on the protected branch.

11. Post-Integration Gate

After merge/cherry-pick/squash merge:

• validate the integration branch again;
• record source lane and integrated commit(s);
• only then mark INTEGRATED;
• cleanup the worktree/branch when no active dependency needs it.

If a shared result later fails, use revert; do not rewrite protected history by default.

Handoff Contract

Every lane must provide:

Task:
Owner:
Branch / Worktree:
Base branch / Base SHA:
Current HEAD:
Dependencies:
Commits + dependency notes:
Files changed:
Validation commands + results:
Known risks:
Recommended integration: merge | squash-merge | cherry-pick <commits> | reject

Hard Stops

Never:

• let parallel agents edit the same writable checkout;
• create a branch or worktree without a registered file manifest where the lane guard applies, or bypass, disable or edit the guard (override, arm, disarm, install, protect, magos.* config, core.hooksPath, GIT_CONFIG_*, .git/hooks, .git/magos) on your own: the user decides. override, arm, disarm, install and protect run only with the user's approval: a click in the host's own approval prompt (Claude Code's permission dialog; in Codex the dialog of the MCP tool magos_approve, where the user ticks Approve and accepts; Hermes' approval prompt), the user's own terminal, or, in Claude Code and Hermes, for arm and for install into the default guard home without --allow-downgrade, the standing approval the user gives by setting magos.approval to auto-safe; override, disarm and protect always need the click or the terminal, and in Codex all five do. Never start the guard's mcp subcommand yourself: only the host starts that server. Never run its hook subcommand either, and write the guard's subcommand as one plain word in the command (plan, check, list, ...), never through a variable, a command substitution or xargs: the hook denies every other form. magos.* config, magos.approval included, is written only by the user;
• delete a lane that holds an open guard claim as if it were unowned;
• give repository-specific branch/worktree advice without inspecting available state first;
• recommend a branching model or branch restructure without first classifying the model the repository actually follows;
• impose a long-lived branch model (for example gitflow-style) where the repository has none and no need was shown;
• assert remote branch-protection settings that local Git cannot show;
• mutate/reset/delete/prune branches or worktrees during reconnaissance merely to make the topology cleaner;
• infer that an old branch is disposable solely from age;
• infer semantic independence solely from non-overlapping commit topology;
• let a worker bypass the review/integration gate onto a protected branch;
• rewrite a dependency-source branch without coordinating dependents;
• force-push or destructively reset shared history by default;
• integrate because an agent merely says "done";
• cherry-pick without dependency checking;
• integrate from an approval whose lane HEAD or target branch has changed.

For planning lane files and the creation guard, read references/lane-split.md. For explicit command contracts, read references/commands.md. For repository investigation and recommendation rules, read references/reconnaissance.md. For branching-model design or audit, read references/branch-strategy.md. For edge cases and the full operation matrix, read references/decision-matrix.md. For lifecycle data, read references/handoff-and-state.md. For rationale and source patterns, read references/design-rationale.md only when needed.