forgehive 0.6.0

package/forgehive/commands/fh-ship.md

@@ -0,0 +1,18 @@
+You are running the ForgeHive ship workflow. Follow all steps before declaring ready to merge.
+
+## Pre-Ship Checklist
+
+1. **Tests** — run the test suite from `package.json` scripts
+   - If tests fail: stop here, fix before proceeding
+2. **Diff summary** — `git diff main...HEAD --stat`
+   - Show the user what changed
+3. **Uncommitted work** — `git status`
+   - Commit or stash before proceeding
+4. **Code quality scan**
+   - Any `console.log` / `debugger` / TODO in the diff?
+   - Any commented-out code?
+   - Any hardcoded secrets or API keys?
+5. **PR draft**
+   - Title: under 70 chars, describes the change (not "fix stuff")
+   - Body: 2-3 bullets of what changed and why
+6. **Ask**: "Soll ich den PR erstellen?" — only create if confirmed

package/forgehive/commands/fh-start-task.md

@@ -0,0 +1,13 @@
+You are starting a new development task using the ForgeHive workflow.
+
+## Pre-Task Checklist
+
+1. Ask the user: **"Was baust du heute?"** (or "What are you building today?")
+2. Read `.forgehive/capabilities.yaml` — understand the available stack
+3. Check `.forgehive/memory/MEMORY.md` — load relevant project context
+4. Run `fh scan --check` to verify the codebase snapshot is current
+5. Create a feature branch:
+   - Convention from `git-conventions` skill: `feat/<short-description>`, `fix/<issue>`, `chore/<task>`
+   - Run: `git checkout -b <branch-name>`
+6. Summarize: what you're building, which files are likely to change, which capabilities apply
+7. Check `.forgehive/skills/INDEX.yaml` for relevant expert skills

package/forgehive/hooks/guardrails.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# ForgeHive Guardrails — PreToolUse hook for Bash
+# Receives tool input as JSON on stdin. Exit 1 to block, exit 0 to allow.
+
+INPUT=$(cat 2>/dev/null || echo "{}")
+COMMAND=$(node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{process.stdout.write(JSON.parse(d).command||'')}catch{process.stdout.write('')}})" 2>/dev/null <<< "$INPUT" || echo "")
+
+DANGEROUS=("git push --force" "git push -f " "git reset --hard" "rm -rf /" "DROP TABLE" "DROP DATABASE")
+
+for PATTERN in "${DANGEROUS[@]}"; do
+  if echo "$COMMAND" | grep -qi "$PATTERN"; then
+    echo "🛡 ForgeHive Guardrail: '$PATTERN' geblockt. Erkläre die Absicht und versuche erneut."
+    exit 1
+  fi
+done
+
+exit 0

package/forgehive/party/defaults.yaml

@@ -0,0 +1,21 @@
+sets:
+  design:
+    agents: [suki, viktor]
+    trigger: "/design-party"
+    description: "UX + Architektur parallel"
+  build:
+    agents: [viktor, kai, sam]
+    trigger: "/party"
+    description: "Architektur + Engineering + QA"
+  review:
+    agents: [kai, sam, eli]
+    trigger: "/review-party"
+    description: "Code Review + QA + Doku"
+  full:
+    agents: [nora, eli, remy, suki, viktor, kai, sam]
+    trigger: "/full-party"
+    description: "Alle Agenten"
+  security:
+    agents: [vera, sam]
+    trigger: "/security-party"
+    description: "Security Review + QA"

package/forgehive/skills/INDEX.yaml

