feat(commands): add research-tool-updates and understand-scrap-issues commands

.rulesync/commands/research-tool-updates.md

@@ -0,0 +1,224 @@
+---
+targets:
+  - claudecode
+description: >-
+  Research recent upstream releases of every rulesync target tool, detect
+  capabilities rulesync has not yet followed, and file one GitHub issue per
+  tool for the gaps.
+---
+
+# Research Tool Updates
+
+TARGET = $ARGUMENTS
+
+Purpose: for every target tool rulesync supports, investigate the tool's recent
+releases (official release notes / GitHub releases preferred), compare them
+against rulesync's current implementation, and open a per-tool GitHub issue for
+any upstream capability rulesync has not yet caught up with. When an issue for
+that tool already exists, supplement it with a comment instead of filing a
+duplicate.
+
+## Step 0: Determine Scope
+
+- If `TARGET` is provided, investigate **only that tool**. Accept either the
+  display name (e.g., `Claude Code`) or the `--targets` id (e.g., `claudecode`).
+  Validate it against the supported tool list from Step 1; if it does not match
+  any known tool, stop and report the valid options.
+- If `TARGET` is empty, investigate **all** supported target tools.
+
+## Step 1: Enumerate Supported Target Tools
+
+Read the **`Supported Tools and Features`** matrix in `README.md`. This matrix
+is the authoritative source of what rulesync supports today. Extract, for each
+in-scope tool:
+
+- The display name and the `--targets` identifier.
+- The currently supported feature columns (`rules`, `ignore`, `mcp`,
+  `commands`, `subagents`, `skills`, `hooks`, `permissions`) and their scope
+  markers, using the legend:
+  - ✅ project mode, 🌏 global mode, 🎮 simulated (project only),
+    🔧 MCP tool config.
+
+Do not hardcode the tool list from memory — re-read the matrix each run so the
+command stays in sync with the README.
+
+## Step 2: Launch One Research Subagent per Target Tool
+
+For each in-scope tool, delegate the investigation to a subagent via the Agent
+tool. Run them in parallel, but cap concurrency to roughly **5 at a time** to
+avoid overload; launch the next wave as earlier ones finish.
+
+- `subagent_type`: `general-purpose`
+- Role framing: "You are researching upstream updates for a single coding-agent
+  tool on behalf of rulesync."
+- Inputs to pass:
+  - The tool display name and `--targets` id.
+  - The tool's matrix row (the features rulesync currently supports and their
+    scope markers).
+- Instructions to include in the subagent prompt:
+  - Start from the `rulesync-feature-research` skill. If
+    `references/<tool>.md` exists under that skill, use it as the map of the
+    tool's official documentation and feature surfaces.
+  - Research the tool's **recent releases**. Prefer primary sources: official
+    release notes, changelogs, and GitHub releases. Use `WebSearch` and
+    `WebFetch`, and confirm candidate URLs against the primary source. Capture
+    exact version numbers, dates, and URLs.
+  - For each rulesync feature dimension (`rules`, `ignore`, `mcp`, `commands`,
+    `subagents`, `skills`, `hooks`, `permissions`), check whether the upstream
+    tool has **introduced or changed** a capability that rulesync has **not yet
+    followed** — e.g., new config keys, new file locations or naming, a new
+    project/global scope, new hook events, new MCP transports, metadata fields,
+    format changes, or deprecated surfaces that rulesync still emits.
+  - Ground every claim in rulesync's actual implementation. Inspect the
+    relevant `src/**` adapters and processor gates (prefer the Serena MCP
+    symbol tools over reading whole files), and validate the generated output
+    with a dry-run:
+
+    ```bash
+    pnpm run dev generate --targets <id> --features "*" --dry-run
+    pnpm run dev generate --targets <id> --features "*" --global --dry-run
+    ```
+
+  - Return a structured report. For each gap include: the feature, the upstream
+    capability with its source URL and version/date, rulesync's current
+    behavior, and a concrete proposed follow-up. If there are no material gaps,
+    return exactly `No gaps`.
+  - Report only **material capability gaps** — do not list tests, fixtures, or
+    refactor chores unless they are required to explain a gap.
+
+## Step 3: Consolidate Findings per Tool
+
+Collect each subagent's report. Group the gaps by tool. Tools that returned
+`No gaps` are skipped in the issue-creation step but still appear in the final
+report.
+
+## Step 4: File One GitHub Issue per Tool with Gaps
+
+Fetch the label vocabulary once up front so it is ready for issue creation:
+
+```bash
+gh label list --limit 100
+```
+
+Then, for **each** tool that has gaps, run the duplicate check below before
+deciding whether to open a new issue.
+
+### Step 4-1: Check for an Existing Issue (mandatory)
+
+Never open an issue without first checking for a duplicate. Search both open and
+recently closed issues, and do not rely on the title alone — a follow-up issue
+for the same tool may use different wording.
+
+```bash
+gh issue list --state all --search "<tool name>" --json number,title,url,state,labels
+gh issue list --state all --search "<--targets id>" --json number,title,url,state,labels
+```
+
+Treat an issue as a duplicate when it tracks the same tool's upstream follow-up,
+even if it only partially overlaps with the newly found gaps. When a candidate
+looks related, read it before deciding:
+
+```bash
+gh issue view <issue_number>
+gh issue view <issue_number> --comments
+```
+
+Branch on the result:
+
+- **A matching issue exists** → go to Step 4-2 (comment, do not open a new
+  issue).
+- **No matching issue exists** → go to Step 4-3 (create a new issue).
+
+### Step 4-2: Supplement the Existing Issue with a Comment
+
+When a duplicate exists, **do not file a new issue**. Instead, leave a comment on
+the existing issue that supplements it with the newly discovered information.
+
+- First read the issue body and its existing comments (Step 4-1) so you only add
+  what is **not already covered** — newly found releases, additional gaps, or
+  changed/closed gaps. Do not restate information that is already there.
+- If the current research surfaced nothing new beyond what the issue already
+  records, skip the comment and just note it in the final report.
+- Write the comment in English, with the same evidence discipline as a new issue
+  (primary-source links and version/date for every claim).
+
+Comment structure:
+
+```markdown
+## Upstream update (re-check on <YYYY-MM-DD>)
+
+### Newly found releases / changes
+
+The releases or changes not yet reflected in this issue, each with an inline
+link to the primary source and the version/date.
+
+### Additional or changed gaps
+
+Gaps not already listed here, or existing gaps that upstream has since
+resolved/deprecated. Use the README support labels (`project`, `global`,
+`simulated`, `unsupported`) when describing rulesync's side.
+
+### References
+
+Full clickable URLs for the new sources, with a short note on why each is cited.
+```
+
+```bash
+gh issue comment <issue_number> --body "<comment>"
+```
+
+### Step 4-3: Create a New Issue
+
+When no matching issue exists, create one issue for the tool. **All issue
+content (title, body, labels) must be written in English**, regardless of the
+conversation language.
+
+- Title: `Follow up <Tool> upstream updates: <short summary>`
+- Body structure:
+
+  ```markdown
+  ## Summary
+
+  One or two sentences describing the upstream updates rulesync should follow.
+
+  ## Recent Releases
+
+  The relevant recent releases / changes, each with an inline link to the
+  primary source and the version/date.
+
+  ## Gaps
+
+  Per feature, what the upstream tool now supports vs. rulesync's current
+  behavior, with source links. Use the README support labels (`project`,
+  `global`, `simulated`, `unsupported`) when describing rulesync's side.
+
+  ## Proposed Follow-up
+
+  Concrete changes rulesync should make (adapters, scope, frontmatter,
+  generated output). Keep it actionable.
+
+  ## References
+
+  Bulleted list of every primary source consulted, with full clickable URLs and
+  a short note on why each is cited.
+  ```
+
+- Labels: pick a small, precise set from the fetched vocabulary (do not invent
+  labels). Typically `enhancement` plus `considering`; add `codex` for the
+  Codex CLI, `security` only when relevant. Do not add `maintainer-scrap`.
+
+```bash
+gh issue create --title "<title>" --body "<body>" --label "<label1>,<label2>"
+```
+
+## Step 5: Report
+
+Output a compact summary, one line per in-scope tool:
+
+- `Filed`: `<Tool>` → `<issue URL>` (short gap summary)
+- `Commented (duplicate)`: `<Tool>` → `<existing issue URL>` (what the comment added)
+- `Skipped (already covered)`: `<Tool>` → `<existing issue URL>` (duplicate with nothing new to add)
+- `No gaps`: `<Tool>`
+
+Then list any tools whose research was inconclusive (e.g., releases could not be
+confirmed from primary sources) so the user can follow up manually.

