@docyrus/docyrus 0.0.48 → 0.0.51

package/resources/pi-agent/skills/diffity-diff/SKILL.md

@@ -1,28 +0,0 @@
----
-name: diffity-diff
-description: Open the diffity diff viewer in the browser to see your changes
-user-invocable: true
----
-
-# Diffity Diff Skill
-
-You are opening the diffity diff viewer so the user can see their changes in the browser.
-
-## Arguments
-
-- `ref` (optional): Git ref to diff (e.g. `main..feature`, `HEAD~3`) or a GitHub PR URL (e.g. `https://github.com/owner/repo/pull/123`). Defaults to working tree changes.
-
-## Instructions
-
-1. Check that `diffity` is available: run `which diffity`. If not found, install it with `npm install -g diffity`.
-2. Run `diffity <ref>` (or just `diffity` if no ref) using the Bash tool with `run_in_background: true`:
-   - The CLI handles everything: if an instance is already running for this repo it reuses it and opens the browser, otherwise it starts a new server and opens the browser.
-   - Do NOT use `&` or `--quiet` — let the Bash tool handle backgrounding.
-3. Wait 2 seconds, then run `diffity list --json` to get the port.
-4. Tell the user diffity is running. Print the URL and keep it short — don't show session IDs, hashes, or other internals. Example:
-
-   > Diffity is running at http://localhost:5391
-   >
-   > When you're ready:
-   > - Leave comments on the diff in your browser, then run **/diffity-resolve** to fix them
-   > - Or run **/diffity-review** to get an AI code review

package/resources/pi-agent/skills/diffity-resolve/SKILL.md

@@ -1,69 +0,0 @@
----
-name: diffity-resolve
-description: Read open review comments and resolve them by making code fixes
-user-invocable: true
----
-
-# Diffity Resolve Skill
-
-You are reading open review comments and resolving them by making the requested code changes.
-
-## Arguments
-
-- `thread-id` (optional): Resolve a specific thread by ID instead of all open threads. Example: `/diffity-resolve abc123`
-
-## CLI Reference
-
-```
-diffity agent diff
-diffity agent list [--status open|resolved|dismissed] [--json]
-diffity agent comment --file <path> --line <n> [--end-line <n>] [--side new|old] --body "<text>"
-diffity agent general-comment --body "<text>"
-diffity agent resolve <id> [--summary "<text>"]
-diffity agent dismiss <id> [--reason "<text>"]
-diffity agent reply <id> --body "<text>"
-```
-
-- `--file`, `--line`, `--body` are required for `comment`
-- `--end-line` defaults to `--line` (single-line comment)
-- `--side` defaults to `new`
-- `general-comment` creates a diff-level comment not tied to any file or line
-- `<id>` accepts full UUID or 8-char prefix
-
-## Prerequisites
-
-1. Check that `diffity` is available: run `which diffity`. If not found, install it with `npm install -g diffity`.
-2. Check that a review session exists: run `diffity agent list`. If this fails with "No active review session", tell the user to start diffity first (e.g. `diffity` or **/diffity-diff**).
-
-## Instructions
-
-1. List open comment threads with full details:
-   ```
-   diffity agent list --status open --json
-   ```
-   If a `thread-id` argument was provided, filter to just that thread. The JSON output includes the full comment body, file path, line numbers, and side for each thread.
-2. If there are no open threads, tell the user there's nothing to resolve.
-3. For each open thread, check the `comments` array and the `author.type` field (`"user"` or `"agent"`) on each comment:
-   a. **Skip** general comments (filePath `__general__`) — these are summaries, not actionable code changes.
-   b. **Skip** threads where the last comment is an agent reply that asks the user a question (e.g. "Could you clarify...?") and the user hasn't responded yet — the agent is waiting for user input. Still process threads where the agent left the original comment (code suggestion, review feedback, etc.) — those are actionable.
-   c. **`[nit]` comments** — these are minor suggestions but still actionable. Resolve them like any other comment.
-   d. **`[question]` comments** (from the user) — read the question, examine the relevant code, and resolve the thread with your answer as the summary:
-      ```
-      diffity agent resolve <thread-id> --summary "Your answer here"
-      ```
-   e. Comments phrased as questions without an explicit `[question]` tag (e.g. "should we add X?" or "can we rename this?") are suggestions — treat them as actionable requests and make the change.
-   f. Read the comment body from the JSON output and understand what change is requested. Interpret the intent:
-      - If the comment suggests a code change, make the change.
-      - If the comment suggests adding documentation, add or update the relevant docs.
-      - If the comment asks a question that implies an action (e.g. "should we add X?"), treat it as a request to do that action.
-      - If the comment is genuinely unclear and you cannot determine what action to take, reply asking for clarification instead of silently skipping:
-        ```
-        diffity agent reply <thread-id> --body "Could you clarify what change you'd like here?"
-        ```
-   g. Read the relevant source file to understand the full context around the commented lines, then make the requested change using the Edit tool.
-   h. After making the change, resolve the thread with a summary:
-      ```
-      diffity agent resolve <thread-id> --summary "Fixed: <brief description of what was changed>"
-      ```
-4. After resolving all applicable threads, run `diffity agent list` to confirm status.
-5. Tell the user to check the browser — resolved status will appear within 2 seconds via polling.

