@rtorcato/repo-tooling 3.24.0 → 3.25.0

package/AGENTS.md

@@ -24,6 +24,7 @@ Every command supports `--json` and a non-interactive mode. Combine with `--yes`
 | `fix --dry-run` | ✅ | ✅ | Print what each fixer would write without writing. Combine with `--json`. |
 | `list --json` | ✅ | ✅ | Enumerate the library's surface area. Each entry has `{ name, description, exports, fixTarget }`. |
 | `copy <name>` | ✅ | text only | Copy a single preset (`biome`, `tsconfig`) into the current directory. |
+| `loop guard --root <path>` | ✅ | ✅ | Guard an `ai-issue-loop` tick: repair a wrongly-bare main checkout, gate the `node_modules` rebuild (`--removed`). Exit `0` continue, `1` repair failed, `2` root is not a repairable checkout — both non-zero halt the tick. |
 
 ## Recommended workflows
 
@@ -104,6 +105,7 @@ A fixer may also **refuse** — the target file holds something the generator ca
 - `src/cli/commands/doctor.ts` — all checks and the public `runDoctor(dir)` / `evaluateNodeVersion(version)` / `nextStepSuggestions(results)`
 - `src/cli/commands/fix.ts` — `Fixer` interface, fixer registry, `fixCommand`
 - `src/cli/commands/fix-targets.ts` — shared check → fix target map (used by both doctor's footer and fix's lookup)
+- `src/cli/commands/loop-guard.ts` — `loop guard`: the `--is-inside-work-tree` / `.git` invariant table and the `node_modules` rebuild gate, drained out of the ai-issue-loop skill's prose (#519)
 - `src/cli/generators/` — one file per concern (linting, testing, build, git, github-actions, security, misc)
 - `tooling/` — every shipped preset, mirrored 1:1 with `package.json` `exports`
 

package/README.md

