oh-my-ag 1.2.0

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

@@ -0,0 +1,47 @@
+---
+name: backend-agent
+description: Backend specialist for APIs, databases, authentication, and server-side logic using FastAPI, Node.js, or other frameworks
+---
+
+# Backend Agent - API & Server Specialist
+
+## When to use
+- Building REST APIs or GraphQL endpoints
+- Database design and migrations
+- Authentication and authorization
+- Server-side business logic
+- Background jobs and queues
+
+## When NOT to use
+- Frontend UI -> use Frontend Agent
+- Mobile-specific code -> use Mobile Agent
+
+## Core Rules
+1. Clean architecture: router -> service -> repository -> models
+2. No business logic in route handlers
+3. All inputs validated with Pydantic/Zod
+4. Parameterized queries only (never string interpolation)
+5. JWT + bcrypt for auth; rate limit auth endpoints
+6. Async/await consistently; type hints on all signatures
+
+## How to Execute
+Follow `resources/execution-protocol.md` step by step.
+See `resources/examples.md` for input/output examples.
+Before submitting, run `resources/checklist.md`.
+
+## Serena Memory (CLI Mode)
+See `../_shared/serena-memory-protocol.md`.
+
+## References
+- Execution steps: `resources/execution-protocol.md`
+- Code examples: `resources/examples.md`
+- Code snippets: `resources/snippets.md`
+- Checklist: `resources/checklist.md`
+- Error recovery: `resources/error-playbook.md`
+- Tech stack: `resources/tech-stack.md`
+- API template: `resources/api-template.py`
+- Context loading: `../_shared/context-loading.md`
+- Reasoning templates: `../_shared/reasoning-templates.md`
+- Clarification: `../_shared/clarification-protocol.md`
+- Context budget: `../_shared/context-budget.md`
+- Lessons learned: `../_shared/lessons-learned.md`

package/.agent/skills/backend-agent/resources/api-template.py

