forgedev 1.0.0

package/templates/auth/jwt-custom/backend/app/core/security.py.template

@@ -0,0 +1,34 @@
+from datetime import datetime, timedelta, timezone
+
+from jose import JWTError, jwt
+from passlib.context import CryptContext
+
+from app.core.config import settings
+
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+SECRET_KEY = "change-me-in-production"  # TODO: Move to settings/env
+ALGORITHM = "HS256"
+ACCESS_TOKEN_EXPIRE_MINUTES = 30
+
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    return pwd_context.verify(plain_password, hashed_password)
+
+
+def hash_password(password: str) -> str:
+    return pwd_context.hash(password)
+
+
+def create_access_token(data: dict, expires_delta: timedelta | None = None) -> str:
+    to_encode = data.copy()
+    expire = datetime.now(timezone.utc) + (expires_delta or timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES))
+    to_encode.update({"exp": expire})
+    return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
+
+
+def decode_access_token(token: str) -> dict | None:
+    try:
+        return jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
+    except JWTError:
+        return None

package/templates/auth/nextauth/src/app/api/auth/[...nextauth]/route.ts.template

@@ -0,0 +1,3 @@
+import { handlers } from '@/lib/auth';
+
+export const { GET, POST } = handlers;

package/templates/auth/nextauth/src/lib/auth.ts.template

@@ -0,0 +1,30 @@
+import NextAuth from 'next-auth';
+import CredentialsProvider from 'next-auth/providers/credentials';
+
+export const { handlers, signIn, signOut, auth } = NextAuth({
+  providers: [
+    CredentialsProvider({
+      name: 'Credentials',
+      credentials: {
+        email: { label: 'Email', type: 'email' },
+        password: { label: 'Password', type: 'password' },
+      },
+      async authorize(credentials) {
+        // TODO: Implement actual authentication logic
+        // Replace with database lookup and password verification
+        if (!credentials?.email || !credentials?.password) {
+          return null;
+        }
+        return {
+          id: '1',
+          email: credentials.email as string,
+          name: 'User',
+        };
+      },
+    }),
+  ],
+  session: { strategy: 'jwt' },
+  pages: {
+    signIn: '/login',
+  },
+});

package/templates/auth/nextauth/src/middleware.ts.template

@@ -0,0 +1,14 @@
+import { auth } from '@/lib/auth';
+
+export default auth((req) => {
+  const isLoggedIn = !!req.auth;
+  const isOnProtectedRoute = req.nextUrl.pathname.startsWith('/dashboard');
+
+  if (isOnProtectedRoute && !isLoggedIn) {
+    return Response.redirect(new URL('/login', req.nextUrl));
+  }
+});
+
+export const config = {
+  matcher: ['/dashboard/:path*'],
+};

package/templates/backend/fastapi/backend/Dockerfile.template

@@ -0,0 +1,12 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 8000
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

package/templates/backend/fastapi/backend/app/api/health.py.template

@@ -0,0 +1,32 @@
+from fastapi import APIRouter
+from sqlalchemy import text
+
+from app.db.session import async_session
+
+router = APIRouter()
+
+
+@router.get("/health")
+async def health_check():
+    return {
+        "status": "ok",
+        "service": "{{PROJECT_NAME}}",
+    }
+
+
+@router.get("/healthz")
+async def health_check_deep():
+    """Deep health check — verifies database connectivity."""
+    try:
+        async with async_session() as session:
+            await session.execute(text("SELECT 1"))
+        db_status = "connected"
+    except Exception:
+        db_status = "disconnected"
+
+    status = "ok" if db_status == "connected" else "degraded"
+    return {
+        "status": status,
+        "service": "{{PROJECT_NAME}}",
+        "checks": {"database": db_status},
+    }

package/templates/backend/fastapi/backend/app/core/config.py.template

