AGENTS.md · Automattic/wp-calypso

Sections

1. Confidentiality
2. Repository layout
3. Clients
4. Packages
5. Apps
6. Development
7. Testing instructions
8. Conventions
9. Pre-PR checks
10. Creating Pull Requests

First lines (shown under the repo's GPL-2.0 license)

# AGENTS.md

## Confidentiality

CRITICAL: This is a **public repository**. Never put an internal link or hostname in a PR description, review comment, commit message, code comment, or any other public-facing text: no wordpress.com URLs (internal sites and P2s), no Slack, Linear, HackerOne, private GitHub repository, or GitHub Enterprise URLs, and no other internal tool URLs. Use shortlinks instead: `PCYsg-hS-p2` for a P2 post, `p<message>-slack-<channel>` for a Slack message (`p<message>/<thread>-slack-<channel>` for a reply in a thread), and the bare issue key (`LIN-123`) for Linear.

## Repository layout

- client/ — main application clients, deployed as single-page React apps.
- packages/ — shared libraries across clients.
- apps/ — standalone mini-apps, deployed separately.

## Clients

- **Calypso** — the classic WordPress.com hosting dashboard, sharing data using Redux and split via Webpack section chunks.
  - client/my-sites — per-site management; deprecated in favor of the Dashboard client
  - client/my-sites/checkout — checkout flow
  - client/me/purchases — redirects to the Dashboard billing screens, plus purchase helpers shared by other sections
  - client/landing/stepper — onboarding/signup flows (site creation, domain purchase, migration wizards)
  - client/reader — WordPress.com Reader: feed streams, discover, conversations, likes, lists, following management
  - Shared infra: client/components, client/state, client/lib, client/layout
- **Jetpack Cloud** (client/jetpack-cloud) — reuses Calypso shared infra (client/state, client/components).
- **A8C for Agencies** (client/a8c-for-agencies) — reuses Calypso shared infra.
- **Dashboard** (client/dashboard) — the new multi-site dashboard. Self-contained: does not reuse Calypso client code. Has its own components, data fetching (TanStack Query), and routing (TanStack Router).
  - client/dashboard/me/billing-purchases — billing & purchase management

## Packages

- **Agents Manager** (`packages/agents-manager`) — shared component library for WordPress.com's unified AI agent experience, running in Calypso, the Dashboard, Simple and Atomic sites, the WooCommerce AI admin and Reader Chat. Also deployed via `apps/agents-manager/` to `widgets.wp.com`. See its `AGENTS.md` for architecture and conventions.
- **AI UI Renderer** (`packages/ai-ui-renderer`) — reusable A2UI v1.0 catalog and rendering primitives built with WordPress components. Agents Manager consumes it; conversation handling and MCP transport stay in consumers.
- **Agenttic** (`packages/agenttic-client`, `packages/agenttic-ui`) — AI agent chat client library and UI components. Also published to npm for consumers outside this repo. ⚠️ Still on its pre-migration package layout (vite-built, ESM-only, flat `dist/`, no `calypso:src`); normalizing it is a future goal, but the published artifact shape is a contract with external consumers — read the Development and Releasing sections in `packages/agenttic-client/README.md` before restructuring or publishing.
- **Help Center** (`packages/help-center`) — shared component library for WordPress.com support. Also deployed via `apps/help-center/` to `widgets.wp.com`.
- **Image Studio** (`packages/image-studio`) — AI-powered image editing and generation. When adding Image Studio entry points, read [packages/image-studio/AGENTS.md](packages/image-studio/AGENTS.md).
- **Calypso Products** (`packages/calypso-products`) — ⚠️ **Avoid.** Deprecated/frozen: a bloated client-side duplicate of product data the backend already owns. Don't add to it; prefer backend-driven data (e.g. `@automattic/api-queries`). See `packages/calypso-products/AGENTS.md`.

## Apps

- **Agents Manager** (`apps/agents-manager`) — build/deploy layer that bundles `packages/agents-manager` into webpack entry points served from `widgets.wp.com`.
- **Help Center** (`apps/help-center`) — build/deploy layer that bundles `packages/help-center` into webpack entry points served from `widgets.wp.com`.
- **Survicate** (`apps/survicate`) — build/deploy layer that bundles `packages/survicate` into the single script wp-admin loads from `widgets.wp.com`. No logic of its own.

## Development

> **Note**: The Calypso dev server uses the `PORT` environment variable (check repo-root `.env`) and falls back to port `3000`. Do not create or modify `.env` unless explicitly asked.

> **Note**: Keep the `@automattic/` scope whenever a command sends a workspace package name to the npm registry (`npm view`, `npx`, `yarn add`, `yarn npm info`). For a `"private": true` package, read its `package.json` instead of the registry.

```bash
# Setup
yarn install

# Build and start the dev server
yarn start

# Build and start the dev server for the Dashboard client only.
yarn start-dashboard
```

If `yarn start` fails with `Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory`, increase the Node heap size by running `NODE_OPTIONS=--max-old-space-size=8192 yarn start`. For other errors, run `yarn calypso-doctor` to diagnose and fix common environment issues.

### Checking a change in a browser

- Use the Node version in `.nvmrc`. The first webpack build takes several minutes after "wp-calypso booted"; until it finishes the page shows only the W logo.
- Sign in on `wordpress.com/log-in` first, then open `calypso.localhost:3000/read?flags=oauth` once. Signing in on the calypso.localhost form doesn't stick, because the login cookie is refused as a cross-site cookie.
- With `?flags=oauth`, loading or reloading a signed-in URL directly (for example `/tags`) redirects to `/discover`, because the server can't see the sign-in. Load `/read?flags=oauth`, wait for the Reader, then navigate inside the app.
- A headless or automated Chrome profile blocks third-party cookies by default; allow them (see `docs/install.md`) or the app never sees the sign-in.
- Test with an account made for testing, never a personal one, and don't save network requests from the login: they hold the password and session cookies.

## Testing instructions

> **Note**: E2E tests require a local Calypso development instance to be running.

```bash
# JavaScript tests
yarn test                                       # Run unit tests for client, packages, server, and build-tools
yarn test-build-tools                           # Run unit tests for build-tools
yarn test-client                                # Run unit tests for client
yarn test-integration                           # Run integration tests
yarn test-apps                                  # Run apps unit tests
yarn test-packages                              # Run packages unit tests
yarn test-server                                # Run server unit tests
yarn test-server:coverage                       # Run server unit tests with coverage info

yarn test-client:watch                          # Run unit tests for client in watch mode
yarn test-client <path_to_test_directory>       # Run client unit tests from a specific directory
yarn test-client --testNamePattern="<TestName>" # Run a specific client unit test

# E2E tests - refer to: test/e2e/AGENTS.md

# Code Quality
yarn lint             # Lint everything
yarn lint:css         # Lint CSS
yarn lint:js          # Lint JavaScript
yarn reformat-files   # Fix formatting with Prettier
yarn typecheck-client # Type-check client
```

## Conventions

- Do NOT add any verbose code comments that narrate what the change does or why it was made (e.g. `// Added this to fix X`, `// Changed from Y to Z`, restating the code in prose). Such explanation belongs in the PR description, not the source. Only keep comments that a future reader genuinely needs — non-obvious rationale, gotchas, links to context — and match the comment density and style of the surrounding code.

## Pre-PR checks

Before pushing a branch or running `gh pr create`, run the type-check that CI will run. PRs touching `client/` may fail the `type_check_client` CI check after opening, so verify locally first:

```bash
yarn               # Install dependencies first if you haven't already
yarn typecheck-client
```

If it runs out of memory, give it a bigger heap: `NODE_OPTIONS=--max-old-space-size=12288 yarn typecheck-client`. If it fails on a workspace package that has no `dist/` yet, build that package first (`cd packages/<name> && yarn build`).

If it fails, fix the type errors at the source — do not silence them with `// @ts-expect-error`, `// @ts-ignore`, or `as any` unless you can justify it in the PR description. Other CI type-checks worth running when relevant: `yarn typecheck-packages`, `yarn typecheck-apps`.

## Creating Pull Requests

- Create PRs as draft. Follow the template in .github/PULL_REQUEST_TEMPLATE.md.
- Branch naming (see `docs/git-workflow.md`): branch off `trunk` and prefix with `add/` (new feature), `update/` (iterating on existing), `fix/` (fixing something broken), or `try/` (experiment). Use a **single slash only** — multiple slashes break Calypso Live testing. Do NOT use Linear's autogenerated `gitBranchName` (e.g. `dotcom-17900-…`); it has no prefix and violates this convention. For the Signup accepts-props initiative, follow the established pattern `add/stepper-<step>-accepts-props` (e.g. `add/stepper-user-step-accepts-props`, `add/stepper-unified-plans-accepts-props`).
- In the PR description:
  - Use Linear issue IDs (e.g., `LIN-123`) instead of full Linear URLs.
  - Avoid mentioning people's names.
  - Include all checklist items from .github/PULL_REQUEST_TEMPLATE.md. Only mark items as completed (`[x]`) if they actually apply; leave inapplicable items unchecked (`[ ]`).
  - For a change users can see (UI, or new or changed translatable strings), add before/after screenshots under Testing Instructions. Reviewers check the expected state against them, and the a8ci18n bot asks for a screenshot of the new strings for translators. Capture with a test account and keep internal hostnames and personal data out of the image. If you can't upload images, say so in the description. Never commit images to the repository to host them.