forgehive 0.6.0

package/forgehive/skills/expert/testing-strategies.md

@@ -0,0 +1,74 @@
+# Testing Strategies
+
+## Core Principle: Test Behavior, Not Implementation
+
+Tests should verify what a unit does, not how it does it. If a refactor breaks tests without changing behavior, the tests are wrong.
+
+## Test Structure (AAA)
+
+```typescript
+it("returns null for unknown user", async () => {
+  // Arrange
+  const repo = new UserRepository(testDb);
+
+  // Act
+  const result = await repo.findById("nonexistent-id");
+
+  // Assert
+  assert.equal(result, null);
+});
+```
+
+## Test Naming
+
+Format: **`[unit] [condition] [expected outcome]`**
+
+```
+✅ "findById returns null for unknown id"
+✅ "parseConfig throws when port is negative"
+❌ "test findById"
+❌ "should work correctly"
+```
+
+## What to Test
+
+| Test | What |
+|---|---|
+| Unit | Pure functions, transformations, business logic |
+| Integration | DB queries, file I/O, external API clients |
+| Contract | API response shapes, event schemas |
+
+**Don't test:** framework behavior, library internals, private methods via backdoor.
+
+## Test Isolation
+
+- Each test owns its state — no shared mutable variables between tests
+- `beforeEach` creates fresh instances, `afterEach` cleans up
+- Integration tests use real dependencies (test DB, temp files) — not mocks
+- Mock only things you don't own (3rd party APIs, time, random)
+
+## Edge Cases to Always Cover
+
+1. Empty / zero / null input
+2. Single item (off-by-one)
+3. Concurrent/duplicate calls (idempotency)
+4. Error paths (not just happy path)
+
+## TDD Cycle
+
+```
+Red → write failing test
+Green → minimal code to pass
+Refactor → clean up, tests still green
+Commit → tests are the safety net
+```
+
+## Anti-Patterns
+
+| Avoid | Why |
+|---|---|
+| Mocking internal modules | Couples tests to implementation |
+| `expect(x).toBeDefined()` only | Doesn't verify actual value |
+| Tests that only pass in sequence | Hidden shared state |
+| Snapshot tests for logic | Fragile, hides intent |
+| Testing mocks | You're testing the mock, not the code |

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

@@ -0,0 +1,62 @@
+# TypeScript Patterns
+
+## Type System
+
+**Prefer `interface` for object shapes, `type` for everything else:**
+```typescript
+interface UserRepository { findById(id: string): Promise<User>; }
+type UserId = string;
+type Result<T> = { data: T; error: null } | { data: null; error: Error };
+```
+
+**Avoid `any` — use `unknown` then narrow:**
+```typescript
+function parse(raw: unknown): Config {
+  if (typeof raw !== "object" || raw === null) throw new Error("invalid");
+  return raw as Config; // after structural check
+}
+```
+
+**`satisfies` for validation without widening:**
+```typescript
+const config = { port: 3000, host: "localhost" } satisfies ServerConfig;
+```
+
+## Functions
+
+- Explicit return types on public/exported functions
+- Arrow functions for callbacks, function declarations for top-level
+- Overloads only when return type changes by input type — otherwise use union
+
+## Async
+
+```typescript
+// Always await — never fire-and-forget without void
+void sendAnalytics(event); // intentional: mark explicitly
+
+// Prefer explicit Promise<T> when body is trivially async
+function getUser(id: string): Promise<User> {
+  return db.users.findUnique({ where: { id } });
+}
+```
+
+## Modules (ESM)
+
+```typescript
+// Named exports > default exports (better tree-shaking + renaming)
+export function parseConfig() {}
+export type { Config };
+
+// Always include .ts extension in ESM imports
+import { parseConfig } from "./config.ts";
+```
+
+## Anti-Patterns
+
+| Avoid | Use instead |
+|---|---|
+| `value!` non-null assertion | Narrow: `if (value == null) throw` |
+| `value as Type` cast | Runtime check + type guard |
+| `// @ts-ignore` | Fix the underlying issue |
+| Nested ternaries | `if/else` or early return |
+| `enum` | `const` object + `keyof typeof` |