package/resources/pi-agent/skills/diffity-review/SKILL.md

@@ -1,176 +0,0 @@
----
-name: diffity-review
-description: Review current diff and leave comments using diffity agent commands
-user-invocable: true
----
-
-# Diffity Review Skill
-
-You are reviewing a diff and leaving inline comments using the `diffity agent` CLI.
-
-## Arguments
-
-- `ref` (optional): Git ref to review (e.g. `main..feature`, `HEAD~3`). Defaults to working tree changes. When both `ref` and `focus` are provided, use both (e.g. `/diffity-review main..feature security`).
-- `focus` (optional): Focus the review on a specific area. One of: `security`, `performance`, `naming`, `errors`, `types`, `logic`. If omitted, review everything.
-
-## CLI Reference
-
-```
-diffity agent diff
-diffity agent list [--status open|resolved|dismissed] [--json]
-diffity agent comment --file <path> --line <n> [--end-line <n>] [--side new|old] --body "<text>"
-diffity agent general-comment --body "<text>"
-diffity agent resolve <id> [--summary "<text>"]
-diffity agent dismiss <id> [--reason "<text>"]
-diffity agent reply <id> --body "<text>"
-```
-
-- `--file`, `--line`, `--body` are required for `comment`
-- `--end-line` defaults to `--line` (single-line comment)
-- `--side` defaults to `new`
-- `general-comment` creates a diff-level comment not tied to any file or line
-- `<id>` accepts full UUID or 8-char prefix
-
-## Prerequisites
-
-1. Check that `diffity` is available: run `which diffity`. If not found, install it with `npm install -g diffity`.
-
-## Instructions
-
-### Step 1: Ensure diffity is running for the correct ref (without opening browser)
-
-The review needs a running session whose ref matches the requested ref. A ref mismatch causes "file not in current diff" errors when adding comments.
-
-1. Run `diffity list --json` to get all running instances. Parse the JSON output and find the entry whose `repoRoot` matches the current repo.
-2. If a matching entry exists, compare its `ref` field against the requested ref:
-   - The registry stores `"work"` for working-tree sessions and the user-provided ref string (e.g. `"main"`, `"HEAD~3"`) for named refs.
-   - If refs **match** → reuse the session, note the port, and continue to Step 2.
-   - If refs **don't match** → restart: run `diffity <ref> --no-open --new` (or `diffity --no-open --new` if no ref). The `--new` flag kills the old session and starts a fresh one. Use Bash tool with `run_in_background: true`. Wait 2 seconds, then verify with `diffity list --json` and note the port.
-   - If **no ref was requested** and the running session's ref is not `"work"` → restart with `diffity --no-open --new` (the running session is for a named ref, but we need working-tree).
-3. If **no session is running** for this repo, start one in the background:
-   - Command: `diffity <ref> --no-open` (or `diffity --no-open` if no ref)
-   - Use Bash tool with `run_in_background: true`
-   - Wait 2 seconds, then verify with `diffity list --json` and note the port.
-
-### Step 2: Review the diff
-
-1. **Get the unified diff** directly from diffity — this handles merge-base resolution, untracked files, and all ref types automatically:
-   ```
-   diffity agent diff
-   ```
-   This outputs the full unified diff for the current session. Line numbers are in the `@@` hunk headers.
-2. Find and read all relevant CLAUDE.md files — the root CLAUDE.md and any CLAUDE.md files in directories containing modified files. These define project-specific rules that the diff must follow.
-
-#### Understand the change before reviewing it
-
-3. **Summarize the change first.** Before looking for problems, build a mental model of the diff:
-   - What is this change trying to accomplish? (new feature, bug fix, refactor, config change)
-   - Which files are structural changes vs. the core logic change?
-   - What is the author's intent? Read commit messages (`git log --oneline <args>`) and any linked issues or PR descriptions for context.
-   - What are the key decisions the author made, and what constraints were they working within?
-
-   Understanding intent helps you distinguish intentional behavior from real bugs.
-
-4. For each changed file, read the **entire file** (not just the diff hunks) to understand the full context.
-5. **Cross-reference callers and dependents.** For any changed function signature, renamed export, modified return type, or altered behavior: grep for usages across the codebase. A function that looks correct in isolation can break every caller. Check:
-   - Who calls this function? Will they handle the new return value / error / null case?
-   - Who imports this module? Will the changed export name resolve?
-   - Does this type change propagate correctly to consumers?
-6. Analyze the code changes using the techniques below. If a `focus` argument was provided, concentrate on that area. Otherwise, apply all analysis passes and the signal threshold.
-
-#### How to analyze
-
-The diff tells you *what* changed; the surrounding code tells you whether the change is *correct*. Apply these analysis passes:
-
-**Data flow analysis** — Trace values through the changed code. Where does each variable come from? Where does it go? Check:
-- Can a value be null/undefined where the changed code assumes it isn't?
-- Does the changed code handle all branches of an upstream conditional?
-- If a function's return type changed, do all callers handle the new shape?
-- Are there narrowing checks (e.g. `if (x)`) that the diff accidentally moved outside of?
-
-**State and lifecycle analysis** — For stateful code (React state, database transactions, streams, event listeners):
-- Does the change create a state that can't be reached or can't be exited?
-- Are resources (listeners, subscriptions, file handles) still cleaned up on all paths?
-- Can concurrent access corrupt shared state?
-- Does the ordering of operations still satisfy invariants (e.g. init before use)?
-
-**Contract analysis** — Check the changed code against the contracts it must satisfy:
-- Does the function still satisfy what its callers expect? (Read the callers, don't guess.)
-- If it implements an interface or overrides a base method, does it still conform?
-- Are pre-conditions and post-conditions preserved?
-- For API endpoints: does the response shape match what clients send/expect?
-
-**Boundary analysis** — For code at system boundaries (user input, network, file I/O, IPC):
-- Is user-controlled input validated before use?
-- Can malformed external data crash the process or corrupt state?
-- Are there injection vectors (SQL, shell, XSS, path traversal)?
-
-**Edge case analysis** — Only for cases that *will* happen in practice, not theoretical ones:
-- Empty arrays/strings, zero, negative numbers — does the code handle them?
-- Off-by-one in loops, slices, or index arithmetic
-- Integer overflow, division by zero where the divisor comes from input
-
-#### What to flag
-
-Flag real problems that would affect correctness, security, or reliability:
-- Code that will fail to compile, parse, or run (syntax errors, type errors, missing imports, unresolved references)
-- Logic errors that will produce wrong results (clear bugs, off-by-one errors, broken conditions)
-- Security vulnerabilities in changed code (injection, XSS, auth bypass, data exposure)
-- Race conditions or data loss risks you can demonstrate with a concrete scenario
-- CLAUDE.md violations where you can quote the exact rule being broken
-- Broken contracts — a changed function that no longer satisfies what its callers expect
-
-Skip style concerns, linter-catchable issues, and pre-existing problems in unchanged code. Focus on the diff, not the whole file.
-
-#### Validate before commenting
-
-For each finding, verify it's real before posting:
-- Re-read the surrounding code — many apparent bugs disappear in full context
-- For "missing import" or "undefined variable" claims, grep to confirm
-- For broken callers, read the actual call sites
-- For CLAUDE.md violations, confirm the rule is scoped to this file
-
-If a repeated pattern appears across files, comment on the first occurrence and mention the pattern in the general summary instead of duplicating comments.
-
-### Step 3: Leave comments
-
-1. Categorize each finding with a severity prefix in the comment body:
-   - `[must-fix]` — Bugs, security issues, data loss risks. Code that will break or produce wrong results.
-   - `[suggestion]` — Concrete improvements with a clear reason. Not style preferences — real improvements.
-   - `[question]` — Something unclear that needs clarification from the author.
-
-2. For each finding, leave an inline comment using:
-   ```
-   diffity agent comment --file <path> --line <n> [--end-line <n>] [--side new] --body "<comment>"
-   ```
-   - Use `--side new` (default) for comments on added/modified code
-   - Use `--side old` for comments on removed code
-   - Use `--end-line` when the issue spans multiple lines
-   - **Lead with the problem**, not background. Be specific and actionable.
-   - For small, self-contained fixes, include a code suggestion showing the fix
-   - For larger fixes (structural changes, multi-location), describe the issue and suggested approach without a full code block
-   - If flagging a CLAUDE.md violation, quote the exact rule being broken
-3. After leaving all inline comments, decide whether a general comment is needed:
-   - **No findings → leave a general comment:** "No issues found. Checked for bugs and CLAUDE.md compliance."
-   - **1-2 findings → skip the general comment** unless there's a cross-cutting concern the inline comments don't cover.
-   - **3+ findings → leave a general comment** summarizing the themes.
-   - **Do not use severity prefixes in the general comment** — prefixes are only for inline findings.
-   - Lead with the verdict, be direct and concise — no compliments, no filler, no narrating what the code does.
-   ```
-   diffity agent general-comment --body "<overall review summary>"
-   ```
-
-### Step 4: Open the browser
-
-1. Open the browser now that comments are ready:
-   ```
-   diffity open <ref>
-   ```
-   Pass the ref argument if one was provided (e.g. `diffity open HEAD~3`). Omit it to open the default view.
-2. Tell the user the review is ready and they can check the browser. Example:
-
-   > Review complete — check your browser.
-   >
-   > Found: 2 must-fix, 1 suggestion
-   >
-   > When you're ready, run **/diffity-resolve** to fix them.