Single-Push Multi-Agent Git Workflow Kit

Three concurrent AI agents, each doing meaningful work — and then three near-simultaneous pushes that trigger three parallel deploys, each one stepping on the last. That is the exact failure mode this kit exists to prevent. The Single-Push Multi-Agent Git Workflow Kit is a WOWHOW framework for teams and solo developers who orchestrate multiple AI coding agents (Claude Code, GitHub Copilot Workspace, Cursor background agents, or custom Agent SDK pipelines) against a single shared repository. It packages a battle-tested pre-push gate script, the WOWHOW Single-Push Protocol playbook, and a coordination checklist into one deployable zip.

What You Get

• README.md — Quick-start and philosophy. Explains the root problem, the three failure classes (race-on-compose, split-brain cron, duplicate liveness kill), and how the kit resolves each one. Get to working state in under 10 minutes.
• pre-push-gate.sh — Drop-in pre-push hook. A shell script that goes in .githooks/pre-push. Runs a configurable build verification command (defaults to next build --no-lint), checks for an in-progress deploy lock on the remote host, and aborts the push if a concurrent deploy is already running. Includes a SKIP_BUILD=1 emergency override for genuine hotfixes. Not a wrapper — the actual hook logic with comments explaining every guard.
• single-push-protocol.md — The WOWHOW Single-Push Protocol playbook. Six named rules with the production incident that inspired each one. Covers: concurrency group configuration in GitHub Actions, how to batch all agent output into one commit before pushing, the snapshot-before-build ordering invariant, and why public URL health checks break during Traefik re-discovery windows (and what to use instead). The framework is named and explained as original WOWHOW IP — not a generic CI/CD tutorial.
• agent-coordination-checklist.md — Pre-push checklist for multi-agent sessions. A 12-point checklist you run before every push when agents have been working in parallel. Checks include: verifying no uncommitted agent output exists in other worktrees, confirming only one branch is ahead of main, confirming deploy lock file is absent on the VPS, and checking that the concurrency group in your workflow file matches the required format. Copy into your repo wiki or run as a manual gate step.
• workflow-concurrency-snippet.yml — GitHub Actions concurrency block. The exact YAML snippet to paste into your deploy workflow. Includes the cancel-in-progress: false setting (not true — the difference matters: cancelling in-progress lets intermediate pushes win over the latest, which is the opposite of what you want) and a comment explaining the queuing behavior.

How to Use

Start with the README to understand which of the three failure classes applies to your stack. Most projects hit Class 1 (concurrent GH Actions SSH sessions) or Class 2 (agent worktrees pushing independently). Class 3 (split-brain cron + CI racing) requires the full playbook.

Copy pre-push-gate.sh to .githooks/pre-push and run chmod +x .githooks/pre-push && git config core.hooksPath .githooks. Edit the four config variables at the top of the file: your build command, your lock file path, your VPS SSH alias (or leave blank to skip remote lock check), and your SKIP_BUILD env var name.

Paste the concurrency snippet from workflow-concurrency-snippet.yml into your deploy workflow under the jobs: top-level key — not inside a job. If you already have a concurrency block, compare it against the snippet: the group name must be consistent across all workflows that touch the same deploy target.

Before your next multi-agent session, run through agent-coordination-checklist.md at the end, not the beginning — it is a pre-push gate, not a session-start ritual. The checklist assumes agents have already committed their work into a staging branch; it validates the merge and push are safe.

Read single-push-protocol.md once in full. The six rules are short. The incident notes are specific. You will recognize at least one scenario from your own deploy history.

Who This Is For

• Developers running Claude Code, Cursor, or Copilot Workspace with multiple background agents working in parallel on the same repo
• Teams using GitHub Actions for continuous deployment who have seen concurrent workflow runs step on each other
• Anyone who has experienced a 502 caused by two deploys racing on docker compose down and docker compose up
• Solo founders with automated pipelines (auto-blog, cron-triggered code changes) that push to main and trigger deploys on their own cadence
• Engineers who use git worktrees to isolate agent workspaces and need a coordination layer before the final merge push

The pre-push hook in this kit does not require any additional tooling beyond bash and git. The GitHub Actions snippet works with any self-hosted or cloud runner. Both are designed to stay in place permanently — not as temporary scaffolding. Browse more developer workflow tools at wowhow.cloud/browse, or check the free tools collection at wowhow.cloud/tools for related utilities.