AGENTS.md · diff
git:20261111.8d21eb5 to git:20261111.605406d
18 added, 0 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
# AGENTS.md
OpenWork is a free, open-source desktop app (macOS, Windows, Linux) for doing
work with AI agents on your own files — an open-source alternative to Claude
Cowork and Codex, built on OpenCode, running any model from 50+ providers.
Desktop mode keeps files local; cloud is optional. Three surfaces live in this
repo:
* **Desktop app** (`apps/`, `packages/`) — local-first agent workspace: chat on
files, skills, browser automation, scheduled automations, Anthropic-compatible
plugins.
* **OpenWork MCP gateway** (`ee/apps/den-api`) — one URL
(`api.openworklabs.com/mcp/agent`) that brings org-assigned skills, plugins,
and connections (Google Workspace, Microsoft 365, MCPs) into Codex, Claude
Code, Cursor, or any MCP client via `search_capabilities` /
`execute_capability`.
* **OpenWork Den** (`ee/apps/den-*`) — the org control plane: provision
inference, manage teams and access, set desktop policies, publish skills and
plugins through marketplaces.
The app consumes OpenWork server surfaces (self-hosted or hosted) rather than
inventing parallel behavior. Anything OpenCode can do is available in OpenWork,
even before a dedicated UI exists.
OpenCode v2 is the default. Hosts select v2 when idle; vanilla upstream OpenCode
owns in-place history migration on startup. Keep populated legacy separate v2
stores readable; never revive OpenWork's retired history-copy worker or locks.
Respect explicit manual engine choices and local support/test overrides; never
restore the retired `engineV2ForceUpgrade` gate. See `docs/opencode-engine-migration.md`.
Customer-cloud managed installation architecture lives in
`infra/managed-deployments/README.md` and `docs/managed-deployments.md`. AWS
uses CloudFormation/CodeBuild; GCP uses customer-approved Cloud Shell and
impersonated Terraform behind `managedDeployments` (cloud only, off), the same
switch as AWS and the deployment agent tools.
Installer publication/configuration is an operator action, not CLI sign-in or a
feature rollout. Never fake readiness; local tests do not prove a live install.
Killing a rollout blocks launches without deleting customer resources or
interrupting authenticated enrollment/health reports.
## Confidentiality (hard rule — this repo is public)
Never let a branch name, commit, PR text, comment, fixture, or evidence identify
a customer, prospect, partner, or outside person; use internal ticket IDs, and
escalate any leak instead of rewriting history.
## Generated API contracts
Den route metadata and shared schemas are the source of truth. OpenAPI and
`packages/sdk/src/gen/**` are ignored build artifacts: never commit or hand-edit
them. CI generates, lints and typechecks them from the PR source and uploads
an artifact. Hosted docs read the normalized deployed contract at
`/openapi.json?public=1`; the raw `/openapi.json` remains available.
`pnpm sdk:build` and SDK typechecks generate missing or stale artifacts first.
`pnpm den:contract` forces a clean generation and prepares/removes a disposable
local MySQL database. Start MySQL with `pnpm dev:den:mysql`; only
`OPENWORK_CONTRACT_MYSQL_URL` can select alternate localhost credentials.
`DATABASE_URL` is never used for generation. After a merge/rebase regenerate
locally when needed; generated files do not enter the merge. Never regenerate
a Drizzle migration snapshot to resolve an API conflict.
Optional: `pnpm hooks:install` enables source validation before commits. It
refuses unstaged/untracked contract inputs and never stages generated outputs.
Hooks never commit, push, or change CI policy; CI remains authoritative.
## Coding
* pnpm only, never npm/yarn. TypeScript: never `any`, typecasts, or `as` unless
100% necessary or instructed.
* Prefer Tailwind, React, shadcn/ui (Base UI), TanStack Query, Zustand, Zod,
Drizzle, Better-Auth. Reuse `@/components`; end users are non-technical.
* Put any change to product behavior that users can see behind a feature
flag, so it can be turned off without a deploy: new or changed flows,
screens, options and defaults. Ship directly only what users won't notice
as a behavior change: fixes that restore intended behavior, polish,
refactors, tests and `/admin` tooling. When unsure, flag. Follow
`.opencode/skills/add-a-feature`.
* Any user-facing UI (desktop app, Den web, MCP Apps, artifact views) follows
`DESIGN.md`: read it before designing, cite its rule ids in PRs, and attach
screenshots of new UI.
+ ## Modules Node loads from source
+
+ Den API and the Gateway run in plain Node and load many workspace exports
+ straight from TypeScript source (`"default": "./src/x.ts"`, most of
+ `@openwork/types/den/*`). Node only removes the types. Development, tests and
+ typecheck are more forgiving, so these pass there and fail the deploy:
+
+ * A relative import without the real file name (`"./sibling"`,
+ `"./sibling.js"`). Import the sibling by package name:
+ `"@openwork/types/den/sibling"`.
+ * A type imported or re-exported without `type`.
+ * `enum`, a namespace with values, constructor parameter properties, `.tsx`.
+
+ After changing a package these services import, or what they import, run
+ `pnpm check:node-source-imports` (two seconds, no build). It runs on every PR.
+ A new service that runs unbundled in Node goes in `SERVICES` in
+ `scripts/check-node-source-imports.mjs`.
+
## Verify changes headless
Launching the desktop app on a developer's computer opens a window that takes
focus. Check app UI in headless Chrome instead:
* Specs: `seed.appWeb` (`write-a-spec`); `run-tests` explains which placement
tests your working tree.
* By hand: `pnpm world up dev-app-web --detach -- --browser`, then drive the
printed `cdp` address (`drive-desktop-cdp`).
* Use the desktop app (`seed.desktop`, `pnpm dev`, `preview-desktop`,
`live-desktop`) only when the user asks or the change needs the desktop
shell: titlebar and window controls, native menus and dialogs, `openwork://`
links and OAuth hand-off, the built-in browser pane, updater, quit and
relaunch, or packaged builds. Prefer `--daytona` for those so the window
opens in a sandbox; Daytona builds a pushed commit, not your working tree.