@ranimontagna/agent-toolkit 0.1.6 → 0.1.7

package/skills/backend/java/java-coding-standards/SKILL.md

@@ -0,0 +1,383 @@
+---
+name: java-coding-standards
+description: "Use when writing or reviewing Java 17+ code in Spring Boot or Quarkus services, including naming, immutability, Optional usage, streams, exceptions, generics, CDI, reactive patterns, and project layout."
+origin: ECC
+---
+
+# Java Coding Standards
+
+Standards for readable, maintainable Java (17+) code in Spring Boot and Quarkus services.
+
+## When to Use
+
+- Writing or reviewing Java code in Spring Boot or Quarkus projects
+- Enforcing naming, immutability, or exception handling conventions
+- Working with records, sealed classes, or pattern matching (Java 17+)
+- Reviewing use of Optional, streams, or generics
+- Structuring packages and project layout
+- **[QUARKUS]**: Working with CDI scopes, Panache entities, or reactive pipelines
+
+## How It Works
+
+### Framework Detection
+
+Before applying standards, determine the framework from the build file:
+
+- Build file contains `quarkus` → apply **[QUARKUS]** conventions
+- Build file contains `spring-boot` → apply **[SPRING]** conventions
+- Neither detected → apply shared conventions only
+
+## Core Principles
+
+- Prefer clarity over cleverness
+- Immutable by default; minimize shared mutable state
+- Fail fast with meaningful exceptions
+- Consistent naming and package structure
+- **[QUARKUS]**: Favor build-time over runtime processing; avoid runtime reflection where possible
+
+## Examples
+
+The sections below show concrete Spring Boot, Quarkus, and shared Java examples
+for naming, immutability, dependency injection, reactive code, exceptions,
+project layout, logging, configuration, and tests.
+
+## Naming
+
+```java
+// PASS: Classes/Records: PascalCase
+public class MarketService {}
+public record Money(BigDecimal amount, Currency currency) {}
+
+// PASS: Methods/fields: camelCase
+private final MarketRepository marketRepository;
+public Market findBySlug(String slug) {}
+
+// PASS: Constants: UPPER_SNAKE_CASE
+private static final int MAX_PAGE_SIZE = 100;
+
+// PASS: [QUARKUS] JAX-RS resources named as *Resource, not *Controller
+public class MarketResource {}
+
+// PASS: [SPRING] REST controllers named as *Controller
+public class MarketController {}
+```
+
+## Immutability
+
+```java
+// PASS: Favor records and final fields
+public record MarketDto(Long id, String name, MarketStatus status) {}
+
+public class Market {
+  private final Long id;
+  private final String name;
+  // getters only, no setters
+}
+
+// PASS: [QUARKUS] Panache active-record entities use public fields (Quarkus convention)
+@Entity
+public class Market extends PanacheEntity {
+  public String name;
+  public MarketStatus status;
+  // Panache generates accessors at build time; public fields are idiomatic here
+}
+
+// PASS: [QUARKUS] Panache MongoDB entities
+@MongoEntity(collection = "markets")
+public class Market extends PanacheMongoEntity {
+  public String name;
+  public MarketStatus status;
+}
+```
+
+## Optional Usage
+
+```java
+// PASS: Return Optional from find* methods
+// [SPRING]
+Optional<Market> market = marketRepository.findBySlug(slug);
+
+// [QUARKUS] Panache
+Optional<Market> market = Market.find("slug", slug).firstResultOptional();
+
+// PASS: Map/flatMap instead of get()
+return market
+    .map(MarketResponse::from)
+    .orElseThrow(() -> new EntityNotFoundException("Market not found"));
+```
+
+## Streams Best Practices
+
+```java
+// PASS: Use streams for transformations, keep pipelines short
+List<String> names = markets.stream()
+    .map(Market::name)
+    .filter(Objects::nonNull)
+    .toList();
+
+// FAIL: Avoid complex nested streams; prefer loops for clarity
+```
+
+## Dependency Injection
+
+```java
+// PASS: [SPRING] Constructor injection (preferred over @Autowired on fields)
+@Service
+public class MarketService {
+  private final MarketRepository marketRepository;
+
+  public MarketService(MarketRepository marketRepository) {
+    this.marketRepository = marketRepository;
+  }
+}
+
+// PASS: [QUARKUS] Constructor injection
+@ApplicationScoped
+public class MarketService {
+  private final MarketRepository marketRepository;
+
+  @Inject
+  public MarketService(MarketRepository marketRepository) {
+    this.marketRepository = marketRepository;
+  }
+}
+
+// PASS: [QUARKUS] Package-private field injection (acceptable in Quarkus — avoids proxy issues)
+@ApplicationScoped
+public class MarketService {
+  @Inject
+  MarketRepository marketRepository;
+}
+
+// FAIL: [SPRING] Field injection with @Autowired
+@Autowired
+private MarketRepository marketRepository; // use constructor injection
+
+// FAIL: [QUARKUS] @Singleton when interception or lazy init is needed
+@Singleton // non-proxyable — use @ApplicationScoped instead
+public class MarketService {}
+```
+
+## Reactive Patterns [QUARKUS]
+
+```java
+// PASS: Return Uni/Multi from reactive endpoints
+@GET
+@Path("/{slug}")
+public Uni<Market> findBySlug(@PathParam("slug") String slug) {
+  return Market.find("slug", slug)
+      .<Market>firstResult()
+      .onItem().ifNull().failWith(() -> new MarketNotFoundException(slug));
+}
+
+// PASS: Non-blocking pipeline composition
+public Uni<OrderConfirmation> placeOrder(OrderRequest req) {
+  return validateOrder(req)
+      .chain(valid -> persistOrder(valid))
+      .chain(order -> notifyFulfillment(order));
+}
+
+// FAIL: Blocking call inside a Uni/Multi pipeline
+public Uni<Market> find(String slug) {
+  Market m = Market.find("slug", slug).firstResult(); // BLOCKING — breaks event loop
+  return Uni.createFrom().item(m);
+}
+
+// FAIL: Subscribing more than once to a shared Uni
+Uni<Market> shared = fetchMarket(slug);
+shared.subscribe().with(m -> log(m));
+shared.subscribe().with(m -> cache(m)); // double subscribe — use Uni.memoize()
+```
+
+## Exceptions
+
+- Use unchecked exceptions for domain errors; wrap technical exceptions with context
+- Create domain-specific exceptions (e.g., `MarketNotFoundException`)
+- Avoid broad `catch (Exception ex)` unless rethrowing/logging centrally
+
+```java
+throw new MarketNotFoundException(slug);
+```
+
+### Centralised Exception Handling
+
+```java
+// [SPRING]
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+  @ExceptionHandler(MarketNotFoundException.class)
+  public ResponseEntity<ErrorResponse> handle(MarketNotFoundException ex) {
+    return ResponseEntity.status(404).body(ErrorResponse.from(ex));
+  }
+}
+
+// [QUARKUS] Option A: ExceptionMapper
+@Provider
+public class MarketNotFoundMapper implements ExceptionMapper<MarketNotFoundException> {
+  @Override
+  public Response toResponse(MarketNotFoundException ex) {
+    return Response.status(404).entity(ErrorResponse.from(ex)).build();
+  }
+}
+
+// [QUARKUS] Option B: @ServerExceptionMapper (RESTEasy Reactive)
+@ServerExceptionMapper
+public RestResponse<ErrorResponse> handle(MarketNotFoundException ex) {
+  return RestResponse.status(Status.NOT_FOUND, ErrorResponse.from(ex));
+}
+```
+
+## Generics and Type Safety
+
+- Avoid raw types; declare generic parameters
+- Prefer bounded generics for reusable utilities
+
+```java
+public <T extends Identifiable> Map<Long, T> indexById(Collection<T> items) { ... }
+```
+
+## Project Structure
+
+### [SPRING] Maven/Gradle
+
+```
+src/main/java/com/example/app/
+  config/
+  controller/
+  service/
+  repository/
+  domain/
+  dto/
+  util/
+src/main/resources/
+  application.yml
+src/test/java/... (mirrors main)
+```
+
+### [QUARKUS] Maven/Gradle
+
+```
+src/main/java/com/example/app/
+  config/              # @ConfigMapping, @ConfigProperty beans, Producers
+  resource/            # JAX-RS resources (not "controller")
+  service/
+  repository/          # PanacheRepository implementations (if not using active record)
+  domain/              # JPA/Panache entities, MongoDB entities
+  dto/
+  util/
+  mapper/              # MapStruct mappers (if used)
+src/main/resources/
+  application.properties   # Quarkus convention (YAML supported with quarkus-config-yaml)
+  import.sql               # Hibernate auto-import for dev/test
+src/test/java/... (mirrors main)
+```
+
+## Formatting and Style
+
+- Use 2 or 4 spaces consistently (project standard)
+- One public top-level type per file
+- Keep methods short and focused; extract helpers
+- Order members: constants, fields, constructors, public methods, protected, private
+
+## Code Smells to Avoid
+
+- Long parameter lists → use DTO/builders
+- Deep nesting → early returns
+- Magic numbers → named constants
+- Static mutable state → prefer dependency injection
+- Silent catch blocks → log and act or rethrow
+- **[QUARKUS]**: `@Singleton` where `@ApplicationScoped` is intended — breaks proxying and interception
+- **[QUARKUS]**: Mixing `quarkus-resteasy-reactive` and `quarkus-resteasy` (classic) — pick one stack
+- **[QUARKUS]**: Panache active-record + repository pattern in the same bounded context — pick one
+
+## Logging
+
+```java
+// [SPRING] SLF4J
+private static final Logger log = LoggerFactory.getLogger(MarketService.class);
+log.info("fetch_market slug={}", slug);
+log.error("failed_fetch_market slug={}", slug, ex);
+
+// [QUARKUS] JBoss Logging (default, zero-cost at build time)
+private static final Logger log = Logger.getLogger(MarketService.class);
+log.infof("fetch_market slug=%s", slug);
+log.errorf(ex, "failed_fetch_market slug=%s", slug);
+
+// [QUARKUS] Alternative: simplified logging with @Inject
+@Inject
+Logger log; // CDI-injected, scoped to declaring class
+```
+
+## Null Handling
+
+- Accept `@Nullable` only when unavoidable; otherwise use `@NonNull`
+- Use Bean Validation (`@NotNull`, `@NotBlank`) on inputs
+- **[QUARKUS]**: Apply `@Valid` on `@BeanParam`, `@RestForm`, and request body parameters
+
+## Configuration
+
+```java
+// [SPRING] @ConfigurationProperties
+@ConfigurationProperties(prefix = "market")
+public record MarketProperties(int maxPageSize, Duration cacheTtl) {}
+
+// [QUARKUS] @ConfigMapping (type-safe, build-time validated)
+@ConfigMapping(prefix = "market")
+public interface MarketConfig {
+  int maxPageSize();
+  Duration cacheTtl();
+}
+
+// [QUARKUS] Simple values with @ConfigProperty
+@ConfigProperty(name = "market.max-page-size", defaultValue = "100")
+int maxPageSize;
+```
+
+## Testing Expectations
+
+### Shared
+- JUnit 5 + AssertJ for fluent assertions
+- Mockito for mocking; avoid partial mocks where possible
+- Favor deterministic tests; no hidden sleeps
+
+### [SPRING]
+- `@WebMvcTest` for controller slices, `@DataJpaTest` for repository slices
+- `@SpringBootTest` reserved for full integration tests
+- `@MockBean` for replacing beans in Spring context
+
+### [QUARKUS]
+- Plain JUnit 5 + Mockito for unit tests (no `@QuarkusTest`)
+- `@QuarkusTest` reserved for CDI integration tests
+- `@InjectMock` for replacing CDI beans in integration tests
+- Dev Services for database/Kafka/Redis — avoid manual Testcontainers setup when Dev Services suffice
+- `@QuarkusTestResource` for custom external service lifecycle
+
+```java
+// [SPRING] Controller test
+@WebMvcTest(MarketController.class)
+class MarketControllerTest {
+  @Autowired MockMvc mockMvc;
+  @MockBean MarketService marketService;
+}
+
+// [QUARKUS] Integration test
+@QuarkusTest
+class MarketResourceTest {
+  @InjectMock
+  MarketService marketService;
+
+  @Test
+  void should_return_404_when_market_not_found() {
+    given().when().get("/markets/unknown").then().statusCode(404);
+  }
+}
+
+// [QUARKUS] Unit test (no CDI, no @QuarkusTest)
+@ExtendWith(MockitoExtension.class)
+class MarketServiceTest {
+  @Mock MarketRepository marketRepository;
+  @InjectMocks MarketService marketService;
+}
+```
+
+**Remember**: Keep code intentional, typed, and observable. Optimize for maintainability over micro-optimizations unless proven necessary.

