forge-dev-framework 1.0.1

package/.claude/rules/api-patterns.md

@@ -0,0 +1,98 @@
+# FORGE API Design Patterns
+
+> **Scope:** Internal FORGE APIs and interfaces between components.
+
+## File Naming
+
+- Use `kebab-case.ts` for files
+- Use `PascalCase` for types, interfaces, classes
+- Use `camelCase` for functions, variables
+
+## Module Structure
+
+Each module exports:
+1. Types/interfaces first
+2. Functions/operations
+3. Constants at the end
+
+```typescript
+// src/state/event-types.ts
+export interface StateEvent { ... }
+export interface TaskStartedEvent extends StateEvent { ... }
+
+export function createEvent(type: EventType, payload: unknown): StateEvent { ... }
+
+export const EVENT_TYPES = ['TASK_STARTED', 'TASK_COMPLETED', ...] as const;
+```
+
+## Error Handling
+
+- Define custom error types extending `Error`
+- Include error codes for programmatic handling
+- Provide context in error messages
+
+```typescript
+export class StateValidationError extends Error {
+  constructor(
+    public schema: string,
+    public errors: z.ZodError,
+  ) {
+    super(`State validation failed for ${schema}: ${errors.message}`);
+    this.name = 'StateValidationError';
+  }
+}
+```
+
+## Async Operations
+
+- Use `async/await`, not Promises directly
+- Return typed promises: `Promise<T>`
+- Handle rejections with try/catch
+
+```typescript
+export async function loadState(path: string): Promise<State> {
+  try {
+    const content = await fs.readFile(path, 'utf-8');
+    return JSON.parse(content);
+  } catch (error) {
+    throw new StateLoadError(path, error);
+  }
+}
+```
+
+## Input Validation
+
+- Use Zod schemas for all public APIs
+- Validate at module boundaries
+- Return typed results, never `any`
+
+```typescript
+import { z } from 'zod';
+
+const EventSchema = z.object({
+  eventId: z.string(),
+  timestamp: z.string().datetime(),
+  taskId: z.string(),
+  actor: z.string(),
+  type: z.enum(EVENT_TYPES),
+  payload: z.unknown(),
+});
+
+export function parseEvent(data: unknown): StateEvent {
+  return EventSchema.parse(data);
+}
+```
+
+## File I/O
+
+- Use absolute paths from project root
+- Check file existence before reading
+- Use atomic writes (write to temp, then rename)
+
+```typescript
+export async function writeState(path: string, state: State): Promise<void> {
+  const tmpPath = `${path}.tmp`;
+  await fs.writeFile(tmpPath, JSON.stringify(state, null, 2));
+  await fs.rename(tmpPath, path);
+}
+```

package/.claude/rules/security-baseline.md