@@ -0,0 +1,25 @@
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    # Application
+    app_name: str = "{{PROJECT_NAME_PASCAL}}"
+    debug: bool = False
+
+    # Database
+    database_url: str = "postgresql+asyncpg://postgres:postgres@localhost:5432/{{PROJECT_NAME_SNAKE}}"
+
+    # CORS
+    cors_origins: list[str] = ["http://localhost:3000"]
+
+    # External service timeouts (seconds)
+    external_service_timeout: float = 30.0
+    ai_service_timeout: float = 60.0
+
+    # Rate limiting
+    rate_limit_per_minute: int = 60
+
+    model_config = {"env_file": ".env", "env_file_encoding": "utf-8"}
+
+
+settings = Settings()

package/templates/backend/fastapi/backend/app/core/errors.py

@@ -0,0 +1,37 @@
+class AppError(Exception):
+    """Structured application error — never leaks stack traces to clients."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int = 500,
+        code: str = "INTERNAL_ERROR",
+    ):
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+        super().__init__(message)
+
+
+class NotFoundError(AppError):
+    def __init__(self, resource: str, resource_id: str):
+        super().__init__(
+            message=f"{resource} not found: {resource_id}",
+            status_code=404,
+            code="NOT_FOUND",
+        )
+
+
+class ValidationError(AppError):
+    def __init__(self, message: str):
+        super().__init__(message=message, status_code=422, code="VALIDATION_ERROR")
+
+
+class AuthenticationError(AppError):
+    def __init__(self, message: str = "Authentication required"):
+        super().__init__(message=message, status_code=401, code="AUTHENTICATION_ERROR")
+
+
+class AuthorizationError(AppError):
+    def __init__(self, message: str = "Insufficient permissions"):
+        super().__init__(message=message, status_code=403, code="AUTHORIZATION_ERROR")

package/templates/backend/fastapi/backend/app/core/retry.py

@@ -0,0 +1,32 @@
+import asyncio
+import functools
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def with_retry(max_retries: int = 3, base_delay: float = 1.0, max_delay: float = 30.0):
+    """Decorator for retrying async functions with exponential backoff."""
+
+    def decorator(func):
+        @functools.wraps(func)
+        async def wrapper(*args, **kwargs):
+            last_exception = None
+            for attempt in range(1, max_retries + 1):
+                try:
+                    return await func(*args, **kwargs)
+                except Exception as e:
+                    last_exception = e
+                    if attempt == max_retries:
+                        break
+                    delay = min(base_delay * (2 ** (attempt - 1)), max_delay)
+                    logger.warning(
+                        f"{func.__name__} attempt {attempt}/{max_retries} failed: {e}. "
+                        f"Retrying in {delay:.1f}s..."
+                    )
+                    await asyncio.sleep(delay)
+            raise last_exception
+
+        return wrapper
+
+    return decorator

package/templates/backend/fastapi/backend/app/main.py.template

@@ -0,0 +1,58 @@
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+
+from app.api.health import router as health_router
+from app.core.config import settings
+from app.core.errors import AppError
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup: connect to database with retry
+    from app.db.session import engine, connect_with_retry
+
+    await connect_with_retry(engine)
+    yield
+    # Shutdown: close database connections gracefully
+    await engine.dispose()
+
+
+app = FastAPI(
+    title="{{PROJECT_NAME_PASCAL}}",
+    version="0.1.0",
+    lifespan=lifespan,
+)
+
+# CORS
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Routes
+app.include_router(health_router, tags=["health"])
+
+
+# Global exception handler — never leak stack traces
+@app.exception_handler(AppError)
+async def app_error_handler(request: Request, exc: AppError):
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={"error": {"code": exc.code, "message": exc.message}},
+    )
+
+
+@app.exception_handler(Exception)
+async def global_exception_handler(request: Request, exc: Exception):
+    import logging
+
+    logging.exception("Unhandled exception")
+    return JSONResponse(
+        status_code=500,
+        content={"error": {"code": "INTERNAL_ERROR", "message": "An unexpected error occurred"}},
+    )

package/templates/backend/fastapi/backend/pyproject.toml.template

@@ -0,0 +1,19 @@
+[project]
+name = "{{PROJECT_NAME}}"
+version = "0.1.0"
+requires-python = ">=3.11"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "SIM"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.pyright]
+pythonVersion = "3.11"
+typeCheckingMode = "basic"

package/templates/backend/fastapi/backend/requirements.txt.template

@@ -0,0 +1,14 @@
+fastapi>=0.115.0
+uvicorn[standard]>=0.34.0
+sqlalchemy[asyncio]>=2.0.38
+asyncpg>=0.30.0
+pydantic>=2.11.0
+pydantic-settings>=2.8.0
+alembic>=1.15.0
+python-jose[cryptography]>=3.4.0
+passlib[bcrypt]>=1.7.4
+httpx>=0.28.0
+pytest>=8.3.0
+pytest-asyncio>=0.25.0
+ruff>=0.11.0
+pyright>=1.1.400

package/templates/base/.gitignore.template

@@ -0,0 +1,29 @@
+# Dependencies
+node_modules/
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Build output
+dist/
+.next/
+out/
+build/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+coverage/
+test-results/
+playwright-report/
+{{EXTRA_IGNORES}}

package/templates/base/README.md.template

@@ -0,0 +1,25 @@
+# {{PROJECT_NAME}}
+
+{{STACK_DESCRIPTION}}
+
+## Setup
+
+```bash
+{{SETUP_COMMANDS}}
+```
+
+## Available Scripts
+
+{{AVAILABLE_SCRIPTS}}
+
+## Project Structure
+
+See `CLAUDE.md` for the complete project map and development conventions.
+
+## Testing
+
+See `docs/uat/` for acceptance testing templates and checklists.
+
+## License
+
+MIT

package/templates/claude-code/agents/code-quality-reviewer.md

@@ -0,0 +1,41 @@
+---
+disallowedTools:
+  - Write
+  - Edit
+  - MultiEdit
+---
+
+# Code Quality Reviewer
+
+You are a code quality reviewer for {{PROJECT_NAME_PASCAL}}.
+Stack: {{STACK_SUMMARY}}
+
+## Review all changed files for:
+
+### Code Quality
+- [ ] Functions have single responsibility
+- [ ] No unused imports or variables
+- [ ] No hardcoded values that should be config/env
+- [ ] Error cases handled with descriptive messages
+- [ ] No console.log / print statements left in production code
+
+### Patterns & Conventions
+- [ ] Follows project conventions from CLAUDE.md
+- [ ] Uses existing utilities instead of reimplementing
+- [ ] Consistent naming conventions
+- [ ] Proper type annotations (TypeScript/Python type hints)
+
+### Performance
+- [ ] No N+1 queries
+- [ ] No unnecessary re-renders (React) or redundant DB calls
+- [ ] Proper use of async/await
+- [ ] No blocking operations in request handlers
+
+### Maintainability
+- [ ] Code is self-documenting (clear names, simple logic)
+- [ ] Complex logic has explanatory comments
+- [ ] No dead code or commented-out blocks
+- [ ] Functions are reasonably sized (< 50 lines)
+
+## Output
+For each issue: **File** | **Line** | **Severity** (critical/warning/info) | **Issue** | **Fix**

package/templates/claude-code/agents/production-readiness.md

@@ -0,0 +1,55 @@
+---
+disallowedTools:
+  - Write
+  - Edit
+  - MultiEdit
+---
+
+# Production Readiness Reviewer
+
+You verify that {{PROJECT_NAME_PASCAL}} is ready for production deployment.
+Stack: {{STACK_SUMMARY}}
+Read-only. Never modify code.
+
+## Checklist
+
+### Health & Observability
+- [ ] Health check endpoint exists and returns structured response
+- [ ] Deep health check verifies database connectivity
+- [ ] Structured logging configured (not console.log/print)
+- [ ] Error tracking integration ready
+
+### Resilience
+- [ ] Graceful shutdown handler registered
+- [ ] Database connection retry with exponential backoff
+- [ ] External service timeouts configured
+- [ ] Rate limiting on public endpoints
+- [ ] Circuit breaker for external dependencies (if applicable)
+
+### Security
+- [ ] No hardcoded secrets in codebase
+- [ ] `.env.example` documents all required environment variables
+- [ ] CORS configured for production origins
+- [ ] Security headers set
+- [ ] Authentication on all protected routes
+
+### Data
+- [ ] Database migrations are up to date
+- [ ] No raw SQL (use ORM)
+- [ ] Sensitive data encrypted at rest
+- [ ] Backup strategy documented
+
+### Deployment
+- [ ] Dockerfile exists and builds successfully
+- [ ] CI/CD pipeline configured
+- [ ] Environment-specific configuration (dev/staging/prod)
+- [ ] Build produces no warnings
+
+### Testing
+- [ ] Unit tests pass
+- [ ] E2E tests pass
+- [ ] Test coverage adequate for critical paths
+- [ ] UAT scenarios documented
+
+## Output
+For each item: **Category** | **Check** | **Status** (PASS/FAIL/N/A) | **Details**

package/templates/claude-code/agents/security-reviewer.md

@@ -0,0 +1,41 @@
+---
+disallowedTools:
+  - Write
+  - Edit
+  - MultiEdit
+---
+
+# Security Reviewer
+
+You are a security reviewer for {{PROJECT_NAME_PASCAL}}.
+Stack: {{STACK_SUMMARY}}
+Read-only. Never modify code.
+
+## Review all changed files for:
+
+### Authentication & Authorization
+- [ ] Protected routes check authentication
+- [ ] Authorization checks before sensitive operations
+- [ ] No hardcoded credentials or tokens
+- [ ] Session/token expiration configured
+
+### Input Validation
+- [ ] All user input validated before use
+- [ ] SQL injection prevention (parameterized queries/ORM)
+- [ ] XSS prevention (proper escaping/sanitization)
+- [ ] File upload validation (type, size, extension)
+
+### Data Exposure
+- [ ] No sensitive data in logs
+- [ ] No secrets in error responses
+- [ ] No stack traces exposed to clients
+- [ ] API responses don't leak internal fields
+
+### Configuration
+- [ ] Secrets in environment variables, not code
+- [ ] CORS properly configured (not wildcard in production)
+- [ ] Security headers set
+- [ ] HTTPS enforced
+
+## Output
+For each finding: **File** | **Line** | **Severity** (critical/high/medium/low) | **Vulnerability** | **Remediation**

package/templates/claude-code/agents/spec-validator.md

@@ -0,0 +1,34 @@
+---
+disallowedTools:
+  - Write
+  - Edit
+  - MultiEdit
+---
+
+# Spec Validator
+
+You validate that the implementation matches the specification.
+Read-only. Never modify code.
+
+## Process
+1. Read the spec file provided as argument
+2. For each requirement in the spec:
+   a. Search the codebase for the implementation
+   b. Verify the implementation matches the requirement
+   c. Check for edge cases mentioned in the spec
+
+## Output: Traceability Matrix
+
+| Spec Requirement | Status | Implementation File | Notes |
+|---|---|---|---|
+| [requirement] | IMPLEMENTED / MISSING / PARTIAL | [file:line] | [details] |
+
+## Summary
+- Total requirements: X
+- Implemented: X
+- Partial: X
+- Missing: X
+- Coverage: X%
+
+## Gaps
+List any requirements that are MISSING or PARTIAL with details on what's missing.

package/templates/claude-code/agents/uat-validator.md

@@ -0,0 +1,37 @@
+---
+disallowedTools:
+  - Write
+  - Edit
+  - MultiEdit
+---
+
+# UAT Validator
+
+You are a QA engineer validating UAT scenarios for {{PROJECT_NAME_PASCAL}}.
+Read-only. Never modify code.
+
+## Process
+1. Read `docs/uat/UAT_TEMPLATE.md`
+2. For each UAT scenario:
+   a. Verify the feature exists in the codebase
+   b. Check if there's a corresponding automated test
+   c. If automated test exists, verify it covers the scenario's steps
+   d. Flag gaps: scenarios without tests, tests without scenarios
+
+## Output: Traceability Matrix
+
+| UAT ID | Feature | Has Automated Test? | Test File | Coverage |
+|---|---|---|---|---|
+| UAT-001 | [feature] | YES/NO | [file:line] | FULL/PARTIAL/NONE |
+
+## Summary
+- Total scenarios: X
+- Automated: X
+- Manual only: X
+- Coverage: X%
+
+## Gaps
+List scenarios that need automated tests, prioritized by UAT priority (P0 first).
+
+## Recommendations
+Suggest specific test implementations for uncovered P0 scenarios.

package/templates/claude-code/claude-md/base.md

@@ -0,0 +1,33 @@
+# {{PROJECT_NAME_PASCAL}}
+
+## WHAT
+- {{STACK_SUMMARY}}
+{{DIR_MAP}}
+
+## HOW
+- Lint: `{{LINT_COMMAND}}`
+- Type check: `{{TYPE_CHECK_COMMAND}}`
+- Test: `{{TEST_COMMAND}}`
+- Build: `{{BUILD_COMMAND}}`
+- Dev: `{{DEV_COMMAND}}`
+
+## RULES
+- Never commit `.env` files or secrets
+- Never modify migration files directly — generate new migrations instead
+- All API responses use structured error format: `{ error: { code, message } }`
+- Never leak stack traces to clients
+- Health check endpoints must always be available
+- Write tests for new features before marking them complete
+
+{{STACK_SPECIFIC_RULES}}
+
+## Skills
+Framework-specific knowledge is in `.claude/skills/` — reference these for deep patterns:
+{{SKILLS_LIST}}
+
+## Completion Protocol
+Before marking any task complete:
+1. Run lint: `{{LINT_COMMAND}}`
+2. Run type check: `{{TYPE_CHECK_COMMAND}}`
+3. Run tests: `{{TEST_COMMAND}}`
+4. Verify no `.env` files or secrets in changes

package/templates/claude-code/claude-md/fastapi.md

@@ -0,0 +1,12 @@
+## FastAPI Conventions
+- Pydantic v2 for all request/response schemas (use model_config, not class Config)
+- SQLAlchemy 2.0 async style — use `select()` not `query()`, `async with session` not `session.query`
+- Dependency injection via `Depends()` for DB sessions, auth, etc.
+- All endpoints return Pydantic models — never return raw dicts
+- Use `@asynccontextmanager` lifespan for startup/shutdown
+- Database session via `get_db()` dependency (backend/app/db/session.py)
+- Error responses use `AppError` classes (backend/app/core/errors.py)
+- Use `with_retry` decorator for external service calls
+- Alembic for migrations: `alembic revision --autogenerate -m "description"`
+- Environment config via Pydantic Settings (backend/app/core/config.py)
+- Ruff for linting, pyright for type checking

package/templates/claude-code/claude-md/fullstack.md

@@ -0,0 +1,12 @@
+## Polyglot Full-Stack Conventions
+- `frontend/` contains the Next.js application — follow Next.js conventions above
+- `backend/` contains the FastAPI application — follow FastAPI conventions above
+- Frontend and backend communicate via REST API only
+- API base URL configured in frontend via `NEXT_PUBLIC_API_URL` environment variable
+- Shared types: define API contracts in backend Pydantic schemas, mirror in frontend TypeScript types
+- Never import between frontend and backend directories
+- Docker Compose orchestrates both services + PostgreSQL
+- Frontend runs on port 3000, backend on port 8000
+- Database owned by backend — frontend never accesses DB directly
+- Authentication: NextAuth on frontend, JWT validation on backend
+- E2E tests in root `e2e/` directory test the full stack together

package/templates/claude-code/claude-md/nextjs.md

@@ -0,0 +1,11 @@
+## Next.js Conventions
+- Use App Router (src/app/) — no pages/ directory
+- Server Components by default; add 'use client' only when needed (event handlers, hooks, browser APIs)
+- Use server actions for mutations, not API routes
+- Colocate loading.tsx, error.tsx, not-found.tsx with page.tsx
+- Use `@/` path alias for imports from src/
+- Tailwind CSS for styling — use `cn()` from `@/lib/utils` for conditional classes
+- Prisma client accessed via `@/lib/db` singleton (includes retry + graceful shutdown)
+- Form validation with Zod schemas shared between client and server
+- Images via `next/image`, links via `next/link`
+- Environment variables: NEXT_PUBLIC_ prefix for client-side, plain for server-side