package/skills/backend/java/java-junit/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright GitHub, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/backend/java/java-junit/NOTICE.md

@@ -0,0 +1,10 @@
+# Third-party notice
+
+This skill was copied from GitHub's awesome-copilot repository.
+
+- Source: https://github.com/github/awesome-copilot/tree/main/skills/java-junit
+- Source commit: 776d84143238cb91f7242665f188887b9e8d2aa9
+- License: MIT
+- Copyright: Copyright GitHub, Inc.
+
+The upstream MIT license is included in `LICENSE`.

package/skills/backend/java/java-junit/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: java-junit
+description: Use when writing or improving JUnit 5 unit tests, including parameterized and data-driven tests.
+origin: awesome-copilot
+---
+
+# JUnit 5+ Best Practices
+
+Your goal is to help me write effective unit tests with JUnit 5, covering both standard and data-driven testing approaches.
+
+## Project Setup
+
+- Use a standard Maven or Gradle project structure.
+- Place test source code in `src/test/java`.
+- Include dependencies for `junit-jupiter-api`, `junit-jupiter-engine`, and `junit-jupiter-params` for parameterized tests.
+- Use build tool commands to run tests: `mvn test` or `gradle test`.
+
+## Test Structure
+
+- Test classes should have a `Test` suffix, e.g., `CalculatorTest` for a `Calculator` class.
+- Use `@Test` for test methods.
+- Follow the Arrange-Act-Assert (AAA) pattern.
+- Name tests using a descriptive convention, like `methodName_should_expectedBehavior_when_scenario`.
+- Use `@BeforeEach` and `@AfterEach` for per-test setup and teardown.
+- Use `@BeforeAll` and `@AfterAll` for per-class setup and teardown (must be static methods).
+- Use `@DisplayName` to provide a human-readable name for test classes and methods.
+
+## Standard Tests
+
+- Keep tests focused on a single behavior.
+- Avoid testing multiple conditions in one test method.
+- Make tests independent and idempotent (can run in any order).
+- Avoid test interdependencies.
+
+## Data-Driven (Parameterized) Tests
+
+- Use `@ParameterizedTest` to mark a method as a parameterized test.
+- Use `@ValueSource` for simple literal values (strings, ints, etc.).
+- Use `@MethodSource` to refer to a factory method that provides test arguments as a `Stream`, `Collection`, etc.
+- Use `@CsvSource` for inline comma-separated values.
+- Use `@CsvFileSource` to use a CSV file from the classpath.
+- Use `@EnumSource` to use enum constants.
+
+## Assertions
+
+- Use the static methods from `org.junit.jupiter.api.Assertions` (e.g., `assertEquals`, `assertTrue`, `assertNotNull`).
+- For more fluent and readable assertions, consider using a library like AssertJ (`assertThat(...).is...`).
+- Use `assertThrows` or `assertDoesNotThrow` to test for exceptions.
+- Group related assertions with `assertAll` to ensure all assertions are checked before the test fails.
+- Use descriptive messages in assertions to provide clarity on failure.
+
+## Mocking and Isolation
+
+- Use a mocking framework like Mockito to create mock objects for dependencies.
+- Use `@Mock` and `@InjectMocks` annotations from Mockito to simplify mock creation and injection.
+- Use interfaces to facilitate mocking.
+
+## Test Organization
+
+- Group tests by feature or component using packages.
+- Use `@Tag` to categorize tests (e.g., `@Tag("fast")`, `@Tag("integration")`).
+- Use `@TestMethodOrder(MethodOrderer.OrderAnnotation.class)` and `@Order` to control test execution order when strictly necessary.
+- Use `@Disabled` to temporarily skip a test method or class, providing a reason.
+- Use `@Nested` to group tests in a nested inner class for better organization and structure.

