Merge branch 'main' into unleashed-romano

2026-09-21 14:07:20 +08:00 · 2026-05-18 08:47:26 -04:00
parent cdbcdb1ef6 84a72b9e3f
commit 5cdb343385
17 changed files with 112 additions and 9 deletions
@@ -0,0 +1,90 @@
+# REVIEW.md
+
+Guidance for the automated reviewer (kilo-code-bot) on PRs in this repo.
+
+The goal of the review is to catch things CI **cannot** catch: bugs, design issues, and judgment calls about style and fork hygiene. Be helpful, not pedantic — frame everything as a suggestion the human can accept or reject.
+
+## Don't duplicate CI
+
+CI already runs and will report failures directly. Do **not** comment on:
+
+- Lint, formatting, or typecheck errors (root `lint`, `turbo typecheck`)
+- Test failures (CLI tests, vscode tests)
+- `knip` unused exports
+- `kilocode_change` marker rules — both directions:
+  - Missing markers on shared opencode files (`script/check-opencode-annotations.ts`)
+  - Markers present in kilo-only paths like `packages/kilo-vscode/`, `packages/kilo-ui/`, `packages/opencode/src/kilocode/` (`bun run check-kilocode-change`)
+- Workflow allowlist drift (`script/check-workflows.ts`)
+- Stale `packages/kilo-docs/source-links.md` (`script/extract-source-links.ts`)
+- Markdown table padding (`script/check-md-table-padding.ts`)
+- Visual regression snapshots (CI generates baselines on Linux)
+- SDK regeneration drift (`generate.yml`)
+- Generated artifact freshness (`check-kilo-generated-artifacts.yml`)
+- Docs link checks, nix evals, container builds
+
+If the only issue you'd raise is one of the above, just say `lgtm`.
+
+## What to focus on
+
+### 1. Bugs and correctness
+
+Read enough of the surrounding file to actually understand the change — diffs alone hide context. Look for:
+
+- Logic errors, off-by-one, wrong conditions, swapped arguments
+- Unhandled error paths, swallowed promises, missing `await`
+- Race conditions, especially around session/process lifecycle in the CLI and Agent Manager
+- Resource leaks (unclosed file handles, child processes, subscriptions)
+- Inputs that aren't validated where they cross trust boundaries (server routes, IPC, config loading)
+
+### 2. Style guide judgment calls
+
+The full guide is in `AGENTS.md`. Don't be a zealot — only flag actual violations, and recognize when the existing code already complies through a different mechanism.
+
+- **No `let`**: prefer `const` with ternary or IIFE (`packages/opencode/src/util/iife.ts`). But `let` is fine when it's genuinely the simplest option; don't demand IIFE rewrites for trivial cases.
+- **No `else`**: prefer early returns. Don't complain about `else` if the code already uses early returns elsewhere. You **may** flag excessive nesting regardless.
+- **No empty `catch`**: always flag — empty catches hide bugs.
+- **Avoid `try`/`catch` where possible**: if a try/catch is added, consider whether it's needed at all.
+- **Avoid `any`**: flag new `any` usage unless there's a clear reason.
+- **Single-word names**: prefer `cfg`, `pid`, `dir`, `opts`, `err` over `inputPID`, `connectTimeout`. Only flag newly introduced multi-word names where a clear single-word alternative exists.
+- **Avoid unnecessary destructuring**: prefer `obj.a` over `const { a } = obj` to preserve context.
+- **Bun APIs**: prefer `Bun.file()` etc. over node equivalents in CLI code.
+- **Type inference**: avoid explicit annotations unless needed for exports/clarity.
+
+When suggesting fixes, ensure the suggestion is valid TypeScript (matched braces, correct syntax). Prefer prose comments over `suggestion` blocks unless the fix is trivially mechanical.
+
+### 3. Fork merge hygiene
+
+Kilo CLI is a fork of opencode. Minimizing diff against upstream is a top priority.
+
+- If a change modifies a shared opencode file (anything under `packages/opencode/` not in a path containing `kilocode`), ask whether the logic could live in a Kilo-only directory instead (`packages/opencode/src/kilocode/`, `packages/kilo-gateway/`, etc.) or be reduced to a smaller hook.
+- Refactors or reorganizations of upstream code are a red flag — flag them unless clearly justified.
+- See `.kilo/skills/kilocode-merge-minimizer/SKILL.md` for the decision rules.
+
+### 4. Cloud config schema mirror
+
+When `Config.Info` in `packages/opencode/src/config/config.ts` gains a new `kilocode_change` field, the matching JSON Schema entry must also be added in the cloud repo (`apps/web/src/app/config.json/extras.ts`). CI does **not** check this — flag it as a reminder if you see a new config field added.
+
+### 5. Test quality
+
+- Tests should exercise real implementation, not duplicate logic into the test.
+- Mocks should be avoided where reasonable; flag mock-heavy tests that look like they're testing the mock rather than the code.
+- New behavior in `packages/opencode/` should generally come with a test under `packages/opencode/test/`.
+
+### 6. User-facing changes
+
+- Features, bug fixes, and breaking changes should include a changeset (`.changeset/*.md`). If a PR clearly changes user-visible behavior and has no changeset, mention it.
+- Changeset descriptions are read by end users — if one is present but written as implementation notes ("Add a new export handler that serializes…"), suggest a user-facing rewrite ("Support exporting conversations as markdown").
+- PR descriptions should explain **why**, not enumerate files. Skip file-by-file inventories.
+
+### 7. UI changes
+
+For changes under `packages/kilo-vscode/webview-ui/`:
+
+- Significant visual or layout changes should have a Storybook story added under `webview-ui/src/stories/`. Minor tweaks and i18n-only changes don't need one.
+- Don't ask for locally generated baseline PNGs — those must come from Linux CI.
+
+## How to comment
+
+- Leave comments on the exact line via `gh api .../pulls/{n}/comments`.
+- Make it clear suggestions are suggestions; the human decides.
+- If the PR is clean against the above, comment `lgtm` and nothing else.
@@ -25,6 +25,8 @@ When you're reviewing a pull request and want a second opinion on a piece of cod

 The bot reads the review comment, the surrounding diff, and the relevant code in the repository to give you an informed answer.

