@rtorcato/repo-tooling 3.21.0 → 3.22.0

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';
@@ -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',
@@ -348,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
@@ -362,26 +362,34 @@ 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') {
+                    // Say what was compared, not what is newer: the version is a label,
+                    // and on a git checkout it can understate the content behind it
+                    // (#522). Naming the escape hatch matters for exactly that case.
+                    console.error(chalk.yellow(`   skipped — ${result.file} is stamped ${result.installedVersion}, above the ${result.shippedVersion} this package reports; not overwritten`));
+                    console.error(chalk.yellow('   overwrite anyway:  fix claude-skills --force-skills'));
+                    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/cli/generators/claude-skills.js

@@ -8,9 +8,15 @@ import { createHash } from 'node:crypto';
 import os from 'node:os';
 import path from 'node:path';
 import fs from 'fs-extra';
+import { realGitExec } from '../../base/git-identity.js';
 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
@@ -122,13 +128,41 @@ export function isNewerVersion(a, b) {
     }
     return false;
 }
+/**
+ * The version to stamp, given what `package.json` claims.
+ *
+ * In a published tarball that field is authoritative — `@semantic-release/npm`
+ * rewrites it before packing. In a *git checkout* it is not: this repo runs
+ * semantic-release without `@semantic-release/git` (#417), so nothing ever
+ * writes the released version back and the field sits at whatever it was last
+ * hand-set to. Observed 2026-08-22: `package.json` 3.11.0 against npm 3.21.1,
+ * ten minor versions of drift.
+ *
+ * That mattered because the stamp feeds the downgrade guard below: a skill
+ * installed from npm could not be updated from a local checkout, and the
+ * refusal claimed the installed copy was "newer" when only its *label* was.
+ *
+ * So when the package root is a git checkout, take the nearest tag as well and
+ * keep whichever is higher. Monotonic on purpose — this can only ever raise the
+ * answer, so a tagless, shallow, or git-less environment keeps today's
+ * behaviour rather than silently stamping something lower.
+ */
+export async function resolveShippedVersion(root, pkgVersion, git = realGitExec) {
+    if (!(await fs.pathExists(path.join(root, '.git'))))
+        return pkgVersion;
+    const described = await git(['describe', '--tags', '--abbrev=0'], root);
+    const tag = described?.trim().replace(/^v/, '');
+    if (!tag || !/^\d+\.\d+/.test(tag))
+        return pkgVersion;
+    return isNewerVersion(tag, pkgVersion) ? tag : pkgVersion;
+}
 /** The skill source and the package version that will be stamped into it. */
-export async function readShippedSkill(name = SHIPPED_SKILL) {
+export async function readShippedSkill(name = SHIPPED_SKILL, git = realGitExec) {
     const root = getPackageRoot();
     const file = path.join(root, 'skills', name, 'SKILL.md');
     const content = await fs.readFile(file, 'utf8');
     const pkg = await fs.readJson(path.join(root, 'package.json'));
-    return { content, version: String(pkg.version), file };
+    return { content, version: await resolveShippedVersion(root, String(pkg.version), git), file };
 }
 /**
  * The command a human runs to see what their fork changed, before deciding
@@ -182,7 +216,12 @@ export async function installClaudeSkill(skillsDir, name = SHIPPED_SKILL, { forc
         installedVersion,
         shippedVersion: shipped.version,
     };
-    if (installedVersion && isNewerVersion(installedVersion, shipped.version)) {
+    // `force` overrides this too, not just the fork check below. It already
+    // overrides the *stronger* protection — overwriting content someone
+    // deliberately edited — so refusing on a version comparison while allowing
+    // that was backwards, and left no escape hatch at all when the comparison
+    // was wrong (#522).
+    if (!force && installedVersion && isNewerVersion(installedVersion, shipped.version)) {
         return { ...base, status: 'declined-downgrade' };
     }
     // Only `pristine` content is provably ours to replace. Anything else is a

package/dist/cli/utils/lockfile.js

@@ -66,13 +66,18 @@ export async function writeLockfile(dir, config, assets) {
     if (!valid) {
         throw new Error(`Refusing to write invalid lockfile:\n  - ${errors.join('\n  - ')}`);
     }
-    const carried = assets ?? (await readLockfile(dir))?.assets;
+    // One read, because everything not rebuilt from `config` has to be carried
+    // forward explicitly — this object is constructed from scratch, so any key
+    // not named here is dropped by the next `fix lockfile`.
+    const existing = await readLockfile(dir);
+    const carried = assets ?? existing?.assets;
     const filepath = path.join(dir, LOCKFILE_NAME);
     const lockfile = {
         $schema: LOCKFILE_SCHEMA_URL,
         version: LOCKFILE_VERSION,
         config,
         ...(carried && Object.keys(carried).length > 0 ? { assets: carried } : {}),
+        ...(existing?.aiLoop ? { aiLoop: existing.aiLoop } : {}),
         writtenBy: `@rtorcato/repo-tooling@${packageJson.version}`,
         writtenAt: new Date().toISOString(),
     };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "3.21.0",
+	"version": "3.22.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/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.