package/skills/frontend/react/react-patterns/SKILL.md

@@ -52,7 +52,7 @@ React has no inheritance model for components. Compose with `children`, render p
 
 ## Hooks Discipline
 
-See [rules/react/hooks.md](../../rules/react/hooks.md) for the full ruleset. Highlights:
+See [rules/react/hooks.md](rules/react/hooks.md) for the full ruleset. Highlights:
 
 - Top-level only, never conditional
 - Cleanup every subscription, interval, listener
@@ -250,7 +250,7 @@ Wrap a component in `React.memo` only when:
 - Form inputs need labels — `<label htmlFor>` or `aria-label` if visually labeled by an icon
 - Manage focus on route changes and modal open/close
 - Run `axe` in component tests (see [skills/react-testing](../react-testing/SKILL.md))
-- Cross-link: [skills/accessibility/SKILL.md](../accessibility/SKILL.md) covers WCAG criteria and pattern libraries
+- Cross-link: skills/accessibility covers WCAG criteria and pattern libraries when that optional skill is installed
 
 ## Routing
 
@@ -264,8 +264,8 @@ This skill is router-agnostic. The patterns above work with React Router, TanSta
 
 ## Related
 
-- Rules: [rules/react/](../../rules/react/) — coding-style, hooks, patterns, security, testing
-- Skills: [react-performance](../react-performance/SKILL.md) for the Vercel-derived performance ruleset, [frontend-patterns](../frontend-patterns/SKILL.md) for cross-framework UI concerns, [accessibility](../accessibility/SKILL.md), [angular-developer](../angular-developer/SKILL.md) for framework comparison
+- Rules: [rules/react/](rules/react/) — coding-style, hooks, patterns, security, testing
+- Skills: [react-performance](../react-performance/SKILL.md) for the Vercel-derived performance ruleset; frontend-patterns for cross-framework UI concerns; accessibility; angular-developer for framework comparison
 - Agents: `react-reviewer` for code review, `react-build-resolver` for build/bundler errors
 - Commands: `/react-review`, `/react-build`, `/react-test`
 