package/forgehive/templates/claude-md.block.md

@@ -0,0 +1,62 @@
+## forgehive
+
+This project uses **forgehive** for structured AI-assisted development.
+
+### Session Start (Required)
+
+1. Read `.forgehive/capabilities.yaml`
+   - If `status: draft` → tell the user: "Run `fh confirm` to activate capabilities."
+   - If `status: confirmed` → load silently and apply throughout the session
+2. Read `.forgehive/memory/MEMORY.md` — follow the index links to load project context
+3. Run `fh scan --check` to verify the stack snapshot is current
+
+### During the Session
+
+- Only suggest tools and libraries listed in `capabilities.yaml`
+- If a capability has a `check` field: verify it before use
+- If a capability has a `fulfill` field and the check fails: fulfill it
+- At session end: append brief notes to `.forgehive/state/YYYY-MM-DD.md`
+- If you learn something non-obvious about the project, offer to persist it to memory
+
+### Skills — Progressive Loading
+
+Before starting a technical task, read `.forgehive/skills/INDEX.yaml` to find relevant skills.
+Load only the skills matching your current task — not all skills at once.
+
+Examples:
+- Working with TypeScript types → load `expert/typescript-patterns.md`
+- Database migration → load `expert/database-patterns.md`
+- Reviewing a PR → load `expert/code-review.md`
+- Security review → load `expert/security-checklist.md`
+- Performance issue → load `expert/performance-patterns.md`
+
+### Workflow Commands
+
+ForgeHive installs slash commands in `.claude/commands/`:
+- `/fh-start-task` — start a new feature branch with full context loaded
+- `/fh-ship` — pre-ship checklist: tests, diff review, PR draft
+- `/fh-review` — structured code review using the review skill
+- `/fh-hotfix` — minimal hotfix protocol (< 50 lines rule)
+
+### Agent Memory
+
+Each agent has persistent memory in `.forgehive/agents/memory/<name>.md`.
+Before activating a party set, read the relevant agent memory files.
+Update memory files when agents make significant decisions.
+Format: `[YYYY-MM-DD] <decision or learned context>`
+
+### Party Mode
+
+Slash commands auto-configured by forgehive:
+- `/party` — activate build agents (Viktor + Kai + Sam)
+- `/design-party` — activate design agents (Suki + Viktor)
+- `/review-party` — activate review agents (Kai + Sam + Eli)
+- `/full-party` — activate all agents
+
+### Prohibited
+
+- Writing to paths outside the project root
+- Modifying `.forgehive/scan-result.yaml` manually
+- Skipping the session-start capability and memory check
+- Suggesting tools not in `capabilities.yaml` without explicitly noting the deviation
+- Activating party agents without reading their memory files first

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "forgehive",
+  "version": "0.6.0",
+  "description": "Context-aware AI development environment — one binary, your stack.",
+  "type": "module",
+  "bin": {
+    "forgehive": "./dist/cli.js",
+    "fh": "./dist/cli.js"
+  },
+  "files": ["dist/", "forgehive/"],
+  "keywords": ["claude", "claude-code", "ai", "mcp", "agents", "context", "forgehive", "development"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "esbuild src/cli.ts --bundle --platform=node --format=esm --banner:js='#!/usr/bin/env node' --outfile=dist/cli.js && chmod +x dist/cli.js",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc",
+    "test": "node --import tsx/esm --test test/*.test.ts",
+    "test:watch": "node --import tsx/esm --test --watch test/*.test.ts"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.6.2",
+    "esbuild": "^0.27.7",
+    "tsx": "^4.19.2",
+    "typescript": "^5.8.3"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0"
+  }
+}