Multi-agent repository operations

Build a control plane in which agents work in parallel but integration is serialized. Do not solve coordination by repeatedly merging the moving default branch into every task branch.

The durable system has four layers:

1. A launcher creates a unique branch and linked worktree before an agent starts.
2. Repository-local AGENTS.md files state the project-specific contract.
3. Impact planning, stable gates, and exact-SHA evidence enforce the contract.
4. One identity owns the final merge lane.

Instructions alone are not enforcement. Prefer executable checks and server-side permissions for every invariant whose violation can corrupt the default branch or restart expensive qualification.

Requirements

Local helpers require Git, Bash, and standard POSIX command-line utilities. GitHub inspection and rollout require an authenticated gh CLI. Non-GitHub repositories can still use the local worktree, contract, and qualification model. Audit mode is read-only.

Select the mode

• Audit: inspect an existing repository and report gaps without writing.
• Bootstrap: add the smallest useful control plane through an isolated worktree and pull request.
• Operate: create a task worktree or explain the normal agent lifecycle.
• Integrate: qualify and merge a frozen candidate. Treat remote settings, labels, checks, and merges as external mutations requiring user authorization.

If the request is only to find an Actions cost regression, keep the scope to cost diagnosis rather than bootstrapping this entire system.

Start with evidence

For an existing repository, run the read-only audit from this skill directory:

bash scripts/audit-repo.sh /absolute/path/to/repository [owner/repository]

Inspect existing AGENTS.md, contributor docs, worktree state, workflows, branch protection, repository plan, and dirty changes before proposing edits. Preserve unrelated work and existing policy. A simple repository with two agents and fast tests does not need a custom merge service.

Read references/control-model.md when choosing the coordination model. Read references/agents-contract.md when creating or revising repository instructions. Read references/github-rollout.md before changing GitHub settings or CI.

Bootstrap in this order

1. Create a dedicated setup worktree. Never edit a shared or dirty checkout.
2. Record the current default-branch SHA and existing protections.
3. Add a short root AGENTS.md with only repository-specific rules.
4. Add deterministic impact and policy tests before optimizing the workflows.
5. Make required gates stable: every pull request reports a conclusion, while unaffected work exits cheaply inside the workflow.
6. Separate automatic deterministic checks from long or premium qualification.
7. Store qualification as evidence for one exact source SHA.
8. Add a semantic-overlap check for movement of the default branch.
9. Establish one merge identity and an ordered ready queue.
10. Observe the new gates green on a real pull request.
11. Only then enable required checks and branch restrictions.

Do not switch on branch protection against check names that have never reported success. Do not make "branch must be up to date" the coordination mechanism in a busy repository.

Non-negotiable invariants

Isolate work

• One task, one branch, one linked worktree.
• Never reset, clean, reuse, or delete another agent's worktree or branch.
• The launcher should place the agent in its worktree; do not rely on the agent remembering to create one after it starts.

When authorized to start a task, the included helper creates a worktree without deleting or overwriting anything:

bash scripts/create-agent-worktree.sh TASK-ID [base-ref] [destination-parent]

Run bash scripts/agent-preflight.sh [repo-path] at the start of agent work. Add --require-clean when checking a newly created worktree.

Wire isolation into the orchestrator before starting the agent; an instruction to an already-running agent is too late. Use porcelain mode to obtain the directory for the session's cwd:

task_path="$(bash scripts/create-agent-worktree.sh --porcelain TASK-ID BASE-REF WORKTREE-PARENT)"
launch-agent --cwd "$task_path"  # replace with the orchestrator's real command

If the orchestrator cannot set the initial working directory, wrap its launch command or reject the launch. Record that real wrapper command in AGENTS.md.

Qualify immutable revisions

Run the read-only context helper from this skill directory and record all three values:

bash scripts/qualification-context.sh /absolute/path/to/task-worktree

Checks, artifacts, reviews, and merge commands must refer to QUALIFIED_HEAD, not a moving branch name. A later push creates a new candidate. Metadata events on an unchanged pull request must not manufacture or invalidate evidence.

Run long or premium tests only after deterministic checks pass. Trigger them once for the frozen affected candidate. The expensive trigger must not cancel, skip, or replace the ordinary checks.

Treat movement of the default branch semantically

Being behind the default branch is not itself a failure. Before integration, compare changes since QUALIFIED_BASE against the candidate:

• Same files, textual conflicts, shared infrastructure, owned workspace, transitive dependency, or unresolved graph edge: integrate once and requalify the affected candidate.
• Proven disjoint: retain the frozen head and its evidence.

The overlap implementation must fail closed for unknown ownership, root build entry points, shared CI, and dependency edges it cannot resolve.

Serialize integration, not development

Agents may develop, test, review, and qualify concurrently. One integrator owns the state transition into the default branch. The merge command must protect the expected head SHA.

If multiple products are independent, use domain lanes: unrelated lanes may keep moving while a candidate requalifies, but a later overlapping candidate may not overtake it.

When agents share one GitHub user or token, documentation cannot distinguish a developer from the integrator. Use a separate GitHub App, machine user, or token, and enforce the distinction on the server.

Deliverables

A complete bootstrap normally produces:

• a concise root AGENTS.md and narrowly scoped nested files when needed;
• a machine-readable ownership/integration configuration when the graph is too complex for path conventions alone;
• worktree launcher and preflight commands;
• executable policy and impact tests;
• stable deterministic and qualification gates;
• a ready-state protocol and one merge actor;
• a staged GitHub settings plan;
• a short operational document with measured CI baseline and rollback.

Keep each artifact independently useful. Do not copy generic skill prose into every repository. The skill supplies the method; the repository records only its own commands, domains, risks, and authorities.

Safety boundaries

• Audit mode is read-only.
• Do not change billing, credentials, branch protection, environments, repository permissions, or merge state unless the user requested that mutation.
• Resolve exact targets before remote changes and verify the persisted result.
• Apply settings in reversible stages, with branch protection last.
• Stop after one infrastructure retry on the same SHA unless the user explicitly asks for monitoring.
• Never bypass missing qualification with an admin merge merely to finish the setup.