AGENTS.md

1# AionUi - Project Guide
2 
3All contributors (human and AI) must follow [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR. ([Chinese version](CONTRIBUTING.zh.md))
4 
5## Code Conventions
6 
7### File & Directory Structure
8 
9- **Directory size limit**: Prefer ≤ **10** direct children per directory; new or substantially reorganized directories must satisfy this.
10 
11See [docs/contributing/file-structure.md](docs/contributing/file-structure.md) for complete rules. Agents must also follow the `architecture` skill (`.claude/skills/architecture/SKILL.md`) when creating files or modules.
12 
13### Naming
14 
15- **Components**: PascalCase (`Button.tsx`, `Modal.tsx`)
16- **Utilities**: camelCase (`formatDate.ts`)
17- **Hooks**: camelCase with `use` prefix (`useTheme.ts`)
18- **Constants files**: camelCase (`constants.ts`) — values inside use UPPER_SNAKE_CASE
19- **Type files**: camelCase (`types.ts`)
20- **Style files**: kebab-case or `ComponentName.module.css`
21- **Unused params**: prefix with `_`
22 
23### UI Library & Icons
24 
25- **Components**: `@arco-design/web-react` — no raw interactive HTML (`<button>`, `<input>`, `<select>`, etc.)
26- **Icons**: `@icon-park/react`
27 
28### CSS
29 
30- Prefer **UnoCSS utility classes**; complex styles use **CSS Modules** (`ComponentName.module.css`)
31- Colors must use **semantic tokens** from `uno.config.ts` or CSS variables — no hardcoded values
32- Arco theme overrides go in `packages/desktop/src/renderer/styles/arco-override.css`; component-scoped Arco overrides use CSS Module with `:global()`
33- Global styles only in `packages/desktop/src/renderer/styles/`
34 
35Formatting rules (Oxfmt, Prettier-compatible):
36 
37- Single-element arrays that fit on one line → inline: `[{ id: 'a', value: 'b' }]`
38- Trailing commas required in multi-line arrays/objects
39- Single quotes for strings
40 
41### TypeScript
42 
43- Strict mode enabled — no `any`, no implicit returns
44- Use path aliases: `@/*`, `@process/*`, `@renderer/*`
45- Prefer `type` over `interface` (per Oxlint config)
46- English for code comments; JSDoc for public functions
47 
48### Internationalization (i18n)
49 
50New or changed user-facing text must use i18n keys; do not introduce hardcoded strings. Languages and modules are defined in `packages/desktop/src/common/config/i18n-config.json`.
51 
52See the `i18n` skill (`.claude/skills/i18n/SKILL.md`) for complete workflow, key naming, and validation steps.
53 
54## Architecture
55 
56Two process types — never mix their APIs:
57 
58| Process  | Path                             | Restriction     |
59| -------- | -------------------------------- | --------------- |
60| Main     | `packages/desktop/src/process/`  | No DOM APIs     |
61| Renderer | `packages/desktop/src/renderer/` | No Node.js APIs |
62 
63Cross-process communication must go through the IPC bridge (`packages/desktop/src/preload/`).
64See [docs/architecture/overview.md](docs/architecture/overview.md) for details.
65 
66## Testing
67 
68**Framework**: Vitest 4 (`vitest.config.ts`). Project coverage target is ≥ 80%; ordinary changes should add focused tests for changed behavior.
69 
70```bash
71bun run test              # run all tests
72bun run test:coverage     # with coverage report
73```
74 
75See the `testing` skill (`.claude/skills/testing/SKILL.md`) for complete workflow and quality rules.
76 
77## Workflow
78 
79### Scope & Enforcement
80 
81- **Hard blockers**: process boundary violations, TypeScript errors, failing tests, unsafe IPC usage, missing i18n for new or changed user-facing text, and raw interactive HTML in new UI.
82- **Current-change requirements**: naming, CSS, file placement, tests, docs, directory size, and single-file-directory rules apply to files created or meaningfully modified by the current change.
83- **Ratchet rules**: existing directory size or single-file-directory violations do not require cleanup during ordinary feature work or bugfixes, but the current change must not make them worse.
84- **No scope expansion**: implementation plans and reviews must not create extra tasks, phases, or acceptance criteria for cleanup unless the user asks for that scope.
85- **Ignored working docs**: `docs/superpowers/` is intentionally gitignored for local Superpowers specs and plans. Do not force-add or otherwise commit files from this directory.
86 
87### During Development
88 
89Auto-fix as you edit:
90 
91```bash
92bun run lint:fix       # auto-fix lint issues (oxlint)
93bun run format         # auto-format all files (oxfmt)
94bunx tsc --noEmit      # verify no type errors
95```
96 
97If your changes touch `packages/desktop/src/renderer/`, `locales/`, or `packages/desktop/src/common/config/i18n`, also run:
98 
99```bash
100bun run i18n:types
101node scripts/check-i18n.js
102```
103 
104### Before Pushing
105 
106AI agents must not push unless explicitly asked. When pushing, use `just push`, never `git push`:
107 
108```bash
109just push                          # lint → format-check → typecheck → test → git push
110just push -u origin feat/branch    # same checks, with extra git push args
111```
112 
113Any step that fails aborts the push. Fix the issue, commit, then retry.
114 
115> **Note for AI agents**: `just push` uses `--quiet` for lint — only errors cause failure. The project has many pre-existing lint _warnings_ which do NOT indicate failure. Judge success by exit code, not by output volume.
116 
117### Before PR (optional stricter check)
118 
119`prek` replicates the **exact CI pipeline** (includes end-of-file, trailing whitespace checks on all file types):
120 
121```bash
122# One-time setup
123npm install -g @j178/prek
124 
125# Run
126prek run --from-ref origin/main --to-ref HEAD
127```
128 
129> `prek` is read-only — it reports but does not fix. If it reports issues, run the auto-fix commands above, commit, then re-run.
130 
131### Commit & PR Format
132 
133Commits and PR titles must follow the Conventional Commit format defined in [CONTRIBUTING.md](CONTRIBUTING.md):
134 
135```text
136<type>(<scope>): <subject>
137```
138 
139Allowed types: `feat`, `fix`, `perf`, `refactor`, `docs`, `style`, `chore`, `test`, `ci`, `build`.
140 
141When opening a PR, fill in the PR body using [.github/pull_request_template.md](.github/pull_request_template.md) and complete its checklists honestly (only check items you actually ran or verified).
142 
143**NEVER add AI signatures** (Co-Authored-By, Generated with, etc.).
144 
145## Skills Index
146 
147| Skill            | Purpose                                                                     | Triggers                                                                                               |
148| ---------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
149| **architecture** | File & directory structure conventions for all process types                | Creating files, adding modules, architectural decisions                                                |
150| **i18n**         | Internationalization workflow and standards                                 | Adding or changing user-facing text, modifying `locales/` or `packages/desktop/src/common/config/i18n` |
151| **testing**      | Testing workflow and quality standards                                      | Writing tests, changing runtime behavior, fixing bugs, or claiming behavior is verified                |
152| **bump-version** | Version bump workflow: update package.json, checks, branch, PR, tag release | Bumping version, `/bump-version`                                                                       |
153 
154> Skills are located in `.claude/skills/` and contain project conventions that apply to **all** agents and contributors.
155