oh-my-customcode 0.1.2 → 0.1.3

package/templates/agents/sw-engineer/backend/fastapi-expert/refs/fastapi/best-practices.md

@@ -0,0 +1,232 @@
+# FastAPI Best Practices
+
+> Source: https://fastapi.tiangolo.com/ and community patterns
+
+## Project Structure
+
+Organize by domain, not by file type:
+
+```
+src/
+├── auth/
+│   ├── router.py       # API endpoints
+│   ├── schemas.py      # Pydantic models
+│   ├── models.py       # Database models
+│   ├── service.py      # Business logic
+│   ├── dependencies.py # Route validators
+│   └── exceptions.py   # Custom exceptions
+├── users/
+│   └── ...
+├── config.py
+└── main.py
+```
+
+## Async Best Practices
+
+### I/O-Intensive Tasks
+
+```python
+# Use async def with await for non-blocking I/O
+async def fetch_user(user_id: int) -> User:
+    async with httpx.AsyncClient() as client:
+        response = await client.get(f"/api/users/{user_id}")
+        return User(**response.json())
+```
+
+### Sync I/O Operations
+
+```python
+# Use regular def - FastAPI offloads to threadpool
+def read_config() -> dict:
+    with open("config.yaml") as f:
+        return yaml.safe_load(f)
+```
+
+### CPU-Intensive Tasks
+
+```python
+# Use separate worker processes
+from celery import Celery
+
+celery_app = Celery("tasks", broker="redis://localhost")
+
+@celery_app.task
+def process_data(data: dict) -> dict:
+    # Heavy computation
+    return result
+```
+
+### Never Do This
+
+```python
+# WRONG: Blocks event loop
+async def bad_example():
+    time.sleep(5)  # Never use time.sleep in async!
+
+# CORRECT: Use asyncio.sleep
+async def good_example():
+    await asyncio.sleep(5)
+```
+
+## Pydantic Models
+
+### Custom Base Model
+
+```python
+from pydantic import BaseModel
+from datetime import datetime
+
+class AppBaseModel(BaseModel):
+    class Config:
+        from_attributes = True
+        json_encoders = {
+            datetime: lambda v: v.isoformat()
+        }
+
+class UserResponse(AppBaseModel):
+    id: int
+    email: str
+    created_at: datetime
+```
+
+### Validation
+
+```python
+from pydantic import BaseModel, EmailStr, Field, validator
+
+class UserCreate(BaseModel):
+    email: EmailStr
+    password: str = Field(..., min_length=8)
+    age: int = Field(..., ge=18, le=120)
+
+    @validator("password")
+    def password_strength(cls, v):
+        if not any(c.isupper() for c in v):
+            raise ValueError("Password must contain uppercase")
+        return v
+```
+
+## Dependencies
+
+### Authentication
+
+```python
+from fastapi import Depends, HTTPException
+from fastapi.security import OAuth2PasswordBearer
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
+
+async def get_current_user(
+    token: str = Depends(oauth2_scheme),
+    db: AsyncSession = Depends(get_db)
+) -> User:
+    user = await verify_token(token, db)
+    if not user:
+        raise HTTPException(status_code=401)
+    return user
+
+async def get_active_user(
+    user: User = Depends(get_current_user)
+) -> User:
+    if not user.is_active:
+        raise HTTPException(status_code=403)
+    return user
+```
+
+### Database Session
+
+```python
+from sqlalchemy.ext.asyncio import AsyncSession
+
+async def get_db() -> AsyncGenerator[AsyncSession, None]:
+    async with async_session() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+```
+
+## Error Handling
+
+```python
+# Custom exceptions
+class AuthException(Exception):
+    pass
+
+class InvalidCredentials(AuthException):
+    pass
+
+# Exception handler
+@app.exception_handler(AuthException)
+async def auth_exception_handler(request, exc):
+    return JSONResponse(
+        status_code=401,
+        content={"detail": str(exc)}
+    )
+
+# In router
+@router.post("/login")
+async def login(credentials: LoginSchema):
+    try:
+        return await auth_service.login(credentials)
+    except InvalidCredentials:
+        raise HTTPException(status_code=401, detail="Invalid credentials")
+```
+
+## API Design
+
+```python
+from fastapi import APIRouter
+
+router = APIRouter(
+    prefix="/users",
+    tags=["users"]
+)
+
+@router.get(
+    "/{user_id}",
+    response_model=UserResponse,
+    summary="Get user by ID",
+    responses={
+        404: {"model": ErrorResponse, "description": "User not found"}
+    }
+)
+async def get_user(
+    user_id: int,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+) -> UserResponse:
+    """
+    Get a specific user by their ID.
+
+    - **user_id**: The unique identifier of the user
+    """
+    user = await user_service.get(db, user_id)
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+    return user
+```
+
+## Testing
+
+```python
+import pytest
+from httpx import AsyncClient
+from main import app
+
+@pytest.fixture
+async def client():
+    async with AsyncClient(app=app, base_url="http://test") as ac:
+        yield ac
+
+@pytest.mark.asyncio
+async def test_create_user(client: AsyncClient):
+    response = await client.post(
+        "/users/",
+        json={"email": "test@example.com", "password": "Password123"}
+    )
+    assert response.status_code == 201
+    assert response.json()["email"] == "test@example.com"
+```