@@ -0,0 +1,326 @@
+"""
+API Endpoint Template for Backend Agent
+
+This template demonstrates best practices for FastAPI endpoints.
+"""
+
+from fastapi import APIRouter, Depends, HTTPException, status, Query
+from sqlalchemy.orm import Session
+from typing import Annotated, List
+from uuid import UUID
+
+from app.database import get_db
+from app.auth import get_current_user
+from app.models import User, Resource
+from app.schemas import ResourceCreate, ResourceUpdate, ResourceResponse
+from app.services import ResourceService
+
+# Type aliases for cleaner code
+DatabaseDep = Annotated[Session, Depends(get_db)]
+UserDep = Annotated[User, Depends(get_current_user)]
+
+# Router setup
+router = APIRouter(
+    prefix="/api/resources",
+    tags=["resources"],
+    responses={404: {"description": "Not found"}},
+)
+
+
+# List endpoint with pagination and filtering
+@router.get(
+    "/",
+    response_model=List[ResourceResponse],
+    summary="List resources",
+    description="Retrieve a paginated list of resources with optional filtering"
+)
+async def list_resources(
+    db: DatabaseDep,
+    current_user: UserDep,
+    skip: int = Query(0, ge=0, description="Number of records to skip"),
+    limit: int = Query(100, ge=1, le=1000, description="Max records to return"),
+    search: str | None = Query(None, description="Search query"),
+    status: str | None = Query(None, description="Filter by status"),
+):
+    """
+    List resources with pagination.
+
+    - **skip**: Offset for pagination
+    - **limit**: Maximum number of records
+    - **search**: Optional search term
+    - **status**: Optional status filter
+    """
+    service = ResourceService(db)
+    resources = service.list_resources(
+        user_id=current_user.id,
+        skip=skip,
+        limit=limit,
+        search=search,
+        status=status,
+    )
+    return resources
+
+
+# Get single resource
+@router.get(
+    "/{resource_id}",
+    response_model=ResourceResponse,
+    summary="Get resource",
+    responses={
+        200: {"description": "Resource found"},
+        404: {"description": "Resource not found"},
+        403: {"description": "Access denied"}
+    }
+)
+async def get_resource(
+    resource_id: UUID,
+    db: DatabaseDep,
+    current_user: UserDep,
+):
+    """
+    Get a specific resource by ID.
+
+    Raises:
+        404: Resource not found
+        403: User doesn't own this resource
+    """
+    service = ResourceService(db)
+    resource = service.get_resource(resource_id)
+
+    if not resource:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Resource {resource_id} not found"
+        )
+
+    # Authorization check
+    if resource.user_id != current_user.id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Access denied"
+        )
+
+    return resource
+
+
+# Create resource
+@router.post(
+    "/",
+    response_model=ResourceResponse,
+    status_code=status.HTTP_201_CREATED,
+    summary="Create resource",
+)
+async def create_resource(
+    resource_data: ResourceCreate,
+    db: DatabaseDep,
+    current_user: UserDep,
+):
+    """
+    Create a new resource.
+
+    - **name**: Resource name (required)
+    - **description**: Optional description
+    - **status**: Initial status (default: active)
+    """
+    service = ResourceService(db)
+
+    try:
+        resource = service.create_resource(
+            user_id=current_user.id,
+            data=resource_data
+        )
+        return resource
+    except ValueError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e)
+        )
+
+
+# Update resource
+@router.patch(
+    "/{resource_id}",
+    response_model=ResourceResponse,
+    summary="Update resource",
+)
+async def update_resource(
+    resource_id: UUID,
+    resource_data: ResourceUpdate,
+    db: DatabaseDep,
+    current_user: UserDep,
+):
+    """
+    Update an existing resource (partial update).
+
+    Only provided fields will be updated.
+    """
+    service = ResourceService(db)
+    resource = service.get_resource(resource_id)
+
+    if not resource:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Resource {resource_id} not found"
+        )
+
+    if resource.user_id != current_user.id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Access denied"
+        )
+
+    try:
+        updated_resource = service.update_resource(resource, resource_data)
+        return updated_resource
+    except ValueError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e)
+        )
+
+
+# Delete resource
+@router.delete(
+    "/{resource_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    summary="Delete resource",
+)
+async def delete_resource(
+    resource_id: UUID,
+    db: DatabaseDep,
+    current_user: UserDep,
+    hard: bool = Query(False, description="Perform hard delete instead of soft delete"),
+):
+    """
+    Delete a resource.
+
+    - **hard=false**: Soft delete (default) - sets deleted_at timestamp
+    - **hard=true**: Hard delete - permanently removes from database
+    """
+    service = ResourceService(db)
+    resource = service.get_resource(resource_id)
+
+    if not resource:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Resource {resource_id} not found"
+        )
+
+    if resource.user_id != current_user.id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Access denied"
+        )
+
+    service.delete_resource(resource, hard=hard)
+    # 204 No Content - no response body
+
+
+# Bulk operations example
+@router.post(
+    "/bulk",
+    response_model=List[ResourceResponse],
+    status_code=status.HTTP_201_CREATED,
+    summary="Bulk create resources",
+)
+async def bulk_create_resources(
+    resources_data: List[ResourceCreate],
+    db: DatabaseDep,
+    current_user: UserDep,
+):
+    """
+    Create multiple resources in one request.
+
+    Useful for batch imports.
+    """
+    if len(resources_data) > 100:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Maximum 100 resources per bulk operation"
+        )
+
+    service = ResourceService(db)
+    created_resources = []
+
+    try:
+        for data in resources_data:
+            resource = service.create_resource(
+                user_id=current_user.id,
+                data=data
+            )
+            created_resources.append(resource)
+
+        return created_resources
+    except ValueError as e:
+        db.rollback()  # Rollback on error
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e)
+        )
+
+
+# Service class template (separate file: app/services/resource_service.py)
+"""
+from sqlalchemy.orm import Session
+from app.models import Resource
+from app.schemas import ResourceCreate, ResourceUpdate
+from datetime import datetime
+from uuid import UUID
+
+class ResourceService:
+    def __init__(self, db: Session):
+        self.db = db
+
+    def list_resources(
+        self,
+        user_id: UUID,
+        skip: int = 0,
+        limit: int = 100,
+        search: str | None = None,
+        status: str | None = None,
+    ):
+        query = self.db.query(Resource).filter(
+            Resource.user_id == user_id,
+            Resource.deleted_at.is_(None)
+        )
+
+        if search:
+            query = query.filter(Resource.name.ilike(f"%{search}%"))
+
+        if status:
+            query = query.filter(Resource.status == status)
+
+        return query.offset(skip).limit(limit).all()
+
+    def get_resource(self, resource_id: UUID) -> Resource | None:
+        return self.db.query(Resource).filter(
+            Resource.id == resource_id,
+            Resource.deleted_at.is_(None)
+        ).first()
+
+    def create_resource(self, user_id: UUID, data: ResourceCreate) -> Resource:
+        resource = Resource(
+            **data.model_dump(),
+            user_id=user_id
+        )
+        self.db.add(resource)
+        self.db.commit()
+        self.db.refresh(resource)
+        return resource
+
+    def update_resource(self, resource: Resource, data: ResourceUpdate) -> Resource:
+        for field, value in data.model_dump(exclude_unset=True).items():
+            setattr(resource, field, value)
+
+        self.db.commit()
+        self.db.refresh(resource)
+        return resource
+
+    def delete_resource(self, resource: Resource, hard: bool = False):
+        if hard:
+            self.db.delete(resource)
+        else:
+            resource.deleted_at = datetime.utcnow()
+
+        self.db.commit()
+"""

