@minakoto00/skills 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 minakoto00
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# VCS Review Flow
+
+`VCS Review Flow` is a `skills.sh`-ready repository of skills for reviewing GitHub pull requests and GitLab merge requests through local worktrees. Install the skill you need, then follow the skill-local guide for workflow details.
+
+## Quickstart
+
+Primary install:
+
+```bash
+npx skills add minakoto00/vcs-review-flow --skill review-pr
+```
+
+Optional shortcut:
+
+```bash
+npx @minakoto00/skills install review-pr
+```
+
+## Available Skills
+
+- `review-pr`: Review the latest open PR or MR in a dedicated worktree and turn remote feedback into a validated change plan. See `skills/review-pr/README.md`.
+
+## Updates
+
+```bash
+npx skills check
+npx skills update
+```
+
+## Advanced Manual Install
+
+For local development or power users, the repo still includes `install-skill.sh`.
+
+```bash
+bash ./install-skill.sh
+```
+
+Use `bash ./install-skill.sh --help` for scripted flags and dry-run options.
+
+## Repository Layout
+
+- `skills/review-pr/README.md`: full guide for the `review-pr` skill
+- `skills/review-pr/SKILL.md`: skill entrypoint used by agents
+- `skills/review-pr/scripts/`: helper scripts used by the skill workflow
+- `install-skill.sh`: advanced manual installer
+- `bin/skills.js`: npm wrapper for `npx @minakoto00/skills install review-pr`
+
+## License
+
+This repository and the published `@minakoto00/skills` package are available under the MIT License. See `LICENSE`.

package/bin/skills.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require("node:child_process");
+
+const REPOSITORY = "minakoto00/vcs-review-flow";
+const SUPPORTED_SKILLS = new Set(["review-pr"]);
+
+function usage() {
+  console.error("Usage: @minakoto00/skills install <skill-name> [--dry-run]");
+}
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+function buildInstallArgs(skillName) {
+  return ["skills", "add", REPOSITORY, "--skill", skillName];
+}
+
+function npxCommand() {
+  return process.platform === "win32" ? "npx.cmd" : "npx";
+}
+
+const args = process.argv.slice(2);
+const dryRunIndex = args.indexOf("--dry-run");
+const dryRun = dryRunIndex !== -1;
+
+if (dryRun) {
+  args.splice(dryRunIndex, 1);
+}
+
+const [command, skillName] = args;
+
+if (command !== "install" || !skillName || args.length !== 2) {
+  usage();
+  process.exit(1);
+}
+
+if (!SUPPORTED_SKILLS.has(skillName)) {
+  fail(`unsupported skill: ${skillName}`);
+}
+
+const installArgs = buildInstallArgs(skillName);
+const renderedCommand = [npxCommand(), ...installArgs].join(" ");
+
+if (dryRun) {
+  console.log(renderedCommand);
+  process.exit(0);
+}
+
+const result = spawnSync(npxCommand(), installArgs, { stdio: "inherit" });
+
+if (result.error) {
+  fail(result.error.message);
+}
+
+process.exit(result.status ?? 1);

package/install-skill.sh