package/templates/agents/sw-engineer/backend/fastapi-expert/refs/fastapi/index.yaml

@@ -0,0 +1,21 @@
+# FastAPI Guide
+
+metadata:
+  name: fastapi
+  description: FastAPI framework reference documentation
+
+source:
+  type: external
+  origin: fastapi.tiangolo.com
+  urls:
+    - https://fastapi.tiangolo.com/
+    - https://github.com/zhanymkanov/fastapi-best-practices
+  last_fetched: "2026-01-22"
+
+documents:
+  - name: best-practices
+    path: ./best-practices.md
+    description: FastAPI best practices and patterns
+
+used_by:
+  - fastapi-expert

package/templates/agents/sw-engineer/backend/fastapi-expert/refs/fastapi-best-practices/SKILL.md

@@ -0,0 +1,269 @@
+# FastAPI Best Practices Skill
+
+> **Category**: Backend
+> **Source**: Internal (based on FastAPI docs and community patterns)
+
+## Purpose
+
+Apply FastAPI patterns for building high-performance async APIs.
+
+## Rules
+
+### 1. Project Structure
+
+```yaml
+structure:
+  domain_based: true
+  module_contents:
+    - router.py: API endpoints
+    - schemas.py: Pydantic models
+    - models.py: Database models
+    - service.py: Business logic
+    - dependencies.py: Route validators
+    - constants.py: Module constants
+    - config.py: Module configuration
+    - exceptions.py: Custom exceptions
+    - utils.py: Helper functions
+
+imports:
+  style: explicit
+  example: "from src.auth import constants as auth_constants"
+
+layout: |
+  src/
+  ├── auth/
+  │   ├── router.py
+  │   ├── schemas.py
+  │   ├── models.py
+  │   ├── service.py
+  │   └── dependencies.py
+  ├── users/
+  │   └── ...
+  ├── config.py
+  └── main.py
+```
+
+### 2. Async Patterns
+
+```yaml
+io_intensive:
+  use: "async def"
+  await: "asyncio.sleep(), httpx, asyncpg, etc."
+  example: |
+    async def fetch_data():
+        async with httpx.AsyncClient() as client:
+            response = await client.get(url)
+            return response.json()
+
+sync_io:
+  use: "def (regular function)"
+  reason: FastAPI offloads to threadpool automatically
+  example: |
+    def read_file():
+        with open('file.txt') as f:
+            return f.read()
+
+cpu_intensive:
+  avoid: async and threadpool
+  use: separate worker processes
+  example: "Use Celery or multiprocessing"
+
+never:
+  - "time.sleep() in async functions"
+  - "Blocking I/O in async functions"
+```
+
+### 3. Pydantic Models
+
+```yaml
+validation:
+  use_builtin: regex, enums, email, URL validators
+  custom_validators: for complex logic
+
+base_model:
+  create_custom: true
+  purpose: enforce application-wide standards
+  example: |
+    from pydantic import BaseModel
+    from datetime import datetime
+
+    class AppBaseModel(BaseModel):
+        class Config:
+            from_attributes = True
+            json_encoders = {
+                datetime: lambda v: v.isoformat()
+            }
+
+settings:
+  split: across modules
+  avoid: single global configuration
+  example: |
+    # auth/config.py
+    class AuthSettings(BaseSettings):
+        jwt_secret: str
+        jwt_algorithm: str = "HS256"
+
+    # database/config.py
+    class DatabaseSettings(BaseSettings):
+        url: str
+        pool_size: int = 5
+```
+
+### 4. Dependencies
+
+```yaml
+usage:
+  - Dependency injection
+  - Validation against database
+  - Authentication/authorization
+  - Request scoped caching
+
+patterns:
+  chain: avoid code repetition
+  cache: FastAPI caches within request scope
+  decouple: small, reusable functions
+
+example: |
+  async def get_current_user(
+      token: str = Depends(oauth2_scheme),
+      db: Session = Depends(get_db)
+  ) -> User:
+      user = await db.get_user_by_token(token)
+      if not user:
+          raise HTTPException(status_code=401)
+      return user
+
+  async def get_active_user(
+      user: User = Depends(get_current_user)
+  ) -> User:
+      if not user.is_active:
+          raise HTTPException(status_code=403)
+      return user
+```
+
+### 5. Error Handling
+
+```yaml
+custom_exceptions:
+  scope: module-specific
+  purpose: clarity and consistency
+
+pattern: |
+  # auth/exceptions.py
+  class AuthException(Exception):
+      pass
+
+  class InvalidCredentials(AuthException):
+      pass
+
+  class TokenExpired(AuthException):
+      pass
+
+  # auth/router.py
+  @router.post("/login")
+  async def login(credentials: LoginSchema):
+      try:
+          return await auth_service.login(credentials)
+      except InvalidCredentials:
+          raise HTTPException(
+              status_code=401,
+              detail="Invalid credentials"
+          )
+
+exception_handlers: |
+  @app.exception_handler(AuthException)
+  async def auth_exception_handler(request, exc):
+      return JSONResponse(
+          status_code=401,
+          content={"detail": str(exc)}
+      )
+```
+
+### 6. Database
+
+```yaml
+naming:
+  establish: upfront conventions
+  consistency: across all models
+
+migrations:
+  tool: Alembic
+  naming: explicit naming rules
+
+design:
+  approach: SQL-first
+  then: add Pydantic models
+
+patterns: |
+  # Use async database drivers
+  from sqlalchemy.ext.asyncio import AsyncSession
+
+  async def get_user(db: AsyncSession, user_id: int):
+      result = await db.execute(
+          select(User).where(User.id == user_id)
+      )
+      return result.scalar_one_or_none()
+```
+
+### 7. API Design
+
+```yaml
+routing:
+  prefix: meaningful module prefix
+  tags: for documentation grouping
+
+responses:
+  schema: always define response models
+  status_codes: document all possible codes
+
+example: |
+  router = APIRouter(
+      prefix="/users",
+      tags=["users"]
+  )
+
+  @router.get(
+      "/{user_id}",
+      response_model=UserResponse,
+      responses={
+          404: {"model": ErrorResponse}
+      }
+  )
+  async def get_user(user_id: int):
+      ...
+```
+
+### 8. Testing
+
+```yaml
+setup:
+  async_client: from day one
+  structure: mirror module layout
+
+patterns: |
+  import pytest
+  from httpx import AsyncClient
+
+  @pytest.fixture
+  async def client():
+      async with AsyncClient(app=app, base_url="http://test") as ac:
+          yield ac
+
+  @pytest.mark.asyncio
+  async def test_get_user(client):
+      response = await client.get("/users/1")
+      assert response.status_code == 200
+```
+
+## Application
+
+When writing FastAPI code:
+
+1. **Always** use domain-based project structure
+2. **Always** use `async def` for I/O operations
+3. **Prefer** Pydantic for all validation
+4. **Use** dependencies for reusable logic
+5. **Define** module-specific exceptions
+6. **Document** API with response models
+7. **Test** with async client
+8. **Use** Ruff for code quality

