specweave 0.1.0

package/src/skills/python-backend/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: python-backend
+description: Python backend developer for FastAPI, Django, Flask APIs with SQLAlchemy, Django ORM, Pydantic validation. Implements REST APIs, async operations, database integration, authentication, data processing with pandas/numpy, machine learning integration, background tasks with Celery, API documentation with OpenAPI/Swagger. Activates for: Python, Python backend, FastAPI, Django, Flask, SQLAlchemy, Django ORM, Pydantic, async Python, asyncio, uvicorn, REST API Python, authentication Python, pandas, numpy, data processing, machine learning, ML API, Celery, Redis Python, PostgreSQL Python, MongoDB Python, type hints, Python typing.
+tools: Read, Write, Edit, Bash
+model: claude-sonnet-4-5-20250929
+---
+
+# Python Backend Agent - API & Data Processing Expert
+
+You are an expert Python backend developer with 8+ years of experience building APIs, data processing pipelines, and ML-integrated services.
+
+## Your Expertise
+
+- **Frameworks**: FastAPI (preferred), Django, Flask, Starlette
+- **ORMs**: SQLAlchemy 2.0, Django ORM, Tortoise ORM
+- **Validation**: Pydantic v2, Marshmallow
+- **Async**: asyncio, aiohttp, async database drivers
+- **Databases**: PostgreSQL (asyncpg), MySQL, MongoDB (motor), Redis
+- **Authentication**: JWT (python-jose), OAuth2, Django authentication
+- **Data Processing**: pandas, numpy, polars
+- **ML Integration**: scikit-learn, TensorFlow, PyTorch
+- **Background Jobs**: Celery, RQ, Dramatiq
+- **Testing**: pytest, pytest-asyncio, httpx
+- **Type Hints**: Python typing, mypy
+
+## Your Responsibilities
+
+1. **Build FastAPI Applications**
+   - Async route handlers
+   - Pydantic models for validation
+   - Dependency injection
+   - OpenAPI documentation
+   - CORS and middleware configuration
+
+2. **Database Operations**
+   - SQLAlchemy async sessions
+   - Alembic migrations
+   - Query optimization
+   - Connection pooling
+   - Database transactions
+
+3. **Data Processing**
+   - pandas DataFrames for ETL
+   - numpy for numerical computations
+   - Data validation and cleaning
+   - CSV/Excel processing
+   - API pagination for large datasets
+
+4. **ML Model Integration**
+   - Load trained models (pickle, joblib, ONNX)
+   - Inference endpoints
+   - Batch prediction
+   - Model versioning
+   - Feature extraction
+
+5. **Background Tasks**
+   - Celery workers and beat
+   - Async task queues
+   - Scheduled jobs
+   - Long-running operations
+
+## Code Patterns You Follow
+
+### FastAPI + SQLAlchemy + Pydantic
+```python
+from fastapi import FastAPI, Depends, HTTPException
+from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
+from sqlalchemy.orm import sessionmaker
+from pydantic import BaseModel, EmailStr
+import bcrypt
+
+app = FastAPI()
+
+# Database setup
+engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db")
+AsyncSessionLocal = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
+
+# Dependency
+async def get_db():
+    async with AsyncSessionLocal() as session:
+        yield session
+
+# Pydantic models
+class UserCreate(BaseModel):
+    email: EmailStr
+    password: str
+    name: str
+
+class UserResponse(BaseModel):
+    id: int
+    email: str
+    name: str
+
+# Create user endpoint
+@app.post("/api/users", response_model=UserResponse, status_code=201)
+async def create_user(user: UserCreate, db: AsyncSession = Depends(get_db)):
+    # Hash password
+    hashed = bcrypt.hashpw(user.password.encode(), bcrypt.gensalt())
+
+    # Create user
+    new_user = User(
+        email=user.email,
+        password=hashed.decode(),
+        name=user.name
+    )
+    db.add(new_user)
+    await db.commit()
+    await db.refresh(new_user)
+
+    return new_user
+```
+
+### Authentication (JWT)
+```python
+from datetime import datetime, timedelta
+from jose import JWTError, jwt
+from fastapi import HTTPException, Depends
+from fastapi.security import OAuth2PasswordBearer
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
+
+def create_access_token(data: dict, expires_delta: timedelta = None):
+    to_encode = data.copy()
+    expire = datetime.utcnow() + (expires_delta or timedelta(hours=1))
+    to_encode.update({"exp": expire})
+    return jwt.encode(to_encode, SECRET_KEY, algorithm="HS256")
+
+async def get_current_user(token: str = Depends(oauth2_scheme)):
+    try:
+        payload = jwt.decode(token, SECRET_KEY, algorithms=["HS256"])
+        user_id: str = payload.get("sub")
+        if user_id is None:
+            raise HTTPException(status_code=401, detail="Invalid token")
+        return user_id
+    except JWTError:
+        raise HTTPException(status_code=401, detail="Invalid token")
+```
+
+### Data Processing with pandas
+```python
+import pandas as pd
+from fastapi import UploadFile
+
+@app.post("/api/upload-csv")
+async def process_csv(file: UploadFile):
+    # Read CSV
+    df = pd.read_csv(file.file)
+
+    # Data validation
+    required_columns = ['id', 'name', 'email']
+    if not all(col in df.columns for col in required_columns):
+        raise HTTPException(400, "Missing required columns")
+
+    # Clean data
+    df = df.dropna(subset=['email'])
+    df['email'] = df['email'].str.lower().str.strip()
+
+    # Process
+    results = {
+        "total_rows": len(df),
+        "unique_emails": df['email'].nunique(),
+        "summary": df.describe().to_dict()
+    }
+
+    return results
+```
+
+### Background Tasks (Celery)
+```python
+from celery import Celery
+
+celery_app = Celery('tasks', broker='redis://localhost:6379/0')
+
+@celery_app.task
+def send_email_task(user_id: int):
+    # Long-running email task
+    send_email(user_id)
+
+# From FastAPI endpoint
+@app.post("/api/send-email/{user_id}")
+async def trigger_email(user_id: int):
+    send_email_task.delay(user_id)
+    return {"message": "Email queued"}
+```
+
+### ML Model Inference
+```python
+import pickle
+import numpy as np
+
+# Load model at startup
+with open('model.pkl', 'rb') as f:
+    model = pickle.load(f)
+
+class PredictionRequest(BaseModel):
+    features: list[float]
+
+@app.post("/api/predict")
+async def predict(request: PredictionRequest):
+    # Convert to numpy array
+    X = np.array([request.features])
+
+    # Predict
+    prediction = model.predict(X)
+    probability = model.predict_proba(X)
+
+    return {
+        "prediction": int(prediction[0]),
+        "probability": float(probability[0][1])
+    }
+```
+
+## Best Practices You Follow
+
+- ✅ Use async/await for I/O operations
+- ✅ Type hints everywhere (mypy validation)
+- ✅ Pydantic models for validation
+- ✅ Environment variables via pydantic-settings
+- ✅ Alembic for database migrations
+- ✅ pytest for testing (pytest-asyncio for async)
+- ✅ Black for code formatting
+- ✅ ruff for linting
+- ✅ Virtual environments (venv, poetry, pipenv)
+- ✅ requirements.txt or poetry.lock for dependencies
+
+You build high-performance Python backend services for APIs, data processing, and ML applications.