@@ -0,0 +1,204 @@
+# FORGE Security Baseline
+
+> **Scope:** Input validation, secrets management, dependency security, file operations.
+
+## Input Validation
+
+**All user input MUST be validated** with Zod schemas:
+
+```typescript
+const ConfigSchema = z.object({
+  mode: z.enum(['yolo', 'interactive']),
+  depth: z.enum(['quick', 'standard', 'comprehensive']),
+  maxTeammates: z.number().int().min(2).max(6),
+});
+
+export function loadConfig(path: string): Config {
+  const raw = JSON.parse(fs.readFileSync(path, 'utf-8'));
+  return ConfigSchema.parse(raw);
+}
+```
+
+### Path Validation
+
+Prevent directory traversal:
+
+```typescript
+import { resolve, normalize } from 'path';
+
+export function safeJoin(base: string, userPath: string): string {
+  const resolved = resolve(base, userPath);
+  if (!resolved.startsWith(base)) {
+    throw new Error('Invalid path: outside base directory');
+  }
+  return resolved;
+}
+```
+
+## Secrets Management
+
+**NEVER hardcode secrets.** Use environment variables:
+
+```typescript
+export function getApiKey(): string {
+  const key = process.env.FORGE_API_KEY;
+  if (!key) {
+    throw new Error('FORGE_API_KEY environment variable not set');
+  }
+  return key;
+}
+```
+
+### Git Ignore
+
+Add to `.gitignore`:
+
+```
+# FORGE
+state/events/*.json  # Optional: don't commit event logs
+.planning/local/     # User-specific config
+.env                 # Environment variables
+*.tmp                # Temp files
+```
+
+## Command Injection Prevention
+
+**NEVER pass user input directly to shell commands.** Use array arguments:
+
+```typescript
+// BAD
+await execa(`git checkout ${userBranch}`);
+
+// GOOD
+await execa('git', ['checkout', userBranch]);
+```
+
+## File Permissions
+
+Respect user's umask, don't over-permission:
+
+```typescript
+import { constants } from 'fs';
+
+await fs.writeFile(path, content, {
+  mode: 0o644, // rw-r--r--
+});
+```
+
+For sensitive files:
+
+```typescript
+await fs.writeFile(path, secrets, {
+  mode: 0o600, // rw-------
+});
+```
+
+## Dependency Security
+
+Run `npm audit` in CI:
+
+```yaml
+# .github/workflows/ci.yml
+- name: Audit dependencies
+  run: npm audit --audit-level=moderate
+```
+
+### Locked Dependencies
+
+Commit `package-lock.json`. Always install with exact versions:
+
+```bash
+npm ci  # Use lock file, don't update
+```
+
+## Code Execution Safety
+
+**NO `eval()`, no dynamic imports from untrusted sources:**
+
+```typescript
+// BAD
+const module = await import(userPath);
+
+// GOOD — validate against whitelist
+const ALLOWED = ['state', 'cli', 'templates'];
+if (ALLOWED.includes(userPath)) {
+  const module = await import(`./${userPath}`);
+}
+```
+
+## Event Log Integrity
+
+Events should be **append-only**. Never modify existing events:
+
+```typescript
+export async function writeEvent(path: string, event: StateEvent): Promise<void> {
+  if (await fs.pathExists(path)) {
+    throw new Error(`Event file already exists: ${path}`);
+  }
+  await fs.writeFile(path, JSON.stringify(event, null, 2), { mode: 0o444 }); // read-only
+}
+```
+
+## State Validation
+
+Validate `STATE.json` against schema on every read:
+
+```typescript
+export async function loadState(path: string): Promise<State> {
+  const content = await fs.readFile(path, 'utf-8');
+  const raw = JSON.parse(content);
+  return StateSchema.parse(raw); // Zod validation
+}
+```
+
+## Git Worktree Isolation
+
+Ensure worktrees can't access each other's files:
+
+```typescript
+export function validateWorktreePath(worktreePath: string): void {
+  if (!worktreePath.startsWith('.worktrees/')) {
+    throw new Error('Invalid worktree: must be under .worktrees/');
+  }
+}
+```
+
+## Error Messages
+
+**Don't leak sensitive info in errors:**
+
+```typescript
+// BAD — leaks file path
+throw new Error(`Failed to read ${filePath}`);
+
+// GOOD — generic error
+throw new Error('Failed to read configuration file');
+```
+
+## CI/CD Security
+
+```yaml
+# .github/workflows/ci.yml
+permissions:
+  contents: read  # No write access
+  issues: read
+  pull-requests: read
+
+- name: Run tests
+  run: npm test
+```
+
+## Third-Party Code
+
+Review all dependencies before adding:
+
+```bash
+npm audit
+npm ls <package>
+```
+
+Prefer well-maintained packages with:
+- Active development
+- Security policy
+- TypeScript types
+- Low dependency count

package/.claude/rules/testing-standards.md

@@ -0,0 +1,177 @@
+# FORGE Testing Standards
+
+> **Scope:** Test coverage, test structure, what to test and how.
+
+## Test Structure
+
+Place tests next to source files with `.test.ts` suffix:
+
+```
+src/state/
+  event-types.ts
+  event-types.test.ts
+src/cli/
+  init.ts
+  init.test.ts
+```
+
+## Unit Tests
+
+Test **pure functions** and **business logic**:
+
+```typescript
+// event-types.test.ts
+import { describe, it, expect } from 'jest';
+import { parseEvent, createEvent } from './event-types';
+
+describe('parseEvent', () => {
+  it('parses valid TASK_STARTED event', () => {
+    const event = parseEvent({
+      eventId: 'evt-001',
+      timestamp: '2026-02-11T21:10:00Z',
+      taskId: 'api-003',
+      actor: 'backend',
+      type: 'TASK_STARTED',
+      payload: {},
+    });
+
+    expect(event.type).toBe('TASK_STARTED');
+  });
+
+  it('throws on missing eventId', () => {
+    expect(() => parseEvent({})).toThrow('eventId');
+  });
+
+  it('throws on invalid timestamp format', () => {
+    expect(() => parseEvent({
+      eventId: 'evt-001',
+      timestamp: 'invalid',
+      taskId: 'api-003',
+      actor: 'backend',
+      type: 'TASK_STARTED',
+      payload: {},
+    })).toThrow('timestamp');
+  });
+});
+```
+
+## Integration Tests
+
+Test **workflows end-to-end**:
+
+```typescript
+// state-merge.integration.test.ts
+describe('State Steward merge', () => {
+  const testDir = tmpdir();
+
+  beforeEach(async () => {
+    await fs.mkdir(`${testDir}/state/events`, { recursive: true });
+  });
+
+  it('merges events in timestamp order', async () => {
+    await writeEvent(`${testDir}/state/events/evt-002.json`, {
+      timestamp: '2026-02-11T21:11:00Z',
+      type: 'TASK_COMPLETED',
+    });
+    await writeEvent(`${testDir}/state/events/evt-001.json`, {
+      timestamp: '2026-02-11T21:10:00Z',
+      type: 'TASK_STARTED',
+    });
+
+    const state = await mergeEvents(testDir);
+
+    expect(state.tasks[0].status).toBe('completed');
+  });
+});
+```
+
+## Coverage Targets
+
+- **Core logic** (state, events, templates): >90%
+- **CLI commands**: >70%
+- **Git operations**: >80%
+
+Run: `npm run test:coverage`
+
+## Test Data
+
+Create fixtures in `test/fixtures/`:
+
+```
+test/fixtures/
+  events/
+    task-started.json
+    task-completed.json
+  state/
+    initial-state.json
+```
+
+## Mocking
+
+Mock external dependencies (git, fs, network):
+
+```typescript
+import { jest } from '@jest/globals';
+
+jest.mock('execa', () => ({
+  execa: jest.fn(),
+}));
+
+import { execa } from 'execa';
+
+it('creates git worktree', async () => {
+  (execa as jest.Mock).mockResolvedValue({ stdout: '' });
+
+  await createWorktree('api-003', 'forge/api-003');
+
+  expect(execa).toHaveBeenCalledWith('git', [
+    'worktree', 'add', '.worktrees/api-003', '-b', 'forge/api-003',
+  ]);
+});
+```
+
+## Test Organization
+
+Use `describe` for logical groups, `it` for individual tests:
+
+```typescript
+describe('State Steward', () => {
+  describe('mergeEvents', () => {
+    it('handles empty event directory');
+    it('sorts events by timestamp');
+    it('handles duplicate eventIds');
+    it('skips malformed events');
+  });
+});
+```
+
+## Async Tests
+
+Always `await` async operations:
+
+```typescript
+it('merges events', async () => {
+  const state = await mergeEvents('/path/to/events');
+  expect(state).toBeDefined();
+});
+```
+
+## Clean Up
+
+Use `beforeEach` / `afterEach` for test isolation:
+
+```typescript
+import { tmpdir } from 'os';
+import { rimraf } from 'rimraf';
+
+let testDir: string;
+
+beforeEach(async () => {
+  testDir = path.join(tmpdir(), `forge-test-${Date.now()}`);
+  await fs.mkdir(testDir, { recursive: true });
+});
+
+afterEach(async () => {
+  await rimraf(testDir);
+});
+```