@@ -0,0 +1,64 @@
+# ForgeHive Skills Index
+# Claude: load only the skills relevant to your current task.
+# Check 'when' field to decide which skills to load.
+
+skills:
+  typescript-patterns:
+    file: expert/typescript-patterns.md
+    tags: [typescript, types, generics, decorators, utility-types]
+    when: "TypeScript types, generics, utility types, decorators"
+
+  testing-strategies:
+    file: expert/testing-strategies.md
+    tags: [testing, tdd, mocking, assertions, coverage, vitest, jest]
+    when: "Writing tests, TDD, mocking dependencies, test design"
+
+  api-design:
+    file: expert/api-design.md
+    tags: [api, rest, graphql, openapi, versioning, endpoints]
+    when: "Designing API endpoints, REST conventions, OpenAPI specs"
+
+  git-conventions:
+    file: expert/git-conventions.md
+    tags: [git, commits, branches, pr, conventional-commits, merge]
+    when: "Git workflow, commit messages, branch naming, PR process"
+
+  error-handling:
+    file: expert/error-handling.md
+    tags: [errors, exceptions, result-types, retry, fallbacks, typescript]
+    when: "Error handling, exceptions, Result/Either types, retry logic"
+
+  security-checklist:
+    file: expert/security-checklist.md
+    tags: [security, auth, xss, sql-injection, owasp, jwt, csrf]
+    when: "Security review, authentication, authorization, input validation"
+
+  performance-patterns:
+    file: expert/performance-patterns.md
+    tags: [performance, caching, profiling, optimization, lazy-loading, memoization]
+    when: "Performance optimization, caching strategies, profiling"
+
+  code-review:
+    file: expert/code-review.md
+    tags: [review, quality, feedback, pr-review, checklist]
+    when: "Code review, PR feedback, quality assessment"
+
+  clean-architecture:
+    file: expert/clean-architecture.md
+    tags: [architecture, domain, use-cases, clean-arch, ddd, layers]
+    when: "Architecture design, layer separation, domain modeling, DDD"
+
+  database-patterns:
+    file: expert/database-patterns.md
+    tags: [database, sql, migrations, indexing, orm, postgres, prisma]
+    when: "Database design, migrations, query optimization, indexing"
+
+  monorepo-patterns:
+    file: expert/monorepo-patterns.md
+    tags: [monorepo, workspaces, turborepo, nx, packages, pnpm]
+    when: "Monorepo setup, workspace management, build orchestration"
+
+  observability:
+    file: expert/observability.md
+    tags: [logging, metrics, tracing, opentelemetry, monitoring, datadog, sentry]
+    when: "Structured logging, metrics (RED/USE), distributed tracing"

package/forgehive/skills/expert/api-design.md

@@ -0,0 +1,77 @@
+# API Design
+
+## REST Resource Design
+
+```
+GET    /users          → list users (paginated)
+POST   /users          → create user
+GET    /users/:id      → get user
+PATCH  /users/:id      → partial update
+DELETE /users/:id      → delete
+
+POST   /users/:id/activate   → actions as sub-resources
+```
+
+**Naming:** plural nouns for collections, snake_case in JSON, kebab-case in URLs.
+
+## Request / Response Shape
+
+```typescript
+// Response envelope
+interface ApiResponse<T> {
+  data: T;
+  meta?: { total: number; page: number; limit: number };
+}
+
+// Error envelope — always consistent
+interface ApiError {
+  error: { code: string; message: string; field?: string };
+}
+```
+
+## Status Codes
+
+| Code | When |
+|---|---|
+| 200 | Successful GET, PATCH |
+| 201 | Successful POST (resource created) |
+| 204 | Successful DELETE (no body) |
+| 400 | Validation error (include field) |
+| 401 | Not authenticated |
+| 403 | Authenticated but not authorized |
+| 404 | Resource not found |
+| 409 | Conflict (duplicate, stale version) |
+| 422 | Semantically invalid (passes schema, fails business rules) |
+| 429 | Rate limited |
+| 500 | Server error (never leak internals) |
+
+## Versioning
+
+Prefix: `/v1/users` — never break existing clients, deprecate with sunset headers.
+
+## Pagination
+
+```json
+GET /users?page=2&limit=20
+
+{
+  "data": [...],
+  "meta": { "total": 143, "page": 2, "limit": 20, "hasNext": true }
+}
+```
+
+## Validation
+
+- Validate at the boundary (route handler) — not deep in business logic
+- Return all validation errors at once, not just the first
+- Use JSON Schema or Zod for input validation
+
+## Anti-Patterns
+
+| Avoid | Use instead |
+|---|---|
+| Verbs in URLs (`/getUser`) | Nouns + HTTP method |
+| `200` for errors | Correct 4xx/5xx |
+| Leaking stack traces | Structured error codes |
+| Inconsistent field naming | Single convention (snake_case) |
+| Boolean flags in body | Semantic sub-resources or PATCH |

package/forgehive/skills/expert/auth-security.md