.rulesync/commands/understand-scrap-issues.md

@@ -0,0 +1,43 @@
+---
+targets:
+  - "*"
+description: >-
+  Fetch the most recent maintainer-scrap issues (up to 3) and understand their
+  content
+---
+
+Fetch the newest scrap issues (GitHub issues labeled `maintainer-scrap`) and understand what each one is about, so you can catch up on recently jotted-down notes before acting on them.
+
+## Step 1: Fetch the Latest Scrap Issues
+
+List the most recent open issues that carry the `maintainer-scrap` label. `gh issue list` returns issues in creation order (newest first), so limiting to 3 yields the 3 newest:
+
+```bash
+gh issue list --label maintainer-scrap --state open --limit 3 --json number,title,url,createdAt
+```
+
+If the result is empty, report that there are no open scrap issues and stop.
+
+## Step 2: Gather Each Issue's Content
+
+For each scrap issue returned, read both the body and the discussion. Run these in parallel across the issues where practical:
+
+```bash
+gh issue view <issue_number>
+gh issue view <issue_number> --comments
+```
+
+If an issue references related pull requests, commits, or files that are needed to understand it, gather that context as well.
+
+## Step 3: Understand and Summarize
+
+For each scrap issue, explain the following based on its content:
+
+1. **Topic:** A one-line summary of what the scrap note is about.
+2. **Background:** The context, motivation, or problem the note captures and why it matters.
+3. **Details / Findings:** The specific observations, problems, or content recorded in the note.
+4. **Proposed Solution / Next Steps:** Any solution or actionable next step mentioned. If none is recorded, state explicitly that it is still undecided.
+
+Keep each summary concise and focused. Present the issues in the order returned (newest first), with the issue number, title, and URL as a heading for each.
+
+Use the language of the current conversation (follow the user's language).