refactor(skill): upgrade open-code-review skill to modular structure with v1.10.1 features

skills/open-code-review/SKILL.md

@@ -1,224 +1,197 @@
 ---
 name: open-code-review
 description: >
-  Performs AI-powered code review on Git changes using the `ocr` CLI from
+  Performs AI-powered code review and repository scanning using the `ocr` CLI from
   alibaba/open-code-review. Use when the user asks to review code, review
-  a pull request, review staged/unstaged changes, review a commit, or
-  compare branches for code quality issues. Produces line-level review
-  comments and can automatically apply fixes when requested. With appropriate
-  review rules, can detect various types of issues including bugs, security
-  vulnerabilities, performance problems, and code quality concerns.
+  a PR, review staged/unstaged changes, review a commit, compare branches, scan
+  repository files, or resume an interrupted review. Supports diff-based review,
+  full-file scanning, and delegate mode. Produces line-level review comments with
+  severity/category classifications and can automatically apply fixes.
 license: Apache-2.0
-compatibility: >
-  Requires the `ocr` CLI installed (via `npm install -g
-  @alibaba-group/open-code-review` or GitHub release binary). Requires a
-  configured LLM (Anthropic or OpenAI-compatible) before first run.
 metadata:
   author: alibaba
   homepage: https://github.com/alibaba/open-code-review
-  version: "1.0.0"
+  version: "1.10.1"
 ---
 
 # Open Code Review
 