@@ -0,0 +1,80 @@
+# Authentication & Session Security
+
+## Secure Password Handling
+
+```typescript
+import bcrypt from "bcrypt";
+
+const SALT_ROUNDS = 12;
+
+export async function hashPassword(plain: string): Promise<string> {
+  return bcrypt.hash(plain, SALT_ROUNDS);
+}
+
+export async function verifyPassword(plain: string, hash: string): Promise<boolean> {
+  return bcrypt.compare(plain, hash);
+}
+```
+
+## JWT Best Practices
+
+```typescript
+import jwt from "jsonwebtoken";
+
+const JWT_SECRET = process.env.JWT_SECRET;
+if (!JWT_SECRET || JWT_SECRET.length < 32) {
+  throw new Error("JWT_SECRET must be at least 32 characters");
+}
+
+export function signToken(userId: string): string {
+  return jwt.sign({ userId }, JWT_SECRET!, {
+    expiresIn: "15m",
+    issuer: "myapp",
+    audience: "myapp-client",
+  });
+}
+
+export function verifyToken(token: string): { userId: string } {
+  return jwt.verify(token, JWT_SECRET!, {
+    issuer: "myapp",
+    audience: "myapp-client",
+  }) as { userId: string };
+}
+```
+
+## Session Security
+
+- Use `httpOnly` and `secure` cookie flags
+- Set `SameSite=Strict` or `SameSite=Lax`
+- Rotate session tokens after privilege escalation
+- Implement absolute session timeout (e.g., 8 hours)
+- Implement idle timeout (e.g., 30 minutes)
+
+```typescript
+app.use(session({
+  secret: process.env.SESSION_SECRET!,
+  resave: false,
+  saveUninitialized: false,
+  cookie: {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === "production",
+    sameSite: "strict",
+    maxAge: 8 * 60 * 60 * 1000, // 8 hours
+  },
+}));
+```
+
+## Multi-Factor Authentication Checklist
+
+- [ ] TOTP (Time-based One-Time Password) support
+- [ ] Recovery codes generated and stored (hashed)
+- [ ] Rate limit MFA attempts
+- [ ] MFA bypass audit logging
+
+## Security Checklist
+
+- [ ] Passwords hashed with bcrypt/argon2 (not MD5/SHA1)
+- [ ] JWT uses short expiry + refresh token pattern
+- [ ] Session tokens regenerated on login
+- [ ] Brute force protection (rate limiting + account lockout)
+- [ ] Secure password reset flow (time-limited tokens)

package/forgehive/skills/expert/clean-architecture.md

@@ -0,0 +1,83 @@
+# Clean Architecture
+
+## Core Principle: Dependency Direction
+
+Dependencies point inward. Business logic doesn't know about databases, HTTP, or frameworks.
+
+```
+[HTTP / CLI]  →  [Use Cases]  →  [Domain]
+[DB / APIs]   →  [Use Cases]
+                    ↑
+             Interfaces defined here,
+             implemented at outer layer
+```
+
+## Layer Responsibilities
+
+**Domain** — pure business logic, no I/O:
+```typescript
+class Order {
+  addItem(product: Product, qty: number): void {
+    if (qty <= 0) throw new InvalidQuantityError(qty);
+    this.items.push({ product, qty });
+  }
+  get total(): Money { return this.items.reduce(/* ... */); }
+}
+```
+
+**Use Cases** — orchestrate domain + I/O via interfaces:
+```typescript
+class PlaceOrderUseCase {
+  constructor(
+    private readonly orders: OrderRepository,   // interface
+    private readonly payments: PaymentGateway,  // interface
+  ) {}
+
+  async execute(cmd: PlaceOrderCommand): Promise<OrderId> {
+    const order = Order.create(cmd);
+    const payment = await this.payments.charge(order.total);
+    order.markPaid(payment.id);
+    return this.orders.save(order);
+  }
+}
+```
+
+**Infrastructure** — concrete implementations (DB, HTTP, external APIs).
+
+## File Structure
+
+```
+src/
+  domain/       ← no external imports
+    order.ts
+    user.ts
+  use-cases/    ← imports domain only
+    place-order.ts
+  infrastructure/  ← implements use-case interfaces
+    postgres-orders.ts
+    stripe-payments.ts
+  http/         ← thin: parse, call use case, respond
+    orders-controller.ts
+```
+
+## Boundaries
+
+Each boundary should answer:
+- **What does it do?** (single responsibility)
+- **How do you call it?** (clear interface)
+- **What does it depend on?** (explicit, inward)
+
+## When to Separate
+
+Three modules that **change together** should probably be one module.
+One module that **changes for different reasons** should be split.
+
+## Anti-Patterns
+
+| Avoid | Why |
+|---|---|
+| Business logic in controllers | Hard to test, hard to reuse |
+| Direct DB calls from domain | Domain coupled to infrastructure |
+| God service with 30 methods | No clear responsibility |
+| Anemic domain (only getters/setters) | Logic lives scattered in services |
+| Circular dependencies | Signals wrong boundary |

