# Development Conventions & AI Agent Rules

# Development Conventions & AI Agent Rules

<details>
<summary>Relevant source files</summary>

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

- [.devin/config.local.json](.devin/config.local.json)
- [.devin/rules/code-guardrails.md](.devin/rules/code-guardrails.md)
- [.devin/rules/file-operations.md](.devin/rules/file-operations.md)
- [.devin/rules/temp-files.md](.devin/rules/temp-files.md)
- [.devin/rules/workflow.md](.devin/rules/workflow.md)
- [.windsurfintructions](.windsurfintructions)
- [AGENTS.md](AGENTS.md)
- [README.md](README.md)
- [docs/ai/README.md](docs/ai/README.md)
- [docs/ai/SKILLS.md](docs/ai/SKILLS.md)
- [docs/ai/WORKFLOWS.md](docs/ai/WORKFLOWS.md)
- [docs/ai/patterns.md](docs/ai/patterns.md)
- [docs/gitflow.md](docs/gitflow.md)
- [src/lib/components/entity-list-table/composables/useBulkActions.svelte.ts](src/lib/components/entity-list-table/composables/useBulkActions.svelte.ts)

</details>



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]():
1.  **Analysis**: Analyze requirements without modifying source files [.devin/rules/workflow.md:11]().
2.  **Plan Creation**: Generate a Markdown plan in `primebrick-workspace/ai-plans/` [.devin/rules/workflow.md:12-13]().
3.  **Halt**: Output *"Planning complete... Awaiting approval"* and stop [.devin/rules/workflow.md:14-15]().
4.  **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
1.  **Installation**: New Shadcn components are added via `npx shadcn-svelte@next add`.
2.  **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]().
3.  **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**
```mermaid
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**
```mermaid
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]()

---