CLAUDE.md

1# CLAUDE.md — Agent Skill Routing for ORGII
2 
3This file orients Claude / orgii agents working in this repo. It tells you **which audit / methodology skill to invoke** for which kind of task, and what to deliver before declaring work done.
4 
5> Cursor IDE users: live UI-feature delivery rules live in `.cursor/rules/ui-feature-workflow.mdc`. This file does **not** replace those — it's about skill routing for AI agents, not unit-test gates.
6 
7This is **advisory**, not a hard contract. Use judgment based on PR size and risk.
8 
9---
10 
11## Skill Routing Table
12 
13| Scenario                                                                                                                   | Skill to invoke                     | When                                                                                                                                          |
14| -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
15| Rust / TypeScript architecture, types, dead code, FSM, naming overload, wire protocol, init parity                         | `architecture-audit`                | Before finalizing a refactor plan; before cleanup/unification PRs; when reviewing a domain rewrite                                            |
16| Frontend UI consistency, design-system component usage, arbitrary Tailwind values, a11y basics, visual-pattern duplication | `frontend-ui-audit`                 | Before delivering a PR that touches `*.tsx` under `src/components/` or `src/modules/**/components/` (component refactors, UI cleanup batches) |
17| React performance, re-renders, async waterfalls, bundle size, heavy dependencies, virtualization, high-frequency events    | `react-best-practices`              | For performance-focused React implementation/review; not for routine styling, copy, or single-file bug fixes without a performance concern    |
18| Both architecture and React performance change together                                                                    | Run both, keep findings categorized | Apply `architecture-audit` to ownership/boundaries and `react-best-practices` to measured React runtime concerns                              |
19| E2E test surface (Playwright / WebDriver), test stability                                                                  | `e2e-testing`                       | When adding or repairing rendered E2E specs                                                                                                   |
20| Cloud sync / session sharing / collab correctness (share, push/retract, fork, replay, comments, continuation)              | `dual-instance-verification`        | Before declaring any sharing/sync change "verified"; when a sharing bug escaped earlier testing                                               |
21 
22Skills live at:
23 
24- `~/.orgii/skills/architecture-audit/SKILL.md` (user-global)
25- `~/.orgii/skills/frontend-ui-audit/SKILL.md` (user-global)
26- `.orgii/skills/architecture-audit/SKILL.md` (workspace copy, if present)
27- `.orgii/skills/react-best-practices/SKILL.md` (workspace; ORGII overlay for Vercel's React guidance)
28- `.orgii/skills/e2e-testing/SKILL.md` (workspace)
29- `.orgii/skills/dual-instance-verification/SKILL.md` (workspace; 双机实测 protocol for cloud sync / sharing)
30 
31If the skill block isn't already prefetched in your context, read its `SKILL.md` before acting on it.
32 
33---
34 
35## Default Delivery Flow
36 
37### Touching `*.tsx` files (UI work)
38 
39Before declaring a UI-touching task complete, ask:
40 
411. **Is this a single-file bug fix?** If yes, skip `frontend-ui-audit` (its own "When NOT To Use" rules out single bug fixes — noise-to-value ratio is too high).
422. **Is this a component refactor, UI cleanup, or "should this use the design system?" question?** If yes, run `frontend-ui-audit` over the changed files and drop a report in `docs/frontend-ui-audit-YYYY-MM-DD/<ComponentName>.md` using the skill's output format. Summarize fix / keep-with-reason / abstract counts in the delivery message so the user can see verdicts without opening the file.
433. **Did you find a fix-candidate that spans multiple files?** Don't fix site-by-site silently. Surface it as a sweep candidate per the skill's `Systematic Sweep Discipline` section and let the user decide whether to land a config-level change.
44 
45### React performance-focused work
46 
47Use `react-best-practices` only when performance is part of the task: re-renders, async waterfalls, bundle/startup cost, heavy dependencies, virtualization, high-frequency events, or subscription scope. Apply its ORGII filter before upstream guidance: Next.js/RSC/server-only rules are inapplicable, SWR is not introduced by default, and runtime performance claims require measurement rather than typecheck-only evidence.
48 
49### Touching Rust / backend / type-level / cross-layer code
50 
51Before finalizing a refactor plan, walk the 10-layer `architecture-audit` checklist (or at least the layers the change clearly touches). State which layers you covered and which you intentionally skipped.
52 
53### When multiple methodologies apply
54 
55Run every applicable skill. Keep architecture, React performance, and UI-consistency findings clearly categorized. Only skills that define an audit-report format require a report; `react-best-practices` is implementation/review guidance and does not create a report by default.
56 
57---
58 
59## What This File Does NOT Do
60 
61- It does **not** force every PR to produce an audit report. Single bug fixes, copy tweaks, hotfix patches → just ship.
62- It does **not** make `react-best-practices` a gate for every `*.tsx` edit. Styling, copy, ordinary UI assembly, and routine single-file bug fixes do not trigger it unless performance is explicitly in scope.
63- It does **not** replace the skills' own `When NOT To Use` rules.
64- It does **not** replace `.cursor/rules/ui-feature-workflow.mdc` for human/Cursor flow (unit tests + TEST_CASES.md + acceptance criteria). Those gates are about delivery quality; this routing is about which methodology to apply.
65- It does **not** mandate any commit-message format (commitlint handles that), any lint rule, or any pre-commit hook. Audit reports are docs, not gates.
66- It does **not** lock in skill content. If `~/.orgii/skills/*/SKILL.md` updates, this file's routing still applies — read the current SKILL.md, not your memory of it.
67 
68---
69 
70## Audit Report Conventions
71 
72- **Location:** `docs/<skill-name>-YYYY-MM-DD/<ComponentName>.md` (one date-stamped folder per audit batch, one file per audited component).
73- **Format:** follow the `## Output Format` section in the relevant skill verbatim — tables with Line / Element / Verdict / Reason / Suggested change columns.
74- **`keep with reason` rows MUST fill the Reason column.** That's the audit's value-add — preventing the next pass from re-flagging the same hit.
75- **Don't modify source code in an audit-only PR.** Audit and fix are separate concerns; mixing them makes review impossible.
76 
77---
78 
79## When You're Unsure
80 
81- If you don't know which skill applies, **lean toward running `frontend-ui-audit` for UI changes and `architecture-audit` for type/control-flow changes**. Both being run when only one was needed costs nothing; missing one is a real gap.
82- If you're certain the user wants direct implementation and not an audit (e.g. "just fix this bug"), do that — don't insert an audit pass unprompted.
83- If the user asks "why didn't audit catch X?", check whether X is in scope for the skill they're invoking before assuming the audit failed. (`architecture-audit` is type/architecture, not UI consistency — see `frontend-ui-audit` for the latter.)
84