From 556fc661a09687fdf92cdaeb6201279ad9259bd5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Elberte=20Pl=C3=ADnio?= Date: Wed, 26 Aug 2026 11:57:25 -0300 Subject: [PATCH 1/2] feat(review-tutor): add harness adapters --- .claude-plugin/marketplace.json | 17 ++++++++ packages/review-tutor/README.md | 40 ++++++++++++++++--- .../claude-plugin/.claude-plugin/plugin.json | 11 +++++ .../skills/review-tutor/SKILL.md | 12 ++++++ .../codex-skill/review-tutor/SKILL.md | 14 +++++++ 5 files changed, 89 insertions(+), 5 deletions(-) create mode 100644 .claude-plugin/marketplace.json create mode 100644 packages/review-tutor/claude-plugin/.claude-plugin/plugin.json create mode 100644 packages/review-tutor/claude-plugin/skills/review-tutor/SKILL.md create mode 100644 packages/review-tutor/codex-skill/review-tutor/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..f5b544e --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,17 @@ +{ + "name": "pickforge", + "owner": { + "name": "Pickforge" + }, + "plugins": [ + { + "name": "review-tutor", + "description": "Open the Pickforge Review Tutor for a PR, diff, or commit in your browser.", + "source": { + "source": "git-subdir", + "url": "https://github.com/pickforge/pickforge-platform.git", + "path": "packages/review-tutor/claude-plugin" + } + } + ] +} diff --git a/packages/review-tutor/README.md b/packages/review-tutor/README.md index 7e53783..9ee54b8 100644 --- a/packages/review-tutor/README.md +++ b/packages/review-tutor/README.md @@ -4,21 +4,51 @@ Review Tutor is a local-first, browser-based companion for guided reviews of PRs ## Install -This package is private and remains at version `0.0.0`, so it is not available through the npm scope. Install it from a local checkout: +Requirements: Node 22 or newer, Git, and whichever of `pi`, `claude`, or `codex` you want as tutor harnesses, each logged in. + +### Pi + +Install from npm or a checkout: ```bash +pi install npm:@pickforge/review-tutor pi install /absolute/path/to/packages/review-tutor ``` -The package manifest loads both the extension and the tutor skill. +Then run: + +```text +/review-tutor +``` + +### Claude Code + +```bash +claude plugin marketplace add pickforge/pickforge-platform +claude plugin install review-tutor@pickforge +``` + +Then run: + +```text +/review-tutor +``` + +### Codex -To try it for one Pi run without installing it: +From a checkout, copy the skill into your Codex home: ```bash -pi -e /absolute/path/to/packages/review-tutor +cp -r packages/review-tutor/codex-skill/review-tutor ~/.codex/skills/review-tutor ``` -`-e` loads the extension only; the tutor skill is registered by `pi install`. The `/review-tutor` command still works fully either way because it reads its skill file directly from the package. +Then ask Codex to "open the review tutor for …". + +### Any shell + +```bash +npx -y @pickforge/review-tutor worktree +``` ## Usage diff --git a/packages/review-tutor/claude-plugin/.claude-plugin/plugin.json b/packages/review-tutor/claude-plugin/.claude-plugin/plugin.json new file mode 100644 index 0000000..2d17a72 --- /dev/null +++ b/packages/review-tutor/claude-plugin/.claude-plugin/plugin.json @@ -0,0 +1,11 @@ +{ + "name": "review-tutor", + "version": "0.0.0", + "description": "Open the Pickforge Review Tutor for a PR, diff, or commit in your browser.", + "author": { + "name": "Pickforge" + }, + "homepage": "https://github.com/pickforge/pickforge-platform/tree/main/packages/review-tutor", + "repository": "https://github.com/pickforge/pickforge-platform", + "license": "MIT" +} diff --git a/packages/review-tutor/claude-plugin/skills/review-tutor/SKILL.md b/packages/review-tutor/claude-plugin/skills/review-tutor/SKILL.md new file mode 100644 index 0000000..e30bfe9 --- /dev/null +++ b/packages/review-tutor/claude-plugin/skills/review-tutor/SKILL.md @@ -0,0 +1,12 @@ +--- +name: review-tutor +description: Open the Review Tutor for a review, PR, diff, or commit in your browser. +disable-model-invocation: true +allowed-tools: Bash(npx -y @pickforge/review-tutor *) +--- + +Review Tutor starts locally and prints its browser session URL. + +!`npx -y @pickforge/review-tutor $ARGUMENTS --detach` + +The URL above is a one-time session link on 127.0.0.1; open it in your browser. Nothing from this conversation is sent to the tutor. diff --git a/packages/review-tutor/codex-skill/review-tutor/SKILL.md b/packages/review-tutor/codex-skill/review-tutor/SKILL.md new file mode 100644 index 0000000..f59096f --- /dev/null +++ b/packages/review-tutor/codex-skill/review-tutor/SKILL.md @@ -0,0 +1,14 @@ +--- +name: review-tutor +description: Open the Review Tutor when the user asks for a review, PR, diff, or tutor session. +--- + +Run this command in the repository root: + +```bash +npx -y @pickforge/review-tutor --detach +``` + +`` can be `worktree`, `staged`, `a...b`, a commit, or a GitHub PR URL. + +Print the URL to the user verbatim. Do not open or fetch the URL yourself. From c920c30636347d05505bcc02582e5bc6d781b72d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Elberte=20Pl=C3=ADnio?= Date: Wed, 26 Aug 2026 12:11:39 -0300 Subject: [PATCH 2/2] fix(review-tutor): address harness adapter review --- .claude-plugin/marketplace.json | 1 + packages/review-tutor/README.md | 2 ++ .../claude-plugin/.claude-plugin/plugin.json | 2 +- .../claude-plugin/skills/review-tutor/SKILL.md | 12 +++++++----- 4 files changed, 11 insertions(+), 6 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index f5b544e..5a8e453 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,5 +1,6 @@ { "name": "pickforge", + "description": "Pickforge Studio plugins.", "owner": { "name": "Pickforge" }, diff --git a/packages/review-tutor/README.md b/packages/review-tutor/README.md index 9ee54b8..c67fcba 100644 --- a/packages/review-tutor/README.md +++ b/packages/review-tutor/README.md @@ -4,6 +4,8 @@ Review Tutor is a local-first, browser-based companion for guided reviews of PRs ## Install +The npm package ships with pickforge-platform v0.13.0; until then, use a checkout: `pi install /path/to/packages/review-tutor` and `node packages/review-tutor/dist/bin.js …` after `bun run build`. + Requirements: Node 22 or newer, Git, and whichever of `pi`, `claude`, or `codex` you want as tutor harnesses, each logged in. ### Pi diff --git a/packages/review-tutor/claude-plugin/.claude-plugin/plugin.json b/packages/review-tutor/claude-plugin/.claude-plugin/plugin.json index 2d17a72..b788f37 100644 --- a/packages/review-tutor/claude-plugin/.claude-plugin/plugin.json +++ b/packages/review-tutor/claude-plugin/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "review-tutor", - "version": "0.0.0", + "version": "0.12.0", "description": "Open the Pickforge Review Tutor for a PR, diff, or commit in your browser.", "author": { "name": "Pickforge" diff --git a/packages/review-tutor/claude-plugin/skills/review-tutor/SKILL.md b/packages/review-tutor/claude-plugin/skills/review-tutor/SKILL.md index e30bfe9..0d923d2 100644 --- a/packages/review-tutor/claude-plugin/skills/review-tutor/SKILL.md +++ b/packages/review-tutor/claude-plugin/skills/review-tutor/SKILL.md @@ -5,8 +5,10 @@ disable-model-invocation: true allowed-tools: Bash(npx -y @pickforge/review-tutor *) --- -Review Tutor starts locally and prints its browser session URL. - -!`npx -y @pickforge/review-tutor $ARGUMENTS --detach` - -The URL above is a one-time session link on 127.0.0.1; open it in your browser. Nothing from this conversation is sent to the tutor. +From the repository root, use Bash to run `npx -y @pickforge/review-tutor --detach`. +Pass the user's argument as ONE single-quoted argv (`'…'`), defaulting to `'worktree'` when absent. +Accepted forms are `worktree`, `staged`, `a...b`, a commit, or a GitHub PR URL. +If the argument contains anything outside `[A-Za-z0-9._/:@#~^-]`, refuse and ask the user to re-enter it. +Print the single URL line verbatim to the user. +Never open, fetch, or curl the URL. +Nothing from the conversation is sent to the tutor.