@retasc/cli 1.45.0 → 1.46.0

package/CHANGELOG.md

@@ -6,6 +6,31 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.46.0 (2026-09-08)
+
+- **RTSC-855** — `retasc doctor` and `retasc setup` now say whether the **Retasc Agent
+  Skill** is installed on this machine, and print the one command that installs it.
+
+  Wiring the MCP server gives an agent the ability to claim work. The skill is what tells
+  it what a lease is, that a claim needs its own worktree, what a checkpoint is for, and
+  how a handoff into review works. Nothing connected the two, so an agent could be fully
+  wired and still have the tools without the manual, and no surface anywhere would
+  mention it. The server cannot fill the gap: MCP carries a bearer token and no
+  filesystem, so only something running on the machine can look.
+
+  The hard part is not finding the file, it is not being wrong about it. A false "not
+  installed" shown to somebody who followed our own instructions teaches them to distrust
+  everything else `doctor` says, so the check knows all three routes a skill really
+  arrives by: global (`~/.claude/skills` and each harness's equivalent), project (the
+  `skills` installer's DEFAULT scope, which lands in the working directory), and, for
+  Claude Code, an installed plugin's own folder, since `/plugin install retasc@retasc` is
+  one of the routes our public README offers and it writes none of the above. It honours
+  `CLAUDE_CONFIG_DIR`, `CODEX_HOME` and `GROK_HOME` for the same reason. The printed
+  command carries `-g` so it installs where the check looks. A harness whose convention
+  we cannot verify is skipped rather than accused, one harness holding the skill silences
+  the nudge for the rest, absence is reported with `ℹ` rather than `✗`, and neither
+  command changes its exit code over any of it.
+
 ## 1.45.0 (2026-09-08)
 
 - **RTSC-862** — a binding now covers every **git worktree** of the repo it was made in.

package/dist/commands/doctor.js

@@ -2,7 +2,9 @@ import { loadConfig } from "../config.js";
 import { claudeConfigPath, isNetworkError, readGlobalBinding, readLocalBinding, readShadowedBinding, resolveBinding, sameIdentity, } from "../lib/binding.js";
 import { getBinding } from "../lib/keystore.js";
 import { gitCommonDir } from "../lib/gitRepo.js";
+import { detectHarnesses } from "../lib/harness.js";
 import { runsOk } from "../lib/launcher.js";
+import { skillLines, skillReport } from "../lib/skill.js";
 import { clean } from "../lib/text.js";
 // RTSC-91 (DESIGN §13): `retasc doctor` — confirm THIS folder is correctly and
 // safely bound. The question a human actually has is "which org/project does
@@ -217,7 +219,15 @@ export async function doctorAction() {
             `    own, so issues can land in the wrong project.\n` +
             `    Fix:  claude mcp remove -s user retasc`);
     }
-    // 3) Ambient context, not a verdict on this folder — so it trails the checks
+    // 3) Does the agent that will use this binding have the manual? (RTSC-855)
+    //
+    // A machine fact rather than a folder fact, so it comes after both folder checks.
+    // It is still a check, not a footnote: everything above proves an agent can REACH
+    // Retasc, and this is the one that says whether it will know what to do when it
+    // gets there. Absence never touches the exit code, and `doctorAction` sets none.
+    for (const line of skillLines(skillReport(detectHarnesses())))
+        console.log(line);
+    // 4) Ambient context, not a verdict on this folder — so it trails the checks
     // rather than framing them, and on macOS it prints nothing at all.
     const note = platformNote();
     if (note)

package/dist/commands/setup.js

@@ -18,6 +18,7 @@ import { wireClaudeHook, hookLauncher } from "../lib/sessionHook.js";
 import { AUTO_WORKSPACE } from "../lib/keystore.js";
 import { HARNESSES, detectHarnesses, tildePath } from "../lib/harness.js";
 import { resolveLauncher, launcherNote } from "../lib/launcher.js";
+import { skillLines, skillReport } from "../lib/skill.js";
 import { VERSION } from "../version.js";
 import { card } from "../lib/card.js";
 /** The one entry every harness gets: the watchdog proxy, resolving its own folder. */
