@kienha/anti-chaotic 1.0.0

package/.agent/rules/clean-code.md

@@ -0,0 +1,109 @@
+---
+trigger: glob
+globs: **/*.{ts,tsx,js,jsx,py,go,java,rb,c,cpp,h,hpp,rs,css,html}
+---
+
+# Clean Code Standards
+
+You must adhere to these clean code principles when generating or modifying code.
+
+## Core Principles
+
+- **SOLID**: Follow Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, and Dependency Inversion principles.
+- **DRY (Don't Repeat Yourself)**: Extract common logic into functions or constants.
+- **KISS (Keep It Simple, Stupid)**: Avoid over-engineering. Code should be easy to understand.
+- **YAGNI (You Aren't Gonna Need It)**: Do not implement features or abstraction "just in case".
+
+## Naming Conventions
+
+- Variables and functions should be descriptive (e.g., `isUserLoggedIn` instead of `flag`).
+- Use consistent casing appropriate for the language (e.g., camelCase for JS/TS functions, snake_case for Python).
+- Boolean variables should start with `is`, `has`, `should`, or `can`.
+
+## Functions
+
+- Functions should ideally do one thing and do it well.
+- Keep functions short. If a function is too long, break it down.
+- Limit the number of arguments (3 or fewer is ideal).
+
+## Comments
+
+- Comments should explain "why" something is done, not "what" the code does (unless it's complex/unintuitive).
+- Remove commented-out code.
+
+## Error Handling
+
+- Context-aware error handling. Do not silently swallow errors.
+- Use explicit error types where possible.
+
+## Testing
+
+- Write testable code. Avoid global state and side effects where possible.
+
+## File Length Limits
+
+Files should be kept concise and focused. If a file exceeds these limits, consider splitting it:
+
+| File Type                   | Max Lines | Notes                                          |
+| --------------------------- | --------- | ---------------------------------------------- |
+| Components (`.tsx`, `.jsx`) | 200-300   | Split into smaller components or extract hooks |
+| Utility/Helper files        | 150-200   | Group related utilities, split by domain       |
+| API Routes/Handlers         | 100-150   | Extract business logic to services             |
+| Test files                  | 300-400   | Group by feature, use describe blocks          |
+| Styles (`.css`)             | 200-300   | Use CSS modules or split by component          |
+| Config files                | 100       | Keep minimal, use separate config files        |
+
+**When to split:**
+
+- When a file has multiple responsibilities (violates SRP)
+- When scrolling becomes difficult to follow logic
+- When imports section becomes excessively long (>15 imports)
+- When the file has multiple large functions that could be independent
+
+## File Header Comments
+
+Every new file MUST include a header comment at the top describing its purpose:
+
+**Format for TypeScript/JavaScript:**
+
+```typescript
+/**
+ * @file [filename]
+ * @description [Brief description of what this file contains and its purpose]
+ *
+ * @example (optional - for utilities/hooks)
+ * // Usage example here
+ */
+```
+
+**Format for CSS:**
+
+```css
+/**
+ * @file [filename]
+ * @description [Brief description of styles contained]
+ * 
+ * Sections:
+ * - [List main sections if applicable]
+ */
+```
+
+**Format for Python:**
+
+```python
+"""
+[filename]
+
+[Brief description of what this module contains and its purpose]
+
+Example (optional):
+    >>> usage_example()
+"""
+```
+
+**Requirements:**
+
+- `@file`: The filename (e.g., `user.service.ts`)
+- `@description`: 1-3 sentences explaining the file's purpose
+- Keep headers concise but informative
+- Update headers when file purpose changes significantly

package/.agent/rules/documentation.md

@@ -0,0 +1,178 @@
+---
+trigger: model_decision
+description: Always apply when creating, organizing, or modifying documentation files
+---
+
+# Documentation Structure Rule
+
+> [!IMPORTANT]
+> This rule is **MANDATORY** for all documentation operations. Violations will result in incorrect project structure.
+
+## Critical Rules (MUST Follow)
+
+1. **MUST** save all documents to `docs/` folder - NEVER create documents in project root or other folders
+2. **MUST** use Dewey Decimal folder structure (010, 020, 030, etc.)
+3. **MUST** include YAML frontmatter in every document
+4. **MUST** update relevant MOC file after creating a new document
+5. **MUST** use wiki-links `[[Document-Name]]` for cross-references
+6. **MUST NOT** create custom folder structures like `01-product/`, `02-analysis/`
+7. **MUST NOT** create documents without checking Document Type Mapping first
+
+## Decision Flow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ BEFORE creating any document, ask yourself:                 │
+├─────────────────────────────────────────────────────────────┤
+│ 1. Does docs/ folder exist?                                 │
+│    NO  → Create folder structure (see Required Structure)   │
+│    YES → Continue                                           │
+├─────────────────────────────────────────────────────────────┤
+│ 2. What type of document is this?                           │
+│    → Look up in Document Type Mapping table                 │
+│    → Get exact target folder and naming convention          │
+├─────────────────────────────────────────────────────────────┤
+│ 3. Does target folder exist?                                │
+│    NO  → Create it with proper Dewey Decimal prefix         │
+│    YES → Continue                                           │
+├─────────────────────────────────────────────────────────────┤
+│ 4. Create document with:                                    │
+│    → Correct naming convention                              │
+│    → Required frontmatter                                   │
+│    → Wiki-links to related documents                        │
+├─────────────────────────────────────────────────────────────┤
+│ 5. AFTER creating document:                                 │
+│    → Update parent folder's MOC file                        │
+│    → Update 000-Index.md if major document                  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Document Type Mapping
+
+| Category             | Document Type       | Target Folder                          | Naming Convention          |
+| -------------------- | ------------------- | -------------------------------------- | -------------------------- |
+| **010-Planning**     | Roadmap             | `docs/010-Planning/`                   | `Roadmap.md`               |
+|                      | OKRs                | `docs/010-Planning/`                   | `OKRs.md`                  |
+|                      | Sprint              | `docs/010-Planning/Sprints/`           | `Sprint-{NNN}.md`          |
+| **020-Requirements** | PRD                 | `docs/020-Requirements/`               | `PRD-{ProjectName}.md`     |
+|                      | BRD                 | `docs/020-Requirements/BRD/`           | `BRD-{NNN}-{Title}.md`     |
+|                      | Use Case            | `docs/020-Requirements/Use-Cases/`     | `UC-{NN}-{Title}.md`       |
+| **022-User-Stories** | Epic                | `docs/022-User-Stories/Epics/`         | `Epic-{Title}.md`          |
+|                      | User Story          | `docs/022-User-Stories/Backlog/`       | `Story-{Title}.md`         |
+|                      | Active Story        | `docs/022-User-Stories/Active-Sprint/` | `Story-{Title}.md`         |
+| **030-Specs**        | ADR                 | `docs/030-Specs/Architecture/`         | `ADR-{NNN}-{Title}.md`     |
+|                      | RFC                 | `docs/030-Specs/Architecture/`         | `RFC-{NNN}-{Title}.md`     |
+|                      | SDD (System Design) | `docs/030-Specs/Architecture/`         | `SDD-{ProjectName}.md`     |
+|                      | Technical Spec      | `docs/030-Specs/`                      | `Spec-{Feature}.md`        |
+|                      | API Endpoint Spec   | `docs/030-Specs/API/`                  | `Endpoint-{Name}.md`       |
+|                      | DB Schema           | `docs/030-Specs/Schema/`               | `DB-Entity-{Name}.md`      |
+| **035-QA**           | Test Plan           | `docs/035-QA/Test-Plans/`              | `MTP-{Name}.md`            |
+|                      | Test Case           | `docs/035-QA/Test-Cases/`              | `TC-{Feature}-{NNN}.md`    |
+| **040-Design**       | Design System       | `docs/040-Design/Design-System/`       | `{Component}.md`           |
+|                      | Wireframe           | `docs/040-Design/Wireframes/`          | `WF-{Screen}-{Device}.png` |
+| **050-Research**     | Research/Analysis   | `docs/050-Research/`                   | `Analysis-{Topic}.md`      |
+| **060-Manuals**      | User Guide          | `docs/060-Manuals/User-Guide/`         | `{Topic}.md`               |
+|                      | Admin Guide         | `docs/060-Manuals/Admin-Guide/`        | `{Topic}.md`               |
+| **090-Archive**      | Deprecated Docs     | `docs/090-Archive/`                    | `{Original-Name}.md`       |
+| **999-Resources**    | Meeting Notes       | `docs/999-Resources/Meeting-Notes/`    | `{Type}-{Date}.md`         |
+|                      | Glossary            | `docs/999-Resources/`                  | `Glossary.md`              |
+|                      | Template            | `docs/999-Resources/Templates/`        | `Template-{Type}.md`       |
+
+## Required Folder Structure
+
+```
+docs/
+├── 000-Index.md                        # "Home Page" - MUST exist
+│
+├── 010-Planning/                       # Strategy, Timelines, Roadmaps
+│   ├── Planning-MOC.md                 # REQUIRED MOC
+│   ├── Roadmap.md
+│   ├── OKRs.md
+│   └── Sprints/
+│
+├── 020-Requirements/                   # Business Requirements
+│   ├── Requirements-MOC.md             # REQUIRED MOC
+│   ├── BRD/
+│   └── Use-Cases/
+│
+├── 022-User-Stories/                   # Agile Backlog
+│   ├── Stories-MOC.md                  # REQUIRED MOC
+│   ├── Epics/
+│   ├── Active-Sprint/
+│   └── Backlog/
+│
+├── 030-Specs/                          # Technical Specs
+│   ├── Specs-MOC.md                    # REQUIRED MOC
+│   ├── Architecture/
+│   ├── API/
+│   └── Schema/
+│
+├── 035-QA/                             # Quality Assurance
+│   ├── QA-MOC.md                       # REQUIRED MOC
+│   ├── Test-Plans/
+│   ├── Test-Cases/
+│   ├── Automation/
+│   ├── Reports/
+│   └── Performance/
+│
+├── 040-Design/                         # UI/UX & Frontend
+│   ├── Design-MOC.md                   # REQUIRED MOC
+│   ├── Wireframes/
+│   ├── Design-System/
+│   ├── Specs/
+│   └── Assets/
+│
+├── 050-Research/                       # Discovery & Analysis
+│   ├── Research-MOC.md                 # REQUIRED MOC
+│   ├── Competitor-Analysis/
+│   └── User-Interviews/
+│
+├── 060-Manuals/                        # End-User Documentation
+│   ├── Manuals-MOC.md                  # REQUIRED MOC
+│   ├── User-Guide/
+│   └── Admin-Guide/
+│
+├── 090-Archive/                        # Deprecated docs (never delete)
+│
+└── 999-Resources/                      # Templates, Scripts, Glossary
+    ├── Templates/
+    ├── Glossary.md
+    └── Meeting-Notes/
+```
+
+## Frontmatter Template
+
+Every document MUST include this frontmatter:
+
+```yaml
+---
+id: {TYPE}-{NNN}           # Unique identifier (e.g., PRD-001, UC-01)
+type: {document_type}      # prd, brd, use-case, epic, story, spec, adr, etc.
+status: draft|review|approved|deprecated
+project: {project_name}    # Optional: for multi-project docs
+owner: @{team_or_person}   # Optional: responsible party
+tags: [tag1, tag2]         # Optional: for search/filtering
+linked-to: [[Related-Doc]] # Optional: primary relationship
+created: YYYY-MM-DD
+updated: YYYY-MM-DD        # Optional: last update date
+---
+```
+
+## Linking Rules
+
+1. **PRD** → links to Epics it spawns: `## Related Epics\n- [[Epic-Feature1]]\n- [[Epic-Feature2]]`
+2. **Epic** → links to parent PRD: `Implements: [[PRD-ProjectName]]`
+3. **Use Case** → links to Epic: `Part of: [[Epic-Feature]]`
+4. **SDD** → links to PRD: `Implements: [[PRD-ProjectName]]`
+5. **ADR** → links to SDD: `Related to: [[SDD-ProjectName]]`
+
+## Validation Checklist
+
+Before finalizing any document, verify:
+
+- [ ] Document is in correct `docs/XXX-Category/` folder
+- [ ] Filename follows naming convention from mapping table
+- [ ] Frontmatter includes required fields (id, type, status, created)
+- [ ] Wiki-links to related documents are added
+- [ ] Parent folder's MOC file is updated with link to new document
+- [ ] 000-Index.md updated (for major documents like PRD, SDD)

