feat: git queue setup — interactive onboarding, subsuming protect and hooks

One command walks through every optional integration, asking permission
per step: (1) the git hooks (auto-requeue + Stable-Commit-Id stamping),
(2) the advisory merge-order gate, (3) the Claude Code skill — embedded
in the binary and written to ~/.claude/skills when Claude Code is
detected — and (4) a marker-delimited git-queue section in the repo's
AGENTS.md when other agent CLIs (Codex, Cursor, Gemini, Windsurf,
Copilot) are detected, AGENTS.md being the cross-agent convention they
read. --yes accepts the repo-local steps non-interactively (agent
integrations always ask); --undo reverses all four. protect and hooks
are removed as commands (their machinery lives on inside setup).

Author: freshtonic

README.md

@@ -60,8 +60,8 @@ To have a plain `git commit`/`git commit --amend` on a queue branch
 automatically requeue its descendants, install the git hooks (per repository):
 
 ```sh
-git queue hooks install     # writes post-commit / post-rewrite hooks
-git queue hooks uninstall   # remove them
+git queue setup             # interactive: hooks, gate, agent skills
+git queue setup --undo      # reverse it all
 ```
 
 Without the hooks, use `git queue commit` / `git queue amend` explicitly.
@@ -148,16 +148,15 @@ git queue create fix-a --base release-1.2            # base named explicitly
 | `git queue reword [<commit>]` | Rewrite a commit message and update descendants (defaults to HEAD). |
 | `git queue move <c>[..<c>] --new-parent <c>` | Move a commit (or an inclusive range) elsewhere in the queue — within one PR or across PRs. Commits can be named by revision or `Stable-Commit-Id` (unique prefix ok). Everything after the removal and insertion points is requeued; conflicts persist as markers. |
 | `git queue requeue` (`restack`) | Requeue the current branch's descendants onto its tip. |
-| `git queue hooks install` / `uninstall` | Make plain `git commit`/amend auto-requeue descendants and stamp `Stable-Commit-Id` trailers on new queue commits. |
 | `git queue sync [--no-push]` | Pull remote commits, drop branches whose PRs have merged (reparenting their children), requeue onto the latest base, push back with `--force-with-lease`, and reconcile the PRs of every published queue (open missing ones, revive closed ones, fix bases/titles/queue maps). |
 | `git queue submit [--draft]` (`push`) | Push the current queue line and open/update its numbered PRs (revives a child PR GitHub closed when its base was deleted). |
 | `git queue yank` | Close every open (non-merged) PR in the current queue. |
-| `git queue protect` | Enable merge-order signalling (a red/green commit status per PR) for this repo. |
+| `git queue setup [--yes] [--undo]` | Interactive, per-step setup: git hooks, merge-order gate, the Claude Code skill, and an `AGENTS.md` section for other agents. `--undo` reverses everything. |
 | `git queue doctor` | Report whether merge-order signalling is enabled (read-only). |
 
 ### Signalling merge order
 
-Run `git queue protect` once to warn reviewers off merging PRs out of order. It
+Enable the gate via `git queue setup` to warn reviewers off merging PRs out of order. It
 sets a local flag (`queue.gate = status`) — no GitHub setup, workflow, ruleset,
 or admin rights required. With it on, `git queue submit` posts a
 `git-queue/merge-order` commit status on every open PR in the queue: green ✓