@@ -0,0 +1,213 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+# shellcheck source=./skills/review-pr/scripts/common.sh
+source "$SCRIPT_DIR/skills/review-pr/scripts/common.sh"
+
+agent=
+scope=
+method=
+project_root=
+conflict_strategy=
+dry_run=false
+
+usage() {
+  cat <<'USAGE'
+Usage: install-skill.sh [--agent codex|claude] [--scope user-global|project-local] [--method symlink|copy] [--project-root <path>] [--conflict replace|backup|cancel] [--dry-run]
+
+Interactive installer for the review-pr skill.
+USAGE
+}
+
+prompt_with_default() {
+  local prompt=$1
+  local default_value=$2
+  local value
+  printf '%s [%s]: ' "$prompt" "$default_value" >&2
+  read -r value
+  printf '%s' "${value:-$default_value}"
+}
+
+choose_option() {
+  local prompt=$1
+  local default_value=$2
+  shift 2
+  local options=("$@")
+  local answer
+  while true; do
+    printf '%s\n' "$prompt" >&2
+    local index=1
+    for option in "${options[@]}"; do
+      if [[ "$option" == "$default_value" ]]; then
+        printf '  %s. %s (default)\n' "$index" "$option" >&2
+      else
+        printf '  %s. %s\n' "$index" "$option" >&2
+      fi
+      index=$((index + 1))
+    done
+    printf '> ' >&2
+    read -r answer
+    answer=${answer:-$default_value}
+    if [[ "$answer" == "$default_value" ]]; then
+      printf '%s\n' "$default_value"
+      return 0
+    fi
+    if [[ "$answer" =~ ^[0-9]+$ ]] && (( answer >= 1 && answer <= ${#options[@]} )); then
+      printf '%s\n' "${options[answer-1]}"
+      return 0
+    fi
+    for option in "${options[@]}"; do
+      if [[ "$answer" == "$option" ]]; then
+        printf '%s\n' "$option"
+        return 0
+      fi
+    done
+    printf 'Invalid choice. Try again.\n' >&2
+  done
+}
+
+determine_target_root() {
+  case "$agent:$scope" in
+    codex:user-global)
+      printf '%s/.agents/skills\n' "$HOME"
+      ;;
+    codex:project-local)
+      printf '%s/.agents/skills\n' "$project_root"
+      ;;
+    claude:user-global)
+      printf '%s/.claude/skills\n' "$HOME"
+      ;;
+    claude:project-local)
+      printf '%s/.claude/skills\n' "$project_root"
+      ;;
+    *)
+      die "unsupported install target: $agent:$scope"
+      ;;
+  esac
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --agent)
+      agent=$2
+      shift 2
+      ;;
+    --scope)
+      scope=$2
+      shift 2
+      ;;
+    --method)
+      method=$2
+      shift 2
+      ;;
+    --project-root)
+      project_root=$2
+      shift 2
+      ;;
+    --conflict)
+      conflict_strategy=$2
+      shift 2
+      ;;
+    --dry-run)
+      dry_run=true
+      shift
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      die "unknown argument: $1"
+      ;;
+  esac
+done
+
+if [[ -z "$agent" ]]; then
+  agent=$(choose_option "Select target agent" codex codex claude)
+fi
+
+if [[ -z "$scope" ]]; then
+  scope=$(choose_option "Select install scope" user-global user-global project-local)
+fi
+
+if [[ -z "$method" ]]; then
+  method=$(choose_option "Select install method" symlink symlink copy)
+fi
+
+if [[ "$scope" == project-local ]]; then
+  default_root=$(pwd)
+  if [[ -z "$project_root" ]]; then
+    project_root=$(prompt_with_default "Project root" "$default_root")
+  fi
+  project_root=$(normalize_path "$project_root")
+fi
+
+case "$agent" in
+  codex|claude) ;;
+  *) die "agent must be codex or claude" ;;
+esac
+
+case "$scope" in
+  user-global|project-local) ;;
+  *) die "scope must be user-global or project-local" ;;
+esac
+
+case "$method" in
+  symlink|copy) ;;
+  *) die "method must be symlink or copy" ;;
+esac
+
+source_dir=$(normalize_path "$SCRIPT_DIR/skills/review-pr")
+skill_name=review-pr
+target_root=$(determine_target_root)
+target_path="$target_root/$skill_name"
+
+if [[ "$dry_run" == true ]]; then
+  print_kv agent "$agent"
+  print_kv scope "$scope"
+  print_kv method "$method"
+  print_kv source_dir "$source_dir"
+  print_kv target_root "$target_root"
+  print_kv target_path "$target_path"
+  print_kv project_root "$project_root"
+  exit 0
+fi
+
+mkdir -p "$target_root"
+
+if [[ -e "$target_path" || -L "$target_path" ]]; then
+  if [[ -z "$conflict_strategy" ]]; then
+    conflict_strategy=$(choose_option "Existing installation found. Choose conflict action" cancel cancel replace backup)
+  fi
+
+  case "$conflict_strategy" in
+    cancel)
+      printf 'Installation cancelled.\n'
+      exit 0
+      ;;
+    replace)
+      rm -rf "$target_path"
+      ;;
+    backup)
+      mv "$target_path" "$target_path.bak.$(date +%Y%m%d%H%M%S)"
+      ;;
+    *)
+      die "conflict strategy must be replace, backup, or cancel"
+      ;;
+  esac
+fi
+
+case "$method" in
+  symlink)
+    ln -s "$source_dir" "$target_path"
+    ;;
+  copy)
+    cp -R "$source_dir" "$target_path"
+    ;;
+esac
+
+print_kv agent "$agent"
+print_kv scope "$scope"
+print_kv method "$method"
+print_kv target_path "$target_path"

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@minakoto00/skills",
+  "version": "0.1.0",
+  "description": "Convenience installer for skills hosted in minakoto00/vcs-review-flow.",
+  "bin": {
+    "minakoto-skills": "bin/skills.js"
+  },
+  "files": [
+    "README.md",
+    "LICENSE",
+    "bin/",
+    "install-skill.sh",
+    "skills/"
+  ],
+  "license": "MIT"
+}