package/skills/frontend/react/react-patterns/rules/react/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Affaan Mustafa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/frontend/react/react-patterns/rules/react/NOTICE.md

@@ -0,0 +1,11 @@
+# Third-party notice
+
+This directory contains React rule references copied from Affaan Mustafa's ECC
+repository.
+
+- Source: https://github.com/affaan-m/ECC/tree/main/rules/react
+- Source commit: 0f84c0e2796703fbda87d577b2636351418c7442
+- License: MIT
+- Copyright: Copyright (c) 2026 Affaan Mustafa
+
+The upstream MIT license is included in `LICENSE`.

package/skills/frontend/react/react-patterns/rules/react/coding-style.md

@@ -0,0 +1,109 @@
+---
+paths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/components/**/*.ts"
+  - "**/components/**/*.js"
+  - "**/hooks/**/*.ts"
+  - "**/hooks/**/*.js"
+---
+# React Coding Style
+
+> This file extends the upstream `typescript/coding-style.md` and `common/coding-style.md` rules with React specific content.
+
+## File Extensions
+
+- `.tsx` for any file containing JSX, even one-liner snippets
+- `.ts` for pure logic, custom hooks without JSX, type definitions, utilities
+- `.test.tsx` / `.test.ts` mirroring the source file
+- Use `.jsx` only when the project intentionally avoids TypeScript — flag every new untyped React file in review
+
+## Naming
+
+- Components: `PascalCase` for both the symbol and the file (`UserCard.tsx`, default export `UserCard`)
+- Custom hooks: `useCamelCase` for the symbol, kebab-case for the file when the project convention is kebab-case (`use-debounce.ts` exports `useDebounce`)
+- Context: `<Domain>Context` symbol, `<Domain>Provider` provider component, `use<Domain>` consumer hook
+- Event handlers: `handleClick`, `handleSubmit` inside the component; the prop that receives it is `onClick`, `onSubmit`
+- Boolean props: `isLoading`, `hasError`, `canSubmit` — never `loading` or `error` alone for booleans
+
+## Component Shape
+
+```tsx
+type Props = {
+  user: User;
+  onSelect: (id: string) => void;
+};
+
+export function UserCard({ user, onSelect }: Props) {
+  return (
+    <button type="button" onClick={() => onSelect(user.id)}>
+      {user.name}
+    </button>
+  );
+}
+```
+
+- Prefer `type Props = {}` for closed component prop shapes
+- Use `interface` only when the prop type is extended via declaration merging or exported as a public API extension point
+- Always destructure props in the parameter list — no `props.user` access inside the body
+- Type the return implicitly through JSX (`function Foo(): JSX.Element` only when the function returns conditionally and the union confuses inference)
+
+## JSX
+
+- Self-close tags with no children: `<img />`, `<UserCard user={u} />`
+- Use fragments `<>...</>` over wrapper `<div>` when no DOM element is needed
+- Conditional rendering: `{condition && <Foo />}` for booleans, ternary for either/or, early return for guard clauses
+- Never put logic inline in JSX when it reads as multi-line — extract to a const above the return or a function
+
+```tsx
+// Prefer
+const greeting = user.isAdmin ? "Welcome, admin" : `Hello ${user.name}`;
+return <h1>{greeting}</h1>;
+
+// Over
+return <h1>{user.isAdmin ? "Welcome, admin" : `Hello ${user.name}`}</h1>;
+```
+
+## Server / Client Boundary (Next.js App Router, RSC)
+
+- Default a new file to Server Component — only add `"use client"` when the file uses state, effects, refs, browser APIs, or event handlers
+- Place the `"use client"` directive on line 1, before any imports
+- Never import a Client Component file from inside a `"use server"` action file
+- Never re-export server-only code through a client module — the bundler will silently include it
+
+## Imports
+
+- React imports first: `import { useState } from "react"`
+- Then third-party libs, then absolute project imports, then relative
+- Type-only imports: `import type { ReactNode } from "react"` — never mix runtime and type imports in one statement when ESLint's `consistent-type-imports` is configured
+
+## Hooks Discipline
+
+See [hooks.md](./hooks.md) for the full ruleset. Style highlights:
+
+- Custom hooks must start with `use` — enforced by `eslint-plugin-react-hooks`
+- Group all hook calls at the top of the component, before any conditional logic
+- Avoid creating ad-hoc hooks for one-line wrappers — inline the call instead
+
+## State
+
+- Local first (`useState`), lift only when shared
+- Context for cross-cutting state read by many components (theme, auth, i18n) — not for high-frequency updates
+- External store (Zustand, Jotai, Redux Toolkit) when state must persist across route changes, sync across tabs, or be debugged via devtools
+- Never duplicate state that can be derived — compute during render
+
+## Class Components
+
+Forbidden in new code. Convert legacy class components to function components when touching them for non-trivial changes.
+
+## File Layout per Component
+
+```
+components/UserCard/
+  UserCard.tsx
+  UserCard.module.css   # or styled-components, or Tailwind classes inline
+  UserCard.test.tsx
+  index.ts              # re-export only
+```
+
+Inline single-file components are fine for trivial presentational pieces.