Load Superpowers review instructions (#13)

Co-authored-by: Danny Kim <temeddix@gmail.com>
Co-committed-by: Danny Kim <temeddix@gmail.com>

.gitea/workflows/check.yml

@@ -14,4 +14,8 @@ jobs:
 
       - uses: denoland/setup-deno@v2
 
-      - run: deno fmt --check . && deno lint . && deno check run.ts
+      - run: >-
+          deno fmt --check . &&
+          deno lint . &&
+          deno check run.ts &&
+          deno test

prompt.md

@@ -19,25 +19,42 @@ author's push credentials. Read the code there, run its checks and tests when
 they bear on the task, and push from there.
 
 For a `pull_request` event, and for a comment on a pull request that asks you to
-review it, review the PR without changing code against its base and head. Run
-the project's checks on the head and treat a failure as at least Important.
-Check the whole repository against the code rules at the end of this prompt, not
-only the diff; a violation is at least Important even when the diff did not
-cause it. Write the complete review, and nothing else, to the file
-`${REVIEW_PATH}`: it is posted verbatim as a pull request review from the bot
-account, and your final response is not posted at all. The file's first line
-must be exactly the verdict and nothing else: `Approved` when the head is ready
-to merge, `Changes requested` otherwise. The mark in front of it is added when
-posting, so write the words alone; any other first line is posted as a plain
-comment, which wastes the run. Minor issues alone never block, and neither does
-a finding the author has answered in the comment history below as intended or a
-false alarm, once the code or docs make that clear. When the verdict is
+review it, use the installed `superpowers:requesting-code-review` skill before
+inspecting the PR. Its exact installed instructions and reviewer template are
+included below, so this run fails before reaching you if they could not be
+loaded. You are the reviewer that has already been dispatched, so run the
+skill's code reviewer template yourself instead of dispatching another reviewer.
+Use the pull request and triggering instruction as its description and
+requirements, and review the exact base and head SHAs without changing code. Run
+the project's required checks on the head and treat a real failure as at least
+Important. The bot automation workflow itself is not a project check: ignore its
+skipped or canceled duplicate/automatic runs, and never reject a PR because the
+current review run is unfinished. Only a failed required check for the reviewed
+head blocks approval. Check the whole repository against the code rules at the
+end of this prompt, not only the diff; a violation is at least Important even
+when the diff did not cause it. Write the complete review, and nothing else, to
+the file `${REVIEW_PATH}`: it is posted verbatim as a pull request review from
+the bot account, and your final response is not posted at all. The file's first
+line must be exactly the verdict and nothing else: `Approved` when the head is
+ready to merge, `Changes requested` otherwise. The mark in front of it is added
+when posting, so write the words alone; any other first line is posted as a
+plain comment, which wastes the run. Minor issues alone never block, and neither
+does a finding the author has answered in the comment history below as intended
+or a false alarm, once the code or docs make that clear. When the verdict is
 `Changes requested`, the second line names what must change in one line,
 addressed to the author; the author's own agent picks the fixes up, so never ask
 `@bot` to make them. For UI changes, check that the result is aligned, clean,
 and pixel-perfect, and that included screenshots prove the intended result was
 achieved.
 
+# Installed Superpowers review skill
+
+${SUPERPOWERS_REVIEW_SKILL}
+
+# Installed Superpowers reviewer template
+
+${SUPERPOWERS_REVIEW_TEMPLATE}
+
 Every finding that belongs to one line of the diff goes on that line instead of
 into the body. Write those to `${ANCHORS_PATH}` as a JSON array, each entry
 `{"path": "<path from the repository root>", "line": <number>, "side": "new" |

run.ts

@@ -4,6 +4,13 @@
 // so it appears as the bot account.
 import { TextLineStream } from "jsr:@std/streams@1/text-line-stream";
 import { retryInvalidToken } from "./auth.ts";
+import {
+  type BotType,
+  loadSuperpowersReviewGuide,
+  parseBotType,
+  superpowersInstallCommands,
+  type SuperpowersReviewGuide,
+} from "./superpowers.ts";
 
 type GiteaUser = { login: string; email: string };
 type GiteaComment = { user: GiteaUser; created_at: string; body: string };
@@ -18,6 +25,7 @@ const API = env("GITEA_API_URL");
 const REPO = env("GITEA_REPOSITORY");
 const INDEX = env("ISSUE_INDEX");
 const EVENT = env("EVENT_NAME");
+const BOT = parseBotType(env("BOT_TYPE"));
 const AUTHOR_TOKEN = env("GITEA_TOKEN");
 const REVIEWER_TOKEN = env("REVIEWER_TOKEN");
 const RULES_PATH = "repos/commons/code-rules/raw/README.md";
@@ -146,6 +154,28 @@ async function run(command: string, args: string[]): Promise<void> {
   if (!success) throw new Error(`${command} ${args[0]} exited with ${code}`);
 }
 
+// The reviewer uses Superpowers' requesting-code-review template. Both plugin
+// installers are idempotent on the persisted bot home.
+async function installSuperpowers(bot: BotType): Promise<void> {
+  for (const { command, args } of superpowersInstallCommands(bot)) {
+    await run(command, args);
+  }
+}
+
+async function prepareSuperpowers(
+  bot: BotType,
+): Promise<SuperpowersReviewGuide> {
+  await installSuperpowers(bot);
+  const guide = await loadSuperpowersReviewGuide(bot, env("HOME"));
+  console.log(
+    `Loaded Superpowers requesting-code-review ${guide.version} from ${guide.skillPath}`,
+  );
+  console.log(
+    `Loaded Superpowers reviewer template from ${guide.templatePath}`,
+  );
+  return guide;
+}
+
 // Commits belong to the same account as the pull request they end up in.
 async function configureGitAuthor(): Promise<void> {
   const user: GiteaUser = await (await gitea(AUTHOR_TOKEN, "user")).json();
@@ -154,7 +184,7 @@ async function configureGitAuthor(): Promise<void> {
   }
 }
 
-async function renderPrompt(): Promise<string> {
+async function renderPrompt(guide: SuperpowersReviewGuide): Promise<string> {
   const comments: GiteaComment[] = await (await gitea(
     REVIEWER_TOKEN,
     `repos/${REPO}/issues/${INDEX}/comments?limit=100`,
@@ -171,6 +201,8 @@ async function renderPrompt(): Promise<string> {
     ISSUE_INDEX: INDEX,
     REVIEW_PATH,
     ANCHORS_PATH,
+    SUPERPOWERS_REVIEW_SKILL: guide.skill,
+    SUPERPOWERS_REVIEW_TEMPLATE: guide.template,
   };
   const template = await Deno.readTextFile(
     new URL("prompt.md", import.meta.url),
@@ -181,13 +213,14 @@ async function renderPrompt(): Promise<string> {
   );
 }
 
-async function runClaude(prompt: string): Promise<string> {
+async function runClaude(): Promise<string> {
   const token = Deno.env.get("BOT_TOKEN");
   if (!token) {
     throw new Error(
       "Run `claude setup-token` locally and set the `bot-token` action input.",
     );
   }
+  const prompt = await renderPrompt(await prepareSuperpowers("claude"));
   const claude = new Deno.Command("claude", {
     args: [
       "--print",
@@ -251,12 +284,13 @@ async function codexDeviceLogin(): Promise<void> {
   await Promise.all([status, drained]);
 }
 
-async function runCodex(prompt: string): Promise<string> {
+async function runCodex(): Promise<string> {
   const loggedIn = await new Deno.Command("codex", {
     args: ["login", "status"],
   })
     .output();
   if (!loggedIn.success) await codexDeviceLogin();
+  const prompt = await renderPrompt(await prepareSuperpowers("codex"));
   const file = await Deno.makeTempFile();
   const attempt = async () => {
     const codex = new Deno.Command("codex", {
@@ -293,10 +327,7 @@ async function runCodex(prompt: string): Promise<string> {
 
 try {
   await configureGitAuthor();
-  const prompt = await renderPrompt();
-  const result = env("BOT_TYPE") === "claude"
-    ? await runClaude(prompt)
-    : await runCodex(prompt);
+  const result = BOT === "claude" ? await runClaude() : await runCodex();
   await postResult(result);
 } catch (error) {
   await postComment(`Bot failed: ${error}`);

superpowers.ts

@@ -0,0 +1,147 @@
+import { join } from "jsr:@std/path@1";
+
+export type BotType = "claude" | "codex";
+
+export type InstallCommand = {
+  command: string;
+  args: string[];
+};
+
+export type SuperpowersReviewGuide = {
+  version: string;
+  skillPath: string;
+  templatePath: string;
+  skill: string;
+  template: string;
+};
+
+export type SuperpowersFileSystem = {
+  readDir(path: string): AsyncIterable<Deno.DirEntry>;
+  readTextFile(path: string): Promise<string>;
+};
+
+const systemFileSystem: SuperpowersFileSystem = {
+  readDir: Deno.readDir,
+  readTextFile: Deno.readTextFile,
+};
+
+export function parseBotType(value: string): BotType {
+  if (value === "claude" || value === "codex") return value;
+  throw new Error(`unsupported bot type: ${value}`);
+}
+
+export function superpowersInstallCommands(
+  bot: BotType,
+): InstallCommand[] {
+  if (bot === "claude") {
+    return [
+      {
+        command: "claude",
+        args: [
+          "plugin",
+          "marketplace",
+          "add",
+          "obra/superpowers-marketplace",
+        ],
+      },
+      {
+        command: "claude",
+        args: [
+          "plugin",
+          "install",
+          "-y",
+          "superpowers@superpowers-marketplace",
+        ],
+      },
+    ];
+  }
+  return [{
+    command: "codex",
+    args: ["plugin", "add", "superpowers@openai-curated-remote"],
+  }];
+}
+
+type Candidate = SuperpowersReviewGuide & { directory: string };
+
+async function readCandidate(
+  directory: string,
+  fileSystem: SuperpowersFileSystem,
+): Promise<Candidate | null> {
+  if (!directory.split(/[\\/]/).includes("superpowers")) return null;
+  const skillPath = join(directory, "SKILL.md");
+  const templatePath = join(directory, "code-reviewer.md");
+  try {
+    const [skill, template] = await Promise.all([
+      fileSystem.readTextFile(skillPath),
+      fileSystem.readTextFile(templatePath),
+    ]);
+    return {
+      directory,
+      version: directory.split(/[\\/]/).at(-3) ?? "unknown",
+      skillPath,
+      templatePath,
+      skill,
+      template,
+    };
+  } catch (error) {
+    if (error instanceof Deno.errors.NotFound) return null;
+    throw error;
+  }
+}
+
+async function findCandidates(
+  directory: string,
+  candidates: Candidate[],
+  fileSystem: SuperpowersFileSystem,
+): Promise<void> {
+  let entries: Deno.DirEntry[];
+  try {
+    entries = [];
+    for await (const entry of fileSystem.readDir(directory)) {
+      entries.push(entry);
+    }
+  } catch (error) {
+    if (error instanceof Deno.errors.NotFound) return;
+    throw error;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory) continue;
+    const child = join(directory, entry.name);
+    if (entry.name === "requesting-code-review") {
+      const candidate = await readCandidate(child, fileSystem);
+      if (candidate !== null) candidates.push(candidate);
+    } else {
+      await findCandidates(child, candidates, fileSystem);
+    }
+  }
+}
+
+// Load the installed files rather than trusting skill discovery in a later
+// non-interactive agent process. The newest cached plugin version is the one
+// the installers activate, and the exact paths are reported by the caller.
+export async function loadSuperpowersReviewGuide(
+  bot: BotType,
+  home: string,
+  fileSystem: SuperpowersFileSystem = systemFileSystem,
+): Promise<SuperpowersReviewGuide> {
+  const root = join(
+    home,
+    bot === "codex" ? ".codex" : ".claude",
+    "plugins",
+    "cache",
+  );
+  const candidates: Candidate[] = [];
+  await findCandidates(root, candidates, fileSystem);
+  candidates.sort((left, right) =>
+    left.version.localeCompare(right.version, undefined, { numeric: true }) ||
+    left.directory.localeCompare(right.directory)
+  );
+  const guide = candidates.at(-1);
+  if (guide === undefined) {
+    throw new Error(
+      `installed Superpowers requesting-code-review files not found under ${root}`,
+    );
+  }
+  const { directory: _, ...result } = guide;
+  return result;
+}

superpowers_test.ts

@@ -0,0 +1,119 @@
+import { assertEquals, assertRejects, assertThrows } from "jsr:@std/assert@1";
+import { join } from "jsr:@std/path@1";
+import {
+  loadSuperpowersReviewGuide,
+  parseBotType,
+  type SuperpowersFileSystem,
+  superpowersInstallCommands,
+} from "./superpowers.ts";
+
+function fakeFileSystem(files: Record<string, string>): SuperpowersFileSystem {
+  return {
+    readTextFile(path) {
+      const contents = files[path];
+      return contents === undefined
+        ? Promise.reject(new Deno.errors.NotFound(path))
+        : Promise.resolve(contents);
+    },
+    async *readDir(directory) {
+      const prefix = `${directory}/`;
+      const children = new Map<string, boolean>();
+      for (const path of Object.keys(files)) {
+        if (!path.startsWith(prefix)) continue;
+        const [name, ...rest] = path.slice(prefix.length).split("/");
+        if (name !== "") children.set(name, rest.length > 0);
+      }
+      if (children.size === 0) throw new Deno.errors.NotFound(directory);
+      for (const [name, isDirectory] of children) {
+        yield {
+          name,
+          isDirectory,
+          isFile: !isDirectory,
+          isSymlink: false,
+        };
+      }
+    },
+  };
+}
+
+Deno.test("installs Superpowers from the Codex marketplace", () => {
+  assertEquals(superpowersInstallCommands("codex"), [{
+    command: "codex",
+    args: ["plugin", "add", "superpowers@openai-curated-remote"],
+  }]);
+});
+
+Deno.test("installs Superpowers from the Claude marketplace", () => {
+  assertEquals(superpowersInstallCommands("claude"), [
+    {
+      command: "claude",
+      args: [
+        "plugin",
+        "marketplace",
+        "add",
+        "obra/superpowers-marketplace",
+      ],
+    },
+    {
+      command: "claude",
+      args: [
+        "plugin",
+        "install",
+        "-y",
+        "superpowers@superpowers-marketplace",
+      ],
+    },
+  ]);
+});
+
+Deno.test("rejects an unsupported bot type", () => {
+  assertThrows(
+    () => parseBotType("other"),
+    Error,
+    "unsupported bot type: other",
+  );
+});
+
+Deno.test("loads the newest installed Superpowers review guide", async () => {
+  const home = "/home/bot";
+  const older = join(
+    home,
+    ".codex/plugins/cache/openai-curated-remote/superpowers/6.3.0/skills/requesting-code-review",
+  );
+  const newer = join(
+    home,
+    ".codex/plugins/cache/openai-curated-remote/superpowers/6.10.0/skills/requesting-code-review",
+  );
+  const guide = await loadSuperpowersReviewGuide(
+    "codex",
+    home,
+    fakeFileSystem({
+      [join(older, "SKILL.md")]: "old",
+      [join(older, "code-reviewer.md")]: "old template",
+      [join(newer, "SKILL.md")]: "new",
+      [join(newer, "code-reviewer.md")]: "template",
+    }),
+  );
+
+  assertEquals(guide.version, "6.10.0");
+  assertEquals(guide.skill, "new");
+  assertEquals(guide.template, "template");
+  assertEquals(guide.skillPath, join(newer, "SKILL.md"));
+});
+
+Deno.test("fails when the installed review guide is incomplete", async () => {
+  const home = "/home/bot";
+  const directory = join(
+    home,
+    ".claude/plugins/cache/superpowers-marketplace/superpowers/6.3.0/skills/requesting-code-review",
+  );
+  const fileSystem = fakeFileSystem({
+    [join(directory, "SKILL.md")]: "skill",
+  });
+
+  await assertRejects(
+    () => loadSuperpowersReviewGuide("claude", home, fileSystem),
+    Error,
+    "installed Superpowers requesting-code-review files not found",
+  );
+});