package/skills/review-pr/README.md

@@ -0,0 +1,163 @@
+# Review PR
+
+`review-pr` reviews the latest open GitHub pull request or GitLab merge request through a local worktree, gathers remote feedback, validates which comments still matter, and then either implements fixes locally or posts a concrete proposal back to the remote.
+
+## What It Does
+
+- resolves the latest open MR/PR, or a user-specified MR/PR number
+- fetches MR/PR review feedback and splits it into `code-review comments` and `discussion comments`
+- detects GitHub vs GitLab from the repo remote
+- inspects `AGENTS.md` and `CLAUDE.md` before any worktree action
+- reuses or creates the correct local worktree for the MR/PR source branch
+- syncs the worktree to the remote branch head
+- supports a review flow that ends with a change plan and explicit finish options
+- can post proposed changes back as a GitLab or GitHub comment instead of implementing locally
+
+## Prerequisites
+
+- `git`
+- `jq`
+- `gh` for GitHub repositories
+- `glab` for GitLab repositories
+
+## Install
+
+Primary install:
+
+```bash
+npx skills add minakoto00/vcs-review-flow --skill review-pr
+```
+
+Optional shortcut:
+
+```bash
+npx @minakoto00/skills install review-pr
+```
+
+## How It Works
+
+From a repository you want to review, the core steps are:
+
+1. Detect the platform.
+2. Resolve the latest open MR/PR or a specific one.
+3. Fetch comment summaries for the MR/PR.
+4. Inspect repo policy from `AGENTS.md` and `CLAUDE.md`.
+5. Ask the user whether to include code-review comments in scope.
+6. Ask the user whether to include discussion comments in scope.
+7. Reuse or create the source-branch worktree.
+8. Run review in that worktree.
+9. Produce a change plan.
+10. Choose whether to implement locally or post the proposal remotely.
+
+If comments are present:
+- ask the user whether to include code-review comments in scope
+- ask the user whether to include discussion comments in scope
+- only the approved comment categories move forward
+- resolved code-review feedback is excluded by default
+- outdated threads are validated separately from unresolved threads
+- group approved unresolved and outdated code-review feedback into issue clusters before validation
+- dispatch several subagents in parallel when approved comments need validation
+- search only within changed files for same-pattern candidates
+- report same-pattern candidates separately from the original issues
+- show a verification report before planning fixes
+- if the user confirms, keep the confirmed issues in scope even when tests do not yet cover them
+
+## Flowchart
+
+```mermaid
+flowchart TD
+    A[Resolve repository root] --> B[Detect GitHub or GitLab]
+    B --> C{Latest open review target or explicit number?}
+    C -->|Latest| D[Resolve latest MR or PR]
+    C -->|Specific| E[Resolve specified MR or PR]
+    D --> F[Fetch review comments]
+    E --> F
+    F --> G{Include code-review comments?}
+    G -->|Yes| H{Include discussion comments?}
+    G -->|No| H
+    H --> I[Inspect AGENTS.md and CLAUDE.md policy]
+    I --> J[Reuse or create worktree]
+    J --> K[Run review in worktree]
+    K --> L[Validate approved comments and same-pattern candidates]
+    L --> M[Confirm verification report]
+    M --> N[Produce change plan]
+    N --> O{Finish option}
+    O -->|1| P[Implement on original source branch]
+    O -->|2| Q[Implement, then merge or cherry-pick elsewhere]
+    O -->|3| R[Post comment-only proposal]
+```
+
+## Local Development
+
+When running the skill directly from a clone of this repository, use the scripts under `skills/review-pr/`.
+
+Detect platform:
+
+```bash
+bash ./skills/review-pr/scripts/detect_platform.sh --repo /path/to/repo
+```
+
+Resolve the latest open MR/PR:
+
+```bash
+bash ./skills/review-pr/scripts/resolve_review_target.sh \
+  --repo /path/to/repo \
+  --latest
+```
+
+Resolve a specific MR/PR number:
+
+```bash
+bash ./skills/review-pr/scripts/resolve_review_target.sh \
+  --repo /path/to/repo \
+  --number 123
+```
+
+Inspect repo worktree policy:
+
+```bash
+bash ./skills/review-pr/scripts/repo_policy.sh \
+  --repo /path/to/repo
+```
+
+Fetch review comments:
+
+```bash
+bash ./skills/review-pr/scripts/fetch_review_comments.sh \
+  --repo /path/to/repo \
+  --number 123 \
+  --platform github \
+  --json
+```
+
+Prepare or reuse the worktree:
+
+```bash
+bash ./skills/review-pr/scripts/worktree_sync.sh \
+  --repo /path/to/repo \
+  --source-branch feat/example \
+  --head-sha abcdef1234567890
+```
+
+Post a comment-only proposal:
+
+```bash
+bash ./skills/review-pr/scripts/post_review_comment.sh \
+  --repo /path/to/repo \
+  --number 123 \
+  --body-file /tmp/review-plan.md
+```
+
+## Safety Rules
+
+- The skill reads both `AGENTS.md` and `CLAUDE.md` when present.
+- If those files conflict on worktree policy, it stops instead of guessing.
+- If an existing worktree is dirty, it stops before syncing.
+- It does not force-push unless the user explicitly asks.
+- It requires `gh` or `glab` authentication for live remote operations.
+
+## Related Files
+
+- `skills/review-pr/SKILL.md`: skill entrypoint and workflow contract
+- `skills/review-pr/scripts/`: runtime helpers for platform detection, target resolution, policy parsing, worktree sync, and comment posting
+- `skills/review-pr/docs/examples.md`: extra examples