package/forgehive/skills/expert/code-review.md

@@ -0,0 +1,81 @@
+# Code Review
+
+## Reviewer Mindset
+
+Your job: find issues the author missed, not rewrite their code. Be direct about problems, respectful about everything else.
+
+## What to Check (Priority Order)
+
+### 1. Correctness
+- Does it do what it claims?
+- Are edge cases handled (null, empty, concurrent)?
+- Are errors handled correctly?
+- Will this break in production?
+
+### 2. Tests
+- Do tests cover the behavior, not just the happy path?
+- Would these tests catch a regression?
+- Are new behaviors tested?
+
+### 3. Design
+- Is the change too large? Should it be split?
+- Does it follow existing patterns?
+- Are there simpler approaches?
+- Are new abstractions justified?
+
+### 4. Security
+- User input validated?
+- Secrets/PII handled correctly?
+- Authorization checked?
+
+### 5. Performance
+- N+1 queries?
+- Unbounded operations on large data?
+- Unnecessary blocking calls?
+
+## Comment Format
+
+```
+// Blocking — must fix before merge
+[BUG] This will NPE when user has no address — add null check at line 42
+
+// Important — should fix
+[DESIGN] This 200-line function is hard to test — consider extracting validateAddress()
+
+// Minor — optional improvement
+[NIT] Variable name `d` unclear — consider `durationMs`
+
+// Question — not blocking
+[Q] Why stringify here instead of using the json field directly?
+
+// Positive — acknowledge good work
+[+] Nice — using Result type here instead of throwing makes the caller explicit
+```
+
+## Self-Review Before Submitting
+
+Run through this before opening a PR:
+- [ ] Read your own diff top to bottom
+- [ ] Does the PR description explain WHY, not just what?
+- [ ] Are there debug logs, TODOs, commented-out code to clean up?
+- [ ] Is the PR size reviewable? (< 400 lines is the sweet spot)
+- [ ] Do all tests pass locally?
+
+## PR Size Guide
+
+| Lines | Status |
+|---|---|
+| < 100 | Ideal |
+| 100–400 | Acceptable |
+| 400–800 | Ask to split |
+| > 800 | Split — no exceptions |
+
+## Anti-Patterns
+
+| Avoid | Why |
+|---|---|
+| "LGTM" without reading | Wastes the review |
+| Bikeshedding on formatting | Use a linter |
+| Rewriting working code | Not your style, their code |
+| Vague comments ("fix this") | Be specific |
+| Approving to avoid conflict | Technical debt |

package/forgehive/skills/expert/database-patterns.md