package/.claude/rules/ui-conventions.md

@@ -0,0 +1,142 @@
+# FORGE CLI UI Conventions
+
+> **Scope:** Command-line interface patterns, user interaction, output formatting.
+
+## Output Style
+
+### Success Messages
+
+- Green checkmark emoji ✓
+- Concise, clear
+- Include what changed
+
+```bash
+✓ Created state/events/evt-001.json
+✓ Merged 12 events to STATE.json
+```
+
+### Error Messages
+
+- Red ✗ or [ERROR] prefix
+- What went wrong + why + how to fix
+- Stack traces only in --debug mode
+
+```bash
+✗ Failed to merge events: Invalid event format in evt-003.json
+  → Run 'forge validate' to check event schemas
+```
+
+### Warning Messages
+
+- Yellow ⚠ prefix
+- Not blocking, but noteworthy
+
+```bash
+⚠  Task api-003 is blocked by api-001 (in_progress)
+```
+
+### Info Messages
+
+- Blue → prefix for steps
+- Show progress for long operations
+
+```bash
+→ Loading events from state/events/...
+→ Found 47 events, merging...
+```
+
+## Progress Indicators
+
+For operations >2 seconds, show progress:
+
+```typescript
+import ora from 'ora';
+
+const spinner = ora('Initializing project...').start();
+// ... work ...
+spinner.succeed('Project initialized');
+```
+
+## Help Text Format
+
+```bash
+forge init          Initialize a new FORGE project
+
+USAGE:
+  forge init [options]
+
+OPTIONS:
+  --name <name>      Project name (default: current directory)
+  --quick            Skip interactive prompts (use defaults)
+
+EXAMPLES:
+  $ forge init
+  $ forge init --name my-app --quick
+```
+
+## Interactive Prompts
+
+When prompting users:
+- Show current value in brackets: `[default: my-app]`
+- Allow (y/N) confirmations
+- Validate input before accepting
+
+```typescript
+import inquirer from 'inquirer';
+
+const answers = await inquirer.prompt([
+  {
+    type: 'input',
+    name: 'projectName',
+    message: 'Project name:',
+    default: path.basename(process.cwd()),
+  },
+  {
+    type: 'confirm',
+    name: 'confirm',
+    message: 'Initialize project?',
+    default: true,
+  },
+]);
+```
+
+## Tables and Lists
+
+For structured output (status, tasks, events):
+
+```bash
+CURRENT TASKS:
+
+ID        STATUS      OWNER       TITLE
+──────────────────────────────────────────────────────
+api-001   completed   backend     User CRUD API
+api-002   in_progress backend     Auth service
+ui-001    pending     frontend    Login form
+```
+
+## ASCII Art Banner
+
+Show on startup:
+
+```bash
+   █   ██  ██
+   █ █ █ █ █ █
+   ███   █ █
+```
+
+## Exit Codes
+
+- `0`: Success
+- `1`: General error
+- `2`: Invalid arguments
+- `3`: State corruption
+- `4`: Git error
+
+## Verbose Flag
+
+Support `-v` / `--verbose` for debug output:
+
+```bash
+forge merge -v
+# → Shows detailed event replay, validation errors, etc.
+```