package/.agent/rules/nano-banana.md

@@ -0,0 +1,46 @@
+---
+trigger: model_decision
+description: Apply this rule when generating images, icons, or visual assets using generate_image tool.
+---
+
+# Generate Image Usage Guide
+
+## 1. The Prompting Formula
+
+To maximize image quality, ALWAYS structure your prompt using this progression. Do not just send a raw description.
+
+**`[Core Subject]` + `[Visual Style]` + `[Lighting/Color]` + `[Technical/Quality specs]`**
+
+### Examples:
+
+- **Bad**: "A robot"
+- **Good**: "Cute round robot avatar, flat vector art style, soft indigo and white lighting, minimal UI icon, high resolution"
+
+- **Bad**: "Dashboard background"
+- **Good**: "Abstract geometric patterns, soft cyberpunk aesthetic, dark slate and neon blue dark mode, subtle texture, 4k wallpaper"
+
+## 2. Capability & Constraints
+
+- **Naming**: You **MUST** use `snake_case` with a maximum of **3 words**.
+  - ✅ `hero_robot_icon`
+  - ❌ `HeroRobotIcon` (CamelCase not allowed)
+  - ❌ `blue_hero_robot_floating_in_space` (Too long)
+- **Text Handling**: The tool cannot render legible text. **NEVER** ask for text inside the image (e.g., "A button that says Start"). Request the _button shape_ only.
+- **Composition**: It excels at single objects (Icons, Avatars) and abstract backgrounds. It struggles with complex multi-character scenes or precise UI layouts.
+
+## 3. High-Leverage Keywords
+
+Use these specific keywords to steer the model towards specific outcomes:
+
+| Goal            | Keywords to Inject                                                                                 |
+| :-------------- | :------------------------------------------------------------------------------------------------- |
+| **UI Icons**    | `vector icon`, `flat design`, `minimalist`, `app icon`, `white background`, `svg style`            |
+| **Game Assets** | `game sprite`, `isometric view`, `digital painting`, `character concept`, `unreal engine 5 render` |
+| **Backgrounds** | `abstract`, `bokeh`, `gradient`, `blur`, `texture`, `wallpaper`, `geometric`                       |
+| **Styling**     | `soft lighting`, `cinematic`, `volumetric light`, `rule of thirds`, `ultra detailed`               |
+
+## 4. Operational Best Practices
+
+1.  **One Concept per Request**: Don't try to generate a "Dashboard with a sidebar and a chart". Generate the "Sidebar background" and the "Chart graphic" separately.
+2.  **Color Accuracy**: Use descriptive color names ("Emerald Green", "Midnight Blue") rather than just Hex codes, as models understand names better visually.
+3.  **Iteration**: If the first specific result isn't perfect, generalize the prompt slightly (remove strict constraints) and try again.

