forgedev 1.0.0

package/templates/claude-code/commands/audit-security.md

@@ -0,0 +1,11 @@
+Run a focused security audit on all changed files.
+
+1. Get list of changed files: `git diff --name-only`
+2. Launch the security-reviewer agent on those files
+3. Additionally check:
+   - No secrets committed (grep for API keys, tokens, passwords in code)
+   - No `.env` files in git tracking
+   - Dependencies have no known critical vulnerabilities
+4. Report all findings by severity
+
+For any CRITICAL findings, provide immediate remediation steps.

package/templates/claude-code/commands/audit-spec.md

@@ -0,0 +1,9 @@
+Run the spec-validator agent against the specification.
+
+1. Find spec files in `docs/` (look for files with "spec", "requirements", or "PRD" in the name)
+2. If no spec found, ask the user to provide the spec file path
+3. Launch the spec-validator agent with the spec file
+4. Report the traceability matrix
+5. Highlight any MISSING or PARTIAL requirements
+
+Focus on P0 requirements first, then P1, then P2.

package/templates/claude-code/commands/audit-wiring.md

@@ -0,0 +1,17 @@
+Verify that all API endpoints are properly wired between frontend and backend.
+
+1. Find all backend API endpoints (route handlers, FastAPI routers)
+2. Find all frontend API calls (fetch, axios, server actions)
+3. Cross-reference: every backend endpoint should have at least one frontend caller
+4. Cross-reference: every frontend API call should hit a real backend endpoint
+5. Check that request/response types match between frontend and backend
+
+Output a wiring matrix:
+| Backend Endpoint | Method | Frontend Caller | Type Match | Status |
+|---|---|---|---|---|
+| /api/users | GET | src/app/users/page.tsx | YES/NO | WIRED/ORPHAN |
+
+Flag:
+- ORPHAN backend endpoints (no frontend caller)
+- DEAD frontend calls (no backend endpoint)
+- TYPE MISMATCH (request/response shape differs)

package/templates/claude-code/commands/done.md

@@ -0,0 +1,19 @@
+Verify that the current task is actually complete before moving on.
+
+## Checklist
+
+1. Run lint and confirm it passes: `{{LINT_COMMAND}}`
+2. Run type check and confirm it passes: `{{TYPE_CHECK_COMMAND}}`
+3. Run tests and confirm they pass: `{{TEST_COMMAND}}`
+4. Check that no `.env` files or secrets are in the changes
+5. Review the git diff to make sure only intended files changed
+6. Verify the feature works as described (manual check or UAT scenario)
+
+## Output
+
+If everything passes:
+```
+Task complete. Ready to commit or move on.
+```
+
+If something fails, explain what needs to be fixed before the task can be considered done.

package/templates/claude-code/commands/generate-prd.md