+{% image src="/docs/img/connect/github/github-review.png" alt="Asking @kilocode-bot a question on a GitHub pull request review comment" width="800" /%}
+
 ### Fix issues directly from GitHub

 Tag the bot on any issue and ask it to handle the fix:
@@ -40,6 +42,8 @@ The bot will:
 - Create a branch with the implementation
 - Open a pull request

+{% image src="/docs/img/connect/github/github-issue.png" alt="Asking @kilocode-bot to fix a GitHub issue" width="800" /%}
+
 ### Diagnose bug reports

 When a bug report comes in and you want to understand what's going on before diving in:
@@ -50,6 +54,8 @@ When a bug report comes in and you want to understand what's going on before div

 The bot examines the bug report, searches the codebase for related code paths, and shares its analysis directly in the issue thread.

+{% image src="/docs/img/connect/github/github-bug.png" alt="Asking @kilocode-bot to diagnose a bug report on a GitHub issue" width="800" /%}
+
 ---

 ## How It Works
@@ -26,6 +26,8 @@ The bot will:
 - Show a thinking/processing animation in Linear while it works
 - Link the resulting pull request back to the issue

+{% image src="/docs/img/connect/linear/linear-fix-issue.png" alt="Asking @kilo to fix an issue in Linear" width="800" /%}
+
 ### Apply changes across multiple repositories

 If a fix or upgrade needs to land in several repos at once:
@@ -36,6 +38,8 @@ If a fix or upgrade needs to land in several repos at once:

 The bot handles each repository independently, creating separate branches and pull requests for each.