@@ -49,6 +50,7 @@ export function runSetup(opts) {
         wired: [],
         failed: [],
         absent: known.filter((h) => !presentIds.has(h.id)).map((h) => h.label),
+        skill: skillReport(present),
     };
     for (const h of present) {
         const outcome = h.install(entry);
@@ -98,6 +100,12 @@ export function printSetup(r) {
     }
     if (r.absent.length)
         console.log(`  Not on this machine: ${r.absent.join(", ")}.`);
+    // RTSC-855 — next to the harness rows, because it is the same kind of fact: what this
+    // machine has, and what it is still missing. `setup` wires the tools; the skill is the
+    // document that tells an agent what to do with them, and nothing else on this receipt
+    // would ever mention that it is absent. Never a failure, and never installed for you.
+    for (const line of skillLines(r.skill))
+        console.log(line);
     console.log("\nThese entries carry no key and name no project, so they are correct in every folder.\n" +
         "Run `retasc bind` in a project to say which org it belongs to, then start your agent\n" +
         "there (or restart it if it's already open).");

package/dist/lib/harness.js

@@ -26,7 +26,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join } from "node:path";
 /**
  * The home directory harness configs are resolved under.
  *
@@ -48,6 +48,38 @@ export function tildePath(p) {
     const h = home();
     return p.startsWith(h + "/") ? `~${p.slice(h.length)}` : p;
 }
+// --- skills directories -----------------------------------------------------
+//
+// Not derived from theory, same rule as the rest of this registry: every path below is a
+// directory the `skills` installer (agentskills.io, the tool `SKILL_INSTALL_CMD` runs)
+// reads for that harness, taken from its published agent table rather than guessed at. If
+// a harness ever grew a convention we could not verify, the honest entry would be an empty
+// list. "We do not know where yours lives" is a finding a human can act on, a made-up path
+// is not.
+//
+// TWO scopes, because the installer has two and defaults to the one a global-only check
+// would never see (`installGlobally = options.global ?? false`, and its interactive prompt
+// offers Project first). A check that read only the home directory would call the skill
+// missing for everybody who ran the install command exactly as printed, forever.
+//
+// The harness's own home variable is honoured here even though `configPath()` does not
+// honour it. That asymmetry is deliberate: this path only READS, so resolving the same
+// home the harness itself resolves can at worst find the skill somewhere true, whereas
+// `configPath()` WRITES and shares its answer with subprocesses. RETASC_HOME still
+// outranks everything, exactly as in `opencodeConfig()`, or the test override would stop
+// protecting the developer's real home the moment one of these variables is set.
+/** A harness's own config home: the test override first, then its documented variable,
+ *  then the default under `~`. */
+function harnessHome(envVar, dir) {
+    if (process.env.RETASC_HOME)
+        return join(home(), dir);
+    return process.env[envVar]?.trim() || join(home(), dir);
+}
+/** `<global skills dir>` plus the project-scope folder this harness reads in the working
+ *  directory. Both are real install targets, so both answer "is the skill here". */
+function skillDirs(globalDir, projectDir) {
+    return [globalDir, join(process.cwd(), ...projectDir.split("/"))];
+}
 export const SERVER_NAME = "retasc";
 // --- shared helpers ---------------------------------------------------------
 /**
@@ -134,11 +166,12 @@ export function tomlBlock(entry) {
         env,
     ].join("\n");
 }
-function tomlHarness(id, label, path, bin) {
+function tomlHarness(id, label, path, bin, skills) {
     return {
         id,
         label,
         configPath: path,
+        skillDirs: () => skillDirs(join(harnessHome(skills.home, skills.dir), "skills"), skills.project),
         detect: () => existsSync(path()) || onPath(bin),
         install(entry) {
             const p = path();
@@ -335,6 +368,53 @@ export function jsonServerValue(entry) {
     return JSON.stringify({ command: entry.command, args: entry.args, env: entry.env }, null, 2);
 }
 // --- Claude Code ------------------------------------------------------------
+/**
+ * The `skills/` folder of every plugin Claude Code has installed (RTSC-855).
+ *
+ * `/plugin install retasc@retasc` is one of the three install routes our public skills
+ * README offers, and it does NOT write into `~/.claude/skills`. The plugin is unpacked
+ * under `~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/` and its skills are
+ * read from there. So a check that only looked in the skills folder would tell exactly
+ * the people who followed our own instructions that they had not.
+ *
+ * Read from the manifest rather than globbed, because the manifest is what Claude Code
+ * itself acts on: a stale directory left behind by an uninstall is not an installed
+ * skill, and enumerating the cache would count it as one. Best effort throughout, because
+ * this feeds a nudge and a manifest we cannot parse must never become a hard failure in
+ * `doctor`.
+ */
+function claudePluginSkillDirs() {
+    try {
+        const manifest = join(harnessHome("CLAUDE_CONFIG_DIR", ".claude"), "plugins", "installed_plugins.json");
+        const parsed = JSON.parse(readIfExists(manifest) || "{}");
+        const plugins = parsed?.plugins;
+        if (!plugins || typeof plugins !== "object")
+            return [];
+        const dirs = [];
+        for (const installs of Object.values(plugins)) {
+            for (const i of Array.isArray(installs) ? installs : []) {
+                // Absolute only. A relative `installPath` would resolve against the CURRENT
+                // DIRECTORY, so running `retasc doctor` inside any repo that happens to contain
+                // `skills/retasc/SKILL.md` (this one does) would report the skill installed.
+                // Claude Code writes absolute paths, so nothing legitimate is dropped.
+                // User scope only. A plugin installed for one project would otherwise make
+                // `doctor` report the skill present in every OTHER folder, where the agent
+                // cannot load it. A false "installed" is the worse error of the two: it
+                // produces silence instead of the nudge this check exists to give.
+                const scope = i?.scope;
+                if (scope !== undefined && scope !== "user")
+                    continue;
+                const p = i?.installPath;
+                if (typeof p === "string" && isAbsolute(p))
+                    dirs.push(join(p, "skills"));
+            }
+        }
+        return dirs;
+    }
+    catch {
+        return [];
+    }
+}
 /**
  * Claude Code is the one harness with a real CLI for this, and `claude mcp add` is
  * the ONLY sanctioned way to edit `~/.claude.json`: a running Claude Code rewrites
@@ -351,6 +431,10 @@ const claudeCode = {
     id: "claude-code",
     label: "Claude Code",
     configPath: () => join(home(), ".claude.json"),
+    skillDirs: () => [
+        ...skillDirs(join(harnessHome("CLAUDE_CONFIG_DIR", ".claude"), "skills"), ".claude/skills"),
+        ...claudePluginSkillDirs(),
+    ],
     // A test home means "do not touch this machine's real config". `claude mcp add`
     // writes ~/.claude.json wherever HOME points, so the override has to gate DETECTION,
     // not just the path: an undetected harness is never installed into.
@@ -404,6 +488,7 @@ const cursor = {
     id: "cursor",
     label: "Cursor",
     configPath: () => join(home(), ".cursor", "mcp.json"),
+    skillDirs: () => skillDirs(join(home(), ".cursor", "skills"), ".agents/skills"),
     detect: () => existsSync(join(home(), ".cursor")) || onPath("cursor-agent"),
     install(entry) {
         const p = join(home(), ".cursor", "mcp.json");
@@ -438,6 +523,7 @@ function addCommandHarness(opts) {
         id: opts.id,
         label: opts.label,
         configPath: opts.configPath,
+        skillDirs: () => skillDirs(join(dirname(opts.configPath()), "skills"), opts.projectSkillDir),
         // Gated on RETASC_HOME for the same reason Claude Code is: this shells out to a
         // command that resolves the REAL home, so a test home has to stop it at DETECTION.
         // An undetected harness is never installed into.
@@ -488,6 +574,7 @@ const opencode = addCommandHarness({
     label: "OpenCode",
     bin: "opencode",
     configPath: opencodeConfig,
+    projectSkillDir: ".agents/skills",
     args: (entry) => [
         "mcp", "add", SERVER_NAME,
         ...Object.entries(entry.env).flatMap(([k, v]) => ["--env", `${k}=${v}`]),
@@ -513,6 +600,7 @@ const gemini = addCommandHarness({
     label: "Gemini CLI",
     bin: "gemini",
     configPath: () => join(home(), ".gemini", "settings.json"),
+    projectSkillDir: ".agents/skills",
     args: (entry) => [
         "mcp", "add",
         "-s", "user",
@@ -524,8 +612,16 @@ const gemini = addCommandHarness({
 // --- the registry -----------------------------------------------------------
 export const HARNESSES = [
     claudeCode,
-    tomlHarness("codex", "Codex", () => join(home(), ".codex", "config.toml"), "codex"),
-    tomlHarness("grok", "Grok", () => join(home(), ".grok", "config.toml"), "grok"),
+    tomlHarness("codex", "Codex", () => join(home(), ".codex", "config.toml"), "codex", {
+        home: "CODEX_HOME",
+        dir: ".codex",
+        project: ".agents/skills",
+    }),
+    tomlHarness("grok", "Grok", () => join(home(), ".grok", "config.toml"), "grok", {
+        home: "GROK_HOME",
+        dir: ".grok",
+        project: ".grok/skills",
+    }),
     cursor,
     opencode,
     gemini,

package/dist/lib/skill.js

@@ -0,0 +1,110 @@
+// RTSC-855: is the Retasc Agent Skill on this machine?
+//
+// This check can only live here. The server sees a bearer token and nothing else, no
+// filesystem and no working directory, so it cannot know whether `skills/retasc/SKILL.md`
+// was ever installed and must not pretend to infer it. The CLI runs on the machine, and
+// `doctor` and `setup` already report local facts, so they are the honest place to ask.
+//
+// What is at stake is not cosmetic. The MCP tools give an agent the ability to claim
+// work; the skill is what tells it what a lease is, that a claim needs its own worktree,
+// what a checkpoint is for, and how a handoff into review works. An agent with the tools
+// and not the manual looks like it is working and quietly gets the protocol wrong.
+//
+// Absence is a FINDING, not a failure. Nothing here touches an exit code, and nothing
+// here writes: installing the skill is a decision for the human, made with one command
+// they can read before they run it.
+//
+// Explicitly NOT in scope: deciding whether an installed copy is STALE. That needs a
+// version stamp on the published skill, which does not exist yet, and a guess at it
+// would produce the one output worse than silence, a confident wrong answer about a
+// file the human can see is right there.
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { clean } from "./text.js";
+/** The skill's folder name, and the name it is published under. */
+export const SKILL_NAME = "retasc";
+/**
+ * The one command to print.
+ *
+ * Harness-agnostic on purpose: `npx skills add Retasc/skills` is the first of the three
+ * routes our public README lists and the only one that is correct for all six harnesses
+ * at once, so a machine with Codex and Cursor on it gets a single line rather than a
+ * decision tree. The Claude Code plugin route and the git-clone route stay in the README
+ * where somebody choosing between them is already reading.
+ *
+ * `-g` is load-bearing and was missing here first time round. The installer defaults to
+ * PROJECT scope (`installGlobally = options.global ?? false`, and its interactive prompt
+ * offers Project first), which installs into the current folder. Without the flag this
+ * command would install the skill somewhere real, the agent would load it in that one
+ * folder, and every other folder would keep being told to run the same command again.
+ * Global is what "install this on my machine" means, and it is what a nudge printed by a
+ * machine-wide check should hand you.
+ */
+export const SKILL_INSTALL_CMD = "npx skills add Retasc/skills -g";
+/** A directory is "holding the skill" when the skill's own file is readable in it. A
+ *  bare `retasc/` folder is not an installed skill, and `existsSync` follows symlinks,
+ *  which is how a checkout linked into `~/.claude/skills` counts (see skills/README.md). */
+function holdsSkill(dir) {
+    try {
+        return existsSync(join(dir, SKILL_NAME, "SKILL.md"));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Which of these harnesses can read the skill, and which cannot.
+ *
+ * Takes the DETECTED harnesses rather than detecting for itself, so the answer is about
+ * agents that actually run here: telling someone the skill is missing from Gemini CLI on
+ * a machine with no Gemini CLI is noise dressed as a finding, and both callers have the
+ * detected list in hand already.
+ */
+export function skillReport(harnesses) {
+    const report = { installed: [], missing: [] };
+    for (const h of harnesses) {
+        let dirs = [];
+        try {
+            dirs = h.skillDirs();
+        }
+        catch {
+            dirs = [];
+        }
+        // No known skills directory means we cannot answer for this harness, and the honest
+        // move is to say nothing rather than to invent a path and report a miss against it.
+        if (!dirs.length)
+            continue;
+        const entry = { label: h.label };
+        (dirs.some(holdsSkill) ? report.installed : report.missing).push(entry);
+    }
+    return report;
+}
+const names = (list) => clean(list.map((p) => p.label).join(", "));
+/**
+ * The lines to print, prefixes included, shared verbatim by `doctor` and `setup`.
+ *
+ * One renderer because the issue asks both surfaces to say the same thing, and two
+ * copies of a sentence are two sentences the moment one of them is edited.
+ *
+ * `ℹ` and not `✗`: this is context about the machine, not a fault in the folder being
+ * checked, and it sits in a report whose ✓/✗ marks people read as pass and fail.
+ */
+export function skillLines(report) {
+    // One harness with the skill is enough to say so and stop talking. The nudge exists for
+    // the machine that has the manual NOWHERE; on a developer laptop that has Cursor and
+    // Gemini installed but points neither at Retasc, listing them as missing on every run
+    // is an unresolvable nag about work nobody intends to do, and a check people learn to
+    // scroll past has stopped being a check. Which harnesses DO have it is named in the ✓
+    // line, so nothing true is being hidden.
+    if (report.installed.length) {
+        return [`  ✓ the Retasc Agent Skill is installed (${names(report.installed)}).`];
+    }
+    if (!report.missing.length)
+        return [];
+    return [
+        `  ℹ the Retasc Agent Skill is not installed for ${names(report.missing)}.\n` +
+            `    It is what teaches an agent to work the queue: dispatch, leases, checkpoints,\n` +
+            `    handing off through review. Without it an agent has the tools and not the manual.\n` +
+            `    Install:  ${SKILL_INSTALL_CMD}`,
+    ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retasc/cli",
-  "version": "1.45.0",
+  "version": "1.46.0",
   "description": "Retasc CLI — the issue tracker AI agents pull work from. Sign in with GitHub or Google, create projects, mint agent API keys, and wire your agent to the Retasc MCP server in one command.",
   "type": "module",
   "bin": {