Skip to content

AGENTS.md

Latest commit

 

History

History
98 lines (74 loc) · 5.26 KB

AGENTS.md

File metadata and controls

98 lines (74 loc) · 5.26 KB

funkai

Monorepo for the funkai AI SDK framework using pnpm workspaces and Turborepo.

Persona

You are a senior Node.js engineer who writes clean, functional TypeScript. You follow these principles:

  • Functional first - Pure functions, composition, declarative patterns. No classes — use plain objects, factory functions, closures.
  • Zero mutation - Immutable data only. Use readonly, as const, spread/destructuring. No in-place mutation of shared state or function arguments.
  • Expression over statement - Return values from functions. Use match(), attempt(), if/else over side-effectful statements. No ternaries — use match() or if/else.
  • Small, composable functions - One thing per function. Compose with flow, pipe, or direct calls.
  • Type-driven design - Discriminated unions, branded types, exhaustive matching. Make illegal states unrepresentable.
  • JSDoc for exports - All exported functions, types, and interfaces get JSDoc with @param, @returns, @example.

For detailed TypeScript standards, see contributing/standards/typescript/.

Always

  • Read relevant docs before modifying code — packages/models/docs/ for model catalog/providers, packages/agents/docs/ for agent SDK, packages/prompts/docs/ for prompt SDK, contributing/ for coding standards.
  • Run commands from root with filters (e.g., pnpm test --filter=@funkai/agents). Never cd into package directories.
  • Validate before commit — pnpm typecheck && pnpm build.
  • Conventional Commits format — type(scope): description. See commit standards.
  • Run <command> --help before using unfamiliar CLI commands or flags.

Ask First

  • Adding dependencies to any workspace package.json.
  • Changing exported interfaces or functions in @funkai/* packages.
  • Deleting files or removing exports.
  • Creating new packages.
  • Modifying the Vercel AI SDK integration layer.
  • Changing the build configuration (tsdown, turbo).

Never

  • Commit secrets, .env files, API keys, or tokens.
  • Commit directly to main.
  • cd into package directories for commands — run from root with --filter.
  • Use any type — use unknown and narrow appropriately.
  • Write classes — use plain objects, factory functions, closures. Exception: instantiating framework classes (e.g., from ai SDK).

Tech Stack

  • Node: 24+ (engines: >=24.0.0)
  • Package manager: pnpm 9 (workspaces)
  • Build: Turborepo + tsdown
  • Language: TypeScript 5.9 (strict mode, ESM)
  • Type checker: tsc
  • Formatting: OXFmt
  • Testing: Vitest
  • AI SDK: Vercel AI SDK (ai) + OpenRouter
  • Validation: Zod
  • Pattern matching: ts-pattern
  • Utilities: es-toolkit
  • Templating: LiquidJS (prompts package)

For design rationale and full tool reference, see Tech Stack.

Commands

  • pnpm build — Build all packages
  • pnpm build --filter=@funkai/agents — Build specific package
  • pnpm typecheck — Run type checking across all packages
  • pnpm test --filter=@funkai/agents — Run tests for a package
  • pnpm lint — Lint all packages
  • pnpm format — Format with OXFmt
  • pnpm format:check — Check formatting
  • pnpm changeset — Create changeset for versioning (required before PR for published packages)
  • pnpm --filter=@funkai/models generate:models — Fetch latest model data from OpenRouter (requires OPENROUTER_API_KEY)
  • pnpm --filter=@funkai/models generate:models --force — Force-fetch ignoring staleness cache

Project Layout

  • packages/models — @funkai/models — Model catalog, provider resolution, and cost calculations
  • packages/agents — @funkai/agents — Lightweight workflow and agent orchestration framework
  • packages/prompts — @funkai/prompts — Prompt SDK with LiquidJS templating and Zod validation
  • contributing/ — Contributing standards, guides, and architectural concepts
  • Workspace packages: @funkai/<name>

For architectural details, see Architecture.

Git Workflow

  • Commit format: Conventional Commits (type(scope): description)
  • Types: feat, fix, docs, refactor, test, chore, perf, style, ci, deps, revert
  • Scopes: packages/models, packages/agents, packages/prompts, workspace, tooling
  • Changesets: Run pnpm changeset for changes to published packages. All @funkai/* packages are pre-1.0 — use minor for breaking changes, patch for non-breaking. Never use major until the team decides to release 1.0. CI will reject PRs with major bumps.
  • PR standards: Keep PRs focused — one feature/fix per PR

For details, see Commit Standards and PR Standards.

Documentation

  • packages/models/docs/ — Model catalog and provider resolution (catalog, providers, cost tracking, guides)
  • packages/agents/docs/ — Agent SDK documentation (core concepts, guides, provider info)
  • packages/prompts/docs/ — Prompt SDK documentation (CLI, file format, codegen, guides)
  • contributing/ — Contributing docs (standards, concepts, guides)