+{% image src="/docs/img/connect/linear/linear-multi-repo.png" alt="Asking @kilo to apply changes across multiple repositories from Linear" width="800" /%}
+
 ### Get help understanding an issue

 Before jumping into a fix, ask the bot to analyze the problem:
@@ -46,6 +50,8 @@ Before jumping into a fix, ask the bot to analyze the problem:

 The bot examines the issue context and searches the connected codebase to surface likely causes.

+{% image src="/docs/img/connect/linear/linear-understand-issue.png" alt="Asking @kilo to analyze the cause of a Linear issue" width="800" /%}
+
 ---

 ## How It Works
@@ -28,6 +28,8 @@ When you mention `@Kilo` in a thread, the bot:
@Kilo how is error handling implemented in the payment processing module?
 ```

+{% image src="/docs/img/connect/slack/slackbot-ask-questions.webp" alt="Asking Kilo a question about the codebase in Slack" width="800" /%}
+
 ### Implement fixes and features from Slack discussions

 When your team identifies a bug or improvement in a thread, ask the bot to handle it:
@@ -43,6 +45,8 @@ The bot will:
 - Create a branch with the implementation
 - Push a pull request to your repository

+{% image src="/docs/img/connect/slack/slackbot-turn-discussions-into-PRs.webp" alt="Kilo turning a Slack thread discussion into a pull request" width="800" /%}
+
 ### Implement changes across multiple repositories

 If the same change needs to land in several repos, just tell the bot:
@@ -51,6 +55,8 @@ If the same change needs to land in several repos, just tell the bot:
@Kilo please fix this in the cloud, landing, and handbook repos
 ```

+{% image src="/docs/img/connect/slack/slackbot-coding.webp" alt="Kilo implementing changes across multiple repositories from Slack" width="800" /%}
+
 ### Debug issues

 Paste an error message or stack trace and ask for help:
@@ -61,6 +67,8 @@ Paste an error message or stack trace and ask for help:
 Can you help me understand what's causing it?
 ```

+{% image src="/docs/img/connect/slack/slackbot-bugs.webp" alt="Kilo helping debug a production error in Slack" width="800" /%}
+
 ---

 ## How to Interact
@@ -189,10 +189,6 @@ Each instance runs on a dedicated machine — there is no shared infrastructure

 Your storage is region-pinned — once your instance is created in a region (e.g., DFW), it always runs there. OpenClaw config lives at `/root/.openclaw` and the workspace at `/root/clawd`.

-{% callout type="info" %}
-These are the beta specifications for machines and subject to change without notice.
-{% /callout %}
-
 ## Related

 - [KiloClaw Overview](/docs/kiloclaw/overview)
@@ -9,10 +9,7 @@ KiloClaw uses Kilo Gateway credits by default — if you route requests through

 ## Instance Hosting

-KiloClaw hosting is **free during the beta period**. Each user gets a dedicated machine (2 shared vCPUs, 3 GB RAM, 10 GB SSD) at no cost.
-
-> ℹ️ **Info**
-> Beta pricing is subject to change. Paid hosting tiers may be introduced after the beta period ends. Any changes will be announced in advance.
+Each user gets a dedicated machine (2 shared vCPUs, 3 GB RAM, 10 GB SSD).

 ## Model Inference

@@ -7,7 +7,7 @@ description: "One-click deployment of your personal AI agent with OpenClaw"

 KiloClaw is Kilo's hosted [OpenClaw](https://openclaw.ai) service — a one-click deployment that gives you a personal AI agent without the complexity of self-hosting. OpenClaw is a 24/7, open source AI agent that connects to chat platforms like Telegram, Discord, and Slack so it can take real actions automatically, not just chat.

-KiloClaw is powered by KiloCode. The API key is platform-managed, so you never need to bring your own. KiloClaw is currently in **Beta**.
+KiloClaw is powered by KiloCode. The API key is platform-managed, so you never need to bring your own.

 ## Why KiloClaw?