forgedev 1.1.3 → 1.3.0

package/templates/claude-code/skills/ai-prompts/SKILL.md

@@ -1,44 +1,122 @@
 ---
-name: AI Prompts
-description: AI/LLM integration patterns and best practices
+name: ai-prompts
+description: AI/LLM integration patterns, guardrails infrastructure, and compliance (EU AI Act, NIST AI RMF)
 ---
 
-# AI/LLM Integration
-
-## Structured Output
-- Always validate AI responses with Pydantic (Python) or Zod (TypeScript)
-- Never use raw string responses in application logic
-- Define response schemas before making API calls
-- Handle malformed responses gracefully
-
-## Prompt Engineering
-- Use system prompts for consistent behavior
-- Include examples (few-shot) for complex tasks
-- Be specific about output format
-- Test prompts with edge cases
-
-## Failover Patterns
-- Implement rule-based fallback when AI is unavailable
-- Set aggressive timeouts (30-60s for most calls)
-- Retry with exponential backoff (max 3 attempts)
-- Cache responses when appropriate
-- Monitor token usage and costs
-
-## Rate Limiting
-- Implement client-side rate limiting before API calls
-- Queue requests during high load
-- Use batch APIs when processing multiple items
-- Handle 429 responses gracefully
-
-## Security
-- Never include user secrets in prompts
-- Sanitize user input before including in prompts
-- Protect against prompt injection attacks (delimiter tokens, input validation, output filtering)
-- Validate and sanitize AI output before using
-- Don't trust AI output for security decisions
-
-## Testing
-- Use golden datasets for regression testing
-- Mock AI responses in unit tests
-- Test timeout and error handling paths
-- Monitor response quality over time
+# AI/LLM Integration & Guardrails
+
+This project includes AI guardrails infrastructure in `src/lib/ai/` (TypeScript) or `app/ai/` (Python).
+
+## Using the AI Client
+
+All AI calls MUST go through the guardrails client. Never call the Anthropic SDK directly.
+
+**TypeScript:**
+```typescript
+import { getAIClient } from '@/lib/ai';
+import { z } from 'zod';
+
+const ai = getAIClient();
+const result = await ai.generate({
+  prompt: 'Analyze this text',
+  schema: z.object({ sentiment: z.enum(['positive', 'negative', 'neutral']), confidence: z.number() }),
+  purpose: 'sentiment-analysis',  // Required for audit trail
+});
+
+if (result.needsHumanReview) {
+  // Route to approval queue — confidence below threshold
+}
+```
+
+**Python:**
+```python
+from app.ai import get_ai_client
+from pydantic import BaseModel
+
+class Sentiment(BaseModel):
+    sentiment: str
+    confidence: float
+
+ai = get_ai_client()
+result = await ai.generate(prompt="Analyze this text", schema=Sentiment, purpose="sentiment-analysis")
+
+if result.needs_human_review:
+    # Route to approval queue
+```
+
+## Guardrails Architecture
+
+| Layer | What It Does | Compliance |
+|-------|-------------|------------|
+| **Input Guard** | Prompt injection detection, input sanitization, length limits | EU AI Act Art. 15, NIST Manage 2.2 |
+| **Output Validation** | Zod/Pydantic schema validation with retry on parse failure | NIST Manage 2.4 |
+| **Confidence Scoring** | Scores each response (0-1), routes low confidence to human review | NIST Measure 2.5, EU AI Act Art. 14 |
+| **Audit Logger** | Structured logging of every AI interaction (input preview, output, confidence, model, latency) | EU AI Act Art. 12, NIST Manage 1.3 |
+| **Health Metrics** | AI-specific health endpoint: availability, confidence distribution, error rates, per-model stats | NIST Manage 3.2, EU AI Act Art. 9 |
+| **AI Disclosure** | All AI responses carry `aiGenerated: true` flag | EU AI Act Art. 50 |
+
+## Rules
+
+- **Never call the Anthropic/OpenAI SDK directly.** Always use `getAIClient()` / `get_ai_client()`
+- **Never use raw string responses in application logic.** Always validate with Zod/Pydantic schemas
+- **Never skip the `purpose` parameter.** Every AI call must be tagged for audit traceability
+- **Never trust AI output for security decisions.** Always validate independently
+- **Never log full prompts.** The audit logger captures only a 200-char preview to avoid PII leakage
+- **Always handle `needsHumanReview`.** If confidence is below threshold, the response must be reviewed before acting on it
+
+## Confidence Thresholds
+
+| Confidence | Action | Use Case |
+|-----------|--------|----------|
+| > 0.9 | Auto-accept | Low-risk: summaries, formatting, classification |
+| 0.7 - 0.9 | Accept with logging | Medium-risk: recommendations, content generation |
+| 0.5 - 0.7 | Flag for review | High-risk: decisions, user-facing content |
+| < 0.5 | Require human approval | Critical: financial, medical, legal, safety |
+
+Configure the threshold per-call via `confidenceThreshold` parameter.
+
+## Prompt Injection Protection
+
+The input guard detects:
+- **Instruction override**: "ignore previous instructions", "disregard your rules"
+- **Role manipulation**: "you are now a...", "pretend to be..."
+- **System prompt extraction**: "show me your system prompt", "repeat your instructions"
+- **Delimiter injection**: `<system>`, `[INST]`, `<|im_start|>`
+- **Data exfiltration**: "send this data to..."
+
+Detected injections are blocked and logged. Suspicious patterns (encoded payloads, code execution) are logged but not blocked.
+
+## AI Health Endpoint
+
+Mount at `/api/ai/health`. Returns:
+```json
+{
+  "status": "ok | degraded | unhealthy",
+  "aiAvailable": true,
+  "metrics": {
+    "totalCalls": 142,
+    "successRate": 0.97,
+    "avgConfidence": 0.84,
+    "avgLatencyMs": 1230,
+    "lowConfidenceRate": 0.08,
+    "errorRate": 0.03
+  },
+  "models": {
+    "claude-sonnet-4-20250514": { "calls": 142, "successRate": 0.97, "avgLatencyMs": 1230 }
+  }
+}
+```
+
+## Recommended Libraries
+
+**TypeScript:** Zod (validation), @anthropic-ai/sdk (model calls), @instructor-ai/instructor (structured extraction)
+**Python:** Pydantic (validation), anthropic (model calls), instructor (structured extraction), guardrails-ai (advanced validation), presidio (PII detection)
+**Observability:** Langfuse (open-source LLM tracing), OpenTelemetry (spans), Helicone (proxy logging)
+
+## Testing AI Integrations
+
+- Mock AI responses in unit tests — never make real API calls in CI
+- Use golden datasets for regression testing prompt quality
+- Test timeout, retry, and error handling paths explicitly
+- Test with adversarial inputs (prompt injection patterns)
+- Monitor confidence score distribution for drift over time

