Skip to content

The open alternative to Salesforce, designed for AI.

docs(codex-plugin): use apply and plan commands (#24512)

Félix Malfait8896d8e56508
diff --git a/packages/twenty-codex-plugin/AGENTS.md b/packages/twenty-codex-plugin/AGENTS.md
index cc956339096..9c1ad1ee63b 100644
--- a/packages/twenty-codex-plugin/AGENTS.md
+++ b/packages/twenty-codex-plugin/AGENTS.md
@@ -33,9 +33,9 @@ If the user's request straddles two skills, do the boundary task in the first sk
These rules apply in every skill. They exist because they have failed before.
-1. **One-shot sync only.** Use `yarn twenty dev --once` to synchronize app changes. Never `yarn twenty dev` (watch mode). Watch mode leaks file handles and produces ambiguous failure output in agent sandboxes.
+1. **Bounded sync only.** Use `yarn twenty apply` to synchronize app changes. Never `yarn twenty dev` (watch mode). Watch mode leaks file handles and produces ambiguous failure output in agent sandboxes.
-2. **Do not run broad validation unless it is requested.** After scaffolding (`create-twenty-app`) or after the CLI generates entities, prefer the bounded command that matches the task: `yarn twenty dev --once` for app sync, the package's unit-test script for unit tests, and `TWENTY_API_URL=http://localhost:2021 yarn test` for the full integration suite. Integration tests must target the isolated test instance on port `2021`, not the dev instance on port `2020`, unless the user explicitly asks otherwise.
+2. **Do not run broad validation unless it is requested.** After scaffolding (`create-twenty-app`) or after the CLI generates entities, prefer the bounded command that matches the task: `yarn twenty apply` for app sync, the package's unit-test script for unit tests, and `TWENTY_API_URL=http://localhost:2021 yarn test` for the full integration suite. Integration tests must target the isolated test instance on port `2021`, not the dev instance on port `2020`, unless the user explicitly asks otherwise.
3. **Use `yarn twenty dev:add` for new entities.** It generates correct file structure, UUIDs, SDK imports, and boilerplate. Do not hand-craft entity files unless modifying existing ones or the CLI does not support that entity type.
diff --git a/packages/twenty-codex-plugin/assets/screenshots/README.md b/packages/twenty-codex-plugin/assets/screenshots/README.md
index 9ecd6029c93..940c56c9320 100644
--- a/packages/twenty-codex-plugin/assets/screenshots/README.md
+++ b/packages/twenty-codex-plugin/assets/screenshots/README.md
@@ -7,7 +7,7 @@ The Codex marketplace listing for the Twenty plugin requires ≥ 1 screenshot sh
Three screenshots, all PNG, at marketplace resolution (preferably 1600×1000 or higher, 16:10):
1. **`01-create-app.png`** — `create-app` mid-flow: user prompt asking to scaffold a new Twenty app, the agent asking for the instance URL, and the `create-twenty-app` output visible.
-2. **`02-develop-and-sync.png`** — `develop-app` adding an entity through `yarn twenty dev:add`, followed by `yarn twenty dev --once` syncing successfully.
+2. **`02-develop-and-sync.png`** — `develop-app` adding an entity through `yarn twenty dev:add`, followed by `yarn twenty apply` syncing successfully.
3. **`03-use-twenty-mcp.png`** — `use-twenty-mcp` retrieving a workspace records table where the record-name column is rendered as a linked Markdown table.
## After Adding the Files
diff --git a/packages/twenty-codex-plugin/references/concepts/how-apps-work.md b/packages/twenty-codex-plugin/references/concepts/how-apps-work.md
index 0390597509f..a3333b9d6a5 100644
--- a/packages/twenty-codex-plugin/references/concepts/how-apps-work.md
+++ b/packages/twenty-codex-plugin/references/concepts/how-apps-work.md
@@ -51,11 +51,11 @@ The development loop is:
create → develop → sync → validate → repeat
```
-1. **Create**: `npx create-twenty-app@latest <app-name>` generates the project, installs dependencies, starts a local Twenty server, and runs an initial sync. The scaffolder handles everything in one command — do not run `yarn twenty dev --once` after scaffolding because the sync already happened.
+1. **Create**: `npx create-twenty-app@latest <app-name>` generates the project, installs dependencies, starts a local Twenty server, and runs an initial sync. The scaffolder handles everything in one command — do not run `yarn twenty apply` after scaffolding because the sync already happened.
2. **Develop**: Add or modify entities in `src/`. Objects go in `src/objects/`, front components in `src/front-components/`, logic functions in `src/logic-functions/`, page layouts in `src/page-layouts/`, and so on. Each entity file exports a `define*` call.
-3. **Sync**: `yarn twenty dev --once` builds, deploys, and installs the app on the active remote in one step. The Twenty instance updates its schema, registers new objects and fields, mounts front components, and activates logic functions. This is the primary way to get changes onto a Twenty instance during development. Sync after every meaningful change.
+3. **Sync**: `yarn twenty apply` builds, deploys, and installs the app on the active remote in one step. The Twenty instance updates its schema, registers new objects and fields, mounts front components, and activates logic functions. This is the primary way to get changes onto a Twenty instance during development. Sync after every meaningful change.
4. **Validate**: `yarn twenty dev:typecheck` checks generated types. `yarn lint` checks local lint rules. Open the workspace in a browser to verify front components render and logic functions execute.
@@ -106,5 +106,5 @@ my-app/
- **Universal identifiers**: Stable UUIDs assigned to every entity. They survive renames, version bumps, and resyncs. Never change a universal identifier after first sync.
- **Remotes**: Named connections to Twenty instances. Stored in `~/.twenty/config.json`. Switch with `yarn twenty remote:use <name>`.
-- **Sync**: `yarn twenty dev --once` builds, deploys, and installs the app on the active remote in one step. This is the standard way to get code changes onto a Twenty instance.
+- **Sync**: `yarn twenty apply` builds, deploys, and installs the app on the active remote in one step. This is the standard way to get code changes onto a Twenty instance.
- **Publish**: `yarn twenty app:publish` packages the app for distribution to other instances or the marketplace. Requires a strictly higher semver version than the previously published version.
diff --git a/packages/twenty-codex-plugin/references/develop-app/app-structure.md b/packages/twenty-codex-plugin/references/develop-app/app-structure.md
index bdbbc5fda0e..e608aa135d2 100644
--- a/packages/twenty-codex-plugin/references/develop-app/app-structure.md
+++ b/packages/twenty-codex-plugin/references/develop-app/app-structure.md
@@ -102,10 +102,10 @@ Once all edits for the change are complete, run lint and typecheck once at the e
```bash
yarn twenty dev:typecheck
yarn lint
-yarn twenty dev --once
+yarn twenty apply
```
-`yarn twenty dev:typecheck` checks generated app types and `yarn lint` checks local lint rules. `yarn twenty dev --once` then builds the app and pushes entity definitions to the active remote; if any definition is invalid, the sync reports the error. Run all three a single time once every edit is done, not repeatedly after each step.
+`yarn twenty dev:typecheck` checks generated app types and `yarn lint` checks local lint rules. `yarn twenty apply` then builds the app and pushes entity definitions to the active remote; if any definition is invalid, the sync reports the error. Run all three a single time once every edit is done, not repeatedly after each step.
When the user explicitly asks to run tests, follow `tests.md`: unit tests may use the package's unit-test script, and the full suite must run with `TWENTY_API_URL=http://localhost:2021` against the isolated test instance.
diff --git a/packages/twenty-codex-plugin/references/develop-app/standalone-pages.md b/packages/twenty-codex-plugin/references/develop-app/standalone-pages.md
index 8db83e663ca..16e8410165b 100644
--- a/packages/twenty-codex-plugin/references/develop-app/standalone-pages.md
+++ b/packages/twenty-codex-plugin/references/develop-app/standalone-pages.md
@@ -400,10 +400,10 @@ If this renders but the full page does not, the issue is inside the full compone
## Deployment And Verification
-Use local dev sync while iterating and one-shot sync for bounded verification. Use `../manage-app/cli-and-sync.md` for exact command behavior, remote setup, verbose troubleshooting, deploys, and logs.
+Use bounded apply for deployment and verification. Use `../manage-app/cli-and-sync.md` for exact command behavior, remote setup, verbose troubleshooting, deploys, and logs.
```bash
-yarn twenty dev --once
+yarn twenty apply
```
Install and update flow:
diff --git a/packages/twenty-codex-plugin/references/develop-app/tests.md b/packages/twenty-codex-plugin/references/develop-app/tests.md
index 754d627d3f8..f8096f6a684 100644
--- a/packages/twenty-codex-plugin/references/develop-app/tests.md
+++ b/packages/twenty-codex-plugin/references/develop-app/tests.md
@@ -1,6 +1,6 @@
# Tests
-Tests use the `*.spec.ts` extension and live in sibling `__tests__/` folders next to the code they cover, matching Twenty backend conventions. Write them where `yarn twenty dev --once` does not validate correctness.
+Tests use the `*.spec.ts` extension and live in sibling `__tests__/` folders next to the code they cover, matching Twenty backend conventions. Write them where `yarn twenty apply` does not validate correctness.
Always write a test file for every util or function. Whenever you create or modify a file in `src/utils/` (or any other testable function file), you MUST create or update its sibling `__tests__/<name>.spec.ts`. A util or function without a spec file is incomplete.
@@ -31,7 +31,7 @@ src/utils/__tests__/map-bar.util.spec.ts
## Running Tests
-Integration tests build, deploy, install, and uninstall the app on whatever server `TWENTY_API_URL` points to. The scaffold defaults to the dev instance (`http://localhost:2020`), so running them there adds and then removes the app from the workspace you sync to with `yarn twenty dev --once`. Always run them against the isolated test instance instead — a separate container, database, and port (`2021`) that does not affect your running dev instance:
+Integration tests build, deploy, install, and uninstall the app on whatever server `TWENTY_API_URL` points to. The scaffold defaults to the dev instance (`http://localhost:2020`), so running them there adds and then removes the app from the workspace you sync to with `yarn twenty apply`. Always run them against the isolated test instance instead — a separate container, database, and port (`2021`) that does not affect your running dev instance:
```bash
# Start the isolated test instance (once).
diff --git a/packages/twenty-codex-plugin/references/develop-app/workflows.md b/packages/twenty-codex-plugin/references/develop-app/workflows.md
index 2587d34aabd..90dcbe9e60b 100644
--- a/packages/twenty-codex-plugin/references/develop-app/workflows.md
+++ b/packages/twenty-codex-plugin/references/develop-app/workflows.md
@@ -44,4 +44,4 @@ Seeders need workflow settings permissions on the app role. Grant via `defineRol
yarn twenty dev:function:exec
```
-`yarn twenty dev --once` skips install hooks. Run again after rebuilding to verify idempotency.
+`yarn twenty apply` skips install hooks. Run it again after rebuilding to verify idempotency.
diff --git a/packages/twenty-codex-plugin/references/manage-app/cli-and-sync.md b/packages/twenty-codex-plugin/references/manage-app/cli-and-sync.md
index a45d352f2fe..4bb66419832 100644
--- a/packages/twenty-codex-plugin/references/manage-app/cli-and-sync.md
+++ b/packages/twenty-codex-plugin/references/manage-app/cli-and-sync.md
@@ -24,10 +24,24 @@ Use these commands to validate an app after changes:
```bash
yarn twenty dev:typecheck
yarn lint
-yarn twenty dev --once
```
-`yarn twenty dev:typecheck` checks generated app types and TypeScript compatibility. `yarn lint` checks local lint rules. `yarn twenty dev --once` performs a bounded build/sync against the active remote.
+If the app is already installed on the active remote, preview and then apply
+the metadata changes:
+
+```bash
+yarn twenty plan
+yarn twenty apply
+```
+
+`yarn twenty dev:typecheck` checks generated app types and TypeScript compatibility. `yarn lint` checks local lint rules. `yarn twenty plan` previews metadata changes, and `yarn twenty apply` performs a bounded build/sync against the active remote.
+
+`yarn twenty plan` is read-only and requires the app to already be installed
+on the active remote. For a first sync, run `yarn twenty apply`; it registers
+the app before synchronizing it. `create-twenty-app` normally performs this
+initial sync, so a successfully scaffolded app does not need an extra apply.
+Use the first-sync path when the scaffold sync failed, or when the app was
+created or copied without being installed on this remote.
If a validation command fails because of entity definitions, switch to `develop-app` for the fix. If it fails because of remotes, authentication, build tooling, sync, logs, deploys, or CI/CD, stay in `manage-app`.
@@ -58,20 +72,20 @@ When the user says "prod", "production", or "workspace de prod", identify the ta
## Development Sync
-Always use one-shot sync to synchronize app changes with the active remote:
+Use the bounded apply command to synchronize app changes with the active remote:
```bash
-yarn twenty dev --once
+yarn twenty apply
```
-Do not use bare `yarn twenty dev` (watch mode). Run `yarn twenty dev --once` each time changes need to be synced.
+Do not use bare `yarn twenty dev` (watch mode). Run `yarn twenty apply` each time changes need to be synced.
-One-shot sync requires an authenticated remote. If authentication fails, re-add or switch the remote before retrying.
+Apply requires an authenticated remote. If authentication fails, re-add or switch the remote before retrying.
-Use verbose one-shot sync for bounded troubleshooting:
+Use verbose apply for bounded troubleshooting:
```bash
-yarn twenty dev --once --verbose
+yarn twenty apply --verbose
```
## Troubleshooting
@@ -79,7 +93,7 @@ yarn twenty dev --once --verbose
Start by identifying which layer is failing:
- Remote/authentication.
-- Dev sync or one-shot sync.
+- Dev sync or apply.
- Build/package generation.
- Deploy/upload/install.
- Runtime function execution.
@@ -91,7 +105,7 @@ Collect the minimum useful context before changing configuration:
sed -n '1,220p' package.json
sed -n '1,220p' src/application-config.ts
yarn twenty remote:list
-yarn twenty dev --once --verbose
+yarn twenty apply --verbose
```
For remote or authentication issues:
@@ -103,7 +117,7 @@ For remote or authentication issues:
For sync issues:
-- Prefer `yarn twenty dev --once --verbose` to get a bounded failure.
+- Prefer `yarn twenty apply --verbose` to get a bounded failure.
- Check generated type or schema errors before editing app entities.
- If the app depends on a changed data model, use `develop-app` to fix the entity definitions.
diff --git a/packages/twenty-codex-plugin/references/publish-app/prepare-for-app-store.md b/packages/twenty-codex-plugin/references/publish-app/prepare-for-app-store.md
index 8d468c6cb5e..cf98a47de82 100644
--- a/packages/twenty-codex-plugin/references/publish-app/prepare-for-app-store.md
+++ b/packages/twenty-codex-plugin/references/publish-app/prepare-for-app-store.md
@@ -155,7 +155,7 @@ Logo guidance:
Screenshot guidance:
-- Capture real app surfaces after `yarn twenty dev --once` or watch-mode sync.
+- Capture real app surfaces after `yarn twenty apply` or watch-mode sync.
- Prefer the most useful user paths: app listing/about page, object index view, record page layout, front component surface, connection settings, or AI skill/agent behavior.
- Use seeded or synthetic data only.
- Hide browser chrome unless it helps explain setup.
@@ -196,7 +196,7 @@ If the app requires a specific Twenty server version, set `engines.twenty` in `p
Before considering README and visuals done:
```bash
-yarn twenty dev --once
+yarn twenty apply
yarn twenty dev:build
```
diff --git a/packages/twenty-codex-plugin/scripts/__tests__/validate.spec.js b/packages/twenty-codex-plugin/scripts/__tests__/validate.spec.js
index 24ecdbb556f..d2cc95a8254 100644
--- a/packages/twenty-codex-plugin/scripts/__tests__/validate.spec.js
+++ b/packages/twenty-codex-plugin/scripts/__tests__/validate.spec.js
@@ -111,6 +111,77 @@ test('assertCliGuidanceSplit passes on current state', () => {
assert.deepStrictEqual(collectFailures(crossDocContracts.assertCliGuidanceSplit), []);
});
+test('assertCliGuidanceSplit catches deprecated dev --once guidance', () => {
+ const cliAndSyncPath = path.join(
+ PLUGIN_ROOT,
+ 'references',
+ 'manage-app',
+ 'cli-and-sync.md',
+ );
+
+ withFileMutation(
+ cliAndSyncPath,
+ (contents) => contents.replace('yarn twenty apply', 'yarn twenty dev --once'),
+ () => {
+ const failures = collectFailures(crossDocContracts.assertCliGuidanceSplit);
+
+ assert.ok(
+ failures.some((failure) => failure.includes('yarn twenty dev --once')),
+ );
+ },
+ );
+});
+
+test('assertCliGuidanceSplit catches deprecated guidance outside the CLI reference', () => {
+ const manageSkillPath = path.join(
+ PLUGIN_ROOT,
+ 'skills',
+ 'manage-app',
+ 'SKILL.md',
+ );
+
+ withFileMutation(
+ manageSkillPath,
+ (contents) => `${contents}\nRun yarn twenty dev --once after editing.\n`,
+ () => {
+ const failures = collectFailures(crossDocContracts.assertCliGuidanceSplit);
+
+ assert.ok(
+ failures.some(
+ (failure) =>
+ failure.includes('skills/manage-app/SKILL.md') &&
+ failure.includes('yarn twenty dev --once'),
+ ),
+ );
+ },
+ );
+});
+
+test('assertCliGuidanceSplit catches stale one-shot sync terminology', () => {
+ const standalonePagesPath = path.join(
+ PLUGIN_ROOT,
+ 'references',
+ 'develop-app',
+ 'standalone-pages.md',
+ );
+
+ withFileMutation(
+ standalonePagesPath,
+ (contents) => `${contents}\nUse one-shot sync for verification.\n`,
+ () => {
+ const failures = collectFailures(crossDocContracts.assertCliGuidanceSplit);
+
+ assert.ok(
+ failures.some(
+ (failure) =>
+ failure.includes('references/develop-app/standalone-pages.md') &&
+ failure.includes('one-shot sync'),
+ ),
+ );
+ },
+ );
+});
+
test('assertTestingGuidance passes on current state', () => {
assert.deepStrictEqual(collectFailures(crossDocContracts.assertTestingGuidance), []);
});
diff --git a/packages/twenty-codex-plugin/scripts/validators/cross-doc-contracts.js b/packages/twenty-codex-plugin/scripts/validators/cross-doc-contracts.js
index 521f8a0020a..0cebd7e96e1 100644
--- a/packages/twenty-codex-plugin/scripts/validators/cross-doc-contracts.js
+++ b/packages/twenty-codex-plugin/scripts/validators/cross-doc-contracts.js
@@ -1,6 +1,6 @@
const path = require('node:path');
-const { PLUGIN_ROOT, readText } = require('./lib');
+const { PLUGIN_ROOT, listFiles, readText } = require('./lib');
const assertTwentyMcpFormattingContract = (fail) => {
const skillPath = path.join(PLUGIN_ROOT, 'skills/use-twenty-mcp/SKILL.md');
@@ -110,7 +110,7 @@ const assertFrontComponentGuidance = (fail) => {
'12 x 12 fill pattern',
'Full-Page Layout Guidance',
'black screen',
- 'yarn twenty dev --once',
+ 'yarn twenty apply',
];
for (const fragment of requiredStandalonePageFragments) {
@@ -122,7 +122,7 @@ const assertFrontComponentGuidance = (fail) => {
const requiredAppStructureFragments = [
'yarn twenty dev:typecheck',
'yarn lint',
- 'yarn twenty dev --once',
+ 'yarn twenty apply',
];
for (const fragment of requiredAppStructureFragments) {
@@ -206,7 +206,7 @@ const assertCliGuidanceSplit = (fail) => {
'run lint and typecheck once at the end (not after each individual edit)',
'yarn twenty dev:typecheck',
'yarn lint',
- 'yarn twenty dev --once',
+ 'yarn twenty apply',
];
for (const fragment of requiredAppStructureFragments) {
@@ -220,6 +220,7 @@ const assertCliGuidanceSplit = (fail) => {
'Use watch mode only',
'Use watch mode for interactive development',
'Use one-shot mode for agents',
+ 'yarn twenty dev --once',
'yarn twenty dev --once --verbose',
'yarn twenty remote:list',
'Do not run `yarn twenty dev:typecheck`',
@@ -261,10 +262,13 @@ const assertCliGuidanceSplit = (fail) => {
'# CLI And Sync',
'yarn twenty dev:typecheck',
'yarn lint',
- 'yarn twenty dev --once',
- 'Always use one-shot sync to synchronize app changes with the active remote',
+ 'yarn twenty plan',
+ 'yarn twenty apply',
+ '`yarn twenty plan` is read-only and requires the app to already be installed',
+ 'For a first sync, run `yarn twenty apply`',
+ 'Use the bounded apply command to synchronize app changes with the active remote',
'Do not use bare `yarn twenty dev` (watch mode)',
- 'yarn twenty dev --once --verbose',
+ 'yarn twenty apply --verbose',
'yarn twenty remote:list',
'yarn twenty dev:build',
'yarn twenty app:publish',
@@ -281,6 +285,7 @@ const assertCliGuidanceSplit = (fail) => {
'run outside the sandbox',
'incompatible Node and Yarn',
'operations/command-execution.md',
+ 'yarn twenty dev --once',
];
for (const fragment of forbiddenCliFragments) {
@@ -288,6 +293,31 @@ const assertCliGuidanceSplit = (fail) => {
fail(`cli-and-sync.md should not warn about the sandbox or reference the removed command-execution.md: ${fragment}`);
}
}
+
+ const agentFacingDocumentPaths = [
+ path.join(PLUGIN_ROOT, 'AGENTS.md'),
+ ...listFiles(path.join(PLUGIN_ROOT, 'skills')).filter((filePath) =>
+ filePath.endsWith('.md'),
+ ),
+ ...listFiles(path.join(PLUGIN_ROOT, 'references')).filter((filePath) =>
+ filePath.endsWith('.md'),
+ ),
+ ];
+
+ for (const documentPath of agentFacingDocumentPaths) {
+ const contents = readText(documentPath);
+
+ for (const deprecatedFragment of [
+ 'yarn twenty dev --once',
+ 'one-shot sync',
+ ]) {
+ if (contents.toLowerCase().includes(deprecatedFragment)) {
+ fail(
+ `${path.relative(PLUGIN_ROOT, documentPath)} contains deprecated ${deprecatedFragment} guidance`,
+ );
+ }
+ }
+ }
};
const assertTestingGuidance = (fail) => {
diff --git a/packages/twenty-codex-plugin/skills/manage-app/SKILL.md b/packages/twenty-codex-plugin/skills/manage-app/SKILL.md
index c21de529e06..75f1454d45e 100644
--- a/packages/twenty-codex-plugin/skills/manage-app/SKILL.md
+++ b/packages/twenty-codex-plugin/skills/manage-app/SKILL.md
@@ -88,7 +88,7 @@ When the user says "prod", "production", or "workspace de prod", identify the ta
# Development Sync
-Always use one-shot sync to synchronize app changes with the active remote:
+Always use bounded apply to synchronize app changes with the active remote:
```bash
yarn twenty apply
@@ -96,14 +96,14 @@ yarn twenty apply
Do not use bare `yarn twenty dev` (watch mode). Run `yarn twenty apply` each time changes need to be synced.
-One-shot sync requires an authenticated remote. If authentication fails, re-add or switch the remote before retrying.
+Bounded apply requires an authenticated remote. If authentication fails, re-add or switch the remote before retrying.
# Troubleshooting
Start by identifying which layer is failing:
- Remote/authentication.
-- Dev sync or one-shot sync.
+- Dev sync or bounded apply.
- Build/package generation.
- Deploy/upload/install.
- Runtime function execution.