package/.agent/skills/ai-engineer/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: ai-engineer
+description: AI Engineer role. Focuses on integrating AI models, building RAG pipelines, and optimizing prompts. Loads specific AI modality guides.
+license: MIT
+metadata:
+  role: AI Engineer
+  version: "1.0"
+---
+
+# AI Engineer
+
+You build intelligence into the application.
+
+## Core Responsibilities
+
+1.  **Model Integration**: Connecting LLMs to Logic.
+2.  **Context Management**: RAG, Vector Search, Memory.
+3.  **Evaluation**: Testing AI quality.
+
+## Dynamic Stack Loading
+
+- **LLMs & RAG**: [Read specific guide](references/llm.md)
+- **MLOps**: (Create `references/mlops.md` if needed)

package/.agent/skills/ai-engineer/references/llm.md

@@ -0,0 +1,13 @@
+# Tech: LLMs & RAG
+
+## Stack
+
+- **SDK**: Vercel AI SDK or LangChain.
+- **Model**: GPT-4o, Claude 3.5 Sonnet.
+- **Vector DB**: Supabase `pgvector`.
+
+## Best Practices
+
+- **Streaming**: Always stream responses using `AIStream`.
+- **Prompts**: Version control your system prompts.
+- **Embeddings**: Normalize text before embedding.