@@ -0,0 +1,81 @@
+# Database Patterns
+
+## Schema Design
+
+**Naming conventions:**
+- Tables: `snake_case`, plural (`users`, `order_items`)
+- Columns: `snake_case` (`created_at`, `user_id`)
+- Primary keys: `id` (UUID or serial)
+- Foreign keys: `<table_singular>_id` (`user_id`, `order_id`)
+- Booleans: `is_` or `has_` prefix (`is_active`, `has_verified_email`)
+
+**Always include:**
+```sql
+CREATE TABLE users (
+  id         UUID        PRIMARY KEY DEFAULT gen_random_uuid(),
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+```
+
+## Migrations
+
+- One logical change per migration file
+- Migrations are **append-only** — never edit a committed migration
+- Always test `UP` and `DOWN` before merging
+- Non-destructive first: add nullable column → backfill → add NOT NULL constraint
+
+```sql
+-- ✅ Safe migration for adding NOT NULL column
+ALTER TABLE users ADD COLUMN locale TEXT;          -- 1. add nullable
+UPDATE users SET locale = 'en' WHERE locale IS NULL; -- 2. backfill
+ALTER TABLE users ALTER COLUMN locale SET NOT NULL; -- 3. constrain
+```
+
+## Indexing Strategy
+
+```sql
+-- Foreign keys (always index)
+CREATE INDEX idx_orders_user_id ON orders(user_id);
+
+-- Common query patterns
+CREATE INDEX idx_users_email ON users(email);
+
+-- Composite: put most selective column first
+CREATE INDEX idx_orders_status_created ON orders(status, created_at DESC);
+
+-- Partial index for common filtered queries
+CREATE INDEX idx_active_users ON users(email) WHERE is_active = true;
+```
+
+## Query Patterns
+
+```typescript
+// Batch load instead of N+1
+const userIds = posts.map(p => p.authorId);
+const users = await db.users.findMany({ where: { id: { in: userIds } } });
+
+// Cursor pagination (stable, works with inserts)
+const posts = await db.posts.findMany({
+  where: { id: { lt: cursor } },
+  orderBy: { id: "desc" },
+  take: 20,
+});
+
+// Use transactions for multi-step mutations
+await db.$transaction(async (tx) => {
+  await tx.orders.create({ data: order });
+  await tx.inventory.decrement({ where: { id: item.id }, by: qty });
+});
+```
+
+## Anti-Patterns
+
+| Avoid | Why |
+|---|---|
+| `SELECT *` | Pulls unused columns, breaks on schema change |
+| No migrations | Schema drift between environments |
+| Storing arrays as comma-separated strings | Use proper array column or join table |
+| Soft-delete without index | Full table scan on active queries |
+| Logic in triggers | Invisible side effects |
+| ORM for complex reports | Write SQL — it's fine |

package/forgehive/skills/expert/error-handling.md

@@ -0,0 +1,90 @@
+# Error Handling
+
+## Core Principle: Errors Are Values
+
+Handle errors explicitly at call sites. Don't let them propagate silently or get swallowed.
+
+## Error Types
+
+```typescript
+// Domain errors — expected, recoverable
+class UserNotFoundError extends Error {
+  readonly code = "USER_NOT_FOUND";
+  constructor(readonly userId: string) {
+    super(`User ${userId} not found`);
+    this.name = "UserNotFoundError";
+  }
+}
+
+// Infrastructure errors — unexpected, potentially fatal
+// → Let them propagate up to the boundary handler
+```
+
+## Result Pattern (for fallible operations)
+
+```typescript
+type Result<T, E extends Error = Error> =
+  | { ok: true; value: T }
+  | { ok: false; error: E };
+
+function parseConfig(raw: unknown): Result<Config, ConfigError> {
+  if (!isValidConfig(raw)) return { ok: false, error: new ConfigError("invalid") };
+  return { ok: true, value: raw as Config };
+}
+
+// Usage — explicit at call site
+const result = parseConfig(input);
+if (!result.ok) {
+  log.error("bad config", result.error);
+  return;
+}
+use(result.value);
+```
+
+## Boundary Handlers
+
+Catch at the outermost layer only:
+
+```typescript
+// HTTP handler
+app.use((err, req, res, next) => {
+  if (err instanceof DomainError) {
+    res.status(err.httpStatus).json({ error: { code: err.code, message: err.message } });
+  } else {
+    log.error("unexpected", err);
+    res.status(500).json({ error: { code: "INTERNAL", message: "Internal error" } });
+  }
+});
+```
+
+## Async Error Handling
+
+```typescript
+// Always handle rejected promises
+const data = await fetchUser(id).catch(err => {
+  if (err instanceof NotFoundError) return null;
+  throw err; // re-throw unexpected errors
+});
+
+// Top-level: never ignore unhandled rejections
+process.on("unhandledRejection", (err) => {
+  log.error("unhandled rejection", err);
+  process.exit(1);
+});
+```
+
+## Logging
+
+- Log at the boundary, not at every layer (avoid duplicate logs)
+- Include context: `log.error("fetch failed", { userId, err })`
+- Never log secrets or PII
+
+## Anti-Patterns
+
+| Avoid | Use instead |
+|---|---|
+| Empty `catch {}` | At minimum log the error |
+| `catch (e: any)` | `catch (e: unknown)` then narrow |
+| Throwing strings | Throw Error instances |
+| Catching everything | Only catch what you can handle |
+| Error codes as numbers | String codes (searchable) |