@heyai-rules/pilo-masterkit 2.1.0 → 3.1.0

package/.agent/mcp-configs/mcp-servers.json

@@ -1,181 +1,181 @@
-{
-  "mcpServers": {
-    "jira": {
-      "command": "uvx",
-      "args": ["mcp-atlassian==0.21.0"],
-      "env": {
-        "JIRA_URL": "YOUR_JIRA_URL_HERE",
-        "JIRA_EMAIL": "YOUR_JIRA_EMAIL_HERE",
-        "JIRA_API_TOKEN": "YOUR_JIRA_API_TOKEN_HERE"
-      },
-      "description": "Jira issue tracking — search, create, update, comment, transition issues"
-    },
-    "github": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-github"],
-      "env": {
-        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT_HERE"
-      },
-      "description": "GitHub operations - PRs, issues, repos"
-    },
-    "firecrawl": {
-      "command": "npx",
-      "args": ["-y", "firecrawl-mcp"],
-      "env": {
-        "FIRECRAWL_API_KEY": "YOUR_FIRECRAWL_KEY_HERE"
-      },
-      "description": "Web scraping and crawling"
-    },
-    "supabase": {
-      "command": "npx",
-      "args": ["-y", "@supabase/mcp-server-supabase@latest", "--project-ref=YOUR_PROJECT_REF"],
-      "description": "Supabase database operations"
-    },
-    "memory": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-memory"],
-      "description": "Persistent memory across sessions"
-    },
-    "omega-memory": {
-      "command": "uvx",
-      "args": ["omega-memory", "serve"],
-      "description": "Persistent agent memory with semantic search, multi-agent coordination, and knowledge graphs — run via uvx (richer than the basic memory store)"
-    },
-    "sequential-thinking": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"],
-      "description": "Chain-of-thought reasoning"
-    },
-    "vercel": {
-      "type": "http",
-      "url": "https://mcp.vercel.com",
-      "description": "Vercel deployments and projects"
-    },
-    "railway": {
-      "command": "npx",
-      "args": ["-y", "@railway/mcp-server"],
-      "description": "Railway deployments"
-    },
-    "cloudflare-docs": {
-      "type": "http",
-      "url": "https://docs.mcp.cloudflare.com/mcp",
-      "description": "Cloudflare documentation search"
-    },
-    "cloudflare-workers-builds": {
-      "type": "http",
-      "url": "https://builds.mcp.cloudflare.com/mcp",
-      "description": "Cloudflare Workers builds"
-    },
-    "cloudflare-workers-bindings": {
-      "type": "http",
-      "url": "https://bindings.mcp.cloudflare.com/mcp",
-      "description": "Cloudflare Workers bindings"
-    },
-    "cloudflare-observability": {
-      "type": "http",
-      "url": "https://observability.mcp.cloudflare.com/mcp",
-      "description": "Cloudflare observability/logs"
-    },
-    "clickhouse": {
-      "type": "http",
-      "url": "https://mcp.clickhouse.cloud/mcp",
-      "description": "ClickHouse analytics queries"
-    },
-    "exa-web-search": {
-      "command": "npx",
-      "args": ["-y", "exa-mcp-server"],
-      "env": {
-        "EXA_API_KEY": "YOUR_EXA_API_KEY_HERE"
-      },
-      "description": "Web search, research, and data ingestion via Exa API — prefer task-scoped use for broader research after GitHub search and primary docs"
-    },
-    "context7": {
-      "command": "npx",
-      "args": ["-y", "@upstash/context7-mcp@latest"],
-      "description": "Live documentation lookup — use with /docs command and documentation-lookup skill (resolve-library-id, query-docs)."
-    },
-    "magic": {
-      "command": "npx",
-      "args": ["-y", "@magicuidesign/mcp@latest"],
-      "description": "Magic UI components"
-    },
-    "filesystem": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/your/projects"],
-      "description": "Filesystem operations (set your path)"
-    },
-    "insaits": {
-      "command": "python3",
-      "args": ["-m", "insa_its.mcp_server"],
-      "description": "AI-to-AI security monitoring — anomaly detection, credential exposure, hallucination checks, forensic tracing. 23 anomaly types, OWASP MCP Top 10 coverage. 100% local. Install: pip install insa-its"
-    },
-    "playwright": {
-      "command": "npx",
-      "args": ["-y", "@playwright/mcp", "--browser", "chrome"],
-      "description": "Browser automation and testing via Playwright"
-    },
-    "fal-ai": {
-      "command": "npx",
-      "args": ["-y", "fal-ai-mcp-server"],
-      "env": {
-        "FAL_KEY": "YOUR_FAL_KEY_HERE"
-      },
-      "description": "AI image/video/audio generation via fal.ai models"
-    },
-    "browserbase": {
-      "command": "npx",
-      "args": ["-y", "@browserbasehq/mcp-server-browserbase"],
-      "env": {
-        "BROWSERBASE_API_KEY": "YOUR_BROWSERBASE_KEY_HERE"
-      },
-      "description": "Cloud browser sessions via Browserbase"
-    },
-    "browser-use": {
-      "type": "http",
-      "url": "https://api.browser-use.com/mcp",
-      "headers": {
-        "x-browser-use-api-key": "YOUR_BROWSER_USE_KEY_HERE"
-      },
-      "description": "AI browser agent for web tasks"
-    },
-    "devfleet": {
-      "type": "http",
-      "url": "http://localhost:18801/mcp",
-      "description": "Multi-agent orchestration — dispatch parallel Claude Code agents in isolated worktrees. Plan projects, auto-chain missions, read structured reports. Repo: https://github.com/LEC-AI/claude-devfleet"
-    },
-    "token-optimizer": {
-      "command": "npx",
-      "args": ["-y", "token-optimizer-mcp"],
-      "description": "Token optimization for 95%+ context reduction via content deduplication and compression"
-    },
-    "laraplugins": {
-      "type": "http",
-      "url": "https://laraplugins.io/mcp/plugins",
-      "description": "Laravel plugin discovery — search packages by keyword, health score, Laravel/PHP version compatibility. Use with laravel-plugin-discovery skill."
-    },
-    "confluence": {
-      "command": "npx",
-      "args": ["-y", "confluence-mcp-server"],
-      "env": {
-        "CONFLUENCE_BASE_URL": "YOUR_CONFLUENCE_URL_HERE",
-        "CONFLUENCE_EMAIL": "YOUR_EMAIL_HERE",
-        "CONFLUENCE_API_TOKEN": "YOUR_CONFLUENCE_TOKEN_HERE"
-      },
-      "description": "Confluence Cloud integration — search pages, retrieve content, explore spaces"
-    },
-    "evalview": {
-      "command": "python3",
-      "args": ["-m", "evalview", "mcp", "serve"],
-      "env": {
-        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE"
-      },
-      "description": "AI agent regression testing — snapshot behavior, detect regressions in tool calls and output quality. 8 tools: create_test, run_snapshot, run_check, list_tests, validate_skill, generate_skill_tests, run_skill_test, generate_visual_report. API key optional — deterministic checks (tool diff, output hash) work without it. Install: pip install \"evalview>=0.5,<1\""
-    }
-  },
-  "_comments": {
-    "usage": "Copy the servers you need to your ~/.claude.json mcpServers section",
-    "env_vars": "Replace YOUR_*_HERE placeholders with actual values",
-    "disabling": "Use disabledMcpServers array in project config to disable per-project",
-    "context_warning": "Keep under 10 MCPs enabled to preserve context window"
-  }
-}
+{
+  "mcpServers": {
+    "jira": {
+      "command": "uvx",
+      "args": ["mcp-atlassian==0.21.0"],
+      "env": {
+        "JIRA_URL": "YOUR_JIRA_URL_HERE",
+        "JIRA_EMAIL": "YOUR_JIRA_EMAIL_HERE",
+        "JIRA_API_TOKEN": "YOUR_JIRA_API_TOKEN_HERE"
+      },
+      "description": "Jira issue tracking — search, create, update, comment, transition issues"
+    },
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT_HERE"
+      },
+      "description": "GitHub operations - PRs, issues, repos"
+    },
+    "firecrawl": {
+      "command": "npx",
+      "args": ["-y", "firecrawl-mcp"],
+      "env": {
+        "FIRECRAWL_API_KEY": "YOUR_FIRECRAWL_KEY_HERE"
+      },
+      "description": "Web scraping and crawling"
+    },
+    "supabase": {
+      "command": "npx",
+      "args": ["-y", "@supabase/mcp-server-supabase@latest", "--project-ref=YOUR_PROJECT_REF"],
+      "description": "Supabase database operations"
+    },
+    "memory": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-memory"],
+      "description": "Persistent memory across sessions"
+    },
+    "omega-memory": {
+      "command": "uvx",
+      "args": ["omega-memory", "serve"],
+      "description": "Persistent agent memory with semantic search, multi-agent coordination, and knowledge graphs — run via uvx (richer than the basic memory store)"
+    },
+    "sequential-thinking": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"],
+      "description": "Chain-of-thought reasoning"
+    },
+    "vercel": {
+      "type": "http",
+      "url": "https://mcp.vercel.com",
+      "description": "Vercel deployments and projects"
+    },
+    "railway": {
+      "command": "npx",
+      "args": ["-y", "@railway/mcp-server"],
+      "description": "Railway deployments"
+    },
+    "cloudflare-docs": {
+      "type": "http",
+      "url": "https://docs.mcp.cloudflare.com/mcp",
+      "description": "Cloudflare documentation search"
+    },
+    "cloudflare-workers-builds": {
+      "type": "http",
+      "url": "https://builds.mcp.cloudflare.com/mcp",
+      "description": "Cloudflare Workers builds"
+    },
+    "cloudflare-workers-bindings": {
+      "type": "http",
+      "url": "https://bindings.mcp.cloudflare.com/mcp",
+      "description": "Cloudflare Workers bindings"
+    },
+    "cloudflare-observability": {
+      "type": "http",
+      "url": "https://observability.mcp.cloudflare.com/mcp",
+      "description": "Cloudflare observability/logs"
+    },
+    "clickhouse": {
+      "type": "http",
+      "url": "https://mcp.clickhouse.cloud/mcp",
+      "description": "ClickHouse analytics queries"
+    },
+    "exa-web-search": {
+      "command": "npx",
+      "args": ["-y", "exa-mcp-server"],
+      "env": {
+        "EXA_API_KEY": "YOUR_EXA_API_KEY_HERE"
+      },
+      "description": "Web search, research, and data ingestion via Exa API — prefer task-scoped use for broader research after GitHub search and primary docs"
+    },
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"],
+      "description": "Live documentation lookup — use with /docs command and documentation-lookup skill (resolve-library-id, query-docs)."
+    },
+    "magic": {
+      "command": "npx",
+      "args": ["-y", "@magicuidesign/mcp@latest"],
+      "description": "Magic UI components"
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/your/projects"],
+      "description": "Filesystem operations (set your path)"
+    },
+    "insaits": {
+      "command": "python3",
+      "args": ["-m", "insa_its.mcp_server"],
+      "description": "AI-to-AI security monitoring — anomaly detection, credential exposure, hallucination checks, forensic tracing. 23 anomaly types, OWASP MCP Top 10 coverage. 100% local. Install: pip install insa-its"
+    },
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp", "--browser", "chrome"],
+      "description": "Browser automation and testing via Playwright"
+    },
+    "fal-ai": {
+      "command": "npx",
+      "args": ["-y", "fal-ai-mcp-server"],
+      "env": {
+        "FAL_KEY": "YOUR_FAL_KEY_HERE"
+      },
+      "description": "AI image/video/audio generation via fal.ai models"
+    },
+    "browserbase": {
+      "command": "npx",
+      "args": ["-y", "@browserbasehq/mcp-server-browserbase"],
+      "env": {
+        "BROWSERBASE_API_KEY": "YOUR_BROWSERBASE_KEY_HERE"
+      },
+      "description": "Cloud browser sessions via Browserbase"
+    },
+    "browser-use": {
+      "type": "http",
+      "url": "https://api.browser-use.com/mcp",
+      "headers": {
+        "x-browser-use-api-key": "YOUR_BROWSER_USE_KEY_HERE"
+      },
+      "description": "AI browser agent for web tasks"
+    },
+    "devfleet": {
+      "type": "http",
+      "url": "http://localhost:18801/mcp",
+      "description": "Multi-agent orchestration — dispatch parallel Claude Code agents in isolated worktrees. Plan projects, auto-chain missions, read structured reports. Repo: https://github.com/LEC-AI/claude-devfleet"
+    },
+    "token-optimizer": {
+      "command": "npx",
+      "args": ["-y", "token-optimizer-mcp"],
+      "description": "Token optimization for 95%+ context reduction via content deduplication and compression"
+    },
+    "laraplugins": {
+      "type": "http",
+      "url": "https://laraplugins.io/mcp/plugins",
+      "description": "Laravel plugin discovery — search packages by keyword, health score, Laravel/PHP version compatibility. Use with laravel-plugin-discovery skill."
+    },
+    "confluence": {
+      "command": "npx",
+      "args": ["-y", "confluence-mcp-server"],
+      "env": {
+        "CONFLUENCE_BASE_URL": "YOUR_CONFLUENCE_URL_HERE",
+        "CONFLUENCE_EMAIL": "YOUR_EMAIL_HERE",
+        "CONFLUENCE_API_TOKEN": "YOUR_CONFLUENCE_TOKEN_HERE"
+      },
+      "description": "Confluence Cloud integration — search pages, retrieve content, explore spaces"
+    },
+    "evalview": {
+      "command": "python3",
+      "args": ["-m", "evalview", "mcp", "serve"],
+      "env": {
+        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE"
+      },
+      "description": "AI agent regression testing — snapshot behavior, detect regressions in tool calls and output quality. 8 tools: create_test, run_snapshot, run_check, list_tests, validate_skill, generate_skill_tests, run_skill_test, generate_visual_report. API key optional — deterministic checks (tool diff, output hash) work without it. Install: pip install \"evalview>=0.5,<1\""
+    }
+  },
+  "_comments": {
+    "usage": "Copy the servers you need to your ~/.claude.json mcpServers section",
+    "env_vars": "Replace YOUR_*_HERE placeholders with actual values",
+    "disabling": "Use disabledMcpServers array in project config to disable per-project",
+    "context_warning": "Keep under 10 MCPs enabled to preserve context window"
+  }
+}