package/.agent/skills/backend-developer/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: backend-developer
+description: Expert Senior Backend Engineer (Polyglot). Focuses on Architecture, API Design, Security, and Scalability across Node, Python, Go, and Java. Strictly follows official documentation and architectural patterns.
+license: MIT
+metadata:
+  role: Senior Backend Engineer
+  version: "2.0"
+  capabilities:
+    ["API Design", "System Architecture", "Security", "Polyglot Development"]
+  languages: ["Node.js", "Python", "Go", "Java", "Kotlin"]
+  databases: ["PostgreSQL", "MongoDB", "Redis"]
+---
+
+# Backend Developer (Expert Polyglot)
+
+You are an **Expert Senior Backend Engineer** with 20+ years of experience. You specialize in building robust, scalable, and secure distributed systems.
+
+**CORE PHILOSOPHY:**
+
+1.  **Documentation is Truth**: Never guess syntax or patterns. If unsure, search official docs (`search_web`, `context7`).
+2.  **Security First**: Every input is malicious until validated. Every endpoint needs explicit AuthN/AuthZ.
+3.  **Simplicity**: Prefer boring technology that works. Complexity must be justified.
+
+## 1. Dynamic Context Loading
+
+**CRITICAL STEP**: Before helping the user, you MUST identify the specific technology stack.
+
+**Logic:**
+
+1.  Check the user's request and open files.
+2.  **Load the relevant references** using `view_file`.
+
+| Detected Stack                | Files to Load                    |
+| :---------------------------- | :------------------------------- |
+| **Architectural / DB Design** | `references/general-patterns.md` |
+| **Node.js (Express)**         | `references/node-express.md`     |
+| **Node.js (NestJS)**          | `references/node-nestjs.md`      |
+| **Python (Django)**           | `references/python-django.md`    |
+| **Python (FastAPI)**          | `references/python-fastapi.md`   |
+| **Go (Gin)**                  | `references/go-gin.md`           |
+| **Go (Echo)**                 | `references/go-echo.md`          |
+| **Java (Spring Boot)**        | `references/java-springboot.md`  |
+
+> [!NOTE]
+> If the user asks a general question (e.g., "How do I secure my API?"), load `references/general-patterns.md`.
+
+## 2. Core Responsibilities
+
+### A. API Design (Contract First)
+
+- **REST**: Use clear resource naming (Plural nouns), standard status codes.
+- **GraphQL**: Schema-first design.
+- **Documentation**: All APIs must be documented (OpenAPI/Swagger).
+
+### B. Database Design
+
+- **Schema**: 3rd Normal Form for Relational. Access-pattern driven for NoSQL.
+- **Indexes**: Mandatory for foreign keys and query predicates.
+- **Migrations**: Database changes must be versioned and reversible.
+
+### C. Security (Zero Trust)
+
+- **Validation**: Use strict schema validation (Zod, Pydantic, Joi) at the entry point.
+- **Auth**: JWT for stateless, Sessions for stateful. Always validate scopes/permissions.
+- **Secrets**: NEVER hardcode secrets. Use Environment Variables.
+
+### D. Testing (Confidence)
+
+- **Unit**: Test logic in isolation. Mock dependencies.
+- **Integration**: Test DB interactions and API endpoints.
+
+## 3. Workflow for New Features
+
+1.  **Requirements**: Understand the data flow and constraints.
+2.  **Design**: Draft the API contract and DB schema.
+3.  **Implementation**:
+    - Create DTOs/Validators.
+    - Implement Service Layer (Business Logic).
+    - Implement Controller/Handler (HTTP Layer).
+4.  **Verification**: Write tests (Happy path + Edge cases).
+
+## 4. Collaboration with Lead Architect
+
+**CRITICAL**: For high-stakes Architectural, Security, or Database Design decisions, you **MUST** align with the `lead-architect` skill.
+
+**When to consult Lead Architect References:**
+
+1.  **System Design**: Deciding between Monolith vs. Microservices.
+2.  **Complex Security**: Implementing Zero Trust, complex OAuth2/OIDC flows, or Threat Modeling.
+3.  **Process**: Defining CI/CD standards or DORA metrics.
+
+**Action**: If the user asks for these, load the relevant `lead-architect` reference (e.g., `.agent/skills/lead-architect/references/system-architecture.md`) OR advise the user to "Consult the Lead Architect skill".
+
+## 5. Interaction Rules
+
+- **Code Reviews**: Be pedantic about security, performance (N+1 queries), and readability.
+- **Explanations**: Explain _WHY_ an architectural decision was made (Trade-offs).
+- **Unknowns**: If you encounter a library or tool you don't know detailed syntax for, utilize `search_web` or `context7` immediately.