@@ -0,0 +1,45 @@
+Generate a Product Requirements Document (PRD) for this project.
+
+## Instructions
+
+1. Read the entire codebase to understand:
+   - What the application does (features, user flows)
+   - Who the users are (roles, personas)
+   - What the tech stack is
+   - What's already built vs what's planned
+
+2. Generate a PRD with these sections:
+
+### Overview
+- Product name and one-line description
+- Problem statement (what problem does this solve?)
+- Target users
+
+### User Personas
+- List each user type with their goals and pain points
+
+### Feature Map
+- Group features by category
+- Mark each as: ✅ Built | 🚧 In Progress | 📋 Planned
+- Include a Mermaid diagram showing the feature hierarchy
+
+### User Flows
+- For each major feature, describe the user flow
+- Include Mermaid sequence diagrams for critical paths
+
+### Data Model
+- Entity relationship diagram (Mermaid ERD)
+- Key entities and their relationships
+
+### Non-Functional Requirements
+- Performance targets
+- Security requirements
+- Scalability considerations
+
+### Milestones
+- Phase 1, 2, 3 with features in each
+
+## Output
+
+Save the PRD to `docs/PRD.md`. Use Mermaid diagrams (```mermaid blocks) for all visual elements.
+Do NOT modify any code — this is a documentation-only task.

package/templates/claude-code/commands/generate-uat.md

@@ -0,0 +1,35 @@
+Generate UAT (User Acceptance Test) scenarios for this project.
+
+## Instructions
+
+1. Read the codebase to identify all user-facing features:
+   - API endpoints and their purposes
+   - UI pages and forms
+   - Authentication flows
+   - Business logic and workflows
+
+2. For each feature, create test scenarios covering:
+   - Happy path (expected usage)
+   - Edge cases (empty inputs, max values, special characters)
+   - Error cases (invalid data, unauthorized access, network failures)
+   - Integration points (features that depend on each other)
+
+3. Prioritize scenarios:
+   - P0: Critical path — app is broken if these fail (login, core CRUD, data integrity)
+   - P1: Important — significant user impact (permissions, validation, error handling)
+   - P2: Nice to have — minor features, cosmetic issues
+
+## Output
+
+Generate two files:
+
+### docs/uat/UAT_TEMPLATE.md
+Markdown table with columns:
+| ID | Feature | Scenario | Steps | Expected Result | Priority |
+
+### docs/uat/UAT_CHECKLIST.csv
+CSV with columns:
+ID,Feature,Scenario,Priority,Status,Tester,Date,Notes
+
+Include at least 5 P0 scenarios, 10 P1 scenarios, and 5 P2 scenarios.
+Do NOT modify any code — this is a documentation-only task.

package/templates/claude-code/commands/help.md

@@ -0,0 +1,26 @@
+Show the developer what workflows are available.
+
+## Available Workflows
+
+### Daily Development
+- `/project:status` — Run all checks and show a project dashboard
+- `/project:next` — Figure out what to work on next
+- `/project:done` — Verify the current task is complete before moving on
+
+### Verification
+- `/project:verify-all` — Run lint, type check, tests, then launch all reviewers
+- `/project:audit-spec` — Validate implementation against a spec/PRD
+- `/project:audit-wiring` — Find dead or unwired features
+- `/project:audit-security` — Run a security audit
+
+### Release
+- `/project:pre-pr` — Run the complete pre-PR checklist
+- `/project:run-uat` — Execute UAT scenarios
+
+### Generation
+- `/project:generate-prd` — Generate a PRD from the current codebase
+- `/project:generate-uat` — Generate UAT scenarios and checklists
+- `/project:optimize-claude-md` — Slim down an oversized CLAUDE.md
+
+## Quick Start
+Run `/project:status` to see where things stand, then `/project:next` to pick up work.

package/templates/claude-code/commands/next.md

@@ -0,0 +1,20 @@
+Figure out what the developer should work on next.
+
+## Steps
+
+1. Check git log for recent commits to understand current progress
+2. Look for TODO/FIXME/HACK comments in the codebase
+3. Check if there are failing tests: `{{TEST_COMMAND}}`
+4. Check if there are lint errors: `{{LINT_COMMAND}}`
+5. Check if docs/uat/UAT_CHECKLIST.csv exists and has unchecked items
+6. Look for open issues or PRs if this is a GitHub repo
+
+## Priority Order
+1. Failing tests or build errors (fix first)
+2. Security issues (from recent audit or TODO comments)
+3. Unchecked UAT scenarios
+4. TODO/FIXME items in code
+5. New feature work
+
+## Output
+Recommend the single most important thing to work on next, with a clear action.

package/templates/claude-code/commands/optimize-claude-md.md

@@ -0,0 +1,31 @@
+Analyze and optimize CLAUDE.md for this project.
+
+## Instructions
+
+1. Read the current CLAUDE.md and measure its size (line count).
+
+2. The target is **under 150 lines**. CLAUDE.md should contain ONLY:
+   - WHAT: One-line project description
+   - HOW: Key commands (lint, test, build, dev)
+   - RULES: Universal rules that apply everywhere (max 10-15 rules)
+   - PITFALLS: Known gotchas specific to this project (max 5)
+
+3. Identify content that should be **moved out**:
+   - Detailed schemas, specs, or data models → `.claude/skills/<topic>/SKILL.md`
+   - Backend-specific rules → `backend/CLAUDE.md`
+   - Frontend-specific rules → `src/CLAUDE.md` or `frontend/CLAUDE.md`
+   - Detailed API documentation → `docs/`
+   - Step-by-step procedures → `.claude/commands/`
+   - Lists of more than 5 items → `.claude/skills/`
+
+4. Present a proposal as a table:
+
+| Content | Current Location | Move To | Lines Saved |
+|---------|-----------------|---------|-------------|
+| ...     | CLAUDE.md:45-80 | .claude/skills/schema/SKILL.md | 35 |
+
+## Rules
+- Do NOT modify any files until I explicitly approve the proposal
+- Show the current line count and target line count
+- Preserve all information — nothing gets deleted, only relocated
+- Each skill file needs frontmatter: name, description, and relevant file patterns

package/templates/claude-code/commands/pre-pr.md

@@ -0,0 +1,19 @@
+Run the complete pre-PR checklist before creating a pull request.
+
+1. Run lint: `{{LINT_COMMAND}}`
+2. Run type check: `{{TYPE_CHECK_COMMAND}}`
+3. Run tests: `{{TEST_COMMAND}}`
+4. Check for uncommitted changes
+5. Launch code-quality-reviewer agent on the PR diff
+6. Launch security-reviewer agent on the PR diff
+7. Check that no `.env` files or secrets are staged
+
+If all checks pass, output:
+- Summary of changes (files changed, lines added/removed)
+- Suggested PR title and description
+- Any warnings (non-blocking issues)
+
+If any check fails, output:
+- Which checks failed
+- How to fix each failure
+- Do NOT proceed with PR creation

package/templates/claude-code/commands/run-uat.md

@@ -0,0 +1,21 @@
+Read docs/uat/UAT_TEMPLATE.md and execute the UAT verification process.
+
+For each scenario in the UAT template:
+1. Check if automated tests exist that cover this scenario
+2. If automated: run the test and report PASS/FAIL
+3. If not automated: flag as MANUAL REQUIRED
+4. Update docs/uat/UAT_CHECKLIST.csv with results
+
+Output:
+- Automated coverage: X/Y scenarios have automated tests
+- Results: X passed, Y failed, Z need manual testing
+- Blocking issues: list any P0 failures
+
+For P0 failures:
+- Show the test output
+- Suggest a fix if the failure is obvious
+- Mark as BLOCKED in the checklist
+
+For scenarios needing manual testing:
+- Provide step-by-step instructions for the tester
+- Note any test data or setup required

package/templates/claude-code/commands/status.md

@@ -0,0 +1,24 @@
+Run all validation checks and show a project dashboard.
+
+## Steps
+
+1. Run lint: `{{LINT_COMMAND}}`
+2. Run type check: `{{TYPE_CHECK_COMMAND}}`
+3. Run tests: `{{TEST_COMMAND}}`
+4. Check git status for uncommitted changes
+5. Check for any `.env` files accidentally tracked
+
+## Output Format
+
+```
+{{PROJECT_NAME_PASCAL}} Status
+──────────────────────────
+Lint:       PASS / FAIL (N issues)
+Types:      PASS / FAIL (N errors)
+Tests:      PASS / FAIL (N passed, M failed)
+Git:        clean / N uncommitted changes
+Secrets:    clean / WARNING
+──────────────────────────
+```
+
+If anything fails, suggest the next step to fix it.

package/templates/claude-code/commands/verify-all.md

@@ -0,0 +1,11 @@
+Run the full verification chain on the current changes.
+
+1. Run lint: `{{LINT_COMMAND}}`
+2. Run type check: `{{TYPE_CHECK_COMMAND}}`
+3. Run tests: `{{TEST_COMMAND}}`
+4. Launch the code-quality-reviewer agent on all changed files (use `git diff --name-only`)
+5. Launch the security-reviewer agent on all changed files
+6. Launch the production-readiness agent
+
+Summarize all findings grouped by severity (critical, high, medium, low).
+If any critical issues found, list them prominently at the top.

package/templates/claude-code/hooks/polyglot.json

@@ -0,0 +1,36 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/guard-protected-files.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/autofix-polyglot.sh"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd frontend && npx tsc --noEmit 2>&1 && npx eslint . 2>&1 && cd ../backend && ruff check . 2>&1"
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/claude-code/hooks/python.json

@@ -0,0 +1,36 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/guard-protected-files.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/autofix-python.sh"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd backend && ruff check . 2>&1 && pyright 2>&1"
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/claude-code/hooks/scripts/autofix-polyglot.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# Auto-fix lint issues on saved TypeScript or Python files (polyglot)
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r ".tool_input.file_path // empty")
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+if [[ "$FILE_PATH" == *.ts || "$FILE_PATH" == *.tsx ]]; then
+  cd frontend && npx eslint --fix "$FILE_PATH" 2>&1 || true
+elif [[ "$FILE_PATH" == *.py ]]; then
+  cd backend && ruff check --fix "$FILE_PATH" 2>&1 || true
+fi
+
+exit 0

package/templates/claude-code/hooks/scripts/autofix-python.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Auto-fix lint issues on saved Python files
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r ".tool_input.file_path // empty")
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+if [[ "$FILE_PATH" == *.py ]]; then
+  cd backend && ruff check --fix "$FILE_PATH" 2>&1 || true
+fi
+
+exit 0

package/templates/claude-code/hooks/scripts/autofix-typescript.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Auto-fix lint issues on saved TypeScript files
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r ".tool_input.file_path // empty")
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+if [[ "$FILE_PATH" == *.ts || "$FILE_PATH" == *.tsx ]]; then
+  npx eslint --fix "$FILE_PATH" 2>&1 || true
+fi
+
+exit 0

package/templates/claude-code/hooks/scripts/guard-protected-files.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Block modifications to .env files and migration files
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r ".tool_input.file_path // empty")
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+case "$FILE_PATH" in
+  *.env|*.env.*)
+    echo "BLOCKED: Do not modify .env files directly" >&2
+    exit 2
+    ;;
+  */prisma/migrations/*|*/alembic/versions/*)
+    echo "BLOCKED: Do not modify migration files directly" >&2
+    exit 2
+    ;;
+esac
+
+exit 0

package/templates/claude-code/hooks/typescript.json

@@ -0,0 +1,36 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/guard-protected-files.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/autofix-typescript.sh"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx tsc --noEmit 2>&1 && npx eslint . 2>&1"
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,43 @@
+---
+name: AI Prompts
+description: AI/LLM integration patterns and best practices
+---
+
+# 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
+- 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

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

@@ -0,0 +1,38 @@
+---
+name: FastAPI
+description: FastAPI + SQLAlchemy 2.0 + Pydantic v2 patterns
+---
+
+# FastAPI Backend
+
+## Endpoint Patterns
+- Use `APIRouter` for route grouping
+- Type all parameters: path params, query params, request bodies
+- Return Pydantic models, not dicts
+- Use `Depends()` for dependency injection (DB sessions, auth, config)
+- Use `status_code` parameter for non-200 responses
+
+## Pydantic v2
+- Use `model_config = ConfigDict(...)` not `class Config`
+- Use `model_validator` not `root_validator`
+- Use `field_validator` not `validator`
+- `from_attributes=True` replaces `orm_mode=True`
+
+## SQLAlchemy 2.0 Async
+- Use `select()` statement style, not `session.query()`
+- Use `async with async_session() as session` for scoped sessions
+- Use `session.execute(select(Model))` then `.scalars().all()`
+- Use `session.get(Model, id)` for single lookups
+- Never use synchronous session methods
+
+## Error Handling
+- Raise `AppError` subclasses, never `HTTPException` with raw strings
+- Global exception handler catches unhandled errors
+- Never expose stack traces or internal details to clients
+- Use structured error format: `{ error: { code, message } }`
+
+## Testing
+- Use `httpx.AsyncClient` with `ASGITransport` for async tests
+- Use `conftest.py` fixtures for test client and DB setup
+- Test both success and error paths
+- Use `pytest.mark.asyncio` for async tests

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

@@ -0,0 +1,39 @@
+---
+name: Next.js
+description: Next.js 15 App Router patterns and best practices
+---
+
+# Next.js 15 App Router
+
+## Routing
+- File-based routing in `src/app/`
+- `page.tsx` for pages, `layout.tsx` for layouts, `loading.tsx` for loading states
+- `error.tsx` for error boundaries, `not-found.tsx` for 404s
+- Route groups `(group)` for organization without URL impact
+- Dynamic routes `[param]`, catch-all `[...slug]`, optional `[[...slug]]`
+
+## Server vs Client Components
+- All components are Server Components by default
+- Add `'use client'` only when you need: event handlers, useState/useEffect, browser APIs
+- Pass server data to client components via props
+- Keep client components as leaves of the component tree
+
+## Data Fetching
+- Server Components: fetch directly in the component, use async/await
+- Client Components: use SWR or React Query
+- Server Actions: `'use server'` functions for mutations
+- Route Handlers: `app/api/*/route.ts` for REST endpoints
+
+## Patterns
+- Use `next/image` for all images (automatic optimization)
+- Use `next/link` for navigation (automatic prefetching)
+- Use `next/font` for fonts (automatic optimization)
+- Metadata API for SEO: export `metadata` object or `generateMetadata` function
+- Parallel routes `@slot` for complex layouts
+- Intercepting routes `(.)` for modals
+
+## Common Mistakes
+- Don't use `useEffect` for data fetching in Server Components
+- 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

@@ -0,0 +1,37 @@
+---
+name: Playwright
+description: Playwright E2E testing patterns and best practices
+---
+
+# Playwright E2E Testing
+
+## Test Structure
+- Tests in `e2e/` directory
+- Use `test.describe()` for grouping related tests
+- 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
+
+## Assertions
+- Use `expect(locator)` for element assertions
+- `toBeVisible()`, `toHaveText()`, `toHaveValue()`, `toHaveCount()`
+- Use `expect(response)` for API assertions
+- Always await assertions
+
+## Common Patterns
+- Navigation: `await page.goto('/')` then assert page loaded
+- Form filling: `await page.fill('[name=email]', 'test@example.com')`
+- Clicking: `await page.click('button[type=submit]')` or `getByRole`
+- Waiting: prefer auto-waiting over explicit waits
+- Network: `page.waitForResponse()` for API-dependent tests
+- Authentication: use `storageState` for persistent auth across tests
+
+## Fixtures
+- Define in `e2e/fixtures/` directory
+- Use `test.extend()` for custom fixtures
+- Share auth state across tests with `storageState`