package/.agent/rules/ARCHITECTURAL_BLUEPRINTS.md

@@ -1,62 +1,62 @@
-# 🏗️ Architectural Blueprints & Design System
-
-This document specifies the technical architecture, design standards, and default tools for the Pilo Masterkit. It follows the **Master + Overrides** pattern for flexible design management.
-
----
-
-## 🏛️ 1. Core Architecture & Tech Stack
-
-- **Frontend**: React 19, Next.js 15, Tailwind CSS v4.
-- **Backend**: Node.js (TypeScript) or Python (FastAPI).
-- **Database**: PostgreSQL (Prisma/Drizzle), Redis for caching.
-- **AI Integration**: Multi-model support (GPT-4o, Claude 3.5/3.7, Gemini 2.0) via API Gateway.
-
----
-
-## 🎨 2. Design System (Aesthetics)
-
-The project follows a **Modern, Minimalist, and Elegant** design philosophy. 
-
-### Global Design Master (`design-system/MASTER.md`)
-All global design tokens, color scales, and typography are defined here. 
-
-### Page-Specific Overrides (`design-system/pages/`)
-Specific pages (e.g., Dashboard, Checkout) can deviate from the Master by providing an override file in this folder.
-
-### Visual Styles
-- **Light Mode**: Elegant (Vanilla/Milk, Soft White, Pastel Orange).
-- **Dark Mode**: Aesthetic/Cosmic (Pink and Blue Pastels, Galaxy theme).
-- **Glassmorphism**: Primary effect for dark mode cards and navbars.
-- **Layout**: Bento Grid, consistent spacing (`max-w-7xl` containers).
-- **Typography**: Inter, Montserrat, or Outfit (Google Fonts).
-
----
-
-## 🛠️ 3. Integrated Kits & Capabilities
-
-We leverage world-class skill sets to ensure project excellence:
-
-1.  **UI/UX Pro Max**: 67 styles, 96 palettes, 57 font pairings. Use for all visual enhancements.
-2.  **Antigravity Kit**: 20 specialized agents and 36 foundational skills.
-3.  **Claude ECC**: Advanced TDD, security auditing, and autonomous workflows.
-
----
-
-## 📐 4. Professional UI Rules (Mandatory)
-
-1.  **No Emojis as Icons**: Use SVG icons ONLY (Heroicons, Lucide, Simple Icons).
-2.  **Stable Hover States**: Use color/opacity transitions. Avoid scale transforms that shift layout.
-3.  **Cursor Pointer**: Mandatory `cursor-pointer` for ALL interactive elements (cards, buttons, links).
-4.  **Floating Navbar**: Fixed elements should have proper floating spacing (e.g., `top-4 left-4 right-4`).
-5.  **Theme Direct Use**: Use theme colors directly (`bg-primary`) instead of wrapping them in unverified variables.
-
----
-
-## 🏁 5. Quality Standards
-
-- **PDCA Cycle**: Plan -> Do -> Check -> Act.
-- **Socratic Gate**: Clarify requirements BEFORE implementation.
-- **Zero-Bug Tolerance**: Every feature must include automated tests and manual walkthroughs.
-
----
-> *"Simplicity is the ultimate sophistication."*
+# 🏗️ Architectural Blueprints & Design System
+
+This document specifies the technical architecture, design standards, and default tools for the Pilo Masterkit. It follows the **Master + Overrides** pattern for flexible design management.
+
+---
+
+## 🏛️ 1. Core Architecture & Tech Stack
+
+- **Frontend**: React 19, Next.js 15, Tailwind CSS v4.
+- **Backend**: Node.js (TypeScript) or Python (FastAPI).
+- **Database**: PostgreSQL (Prisma/Drizzle), Redis for caching.
+- **AI Integration**: Multi-model support (GPT-4o, Claude 3.5/3.7, Gemini 2.0) via API Gateway.
+
+---
+
+## 🎨 2. Design System (Aesthetics)
+
+The project follows a **Modern, Minimalist, and Elegant** design philosophy. 
+
+### Global Design Master (`design-system/MASTER.md`)
+All global design tokens, color scales, and typography are defined here. 
+
+### Page-Specific Overrides (`design-system/pages/`)
+Specific pages (e.g., Dashboard, Checkout) can deviate from the Master by providing an override file in this folder.
+
+### Visual Styles
+- **Light Mode**: Elegant (Vanilla/Milk, Soft White, Pastel Orange).
+- **Dark Mode**: Aesthetic/Cosmic (Pink and Blue Pastels, Galaxy theme).
+- **Glassmorphism**: Primary effect for dark mode cards and navbars.
+- **Layout**: Bento Grid, consistent spacing (`max-w-7xl` containers).
+- **Typography**: Inter, Montserrat, or Outfit (Google Fonts).
+
+---
+
+## 🛠️ 3. Integrated Kits & Capabilities
+
+We leverage world-class skill sets to ensure project excellence:
+
+1.  **UI/UX Pro Max**: 67 styles, 96 palettes, 57 font pairings. Use for all visual enhancements.
+2.  **Antigravity Kit**: 20 specialized agents and 36 foundational skills.
+3.  **Claude ECC**: Advanced TDD, security auditing, and autonomous workflows.
+
+---
+
+## 📐 4. Professional UI Rules (Mandatory)
+
+1.  **No Emojis as Icons**: Use SVG icons ONLY (Heroicons, Lucide, Simple Icons).
+2.  **Stable Hover States**: Use color/opacity transitions. Avoid scale transforms that shift layout.
+3.  **Cursor Pointer**: Mandatory `cursor-pointer` for ALL interactive elements (cards, buttons, links).
+4.  **Floating Navbar**: Fixed elements should have proper floating spacing (e.g., `top-4 left-4 right-4`).
+5.  **Theme Direct Use**: Use theme colors directly (`bg-primary`) instead of wrapping them in unverified variables.
+
+---
+
+## 🏁 5. Quality Standards
+
+- **PDCA Cycle**: Plan -> Do -> Check -> Act.
+- **Socratic Gate**: Clarify requirements BEFORE implementation.
+- **Zero-Bug Tolerance**: Every feature must include automated tests and manual walkthroughs.
+
+---
+> *"Simplicity is the ultimate sophistication."*