package/.agent/skills/backend-developer/references/general-patterns.md

@@ -0,0 +1,65 @@
+# General Backend Patterns & Architecture
+
+# General Backend Patterns & Architecture
+
+> [!NOTE]
+> This guide covers **Applied Architecture** (Implementation details). For high-level System Design, Decision Records (ADRs), and detailed Cloud Infrastructure, refer to the **[Lead Architect Skill](../lead-architect/SKILL.md)**.
+
+This reference covers universal principles applicable across all languages and frameworks.
+
+## 1. Architectural Patterns
+
+### Clean Architecture / Hexagonal / Onion
+
+Separation of concerns is paramount.
+
+- **Domain Layer**: Pure business logic. No dependencies on frameworks or DBs.
+- **Application Layer**: Use cases / Services. Orchestrates the domain.
+- **Adapters (Interface) Layer**: Controllers, API Handlers, CLI.
+- **Infrastructure Layer**: DB Implementations, External APIs.
+
+### Domain-Driven Design (DDD)
+
+- **Entities**: Objects with identity (e.g., User, Order).
+- **Value Objects**: Immutable objects defined by attributes (e.g., Email, Money).
+- **Aggregates**: Clusters of objects treated as a unit (Order + OrderItems).
+- **Repositories**: Interface for collection-like access to Aggregates.
+
+## 2. Database Design
+
+### Relational (PostgreSQL, MySQL)
+
+- **Naming**: `snake_case` for tables and columns. Plural table names (`users`, `orders`).
+- **Primary Keys**: Use UUIDs (v7 preferred for sorting) or BigInt. Avoid auto-increment for distributed systems.
+- **Foreign Keys**: Always define constraints. Index FK columns.
+- **Transactions**: Use transactions for atomic operations involving multiple writes.
+
+### NoSQL (MongoDB)
+
+- **Embedding vs. Referencing**:
+  - **Embed**: Used together, read together, low cardinality (e.g., OrderItems in Order).
+  - **Reference**: High cardinality, updated independently (e.g., User in Order).
+- **Schema Validation**: Use JSON Schema validation on the collection level.
+
+### Caching (Redis)
+
+- **Cache-Aside (Lazy Loading)**: App checks cache -> Miss -> Read DB -> Set Cache.
+- **TTL**: Always set a Time-To-Live. avoid permanent keys unless necessary.
+- **Keys**: Use namespaced keys `app:resource:id` (e.g., `shop:product:123`).
+
+## 3. Security Best Practices (OWASP)
+
+> **Advanced Security**: For Threat Modeling, Zero Trust Architecture, and compliance auditing, see `lead-architect/references/infrastructure.md`.
+
+- **Injection**: Use parameterized queries (SQL) or ORMs. Never string concat user input.
+- **Auth**:
+  - **Passwords**: Bcrypt, Argon2. Never MD5/SHA1.
+  - **JWT**: Short-lived access tokens (15m), Long-lived refresh tokens.
+- **Rate Limiting**: Implement Global and Per-User rate limits (Redis Token Bucket).
+- **CORS**: Restrict `Access-Control-Allow-Origin` to known domains.
+
+## 4. Scalability
+
+- **Statelessness**: Application servers should be stateless. Store session data in Redis.
+- **Async Processing**: Offload heavy tasks (Email, Image Processing) to message queues (RabbitMQ, Kafka, BullMQ, Celery).
+- **Idempotency**: API endpoints (especially POST/payment) should handle duplicate requests gracefully.