package/.agent/skills/backend-agent/resources/checklist.md

@@ -0,0 +1,36 @@
+# Backend Agent - Self-Verification Checklist
+
+Run through every item before submitting your work.
+
+## API Design
+- [ ] RESTful conventions followed (proper HTTP methods, status codes)
+- [ ] OpenAPI documentation complete (all endpoints documented)
+- [ ] Request/response schemas defined with Pydantic
+- [ ] Pagination for list endpoints returning > 20 items
+- [ ] Consistent error response format
+
+## Database
+- [ ] Migrations created (Alembic) and tested
+- [ ] Indexes on foreign keys and frequently queried columns
+- [ ] No N+1 queries (use joinedload/selectinload)
+- [ ] Transactions used for multi-step operations
+
+## Security
+- [ ] JWT authentication on protected endpoints
+- [ ] Password hashing with bcrypt (cost 10-12)
+- [ ] Rate limiting on auth endpoints
+- [ ] Input validation with Pydantic (no raw user input in queries)
+- [ ] SQL injection protected (ORM or parameterized queries)
+- [ ] No secrets in code or logs
+
+## Testing
+- [ ] Unit tests for service layer logic
+- [ ] Integration tests for all endpoints (happy + error paths)
+- [ ] Auth scenarios tested (missing token, expired, wrong role)
+- [ ] Test coverage > 80%
+
+## Code Quality
+- [ ] Clean architecture layers: router -> service -> repository
+- [ ] No business logic in route handlers
+- [ ] Async/await used consistently
+- [ ] Type hints on all function signatures

package/.agent/skills/backend-agent/resources/error-playbook.md