package/.agent/rules/CODE_CRAFTSMANSHIP.md

@@ -1,69 +1,69 @@
-# 💻 Code Craftsmanship Standards
-
-This document specifies the coding standards, directory structures, and mandatory design patterns for the Pilo Masterkit. 
-
-> *"Code is read more often than it is written. Write for the human first, the machine second."*
-
----
-
-## 🏗️ 1. Project Architecture (Feature-based)
-
-The project uses a **Feature-based Architecture** to ensure high cohesion and low coupling.
-
-### Frontend (Next.js 15 App Router)
-- `src/app/`: Define Routes (Pages, Layouts, Loading, Error).
-- `src/components/ui/`: Base UI primitives (shadcn/ui, tailwind-v4).
-- `src/components/features/`: Complex components tied to business logic.
-- `src/hooks/`: Reusable custom React Hooks.
-- `src/lib/`: Utility libraries and service configurations (Prisma, Cloudinary, etc.).
-
-### Backend (Node.js / FastAPI)
-- `api/routes/`: Endpoint definitions and routing logic.
-- `api/controllers/`: Core business logic handlers.
-- `api/models/`: Data structure definitions and validation schemas.
-
----
-
-## ⚡ 2. Core Coding Principles
-
-### Immutability (CRITICAL)
-- **Rule**: Always create new objects/arrays instead of mutating existing ones.
-- **Pattern**: Use spreads `[...arr]`, `{...obj}` or functional updates.
-- **Reason**: Enhances predictability, debuggability, and compatibility with React's rendering cycle.
-
-### Small & Focused Files
-- **Files**: Aim for 200-400 lines typical. **800 lines MAX**.
-- **Functions**: Small and atomic (<50 lines). If a function does two things, split it.
-- **Cohesion**: Keep related logic together; separate unrelated concerns.
-
-### Error Handling
-- **No Silencing**: Never silently swallow errors with empty `catch` blocks.
-- **User-Friendly**: Provide clear, non-technical messages in UI components.
-- **Detailed Logging**: Log full error context and stack traces server-side.
-
----
-
-## 📝 3. Naming Conventions
-
-- **Files & Folders**: `kebab-case` (e.g., `user-profile.tsx`, `api-gateway/`).
-- **Components**: `PascalCase` (e.g., `UserProfileCard`).
-- **Variables & Functions**: `camelCase` (e.g., `fetchUserData`).
-- **Constants**: `UPPER_SNAKE_CASE` (e.g., `MAX_RETRY_LIMIT`).
-- **Boolean Variables**: Prefix with `is`, `has`, or `should` (e.g., `isLoading`, `hasError`).
-
----
-
-## 🧹 4. Development Patterns
-
-### React 19 & Next.js 15
-- **Server Components (RSC)**: Default to Server Components for data fetching.
-- **Client Components**: Use `"use client"` only when interactivity (hooks/events) is required.
-- **Data Mutations**: Use **Server Actions** for all data-changing operations.
-
-### Backend & API
-- **Statelessness**: Every API endpoint must be stateless.
-- **Validation**: Strict schema-based validation using `Zod` (TypeScript) or `Pydantic` (Python).
-- **Graceful Failure**: Return consistent error envelopes with appropriate HTTP status codes.
-
----
-> *"Simplicity is the key to brilliance."*
+# 💻 Code Craftsmanship Standards
+
+This document specifies the coding standards, directory structures, and mandatory design patterns for the Pilo Masterkit. 
+
+> *"Code is read more often than it is written. Write for the human first, the machine second."*
+
+---
+
+## 🏗️ 1. Project Architecture (Feature-based)
+
+The project uses a **Feature-based Architecture** to ensure high cohesion and low coupling.
+
+### Frontend (Next.js 15 App Router)
+- `src/app/`: Define Routes (Pages, Layouts, Loading, Error).
+- `src/components/ui/`: Base UI primitives (shadcn/ui, tailwind-v4).
+- `src/components/features/`: Complex components tied to business logic.
+- `src/hooks/`: Reusable custom React Hooks.
+- `src/lib/`: Utility libraries and service configurations (Prisma, Cloudinary, etc.).
+
+### Backend (Node.js / FastAPI)
+- `api/routes/`: Endpoint definitions and routing logic.
+- `api/controllers/`: Core business logic handlers.
+- `api/models/`: Data structure definitions and validation schemas.
+
+---
+
+## ⚡ 2. Core Coding Principles
+
+### Immutability (CRITICAL)
+- **Rule**: Always create new objects/arrays instead of mutating existing ones.
+- **Pattern**: Use spreads `[...arr]`, `{...obj}` or functional updates.
+- **Reason**: Enhances predictability, debuggability, and compatibility with React's rendering cycle.
+
+### Small & Focused Files
+- **Files**: Aim for 200-400 lines typical. **800 lines MAX**.
+- **Functions**: Small and atomic (<50 lines). If a function does two things, split it.
+- **Cohesion**: Keep related logic together; separate unrelated concerns.
+
+### Error Handling
+- **No Silencing**: Never silently swallow errors with empty `catch` blocks.
+- **User-Friendly**: Provide clear, non-technical messages in UI components.
+- **Detailed Logging**: Log full error context and stack traces server-side.
+
+---
+
+## 📝 3. Naming Conventions
+
+- **Files & Folders**: `kebab-case` (e.g., `user-profile.tsx`, `api-gateway/`).
+- **Components**: `PascalCase` (e.g., `UserProfileCard`).
+- **Variables & Functions**: `camelCase` (e.g., `fetchUserData`).
+- **Constants**: `UPPER_SNAKE_CASE` (e.g., `MAX_RETRY_LIMIT`).
+- **Boolean Variables**: Prefix with `is`, `has`, or `should` (e.g., `isLoading`, `hasError`).
+
+---
+
+## 🧹 4. Development Patterns
+
+### React 19 & Next.js 15
+- **Server Components (RSC)**: Default to Server Components for data fetching.
+- **Client Components**: Use `"use client"` only when interactivity (hooks/events) is required.
+- **Data Mutations**: Use **Server Actions** for all data-changing operations.
+
+### Backend & API
+- **Statelessness**: Every API endpoint must be stateless.
+- **Validation**: Strict schema-based validation using `Zod` (TypeScript) or `Pydantic` (Python).
+- **Graceful Failure**: Return consistent error envelopes with appropriate HTTP status codes.
+
+---
+> *"Simplicity is the key to brilliance."*