From a027ab946337f66b5441d342e8a892c4e741d01d Mon Sep 17 00:00:00 2001 From: Edwin Jose Date: Mon, 13 Jul 2026 13:09:26 -0500 Subject: [PATCH 1/4] Add openrag-dev plugin with qa-handoff skill New sibling plugin for internal contributor/QA workflow skills (separate from the end-user-facing openrag plugin). First skill generates a QA handoff message for a release branch: per-commit fix summary, PR link, and grounded test steps within a date range, rendered from a bundled standard template. Includes a plugin README covering install/usage (Claude Code marketplace, Agent SDK, generic, and the third-party `npx skills` CLI), and updates the top-level plugin docs accordingly. --- .claude-plugin/marketplace.json | 5 ++ AGENTS.md | 6 ++ plugins/README.md | 61 ++++++++++++---- plugins/openrag-dev/README.md | 70 +++++++++++++++++++ .../openrag-dev/skills/qa-handoff/SKILL.md | 57 +++++++++++++++ .../openrag-dev/skills/qa-handoff/TEMPLATE.md | 23 ++++++ 6 files changed, 207 insertions(+), 15 deletions(-) create mode 100644 plugins/openrag-dev/README.md create mode 100644 plugins/openrag-dev/skills/qa-handoff/SKILL.md create mode 100644 plugins/openrag-dev/skills/qa-handoff/TEMPLATE.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 8789051a3..059a8cf70 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -7,6 +7,11 @@ "name": "openrag", "source": "./plugins/openrag", "description": "Guided installation and SDK integration skills for OpenRAG." + }, + { + "name": "openrag-dev", + "source": "./plugins/openrag-dev", + "description": "Developer/QA workflow skills for OpenRAG contributors." } ] } diff --git a/AGENTS.md b/AGENTS.md index 79696881f..5bf4315af 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,6 +9,12 @@ This repository ships with **agent skills** that any compliant agent can use to | `openrag_install` | [`plugins/openrag/skills/install/SKILL.md`](plugins/openrag/skills/install/SKILL.md) | Plan and execute a minimal OpenRAG installation, verify locally. | | `openrag_sdk` | [`plugins/openrag/skills/sdk/SKILL.md`](plugins/openrag/skills/sdk/SKILL.md) | Guide SDK integration (Python, TypeScript, MCP) with code examples. | +The `openrag-dev` plugin holds internal contributor/QA workflow skills (not distributed to end users installing OpenRAG): + +| Skill | File | Purpose | +| --- | --- | --- | +| `openrag_dev_qa_handoff` | [`plugins/openrag-dev/skills/qa-handoff/SKILL.md`](plugins/openrag-dev/skills/qa-handoff/SKILL.md) | Generate a QA handoff message for a release branch: per-commit fix summary, PR link, and test steps within a date range. | + ## How to use these skills Pick the path that matches your agent runtime. diff --git a/plugins/README.md b/plugins/README.md index 28e494821..09ee6a45e 100644 --- a/plugins/README.md +++ b/plugins/README.md @@ -12,51 +12,82 @@ openrag/ │ └── marketplace.json # turns the repo into a Claude Code marketplace ├── plugins/ │ ├── README.md # this file -│ └── openrag/ # one plugin, can grow to many +│ ├── openrag/ # end-user facing: install + SDK integration +│ │ ├── .claude-plugin/ +│ │ │ └── plugin.json # plugin manifest (name, version, repo) +│ │ └── skills/ +│ │ ├── install/SKILL.md # guided OpenRAG installation +│ │ └── sdk/SKILL.md # OpenRAG SDK integration helper +│ └── openrag-dev/ # internal contributor/QA workflow skills │ ├── .claude-plugin/ -│ │ └── plugin.json # plugin manifest (name, version, repo) +│ │ └── plugin.json │ └── skills/ -│ ├── install/SKILL.md # guided OpenRAG installation -│ └── sdk/SKILL.md # OpenRAG SDK integration helper +│ └── qa-handoff/SKILL.md # release-branch QA handoff generator ├── .claude/ -│ └── skills/ # symlinks into plugins/openrag/skills -│ ├── install -> ../../plugins/openrag/skills/install -│ └── sdk -> ../../plugins/openrag/skills/sdk +│ └── skills/ # symlinks into plugins//skills +│ ├── install -> ../../plugins/openrag/skills/install +│ ├── sdk -> ../../plugins/openrag/skills/sdk +│ └── qa-handoff -> ../../plugins/openrag-dev/skills/qa-handoff └── AGENTS.md # entry point for any agent working in the repo ``` -The skills under `plugins/openrag/skills/` are the single source of truth. Everything else (`.claude/skills/` symlinks, marketplace/plugin manifests, `AGENTS.md`) points at them, so edits in one place propagate everywhere. +The skills under each `plugins//skills/` directory are the single source of truth. Everything else (`.claude/skills/` symlinks, marketplace/plugin manifests, `AGENTS.md`) points at them, so edits in one place propagate everywhere. + +## Available plugins + +| Plugin | Audience | README | +| --- | --- | --- | +| `openrag` | People using/installing OpenRAG | [`plugins/openrag/`](openrag/) — install and SDK-integration skills (no dedicated README yet; see this file) | +| `openrag-dev` | OpenRAG contributors | [`plugins/openrag-dev/README.md`](openrag-dev/README.md) — internal dev/QA workflow skills | ## How users consume the skills -There are four ways to get these skills in front of an agent. +There are five ways to get these skills in front of an agent. The examples below use the `openrag` plugin; swap in `openrag-dev` (or any future plugin) to get that one instead — see its README for plugin-specific details. ### 1. Clone this repo and use Claude Code -No install step. `.claude/skills/` symlinks into the plugin, so Claude Code auto-discovers `install` and `sdk` when it starts in this directory. Invoke with `/install` or `/sdk`, or let Claude trigger them automatically based on the `description` fields. +No install step. `.claude/skills/` symlinks into each plugin, so Claude Code auto-discovers every skill (`install`, `sdk`, `qa-handoff`, ...) when it starts in this directory. Invoke with `/install`, `/sdk`, `/qa-handoff`, etc., or let Claude trigger them automatically based on the `description` fields. ### 2. Install into Claude Code globally (any project) ``` /plugin marketplace add langflow-ai/openrag /plugin install openrag@openrag +/plugin install openrag-dev@openrag ``` -The first command registers this repo as a marketplace (reads `.claude-plugin/marketplace.json`). The second installs the `openrag` plugin defined in `plugins/openrag/.claude-plugin/plugin.json`. The skills then work in any directory, not just this repo. +The first command registers this repo as a marketplace (reads `.claude-plugin/marketplace.json`). The next two install individual plugins, each defined by its own `plugins//.claude-plugin/plugin.json`. Installed skills then work in any directory, not just this repo. ### 3. Load from the Claude Agent SDK or other skill-aware runtimes -Point your skill loader at `plugins/openrag/skills/`. Each subdirectory is one skill. The SKILL.md format is Anthropic's Agent Skills spec and is consumed by the Claude Agent SDK and compatible runtimes. +Point your skill loader at `plugins//skills/`. Each subdirectory is one skill. The SKILL.md format is Anthropic's Agent Skills spec and is consumed by the Claude Agent SDK and compatible runtimes. ### 4. Any other agent (generic) Read `SKILL.md` directly. The frontmatter `description` tells the agent when the skill is relevant; the markdown body is the instruction set. `AGENTS.md` at the repo root lists the available skills and links to them. +### 5. `npx skills` CLI (any repo, any supported agent) + +[`npx skills`](https://github.com/vercel-labs/skills) is a third-party, agent-agnostic package manager for `SKILL.md`-based skills — it works with Claude Code, Cursor, OpenCode, Codex, and others. It scans a source for `SKILL.md` files and installs them into the target agent's skills directory (symlinked by default). + +```bash +# from a clone of this repo — discovers every SKILL.md across all plugins +npx skills add . --list + +# once pushed, from anywhere +npx skills add langflow-ai/openrag --skill qa-handoff + +# or point at one skill directly +npx skills add https://github.com/langflow-ai/openrag/tree/main/plugins/openrag-dev/skills/qa-handoff +``` + +This is not part of the Claude Code plugin/marketplace system above — it's a separate, agent-agnostic CLI. It only sees what's pushed to the remote (or a local path given directly), not uncommitted local changes. + ## Authoring new skills When adding a skill: -1. Create `plugins/openrag/skills//SKILL.md` with frontmatter: +1. Create `plugins//skills//SKILL.md` (e.g. `plugins/openrag/skills//SKILL.md` for end-user facing skills, `plugins/openrag-dev/skills//SKILL.md` for contributor/QA workflow skills) with frontmatter: ```yaml --- name: @@ -65,7 +96,7 @@ When adding a skill: ``` 2. Add a symlink so Claude Code in this repo picks it up: ``` - ln -s ../../plugins/openrag/skills/ .claude/skills/ + ln -s ../../plugins//skills/ .claude/skills/ ``` 3. List it in `AGENTS.md` so non-Claude agents can find it. 4. Keep the body **agent-neutral**: no references to tools or features that only exist in one runtime (no `TodoWrite`, no specific slash-command assumptions, no hook-based automations). Describe actions in generic terms: read files, run commands, fetch URLs, ask the user. @@ -73,4 +104,4 @@ When adding a skill: ## Versioning -Bump `plugins/openrag/.claude-plugin/plugin.json`'s `version` field when the skill set changes materially. Marketplace users pin to specific versions. +Bump the relevant plugin's `.claude-plugin/plugin.json` `version` field (e.g. `plugins/openrag/.claude-plugin/plugin.json`, `plugins/openrag-dev/.claude-plugin/plugin.json`) when that plugin's skill set changes materially. Marketplace users pin to specific versions. diff --git a/plugins/openrag-dev/README.md b/plugins/openrag-dev/README.md new file mode 100644 index 000000000..43d5f5cb6 --- /dev/null +++ b/plugins/openrag-dev/README.md @@ -0,0 +1,70 @@ +# OpenRAG Dev Plugin + +Internal developer/QA workflow skills for OpenRAG contributors. Unlike the `openrag` plugin (guided install, SDK integration — aimed at people using OpenRAG), this plugin is for people working *on* OpenRAG: it assumes access to the project's git history and, for full functionality, the GitHub CLI. + +## Skills + +| Skill | Purpose | +| --- | --- | +| `openrag_dev_qa_handoff` | Generate a QA handoff message for a release branch: per-commit fix summary, PR link, and test steps within a date range. See [`skills/qa-handoff/SKILL.md`](skills/qa-handoff/SKILL.md). | + +## Install + +### Option 1: Clone this repo and use Claude Code (recommended for contributors) + +No install step. `.claude/skills/qa-handoff` already symlinks into `plugins/openrag-dev/skills/qa-handoff`, so Claude Code auto-discovers it when you start a session in this repo. Invoke it with `/qa-handoff`, or just ask for a QA handoff — Claude triggers it automatically based on the skill's `description`. + +### Option 2: Install globally via the Claude Code marketplace + +``` +/plugin marketplace add langflow-ai/openrag +/plugin install openrag-dev@openrag +``` + +Makes the skill available in any repo, not just this checkout — useful since a QA handoff only needs `git`/`gh` access to whichever repo's branch you're asking about. + +### Option 3: Claude Agent SDK / other skill-aware runtimes + +Point your skill loader at `plugins/openrag-dev/skills/`. Each subdirectory is one skill (currently just `qa-handoff`). + +### Option 4: Any other agent (generic) + +Read `plugins/openrag-dev/skills/qa-handoff/SKILL.md` directly — the frontmatter `description` says when to use it, the body is the instruction set. + +### Option 5: `npx skills` CLI (any repo, any supported agent) + +[`npx skills`](https://github.com/vercel-labs/skills) is a third-party, agent-agnostic package manager for `SKILL.md`-based skills (Claude Code, Cursor, OpenCode, Codex, and others). It scans a source for `SKILL.md` files and installs them into the target agent's skills directory. + +```bash +# from a clone of this repo +npx skills add . --skill qa-handoff + +# once this repo/branch is pushed, from anywhere +npx skills add langflow-ai/openrag --skill qa-handoff + +# or point at the skill directly +npx skills add https://github.com/langflow-ai/openrag/tree/main/plugins/openrag-dev/skills/qa-handoff +``` + +This only sees what's actually pushed to the remote (or a local path you point it at directly) — it doesn't read uncommitted or unpushed local changes unless you use the local-path form above. + +## Use + +Ask your agent for a QA handoff, for example: + +- "Generate a QA handoff for release-1.52" +- "QA handoff for main, last 3 days" +- "Prepare a release handoff for release-saas-ga-0.6.2 from July 10th" + +If you don't give a date range, the skill asks how many days back to look and defaults to the **last 24 hours** if you don't answer. + +Output always follows the standard layout in [`skills/qa-handoff/TEMPLATE.md`](skills/qa-handoff/TEMPLATE.md): a header (branch, date range, latest SHA, commit count) followed by one section per commit — a plain-English one-liner, what was fixed, the PR link, and "what to test" / "how to test" bullet lists grounded in the commit's diff and PR description. + +## Requirements + +- `git`, with the branch in question fetchable +- `gh` CLI, authenticated (`gh auth status`) — optional but recommended; without it, PR links fall back to numbers parsed from commit messages and PR-body testing notes aren't available + +## Adding more skills to this plugin + +Follow the same authoring steps as the rest of the repo's skills — see [`plugins/README.md`](../README.md#authoring-new-skills). Bump this plugin's `version` in [`.claude-plugin/plugin.json`](.claude-plugin/plugin.json) when the skill set changes materially. diff --git a/plugins/openrag-dev/skills/qa-handoff/SKILL.md b/plugins/openrag-dev/skills/qa-handoff/SKILL.md new file mode 100644 index 000000000..c775a6218 --- /dev/null +++ b/plugins/openrag-dev/skills/qa-handoff/SKILL.md @@ -0,0 +1,57 @@ +--- +name: openrag_dev_qa_handoff +description: Generate a QA handoff message summarizing every commit merged into a release branch within a date range, including the branch's latest SHA, each commit's PR link, a plain-English fix summary, and concrete test steps. Use when the user asks to prepare a QA handoff, release handoff, or "what changed" summary for a branch. +--- + +Generate a QA handoff message for a release branch: a scannable, per-commit breakdown of what changed, who can review the PR, and how QA should verify it. + +## Step 1: Gather inputs + +- **Release branch**: if not given, ask for it. If the user is working inside a git repository and doesn't name a branch, offer the current branch as a candidate but confirm before using it. +- **Date range**: ask "How many days back should I look?" and offer **last 24 hours as the default** if the user gives no answer. Also accept, if the user states it directly: + - a number of days ("last 3 days") → range = now minus N days, through now + - an explicit start date, optionally with an end date ("from July 10th", "from July 10 to July 12") → use exactly as given +- If the range was inferred from a default or a vague answer, state the resolved range back to the user in one line before proceeding (e.g. "Looking at commits on `release-1.52` from 2026-07-12 09:00 to 2026-07-13 09:00."). Skip this confirmation if the user already gave explicit dates. + +## Step 2: Resolve the branch and its latest commit + +- Make sure the branch ref is current (fetch it if working from a local clone). +- Get the latest commit SHA on that branch. +- Determine the repository's owner/name from its remote URL — needed to construct PR links. + +## Step 3: List commits in range + +- List every commit reachable on the branch whose commit date falls within the resolved date range. +- Order newest first. +- If no commits fall in the range, say so plainly and stop. Do not fabricate commits or invent a handoff for an empty range. + +## Step 4: Enrich each commit + +For every commit in range, gather: + +1. **Full commit message** (subject + body) — the body sometimes has more context than the subject line alone. +2. **PR number**: most commits on this project are squash-merged and end with a trailing `(#1234)` in the subject. Extract it with a regex. Some backport commits carry two numbers (e.g. `(#1587) (#2008)`) — when that happens, use the **last** number, since that's the PR that actually merged the commit into this branch. If no number appears in the message, search for a merged pull request associated with that commit SHA instead of guessing. +3. **PR link**: build it from the repo owner/name resolved in Step 2 and the PR number, in the form `https://github.com///pull/`. +4. **PR testing notes**: fetch the pull request's description/body and look for any existing "Test plan", "Testing", or "How to test" section — reuse it rather than reinventing test steps the author already wrote. +5. **Diff**: inspect the commit's changed files and the actual diff content. This is the source of truth for what to write in "Fixed", "what to test", and "how to test" — never write a claim the diff doesn't support. +6. **Compose**, grounded in 1–5 above: + - **One-liner**: a plain-English restatement of the commit subject, with any conventional-commit prefix (`fix:`, `feat:`, `refactor:`, …) and trailing PR reference stripped. Rewrite terse subjects into something a non-author can understand. + - **Fixed**: 1–2 sentences on the actual bug or behavior addressed. Pull from the commit body or PR body if either has more detail than the subject; otherwise infer precisely from the diff. + - **What to test**: bullet list of the feature areas or user flows the diff touches. + - **How to test**: bullet list of concrete, actionable steps (setup → action → expected result). Prefer the PR's own testing notes when present; otherwise derive steps directly from the diff — never write a step disconnected from what actually changed. + +## Step 5: Render + +Fill in the standard template in `TEMPLATE.md` (bundled alongside this file) with the gathered header fields and one commit section per commit, newest first. Use that template's exact structure every time — don't freehand a different layout. + +## Step 6: Deliver + +- Post the rendered handoff message in the conversation. +- Offer — don't assume — to save it to a file such as `qa-handoff--.md` if the user wants a persistent copy. + +## Edge cases + +- **No PR found for a commit**: state "No PR found" in that commit's PR field rather than guessing a link. +- **No way to look up merged PRs by commit SHA**: fall back to regex-extracted PR numbers only, and note in the handoff that PR-body testing notes could not be checked for commits without an explicit `(#N)` reference. +- **Diff too large to read in full**: summarize from the file-level change list (which files, what kind of change) rather than skipping the commit or inventing detail. +- Never fabricate test steps, PR links, or fix descriptions that aren't grounded in the commit's actual message, diff, or PR body. diff --git a/plugins/openrag-dev/skills/qa-handoff/TEMPLATE.md b/plugins/openrag-dev/skills/qa-handoff/TEMPLATE.md new file mode 100644 index 000000000..dae356070 --- /dev/null +++ b/plugins/openrag-dev/skills/qa-handoff/TEMPLATE.md @@ -0,0 +1,23 @@ +# QA Handoff — +**Range:** → +**Latest SHA:** `` +**Commits in range:** + +--- + +## . +- **Fixed:** <1-2 sentence description of the bug/behavior fixed> +- **PR:** +- **SHA:** `` + +**What to test** +- +- <...> + +**How to test** +- +- +- <...> + +--- + From 0e4069786f5e11f79558292b54d467419be5be1f Mon Sep 17 00:00:00 2001 From: Edwin Jose Date: Mon, 13 Jul 2026 13:14:53 -0500 Subject: [PATCH 2/4] Fix npx skills --skill examples to use the SKILL.md name --skill matches against the frontmatter name (openrag_dev_qa_handoff), not the skill's directory name (qa-handoff) -- confirmed by running the CLI against this repo, which listed the skill under its frontmatter name. --- frontend/.husky/post-checkout | 1 + frontend/.husky/post-commit | 1 + frontend/.husky/post-merge | 1 + frontend/.husky/pre-commit | 2 +- plugins/README.md | 6 +++--- plugins/openrag-dev/README.md | 8 ++++---- 6 files changed, 11 insertions(+), 8 deletions(-) create mode 100755 frontend/.husky/post-checkout create mode 100755 frontend/.husky/post-commit create mode 100755 frontend/.husky/post-merge diff --git a/frontend/.husky/post-checkout b/frontend/.husky/post-checkout new file mode 100755 index 000000000..7669ee4a4 --- /dev/null +++ b/frontend/.husky/post-checkout @@ -0,0 +1 @@ +.husky/_/post-checkout diff --git a/frontend/.husky/post-commit b/frontend/.husky/post-commit new file mode 100755 index 000000000..2db986111 --- /dev/null +++ b/frontend/.husky/post-commit @@ -0,0 +1 @@ +.husky/_/post-commit diff --git a/frontend/.husky/post-merge b/frontend/.husky/post-merge new file mode 100755 index 000000000..392a1436f --- /dev/null +++ b/frontend/.husky/post-merge @@ -0,0 +1 @@ +.husky/_/post-merge diff --git a/frontend/.husky/pre-commit b/frontend/.husky/pre-commit index f450749af..ea4e3d9d3 100755 --- a/frontend/.husky/pre-commit +++ b/frontend/.husky/pre-commit @@ -1 +1 @@ -cd frontend && npx lint-staged +.husky/_/pre-commit diff --git a/plugins/README.md b/plugins/README.md index 09ee6a45e..28c4a9b7e 100644 --- a/plugins/README.md +++ b/plugins/README.md @@ -74,10 +74,10 @@ Read `SKILL.md` directly. The frontmatter `description` tells the agent when the # from a clone of this repo — discovers every SKILL.md across all plugins npx skills add . --list -# once pushed, from anywhere -npx skills add langflow-ai/openrag --skill qa-handoff +# once pushed, from anywhere — --skill matches the SKILL.md frontmatter `name`, not the directory name +npx skills add langflow-ai/openrag --skill openrag_dev_qa_handoff -# or point at one skill directly +# or point at one skill's directory directly (no --skill needed) npx skills add https://github.com/langflow-ai/openrag/tree/main/plugins/openrag-dev/skills/qa-handoff ``` diff --git a/plugins/openrag-dev/README.md b/plugins/openrag-dev/README.md index 43d5f5cb6..edfa0d2be 100644 --- a/plugins/openrag-dev/README.md +++ b/plugins/openrag-dev/README.md @@ -36,13 +36,13 @@ Read `plugins/openrag-dev/skills/qa-handoff/SKILL.md` directly — the frontmatt [`npx skills`](https://github.com/vercel-labs/skills) is a third-party, agent-agnostic package manager for `SKILL.md`-based skills (Claude Code, Cursor, OpenCode, Codex, and others). It scans a source for `SKILL.md` files and installs them into the target agent's skills directory. ```bash -# from a clone of this repo -npx skills add . --skill qa-handoff +# from a clone of this repo — --skill matches the SKILL.md frontmatter `name`, not the directory name +npx skills add . --skill openrag_dev_qa_handoff # once this repo/branch is pushed, from anywhere -npx skills add langflow-ai/openrag --skill qa-handoff +npx skills add langflow-ai/openrag --skill openrag_dev_qa_handoff -# or point at the skill directly +# or point at the skill's directory directly (no --skill needed) npx skills add https://github.com/langflow-ai/openrag/tree/main/plugins/openrag-dev/skills/qa-handoff ``` From 589e367061fbb8750e529633c025251efd13a226 Mon Sep 17 00:00:00 2001 From: Edwin Jose Date: Mon, 13 Jul 2026 13:47:18 -0500 Subject: [PATCH 3/4] delete metadata --- frontend/.husky/post-checkout | 1 - frontend/.husky/post-commit | 1 - frontend/.husky/post-merge | 1 - frontend/.husky/pre-commit | 1 - 4 files changed, 4 deletions(-) delete mode 100755 frontend/.husky/post-checkout delete mode 100755 frontend/.husky/post-commit delete mode 100755 frontend/.husky/post-merge delete mode 100755 frontend/.husky/pre-commit diff --git a/frontend/.husky/post-checkout b/frontend/.husky/post-checkout deleted file mode 100755 index 7669ee4a4..000000000 --- a/frontend/.husky/post-checkout +++ /dev/null @@ -1 +0,0 @@ -.husky/_/post-checkout diff --git a/frontend/.husky/post-commit b/frontend/.husky/post-commit deleted file mode 100755 index 2db986111..000000000 --- a/frontend/.husky/post-commit +++ /dev/null @@ -1 +0,0 @@ -.husky/_/post-commit diff --git a/frontend/.husky/post-merge b/frontend/.husky/post-merge deleted file mode 100755 index 392a1436f..000000000 --- a/frontend/.husky/post-merge +++ /dev/null @@ -1 +0,0 @@ -.husky/_/post-merge diff --git a/frontend/.husky/pre-commit b/frontend/.husky/pre-commit deleted file mode 100755 index ea4e3d9d3..000000000 --- a/frontend/.husky/pre-commit +++ /dev/null @@ -1 +0,0 @@ -.husky/_/pre-commit From a7b8d88cab9a57586db612fa82e2a699be9461af Mon Sep 17 00:00:00 2001 From: Edwin Jose Date: Thu, 16 Jul 2026 11:04:56 -0500 Subject: [PATCH 4/4] feat: add openrag_dev_backport skill, fix openrag-dev plugin wiring - Add plugins/openrag-dev/skills/backport: automates backporting commits/PRs from a source branch into a target branch (e.g. a release branch into main) -- lists missing commits, skips ones already applied under a different SHA, resolves cross-commit ordering, resolves conflicts, verifies, and opens one PR per commit. - Add the openrag-dev plugin manifest (plugins/openrag-dev/.claude-plugin/plugin.json) and the .claude/skills/qa-handoff symlink, both referenced by existing docs but missing from the branch -- without them the plugin wasn't actually installable/discoverable. - Wire the new skill into AGENTS.md and the plugins READMEs alongside qa-handoff. Also restores frontend/.husky/pre-commit, which commit 589e3670 deleted as collateral damage. Its content now matches main's exactly (cd frontend && npx lint-staged). The other three files that commit removed (post-checkout, post-commit, post-merge) were never on main -- they were transient artifacts of running `npx skills` locally in an earlier commit on this branch -- so their removal was correct and is left as-is. --- .claude/skills/backport | 1 + .claude/skills/qa-handoff | 1 + AGENTS.md | 1 + frontend/.husky/pre-commit | 1 + plugins/README.md | 8 ++- .../openrag-dev/.claude-plugin/plugin.json | 6 ++ plugins/openrag-dev/README.md | 24 ++++++-- plugins/openrag-dev/skills/backport/SKILL.md | 59 +++++++++++++++++++ .../openrag-dev/skills/backport/TEMPLATE.md | 18 ++++++ 9 files changed, 111 insertions(+), 8 deletions(-) create mode 120000 .claude/skills/backport create mode 120000 .claude/skills/qa-handoff create mode 100755 frontend/.husky/pre-commit create mode 100644 plugins/openrag-dev/.claude-plugin/plugin.json create mode 100644 plugins/openrag-dev/skills/backport/SKILL.md create mode 100644 plugins/openrag-dev/skills/backport/TEMPLATE.md diff --git a/.claude/skills/backport b/.claude/skills/backport new file mode 120000 index 000000000..cbaaad36a --- /dev/null +++ b/.claude/skills/backport @@ -0,0 +1 @@ +../../plugins/openrag-dev/skills/backport \ No newline at end of file diff --git a/.claude/skills/qa-handoff b/.claude/skills/qa-handoff new file mode 120000 index 000000000..7e5e47f7a --- /dev/null +++ b/.claude/skills/qa-handoff @@ -0,0 +1 @@ +../../plugins/openrag-dev/skills/qa-handoff \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index 5bf4315af..964695683 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,6 +14,7 @@ The `openrag-dev` plugin holds internal contributor/QA workflow skills (not dist | Skill | File | Purpose | | --- | --- | --- | | `openrag_dev_qa_handoff` | [`plugins/openrag-dev/skills/qa-handoff/SKILL.md`](plugins/openrag-dev/skills/qa-handoff/SKILL.md) | Generate a QA handoff message for a release branch: per-commit fix summary, PR link, and test steps within a date range. | +| `openrag_dev_backport` | [`plugins/openrag-dev/skills/backport/SKILL.md`](plugins/openrag-dev/skills/backport/SKILL.md) | Backport commits/PRs from a source branch into a target branch: one PR per commit, ordered, conflicts resolved and verified. | ## How to use these skills diff --git a/frontend/.husky/pre-commit b/frontend/.husky/pre-commit new file mode 100755 index 000000000..f450749af --- /dev/null +++ b/frontend/.husky/pre-commit @@ -0,0 +1 @@ +cd frontend && npx lint-staged diff --git a/plugins/README.md b/plugins/README.md index 28c4a9b7e..9193407ff 100644 --- a/plugins/README.md +++ b/plugins/README.md @@ -22,12 +22,14 @@ openrag/ │ ├── .claude-plugin/ │ │ └── plugin.json │ └── skills/ -│ └── qa-handoff/SKILL.md # release-branch QA handoff generator +│ ├── qa-handoff/SKILL.md # release-branch QA handoff generator +│ └── backport/SKILL.md # cross-branch PR backport automation ├── .claude/ │ └── skills/ # symlinks into plugins//skills │ ├── install -> ../../plugins/openrag/skills/install │ ├── sdk -> ../../plugins/openrag/skills/sdk -│ └── qa-handoff -> ../../plugins/openrag-dev/skills/qa-handoff +│ ├── qa-handoff -> ../../plugins/openrag-dev/skills/qa-handoff +│ └── backport -> ../../plugins/openrag-dev/skills/backport └── AGENTS.md # entry point for any agent working in the repo ``` @@ -46,7 +48,7 @@ There are five ways to get these skills in front of an agent. The examples below ### 1. Clone this repo and use Claude Code -No install step. `.claude/skills/` symlinks into each plugin, so Claude Code auto-discovers every skill (`install`, `sdk`, `qa-handoff`, ...) when it starts in this directory. Invoke with `/install`, `/sdk`, `/qa-handoff`, etc., or let Claude trigger them automatically based on the `description` fields. +No install step. `.claude/skills/` symlinks into each plugin, so Claude Code auto-discovers every skill (`install`, `sdk`, `qa-handoff`, `backport`, ...) when it starts in this directory. Invoke with `/install`, `/sdk`, `/qa-handoff`, `/backport`, etc., or let Claude trigger them automatically based on the `description` fields. ### 2. Install into Claude Code globally (any project) diff --git a/plugins/openrag-dev/.claude-plugin/plugin.json b/plugins/openrag-dev/.claude-plugin/plugin.json new file mode 100644 index 000000000..377d6af70 --- /dev/null +++ b/plugins/openrag-dev/.claude-plugin/plugin.json @@ -0,0 +1,6 @@ +{ + "name": "openrag-dev", + "version": "0.1.0", + "description": "OpenRAG contributor/QA workflow skills: QA handoff generation, cross-branch backporting.", + "repository": "https://github.com/langflow-ai/openrag" +} diff --git a/plugins/openrag-dev/README.md b/plugins/openrag-dev/README.md index edfa0d2be..7ce998496 100644 --- a/plugins/openrag-dev/README.md +++ b/plugins/openrag-dev/README.md @@ -7,12 +7,13 @@ Internal developer/QA workflow skills for OpenRAG contributors. Unlike the `open | Skill | Purpose | | --- | --- | | `openrag_dev_qa_handoff` | Generate a QA handoff message for a release branch: per-commit fix summary, PR link, and test steps within a date range. See [`skills/qa-handoff/SKILL.md`](skills/qa-handoff/SKILL.md). | +| `openrag_dev_backport` | Backport commits/PRs from a source branch into a target branch (e.g. a release branch into main): one PR per commit, correctly ordered, conflicts resolved and verified. See [`skills/backport/SKILL.md`](skills/backport/SKILL.md). | ## Install ### Option 1: Clone this repo and use Claude Code (recommended for contributors) -No install step. `.claude/skills/qa-handoff` already symlinks into `plugins/openrag-dev/skills/qa-handoff`, so Claude Code auto-discovers it when you start a session in this repo. Invoke it with `/qa-handoff`, or just ask for a QA handoff — Claude triggers it automatically based on the skill's `description`. +No install step. `.claude/skills/qa-handoff` and `.claude/skills/backport` already symlink into their respective `plugins/openrag-dev/skills/` directories, so Claude Code auto-discovers both when you start a session in this repo. Invoke with `/qa-handoff` or `/backport`, or just ask — Claude triggers the right one automatically based on each skill's `description`. ### Option 2: Install globally via the Claude Code marketplace @@ -25,11 +26,11 @@ Makes the skill available in any repo, not just this checkout — useful since a ### Option 3: Claude Agent SDK / other skill-aware runtimes -Point your skill loader at `plugins/openrag-dev/skills/`. Each subdirectory is one skill (currently just `qa-handoff`). +Point your skill loader at `plugins/openrag-dev/skills/`. Each subdirectory is one skill (`qa-handoff`, `backport`). ### Option 4: Any other agent (generic) -Read `plugins/openrag-dev/skills/qa-handoff/SKILL.md` directly — the frontmatter `description` says when to use it, the body is the instruction set. +Read the relevant `SKILL.md` directly (`plugins/openrag-dev/skills/qa-handoff/SKILL.md` or `plugins/openrag-dev/skills/backport/SKILL.md`) — the frontmatter `description` says when to use it, the body is the instruction set. ### Option 5: `npx skills` CLI (any repo, any supported agent) @@ -38,6 +39,7 @@ Read `plugins/openrag-dev/skills/qa-handoff/SKILL.md` directly — the frontmatt ```bash # from a clone of this repo — --skill matches the SKILL.md frontmatter `name`, not the directory name npx skills add . --skill openrag_dev_qa_handoff +npx skills add . --skill openrag_dev_backport # once this repo/branch is pushed, from anywhere npx skills add langflow-ai/openrag --skill openrag_dev_qa_handoff @@ -50,6 +52,8 @@ This only sees what's actually pushed to the remote (or a local path you point i ## Use +### QA handoff + Ask your agent for a QA handoff, for example: - "Generate a QA handoff for release-1.52" @@ -60,10 +64,20 @@ If you don't give a date range, the skill asks how many days back to look and de Output always follows the standard layout in [`skills/qa-handoff/TEMPLATE.md`](skills/qa-handoff/TEMPLATE.md): a header (branch, date range, latest SHA, commit count) followed by one section per commit — a plain-English one-liner, what was fixed, the PR link, and "what to test" / "how to test" bullet lists grounded in the commit's diff and PR description. +### Backport + +Ask your agent to backport a branch, for example: + +- "Backport release-saas-ga-0.6.2 into main" +- "Which PRs are in release-1.52 but not main? Backport them." +- "Forward-port everything in this release branch that hasn't landed on main yet" + +The skill lists commits present on the source branch but missing from the target, skips anything already applied under a different SHA, works out cross-commit ordering from file overlap, then opens one PR per commit against the target branch — conflicts are inspected and resolved (never guessed), and every resolution is verified with the relevant tests/typecheck before pushing. See [`skills/backport/SKILL.md`](skills/backport/SKILL.md) for the full procedure and [`skills/backport/TEMPLATE.md`](skills/backport/TEMPLATE.md) for the PR body layout it uses. + ## Requirements -- `git`, with the branch in question fetchable -- `gh` CLI, authenticated (`gh auth status`) — optional but recommended; without it, PR links fall back to numbers parsed from commit messages and PR-body testing notes aren't available +- `git`, with both branches fetchable +- `gh` CLI, authenticated (`gh auth status`) — required for `backport` (creating PRs); optional but recommended for `qa-handoff` (without it, PR links fall back to numbers parsed from commit messages and PR-body testing notes aren't available) ## Adding more skills to this plugin diff --git a/plugins/openrag-dev/skills/backport/SKILL.md b/plugins/openrag-dev/skills/backport/SKILL.md new file mode 100644 index 000000000..c3ca63277 --- /dev/null +++ b/plugins/openrag-dev/skills/backport/SKILL.md @@ -0,0 +1,59 @@ +--- +name: openrag_dev_backport +description: Backport commits/PRs present on a source branch but missing from a target branch (e.g. a release branch into main). Cherry-picks each missing commit, skips commits already present under a different SHA, resolves cross-commit ordering, resolves merge conflicts, verifies with tests/typecheck, and opens one PR per backported commit against the target branch. Use when the user asks to backport, forward-port, or bring one branch's changes into another. Inputs — source branch and target branch, e.g. release-saas-ga-0.6.2 into main. +--- + +Backport every commit that exists on a source branch but is missing from a target branch: one clean PR per commit, correctly ordered, conflicts resolved and verified rather than guessed. + +## Step 1: Gather inputs + +- **Source branch** and **target branch**: if either is missing, ask for both. Example: source `release-saas-ga-0.6.2`, target `main`. +- Confirm the repo/remote (`git remote -v` or the current directory's origin) rather than assuming. +- Do the work in an isolated git worktree tracking the target branch, not the user's current checkout — never disturb a working tree that might hold the user's own in-progress (possibly uncommitted) work. + +## Step 2: List candidate commits + +- Fetch both branches, then list commits reachable on source but not target: `git log .. --oneline`. +- Resolve each commit to a PR number: most commits on this project are squash-merged and end with a trailing `(#1234)` in the subject. Some backport-of-backport commits carry two numbers (e.g. `(#2016) (#2021)`) — use the **last** number, since that's the PR that actually merged the commit into the source branch. If no number appears, look up a merged PR associated with that commit SHA instead of guessing. + +## Step 3: Filter out false positives + +A commit can show up in Step 2's list yet already be effectively present on target under a *different* SHA — e.g. the original PR was merged straight to target, and only later cherry-picked into source under a new PR number (or vice versa: something merged into target already carries the same change as an older source commit). + +- Cross-check: does target's log already contain a commit referencing the same PR number, or a matching title/keywords? +- The decisive test: attempt the cherry-pick (Step 5). An **empty cherry-pick result means the change is already applied** — skip it, record it as already-present, and move on. Don't trust title-matching alone; verify with the empty-diff test before ruling a commit out. + +## Step 4: Determine ordering and dependencies + +- List the files each remaining candidate commit touches. +- Commits that touch overlapping files must be applied in the **same chronological order they were originally merged on the source branch**, each one's backport branch stacked on top of the previous dependency's backport branch — not directly on target. This reproduces the exact context the commit was originally written against and avoids spurious conflicts that have nothing to do with the real change. +- Commits with no file overlap with anything else in the candidate set branch directly off target and can be done in any order / in parallel. + +## Step 5: Apply each commit + +Work through the candidates in dependency order from Step 4. For each: + +1. Create a branch (naming: `backport/-`) off target, or off the predecessor's backport branch if it's part of a dependency chain. +2. Cherry-pick the commit. + - **Empty result** → already present on target (Step 3 confirmed this can happen) — delete the branch, record it as skipped, move to the next commit. + - **Clean pick** → continue to verification. + - **Conflict** → inspect every conflicted hunk before resolving anything. Two distinct situations look similar but need different fixes: + - *Additive conflict against an unrelated feature already independently on target* (target evolved on its own since source and this commit diverged): usually both sides' changes are wanted together. Confirm any field/parameter one side references is actually in scope on the other side (e.g. read the surrounding function signature or dataclass) before assuming "keep both" is correct — don't paste both blocks blindly. + - *Ordering conflict against another commit still waiting to be backported*: this means Step 4's dependency chain was wrong or incomplete — fix the chain (stack this branch on the right predecessor) rather than hand-resolving text that will just conflict again on the next commit. + - When a HEAD-side conflict block looks like dead/stale code inconsistent with the rest of the file (e.g. an old calling convention no longer used elsewhere in the same file), verify against the source branch's own final version of that file before trusting either side blindly. +3. Verify before pushing: run the most relevant existing tests, a typecheck, or at minimum a syntax check on every file touched by conflict resolution. Never push a conflict resolution that wasn't exercised somehow. +4. Push the branch and open one PR per commit against target: + - Title: ` (backport of #)`. + - Body: what it backports (link the source PR), any dependency PRs this one is stacked on plus the required merge order, and — if conflicts needed resolving — a plain description of the reasoning and how it was verified (tests run, typecheck clean, etc.). + +## Step 6: Report + +Give the user a table: PR opened per commit, the merge order required for any stacked chain (call out explicitly which PRs must land before which), and which candidate commits were skipped because they were already present on target (with which existing target commit/PR made them redundant, if known). + +## Edge cases + +- **No candidate commits found**: say so plainly and stop. Do not fabricate a backport for an empty diff. +- **Commit has no associated PR** (direct push): fall back to referencing the commit SHA and message in the PR body instead of a PR link. +- **Updating an existing backport PR whose target has advanced**: if a predecessor in a stacked chain merges and a later PR in the chain now conflicts against the new target tip, merge target into that branch and resolve using the same judgment as Step 5 — don't recreate the branch from scratch unless asked. +- Never force-push over an already-open backport branch without first checking its current state (`gh pr view`) — another commit or review feedback may already be on it. +- Never touch a PR the user has explicitly said to leave alone. diff --git a/plugins/openrag-dev/skills/backport/TEMPLATE.md b/plugins/openrag-dev/skills/backport/TEMPLATE.md new file mode 100644 index 000000000..fa86f3aa2 --- /dev/null +++ b/plugins/openrag-dev/skills/backport/TEMPLATE.md @@ -0,0 +1,18 @@ +# Backport PR body — → + +## Summary +Backports # from `` to ``. + +<1-2 sentence plain-English description of what the change does> + +## Depends on + +Depends on <#PR> () — stacked because it touches in the same area. Merge order: <#PR1> → <#PR2> → ... → this PR. + +## Conflict notes + +Cherry-pick conflicted in `` against . Resolved by . Verified with . + +## Test plan +- [ ] +- [ ] CI passes