rush-ai 0.6.0 → 0.7.0

package/AGENTS.md

@@ -0,0 +1,37 @@
+# AGENTS.md — for AI agents using rush-ai
+
+If you are an AI agent (Cursor, Claude Code, or another IDE-resident assistant) and you landed in this package, read this file first.
+
+## What rush-ai is for
+
+`rush-ai` is how a local agent hands off work to the Rush platform — without asking the user to re-state anything. Two situations you'll use it in:
+
+1. **Hand-off** — the conversation you're in produces work that belongs on Rush (a live website, a task for a specialist). Relay the context you already have. → read [`skills/hand-off.md`](./skills/hand-off.md).
+2. **Sub-agent in your workflow** — you're composing a multi-step plan and a step needs a specialist from Rush's agent shelf. → read [`skills/agent-shelf.md`](./skills/agent-shelf.md).
+
+## Getting usage on demand
+
+From inside any shell (the one you already have a Bash tool for), these three commands give you everything you need:
+
+```bash
+npx rush-ai skill                   # prints the index — start here
+npx rush-ai skill hand-off          # full hand-off playbook
+npx rush-ai skill agent-shelf       # full agent-shelf playbook
+npx rush-ai agent list              # see the live list of available agents
+```
+
+Every command also supports `--help` with a "When to use" section and example flows.
+
+## Defaults that save you a round-trip
+
+- Recommended invocation: **`npx rush-ai`** (always latest, zero install).
+- Default agent: **`rush`** — `-a` defaults to `rush` when omitted. Pass `-a web-builder` for site-building tasks.
+- Always pass **`--json`** when the result will be parsed.
+- Iterate with **`task send <id>`**, not a new `task create`.
+
+## What NOT to do
+
+- Don't ask the user to summarize requirements they already told you — relay them.
+- Don't invent agent names; always confirm via `agent list`.
+- Don't run `npx rush-ai auth login` for the user (it's interactive / opens a browser). Ask them to.
+- Don't silently retry a failed task. Surface the error and ask what to do.

package/dist/index.js

@@ -161,37 +161,122 @@ function requireAuth() {
 }
 
 // src/commands/agent/index.ts