package/templates/claude-code/skills/git-workflow/SKILL.md

@@ -5,10 +5,10 @@ description: Git branching, commits, PR workflow, and conflict resolution patter
 
 ## Branching Strategy
 
-- `main` — production-ready code, never commit directly
-- `feat/<name>` — new features, branch from main
-- `fix/<name>` — bug fixes, branch from main
-- `chore/<name>` — maintenance, config changes, dependency updates
+- `main` - production-ready code, never commit directly
+- `feat/<name>` - new features, branch from main
+- `fix/<name>` - bug fixes, branch from main
+- `chore/<name>` - maintenance, config changes, dependency updates
 
 Always create a feature branch before starting work:
 ```bash
@@ -59,6 +59,6 @@ If rebase gets messy: `git rebase --abort` and start over.
 
 - Never force-push to `main`
 - Never commit `.env` files, credentials, or large binaries
-- Never rebase commits that have been pushed and shared
-- Never merge main into feature branches (rebase instead)
+- Never rebase shared branches (`main`, `develop`). Only rebase your own feature branches
+- Update feature branches with `git rebase origin/main`, not `git merge main` (force-push your branch after)
 - Always pull before pushing: `git pull --rebase` (pulls current branch's upstream)

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

@@ -33,7 +33,7 @@ description: Next.js 15 App Router patterns and best practices
 - Intercepting routes `(.)` for modals
 
 ## Common Mistakes
-- Don't use `useEffect` for data fetching in Server Components
+- Avoid Client Components with `useEffect` for data fetching. Prefer async Server Components instead
 - Don't pass functions as props from Server to Client Components
 - Don't use `router.push` when `<Link>` works
 - Don't create API routes for data that Server Components can fetch directly

package/templates/claude-code/skills/playwright/SKILL.md

@@ -11,11 +11,12 @@ description: Playwright E2E testing patterns and best practices
 - Use `test.beforeEach()` for common setup (navigation, auth)
 - Use page object pattern for complex pages
 
-## Selectors
-- Prefer `data-testid` attributes: `page.getByTestId('submit-btn')`
-- Use accessible selectors: `page.getByRole('button', { name: 'Submit' })`
-- Use text selectors: `page.getByText('Welcome')`
-- Avoid CSS selectors — they break when styles change
+## Selector Priority
+1. `getByRole()`: buttons, links, headings (best for accessibility)
+2. `getByLabel()`: form inputs by label
+3. `getByText()`: visible text content
+4. `getByTestId()`: `data-testid` attributes (last resort)
+- Avoid CSS selectors or XPath. They break when styles change
 
 ## Assertions
 - Use `expect(locator)` for element assertions

package/templates/claude-code/skills/security-api/SKILL.md

@@ -20,7 +20,7 @@ description: API security best practices
 - Validate file uploads (size, type, extension)
 
 ## SQL Injection Prevention
-- Use SQLAlchemy ORM — never raw SQL strings
+- Use SQLAlchemy ORM. Never raw SQL strings
 - If raw SQL needed, use `text()` with bound parameters
 - Never interpolate user input into queries
 

package/templates/claude-code/skills/security-web/SKILL.md

@@ -6,7 +6,7 @@ description: Web application security best practices
 # Web Application Security
 
 ## XSS Prevention
-- React escapes by default — never use `dangerouslySetInnerHTML`
+- React escapes by default. Never use `dangerouslySetInnerHTML`
 - Sanitize user input before rendering
 - Use Content Security Policy headers
 - Validate URLs before using in `href` or `src`
@@ -39,3 +39,4 @@ description: Web application security best practices
 - Use Prisma `select` or `omit` to control returned fields
 - Never log sensitive data
 - Strip internal IDs from client-facing responses when possible
+

package/templates/claude-code/skills/testing-patterns/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: testing-patterns
-description: Universal testing principles — test pyramid, AAA pattern, mocking strategies, and coverage targets
+description: Universal testing principles - test pyramid, AAA pattern, mocking strategies, and coverage targets
 ---
 
 ## Test Pyramid
 
 ```
