Repo-specific guide to the Ever Works monorepo (ever-works/ever-works) — its pnpm + Turborepo layout, the per-workspace test runners (Jest vs Vitest vs Playwright), file-naming and import-alias conventions, the commit/branch model, and the real build/lint/type-check commands. Use this whenever working anywhere in this repository so changes match the codebase's actual conventions and pass CI.
Repo-specific guide to the Ever Works monorepo (ever-works/ever-works) — its pnpm + Turborepo layout, the per-workspace test runners (Jest vs Vitest vs Playwright), file-naming and import-alias conventions, the commit/branch model, and the real build/lint/type-check commands. Use this whenever working anywhere in this repository so changes match the codebase's actual conventions and pass CI.
Ever Works monorepo
Ever Works is an open-source, AI-powered work/content builder platform — an
open agentic runtime that researches, ships, and maintains content-rich websites
and Git repositories.
Read the repo's own instructions first.AGENTS.md (repo root) routes agents
to CLAUDE.md (repo root), which is the canonical, authoritative rule set.
This skill is a concise summary of those files plus conventions verified from the
code. If anything here ever diverges from CLAUDE.md, CLAUDE.md wins — do
not treat this skill as a replacement for it.
Monorepo layout (Turborepo + pnpm workspaces)
Workspaces are apps/*, packages/*, and packages/plugins/*; Turborepo orders
builds via ^build.
apps/api — NestJS 11 REST API (SWC compiler, TypeORM, JWT + OAuth). Dev port 3100.
apps/web — Next.js 16 App Router (React 19, Tailwind CSS 4, next-intl). Dev port 3000.
packages/agent — @ever-works/agent, the core AI agent logic (NestJS + SWC), 21 sub-module exports; consumed by the API.
packages/plugins/* — 39 provider plugins (ai-provider, ai-gateway, search, content-extractor, screenshot, git-provider, deployment, pipeline, …). Each is ESM, built with tsup, tested with Vitest.
docs/ — markdown docs content; .specify/ — GitHub Spec Kit (feature specs live under docs/specs/features/).
Commands (pnpm only — never npm/yarn; Node >= 22)
pnpm install
pnpm dev:web # Next.js app on :3000 (next dev --turbopack)
pnpm dev:api # NestJS API on :3100
pnpm build # Turborepo build (excludes apps/docs)
pnpm build:web # single target; also build:api, build:plugins, build:packages
pnpm type-check # tsc --noEmit across all workspaces
pnpm lint # ESLint (flat config, eslint.config.mjs — ESLint 9)
pnpm format # Prettier (format:check to verify only)
pnpm test# All unit tests (turbo fans out to each workspace's runner)
pnpm test:e2e # Web Playwright e2e
Package manager is pinned: pnpm@10.33.3. Run pnpm install after adding deps.
Testing (three runners — use the one the package uses)
Ever Works uses Jest and Vitest, split by build tooling (see the repo's own
docs/testing/overview.md), plus Playwright for web e2e:
Jest — packages/agent (~26 suites / ~719 tests, packages/agent/jest.config.js) and apps/api (apps/api/jest.config.js). These are the SWC/NestJS packages. Test files are *.spec.ts.
cd packages/agent && pnpm test · pnpm test:cov · npx jest --testPathPattern='generators'
cd apps/api && pnpm test
Vitest — packages/plugin, every packages/plugins/*, and apps/web unit tests. Test files are *.spec.ts.
cd packages/plugins/openai && pnpm test · npx vitest run src/openai.spec.ts
cd apps/web && pnpm test (web unit)
Playwright — apps/web end-to-end. Specs in apps/web/e2e/*.spec.ts, config apps/web/playwright.config.ts.
cd apps/web && pnpm test:e2e (or pnpm test:e2e from the repo root)
Root pnpm test runs turbo run test, delegating to each workspace's own runner.
File & symbol naming
Follow the "Code Style → Naming" section of CLAUDE.md as authoritative. Verified
across the tree, the working rules are:
kebab-case for all non-component TypeScript files: NestJS *.service.ts, *.controller.ts, *.module.ts, *.dto.ts, entities, guards, and shared/agent modules (e.g. tenant-job-runtime.service.ts, account-import.service.ts); web hooks are use-*.ts (e.g. use-local-storage.ts); lib/ and utility files are kebab-case too.
PascalCase for React component files under apps/web/src/components/** and apps/docs/src/theme/** (e.g. ActivityTable.tsx, AgentActivityClient.tsx). This is the dominant convention for components (~340 files).
lowercase reserved names for Next.js App Router files — page.tsx, layout.tsx, loading.tsx, route.ts, etc. (framework-required).
Symbols: PascalCase for classes / interfaces / types, camelCase for functions / variables, UPPER_SNAKE_CASE for constants.
A few legacy files deviate (a camelCase hook, a kebab-case component). When unsure, match the sibling files in the directory you are editing and defer to CLAUDE.md.
Imports & path aliases
@/* → apps/web/src/* (web). e.g. import { APP_NAME } from '@/lib/constants'.
@src/* → apps/api/src/* (api).
@ever-works/* → workspace packages. e.g. import { BasePlugin } from '@ever-works/plugin'; plugins also import sub-paths such as @ever-works/plugin/abstract and @ever-works/plugin/ai.
Use relative imports within the same feature folder. There is no import-renaming convention (import { X as Y }) — do not introduce one.
Code style
Prettier formats the repo. The root package.json config (tabs, print width 120, single quotes, semicolons, no trailing commas) takes precedence over the per-package .prettierrc (spaces, width 100). Run pnpm format; don't hand-fight it.
Conventional Commits, enforced by commitlint (@commitlint/config-conventional, run via husky): feat:, fix:, docs:, refactor:, test:, chore: (plus the standard build, ci, perf, style, revert). Scopes are welcome, e.g. feat(api): ….
Branches:develop (default / integration) → stage → main (production). Promote changes forward through the cascade — open a PR from develop → stage, then stage → main; the repo uses dedicated cascade/* branches for these promotions. Merge the whole branch forward rather than cherry-picking individual commits.
Deployment (do not run ad-hoc deploy commands)
Apps ship as containers (node:22-alpine) to Kubernetes via GitOps. The API
self-applies pending TypeORM migrations on boot (migrationsRun, gated by the
RUN_MIGRATIONS env). Trigger.dev tasks deploy via pnpm deploy:trigger. Do not
invent or run other deploy / kubectl commands from this repository.
Gotchas
Web build uses Webpack, not Turbopack.apps/web builds with next build --webpack (dev uses --turbopack). Keep the --webpack flag on the build script.
Build shared packages before type-checking / testing.@ever-works/contracts and @ever-works/plugin must be built (pnpm build / pnpm build:plugins) before apps/web type-check or agent tests can resolve them. The agent Jest config also maps those packages to source via moduleNameMapper — if test imports fail, build first.
TypeORM migrations ship with entity changes. Any entity/schema change needs a migration in the same PR (apps/api/src/migrations/). See docs/specs/architecture/database-migrations.md.
DTS build failure with conditional spreads....cond && { key: value } yields string | false and breaks declaration emit — use explicit if blocks to add properties conditionally.
No stray docs in the repo root. Working/plan/summary/tracker markdown goes under docs/internal/ (or docs/specs/<feature>/), never the root — see AGENTS.md / CLAUDE.md.
UI & design patterns
Canonical CTA rules (light vs dark mode) and KPI / stat-card rules live in
references/ui-patterns.md. Follow them for
apps/web UI work.
Authoritative source
AGENTS.md → CLAUDE.md (repo root) are the source of truth; AUGMENT.md and
.github/copilot-instructions.md add tool-specific notes. Prefer updating
CLAUDE.md over duplicating rules here.
