agentic-loop 1.0.0

package/templates/config/rust.json

@@ -0,0 +1,81 @@
+{
+  "auth": {
+    "testUser": "",
+    "testPassword": "",
+    "loginEndpoint": "/api/auth/login",
+    "loginMethod": "POST",
+    "tokenType": "jwt",
+    "tokenHeader": "Authorization",
+    "tokenPrefix": "Bearer"
+  },
+
+  "docker": {
+    "enabled": false,
+    "composeFile": "docker-compose.yml",
+    "serviceName": "app",
+    "execPrefix": "docker compose exec -T"
+  },
+
+  "paths": {
+    "src": "src",
+    "tests": "tests",
+    "e2e": "tests/e2e"
+  },
+
+  "commands": {
+    "dev": "cargo run",
+    "install": "cargo build",
+    "seed": "",
+    "resetDb": ""
+  },
+
+  "migrations": {
+    "command": "sqlx migrate run",
+    "pattern": "migrations/.*\\.sql$"
+  },
+
+  "checks": {
+    "build": "cargo build",
+    "lint": "cargo clippy -- -D warnings",
+    "test": "cargo test"
+  },
+
+  "api": {
+    "baseUrl": "http://localhost:8080",
+    "healthEndpoint": "/health",
+    "timeout": 30
+  },
+
+  "playwright": {
+    "enabled": false,
+    "testDir": "tests/e2e",
+    "projects": ["chromium"],
+    "baseUrl": "http://localhost:8080"
+  },
+
+  "verification": {
+    "codeReviewEnabled": true,
+    "browserEnabled": true,
+    "a11yEnabled": false,
+    "mobileViewport": 375,
+    "screenshotOnFailure": true
+  },
+
+  "urls": {
+    "app": "http://localhost:8080",
+    "docs": "http://localhost:8080/swagger"
+  },
+
+  "env": {
+    "required": ["DATABASE_URL"],
+    "optional": ["REDIS_URL"]
+  },
+
+  "maxIterations": 20,
+  "maxSessionSeconds": 600,
+
+  "contextRotThreshold": {
+    "maxStories": 10,
+    "maxFilesChanged": 20
+  }
+}

package/templates/examples/CLAUDE-django.md

@@ -0,0 +1,174 @@
+# Project Instructions for AI Coding Agents
+
+## Naming Conventions
+- **Files**: `snake_case.py` — e.g., `user_views.py`, `auth_serializers.py`
+- **Functions/Variables**: `snake_case` — e.g., `get_user_by_id`, `is_authenticated`
+- **Classes**: `PascalCase` — e.g., `UserViewSet`, `AuthSerializer`
+- **Models**: `PascalCase` singular — e.g., `User`, `BlogPost` (Django pluralizes table names)
+- **Constants**: `SCREAMING_SNAKE` — e.g., `MAX_UPLOAD_SIZE`, `DEFAULT_PAGE_SIZE`
+- **URL patterns**: `kebab-case` — e.g., `/api/user-profile/`, `/api/blog-posts/`
+- **Template files**: `snake_case.html` — e.g., `user_detail.html`
+
+## Tech Stack
+- **Backend**: Django 5, Django REST Framework
+- **Database**: PostgreSQL
+- **Cache/Queue**: Redis, Celery
+- **Testing**: pytest, pytest-django
+
+## Code Quality Standards
+
+### Python Style
+- Follow PEP 8
+- Use type hints for function signatures
+- Maximum line length: 88 (Black default)
+- Use f-strings for string formatting
+
+```python
+# Good
+def get_user_by_email(email: str) -> User | None:
+    """Fetch a user by their email address."""
+    return User.objects.filter(email=email).first()
+```
+
+### Django Models
+- Use explicit `related_name` on ForeignKey/M2M
+- Add `__str__` method to all models
+- Use model managers for complex queries
+- Add indexes for frequently queried fields
+
+```python
+class Order(models.Model):
+    user = models.ForeignKey(
+        User,
+        on_delete=models.CASCADE,
+        related_name='orders'
+    )
+    created_at = models.DateTimeField(auto_now_add=True, db_index=True)
+
+    class Meta:
+        ordering = ['-created_at']
+
+    def __str__(self):
+        return f"Order {self.id} by {self.user.email}"
+```
+
+### Django REST Framework
+- Use serializers for all input/output
+- Use ViewSets for CRUD operations
+- Use proper permission classes
+- Return appropriate HTTP status codes
+
+```python
+class OrderViewSet(viewsets.ModelViewSet):
+    serializer_class = OrderSerializer
+    permission_classes = [IsAuthenticated]
+
+    def get_queryset(self):
+        # Only return user's own orders
+        return Order.objects.filter(user=self.request.user)
+
+    def perform_create(self, serializer):
+        serializer.save(user=self.request.user)
+```
+
+### Error Handling
+- Use DRF exceptions for API errors
+- Log errors with context
+- Never expose internal errors to users
+- Handle specific exceptions, not bare except
+
+```python
+# Bad
+try:
+    process_order(order)
+except Exception:
+    pass
+
+# Good
+try:
+    process_order(order)
+except PaymentError as e:
+    logger.error(f"Payment failed for order {order.id}: {e}")
+    raise ValidationError({"payment": "Payment processing failed"})
+except InventoryError as e:
+    logger.warning(f"Inventory issue for order {order.id}: {e}")
+    raise ValidationError({"inventory": str(e)})
+```
+
+### Database Queries
+- Avoid N+1 queries (use select_related/prefetch_related)
+- Use .only() or .defer() for large models
+- Use database transactions for multi-step operations
+- Add indexes for filter/order fields
+
+```python
+# Bad - N+1 query
+orders = Order.objects.all()
+for order in orders:
+    print(order.user.email)  # Hits DB for each order
+
+# Good
+orders = Order.objects.select_related('user').all()
+for order in orders:
+    print(order.user.email)  # No additional queries
+```
+
+### Security
+- Use Django's CSRF protection
+- Validate all user input with serializers
+- Use parameterized queries (Django ORM does this)
+- Never trust user input for file paths or shell commands
+
+### Testing
+- Use pytest and pytest-django
+- Use fixtures for test data
+- Test API endpoints with APIClient
+- Mock external services
+
+```python
+@pytest.mark.django_db
+class TestOrderAPI:
+    def test_create_order(self, authenticated_client, product):
+        response = authenticated_client.post('/api/orders/', {
+            'product_id': product.id,
+            'quantity': 2,
+        })
+        assert response.status_code == 201
+        assert Order.objects.count() == 1
+
+    def test_cannot_create_order_unauthenticated(self, client):
+        response = client.post('/api/orders/', {})
+        assert response.status_code == 401
+```
+
+## File Structure
+```
+project/
+├── config/           # Django settings, URLs, WSGI
+├── apps/
+│   ├── users/        # User-related models, views
+│   ├── orders/       # Order-related models, views
+│   └── common/       # Shared utilities
+├── tests/            # Test files
+└── manage.py
+```
+
+## Environment Variables
+```python
+# settings.py
+DATABASE_URL = os.getenv('DATABASE_URL')
+SECRET_KEY = os.getenv('SECRET_KEY')
+DEBUG = os.getenv('DEBUG', 'False').lower() == 'true'
+```
+
+## Pre-commit Hooks
+This project uses agentic-loop hooks. Run `/vibe-check` before committing.
+
+## Common Commands
+```bash
+make up              # Start Docker services
+make migrate         # Run migrations
+make test            # Run tests
+make shell           # Django shell
+make logs            # View logs
+```

