docs(agents): consolidate AGENTS.md and align skills with latest prompt guidelines (#196)

AGENTS.md

@@ -1,304 +1,106 @@
 # Repository Guidelines
 
+Rules for agents working in this repository. When a rule conflicts with what you find in the code, surface the conflict instead of silently deviating.
+
 ## Project Structure & Module Organization
 
 - Core application lives under `app/`, with App Router layouts in `app/(auth)/`, `app/(dashboard)/`.
 - Supporting UI atoms live in `components/`; shared hooks in `hooks/`, shared contexts in `contexts/`.
 - Configuration lives in `next.config.ts`, `app.config.ts` (if present), and `config/`.
 - Shared utilities and lib code are in `lib/`; type definitions in `types/`.
-- i18n locale files live under `i18n/locales/` (structure must match the old project).
-- Static assets belong in `public/` or `assets/`.
-- Tests belong in `tests/` (mirror source structure when tests exist).
-- **UI vs feedback**: `components/ui/` holds presentational, declarative UI primitives (e.g. Button, Dialog). `lib/feedback/` holds global imperative APIs for toast and confirm dialogs (MessageProvider/useMessage, DialogProvider/useDialog). Use `@/lib/feedback/message` and `@/lib/feedback/dialog` for imperative feedback; use `@/components/ui/*` for declarative UI.
-
----
+- i18n locale files live under `i18n/locales/`; their structure must match the old project — do not alter i18n layout or keys arbitrarily.
+- Static assets belong in `public/` or `assets/`; tests in `tests/` (mirror source structure).
+- **UI vs feedback**: `components/ui/` holds presentational, declarative UI primitives (Button, Dialog). `lib/feedback/` holds global imperative APIs for toast and confirm dialogs. Use `@/lib/feedback/message` and `@/lib/feedback/dialog` for imperative feedback; use `@/components/ui/*` for declarative UI.
 
 ## Build, Test, and Development Commands
 
-- **Node version requirement**: Before running `pnpm` commands (especially checks/tests), run `nvm use v22` in this repository.
+Run `nvm use v22` before any `pnpm` command in this repository.
 
-- `pnpm dev` – start the Next.js development server with hot reload.
-- `pnpm build` – create a production build.
-- `pnpm start` – run the production bundle locally.
-- `pnpm lint` – run ESLint.
-- `pnpm test:run` – run the test suite (when configured).
-- `pnpm tsc --noEmit` – perform a strict TypeScript type check (or rely on `next build` for type-checking).
+- `pnpm dev` – start the dev server (applies theme overrides first).
+- `pnpm build` – production build (also type-checks); `pnpm start` – run it locally.
+- `pnpm lint` / `pnpm lint:fix` – run / auto-fix ESLint.
+- `pnpm type-check` – strict TypeScript check (applies theme overrides, then `tsc --noEmit`).
+- `pnpm format` / `pnpm format:check` – Prettier write / check.
+- `pnpm test:run` – run the test suite.
 
----
+## Quality Gates — must pass before every commit
 
-## Mandatory Code Quality Checks
+1. `pnpm install --frozen-lockfile` – lockfile in sync. After changing `package.json`, run `pnpm install` and commit the updated `pnpm-lock.yaml`; CI fails otherwise.
+2. `pnpm type-check` – zero type errors.
+3. `pnpm lint` – zero ESLint errors.
+4. `pnpm format:check` – consistent formatting (fix with `pnpm format` or `pnpm lint:fix`).
+5. `pnpm test:run` – all tests pass, and tests are updated to match the change (see Testing Guidelines).
 
-**⚠️ CRITICAL: These checks MUST pass before every commit.**
+Never bypass hooks with `--no-verify`, never disable a failing test instead of fixing it, and never commit code that does not compile.
 
-Before committing any code changes, you MUST run and pass:
+## Engineering Principles
 
-1. **Lockfile Sync Check**: `pnpm install --frozen-lockfile`
-   - Ensures `pnpm-lock.yaml` is in sync with `package.json`
-   - **MUST run `pnpm install` after modifying `package.json` and commit the updated `pnpm-lock.yaml`**
-   - CI will fail if the lockfile is out of sync.
-
-2. **TypeScript Type Check**: `pnpm tsc --noEmit` (or `pnpm build`)
-   - Ensures all TypeScript types are correct.
-   - Must have zero errors before committing.
-
-3. **Lint Check**: `pnpm lint`
-   - Ensures code follows ESLint rules.
-   - Fix issues before committing.
-
-4. **Format Check** (if Prettier is configured): `pnpm prettier --check .`
-   - Ensures consistent formatting.
-   - If it fails, run `pnpm lint:fix` or `pnpm format` (when available) to auto-fix.
-
-5. **Test Coverage Check** (when tests exist): Review and update tests for code changes
-   - **MUST review test cases** when modifying code: add tests for new features, update tests for changed behavior, remove tests for removed features.
-   - Run `pnpm test:run` to ensure all tests pass.
-   - Ensure test cases accurately reflect the current implementation.
-
-**Automated Enforcement**: If a pre-commit hook exists, it will run these checks. If any check fails, the commit will be blocked.
-
-**Quick Fix**: If checks fail:
-
-1. Run `pnpm install` to sync lockfile (if `package.json` changed).
-2. Fix ESLint/Prettier issues.
-3. Address TypeScript errors manually.
-4. Review and update test cases as needed, then run `pnpm test:run` to verify.
-
----
+- **Code must be as concise and elegant as possible**: the smallest change that solves the problem; reuse existing utilities/components instead of duplicating logic; remove dead code as you go. Single responsibility per function/component; no premature abstraction, clever tricks, or gratuitous indirection — prefer the boring, obvious solution.
+- No TODO comments without an issue number.
+- Composition over inheritance; explicit data flow over implicit coupling; interfaces over singletons.
+- Before implementing, study 2–3 similar existing features and follow their patterns, libraries, and test styles (especially `console-old` during migration). Verify assumptions against real code.
+- Fail fast with descriptive errors, handle them at the appropriate level, and never silently swallow exceptions.
+- When multiple approaches are valid, prefer in order: testability, readability, consistency with project patterns, simplicity, reversibility.
+- Don't introduce new tools or dependencies without strong justification.
 
 ## Coding Style & Naming Conventions
 
-- Use Prettier defaults when configured; run `pnpm lint:fix` or `pnpm format` after making changes.
-- React components use functional components with TypeScript; prefer hooks and custom hooks for shared logic.
-- Component files use **kebab-case** (e.g. `bucket-selector.tsx`); reference them with **PascalCase** in JSX (e.g. `<BucketSelector />`).
-- Override shadcn primitives **outside** `components/ui/`; never edit files in that directory directly.
+- Use Prettier defaults; run `pnpm lint:fix` or `pnpm format` after making changes.
+- React components are functional components with TypeScript; prefer hooks and custom hooks for shared logic.
+- Component files use **kebab-case** (`bucket-selector.tsx`); reference them with **PascalCase** in JSX (`<BucketSelector />`).
+- Override shadcn primitives **outside** `components/ui/`; never edit files in that directory directly. Extend via wrapper components instead of forking primitives.
 - Render tabular data with the shared `DataTable` + `useDataTable` utilities unless a specific requirement makes them unsuitable.
-- Language pack files must follow the structure used in the old project; do not alter i18n layout or keys arbitrarily.
 
 ### Component structure and naming
 
-- **Directories**: Group by **domain/feature**; use plural for domain folders (e.g. `buckets/`, `user/`, `object/`).
-- **File names**: kebab-case; **do not repeat the directory name** in the filename (e.g. under `buckets/` use `info.tsx`, `new-form.tsx`, `selector.tsx` instead of `bucket-info.tsx`, `bucket-new-form.tsx`). The path already provides context.
-- **Component names**: PascalCase, aligned with the domain and purpose (e.g. `BucketInfo`, `UserDropdown`); component names may still include the domain when used in JSX for clarity.
-- **Forms**: Use consistent patterns per domain: `XxxNewForm` / `XxxEditForm` or `XxxForm`; files can be `new-form.tsx`, `edit-form.tsx`, `form.tsx` under the domain folder.
-- **Placement**: Components used only by one domain live in that domain folder; components reused by 3+ different domain pages may stay at root or under `components/shared/` (document if so).
-
----
+- **Directories**: group by domain/feature; plural folder names (`buckets/`, `user/`, `object/`).
+- **File names**: kebab-case; do not repeat the directory name (under `buckets/` use `info.tsx`, `new-form.tsx` — not `bucket-info.tsx`). The path already provides context.
+- **Component names**: PascalCase, aligned with domain and purpose (`BucketInfo`, `UserDropdown`); may include the domain in JSX for clarity.
+- **Forms**: consistent per-domain patterns: `XxxNewForm` / `XxxEditForm` / `XxxForm` in `new-form.tsx`, `edit-form.tsx`, `form.tsx`.
+- **Placement**: single-domain components live in that domain folder; components reused by 3+ domains may live at root or `components/shared/` (document if so).
 
 ## Testing Guidelines
 
-- When tests are configured, add new suites under `tests/`, mirroring source structure.
-- Name files `*.spec.ts` or `*.test.ts`.
-- Keep tests deterministic; mock network calls through provided hooks or context.
-- **⚠️ CRITICAL: Every code change MUST include corresponding test updates** when tests exist:
-  - **New features**: Add comprehensive test cases covering happy paths and edge cases.
-  - **Modified behavior**: Update existing tests to reflect new implementation.
-  - **Removed features**: Remove or update tests for deprecated/removed functionality.
-  - **Bug fixes**: Add regression tests to prevent future occurrences.
+- Add suites under `tests/`, mirroring source structure; name files `*.test.ts`. Note: `test:run` currently only picks up `tests/lib/*.test.{js,ts}` — extend its glob in `package.json` when adding suites elsewhere, or they will silently never run.
+- Test behavior, not implementation; clear scenario-describing names; one assertion per test when possible; deterministic; mock network calls through provided hooks or context; use existing test utilities.
+- **Every code change must include corresponding test updates**: new features get happy-path and edge-case coverage; modified behavior gets updated tests; removed features get their tests removed; bug fixes get regression tests.
 - Run `pnpm test:run` before submitting any changes.
 
----
+## Workflow
+
+- Break complex work into 3–5 stages and implement incrementally so every commit compiles and passes tests. Prefer test-first for behavior changes (red → green → refactor).
+- Document a plan in `IMPLEMENTATION_PLAN.md` **only when explicitly requested** (see Documentation Restriction); if used, give each stage a Goal, Success Criteria, Tests, and Status, keep status current, and delete the file when done.
+- **Stop after 3 failed attempts** at the same problem. Then: document what failed and why, research 2–3 alternative implementations, question whether the abstraction or problem split is right, and try a different angle.
 
 ## Commit & Pull Request Guidelines
 
-- Follow conventional, action-oriented commit subjects (e.g. `feat: add bucket selector`, `fix: correct object list pagination`).
-- Each pull request should include: a concise summary, linked issue or task, screenshots for UI work, and testing notes.
-- Keep PRs scoped; large refactors should be coordinated in advance.
-- Commit message and PR title must be in English.
-- When a PR template exists (e.g. `.github/pull_request_template.md`), follow it strictly.
+- Conventional, action-oriented commit subjects (`feat: add bucket selector`, `fix: correct object list pagination`); message body explains _why_. Commit messages and PR titles in English.
+- Each PR includes: concise summary, linked issue or task, screenshots for UI work, and testing notes. Follow `.github/pull_request_template.md` strictly.
+- **Screenshot diffs**: whenever a PR touches anything user-visible, provide before/after page screenshots in the PR description (run the app locally, capture affected pages before and after, present as a before/after pair). If "before" is impractical (e.g. a brand-new page), include "after" screenshots of every affected state — empty, loaded, error, and mobile when relevant.
+- Keep PRs scoped; coordinate large refactors in advance.
 
----
+## Multi-Role Adversarial Verification
 
-## UI Theme Overrides
+For every non-trivial change, verify from multiple independent roles before considering it done — each role actively tries to find problems rather than confirm success:
 
-- For every Console UI, interaction, settings, form, dialog, table, responsive-layout, or visual-review change, read and follow `skills/rustfs-console-design-guide/SKILL.md` before editing. Use `skills/ui-audit/SKILL.md` as the audit workflow and the Console design guide as the source of design decisions.
-- Apply visual tweaks (e.g. removing shadows, altering colors) at usage sites via classes such as `class="shadow-none"`.
-- When extending shadcn components, create wrapper components (e.g. `BucketSelector.tsx`) instead of forking primitives.
+- **Reviewer**: challenge correctness — edge cases, error handling, state/race issues, regressions in adjacent features.
+- **Tester**: try to break it — run type check, lint, tests; exercise affected pages/flows including empty, error, and loading states.
+- **UX auditor** (UI changes): check against `skills/rustfs-console-design-guide/SKILL.md` — layout, spacing, dark mode, responsiveness, i18n text.
+- **Simplifier**: ask whether the same result could be achieved with less code; remove anything not strictly needed.
+
+Scale rigor to the change: a one-line fix needs a quick reviewer + tester pass; a new feature or refactor deserves the full panel. When agent tooling supports it (subagents/workflows), run these roles as independent adversarial checks rather than a single self-review.
+
+## UI Design & Theme
+
+- **Consistent style, best-practice interactions**: all UI shares one unified visual language — reuse existing components, spacing, typography, and color tokens instead of inventing variants; the same kind of element must look and behave the same everywhere. Follow established UX practices: clear loading/empty/error states, immediate feedback via `@/lib/feedback/*`, sensible focus and keyboard behavior, and confirmation before destructive actions.
+- For every Console UI, interaction, settings, form, dialog, table, responsive-layout, or visual-review change, read and follow `skills/rustfs-console-design-guide/SKILL.md` before editing. Use `skills/ui-audit/SKILL.md` as the audit workflow; the design guide is the source of design decisions.
+- Apply visual tweaks at usage sites via classes (e.g. `className="shadow-none"`).
 - Do not change base colors or theme variables defined in `console-new` unless explicitly required by the migration plan.
-
----
-
-# Development Guidelines
-
-## Philosophy
-
-### Core Beliefs
-
-- **Incremental progress over big bangs** – Small changes that compile and pass tests.
-- **Learning from existing code** – Study and plan before implementing.
-- **Pragmatic over dogmatic** – Adapt to project reality.
-- **Clear intent over clever code** – Be boring and obvious.
-
-### Simplicity Means
-
-- Single responsibility per function/class.
-- Avoid premature abstractions.
-- No clever tricks – choose the boring solution.
-- If you need to explain it, it’s too complex.
-
----
-
-## Process
-
-### 1. Planning & Staging
-
-Break complex work into 3–5 stages. Document in `IMPLEMENTATION_PLAN.md` **only when explicitly requested** (see Documentation Restriction):
-
-```markdown
-## Stage N: [Name]
-
-**Goal**: [Specific deliverable]
-**Success Criteria**: [Testable outcomes]
-**Tests**: [Specific test cases]
-**Status**: [Not Started|In Progress|Complete]
-```
-
-- Update status as you progress.
-- Remove the file when all stages are done.
-
-### 2. Implementation Flow
-
-1. **Understand** – Study existing patterns in the codebase.
-2. **Test** – Write tests first (red).
-3. **Implement** – Minimal code to pass (green).
-4. **Refactor** – Clean up with tests passing.
-5. **Commit** – With a clear message linking to the plan.
-
-### 3. When Stuck (After 3 Attempts)
-
-**CRITICAL**: Maximum 3 attempts per issue, then STOP.
-
-1. **Document what failed**:
-   - What you tried.
-   - Specific error messages.
-   - Why you think it failed.
-
-2. **Research alternatives**:
-   - Find 2–3 similar implementations.
-   - Note different approaches used.
-
-3. **Question fundamentals**:
-   - Is this the right abstraction level?
-   - Can this be split into smaller problems?
-   - Is there a simpler approach entirely?
-
-4. **Try a different angle**:
-   - Different library/framework feature?
-   - Different architectural pattern?
-   - Remove abstraction instead of adding?
-
----
-
-## Technical Standards
-
-### Architecture Principles
-
-- **Composition over inheritance** – Use dependency injection.
-- **Interfaces over singletons** – Enable testing and flexibility.
-- **Explicit over implicit** – Clear data flow and dependencies.
-- **Test-driven when possible** – Never disable tests; fix them.
-
-### Code Quality
-
-- **Every commit must**:
-  - Compile successfully.
-  - Pass all existing tests.
-  - Include tests for new functionality (when tests exist).
-  - Follow project formatting/linting.
-
-- **Before committing**:
-  - Run formatters/linters.
-  - Self-review changes.
-  - Ensure commit message explains "why".
-
-### Error Handling
-
-- Fail fast with descriptive messages.
-- Include context for debugging.
-- Handle errors at the appropriate level.
-- Never silently swallow exceptions.
-
----
-
-## Decision Framework
-
-When multiple valid approaches exist, choose based on:
-
-1. **Testability** – Can I easily test this?
-2. **Readability** – Will someone understand this in 6 months?
-3. **Consistency** – Does this match project patterns?
-4. **Simplicity** – Is this the simplest solution that works?
-5. **Reversibility** – How hard is it to change later?
-
----
-
-## Project Integration
-
-### Learning the Codebase
-
-- Find 3 similar features/components.
-- Identify common patterns and conventions.
-- Use the same libraries/utilities when possible.
-- Follow existing test patterns.
-
-### Tooling
-
-- Use the project’s existing build system.
-- Use the project’s test framework.
-- Use the project’s formatter/linter settings.
-- Don’t introduce new tools without strong justification.
-
----
-
-## Quality Gates
-
-### Definition of Done
-
-- [ ] Tests written and passing (when applicable).
-- [ ] Code follows project conventions.
-- [ ] No linter/formatter warnings.
-- [ ] Commit messages are clear.
-- [ ] Implementation matches plan.
-- [ ] No TODOs without issue numbers.
-
-### Test Guidelines
-
-- Test behavior, not implementation.
-- One assertion per test when possible.
-- Clear test names describing the scenario.
-- Use existing test utilities/helpers.
-- Tests should be deterministic.
-
----
+- During migration: do not modify page text, add UI components, or change component positions without plan approval.
 
 ## Documentation Restriction
 
-**Unless explicitly requested**, do not produce any summary-type, plan-type, analysis-type, or similar documentation in the project. This includes but is not limited to:
-
-- `IMPLEMENTATION_PLAN.md`, `SUMMARY.md`, `PLAN.md`, `CHANGELOG.md`
-- Migration summaries, progress reports, or task completion reports
-- **Analysis documents** (e.g. refactor analysis, page/code analysis, architecture analysis, `*_ANALYSIS*.md`)
-- Any document created proactively to describe or track work
-
-Create such documents only when the user explicitly asks for them.
-
----
-
-## Important Reminders
-
-**NEVER**:
-
-- Use `--no-verify` to bypass commit hooks.
-- Disable tests instead of fixing them.
-- Commit code that doesn’t compile.
-- Make assumptions – verify with existing code.
-- During migration: modify page text, add UI components, or change component positions without plan approval.
-
-**ALWAYS**:
-
-- Commit working code incrementally.
-- Update plan documentation as you go.
-- Learn from existing implementations if exists (especially `console-old`).
-- Stop after 3 failed attempts and reassess.
+**Unless explicitly requested**, do not create summary, plan, analysis, or report documents in the project — including `IMPLEMENTATION_PLAN.md`, `SUMMARY.md`, `PLAN.md`, `CHANGELOG.md`, migration summaries, progress reports, and `*_ANALYSIS*.md`. Create them only when the user explicitly asks.
 
 <!-- BEGIN:nextjs-agent-rules -->
 

skills/rustfs-console-design-guide/SKILL.md

@@ -5,6 +5,8 @@ description: Design and review RustFS Console interfaces with a consistent visua
 
 # RustFS Console Design Guide
 
+This guide is the source of design decisions; use `skills/ui-audit/SKILL.md` as the companion workflow for audit execution, browser validation, and evidence capture.
+
 Use this guide while shaping the interface, before implementation details harden. Treat Console as an operational tool: the design should help people understand system state, make a deliberate change, and recover when reality is uncertain.
 
 ## Design objectives
@@ -179,7 +181,7 @@ For broad UI work, inspect the whole task flow before polishing individual compo
 5. Implement the smallest coherent design change.
 6. Recapture the exact state and compare it with the original.
 
-Record each concrete finding in `docs/ui-review/register.md` and map screenshots in the Console UI review manifest. Label static fixtures as illustrative evidence; do not present them as runtime proof.
+Record each concrete finding in `docs/ui-review/register.md` and map screenshots in the Console UI review manifest. Label static fixtures as illustrative evidence; do not present them as runtime proof. The before/after captures from steps 1 and 6 double as the screenshot diff required in the PR description (see AGENTS.md).
 
 ## 10. Common failure patterns
 

skills/ui-audit/SKILL.md

@@ -97,7 +97,7 @@ Keep each patch small and tied to one audit issue.
 
 ## Browser Validation
 
-Use the preferred local browser automation surface when available for local targets. Validate after meaningful UI edits:
+Use the available browser automation tools (in-app Browser pane, Chrome MCP, or Playwright — whichever the session provides) against the local dev server. Validate after meaningful UI edits:
 
 1. Page identity: URL and title match the target.
 2. Not blank: DOM snapshot or screenshot contains meaningful content.
@@ -117,17 +117,18 @@ Save screenshots outside the repo, usually under `/tmp`, and include them in the
 
 ## Quality Gates
 
-Run the narrow checks for touched files first, then broader checks using the project's package manager:
+Run the narrow checks for touched files first, then the project's mandated checks. In this repository (run `nvm use v22` first):
 
 ```bash
 pnpm prettier --check <touched files>
 pnpm type-check
 pnpm lint
+pnpm test:run
 git diff --check
-pnpm exec prettier --check $(rg --files -g '*.{ts,tsx,js,jsx,json,css,md,yml,yaml}' -g '!node_modules' -g '!pnpm-lock.yaml')
+pnpm format:check
 ```
 
-Adapt command names to the repo: `npm`, `yarn`, `bun`, `cargo`, `swift`, or platform-specific test/build commands when appropriate.
+In other repositories, adapt command names to the local stack: `npm`, `yarn`, `bun`, `cargo`, `swift`, or platform-specific test/build commands.
 
 Also run project-mandated commands when present. If a mandated command fails because the repository is already misconfigured, report the exact blocker and continue validating what can be validated.
 
@@ -138,5 +139,5 @@ Respond in the user's language. Keep it concise:
 - Summarize main UI fixes by category.
 - List validation commands and pass/fail status.
 - Call out known blockers separately.
-- Include before/after or current-state screenshots using absolute local paths.
+- Include before/after or current-state screenshots using absolute local paths; reuse these captures as the PR screenshot diff required by AGENTS.md.
 - Mention untested areas only when they materially affect confidence.