+var AGENT_HELP_AFTER = `
+When to use:
+  Rush hosts a shelf of specialist agents \u2014 call them as sub-agents from
+  your own workflows instead of writing the prompts yourself. Always
+  discover first, then invoke.
+
+Typical flows:
+  $ rush-ai agent list --default --json        # just the built-in defaults
+  $ rush-ai agent list --search "\u4EBA\u529B" --json  # fuzzy-filter by name / desc
+  $ rush-ai agent list --all --json            # everything \u2014 may be long
+  $ rush-ai agent info <name> --json           # inspect one agent's skills / MCP
+
+  $ rush-ai task create -a <name> -p "..."     # call the agent as a sub-agent
+  $ rush-ai task status <id> --json            # grab its output
+
+Built-in default agents (see --default):
+  rush              general-purpose agent
+  web-builder       site / landing-page builder (returns previewUrl + gitRepoUrl)
+  skill-publisher   publishes reusable skills back onto the platform
+
+For agents: run \`rush-ai skill agent-shelf\` for the full playbook.
+`;
 function registerAgentCommand(program) {
-  const agent = program.command("agent").description("Manage and inspect agents");
-  agent.command("list").alias("ls").description("List available agents").action(async () => {
-    requireAuth();
-    const format = resolveFormat(program.opts());
-    const client = createClient();
-    const { data } = await client.get("/api/agents");
-    if (format === "json") {
-      output.log(JSON.stringify(data, null, 2));
-      return;
-    }
-    if (data.agents.length === 0) {
-      output.info("No agents found.");
-      return;
+  const agent = program.command("agent").description("Manage and inspect agents").addHelpText("after", AGENT_HELP_AFTER);
+  agent.command("list").alias("ls").description("List available agents").option(
+    "-l, --limit <n>",
+    "Max agents per page (1\u2013500, default 50)",
+    (v) => Number.parseInt(v, 10),
+    50
+  ).option(
+    "-p, --page <n>",
+    "Page number (1-indexed, default 1)",
+    (v) => Number.parseInt(v, 10),
+    1
+  ).option("-q, --search <text>", "Filter agents by name / description").option(
+    "--default",
+    "Only show built-in default agents (web-builder, rush, skill-publisher, ...)"
+  ).option(
+    "--all",
+    "Fetch every page and return the full list (may issue several requests)"
+  ).action(
+    async (opts) => {
+      requireAuth();
+      const format = resolveFormat(program.opts());
+      const client = createClient();
+      const baseParams = new URLSearchParams();
+      const rawLimit = Number.isFinite(opts.limit) ? opts.limit : 50;
+      const apiLimit = Math.min(Math.max(rawLimit, 1), 500);
+      const rawPage = Number.isFinite(opts.page) ? opts.page : 1;
+      const requestedPage = Math.max(rawPage, 1);
+      if (opts.search) baseParams.set("q", opts.search);
+      if (opts.default) baseParams.set("is_builtin", "true");
+      async function fetchPage(page2, limit) {
+        const params = new URLSearchParams(baseParams);
+        params.set("page", String(page2));
+        params.set("limit", String(limit));
+        const { data: data2 } = await client.get(
+          `/api/agents?${params.toString()}`
+        );
+        return data2;
+      }
+      let data;
+      if (opts.all) {
+        const first = await fetchPage(1, 500);
+        const totalPages2 = first.pagination?.totalPages ?? 1;
+        const all = [...first.agents];
+        for (let p = 2; p <= totalPages2; p++) {
+          const next = await fetchPage(p, 500);
+          all.push(...next.agents);
+        }
+        data = {
+          agents: all,
+          pagination: first.pagination ? { ...first.pagination, page: 1, limit: all.length } : {
+            total: all.length,
+            page: 1,
+            limit: all.length,
+            totalPages: 1
+          }
+        };
+      } else {
+        data = await fetchPage(requestedPage, apiLimit);
+      }
+      if (format === "json") {
+        output.log(JSON.stringify(data, null, 2));
+        return;
+      }
+      if (data.agents.length === 0) {
+        output.info("No agents found.");
+        return;
+      }
+      const total = data.pagination?.total ?? data.agents.length;
+      const shown = data.agents.length;
+      const page = data.pagination?.page ?? 1;
+      const totalPages = data.pagination?.totalPages ?? 1;
+      output.log(output.bold(`Agents (showing ${shown} of ${total}):`));
+      output.newline();
+      const rows = data.agents.map((a) => ({
+        Name: a.name,
+        Description: truncate2(a.description ?? "", 50),
+        Status: a.status,
+        Skills: String(a.skills?.length ?? 0),
+        MCP: String(a.mcp_servers?.length ?? 0)
+      }));
+      output.log(
+        formatOutput(rows, format, {
+          columns: { Description: { maxWidth: 50 } }
+        })
+      );
+      if (!opts.all && shown < total) {
+        output.newline();
+        output.dim(
+          `Page ${page}/${totalPages}. Use --page <n>, --limit <n>, --search <text>, or --all to see more.`
+        );
+      }
     }
-    const total = data.pagination?.total ?? data.agents.length;
-    output.log(output.bold(`Agents (${total} total):`));
-    output.newline();
-    const rows = data.agents.map((a) => ({
-      Name: a.name,
-      Description: truncate2(a.description ?? "", 50),
-      Status: a.status,
-      Skills: String(a.skills?.length ?? 0),
-      MCP: String(a.mcp_servers?.length ?? 0)
-    }));
-    output.log(
-      formatOutput(rows, format, {
-        columns: { Description: { maxWidth: 50 } }
-      })
-    );
-  });
+  );
   agent.command("info").description("Show agent details").argument("<name>", "Agent name or ID").action(async (nameOrId) => {
     requireAuth();
     const format = resolveFormat(program.opts());
@@ -286,7 +371,7 @@ function getApiBaseUrl() {
 async function loginViaBrowser(jsonMode) {
   const baseUrl = getApiBaseUrl();
   const state = randomBytes(16).toString("hex");
-  return new Promise((resolve9, reject) => {
+  return new Promise((resolve10, reject) => {
     const server = createServer(async (req, res) => {
       try {
         const url = new URL(req.url ?? "/", "http://localhost");
@@ -382,7 +467,7 @@ async function loginViaBrowser(jsonMode) {
             );
           }
         }
-        resolve9();
+        resolve10();
       } catch (err) {
         server.close();
         reject(
@@ -3244,6 +3329,66 @@ function printVerifyResults(results) {
   }
 }
 
+// src/commands/skill/index.ts
+import { existsSync as existsSync17, readdirSync as readdirSync2, readFileSync as readFileSync10 } from "fs";
+import { basename as basename2, resolve as resolve8 } from "path";
+var SKILL_DESCRIPTION = "Print agent usage skills (hand-off, agent-shelf, ...) as raw markdown.";
+var SKILL_HELP_AFTER = `
+Examples:
+  $ npx rush-ai skill                  Print the skills index
+  $ npx rush-ai skill hand-off         Print the hand-off playbook
+  $ npx rush-ai skill agent-shelf      Print the agent-shelf playbook
+  $ npx rush-ai skill --list           List available skills
+
+Designed to be consumed by AI agents inside IDEs (Cursor, Claude Code,
+etc). Output is raw markdown on stdout \u2014 pipe it, grep it, feed it to
+your own context.
+`;
+function resolveSkillsDir() {
+  const baseDir = import.meta.dirname ?? __dirname;
+  if (!baseDir) return null;
+  const candidates = [
+    resolve8(baseDir, "skills"),
+    resolve8(baseDir, "..", "skills"),
+    resolve8(baseDir, "..", "..", "skills"),
+    resolve8(baseDir, "..", "..", "..", "skills"),
+    resolve8(baseDir, "..", "..", "..", "..", "skills")
+  ];
+  for (const p of candidates) {
+    if (existsSync17(p)) return p;
+  }
+  return null;
+}
+function listSkills(dir) {
+  return readdirSync2(dir).filter((f) => f.endsWith(".md")).map((f) => basename2(f, ".md")).sort();
+}
+function registerSkillCommand(program) {
+  program.command("skill [name]").description(SKILL_DESCRIPTION).addHelpText("after", SKILL_HELP_AFTER).option("--list", "List available skill names and exit").action((name, opts) => {
+    const dir = resolveSkillsDir();
+    if (!dir) {
+      output.error(
+        "Could not locate the skills/ directory. This is a packaging bug \u2014 please file an issue."
+      );
+      process.exit(2);
+      return;
+    }
+    const available = listSkills(dir);
+    if (opts.list) {
+      for (const s of available) output.log(s);
+      return;
+    }
+    const target = name ?? "README";
+    const file = resolve8(dir, `${target}.md`);
+    if (!existsSync17(file)) {
+      output.error(`Unknown skill "${target}".`);
+      output.dim(`Available: ${available.join(", ") || "(none)"}`);
+      process.exit(1);
+      return;
+    }
+    process.stdout.write(readFileSync10(file, "utf-8"));
+  });
+}
+
 // src/commands/task/index.ts
 import { createWriteStream } from "fs";
 import { mkdir as mkdir2 } from "fs/promises";
@@ -3285,28 +3430,28 @@ async function readStdinIfPiped() {
   if (process.stdin.isTTY) {
     return null;
   }
-  return new Promise((resolve9, reject) => {
+  return new Promise((resolve10, reject) => {
     const chunks = [];
     process.stdin.on("data", (chunk) => {
       chunks.push(chunk);
     });
     process.stdin.on("end", () => {
-      resolve9(Buffer.concat(chunks).toString("utf-8").trim());
+      resolve10(Buffer.concat(chunks).toString("utf-8").trim());
     });
     process.stdin.on("error", reject);
   });
 }
 
 // src/commands/task/deploy.ts
-import { resolve as resolve8 } from "path";
+import { resolve as resolve9 } from "path";
 import chalk7 from "chalk";
 
 // src/util/git.ts
 import { execFileSync as execFileSync3 } from "child_process";
-import { existsSync as existsSync17 } from "fs";
+import { existsSync as existsSync18 } from "fs";
 import { join as join8 } from "path";
 function isGitRepo(projectPath) {
-  return existsSync17(join8(projectPath, ".git"));
+  return existsSync18(join8(projectPath, ".git"));
 }
 function gitInit(projectPath) {
   execFileSync3("git", ["init"], { cwd: projectPath, stdio: "pipe" });
@@ -3374,7 +3519,7 @@ function registerDeploySubcommand(task, program) {
     requireAuth();
     const format = resolveFormat(program.opts());
     const client = createClient();
-    const projectPath = resolve8(opts.path);
+    const projectPath = resolve9(opts.path);
     if (format !== "json") {
       output.info("Checking project readiness...");
     }
@@ -3618,10 +3763,31 @@ function buildCategorySummary(files) {
   }
   return Object.entries(counts).map(([cat, count]) => `${count} ${cat}`).join(", ");
 }
+var TASK_HELP_AFTER = `
+When to use:
+  Call \`task create\` whenever the next unit of work belongs on the Rush
+  platform instead of your local machine \u2014 a specialist Rush agent runs
+  it, and you get a task id to track / iterate on.
+
+Typical flows:
+  # Hand-off from an IDE conversation \u2192 Rush agent builds, you iterate
+  $ rush-ai task create -a web-builder -p "<prompt synthesized from context>" --json
+  $ rush-ai task status <id> --json          # includes previewUrl / gitRepoUrl
+  $ rush-ai task send <id> -p "<follow-up>"  # same task, keep iterating
+
+  # Quick one-shot with the default agent (\`rush\`)
+  $ rush-ai task create -a rush -p "Summarize the latest release notes"
+
+For agents: run \`rush-ai skill hand-off\` for the full playbook.
+`;
 function registerTaskCommand(program) {
-  const task = program.command("task").description("Create and manage tasks");
+  const task = program.command("task").description("Create and manage tasks").addHelpText("after", TASK_HELP_AFTER);
   registerDeploySubcommand(task, program);
-  task.command("create").description("Create a task asynchronously").requiredOption("-a, --agent <name>", "Agent name to execute the task").option("-p, --prompt <text>", "Task prompt").option("--skills <skills>", "Comma-separated skills to add", commaSplit).option("--mcp <servers>", "Comma-separated MCP servers to add", commaSplit).action(
+  task.command("create").description("Create a task asynchronously").option(
+    "-a, --agent <name>",
+    "Agent name to execute the task (defaults to `rush`)",
+    "rush"
+  ).option("-p, --prompt <text>", "Task prompt").option("--skills <skills>", "Comma-separated skills to add", commaSplit).option("--mcp <servers>", "Comma-separated MCP servers to add", commaSplit).action(
     async (options) => {
       requireAuth();
       const format = resolveFormat(program.opts());
@@ -4078,6 +4244,7 @@ function registerCommands(program) {
   registerAuthCommand(program);
   registerAgentCommand(program);
   registerTaskCommand(program);
+  registerSkillCommand(program);
   registerCheckCommand(program);
   registerMcpCommand(program);
   registerPluginCommand(program);
@@ -4149,17 +4316,29 @@ async function checkForUpdate(currentVersion) {
 // src/index.ts
 var BANNER = `
   ${chalk8.bold.cyan("Rush CLI")} ${chalk8.dim(`v${VERSION}`)}
-  ${chalk8.dim("The command-line interface for the Rush AI platform")}
+  ${chalk8.dim("Call Rush agents from your terminal \u2014 relay the context, not the prompt.")}
+
+  ${chalk8.dim("Use cases:")}
+    ${chalk8.dim("\xB7")} From Cursor / Claude Code, hand off a task to a Rush agent without restating context.
+    ${chalk8.dim("\xB7")} Compose workflows where a Rush specialist agent runs as your sub-agent.
+
+  ${chalk8.dim("For agents:")} ${chalk8.cyan("rush-ai skill")} prints ready-to-consume usage playbooks.
 `;
 function showWelcomeGuide() {
   const lines = [
     "",
     `  ${chalk8.bold.cyan("Rush CLI")} ${chalk8.dim(`v${VERSION}`)}`,
+    `  ${chalk8.dim("Call Rush agents from your terminal \u2014 relay the context, not the prompt.")}`,
     "",
     chalk8.dim("  Quick start:"),
-    `    ${chalk8.cyan("rush-ai auth login")}          Log in to Rush platform`,
-    `    ${chalk8.cyan("rush-ai agent list")}          Browse available agents`,
-    `    ${chalk8.cyan("rush-ai task create -a <agent>")} Create a task`,
+    `    ${chalk8.cyan("rush-ai auth login")}                  Log in to the Rush platform`,
+    `    ${chalk8.cyan("rush-ai agent list")}                  Browse available agents`,
+    `    ${chalk8.cyan("rush-ai task create -a web-builder")}  Hand a task to a Rush agent`,
+    "",
+    chalk8.dim("  For AI agents:"),
+    `    ${chalk8.cyan("rush-ai skill")}                       Print usage playbooks (markdown)`,
+    `    ${chalk8.cyan("rush-ai skill hand-off")}              IDE \u2192 Rush task hand-off`,
+    `    ${chalk8.cyan("rush-ai skill agent-shelf")}           Calling a Rush agent as a sub-agent`,
     ""
   ];
   try {