Frontend

Development Conventions & AI Agent Rules

Relevant source files

The following files were used as context for generating this wiki page:

This page outlines the technical standards for the Primebrick Frontend, focusing on Svelte 5 implementation patterns, the strict operational rules for AI agents (Devin/Windsurf), and the workflow for managing vendored UI components.

Svelte 5 Runes Standards

The project exclusively utilizes Svelte 5 Runes for reactivity and component logic. Legacy Svelte 4 syntax (e.g., export let, $:) is prohibited AGENTS.md:12-13.

Reactivity with `$state` and `$derived`

State: All reactive state must be declared using let x = $state<Type>(value) .windsurfintructions:4.
Simple Derivations: Use $derived(expression) for simple logic. Anonymous functions inside $derived() are strictly forbidden (e.g., use $derived(a + b) instead of $derived(() => a + b)) AGENTS.md:19-20.
Complex Derivations: For logic involving loops, multiple conditions, or complex calculations, use $derived.by<Type>(() => { ... return value; }) .windsurfintructions:10.

Component Interface: `$props` and `Snippet`

Props: Props are destructured directly from $props() with explicit TypeScript interfaces AGENTS.md:16-18.
Events: The project does not use createEventDispatcher. Events are handled via callback functions passed as props AGENTS.md:22-23.
Children: To pass HTML or components as children, use the Snippet type and the {#render ...} block AGENTS.md:24-25.

Composable Logic (`.svelte.ts`)

Logic shared across components or managing complex state (like bulk actions) is encapsulated in .svelte.ts files using runes to maintain reactivity outside of .svelte files src/lib/components/entity-list-table/composables/useBulkActions.svelte.ts:59-61.

Sources: AGENTS.md:12-25, .windsurfintructions:1-16, src/lib/components/entity-list-table/composables/useBulkActions.svelte.ts:1-61

AI Agent Operational Rules

AI agents (Devin, Windsurf, etc.) must adhere to strict guardrails to ensure repository stability and predictable workflows.

1. The "Never Auto-Commit" Rule

CRITICAL: Agents are strictly forbidden from running git commit without explicit user instruction AGENTS.md:3-9.

Agents must wait for keywords like "commit" or "procedi con il commit" docs/gitflow.md:11.
When instructed to commit, agents must stage all changes (git add -A) across the workspace and push to origin docs/gitflow.md:98-103.

2. Tic-Toc Planning Workflow

Before modifying code, agents must follow the "Tic-Toc" plan-then-execute cycle .devin/rules/workflow.md:4-5:

Analysis: Analyze requirements without modifying source files .devin/rules/workflow.md:11.
Plan Creation: Generate a Markdown plan in primebrick-workspace/ai-plans/ .devin/rules/workflow.md:12-13.
Halt: Output "Planning complete... Awaiting approval" and stop .devin/rules/workflow.md:14-15.
Proceed: Only begin implementation after the user sends the keyword "PROCEED" .devin/rules/workflow.md:16.

3. File & Environment Guardrails

Temporary Files: Agents must NEVER create temporary scripts or patches within the project repositories. Use d:\git\primebrick\temp\ (Windows) or /tmp/ (Linux) and clean up immediately .devin/rules/temp-files.md:11-23.
Verification: Agents must use empirical tools (Test-Path, ls, grep) to verify file states rather than relying on IDE "open files" context .devin/rules/file-operations.md:15-25.
Error Handling: Agents have a maximum of 2 self-correction attempts for linting or compilation errors. If failure persists, the session must be marked as BLOCKED and escalated to the user .devin/rules/code-guardrails.md:6-10.

Sources: AGENTS.md:3-10, docs/gitflow.md:5-15, .devin/rules/workflow.md:1-17, .devin/rules/temp-files.md:1-37, .devin/rules/file-operations.md:1-42, .devin/rules/code-guardrails.md:1-15

Shadcn-Svelte & Vendor Workflow

The project uses a two-tier component architecture to balance standard UI primitives with custom domain requirements.

Component Hierarchy

Category	Location	Purpose
UI Primitives	`src/lib/components/ui/*`	Vendored Shadcn-Svelte components.
Domain Components	`src/lib/components/*`	Application-specific logic (e.g., `EntityListTable`).

Update Workflow

Installation: New Shadcn components are added via npx shadcn-svelte@next add.
Customization: Once added to src/lib/components/ui/, components are considered "owned" by the project. Any styling adjustments must use Tailwind CSS classes or the global theme variables in src/app.css README.md:41-48.
AI Constraints: Agents must not modify components.json or the fundamental structure of the ui/ directory without explicit instruction.

Sources: README.md:32-53, docs/ai/README.md:1-13

Data Flow: AI Plan to Implementation

The following diagram illustrates the transition from a natural language request to a verified code change following the repository's strict rules.

AI Workflow State Machine

Code
stateDiagram-v2
    [*] --> "Natural Language Task"
    "Natural Language Task" --> "Analysis Phase" : "Read codebase"
    "Analysis Phase" --> "Plan Creation" : "Generate .md in ai-plans/"
    "Plan Creation" --> "MANDATORY_BLOCKER" : "Awaiting 'PROCEED'"
    "MANDATORY_BLOCKER" --> "Implementation" : "User says PROCEED"
    
    state "Implementation" {
        direction TB
        "Apply Changes" --> "Run pnpm check"
        "Run pnpm check" --> "Self-Correction" : "Error Found"
        "Self-Correction" --> "Apply Changes" : "Attempt < 2"
        "Self-Correction" --> "BLOCKED" : "Attempt >= 2"
    }
    
    "Implementation" --> "User Review" : "Task Complete"
    "User Review" --> "Git Commit" : "User says 'commit'"
    "Git Commit" --> [*]

Sources: .devin/rules/workflow.md:1-17, .devin/rules/code-guardrails.md:1-15, docs/gitflow.md:5-15

Code Entity Mapping: Svelte 5 Runes

This diagram bridges the Svelte 5 Rune concepts to their specific implementation patterns used in the Primebrick codebase.

Rune Implementation Mapping

Code
graph TD
    subgraph "Natural Language Space"
        A["Reactive Variable"]
        B["Computed Property"]
        C["Component Inputs"]
        D["HTML Slot / Fragment"]
        E["Event Handling"]
    end

    subgraph "Code Entity Space (Svelte 5)"
        A1["$state<T>(initial)"]
        B1["$derived(expression)"]
        B2["$derived.by(() => { ... })"]
        C1["$props() destructuring"]
        D1["Snippet type / {#render}"]
        E1["Callback props (onchange)"]
    end

    A --- A1
    B --- B1
    B --- B2
    C --- C1
    D --- D1
    E --- E1

Sources: AGENTS.md:12-26, .windsurfintructions:1-16

Last modified on July 13, 2026

Date Dropper & Wheel Picker Entity Forms & Audit System

Frontend

Development Conventions & AI Agent Rules

Relevant source files

The following files were used as context for generating this wiki page:

Svelte 5 Runes Standards

The project exclusively utilizes Svelte 5 Runes for reactivity and component logic. Legacy Svelte 4 syntax (e.g., export let, $:) is prohibited AGENTS.md:12-13.

Reactivity with `$state` and `$derived`

State: All reactive state must be declared using let x = $state<Type>(value) .windsurfintructions:4.
Simple Derivations: Use $derived(expression) for simple logic. Anonymous functions inside $derived() are strictly forbidden (e.g., use $derived(a + b) instead of $derived(() => a + b)) AGENTS.md:19-20.
Complex Derivations: For logic involving loops, multiple conditions, or complex calculations, use $derived.by<Type>(() => { ... return value; }) .windsurfintructions:10.

Component Interface: `$props` and `Snippet`

Props: Props are destructured directly from $props() with explicit TypeScript interfaces AGENTS.md:16-18.
Events: The project does not use createEventDispatcher. Events are handled via callback functions passed as props AGENTS.md:22-23.
Children: To pass HTML or components as children, use the Snippet type and the {#render ...} block AGENTS.md:24-25.

Composable Logic (`.svelte.ts`)

Sources: AGENTS.md:12-25, .windsurfintructions:1-16, src/lib/components/entity-list-table/composables/useBulkActions.svelte.ts:1-61

AI Agent Operational Rules

AI agents (Devin, Windsurf, etc.) must adhere to strict guardrails to ensure repository stability and predictable workflows.

1. The "Never Auto-Commit" Rule

CRITICAL: Agents are strictly forbidden from running git commit without explicit user instruction AGENTS.md:3-9.

Agents must wait for keywords like "commit" or "procedi con il commit" docs/gitflow.md:11.
When instructed to commit, agents must stage all changes (git add -A) across the workspace and push to origin docs/gitflow.md:98-103.

2. Tic-Toc Planning Workflow

Before modifying code, agents must follow the "Tic-Toc" plan-then-execute cycle .devin/rules/workflow.md:4-5:

Analysis: Analyze requirements without modifying source files .devin/rules/workflow.md:11.
Plan Creation: Generate a Markdown plan in primebrick-workspace/ai-plans/ .devin/rules/workflow.md:12-13.
Halt: Output "Planning complete... Awaiting approval" and stop .devin/rules/workflow.md:14-15.
Proceed: Only begin implementation after the user sends the keyword "PROCEED" .devin/rules/workflow.md:16.

3. File & Environment Guardrails

Temporary Files: Agents must NEVER create temporary scripts or patches within the project repositories. Use d:\git\primebrick\temp\ (Windows) or /tmp/ (Linux) and clean up immediately .devin/rules/temp-files.md:11-23.
Verification: Agents must use empirical tools (Test-Path, ls, grep) to verify file states rather than relying on IDE "open files" context .devin/rules/file-operations.md:15-25.
Error Handling: Agents have a maximum of 2 self-correction attempts for linting or compilation errors. If failure persists, the session must be marked as BLOCKED and escalated to the user .devin/rules/code-guardrails.md:6-10.

Sources: AGENTS.md:3-10, docs/gitflow.md:5-15, .devin/rules/workflow.md:1-17, .devin/rules/temp-files.md:1-37, .devin/rules/file-operations.md:1-42, .devin/rules/code-guardrails.md:1-15

Shadcn-Svelte & Vendor Workflow

The project uses a two-tier component architecture to balance standard UI primitives with custom domain requirements.

Component Hierarchy

Category	Location	Purpose
UI Primitives	`src/lib/components/ui/*`	Vendored Shadcn-Svelte components.
Domain Components	`src/lib/components/*`	Application-specific logic (e.g., `EntityListTable`).

Update Workflow

Installation: New Shadcn components are added via npx shadcn-svelte@next add.
Customization: Once added to src/lib/components/ui/, components are considered "owned" by the project. Any styling adjustments must use Tailwind CSS classes or the global theme variables in src/app.css README.md:41-48.
AI Constraints: Agents must not modify components.json or the fundamental structure of the ui/ directory without explicit instruction.

Sources: README.md:32-53, docs/ai/README.md:1-13

Data Flow: AI Plan to Implementation

The following diagram illustrates the transition from a natural language request to a verified code change following the repository's strict rules.

AI Workflow State Machine

Code
stateDiagram-v2
    [*] --> "Natural Language Task"
    "Natural Language Task" --> "Analysis Phase" : "Read codebase"
    "Analysis Phase" --> "Plan Creation" : "Generate .md in ai-plans/"
    "Plan Creation" --> "MANDATORY_BLOCKER" : "Awaiting 'PROCEED'"
    "MANDATORY_BLOCKER" --> "Implementation" : "User says PROCEED"
    
    state "Implementation" {
        direction TB
        "Apply Changes" --> "Run pnpm check"
        "Run pnpm check" --> "Self-Correction" : "Error Found"
        "Self-Correction" --> "Apply Changes" : "Attempt < 2"
        "Self-Correction" --> "BLOCKED" : "Attempt >= 2"
    }
    
    "Implementation" --> "User Review" : "Task Complete"
    "User Review" --> "Git Commit" : "User says 'commit'"
    "Git Commit" --> [*]

Sources: .devin/rules/workflow.md:1-17, .devin/rules/code-guardrails.md:1-15, docs/gitflow.md:5-15

Code Entity Mapping: Svelte 5 Runes

This diagram bridges the Svelte 5 Rune concepts to their specific implementation patterns used in the Primebrick codebase.

Rune Implementation Mapping

Code
graph TD
    subgraph "Natural Language Space"
        A["Reactive Variable"]
        B["Computed Property"]
        C["Component Inputs"]
        D["HTML Slot / Fragment"]
        E["Event Handling"]
    end

    subgraph "Code Entity Space (Svelte 5)"
        A1["$state<T>(initial)"]
        B1["$derived(expression)"]
        B2["$derived.by(() => { ... })"]
        C1["$props() destructuring"]
        D1["Snippet type / {#render}"]
        E1["Callback props (onchange)"]
    end

    A --- A1
    B --- B1
    B --- B2
    C --- C1
    D --- D1
    E --- E1

Sources: AGENTS.md:12-26, .windsurfintructions:1-16

Last modified on July 13, 2026

Date Dropper & Wheel Picker Entity Forms & Audit System

Development Conventions & AI Agent Rules

Svelte 5 Runes Standards

Reactivity with $state and $derived

Component Interface: $props and Snippet

Composable Logic (.svelte.ts)

AI Agent Operational Rules

1. The "Never Auto-Commit" Rule

2. Tic-Toc Planning Workflow

3. File & Environment Guardrails

Shadcn-Svelte & Vendor Workflow

Component Hierarchy

Update Workflow

Data Flow: AI Plan to Implementation

Code Entity Mapping: Svelte 5 Runes

Development Conventions & AI Agent Rules

Svelte 5 Runes Standards

Reactivity with $state and $derived

Component Interface: $props and Snippet

Composable Logic (.svelte.ts)

AI Agent Operational Rules

1. The "Never Auto-Commit" Rule

2. Tic-Toc Planning Workflow

3. File & Environment Guardrails

Shadcn-Svelte & Vendor Workflow

Component Hierarchy

Update Workflow

Data Flow: AI Plan to Implementation

Code Entity Mapping: Svelte 5 Runes

Reactivity with `$state` and `$derived`

Component Interface: `$props` and `Snippet`

Composable Logic (`.svelte.ts`)

Reactivity with `$state` and `$derived`

Component Interface: `$props` and `Snippet`

Composable Logic (`.svelte.ts`)