-        /  E2E  \        — Few, slow, high confidence
-       / Integration \   — Some, medium speed
-      /    Unit Tests   \— Many, fast, focused
+        /  E2E  \        - Few, slow, high confidence
+       / Integration \   - Some, medium speed
+      /    Unit Tests   \- Many, fast, focused
 ```
 
 - **Unit tests** (70%): Test individual functions in isolation. Fast, many.
@@ -21,14 +21,14 @@ Every test follows this structure:
 
 ```
 test('should calculate total with tax', () => {
-  // Arrange — set up test data
+  // Arrange: set up test data
   const items = [{ price: 10 }, { price: 20 }];
   const taxRate = 0.1;
 
-  // Act — execute the function
+  // Act: execute the function
   const total = calculateTotal(items, taxRate);
 
-  // Assert — verify the result
+  // Assert: verify the result
   expect(total).toBe(33);
 });
 ```
@@ -52,7 +52,7 @@ test('should calculate total with tax', () => {
 
 | What | When to Mock |
 |------|-------------|
-| External APIs | Always — they're slow and unreliable |
+| External APIs | Always. They're slow and unreliable |
 | Database | Integration tests use real DB, unit tests mock |
 | Time/Date | When testing time-dependent logic |
 | File system | When testing file operations |
@@ -84,7 +84,7 @@ Use descriptive names that explain the scenario:
 
 - **80% minimum** for all code
 - **100% required** for: auth logic, financial calculations, security-critical code
-- Coverage measures lines hit, not correctness — high coverage with weak assertions is useless
+- Coverage measures lines hit, not correctness. High coverage with weak assertions is useless
 - Focus on meaningful assertions, not just line coverage
 
 ## Common Anti-Patterns

package/templates/database/prisma-postgres/{.env.example → .env.example.template}

@@ -1 +1,2 @@
+# Local development only. Change credentials before deploying to production.
 DATABASE_URL="postgresql://postgres:postgres@localhost:5432/{{PROJECT_NAME_SNAKE}}"

package/templates/database/sqlalchemy-postgres/{.env.example → .env.example.template}

@@ -1,2 +1,3 @@
+# Local development only. Change credentials before deploying to production.
 DATABASE_URL="postgresql+asyncpg://postgres:postgres@localhost:5432/{{PROJECT_NAME_SNAKE}}"
 JWT_SECRET_KEY="change-me-generate-a-random-secret"

package/templates/docs-portal/fastapi/backend/app/portal/docs_reader.py

@@ -0,0 +1,201 @@
+"""Reads and organizes markdown files from the docs/ directory."""
+
+import logging
+from datetime import datetime
+from pathlib import Path
+from dataclasses import dataclass, field
+
+import bleach
+import markdown
+
+logger = logging.getLogger(__name__)
+
+DOCS_ROOT = Path(__file__).resolve().parent.parent.parent.parent / "docs"
+
+ALLOWED_HTML_TAGS = [
+    "a",
+    "p",
+    "ul",
+    "ol",
+    "li",
+    "strong",
+    "em",
+    "code",
+    "pre",
+    "blockquote",
+    "hr",
+    "br",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "table",
+    "thead",
+    "tbody",
+    "tr",
+    "th",
+    "td",
+]
+ALLOWED_HTML_ATTRIBUTES = {
+    "a": ["href", "title"],
+    "th": ["align"],
+    "td": ["align"],
+}
+ALLOWED_PROTOCOLS = ["http", "https", "mailto"]
+
+CATEGORY_META: dict[str, dict] = {
+    "prd": {"label": "Product", "description": "Product requirements and roadmap", "icon": "📋", "order": 1},
+    "sdd": {"label": "Architecture", "description": "System design and technical architecture", "icon": "🏗️", "order": 2},
+    "uat": {"label": "Testing", "description": "Test plans, results, and acceptance criteria", "icon": "✅", "order": 3},
+    "sessions": {"label": "Session Logs", "description": "Testing session results and bug reports", "icon": "📝", "order": 4},
+}
+
+
+@dataclass
+class DocFile:
+    slug: str
+    title: str
+    content: str
+    html: str
+    category: str
+    category_label: str
+    last_modified: datetime
+
+
+@dataclass
+class DocCategory:
+    id: str
+    label: str
+    description: str
+    icon: str
+    order: int
+    docs: list[dict] = field(default_factory=list)
+
+
+def _extract_title(content: str, filename: str) -> str:
+    for line in content.split("\n"):
+        line = line.strip()
+        if line.startswith("# ") and not line.startswith("##"):
+            return line[2:].strip()
+    return filename.replace(".md", "").replace("-", " ").replace("_", " ").title()
+
+
+def _render_markdown(content: str) -> str:
+    md = markdown.Markdown(extensions=["tables", "fenced_code", "toc"])
+    html = md.convert(content)
+    return bleach.clean(
+        html,
+        tags=ALLOWED_HTML_TAGS,
+        attributes=ALLOWED_HTML_ATTRIBUTES,
+        protocols=ALLOWED_PROTOCOLS,
+        strip=True,
+    )
+
+
+def get_categories() -> list[DocCategory]:
+    if not DOCS_ROOT.exists():
+        return []
+
+    categories: list[DocCategory] = []
+
+    for entry in sorted(DOCS_ROOT.iterdir()):
+        if not entry.is_dir():
+            continue
+
+        category_id = entry.name
+        meta = CATEGORY_META.get(category_id, {
+            "label": category_id.capitalize(),
+            "description": "",
+            "icon": "📄",
+            "order": 99,
+        })
+
+        md_files = sorted(entry.glob("*.md"))
+        if not md_files:
+            continue
+
+        docs = []
+        for f in md_files:
+            try:
+                content = f.read_text(encoding="utf-8")
+                docs.append({
+                    "slug": f.stem,
+                    "title": _extract_title(content, f.name),
+                })
+            except (OSError, UnicodeDecodeError) as exc:
+                logger.warning("Skipping docs file %s: %s", f.name, exc)
+                continue
+
+        categories.append(DocCategory(
+            id=category_id,
+            label=meta["label"],
+            description=meta["description"],
+            icon=meta["icon"],
+            order=meta["order"],
+            docs=docs,
+        ))
+
+    # Top-level markdown files
+    top_level = sorted(DOCS_ROOT.glob("*.md"))
+    if top_level:
+        docs = []
+        for f in top_level:
+            content = f.read_text(encoding="utf-8")
+            docs.append({
+                "slug": f.stem,
+                "title": _extract_title(content, f.name),
+            })
+        categories.append(DocCategory(
+            id="_general",
+            label="General",
+            description="Project documentation",
+            icon="📄",
+            order=99,
+            docs=docs,
+        ))
+
+    return sorted(categories, key=lambda c: c.order)
+
+
+def get_doc(category: str, slug: str) -> DocFile | None:
+    if category == "_general":
+        file_path = DOCS_ROOT / f"{slug}.md"
+    else:
+        file_path = DOCS_ROOT / category / f"{slug}.md"
+
+    # Prevent path traversal — resolved path must stay within DOCS_ROOT
+    docs_root_resolved = DOCS_ROOT.resolve()
+    resolved = file_path.resolve()
+    try:
+        resolved.relative_to(docs_root_resolved)
+    except ValueError:
+        return None
+
+    if not resolved.exists():
+        return None
+
+    content = resolved.read_text(encoding="utf-8")
+    stat = resolved.stat()
+    meta = CATEGORY_META.get(category, {"label": "General"})
+
+    return DocFile(
+        slug=slug,
+        title=_extract_title(content, f"{slug}.md"),
+        content=content,
+        html=_render_markdown(content),
+        category=category,
+        category_label=meta["label"],
+        last_modified=datetime.fromtimestamp(stat.st_mtime),
+    )
+
+
+def get_all_docs() -> list[DocFile]:
+    docs: list[DocFile] = []
+    for cat in get_categories():
+        for doc_meta in cat.docs:
+            doc = get_doc(cat.id, doc_meta["slug"])
+            if doc:
+                docs.append(doc)
+    return docs