package/templates/examples/CLAUDE-fastapi.md

@@ -0,0 +1,270 @@
+# CLAUDE.md - FastAPI Project
+
+## Naming Conventions
+- **Files**: `snake_case.py` — e.g., `user_service.py`, `auth_router.py`
+- **Functions/Variables**: `snake_case` — e.g., `get_user_by_id`, `is_valid`
+- **Classes**: `PascalCase` — e.g., `UserService`, `AuthRouter`
+- **Pydantic Models**: `PascalCase` — e.g., `UserCreate`, `UserResponse`
+- **Constants**: `SCREAMING_SNAKE` — e.g., `MAX_RETRIES`, `DEFAULT_LIMIT`
+- **Database tables**: `snake_case` — e.g., `user_sessions`, `api_keys`
+- **API endpoints**: `kebab-case` — e.g., `/api/user-profile`, `/api/v1/auth`
+
+## Project Overview
+
+This is a FastAPI backend application with async SQLAlchemy and Pydantic.
+
+## Tech Stack
+
+- **Framework**: FastAPI
+- **ORM**: SQLAlchemy 2.0 (async)
+- **Validation**: Pydantic v2
+- **Database**: PostgreSQL
+- **Migrations**: Alembic
+- **Testing**: pytest + httpx
+- **Task Queue**: Celery + Redis (if applicable)
+
+## Project Structure
+
+```
+app/
+├── main.py              # FastAPI app entry point
+├── config.py            # Settings via pydantic-settings
+├── database.py          # Async SQLAlchemy setup
+├── models/              # SQLAlchemy models
+├── schemas/             # Pydantic schemas
+├── routers/             # API route handlers
+├── services/            # Business logic
+├── dependencies.py      # FastAPI dependencies
+└── exceptions.py        # Custom exceptions
+tests/
+├── conftest.py          # Fixtures
+├── test_api/            # API tests
+└── test_services/       # Unit tests
+```
+
+## Commands
+
+```bash
+# Development
+uvicorn app.main:app --reload --port 8000
+
+# Database
+alembic upgrade head                    # Run migrations
+alembic revision --autogenerate -m ""   # Create migration
+
+# Testing
+pytest                                  # Run all tests
+pytest -x                               # Stop on first failure
+pytest --cov=app                        # With coverage
+
+# Linting
+ruff check app/
+ruff format app/
+```
+
+## Code Standards
+
+### API Endpoints
+
+```python
+# Good - explicit status codes, response model, dependencies
+@router.post("/users", status_code=status.HTTP_201_CREATED, response_model=UserResponse)
+async def create_user(
+    user_in: UserCreate,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+) -> UserResponse:
+    """Create a new user."""
+    return await user_service.create(db, user_in)
+
+# Bad - implicit everything
+@router.post("/users")
+async def create_user(user_in: UserCreate, db = Depends(get_db)):
+    return await create(db, user_in)
+```
+
+### Pydantic Schemas
+
+```python
+# Good - explicit validation, examples, field descriptions
+class UserCreate(BaseModel):
+    email: EmailStr = Field(..., description="User's email address")
+    password: str = Field(..., min_length=8, description="Password (min 8 chars)")
+    name: str = Field(..., min_length=1, max_length=100)
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "email": "user@example.com",
+                "password": "securepass123",
+                "name": "John Doe"
+            }
+        }
+    )
+
+# Bad - no validation
+class UserCreate(BaseModel):
+    email: str
+    password: str
+    name: str
+```
+
+### SQLAlchemy Models
+
+```python
+# Good - explicit types, relationships, indexes
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    email: Mapped[str] = mapped_column(String(255), unique=True, index=True)
+    hashed_password: Mapped[str] = mapped_column(String(255))
+    is_active: Mapped[bool] = mapped_column(default=True)
+    created_at: Mapped[datetime] = mapped_column(default=func.now())
+
+    # Relationships
+    posts: Mapped[list["Post"]] = relationship(back_populates="author")
+
+# Bad - old style, no types
+class User(Base):
+    __tablename__ = "users"
+    id = Column(Integer, primary_key=True)
+    email = Column(String)
+    password = Column(String)
+```
+
+### Async Database Sessions
+
+```python
+# Good - async context manager
+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
+
+# Bad - no cleanup
+async def get_db():
+    return async_session()
+```
+
+### Error Handling
+
+```python
+# Good - custom exceptions with proper HTTP codes
+class NotFoundError(Exception):
+    def __init__(self, resource: str, id: int):
+        self.resource = resource
+        self.id = id
+
+@app.exception_handler(NotFoundError)
+async def not_found_handler(request: Request, exc: NotFoundError):
+    return JSONResponse(
+        status_code=404,
+        content={"detail": f"{exc.resource} with id {exc.id} not found"}
+    )
+
+# Bad - generic exceptions
+raise Exception("User not found")
+```
+
+### Service Layer
+
+```python
+# Good - service handles business logic
+class UserService:
+    async def create(self, db: AsyncSession, user_in: UserCreate) -> User:
+        # Check if exists
+        existing = await self.get_by_email(db, user_in.email)
+        if existing:
+            raise ConflictError("User", "email", user_in.email)
+
+        # Hash password
+        hashed = hash_password(user_in.password)
+
+        # Create user
+        user = User(email=user_in.email, hashed_password=hashed, name=user_in.name)
+        db.add(user)
+        await db.flush()
+        return user
+
+# Bad - logic in router
+@router.post("/users")
+async def create_user(user_in: UserCreate, db: AsyncSession = Depends(get_db)):
+    existing = await db.execute(select(User).where(User.email == user_in.email))
+    if existing.scalar():
+        raise HTTPException(409, "Email exists")
+    hashed = bcrypt.hash(user_in.password)
+    user = User(email=user_in.email, hashed_password=hashed)
+    db.add(user)
+    # ... more logic
+```
+
+## Do NOT
+
+- Use `Any` type - create proper Pydantic models
+- Put business logic in routers - use service layer
+- Use synchronous database calls in async endpoints
+- Hardcode secrets - use `pydantic-settings` with env vars
+- Skip input validation - use Pydantic Field validators
+- Return SQLAlchemy models directly - use response schemas
+- Use `*` imports - explicit imports only
+- Catch generic `Exception` - catch specific exceptions
+
+## Do
+
+- Use async/await consistently
+- Add OpenAPI descriptions to all endpoints
+- Use dependency injection for services
+- Write tests for all endpoints
+- Use Alembic for all schema changes
+- Add proper logging with structlog
+- Use HTTPException for API errors
+- Validate all inputs with Pydantic
+
+## Environment Variables
+
+```bash
+DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/dbname
+SECRET_KEY=your-secret-key
+REDIS_URL=redis://localhost:6379/0
+DEBUG=false
+```
+
+Always use `pydantic-settings`:
+
+```python
+class Settings(BaseSettings):
+    database_url: PostgresDsn
+    secret_key: str
+    debug: bool = False
+
+    model_config = SettingsConfigDict(env_file=".env")
+
+settings = Settings()
+```
+
+## Testing
+
+```python
+# Good - async test with fixtures
+@pytest.mark.asyncio
+async def test_create_user(client: AsyncClient, db: AsyncSession):
+    response = await client.post(
+        "/api/users",
+        json={"email": "test@example.com", "password": "testpass123", "name": "Test"}
+    )
+    assert response.status_code == 201
+    data = response.json()
+    assert data["email"] == "test@example.com"
+    assert "password" not in data  # Never return password
+
+# conftest.py
+@pytest.fixture
+async def client(app: FastAPI) -> AsyncGenerator[AsyncClient, None]:
+    async with AsyncClient(app=app, base_url="http://test") as client:
+        yield client
+```