@jhm1909/ag-kit 0.1.0

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.

package/.agent/skills/backend-developer/references/java-springboot.md

@@ -0,0 +1,83 @@
+# Java - Spring Boot Best Practices
+
+**Official Documentation**: [spring.io/projects/spring-boot](https://spring.io/projects/spring-boot) - The Enterprise Standard.
+
+## 1. Golden Rules
+
+1.  **Annotations**: Rely on Spring magic (`@Service`, `@Repository`, `@Transactional`). Don't fight the framework.
+2.  **Lombok**: Use Lombok (`@Data`, `@Builder`, `@RequiredArgsConstructor`) to reduce boilerplate.
+3.  **Layered Architecture**: Controller -> Service -> Repository. Never call Repository from Controller.
+
+## 2. Folder Structure (Maven/Gradle Standard)
+
+```
+src/main/java/com/example/project/
+├── config/              # SecurityConfig, AppConfig
+├── controller/          # REST Endpoints
+│   └── UserController.java
+├── service/             # Business Logic
+│   └── UserService.java
+├── repository/          # JPA Repositories
+│   └── UserRepository.java
+├── model/               # JPA Entities
+│   └── User.java
+├── dto/                 # Data Transfer Objects
+│   └── UserDTO.java
+└── exception/           # Global Exception Handling
+```
+
+## 3. Code Patterns
+
+### Validation (Bean Validation)
+
+Use `jakarta.validation` annotations on DTOs.
+
+```java
+@Data
+public class UserDTO {
+    @NotNull
+    @Email
+    private String email;
+
+    @Size(min = 8)
+    private String password;
+}
+
+// Controller
+@PostMapping
+public ResponseEntity<User> create(@Valid @RequestBody UserDTO userDto) {
+    // ...
+}
+```
+
+### Database (Spring Data JPA)
+
+Define Interfaces extending `JpaRepository`.
+
+```java
+public interface UserRepository extends JpaRepository<User, Long> {
+    Optional<User> findByEmail(String email);
+
+    @Query("SELECT u FROM User u WHERE u.isActive = true")
+    List<User> findAllActive();
+}
+```
+
+## 4. Security (Spring Security)
+
+- **Configuration**: Use `SecurityFilterChain` bean (Modern Spring Security 6+).
+- **Passwords**: `BCryptPasswordEncoder` is the standard.
+
+```java
+@Bean
+public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
+    http
+        .csrf(csrf -> csrf.disable()) // For stateless REST APIs
+        .sessionManagement(sess -> sess.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
+        .authorizeHttpRequests(auth -> auth
+            .requestMatchers("/api/auth/**").permitAll()
+            .anyRequest().authenticated()
+        );
+    return http.build();
+}
+```

package/.agent/skills/backend-developer/references/node-express.md

@@ -0,0 +1,64 @@
+# Node.js - Express.js Best Practices
+
+**Official Documentation**: [expressjs.com](https://expressjs.com/) - Consult for Middleware syntax and Router API.
+
+## 1. Golden Rules
+
+1.  **Always use Async/Await**: Avoid strict callbacks. Use `express-async-errors` (or Node 20+ support) to handle async errors globally.
+2.  **Environment Variables**: Never hardcode config. Use strict parsing (e.g., `dotenv` + `envalid`/`zod`).
+3.  **Middleware Order**: Global Middleware (Cors/Helmet) -> Routes -> 404 Handler -> Global Error Handler.
+
+## 2. Folder Structure (Feature-based)
+
+```
+src/
+├── config/             # Environment variables & constants
+├── modules/            # Feature modules
+│   ├── users/
+│   │   ├── users.controller.ts  # Route definitions
+│   │   ├── users.service.ts     # Business logic
+│   │   ├── users.repository.ts  # DB access (TypeORM/Prisma)
+│   │   └── dtos/                # Validation classes
+│   └── auth/
+├── shared/             # Shared utilities, middlewares, guards
+│   ├── middlewares/
+│   └── utils/
+├── app.ts              # App cleanup & middleware setup
+└── server.ts           # Entry point
+```
+
+## 3. Code Patterns
+
+### Validation (Zod)
+
+Use Zod for strict runtime validation of request bodies.
+
+```typescript
+import { z } from "zod";
+
+export const CreateUserSchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),
+});
+
+// Use in middleware...
+```
+
+### Error Handling
+
+Centralize error handling with a custom Error class.
+
+```typescript
+// middleware/error.middleware.ts
+export const errorHandler = (err, req, res, next) => {
+  const statusCode = err.statusCode || 500;
+  const message = err.message || "Internal Server Error";
+  res.status(statusCode).json({ status: "error", message });
+};
+```
+
+## 4. Security (Helmet & CORS)
+
+- **Helmet**: Mandatory. `app.use(helmet())`.
+- **CORS**: whitelist specific origins.
+- **Rate Limit**: `express-rate-limit` for public endpoints.

package/.agent/skills/backend-developer/references/node-nestjs.md

@@ -0,0 +1,69 @@
+# Node.js - NestJS Best Practices
+
+**Official Documentation**: [docs.nestjs.com](https://docs.nestjs.com/) - This is the BIBLE. Follow it strictly.
+
+## 1. Golden Rules
+
+1.  **Dependency Injection (DI)**: Everything is a Provider (Injectable). Never instantiate services manually with `new Service()`.
+2.  **Modules**: Organize code by domain `Modules` (UserModule, AuthModule). Use `SharedModule` for utilities.
+3.  **DTOs**: Use Classes with `class-validator` decorators for all inputs.
+
+## 2. Folder Structure (Standard NestJS)
+
+```
+src/
+├── app.module.ts       # Root module
+├── main.ts             # Entry point
+├── modules/
+│   ├── users/
+│   │   ├── users.module.ts
+│   │   ├── users.controller.ts
+│   │   ├── users.service.ts
+│   │   └── dto/
+│   │       └── create-user.dto.ts
+│   └── auth/
+└── common/             # Interceptors, Filters, Guards, Decorators
+    ├── filters/
+    ├── guards/
+    └── pipes/
+```
+
+## 3. Code Patterns
+
+### Validation (Pipes)
+
+Enable global validation pipe in `main.ts`.
+
+```typescript
+// main.ts
+app.useGlobalPipes(
+  new ValidationPipe({
+    whitelist: true, // Strip properties not in DTO
+    forbidNonWhitelisted: true, // Throw error if extra props sent
+    transform: true, // Auto-transform payloads to DTO instances
+  }),
+);
+```
+
+### Configuration
+
+Use `@nestjs/config` for environment variables. Ensure validation with `joi` or custom validate function.
+
+```typescript
+ConfigModule.forRoot({
+  isGlobal: true,
+  validationSchema: Joi.object({
+    DATABASE_URL: Joi.string().required(),
+  }),
+});
+```
+
+### Database (TypeORM / Prisma)
+
+- **Prisma**: Preferred for type-safety. Create a `PrismaService` extending `PrismaClient` and `OnModuleInit`.
+- **TypeORM**: Use standard Repository pattern provided by `@nestjs/typeorm`.
+
+## 4. Security
+
+- **Guards**: Use `@UseGuards(JwtAuthGuard)` for protected routes.
+- **Interceptors**: Use `ClassSerializerInterceptor` to automatically exclude `@Exclude()` fields (like password) from responses.

package/.agent/skills/backend-developer/references/python-django.md

@@ -0,0 +1,67 @@
+# Python - Django Best Practices
+
+**Official Documentation**: [docs.djangoproject.com](https://docs.djangoproject.com/) - The gold standard of documentation.
+
+## 1. Golden Rules
+
+1.  **Batteries Included**: Use reliable built-in features (Auth, Admin, ORM) before 3rd party libs.
+2.  **Fat Models, Thin Views**: Put business logic in Models or separate Service layer (`services.py`), not in Views.
+3.  **Class Based Views (CBV) vs DRF**: For APIs, use **Django Rest Framework (DRF)**.
+
+## 2. Folder Structure (Standard Layout)
+
+```
+project_root/
+├── manage.py
+├── config/             # Project settings (replaces default 'project_name' folder)
+│   ├── settings.py
+│   ├── urls.py
+│   └── wsgi.py
+├── apps/               # Functionality based apps
+│   ├── users/
+│   │   ├── models.py
+│   │   ├── serializers.py  # DRF DTOs
+│   │   ├── views.py
+│   │   ├── urls.py
+│   │   └── services.py     # Business logic
+│   └── products/
+└── requirements.txt
+```
+
+## 3. Code Patterns (DRF)
+
+### Serializers (Validation)
+
+Use `ModelSerializer` for DB-backed APIs, `Serializer` for non-DB inputs.
+
+```python
+from rest_framework import serializers
+from .models import User
+
+class UserSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = User
+        fields = ['id', 'email', 'username']
+        read_only_fields = ['id']
+```
+
+### Views (ViewSets)
+
+Prefer `ModelViewSet` for standard CRUD. Use `APIView` for custom logic.
+
+```python
+from rest_framework import viewsets
+from .models import User
+from .serializers import UserSerializer
+
+class UserViewSet(viewsets.ModelViewSet):
+    queryset = User.objects.all()
+    serializer_class = UserSerializer
+    permission_classes = [IsAuthenticated]
+```
+
+## 4. Security
+
+- **Settings**: `DEBUG = False` in production.
+- **Secrets**: Use `python-decouple` or `django-environ` for `.env` files.
+- **Middleware**: `SecurityMiddleware`, `CsrfViewMiddleware` (automatically included, do not remove).

package/.agent/skills/backend-developer/references/python-fastapi.md

@@ -0,0 +1,80 @@
+# Python - FastAPI Best Practices
+
+**Official Documentation**: [fastapi.tiangolo.com](https://fastapi.tiangolo.com/) - Essential for Pydantic models and Dependency Injection.
+
+## 1. Golden Rules
+
+1.  **Strict Pydantic Models**: Every Request body and Response model must be a Pydantic schema.
+2.  **Dependency Injection**: Use `Depends` for Database sessions, Auth, and Services.
+3.  **Async/Await**: Use `async def` for I/O bound operations (DB, API calls). Use `def` for CPU bound to run in threadpool.
+
+## 2. Folder Structure
+
+```
+src/
+├── app/
+│   ├── api/                # Router/Endpoints
+│   │   ├── v1/
+│   │       ├── endpoints/
+│   │           ├── users.py
+│   │           └── login.py
+│   ├── core/               # Config, Security, Events
+│   │   ├── config.py
+│   │   └── security.py
+│   ├── crud/               # DB operations (Repository pattern)
+│   │   └── crud_user.py
+│   ├── models/             # SQLAlchemy/SQLModel tables
+│   │   └── user.py
+│   ├── schemas/            # Pydantic models (DTOs)
+│   │   └── user.py
+│   └── main.py
+└── algembic/                 # Migrations
+```
+
+## 3. Code Patterns
+
+### Validation (Pydantic)
+
+Separate `Base`, `Create`, `Update`, and `Response` schemas.
+
+```python
+from pydantic import BaseModel, EmailStr
+
+class UserBase(BaseModel):
+    email: EmailStr
+    is_active: bool = True
+
+class UserCreate(UserBase):
+    password: str
+
+class UserResponse(UserBase):
+    id: int
+    class Config:
+        from_attributes = True # for ORM compatibility
+```
+
+### Dependency Injection (DB Session)
+
+```python
+# deps.py
+def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+
+# usage in route
+@router.post("/", response_model=schemas.UserResponse)
+def create_user(
+    user: schemas.UserCreate,
+    db: Session = Depends(get_db)
+):
+    return crud.create_user(db=db, user=user)
+```
+
+## 4. Security
+
+- **OAuth2**: Use `FastAPI.security.OAuth2PasswordBearer` for standard flows.
+- **Password Hashing**: Use `passlib[bcrypt]`.
+- **CORS**: `CORSMiddleware` configured in `main.py`.