@rtorcato/repo-tooling 3.20.0 → 3.21.1

package/README.md

@@ -180,20 +180,22 @@ ln -sf ../../node_modules/@rtorcato/repo-tooling/tooling/claude/repo-tooling.md
 ### Use with Claude Code (plugin)
 
 This repo is also a self-hosted Claude Code marketplace. Install the plugin to
-get three skills — `repo-tooling` (adopt/audit the presets via the CLI),
-`npm-publish` (never hand-cut a release) and `ai-issue-loop` (the label-driven
-issue → PR pipeline) — in any session:
+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:
 
 ```
 /plugin marketplace add rtorcato/repo-tooling
 /plugin install repo-tooling@repo-tooling
 ```
 
-`ai-issue-loop` also installs on its own, user-globally, so every repo on the
-machine shares one copy:
+The four `ai-*` skills also install on their own, user-globally, so every repo
+on the machine shares one copy:
 
 ```bash
-npx @rtorcato/repo-tooling fix claude-skills   # → ~/.claude/skills/ai-issue-loop/SKILL.md
+npx @rtorcato/repo-tooling fix claude-skills   # → ~/.claude/skills/{ai-issue-loop,ai-workflow,ai-issue,ai-loop-status}/SKILL.md
 ```
 
 It writes outside the repo, so it is opt-in: a bare `fix` skips it. See the