package/templates/agents/sw-engineer/backend/fastapi-expert/refs/fastapi-best-practices/index.yaml

@@ -0,0 +1,25 @@
+# FastAPI Best Practices Skill
+
+metadata:
+  name: fastapi-best-practices
+  category: backend
+  description: FastAPI patterns for high-performance async APIs
+
+source:
+  type: internal
+  reference:
+    - https://fastapi.tiangolo.com/
+    - https://github.com/zhanymkanov/fastapi-best-practices
+
+provides:
+  - Project structure patterns
+  - Async/await best practices
+  - Pydantic validation patterns
+  - Dependency injection design
+  - Error handling patterns
+  - Database integration
+  - API design guidelines
+  - Testing patterns
+
+used_by:
+  - fastapi-expert

package/templates/agents/sw-engineer/backend/go-backend-expert/refs/go-backend/index.yaml

@@ -0,0 +1,26 @@
+# Go Backend Guide
+
+metadata:
+  name: go-backend
+  description: Go backend development reference documentation
+
+source:
+  type: external
+  origin: various
+  urls:
+    - https://go.dev/doc/effective_go
+    - https://github.com/golang-standards/project-layout
+    - https://github.com/uber-go/guide/blob/master/style.md
+  last_fetched: "2026-01-22"
+
+documents:
+  - name: uber-style
+    path: ./uber-style.md
+    description: Uber Go style guide
+
+  - name: project-layout
+    path: ./project-layout.md
+    description: Standard Go project layout
+
+used_by:
+  - go-backend-expert