refactor: migrate agent configurations and skills to the .agent directory and add project documentation
This commit is contained in:
@@ -0,0 +1,38 @@
|
||||
---
|
||||
name: blazor-hybrid-bridge
|
||||
description: Standards for cross-platform compatibility (Web & MAUI Hybrid)
|
||||
---
|
||||
# Cross-Platform Integration
|
||||
|
||||
- **Abstraction Layer:**
|
||||
- Define all platform-specific logic in `NexusReader.Application/Abstractions/Services`.
|
||||
- Use `IPlatformService` for device hardware (Haptics, Orientation).
|
||||
- Use `INativeStorageService` for persistent key-value storage.
|
||||
|
||||
- **Implementation Strategy:**
|
||||
- **MAUI**: Implement in `NexusReader.Infrastructure.Mobile` using `Microsoft.Maui.*` APIs.
|
||||
- **Web**: Implement in `NexusReader.Web.Client` using `IJSRuntime` to access Browser APIs (e.g., `navigator.vibrate`, `localStorage`).
|
||||
|
||||
- **UI Compatibility:**
|
||||
- **Notch Support**: Use `env(safe-area-inset-top)` and other safe-area variables in CSS to prevent content from being hidden by hardware notches or home indicators.
|
||||
- **Touch Optimization**:
|
||||
- Use `user-select: none` for non-text interactive elements.
|
||||
- Ensure touch targets are at least `44x44px`.
|
||||
- Handle `active` states for immediate feedback on mobile.
|
||||
|
||||
- **Platform Detection:**
|
||||
- Use `IPlatformService.GetDeviceContext()` to determine `DeviceType` (Phone, Tablet, Desktop).
|
||||
- Adapt UI layout dynamically based on the context (e.g., sidebars on Tablet/Desktop, bottom navigation on Phone).
|
||||
|
||||
- **Real-time & Events (SignalR / UI):**
|
||||
- **Debouncing**: Implement trailing-edge debouncing using `CancellationTokenSource` and `Task.Delay` for high-frequency UI events (like scrolling). Do not just drop events inside a time window, as the final state might be lost.
|
||||
- **Dependency Isolation**: Blazor WebAssembly (`Web.Client`) cannot reference projects that require `Microsoft.AspNetCore.App` (like SignalR Hubs). Keep SignalR abstractions in `UI.Shared` and the Hub implementation strictly on the server (`Infrastructure` or `Web.New`).
|
||||
|
||||
- **Dependency Injection:**
|
||||
- Register implementations in `MauiProgram.cs` for mobile and `Program.cs` for web.
|
||||
- Components in `NexusReader.UI.Shared` must only depend on the interfaces.
|
||||
|
||||
- **JS Interop Standards:**
|
||||
- Keep JS Interop calls isolated within service implementations.
|
||||
- Use `IJSObjectReference` for module-based scripts to avoid global namespace pollution.
|
||||
- Always provide a fallback or graceful failure for browsers that don't support specific APIs.
|
||||
@@ -0,0 +1,9 @@
|
||||
---
|
||||
name: blazor-state-performance
|
||||
description: Performance & State Persistence in Blazor .NET 10
|
||||
---
|
||||
# Performance Rules
|
||||
|
||||
- **State Management:** Use `PersistentComponentState` to sync data between prerendering and client-side.
|
||||
- **Optimization:** Use `@key` directive for list iterations to minimize DOM diffing.
|
||||
- **Memory:** Always implement `IAsyncDisposable` in components using JS Interop to prevent memory leaks.
|
||||
@@ -0,0 +1,54 @@
|
||||
# .NET Async Best Practices: Avoiding `async void`
|
||||
|
||||
This document defines the core rules for handling asynchronous operations in .NET, specifically focused on the dangers of `async void`.
|
||||
|
||||
## The Rule: NEVER Use `async void`
|
||||
`async void` is a critical anti-pattern in .NET that must be avoided in almost all scenarios.
|
||||
|
||||
### Why `async void` is Dangerous:
|
||||
1. **Untraceable Crashes**: Exceptions thrown in an `async void` method cannot be caught by a `try-catch` block outside the method. They often crash the entire process.
|
||||
2. **Impossible to Await**: Callers cannot know when the operation has finished, leading to race conditions and "disposed object" exceptions (especially with `DbContext`).
|
||||
3. **Broken Lifecycle**: In Blazor and ASP.NET Core, the DI container might dispose of scoped services (like `DbContext`) before the `async void` method completes its work.
|
||||
|
||||
## Correct Patterns
|
||||
|
||||
### 1. Standard Methods
|
||||
Always return `Task` or `ValueTask` instead of `void`.
|
||||
```csharp
|
||||
// BAD
|
||||
public async void SaveDataAsync() { ... }
|
||||
|
||||
// GOOD
|
||||
public async Task SaveDataAsync() { ... }
|
||||
```
|
||||
|
||||
### 2. Async Events (Blazor/Services)
|
||||
When dealing with events that are defined as `Action` or `EventHandler`, do not use `async void` in the handler. Instead, refactor the event to support `Task`.
|
||||
|
||||
#### Pattern A: Use `Func<Task>` for Events
|
||||
Instead of `Action`, use `Func<Task>` so the invoker can await all handlers.
|
||||
```csharp
|
||||
// Interface
|
||||
event Func<Task>? OnChanged;
|
||||
|
||||
// Invoker
|
||||
if (OnChanged != null)
|
||||
{
|
||||
foreach (var handler in OnChanged.GetInvocationList().Cast<Func<Task>>())
|
||||
{
|
||||
await handler();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Pattern B: Wrapper for Legacy Events
|
||||
If you *must* subscribe to a legacy `void` event, use a Task-returning method and a lambda, but be aware of the "fire-and-forget" risks.
|
||||
```csharp
|
||||
// Better than async void, but still has lifecycle risks
|
||||
NavigationService.OnChanged += () => { _ = HandleChangedAsync(); };
|
||||
```
|
||||
|
||||
## Special Exceptions
|
||||
The ONLY valid place for `async void` is in **Top-level Event Handlers** in legacy UI frameworks (WinForms/WPF) where the event signature is fixed and cannot be changed. Even then, the method body should be wrapped in a `try-catch` that logs or handles all exceptions.
|
||||
|
||||
In modern Blazor and Web development, there is **zero justification** for `async void`.
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
name: nexus-clean-architecture
|
||||
description: Clean Architecture & CQRS implementation for .NET 10 with Blazor Hybrid
|
||||
---
|
||||
# Clean Architecture Standards
|
||||
|
||||
- **Project Structure (Layered):**
|
||||
- `NexusReader.Domain`: Enterprise business rules (Entities, Value Objects, Domain Events).
|
||||
- `NexusReader.Application`: Application business rules (Commands, Queries, DTOs, Mappings, Interfaces).
|
||||
- `NexusReader.Infrastructure`: Data access, external services, and platform-specific implementations.
|
||||
- `NexusReader.UI.Shared`: UI logic and Blazor components.
|
||||
- `NexusReader.Maui` / `NexusReader.Web`: Platform host projects.
|
||||
|
||||
- **CQRS & Messaging:**
|
||||
- **MediatR**: Use standard `MediatR` for decoupling.
|
||||
- **Queries**: Read-only operations, return `Task<Result<T>>`.
|
||||
- **Commands**: State-changing operations, return `Task<Result>` or `Task<Result<T>>`.
|
||||
- **Handlers**: Located in `Application` layer, grouped by feature (e.g., `Queries/Reader/...`).
|
||||
- **Client-Server Boundaries**: DO NOT execute MediatR handlers directly from WASM/MAUI clients if the handler relies on server-only infrastructure (e.g., `AppDbContext`, `IHubContext`). Instead, the client must trigger an API or SignalR endpoint, and the server dispatches the MediatR command.
|
||||
|
||||
- **Functional Error Handling:**
|
||||
- Mandatory use of `FluentResults`.
|
||||
- No exceptions for business logic flow. Handlers must return `Result.Ok()` or `Result.Fail()`.
|
||||
|
||||
- **UI Architecture (Atomic Design):**
|
||||
- Components in `NexusReader.UI.Shared` must follow Atomic Design:
|
||||
- `Atoms`: Smallest functional units (Buttons, Inputs).
|
||||
- `Molecules`: Groups of atoms (Search Bar, Form Field).
|
||||
- `Organisms`: Complex UI sections (Navigation, Header).
|
||||
- `Pages`: Composed organisms forming a full view.
|
||||
|
||||
- **Object Mapping:**
|
||||
- Use `Mapster` for all DTO/Entity mappings.
|
||||
- Centralize configuration in `NexusReader.Application/Mappings/MappingConfig.cs`.
|
||||
- No `AutoMapper` allowed.
|
||||
|
||||
- **Cross-Platform Strategy:**
|
||||
- Maximize code sharing in `NexusReader.UI.Shared`.
|
||||
- Use `IPlatformService` (or similar abstractions) for native features, implemented in `Infrastructure.Mobile` or Maui projects.
|
||||
|
||||
- **Code Validation (CRITICAL):**
|
||||
- **Mandatory Build Verification**: After any code change, the agent MUST run `dotnet build` on the solution. The agent must verify that the build completes with `Exit code: 0` and without errors before concluding the task or requesting user feedback.
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
name: nexus-code-review
|
||||
description: Code Review Checklist and Standards for NexusReader SaaS
|
||||
---
|
||||
# NexusReader Code Review Standards
|
||||
|
||||
When conducting or receiving a code review for NexusReader, ensure the implementation adheres to the following critical architectural and performance standards:
|
||||
|
||||
## 1. Architectural Boundaries (CQRS & Blazor Hybrid)
|
||||
- [ ] **Client vs. Server Execution**: MediatR handlers that depend on server-side infrastructure (`AppDbContext`, `IHubContext`, secrets) MUST NOT be executed directly from client environments (WASM/MAUI).
|
||||
- [ ] **Dependency Leakage**: Ensure `NexusReader.Web.Client` (WASM) does not reference `NexusReader.Infrastructure` if the infrastructure requires `Microsoft.AspNetCore.App` framework references.
|
||||
- [ ] **SignalR Bridges**: Client-initiated state changes should be sent via SignalR `SendAsync` to a server Hub, which then dispatches the internal `MediatR` command.
|
||||
|
||||
## 2. Event Handling & Debouncing
|
||||
- [ ] **High-Frequency UI Events**: UI actions like scrolling, resizing, or typing must be debounced.
|
||||
- [ ] **Trailing-Edge Debounce**: Use a `CancellationTokenSource` and `Task.Delay` to ensure the *last* event in a rapid sequence is executed. Do not use simple time-window drops, as they result in lost final states.
|
||||
- [ ] **Async Void**: Ensure UI event handlers do not use `async void` unless they are top-level framework event bindings, and even then, they must catch all exceptions.
|
||||
|
||||
## 3. SignalR & Real-Time Contexts
|
||||
- [ ] **Authentication Context**: Do not rely on `IHttpContextAccessor` inside MediatR handlers triggered by SignalR Hubs. Use `Context.UserIdentifier` directly from the Hub and pass it as a command parameter.
|
||||
- [ ] **Connection State**: Always check `HubConnection.State == HubConnectionState.Connected` before attempting to send messages from the client.
|
||||
- [ ] **Targeted Broadcasting**: Use SignalR `Groups` (e.g., `$"User_{userId}"`) to broadcast updates only to the devices owned by the relevant user.
|
||||
|
||||
## 4. Performance & Scalability
|
||||
- [ ] **Database Write Contention**: High-frequency telemetry (like reading progress) should ideally be batched or cached in-memory before writing to SQL, unless real-time persistence is strictly required.
|
||||
- [ ] **Memory Leaks**: Ensure all components and services that subscribe to events (e.g., `OnProgressReceived`, JS Observers) implement `IDisposable` or `IAsyncDisposable` and properly unsubscribe.
|
||||
|
||||
## 5. Standard Nexus Guidelines
|
||||
- [ ] **Result Pattern**: Ensure all application logic returns `Result` or `Result<T>` via FluentResults. No exceptions for control flow.
|
||||
- [ ] **AI Prompts**: Ensure changes to AI logic do not bypass the `PromptRegistry` or token estimation limits defined in `AiSettings`.
|
||||
@@ -0,0 +1,11 @@
|
||||
---
|
||||
name: nexus-graph-d3
|
||||
description: D3.js standards for Knowledge Graph
|
||||
---
|
||||
# D3.js Standards
|
||||
|
||||
- **Data Exchange:** Use `System.Text.Json` with CamelCase naming.
|
||||
- **JS Interop:** Use ES6 modules and `IJSObjectReference`.
|
||||
- **Responsiveness:** SVG must use `viewBox` for fluid portrait scaling.
|
||||
- **Visuals:** Use CSS variables (`--nexus-neon`) for node styling.
|
||||
- **Events:** JS emits events (like `nodeClicked`) caught by Blazor via `DotNetObjectReference`.
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
name: nexus-identity-saas
|
||||
description: Standards for Identity, Authentication, and SaaS feature implementations
|
||||
---
|
||||
# Identity & SaaS Integration
|
||||
|
||||
- **Core Identity Model:**
|
||||
- Extend `IdentityUser` to create a custom `NexusUser` model containing SaaS-specific properties (e.g., `AITokenLimit`, `AITokensUsed`, `TenantId`, `CurrentPlan`).
|
||||
- Place core domain models in the core project layer (e.g., `NexusArchitect.Core` or `NexusReader.Domain`).
|
||||
- Configure `ApplicationDbContext` to inherit from `IdentityDbContext<NexusUser>` and map custom fields and relationships correctly.
|
||||
|
||||
- **Authentication Endpoints & Providers:**
|
||||
- Use native ASP.NET Core Identity API endpoints (`/register`, `/login`, `/refresh`) or scaffolded Razor components in Blazor (`Components/Account/Pages`).
|
||||
- Integrate OAuth2 providers (like Google, Facebook, Microsoft) natively via ASP.NET Core's external login providers.
|
||||
- Utilize `SignInManager<TUser>` and `UserManager<TUser>` for custom login logic and user management.
|
||||
|
||||
- **Service Configuration & Policies:**
|
||||
- Register Identity using `builder.Services.AddDefaultIdentity<NexusUser>()` or `AddIdentity<NexusUser, IdentityRole>()` followed by `.AddEntityFrameworkStores<ApplicationDbContext>()`.
|
||||
- Configure `IdentityOptions` in `Program.cs` to enforce strict security standards:
|
||||
- **Password:** `RequireDigit`, `RequireLowercase`, `RequireUppercase`, `RequireNonAlphanumeric`, `RequiredLength` (min 8).
|
||||
- **Lockout:** Set `MaxFailedAccessAttempts` and `DefaultLockoutTimeSpan` to prevent brute-force attacks.
|
||||
- **User:** Enforce `RequireUniqueEmail = true`.
|
||||
|
||||
- **Authorization & Policies:**
|
||||
- Implement Roles and Claims-based authorization.
|
||||
- Create robust Policies (e.g., `ProUser`) and use custom `Requirement` handlers for specific business logic like checking if `AITokensUsed < AITokenLimit`.
|
||||
|
||||
- **Mobile / Blazor Hybrid Auth State:**
|
||||
- Ensure authentication state persists securely within the MAUI container.
|
||||
- Store JWT tokens and sensitive session data in `SecureStorage`.
|
||||
- Provide a seamless mechanism to restore the `AuthenticationStateProvider` on app launch if the token is valid.
|
||||
|
||||
- **SaaS Features & Webhooks:**
|
||||
- Integrate third-party payment/subscription providers (e.g., Stripe) using secure webhooks.
|
||||
- Sync external subscription status with internal user claims and limits (e.g., upgrade `AITokenLimit` upon a webhook success event for a "Pro" plan).
|
||||
|
||||
- **Verification:**
|
||||
- Write unit tests for custom authorization handlers and token limit logic.
|
||||
- Ensure the UI handles unauthorized and out-of-tokens states gracefully and points users to subscription management.
|
||||
@@ -0,0 +1,41 @@
|
||||
---
|
||||
name: nexus-ui-engine
|
||||
description: Design System & Component rules for Blazor
|
||||
---
|
||||
# UI Standards
|
||||
|
||||
- **Atomic Design:**
|
||||
- Build reusable components in `NexusReader.UI.Shared/Components`.
|
||||
- `Atoms`: Base elements (`NexusButton`, `NexusIcon`, `NexusTypography`).
|
||||
- `Molecules`: Small groups (`AiAssistantBubble`, `KnowledgeCheck`).
|
||||
- `Organisms`: High-level sections (`KnowledgeGraph`, `ReaderCanvas`).
|
||||
|
||||
- **Styling & Isolation:**
|
||||
- Mandatory use of scoped CSS (`.razor.css`).
|
||||
- No global CSS except for design tokens in `app.css`.
|
||||
- Use `::deep` only when absolutely necessary to style child components.
|
||||
|
||||
- **Design System (Nexus Neon):**
|
||||
- **Color Palette:**
|
||||
- Primary Accent: `--nexus-neon` (`#00ff99`) - Used for borders, highlights, and icons.
|
||||
- Dark Mode: `--nexus-bg` (`#0a0a0a`), `--nexus-card` (`#141414`).
|
||||
- Light Mode: `--nexus-bg` (`#f8f9fa`), `--nexus-card` (`#ffffff`).
|
||||
- **Typography:**
|
||||
- UI Elements: `Inter` (Sans-Serif) for controls, menus, and labels.
|
||||
- Reading Content: `Merriweather` (Serif) for books and articles to ensure high readability.
|
||||
- **Effects:**
|
||||
- Subtle neon glows (`box-shadow: 0 0 15px rgba(0, 255, 153, 0.3)`).
|
||||
- Glassmorphism for overlays and modals.
|
||||
|
||||
- **Adaptive Layouts:**
|
||||
- Support `.platform-mobile` and `.platform-desktop` context classes.
|
||||
- Handle safe-area insets (`--safe-area-inset-*`) for mobile devices.
|
||||
|
||||
- **Accessibility (A11y):**
|
||||
- Touch Targets: Min `44x44px` on mobile (enforced via CSS variables).
|
||||
- Contrast: Minimum ratio of 4.5:1.
|
||||
- Semantic HTML: Use appropriate tags (`<button>`, `<article>`, `<nav>`).
|
||||
|
||||
- **Interactive Flow:**
|
||||
- AI Assistant interactions must be non-blocking and smoothly transition using CSS animations.
|
||||
- Interactive elements must have clear `:hover`, `:active`, and `:focus` states.
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
name: semantic-kernel-orchestrator
|
||||
description: Integrating AI logic with .NET Semantic Kernel
|
||||
---
|
||||
# AI Implementation Rules
|
||||
|
||||
- **Kernel Setup:** Use Microsoft Semantic Kernel with .NET 10.
|
||||
- **Function Calling:** Define C# Plugins for "Graph Update" and "Quiz Generation".
|
||||
- **Streaming:** Implement `IAsyncEnumerable<string>` for real-time assistant responses in the UI.
|
||||
- **Context:** Ensure chapter metadata is passed as Semantic Memory.
|
||||
Reference in New Issue
Block a user