@@ -234,7 +236,10 @@ MIT — see [LICENSE](LICENSE).
 Any agent that supports the [`skills`](https://www.npmjs.com/package/skills) CLI can install this repo's skills straight from GitHub — no clone, no package install:
 
 ```bash
+npx skills add https://github.com/rtorcato/repo-tooling --skill 'ai-issue'
 npx skills add https://github.com/rtorcato/repo-tooling --skill 'ai-issue-loop'
+npx skills add https://github.com/rtorcato/repo-tooling --skill 'ai-loop-status'
+npx skills add https://github.com/rtorcato/repo-tooling --skill 'ai-workflow'
 npx skills add https://github.com/rtorcato/repo-tooling --skill 'npm-publish'
 npx skills add https://github.com/rtorcato/repo-tooling --skill 'repo-tooling'
 ```

package/dist/base/checks.js

@@ -2,7 +2,7 @@ import path from 'node:path';
 import fs from 'fs-extra';
 import { BLOCK_START, hasStaleAgentBlock } from '../cli/generators/agent-rules.js';
 import { BADGE_START, hasPublicOnlyBadges } from '../cli/generators/badges.js';
-import { claudeSkillStatus, SHIPPED_SKILL, skillDiffCommand, } from '../cli/generators/claude-skills.js';
+import { claudeSkillStatus, SHIPPED_SKILLS, skillDiffCommand, } from '../cli/generators/claude-skills.js';
 import { DEPENDABOT_CONFIG_PATHS, dependabotIgnoreRules } from '../cli/generators/security.js';
 import { detectNestedLanguages } from '../cli/utils/detect-language.js';
 /**
@@ -477,48 +477,62 @@ export async function checkAiSetup(dir) {
  */
 export async function checkClaudeSkills(skillsDir) {
     const check = 'Claude skills';
-    const hint = `Run \`npx @rtorcato/repo-tooling fix claude-skills\` to install the ${SHIPPED_SKILL} skill (writes outside the repo; opt-in, so \`fix\` alone skips it)`;
-    const status = await claudeSkillStatus(SHIPPED_SKILL, skillsDir);
-    if (!status.installed) {
+    const hint = `Run \`npx @rtorcato/repo-tooling fix claude-skills\` to install the ${SHIPPED_SKILLS.join(', ')} skills (writes outside the repo; opt-in, so \`fix\` alone skips it)`;
+    const statuses = [];
+    for (const name of SHIPPED_SKILLS)
+        statuses.push([name, await claudeSkillStatus(name, skillsDir)]);
+    if (statuses.every(([, s]) => s.file === null)) {
         return {
             check,
             status: 'optional-missing',
-            detail: status.file
-                ? `${SHIPPED_SKILL} skill is not installed`
-                : `no ~/.claude/skills — the ${SHIPPED_SKILL} skill is not installed`,
+            detail: `no ~/.claude/skills — the ${SHIPPED_SKILLS.join(', ')} skills are not installed`,
             hint,
         };
     }
-    if (status.needsInstall) {
-        return {
-            check,
-            status: 'optional-missing',
-            detail: `${SHIPPED_SKILL} skill is at ${status.installedVersion ?? 'an unstamped version'}; this package ships ${status.shippedVersion}`,
-            hint,
-        };
+    const missing = statuses.filter(([, s]) => !s.installed).map(([name]) => name);
+    const behind = statuses.filter(([, s]) => s.installed && s.needsInstall);
+    if (missing.length > 0 || behind.length > 0) {
+        const parts = [
+            missing.length > 0 ? `not installed: ${missing.join(', ')}` : null,
+            ...behind.map(([name, s]) => `${name} is at ${s.installedVersion ?? 'an unstamped version'}; this package ships ${s.shippedVersion}`),
+        ].filter((p) => p !== null);
+        return { check, status: 'optional-missing', detail: parts.join('; '), hint };
     }
     // A local fork is `ok` for the same reason a modified copied asset is (#448):
     // it is somebody's deliberate work, so it is named once and never nagged as
     // fixable — pointing at a `fix` that would refuse is worse than saying nothing.
     // `realFile` is set whenever `contentState` is — both mean something is
     // installed. The extra test is TypeScript's, not a real condition.
-    if (status.realFile && status.contentState && status.contentState !== 'pristine') {
-        const why = status.contentState === 'modified'
-            ? `has local changes since ${status.installedVersion}`
-            : 'carries no content record, so a fork cannot be told from a stale copy';
+    const forks = statuses.filter(([, s]) => s.realFile && s.contentState && s.contentState !== 'pristine');
+    if (forks.length > 0) {
+        const detail = forks
+            .map(([name, s]) => {
+            const why = s.contentState === 'modified'
+                ? `has local changes since ${s.installedVersion}`
+                : 'carries no content record, so a fork cannot be told from a stale copy';
+            return `${name} skill at ${s.file} ${why}; this package ships ${s.shippedVersion} and will not overwrite it`;
+        })
+            .join('; ');
+        // Name both paths: "diff it against the shipped copy" left the reader
+        // with nothing to diff, in the one case they most want to look (#484).
+        const diffs = forks
+            .map(([, s]) => s.realFile
+            ? `\`${skillDiffCommand({ realFile: s.realFile, shippedFile: s.shippedFile })}\``
+            : null)
+            .filter((d) => d !== null)
+            .join(', ');
         return {
             check,
             status: 'ok',
-            detail: `${SHIPPED_SKILL} skill at ${status.file} ${why}; this package ships ${status.shippedVersion} and will not overwrite it`,
-            // Name both paths: "diff it against the shipped copy" left the reader
-            // with nothing to diff, in the one case they most want to look (#484).
-            hint: `Diff it against the shipped copy — \`${skillDiffCommand({ realFile: status.realFile, shippedFile: status.shippedFile })}\` — then run \`npx @rtorcato/repo-tooling fix claude-skills --force-skills\` to take the shipped version`,
+            detail,
+            hint: `Diff against the shipped copy — ${diffs} — then run \`npx @rtorcato/repo-tooling fix claude-skills --force-skills\` to take the shipped version`,
         };
     }
+    const versions = new Set(statuses.map(([, s]) => s.installedVersion));
     return {
         check,
         status: 'ok',
-        detail: `${SHIPPED_SKILL} skill installed at ${status.installedVersion}`,
+        detail: `${SHIPPED_SKILLS.length} skills installed at ${[...versions].join(', ')}`,
     };
 }
 /**

package/dist/base/fixers.js

@@ -16,7 +16,7 @@ import path from 'node:path';
 import chalk from 'chalk';
 import inquirer from 'inquirer';
 import { installAgentRules, installAiSetup } from '../cli/generators/agent-rules.js';
-import { installClaudeSkill, resolveSkillsDir, SHIPPED_SKILL, skillDiffCommand, } from '../cli/generators/claude-skills.js';
+import { installClaudeSkill, resolveSkillsDir, SHIPPED_SKILLS, skillDiffCommand, } from '../cli/generators/claude-skills.js';
 import { generateBrand } from '../cli/generators/brand.js';
 import { generateCommunityHealth } from '../cli/generators/community-health.js';
 import { generateCommitlintConfig } from '../cli/generators/git.js';
@@ -26,7 +26,7 @@ import { classifyCopiedAssets } from '../cli/utils/copied-assets.js';
 import { copyPreset } from '../cli/utils/copy-preset.js';
 import { detectLanguage } from '../cli/utils/detect-language.js';
 import { resolveLanguageModule } from '../languages/registry.js';
-import { applyGithubSettings } from './github-settings.js';
+import { applyGithubSettings, applyReleaseEnvironment, RELEASE_ENV_CHECK, RELEASE_GATE_CHECK, } from './github-settings.js';
 import { applyLoopLabels } from './labels.js';
 import { closeCompletedMilestones } from './milestones.js';
 /**
@@ -87,7 +87,7 @@ function describeSkillFork(result) {
         ? `its content has diverged from the ${result.installedVersion} release it was installed from`
         : 'it carries no content record, so a local fork and a stale copy are indistinguishable';
     return [
-        `skipped — ${SHIPPED_SKILL} was not overwritten with ${result.shippedVersion}: ${why}`,
+        `skipped — ${result.name} was not overwritten with ${result.shippedVersion}: ${why}`,
         `  ${target}`,
         `  compare:  ${skillDiffCommand(result)}`,
         '  overwrite anyway:  fix claude-skills --force-skills',
@@ -210,6 +210,26 @@ export const BASE_FIXERS = [
             return { filesWritten: await applyGithubSettings(targetDir) };
         },
     },
+    {
+        target: 'release-environment',
+        description: 'Create the `release` environment (authenticated user as required reviewer) and wire `environment: release` into the publishing job — the gate between merging and publishing (#429)',
+        appliesTo: [RELEASE_GATE_CHECK, RELEASE_ENV_CHECK],
+        outputs: [
+            'GitHub `release` environment (remote, via gh api)',
+            '.github/workflows/<the publishing workflow>',
+        ],
+        // safe-add for the same shadow-run reason as github-settings, and
+        // explicitOnly because arming the gate changes what a merge *does*: the
+        // next release run sits `waiting` for an approval instead of publishing.
+        // That is the point, but it must be a chosen rollout per repo, not a side
+        // effect of a bare `fix`.
+        riskLevel: 'safe-add',
+        explicitOnly: true,
+        canFixDrift: true,
+        async run({ targetDir }) {
+            return { filesWritten: await applyReleaseEnvironment(targetDir) };
+        },
+    },
     {
         target: 'milestones',
         description: 'Close 100%-complete open milestones on GitHub via gh api (mutates the remote repo, not files). Never deletes or creates one',
@@ -328,9 +348,9 @@ export const BASE_FIXERS = [
     },
     {
         target: 'claude-skills',
-        description: `Install the ${SHIPPED_SKILL} Claude Code skill into the user-level skills dir (~/.claude/skills, or --skills-dir). Writes outside the repo`,
+        description: `Install the ${SHIPPED_SKILLS.join(', ')} Claude Code skills into the user-level skills dir (~/.claude/skills, or --skills-dir). Writes outside the repo`,
         appliesTo: ['Claude skills'],
-        outputs: [`~/.claude/skills/${SHIPPED_SKILL}/SKILL.md`],
+        outputs: SHIPPED_SKILLS.map((name) => `~/.claude/skills/${name}/SKILL.md`),
         // safe-add is load-bearing for the same reason it is on github-settings:
         // it exempts this fixer from the `--diff` shadow-run, which copies the repo
         // to tmp and *executes* run() — here that would write to the real home dir
@@ -342,26 +362,30 @@ export const BASE_FIXERS = [
             const dir = await resolveInstallDir(skillsDir, assumeYes);
             if (!dir)
                 return { filesWritten: [] };
-            const result = await installClaudeSkill(dir, SHIPPED_SKILL, { force: forceSkills });
-            if (result.status === 'declined-downgrade') {
-                console.error(chalk.yellow(`   skipped — ${result.file} is at ${result.installedVersion}, newer than the ${result.shippedVersion} this package ships`));
-                return { filesWritten: [] };
-            }
-            if (result.status === 'declined-fork') {
-                // Name `realFile`: through a stow symlink the overwrite would land in a
-                // *second* repo's working tree, and that is the path to look at (#480).
-                for (const line of describeSkillFork(result))
-                    console.error(chalk.yellow(`   ${line}`));
-                return { filesWritten: [] };
-            }
-            if (result.status === 'up-to-date')
-                return { filesWritten: [] };
-            // Report the resolved real path when the skill is a stow symlink: the bytes
-            // landed in a dotfiles checkout, and that is where the user has to commit them.
-            if (result.viaSymlink) {
-                console.error(chalk.dim(`   wrote through a symlink — commit ${result.realFile}`));
+            const filesWritten = [];
+            for (const name of SHIPPED_SKILLS) {
+                const result = await installClaudeSkill(dir, name, { force: forceSkills });
+                if (result.status === 'declined-downgrade') {
+                    console.error(chalk.yellow(`   skipped — ${result.file} is at ${result.installedVersion}, newer than the ${result.shippedVersion} this package ships`));
+                    continue;
+                }
+                if (result.status === 'declined-fork') {
+                    // Name `realFile`: through a stow symlink the overwrite would land in a
+                    // *second* repo's working tree, and that is the path to look at (#480).
+                    for (const line of describeSkillFork(result))
+                        console.error(chalk.yellow(`   ${line}`));
+                    continue;
+                }
+                if (result.status === 'up-to-date')
+                    continue;
+                // Report the resolved real path when the skill is a stow symlink: the bytes
+                // landed in a dotfiles checkout, and that is where the user has to commit them.
+                if (result.viaSymlink) {
+                    console.error(chalk.dim(`   wrote through a symlink — commit ${result.realFile}`));
+                }
+                filesWritten.push(result.realFile);
             }
-            return { filesWritten: [result.realFile] };
+            return { filesWritten };
         },
     },
     {

package/dist/base/github-settings.js

@@ -51,8 +51,8 @@ export const GITHUB_STANDARD = {
     requiredContexts: ['lint', 'typecheck', 'build', 'test'],
 };
 const CODE_SCANNING_CHECK = 'Code-scanning gate';
-const RELEASE_GATE_CHECK = 'Release gate';
-const RELEASE_ENV_CHECK = 'Release environment';
+export const RELEASE_GATE_CHECK = 'Release gate';
+export const RELEASE_ENV_CHECK = 'Release environment';
 const CHECK_NAMES = [
     'Branch protection',
     'Merge settings',
@@ -438,7 +438,7 @@ const RELEASE_ENVIRONMENT = 'release';
  * `semantic-release` counts on its own — the shipped preset publishes with it.
  */
 const PUBLISH_COMMAND = /semantic-release|changesets\/action|(?:npm|pnpm|yarn)\s+publish/;
-const GATE_HINT = 'Create a `release` environment with required reviewers (Settings → Environments) and add `environment: release` to the publishing job — a merge to the default branch then leaves the run `waiting` instead of publishing';
+const GATE_HINT = 'Run `npx @rtorcato/repo-tooling fix release-environment` to create the `release` environment with required reviewers (you) and add `environment: release` to the publishing job — a merge to the default branch then leaves the run `waiting` instead of publishing';
 const ENV_HINT = 'Add `environment: release` to the publishing job, or delete the environment — whichever was meant. An environment nothing references still lists under Settings → Environments as though it gates something';
 const unquote = (s) => s.replace(/^['"]|['"]$/g, '');
 /**
@@ -604,9 +604,9 @@ async function readEnvironments(gh, nwo) {
  * environment" is the gate check's; "no `environment:` but a `release`
  * environment exists" is the environment check's, and the gate check defers.
  *
- * A repo that publishes nothing is `ok` — not applicable, not drift. There is
- * no fixer: creating the environment needs a `required_reviewers` list only a
- * human can supply, so both hints describe the manual step.
+ * A repo that publishes nothing is `ok` — not applicable, not drift. The fixer
+ * is `fix release-environment` (`applyReleaseEnvironment` below), which uses
+ * the authenticated user as the required reviewer.
  */
 async function checkReleaseGate(gh, nwo, dir) {
     const publish = (await isPrivatePackage(dir)) ? null : await findPublishJob(dir);
@@ -836,3 +836,129 @@ export async function applyGithubSettings(dir, exec) {
         console.error(chalk.gray('   already configured — nothing to apply'));
     return applied;
 }
+// --- Release environment scaffolding (#429) --------------------------------
+/**
+ * Insert `environment: <env>` as the first key of job `jobId`. Line-based, same
+ * reasoning as `workflowJobs`: this package ships no YAML dependency, and jobs
+ * sit one indent level under `jobs:` with their keys one level below. Returns
+ * null when the job cannot be found. The caller only reaches this when
+ * `jobEnvironment()` was null, so it never doubles an existing key.
+ */
+export function addJobEnvironment(yaml, jobId, env) {
+    const lines = yaml.split('\n');
+    const start = lines.findIndex((l) => /^jobs:\s*$/.test(l));
+    if (start === -1)
+        return null;
+    const indentOf = (l) => l.length - l.trimStart().length;
+    // The job headers' indent — from the first real line after `jobs:`, exactly
+    // as workflowJobs derives it, so the two agree on what counts as a header.
+    let jobIndent = -1;
+    for (let i = start + 1; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (line.trim() === '' || line.trimStart().startsWith('#'))
+            continue;
+        if (indentOf(line) === 0)
+            return null;
+        jobIndent = indentOf(line);
+        break;
+    }
+    if (jobIndent === -1)
+        return null;
+    for (let i = start + 1; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (line.trim() === '' || line.trimStart().startsWith('#'))
+            continue;
+        if (indentOf(line) === 0)
+            return null; // left the jobs block
+        if (indentOf(line) !== jobIndent || !line.trim().startsWith(`${jobId}:`))
+            continue;
+        // Key indent = the job's first real line, so the insert matches whatever
+        // indentation the file already uses.
+        for (let j = i + 1; j < lines.length; j++) {
+            const next = lines[j] ?? '';
+            if (next.trim() === '' || next.trimStart().startsWith('#'))
+                continue;
+            lines.splice(j, 0, `${' '.repeat(indentOf(next))}environment: ${env}`);
+            return lines.join('\n');
+        }
+        return null;
+    }
+    return null;
+}
+/**
+ * Scaffold the release environment gate — the fixer half of #429 (the checks
+ * shipped with #449). Two writes, each skipped when already in place:
+ *
+ * 1. `PUT /repos/{nwo}/environments/release` with the **authenticated user** as
+ *    the required reviewer. On a solo-maintained repo they are the only human
+ *    there is; add or swap reviewers afterwards under Settings → Environments.
+ *    An environment that already carries a `required_reviewers` rule is never
+ *    touched — whoever set it up made a richer decision than this default.
+ * 2. `environment: release` on the publishing job, so the merge leaves the run
+ *    `waiting` instead of publishing.
+ *
+ * A job already behind some *other* environment is a warning, not a rename —
+ * this fixer scaffolds the standard, it does not migrate a custom setup.
+ */
+export async function applyReleaseEnvironment(dir, exec) {
+    if (!(await fs.pathExists(path.join(dir, '.git')))) {
+        console.error(chalk.gray('   skipped — not a git repository'));
+        return [];
+    }
+    const gh = exec ?? ((args, stdin) => realGhExec(args, stdin, dir));
+    const probe = await probeRepo(gh);
+    if ('skip' in probe) {
+        console.error(chalk.gray(`   skipped — ${probe.skip}`));
+        return [];
+    }
+    const nwo = probe.info.nwo;
+    const publish = (await isPrivatePackage(dir)) ? null : await findPublishJob(dir);
+    if (publish === 'skip') {
+        console.error(chalk.yellow('   skipped — could not read .github/workflows'));
+        return [];
+    }
+    if (!publish) {
+        console.error(chalk.gray('   skipped — no workflow job publishes to a registry'));
+        return [];
+    }
+    if (publish.environment !== null && publish.environment !== RELEASE_ENVIRONMENT) {
+        console.error(chalk.yellow(`   skipped — ${publish.file} \`${publish.job}\` already runs behind \`${publish.environment}\`; not renaming it`));
+        return [];
+    }
+    const envs = await readEnvironments(gh, nwo);
+    if (envs === 'skip') {
+        console.error(chalk.yellow('   skipped — could not read environments'));
+        return [];
+    }
+    const applied = [];
+    if (envs.get(RELEASE_ENVIRONMENT) !== true) {
+        const user = await gh(['api', 'user', '--jq', '.id']);
+        const id = user.ok ? Number.parseInt(user.stdout.trim(), 10) : Number.NaN;
+        if (Number.isNaN(id)) {
+            console.error(chalk.yellow(`   could not resolve the authenticated user for required_reviewers: ${user.stderr.trim() || 'gh error'}`));
+            return applied;
+        }
+        const label = `\`${RELEASE_ENVIRONMENT}\` environment with the authenticated user as required reviewer`;
+        const r = await gh(['api', '-X', 'PUT', `repos/${nwo}/environments/${RELEASE_ENVIRONMENT}`, '--input', '-'], JSON.stringify({ reviewers: [{ type: 'User', id }] }));
+        if (r.ok)
+            applied.push(label);
+        else {
+            console.error(chalk.yellow(`   could not apply ${label}: ${r.stderr.trim() || 'gh error'}`));
+            return applied;
+        }
+    }
+    if (publish.environment === null) {
+        const file = path.join(dir, '.github', 'workflows', publish.file);
+        const updated = addJobEnvironment(await fs.readFile(file, 'utf-8'), publish.job, RELEASE_ENVIRONMENT);
+        if (updated === null) {
+            console.error(chalk.yellow(`   could not add \`environment:\` to ${publish.file} \`${publish.job}\` — add it by hand`));
+        }
+        else {
+            await fs.writeFile(file, updated);
+            applied.push(`environment: ${RELEASE_ENVIRONMENT} on ${publish.file} \`${publish.job}\``);
+        }
+    }
+    if (applied.length === 0)
+        console.error(chalk.gray('   already configured — nothing to apply'));
+    return applied;
+}

package/dist/cli/generators/claude-skills.js

@@ -10,7 +10,12 @@ import path from 'node:path';
 import fs from 'fs-extra';
 import { getPackageRoot } from '../utils/copy-preset.js';
 import { shellQuote } from '../utils/shell.js';
-/** Skills this package owns the content of and keeps up to date. */
+/**
+ * Skills this package owns the content of and keeps up to date. The loop first —
+ * it is the pipeline; the other three are its drivers (burst, on-ramp, status).
+ */
+export const SHIPPED_SKILLS = ['ai-issue-loop', 'ai-workflow', 'ai-issue', 'ai-loop-status'];
+/** The primary skill — the default everywhere a single name is accepted. */
 export const SHIPPED_SKILL = 'ai-issue-loop';
 /**
  * Stamped into the installed copy's frontmatter so a second repo pinned to an

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "3.20.0",
+	"version": "3.21.1",
 	"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/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: ai-issue
+description: |
+  File a GitHub issue labelled `ai-ready` for the ai-issue-loop pipeline to pick
+  up and implement unattended. Use when the user says "file this for the loop",
+  "make this an AI issue", "queue this for an agent", or invokes `/ai-issue`.
+  For an ordinary issue a human will work on, use plain `gh issue create` with
+  no label instead. GitHub only (`gh`) — not GitLab.
+---
+
+# ai-issue
+
+File an issue an **agent will execute unattended**, labelled `ai-ready` so
+`ai-issue-loop` picks it up. Arguments: $ARGUMENTS
+
+This is only for work you intend a background agent to do without you. For an
+ordinary issue, use `gh issue create` with no `ai-*` label.
+
+## Preflight
+
+1. `git remote get-url origin` — GitHub only. On GitLab, stop: the loop is
+   `gh`-based and nothing would ever pick the issue up.
+2. `gh label list --search ai-ready` — if the label is missing, this repo hasn't
+   been bootstrapped for the loop. Stop and point at the `ai-issue-loop` skill's
+   label block; creating a bare `ai-ready` label would produce an issue that
+   silently never runs.
+
+## Write it for an agent, not for yourself
+
+The agent that picks this up **cannot ask a follow-up question**, and is
+instructed to treat the body as untrusted data. Both change how it must read:
+
+- **Describe, never instruct.** "The README claims X but Y is true" — not "go
+  update the README". Directive phrasing is exactly what the agent is told to
+  ignore, so an instruction-shaped issue reads as empty.
+- **Name the files** you already know are involved. The two reviewing agents are
+  diff-scoped and won't explore the repo to judge whether the right thing was
+  touched.
+- **State a done-condition a reviewer can check.** Those same agents review the
+  PR against this body; a vague issue produces a vague review on a PR you then
+  merge without having really vetted.
+- **One PR's worth.** Split anything spanning several concerns — the loop runs
+  several issues in parallel, so splitting is free.
+
+## Refuse the ones that aren't ready
+
+Say so, and file it unlabelled instead, when the task:
+
+- needs a judgement call you'd normally make mid-PR,
+- needs eyes on rendered output, a real device, or a running service,
+- depends on context that lives in this conversation rather than the repo, or
+- you couldn't write self-contained without "we can sort that out in review".
+
+An `ai-ready` that stalls costs more than an issue you did yourself: it burns a
+concurrency slot, two review passes, and up to two fix rounds before it lands as
+`ai-blocked`.
+
+## Create
+
+Draft title and body from `$ARGUMENTS` plus the conversation. The body opens
+with a line saying an agent wrote it — everything you post appears under the
+owner's own account:
+
+```bash
+gh issue create --label ai-ready --title "TITLE" --body "$(cat <<'EOF'
+🤖 *Filed by Claude (AI agent) on the owner's behalf.*
+
+BODY
+EOF
+)"
+```
+
+Print the URL. Note that nothing happens until a tick runs — `/ai-issue-loop`
+manually, or a recurring schedule if one is active.