Conventions

Cross-cutting conventions for all projects. Tech stack, workflow, and standards.

Directory Structure

Domain	Purpose	Scale
`family/`	Legal, financial, shared family resources	Small projects, documentation
`self/`	Learning, research, legacy for children	Experiments, knowledge base
`work/`	Professional projects, startups, investments	Monorepos, production apps
`pages/`	Static site deployment (Cloudflare Pages)	Cross-cutting infrastructure

Writing Style: No Fluff

Every sentence must carry value. No setup sentences, no rhetorical buildup, no hedging.

Do	Don't
Start with the point	"Here's what happened:", "Let me explain:"
Let tables/lists speak	"The following shows:"
Data and specifics	Adjectives and vague claims
Active voice	Passive voice
Compress ruthlessly	"In order to", "essentially", "basically"

Formatting Rules

Tables for comparisons and quick reference
Bullets for 3+ items
Bold for key terms on first use
Blockquotes for key statements only
Minimal headers — only when section changes topic

Terminology (Worca/HIHQ)

Use	Avoid
Talent	Candidates, users
Curate	Source, find
Judgment	Algorithm, system
Represent	Match, connect

Tech Stack Defaults

Layer	Technology
Frontend	React 19 + Vite + TypeScript
Backend	Express 5 + TypeScript + Prisma 6
Database	PostgreSQL 16 (Docker)
Monorepo	pnpm workspaces + Turborepo
Node	>=20.0.0

Monorepo Structure

apps/
├── frontend/          # React app
└── backend/           # Express API + Prisma
packages/
├── shared/            # Shared types (@scope/shared)
├── tsconfig/          # Shared TS configs
└── eslint-config/     # Shared ESLint

Environment

OS: macOS (Darwin)
Package Manager: pnpm (required)
Node: >=20.0.0
Docker: For PostgreSQL

Claude Code Workflow

Verification First

Always give Claude a way to verify work. This 2-3x quality.

Project Type	Verification
TypeScript	`pnpm type-check` after changes
Tests	Run relevant test suite
Builds	`pnpm build` before committing
Prisma	`pnpm db:generate` after schema changes

Plan Mode

Start complex tasks with Plan mode (shift+tab twice). Iterate on plan before auto-accepting.

When Claude Does Something Wrong

Add it to the relevant CLAUDE.md. The file is a living document — learnings compound.

Proactive Behavior

In work/ projects, Claude should:

Research and pull available info without being asked
Create/update relevant files automatically
Surface decisions that need human attention
Be direct when something doesn't fit

Human-AI Division

AI Handles	Human Handles
Research, documentation	Vision, judgment
File organization	Relationships
Drafting, analysis	Final decisions
Pipeline cleanup	Context AI can't access

Project-Specific CLAUDE.md Files

Each major project has its own CLAUDE.md with project overview, tech stack, commands, business context, and domain-specific instructions.

Project	Focus
`family/`	Writing style, legal/financial context
`work/hihq-monorepo/`	Talent management, boutique scale, UI guidelines
`work/angel-pipeline/`	Deal tracking, investment thesis, proactive research
`work/worca/`	Branding, blog style
`self/research/`	Source conventions, knowledge preservation

UI/Frontend Defaults

When building HTML visualizations for markdown files.

Theme: Cool Ivory

Background #fffff8

Text #2c2c2c

Secondary BG #f8f8f5

Border #e8e8e3

Color Palette

Accent Blue #4a6fa5

Success #5a8a6a

Warning #b8923a

Danger #b85a5a

Info #5a8a9a

Design Principles

Simple tables over multi-section cards
Serif typography — Libre Baskerville, classic paper feel
Muted colors — all colors softened to match ivory
Minimal styling — let content speak
Mobile-first responsive — all HTML must work on mobile

Mobile Responsive Requirements

Breakpoint	Target	Key Changes
≤768px	Tablets/phones	Cards instead of tables, stacked filters, 16px inputs
≤480px	Small phones	Further reduced padding/fonts

Reference Files

pages/src/pages/style-guide.astro — Full component reference
pages/src/styles/global.css — Theme CSS variables

Commands Reference

Development

pnpm dev Start dev servers

pnpm build Build all packages

pnpm type-check TypeScript checking

pnpm lint Lint all packages

Database (Prisma projects)

pnpm db:generate Generate Prisma Client

pnpm db:migrate Run migrations

pnpm db:seed Seed data

pnpm db:studio Prisma Studio GUI

Shared Package (monorepos)

pnpm --filter @scope/shared build Rebuild after changing shared types

Static Page Deployment

cd pages && pnpm dev Local dev at localhost:4321

cd pages && pnpm build Build static files

cd pages && pnpm deploy Build & deploy to CF Pages

Quick Reference

TypeScript Run type-check before committing

Shared Rebuild shared package after type changes

Prisma Use migrations for schema changes, never edit DB directly

Context Each project's CLAUDE.md has specific context — read it first

Enter Passcode