@@ -195,7 +194,7 @@ stable identity: a `Stable-Commit-Id:` trailer in the commit message (the same i
 Gerrit's `Change-Id`), minted once and carried by git itself through every
 rebase, cherry-pick, replay and amend.
 
-- `git queue commit` stamps one automatically, and `git queue hooks install`
+- `git queue commit` stamps one automatically, and `git queue setup`
   adds a `commit-msg` hook so plain `git commit` on a queue branch does too.
   Commits off the queue are never touched.
 - `git queue track` offers to stamp the branch's existing commits (with a
@@ -260,7 +259,7 @@ what you're doing:
 Branches left holding persisted conflict markers are shown with `⚠ conflict
 markers` in `git queue status`. Search for `<<<<<<<`, resolve, and commit.
 
-Prefer plain `git commit`? Run `git queue hooks install` and a post-commit /
+Prefer plain `git commit`? Run `git queue setup` and a post-commit /
 post-rewrite hook will call `git queue requeue` for you (the hooks are guarded
 against recursion and no-op off a queue).
 
@@ -280,7 +279,7 @@ State lives in the repository's own git config (nothing outside git):
 | `branch.<n>.queueParentSha` | Parent tip when `<n>` was last based — the rebase anchor used by `sync`. |
 | `branch.<n>.queuePr` | Cached PR number. |
 | `branch.<n>.queueDescription` | PR body text set by `git queue describe`. |
-| `queue.gate` | `status` once `git queue protect` enables merge-order signalling. |
+| `queue.gate` | `status` once `git queue setup` enables merge-order signalling. |
 
 (Conflict-marker state is **not** stored — `status` detects `<<<<<<<` in each
 branch's tip live, so it can never report a stale warning.)

index.html

@@ -52,9 +52,9 @@ below own that propagation.
 | One big branch → a queue | `git queue split` | Editor assigns commits to branches |
 | Adopt an existing branch AND divide it | `git queue track --split` (add `--stamp-ids` to skip the prompt) | track + stamp + split editor in one step |
 | Abandon a queue's open PRs | `git queue yank` | Closes every open (non-merged) PR in the queue |
-| Stop PRs merging out of order | `git queue protect` | Enables merge-order statuses on each PR (one-time) |
+| Stop PRs merging out of order | `git queue setup` (enable the gate step) | Red/green merge-order status per PR (advisory) |
 | Check enforcement is on | `git queue doctor` | Read-only report of the gate status |
-| Give commits stable identity across rewrites | `git queue hooks install`, `git queue commit`, or `git queue track --stamp-ids` for existing commits | Stamps a `Stable-Commit-Id:` trailer; powers safe sync (no self-conflicts) and squash-merge detection |
+| Give commits stable identity across rewrites | `git queue setup`, `git queue commit`, or `git queue track --stamp-ids` for existing commits | Stamps a `Stable-Commit-Id:` trailer; powers safe sync (no self-conflicts) and squash-merge detection |
 | Move around the queue | `git queue up` / `down`, `git queue status` | Navigate / view |
 | See every commit in the queue with its Stable-Commit-Id | `git queue log` | Status tree + indented per-branch commits, newest first |
 | Address a commit by its id | `git queue move q-3zz02424 --new-parent <rev>`, `git queue reword q-…` | Any commit argument accepts a `Stable-Commit-Id` (unique prefix ok), as shown by `git queue log` |
@@ -91,7 +91,7 @@ markers.
 
 ## Enforcing merge order
 
-To warn reviewers off merging PRs out of order, run `git queue protect` **once**
+To warn reviewers off merging PRs out of order, run `git queue setup` **once**
 per repo. It enables *status-based* gating (`queue.gate = status`) — no GitHub
 workflow, ruleset, or admin rights needed. Then `git queue submit` posts a
 `git-queue/merge-order` commit status on every open PR: green ✓ on the

skills/using-git-queue/SKILL.md

@@ -24,6 +24,179 @@ fn apply_status_gate(entries: &[Entry]) -> Result<()> {
     Ok(())
 }
 
+/// Ask a yes/no question on the TTY; `default_yes` decides bare Enter.
+fn confirm(question: &str, default_yes: bool) -> bool {
+    use std::io::Write;
+    print!("{question} [{}] ", if default_yes { "Y/n" } else { "y/N" });
+    std::io::stdout().flush().ok();
+    let mut answer = String::new();
+    std::io::stdin().read_line(&mut answer).ok();
+    match answer.trim().to_lowercase().as_str() {
+        "" => default_yes,
+        "y" | "yes" => true,
+        _ => false,
+    }
+}
+
+/// `git queue setup [--yes] [--undo]` — interactive, per-step opt-in setup:
+/// the git hooks, the merge-order gate, the Claude Code skill, and (when
+/// other agents are detected) an AGENTS.md section. `--yes` accepts the two
+/// repo-local steps non-interactively; the integrations always ask.
+pub fn setup(yes: bool, undo: bool) -> Result<()> {
+    git::ensure_repo()?;
+    if undo {
+        return setup_undo();
+    }
+    let tty = std::io::IsTerminal::is_terminal(&std::io::stdin());
+    if !tty && !yes {
+        bail!("`git queue setup` is interactive; pass --yes to accept the repo-local steps");
+    }
+    let ask = |q: &str| -> bool {
+        if tty {
+            confirm(q, true)
+        } else {
+            yes
+        }
+    };
+
+    // 1. Hooks.
+    if ask(
+        "Install the git hooks? (plain `git commit`/`--amend` auto-requeue descendants;
+new queue commits get a Stable-Commit-Id)",
+    ) {
+        hooks_install()?;
+    }
+    // 2. Merge-order gate.
+    if ask(
+        "Enable the merge-order gate? (submit/sync post a red/green commit status per PR
+so reviewers see which PR merges next)",
+    ) {
+        meta::set_gate("status")?;
+        println!("Merge-order gate enabled.");
+    }
+    // 3. Claude Code skill (only when Claude Code is present; interactive only).
+    let home = std::env::var("HOME").unwrap_or_default();
+    let claude_dir = std::path::Path::new(&home).join(".claude");
+    if tty
+        && claude_dir.exists()
+        && confirm(
+            "Claude Code detected. Install the `using-git-queue` skill so Claude drives
+git-queue correctly?",
+            true,
+        )
+    {
+        let dir = claude_dir.join("skills").join("using-git-queue");
+        std::fs::create_dir_all(&dir)?;
+        std::fs::write(dir.join("SKILL.md"), EMBEDDED_SKILL)?;
+        println!("Installed {}.", dir.join("SKILL.md").display());
+    }
+    // 4. Other agents -> AGENTS.md (the cross-agent convention).
+    let others: Vec<&str> = [
+        ("codex", ".codex"),
+        ("cursor", ".cursor"),
+        ("gemini", ".gemini"),
+        ("windsurf", ".windsurf"),
+        ("copilot", ".config/github-copilot"),
+    ]
+    .iter()
+    .filter(|(_, d)| std::path::Path::new(&home).join(d).exists())
+    .map(|(n, _)| *n)
+    .collect();
+    if tty
+        && !others.is_empty()
+        && confirm(
+            &format!(
+                "Detected other agents ({}). Add a git-queue section to this repo's AGENTS.md
+(read by Codex, Cursor, Copilot and most agent CLIs)?",
+                others.join(", ")
+            ),
+            true,
+        )
+    {
+        write_agents_md_section()?;
+    }
+    println!(
+        "
+Setup done. `git queue doctor` reports the current state."
+    );
+    Ok(())
+}
+
+fn setup_undo() -> Result<()> {
+    hooks_uninstall()?;
+    let _ = git::ok(&["config", "--local", "--unset", "queue.gate"]);
+    println!("Merge-order gate disabled.");
+    let home = std::env::var("HOME").unwrap_or_default();
+    let skill = std::path::Path::new(&home).join(".claude/skills/using-git-queue/SKILL.md");
+    if skill.exists() {
+        std::fs::remove_file(&skill).ok();
+        println!("Removed {}.", skill.display());
+    }
+    strip_agents_md_section()?;
+    Ok(())
+}
+
+const EMBEDDED_SKILL: &str = include_str!("../skills/using-git-queue/SKILL.md");
+const AGENTS_BEGIN: &str = "<!-- git-queue:agents:begin -->";
+const AGENTS_END: &str = "<!-- git-queue:agents:end -->";
+
+/// Idempotently write a marker-delimited git-queue section into AGENTS.md.
+fn write_agents_md_section() -> Result<()> {
+    let section = format!(
+        "{AGENTS_BEGIN}
+## git-queue (PR queues)
+
+         This repo uses git-queue for stacked/queued PRs. Rules:
+
+         - See `git queue --help` (man page) for every command; `git queue status`/`log` show the queue.
+         - Never hand-rebase a queue branch: use `git queue commit`/`amend`/`move`/`checkout`.
+         - After changing history, run `git queue sync` to requeue, push (lease) and refresh PRs.
+         - PRs merge front-first; never merge a PR whose `git-queue/merge-order` status is red.
+         - Commits carry `Stable-Commit-Id:` trailers — preserve commit messages when rewriting.
+         {AGENTS_END}
+"
+    );
+    let path = std::path::Path::new("AGENTS.md");
+    let existing = std::fs::read_to_string(path).unwrap_or_default();
+    let updated = match (existing.find(AGENTS_BEGIN), existing.find(AGENTS_END)) {
+        (Some(a), Some(b)) if b > a => format!(
+            "{}{}{}",
+            &existing[..a],
+            section.trim_end(),
+            &existing[b + AGENTS_END.len()..]
+        ),
+        _ if existing.is_empty() => section,
+        _ => format!(
+            "{}
+{}",
+            existing.trim_end(),
+            section
+        ),
+    };
+    std::fs::write(path, updated)?;
+    println!("Wrote the git-queue section of AGENTS.md.");
+    Ok(())
+}
+
+fn strip_agents_md_section() -> Result<()> {
+    let path = std::path::Path::new("AGENTS.md");
+    let Ok(existing) = std::fs::read_to_string(path) else {
+        return Ok(());
+    };
+    if let (Some(a), Some(b)) = (existing.find(AGENTS_BEGIN), existing.find(AGENTS_END)) {
+        if b > a {
+            let rest = format!("{}{}", &existing[..a], &existing[b + AGENTS_END.len()..]);
+            if rest.trim().is_empty() {
+                std::fs::remove_file(path).ok();
+            } else {
+                std::fs::write(path, rest)?;
+            }
+            println!("Removed the git-queue section of AGENTS.md.");
+        }
+    }
+    Ok(())
+}
+
 /// `git queue doctor` — report-only diagnostics for merge-order enforcement.
 pub fn doctor() -> Result<()> {
     git::ensure_repo()?;
@@ -40,10 +213,10 @@ pub fn doctor() -> Result<()> {
             println!("    on the ones behind it.");
         }
         Some(other) => {
-            println!("  ! gate: unknown mode `{other}` \u{2014} run `git queue protect` to (re)enable status mode");
+            println!("  ! gate: unknown mode `{other}` \u{2014} run `git queue setup` to (re)enable status mode");
         }
         None => {
-            println!("  \u{2717} gate: not enabled \u{2014} run `git queue protect` to turn it on");
+            println!("  \u{2717} gate: not enabled \u{2014} run `git queue setup` to turn it on");
         }
     }
 