@@ -91,6 +91,7 @@ See the [Getting Started guide](https://rtorcato.github.io/repo-tooling/guides/g
 | `copy <config>` | Copy a single config file into the current project. | `npx @rtorcato/repo-tooling copy biome` |
 | `doctor` | Diagnose an existing project for missing or drifted tooling. | `npx @rtorcato/repo-tooling doctor` |
 | `fix [target]` | Apply scaffolders for what `doctor` flagged (`--yes`, `--dry-run`, `--diff`). | `npx @rtorcato/repo-tooling fix` |
+| `loop guard` | Repair a main checkout that has gone `core.bare = true`, and gate the `node_modules` rebuild after a worktree removal. Exits `1` if the repair failed and `2` if the root is not a repairable checkout — see `--help`. | `npx @rtorcato/repo-tooling loop guard --root .` |
 
 Prefer to run the audit in CI? `doctor` also ships as a GitHub Action:
 
@@ -181,10 +182,11 @@ ln -sf ../../node_modules/@rtorcato/repo-tooling/tooling/claude/repo-tooling.md
 
 This repo is also a self-hosted Claude Code marketplace. Install the plugin to
 get six skills — `repo-tooling` (adopt/audit the presets via the CLI),
-`npm-publish` (never hand-cut a release), `ai-issue-loop` (the label-driven
-issue → PR pipeline), `ai-workflow` (burst the `ai-ready` queue in parallel
-worktrees), `ai-issue` (file agent-executable issues) and `ai-loop-status`
-(read-only pipeline status) — in any session:
+`npm-publish` (never hand-cut a release), `ai-workflow` (**the entry point** to
+the `ai-ready` issue → PR pipeline: bursts the queue in parallel worktrees, then
+schedules the engine below), `ai-issue-loop` (that engine — one stateless tick;
+it runs on a loop rather than being typed), `ai-issue` (file agent-executable
+issues) and `ai-loop-status` (read-only pipeline status) — in any session:
 
 ```
 /plugin marketplace add rtorcato/repo-tooling

package/dist/base/git-identity.js

@@ -44,6 +44,30 @@ const DETAIL = {
 const HINT = 'Commits made with this identity will not link to your forge account, and the address cannot be added as a verified secondary email to fix them retroactively (#327). Set a real one: `git config --global user.email you@yourdomain.com` — or per-repo, drop `--global`.';
 const CHECK = 'Git identity';
 const GIT_TIMEOUT_MS = 5_000;
+/**
+ * Git exports these to everything a hook runs, and they outrank `cwd`/`-C`: a
+ * child spawned from a `pre-push` answers about the *hook's* repository, not
+ * the directory it was handed. Harmless for a config read; not harmless for
+ * `loop guard`, whose whole job is deciding whether one specific checkout has
+ * gone bare (#519). Every caller here names its repo explicitly, so the
+ * ambient one is never what was meant.
+ */
+const AMBIENT_REPO_VARS = [
+    'GIT_DIR',
+    'GIT_WORK_TREE',
+    'GIT_INDEX_FILE',
+    'GIT_COMMON_DIR',
+    'GIT_OBJECT_DIRECTORY',
+    'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+    'GIT_PREFIX',
+    'GIT_NAMESPACE',
+];
+function repoScopedEnv() {
+    const env = { ...process.env };
+    for (const key of AMBIENT_REPO_VARS)
+        delete env[key];
+    return env;
+}
 /** Never rejects; a missing or failing git resolves to null. */
 export const realGitExec = (args, cwd) => new Promise((resolve) => {
     let settled = false;
@@ -56,7 +80,11 @@ export const realGitExec = (args, cwd) => new Promise((resolve) => {
     };
     // Args are internal constants, never user free-text — shell:false keeps
     // this injection-safe.
-    const child = spawn('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'] });
+    const child = spawn('git', args, {
+        cwd,
+        env: repoScopedEnv(),
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
     let stdout = '';
     const timer = setTimeout(() => {
         child.kill();

package/dist/cli/commands/loop-guard.js

@@ -0,0 +1,186 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import chalk from 'chalk';
+import fs from 'fs-extra';
+import { realGitExec } from '../../base/git-identity.js';
+/**
+ * The invariant table from the skill, verified on git 2.55.0:
+ *
+ * | repo state | `--is-inside-work-tree` | `.git` |
+ * |---|---|---|
+ * | healthy checkout | `true`, exit 0 | directory |
+ * | **wrongly bare** | `false`, **exit 0** | directory |
+ * | genuinely bare | `false`, exit 0 | absent |
+ * | linked worktree | `true`, exit 0 | file |
+ *
+ * Two things it encodes. **Stdout, not the exit code** — `rev-parse
+ * --is-inside-work-tree` exits `0` either way and only *prints* the answer, so
+ * an exit-code probe is dead code (`insideWorkTree` is `null` only when git
+ * itself failed, i.e. there is no repo here). And **`.git` must be a directory
+ * before repairing** — a genuinely bare repo prints `false` too, and nothing
+ * else separates the two. This ships to consumers' machines, where "repairing"
+ * someone's real bare clone is the damage rather than the fix.
+ */
+export function classifyRoot(insideWorkTree, gitEntry) {
+    if (insideWorkTree === null)
+        return 'not-a-repo';
+    if (insideWorkTree.trim() === 'true')
+        return 'work-tree';
+    if (gitEntry === 'directory')
+        return 'wrongly-bare';
+    // A linked worktree's `.git` is a file; its main checkout is where a repair
+    // belongs, and that is not the path we were handed.
+    if (gitEntry === 'file')
+        return 'linked-worktree';
+    return 'genuinely-bare';
+}
+/**
+ * `--frozen-lockfile` forbids re-resolution, so neither `pnpm-lock.yaml` nor a
+ * `pnpm-workspace.yaml` carve-out moves as a side effect of a cleanup.
+ * `--config.confirmModulesPurge=false` gets past
+ * `ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY` — which is why a bare `pnpm
+ * install` cannot repair this.
+ */
+export const REBUILD_ARGS = [
+    'install',
+    '--frozen-lockfile',
+    '--config.confirmModulesPurge=false',
+];
+const realInstall = (cwd) => new Promise((resolve) => {
+    // stdout stays clean for the `--json` payload; pnpm's diagnostics are
+    // still visible on stderr.
+    const child = spawn('pnpm', [...REBUILD_ARGS], {
+        cwd,
+        stdio: ['ignore', 'ignore', 'inherit'],
+    });
+    child.on('close', (code) => resolve(code === 0));
+    child.on('error', () => resolve(false));
+});
+async function gitEntryKind(root) {
+    // lstat, not stat: the file/directory distinction is the whole discriminator.
+    try {
+        const stat = await fs.lstat(path.join(root, '.git'));
+        return stat.isDirectory() ? 'directory' : 'file';
+    }
+    catch {
+        return 'absent';
+    }
+}
+/** `ai-*` directories one level down, in either place worktrees are kept. */
+async function findLive(dirs) {
+    const live = [];
+    for (const dir of dirs) {
+        // A missing worktree root is the normal case, not an error.
+        const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            if (entry.isDirectory() && entry.name.startsWith('ai-'))
+                live.push(path.join(dir, entry.name));
+        }
+    }
+    return live;
+}
+/** The sibling layout the skill uses: `<parent>/<name>-worktrees`. */
+export function defaultWorktreeRoot(root) {
+    return path.join(path.dirname(root), `${path.basename(root)}-worktrees`);
+}
+const stamp = () => new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+const UNUSABLE = {
+    'genuinely-bare': 'main checkout is a genuinely bare repository (.git absent) — refusing to flip core.bare on a real bare clone',
+    'linked-worktree': '--root points at a linked worktree (.git is a file), not the main checkout — repair belongs on the main checkout',
+    'not-a-repo': 'not a git repository',
+};
+/**
+ * One tick's worth of guarding, as data. The command wrapper prints it and
+ * sets the exit code; tests call this directly.
+ */
+export async function runLoopGuard(options = {}) {
+    const root = path.resolve(options.root ?? process.cwd());
+    const worktreeRoot = options.worktreeRoot
+        ? path.resolve(options.worktreeRoot)
+        : defaultWorktreeRoot(root);
+    const git = options.git ?? ((args) => realGitExec(args, root));
+    const install = options.install ?? realInstall;
+    const messages = [];
+    const state = classifyRoot(await git(['rev-parse', '--is-inside-work-tree']), await gitEntryKind(root));
+    let bare = 'healthy';
+    let exitCode = 0;
+    if (state === 'wrongly-bare') {
+        messages.push(`⚠ main checkout bare at ${stamp()} — repairing`);
+        // Writes $ROOT/.git/config, which a restrictive sandbox refuses with
+        // `error: could not lock config file .git/config`. Aborting beats
+        // reporting a healthy repo while it stays broken.
+        if ((await git(['config', 'core.bare', 'false'])) === null) {
+            bare = 'repair-failed';
+            exitCode = 1;
+            messages.push('⚠ repair FAILED — main checkout still bare');
+        }
+        else {
+            bare = 'repaired';
+            messages.push('main checkout repaired — core.bare is false');
+        }
+    }
+    else if (state !== 'work-tree') {
+        bare = 'unrepairable';
+        exitCode = 2;
+        messages.push(`⚠ ${UNUSABLE[state]}`);
+    }
+    else {
+        messages.push('main checkout is a work tree');
+    }
+    const live = await findLive([worktreeRoot, path.join(root, '.claude', 'worktrees')]);
+    const rebuild = await decideRebuild({ root, removed: options.removed === true, exitCode, live });
+    let outcome = rebuild;
+    if (rebuild === 'deferred') {
+        messages.push(`rebuild deferred — ${live.length} worktree(s) still live`);
+    }
+    else if (rebuild === 'rebuilt') {
+        messages.push('rebuilding the main checkout’s node_modules');
+        if (!(await install(root))) {
+            outcome = 'rebuild-failed';
+            // Not fatal: a broken .bin cannot corrupt a commit the way a bare
+            // checkout does. Loud, though — a silent skip is the breakage this
+            // guard exists to end.
+            messages.push('⚠ node_modules rebuild FAILED — main checkout may be unbuildable');
+        }
+        else {
+            messages.push('node_modules rebuilt');
+        }
+    }
+    return { root, worktreeRoot, state, bare, rebuild: outcome, live, exitCode, messages };
+}
+/**
+ * The three load-bearing conditions, kept separate from the run so a test can
+ * assert them without a pnpm install:
+ *
+ * - **`removed`** — set by every removal path, merged-PR cleanup *and* stall
+ *   reaping. A reaped worktree needs this most: its agent died mid-command.
+ * - **`pnpm-lock.yaml`** — non-pnpm repos skip the whole thing.
+ * - **no live worktrees** — the rebuild *purges* the shared modules dir, which
+ *   would be yanked out from under any agent still running in a surviving
+ *   worktree. Deferring costs a broken main checkout until the last worktree
+ *   clears; not deferring costs a live implementer run.
+ */
+export async function decideRebuild(input) {
+    if (!input.removed)
+        return 'not-requested';
+    // Nothing runs against a root we are about to halt the tick over.
+    if (input.exitCode !== 0)
+        return 'skipped-root-unusable';
+    if (!(await fs.pathExists(path.join(input.root, 'pnpm-lock.yaml'))))
+        return 'skipped-no-lockfile';
+    return input.live.length > 0 ? 'deferred' : 'rebuilt';
+}
+export async function loopGuardCommand(options) {
+    const result = await runLoopGuard(options);
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        console.log();
+        for (const line of result.messages) {
+            console.log(`  ${line.startsWith('⚠') ? chalk.yellow(line) : chalk.gray(line)}`);
+        }
+        console.log();
+    }
+    process.exitCode = result.exitCode;
+}

package/dist/cli/index.js

@@ -6,6 +6,7 @@ import fs from 'fs-extra';
 import packageJson from '../../package.json' with { type: 'json' };
 import { doctorCommand } from './commands/doctor.js';
 import { fixCommand } from './commands/fix.js';
+import { loopGuardCommand } from './commands/loop-guard.js';
 import { setupProject } from './commands/setup.js';
 import { copyPreset, PRESETS } from './utils/copy-preset.js';
 async function isSelfRepo(dir) {
@@ -346,6 +347,22 @@ program
     skillsDir: options.skillsDir,
     forceSkills: options.forceSkills,
 }));
+// Mechanics the ai-issue-loop skill used to describe in prose-with-shell (#519).
+// Deliberately outside the isSelfRepo hook below: the loop runs against this
+// repo like any other, and a guard that refuses here would guard nothing.
+const loop = program.command('loop').description('🔁 ai-issue-loop mechanics as tested commands');
+loop
+    .command('guard')
+    .description('🛡️  Repair a wrongly-bare main checkout and gate the node_modules rebuild')
+    .option('--root <path>', 'Main checkout the loop branches worktrees from', process.cwd())
+    .option('--worktree-root <path>', 'Where ai-* worktrees live (default: <root>-worktrees)')
+    .option('--removed', 'A worktree was removed this tick — consider rebuilding node_modules')
+    .option('--json', 'Emit machine-readable JSON output')
+    .addHelpText('after', '\nExit codes:\n' +
+    '  0  root is a usable work tree (healthy, or repaired in place) — continue the tick\n' +
+    '  1  repair was attempted and failed; the root is still bare — halt the tick\n' +
+    '  2  root is not a repairable main checkout (bare clone, linked worktree, or not a repo) — halt the tick\n')
+    .action(loopGuardCommand);
 program.hook('preAction', async (_, actionCommand) => {
     const name = actionCommand.name();
     if (name === 'setup' || name === 'doctor' || name === 'fix') {

package/dist/cli/utils/shell.js

@@ -1,4 +1,12 @@
 /**
+ * Quote a value as one literal argument **for a POSIX `sh` command line, and
+ * nothing else**. The result is wrong in `cmd.exe`, which does not treat `'` as
+ * a quote at all, and wrong in PowerShell, which does — but escapes an embedded
+ * `'` by doubling it rather than POSIX's `'\''`, so this output still mangles
+ * any value containing one. It is also wrong anywhere the value lands inside
+ * double quotes or an existing quoted string — it is a whole argument, not a
+ * fragment.
+ *
  * POSIX single-quote escaping — the only form correct for arbitrary bytes.
  * Inside single quotes every character is literal, so `'` is the sole one
  * needing care: end the quote, escape it, start a new one. Double quotes are

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "3.24.0",
+	"version": "3.25.0",
 	"description": "One CLI to scaffold, audit and fix your repo's whole toolchain — linting, tests, commits, releases & CI.",
 	"type": "module",
 	"keywords": [

package/skills/ai-issue-loop/SKILL.md

@@ -2,11 +2,14 @@
 name: ai-issue-loop
 model: sonnet
 description: |
-  Run one tick of the label-driven GitHub issue pipeline: pick up `ai-ready`
-  issues into per-issue worktrees, review the resulting PRs with other agents,
-  and auto-merge once both reviewers pass. Use when the user says "run the
-  issue loop", "work the ai-ready issues", "babysit the AI PRs", or invokes
-  `/ai-issue-loop`. Designed to be driven by `/loop 15m /ai-issue-loop`.
+  **The engine behind `/ai-workflow` — normally you do not invoke this
+  directly.** One stateless tick over the GitHub label state: answer
+  `ai-changes` with a fix round, merge Dependabot PRs, hand passed issue PRs to
+  the human, clean up merged worktrees, reap stalled agents, and pick up any
+  remaining `ai-ready` issues. `/ai-workflow` is the entry point and schedules
+  this itself via `/loop 15m /ai-issue-loop`; reach for it directly only to
+  force a tick early — "run one tick", "babysit the AI PRs" — or when the user
+  invokes `/ai-issue-loop`. Only Dependabot PRs ever merge unattended.
   GitHub only (`gh`) — not GitLab.
 ---
 
@@ -263,9 +266,9 @@ immediately after a `worktree remove` and some with nothing removed at all. The
 is unidentified, so this is detection and repair only:
 
 ```bash
-if [ "$(git -C "$ROOT" rev-parse --is-inside-work-tree 2>/dev/null)" != true ] && [ -d "$ROOT/.git" ]; then
+if [ "$(env -u GIT_DIR -u GIT_WORK_TREE git -C "$ROOT" rev-parse --is-inside-work-tree 2>/dev/null)" != true ] && [ -d "$ROOT/.git" ]; then
   echo "⚠ main checkout bare at $(date -u +%FT%TZ) — repairing"
-  git -C "$ROOT" config core.bare false || {
+  env -u GIT_DIR -u GIT_WORK_TREE git -C "$ROOT" config core.bare false || {
     echo "⚠ repair FAILED — main checkout still bare"; exit 1; }
 fi
 ```
@@ -291,6 +294,14 @@ too, and nothing else separates the two — this skill ships to users' `~/.claud
 where "repairing" someone's real bare clone is the damage rather than the fix. The same
 check skips a linked worktree, whose `.git` is a file.
 
+**`GIT_DIR` and `GIT_WORK_TREE` beat `-C`, so unset them.** When either is exported —
+some tooling wrappers do — git ignores `-C "$ROOT"` and operates on whatever they
+point at, so the probe would diagnose a *different* repo and the repair would write
+that repo's `.git/config`. Both failures are silent, and both are worse than the bug
+being guarded against. This skill installs into arbitrary users' `~/.claude/skills/`,
+so the caller's environment is not ours to assume; `env -u` scopes the unset to the
+one command rather than to the tick.
+
 **Fail loudly.** The repair writes `$ROOT/.git/config`, which a restrictive sandbox
 refuses with `error: could not lock config file .git/config: Operation not permitted` —
 observed. Aborting beats reporting a healthy repo while it stays broken.
@@ -348,9 +359,54 @@ and lacks either `ai-ok-*`, disarm it before labelling:
 gh pr merge <N> --disable-auto
 ```
 
-If there are no open PRs carrying any `ai-*` label **and** no eligible `ai-ready`
-issues (Pass 4's query), skip straight to Pass 5 with `SUMMARY=idle`. Skip the
-passes, never the report.
+**Adopt agent-opened PRs the same way.** A PR an agent opens outside Pass 4 — one
+with no `ai-ready` issue behind it — carries no `ai-*` label, so it matches no pass
+and is therefore assigned by nothing: it never reaches *Assigned to you*, which is
+the view where merges actually happen. Observed on #548, which passed all five
+required checks and read *Able to merge* while its assignees read *No one—assign
+yourself*. Label it `ai-review` and Pass 1 hands it over on the existing path once
+both arms pass — no second assignment rule is needed:
+
+```bash
+ME=$(gh api user --jq .login)   # the identity every loop agent opens PRs as
+gh pr list --state open --json number,author,labels,body \
+  | jq -r --arg me "$ME" \
+      '.[] | select(.author.login == $me)
+           | select([.labels[].name] | any(startswith("ai-")) | not)
+           | select((.body // "") | startswith("🤖 "))
+           | .number'
+```
+
+**The `🤖` header is the discriminator, not the login.** Every agent authenticates as
+the owner's own `gh`, so author login alone cannot tell a PR an agent opened from one
+the owner wrote by hand — and a PR the owner wrote themselves must not be swept in,
+which would put two reviewers on work nobody asked to have reviewed. The header is
+wire format, the same as the `<!-- ai-issue-loop:* -->` markers: every PR body this
+pipeline writes opens with `🤖 *Automated …*` or `🤖 *Opened by …*`, so match it and
+do not redefine it. `(.body // "")` is load-bearing for the reason Pass 1's upsert
+spells out — a null body throws and empties the whole filter, here adopting nothing
+rather than everything.
+
+If there are no open PRs carrying any `ai-*` label, no eligible `ai-ready` issues
+(Pass 4's query), **and** no `ai-*` worktree left on disk, skip straight to Pass 5
+with `SUMMARY=idle`. Skip the passes, never the report.
+
+```bash
+find "$WT_ROOT" "$ROOT/.claude/worktrees" -maxdepth 1 -name 'ai-*' -type d 2>/dev/null
+```
+
+**The third condition is not implied by the other two.** Pass 2's cleanup is keyed
+off worktrees *on disk*, never off open PRs, so the moment the last open PR is merged
+by hand both of the other conditions go true while its worktree is still present and
+its issue still carries `ai-wip` — the label only Pass 2 ever clears. Every later tick
+meets the same two conditions, so the worktree and the label survive indefinitely
+while the loop reports `idle`. The two leaks also protect each other: the
+orphan-worktree rule that would otherwise reap it matches only a worktree *whose issue
+is not `ai-wip`*, and the stale label is exactly what stops it. Observed 2026-08-26 —
+#541 and #542 closed and their PRs merged, both worktrees still on disk, both issues
+still `ai-wip`. No concurrency slot leaks (the cap counts *open* `ai-wip` issues); what
+leaks is disk, an issue list that reads as though agents are still working, and Pass
+2's `node_modules` rebuild, which is gated on `REMOVED=1` and so never runs.
 
 ### Pass 1 — merge
 
@@ -719,13 +775,16 @@ where `ai-blocked` would not be — nothing is lost, only the queue is honest.
 **Then re-check `core.bare`** — the same probe as Pass 0, against the same `ROOT`:
 
 ```bash
-if [ "$(git -C "$ROOT" rev-parse --is-inside-work-tree 2>/dev/null)" != true ] && [ -d "$ROOT/.git" ]; then
+if [ "$(env -u GIT_DIR -u GIT_WORK_TREE git -C "$ROOT" rev-parse --is-inside-work-tree 2>/dev/null)" != true ] && [ -d "$ROOT/.git" ]; then
   echo "⚠ main checkout bare at $(date -u +%FT%TZ) — repairing"
-  git -C "$ROOT" config core.bare false || {
+  env -u GIT_DIR -u GIT_WORK_TREE git -C "$ROOT" config core.bare false || {
     echo "⚠ repair FAILED — main checkout still bare"; exit 1; }
 fi
 ```
 
+The `env -u` prefix carries the same weight here as in Pass 0, and for the same
+reason — keep it on both lines.
+
 This is the last pass that *removes* worktrees, not the tick's last touch on the main
 checkout — Pass 4 still runs `git -C "$ROOT" worktree add` against it. That is exactly
 why the re-check belongs here: it catches a flip after this pass's removals and before

package/skills/ai-workflow/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: ai-workflow
 description: |
-  Implement the `ai-ready` GitHub issue queue in parallel — one agent per issue,
-  each in its own git worktree, ending at open PRs reviewed by two agents. Use
-  when the user says "burst the queue", "work all the ai-ready issues in
-  parallel", or invokes `/ai-workflow`. Hands off to the ai-issue-loop skill for
-  fix rounds and merging. GitHub only (`gh`) — not GitLab.
+  **The entry point for the `ai-ready` issue pipeline — start here.** Implements
+  the queue in parallel, one agent per issue, each in its own git worktree,
+  ending at open PRs reviewed by two agents; then registers the ai-issue-loop
+  engine on a 15-minute loop to carry those PRs through fix rounds and cleanup.
+  Use when the user says "burst the queue", "run the AI pipeline", "work the
+  ai-ready issues", or invokes `/ai-workflow`. Never merges. GitHub only
+  (`gh`) — not GitLab.
 ---
 
 # ai-workflow