@@ -0,0 +1,98 @@
+# Backend Agent - Error Recovery Playbook
+
+When you encounter a failure, find the matching scenario and follow the recovery steps.
+Do NOT stop or ask for help until you have exhausted the playbook.
+
+---
+
+## Import / Module Not Found
+
+**Symptoms**: `ModuleNotFoundError`, `ImportError`, `No module named X`
+
+1. Check the import path — typo? wrong package name?
+2. Verify the dependency exists in `pyproject.toml` or `requirements.txt`
+3. If missing: note it in your result as "requires `pip install X`" — do NOT install yourself
+4. If it's a local module: check the directory structure with `get_symbols_overview`
+5. If the path changed: use `search_for_pattern("class ClassName")` to find the new location
+
+---
+
+## Test Failure
+
+**Symptoms**: `pytest` returns FAILED, assertion errors
+
+1. Read the full error output — which test, which assertion, expected vs actual
+2. `find_symbol("test_function_name")` to read the test code
+3. Determine: is the test wrong or is the implementation wrong?
+   - Test expects old behavior → update test
+   - Implementation has a bug → fix implementation
+4. Re-run the specific test: `pytest path/to/test.py::test_name -v`
+5. After fix, run full test suite to check for regressions
+6. **3회 실패 시**: 다른 접근 방식 시도. 현재 시도를 progress에 기록하고 대안 구현
+
+---
+
+## Database Migration Error
+
+**Symptoms**: `alembic upgrade head` fails, `IntegrityError`, duplicate column
+
+1. Read the error — is it a conflict with existing migration?
+2. Check current DB state: `alembic current`
+3. If migration conflicts: `alembic downgrade -1` then fix migration script
+4. If schema mismatch: compare model with actual DB schema
+5. **절대 하지 말 것**: `alembic stamp head` (데이터 손실 위험)
+
+---
+
+## Authentication / JWT Error
+
+**Symptoms**: 401/403 responses, `InvalidTokenError`, `ExpiredSignatureError`
+
+1. Check: is the secret key consistent between encode and decode?
+2. Check: is the algorithm specified (`HS256` vs `RS256`)?
+3. Check: is the token being sent in the correct header format? (`Bearer {token}`)
+4. Check: is token expiry set correctly? (access: 15min, refresh: 7day)
+5. Test with a manually created token to isolate the issue
+
+---
+
+## N+1 Query / Slow Response
+
+**Symptoms**: API response > 500ms, many similar SQL queries in logs
+
+1. Enable SQL logging: `echo=True` on engine
+2. Count queries for a single request
+3. If N+1: add `joinedload()` or `selectinload()` to the query
+4. If slow single query: check indexes with `EXPLAIN ANALYZE`
+5. If still slow: consider caching with Redis
+
+---
+
+## Rate Limit / Quota Error (Gemini API)
+
+**Symptoms**: `429`, `RESOURCE_EXHAUSTED`, `rate limit exceeded`
+
+1. **즉시 멈춤** — 추가 API 호출 하지 말 것
+2. 현재까지 작업을 `progress-{agent-id}.md`에 저장
+3. `result-{agent-id}.md`에 Status: `quota_exceeded` 기록
+4. 남은 작업 목록을 명시하여 orchestrator가 나중에 재시도할 수 있게 함
+
+---
+
+## Serena Memory 접근 불가
+
+**Symptoms**: `write_memory` / `read_memory` 실패, timeout
+
+1. 1회 재시도 (일시적 오류일 수 있음)
+2. 2회 연속 실패 시: 로컬 파일로 대체
+   - progress → `/tmp/progress-{agent-id}.md`로 작성
+   - result → `/tmp/result-{agent-id}.md`로 작성
+3. result에 `memory_fallback: true` 플래그 추가
+
+---
+
+## 일반 원칙
+
+- **3회 실패**: 같은 접근 3번 실패하면 반드시 다른 방법 시도
+- **막힘**: 5턴 이상 진전 없으면 현재 상태 저장하고 result에 `Status: blocked` 기록
+- **범위 초과**: 다른 에이전트 영역의 문제 발견 시, result에 기록만 하고 직접 수정하지 말 것

package/.agent/skills/backend-agent/resources/examples.md

