twenty/packages/twenty-codex-plugin/AGENTS.md

Twenty Codex Plugin — Agent Guidance

This file is the canonical entry point for any agent (Codex, ChatGPT Developer Mode, or compatible) running with the Twenty plugin loaded. It encodes the boundaries, conventions, and operating rules that apply across all five bundled skills.

Per-skill SKILL.md files own task-specific guidance. This file owns the cross-skill expectations.

What This Plugin Does

The Twenty Codex plugin helps users build, operate, develop, publish, and query Twenty apps — modular extensions for the Twenty CRM platform. It bundles:

• 5 skills for the canonical Twenty app workflows.
• 15 reference docs under references/ covering concepts, data model, UI, layouts, CLI, publishing, and MCP.
• 1 public MCP server (twenty-docs) for searching official Twenty documentation.
• 1 setup helper (scripts/setup-mcp.sh) for adding user-local workspace MCP endpoints.

A Twenty app is a standalone npm package that extends a running Twenty instance. It is not a standalone application. For the full mental model read references/concepts/how-apps-work.md before doing anything substantive.

Skill Routing

Pick exactly one skill at a time based on the user's intent. Skills are deliberately disjoint.

User intent	Skill
Scaffold a brand-new Twenty app	create-app
Add or modify objects, fields, logic, views, front components, workflows	develop-app
Manage remotes, sync, build, deploy, logs, troubleshoot, CI/CD	manage-app
Prepare README, marketplace metadata, logos, screenshots for publishing	publish-app
Connect to a workspace via MCP, retrieve records, format readable Markdown	use-twenty-mcp

If the user's request straddles two skills, do the boundary task in the first skill and explicitly hand off to the second. Never silently combine.

Durable Operating Rules

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.

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.

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.

4. Confirm destructive operations. Deploys to production, uninstalls, production remote changes, and production syncs require explicit user confirmation before execution. Treat --remote production as user-visible.

5. Never bundle workspace-specific MCP URLs. Workspace MCP endpoints belong in the user's local .mcp.json and Codex MCP config. The plugin only ships the public twenty-docs MCP server. Use scripts/setup-mcp.sh to configure workspace MCP for a specific user.

6. Never put credentials in source. Bearer tokens, API keys, OAuth secrets, and workspace-specific URLs are user-local. TWENTY_DEPLOY_API_KEY and similar live in CI secret stores, never committed.

Reference Doc Map

When a skill points at a reference, read only what the task needs:

• concepts/how-apps-work.md — foundational. Read at the start of any non-trivial task.
• develop-app/app-structure.md — file layout, entity creation, validation checklist.
• develop-app/data-model.md — objects, fields, relations, roles, permissions.
• develop-app/front-components.md — front component source, SDK imports, runtime verification.
• develop-app/layout.md — views, navigation, page layouts, front component placement.
• develop-app/standalone-pages.md — full-page custom UI through standalone page layouts.
• develop-app/logic.md — logic functions, skills, agents, post-install, connection providers.
• develop-app/workflows.md — workflows, manual triggers, draft/activate lifecycle.
• develop-app/tests.md — test organization (*.spec.ts in __tests__/).
• design/front-component-ui.md — Twenty UI defaults and visual design rules.
• manage-app/cli-and-sync.md — CLI command semantics, sync modes, build, deploy, logs, CI/CD.
• publish-app/prepare-for-app-store.md — README, marketplace metadata, logos, screenshots.
• use-twenty-mcp/setup.md — workspace MCP URL normalization and OAuth setup.
• use-twenty-mcp/result-formatting.md — record link building, date formatting, readable Markdown.

How to Verify You're Following Best Practices

Run yarn workspace twenty-codex-plugin validate after any change to this plugin. Every box in CHECKLIST.md must be satisfied before a release.

Boundaries

This file is for agents using the plugin. If you are editing the plugin itself, see CONTRIBUTING.md.