AGENTS.md · diff

git:20261113.52332f7 to git:20261115.d7237d2

34 added, 108 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 or expose internal ticket IDs.
- Use semantic names and generic descriptions; keep customer/task-to-PR links
- private. 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
+ OpenWork is an open-source desktop app for doing work with AI agents on your
+ own files, built on OpenCode. This repo is public.
- 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:
+ * `apps/`, `packages/`: the desktop app.
+ * `ee/apps/den-api`: the MCP gateway.
+ * `ee/apps/den-*`: Den, the org control plane.
- * 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`.
+ ## Rules
- 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`.
+ * **Confidentiality.** Never let a branch name, commit, PR text, comment,
+ fixture, or evidence identify a customer, prospect, partner, or outside
+ person, or expose internal ticket IDs. Escalate a leak instead of rewriting
+ history.
+ * **Feature flags.** Any change to product behavior that users can see goes
+ behind a flag (`add-a-feature`). When unsure, flag.
+ * **UI follows `DESIGN.md`.** Cite its rule ids in the PR and attach
+ screenshots.
+ * **Generated contracts.** Never commit or hand-edit OpenAPI or
+ `packages/sdk/src/gen/**`. Never regenerate a Drizzle migration snapshot to
+ resolve a conflict.
+ * **Code.** pnpm only. No `any`, typecasts, or `as` unless unavoidable. Reuse
+ `@/components`; end users are non-technical.
+ * **Fix the root cause.** A workaround you find is debt to remove, not a
+ pattern to copy. Never write a comment or doc that justifies a shortcut.
+ * Den API and the Gateway load TypeScript source in plain Node: after changing
+ what they import, run `pnpm check:node-source-imports`.
- ## Verify changes headless
+ ## Prove it works
- Launching the desktop app on a developer's computer opens a window that takes
- focus. Check app UI in headless Chrome instead:
+ A change is done when it is proven on the real product, not when it compiles
+ (`verify-openwork`, `write-a-spec`, `run-tests`). Check UI headless:
+ `pnpm world up dev-app-web --detach -- --browser`, then `drive-desktop-cdp`.
+ Open a desktop window only when the user asks or the change needs the desktop
+ shell, and prefer `--daytona`.
- * 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.
+ ## Keep this file small
+ Prose is the weakest guardrail. When an agent gets something wrong, make the
+ mistake impossible in code, or catch it with a lint rule, type, or test. Add a
+ line here or a skill only for judgment no check can encode, and delete it when
+ a check replaces it.