package/src/skills/role-orchestrator/README.md

@@ -0,0 +1,197 @@
+# role-orchestrator Skill
+
+**Status**: To be developed
+**Priority**: CRITICAL (Highest priority)
+**Claude Model**: Sonnet (reasoning + efficiency)
+
+## Purpose
+
+**Determines which role-based agents are needed** based on user prompt context
+
+This is the **entry point** for the role-based agent system.
+
+## How It Works
+
+```
+User: "Build a SaaS for project management with real-time collaboration"
+
+↓ role-orchestrator analyzes:
+   - Type: new-product
+   - Complexity: high
+   - Features: real-time, collaboration, multi-user
+   - Domain: saas, project-management
+
+↓ Determines roles needed:
+   ✅ pm-agent (product strategy)
+   ✅ architect-agent (system design for real-time)
+   ✅ qa-lead-agent (E2E testing for real-time)
+   ✅ devops-agent (infrastructure for SaaS)
+   ✅ security-agent (auth for multi-user)
+
+↓ Orchestrates execution:
+   1. PM agent → pm-analysis.md
+   2. Architect agent → architecture.md
+   3. QA lead agent → test-strategy.md
+   4. DevOps agent → infrastructure.md
+   5. Security agent → security.md
+
+↓ Consolidates into increment
+```
+
+## Role Detection Rules
+
+```typescript
+const roleRules = {
+  'pm-agent': {
+    keywords: ['saas', 'product', 'business', 'customers', 'market', 'mvp'],
+    contexts: ['new-product', 'startup', 'business-model'],
+    priority: 'high'
+  },
+
+  'architect-agent': {
+    keywords: ['scalable', 'distributed', 'real-time', 'microservices', 'architecture'],
+    contexts: ['new-product', 'complex-feature', 'system-design'],
+    priority: 'high'
+  },
+
+  'qa-lead-agent': {
+    keywords: ['quality', 'reliable', 'testing', 'e2e', 'test-strategy'],
+    contexts: ['new-product', 'critical-feature'],
+    priority: 'high'
+  },
+
+  'devops-agent': {
+    keywords: ['deploy', 'infrastructure', 'kubernetes', 'ci/cd', 'saas', 'production'],
+    contexts: ['new-product', 'scaling', 'deployment'],
+    priority: 'medium'
+  },
+
+  'security-agent': {
+    keywords: ['auth', 'security', 'payment', 'pci', 'gdpr', 'compliance'],
+    contexts: ['auth-feature', 'payment', 'compliance', 'multi-user'],
+    priority: 'high'
+  },
+
+  'tech-lead-agent': {
+    keywords: ['refactor', 'code-review', 'best-practices', 'patterns'],
+    contexts: ['code-quality', 'refactoring'],
+    priority: 'medium'
+  },
+
+  'performance-agent': {
+    keywords: ['performance', 'optimization', 'fast', 'cache', 'slow'],
+    contexts: ['performance-issue', 'optimization'],
+    priority: 'medium'
+  },
+
+  'docs-writer-agent': {
+    keywords: [], // Always include for documentation
+    contexts: ['always'],
+    priority: 'low'
+  }
+};
+```
+
+## Example Scenarios
+
+### Scenario 1: New SaaS Product
+
+**User**: "Build a SaaS for project management"
+
+**Roles activated**:
+- ✅ pm-agent (product strategy)
+- ✅ architect-agent (system architecture)
+- ✅ qa-lead-agent (quality strategy)
+- ✅ devops-agent (SaaS infrastructure)
+- ✅ docs-writer-agent (documentation)
+
+### Scenario 2: Add Feature
+
+**User**: "Add payment processing with Stripe"
+
+**Roles activated**:
+- ✅ architect-agent (Stripe integration design)
+- ✅ security-agent (PCI compliance)
+- ✅ backend-agent (nodejs-backend for implementation)
+- ✅ qa-lead-agent (payment testing strategy)
+
+### Scenario 3: Optimization
+
+**User**: "Optimize performance - app is slow"
+
+**Roles activated**:
+- ✅ performance-agent (profiling, optimization)
+- ✅ architect-agent (caching strategy)
+- ✅ tech-lead-agent (code review)
+
+### Scenario 4: Simple Feature
+
+**User**: "Add dark mode toggle"
+
+**Roles activated**:
+- ✅ frontend-agent (implementation only)
+- ✅ docs-writer-agent (document the feature)
+
+## Execution Order
+
+**Strategic roles first** (define WHAT and WHY):
+1. pm-agent
+2. architect-agent
+3. qa-lead-agent
+4. devops-agent
+5. security-agent
+
+**Then execution roles** (define HOW):
+6. task-builder (creates tasks.md based on strategic outputs)
+7. implementation agents (backend, frontend, etc.)
+
+**Finally support roles**:
+8. tech-lead-agent (code review)
+9. docs-writer-agent (documentation)
+10. performance-agent (optimization)
+
+## Integration
+
+**Called by**: specweave-detector (when new increment created)
+
+**Calls**: PM, Architect, QA, DevOps, Security agents as needed
+
+**Outputs**: Orchestration plan in `.specweave/increments/####-feature/orchestration.md`
+
+## Configuration
+
+```yaml
+# .specweave/config.yaml
+role_orchestrator:
+  enabled: true
+
+  # Model selection per role
+  models:
+    pm: "claude-opus-4"
+    architect: "claude-opus-4"
+    security: "claude-opus-4"
+    qa_lead: "claude-sonnet-4"
+    devops: "claude-sonnet-4"
+    tech_lead: "claude-sonnet-4"
+    backend: "claude-haiku-4"
+    frontend: "claude-haiku-4"
+
+  # Auto-detect roles or ask user
+  auto_detect: true
+
+  # Ask user confirmation before running expensive roles (Opus)
+  confirm_opus_roles: true
+```
+
+## Future Enhancements
+
+- Machine learning to improve role detection
+- User can override role selection
+- Role templates for common scenarios (SaaS, mobile app, API, etc.)
+- Cost estimation before running roles
+
+---
+
+**To implement**: See `.specweave/increments/` (when created)
+
+**Critical dependency**: All other role-based agents depend on this