@@ -58,32 +231,6 @@ pub fn doctor() -> Result<()> {
     Ok(())
 }
 
-/// `git queue protect` — enable status-based merge-order signalling.
-///
-/// A commit status is the one advisory GitHub mechanism that composes with
-/// base-chaining: it shows up in every PR's checks UI (red ✗ with "merge PR #N
-/// first") while leaving the PRs as normal, reviewable, non-draft PRs and
-/// never blocking pushes. Anything that actually disables the merge button
-/// requires base-branch rules, which also gate pushes to the queue branches.
-pub fn protect() -> Result<()> {
-    git::ensure_repo()?;
-    meta::set_gate("status")?;
-    println!("Enabled status-based merge-order signalling for this repository.\n");
-    println!(
-        "`git queue submit` now posts a `{}` commit status on every open",
-        render::GATE_CONTEXT
-    );
-    println!("PR in the queue: green \u{2713} on the front (mergeable) PR, red \u{2717} \u{201c}merge PR #N");
-    println!(
-        "first\u{201d} on every PR above it. As PRs land, `git queue sync` + `git queue submit`"
-    );
-    println!("promote the PR now at the front to green.\n");
-    println!("No GitHub setup or admin rights needed, and PRs stay normal (no drafts). The gate");
-    println!("is advisory: the red \u{2717} warns reviewers, but the merge button still works.");
-    println!("Run `git queue submit` now to apply it.");
-    Ok(())
-}
-
 /// `git queue create <name> [--base <branch>]` — new branch queued after the
 /// current one (or on an explicit `--base` branch).
 pub fn create(name: &str, base: Option<&str>, queue_flag: Option<&str>) -> Result<()> {
@@ -1433,7 +1580,7 @@ fn report_line(line: &Line, outcome: &LinePrs, heading: &str) -> Result<()> {
     let gate = meta::gate();
     let gated = gate.as_deref() == Some("status");
     if let Some(other) = gate.as_deref().filter(|g| *g != "status") {
-        eprintln!("warning: unknown queue.gate mode `{other}` — no merge gate applied; run `git queue protect` to enable status mode");
+        eprintln!("warning: unknown queue.gate mode `{other}` — no merge gate applied; run `git queue setup` to enable status mode");
     }
     if gated {
         apply_status_gate(&outcome.entries)?;
@@ -2089,7 +2236,7 @@ fn id_hook_snippet() -> String {
 }
 
 /// `git queue hooks install` — make plain `git commit`/amend auto-requeue.
-pub fn hooks_install() -> Result<()> {
+fn hooks_install() -> Result<()> {
     git::ensure_repo()?;
     let dir = std::path::PathBuf::from(git::out(&["rev-parse", "--git-path", "hooks"])?);
     std::fs::create_dir_all(&dir)?;
@@ -2102,7 +2249,7 @@ pub fn hooks_install() -> Result<()> {
 }
 
 /// `git queue hooks uninstall` — remove the git-queue hook blocks.
-pub fn hooks_uninstall() -> Result<()> {
+fn hooks_uninstall() -> Result<()> {
     git::ensure_repo()?;
     let dir = std::path::PathBuf::from(git::out(&["rev-parse", "--git-path", "hooks"])?);
     for name in ["post-commit", "post-rewrite", "commit-msg"] {