-A skill for invoking [open-code-review](https://github.com/alibaba/open-code-review) (`ocr`) — an open-source AI code review CLI that reads Git diffs and generates structured, line-level review comments.
+A skill for invoking [open-code-review](https://github.com/alibaba/open-code-review) (`ocr`) — an open-source AI code review CLI that reads Git diffs or scans source files and delegates to tool-calling LLM agents to generate structured, line-level review comments.
 
-## Workflow
-
-### Step 1: Gather Business Context
+## Progressive Reference Navigation
 
-Analyze the review target (commits, branch, or changes) to extract concise business context. Pass this context via `--background` to improve review quality.
+Read specific references based on task needs; do not load all files at once:
 
-### Step 2: Run Code Review
+| Scenario | Reference File |
+|----------|----------------|
+| Complete flag reference & defaults | [references/flags.md](./references/flags.md) |
+| Installation / LLM config / Per-run overrides | [references/llm-config.md](./references/llm-config.md) |
+| Custom review rules format & debugging | [references/rules.md](./references/rules.md) |
+| MCP Server integration & config | [references/mcp.md](./references/mcp.md) |
+| Troubleshooting / Performance tuning / Session management | [references/troubleshooting.md](./references/troubleshooting.md) |
 
-Run the OCR command with appropriate flags. **Always pass business context via `--background`** when available:
+## Mode Selection
 
-```bash
-ocr review --audience agent --background "business context here" [user-args]
+```
+User Request → Has git diff context?
+  ├─ YES → Review Mode
+  │         ├─ Single commit → --commit <hash>
+  │         ├─ Branch comparison → --from <ref> --to <ref>
+  │         └─ Workspace (staged+unstaged+untracked) → No extra flag
+  └─ NO → Scan Mode
+           ├─ Entire repository → No --path
+           └─ Specific path/directory → --path <paths>
+
+LLM not configured & user does not want to configure?
+  → Switch to `open-code-review-delegate` skill (host agent conducts review; OCR handles file selection & rule resolution)
 ```
 
-**Argument handling:**
-
-- **Background context** (RECOMMENDED): use `--background "context"` or `-b "context"` to provide business context for better review quality
-- **Default** (no user arguments): reviews staged, unstaged, and untracked changes (workspace mode)
-- **Specific commit**: use `--commit` or `-c` to review a single commit against its parent
-- **Branch comparison**: use `--from <ref>` and `--to <ref>` to review diff between two refs
-- **Timeout**: default timeout is 10 minutes per file; adjust with `--timeout <minutes>`
-- **Concurrency**: default concurrency is 8 file workers; reduce with `--concurrency <n>` if rate limits are hit
-- **Preview mode**: use `--preview` or `-p` to preview which files will be reviewed without running the LLM
-- **Installation**: if `ocr` command is not found, install it by running `npm i -g @alibaba-group/open-code-review`
-
-**Common invocation patterns:**
-
-| User says | Command to run |
-|-----------|---------------|
-| "review my changes" / "review the working copy" | `ocr review --audience agent -b "context"` |
-| "review this PR" / "review feature branch" | `ocr review --audience agent -b "context" --from main --to <branch>` |
-| "review commit abc123" | `ocr review --audience agent -b "context" --commit abc123` |
-| "what would be reviewed?" (dry-run) | `ocr review --preview` |
-
-**Output mode:**
-
-- Always use `--audience agent` to suppress progress UI and emit only the final summary
-- **Prevent output truncation**: For large reviews or restricted tool environments, redirect output to a temporary file (`ocr review --audience agent ... > /tmp/ocr_out.txt 2>&1`) and inspect it in full via a file reading tool instead of piping through `tail` or `head`, which drops earlier review comments.
-
-**On failure:** If `ocr review` exits non-zero (e.g. an LLM connection error), do not retry blindly — consult the Troubleshooting section below for the matching fix before re-running.
-
-### Step 3: Report
-
-OCR output includes structured `severity` (critical / high / medium / low) and `category` (bug / security / performance / maintainability / test / style / documentation / other) on each comment. Present results grouped by severity, discarding `low` severity items that are likely false positives or nitpicks.
-
-### Step 4: Fix
-
-Before applying fixes, check whether the user requested automatic fixes:
-
-- If the user explicitly requested "review and fix" or similar, proceed with automatic fixes
-- If the user only requested "review" without fix intent, ask for permission before applying any changes
-
-When fixing issues and suggestions:
-
-- Focus on critical, high, and medium severity items
-- Apply fixes directly to the code when safe and well-defined
-- For complex fixes requiring manual intervention, clearly describe what needs to be done
-- Always verify fixes with the user before committing
-
-## Output Format
-
-Each comment in OCR's output contains:
-
-- `path`: File path
-- `content`: Review comment text
-- `start_line` / `end_line`: Line range (both 0 means positioning failed)
-- `category`: Issue category (bug, security, performance, maintainability, test, style, documentation, other)
-- `severity`: Issue severity (critical, high, medium, low)
-- `suggestion_code`: Optional fix suggestion
-- `existing_code`: Optional original code snippet
-- `thinking`: Optional LLM reasoning process
-
-Present results grouped by severity using this template:
-
-```markdown
-## Code Review Results
-
-**Files reviewed**: N
-**Issues found**: X critical, Y high, Z medium
-
-### Critical
-
-- **`path/to/file.java:42`** [bug] — Brief description
-  > Recommendation: How to fix
-
-### High
+## Workflow
 
-- **`path/to/file.java:26`** [bug] — Brief description
-  > Recommendation: How to fix
+### Step 1: Gather Business Context
 
-### Medium
+Analyze the review target and extract concise business context to improve review quality.
 
-- **`path/to/file.ts:88`** [performance] — Brief description
-  > Recommendation: How to fix (if applicable)
-```
+- Short context (< 2000 chars): `--background "context"` / `-b "context"` (inline raw string)
+- Long context (PRD/docs): write to a temporary `.md` file, `--background-file <path>` / `-B <path>` (max 1 MB; stripped & wrapped in `<ocr_user_background>` tags; soft limit 2000 chars, hard limit 8000)
 
-If no critical, high, or medium severity issues remain after filtering, state: "Review complete — no critical, high, or medium issues found in N files."
+### Step 2: Execute Review or Scan
 
-**Handling mispositioned comments:**
+**Always use `--audience agent`** (suppresses progress UI). Prefer `--format json`.
 
-When `start_line` and `end_line` are both `0`, the comment failed to locate the exact position in the file. In such cases:
+> 💡 **Prevent output truncation**: For large reviews or scans, prefer `--output <path>` / `-o <path>` (e.g. `ocr scan --audience agent --format json -o scratch/ocr_result.json -b "ctx"`). OCR writes natively to a UTF-8 file (created lazily on first write) and prints the file path on stderr. Then inspect it directly via `view_file`.
+> - If truncation already happened on stdout: **no need to re-run `ocr`** — extract comments on demand via `ocr session comments <session-id> --severity high,critical --json`.
 
-1. Read the comment content to understand the issue
-2. Examine the target file mentioned in the comment
-3. Identify the relevant code section based on the comment's context
-4. Apply the fix or suggestion to the correct location
+#### Review Mode (Diff-based)
 
-## Custom Review Rules
+| User Intent | Command |
+|-------------|---------|
+| "Review my changes" | `ocr review --audience agent --format json -b "ctx"` |
+| "Review feature PR" | `ocr review --audience agent --format json -b "ctx" --from main --to feature` |
+| "Review commit abc123" | `ocr review --audience agent --format json -b "ctx" --commit abc123` |
+| "High effort deep review" | `ocr review --audience agent --format json --effort high -b "ctx"` |
+| "Write results to file" | `ocr review --audience agent --format json -o result.json -b "ctx"` |
+| "Which files will be reviewed?" | `ocr review --preview --format json` |
+| "Resume interrupted review" | `ocr review --audience agent --format json --from main --to feature --resume <session-id>` |
 
-If the user wants project-specific rules, OCR resolves them in this priority order:
+#### Scan Mode (Full-file, No Diff Required)
 
-1. `--rule <path>` flag (highest)
-2. `<repo>/.opencodereview/rule.json`
-3. `~/.opencodereview/rule.json`
-4. Built-in system defaults (lowest)
+| User Intent | Command |
+|-------------|---------|
+| "Scan the whole repo" | `ocr scan --audience agent --format json -b "ctx"` |
+| "Scan src/auth/ for security" | `ocr scan --audience agent --format json --path src/auth -b "security audit"` |
+| "Fast scan without summary" | `ocr scan --audience agent --format json --no-summary --no-dedup` |
+| "Write results to file" | `ocr scan --audience agent --format json -o result.json -b "ctx"` |
+| "Resume interrupted scan" | `ocr scan --audience agent --format json --resume <session-id>` |
+| "Which files will be scanned?" | `ocr scan --preview --format json` |
 
-By default, the first matching user rule replaces the built-in system rule. Set `merge_system_rule: true` on a rule entry when the matched system rule and user rule should both be included.
+### Step 3: Classify and Parse
 
-Rule file format:
+JSON output core structure:
 
 ```json
 {
-  "rules": [
-    {
-      "path": "**/*.java",
-      "rule": "All new methods must validate required parameters for null",
-      "merge_system_rule": true
-    },
-    {
-      "path": "**/*mapper*.xml",
-      "rule": "Check SQL for injection risks and missing closing tags"
-    }
-  ]
+  "status": "review: complete | partial | failed | skipped; scan: success | completed_with_warnings | completed_with_errors",
+  "session_id": "...",
+  "llm": { "provider": "anthropic", "model": "claude-opus-5" },
+  "trace_id": "...",
+  "summary": {
+    "files_reviewed": 12,
+    "comments": 5,
+    "total_tokens": 45000,
+    "input_tokens": 40000,
+    "output_tokens": 5000,
+    "cache_read_tokens": 12000,
+    "cache_write_tokens": 3000,
+    "elapsed": "32s",
+    "budget_exceeded": false
+  },
+  "tool_calls": { "total": 58, "by_tool": { "file_read": 40, "code_search": 18 } },
+  "comments": [{
+    "path": "src/auth/login.ts",
+    "content": "Review comment content",
+    "start_line": 42,
+    "end_line": 45,
+    "category": "security",
+    "severity": "high",
+    "suggestion_code": "Optional fix suggestion",
+    "existing_code": "Original code",
+    "thinking": "Optional LLM reasoning"
+  }],
+  "warnings": [{ "file": "...", "message": "...", "type": "timeout" }],
+  "project_summary": "Optional scan summary",
+  "manifest": { "terminal_state": "complete", "coverage": { "selected": [{ "item_id": "...", "path": "..." }], "completed": [...], "reused": [], "failed": [], "waived": [] } }
 }
 ```
 
-To preview which rule applies to a file before reviewing:
-
-```bash
-ocr rules check src/main/java/com/example/Foo.java
-```
+> **Structure notes**: `manifest` is emitted in review mode only (`manifest.coverage` fields are `CoverageItem[]` arrays; read `summary.files_reviewed` for total files reviewed); `tool_calls` is always emitted; `llm`, `trace_id`, `project_summary`, `resume`, `message` are optional; run-level failures emit a `status:"failed"` JSON object to **stderr**.
 
-## Gotchas
+Classify by severity:
 
-- **LLM must be configured first** — `ocr review` will fail loudly if no LLM is reachable. See the Troubleshooting section below if this happens.
-- **Working directory matters** — `ocr review` operates on the Git repo at the current directory. Use `--repo /path/to/repo` to run from elsewhere.
-- **Untracked files are reviewed in workspace mode** — running bare `ocr review` includes staged, unstaged, *and* untracked changes. Stage selectively if you want narrower scope.
-- **Large diffs may hit token limits** — files with very large diffs may be truncated. The default `MAX_TOKENS` is 58888 per request.
-- **Plan phase triggers at 50 lines** — diffs exceeding 50 changed lines run an extra risk-analysis phase before main review. This adds latency but improves quality.
-- **Don't pass `--audience human`** — it streams progress UI that pollutes output. Always use `--audience agent`.
-- **Comment language follows config** — set `language` config to `English` or `Chinese` (default: Chinese) to control review comment language.
-- **Avoid output truncation** — Large review runs produce verbose output. Never pipe command output to `tail` or `head` as it drops review comments from earlier sections. Redirect output to a file and read it in full.
+- **critical / high** → Must report. Bugs, security risks, data loss risks, clear defects.
+- **medium** → Report with context. Performance issues, error-handling flaws, maintainability concerns.
+- **low** → Silently discard unless user requests full verbosity.
 
-## Validation
+Categories: `bug`, `security`, `performance`, `maintainability`, `test`, `style`, `documentation`, `other`.
 
-After the review completes, verify success by checking:
+### Step 4: Report
 
-1. The command exited with code 0
-2. Comments were generated (or "No comments generated" message appears)
-3. Warnings (if any) are displayed in stderr
+```markdown
+## Code Review Results
 
-If errors occurred, check the stderr warnings for details about which files failed and why.
+**Files Reviewed**: N | **Issues Found**: X high / Y medium | **Tokens Used**: Z
 
-## Troubleshooting
+### High / Critical
 
-**`ocr: command not found`**
+- **`path/to/file.ts:42-45`** [security] — Brief description
+  > Fix recommendation
 
-Install the CLI:
+### Medium
 
-```bash
-npm install -g @alibaba-group/open-code-review
+- **`path/to/file.go:88`** [performance] — Brief description
+  > Recommendation
 ```
 
-**`ocr review` fails with LLM connection error**
+If no issues found: "Review complete — 0 issues found across N files."
 
-Prompt the user to configure an LLM provider.
+**Handling mispositioned comments** (`start_line` and `end_line` are 0): Read the comment content, inspect the target file, locate the target code section, and report/fix at the correct position.
 
-Interactive setup (recommended):
+### Step 5: Fix (Optional)
 
-```bash
-ocr config provider
-```
+- User asks "review and fix" → Fix critical/high items directly.
+- User asks "review" only → Ask for permission before modifying code.
+- Apply safe and well-defined fixes directly.
+- Verify fixes pass compilation/tests before marking complete.
 
-Manual setup (alternative):
+## Gotchas & Notes
 
-```bash
-ocr config set llm.url https://api.anthropic.com/v1/messages
-ocr config set llm.auth_token <api-key>
-ocr config set llm.model claude-opus-4-6
-ocr config set llm.use_anthropic true
-```
+- **Always use `--audience agent`** — `human` mode outputs progress UI that pollutes agent output.
+- **Per-run overrides** — Override provider, model, tokens, or review effort on single runs using `--provider <name>`, `--model <name>`, `--max-tokens <n>`, or `--effort <low|medium|high>`.
+- **Review Effort Levels** — `--effort` preset: `low` (1 main loop round), `medium` (default, 2 rounds), `high` (3 rounds). Higher effort yields higher recall with more tokens. Persist via `ocr config set effort <level>`.
+- **Working directory matters** — `ocr` operates on the git repo in cwd. Use `--repo /path` to override.
+- **Workspace mode includes untracked files** — Bare `ocr review` reviews staged + unstaged + untracked changes.
+- **Plan phase at 50+ lines** — Diffs exceeding 50 changed lines run a pre-review risk analysis plan phase.
+- **Background sanitization** — Applies to `--background-file` (`-B`) only: control chars stripped, wrapped in `<ocr_user_background>` tags, soft limit 2000 chars, hard limit 8000. Inline `--background` (`-b`) passes through raw without limits.
+- **Ref injection defense** — `--from`/`--to`/`--commit` values cannot start with `-`.
+- **Scan mode needs no git** — `ocr scan` runs on non-git directories.
+- **Resume conditions** — `ocr scan` fully supports `--resume`; `ocr review` supports `--resume` only in `--from/--to` or `--commit` modes (not workspace mode).
+- **`--preview` and `--resume` are mutually exclusive.**
+- **Language configuration** — Default: English. Switch via `ocr config set language 中文`.
+- **Default MAX_TOKENS** — Default prompt token ceiling is 200,000 in review mode and 58,888 in scan mode (configurable via `--max-tokens` or `max_tokens`).
+- **Prevent Tool Output Truncation** — For large reviews or scans, prefer `-o <path>` / `--output <path>` to write directly to a UTF-8 file and read with `view_file`. If output is truncated, extract comments via `ocr session comments <session-id> --severity high,critical --json` without re-running.
+- **Do not test connectivity pre-emptively** — Execute review/scan directly; troubleshoot only on actual LLM failure (see troubleshooting.md).
+
+## Verification
+
+After review completes:
 
-Verify connectivity with `ocr llm test`. Stop here and ask the user to provide credentials — never invent or hardcode API keys.
+1. Command exit code is 0
+2. JSON `status` field is `"complete"` (or `"partial"` with acceptable warnings)
+3. `comments` array structured as expected
+4. `summary.files_reviewed` matches target count
 
 ## References
 
-- Full docs: https://github.com/alibaba/open-code-review
-- NPM package: https://www.npmjs.com/package/@alibaba-group/open-code-review
-- Issue tracker: https://github.com/alibaba/open-code-review/issues
+- Homepage & Docs: https://github.com/alibaba/open-code-review
+- NPM Package: https://www.npmjs.com/package/@alibaba-group/open-code-review
+- Issue Tracker: https://github.com/alibaba/open-code-review/issues