chore: add issue/PR templates, PR check, AGENTS.md and shared agent skills (#1043)

Adds a PR template (linked issue, what and why, how it was verified, review focus), a minimal reproduction field on the bug form and required acceptance criteria on the feature form, and CONTRIBUTING.md with the issue and PR rules. A PR check labels needs-info and leaves one comment when the issue link or the verification section is missing; it only reads the title and description.

AGENTS.md is now tracked, with CLAUDE.md linking to it, and covers layout, rules, commands, the checks CI runs, pitfalls and parallel worktrees. The verify and issue-fix skills are shared under .agents/skills and linked from .claude/skills; the rest of .claude/ stays local.

.agents/skills/issue-fix/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: issue-fix
+description: Triage and fix a GitHub issue (or a user-reported bug) end to end — reproduce, find the root cause, generalise it to every sibling case, fix the class rather than the instance, verify, and open one PR. Use when given an issue URL/number or asked to fix a reported bug and open a PR ("看看这个 issue", "修一下这个 bug", "提 pr").
+---
+
+# Fix an issue: from one case to the whole class
+
+The reported case is one sample of a defect class. A fix that only makes the
+screenshot go away is not done: the next question is always "does this break for other
+languages / platforms / entry points too?". Answer that before anyone asks.
+
+## 1. Read and reproduce
+
+- `gh issue view <n> --comments` (repo `l0ng-ai/openidea`). Read attached logs/screenshots
+  closely: OS, language, toolchain versions, exact error text.
+- Locate the code path and confirm the claim in code, with `file:line` evidence.
+  Say plainly whether it is a real bug, a missing feature, or user environment.
+- Reproduce locally when possible (`fixtures/` projects, `/verify` for runtime). If the
+  reporter's platform (often Windows/Linux) can't be reproduced here, say so up front.
+- Do not ask for a generic environment/log checklist before trying the flow and inspecting the code.
+  Record the attempt and result; ask only for a fact that actually blocks the next diagnostic step.
+  Missing fields, limited time, or unavailable automation are not by themselves reasons to ask the reporter.
+- Treat a maintainer-confirmed bug as an investigation task even if local reproduction fails. Distinguish
+  “not reproduced here” from “not a bug”, and do not require the reporter to prove its existence again.
+
+## 2. Name the root cause as a class
+
+Write one sentence of the form "<mechanism> is missing/wrong, so any <X> hits it",
+not "<this button> is broken". Typical classes in this codebase:
+
+- Per-language config handled for one language only (`languages/*.toml`, `ide-sdk`).
+- Platform gaps: paths, executables, shells, `.cmd`/`.exe`, separators — macOS-only code.
+- Toolchain/version discovery: one probe location, no version check, no rescan.
+- Two features each implementing half a flow and never joined (feature isolation →
+  should go through an action/service).
+- State not reset on project switch / window reuse; events not scoped per window.
+- Failure surfaced as raw stderr/stack trace or retried until "crashed" instead of a
+  clear status with an action.
+- UI: same primitive styled differently in N places.
+
+## 3. Sweep for siblings
+
+Search systematically, not by memory:
+
+- Same pattern elsewhere: `git grep` the function, the config key, the error string,
+  the hard-coded path/flag. Check every `languages/*.toml` entry and every platform branch.
+- Same flow for other languages/runtimes (Java ↔ Kotlin/Gradle, Python ↔ venv/uv,
+  Node ↔ Deno/Bun, Go, Rust …): would they fail the same way?
+- Other callers/entry points of the same flow (menu, context menu, gutter, shortcut, CLI arg).
+- Neighbouring failure modes of the same mechanism (not installed / wrong version /
+  installed but crashes / slow start / installed mid-session).
+  For broad sweeps spawn one Explore agent with the class description, not the instance.
+
+## 4. Decide the fix at the right altitude
+
+- Fix the mechanism once (shared helper, action, config hook) so siblings are fixed
+  by construction; don't patch each call site.
+- Respect `AGENTS.md` rules (crate boundaries, no cross-feature imports, `IdeResult`,
+  UTF-16). If the right fix breaks a rule, pick the rule-respecting design and say why.
+- Compare with how established IDEs solve it when relevant; prefer the established answer.
+- Present: root cause, sibling table, proposed fix, what's deferred. When the user leaves
+  the choice to you, go ahead without asking again.
+
+## 5. Implement and test the class
+
+- Tests cover the class: table-driven over languages/platforms/states, not just the
+  reported input. Include the reporter's case verbatim.
+- Run the scoped checks (`pnpm vitest run <path>`, `cargo nextest run -p <crate>`), then
+  `/verify` in the app for UI or runtime behaviour.
+
+## 6. PR
+
+- One branch `fix/<slug>`, one PR unless the user asks otherwise; `Fixes #<n>` in the body.
+- Don't stage untracked IDE-state dirs (`.ideal/`, `.openidea/`) or screenshots.
+- PR body follows `.github/pull_request_template.md`: `Closes #<n>`, then
+  **What and why** (user-visible change + root cause at class level, 2–4 sentences),
+  **How it was verified** (commands run and results, siblings fixed/deferred, what could break and how
+  it was checked, what was not verified, e.g. "Windows not tested"; for UI changes the before/after
+  screenshot paths from `/verify`), **Review focus** (optional). Short and plain.
+
+## Report format
+
+Reply in the user's language:
+
+```
+Root cause: <one sentence, class level>
+Sibling sweep:
+| Location / case | Affected? | Action |
+Fixed / not covered (why) / not verified (platform)
+PR: <url>
+```

.agents/skills/verify/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: verify
+description: Build, launch and drive the OpenIDEA desktop app through the Tauri MCP bridge to verify a change at runtime.
+---
+
+# Verify OpenIDEA in the running app
+
+## Launch
+
+- Run the app from the worktree that holds the change: `pnpm tauri dev` in the background, logging
+  into your task's scratch subdirectory. Use `pnpm dev:app` instead when your checks call
+  `window.__TAURI__` from `execute_js`. The wrapper gives each worktree its own app identity, data,
+  settings and Vite port, so other worktrees and the installed app don't interfere. If it reports a
+  session already running for this worktree, reuse that one.
+- Once the app is up, `pnpm dev:status` lists this worktree's MCP bridges. Pass the reported
+  `appIdentifier` (the port) on every `mcp__tauri__*` call. The MCP server is shared between
+  sessions: never `driver_session stop` without an `appIdentifier`, and re-check `document.title` /
+  `location.href` before acting if anything looks off.
+- Make sure the binary contains the change: a session already running for this worktree may be an
+  older build. Restart it after Rust changes; frontend changes reload through Vite.
+- After the app restarts, `driver_session start` again for your port (a stale session says "Already connected").
+- If the `pnpm tauri dev` process exits while the app window stays open, Vite is gone and any webview
+  reload shows an empty `#root`. Stop that app and start the session again.
+- Stop everything you started when done and nothing else; never use process-name kills.
+
+## Driving
+
+- `manage_window focus` before screenshots / timing-sensitive steps: a background window throttles timers
+  (debounced LSP / VCS refreshes stall, `setTimeout` promises in `execute_js` time out) and native
+  screenshots come back black.
+- Settings is a separate native window `settings-main`; pass `windowId`, focus it before screenshotting.
+- CodeMirror / xterm ignore MCP `type`. Focus the element, then `document.execCommand('insertText', false, text)`.
+  For xterm Enter, dispatch a `keydown` (`key: 'Enter', keyCode: 13`) on `.xterm-helper-textarea`.
+- MCP clicks arrive with `event.detail === 0`; CodeMirror treats them as line-select clicks. Set the caret
+  through the view instead: `document.querySelector('.cm-content').cmTile.view`.
+- MCP `text` strategy can resolve to a hidden node; prefer coordinates (CSS px = image px × 0.9) or CSS selectors.
+- CSS-module edits often trigger a full page reload in dev: dialogs close, Run sessions and terminal
+  scrollback reset, and each reload spawns a fresh shell. Re-open what you were testing.
+
+## Evidence
+
+- For UI or interaction changes, capture `before.png` (on `main` or with the fix reverted) and
+  `after.png` at the same state and window size, into your task's scratch subdirectory. Multi-step
+  flows: a numbered series (`after-1.png`, `after-2.png`, ...).
+- Report the absolute paths; they go into the PR's **How it was verified** section and the triage
+  acceptance entry. Never commit screenshots to the feature branch.
+
+## Fixture
+
+`fixtures/` has sample projects (go-app, rust-app, ts-app, kotlin-gradle, polyglot). Copy one into
+your scratch directory before editing it, and don't commit the IDE state it creates (`.openidea/`).
+
+## Flows worth driving
+
+⌘⇧O Goto File · ⌘⇧F Find in Files (preview scroll + highlight) · ⌘⇧A Find Action · editor edit/undo/autosave ·
+Terminal (Unicode, venv) · Commit view at the default narrow width · Problems · Run → Stop · Project view
+New / Delete (nested `a/b.txt` names) · ⌘, Settings search (+ Keymap filter) · Git Log on a repo without commits.

.claude/skills/issue-fix

@@ -0,0 +1 @@
+../../.agents/skills/issue-fix

.claude/skills/verify

@@ -0,0 +1 @@
+../../.agents/skills/verify

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -42,6 +42,12 @@ body:
         3. ...
     validations:
       required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: A link to a small public repository, or the smallest files/snippet that trigger the problem. Optional, but it's the fastest way to get a fix.
+      placeholder: https://github.com/you/repro-project
   - type: textarea
     id: expected
     attributes:

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -27,6 +27,16 @@ body:
       description: How you'd like it to work. Mockups or examples from other tools are welcome.
     validations:
       required: true
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+      description: How we'll know it's done. One observable behavior per line.
+      placeholder: |
+        - [ ] Right-clicking a test class shows "Run with Coverage"
+        - [ ] Coverage results open in the Coverage tool window
+    validations:
+      required: true
   - type: textarea
     id: alternatives
     attributes:

.github/pull_request_template.md

@@ -0,0 +1,17 @@
+Closes #
+
+## What and why
+
+<!-- 2–4 sentences: the change a user notices, and the root cause.
+     If it doesn't fit, the PR is probably too big; split it. -->
+
+## How it was verified
+
+<!-- Required. Commands you actually ran and their results; what else this could
+     affect and how you checked it still works.
+     UI changes: before/after screenshots. Multi-step interactions: a recording.
+     Backend changes: logs or command output. -->
+
+## Review focus
+
+<!-- Optional: anything you want reviewers to look at closely. -->

.github/workflows/pr-check.yml

@@ -0,0 +1,69 @@
+name: PR check
+on:
+  # pull_request_target so the check can label PRs from forks. It never checks out
+  # or runs PR code: it only reads the PR title and description.
+  pull_request_target:
+    types: [opened, edited, reopened, ready_for_review]
+
+permissions:
+  issues: write
+  pull-requests: write
+
+concurrency:
+  group: pr-check-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    if: github.event.pull_request.user.type != 'Bot' && !github.event.pull_request.draft
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            const pr = context.payload.pull_request;
+            const LABEL = 'needs-info';
+            const MARKER = '<!-- pr-check -->';
+            // Docs, CI and pure refactors may skip the linked issue.
+            const NO_ISSUE_TYPES = /^(docs|ci|build|chore|refactor|style|test)(\(.+\))?!?:/;
+
+            const body = (pr.body || '').replace(/<!--[\s\S]*?-->/g, '');
+            const problems = [];
+
+            const linksIssue =
+              /\b(close[sd]?|fix(e[sd])?|resolve[sd]?)\s*:?\s+(#\d+|https:\/\/github\.com\/[\w.-]+\/[\w.-]+\/issues\/\d+)/i.test(body);
+            if (!linksIssue && !NO_ISSUE_TYPES.test(pr.title)) {
+              problems.push('Link the issue this PR resolves, e.g. `Closes #123`.');
+            }
+
+            const verified = body.match(/^##+\s*How it was verified\s*$([\s\S]*?)(?=^##+\s|(?![\s\S]))/im);
+            if (!verified || !verified[1].trim()) {
+              problems.push('Fill in **How it was verified**: the commands you ran and their results. UI changes need before/after screenshots.');
+            }
+
+            const { owner, repo } = context.repo;
+            const issue_number = pr.number;
+            const comments = await github.paginate(github.rest.issues.listComments, { owner, repo, issue_number });
+            const existing = comments.find(c => c.user.type === 'Bot' && c.body.includes(MARKER));
+            const labeled = pr.labels.some(l => l.name === LABEL);
+
+            if (problems.length) {
+              const text = `${MARKER}\nThanks for the PR. Before review, please update the description (see [CONTRIBUTING.md](https://github.com/${owner}/${repo}/blob/main/CONTRIBUTING.md)):\n\n${problems.map(p => `- ${p}`).join('\n')}\n\nThis check reruns when you edit the description.`;
+              if (existing) {
+                await github.rest.issues.updateComment({ owner, repo, comment_id: existing.id, body: text });
+              } else {
+                await github.rest.issues.createComment({ owner, repo, issue_number, body: text });
+              }
+              if (!labeled) {
+                await github.rest.issues.addLabels({ owner, repo, issue_number, labels: [LABEL] });
+              }
+              return;
+            }
+
+            // Only undo what this check did: the label is cleared only when our comment exists.
+            if (existing) {
+              await github.rest.issues.deleteComment({ owner, repo, comment_id: existing.id });
+              if (labeled) {
+                await github.rest.issues.removeLabel({ owner, repo, issue_number, name: LABEL }).catch(() => {});
+              }
+            }

.gitignore

@@ -30,9 +30,13 @@ target/
 test-results/
 playwright-report/
 
-# Local AI agent files
-CLAUDE.md
-.claude/
+# Local AI agent files. Shared skills live in .agents/skills; .claude/skills links to them.
+CLAUDE.local.md
+.claude/*
+!.claude/skills/
+.claude/skills/*
+!.claude/skills/verify
+!.claude/skills/issue-fix
 
 # Local reference screenshots
 pycharm-screenshots/

AGENTS.md

@@ -0,0 +1,118 @@
+# OpenIDEA — contributor guide
+
+Rust + Tauri 2 desktop IDE with full-featured, multi-language code intelligence.
+Visual style: dark, low-contrast greys, one cool accent
+(`src/styles/tokens.css` is the source of truth for colours and metrics).
+
+## Layout
+
+- `crates/ide-*` — backend crates; one domain each. Depend on `ide-core` for shared
+  types; never reach into another crate's internals.
+- `src-tauri/` — glue only: `state.rs` (AppState / Project), `commands/<domain>.rs`
+  (thin typed IPC adapters), `events.rs`. No domain logic here.
+- `src/bindings.ts` — generated by tauri-specta (`pnpm gen:bindings`). Never edit.
+- `src/platform/` — ipc (`call`, `onIdeEvent`, `nextRequestId`), actions registry,
+  keymap + dispatcher, context keys / `when` clauses, project store.
+- `src/workbench/contributions.ts` — extension points (tool windows, status items,
+  overlays, editor kinds) and cross-feature services (editor, tool windows, notifications).
+- `src/ui/` — design-system primitives. `src/features/<name>/` — one feature each,
+  exporting `activate()` registered in `src/features/index.ts`.
+- `languages/<id>.toml` — language definitions (detection, comments, LSP, DAP).
+- `crates/ide-host` — the `openidea-server` binary for remote development.
+- `wit/` — plugin interface definitions; `plugins/` — sample and bundled plugins;
+  `templates/` — plugin starter templates.
+- `e2e/` — Playwright UI tests (`pnpm e2e`). `fixtures/` — sample projects per language
+  for manual and automated testing.
+
+## Rules
+
+- IPC coordinates: 0-based lines, **UTF-16** columns/offsets everywhere (`ide-core::text`).
+- Every command returns `IdeResult<T>`; convert internal errors at the crate edge.
+- Streaming → `tauri::ipc::Channel<T>`; cancellable → UI-allocated `RequestId` +
+  `cancel_request`. Backend → UI notifications → `IdeEvent` via `EventSink`.
+- Long work never blocks the UI thread or a Tauri command thread: use
+  `spawn_blocking`/rayon, honour `CancellationToken`.
+- Frontend features never import each other; communicate via actions, contributions
+  and services. All user-invocable behaviour is an action with a stable id; default
+  shortcuts live in `src/platform/keymaps/`.
+- Styling: CSS Modules + tokens only (no hex literals in components). Inline SVG
+  icons from `src/ui/icons.tsx`, never emoji. Real `<button>`/`<input>`; `aria-label` on icon buttons.
+- User-visible text goes through the text catalog: add every new string to both
+  `src/platform/locales/text/en.json` and `zh.json` (`textCatalog.test.ts` enforces it).
+- Keep comments sparse and purposeful; match surrounding style.
+- For GUI verification, prefer Tauri MCP; use Computer Use only when Tauri MCP is
+  unavailable or cannot cover the required checks.
+
+## Issues & PRs
+
+Follow `CONTRIBUTING.md` and `.github/pull_request_template.md`: one issue per PR with
+`Closes #<n>`, reproduce first, keep the diff focused, short plain description, and a
+**How it was verified** section with commands run, results and (for UI) before/after screenshots.
+Unclear product decisions → `needs-decision` and stop.
+
+## Skills
+
+Shared agent skills live in `.agents/skills/` (`.claude/skills/` links to them):
+`verify` drives the running app through Tauri MCP and captures screenshot evidence;
+`issue-fix` takes an issue from reproduction to one PR.
+
+## Commands
+
+- `pnpm tauri dev` — run the app with worktree isolation (Node 22.18+).
+  `pnpm dev:app` also enables the global Tauri API. `pnpm dev:status` reports
+  this worktree's running MCP bridges and actual ports.
+- `pnpm build` — typecheck + bundle frontend.
+- `cargo nextest run --workspace` (or `cargo test`), `cargo clippy --workspace --all-targets -- -D warnings`, `cargo fmt --all`.
+- `pnpm test`, `pnpm e2e`, `pnpm lint`, `pnpm format:check`, `pnpm knip`, `pnpm typecheck`,
+  `pnpm gen:bindings`.
+- `pnpm perf` (UI interaction latency / frames / leaks), `pnpm perf:rust` (criterion
+  benches vs budgets). Budgets: `perf/budgets.json`.
+
+## Before opening a PR
+
+Run what CI runs for the parts you touched:
+
+- Rust: `cargo fmt --all --check`, `cargo clippy --workspace --all-targets -- -D warnings`,
+  `cargo nextest run --workspace`. After changing IPC types, run `pnpm gen:bindings` and
+  commit `src/bindings.ts`; CI fails if it differs.
+- Frontend: `pnpm typecheck`, `pnpm lint`, `pnpm format:check`, `pnpm knip`, `pnpm test`,
+  `pnpm build`, and `pnpm e2e` for UI flows.
+- UI or runtime behaviour: verify in the running app (`.agents/skills/verify`).
+
+## Pitfalls
+
+- Run a subset of frontend tests with `pnpm vitest run <path>`. `pnpm test -- <path>` ignores
+  the filter and runs the whole suite, which takes several minutes.
+- Don't run clippy while iterating: `pnpm tauri dev` compiles anyway. Run
+  `cargo fmt --all` + `cargo clippy -p <crate> --all-targets -- -D warnings` once, right
+  before committing. A cold build cache can take around 5 minutes. Run long checks one at
+  a time, not chained in one shell call that may hit the 10-minute tool timeout.
+- `pnpm tauri dev` does a full debug build. Clippy only checks the code, so a passing clippy
+  doesn't make the first launch fast.
+
+## Parallel worktrees
+
+Several worktrees can be developed and run side by side.
+
+- Create one per task: `git worktree add ../<name> -b <branch> origin/main`, then
+  `pnpm install` in it.
+- Launch with `pnpm tauri dev` / `pnpm dev:app`, not the raw `pnpm exec tauri dev` CLI. The
+  wrapper starts Vite on a worktree-derived port (advancing if occupied), passes its actual
+  URL to Tauri, and reports an existing launcher instead of starting another for the same
+  worktree. HMR uses the Vite port.
+- Debug app identity, data, settings, logs and single-instance scope follow the canonical
+  worktree path captured at build time, independent of launch cwd. Launching the same debug
+  binary again focuses its existing instance and forwards its path argument. Different
+  worktrees and the installed release can coexist. `--release` uses normal release identity
+  and bypasses the development wrapper.
+- MCP bridge ports are dynamic (9223–9322). Use `pnpm dev:status`, connect to the reported
+  port, verify identifier/cwd, and pass `appIdentifier: <port>` explicitly. Do not assume the
+  default MCP session belongs to this worktree.
+- Keep each worktree's Cargo output directory separate; do not point `CARGO_TARGET_DIR` or
+  `target` symlinks at a shared directory.
+- Each worktree's first build is cold (around 5 minutes) and its Cargo output takes
+  15–30 GB. Avoid running several heavy builds on one machine at the same time.
+- Stop only processes started for the current worktree/session. Never use broad
+  process-name kills such as `pkill openidea`.
+- When done: stop that worktree's app and dev session, delete its build output, then
+  `git worktree remove ../<name>`.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing to OpenIDEA
+
+These rules apply to everyone, and to any coding agent working on their behalf.
+Project layout, coding rules, commands and checks are in [AGENTS.md](AGENTS.md).
+
+## Issues
+
+- One problem or request per issue. Use the issue forms.
+- Bugs: steps that reproduce the problem from a fresh start. A minimal sample
+  project is the fastest way to get a fix.
+- Features: state the problem and the acceptance criteria. A feature is ready to
+  build once a maintainer labels it `planned`.
+- Labels track status: `needs-info` waits on the reporter, `needs-decision` waits
+  on a maintainer, `planned` is accepted, `needs-acceptance` has a fix waiting to be
+  checked.
+
+## Pull requests
+
+- One issue per PR, linked with `Closes #123`. Feature PRs need a `planned` issue.
+  Docs, CI and pure refactors may skip the issue.
+- Reproduce the problem first, or write a test that fails before the fix.
+- Fix the cause, and check whether the same cause breaks anything nearby.
+- Keep the diff focused. Unrelated refactors go in their own PR.
+- Title: [Conventional Commits](https://www.conventionalcommits.org/), e.g.
+  `fix(editor): keep the caret visible after folding`.
+- Fill in the template. Keep the description short and in plain words. If it
+  doesn't fit in a few sentences, the PR is probably too big.
+- **How it was verified** is required: the commands you ran and their results,
+  and what else the change could affect. UI changes need before/after screenshots;
+  multi-step interactions need a recording.
+- If a change needs a product decision you can't make, ask in the issue and stop
+  rather than guessing.
+
+A check on each PR adds `needs-info` when the issue link or the verification
+section is missing, and removes it once they're filled in.