package/.agent/skills/backend-developer/references/go-echo.md

@@ -0,0 +1,68 @@
+# Go - Echo Best Practices
+
+**Official Documentation**: [echo.labstack.com](https://echo.labstack.com/)
+
+## 1. Golden Rules
+
+1.  **Interfaces**: Define interfaces for your Services and Repositories to make handlers testable.
+2.  **Middleware**: Use Echo's robust middleware suite (Recover, Logger, CORS).
+3.  **Error Handling**: Use `echo.NewHTTPError` to return standard errors that middleware can log.
+
+## 2. Folder Structure
+
+Common Domain-Driven structure.
+
+```
+cmd/server/main.go
+internal/
+├── user/
+│   ├── delivery/
+│   │   └── http/
+│   │       └── handler.go
+│   ├── usecase/
+│   │   └── service.go
+│   ├── repository/
+│   │   └── pg_repo.go
+│   └── domain.go      # Interface definitions & Models
+pkg/
+└── database/
+```
+
+## 3. Code Patterns
+
+### Handlers
+
+Bind and Validate in one step if using custom validator.
+
+```go
+type UserDTO struct {
+    Email string `json:"email" validate:"required,email"`
+    Name  string `json:"name" validate:"required"`
+}
+
+func (h *UserHandler) Register(c echo.Context) error {
+    ctx := c.Request().Context()
+    var user UserDTO
+    if err := c.Bind(&user); err != nil {
+        return echo.NewHTTPError(http.StatusBadRequest, err.Error())
+    }
+    if err := c.Validate(&user); err != nil {
+        return echo.NewHTTPError(http.StatusBadRequest, err.Error())
+    }
+
+    // Call usecase...
+    return c.JSON(http.StatusCreated, user)
+}
+```
+
+## 4. Security
+
+- **Middleware**: Always Include `middleware.Recover()` and `middleware.Logger()`.
+- **CORS**: Be specific.
+
+```go
+e.Use(middleware.CORSWithConfig(middleware.CORSConfig{
+  AllowOrigins: []string{"https://labstack.com"},
+  AllowHeaders: []string{echo.HeaderOrigin, echo.HeaderContentType, echo.HeaderAccept},
+}))
+```

package/.agent/skills/backend-developer/references/go-gin.md

@@ -0,0 +1,76 @@
+# Go - Gin Best Practices
+
+**Official Documentation**: [gin-gonic.com](https://gin-gonic.com/)
+
+## 1. Golden Rules
+
+1.  **Error Handling**: Go has no exceptions. Return errors explicitly. Use custom error types/constants.
+2.  **Context**: Always pass `context.Context` to DB and Service layers for timeout/cancellation control.
+3.  **Structure**: Avoid global variables. Use dependency injection (manual or fx) for handlers.
+
+## 2. Folder Structure (Standard Go Layout)
+
+Based on [golang-standards/project-layout](https://github.com/golang-standards/project-layout)
+
+```
+cmd/
+└── api/
+    └── main.go           # Entry point
+internal/
+├── domain/               # Enterprise logic (Entities, Interfaces)
+│   └── user.go
+├── handler/              # HTTP Handlers (Gin specific)
+│   └── user_handler.go
+├── service/              # Business Logic (Implementation of Interfaces)
+│   └── user_service.go
+└── repository/           # DB Access (Implementation of Interfaces)
+    └── postgres/
+        └── user_repo.go
+pkg/                      # Publicly sharable code
+└── utils/
+go.mod
+```
+
+## 3. Code Patterns
+
+### Validation (Binding)
+
+Use `binding` tag (validator v10) in structs.
+
+```go
+type CreateUserRequest struct {
+    Email    string `json:"email" binding:"required,email"`
+    Password string `json:"password" binding:"required,min=8"`
+}
+
+func (h *UserHandler) Create(c *gin.Context) {
+    var req CreateUserRequest
+    if err := c.ShouldBindJSON(&req); err != nil {
+        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+        return
+    }
+    // ... call service
+}
+```
+
+### DB Access (GORM or sqlc)
+
+- **GORM**: Good for rapid dev.
+- **sqlc**: Generates type-safe code from SQL. Preferred for performance/control.
+
+```go
+// Direct SQL/sqlc style is clearer than complex ORM magic
+func (r *UserRepository) GetByID(ctx context.Context, id int64) (*domain.User, error) {
+    row := r.db.QueryRowContext(ctx, "SELECT id, email FROM users WHERE id = $1", id)
+    var u domain.User
+    if err := row.Scan(&u.ID, &u.Email); err != nil {
+        return nil, err
+    }
+    return &u, nil
+}
+```
+
+## 4. Security
+
+- **Gin Mode**: Set `GIN_MODE=release` in production.
+- **Trusted Proxies**: Configure `router.SetTrustedProxies()` if behind Nginx/LoadBalancer.