@@ -0,0 +1,85 @@
+# Backend Agent - Examples
+
+## Example 1: CRUD API Endpoint
+
+**Input**: "Create a TODO CRUD API with user ownership"
+
+**Output**:
+```
+## Task: TODO CRUD API
+
+### Endpoints Implemented
+- POST /api/todos (create)
+- GET /api/todos (list, user-scoped)
+- GET /api/todos/{id} (detail)
+- PATCH /api/todos/{id} (update)
+- DELETE /api/todos/{id} (delete)
+
+### Database Schema
+- todos table: id (UUID), title (VARCHAR), completed (BOOL), user_id (FK), created_at
+- Index on user_id
+
+### Security
+- [x] All endpoints require JWT auth
+- [x] User can only access own todos (user_id filter)
+- [x] Input validated with Pydantic
+
+### Files Created
+- app/models/todo.py
+- app/schemas/todo.py
+- app/services/todo_service.py
+- app/api/todos.py
+- tests/test_todos.py
+- alembic/versions/xxx_add_todos.py
+```
+
+## Example 2: Authentication System
+
+**Input**: "Add JWT authentication with register and login"
+
+**Output**:
+```
+## Task: JWT Authentication
+
+### Endpoints Implemented
+- POST /api/auth/register (email + password)
+- POST /api/auth/login (returns access + refresh tokens)
+- POST /api/auth/refresh (refresh token rotation)
+
+### Security
+- [x] Password hashed with bcrypt (cost 12)
+- [x] Access token: 15min expiry
+- [x] Refresh token: 7 day expiry, single-use rotation
+- [x] Rate limiting: 5 attempts/min on login
+- [x] Email validation with Pydantic EmailStr
+
+### Files Created
+- app/models/user.py
+- app/schemas/auth.py
+- app/services/auth_service.py
+- app/api/auth.py
+- app/core/security.py (JWT helpers, password hashing)
+- tests/test_auth.py
+```
+
+## Example 3: Fixing N+1 Query
+
+**Input**: "The /api/posts endpoint is slow, taking 2s for 50 posts"
+
+**Output**:
+```
+## Task: Fix N+1 Query in Posts API
+
+### Root Cause
+Each post triggers a separate query for its author (N+1 problem).
+
+### Fix
+Added joinedload(Post.author) to the query.
+
+### Before: 51 queries (1 + 50)
+### After: 1 query with JOIN
+
+### Files Modified
+- app/api/posts.py (added eager loading)
+- tests/test_posts.py (added performance assertion)
+```

package/.agent/skills/backend-agent/resources/execution-protocol.md

@@ -0,0 +1,45 @@
+# Backend Agent - Execution Protocol
+
+## Step 0: Prepare
+1. **Assess difficulty** — see `../_shared/difficulty-guide.md`
+   - **Simple**: Skip to Step 3 | **Medium**: All 4 steps | **Complex**: All steps + checkpoints
+2. **Check lessons** — read your domain section in `../_shared/lessons-learned.md`
+3. **Clarify requirements** — follow `../_shared/clarification-protocol.md`
+   - Check **Uncertainty Triggers**: 비즈니스 로직, 보안/인증, 기존 코드 충돌?
+   - Determine level: LOW → proceed | MEDIUM → present options | HIGH → ask immediately
+4. **Budget context** — follow `../_shared/context-budget.md` (read symbols, not whole files)
+
+**⚠️ Intelligent Escalation**: When uncertain, escalate early. Don't blindly proceed.
+
+Follow these steps in order (adjust depth by difficulty).
+
+## Step 1: Analyze
+- Read the task requirements carefully
+- Identify which endpoints, models, and services are needed
+- Check existing code with Serena: `get_symbols_overview("app/api")`, `find_symbol("existing_function")`
+- List assumptions; ask if unclear
+
+## Step 2: Plan
+- Decide on file structure: models, schemas, routes, services
+- Define API contracts (method, path, request/response types)
+- Plan database schema changes (tables, columns, indexes, migrations)
+- Identify security requirements (auth, validation, rate limiting)
+
+## Step 3: Implement
+- Create/modify files in this order:
+  1. Database models + migrations
+  2. Pydantic schemas (request/response)
+  3. Service layer (business logic)
+  4. API routes (thin, delegate to services)
+  5. Tests (unit + integration)
+- Use `resources/api-template.py` as reference
+- Follow clean architecture: router -> service -> repository -> models
+
+## Step 4: Verify
+- Run `resources/checklist.md` items
+- Run `../_shared/common-checklist.md` items
+- Ensure all tests pass
+- Confirm OpenAPI docs are complete
+
+## On Error
+See `resources/error-playbook.md` for recovery steps.