package/skills/review-pr/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: review-pr
+description: Use when you need to review or update the latest open GitLab merge request or GitHub pull request through a local worktree, or when a user provides a specific MR or PR number.
+---
+
+# Review PR
+
+Use this skill when the user wants you to pull, review, or update a remote GitLab MR or GitHub PR through a local worktree instead of switching the current checkout.
+
+## Prerequisites
+
+- `git`
+- `jq`
+- `gh` for GitHub repositories
+- `glab` for GitLab repositories
+
+## Workflow
+
+1. Resolve the repository root.
+
+```bash
+git rev-parse --show-toplevel
+```
+
+2. Detect the VCS platform.
+
+```bash
+bash scripts/detect_platform.sh --repo <repo-root>
+```
+
+3. Resolve the review target.
+
+Latest open MR/PR:
+
+```bash
+bash scripts/resolve_review_target.sh --repo <repo-root> --latest
+```
+
+Specific MR/PR number:
+
+```bash
+bash scripts/resolve_review_target.sh --repo <repo-root> --number <number>
+```
+
+4. Fetch remote review comments for the resolved MR/PR.
+
+```bash
+bash scripts/fetch_review_comments.sh --repo <repo-root> --number <number> --platform <github|gitlab> --json
+```
+
+Rules:
+- if `code-review comments` exist, ask the user whether to include code-review comments in scope before continuing
+- if `discussion comments` exist, ask the user whether to include discussion comments in scope after the code-review comment decision
+- only the approved comment categories enter the active review scope
+- preserve richer remote metadata for approved code-review comments when the platform provides it
+- resolved code-review feedback is excluded from review scope by default
+- outdated code-review feedback is validated separately from unresolved threads
+- approved unresolved and outdated code-review feedback is grouped into issue clusters before validation
+- if any categories are approved, dispatch several subagents in parallel to validate whether those approved comments still make sense
+- subagents search only within changed files for same-pattern candidates
+- report same-pattern candidates separately from the original issue clusters
+- present a simple verification report before planning fixes
+- ask the user to confirm the verification report before planning fixes
+- if the user confirms, treat the confirmed comments as in-scope issues even when tests do not yet cover them
+
+5. Inspect repository policy before touching worktrees.
+
+```bash
+bash scripts/repo_policy.sh --repo <repo-root>
+```
+
+Read both `AGENTS.md` and `CLAUDE.md` when present. If they conflict on worktree location or workflow, surface that conflict instead of guessing.
+
+6. Reuse or create the worktree for the MR/PR source branch.
+
+```bash
+bash scripts/worktree_sync.sh \
+  --repo <repo-root> \
+  --source-branch <source-branch> \
+  --head-sha <head-sha>
+```
+
+Rules:
+- if the matching worktree already exists locally, sync it to the latest remote branch head
+- if the matching worktree does not exist, create it in the repo-approved location
+- if the existing worktree has uncommitted changes, stop and ask before syncing
+
+7. Run review from the prepared worktree.
+
+If the environment exposes a review skill such as `requesting-code-review`, invoke it with:
+- the user's review request
+- the resolved base/head context
+- the approved comment categories plus their pulled comment content
+- the richer remote metadata for approved code-review comments
+- the prepared worktree path
+
+If no dedicated review skill is available, perform the review directly with a code-review mindset.
+
+8. If approved comment categories were selected, validate them before fix planning.
+
+For approved comments:
+- exclude resolved code-review feedback from active validation by default
+- validate outdated threads separately from unresolved threads
+- group approved code-review feedback into issue clusters before dispatch
+- dispatch several subagents in parallel to classify each selected comment or issue cluster as likely valid, unclear, or likely stale
+- search only within changed files for same-pattern candidates
+- report same-pattern candidates separately from the original issue clusters
+- produce a verification report with a short reason for each classification
+- ask the user to confirm the verification report before planning fixes
+
+9. After review and any required confirmation, produce a change plan.
+
+The change plan must include:
+- key findings being addressed
+- likely files or areas to change
+- implementation direction
+- verification steps
+
+If the user confirmed approved comments as valid, include them in the change plan even when tests do not yet cover them.
+
+10. Present exactly these finish options.
+
+```text
+1. Implement locally on the original source branch, commit, and push to update the MR/PR.
+2. Implement locally on the original source branch, commit there, then merge or cherry-pick into a user-specified branch.
+3. Do not implement locally; post the proposed changes as a GitLab/GitHub comment with concrete patch guidance.
+```
+
+## Safety Stops
+
+- Stop if `gh` or `glab` is missing for the detected platform.
+- Stop if authentication fails.
+- Stop if there are no open MRs/PRs.
+- Stop if the remote source branch no longer exists.
+- Stop before syncing a dirty worktree.
+- Never force-push unless the user explicitly asks.
+
+## Quick Reference
+
+Detect platform:
+
+```bash
+bash scripts/detect_platform.sh --repo <repo-root>
+```
+
+Resolve latest target:
+
+```bash
+bash scripts/resolve_review_target.sh --repo <repo-root> --latest
+```
+
+Resolve explicit target:
+
+```bash
+bash scripts/resolve_review_target.sh --repo <repo-root> --number 123
+```
+
+Inspect repo policy:
+
+```bash
+bash scripts/repo_policy.sh --repo <repo-root>
+```
+
+Sync worktree:
+
+```bash
+bash scripts/worktree_sync.sh --repo <repo-root> --source-branch feat/example --head-sha <sha>
+```
+
+Fetch review comments:
+
+```bash
+bash scripts/fetch_review_comments.sh --repo <repo-root> --number 123 --platform github --json
+```
+
+Post comment-only proposal:
+
+```bash
+bash scripts/post_review_comment.sh --repo <repo-root> --number 123 --body-file /tmp/review-plan.md
+```